friedkiwi/ibm-information-center
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
master
ibm-information-center/dist/eclipse/plugins/i5OS.ic.apis_5.4.0.1/qmhrdqm.htm

1044 lines
32 KiB
HTML
Raw Permalink Blame History

<!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>Retrieve Data Queue Message (QMHRDQM) 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. -->
<!-- QMHRDQM SCRIPT J converted by B2H R4.1 (346) (CMS) by PMHALL at -->
<!-- RCHVMW2 on 7 Oct 1998 at 12:44:19 -->
<!-- Change History: -->
<!-- YYMMDD USERID Change description -->
<!-- Edited by Kersten Jan 02 -->
<!--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>Retrieve Data Queue Message (QMHRDQM) API</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%">Receiver variable</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 receiver variable</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 data 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 selection information</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Char(*)</td>
</tr>
<tr>
<td align="center" valign="top">6</td>
<td align="left" valign="top">Length of message selection information</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Binary(4)</td>
</tr>
<tr>
<td align="center" valign="top">7</td>
<td align="left" valign="top">Message selection information 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">8</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;Default Public Authority: *USE<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;Threadsafe: Yes<br>
<!-- iddvc RMBR -->
<br>
</div>
<p>The Retrieve Data Queue Message (QMHRDQM) API retrieves one or more messages
from a data queue.</p>
<p>The QMHRDQM API allows the retrieval of multiple messages per call. The
message selection information parameter allows you to have some control over
which messages are returned. The QMHRDQM API can be used to retrieve the
following:</p>
<ul>
<li>The first or last message of a data queue</li>
<li>All messages of a data queue</li>
<li>Selected messages from a keyed data queue</li>
</ul>
<p>The QMHRDQM API is similar in function to the QRCVDTAQ API. However, the
QRCVDTAQ API can remove the received message from the data queue; QMHRDQM API
does <strong>not</strong> remove received messages.</p>
<p>Distributed data management (DDM) data queues are not supported using this
API.</p>
<br>
<h3>Authorities and Locks</h3>
<dl>
<dt><em>Data Queue Authority</em></dt>
<dd>*OBJOPR and *READ</dd>
<dt><em>Data Queue Library Authority</em></dt>
<dd>*EXECUTE</dd>
<dt><em>Data Queue Lock</em></dt>
<dd>*EXCLRD</dd>
</dl>
<p>Internally, when a job uses API QSNDDTAQ (Send Data Queue), QRCVDTAQ
(Receive Data Queue), QMHQRDQD (Retrieve Data Queue Description), or QMHRDQM
(Retrieve Data Queue Message), a cache is created to allow faster access to the
data queue. An entry in the cache means a user is authorized to the data queue.
An entry is added to the cache when a user calling one of the APIs has the
required authority to the data queue. An entry is also added to the cache when
QSNDDTAQ is called to handle a journal entry for a data queue created with the
sender ID attribute set to *YES, and the user requesting the the send function
has the required authority to the current profile name in the sender ID
information of the journal entry. The data in the cache is used until the job
ends, so if you need to immediately change a user's authority to one of these
objects, you may need to end that user's jobs.</p>
<br>
<h3>Required Parameter Group</h3>
<dl>
<dt><strong>Receiver variable</strong></dt>
<dd>OUTPUT; CHAR(*)
<p>The receiver variable that receives the information requested. You can
specify the size of the area to be smaller than the format requested as long as
you specify the length parameter correctly. As a result, the API returns only
the data that the area can hold.</p>
</dd>
<dt><strong>Length of receiver variable</strong></dt>
<dd>INPUT; BINARY(4)
<p>The length of the receiver variable provided. The length of receiver
variable parameter may be specified up to the size of the receiver variable
specified in the user program. If the length of receiver variable parameter
specified is larger than the allocated size of the receiver variable specified
in the user program, the results are not predictable. The minimum length is 8
bytes</p>
</dd>
<dt><strong>Format name</strong></dt>
<dd>INPUT; CHAR(8)
<p>The format of the data to be placed in the receiver variable.</p>
<p>The valid format names are:</p>
<table cellpadding="5">
<!-- cols="25 75" -->
<tr>
<td align="left" valign="top"><em><a href="#HDRRDQM01">RDQM0100</a></em></td>
<td align="left" valign="top">Retrieved data queue message(s) information.</td>
</tr>
<tr>
<td align="left" valign="top"><em><a href="#HDRRDQM02">RDQM0200</a></em></td>
<td align="left" valign="top">Retrieved data queue message(s) information.</td>
</tr>
</table>
<p>The RDQM0200 format differs from RDQM0100 in that when the user requests to
retrieve the number of bytes equal to the maximum message entry size specified,
this returns the length and data of the message entry that was enqueued instead
of the maximum length and data contained in the data queue entry. Therefore,
the repeating fields at the end of format RDQM0200 could require less space
than format RDQM0100, which uses the same amount of space for each entry
retrieved from the queue.</p>
</dd>
<dt><strong>Qualified data queue name</strong></dt>
<dd>INPUT; CHAR(20)
<p>The data queue whose description is to be returned. The first 10 characters
contain the data queue name, and the second 10 characters contain the data
queue library name.</p>
<p>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><strong>Note:</strong> To improve data queue performance, the data queue
APIs remember addressing information for the last data queues used. When this
occurs, a specific (not *LIBL or *CURLIB) value is provided for the library
name, and the data queue is
located in the system auxiliary storage pool (ASP number 1) or a basic user ASP
(ASP numbers 2-32). The addressing information for data queues located in
independent ASPs is not saved.</p>
<p>Because the addressing information is saved, users of this API should be
aware of the following scenario:</p>
<p>If, a job references a data queue, the data queue is moved using the Move
Object (MOVOBJ) command or renamed using the Rename Object (RNMOBJ) command,
and a new data queue is created with the same name and library as the data
queue that was renamed or moved, then, the job continues to reference the
original data queue, not the newly created data queue.</p>
</dd>
<dt><strong>Message selection information</strong></dt>
<dd>INPUT; CHAR(*)
<p>Identifies which message (or messages) you want to retrieve. The layout of
this parameter is determined by the value of the message selection information
format name.</p>
</dd>
<dt><strong>Length of message selection information</strong></dt>
<dd>INPUT; BINARY(4)
<p>The length of the message selection information parameter. This must be 8
bytes for RDQS0100 and 16 bytes plus the size of the key for RDQS0200.</p>
</dd>
<dt><strong>Message selection information format name</strong></dt>
<dd>INPUT; CHAR(8)
<p>The format of the message selection information parameter.</p>
<p>The following format names can be used:</p>
<table cellpadding="5">
<!-- cols="25 75" -->
<tr>
<td align="left" valign="top"><em><a href="#HDRRDQS1">RDQS0100</a></em></td>
<td align="left" valign="top">Format to select messages when using nonkeyed
data queues.</td>
</tr>
<tr>
<td align="left" valign="top"><em><a href="#HDRRDQS2">RDQS0200</a></em></td>
<td align="left" valign="top">Format to select messages when using keyed data
queues.</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><a name="HDRRDQM01">RDQM0100 Format</a></h3>
<p>The following table lists the fields returned in the RDQM0100 format of the
receiver variable parameter. For a detailed description of each field, see <a
href="#HDRRDQMFD">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">Number of messages returned</td>
</tr>
<tr>
<td align="center" valign="top">12</td>
<td align="center" valign="top">C</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Number of messages available</td>
</tr>
<tr>
<td align="center" valign="top">16</td>
<td align="center" valign="top">10</td>
<td align="left" valign="top">BINARY (4)</td>
<td align="left" valign="top">Message key length returned</td>
</tr>
<tr>
<td align="center" valign="top">20</td>
<td align="center" valign="top">14</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Message key length available</td>
</tr>
<tr>
<td align="center" valign="top">24</td>
<td align="center" valign="top">18</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Maximum message text length requested</td>
</tr>
<tr>
<td align="center" valign="top">28</td>
<td align="center" valign="top">1C</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Maximum message text length available</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">Entry length returned</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">Entry length available</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">Offset to first message entry</td>
</tr>
<tr>
<td align="center" valign="top">44</td>
<td align="center" valign="top">2C</td>
<td align="left" valign="top">CHAR(10)</td>
<td align="left" valign="top">Actual data queue library name</td>
</tr>
<tr>
<td align="center" valign="top">54</td>
<td align="center" valign="top">36</td>
<td align="left" valign="top">CHAR(*)</td>
<td align="left" valign="top">Reserved</td>
</tr>
<tr>
<td align="left" valign="top" rowspan="5" colspan="2">These fields repeat for
each message retrieved.</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Offset to next message entry</td>
</tr>
<tr>
<td align="left" valign="top">CHAR(8)</td>
<td align="left" valign="top">Message enqueue date and time</td>
</tr>
<tr>
<td align="left" valign="top">CHAR(*)</td>
<td align="left" valign="top">Message key</td>
</tr>
<tr>
<td align="left" valign="top">CHAR(*)</td>
<td align="left" valign="top">Message text</td>
</tr>
<tr>
<td align="left" valign="top">CHAR(*)</td>
<td align="left" valign="top">Reserved</td>
</tr>
</table>
<br>
<br>
<h3><a name="HDRRDQM02">RDQM0200 Format</a></h3>
<p>The following table lists the fields returned in the RDQM0200 format of the
receiver variable parameter. For a detailed description of each field, see <a
href="#HDRRDQMFD">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">Number of messages returned</td>
</tr>
<tr>
<td align="center" valign="top">12</td>
<td align="center" valign="top">C</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Number of messages available</td>
</tr>
<tr>
<td align="center" valign="top">16</td>
<td align="center" valign="top">10</td>
<td align="left" valign="top">BINARY (4)</td>
<td align="left" valign="top">Message key length returned</td>
</tr>
<tr>
<td align="center" valign="top">20</td>
<td align="center" valign="top">14</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Message key length available</td>
</tr>
<tr>
<td align="center" valign="top">24</td>
<td align="center" valign="top">18</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Maximum message text length requested</td>
</tr>
<tr>
<td align="center" valign="top">28</td>
<td align="center" valign="top">1C</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Maximum message text length available</td>
</tr>
<tr>
<td align="center" valign="top">32</td>
<td align="center" valign="top">20</td>
<td align="left" valign="top">CHAR(8)</td>
<td align="left" valign="top">Reserved</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">Offset to first message entry</td>
</tr>
<tr>
<td align="center" valign="top">44</td>
<td align="center" valign="top">2C</td>
<td align="left" valign="top">CHAR(10)</td>
<td align="left" valign="top">Actual data queue library name</td>
</tr>
<tr>
<td align="center" valign="top">54</td>
<td align="center" valign="top">36</td>
<td align="left" valign="top">CHAR(*)</td>
<td align="left" valign="top">Reserved</td>
</tr>
<tr>
<td align="left" valign="top" rowspan="6" colspan="2">These fields repeat for
each message retrieved.</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Offset to next message entry</td>
</tr>
<tr>
<td align="left" valign="top">CHAR(8)</td>
<td align="left" valign="top">Message enqueue date and time</td>
</tr>
<tr>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Enqueued message entry length</td>
</tr>
<tr>
<td align="left" valign="top">CHAR(*)</td>
<td align="left" valign="top">Message key</td>
</tr>
<tr>
<td align="left" valign="top">CHAR(*)</td>
<td align="left" valign="top">Message text</td>
</tr>
<tr>
<td align="left" valign="top">CHAR(*)</td>
<td align="left" valign="top">Reserved</td>
</tr>
</table>
<br>
<br>
<h3><a name="HDRRDQS1">RDQS0100 Format</a></h3>
<p>The following table describes the RDQS0100 format of the Message selection
information parameter. This format is used with data queues when selection with
keys is not necessary. This format cannot be used with keyed data queues. To
retrieve messages using keys and key search order, use format RDQS0200. For a
detailed description of each field, see <a href="#HDRRDQMFD">Field
Descriptions</a>.</p>
<p>For example, to retrieve the first 10 bytes of the last entry in a data
queue specify the following: Parameter seven would contain a format name of
'RDQS0100' and parameter five would consist of a Selection type of 'L', the
Reserved field would be blanks, and Number of message text bytes to retrieve
would be 10.</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%">CHAR(1)</td>
<td align="left" valign="top" width="60%">Selection type</td>
</tr>
<tr>
<td align="center" valign="top">1</td>
<td align="center" valign="top">1</td>
<td align="left" valign="top">CHAR(3)</td>
<td align="left" valign="top">Reserved</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">Number of message text bytes to retrieve</td>
</tr>
</table>
<br>
<br>
<h3><a name="HDRRDQS2">RDQS0200 Format</a></h3>
<p>The following table describes the RDQS0200 format of the Message selection
information parameter. This format is used to retrieve messages from data
queues when selection with keys is necessary. When using this format, all
messages satisfying the key search order are returned. For a detailed
description of each field, see <a href="#HDRRDQMFD">Field Descriptions</a>.</p>
<p><strong>Note:</strong> This format is valid only if the queue was created as
a keyed data queue.</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%">CHAR(1)</td>
<td align="left" valign="top" width="60%">Selection type</td>
</tr>
<tr>
<td align="center" valign="top">1</td>
<td align="center" valign="top">1</td>
<td align="left" valign="top">CHAR(2)</td>
<td align="left" valign="top">Key search order</td>
</tr>
<tr>
<td align="center" valign="top">3</td>
<td align="center" valign="top">3</td>
<td align="left" valign="top">CHAR(1)</td>
<td align="left" valign="top">Reserved</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">Number of message text bytes to retrieve</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">Number of message key bytes to retrieve</td>
</tr>
<tr>
<td align="center" valign="top">12</td>
<td align="center" valign="top">C</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Length of Key</td>
</tr>
<tr>
<td align="center" valign="top">16</td>
<td align="center" valign="top">10</td>
<td align="left" valign="top">CHAR(*)</td>
<td align="left" valign="top">Key</td>
</tr>
</table>
<br>
<br>
<h3><a name="HDRRDQMFD">Field Descriptions</a></h3>
<p><strong>Actual data queue library name.</strong> The library in which the
data queue was found. This name is found by searching the library list (*LIBL)
or the current library (*CURLIB). If the data queue is in a library other than
your current library or library list, it will not be found.</p>
<p><strong>Bytes available.</strong> The number of bytes of data available to
be returned. All available data is returned if enough space is provided.</p>
<p><strong>Bytes returned.</strong> The number of bytes of data returned.</p>
<p><strong>Enqueued message entry length.</strong> The number of bytes
specified for the message entry length when the entry was placed on the data
queue. For a data queue created with SENDERID(*YES), this length is the message
entry length specified plus 36 bytes for the sender ID. This is the number of
bytes returned in the message text field unless the number of message text
bytes to retrieve field is less than this value. In that case, the maximum
message text length requested is returned in the message text field.</p>
<p><strong>Entry length available.</strong> The total number of bytes available
to be retrieved for each message entry.</p>
<p><strong>Entry length returned.</strong> The number of bytes retrieved for
each message entry.</p>
<p><strong>Key.</strong> The key field to be compared with the actual keys of
the messages on the data queue.</p>
<p><strong>Key search order.</strong> A relational operator specifying the
comparison criteria between the message key specified in the RDQS0200 format
and the actual keys of messages in the data queue.</p>
<p>Valid values are:</p>
<table cellpadding="5">
<!-- cols="5 95" -->
<tr>
<td align="left" valign="top"><em>GT</em></td>
<td align="left" valign="top">All messages with a key greater than that
specified in the key field are to be returned.</td>
</tr>
<tr>
<td align="left" valign="top"><em>LT</em></td>
<td align="left" valign="top">All messages with a key less than that specified
in the key field are to be returned.</td>
</tr>
<tr>
<td align="left" valign="top"><em>NE</em></td>
<td align="left" valign="top">All messages with a key not equal to that
specified in the key field are to be returned.</td>
</tr>
<tr>
<td align="left" valign="top"><em>EQ</em></td>
<td align="left" valign="top">All messages with a key equal to that specified
in the key field are to be returned.</td>
</tr>
<tr>
<td align="left" valign="top"><em>GE</em></td>
<td align="left" valign="top">All messages with a key greater than or equal to
that specified in the key field are to be returned.</td>
</tr>
<tr>
<td align="left" valign="top"><em>LE</em></td>
<td align="left" valign="top">All messages with a key less than or equal to
that specified in the key field are to be returned.</td>
</tr>
</table>
<p><strong>Length of key.</strong> The length of the data provided in the key
field. This must be a value from 1 through 256.</p>
<p><strong>Maximum message text length available.</strong> The maximum message
entry size (in bytes) specified when the data queue was created. For a data
queue created with SENDERID(*YES), this length is the maximum entry size plus
36 bytes for the sender ID.</p>
<p><strong>Maximum message text length requested.</strong> The value specified
in the message selection format (RDQS0100 or RDQS0200) for the number of
message text bytes to retrieve.</p>
<p><strong>Message enqueue date and time.</strong> The date and time that the
message was placed on the data queue. Its format is a system time stamp (*DTS). The <a href="qwccvtdt.htm">Convert Date and Time Format</a> (QWCCVTDT) API can be used to convert this time stamp to a character format.</p>
<p><strong>Message key.</strong> The key of the message.</p>
<p><strong>Message key length available.</strong> The size (in bytes) of the
key at the creation time of the data queue.</p>
<p><strong>Message key length returned.</strong> The number of bytes retrieved
in the message key field.</p>
<p><strong>Message text.</strong> The text of the message. For the RDQM0100
format, the number of bytes of message text returned is the maximum message
text length requested. For the RDQM0200 format, the number of bytes of message
text returned is the minimum of the maximum message text length requested field
or the enqueued message entry length field. For example, with RDQM0200, if the
maximum message text length requested is less than the enqueued message entry
length, some text of the data queue entry would not be returned.</p>
<p><strong>Number of message key bytes to retrieve.</strong> The number of
message key bytes to return for each data queue entry. The maximum value
allowed is 256. If the number of bytes requested exceeds the actual message key
length, the key is padded with binary zeros. If the number of message key bytes
requested is less than the actual key, the key is truncated.</p>
<p><strong>Number of message text bytes to retrieve.</strong> The number of
message text bytes to return for each data queue entry. The maximum value
allowed is 65536. The maximum message text length returned field is equal to
this value. If the number of bytes requested exceeds the actual message text
length, the text is padded with binary zeros if the RDQM0100 format is used. If
the RQDM0200 format is used, and the actual message text length is less than
the number of bytes requested, the number of bytes returned is the actual
message length, and no padding is done. If the number of message text bytes is
less than the actual text, the message text is truncated.</p>
<p><strong>Number of messages available.</strong> The number of messages on the
data queue that satisfy the search criteria specified in the Message selection
information parameter.</p>
<p><strong>Number of messages returned.</strong> The number of messages
retrieved.</p>
<p><strong>Offset to first message entry.</strong> The offset at which the
first message entry begins. If this value is 0, there is no message
available.</p>
<p><strong>Offset to next message entry.</strong> The offset to the next
message entry. If this value is 0, there are no more messages returned.</p>
<p><strong>Reserved.</strong> An unused field.</p>
<p><strong>Selection type.</strong> Selection type depends on the format
used.</p>
<p>For the RDQS0100 format, valid values are:</p>
<table cellpadding="5">
<!-- cols="5 95" -->
<tr>
<td align="left" valign="top"><em>A</em></td>
<td align="left" valign="top">All messages are to be returned in the order
based on the type of data queue. FIFO queues are returned in FIFO order, LIFO
queues are returned in LIFO order and keyed queues are returned in ascending
key order.</td>
</tr>
<tr>
<td align="left" valign="top"><em>F</em></td>
<td align="left" valign="top">The first message is to be returned</td>
</tr>
<tr>
<td align="left" valign="top"><em>L</em></td>
<td align="left" valign="top">The last message is to be returned</td>
</tr>
<tr>
<td align="left" valign="top"><em>R</em></td>
<td align="left" valign="top">All messages are to be returned in reverse order
of the type of data queue. For example, LIFO queues are returned in FIFO
order.</td>
</tr>
</table>
<p>For the RDQS0200 format, valid values are:</p>
<table cellpadding="5">
<!-- cols="5 95" -->
<tr>
<td align="left" valign="top"><em>K</em></td>
<td align="left" valign="top">Messages meeting the key criteria are to be
returned</td>
</tr>
</table>
<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 width="15%" valign="top">CPF3C21 E</td>
<td width="85%" valign="top">Format name &amp;1 is not valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3C24 E</td>
<td align="left" valign="top">Length of the receiver variable is 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">CPF3CF1 E</td>
<td align="left" valign="top">Error code parameter not valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9503 E</td>
<td align="left" valign="top">Cannot lock data queue &amp;1 in &amp;2.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9504 E</td>
<td align="left" valign="top">An invalid search order was specified.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9509 E</td>
<td align="left" valign="top">Space access error.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9511 E</td>
<td align="left" valign="top">Function not supported for DDM data queue
&amp;1.</td>
</tr>
<tr>
<td align="left" valign="top">CPF950B E</td>
<td align="left" valign="top">The specified selection type is not valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF950C E</td>
<td align="left" valign="top">The specified retrieve length is not valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF950D E</td>
<td align="left" valign="top">The specified message selection template length
is not valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF950E E</td>
<td align="left" valign="top">The data queue is not a keyed data queue.</td>
</tr>
<tr>
<td align="left" valign="top">CPF950F E</td>
<td align="left" valign="top">The specified key length is not valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9519 E</td>
<td align="left" valign="top">Internal program error occurred.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9801 E</td>
<td align="left" valign="top">Object &amp;2 in library &amp;3 not found.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9802 E</td>
<td align="left" valign="top">Not authorized to object &amp;2 in &amp;3.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9807 E</td>
<td align="left" valign="top">One or more libraries in library list
deleted.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9808 E</td>
<td align="left" valign="top">Cannot allocate one or more libraries on library
list.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9810 E</td>
<td align="left" valign="top">Library &amp;1 not found.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9820 E</td>
<td align="left" valign="top">Not authorized to use library &amp;1.</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">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: V2R3
<hr>
<table cellpadding="2" cellspacing="2" align="center">
<tr align="center">
<td valign="middle" align="center"><a href="#Top_Of_Page">Top</a> | <a href=
"obj1.htm">Object API categories</a> | <a href="aplist.htm">API by
category</a></td>
</tr>
</table>
</body>
</html>
Reference in New Issue View Git Blame Copy Permalink