The format of the open list information is common across many of the open list APIs.
This common open list structure provides information necessary to the API caller in order to properly process the list. If the API error code parameter indicates that no error occurred then the Information complete indicator should be checked for a value of either 'C' (complete and accurate) or 'P' (partial and accurate). If one of these values is found then the caller should process the number of entries indicated by Records returned.
When these records have been processed the API caller should then determine if all records that could be returned in the list have been returned. This is accomplished by comparing Total records to the sum of First record in receiver variable and Records returned less 1. When Total records is greater than or equal to First record in receiver variable + Records returned -1 then additional calls to QGYGTLE may continue to receive new records if List status indicator is not '3' or '5'. When Total records have been processed and List status is '2' or '5', or if the caller no longer needs to process the list, a call to QGYCLST should be done.
The open list APIs return data for use by the process open list APIs. The process open list APIs are located in the Process Open List category, whereas the open list APIs can be found in the applicable sections. For example, the Open List of Messages (QGYOLMSG) API is located in the Message Handling part.
The following shows the format of the list information parameter in the open list APIs. For a detailed description of each field, see Field descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Total records |
| 4 | 4 | BINARY(4) | Records returned |
| 8 | 8 | CHAR(4) | Request handle |
| 12 | C | BINARY(4) | Record length |
| 16 | 10 | CHAR(1) | Information complete indicator |
| 17 | 11 | CHAR(13) | Date and time created |
| 30 | 1E | CHAR(1) | List status indicator |
| 31 | 1F | CHAR(1) | Reserved |
| 32 | 20 | BINARY(4) | Length of information returned |
| 36 | 24 | BINARY(4) | First record in receiver variable |
| 40 | 28 | CHAR(40) | Reserved |
Date and time created. The date and time when the list was created. The 13 characters are:
| Character | Description |
|---|---|
| 1 | Century, where 0 indicates years 19 xx and 1 indicates years 20 xx. |
| 2-7 | The date, in YYMMDD (year, month, day) format. |
| 8-13 | The time of day, in HHMMSS (hours, minutes, seconds) format. |
First record in receiver variable. The number of the first record returned in the receiver variable.
Information complete indicator. Whether all requested information has been supplied. Possible values follow:
| Value | Description |
|---|---|
| C | Complete and accurate information. All of the requested records have been returned in the receiver variable. |
| I | Incomplete information. An interruption causes the receiver variable to contain incomplete information. |
| P | Partial and accurate information. Partial information is returned when the receiver variable is full and not all of the records requested are returned. |
Length of information returned. The size, in bytes, of the information that is returned in the receiver variable.
List status indicator. The status of building the list. Possible values follow:
| Value | Description |
|---|---|
| 0 | The building of the list is pending. |
| 1 | The list is in the process of being built. |
| 2 | The list has been completely built. |
| 3 | An error occurred when building the list. The next call to the Get List Entries (QGYGTLE) API will cause the error to be signaled to the caller of the QGYGTLE API. |
| 4 | The list is primed and ready to be built. The list will be built asynchronously by a server job, but the server job has not necessarily started building the list yet. |
| 5 | Given the current selection criteria and information requested, there is too much data to be returned. The list is incomplete, but data collected to this point is available. |
Record length. The length of each record of information returned. For variable length records, this value is set to zero. For variable length records, you can obtain the length of individual records from the records themselves.
Records returned. The number of records that are returned in the receiver variable. This number is the smallest of the following values:
Request handle. The handle of the request that can be used for subsequent requests of information from the list. The handle is valid until the Close List (QGYCLST) API is called to close the list, or until the job ends.
Reserved. An ignored field.
Total records. The total number of records available in the list.