243 lines
16 KiB
HTML
243 lines
16 KiB
HTML
<?xml version="1.0" encoding="UTF-8"?>
|
|
<!DOCTYPE html
|
|
PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|
<html lang="en-us" xml:lang="en-us">
|
|
<head>
|
|
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
|
|
<meta name="security" content="public" />
|
|
<meta name="Robots" content="index,follow" />
|
|
<meta http-equiv="PICS-Label" content='(PICS-1.1 "http://www.icra.org/ratingsv02.html" l gen true r (cz 1 lz 1 nz 1 oz 1 vz 1) "http://www.rsac.org/ratingsv01.html" l gen true r (n 0 s 0 v 0 l 0) "http://www.classify.org/safesurf/" l gen true r (SS~~000 1))' />
|
|
<meta name="DC.Type" content="task" />
|
|
<meta name="DC.Title" content="Monitor for messages in a CL program or procedure" />
|
|
<meta name="abstract" content="You can monitor for exception messages. Exception messages include escape, notify, and status messages that are sent to your CL procedure's or program's call message queue by the commands in your procedure or program or by commands in another procedure or program. Diagnostic messages cannot be monitored." />
|
|
<meta name="description" content="You can monitor for exception messages. Exception messages include escape, notify, and status messages that are sent to your CL procedure's or program's call message queue by the commands in your procedure or program or by commands in another procedure or program. Diagnostic messages cannot be monitored." />
|
|
<meta name="DC.subject" content="MONMSG (Monitor Message) command, in CL procedure, Monitor Message (MONMSG) command, command, CL, MONMSG (Monitor Message), Monitor Message (MONMSG), message, monitoring, description, control language (CL), procedure, monitoring for message, escape message, escape, status message, receiving, notify message, program level, specific command level, example, message for specific command, message within procedures" />
|
|
<meta name="keywords" content="MONMSG (Monitor Message) command, in CL procedure, Monitor Message (MONMSG) command, command, CL, MONMSG (Monitor Message), Monitor Message (MONMSG), message, monitoring, description, control language (CL), procedure, monitoring for message, escape message, escape, status message, receiving, notify message, program level, specific command level, example, message for specific command, message within procedures" />
|
|
<meta name="DC.Relation" scheme="URI" content="wmsgs.htm" />
|
|
<meta name="DC.Relation" scheme="URI" content="wchmsg.htm" />
|
|
<meta name="DC.Relation" scheme="URI" content="dfthd.htm" />
|
|
<meta name="DC.Relation" scheme="URI" content="ntmsg.htm" />
|
|
<meta name="DC.Relation" scheme="URI" content="ssmsg.htm" />
|
|
<meta name="DC.Relation" scheme="URI" content="preventsmg.htm" />
|
|
<meta name="DC.Relation" scheme="URI" content="amsgi.htm" />
|
|
<meta name="DC.Relation" scheme="URI" content="enmsg.htm" />
|
|
<meta name="copyright" content="(C) Copyright IBM Corporation 1998, 2006" />
|
|
<meta name="DC.Rights.Owner" content="(C) Copyright IBM Corporation 1998, 2006" />
|
|
<meta name="DC.Format" content="XHTML" />
|
|
<meta name="DC.Identifier" content="monmg" />
|
|
<meta name="DC.Language" content="en-us" />
|
|
<!-- All rights reserved. Licensed Materials Property of IBM -->
|
|
<!-- US Government Users Restricted Rights -->
|
|
<!-- Use, duplication or disclosure restricted by -->
|
|
<!-- GSA ADP Schedule Contract with IBM Corp. -->
|
|
<link rel="stylesheet" type="text/css" href="./ibmdita.css" />
|
|
<link rel="stylesheet" type="text/css" href="./ic.css" />
|
|
<title>Monitor for messages in a CL program or procedure</title>
|
|
</head>
|
|
<body id="monmg"><a name="monmg"><!-- --></a>
|
|
<!-- Java sync-link --><script language="Javascript" src="../rzahg/synch.js" type="text/javascript"></script>
|
|
<h1 class="topictitle1">Monitor for messages in a CL program or procedure</h1>
|
|
<div><p>You can monitor for exception messages. Exception messages include
|
|
escape, notify, and status messages that are sent to your CL procedure's or
|
|
program's call message queue by the commands in your procedure or program
|
|
or by commands in another procedure or program. Diagnostic messages cannot
|
|
be monitored.</p>
|
|
<div class="section"> <p>Monitorable messages are those *ESCAPE, *STATUS, and *NOTIFY
|
|
messages that can be issued by each CL command that can be used in a program.
|
|
Each IBM-supplied command identifies in its help documentation which exception
|
|
messages it generates. You can use this information to determine which messages
|
|
you want to monitor for in your program.</p>
|
|
<p>Using the <span class="cmdname">Monitor
|
|
Message (MONMSG)</span> command, you can monitor for one or more messages
|
|
sent to the call message queue for the conditions specified in the command.
|
|
You can then use the <span class="cmdname">Monitor Message (MONMSG)</span> command to
|
|
specify that if the condition exists, the CL command specified on the MONMSG
|
|
command is run. The logic involved with the <span class="cmdname">Monitor Message (MONMSG)</span> command
|
|
is as follows:</p>
|
|
<p><strong>Escape Messages:</strong> Escape messages are sent to tell
|
|
your procedure or program of an error condition that forced the sender to
|
|
end. By monitoring for escape messages, you can take corrective actions or
|
|
clean up and end your procedure or program.</p>
|
|
<p><strong>Status or Notify Messages</strong> Status
|
|
and notify messages are sent to tell your procedure or program of an abnormal
|
|
condition that is not serious enough for the sender to end. By monitoring
|
|
for status or notify messages, your procedure or program can detect this condition
|
|
and not allow the function to continue.</p>
|
|
<p>You can monitor for messages
|
|
using two levels of <span class="cmdname">Monitor Message (MONMSG)</span> commands:
|
|
</p>
|
|
<ul><li>Procedure level: You can monitor for an escape, notify, or status message
|
|
sent by any command in your procedure by specifying the <span class="cmdname">Monitor Message
|
|
(MONMSG)</span> command immediately following the last declare command
|
|
in your CL procedure or program. This is called a procedure-level <span class="cmdname">Monitor
|
|
Message (MONMSG)</span> command. You can use as many as 100 procedure-level
|
|
MONMSG commands in a procedure or OPM program. (A CL procedure or OPM program
|
|
can contain a total of 1000 MONMSG commands.) This lets you handle the same
|
|
escape message in the same way for all commands. The EXEC parameter is optional,
|
|
and only the GOTO command can be specified on this EXEC parameter. </li>
|
|
<li>Specific command level: You can monitor for an escape, notify, or status
|
|
message sent by a specific command in your procedure or program by specifying
|
|
the MONMSG command immediately following the command. This is called a command
|
|
level MONMSG command. You can use as many as 100 command-level MONMSG commands
|
|
for a single command. This lets you handle different escape messages in different
|
|
ways.</li>
|
|
</ul>
|
|
<p>To monitor for escape, status, or notify messages, you must specify,
|
|
on the MONMSG command, generic message identifiers for the messages in one
|
|
of the following ways: </p>
|
|
<ul><li><samp class="codeph">pppmmnn</samp> <p>Monitors for a specific message. For example,
|
|
MCH1211 is the message identifier of the zero divide escape message.</p>
|
|
</li>
|
|
<li><samp class="codeph">pppmm00</samp> <p>Monitors for any message with a generic message
|
|
identifier that begins with a specific licensed program (<samp class="codeph">ppp</samp>)
|
|
and the digits specified by mm. For example, CPF5100 indicates that all notify,
|
|
status, and escape messages beginning with CPF51 are monitored.</p>
|
|
</li>
|
|
<li><samp class="codeph">ppp0000</samp> <div class="p">Monitors for every message with a generic
|
|
message identifier that begins with a specific licensed program (<samp class="codeph">ppp</samp>).
|
|
For example, <samp class="codeph">CPF0000</samp> indicates that all notify, status, and
|
|
escape messages beginning with <samp class="codeph">CPF</samp> are monitored. <div class="note"><span class="notetitle">Note:</span> Do
|
|
not use <samp class="codeph">MONMSG CPF0000</samp> when doing system function, such as
|
|
install or saving or restoring your entire system, since you may lose important
|
|
information.</div>
|
|
</div>
|
|
</li>
|
|
<li>CPF9999 <p>Monitors for function check messages. If an error message
|
|
is not monitored, it becomes a CPF9999 (function check).</p>
|
|
</li>
|
|
</ul>
|
|
<div class="note"><span class="notetitle">Note:</span> Generally, when monitoring, your monitor also gets control when
|
|
notify and status messages are sent.</div>
|
|
<p>In addition to monitoring for
|
|
escape messages by message identifier, you can compare a character string,
|
|
which you specify on the <span class="cmdname">Monitor Message (MONMSG)</span> command,
|
|
to message data sent in the message. For example, the following command monitors
|
|
for an escape message (CPF5101) for the file MYFILE. The name of the file
|
|
is specified as message data when the CPF5101 message is sent by a program.</p>
|
|
<pre>MONMSG MSGID(CPF5101) CMPDTA(MYFILE) EXEC(GOTO EOJ)</pre>
|
|
<p>The compare data can be as long as 28 characters, and the comparison
|
|
starts with the first character of the first field of the message data. If
|
|
the compare data matches the message data, the action specified on the EXEC
|
|
parameter is run.</p>
|
|
<p>The EXEC parameter on the <span class="cmdname">Monitor Message
|
|
(MONMSG)</span> command specifies how an escape message is to be handled.
|
|
Any command except PGM, ENDPGM, IF, ELSE, DCL, DCLF, ENDDO, and MONMSG can
|
|
be specified on the EXEC parameter. You can specify a DO command on the EXEC
|
|
parameter, and the commands in the do group are run. When the
|
|
command or do group (on the EXEC parameter) has been run, control returns
|
|
to the command in your procedure or program that is after the command that
|
|
sent the escape message. However, if you specify a GOTO or RETURN command,
|
|
control does not return. If you do not specify the EXEC parameter, the escape
|
|
message is ignored and your procedure continues.</p>
|
|
<p>The following shows
|
|
an example of a <span class="cmdname">Change Variable (CHGVAR)</span> command being
|
|
monitored for a zero divide escape message, message identifier MCH1211: </p>
|
|
<pre>CHGVAR VAR(&A) VALUE(&A / &B)
|
|
MONMSG MSGID(MCH1211) EXEC(CHGVAR VAR(&A) VALUE(1))</pre>
|
|
<p>The value of the variable &A is changed to the value of &A
|
|
divided by &B. If &B equals 0, the divide operation cannot be done
|
|
and the zero divide escape message is sent to the procedure. When this happens,
|
|
the value of &A is changed to 1 (as specified on the EXEC parameter).
|
|
You may also test &B for zero, and only perform the division if it is
|
|
not zero. This is more efficient than attempting the operation and monitoring
|
|
for the escape message.</p>
|
|
<p>In the following example, the procedure monitors
|
|
for the escape message CPF9801 (object not found message) on the <span class="cmdname">Check
|
|
Object (CHKOBJ)</span> command: </p>
|
|
<pre> PGM
|
|
CHKOBJ LIB1/PGMA *PGM
|
|
MONMSG MSGID(CPF9801) EXEC(GOTO NOTFOUND)
|
|
CALL LIB1/PGMA
|
|
RETURN
|
|
NOTFOUND: CALL FIX001 /* PGMA Not Found Routine */
|
|
ENDPGM</pre>
|
|
<p>The following CL procedure contains two <span class="cmdname">Call (CALL)</span> commands
|
|
and a procedure-level MONMSG command for CPF0001. (This escape message occurs
|
|
if a <span class="cmdname">Call (CALL)</span> command cannot be completed successfully.)
|
|
If either CALL command fails, the procedure sends the completion message
|
|
and ends. </p>
|
|
<pre> PGM
|
|
MONMSG MSGID(CPF0001) EXEC(GOTO ERROR)
|
|
CALL PROGA
|
|
CALL PROGB
|
|
RETURN
|
|
ERROR: SNDPGMMSG MSG('A CALL command failed') MSGTYPE(*COMP)
|
|
ENDPGM</pre>
|
|
<p>If the EXEC parameter is not coded on a procedure-level MONMSG
|
|
command, any escape message that is handled by the MONMSG command is ignored.
|
|
If the escape message occurs on any command except the condition of an IF
|
|
command, the procedure or program continues processing with the command that
|
|
would have been run next if the escape message had not occurred. If the escape
|
|
message occurs on the condition of an IF command, the procedure or program
|
|
continues processing as if the condition on the IF command were false. The
|
|
following example illustrates what happens if an escape message occurs at
|
|
different points in the procedure: </p>
|
|
<pre>PGM
|
|
DCL &A TYPE(*DEC) LEN(5 0)
|
|
DCL &B TYPE(*DEC) LEN(5 0)
|
|
MONMSG MSGID(CPF0001 MCH1211)
|
|
CALL PGMA PARM(&A &B)
|
|
IF (&A/&B *EQ 5) THEN(CALL PGMB)
|
|
ELSE CALL PGMC
|
|
CALL PGMD
|
|
ENDPGM</pre>
|
|
<p>Depending on where an escape message occurs, the following
|
|
happens: </p>
|
|
<ul><li>If CPF0001 occurs on the call to PGMA, the procedure resumes processing
|
|
on the IF command.</li>
|
|
<li>If MCH1211 (divide by 0) occurs on the IF command, the IF condition is
|
|
considered false, and the procedure resumes processing with the call to PGMC.</li>
|
|
<li>If CPF0001 occurs on the call to PGMB or PGMC, the procedure resumes processing
|
|
with the call to PGMD.</li>
|
|
<li>If CPF0001 occurs on the call to PGMD, the procedure resumes processing
|
|
with the ENDPGM command, which causes a return to the calling procedure.</li>
|
|
</ul>
|
|
<p>You can also monitor for the same escape message to be sent by a specific
|
|
command in your procedure or program <em>and</em> by another command. This requires
|
|
two <span class="cmdname">Monitor Message (MONMSG)</span> commands. One <span class="cmdname">Monitor
|
|
Message (MONMSG)</span> command follows the command that needs special
|
|
handling for the escape message; for that command, this <span class="cmdname">Monitor Message
|
|
(MONMSG)</span> command is used when the escape message is sent. The other <span class="cmdname">Monitor
|
|
Message (MONMSG)</span> command follows the last declare command so that
|
|
for all other commands, this <span class="cmdname">Monitor Message (MONMSG)</span> command
|
|
is used.</p>
|
|
<p><span class="cmdname">Monitor Message (MONMSG)</span> commands apply
|
|
only to the CL procedure or OPM program in which they are coded. MONMSG commands
|
|
from one procedure do not apply to another procedure even though both are
|
|
part of the same program. Online help and documentation for each command contains
|
|
a list of the escape, notify, and status messages that are issued for the
|
|
command. You should also keep a list of all messages that you have defined.</p>
|
|
<div class="note"><span class="notetitle">Note:</span> The
|
|
above paragraph is not true for ILE procedures because of the way messages
|
|
percolate. The system requires MONMSG to handle any escape message that is
|
|
sent to a procedure. Otherwise, the message percolates up the call stack until
|
|
it finds a procedure that has a <span class="cmdname">Monitor Message (MONMSG)</span> to
|
|
handle it or hits a control boundary.</div>
|
|
</div>
|
|
</div>
|
|
<div>
|
|
<ul class="ullinks">
|
|
<li class="ulchildlink"><strong><a href="wchmsg.htm">Watch for messages</a></strong><br />
|
|
The system provides a watch for event function which allows you to watch for messages.</li>
|
|
<li class="ulchildlink"><strong><a href="dfthd.htm">CL handling for unmonitored messsages</a></strong><br />
|
|
The system provides default monitoring and handling of any messages you do not monitor.</li>
|
|
<li class="ulchildlink"><strong><a href="ntmsg.htm">Monitor for notify messages</a></strong><br />
|
|
You can monitor for notify messages that are sent to your CL procedure's or program's call message queue by the commands in your procedure or program or by the programs and procedures it calls.</li>
|
|
<li class="ulchildlink"><strong><a href="ssmsg.htm">Monitor for status messages</a></strong><br />
|
|
You can monitor for status messages that are sent by the commands in your CL procedure or by the programs or procedures it calls.</li>
|
|
<li class="ulchildlink"><strong><a href="preventsmg.htm">Prevent the display of status messages</a></strong><br />
|
|
You cannot prevent commands from sending status messages, but you can prevent the status messages from being displayed at the bottom of the screen.</li>
|
|
</ul>
|
|
|
|
<div class="familylinks">
|
|
<div class="parentlink"><strong>Parent topic:</strong> <a href="wmsgs.htm" title="This discusses some of the ways that messages can be used to communicate between users and programs.">Messages</a></div>
|
|
</div>
|
|
<div class="relconcepts"><strong>Related concepts</strong><br />
|
|
<div><a href="enmsg.htm" title="You can send both escape and notify messages from your CL procedure or program to message queues.">Escape and notify messages</a></div>
|
|
</div>
|
|
<div class="reltasks"><strong>Related tasks</strong><br />
|
|
<div><a href="amsgi.htm" title="The message identifier you specify on the Add Message Description (ADDMSGD) command is used to refer to the message and is the name of the message description.">Assign a message identifier</a></div>
|
|
</div>
|
|
</div>
|
|
</body>
|
|
</html> |