1666 lines
52 KiB
HTML
1666 lines
52 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>Receive Nonprogram Message (QMHRCVM) 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. -->
|
||
|
<!-- AMHRCVM SCRIPT A converted by B2H R4.1 (346) (CMS) by HOLTJM at -->
|
||
|
<!-- RCHVMW2 on 28 Jan 1999 at 12:17:55 -->
|
||
|
<!-- 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 type="text/javascript" language="Javascript" src="../rzahg/synch.js">
|
||
|
</script>
|
||
|
|
||
|
<h2>Receive Nonprogram Message (QMHRCVM) API</h2>
|
||
|
|
||
|
<div class="box" style="width: 75%;">
|
||
|
<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%">Message information</td>
|
||
|
<td align="left" valign="top" width="20%">Output</td>
|
||
|
<td align="left" valign="top" width="20%">Char(*)</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="center" valign="top">2</td>
|
||
|
<td align="left" valign="top">Length of message information</td>
|
||
|
<td align="left" valign="top">Input</td>
|
||
|
<td align="left" valign="top">Binary(4)</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="center" valign="top">3</td>
|
||
|
<td align="left" valign="top">Format name</td>
|
||
|
<td align="left" valign="top">Input</td>
|
||
|
<td align="left" valign="top">Char(8)</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="center" valign="top">4</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">5</td>
|
||
|
<td align="left" valign="top">Message type</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">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">7</td>
|
||
|
<td align="left" valign="top">Wait time</td>
|
||
|
<td align="left" valign="top">Input</td>
|
||
|
<td align="left" valign="top">Binary(4)</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="center" valign="top">8</td>
|
||
|
<td align="left" valign="top">Message action</td>
|
||
|
<td align="left" valign="top">Input</td>
|
||
|
<td align="left" valign="top">Char(10)</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="center" valign="top">9</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>
|
||
|
Optional Parameter Group 1:<br>
|
||
|
<!-- iddvc RMBR -->
|
||
|
|
||
|
<br>
|
||
|
<table width="100%">
|
||
|
|
||
|
<tr>
|
||
|
<td align="center" valign="top" width="10%">10</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>
|
||
|
Optional Parameter Group 2:<br>
|
||
|
<!-- iddvc RMBR -->
|
||
|
<br>
|
||
|
<table width="100%">
|
||
|
|
||
|
<tr>
|
||
|
<td align="center" valign="top" width="10%">11</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>
|
||
|
Default Public Authority: *USE<br>
|
||
|
<!-- iddvc RMBR -->
|
||
|
<br>
|
||
|
Threadsafe: Yes<br>
|
||
|
<!-- iddvc RMBR -->
|
||
|
<br>
|
||
|
</div>
|
||
|
|
||
|
<p>The Receive Nonprogram Message (QMHRCVM) API receives a message from a
|
||
|
nonprogram message queue. To receive a message from a program message queue or
|
||
|
from the external message queue, see <a href="QMHRCVPM.htm">Receive Program
|
||
|
Message</a> API.</p>
|
||
|
|
||
|
<br>
|
||
|
|
||
|
|
||
|
<h3>Authorities and Locks</h3>
|
||
|
|
||
|
<dl>
|
||
|
<dt><em>Message Queue Authority</em></dt>
|
||
|
|
||
|
<dd>*USE and *DLT if the message action parameter specifies *REMOVE; *USE for
|
||
|
other message actions.<br>
|
||
|
<br>
|
||
|
</dd>
|
||
|
|
||
|
<dt><em>Message Queue Library Authority</em></dt>
|
||
|
|
||
|
<dd>*EXECUTE<br></dd>
|
||
|
|
||
|
<dt><em>Message File Authority</em></dt>
|
||
|
<dd>*USE, if receiving a predefined message and the message file used when the message was sent was deleted and recreated.<br>
|
||
|
<br>
|
||
|
</dd>
|
||
|
|
||
|
|
||
|
<dt><em>Message File Library Authority</em></dt>
|
||
|
|
||
|
<dd>*EXECUTE, if receiving a predefined message and the message file used when the message was sent was deleted and recreated.
|
||
|
<br>
|
||
|
<br>
|
||
|
</dd>
|
||
|
|
||
|
<dt><em>Message Queue Lock</em></dt>
|
||
|
|
||
|
<dd>If a wait time is specified and the API must wait, the message queue is
|
||
|
allocated to the job calling the API for the duration of the wait.
|
||
|
|
||
|
<p>Other jobs on the system can only send messages to the queue during the wait
|
||
|
time. Other jobs cannot place the queue in *BREAK or *NOTIFY mode, remove
|
||
|
messages from the queue, or do an additional receive message with wait
|
||
|
operation during this time.</p>
|
||
|
</dd>
|
||
|
</dl>
|
||
|
|
||
|
<br>
|
||
|
|
||
|
|
||
|
<h3>Required Parameter Group</h3>
|
||
|
|
||
|
<dl>
|
||
|
<dt><strong>Message information</strong></dt>
|
||
|
|
||
|
<dd>OUTPUT; CHAR(*)
|
||
|
|
||
|
<p>The variable that receives the information returned, in the format specified
|
||
|
by the format name parameter, of the length specified by the length of message
|
||
|
information parameter.</p>
|
||
|
</dd>
|
||
|
|
||
|
<dt><strong>Length of message information</strong></dt>
|
||
|
|
||
|
<dd>INPUT; BINARY(4)
|
||
|
|
||
|
<p>The size of the area to contain the message information, in bytes. The
|
||
|
minimum size is 8.</p>
|
||
|
|
||
|
<p>This parameter must specify the size of the variable you use for the message
|
||
|
information parameter. If this parameter specifies a longer size, other parts
|
||
|
of storage could be overwritten when the API returns the information.</p>
|
||
|
|
||
|
<p>The API returns as much information as it can fit in this length. If the
|
||
|
available message information is longer, it is truncated. If the available
|
||
|
message information is shorter, the unused output area is unchanged; whatever
|
||
|
is already stored in that space remains there.</p>
|
||
|
|
||
|
<p>To determine how much information the API actually returns in response to
|
||
|
this call, see the bytes returned field in the RCVM0100 or RCVM0200 output. To
|
||
|
determine how much information the API could return if space were available,
|
||
|
see the bytes available field.</p>
|
||
|
</dd>
|
||
|
|
||
|
<dt><strong>Format name</strong></dt>
|
||
|
|
||
|
<dd>INPUT; CHAR(8)
|
||
|
|
||
|
<p>The format to use for the message information. Specify one of these format
|
||
|
names:</p>
|
||
|
|
||
|
<table cellpadding="5">
|
||
|
<!-- cols="15 85" -->
|
||
|
<tr>
|
||
|
<td align="left" valign="top"><em>RCVM0100</em></td>
|
||
|
<td align="left" valign="top">Brief message information. For details, see <a
|
||
|
href="#HDRRCVM1">RCVM0100 Format</a>.</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top"><em>RCVM0200</em></td>
|
||
|
<td align="left" valign="top">All message information. For details, see <a
|
||
|
href="#HDRRCVM2">RCVM0200 Format</a>.</td>
|
||
|
</tr>
|
||
|
</table>
|
||
|
|
||
|
<br>
|
||
|
</dd>
|
||
|
|
||
|
<dt><strong>Qualified message queue name</strong></dt>
|
||
|
|
||
|
<dd>INPUT; CHAR(20)
|
||
|
|
||
|
<p>The name of the message queue from which to receive the message, and the
|
||
|
library in which it resides. 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>
|
||
|
|
||
|
<p>You cannot receive messages from the history log, QHST.</p>
|
||
|
</dd>
|
||
|
|
||
|
<dt><strong>Message type</strong></dt>
|
||
|
|
||
|
<dd>INPUT; CHAR(10)
|
||
|
|
||
|
<p>The type of the message being received. The message type and message key
|
||
|
parameters work together. Depending on the message type, the key can be
|
||
|
required, optional, or disallowed. For a list of valid message types and
|
||
|
information about how they work with the message key parameter, see <a href=
|
||
|
"#HDRMSGKEYB">Message Types and Message Keys</a>.</p>
|
||
|
</dd>
|
||
|
|
||
|
<dt><strong>Message key</strong></dt>
|
||
|
|
||
|
<dd>INPUT; CHAR(4)
|
||
|
|
||
|
<p>The key to the message being received. The key is assigned by the command or
|
||
|
API that sends the message.</p>
|
||
|
|
||
|
<p>What you can use for this parameter depends on what you use for the message
|
||
|
type. For details, see <a href="#HDRMSGKEYB">Message Types and Message
|
||
|
Keys</a>.</p>
|
||
|
|
||
|
<p>If you are not receiving messages by key, use blanks for this parameter.</p>
|
||
|
|
||
|
<p>If you specify a key and the message queue does not contain a message with
|
||
|
that key, an error is returned.</p>
|
||
|
|
||
|
<p>If you specify a key and the message queue does contain a message with that
|
||
|
key, the API might or might not return a message. It never returns an error in
|
||
|
this case. Whether or not the API returns a message depends on the value of the
|
||
|
message type parameter. For example, if you specify the message type *PRV and
|
||
|
there is no message before the message with the key, the API does not return a
|
||
|
message. Because the key you specified is valid, the API does not return an
|
||
|
error either.</p>
|
||
|
|
||
|
<p>You can receive the reply to an inquiry message through the key to the
|
||
|
sender's copy of the inquiry. If the reply is not available, no message is
|
||
|
returned, and the API does not return an error.</p>
|
||
|
|
||
|
<p>When the message type is the special value *NEXT, you can use the special
|
||
|
value *TOP for the message key. *TOP returns the message at the top of the
|
||
|
queue.</p>
|
||
|
|
||
|
<p>When the message type is the special value *NEXT or *PRV, you can use
|
||
|
hexadecimal zeros for the message key for the first receive operation.</p>
|
||
|
</dd>
|
||
|
|
||
|
<dt><strong>Wait time</strong></dt>
|
||
|
|
||
|
<dd>INPUT; BINARY(4)
|
||
|
|
||
|
<p>The length of time in seconds
|
||
|
to wait for the message to
|
||
|
arrive in the queue so it can be received.</p>
|
||
|
|
||
|
<p>The system ignores this parameter when you specify both a message key and a
|
||
|
message type other than reply (*RPY). The parameter is used in only two
|
||
|
cases:</p>
|
||
|
|
||
|
<ol>
|
||
|
<li>The message type is reply (*RPY), and the message key parameter specifies
|
||
|
the key to the sender's copy of the message.<br>
|
||
|
<br>
|
||
|
</li>
|
||
|
|
||
|
<li>The message type is anything except reply (*RPY), and the message key
|
||
|
parameter is blank. In this case, the QMHRCVM API does not use the wait time
|
||
|
parameter immediately. First, the API checks the queue for the first message of
|
||
|
that type that has not been received. If no such message is found, the API then
|
||
|
waits the specified length of time for a message to arrive.</li>
|
||
|
</ol>
|
||
|
|
||
|
<p>Valid values follow:</p>
|
||
|
|
||
|
<table cellpadding="5">
|
||
|
<!-- cols="15 85" -->
|
||
|
<tr>
|
||
|
<td align="left" valign="top"><em>0</em></td>
|
||
|
<td align="left" valign="top">Do not wait for the message. You must use 0 if
|
||
|
you specify a message key and the message is not a reply message.</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top"><em>-1</em></td>
|
||
|
<td align="left" valign="top">Wait until the message arrives in the queue and
|
||
|
is received, no matter how long it takes. The system has no limit for the wait
|
||
|
time.</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top"><em>n (any positive number)</em></td>
|
||
|
<td align="left" valign="top">Wait <strong>n</strong> seconds for the message
|
||
|
to arrive in the queue.</td>
|
||
|
</tr>
|
||
|
</table>
|
||
|
|
||
|
<p>If you specify a value of zero or above and the message does not arrive in
|
||
|
the specified time, most fields in the RCVM0100 or RCVM0200 output are
|
||
|
unchanged. The bytes returned output field has a value of 8, and the bytes
|
||
|
available output field has a value of 0. The remaining output fields are
|
||
|
unchanged; they contain whatever was already stored in the space.</p>
|
||
|
</dd>
|
||
|
|
||
|
<dt><strong>Message action</strong></dt>
|
||
|
|
||
|
<dd>INPUT; CHAR(10)
|
||
|
|
||
|
<p>The action to take after the message is received. Valid values follow:</p>
|
||
|
|
||
|
<table cellpadding="5">
|
||
|
<!-- cols="15 85" -->
|
||
|
<tr>
|
||
|
<td align="left" valign="top"><em>*OLD</em></td>
|
||
|
<td align="left" valign="top">Keep the message in the message queue and mark it
|
||
|
as an old message. You can receive the message again only by using the message
|
||
|
key or by specifying the message type *NEXT, *PRV (previous), *FIRST, or
|
||
|
*LAST.</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top"><em>*REMOVE</em></td>
|
||
|
<td align="left" valign="top">Remove the message from the message queue. The
|
||
|
message key is no longer valid, so you cannot receive the message again.</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top"><em>*SAME</em></td>
|
||
|
<td align="left" valign="top">Keep the message in the message queue without
|
||
|
changing its new or old designation. *SAME lets you receive the message again
|
||
|
later without using the message key.</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) in which that you want your
|
||
|
message text and replacement data returned. This applies to the message text
|
||
|
and the parts of the replacement data defined as a convertible character field
|
||
|
(*CCHAR). For more information about *CCHAR fields, see the <a href=
|
||
|
"../cl/addmsgd.htm">Add Message Description (ADDMSGD) Command</a>. The
|
||
|
following values are allowed:</p>
|
||
|
|
||
|
<table cellpadding="5">
|
||
|
<!-- cols="15 85" -->
|
||
|
<tr>
|
||
|
<td align="left" valign="top"><em>0</em></td>
|
||
|
<td align="left" valign="top">The received message is converted to the CCSID of
|
||
|
the job before being returned. This is the default value if this parameter is
|
||
|
not coded.
|
||
|
|
||
|
<p>If the job is 65535 and the text or data is something other than EBCDIC
|
||
|
single byte or EBCDIC mixed, the text and data are converted to the default job
|
||
|
CCSID.</p>
|
||
|
</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top"><em>65535</em></td>
|
||
|
<td align="left" valign="top">The received message will not be converted before
|
||
|
being returned.<br>
|
||
|
<br>
|
||
|
</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top"><em>CCSID</em></td>
|
||
|
<td align="left" valign="top">Specify a CCSID you want your text and data
|
||
|
converted to before being returned. Only CCSIDs that a job can be changed to
|
||
|
are acceptable values. This API will validate the CCSID specified.</td>
|
||
|
</tr>
|
||
|
</table>
|
||
|
|
||
|
<p><strong>Note:</strong> If an invalid CCSID conversion is detected during the
|
||
|
receive function, the data is not converted before it is returned. The CCSID
|
||
|
conversion status field should be checked to determine if an error
|
||
|
occurred.</p>
|
||
|
|
||
|
<p>For more information about message handler and its use of 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>Removing an unanswered inquiry causes the default reply to be
|
||
|
sent to the inquiry message. This value indicates whether a
|
||
|
reply handling exit program will be allowed to reject a
|
||
|
default reply that is sent as a result of using this
|
||
|
function. A reply handling exit program can be registered via
|
||
|
the system registration facility for exit point
|
||
|
QIBM_QMH_REPLY_INQ. If this parameter is not specified, a value
|
||
|
of *NO is used. This parameter is only applicable
|
||
|
when *REMOVE is specified for the message action
|
||
|
parameter. Valid values are: </p>
|
||
|
|
||
|
<table cellpadding="5">
|
||
|
<!-- cols="15 85" -->
|
||
|
<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>
|
||
|
|
||
|
</dd>
|
||
|
</dl>
|
||
|
|
||
|
|
||
|
<h3><a name="HDRMSGKEYB">Message Types and Message Keys</a></h3>
|
||
|
|
||
|
<p>The message type and message key parameters work together. Depending on the
|
||
|
message type, the key can be required, optional, or disallowed. The following
|
||
|
table lists each message type you can specify, tells whether it requires a key,
|
||
|
and gives other information about using that type.</p>
|
||
|
|
||
|
<p>When used without a key, most message types receive only new messages. When
|
||
|
used with a key, most can receive old or new messages. Message types *FIRST,
|
||
|
*LAST, *PRV (previous), and *NEXT always receive both old and new messages.</p>
|
||
|
|
||
|
<p><strong>New messages</strong> are messages that have been sent to a queue
|
||
|
and have not yet been received. <strong>Old messages</strong> are messages that
|
||
|
have been received but have not yet been removed from the queue.</p>
|
||
|
|
||
|
<p>All message types listed in the following table are received in first-in
|
||
|
first-out (FIFO) order.</p>
|
||
|
|
||
|
<p>The following terms are used to describe the message key in the following
|
||
|
table:</p>
|
||
|
|
||
|
<table cellpadding="5">
|
||
|
<!-- cols="15 85" -->
|
||
|
<tr>
|
||
|
<td align="left" valign="top"><em>Disallowed</em></td>
|
||
|
<td align="left" valign="top">Do not specify a message key. Instead, use blanks
|
||
|
for the message key parameter. Specifying a message key results in an
|
||
|
error.</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top"><em>Required</em></td>
|
||
|
<td align="left" valign="top">Specify a message key. Not specifying a message
|
||
|
key results in an error.</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top"><em>Optional</em></td>
|
||
|
<td align="left" valign="top">You can either specify a message key or use
|
||
|
blanks for the message key parameter.
|
||
|
|
||
|
<p>When you do not specify a message key, the first new message of the
|
||
|
specified type is received. If a new message of that type is not in the message
|
||
|
queue, no error is returned. The unused space allowed for the output in the
|
||
|
message information parameter is unchanged.</p>
|
||
|
|
||
|
<p>When you specify a message key and the message in the message queue is of
|
||
|
the type specified, the message is received. If the message is not found, or if
|
||
|
the message found does not match the type specified, an error code or exception
|
||
|
is returned.</p>
|
||
|
</td>
|
||
|
</tr>
|
||
|
</table>
|
||
|
|
||
|
<p>There are two cases where the message is not found and no error is returned.
|
||
|
In both cases, the bytes returned field equals 8 and the bytes available field
|
||
|
equals 0. The two cases are:</p>
|
||
|
|
||
|
<ul>
|
||
|
<li>Receiving without a message key (the key is optional or disallowed). A
|
||
|
message of the specified type is not found in the queue.<br>
|
||
|
<br>
|
||
|
</li>
|
||
|
|
||
|
<li>Receiving with a message key (the key is required) and the message type is
|
||
|
*PRV or *NEXT. The message with the key specified was found in the queue, but
|
||
|
no *PRV or *NEXT message is found.</li>
|
||
|
</ul>
|
||
|
|
||
|
<p>The message types you can specify in the QMHRCVM API follow:</p>
|
||
|
|
||
|
<table>
|
||
|
<tr>
|
||
|
|
||
|
<th align="left" valign="bottom">Message Type</th>
|
||
|
<th align="left" valign="bottom">Message Key</th>
|
||
|
<th align="left" valign="bottom">Description</th>
|
||
|
</tr>
|
||
|
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top" width="15%">*ANY</td>
|
||
|
<td align="left" valign="top" width="15%">Optional</td>
|
||
|
<td align="left" valign="top" width="70%">Receives a message of any type except
|
||
|
sender's copy.</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top">*COMP</td>
|
||
|
<td align="left" valign="top">Optional</td>
|
||
|
<td align="left" valign="top">Receives a completion message.</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top">*COPY</td>
|
||
|
<td align="left" valign="top">Required</td>
|
||
|
<td align="left" valign="top">Receives the sender's copy of a previously sent
|
||
|
inquiry message. The qualified message queue name parameter must specify the
|
||
|
reply message queue specified when the inquiry was sent.</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top">*DIAG</td>
|
||
|
<td align="left" valign="top">Optional</td>
|
||
|
<td align="left" valign="top">Receives a diagnostic message.</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top">*FIRST</td>
|
||
|
<td align="left" valign="top">Disallowed</td>
|
||
|
<td align="left" valign="top">Receives the first new or old message in the
|
||
|
queue.</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top">*INFO</td>
|
||
|
<td align="left" valign="top">Optional</td>
|
||
|
<td align="left" valign="top">Receives an informational message.</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top">*INQ</td>
|
||
|
<td align="left" valign="top">Optional</td>
|
||
|
<td align="left" valign="top">Receives an inquiry message. If the message
|
||
|
action is *REMOVE and a reply to the inquiry message has not been sent yet, the
|
||
|
default reply is automatically sent when the inquiry message is received.</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top">*LAST</td>
|
||
|
<td align="left" valign="top">Disallowed</td>
|
||
|
<td align="left" valign="top">Receives the last new or old message in the
|
||
|
queue.</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top">*NEXT</td>
|
||
|
<td align="left" valign="top">Required</td>
|
||
|
<td align="left" valign="top">Receives the next new or old message after the
|
||
|
message with the specified key.
|
||
|
|
||
|
<p>You can use the special value *TOP for the message key. *TOP designates the
|
||
|
message at the top of the message queue.</p>
|
||
|
|
||
|
<p>You can use hexadecimal zeros (hex 00000000) for the message key for the
|
||
|
first receive operation to receive the first message on the queue.</p>
|
||
|
</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top">*PRV</td>
|
||
|
<td align="left" valign="top">Required</td>
|
||
|
<td align="left" valign="top">Receives the new or old message before the
|
||
|
message with the specified key.
|
||
|
|
||
|
<p>You can use hexadecimal zeros (hex 00000000) for the message key for the
|
||
|
first receive operation to receive the last message on the queue.</p>
|
||
|
</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top">*RPY</td>
|
||
|
<td align="left" valign="top">Optional</td>
|
||
|
<td align="left" valign="top">Receives the reply to an inquiry message. For the
|
||
|
message key, you can use the key to the sender's copy of the inquiry or notify
|
||
|
message.</td>
|
||
|
</tr>
|
||
|
</table>
|
||
|
|
||
|
<br>
|
||
|
<br>
|
||
|
|
||
|
|
||
|
<h3><a name="HDRRCVM1">RCVM0100 Format</a></h3>
|
||
|
|
||
|
<p>The following table lists the fields returned in the RCVM0100 format. For
|
||
|
more information about each item of information, see <a href="#HDRRCVMFD">Field
|
||
|
Descriptions</a>.</p>
|
||
|
|
||
|
<table border width="80%">
|
||
|
<tr>
|
||
|
<th align="center" valign="bottom" colspan="2">Offset</th>
|
||
|
<th align="left" valign="bottom" rowspan="2">Type</th>
|
||
|
<th align="left" valign="bottom" rowspan="2">Field</th>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<th align="center" valign="bottom">Dec</th>
|
||
|
<th align="center" valign="bottom">Hex</th>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="center" valign="top" width="10%">0</td>
|
||
|
<td align="center" valign="top" width="10%">0</td>
|
||
|
<td align="left" valign="top" width="20%">BINARY(4)</td>
|
||
|
<td align="left" valign="top" width="60%">Bytes returned</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="center" valign="top">4</td>
|
||
|
<td align="center" valign="top">4</td>
|
||
|
<td align="left" valign="top">BINARY(4)</td>
|
||
|
<td align="left" valign="top">Bytes available</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="center" valign="top">8</td>
|
||
|
<td align="center" valign="top">8</td>
|
||
|
<td align="left" valign="top">BINARY(4)</td>
|
||
|
<td align="left" valign="top">Message severity</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="center" valign="top">12</td>
|
||
|
<td align="center" valign="top">C</td>
|
||
|
<td align="left" valign="top">CHAR(7)</td>
|
||
|
<td align="left" valign="top">Message identifier</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="center" valign="top">19</td>
|
||
|
<td align="center" valign="top">13</td>
|
||
|
<td align="left" valign="top">CHAR(2)</td>
|
||
|
<td align="left" valign="top">Message type</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="center" valign="top">21</td>
|
||
|
<td align="center" valign="top">15</td>
|
||
|
<td align="left" valign="top">CHAR(4)</td>
|
||
|
<td align="left" valign="top">Message key</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="center" valign="top">25</td>
|
||
|
<td align="center" valign="top">19</td>
|
||
|
<td align="left" valign="top">CHAR(7)</td>
|
||
|
<td align="left" valign="top">Reserved</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="center" valign="top">32</td>
|
||
|
<td align="center" valign="top">20</td>
|
||
|
<td align="left" valign="top">BINARY(4)</td>
|
||
|
<td align="left" valign="top">CCSID conversion status indicator of message data
|
||
|
or text</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="center" valign="top">36</td>
|
||
|
<td align="center" valign="top">24</td>
|
||
|
<td align="left" valign="top">BINARY(4)</td>
|
||
|
<td align="left" valign="top">CCSID of message data or text</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="center" valign="top">40</td>
|
||
|
<td align="center" valign="top">28</td>
|
||
|
<td align="left" valign="top">BINARY(4)</td>
|
||
|
<td align="left" valign="top">Length of replacement data or impromptu message
|
||
|
text returned</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="center" valign="top">44</td>
|
||
|
<td align="center" valign="top">2C</td>
|
||
|
<td align="left" valign="top">BINARY(4)</td>
|
||
|
<td align="left" valign="top">Length of replacement data or impromptu message
|
||
|
text available</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="center" valign="top">48</td>
|
||
|
<td align="center" valign="top">30</td>
|
||
|
<td align="left" valign="top">CHAR(*)</td>
|
||
|
<td align="left" valign="top">Replacement data or impromptu message text</td>
|
||
|
</tr>
|
||
|
</table>
|
||
|
|
||
|
<br>
|
||
|
<br>
|
||
|
|
||
|
|
||
|
<h3><a name="HDRRCVM2">RCVM0200 Format</a></h3>
|
||
|
|
||
|
<p>The following table lists the fields returned in the RCVM0200 format. For
|
||
|
more information about each item of information, see <a href="#HDRRCVMFD">Field
|
||
|
Descriptions</a>.</p>
|
||
|
|
||
|
<table border width="80%">
|
||
|
<tr>
|
||
|
<th align="center" valign="bottom" colspan="2">Offset</th>
|
||
|
<th align="left" valign="bottom" rowspan="2">Type</th>
|
||
|
<th align="left" valign="bottom" rowspan="2">Field</th>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<th align="center" valign="bottom">Dec</th>
|
||
|
<th align="center" valign="bottom">Hex</th>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="center" valign="top" width="10%">0</td>
|
||
|
<td align="center" valign="top" width="10%">0</td>
|
||
|
<td align="left" valign="top" width="20%">BINARY(4)</td>
|
||
|
<td align="left" valign="top" width="60%">Bytes returned</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="center" valign="top">4</td>
|
||
|
<td align="center" valign="top">4</td>
|
||
|
<td align="left" valign="top">BINARY(4)</td>
|
||
|
<td align="left" valign="top">Bytes available</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="center" valign="top">8</td>
|
||
|
<td align="center" valign="top">8</td>
|
||
|
<td align="left" valign="top">BINARY(4)</td>
|
||
|
<td align="left" valign="top">Message severity</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="center" valign="top">12</td>
|
||
|
<td align="center" valign="top">C</td>
|
||
|
<td align="left" valign="top">CHAR(7)</td>
|
||
|
<td align="left" valign="top">Message identifier</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="center" valign="top">19</td>
|
||
|
<td align="center" valign="top">13</td>
|
||
|
<td align="left" valign="top">CHAR(2)</td>
|
||
|
<td align="left" valign="top">Message type</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="center" valign="top">21</td>
|
||
|
<td align="center" valign="top">15</td>
|
||
|
<td align="left" valign="top">CHAR(4)</td>
|
||
|
<td align="left" valign="top">Message key</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="center" valign="top">25</td>
|
||
|
<td align="center" valign="top">19</td>
|
||
|
<td align="left" valign="top">CHAR(10)</td>
|
||
|
<td align="left" valign="top">Message file name</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="center" valign="top">35</td>
|
||
|
<td align="center" valign="top">23</td>
|
||
|
<td align="left" valign="top">CHAR(10)</td>
|
||
|
<td align="left" valign="top">Message file library specified</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="center" valign="top">45</td>
|
||
|
<td align="center" valign="top">2D</td>
|
||
|
<td align="left" valign="top">CHAR(10)</td>
|
||
|
<td align="left" valign="top">Message file library used</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="center" valign="top">55</td>
|
||
|
<td align="center" valign="top">37</td>
|
||
|
<td align="left" valign="top">CHAR(10)</td>
|
||
|
<td align="left" valign="top">Sending job</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="center" valign="top">65</td>
|
||
|
<td align="center" valign="top">41</td>
|
||
|
<td align="left" valign="top">CHAR(10)</td>
|
||
|
<td align="left" valign="top">Sending job's user profile</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="center" valign="top">75</td>
|
||
|
<td align="center" valign="top">4B</td>
|
||
|
<td align="left" valign="top">CHAR(6)</td>
|
||
|
<td align="left" valign="top">Sending job's number</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="center" valign="top">81</td>
|
||
|
<td align="center" valign="top">51</td>
|
||
|
<td align="left" valign="top">CHAR(12)</td>
|
||
|
<td align="left" valign="top">Sending program name</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="center" valign="top">93</td>
|
||
|
<td align="center" valign="top">5D</td>
|
||
|
<td align="left" valign="top">CHAR(4)</td>
|
||
|
<td align="left" valign="top">Reserved</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="center" valign="top">97</td>
|
||
|
<td align="center" valign="top">61</td>
|
||
|
<td align="left" valign="top">CHAR(7)</td>
|
||
|
<td align="left" valign="top">Date sent</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="center" valign="top">104</td>
|
||
|
<td align="center" valign="top">68</td>
|
||
|
<td align="left" valign="top">CHAR(6)</td>
|
||
|
<td align="left" valign="top">Time sent</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="center" valign="top">110</td>
|
||
|
<td align="center" valign="top">6E</td>
|
||
|
<td align="left" valign="top">CHAR(6)</td>
|
||
|
<td align="left" valign="top">Microseconds</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="center" valign="top">116</td>
|
||
|
<td align="center" valign="top">74</td>
|
||
|
<td align="left" valign="top">CHAR(10)</td>
|
||
|
<td align="left" valign="top">Sending user profile</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="center" valign="top">126</td>
|
||
|
<td align="center" valign="top">7E</td>
|
||
|
<td align="left" valign="top">CHAR(1)</td>
|
||
|
<td align="left" valign="top">Reserved</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="center" valign="top">127</td>
|
||
|
<td align="center" valign="top">7F</td>
|
||
|
<td align="left" valign="top">BINARY(4)</td>
|
||
|
<td align="left" valign="top">CCSID conversion status indicator for text</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="center" valign="top">131</td>
|
||
|
<td align="center" valign="top">83</td>
|
||
|
<td align="left" valign="top">BINARY(4)</td>
|
||
|
<td align="left" valign="top">CCSID conversion status indicator for data</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="center" valign="top">135</td>
|
||
|
<td align="center" valign="top">87</td>
|
||
|
<td align="left" valign="top">CHAR(9)</td>
|
||
|
<td align="left" valign="top">Alert option</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="center" valign="top">144</td>
|
||
|
<td align="center" valign="top">90</td>
|
||
|
<td align="left" valign="top">BINARY(4)</td>
|
||
|
<td align="left" valign="top">CCSID of message or message help</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="center" valign="top">148</td>
|
||
|
<td align="center" valign="top">94</td>
|
||
|
<td align="left" valign="top">BINARY(4)</td>
|
||
|
<td align="left" valign="top">CCSID of replacement data or impromptu message
|
||
|
text</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="center" valign="top">152</td>
|
||
|
<td align="center" valign="top">98</td>
|
||
|
<td align="left" valign="top">BINARY(4)</td>
|
||
|
<td align="left" valign="top">Length of replacement data or impromptu message
|
||
|
text returned</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="center" valign="top">156</td>
|
||
|
<td align="center" valign="top">9C</td>
|
||
|
<td align="left" valign="top">BINARY(4)</td>
|
||
|
<td align="left" valign="top">Length of replacement data or impromptu message
|
||
|
text available</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="center" valign="top">160</td>
|
||
|
<td align="center" valign="top">A0</td>
|
||
|
<td align="left" valign="top">BINARY(4)</td>
|
||
|
<td align="left" valign="top">Length of message returned</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="center" valign="top">164</td>
|
||
|
<td align="center" valign="top">A4</td>
|
||
|
<td align="left" valign="top">BINARY(4)</td>
|
||
|
<td align="left" valign="top">Length of message available</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="center" valign="top">168</td>
|
||
|
<td align="center" valign="top">A8</td>
|
||
|
<td align="left" valign="top">BINARY(4)</td>
|
||
|
<td align="left" valign="top">Length of message help returned</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="center" valign="top">172</td>
|
||
|
<td align="center" valign="top">AC</td>
|
||
|
<td align="left" valign="top">BINARY(4)</td>
|
||
|
<td align="left" valign="top">Length of message help available</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="center" valign="top">176</td>
|
||
|
<td align="center" valign="top">B0</td>
|
||
|
<td align="left" valign="top">CHAR(*)</td>
|
||
|
<td align="left" valign="top">Replacement data or impromptu text</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top" rowspan="2" colspan="2">The offsets to these
|
||
|
fields equal the offset to the last fixed-length field plus the length of the
|
||
|
previous variable length fields.<br>
|
||
|
</td>
|
||
|
<td align="left" valign="top">CHAR(*)</td>
|
||
|
<td align="left" valign="top">Message</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top">CHAR(*)</td>
|
||
|
<td align="left" valign="top">Message help</td>
|
||
|
</tr>
|
||
|
</table>
|
||
|
|
||
|
<br>
|
||
|
<br>
|
||
|
|
||
|
|
||
|
<h3><a name="HDRRCVMFD">Field Descriptions</a></h3>
|
||
|
|
||
|
<p>The following field descriptions apply only when a message is received. If
|
||
|
no message is found, only the bytes available and bytes returned fields contain
|
||
|
new values. The remaining fields contain whatever information was already
|
||
|
stored in the space allowed for the output.</p>
|
||
|
|
||
|
<p><strong>Alert option.</strong> Whether and when an SNA alert is created and
|
||
|
sent for the message. If a message is received, the value is one of the
|
||
|
following:</p>
|
||
|
|
||
|
<table cellpadding="5">
|
||
|
<!-- cols="15 85" -->
|
||
|
<tr>
|
||
|
<td align="left" valign="top"><em>*DEFER</em></td>
|
||
|
<td align="left" valign="top">An alert is sent after local problem
|
||
|
analysis.</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top"><em>*IMMED</em></td>
|
||
|
<td align="left" valign="top">An alert is sent immediately when the message is
|
||
|
sent to a message queue that has the allow alerts attribute set to *YES.</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top"><em>*NO</em></td>
|
||
|
<td align="left" valign="top">No alert is sent.</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top"><em>*UNATTEND</em></td>
|
||
|
<td align="left" valign="top">An alert is sent immediately when the system is
|
||
|
running in unattended mode (when the value of the alert status network
|
||
|
attribute, ALRSTS, is *UNATTEND).</td>
|
||
|
</tr>
|
||
|
</table>
|
||
|
|
||
|
<p>For more information, see the <a href="../books/sc415413.pdf" target=
|
||
|
"_blank">Alerts Support</a> <img src="wbpdf.gif" alt="Link to PDF"> book.</p>
|
||
|
|
||
|
<p><strong>Bytes available.</strong> The length of all available information
|
||
|
that could be returned for the format. Bytes available can be greater than the
|
||
|
length specified in the API's length of message information parameter. If it is
|
||
|
greater, the information returned in the message information parameter is
|
||
|
truncated to the length specified.</p>
|
||
|
|
||
|
<p><strong>Bytes returned.</strong> The length of all information returned in
|
||
|
the format. The value of the bytes returned field is always less than or equal
|
||
|
to the length of the message information parameter. Also, it is always less
|
||
|
than or equal to the bytes available. There is one exception to this. When you
|
||
|
attempt to receive a message and the message is not found, the following
|
||
|
occurs:</p>
|
||
|
|
||
|
<ul>
|
||
|
<li>The value of the bytes returned field is 8.</li>
|
||
|
|
||
|
<li>The value of the bytes available field is 0.</li>
|
||
|
|
||
|
<li>The remaining fields are unchanged (that is, they contain whatever was
|
||
|
already stored in that space).</li>
|
||
|
</ul>
|
||
|
|
||
|
<p>If the bytes returned value is less than the length specified in the length
|
||
|
of message information parameter, the extra space in the message information
|
||
|
parameter is unchanged.</p>
|
||
|
|
||
|
<p><strong>CCSID conversion status indicator for text.</strong> The following
|
||
|
values may be returned:</p>
|
||
|
|
||
|
<table cellpadding="5">
|
||
|
<!-- cols="5 95" -->
|
||
|
<tr>
|
||
|
<td align="left" valign="top"><em>0</em></td>
|
||
|
<td align="left" valign="top">No conversion was needed because the CCSID of the
|
||
|
message or message help text matched the CCSID you wanted the message or
|
||
|
message help text converted to.</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top"><em>1</em></td>
|
||
|
<td align="left" valign="top">No conversion occurred because either the message
|
||
|
or message help text was 65535 or the CCSID you wanted the message or message
|
||
|
help text converted to was 65535.</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top"><em>2</em></td>
|
||
|
<td align="left" valign="top">No conversion occurred because you did not supply
|
||
|
enough space for the message or message help.</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top"><em>3</em></td>
|
||
|
<td align="left" valign="top">The message or message help text was converted to
|
||
|
the CCSID specified using the best fit conversion tables.</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top"><em>4</em></td>
|
||
|
<td align="left" valign="top">A conversion error occurred using the best fit
|
||
|
conversion tables so a default conversion was attempted. This completed without
|
||
|
error.</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top"><em>-1</em></td>
|
||
|
<td align="left" valign="top">An error occurred on both the best fit and
|
||
|
default conversions. The text was not converted.</td>
|
||
|
</tr>
|
||
|
</table>
|
||
|
|
||
|
<p><strong>CCSID conversion status indicator for data.</strong> The following
|
||
|
values may be returned:</p>
|
||
|
|
||
|
<table cellpadding="5">
|
||
|
<!-- cols="5 95" -->
|
||
|
<tr>
|
||
|
<td align="left" valign="top"><em>0</em></td>
|
||
|
<td align="left" valign="top">No conversion was needed because the CCSID of the
|
||
|
replacement data or impromptu message text matched the CCSID you wanted the
|
||
|
data or text converted to.</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top"><em>1</em></td>
|
||
|
<td align="left" valign="top">No conversion occurred because either the data
|
||
|
was 65535 or the CCSID you wanted the data converted to was 65535.</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top"><em>2</em></td>
|
||
|
<td align="left" valign="top">No conversion occurred because you did not supply
|
||
|
enough space for the data.</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top"><em>3</em></td>
|
||
|
<td align="left" valign="top">The data was converted to the CCSID specified
|
||
|
using the best fit conversion tables.</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top"><em>4</em></td>
|
||
|
<td align="left" valign="top">A conversion error occurred using the best fit
|
||
|
conversion tables so a default conversion was attempted. This completed without
|
||
|
error.</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top"><em>-1</em></td>
|
||
|
<td align="left" valign="top">An error occurred on both the best fit and
|
||
|
default conversions. The data was not converted.</td>
|
||
|
</tr>
|
||
|
</table>
|
||
|
|
||
|
<p><strong>CCSID of message and message help.</strong> The CCSID of the text in
|
||
|
the message and message help fields is returned. The inserted replacement data
|
||
|
may not be the same CCSID. Refer to the CCSID of the replacement data or
|
||
|
impromptu message text field description for a more details.</p>
|
||
|
|
||
|
<p>If a conversion error occurs or the CCSID you requested the text to be
|
||
|
converted to is 65535, the CCSID that the message description is stored in is
|
||
|
returned. Otherwise, the CCSID you wanted your text converted to is returned.
|
||
|
If you do not want the text converted before it is returned to you but you do
|
||
|
want to know the CCSID that the message description is stored in, specify 65535
|
||
|
on the coded character set identifier parameter. The CCSID that the message
|
||
|
description is stored in is returned in the CCSID of message and message help
|
||
|
output field.</p>
|
||
|
|
||
|
<p><strong>CCSID of replacement data or impromptu message text.</strong> The
|
||
|
CCSID of the replacement data or impromptu message text is returned. If an
|
||
|
impromptu message text is received, this is the CCSID of the impromptu message
|
||
|
text. When replacement data is received, this is the CCSID of the replacement
|
||
|
data fields defined as convertible character (*CCHAR) in the message
|
||
|
description. All other replacement data is not converted before it is returned.
|
||
|
If a conversion error occurs or the CCSID you requested the data to be
|
||
|
converted to is 65535, the CCSID of the data or text is returned. If
|
||
|
replacement data is being returned and there is no *CCHAR replacement data,
|
||
|
65535 is returned. Otherwise the CCSID you wanted the data converted to is
|
||
|
returned.</p>
|
||
|
|
||
|
<p><strong>Date sent.</strong> The date on which the message was sent, in
|
||
|
CYYMMDD (century, year, month, day) format.</p>
|
||
|
|
||
|
<p><strong>Length (general information about the following length
|
||
|
fields).</strong> These formats use two types of length fields, each related to
|
||
|
a single variable length text field. (The variable length text fields return
|
||
|
information to the caller.) The first type of length field is returned length;
|
||
|
the second is available length. <strong>Returned length</strong> is the actual
|
||
|
length of the text in the variable length text field. <strong>Available
|
||
|
length</strong> is the length of the text before it is placed in the variable
|
||
|
length text field. It is always greater than or equal to the returned length.
|
||
|
If the available length equals the returned length, all the message information
|
||
|
is returned. If the text is truncated when placed in the variable length field,
|
||
|
the available length is greater than the returned length by the number of
|
||
|
characters truncated.</p>
|
||
|
|
||
|
<p><strong>Length of message available.</strong> The length of the available
|
||
|
message text, in bytes. If an immediate message is received, the value of this
|
||
|
field is zero.</p>
|
||
|
|
||
|
<p><strong>Length of message help available.</strong> The length of the
|
||
|
available message help information, in bytes. If an impromptu message is
|
||
|
received, the value of this field is zero.</p>
|
||
|
|
||
|
<p><strong>Length of message help returned.</strong> The length of the message
|
||
|
help information, in bytes. If an impromptu message is received, the value of
|
||
|
this field is zero.</p>
|
||
|
|
||
|
<p><strong>Length of message returned.</strong> The length of the returned text
|
||
|
of a predefined message, in bytes. If an impromptu message is received, the
|
||
|
value of this field is zero.</p>
|
||
|
|
||
|
<p><strong>Length of replacement data or impromptu message text
|
||
|
available.</strong> The length of the available impromptu message text or
|
||
|
replacement data, in bytes. If the message identifier is not blank, this field
|
||
|
contains the length of the available replacement data for a predefined message.
|
||
|
If the message identifier is blank, this field contains the length of the
|
||
|
available text of an impromptu message.</p>
|
||
|
|
||
|
<p><strong>Length of replacement data or impromptu message text
|
||
|
returned.</strong> The length of the returned impromptu message text or
|
||
|
replacement data, in bytes. If the message identifier is not blank, this field
|
||
|
contains the length of the replacement data. If the message identifier is
|
||
|
blank, this field contains the length of the impromptu message text.</p>
|
||
|
|
||
|
<p><strong>Message.</strong> The text of a predefined message. If an impromptu
|
||
|
message is received, this field is blank.</p>
|
||
|
|
||
|
<p>The API can truncate the message to fit the available space. If truncation
|
||
|
occurs in the middle of double-byte character set (DBCS) data, the API returns
|
||
|
only complete DBCS characters. It ends the data with a DBCS shift-in
|
||
|
character.</p>
|
||
|
|
||
|
<p><strong>Message file name.</strong> The name of the message file containing
|
||
|
the message received.</p>
|
||
|
|
||
|
<p><strong>Message file library specified.</strong> The name of the library
|
||
|
containing the message file, as specified in the call to this API. If you
|
||
|
specify *CURLIB or *LIBL for the library when you send the message, that value
|
||
|
is returned as the library here. For the actual library used when the message
|
||
|
is sent, see the message file library used field.</p>
|
||
|
|
||
|
<p><strong>Message file library used.</strong> The name of the library used to
|
||
|
send the message. Because the library can contain override instructions, this
|
||
|
is not necessarily the library in which the message actually resides.</p>
|
||
|
|
||
|
<p><strong>Message help.</strong> The message help for the message received. If
|
||
|
an immediate message is received, this field is blank.</p>
|
||
|
|
||
|
<p>The API can truncate the message help to fit the available space. If
|
||
|
truncation occurs in the middle of double-byte character set (DBCS) data, the
|
||
|
API returns only complete DBCS characters. It ends the data with a DBCS
|
||
|
shift-in character.</p>
|
||
|
|
||
|
<p><strong>Message identifier.</strong> The identifying code of the message
|
||
|
received. If an impromptu message is received, this field is blank.</p>
|
||
|
|
||
|
<p><strong>Message key.</strong> The key to the message received. The key is
|
||
|
assigned by the command or API that sends the message. If the message action
|
||
|
parameter specifies *REMOVE, this field is blank.</p>
|
||
|
|
||
|
<p><strong>Message severity.</strong> The severity of the message received.
|
||
|
Possible values are 0 through 99.</p>
|
||
|
|
||
|
<p><strong>Message type.</strong> The message type of the message received. The
|
||
|
possible values and their meanings are:</p>
|
||
|
|
||
|
<table cellpadding="5">
|
||
|
<tr>
|
||
|
<th align="left" valign="top">Value</th>
|
||
|
<th align="left" valign="top">Message Type</th>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top" width="15%"><em>01</em></td>
|
||
|
<td align="left" valign="top" width="85%">Completion</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top"><em>02</em></td>
|
||
|
<td align="left" valign="top">Diagnostic</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top"><em>04</em></td>
|
||
|
<td align="left" valign="top">Informational</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top"><em>05</em></td>
|
||
|
<td align="left" valign="top">Inquiry</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top"><em>06</em></td>
|
||
|
<td align="left" valign="top">Sender's copy</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top"><em>08</em></td>
|
||
|
<td align="left" valign="top">Request</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top"><em>10</em></td>
|
||
|
<td align="left" valign="top">Request with prompting</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top"><em>14</em></td>
|
||
|
<td align="left" valign="top">Notify</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top"><em>15</em></td>
|
||
|
<td align="left" valign="top">Escape</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top"><em>21</em></td>
|
||
|
<td align="left" valign="top">Reply, not validity checked</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top"><em>22</em></td>
|
||
|
<td align="left" valign="top">Reply, validity checked</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top"><em>23</em></td>
|
||
|
<td align="left" valign="top">Reply, message default used</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top"><em>24</em></td>
|
||
|
<td align="left" valign="top">Reply, system default used</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top"><em>25</em></td>
|
||
|
<td align="left" valign="top">Reply, from system reply list</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top">26</td>
|
||
|
<td align="left" valign="top">Reply, from exit program</td>
|
||
|
</tr>
|
||
|
|
||
|
</table>
|
||
|
|
||
|
<p>
|
||
|
<strong>Microseconds.</strong> The microseconds part of the time sent.</p>
|
||
|
|
||
|
<p><strong>Replacement data or impromptu message text.</strong> The values for
|
||
|
substitution variables in a predefined message, or the text of an impromptu
|
||
|
message. If the message identifier is not blank, this field contains message
|
||
|
data. If the message identifier is blank, this field contains impromptu message
|
||
|
text.</p>
|
||
|
|
||
|
<p>If this field contains message data that contains pointer data, each pointer
|
||
|
must start on a 16-byte boundary. If you are running at security level 50, the
|
||
|
pointer data is invalidated.</p>
|
||
|
|
||
|
<p>The API can truncate the data or text to fit the available space. If the
|
||
|
field contains the text of an impromptu message and is truncated in the middle
|
||
|
of double-byte character set (DBCS) data, the API returns only complete DBCS
|
||
|
characters. It ends the data with a DBCS shift-in character. However, if the
|
||
|
field contains data for a predefined message, the API does not check for DBCS
|
||
|
data. This is because message data can contain pointers, and pointers can
|
||
|
contain the same characters used to mark DBCS data.</p>
|
||
|
|
||
|
<p><strong>Reserved.</strong> An ignored field.</p>
|
||
|
|
||
|
<p><strong>Sending job.</strong> The name of the job in which the message being
|
||
|
received was sent.</p>
|
||
|
|
||
|
<p><strong>Sending job's number.</strong> The job number of the job in which
|
||
|
the message being received was sent.</p>
|
||
|
|
||
|
<p><strong>Sending job's user profile.</strong> The name of the user profile
|
||
|
in the qualified job name of the job that
|
||
|
sent the message being received.
|
||
|
|
||
|
</p>
|
||
|
|
||
|
<p><strong>Sending program name.</strong> The original program model (OPM)
|
||
|
program name or ILE bound program name that contains the procedure sending the
|
||
|
message.</p>
|
||
|
|
||
|
<p><strong>Sending program's instruction number.</strong> The number of the
|
||
|
program instruction that issued the command or called the API used to send the
|
||
|
message being received.</p>
|
||
|
|
||
|
<p><strong>Sending user profile.</strong> The name of the user profile
|
||
|
that the thread was running under when the message was sent.</p>
|
||
|
|
||
|
<p><strong>Time sent.</strong> The time at which the message being received was
|
||
|
sent, in HHMMSS (hour, minute, second) format.</p>
|
||
|
|
||
|
<br>
|
||
|
|
||
|
|
||
|
<h3>Error Messages</h3>
|
||
|
|
||
|
<table width="100%" cellpadding="5">
|
||
|
<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" width="15%">CPF24AF E</td>
|
||
|
<td align="left" valign="top" width="85%">Message key not allowed with message
|
||
|
type specified.</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top">CPF24A7 E</td>
|
||
|
<td align="left" valign="top">Value for the length of message information not
|
||
|
valid.</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top">CPF24A8 E</td>
|
||
|
<td align="left" valign="top">Value for wait time not valid.</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top">CPF24A9 E</td>
|
||
|
<td align="left" valign="top">Value for message action not valid.</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top">CPF24B1 E</td>
|
||
|
<td align="left" valign="top">Message key required for message type
|
||
|
specified.</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top">CPF24B2 E</td>
|
||
|
<td align="left" valign="top">Message key of *TOP requires message type of
|
||
|
*NEXT.</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top">CPF24B3 E</td>
|
||
|
<td align="left" valign="top">Message type &1 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">CPF2401 E</td>
|
||
|
<td align="left" valign="top">Not authorized to library &1.</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top">CPF2403 E</td>
|
||
|
<td align="left" valign="top">Message queue &1 in &2 not found.</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top">CPF2407 E</td>
|
||
|
<td align="left" valign="top">Message file &1 in &2 not found.</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top">CPF2408 E</td>
|
||
|
<td align="left" valign="top">Not authorized to message queue &1.</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top">CPF2410 E</td>
|
||
|
<td align="left" valign="top">Message key not found in message queue
|
||
|
&1.</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top">CPF2411 E</td>
|
||
|
<td align="left" valign="top">Not authorized to message file &1 in
|
||
|
&2.</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">CPF2433 E</td>
|
||
|
<td align="left" valign="top">Function not allowed for system log message queue
|
||
|
&1.</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top">CPF2450 E</td>
|
||
|
<td align="left" valign="top">Work station message queue &1 not allocated
|
||
|
to job.</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top">CPF2451 E</td>
|
||
|
<td align="left" valign="top">Message queue &1 is allocated to another
|
||
|
job.</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top">CPF247E E</td>
|
||
|
<td align="left" valign="top">CCSID &1 is not valid.</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top">CPF2477 E</td>
|
||
|
<td align="left" valign="top">Message queue &1 currently in use.</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top">CPF2531 E</td>
|
||
|
<td align="left" valign="top">Message file &1 in &2 damaged for
|
||
|
&3.</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top">CPF2548 E</td>
|
||
|
<td align="left" valign="top">Damage to message file &1 in &2.</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top">CPF2551 E</td>
|
||
|
<td align="left" valign="top">Message key and message type combination not
|
||
|
valid.</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">CPF3C21 E</td>
|
||
|
<td align="left" valign="top">Format name &1 is not valid.</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top">CPF3C3A E</td>
|
||
|
<td align="left" valign="top">Value for parameter &2 for API &1 not valid.</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top">CPF3C36 E</td>
|
||
|
<td align="left" valign="top">Number of parameters, &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 &1.</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top">CPF9872 E</td>
|
||
|
<td align="left" valign="top">Program or service program &1 in library
|
||
|
&2 ended. Reason code &3.</td>
|
||
|
</tr>
|
||
|
</table>
|
||
|
|
||
|
<br>
|
||
|
|
||
|
|
||
|
<hr>
|
||
|
API introduced: V2R1.1
|
||
|
|
||
|
<hr>
|
||
|
<center>
|
||
|
<table 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>
|
||
|
</center>
|
||
|
</body>
|
||
|
</html>
|
||
|
|