System i: Programming Message Handling APIs - IBM
System i: Programming Message Handling APIs - IBM
System i: Programming Message Handling APIs - IBM
You also want an ePaper? Increase the reach of your titles
YUMPU automatically turns print PDFs into web optimized ePapers that Google loves.
5 Format of message selection information Input Char(8)<br />
6 Error code I/O Char(*)<br />
Default Public Authority: *USE<br />
Threadsafe: No<br />
The List Nonprogram <strong>Message</strong>s (QMHLSTM) API lists messages from one or two nonprogram message<br />
queues. This API obtains the requested message information and returns it in a user space through the<br />
format specified in the parameter list.<br />
If multiple message queues are specified, the messages are sorted by their sending dates and times.<br />
However, messages listed as a reply message to an inquiry or a sender’s copy message are sorted<br />
differently. When a reply message exists for one of these types, it is listed immediately following the<br />
inquiry or sender’s copy message with which it is associated.<br />
If messages in multiple queues have identical sending dates and times, the message from the first queue<br />
in the qualified message queue names array is listed first.<br />
If the last message listed is an inquiry or sender’s copy message, the user must call the API again using<br />
parameters that would include listing the next later message after the inquiry or sender’s copy message<br />
in order to determine and obtain an available reply message.<br />
The QMHLSTM API lists messages from nonprogram message queues only. The QMHLSTM API cannot<br />
be used to list messages sent to a job log (including the external message (*EXT) queue of a job). See “List<br />
Job Log <strong>Message</strong>s (QMHLJOBL) API” on page 13 (QMHLJOBL) API for information on listing messages<br />
sent to a job log. QMHLSTM cannot be used to list messages sent to the history log (QHST).<br />
The generated list replaces any existing information in the user space.<br />
If the user space is not large enough to contain the amount of data that is to be returned, the user space<br />
is increased up to the maximum user space size allowed (16MB) or to the maximum amount of storage<br />
allowed to the user of the API. If this is not large enough to contain the data to be returned, only the<br />
number of complete messages that fit in the user space are returned. The information status field in the<br />
generic header is set to P (partial but accurate). The user can then resubmit the request from the last<br />
message returned to obtain the additional messages. The key of the last message listed for each message<br />
queue is provided in the ending message key field in the header portion of the user space.<br />
An alternative to making multiple calls to QMHLSTM to list all of the messages is to change to use the<br />
Open List of <strong>Message</strong>s (QGYOLMSG) API. QGYOLMSG can create a list that contains up to 2GB of data.<br />
Instead of acessing a user space to get the message entries, the Get List Entry (QGYGTLE) API is used to<br />
get the the message entries from the list created by QGYOLMSG.<br />
New messages are prevented from being added to or removed from the message queues being listed<br />
during the use of this API. The maximum messages requested field and the number of fields to return<br />
field for each listed message increases the time that the queues are unavailable. Users of this API should<br />
use caution when listing many messages or many fields. Try to avoid causing lock-out situations on<br />
highly used message queues.<br />
Authorities and Locks<br />
<strong>Message</strong> queue<br />
*USE<br />
<strong>Message</strong> queue library<br />
*EXECUTE<br />
<strong>Message</strong> <strong>Handling</strong> <strong>APIs</strong> 31
Change language