List Nonprogram Messages (QMHLSTM) API


  Required Parameter Group:


  Default Public Authority: *USE

  Threadsafe: No

The List Nonprogram Messages (QMHLSTM) API lists messages from one or two nonprogram message queues. This API obtains the requested message information and returns it in a user space through the format specified in the parameter list.

If multiple message queues are specified, the messages are sorted by their sending dates and times. However, messages listed as a reply message to an inquiry or a sender's copy message are sorted differently. When a reply message exists for one of these types, it is listed immediately following the inquiry or sender's copy message with which it is associated.

If messages in multiple queues have identical sending dates and times, the message from the first queue in the qualified message queue names array is listed first.

If the last message listed is an inquiry or sender's copy message, the user must call the API again using parameters that would include listing the next later message after the inquiry or sender's copy message in order to determine and obtain an available reply message.

The QMHLSTM API lists messages from nonprogram message queues only. The QMHLSTM API cannot be used to list messages sent to a job log (including the external message (*EXT) queue of a job). See List Job Log Messages (QMHLJOBL) API for information on listing messages sent to a job log. QMHLSTM cannot be used to list messages sent to the history log (QHST).

The generated list replaces any existing information in the user space.

If the user space is not large enough to contain the amount of data that is to be returned, the user space is increased up to the maximum user space size allowed (16MB) or to the maximum amount of storage allowed to the user of the API. If this is not large enough to contain the data to be returned, only the number of complete messages that fit in the user space are returned. The information status field in the generic header is set to P (partial but accurate). The user can then resubmit the request from the last message returned to obtain the additional messages. The key of the last message listed for each message queue is provided in the ending message key field in the header portion of the user space.

An alternative to making multiple calls to QMHLSTM to list all of the messages is to change to use the Open List of Messages (QGYOLMSG) API. QGYOLMSG can create a list that contains up to 2GB of data. Instead of acessing a user space to get the message entries, the Get List Entry (QGYGTLE) API is used to get the the message entries from the list created by QGYOLMSG.

New messages are prevented from being added to or removed from the message queues being listed during the use of this API. The maximum messages requested field and the number of fields to return field for each listed message increases the time that the queues are unavailable. Users of this API should use caution when listing many messages or many fields. Try to avoid causing lock-out situations on highly used message queues.


Authorities and Locks

Message queue
*USE
Message queue library
*EXECUTE
User space
*CHANGE
User space library
*EXECUTE
User space lock
*EXCLRD

Required Parameter Group

Qualified user space name
INPUT;CHAR(20)

The user space that receives the generated list, and the library in which it is located. The first 10 characters contain the user space name, and the second 10 characters contain the user space library. You can use these special values for the library name:


Format name
INPUT; CHAR(8)

The format of the returned message information. You must use this format:


Message selection information
INPUT; CHAR(*)

The information that determines the message queues and messages to be listed. The format of this information is described in MSLT0100 Format and in MSLT0200 Format.

Size of message selection information
INPUT; BINARY(4)

The size, in bytes, of the message selection information parameter.

Format of message selection information
INPUT; CHAR(8)

The format of the message selection information parameter. You must use one of these formats:

Error code
I/O; CHAR(*)

The structure in which to return error information. For the format of the structure, see Error code parameter.


Format of Generated Lists

The user space created consists of:

For details about the user area and generic header, see User spaces. For details about the remaining items, see the following sections. For descriptions of each field in the list returned, see Field Descriptions.


Input Parameter Section



Header Section



LSTM0100 Format

The following table shows the information returned in the list data section of the user space for the LSTM0100 format. The offsets listed are from the beginning of the user space. For a detailed description of each field, see Field Descriptions.

The structure defined by this format is repeated for each message entry returned.



MSLT0100 Format

The organization of the MSLT0100 format of the message selection information parameter follows. For a detailed description of each field, see Field Descriptions.



MSLT0200 Format

The organization of the MSLT0200 format of the message selection information parameter follows. For a detailed description of each field, see Field Descriptions.



Valid Field Identifiers

The following table contains a list of the valid identifiers for the MSLT0100 and the MSLT0200 format.



Field Descriptions

Alert option. Whether and when an SNA alert is created and sent for the message. If a message is listed, the value is one of the following:

For more information on alerts, see the Alerts Support Link to PDF manual.

This field is set to blanks if no alert option was specified when the message was sent.

CCSID conversion status indicator for data. The following values may be returned:

CCSID conversion status indicator for text. The following values may be returned:

Coded character set identifier (CCSID) for data. The coded character set identifier that the data is returned in. If a conversion error occurs or if the CCSID you requested the data to be converted to is 65535, the CCSID of the data is returned. If there is no *CCHAR replacement data, 65535 is returned. Otherwise the CCSID you wanted the data converted to is returned.

This only applies to the part of the replacement data that corresponds to a convertible character data type (*CCHAR).

For more information about message handler and its use of CCSIDs, see CCSID support for messages.

Coded character set identifier (CCSID) for text. The coded character set identifier that the message text is returned in. If a conversion error occurs or if the CCSID you requested the message text to be converted to is 65535, the CCSID that the message text is stored in is returned. Otherwise the CCSID you wanted your message text converted to is returned. If you do not want the message text converted before it is returned to you but you do want to know the CCSID that the message text is stored in, specify 65535 on the Coded character set identifier to return text and data in parameter. The CCSID that the message text is stored in is returned in the Coded character set identifier for text output field.

This applies to the following fields only:

Note: This CCSID value does not apply to the replacement data that has been substituted into the text. See the Coded character set identifier for data for this information.

Coded character set identifier (CCSID) to return text and data in. The CCSID that the text and data are converted to before they are returned. The following values are allowed:

Coded character set identifier (CCSID) specified. The CCSID that was specified that the text and data are converted to before they are returned.

Coded character set identifier (CCSID) used. The CCSID that was used that the text and data are converted to before they are returned.

Critical break message status. Whether the message was sent by the operating system as a critical break message. The following values are returned:

Data. The data returned for the specified identifier field.

Date sent. The date on which the message was sent, in CYYMMDD (century, year, month, and day) format.

Date and time criteria. The date and time starting point for messages to be listed. This is optional and must be blanks if not specified. The search for messages to list begins from the message that is specified by the starting message key. If the date and time criteria is specified in the call to the API and the list direction is *PRV, then only messages whose time of arrival on the queue is equal to or less than the date and time criteria that is specified are listed. Similarly, if the direction is *NEXT and the date and time criteria is specified on the call to the API, then only those messages whose time of arrival on the queue is equal to or greater than that specified are listed. The format of this field is in the CYYMMDDHHMMSS as follows:

Date and time criteria specified. The date and time criteria as specified on the call to the API.

Date and time of first message listed. The date and time of the first message that is actually listed by the API. If no message is actually listed by the API, this field is blank.

Date and time of last message listed. The date and time of the last message that is actually listed by the API. If no message is actually listed by the API, this field is blank.

Default reply. The text of the default reply. When a stored message is being listed and a default reply exists. If this is not an inquiry message or no default reply exists, this field is not used and the length of data field is 0.

Ending message key used. The message keys of the last message actually listed by the API. If no message is listed from a particular queue, the value returned for that queue is the same as that in the starting message key specified field.

Format of message selection information specified. The format name of the message selection information parameter as specified on the call to the API.

Format name specified. The format name as specified on the call to the API.

Identifier field. The field returned. See Valid Field Identifiers for the list of valid field identifiers.

Identifiers of fields to return. The list of the field identifiers to be returned in the LSTM0100 format. For a list of the valid field identifiers, see Valid Field Identifiers. An error is returned if the identifier matches one specified earlier in the array, or if the identifier is not valid.

Identifiers of fields to return specified. The list of field identifiers to return as specified on the call to the API.

Length of data. The length of the data returned for the data field, in bytes.

Length of field information returned. The total length of information returned for this field, in bytes.

List direction. The direction to list messages. You must use one of these directions:

If multiple message queues are to be listed, messages are intermixed and sorted by date and time in the specified manner.

List direction specified. The direction to list messages as specified on the call to the API.

Maximum message help length. The maximum number of characters of text that this API returns for field identifiers 0401, 0402, 0403, and 0404. (See Valid Field Identifiers.)

Specify a value to limit the number of characters returned for field identifiers 0401, 0402, 0403, and 0404. This value can be no smaller than 4. The maximum allowed value is 32765. To specify that the maximum length be used, use the special value of -1. This value is not checked if field identifiers 0401, 0402, 0403, or 0404 are not specified.

Maximum message help length specified. The maximum number of characters to return for field identifiers 0401, 0402, 0403, and 0404 as specified on the call to the API.

Maximum message length. The maximum number of characters of text that this API returns for field identifiers 0301 and 0302. (See Valid Field Identifiers.)

Specify a value to limit the number of characters returned for field identifiers 0301 and 0302. This value can be no smaller than 4. The maximum allowed value is 32765. To specify that the maximum length be used, use the special value of -1. This value is not checked if field identifiers 0301 or 0302 are not specified.

Maximum message length specified. The maximum number of characters to return for field identifiers 0301 and 0302 as specified on the call to the API.

Maximum messages requested. The maximum number of messages to be returned.

If fewer messages than the number requested exist on the queues, only the number of messages that exist are returned. No error is signaled, and the information status field in the generic header would be marked as C for complete and accurate.

Use the special value of -1 to list all messages on the queues in the specified list direction. The list runs from the starting message keys that meet the selection and severity criteria.

Maximum messages requested specified. The number of messages requested to be listed as specified on the call to the API.

Message. The text of a predefined message without replacement data substitution. If an impromptu message is listed, this field contains the impromptu message text.

Message file library specified at send time. The name of the library containing the message file as specified when the message was sent. If *CURLIB or *LIBL was specified for the library when the message was sent, 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.

Message file library used. The actual name of the library that contains the message file used to retrieve the message information. If an immediate message is listed, this field is set to blanks.

Message file name. The name of the message file containing the message listed.

Message help. The message help for the message listed without formatting characters and without replacement data. If an impromptu message is listed, this field contains the impromptu message text.

Message help with formatting characters. The message help for the message listed, including formatting characters.

Three format control characters can be returned within the message. They are defined in the online help for the Add Message Description (ADDMSGD) command to have these meanings:

If an impromptu message is listed, this field contains the impromptu message text.

Message help with replacement data. The message help for the message listed, including the replacement data. If an impromptu message is listed, this field contains the impromptu message text.

Message help with replacement data and formatting characters. The message help for the message listed, including the replacement data and the formatting characters. See the message help with formatting characters field for an explanation of formatting characters. If an impromptu message is listed, this field contains the impromptu message text.

Message identifier. The identifying code of the message listed. If an impromptu message is listed, this field is set to blanks.

Message key. The key of the message listed.

Message queue. The name of the message queue where the message was listed.

Message queue library used. The actual library that contains the message queue.

Message queue names specified. The qualified message queue names specified on the call to the API.

Message queue names used. The actual message queue names used to list messages. The first 10 characters are the message queue name, and the second 10 characters are the message queue library.

Message severity. The severity of the message listed. Possible values are 0 through 99.

Message type. The type of message listed. The possible values and their meanings follow:

Message with replacement data. The text of a predefined message with the replacement data included. If an impromptu message is listed, this field contains the impromptu message text.

Microseconds. The microseconds part of the time sent.

Number of fields returned. The number of identifier fields returned to the application.

Number of fields to return. The number of fields to return in the LSTM0100 format (the number of entries in the identifiers of fields to return array).

Number of fields to return specified. The number of identifier fields to return as specified on the call to the API.

Number of message queues. The number of message queues to list. The valid values follow:

Number of message queues specified. The number of message queues to be listed as specified on the call to the API. This is the size of the declared array of the message queue names specified and the starting message key specified fields.

Number of message queues used. The number of message queues listed. This is the number of elements in the message queue names used, starting message key used, and ending message key arrays.

Number of receiving statement numbers or instruction numbers available followed by an array of the receiving statement numbers or instruction numbers. This field can be specified for the QMHLSTM API, but it never returns any data and the length of data field is 0.

Number of sending statement numbers or instruction numbers available followed by an array of the sending statement numbers or instruction numbers. This field can be specified for the QMHLSTM API, but it never returns any data and the length of data field is 0.

Offset to ending message key. The offset, in bytes, from the beginning of the user space to the beginning of the ending message key field.

Offset to fields returned. The offset, in bytes, from the beginning of the user space to the beginning of the first repeating identified field of the LSTM0100 format.

Offset to identifiers of fields to return. The offset, in bytes, from the beginning of the message selection information parameter to the beginning of the identifiers of fields to return field.

Offset to identifiers of fields to return specified. The offset, in bytes, from the beginning of the user space to the beginning of the identifiers of fields to return specified field.

Offset to message queue names specified. The offset, in bytes, from the beginning of the user space to the beginning of the message queue names specified field.

Offset to message queue names used. The offset, in bytes, from the beginning of the user space to the beginning of the message queue names used field.

Offset to qualified message queue names. The offset, in bytes, from the beginning of the message selection information parameter to the beginning of the qualified message queue names field.

Offset to starting message keys. The offset, in bytes, from the beginning of the message selection information parameter to the beginning of the starting message key field.

Offset to starting message key specified. The offset, in bytes, from the beginning of the user space to the beginning of the starting message key specified field.

Offset to starting message key used. The offset, in bytes, from the beginning of the user space to the beginning of the starting message key used field.

Offset to the next entry. The offset, in bytes, from the beginning of the user space to the beginning of the next message entry.

Offset to the next field information returned. The offset, in bytes, from the beginning of the user space to the beginning of the next repeating identified field of the LSTM0100 format.

Problem identification. The number the system generates to identify a problem if problem analysis can be run for the message being listed. The problem identification is in the following format:

If problem analysis cannot be run, and this field is specified, the length of data field is 0.

Qualified message queue names. The list of message queues and the libraries where the message queues are located. The number of entries in the array must match the number specified in the number of message queues field. The first 10 characters of each entry contain the message queue name, and the second 10 characters of each entry contain the message queue library. You can use the following values for the library name:

Qualified sender job name. The name of the job that sent the message. The job name has three parts:

Receiving module name. This field can be specified for the QMHLSTM API, but it never returns any data and the length of data field is 0.

Receiving procedure name. This field can be specified for the QMHLSTM API, but it never returns any data and the length of data field is 0.

Receiving program name. This field can be specified for the QMHLSTM API, but it never returns any data and the length of data field is 0.

Receiving type. This field can be specified for the QMHLSTM API, but it never returns any data and the length of data field is 0.

Replacement data or impromptu message text. The values for replacement variables in a predefined message, or the text of an impromptu message. If the message identifier field is not blank, this field contains message data. If the message identifier field is blank, this field contains impromptu message text.

Any pointer data in this field is marked as not valid if both:

Reply status. The reply status of the message (whether it accepts a reply, and if so, whether a reply has been sent). Possible values and their meanings follow:

Request level. This field can be specified for the QMHLSTM API, but it never returns any data and the length of data field is 0.

Request status. This field can be specified for the QMHLSTM API, but it never returns any data the length of data field is 0.

Reserved. An ignored field.

Selection criteria. The type of messages to be listed. Valid values follow:

Selection criteria specified. The selection criteria as specified on the call to the API.

Sender type. This field can be specified for the QMHLSTM API, but it never returns any data and the length of data field is 0.

Sending module name. This field can be specified for the QMHLSTM API, but it never returns any data and the length of data field is 0.

Sending procedure name. This field can be specified for the QMHLSTM API, but it never returns any data and the length of data field is 0.

Sending program name. The sending program name or ILE program name that contains the procedure sending the message. Under certain conditions, the actual name of the program that sent the message is not known. In these cases, this field contains the 6-byte hexadecimal address of the program converted into 12 displayable characters. In all other cases, the 10-character program name is returned left-justified in the field; the final 2 characters contain blanks.

Sending statement numbers or instruction numbers. This field can be specified for the QMHLSTM API, but it never returns any data and the length of data field is 0.

Sending user profile. The name of the user profile that the thread was running under when the message was sent.

Severity criteria. The minimum severity of a message to be included in the list. The value must be between 0 and 99. To retrieve all messages, specify a severity criteria of 0.

Severity criteria specified. The severity criteria as specified on the call to the API.

Size of message selection information specified. The size of the message selection information field, in bytes, as specified in the call to the API.

Starting message key. The message key used to begin searching for messages to list from the corresponding entry in the qualified message queue names field. You can use these special values for the message keys:

If a value other than X'00000000' or X'FFFFFFFF' is specified and a message with that key does not exist, an error is returned.

If the message that is specified by the starting message key exists but does not meet the selection criteria, the severity criteria, or the date and time criteria fields that are specified, no error is returned. The search for messages to list begins from the message that is specified by the starting message key.

Starting message key specified. The starting message keys as specified on the call to the API.

Starting message key used. The message keys of the first message actually listed by the API. If no message is listed from a particular message queue, the value returned for that queue is the same as that in the starting message key specified field.

Status of data. The status of the data listed for this message. Possible values and their meanings follow:

This field is applicable to the field identifiers that are retrieved from the message file for a stored message. A description of the action that occurs for specific field identifiers when the status of data field is not blank follows:

This field is also applicable to the various sending information fields (identifiers 0601, 0603) when a problem is encountered while attempting to retrieve this information. When one of these fields cannot be retrieved from the message:

The status of data field is always blank for the other field identifiers. The length of data field is zero.

Time sent. The time at which the message being listed was sent, in HHMMSS (hour, minute, and second) format.

Type of data. The type of data returned.

User space library specified. The name of the user space library as specified on the call to the API.

User space library used. The actual name of the library where this user space was found.

User space name specified. The name of the user space as specified on the call to the API.

User space name used. The actual name of the user space used to store the data listed.


Error Messages


API introduced: V2R3

[ Back to top | Message Handling APIs | APIs by category ]