628 lines
23 KiB
HTML
628 lines
23 KiB
HTML
|
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
||
|
|
<html>
|
||
|
|
<head>
|
||
|
|
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
|
||
|
|
<meta name="Copyright" content="Copyright (c) 2006 by IBM Corporation">
|
||
|
|
<title>Reply Handling Exit Program</title>
|
||
|
|
|
||
|
|
<!-- Begin Header Records ========================================== -->
|
||
|
|
<!-- 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. -->
|
||
|
|
<!--End Header Records -->
|
||
|
|
<link rel="stylesheet" type="text/css" href="../rzahg/ic.css">
|
||
|
|
</head>
|
||
|
|
<body>
|
||
|
|
<a name="Top_Of_Page"></a>
|
||
|
|
<!-- Java sync-link -->
|
||
|
|
<script language="Javascript" src="../rzahg/synch.js" type="text/javascript">
|
||
|
|
</script>
|
||
|
|
|
||
|
|
<h2>Reply Handling Exit Program</h2>
|
||
|
|
|
||
|
|
<div class="box" style="width: 80%;">
|
||
|
|
<br>
|
||
|
|
Required Parameter Group:<br>
|
||
|
|
<!-- iddvc RMBR -->
|
||
|
|
<br>
|
||
|
|
<table width="100%">
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="top" width="10%">1</td>
|
||
|
|
<td align="left" valign="top" width="50%">Type of call</td>
|
||
|
|
<td align="left" valign="top" width="20%">Input</td>
|
||
|
|
<td align="left" valign="top" width="20%">Binary(4)</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="top">2</td>
|
||
|
|
<td align="left" valign="top">Qualified message queue name</td>
|
||
|
|
<td align="left" valign="top">Input</td>
|
||
|
|
<td align="left" valign="top">Char(20)</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="top">3</td>
|
||
|
|
<td align="left" valign="top">Message key</td>
|
||
|
|
<td align="left" valign="top">Input</td>
|
||
|
|
<td align="left" valign="top">Char(4)</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="top">4</td>
|
||
|
|
<td align="left" valign="top">Message identifier</td>
|
||
|
|
<td align="left" valign="top">Input</td>
|
||
|
|
<td align="left" valign="top">Char(7)</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="top">5</td>
|
||
|
|
<td align="left" valign="top">Reply</td>
|
||
|
|
<td align="left" valign="top">I/O</td>
|
||
|
|
<td align="left" valign="top">Char(*)</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="top">6</td>
|
||
|
|
<td align="left" valign="top">Length of the reply</td>
|
||
|
|
<td align="left" valign="top">I/O</td>
|
||
|
|
<td align="left" valign="top">Binary(4)</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="top">7</td>
|
||
|
|
<td align="left" valign="top">CCSID of the reply</td>
|
||
|
|
<td align="left" valign="top">I/O</td>
|
||
|
|
<td align="left" valign="top">Binary(4)</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="top">8</td>
|
||
|
|
<td align="left" valign="top">Reply action return code</td>
|
||
|
|
<td align="left" valign="top">Output</td>
|
||
|
|
<td align="left" valign="top">Binary(4)</td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
Exit Point Name: QIBM_QMH_REPLY_INQ<br>
|
||
|
|
<!-- iddvc RMBR -->
|
||
|
|
<br>
|
||
|
|
Exit Point Format Name: RPYI0100<br>
|
||
|
|
<!-- iddvc RMBR -->
|
||
|
|
<br>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
<p>A reply handling exit program is called when a reply is sent to an inquiry
|
||
|
|
message. The operating system calls the user-written exit program identified
|
||
|
|
through the registration facility. The program is called after the system
|
||
|
|
validates the reply, but before the reply is sent to the inquiry message. For
|
||
|
|
some inquiry messages, a reply handling exit program can indicate that the reply
|
||
|
|
should be rejected. When an exit program indicates that the reply should be
|
||
|
|
rejected, a diagnostic message (CPD2476 Reply rejected by a reply handling exit
|
||
|
|
program) is sent to the caller of the send reply function.</p>
|
||
|
|
|
||
|
|
|
||
|
|
<p>This is followed by an escape message CPF2422 (Reply not valid).
|
||
|
|
An exit program can also replace the reply value to be sent.
|
||
|
|
When an exit program indicates that the reply should be replaced, the
|
||
|
|
send reply function sends a
|
||
|
|
diagnostic message to itself. The message is CPD2479 (Reply
|
||
|
|
handling exit program requested to replace a reply value). After the
|
||
|
|
reply is sent, CPF2458 (Reply replaced by a reply handling exit program)
|
||
|
|
will be sent as a diagnostic message and a
|
||
|
|
status message to the caller of the send reply function. The status
|
||
|
|
message allows the caller to monitor for the condition when a
|
||
|
|
reply value other than what was specified is sent. When the
|
||
|
|
condition occurs, the caller can then receive the diagnostic
|
||
|
|
message to obtain details about the reply replacement. </p>
|
||
|
|
|
||
|
|
|
||
|
|
<p>The first parameter
|
||
|
|
sent to the exit program indicates the various reasons for which the exit
|
||
|
|
program can be called.</p>
|
||
|
|
|
||
|
|
<p>The exit point supports an unlimited number of exit programs. If multiple
|
||
|
|
exit programs are defined, all of the exit programs are called for each reply
|
||
|
|
to an inquiry message until one of the exit programs rejects the reply or
|
||
|
|
replaces the reply value. When a reply is rejected or replaced, any exit
|
||
|
|
program that was previously notified of the reply is called again to be
|
||
|
|
informed the reply is now being rejected or replaced. See
|
||
|
|
<a href="#reqparam">Required Parameters</a> for details on the types of calls the
|
||
|
|
exit program must handle and the valid return codes that can be specified to
|
||
|
|
return to the exit point. For information about adding or removing an exit
|
||
|
|
program for an exit point, see <a href="reg1.htm">Registration Facility</a>
|
||
|
|
documentation.</p>
|
||
|
|
|
||
|
|
<p>The exit program can use the receive message function to obtain additional
|
||
|
|
information about the message being replied to. For example, the program can
|
||
|
|
obtain the message data, the sender of the message, and so on. If the exit
|
||
|
|
program attempts to obtain information from the sending job, it needs to take
|
||
|
|
into account that the job that sent the inquiry could have ended before the
|
||
|
|
inquiry is replied to, thus requiring the exit program to handle a
|
||
|
|
not-found error. The exit program is executed within the same job as the
|
||
|
|
user that entered a reply. It can use commands or APIs to obtain information
|
||
|
|
about the current job and current user that provided the reply.</p>
|
||
|
|
|
||
|
|
<h3>Authorities and Locks</h3>
|
||
|
|
|
||
|
|
<dl>
|
||
|
|
<dt><em>User Profile Authority</em></dt>
|
||
|
|
|
||
|
|
<dd>*ALLOBJ and *SECADM to add or remove exit programs in the registration
|
||
|
|
facility.</dd>
|
||
|
|
</dl>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
|
||
|
|
|
||
|
|
<h3><a name="reqparam">Required Parameter Group</a></h3>
|
||
|
|
|
||
|
|
<dl>
|
||
|
|
<dt><strong>Type of call</strong></dt>
|
||
|
|
|
||
|
|
<dd>INPUT; BINARY(4)
|
||
|
|
|
||
|
|
<p>The reason the exit program is being called. The valid values are:</p>
|
||
|
|
|
||
|
|
<table cellpadding="5">
|
||
|
|
<!-- cols="5 95" -->
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>0</em></td>
|
||
|
|
<td align="left" valign="top"><strong>Reply notification--no action
|
||
|
|
allowed.</strong> Informs an exit program that a reply is being sent to an
|
||
|
|
inquiry message. The original reply value has been replaced by another
|
||
|
|
exit program so any remaining exit programs are informed of the reply with
|
||
|
|
this value, but the reply cannot be rejected or replaced. The return code
|
||
|
|
parameter is ignored by the exit point.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>1</em></td>
|
||
|
|
<td align="left" valign="top"><strong>Reply validation requested.</strong> The
|
||
|
|
exit program should set the return code parameter to indicate whether the reply
|
||
|
|
should be accepted, rejected, or replaced. A return code parameter with a
|
||
|
|
value other than 0 or 2 will cause the reply to be accepted.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>2</em></td>
|
||
|
|
<td align="left" valign="top"><strong>Default reply validation
|
||
|
|
requested.</strong> The default reply is being sent to an inquiry message. The
|
||
|
|
exit program should set the return code parameter to indicate whether the
|
||
|
|
reply should be accepted or replaced. The exit program can set the return
|
||
|
|
code parameter to indicate rejected, but this will cause the inquiry
|
||
|
|
message to be left as unanswered (and possibly cause the job to hang). A
|
||
|
|
return code parameter with a value other than 0 or 2 will cause the
|
||
|
|
reply to be accepted.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>3</em></td>
|
||
|
|
<td align="left" valign="top"><strong>Default reply notification.</strong>
|
||
|
|
Informs an exit program that an inquiry message is being replied to with
|
||
|
|
the default reply and the reply cannot be rejected, but the reply value
|
||
|
|
can be replaced by an exit program. A return code parameter value
|
||
|
|
other than 2 is ignored by the exit point and the reply is accepted.
|
||
|
|
If a user or job requested a function that sends a default reply
|
||
|
|
and the reply is not allowed to be rejected, this value would
|
||
|
|
be sent to an exit program. Examples of when this value would be used:
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li>deleting a message queue that contains unanswered inquiry messages.</li>
|
||
|
|
|
||
|
|
<li>sending the default reply to an unanswered inquiry and the parameter
|
||
|
|
to allow default reply rejection was not specified.</li>
|
||
|
|
|
||
|
|
<li>sending an inquiry to a message queue that is in default mode.</li>
|
||
|
|
|
||
|
|
<li>sending an inquiry to *EXT so it shows the Display Program Messages
|
||
|
|
screen and the user presses F3, F12 or Enter to exit the
|
||
|
|
screen without entering any reply.</li>
|
||
|
|
|
||
|
|
<li>sending an inquiry to *EXT in a batch job.</li>
|
||
|
|
|
||
|
|
<li>a job uses an inquiry message reply job attribute of *DFT.</li>
|
||
|
|
|
||
|
|
<li>wrapping a message queue.</li>
|
||
|
|
</ul>
|
||
|
|
</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>4</em></td>
|
||
|
|
<td align="left" valign="top"><strong>Reply rejected notification.</strong>
|
||
|
|
Informs an exit program that another exit program rejected the reply to an
|
||
|
|
inquiry message. The return code parameter is ignored by the exit point and a
|
||
|
|
reply is not sent to the inquiry message. When an exit program rejects a reply,
|
||
|
|
any exit programs that previously accepted the reply are notified that a reply was
|
||
|
|
rejected with the use of this value but any
|
||
|
|
remaining exit programs that have never been informed of the reply will not be
|
||
|
|
called to be notified of the rejection.
|
||
|
|
|
||
|
|
<p>When a reply is rejected, message
|
||
|
|
CPD2476 (Reply rejected by a reply handling exit program) is sent
|
||
|
|
as a diagnostic message to the caller of the send reply function to indicate
|
||
|
|
the reply they requested to be sent was rejected.
|
||
|
|
The send reply function will also send message CPD2476 a second time. The second
|
||
|
|
time it will be sent to the send reply function instead of to its caller. This
|
||
|
|
will allow an exit program to receive the CPD2476 by specifying to receive
|
||
|
|
the message from the invocation previous to the exit program.
|
||
|
|
So there are not two CPD2476 messages left in the job log, the second CPD2476
|
||
|
|
will be removed by the send reply function
|
||
|
|
after all the exit programs that accepted the reply are notified of the
|
||
|
|
reply rejection.</p>
|
||
|
|
|
||
|
|
</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>5</em></td>
|
||
|
|
<td align="left" valign="top"><strong>Replaced reply not valid.</strong>
|
||
|
|
Informs an exit program that the reply information it specified for replacement
|
||
|
|
is not valid. <p>The send reply function will send a diagnostic message to itself
|
||
|
|
to indicate the problem with the reply information. One of the following
|
||
|
|
messages could be sent:
|
||
|
|
CPD2477 (Reply replaced by exit program not valid) or
|
||
|
|
CPD2478 (Reply replaced by exit program same as original reply value).</p>
|
||
|
|
|
||
|
|
<p>The return code parameter will be ignored by the exit point
|
||
|
|
and the original reply value, now specified in parameters 5 though 7, will
|
||
|
|
be used as the reply value for the message. The next reply handling
|
||
|
|
exit program will be called or the reply will be sent if there are no
|
||
|
|
other exit programs to call.</p></td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>6</em></td>
|
||
|
|
<td align="left" valign="top"><strong>Reply replaced notification.</strong>
|
||
|
|
Informs an exit program, that has already accepted the reply, that another
|
||
|
|
exit program replaced that reply.
|
||
|
|
|
||
|
|
<p>When a reply is replaced, the send reply function will send
|
||
|
|
CPD2479 (Reply handling exit program requested to replace a reply value)
|
||
|
|
as a diagnostic message to itself. This will allow
|
||
|
|
an exit program to receive the message from the previous invocation
|
||
|
|
to find out information about the replacement.</p>
|
||
|
|
|
||
|
|
<p>The return code parameter is ignored
|
||
|
|
by the exit point. The reply cannot be rejected nor replaced. Parameters
|
||
|
|
5 through 7 contain the new reply value to be sent to the inquiry message.</p></td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>7</em></td>
|
||
|
|
<td align="left" valign="top"><strong>Reply cannot be sent
|
||
|
|
notification.</strong> The return code parameter is ignored by the exit point.
|
||
|
|
The reply is not sent to the inquiry message. When an exit program accepts a
|
||
|
|
reply, but then the system is not able to send that reply to the inquiry
|
||
|
|
message, this value will be used to notify all the exit programs. This may
|
||
|
|
indicate that something is wrong with the queue. After exit programs are
|
||
|
|
notified, an error message is sent by the system reply function as it ends or
|
||
|
|
returns.</td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
|
||
|
|
<p><strong>Note:</strong> For values 0, 4, 5, and 6, parameter 8 will be ignored.
|
||
|
|
For values 4 and 7, parameter 5 will be blank and parameters 6 and 7 will be
|
||
|
|
zero.</p>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><strong>Qualified message queue name</strong></dt>
|
||
|
|
|
||
|
|
<dd>INPUT; CHAR(20)
|
||
|
|
|
||
|
|
<p>The name of the message queue and library containing the inquiry message.
|
||
|
|
The message queue name is a 10-character field that is left-justified and
|
||
|
|
padded with blanks if the name is less than 10 characters. The 10-character
|
||
|
|
message queue name is followed by the 10-character library name that is padded
|
||
|
|
with blanks to the right, if necessary. A special value of *EXT will be used
|
||
|
|
for the message queue name with blanks for the library name to indicate the
|
||
|
|
inquiry message was sent to the job's external message queue.</p>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><strong>Message key</strong></dt>
|
||
|
|
|
||
|
|
<dd>INPUT; CHAR(4)
|
||
|
|
|
||
|
|
<p>The message reference key of the inquiry message that is being replied
|
||
|
|
to.</p>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><strong>Message identifier</strong></dt>
|
||
|
|
|
||
|
|
<dd>INPUT; CHAR(7)
|
||
|
|
|
||
|
|
<p>The message identifier of the inquiry message that is being replied to. This
|
||
|
|
value will be blank for an impromptu message.</p>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><strong>Reply</strong></dt>
|
||
|
|
|
||
|
|
<dd>I/O; CHAR(*)
|
||
|
|
|
||
|
|
<p>The reply to be sent to an inquiry message. If a reply is being replaced
|
||
|
|
by an exit program, the new reply value is specified in this parameter.</p>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><strong>Length of the reply</strong></dt>
|
||
|
|
|
||
|
|
<dd>I/O; BINARY(4)
|
||
|
|
|
||
|
|
<p>The length of the specified reply. The maximum value is 132. If a
|
||
|
|
reply is being replaced by an exit program, the length of the new reply
|
||
|
|
value is specified in this parameter. If a reply
|
||
|
|
is being replaced with a default reply value, a value of
|
||
|
|
0 can be specified.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><strong>CCSID of the reply</strong></dt>
|
||
|
|
|
||
|
|
<dd>I/O; BINARY(4)
|
||
|
|
|
||
|
|
<p>The coded character set identifier of the specified reply. If a reply
|
||
|
|
is being replaced, the CCSID of the reply is specified in this parameter.
|
||
|
|
|
||
|
|
The valid values are:</p>
|
||
|
|
|
||
|
|
<table cellpadding="5">
|
||
|
|
<!-- cols="15 85" -->
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>0</em></td>
|
||
|
|
<td align="left" valign="top">The message reply text is assumed
|
||
|
|
to be in the CCSID of the job running the exit program.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>65535</em></td>
|
||
|
|
<td align="left" valign="top">The message reply text will not be
|
||
|
|
converted.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>CCSID</em></td>
|
||
|
|
<td align="left" valign="top">Specify a valid CCSID that your message
|
||
|
|
reply text is in. Valid values are between 1 and 65535.
|
||
|
|
</td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
|
||
|
|
<p>For a list of valid CCSIDs, see <a href="../nls/rbagsccsidmsgsup2.htm">
|
||
|
|
CCSIDs: Message Support</a> in the Globalization topic.</p>
|
||
|
|
</dd>
|
||
|
|
</dl>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
<h3><a name="Header_179">Coded Character Set Identifier (CCSID)
|
||
|
|
Considerations</a></h3>
|
||
|
|
|
||
|
|
<p>If the inquiry message that this reply is being sent to is an impromptu
|
||
|
|
message, the text supplied on the reply parameter is assumed to be in the
|
||
|
|
CCSID of the job running this exit program unless the coded character set identifier
|
||
|
|
is supplied in the CCSID parameter. If the inquiry message that this reply is
|
||
|
|
being sent to is a predefined message, then the text supplied on the reply text
|
||
|
|
parameter is considered 65535 and is not converted. For more information about
|
||
|
|
message handler and its use of CCSIDs, see <em>CCSIDs: Message Support</em> in
|
||
|
|
the Globalization topic.</p>
|
||
|
|
|
||
|
|
<dl>
|
||
|
|
|
||
|
|
<dt><strong>Reply action return code</strong></dt>
|
||
|
|
|
||
|
|
<dd>OUTPUT; BINARY(4)
|
||
|
|
|
||
|
|
<p>The return code to indicate whether the reply should be rejected,
|
||
|
|
accepted, or replaced. The valid values are:</p>
|
||
|
|
|
||
|
|
<table cellpadding="5">
|
||
|
|
<!-- cols="5 95" -->
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>0</em></td>
|
||
|
|
<td align="left" valign="top">The reply should be rejected. Any exit program
|
||
|
|
that previously accepted the reply will be notified of the reply
|
||
|
|
rejection. Any remaining exit programs will not be called.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>1</em></td>
|
||
|
|
<td align="left" valign="top">The reply should be accepted. The next
|
||
|
|
exit program will be called or the reply will be sent if there are no
|
||
|
|
other exit programs.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>2</em></td>
|
||
|
|
<td align="left" valign="top">The reply should be replaced using the values
|
||
|
|
provided in parameters 5 through 7, reply, length of the reply, and CCSID
|
||
|
|
of the reply. If the replaced reply value is not valid,
|
||
|
|
or if the reply value is the same as the original reply value,
|
||
|
|
the send reply function will send one of these messages as a diagnostic
|
||
|
|
message to itself:
|
||
|
|
CPD2477 (Reply replaced by exit program not valid) or
|
||
|
|
CPD2478 (Reply replaced by exit program same as original reply value). Then
|
||
|
|
it will notify the exit program of the the error with a type of call value
|
||
|
|
of 5 and then act as if the exit program accepted the original value and the next
|
||
|
|
exit program will be called or the original reply will be sent if there are
|
||
|
|
no other exit programs. If the replaced reply is valid, any exit program
|
||
|
|
that previously accepted the reply will be notified of the reply
|
||
|
|
replacement. The remaining reply handling exit programs will be called
|
||
|
|
but they will not be allowed to reject or replace the reply. If there are
|
||
|
|
no remaining exit programs to call, the new reply value will be sent.</td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
|
||
|
|
<p><strong>Note:</strong> A value other than 0 or 2 will cause the reply to be
|
||
|
|
accepted.</p>
|
||
|
|
</dd>
|
||
|
|
</dl>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
|
||
|
|
|
||
|
|
<h3>Usage Notes</h3>
|
||
|
|
|
||
|
|
<ol>
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
<li>System debug breakpoints in reply handling exit programs will be ignored
|
||
|
|
while processing the reply handling exit point. When sending a reply
|
||
|
|
and a reply handling exit program is called, message
|
||
|
|
CPF195A (Breakpoint already run when notification received) will
|
||
|
|
be generated for any breakpoints set in the exit program.
|
||
|
|
<br>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
<li>A reply handling exit program can send a message other than an inquiry and
|
||
|
|
reply, but the program will get into a recursive loop if it tries to do
|
||
|
|
functions like the following that affect inquiry messages and their reply:
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li>send a reply to the inquiry message that it is being called to handle.</li>
|
||
|
|
|
||
|
|
<li>send a reply to any other inquiry message.</li>
|
||
|
|
|
||
|
|
<li>receive an unanswered inquiry message with the remove option set to
|
||
|
|
yes.</li>
|
||
|
|
|
||
|
|
<li>remove an unanswered inquiry message.</li>
|
||
|
|
|
||
|
|
<li>send an inquiry message to *EXT.</li>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<p>For example, a user enters a reply, so a reply handling exit program is
|
||
|
|
called. The exit program sends a reply to the inquiry (or tries to remove the
|
||
|
|
message, but the default reply must be sent first); this calls the exit program
|
||
|
|
again, causing a loop.</p>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>The time between checking if there is a reply for an inquiry and actually
|
||
|
|
sending the reply to the inquiry message will be greater with the use of reply
|
||
|
|
handling exit programs. If the message queue is not already allocated to the
|
||
|
|
job in which the reply is being sent, when the reply is sent it is implicitly
|
||
|
|
allocated internally for the duration of the send. This means that if there are
|
||
|
|
a number of exit programs to call or if an exit program runs for a long time,
|
||
|
|
other users or jobs trying to use the message queue can see CPF2477 (message
|
||
|
|
queue in use) more often if the exit programs could not complete during the
|
||
|
|
internal lock wait time built into message handling functions.<br>
|
||
|
|
<br>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
<li>Messages that provide information about reply rejection or
|
||
|
|
replacement should not be removed by an exit program. When
|
||
|
|
an exit program is receiving one of these messages, the
|
||
|
|
program should specify parameter values on the receive such
|
||
|
|
that it allows the messages to remain in the job log so they
|
||
|
|
are available to be received by other exit programs.<br>
|
||
|
|
<br>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>If an exit program uses a receive function to receive
|
||
|
|
additional information about the inquiry message on a
|
||
|
|
nonprogram (standard) message queue, it should:
|
||
|
|
<ul>
|
||
|
|
<li>use the receive nonprogram message API, QMHRCVM, and
|
||
|
|
</li>
|
||
|
|
<li>specify *SAME for the message action parameter.
|
||
|
|
</li>
|
||
|
|
</ul>
|
||
|
|
Using this value on the API will not change the status of the
|
||
|
|
message so other exit programs can still receive the
|
||
|
|
message, but it will also allow the receive to occur even
|
||
|
|
if the queue is implicitly locked due to a
|
||
|
|
break handling program or a receive message with a
|
||
|
|
wait time specified.
|
||
|
|
</li>
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
<li>Error situations:
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li>If an error occurs while retrieving the list of exit programs for the reply
|
||
|
|
handling exit point, the error will be left in the joblog and the reply will be
|
||
|
|
accepted as if no exit programs were specified for the exit point.</li>
|
||
|
|
|
||
|
|
<li>A reply will be accepted if a reply handling exit program:
|
||
|
|
<ul>
|
||
|
|
<li>cannot be found</li>
|
||
|
|
<li>specifies a return code that is not valid</li>
|
||
|
|
<li>sends any error messages</li>
|
||
|
|
<li>tries to replace a reply value with a reply that is not valid</li>
|
||
|
|
</ul></li>
|
||
|
|
|
||
|
|
<li>Any message resulting from calling the exit program (such as program not
|
||
|
|
found) or any message issued by the exit program will be left in the joblog. No
|
||
|
|
new or additional message will be sent to indicate that an error occurred or
|
||
|
|
that the return code was not valid.</li>
|
||
|
|
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>The send reply function is threadsafe. A reply handling exit program can be
|
||
|
|
called from within a multithreaded job. When a reply handling exit program is
|
||
|
|
added to the registration facility, it can specify a multithreaded job action.
|
||
|
|
One of the following actions will be taken in a multithreaded job, depending on
|
||
|
|
the value indicated by the registration facility:<br>
|
||
|
|
<br>
|
||
|
|
|
||
|
|
|
||
|
|
<table cellpadding="5">
|
||
|
|
<!-- cols="5 95" -->
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>1</em></td>
|
||
|
|
<td align="left" valign="top">The exit program will be called.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>2</em></td>
|
||
|
|
<td align="left" valign="top">The exit program will be called and then CPI3C80
|
||
|
|
(an exit program was called in a multithreaded job) will be issued as an
|
||
|
|
informational message to the caller of the send reply function for each exit
|
||
|
|
program with this value. If an exit program is called again for a reply being
|
||
|
|
rejected by another exit program, the CPI3C80 will not be resent.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>3</em></td>
|
||
|
|
<td align="left" valign="top">The exit program will NOT be called and CPF3C80
|
||
|
|
(an exit program was not called in a multithreaded job) will be issued as an
|
||
|
|
informational message to the caller of the send reply function for each exit
|
||
|
|
program with this value. For exit programs with this value, the exit point will
|
||
|
|
act as if the reply was accepted by the exit program and continue the function
|
||
|
|
of calling the next exit program or sending the reply.</td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
|
||
|
|
</ol>
|
||
|
|
|
||
|
|
<hr>
|
||
|
|
Exit program introduced: V5R2
|
||
|
|
|
||
|
|
<hr>
|
||
|
|
<table align="center" cellpadding="2" cellspacing="2">
|
||
|
|
<tr align="center">
|
||
|
|
<td valign="middle" align="center"><a href="#Top_Of_Page">Top</a> | <a href=
|
||
|
|
"mh1.htm">Message Handling APIs</a> | <a href="aplist.htm">APIs by
|
||
|
|
category</a></td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
</body>
|
||
|
|
</html>
|
||
|
|
|