ibm-information-center/dist/eclipse/plugins/i5OS.ic.apis_5.4.0.1/XREPLY.htm

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>
&nbsp;&nbsp;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>
&nbsp;&nbsp;Exit Point Name: QIBM_QMH_REPLY_INQ<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;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>