CL Command Reference - MONMSG
CL Command List > MONMSG Reference
Description:
The Monitor Message (MONMSG) command is used to monitor escape, notify, and status messages sent to the program message queue of the program in which the command is used. Completion and diagnostic messages cannot be monitored.
When the MONMSG command is compiled in a control language (CL) program, it establishes a monitor for the arrival of the specified messages. The command monitors the messages for the condition specified by the comparison data given in the command. If a message meeting the conditions arrives on the message queue, the CL command specified on the MONMSG command is processed.
Up to 1000 MONMSG commands can be specified in a program to monitor the arrival of messages for specific conditions or for a group of conditions. Specific message identifiers or generic message identifiers can be monitored.
The MONMSG command can be coded following most commands in a CL procedure. A MONMSG command that is not placed at the beginning of the program applies only to the immediately preceding command; this is called a command-level MONMSG command. The command-level MONMSG command monitors only messages sent by the previous command. If the message sent by that command meets the conditions specified in the MONMSG command, the action specified in the same MONMSG command is taken. As many as 100 MONMSG commands, coded immediately after a command, can monitor the messages sent by that command.
When the action specified in the MONMSG command has been performed, and that action does not end with a GOTO or RETURN command, control returns to the command in the program that follows the command that sent the message. If the action ends with a GOTO command, control branches to the command in the program specified in the GOTO command. If the action ends with a RETURN command, control returns to the program that called the program that contains the MONMSG command.
If one or more MONMSG commands are placed at the beginning of the program, immediately following the declare commands or the PGM command if there are no declare commands, they monitor messages sent by all of the commands in the program (maximum of 100). This is called a program-level MONMSG command. If any message sent by any command in the program meets the conditions specified in any one of the program-level MONMSG commands, the corresponding action specified in the same command is taken.
The action taken by a command-level MONMSG command overrides a program-level MONMSG command.
If a command is coded for the EXEC parameter on a MONMSG command that is placed at the beginning of a program, only the GOTO command can be used, and it must specify the label for the command to which control is to be passed if a monitored message occurs. The label specified on a program-level MONMSG command cannot be a label associated with a subroutine. If a GOTO command is performed for a program-level MONMSG, the subroutine stack will be reset by the next Call Subroutine (CALLSUBR) command.
If a command is not coded for the EXEC parameter, monitored messages are ignored.
Restrictions:
. This command is valid only in CL procedures.
. It can be coded after the last declare command (if declare commands are used), following the PGM command that begins the program, or it can be coded following any command allowed in CL procedures, except for the following: DO, DOWHILE, DOUNTIL, DOFOR, ELSE, ENDDO, SELECT, WHEN, OTHERWISE, ENDSELECT, ENDPGM, CALLSUBR, SUBR, RTNSUBR, ENDSUBR, GOTO, IF, or RETURN. Note that if another program sends a message that is monitored by this command, a return cannot be made to that program.
Examples:
Example 1: Monitoring Messages Sent by Any Command
PGM
MONMSG MSGID(CPF0001 CPF1999) EXEC(GOTO EXIT2)
This example shows a MONMSG command at the beginning of a CL procedure that monitors for messages CPF0001 and CPF1999; these messages might be sent by any command processed later in the procedure. When either message is received from any of the commands running in the procedure, control branches to the command identified by the label EXIT2.
CPF0001 states that an error was found in the command that is identified in the message itself. CPF1999, which can be sent by many of the debugging commands (like CHGPGMVAR), states that errors occurred on the command, but it does not identify the command in the message.
Example 2: Monitoring Messages Sent by a Single Command
CHGVAR VAR(&A) VALUE(&A / &B)
MONMSG MSGID(MCH1211) EXEC(CHGVAR VAR(&A) VALUE(1))
In this example, the MONMSG command follows a Change Variable (CHGVAR) command and, therefore, is only monitoring messages sent by the CHGVAR command. Escape message MCH1211 is sent to this program¡¯s message queue when a division by zero is attempted. Because MSGID(MCH1211) is specified, the MONMSG command is monitoring for this condition; when it receives the message, the second CHGVAR command is processed. In this command, the variable &A is set to a value of 1.