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

658 lines
20 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>Retrieve Nonprogram Message Queue Attributes (QMHRMQAT) API</title>
<!-- Begin Header Records ========================================== -->
<!-- All rights reserved. Licensed Materials Property of IBM -->
<!-- US Government Users Restricted Rights -->
<!-- Use, duplication or disclosure restricted by -->
<!-- GSA ADP Schedule Contract with IBM Corp. -->
<!-- MH1TEMP SCRIPT A converted by B2H R4.1 (346) (CMS) by HOLTJM at -->
<!-- RCHVMW2 on 26 Jan 1999 at 10:37:34 -->
<!-- Change History: -->
<!-- YYMMDD USERID Change description -->
<!--File Edited Sept 2001 by v2cdijab -->
<!--End Header Records -->
<link rel="stylesheet" type="text/css" href="../rzahg/ic.css">
</head>
<body>
<a name="Top_Of_Page"></a>
<!-- Java sync-link -->
<script language="Javascript" src="../rzahg/synch.js" type="text/javascript">
</script>
<h2>Retrieve Nonprogram Message Queue Attributes (QMHRMQAT) API</h2>
<div class="box" style="width: 65%;">
<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="55%">Message queue information</td>
<td align="left" valign="top" width="15%">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 queue 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">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: No<br>
<!-- iddvc RMBR -->
<br>
</div>
<p>The Retrieve Nonprogram Message Queue Attributes (QMHRMQAT) API provides
information about the attributes of a nonprogram message queue. For more
information on the attributes of nonprogram message queues, see the Create
Message Queue (CRTMSGQ) command and the Change Message Queue (CHGMSGQ) command
documentation in the online help.</p>
<br>
<h3>Authorities and Locks</h3>
<dl>
<dt><em>Message queue</em></dt>
<dd>*USE</dd>
<dt><em>Message queue library</em></dt>
<dd>*EXECUTE</dd>
</dl>
<br>
<h3>Required Parameter Group</h3>
<dl>
<dt><strong>Message queue information</strong></dt>
<dd>OUTPUT; CHAR(*)
<p>The parameter to receive the message queue information. The format of the
returned data is specified in <a href="#HDRRMQA100">RMQA0100 Format</a>.</p>
</dd>
<dt><strong>Length of message queue information</strong></dt>
<dd>INPUT; BINARY(4)
<p>The size of the area to contain the message information, in bytes. If the
length specified is larger than the actual size of the message queue
information parameter, the results may not be predictable. The minimum length
is 8 bytes.</p>
</dd>
<dt><strong>Format name</strong></dt>
<dd>INPUT; CHAR(8)
<p>The format of the information to be returned. You must use the following
format name:</p>
<table cellpadding="5">
<!-- cols="15 85" -->
<tr>
<td align="left" valign="top"><em>RMQA0100</em></td>
<td align="left" valign="top">This format is described in <a href=
"#HDRRMQA100">RMQA0100 Format</a>.</td>
</tr>
</table>
<br>
</dd>
<dt><strong>Qualified message queue name</strong></dt>
<dd>INPUT; CHAR(20)
<p>The message queue and the library in which the message queue is located. The
first 10 characters contain the message queue name, and the second 10
characters contain the message queue library. You can use these special values
for the library name:</p>
<table cellpadding="5">
<!-- cols="15 85" -->
<tr>
<td align="left" valign="top"><em>*CURLIB</em></td>
<td align="left" valign="top">The job's current library</td>
</tr>
<tr>
<td align="left" valign="top"><em>*LIBL</em></td>
<td align="left" valign="top">The library list</td>
</tr>
</table>
<br>
</dd>
<dt><strong>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="HDRRMQA100">RMQA0100 Format</a></h3>
<p>The following table shows the information returned in the message queue
information parameter for the RMQA0100 format. For a detailed description of
each field, see <a href="#HDRRMQAFD">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">CHAR(10)</td>
<td align="left" valign="top">Message queue used</td>
</tr>
<tr>
<td align="center" valign="top">18</td>
<td align="center" valign="top">12</td>
<td align="left" valign="top">CHAR(10)</td>
<td align="left" valign="top">Message queue library used</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">Number of messages on queue</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">Current storage size</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">Increment storage size</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">Number of increments</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">Maximum increments</td>
</tr>
<tr>
<td align="center" valign="top">48</td>
<td align="center" valign="top">30</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Severity code filter</td>
</tr>
<tr>
<td align="center" valign="top">52</td>
<td align="center" valign="top">34</td>
<td align="left" valign="top">CHAR(7)</td>
<td align="left" valign="top">Delivery</td>
</tr>
<tr>
<td align="center" valign="top">59</td>
<td align="center" valign="top">3B</td>
<td align="left" valign="top">CHAR(10)</td>
<td align="left" valign="top">Break-handling program name</td>
</tr>
<tr>
<td align="center" valign="top">69</td>
<td align="center" valign="top">45</td>
<td align="left" valign="top">CHAR(10)</td>
<td align="left" valign="top">Break-handling program library</td>
</tr>
<tr>
<td align="center" valign="top">79</td>
<td align="center" valign="top">4F</td>
<td align="left" valign="top">CHAR(4)</td>
<td align="left" valign="top">Force to auxiliary storage</td>
</tr>
<tr>
<td align="center" valign="top">83</td>
<td align="center" valign="top">53</td>
<td align="left" valign="top">CHAR(50)</td>
<td align="left" valign="top">Text description</td>
</tr>
<tr>
<td align="center" valign="top">133</td>
<td align="center" valign="top">85</td>
<td align="left" valign="top">CHAR(1)</td>
<td align="left" valign="top">Allow alerts</td>
</tr>
<tr>
<td align="center" valign="top">134</td>
<td align="center" valign="top">86</td>
<td align="left" valign="top">CHAR(2)</td>
<td align="left" valign="top">Reserved</td>
</tr>
<tr>
<td align="center" valign="top">136</td>
<td align="center" valign="top">88</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Coded character set identifier (CCSID)</td>
</tr>
<tr>
<td align="center" valign="top">140</td>
<td align="center" valign="top">8C</td>
<td align="left" valign="top">CHAR(10)</td>
<td align="left" valign="top">Message queue full action</td>
</tr>
<tr>
<td align="center" valign="top">150</td>
<td align="center" valign="top">96</td>
<td align="left" valign="top">CHAR(10)</td>
<td align="left" valign="top">Allow other jobs to reply</td>
</tr>
</table>
<br>
<br>
<h3><a name="HDRRMQAFD">Field Descriptions</a></h3>
<p><strong>Allow alerts.</strong> Whether this message queue allows alerts to
be generated from alert messages sent to it. The values are:</p>
<table cellpadding="5">
<!-- cols="5 95" -->
<tr>
<td align="left" valign="top"><em>1</em></td>
<td align="left" valign="top">Allow alerts to be generated</td>
</tr>
<tr>
<td align="left" valign="top"><em>0</em></td>
<td align="left" valign="top">Do not allow alerts to be generated</td>
</tr>
</table>
<p>See the <a href="../books/sc415413.pdf" target="_blank">Alerts
Support</a> <img src="wbpdf.gif" alt="Link to PDF"> book for information on
alerts.</p>
<p><strong>Allow other jobs to reply.</strong> Whether other jobs can reply to
messages on the message queue when it is in *BREAK delivery mode with a
break-handling program other than *DSPMSG specified.</p>
<p>The field is set to *ALWRPY if the queue is in break mode and *DSPMSG is the
break-handling program.</p>
<p>The field is set to blanks if the queue is not in break mode.</p>
<p>The possible values follow:</p>
<table cellpadding="5">
<!-- cols="15 85" -->
<tr>
<td align="left" valign="top"><em>*NOALWRPY</em></td>
<td align="left" valign="top">When the message queue is in *BREAK mode with a
break-handling program other than *DSPMSG specified, other jobs can display the
message queue but cannot reply to inquiry messages on the message queue.</td>
</tr>
<tr>
<td align="left" valign="top"><em>*ALWRPY</em></td>
<td align="left" valign="top">When the message queue is in *BREAK mode with a
break-handling program other than *DSPMSG specified, other jobs can reply to
inquiry messages on the message queue.</td>
</tr>
</table>
<p><strong>Break-handling program library.</strong> The library that is
specified for the break-handling program.</p>
<p>If the message queue is not in break mode or the break-handling program name
is specified as *DSPMSG, this field is set to blanks.</p>
<p>The following special values or a specific library may be returned:</p>
<table cellpadding="5">
<!-- cols="15 85" -->
<tr>
<td align="left" valign="top"><em>*LIBL</em></td>
<td align="left" valign="top">The library list is used to locate the
program.</td>
</tr>
<tr>
<td align="left" valign="top"><em>*CURLIB</em></td>
<td align="left" valign="top">The current library for the job is used to locate
the program.</td>
</tr>
</table>
<p><strong>Break-handling program name.</strong> The program that is called
when messages are sent to this message queue. The delivery field must be set to
*BREAK. The severity of the message sent to the queue must be equal to or
greater than the value shown in the severity code filter field.</p>
<p>The field is set to *DSPMSG if the queue is in break mode and there is no
break-handling program set.</p>
<p>The field is set to blanks if the queue is not in break mode.</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>Coded character set identifier (CCSID).</strong> The coded character
set identifier (CCSID) that is associated with this message queue. A special
value of 65535 means that no conversions are to occur when sending or receiving
messages from this message queue. A special value of 65534 means to use the
CCSID associated with the message when conversions are to occur. For more
information about the message handler use of CCSIDs, see <a href=
"../nls/rbagsccsidmsgsup2.htm">CCSIDs: Message Support</a> in the Globalization
topic.</p>
<p><strong>Current storage size.</strong> The current storage size of the
message queue in bytes.</p>
<p><strong>Delivery.</strong> How the messages that are sent to this message
queue are delivered. The method of delivery is in effect only as long as the
message queue is allocated to a job. When the queue is no longer allocated, the
delivery mode is changed to *HOLD for work-station, system-operator, and user
message queues. The possible values follow:</p>
<table cellpadding="5">
<!-- cols="15 85" -->
<tr>
<td align="left" valign="top"><em>*HOLD</em></td>
<td align="left" valign="top">The messages are held in the message queue until
they are requested by a user or program.</td>
</tr>
<tr>
<td align="left" valign="top"><em>*BREAK</em></td>
<td align="left" valign="top">When a message arrives at the message queue, the
job to which the message queue is allocated is interrupted. Then the program
specified on the break-handling program name field is called. If the
break-handling program name is set to *DSPMSG, the Display Message (DSPMSG)
command is processed.</td>
</tr>
<tr>
<td align="left" valign="top"><em>*NOTIFY</em></td>
<td align="left" valign="top">When a message arrives at the message queue, an
interactive job to which the message queue is allocated is notified. The
message light turns on and a buzzer sounds (if the feature is available).</td>
</tr>
<tr>
<td align="left" valign="top"><em>*DFT</em></td>
<td align="left" valign="top">Messages requiring replies are answered with
their default reply. No messages are added to the message queue unless the
message queue is QSYSOPR.</td>
</tr>
</table>
<p><strong>Force to auxiliary storage.</strong> Whether changes made to the
message queue description or messages added to or removed from the queue are
immediately forced into auxiliary storage. If the value is *YES and a system
failure occurs, the changes to the message queue are not lost.</p>
<p>One of the following modes is returned:</p>
<table cellpadding="5">
<!-- cols="10 90" -->
<tr>
<td align="left" valign="top"><em>*YES</em></td>
<td align="left" valign="top">All changes to the message queue description and
to the messages in the queue are immediately forced into auxiliary
storage.</td>
</tr>
<tr>
<td align="left" valign="top"><em>*NO</em></td>
<td align="left" valign="top">Changes made to the message queue description,
including its messages, are not immediately forced into auxiliary storage.</td>
</tr>
</table>
<p><strong>Increment storage size.</strong> The number of bytes added each time
the message queue is increased in size.</p>
<p><strong>Maximum increments.</strong> The maximum number of times the message
queue can be incremented. If *NOMAX is specified for this attribute when the
message is created, the value determined by the system as the maximum number of
times that the message queue can be incremented is returned.</p>
<p><strong>Message queue full action.</strong> The action to take when the
message queue becomes full. The possible values follow:</p>
<table cellpadding="5">
<!-- cols="15 85" -->
<tr>
<td align="left" valign="top"><em>*SNDMSG</em></td>
<td align="left" valign="top">When the queue is full, message CPF2460 (Message
queue could not be extended) will be sent to the program or user that sends a
message to the full message queue.</td>
</tr>
<tr>
<td align="left" valign="top"><em>*WRAP</em></td>
<td align="left" valign="top">When the queue is full, it is wrapped by removing
messages from the queue to make space for new messages to be added to the
queue.</td>
</tr>
</table>
<p><strong>Message queue library used.</strong> The actual library name that
contains the message queue.</p>
<p><strong>Message queue used.</strong> The name of the message queue whose
attributes were returned.</p>
<p><strong>Number of increments.</strong> The number of times that the message
queue has been increased in size.</p>
<p><strong>Number of messages on queue.</strong> The number of messages
currently on the message queue.</p>
<p><strong>Severity code filter.</strong> The lowest severity level that a
message can have and still be delivered to a user in break or notify mode.
Messages arriving at the message queue whose severities are lower than that
specified here do not interrupt the job or turn on the message waiting light.
Valid values are 0 through 99.</p>
<p><strong>Reserved.</strong> An ignored field.</p>
<p><strong>Text description.</strong> Text that briefly describes the message
queue.</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%">CPF24B4 E</td>
<td align="left" valign="top" width="85%">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 &amp;1.</td>
</tr>
<tr>
<td align="left" valign="top">CPF2403 E</td>
<td align="left" valign="top">Message queue &amp;1 in &amp;2 not found.</td>
</tr>
<tr>
<td align="left" valign="top">CPF2408 E</td>
<td align="left" valign="top">Not authorized to message queue &amp;1.</td>
</tr>
<tr>
<td align="left" valign="top">CPF2477 E</td>
<td align="left" valign="top">Message queue &amp;1 currently in use.</td>
</tr>
<tr>
<td align="left" valign="top">CPF2536 E</td>
<td align="left" valign="top">Value &amp;1, for the length of message queue
information 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 &amp;1 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">CPF8127 E</td>
<td align="left" valign="top">&amp;8 damage on message queue &amp;4 in &amp;9.
VLIC log-&amp;7.</td>
</tr>
<tr>
<td align="left" valign="top">CPF8176 E</td>
<td align="left" valign="top">Message queue for device description &amp;4
damaged.</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>
<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>
<br>
</body>
</html>