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

567 lines
15 KiB
HTML
Raw Permalink Normal View History

2024-04-02 14:02:31 +00:00
<!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>Send Reply Message (QMHSNDRM) API</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. -->
<!-- MH1TEMP SCRIPT A converted by B2H R4.1 (346) (CMS) by HOLTJM at -->
<!-- RCHVMW2 on 26 Jan 1999 at 10:37:34 -->
<!-- Change History: -->
<!-- YYMMDD USERID Change description -->
<!--File Edited Oct 2001 by v2cdijab -->
<!--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>Send Reply Message (QMHSNDRM) API</h2>
<div class="box" style="width: 75%;">
<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%">Message key</td>
<td align="left" valign="top" width="20%">Input</td>
<td align="left" valign="top" width="20%">Char(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">Reply text</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Char(*)</td>
</tr>
<tr>
<td align="center" valign="top">4</td>
<td align="left" valign="top">Length of reply text</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Binary(4)</td>
</tr>
<tr>
<td align="center" valign="top">5</td>
<td align="left" valign="top">Remove message</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Char(10)</td>
</tr>
<tr>
<td align="center" valign="top">6</td>
<td align="left" valign="top">Error code</td>
<td align="left" valign="top">I/O</td>
<td align="left" valign="top">Char(*)</td>
</tr>
</table>
<br>
&nbsp;&nbsp;Optional Parameter Group 1:<br>
<!-- iddvc RMBR -->
<br>
<table width="100%">
<tr>
<td align="center" valign="top" width="10%">7</td>
<td align="left" valign="top" width="50%">Coded character set identifier</td>
<td align="left" valign="top" width="20%">Input</td>
<td align="left" valign="top" width="20%">Binary(4)</td>
</tr>
</table>
<br>
&nbsp;&nbsp;Optional Parameter Group 2:<br>
<!-- iddvc RMBR -->
<br>
<table width="100%">
<tr>
<td align="center" valign="top" width="10%">8</td>
<td align="left" valign="top" width="50%">Allow default
reply rejection</td>
<td align="left" valign="top" width="20%">Input</td>
<td align="left" valign="top" width="20%">Char(10)</td>
</tr>
</table>
<br>
&nbsp;&nbsp;Default Public Authority: *USE<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;Threadsafe: Yes<br>
<!-- iddvc RMBR -->
<br>
</div>
<p>The Send Reply Message (QMHSNDRM) API sends a reply message to the sender of
an inquiry message.</p>
<p>If your application attempts to diagnose and recover from errors, it might
need to take additional action when using the QMHSNDRM API. When the QMHSNDRM
API encounters errors in the reply being sent, it sends a diagnostic message
describing each error to your program message queue. After the last diagnostic
message, the QMHSNDRM API sends a general escape message, CPF2422. Exit point
QIBM_QMH_REPLY_INQ has been added to the system registration facility to allow
an exit program to be called when a reply is sent to an inquiry message. A reply
handling exit program can accept, reject or replace the reply value. If the
reply is rejected, a diagnostic is sent followed by CPF2422 as indicated
above. If the reply value sent with this API is replaced by a reply handling
exit program, CPF2458 (Reply replaced by reply handling exit program) is sent
as a diagnostic message to the caller of the QMHSNDRM API to identify the new
reply value and then the CPF2458 is sent again as a status message that could
be monitored to allow an application to be notified of the reply replacement.</p>
<p>To diagnose and recover from these errors, your application should call the
QMHRCVPM API to receive the diagnostic messages sent.</p>
<br>
<h3>Authorities and Locks</h3>
<dl>
<dt><em>Message File Authority</em></dt>
<dd>*USE</dd>
<dt><em>Message File Library Authority</em></dt>
<dd>*EXECUTE</dd>
<dt><em>Message Queue Authority</em></dt>
<dd>*USE and *ADD. Also need *DLT to remove a message.</dd>
<dt><em>Message Queue Library Authority</em></dt>
<dd>*EXECUTE<br>
<br>
</dd>
</dl>
<br>
<h3>Required Parameter Group</h3>
<dl>
<dt><strong>Message key</strong></dt>
<dd>INPUT; CHAR(4)
<p>The key to the inquiry message that the reply answers. The key is assigned
by the command or API that sends the message. You can obtain the key in these
ways:</p>
<ul>
<li>By receiving an inquiry message with any of the following:
<ul>
<li>Receive Message (RCVMSG) command</li>
<li>Receive Program Message (QMHRCVPM) API</li>
<li>Receive Nonprogram Message (QMHRCVM) API</li>
<li>List Messages (QMHLSTM) API</li>
<li>List Job Log (QMHLJOBL) API</li>
</ul>
</li>
<li>Through a break-handling program. See the <a href="../rbam6/clpro.htm">CL Programming</a> topic for more information.</li>
</ul>
<br>
</dd>
<dt><strong>Qualified message queue name</strong></dt>
<dd>INPUT; CHAR(20)
<p>The name of the message queue containing the inquiry message being answered,
and the library in which it resides. The message queue is the one in which the
inquiry--not the sender's copy--is located. The first 10 characters specify the
message queue, and the second 10 characters specify the library. You can use
these special values for the library name:</p>
<table cellpadding="5">
<!-- cols="15 85" -->
<tr>
<td align="left" valign="top"><em>*CURLIB</em></td>
<td align="left" valign="top">The job's current library</td>
</tr>
<tr>
<td align="left" valign="top"><em>*LIBL</em></td>
<td align="left" valign="top">The library list</td>
</tr>
</table>
<br>
</dd>
<dt><strong>Reply text</strong></dt>
<dd>INPUT; CHAR(*)
<p>The complete text of the reply being sent. To send the default reply stored
in the message description, use blanks for this parameter.
A reply handling exit program
can be used to limit the use of default replies. See the allow default reply
rejection parameter below for more information.
</p>
</dd>
<dt><strong>Length of reply text</strong></dt>
<dd>INPUT; BINARY(4)
<p>The length of the reply text, in bytes. If you use blanks in the reply text
parameter to indicate that you are using the default reply, you can specify any
valid value for this parameter. Valid values are 1 through 132.</p>
</dd>
<dt><strong>Remove message</strong></dt>
<dd>INPUT; CHAR(10)
<p>Whether the inquiry message and the reply are removed from the message queue
after the reply is sent. Valid values follow:</p>
<table cellpadding="5">
<!-- cols="10 90" -->
<tr>
<td align="left" valign="top"><em>*NO</em></td>
<td align="left" valign="top">Keep the inquiry message and the reply.</td>
</tr>
<tr>
<td align="left" valign="top"><em>*YES</em></td>
<td align="left" valign="top">Remove the inquiry message and the reply.</td>
</tr>
</table>
<br>
</dd>
<dt><strong>Error code</strong></dt>
<dd>I/O; CHAR(*)
<p>The structure in which to return error information. For the format of the
structure, see <a href="../apiref/error.htm#hdrerrcod">Error Code Parameter</a>.</p>
</dd>
</dl>
<br>
<h3>Optional Parameter Group 1</h3>
<dl>
<dt><strong>Coded character set identifier</strong></dt>
<dd>INPUT; BINARY(4)
<p>The coded character set identifier (CCSID) that the supplied message reply
text is in. The following values are allowed:</p>
<table cellpadding="5">
<!-- cols="10 90" -->
<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 this API. This is the default value if this parameter
is not specified.</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. This API will validate the
CCSID.</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>
<h3>Optional Parameter Group 2</h3>
<dl>
<dt><strong>Allow default reply rejection</strong></dt>
<dd>INPUT; CHAR(10)
<p>Specifies whether a reply handling exit program will be
allowed to reject a default reply. A default reply is
requested by using blanks as the value for the
reply text parameter. A reply handling exit program can
be registered using the system registration facility for exit point
QIBM_QMH_REPLY_INQ. If this parameter is not specified, a value
of *NO is used. Valid values are: </p>
<table cellpadding="5">
<!-- cols="10 90" -->
<tr>
<td align="left" valign="top"><em>*NO</em></td>
<td align="left" valign="top">A reply handling exit program will
not be allowed to reject a default reply.
</td>
</tr>
<tr>
<td align="left" valign="top"><em>*YES</em></td>
<td align="left" valign="top">A reply handling exit program will
be allowed to reject a default reply. If an exit program rejects
the reply, a CPD2476 (Reply rejected by a reply handling exit
program) will be sent as a diagnostic message to the program
using this function. The CPD2476 will be followed by a
CPF2422 (Reply not valid) escape message that the program using
this function should monitor for to handle and recover from
error situations.
<br>
</td>
</tr>
</table>
<p><strong>Note: </strong>If a default reply is not being sent,
this parameter is ignored and a reply handling exit program
can reject or replace the reply value.</p>
</dd>
</dl>
<br>
<h3>Coded Character Set Identifier (CCSID) Considerations</h3>
<p>If the inquiry message that this reply is being sent to is an impromptu
message, the text supplied on the reply text parameter is assumed to be in the
CCSID of the job executing this API 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>
<br>
<h3>Error Messages</h3>
<table width="100%" cellpadding="5">
<!-- cols="15 85" -->
<tr>
<th align="left" valign="top">Message ID</th>
<th align="left" valign="top">Error Message Text</th>
</tr>
<tr>
<td align="left" valign="top">CPF24A4 E</td>
<td align="left" valign="top">Value for remove message not
valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF24B4 E</td>
<td align="left" valign="top">Severe error while addressing parameter
list.</td>
</tr>
<tr>
<td align="left" valign="top">CPF24B6 E</td>
<td align="left" valign="top">Length of &amp;1, not valid for message text or
data.</td>
</tr>
<tr>
<td align="left" valign="top">CPF2401 E</td>
<td align="left" valign="top">Not authorized to library &amp;1.</td>
</tr>
<tr>
<td align="left" valign="top">CPF2403 E</td>
<td align="left" valign="top">Message queue &amp;1 in &amp;2 not found.</td>
</tr>
<tr>
<td align="left" valign="top">CPF2408 E</td>
<td align="left" valign="top">Not authorized to message queue &amp;1.</td>
</tr>
<tr>
<td align="left" valign="top">CPF2410 E</td>
<td align="left" valign="top">Message key not found in message queue
&amp;1.</td>
</tr>
<tr>
<td align="left" valign="top">CPF2420 E</td>
<td align="left" valign="top">Reply already sent for inquiry or notify
message.</td>
</tr>
<tr>
<td align="left" valign="top">CPF2422 E</td>
<td align="left" valign="top">Reply not valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF2432 E</td>
<td align="left" valign="top">Cannot send reply to message type other than *INQ
or *NOTIFY.</td>
</tr>
<tr>
<td align="left" valign="top">CPF2433 E</td>
<td align="left" valign="top">Function not allowed for system log message queue
&amp;1.</td>
</tr>
<tr>
<td align="left" valign="top">CPF2439 E</td>
<td align="left" valign="top">Reply value entered is not valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF2440 E</td>
<td align="left" valign="top">Reply must be in range of &amp;1 to &amp;2.</td>
</tr>
<tr>
<td align="left" valign="top">CPF2442 E</td>
<td align="left" valign="top">Reply does not meet specified relations.</td>
</tr>
<tr>
<td align="left" valign="top">CPF2460 E</td>
<td align="left" valign="top">Message queue &amp;1 could not be extended.</td>
</tr>
<tr>
<td align="left" valign="top">CPF2458 S</td>
<td align="left" valign="top">Reply replaced by reply handling exit program.
</td>
</tr>
<tr>
<td align="left" valign="top">CPF2466 E</td>
<td align="left" valign="top">Reply length greater than &amp;1.</td>
</tr>
<tr>
<td align="left" valign="top">CPF247E E</td>
<td align="left" valign="top">CCSID &amp;1 is not valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF2477 E</td>
<td align="left" valign="top">Message queue &amp;1 currently in use.</td>
</tr>
<tr>
<td align="left" valign="top">CPF2547 E</td>
<td align="left" valign="top">Damage to message file QCPFMSG.</td>
</tr>
<tr>
<td align="left" valign="top">CPF2548 E</td>
<td align="left" valign="top">Damage to message file &amp;1 in &amp;2.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3CF1 E</td>
<td align="left" valign="top">Error code parameter not valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3C3A E</td>
<td align="left" valign="top">Value for parameter &amp;2 for API &amp;1 not valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3C36 E</td>
<td align="left" valign="top">Number of parameters, &amp;1, entered for this
API was not valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3C90 E</td>
<td align="left" valign="top">Literal value cannot be changed.</td>
</tr>
<tr>
<td align="left" valign="top">CPF8100 E</td>
<td align="left" valign="top">All CPF81xx messages could be returned. xx is
from 01 to FF.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9830 E</td>
<td align="left" valign="top">Cannot assign library &amp;1.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9838 E</td>
<td align="left" valign="top">User profile storage limit exceeded.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9872 E</td>
<td align="left" valign="top">Program or service program &amp;1 in library
&amp;2 ended. Reason code &amp;3.</td>
</tr>
</table>
<br>
<hr>
API introduced: V2R1.1
<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>