Open List of History Log Messages (QMHOLHST) API
Required Parameter Group:
| 1 | Receiver variable | Output | Char(*) |
| 2 | Length of receiver variable | Input | Binary(4) |
| 3 | Format name | Input | Char(8) |
| 4 | List Information | Output | Char(80) |
| 5 | Number of records to return | Input | Binary(4) |
| 6 | Message selection information | Input | Char(*) |
| 7 | CCSID | Input | Binary(4) |
| 8 | Time Zone | Input | Char(10) |
| 9 | Error code | I/O | Char(*) |
Default Public Authority: *USE
Threadsafe: No
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.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Length of the fixed portion of the information |
| 4 | 4 | CHAR(10) | Start date |
| 14 | E | CHAR(10) | Start time |
| 24 | 18 | CHAR(6) | Start after time microseconds |
| 30 | 1E | CHAR(10) | End by date |
| 40 | 28 | CHAR(10) | End by time |
| 50 | 32 | CHAR(6) | End by time microseconds |
| 56 | 38 | BINARY(4) | Message ID list contents indicator |
| 60 | 3C | BINARY(4) | Offset to list of message IDs |
| 64 | 40 | BINARY(4) | Number of messages IDs in list |
| 68 | 44 | BINARY(4) | Offset to jobs to list |
| 72 | 48 | BINARY(4) | Number of jobs to list |
| 76 | 4C | BINARY(4) | Message severity |
| 80 | 50 | BINARY(4) | Message types list contents indicator |
| 84 | 54 | BINARY(4) | Offset to list of message types |
| 88 | 58 | BINARY(4) | Number of message types in list |
| 92 | 5C | CHAR(*) | Reserved |
| CHAR(*) | Message IDs list | ||
| CHAR(*) | Jobs to list | ||
| CHAR(*) | Message types list | ||
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:
| *CURRENT | The current day is the last day for which logged data is listed. | ||||||||
| *END | The last day on which data was logged is the last day for which the logged data is listed. if *END is specified, ending time must be set to *AVAIL. | ||||||||
| end-date | The format of this field is in CYYMMDD as follows, with the last 3 bytes set to blanks: | ||||||||
|
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:
| *AVAIL | Any logged data that is available for the specified ending time is listed. This is the only valid value if End by date is *END. | ||||||
| end-time | Specify the ending time for the specified ending date that indicates the logged data to be listed. The time is specified in 24-hour format and the format of this field is in the HHMMSS as follows, with the last 4 bytes of the field set to blanks: | ||||||
|
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:
| These fields repeat for each job specified. | CHAR(10) | Job name |
| CHAR(10) | User name | |
| CHAR(6) | Job number |
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:
| This field repeats for each message ID specified. | CHAR(7) | Message ID |
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:
| This field repeats for each message type specified. | CHAR(10) | Message type |
Valid message type values and their meanings follow:
| Value | Message type |
|---|---|
| *COMP | Completion |
| *COPY | Copy |
| *DIAG | Diagnostic |
| *ESCAPE | Escape |
| *INFO | Informational |
| *INQ | Inquiry |
| *NOTIFY | Notify |
| *RPY | Reply |
| *RQS | Request |
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:
| *CURRENT | The logged data for the current day and between the specified starting and ending times (if specified) is listed. | ||||||||
| *BEGIN | The logged data from the beginning of the log is listed. | ||||||||
| start-date | The format of this field is in CYYMMDD as follows, with the last 3 bytes set to blanks: | ||||||||
|
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:
| *AVAIL | Any logged data that is available for the specified starting time is listed. | ||||||
| start-time | Specify the starting time for the specified starting date that indicates the logged data to be listed. The time is specified in 24-hour format and the format of this field is in the HHMMSS as follows, with the last 4 bytes of the field set to blanks: | ||||||
|
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.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Length of this entry |
| 4 | 4 | BINARY(4) | Message severity |
| 8 | 8 | CHAR(7) | Message identifier |
| 15 | F | CHAR(2) | Message type |
| 17 | 11 | CHAR(10) | Message file name |
| 27 | 19 | CHAR(10) | Message file library |
| 37 | 25 | CHAR(7) | Date sent |
| 44 | 2C | CHAR(6) | Time sent |
| 50 | 32 | CHAR(6) | Microseconds |
| 56 | 36 | CHAR(10) | From job |
| 66 | 42 | CHAR(10) | From job user |
| 76 | 4C | CHAR(6) | From job number |
| 82 | 52 | CHAR(10) | From user |
| 92 | 5C | CHAR(1) | Status of data |
| 93 | 5D | CHAR(3) | Reserved |
| 96 | 60 | BINARY(4) | Displacement to the first level message or immediate text |
| 100 | 64 | BINARY(4) | Length of the first level message or immediate text |
| 104 | 68 | BINARY(4) | Displacement to the message replacement data |
| 108 | 6C | BINARY(4) | Length of the message replacement data |
| 112 | 70 | BINARY(4) | CCSID for text |
| 116 | 74 | BINARY(4) | CCSID conversion status indicator for text |
| 120 | 78 | BINARY(4) | CCSID for data |
| 124 | 7C | BINARY(4) | CCSID conversion status indicator for data |
| CHAR(*) | Reserved | ||
| CHAR(*) | First level message or immediate text | ||
| CHAR(*) | Message replacement data | ||
Field Descriptions
CCSID conversion status indicator for data. The following values may be returned:
| 0 | No conversion was needed because the CCSID of the data matched the CCSID you wanted the data converted to. |
| 1 | No conversion occurred because either the data was 65535 or the CCSID you wanted the data converted to was 65535. |
| 2 | No conversion occurred because you did ask for any data to be returned, or there was no *CCHAR type data. |
| 3 | The data was converted to the CCSID specified using the best fit conversion tables. |
| 4 | A conversion error occurred using the best fit conversion tables so a default conversion was attempted. This completed without error. |
| -1 | An error occurred on both the best fit and default conversions. The data was not converted. |
CCSID conversion status indicator for text. The following values may be returned:
| 0 | No conversion was needed because the CCSID of the data matched the CCSID you wanted the data converted to. |
| 1 | No conversion occurred because either the data was 65535 or the CCSID you wanted the data converted to was 65535. |
| 2 | No conversion occurred because you did ask for any data to be returned, or there was no *CCHAR type data. |
| 3 | The data was converted to the CCSID specified using the best fit conversion tables. |
| 4 | A conversion error occurred using the best fit conversion tables so a default conversion was attempted. This completed without error. |
| -1 | An error occurred on both the best fit and default conversions. The data was not converted. |
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:
| Value | Message Type |
|---|---|
| 01 | Completion |
| 02 | Diagnostic |
| 04 | Informational |
| 05 | Inquiry |
| 06 | Sender's copy |
| 08 | Request |
| 10 | Request with prompting |
| 14 | Notify |
| 15 | Escape |
| 21 | Reply, not checked for validity |
| 22 | Reply, checked for validity |
| 23 | Reply, message default used |
| 24 | Reply, system default used |
| 25 | Reply, from system reply list |
| 26 | Reply, from exit program |
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:
| blank | The data returned is complete. |
| A | The caller of the API was not authorized to view the data. This occurs when the caller of the API is not authorized to the message file or the message file library containing a stored message being listed. |
| D | The data was damaged. This occurs when the message file or library specified at send time for a stored message is damaged when the API is called. |
| U | The data was unavailable. This occurs when the message file or library specified at send time for a stored message is exclusively used by another process when the API is called. |
| N | The data was not found. This occurs when the message file or library specified at send time for a stored message cannot be found or resolved when the API is called. |
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
| Message ID | Error Message Text |
|---|---|
| CPF241D E | Severity criteria specified is not valid. |
| CPF247E E | CCSID &1 is not valid. |
| CPF2499 E | Message identifier &1 not allowed. |
| CPF24B3 E | Message type &1 is not valid. |
| CPF24B4 E | Severe error while addressing parameter list. |
| CPF2519 E | Error occurred while processing message ID list. |
| CPF2568 E | Value &1 for message selection criteria not valid. |
| CPF3C19 E | Error occurred with receiver variable specified. |
| CPF3C21 E | Format name &1 is not valid. |
| CPF3C3C E | Value for parameter &1 not valid. |
| CPF3CF1 E | Error code parameter not valid. |
| CPF9845 E | Error occurred while opening file &1. |
| CPF9847 E | Error coccurred while closing file &1 in library &2. |
| GUI0002 E | &2 is not valid for length of receiver variable |
| GUI0027 E | &1 is not valid for number of records to return. |
API introduced: V6R1