CL Command Reference - RCVMSG
CL Command List > RCVMSG Reference
Description:
The Receive Message (RCVMSG) command is used by a program to receive a message previously sent to a message queue.
The RCVMSG command receives messages from a job message queue (a message queue associated with a call stack entry or the external message queue (*EXT)), or from a named message queue. The program can receive a message from a message queue associated with its own call stack entry or from a message queue associated with another call stack entry.
This command copies a message received in the specified message queue into control language (CL) variables within the program. The message and its attributes are copied into the CL variables specified by the parameters KEYVAR through DTACCSID.
You can specify the message being received by indicating the message type, the reference key of the message, or both. The program receiving the message can also specify, on the RCVMSG command, whether a message is removed from the message queue or left there as an old message. If the specified message queue is not allocated to the job in which this command is entered, or to any other job, the message queue is implicitly allocated by this command for the duration of the command¡¯s processing.
If a message of the specified type does not exist on the queue, the requesting program can either wait for a message to arrive or continue with other processing. This allows a set of message queues to be polled.
If the message received is an unhandled exception message, the program can specify whether this command should handle the exception. An unhandled exception message is an escape, status, or notify message that has been sent to an Integrated Language Environment (ILE) procedure. When this command is run, the ILE procedure has not yet taken action to tell the system that the exception is handled. One action the ILE procedure can take is to call a CL program that receives the message using this command.
Examples:
Example 1: Receiving a Message
RCVMSG MSGQ(SMITH) MSGKEY(&KEY) MSG(&WORK)
This command receives the message having the message reference key specified by the program variable &KEY from the message queue SMITH. The text of the message is copied into the CL variable &WORK.
Example 2: Receiving a New Message
RCVMSG MSGQ(INV) WAIT(120) MSG(&WORK)
This command receives a new message from the message queue named INV into the CL variable &WORK. The program waits no more than 120 seconds for the arrival of a new message if there are no new messages in the message queue. If there is more than one new message in the queue, the first message in the queue is the message received by the program.
Example 3: Receiving a Message From a Procedure
RCVMSG PGMQ(*SAME CURRENT_MONTH_TOTALS) MSGTYPE(*EXCP)
RMV(*KEEPEXCP) MSGID(&MID) MSG(&MTEXT)
This command receives an exception message from the procedure CURRENT_MONTH_TOTALS. Since the specified name is more than 10 characters, the system does not search for any programs. If the message is an unhandled exception, the message is left on the call message queue as a new message and the exception is not handled by the RCVMSG command. The message ID is returned in the CL variable &MID and the message text in the CL variable &MTEXT. To handle the exception and remove the message, run the following RCVMSG command:
RCVMSG PGMQ(*SAME CURRENT_MONTH_TOTALS) MSGTYPE(*EXCP) RMV(*YES)
Example 4: Receiving a Message from a Program or Procedure
RCVMSG PGMQ(*SAME TARGETPGM) MSGTYPE(*EXCP) RMV(*NO)
MSGID(&MID) MSG(&MTEXT)
This command receives an exception message from the message queue of the program or procedure named TARGETPGM. Since the specified name is only 9 characters, the system searches both programs and procedures. Because RMV(*NO) is specified, if the message is an unhandled exception, the exception is handled by the RCVMSG command. The message is left on the message queue as an old message.
Example 5: Receiving a Message Using Qualifiers
RCVMSG PGMQ(*SAME PRINT_RPT_FMT1 DEPTRPTS AREARPTS)
MSGTYPE(*EXCP) RMV(*YES) MSGID(&MID) MSG(&MTEXT)
This command receives an exception message from the message queue of the procedure named PRINT_RPT_FMT1. The procedure must have been compiled into the module DEPTRPTS and have been bound into the bound program AREARPTS. Since RMV(*YES) is specified, the exception is handled if the exception message is for an unhandled exception. The message is always removed from the message queue.
Example 6: Receiving a Message Using a Partial Procedure Name
RCVMSG PGMQ(*SAME ¡¯HANDLE_FORM_NUM>>>¡¯) MSGID(&MID) MSG(&MTEXT)
This command receives a new message from the most recent procedure whose name begins with HANDLE_FORM_NUM.