Open List of Messages (QGYOLMSG) API

The Open List of Messages (QGYOLMSG) API provides information on one of the following:

• Messages for the current user
• Messages for a specific user
• Messages on one specific message queue

If messages for the current user are to be listed, the user's messages are listed from both the user message queue and the APPC device message queue. The messages are sorted by their type and sending date and time, unless the message being listed is a message needing a reply or a reply message. When a reply message exists for a message needing a reply, the reply message is not positioned by the sending date and time of the reply. The reply message is listed immediately after the message that needs a reply.

This API only lists messages from nonprogram message queues. The Open List of Messages API cannot be used to list messages sent to a job log (including *EXT) or to list messages sent to the QHST message queue.

New messages are prevented from being added to or removed from the message queues listed during the use of the QGYOLMSG API when it calls the List Nonprogram Messages (QMHLSTM) API.

Message file overrides are not honored by the server job when the list is built asynchronously by the server job.

Note: The QTEMP library and the system portion of the library list could be different between the main job and the server job when the list is being built asynchronously. If this is a problem, then request that the list be built synchronously.

For more information, see Process Open List APIs.

Differences between the QMHLSTM and QGYOLMSG APIs

The differences between the QGYOLMSG API and the List Nonprogram Messages (QMHLSTM) API follow:

• The message information for the QGYOLMSG API is returned into a receiver variable instead of a user space.
• The request handle parameter was added to the QGYOLMSG API so that a distinct value is associated with the list. This value ensures that a request for more messages from the list (Get List Entries (QGYGTLE) API) is sent to the correct list.
• The total records parameter was added to the QGYOLMSG API so that the caller of the API knows the size of the list from which information can be requested.
• The records returned parameter was added to the QGYOLMSG API. If the request is for X records and only Y records exist (where Y > X), the requestor is aware that it did not get the number of records requested.
• The amount of information returned by the QMHLSTM API is limited by the size of a user space, approximately 16MB. The list created by the QGYOLMSG API can contain up to 2GB of information.

Difference between the QSYRUSRI and QGYOLMSG APIs

The difference between the QGYOLMSG API and the Retrieve User Information (QSYRUSRI) API is:

• The user name parameter was added to the QGYOLMSG API so that the message queue name for that user can be retrieved by calling the QSYRUSRI API.

Authorities and Locks

Message Queue

*USE

Message Queue Library

*EXECUTE

Required Parameter Group

Receiver variable

OUTPUT; CHAR(*)

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.

The entries returned are in the LSTM0100 format. See LSTM0100 Format for information about the format.

Length of receiver variable

INPUT; BINARY(4)

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.

List information

OUTPUT; CHAR(80)

The variable used to return status information about the list of messages that was opened. For a description of the layout of this parameter, see Format of Open List Information.

Number of records to return

INPUT; BINARY(4)

The number of records in the list to put into the receiver variable after the sorting has been done. The valid values for this field are as follows:

-1	All records are built synchronously in the list by the main job.
0	All records are built asynchronously in the list by a server job.

If a positive number of records is specified, at least that many records are built synchronously (in order to return those records immediately to the caller of this API), and the remainder are built asynchronously by a server job.

Sort information

INPUT; CHAR(1)

Indicates whether the list should be sorted by type if the selection criteria contains *ALL. Possible values are as follows:

0	No sort
1	Sort by the following message types in the listed order: *MNR Unanswered, inquiry-type messages *SCNR Unanswered, sender's-copy type of messages *MNNR Informational, completion, diagnostic, request, notify, escape, request, answered inquiry, and answered, sender's-copy type messages.

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 Message Selection Information Format.

Size of message selection information

INPUT; BINARY(4)

The size, in bytes, of the message selection information parameter. The minimum value required for this parameter is 62.

User or queue information

INPUT; CHAR(21)

The name that is given (the user name or the qualified user message queue name) and the value of that name. This parameter consists of the following parts:

User or queue indicator

CHAR(1)

Whether a value is given in the user name part of this parameter, or in the qualified-user message queue name part of this parameter. One of the following values must be specified:

0	The user name is given
1	The user message queue name is given

Depending on the value of this parameter, either the user name or the qualified-user message queue name contains a nonblank value.

User or queue name

CHAR(20)

If the user or queue indicator value is 0, the first 10 characters specify the user name for which information is returned; the last 10 characters must be blank. You can specify the following special value in the first 10 characters:

*CURRENT

The information for the user running currently is returned.

This value is used to get the message queue name for the user.

If the user or queue indicator value is 1, this field contains the name of a message queue. The first 10 characters contain the name of the message queue, and the second 10 characters contain the name of the library where the message queue is located.

Message queues used

OUTPUT; CHAR(44)

The name given (the user name or the qualified user message queue name) and the value of that name. This parameter consists of two parts:

Number of queues used

BINARY(4)

The number of message queues used to build the list. This value is 2 if both of the following list items are true:

• *CURRENT is specified for the user name in the user or queue information parameter
• Messages from both a user queue and a workstation message queue are included in the list.

Otherwise, this value is set to 1.

Message queue names

ARRAY(2) OF CHAR(20)

An array of qualified message queue names, which contain the names of the queues used to build the list. For each array element, the first 10 characters represent the message queue name, and the last 10 characters hold the library name.

Error code

I/O; CHAR(*)

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

LSTM0100 Format

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

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

Field Descriptions

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.

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

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.

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 identifier.

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

Message identifier. The identifying code of the message listed. If an immediate 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 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:

Microseconds. The microseconds part of the time sent.

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

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

Offset to the next entry. The offset, in bytes, from the beginning of the receiver variable to the beginning of the next message entry.

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

Reserved. An ignored 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 set to N.
• The length of data field is set to 0.

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.

Message Selection Information Format

The organization of the message selection information parameter is shown below. For detailed descriptions of each field, see Field Descriptions.

Field Descriptions

Identifiers of fields to return. The list of the identifiers of fields to be returned in the receiver variable. For a list of the valid field identifiers, see Valid Field Identifiers.

The reply status field must always be requested.

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.

Maximum message help length. The maximum length to be returned for fields 0401, 0402, 0403, and 0404.

Maximum message length. The maximum length to be returned for fields 0301 and 0302.

Number of fields to return. The number of fields to return. The reply status field must always be requested.

Number of selection criteria. The number of selection criteria specified. You must specify at least 1 and no more than 3.

Offset of 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 array.

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

Offset to selection criteria. The offset, in bytes, from the beginning of the message selection information parameter to the beginning of the selection criteria array.

Reserved. An ignored field.

Selection criteria. The type of messages to be listed. You must use at least one of these values and no more than three for this parameter. If more than one value is given and one of them is *ALL, an error is given. If more than one value is given, the messages are grouped by type. Specifying all three values is equivalent to specifying *ALL and requesting sorting.

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

Starting message keys. The message key used to begin searching for messages to list from the corresponding entry in the message queue. If *CURRENT is specified for the user name in the user or queue information parameter, two values must be specified. The first value is the starting message key for the current user's user message queue. The second value is the starting message key for the current user's workstation message queue. If either a specific user name or a specific message queue name is specified in the user or queue information parameter, only one message key is used.

You can use these special values for the message keys:

If a value other than '00000000'X or 'FFFFFFFF'X is specified and a message with that key does not exist, an error is returned. If a key of a reply message is specified, the message search begins with the inquiry or sender's copy message that the reply is associated with, not the reply message itself.

If the message specified by the starting message key exists but does not meet the selection criteria and severity criteria parameters specified, no error is returned and the search for messages to list begins from the message specified by the starting message key.

Valid Field Identifiers

For a detailed description of each field, see Field Descriptions.

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 about alerts, see the Alerts Support book.

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 replacement data is returned in. This only applies to the part of the replacement data that corresponds to a convertible character data type (*CCHAR). All other replacement data will not be converted before it is returned and can be considered to have a CCSID of 65535. 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.

For more information about message handler and its use of CCSIDs, see CCSIDs: Message Support in the Globalization topic. For more information about the *CCHAR field type, see the Add Message Description (ADDMSGD) command.

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 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 field.

This applies to the following fields only:

• Message
• Message with replacement data
• Message help
• Message help with replacement data
• Message help with replacement data and formatting characters
• Message help with formatting characters

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

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

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.

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

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

Message help. The message help for the message listed without formatting characters and without replacement of data. If an immediate message is listed, this field contains the immediate 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 of the Add Message Description (ADDMSGD) command to have these meanings:

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

Message help with replacement data. The message help for the message listed, including the replacement data. If an immediate message is listed, this field contains the immediate 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 description of the message help with formatting characters field for an explanation of formatting characters. If an immediate message is listed, this field contains the immediate message text.

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

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 QGYOLMSG 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 QGYOLMSG API, but it never returns any data and the length of data field is 0.

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 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 QGYOLMSG 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 QGYOLMSG 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 QGYOLMSG API, but it never returns any data and the length of data field is 0.

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

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

Any pointer data in this field is marked as not valid if both of the following are true:

• The API is called by a call stack entry not running in system state.
• The system security level is 50 or above.

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

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

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

Sender type. This field can be specified for the QGYOLMSG 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 QGYOLMSG 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 QGYOLMSG 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.

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

Error Messages