Monitor Message (MONMSG)

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. Other message types (completion, diagnostic, etc.) 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 program or ILE 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 a CL program or ILE CL procedure.
• 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 a CL program or ILE CL procedure, 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.

Parameters

Message identifier (MSGID)

Specifies the message identifiers of one or more escape, notify, or status messages that are to be monitored by this command. As many as 50 specific or generic message identifiers can be specified on one command.

Note: Many CL commands issue one escape message for many different error conditions. Details about the error or failure are given in diagnostic messages that precede the escape message. Although diagnostic messages cannot be monitored, they can be received from the job's external message queue after the escape message has activated the user's message monitor.

The first 3 characters of a message identifier must be a code consisting of an alphabetic character followed by two alphanumeric (alphabetic or decimal) characters; the last 4 characters may consist of the decimal numbers 0 through 9 and the characters A through F.

Note: Message identifiers using the MCH code (MCHnnnn) use only the numbers 0 through 9 in the last four characters.

If zeros are specified in either two or all four of the rightmost positions, such as USRmm00, a generic message identifier is specified. For example, if CPF0000 is specified, all messages with the prefix 'CPF' are monitored. Generic message identifiers can be used for both command-level MONMSG and procedure-level MONMSG statements.

Specify the message identifiers of 1 to 50 messages that are monitored when they arrive at this program's message queue. The message identifiers and message text of the escape, notify, and status messages which may be sent by a command can be found in the command's documentation in the Information Center as well as the command's online help. CL variables cannot be used to specify message identifiers.

This is a required parameter.

Comparison data (CMPDTA)

Specifies the comparison data that is used to determine whether the monitored message (having one of the specified message identifiers) received on the program's message queue is acted on by this command. The message data specified in the MSGDTA parameter of the Send Program Message (SNDPGMMSG) command is compared with this comparison data. If the first part (up through the first 28 characters, or less) of the message's substitution values matches the comparison data specified, the action specified in the EXEC parameter of this command is taken. The action is also taken if no comparison data is specified.

*NONE

No comparison data is specified. If the message in the program's message queue is from a command that this command is monitoring, and if it has the specified identifier, the action specified for the Command to execute (EXEC) parameter is taken.

comparison-data

Specify a character string of no more than 28 characters, enclosed in apostrophes if necessary, that is compared with the same number of characters in the message data of the received message, starting with the first character in the message data. If the comparison data matches the first part of the received message data, this command performs the function specified in the EXEC parameter. A CL variable cannot be specified for the comparison data.

The comparison data can be displayed by the Display Program Variable (DSPPGMVAR) command.

Command to execute (EXEC)

Specifies the CL command to be processed when a monitored message sent to the program's message queue meets the conditions specified in this command. If no command is specified and a monitored message arrives on the queue, the message is ignored, and control passes to the next command in the program.

If the MONMSG command is placed at the beginning of the program, the EXEC parameter must specify the GOTO command and the label identifying the command that receives control.

Specify the CL command, including its parameters to be used, that is run when a message meeting the conditions specified in this command is received. The command specified is not run if the received message does not meet the specified conditions. A CL variable cannot be specified in place of the CL command.

Note: If a DO, DOWHILE, DOUNTIL, DOFOR, or SELECT command is specified on EXEC, the entire group associated with the command is processed if the condition is met.

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.

Error messages

None