Receiving messages into a CL procedure or program

To obtain a message from a message queue for your procedure or program, use the Receive Message (RCVMSG) command.

Messages can be received in the following ways:

  • By message type. You can specify that all types or that a specific type can be received (MSGTYPE parameter). New messages (those that have not been received in the procedure or program) are received in a first-in-first-out (FIFO) order. However, ESCAPE type messages are received in last-in-first-out (LIFO) order.
  • By message reference key. You can do one of the following:
    • Receive a message using its message reference key. The system assigns a message reference key to each message on a message queue and passes the key as variable data because it is unprintable. You must declare this variable in your CL procedure or program (DCL command). You must specify the MSGKEY parameter on the Receive Message (RCVMSG) command to identify the CL variable through which the key is to be passed. This will indicate the specific message to be received.
    • Receive the next message on a message queue following the message with a specified message reference key. In addition to specifying the MSGKEY parameter, you must specify MSGTYPE(*NEXT).
    • Receive the message on a message queue that is before a message with a specified message reference key. In addition to specifying the MSGKEY parameter, you must specify MSGTYPE(*PRV).
  • By its location on the message queue. You must specify MSGTYPE(*FIRST) for the first message on the message queue; specify MSGTYPE(*LAST) for the last.
  • By both message type and message reference key (MSGTYPE and MSGKEY parameters).

To receive a message, you can specify:

  • Message queue. Where the message is to be received from.
  • Message type. Specify either a specific message type, or a value of *ANY to represent any type of message.
  • Whether to wait for the arrival of a message. After the wait is over and no message is received, the CL variables requested to be returned are filled with blanks (or zeros if numeric) and control returns to the procedure or program running the Receive Message (RCVMSG) command.
  • Whether to remove the message from the message queue after it is received. If it is not removed, it becomes an old message on the message queue and can only be received again (by a procedure) through its message reference key. However, if messages on the message queue are reset to new messages through the Change Message Queue (CHGMSGQ) command, you do not have to use the message reference key to receive the message. Note that inquiry messages that have already been replied to are not reset to a new status.
  • CCSID to convert to. Specifies the CCSID that you want your message text returned in.
  • A group of CL variables into which the following information is placed (each corresponds to one variable on the Receive Message (RCVMSG) command). One or more of the following return variables can be specified:
    • Message reference key of the message in the message queue (character variable, 4 characters)
    • Message (character variable, length varies)
    • Length of message, including length of substitution variable data (decimal variable, 5 decimal positions)
    • Message online help information (character variable, length varies)
    • Length of message help, including length of substitution variable data (decimal variable, 5 decimal positions)
    • Message data for the substitution variables provided by the sender of the message (character variable, length varies)
    • Length of the message data (decimal variable, 5 decimal positions)
    • Message identifier (character variable, 7 characters)
    • Severity code (decimal variable, length of 2)
    • Sender of the message (character variable, minimum of 80 characters, but a minimum of 87 characters are needed to obtain the current user information)
    • Type of message received (character variable, 2 characters long)
    • Alert option of the message received (character variable, 9 characters)
    • Message file that contains the predefined message (character variable, 10 characters)
    • Message file library name that contains the message file used to receive the message (character variable, 10 characters)
    • Message file library name that contains the message file used to send the message (character variable, 10 characters)
    • 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)

In the following sample Receive Message (RCVMSG) command, a message is obtained from message queue INVN in the QGPL library. The message text received is placed in the variable &MSG. *ANY is the default value on the MSGTYPE parameter.


RCVMSG MSGQ(QGPL/INVN) MSGTYPE(*ANY) MSG(&MSG)

When working with the call stack entry message queue of an Integrated Language Environment® (ILE) procedure written in a language other than CL, it is possible to receive an exception message (Escape or Notify) when the exception is not yet handled. The Receive Message (RCVMSG) command can be used to both receive a message and indicate to the system that the exception has been handled.

This can be controlled by using the RMV keyword. If *NO is specified for this keyword, the exception is handled and the message is left on the message queue as an old message. If *KEEPEXCP is specified, the exception is not handled and the message is left on the message queue as a new message. If *YES is specified, the exception message is handled and the message is removed from the message queue.

The RTNTYPE keyword can be used to determine if the message received is an exception message, and if so, whether the exception has been handled.