RTVMSG (Retrieve Message)

RTVMSG Command syntax diagram

 

Purpose

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.

Restriction: The user of this command must have *USE authority for the message file and the library in which the message file is stored.

 

Required Parameters

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

MSGF
Specifies the qualified name of the message file that contains the predefined message being retrieved.

The name of the message file can be qualified by one of the following library values:

*LIBL: All libraries in the job's library list are searched until the first match is found.

*CURLIB: The current library for the job is searched. If no library is specified as the current library for the job, the QGPL library is used.

library-name: Specify the name of the library to be searched.

message-file-name: Specify the name of the message file to use.

 

Optional Parameters

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 topic in the Information Center for a list of valid CCSID values. Only those CCSID values that the job can be changed to are accepted.

For more information on the message handler and its use of CCSIDs, see the Globalization topic in the Information Center.

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. The values, which take the place of the substitution variables defined in the message text when the message was defined, 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. The CL Programming book has more details.

  • Multiple values must be specified in the same order in the character string as the substitution variables were defined in the FMT parameter of the ADDMSGD command.

  • Each value must be specified as long as its associated variable was defined, and 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.

  • 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 by this command 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 coded. 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 SNDUSRMSG or SNDPGMMSG commands.

MSG
Specifies the name of the CL character variable in the program into which the first-level message text from the retrieved message is copied. If a CL variable name is not specified, the text is not copied into the program.

The specified variable must be a character variable. If the retrieved text is longer than the variable's field length, the text is truncated. If the text is shorter, it is padded to the right with blanks. Although this is a variable-length field, most first-level message text is designed to be less than 132 characters.

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

The specified variable must be a decimal variable that has a length of five digits. If a CL variable name is not specified, the length is not copied into the program.

SECLVL
Specifies the name of the CL character variable in the program into which the second-level message text of the retrieved message is copied. If a variable name is not specified, the second-level message text is not copied into the program.

If the retrieved second-level message text is longer than the variable's field length, the text is truncated. If the text is shorter, it is padded on the right with blanks. Although this is a variable length field, most second-level message text is designed to be less than 3000 characters.

SECLVLLEN
Specifies the name of the CL decimal variable in the program into which the total length of the second-level message text being retrieved is copied. The length specified is the total length after the substitution values (specified 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. If a CL variable name is not specified, the length is not copied into the program.

SEV
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.

ALROPT
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.

LOGPRB
Specifies the name of the variable into which a Y (yes) or N (no) is returned indicating whether or not the message can be logged in the service activity log. The variable must be a character variable one position long.

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. If a conversion error occurs, or if the CCSID you requested the text to be converted to is 65535, the CCSID that the message description is stored in is returned. 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 on 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.

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. If a conversion error occurs, or if the CCSID you requested the text to be converted to is 65535, the CCSID specified on the MDTACCSID parameter is returned. Otherwise the CCSID you wanted the text converted to is returned. In the case 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.

MDTACCSID
Specifies the CCSID that the supplied message data is to be considered 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. For a list of valid CCSID values, see the Globalization topic in the Information Center.

Examples for RTVMSG

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- and Second-Level Message Text 

RTVMSG  MSGID(UIN0150)  MSGF(INV)  MSG(&MSG)
  SECLVL(&SECLVL)

This command retrieves the first- 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 for RTVMSG

*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 allowed.
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.