Open list information format
The format of the open list information is common across many of the open list APIs.
This common open list structure provides information necessary for the API caller to properly process the list. If the API error code parameter indicates that no error occurred, 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, the API caller should process the number of entries indicated by the records returned field.
When these records have been processed, the API caller should determine whether all records that can be returned in the list have been returned. The API caller can determine this by comparing the total records value with the sum of the first record in receiver variable value and the records returned value less 1. When the total records value is greater than or equal to the first record in receiver variable value plus the records returned value minus 1, additional calls to the Get List Entries (QGYGTLE) API can continue to receive new records if the list status indicator is not 3 or 5. When total records have been processed and the list status indicator 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 categories. For example, the Open List of Messages (QGYOLMSG) API is located in the Message Handling category.
The following table 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 |
Field descriptions
Date and time created. The date and time when the list was created. The 13 characters follow.
| 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 access the next record in the list by using Offset to the next entry, Displacement to the next entry, or Length of this entry, which is provided with each list entry returned.
Records returned. The number of records that are returned in the receiver variable. This number is the smallest of the following values:
- The number of records that will fit into the receiver variable.
- The number of records in the list.
- The number of records that are requested.
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.