Retrieve Message (RTVMSG)

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.

Parameters

Message identifier (MSGID)

Specifies the message identifier of the predefined message that is being retrieved from the specified message file.

This is a required parameter.

Message file (MSGF)

Specifies the message file that contains the predefined message to be retrieved.

This is a required parameter.

Qualifier 1: Message file

name

Specify the name of the message file containing the message to be retrieved.

Qualifier 2: Library

*LIBL

All libraries in the library list for the current thread are searched until the first match is found.

*CURLIB

The current library for the job is used to locate the message file. If no current library entry exists in the library list, QGPL is used.

name

Specify the library where the message file is located.

Message data field values (MSGDTA)

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.

As many substitution values can be specified in the character string as there are substitution variables in the predefined message description. The values, which take the place of the substitution variables in the message text, must be specified by the following rules:

• Multiple values must be concatenated to form a single character string. The length of the entire character string of concatenated substitution values cannot exceed 512 characters.
• Multiple values in the character string must be specified in the same order as the substitution variables were defined in the FMT parameter of the ADDMSGD command.
• Each value must be specified with the length of its associated variable in the message description. The specified character string must be the same length as the sum of the message data fields defined in the message description.
• For multiple values, each substitution value can be specified as a CL program constant or CL variable. That is, any combination of constants and variables can be specified if they are first concatenated into one character string and they are in the same format and sequence expected by the message description.
• The length of the substitution value should be the same length as the length defined for the substitution variables. If the substitution value length is longer than the substitution variable length, the message data is truncated. If the substitution value is shorter, it becomes a null field.
• The message data supplied that corresponds to a *CCHAR type field, is assumed to be in the CCSID of the job running this command, unless the MDTACCSID parameter is specified. For more information on the *CCHAR type field, see the Add Message Description (ADDMSGD) command.

For more information on coding this parameter, refer to the description of the MSGDTA parameter in the SNDPGMMSG command.

CL var for 1st level text (MSG)

Specifies the name of the CL character variable into which the text of the retrieved message is returned. If a CL variable name is not specified, the message text is not returned to the program. This is a variable length field, but most messages are designed to be less than 132 characters long.

CL var for MSGLEN (5 0) (MSGLEN)

Specifies the name of the CL decimal variable into which the total length of the message text available to be retrieved is returned. The length returned is the total length after the substitution values (supplied in the MSGDTA parameter) are placed in the text.

The specified variable must be a decimal variable that has a length of five digits.

CL var for 2nd level text (SECLVL)

Specifies the name of the CL character variable into which the second level message text, or message help, of the retrieved message is returned. If a variable name is not specified, the message help is not returned to the program. This is a variable length field, but most message help is designed to be less than 3000 characters long.

CL var for SECLVLLEN (5 0) (SECLVLLEN)

Specifies the name of the CL decimal variable into which the total length of the message help being retrieved is returned. The length returned is the total length after the substitution values (supplied in the MSGDTA parameter) are placed in the second-level message text.

The specified variable must be a decimal variable that has a length of five positions.

CL var for SEV (2 0) (SEV)

Specifies the name of the CL decimal variable into which the severity code of the retrieved message is returned. 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 returned to the program.

CL var for ALROPT (9) (ALROPT)

Specifies the name of the CL variable into which the alert option of the retrieved message is returned. 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 returned to the program.

CL var for LOGPRB (1) (LOGPRB)

Specifies whether the message will be logged in the problem log. The variable must be a character variable one position long. The values returned are Y (yes) or N (no).

Convert to CCSID (CCSID)

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.

*JOB

The retrieved message description is converted to the CCSID of the job before being returned.

*HEX

The retrieved message description is not converted before being returned.

coded-character-set-identifier

Specify the CCSID that you want your message description converted to before it is returned.

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 i5/OS globalization topic collection in the IBM i Information Center at http://www.ibm.com/systems/i/infocenter/.

Message data CCSID (MDTACCSID)

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.

*JOB

The message data supplied is assumed to be in the CCSID of the job running this command.

*HEX

The message data supplied is assumed to be 65535 and is never converted.

coded-character-set-identifier

The message data supplied is assumed to be in the CCSID specified. 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.

CL var for text CCSID (5 0) (TXTCCSID)

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:

• If a conversion error occurs.
• If the job has a CCSID of 65535 and you did not specify the CCSID parameter.
• If you specify *JOB for the CCSID parameter.
• If the CCSID you requested the text to be converted to is 65535.

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.

CL var for data CCSID (5 0) (DTACCSID)

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:

• If a conversion error occurs.
• If the job has a CCSID of 65535 and you did not specify the CCSID parameter.
• If you specify *JOB for the CCSID parameter.
• If the CCSID you requested the text to be converted to is 65535.

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.

Examples

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.

Error messages

*ESCAPE Messages

CPF2401

Not authorized to library &1.

CPF2407

Message file &1 in &2 not found.

CPF2411

Not authorized to message file &1 in &2.

CPF247E

CCSID &1 is not valid.

CPF2471

Length of field not valid.

CPF2499

Message identifier &1 not valid.

CPF2531

Message file &1 in &2 damaged for &3.

CPF2547

Damage to message file QCPFMSG.

CPF2548

Damage to message file &1 in &2.

CPF8126

Message file &4 in &9 damaged.

CPF9830

Cannot assign library &1.

*STATUS Messages

CPF2419

Message identifier &1 not found in message file &2 in &3.

*NOTIFY Messages

CPF2465

Replacement text of message &1 in &2 in &3 not valid for format specified.