Differences between iseries as400 API QMHLJOBL and QGYOLJBL

Differences between iseries as400 QMHLJOBL and QGYOLJBL

The Open List of Job Log Messages (QGYOLJBL) API lists messages from a job log. The returned messages are sorted by their sending date and time unless the message being listed is a reply message to an inquiry, a sender's copy, or a notify type message. When a reply message exists for one of these messages, the reply message is not positioned according to the sending date and time of the reply. The reply message is, instead, listed immediately following the inquiry, the sender's copy, or the notify message that it is associated with

The List Job Log Messages (QMHLJOBL) API lists messages sent to the job message queue of a job. This API gets the requested message information and returns it in a user space in the format specified in the parameter list. The following discusses how the list is sorted for nonbatch jobs and for batch jobs.

When the job whose messages are being listed is not a batch job, the returned messages are sorted by their sending date and time unless the message being listed is a reply message to an inquiry, a sender's copy, or a notify message. If it is a reply message, it is listed immediately following the inquiry, sender's copy, or notify message with which it is associated.

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

When the job whose messages are listed is a batch job, the messages are grouped into two categories:

Request messages that have been or are being processed, and the other messages that occurred during the processing of those requests.
Request messages that are yet to be processed, and any diagnostic messages associated with these request messages.
The API treats unprocessed request messages as if they had a sending time later than all the request messages and their associated messages that have been or are being processed. The following two examples describe the sorting further.

For example, if the call to this API specifies to list the messages for a batch job from oldest to newest, the list consists of all requests and their associated messages that have been or are being processed. They are sorted as described above for a job that is not a batch job. They are followed by any request messages and any associated diagnostic messages that have not yet been processed (in the order that they will be processed).

As an opposite example, if the call to this API specifies to list the messages for a batch job from newest to oldest, the list consists of the request messages that remain to be processed. They are in the opposite order that they are processed. They are followed by the request messages that have been or are being processed and their associated messages. These are sorted backward through time as described above for nonbatch jobs.

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

If the user space is not large enough to contain the data to be returned, the user space is increased to the maximum user space size allowed (16MB) or 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.

The maximum messages requested field and the number of fields to return field for each listed message increase the system resources required to create the list. Users of this API should use caution when specifying parameters that list many messages or request many identified fields to be returned for each listed message

The differences between the QGYOLJBL API and the List Job Log Messages (QMHLJOBL) API follow:

The message information for the QGYOLJBL API is returned into a receiver variable instead of a user space.
The request handle parameter was added to the QGYOLJBL API, so that a distinct value is associated with the list. This value ensures that a request for more messages from the list (call QGYGTLE API) is sent to the correct list.
The total records parameter was added to the QGYOLJBL 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 QGYOLJBL API. Now 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 QMHLJOBL API is limited by the size of a user space, approximately 16MB. The list created by the QGYOLJBL API can contain up to 2GB of information