Monitor Message (MONMSG) Command

Escape messages are sent to CL procedures by the commands in the CL procedures and by the programs and procedures they call. These escape messages are sent to tell the procedures that errors were detected and requested functions were not performed. CL procedures can monitor for the arrival of escape messages, and you can specify through commands how to handle the messages. For example, if a CL procedure tries to move a data area that has been deleted, an object-not-found escape message is sent to the procedure by the Move Object (MOVOBJ) command.

Using the Monitor Message (MONMSG) command, you can direct a procedure to take predetermined action if specific errors occur during the processing of the immediately preceding command. The Monitor Message (MONMSG) command has the following parameters:

MONMSG   MSGID(message-identifier) CMPDTA(comparison-data) +
         EXEC(CL-command)

Each message that is sent for a specific error has a unique identifier. You can enter as many as 50 message identifiers on the MSGID parameter. (See the online help for messages and identifiers). The CMPDTA parameter allows even greater specification of error messages because you can check for a specific character string in the MSGDTA portion of the message. On the EXEC parameter, you can specify a CL command (such as a Call Program (CALL), Do (DO), or a Go To (GOTO)), which directs the procedure to perform error recovery.

In the following example, the Monitor Message (MONMSG) command follows the Receive File (RCVF) command and, therefore, is only monitoring for messages sent by the RCVF command:

READLOOP:  RCVF                          /* Read a file record  */
           MONMSG  MSGID(CPF0864)  EXEC(GOTO CMDLBL(EOF))
           /*  Process the file record  */
           GOTO  CMDLBL(READLOOP)       /*  Get another record  */
EOF:       /*  End of file processing  */

The escape message, CPF0864, is sent to the procedure's invocation queue when there are no more records in the file to read. Because the example specifies MSGID(CPF0864), the MONMSG monitors for this condition. When it receives the message, the GOTO CMDLBL(EOF) command is run.

You can also use the Monitor Message (MONMSG) command to monitor for messages sent by any command in a CL procedure. The following example includes two Monitor Message (MONMSG) commands. The first Monitor Message (MONMSG) command monitors for the messages CPF0001 and CPF1999; these messages might be sent by any command run 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.

The second MONMSG command monitors for the messages CPF2105 and MCH1211. Because no command is coded for the EXEC parameter, these messages are ignored.

PGM
DCL
MONMSG MSGID(CPF0001 CPF1999) EXEC(GOTO EXIT2)
MONMSG MSGID(CPF2105 MCH1211)
.
.
.
ENDPGM

Message CPF0001 states that an error was found in the command that is identified in the message itself. Message CPF1999, which can be sent by many of the debugging commands, such as Change Program Variable (CHGPGMVAR), states that errors occurred on the command, but it does not identify the command in the message.

All error conditions monitored for by the Monitor Message (MONMSG) command with the EXEC parameter specified (CPF0001 or CPF1999) are handled in the same way at EXIT2, and it is not possible to return to the next sequential statement after the error. You can avoid this by monitoring for specific conditions after each command and branching to specific error correction procedures.

All error conditions monitored for by the Monitor Message (MONMSG) command without the EXEC parameter specified (CPF2105 or MCH1211) are ignored, and procedure processing continues with the next command.

If the error occurs when evaluating the expression on an IF command, the condition is considered false. In the following example, MCH1211 (divide by zero) could occur on the IF command. The condition would be considered false, and PROCA would be called.

IF(&A / &B *EQ 5) THEN(DLTF ABC)
ELSE CALLPRC PROCA

If you code the Monitor Message (MONMSG) command at the beginning of your CL procedure, the messages you specify are monitored throughout the program, regardless of which command produces these messages. If the EXEC parameter is used, only the GOTO command can be specified. If the GOTO command is run in your program, the subroutine stack will be reset.

You can specify the same message identifier on a procedure-level or a command-level Monitor Message (MONMSG) command. The command-level Monitor Message (MONMSG) commands take precedence over the procedure-level MONMSG commands. In the following example, if message CPF0001 is received on CMDB, CMDC is run. If message CPF0001 is received on any other command in the procedure, the procedure branches to EXIT2. If message CPF1999 is received on any command, including CMDB, the procedure branches to EXIT2.

PGM
MONMSG MSGID(CPF0001 CPF1999) EXEC(GOTO EXIT2)
CMDA
CMDB
MONMSG MSGID(CPF0001) EXEC(CMDC)
CMDD
EXIT2:  ENDPGM

Because many escape messages can be sent to a procedure, you must decide which ones you want to monitor for and handle. Most of these messages are sent to a procedure only if there is an error in the procedure. Others are sent because of conditions outside the procedure. Generally, a CL procedure should monitor for those messages that pertain to its basic function and that it can handle appropriately. For all other messages, i5/OS™ assumes an error has occurred and takes appropriate default action.