177 lines
10 KiB
HTML
177 lines
10 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="Use break-handling programs" />
|
||
|
|
<meta name="abstract" content="A break-handling program is one that is automatically called when a message arrives at a message queue that is in *BREAK mode." />
|
||
|
|
<meta name="description" content="A break-handling program is one that is automatically called when a message arrives at a message queue that is in *BREAK mode." />
|
||
|
|
<meta name="DC.subject" content="break-handling program, program, break-handling, example" />
|
||
|
|
<meta name="keywords" content="break-handling program, program, break-handling, example" />
|
||
|
|
<meta name="DC.Relation" scheme="URI" content="wmsgs.htm" />
|
||
|
|
<meta name="DC.Relation" scheme="URI" content="msghp.htm" />
|
||
|
|
<meta name="DC.Relation" scheme="URI" content="../apis/XBREAK.htm" />
|
||
|
|
<meta name="DC.Relation" scheme="URI" content="ussrl.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="bhprg" />
|
||
|
|
<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>Use break-handling programs</title>
|
||
|
|
</head>
|
||
|
|
<body id="bhprg"><a name="bhprg"><!-- --></a>
|
||
|
|
<!-- Java sync-link --><script language="Javascript" src="../rzahg/synch.js" type="text/javascript"></script>
|
||
|
|
<h1 class="topictitle1">Use break-handling programs</h1>
|
||
|
|
<div><p>A break-handling program is one that is automatically called when
|
||
|
|
a message arrives at a message queue that is in *BREAK mode. </p>
|
||
|
|
<div class="section"> <p>You must specify the name of both the program and the break delivery
|
||
|
|
name on the same <span class="cmdname">Change Message Queue (CHGMSGQ)</span> command.
|
||
|
|
Although you specify the program on the CHGMSGQ command, it is one or more
|
||
|
|
procedures within the program that processes the message. A procedure within
|
||
|
|
this program must run a <span class="cmdname">Receive Message (RCVMSG)</span> command
|
||
|
|
to receive the message. To receive and handle the message, the user-defined
|
||
|
|
program called to handle messages for break delivery receives parameters.
|
||
|
|
Specifically, the first procedure to run within the program receives these
|
||
|
|
parameters. The parameters identify the message queue and the message reference
|
||
|
|
key (MRK) of the message that is causing the break. If the system calls a
|
||
|
|
break-handling program, it interrupts the job that has the message queue in
|
||
|
|
break mode. When the break-handling program ends, the interrupted program
|
||
|
|
resumes processing.</p>
|
||
|
|
<p>The following program (PGMA), which consists of
|
||
|
|
only this one procedure, is an example of a break-handling program. </p>
|
||
|
|
<pre>PGM PARM(&MSGQ &MSGLIB &MRK)
|
||
|
|
DCL VAR(&MSGQ) TYPE(*CHAR) LEN(10)
|
||
|
|
DCL VAR(&MSGLIB) TYPE(*CHAR) LEN(10)
|
||
|
|
DCL VAR(&MRK) TYPE(*CHAR) LEN(4)
|
||
|
|
DCL VAR(&MSG) TYPE(*CHAR) LEN(75)
|
||
|
|
RCVMSG MSGQ(&MSGLIB/&MSGQ) MSGKEY(&MRK) +
|
||
|
|
MSG(&MSG)
|
||
|
|
.
|
||
|
|
.
|
||
|
|
.
|
||
|
|
ENDPGM</pre>
|
||
|
|
<p>After the break-handling program is created, running the following
|
||
|
|
command connects it to the QSYSMSG message queue.</p>
|
||
|
|
<pre>CHGMSGQ MSGQ(QSYS/QSYSMSG) DLVRY(*BREAK) PGM(PGMA)</pre>
|
||
|
|
<div class="note"><span class="notetitle">Note:</span> <ol><li>When messages are handled, they should be removed from the message queue.
|
||
|
|
When a message queue is put in break mode, any message on the queue will
|
||
|
|
cause the break-handling program to get called. During CHGMSGQ, the break
|
||
|
|
program is called only once when a message is found that meets the criteria
|
||
|
|
of the message severity for the queue, regardless of how many messages meeting
|
||
|
|
the message severity criteria are found so the break handling program should
|
||
|
|
handle all of the messages on the queue. After CHGMSGQ, the break
|
||
|
|
program is called for each message that meets the message severity criteria.</li>
|
||
|
|
<li>The procedure or program receiving the message should not be coded with
|
||
|
|
a wait-time other than zero to receive a message. You can specify a value
|
||
|
|
other than zero for the wait parameter with the <span class="cmdname">Receive Message (RCVMSG)</span> command.
|
||
|
|
The message arrival event cannot be handled by the system while the job is
|
||
|
|
running a break-handling event.</li>
|
||
|
|
<li>The message queue severity can be set to indicate that the break-handling
|
||
|
|
program should only be called if the severity of the message sent is equal
|
||
|
|
to or greater than the severity of the message queue.</li>
|
||
|
|
</ol>
|
||
|
|
</div>
|
||
|
|
<p>An example of a break-handling program is to have the program
|
||
|
|
send a message, which is normally sent to the QSYSOPR queue, to another queue
|
||
|
|
in place of or in addition to QSYSOPR.</p>
|
||
|
|
<p>The following is an example of
|
||
|
|
a user-defined program (again with only one procedure) to handle break messages.
|
||
|
|
The display station user does not need to respond to the messages CPA5243
|
||
|
|
(Press Ready, Start, or Start-Stop on device &1) and CPA5316 (Verify alignment
|
||
|
|
on device &3) when this program is used. </p>
|
||
|
|
<pre>BRKPGM: PGM (&MSGQ &MSGQLIB &MSGMRK)
|
||
|
|
DCL &MSGQ TYPE(*CHAR) LEN(10)
|
||
|
|
DCL &MSGQLIB TYPE(*CHAR) LEN(10)
|
||
|
|
DCL &MSGMRK TYPE(*CHAR) LEN(4)
|
||
|
|
DCL &MSGID TYPE(*CHAR) LEN(7)
|
||
|
|
RCVMSG MSGQ(&MSGQLIB/&MSGQ) MSGKEY(&MSGMRK) +
|
||
|
|
MSGID(&MSGID) RMV(*NO)
|
||
|
|
/* Ignore message CPA5243 */
|
||
|
|
IF (&MSGID *EQ 'CPA5243') GOTO ENDBRKPGM
|
||
|
|
/* Reply to forms alignment message */
|
||
|
|
IF (&MSGID *EQ 'CPA5316') +
|
||
|
|
DO
|
||
|
|
SNDRPY MSGKEY(&MSGMRK) MSGQ(&MSGQLIB/&MSGQ) RPY(I)
|
||
|
|
ENDDO
|
||
|
|
/* Other messages require user intervention */
|
||
|
|
ELSE CMD(DSPMSG MSGQ(&MSGQLIB/&MSGQ))
|
||
|
|
ENDBRKPGM: ENDPGM</pre>
|
||
|
|
<div class="attention"><span class="attentiontitle">Attention:</span> <p>In the above example of a break-handling
|
||
|
|
program, if a CPA5316 message should arrive at the queue while the <span class="cmdname">Display
|
||
|
|
Message (DSPMSG)</span> command is running, the DSPMSG display shows the
|
||
|
|
original message that caused the break and the CPA5316 message. The DSPMSG
|
||
|
|
display waits for the operator to reply to the CPA5316 message before proceeding.</p>
|
||
|
|
</div>
|
||
|
|
<div class="note"><span class="notetitle">Note:</span> This
|
||
|
|
program cannot open a display file if the interrupted program is waiting for
|
||
|
|
input data from the display.</div>
|
||
|
|
<p>You can use the system reply list to
|
||
|
|
indicate the system will issue a reply to predefined inquiry messages. The
|
||
|
|
display station user, therefore, does not need to reply. </p>
|
||
|
|
<p>A procedure
|
||
|
|
within a user break-handling program may need a Suspend and Restore procedure
|
||
|
|
to ensure the display is suspended and restored while the message handling
|
||
|
|
function is being performed. The Suspend and Restore procedure is necessary
|
||
|
|
only if the following conditions exist: </p>
|
||
|
|
<ul><li>A procedure in the break-program displays other menus or screens</li>
|
||
|
|
<li>The break-program calls other programs which may display other menus or
|
||
|
|
screens.</li>
|
||
|
|
</ul>
|
||
|
|
<p>The following example clarifies the user procedure and display file
|
||
|
|
needed to suspend and restore the display:</p>
|
||
|
|
<div class="note"><span class="notetitle">Note:</span> RSTDSP(*YES) must be specified
|
||
|
|
to create the display file.</div>
|
||
|
|
<pre> A R SAVFMT OVERLAY KEEP
|
||
|
|
A*
|
||
|
|
A R DUMMY OVERLAY
|
||
|
|
A KEEP
|
||
|
|
A ASSUME
|
||
|
|
A DUMMYR 1A 1 2DSPATR(ND)
|
||
|
|
|
||
|
|
|
||
|
|
PGM PARM(&MSGQ &MSGLIB &MRK)
|
||
|
|
DCL VAR(&MSGQ) TYPE(*CHAR) LEN(10)
|
||
|
|
DCL VAR(&MSGLIB) TYPE(*CHAR) LEN(10)
|
||
|
|
DCL VAR(&MRK) TYPE(*DEC) LEN(4)
|
||
|
|
DCLF FILE(UDDS/BRKPGMFM)
|
||
|
|
SNDF RCDFMT(SAVFMT)
|
||
|
|
CALL PGM(User's Break Program)
|
||
|
|
SNDF RCDFMT(SAVFMT)
|
||
|
|
ENDPGM</pre>
|
||
|
|
<p>If you do not want the user specified break-handling program
|
||
|
|
to interrupt the interactive job, the program may be submitted to run in batch.
|
||
|
|
You may do this by specifying a break-handling program that receives the
|
||
|
|
message and then performs a <span class="cmdname">Submit Job (SBMJOB)</span>. The SBMJOB
|
||
|
|
performs a call to the current break-handling program with any parameters
|
||
|
|
that you want to use. (An example is information from the receive message.)
|
||
|
|
Control will then be returned to the interactive job and it will continue
|
||
|
|
normally.</p>
|
||
|
|
</div>
|
||
|
|
</div>
|
||
|
|
<div>
|
||
|
|
<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="msghp.htm" title="A break-handling program can be called whenever a message of equal or higher severity than the severity code filter arrives on a message queue that is in break delivery mode.">Message queues in break mode</a></div>
|
||
|
|
</div>
|
||
|
|
<div class="reltasks"><strong>Related tasks</strong><br />
|
||
|
|
<div><a href="ussrl.htm" title="The system reply list allows you to specify that the system will automatically issue the reply to specified predefined inquiry messages so the display station user does not need to reply.">Use the system reply list</a></div>
|
||
|
|
</div>
|
||
|
|
<div class="relinfo"><strong>Related information</strong><br />
|
||
|
|
<div><a href="../apis/XBREAK.htm">Break Handling Exit Program</a></div>
|
||
|
|
</div>
|
||
|
|
</div>
|
||
|
|
</body>
|
||
|
|
</html>
|