Open List of Job Log Messages (QGYOLJBL) API

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.

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, request that the list be built synchronously.

For more information, see Process Open List APIs.

Differences between QMHLJOBL and QGYOLJBL

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.

Authorities and Locks

User Space Lock

*EXCLRD

Job Authority

• *JOBCTL special authority if the job for which messages are being listed has a different user profile from that of the job that calls the QGYOLJBL API.
• *ALLOBJ special authority if the job for which messages are being retrieved has *ALLOBJ special authority. As an alternative to having *ALLOBJ authority, the user that calls the API can be authorized to the All Object Job Log function of the IBM^® i operating system through System i™ Navigator's Application Administration support. The Change Function Usage (CHGFCNUSG) command, with a function ID of QIBM_ACCESS_ALLOBJ_JOBLOG, can also be used to change the list of users that are allowed to access a job log that has *ALLOBJ special authority.

For additional information on job authorities, see Planning and setting up system security.

Required Parameter Group

Receiver variable

OUTPUT; CHAR(*)

The variable used to return the requested number of records containing message information. See OLJL0100 Format for a description of this parameter.

Length of receiver variable

INPUT; BINARY(4)

The length of the receiver variable.

List information

OUTPUT; CHAR(80)

The variable used to return status information about the list of job log messages that was opened. For a description of this parameter, see Open list information format.

Number of records to return

INPUT; BINARY(4)

The number of records in the list to be put into the receiver variable. Valid values for this field are:

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

Message selection information

INPUT; CHAR(*)

The information that determines the job message queue 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 of this parameter is 85.

Error code

I/O; CHAR(*)

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

OLJL0100 Format

For detailed descriptions of each field, see the Field Descriptions.

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 ID actually returned in the OLJL0100 format. 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 were 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 impromptu message is listed, this field is set to blanks.

Message key. The message reference key of the message listed.

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 OLJL0100 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 OLJL0100 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 and receiving information fields when a problem is encountered while attempting to retrieve this information. This includes field identifiers 0602, 0603, 0604, 0605, 0606, 0702, 0703, 0704, 0705, and 0706. When one of these fields cannot be retrieved from the message, the status of data field is set to U and the field is set to blanks.

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

Thread ID. The 8-byte thread ID of the thread in which this message was sent.

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

For detailed descriptions of each field, see the Field Descriptions.

Field Descriptions

Call message queue name. The name of the call message queue from which to list messages. You must use these values:

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

Internal job identifier. The internal name for the job. The List Job (QUSLJOB) API creates this identifier. If you do not specify *INT for the job name parameter, this parameter must contain blanks. With this parameter, the system can locate the job more quickly than with a job name.

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

Maximum message help length. The maximum length of data to be returned for field identifiers 0401, 0402, 0403, and 0404.

Maximum message length. The maximum length of data to be returned for field identifiers 0301 and 0302.

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

To avoid heavy utilization of system resources, users of this API must be cautious of selecting too many fields to return for the messages that are listed.

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

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.

Qualified job name. The name of the job whose messages are to be listed. The qualified job name has three parts:

Size of call message queue name. The length of the call message queue name parameter, in bytes. The maximum length that can be specified is 256; the minimum length is 1.

Starting message key. The message key to be used to begin searching for messages to list from the job. You can use these special values for the message key:

If the specified key does not exist, messages are listed with the next key that does exist in the search direction specified by the list direction parameter.

If a key of a reply message is specified, the message search begins with the inquiry or notify 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 parameter and the severity criteria parameter specified, no error is returned. The search for messages to list begins from the point that is 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. The value is one of the following:

For more information about alerts, see the Alerts Support 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 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 CCSID support for messages. 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 for data for this information.

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 impromptu message is listed, this field contains the impromptu 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 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 immediate 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 description of 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 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.

Number of the receiving statement numbers or instruction numbers available followed by an array of the receiving statement numbers. The number of statement numbers or instruction numbers available for the receiving program or procedure.

For original program model (OPM) programs and nonoptimized procedures, this count is 1.

For optimized procedures, this count can be greater than 1. In this case, each statement number represents a potential point at which the message could have been received. If the mapping table information has been removed from the program, this field returns a count of 0 and no statement numbers are available. The array of receiving statement numbers or instruction numbers immediately follows this field in the returned data.

Number of sending statement numbers or instruction numbers available followed by an array of the sending statement numbers or instruction numbers. The number of statement numbers or instruction numbers available for the sending program or procedure.

For OPM programs and nonoptimized procedures, this count is 1.

For optimized procedures, this count can be greater than 1. In this case, each statement number represents a potential point at which the message could have been sent. If the mapping table information has been removed from the program, this field returns a count of 0, and no statement numbers are available. The array of sending statement numbers or instruction numbers immediately follows this field in the returned data.

Problem identification. This field can be specified for the QGYOLJBL API, but it never returns any data and the length of data field is 0.

Qualified sender job name. This field can be specified for the QGYOLJBL API, but it never returns any data and the length of data field is 0.

Receiving module name. The name of the module that contains the procedure where the message was sent. If the message was not sent to a procedure within an Integrated Language Environment^® (ILE) program, this field is not set and the length of data field is 0.

Receiving procedure name. The name of the procedure receiving the message. If the message was not sent to a procedure within an ILE program, this field is not set and the length of data field is 0. A nested procedure name has each procedure name separated by a colon. The outermost procedure name is identified first followed by the procedures it contains. The innermost procedure is identified last in the string.

Receiving program name. The program name, or the ILE program name that contains the procedure that the message was sent to.

Receiving type. The type of the receiver (whether it is a program or a procedure). Possible values and their meanings follow:

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 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). Possible values and their meanings follow:

Request level. The level of the request-processing program that received the request message. If the message being listed is not a request, this field is set to 0.

Request status. Information regarding the processing status of the request message. Possible values and their meanings follow:

If the message being listed is not a request, this field is set to a blank character.

Sender type. The type of the sender (whether it is a program or procedure). Possible values and their meanings follow:

Sending module name. The name of the module that contains the procedure sending the message. If the message was not sent by a procedure within an ILE program, this field is not set and the length of data field is 0.

Sending procedure name. The name of the procedure sending the message. If the message was not sent by a procedure within an ILE program, this field is not set and the length of data field is 0. A nested procedure name has each procedure name separated by a colon. The outermost procedure name is identified first followed by the procedures it contains. The innermost procedure is identified last in the string.

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

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