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