Retrieving message descriptions from a message file

To retrieve the text of a message from a message file into a variable in a CL program or procedure, use the Retrieve Message (RTVMSG) command. The RTVMSG command operates on predefined message descriptions.

You can specify the message identifier and message file name in addition to the following items:

  • CCSID to convert to. It specifies the coded character set identifier that you want your message text and data returned in.
  • Message data fields. The message data to be inserted for the substitution variables.
  • Message data CCSID. It specifies the coded character set identifier that the supplied message data is to be considered in.
  • A group of CL variables into which the following information is placed (each corresponds to one variable):
    • Message (character variable, length varies)
    • Length of message, including length of substitution variable data (decimal variable, 5 decimal positions)
    • Message help information (character variable, length varies)
    • Length of message help, including length of substitution variable data (decimal variable, 5 decimal positions)
    • Severity code (decimal variable, 2 decimal positions)
    • Alert option (character variable, 9 characters)
    • Log problem in the service activity log (character variable, 1 character)
    • Message data CCSID is the coded character set identifier associated with the replacement data returned (decimal variable, 5 decimal positions)
    • Text data CCSID is the coded character set identifier associated with the text returned by the Message and the Message help parameters (decimal variable, 5 decimal positions)

For example, the following command adds the message description for the message USR1001 to the message file USRMSG: 


ADDMSGD   MSGID(USR1001) MSGF(QGPL/USRMSG) +
          MSG('File &1 not found in library &2') +
          SECLVL('Change file name or library name') +
          SEV(40) FMT((*CHAR 10) (*CHAR 10))

The following commands result in the substitution of the file name INVENT in the 10-character variable &FILE and the library name QGPL in the 10-character variable &LIB in the retrieved message USR1001. 


DCL &FILE TYPE(*CHAR) LEN(10) VALUE(INVENT)
DCL &LIB TYPE(*CHAR) LEN(10) VALUE(QGPL)
DCL &A TYPE(*CHAR) LEN(20)
DCL &MSG TYPE(*CHAR) LEN(50)
CHGVAR VAR(&A) VALUE(&FILE||&LIB)
RTVMSG   MSGID(USR1001) MSGF(QGPL/USRMSG) +
         MSGDTA(&A) MSG(&MSG)

The data for substitution variable &1 and &2 is contained in the procedure variable &A, in which the values of the procedure variables &FILE and &LIB have been concatenated. When the retrieve command is done, the following message is placed in the CL variable &MSG: 


   File INVENT not found in library QGPL

If the MSGDTA parameter is not used in the Retrieve Message (RTVMSG) command, the following message is placed in the CL variable &MSG:


   File not found in library

After the message is placed in the variable &MSG, you can perform the following tasks:

  • Send the message using the Send Program Message (SNDPGMMSG) command
  • Use the variable as the text for a message line in DDS (M in position 38)
  • Use a message subfile
  • Print or display the message