Open List of History Log Messages (QMHOLHST) API

The Open List of History Log Messages (QMHOLHST) API provides information about messages that were sent to the QHST message queue. When the API is called, it will cause messages to be moved from the QHST message queue into the QHST database files. The API will return the message text based on the current contents of the message file when the API is called. The returned messages are sorted by their sending date and time unless:

• Inquiry messages have been answered. When a reply is sent to any inquiry message in QHST, the inquiry message is first resent to QHST along with its reply, so the inquiry and reply are together. This means that there will be two inquiry messages for each reply message in the QHST log files, so the initial inquiry message may appear unanswered.
• If there are multiple QHST files with the same dates and times all messages are returned from one file and then the messages from the next file are returned. So messages may appear to be returned out of order.

This API can be used with other open list APIs to process the contents of the list. The QGYCLST API should be used to close the list before calling this API to generate a new list. 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, request that the list be built synchronously.

For more information, see Process Open List APIs.

Authorities and Locks

None.

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 of the receiver variable parameter correctly. As a result, the API returns only the complete data for a message that the area can hold. If there was space for all but 5 bytes of the message text then none of the information for that message would be returned.

The entries are returned in the format specified in the Format name parameter. See HSTL0100 Format for a description of this parameter.

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. If 0 is specified for the length of the receiver variable and the number of records to return is -2, the API will move the contents of the QHST message queue into the QHST log files without returning the contents of the log files. For calls to this function a large receiver should be used to allow for multiple messages to be listed.

Format Name

INPUT; CHAR(8)

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

HSTL0100

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

List information

OUTPUT; CHAR(80)

The variable used to return status information about the list of history 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:

-2	No records are built, the contents of the QHST queue are moved into the QHST log files. This value is only valid when the parameter length of the receiver variable is set to 0.
-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. The remainder of the records in the list can be accessed with the QGYGTLE API.

Message selection information

INPUT; CHAR(*)

Specifies the criteria for the messages to be returned in the HSTL0100 format. The format of this information is described in Message Selection Information Format.

CCSID

INPUT; BINARY(4)

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 data is returned in the CCSID it was created with. If you specify 0, the data is returned in the CCSID of the job. This field only applies to the message text and *CCHAR(converted character data type) of the message data returned on the HSTL0100 Format. The CCSID is validated by this API. Only CCSIDs that a job can be changed to are accepted.

Time zone

INPUT; CHAR(10)

Specifies the time zone that the time and date data is input and returned in. valid values for this field are:

*SYS	Local system value associated with the time zone is specified by the time zone system value
*UTC	Coordinated Universal Time(UTC) value.
*JOB	Local job time value and the associated time zone is specified by the job attribute.
Time zone name	Specifies the name of a time zone description(*TIMZON) object.

Error code

I/O; CHAR(*)

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

Message Selection Information Format

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

Field Descriptions

End by date. Specifies the ending date for messages and jobs to be listed. If not specified, *END will be used.

One of the following is used to specify the ending date before which or on which the data must have been logged:

End by time. Specifies the ending time for messages and jobs to be listed. If not specified, *AVAIL will be used.

One of the following is used to specify the ending time before which the data must have been logged:

End by time microseconds. Specifies the ending times microseconds. Messages will be listed up to and including this time if available. If not specified, 0 will be used.

Jobs to list. Specifies the specific jobs (if any) for which messages in the log are listed. The messages for the specified jobs are retrieved only if they were logged in the period of time, message severity, message types and messages specified on the call. If the offset and number of jobs to list are 0 all available jobs will be listed.

A job name can be qualified with up to 3 elements.

• job-name
• user-name/job-name
• job-number/user-name/job-name

If a job name is not qualified with a user name and number, all jobs by that name in the log, within the selection will have their messages returned. Use blanks for the job-number or user-name if the job-name is to be listed for all job-number/user-names. Any other qualifications would result in all jobs being listed. For example, if a user-name was listed with blanks for the job-name and job-number, then the job data would be ignored and all jobs would be returned. Up to 5 jobs are supported.

Format of the Jobs to list:

Length of the fixed portion of the information. Specifies the length of the fixed portion of the selection information.

Message IDs list. Specifies the specific message IDs to be retrieved or omitted. Up to 200 message IDs are supported. If not specified, all of the messages will be listed for the jobs, message severity, message types and times specified. If the offset, list contents indicator and number message IDs are 0 all available messages will be listed. To select specific generic types of messages, specify the 3-character code that identifies the message file followed by all zeros. For example, CPF0000 specifies that all CPF messages that meet the specifications of the previous parameters are selected or omitted. If an identifier is specified as pppnn00, any message beginning with the specified five characters (pppnn) can be selected or omitted.

Format of Message IDs list:

Message IDs list contents indicator. Specifies if the messages IDs in the list are to be omitted or selected. To omit the message IDs in the list set this field to 1. To select the message IDs in the list set this field to 0. If not specified, 0 will be used.

Message types list. Specifies the specific message types to be retrieved or omitted. Up to 9 message types are supported. If not specified all of the messages will be listed for the jobs, message severity and times specified. If the offset, list contents indicator and number of message types are 0, all available message types will be listed.

Format of Message types list:

Valid message type values and their meanings follow:

Message types list contents indicator. Specifies if the message types in the list are to be omitted or selected. To omit the message types in the list set this field to 1. To select the message types in the list set this field to 0. If not specified, 0 will be used.

Message severity. The minimum severity of the messages to be listed. Possible values are 0 through 99. Specify 0 to list all messages for the jobs, times, message types and message IDs specified. If not specified, 0 will be used.

Number of jobs to list. Specifies the number of jobs to list. Specifying 0 for this field will list all jobs available for the time, message severity, message types and message IDs specified. A maximum of 5 jobs can be specified. If the number of jobs to list does not match the number of jobs specified unpredictable results may occur. If not specified, 0 will be used.

Number of message IDs in list. Specifies the number of message IDs in the list. Specifying 0 for this field will list all messages available for the time, jobs, message types and severity level specified. A maximum of 100 message IDs can be specified. If the number of message IDs in list does not match the message IDs in the list unpredictable results may occur. If not specified, 0 will be used.

Number of message types in list. Specifies the number of message types in the list. Specifying 0 for this field will list all message types available for the time, jobs, message IDs and severity level specified. A maximum of 9 message types can be specified. If the number of message types in list does not match the message types in the list unpredictable results may occur. If not specified, 0 will be used.

Offset to jobs to list. The offset, in bytes, from the beginning of the message selection information format to the beginning of the jobs to list entry. Specifying 0 for this field and number of jobs to list will list all jobs available for the time, message severity, message types and message IDs specified. If this is set to 0, the number of jobs to list must also be set to 0. If not specified, 0 will be used.

Offset to list of message IDs. The offset, in bytes, from the beginning of the message selection information format to the beginning of the message IDs list entry. Specifying 0 for this field, message IDs list contents indicator and number of message IDs in list will list all messages available for the time, message severity, message types and jobs to list specified. If this is set to 0, the number of message IDs in list must also be set to 0. If not specified, 0 will be used.

Offset to list of message types. The offset, in bytes, from the beginning of the message selection information format to the beginning of the message types list entry. Specifying 0 for this field, message types list contents indicator and number of message types in list will list all message types available for the time, message IDs, message severity and jobs to list specified. If this is set to 0 the number of message types in list must also be set to 0. If not specified, 0 will be used.

Reserved. An ignored field.

Start date. Specifies the starting date for messages and jobs to be listed. If not specified, *CURRENT will be used.

One of the following is used to specify the starting date on which or after which the data must have been logged. Any entries logged before the specified date are not listed:

Start time. Specifies the starting time for messages and jobs to be listed. If not specified, *AVAIL will be used.

One of the following is used to specify the starting time at which or after which the data must have been logged. Any entries logged before the specified time and date are not listed:

Start after time microseconds. Specifies the starting times microseconds to be used. The messages listed will be listed after this time. If not specified, 0 will be used.

HSTL0100 Format

The following table shows the information returned in the receiver variable for the HSTL0100 format. The displacements listed are from the beginning of the entry. For detailed descriptions of each field, see the Field Descriptions.

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

Field Descriptions

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 in the IBM^® i globalization topic collection. 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.

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

Displacement to the first level message or immediate text. The displacement, in bytes, from the beginning of this entry to the beginning of the First level message or immediate text of the HSTL0100 format. This can be 0 if there is no message text available.

Displacement to the message replacement text. The displacement, in bytes, from the beginning of this entry to the beginning of the replacement message text of the HSTL0100 format. This can be 0 if there is no message replacement text available.

First level message or immediate text. The first level text of the message or the immediate text.

From job. The job from which the message was sent.

From job number. The number of the job from which the message was sent.

From job user. The name of the user in the qualified job name of the job that sent the message.

From user. The current user from which the message was sent.

Length of this entry. The length, in bytes, of this entry. This length can be used to access the next entry.

Length of the first level message or immediate text. The length of the first level message or immediate text returned, in bytes.

Length of the message replacement data. The length of the Message replacement data returned, in bytes.

Message file library. The name of the library containing the message file. 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. If an immediate message is listed, this field is set to blanks.

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

Message replacement data. The replacement data that was sent with the message.

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.

Reserved. An ignored field.

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

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

Usage Notes

• To obtain the second-level text of the message the QMHRTVM API can be used with the message ID, message file, and message data information returned in the HSTL0100 format.
• The messages are copied from the QHST message queue to the QHST database files in a different job while this API returns the messages from the database files. Since multiple jobs are using the files concurrently and new messages are being sent to the QHST queue, the API may reach the end of the database files before the messages remaining in the queue can be copied to the database files. To get any new messages that the API was not able to return in the current list, use the time for the last record in the current list as the starting time for the next call to the API.

Error messages

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