| Where allowed to run: Compiled CL program or interpreted REXX (*BPGM *IPGM *BREXX *IREXX) Threadsafe: Yes |
Parameters Examples Error messages |
The Retrieve Message (RTVMSG) command is used in a CL program or REXX procedure to retrieve a specified predefined message from a message file and to copy it into CL variables. Substitution values can be specified in the MSGDTA parameter (as a single character string containing one or more concatenated message data fields) to replace the substitution variables in the predefined message text. The program can later write the message to an output device file to be printed, for example.
The CL prompt for this command lists the minimum length for retrieved variables next to the parameters that have a minimum length. For character variables, a single number is shown. For decimal variables, two numbers are shown. The first number indicates the minimum variable length and the second number indicates the minimum number of decimal positions.
Restrictions: The user of this command must have use (*USE) authority for the message file and *USE authority for the library in which the message file is located.
| Top |
| Keyword | Description | Choices | Notes |
|---|---|---|---|
| MSGID | Message identifier | Name | Required, Positional 1 |
| MSGF | Message file | Qualified object name | Required, Positional 2 |
| Qualifier 1: Message file | Name | ||
| Qualifier 2: Library | Name, *LIBL, *CURLIB | ||
| MSGDTA | Message data field values | Character value | Optional |
| MSG | CL var for 1st level text | Character value | Optional |
| MSGLEN | CL var for MSGLEN (5 0) | Decimal number | Optional |
| SECLVL | CL var for 2nd level text | Character value | Optional |
| SECLVLLEN | CL var for SECLVLLEN (5 0) | Decimal number | Optional |
| SEV | CL var for SEV (2 0) | Decimal number | Optional |
| ALROPT | CL var for ALROPT (9) | Character value | Optional |
| LOGPRB | CL var for LOGPRB (1) | Character value | Optional |
| CCSID | Convert to CCSID | 1-65535, *HEX, *JOB | Optional |
| MDTACCSID | Message data CCSID | 1-65535, *HEX, *JOB | Optional |
| TXTCCSID | CL var for text CCSID (5 0) | Decimal number | Optional |
| DTACCSID | CL var for data CCSID (5 0) | Decimal number | Optional |
| Top |
Specifies the message identifier of the predefined message that is being retrieved from the specified message file.
This is a required parameter.
| Top |
Specifies the message file that contains the predefined message to be retrieved.
This is a required parameter.
Qualifier 1: Message file
Qualifier 2: Library
| Top |
Specifies the substitution values that are used in the retrieved message if the predefined message contains substitution variables. Either a character string or a CL variable containing the character string can be specified.
| Top |
Specifies the name of the CL character variable in the program into which the text of the retrieved message is copied. If a CL variable name is not specified, the message text is not copied into the program. This is a variable length field, but most messages are designed to be less than 132 characters long.
| Top |
Specifies the name of the CL decimal variable in the program into which the total length of the message text available to be retrieved is copied.
The specified variable must be a decimal variable that has a length of five digits.
| Top |
Specifies the name of the CL character variable in the program into which the second level message, or message help, of the retrieved message is copied. If a variable name is not specified, the message help is not copied into the program. This is a variable length field, but most message help is designed to be less than 3000 characters long.
| Top |
Specifies the name of the CL decimal variable in the program into which the total length of the message help being retrieved is copied.
The specified variable must be a decimal variable that has a length of five positions.
| Top |
Specifies the name of the CL decimal variable into which the severity code of the retrieved message is copied. The specified variable must be a decimal variable that has a length of two positions. If a variable name is not specified, the severity code of the retrieved message is not copied into the program.
| Top |
Specifies the name of the CL variable into which the alert option of the retrieved message is copied. The variable must be a character variable nine positions long. If a character variable is not specified, the alert option of the retrieved message is not copied into the program.
| Top |
Specifies whether the message will be logged in the problem log. The variable must be a character variable one position long.
| Top |
Specifies the coded character set identifier (CCSID) in which you want your message text returned. This applies only to text returned in the MSG and SECLVL parameters. When replacement data is substituted into the text returned in the MSG or SECLVL parameters, only the part of the replacement data that is defined as a character that can be converted (*CCHAR) is converted. The rest of the replacement data will not be converted. For more information about the *CCHAR field, see the Add Message Description (ADDMSGD) command.
Note: The valid values range from 1 through 65535. See the Globalization information in the iSeries Information Center at http://www.ibm.com/eserver/iseries/infocenter for a list of valid CCSID values. Only CCSIDs that you can change your job to are accepted.
For more information on the message handler and its use of CCSIDs, see the Globalization topic in the iSeries Information Center at http://www.ibm.com/eserver/iseries/infocenter.
| Top |
Specifies the CCSID that the supplied message data is assumed to be in. This only applies to the parts of the replacement data that are defined as *CCHAR. The rest of the replacement data will never be converted and is assumed to have a CCSID of 65535.
| Top |
Specifies the name of the CL variable, if any, used to return the coded character set identifier (CCSID) associated with the text returned by the MSG and SECLVL parameters. The CCSID that the message description is stored in is returned if the one of the following occurs:
Otherwise, the CCSID you wanted the text converted to is returned. If you do not want the text converted before it is returned to you but you do want to know the CCSID that the message description is stored in, specify 65535 for the CCSID parameter. The CCSID that the message description is stored in is returned in the TXTCCSID parameter. You can also check for a conversion error by comparing the CCSID you passed in against the TXTCCSID returned. If they are not equal and they are not 65535, a conversion error occurred.
| Top |
Specifies the name of the CL variable, if any, used to return the coded character set identifier (CCSID) associated with the replacement data defined as *CCHAR. All other replacement data is not converted before it is returned. The CCSID specified for the MDTACCSID parameter is returned if the one of the following occurs:
Otherwise the CCSID you wanted the text converted to is returned. When there is no *CCHAR replacement data in the text, 65535 is returned. You can check for a conversion error by comparing the CCSID you passed in against the DTACCSID returned. If they are not equal and they are not 65535, a conversion error occurred.
| Top |
Example 1: Replacing Substitution Variables
RTVMSG MSGID(UIN0145) MSGF(INVN) MSG(&WORK)
MSGDTA('any old time')
This command retrieves the message text of the message UIN0145 stored in the INVN message file. The retrieved text is copied into the CL variable &WORK after the substitution variables are replaced with the values any, old, and time. This example assumes that the substitution variables &1, &2, and &3 have been defined in the message as character variables, each 4 characters long.
Example 2: Retrieving First-Level and Second-Level Message Text
RTVMSG MSGID(UIN0150) MSGF(INV) MSG(&MSG)
SECLVL(&SECLVL)
This command retrieves the first-level message text and second-level message text of the message UIN0150, which is stored in message file INV, and moves it into the CL variables &MSG and &SECLVL.
| Top |
*ESCAPE Messages
*STATUS Messages
*NOTIFY Messages
| Top |