List Job Log Messages (QMHLJOBL) API

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.

An alternative to making multiple calls to QMHLJOBL to list all of the messages is to change to use the Open List of Job Log Messages (QGYOLJBL) API. QGYOLJBL 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 QGYOLJBL.

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.

Authorities and Locks

User space

*CHANGE

User space library

*EXECUTE

User space lock

*EXCLRD

Job authority

• *JOBCTL special authority if the job for which messages are being retrieved has a user profile different from that of the job that calls the QMHLJOBL 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

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:

*CURLIB	The job's current library
*LIBL	The library list

Format name

INPUT; CHAR(8)

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

LJOB0100

Basic message information with identified return fields. This format is described in LJOB0100 Format.

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 JSLT0100 Format and in JSLT0200 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:

JSLT0100	The specific information identifying the messages to be listed. This format is described in JSLT0100 Format. Message text and data are returned in the CCSID of your job.
JSLT0200	The specific information identifying the messages to be listed. This format is described in JSLT0200 Format. This format is the same as JSLT0100 with the exception that you can specify the CCSID you want your message text and data returned in.

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:

• A user area
• A generic header
• An input parameter section
• A header section
• LJOB0100 format

For details about the user area and generic header, see the 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

LJOB0100 Format

The following table shows the information returned in the list data section of the user space for the LJOB0100 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.

JSLT0100 Format

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

JSLT0200 Format

The organization of the JSLT0200 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 that can be specified in the message selection information parameter. 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.

Call message queue name. The name of the call message queue from which the messages are listed. You must use one of these values:

Call message queue specified. The call message queue name as specified on the call to the API.

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

Coded character set identifier 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 specified. The CCSID that was specified that the text and data are converted to before they are returned.

Coded character set identifier used. The CCSID that was used that the text and data are converted to before they 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.

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. The message key of the last message actually listed by the API. If no message is listed, the value returned is the same as the value specified 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 ID actually returned in the LJOB0100 format. See Valid Field Identifiers for the list of valid field identifiers.

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

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

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 qualified job name parameter, this parameter must contain blanks. If your application already has this information available from QUSLJOB, the QMHLJOBL API can locate the job more quickly with this information than with a job name. However, calling QUSLJOB solely to obtain this parameter for use by QMHLJOBL would result in poorer performance than using a job name in calling QMHLJOBL.

Internal job identifier specified. The internal job identifier as specified on the call to the API.

Job name specified. The job name of the job that lists the messages as specified on the call to the API.

Job name used. The actual job name of the job that was used to list the messages.

Job number specified. The job number of the job that lists the messages as specified on the call to the API.

Job number used. The actual job number of the job that was used to list the messages.

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.

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

Length of call message queue specified. The length of the call message queue specified field, in bytes.

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

When a batch job is being listed, request messages that have not yet been processed or received are considered to have a sending date and time later than all other messages on the job log. This is also true for any diagnostic messages associated with those request messages.

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.

Specify a value to limit the number of characters returned for field identifiers 0301 and 0302. (See Valid Field Identifiers.) 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 -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 job message queue, 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.

To list all messages in the job log in the specified list direction from the starting message key, use the special value of -1.

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

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. If the message being listed was sent from one job to another job, this field will be set to blanks if the message has not been modified within the target job. Once the message is modified within the target job, then this field will no longer be 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 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. In the Add Message Description (ADDMSGD) command, they are defined 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 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:

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

Offset 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 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 to call message queue specified. The offset, in bytes, from the beginning of the user space to the beginning of the call message queue specified 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 LJOB0100 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 array.

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, in bytes, to the next field information returned. The offset from the beginning of the user space to the beginning of the next repeating identified field of the LJOB0100 format.

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

Qualified job name. The specific job name of the job whose messages are to be listed, or one of the following special values:

Qualified user name. A specific user profile name of the job whose messages are to be listed, or blanks when the Qualified Job Name parameter is the special value of * or *INT.

Qualified job number. A specific job number of the job whose messages are to be listed, or blanks when the Qualified Job Name parameter is the special value of * or *INT.

Qualified sender job name. This field can be specified for the QMHLJOBL 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 a 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:

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

Reserved. An ignored field.

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.

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 to begin searching for messages to list from the job. You can use these special values for the message key:

When the list direction field is *NEXT, the first message listed is the first message with a message key equal to or greater than the key specified. If no message is found in this manner, an error is returned. When the list direction field is *PRV, the first message listed is the first message with a message key equal or less than the key specified. If no message is found in this manner, an error is returned.

If a key of a reply message is specified, the message search begins with the inquiry, sender's copy, or notify message with which the reply is associated. It does not begin with the reply message itself.

Note: When a batch job is being listed, request messages that have not yet been processed or received are considered to have a sending date and time later than all other messages on the job log. This is also true for any diagnostic messages associated with those request messages. If the starting message key provided is to one of these messages, and the list direction is *NEXT, only additional request messages and associated diagnostic messages that remain to be processed are listed. If the list direction is *PRV, any earlier request messages or associated diagnostic messages are listed. These are followed by messages on the job log associated with request messages that have been or are being processed.

Starting message key specified. The starting message key 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, the value returned is the same as the value specified 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 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.

User profile specified. The user profile of the job from which to list messages as specified on the call to the API.

User profile used. The actual user profile of the job used from which to list messages.

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

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