| 1 | Receiver variable | Output | Char(*) |
| 2 | Length of receiver variable | Input | Binary(4) |
| 3 | Request handle | Input | Char(4) |
| 4 | List information | Output | Char(80) |
| 5 | Number of records to return | Input | Binary(4) |
| 6 | Starting record | Input | Binary(4) |
| 7 | Error code | I/O | Char(*) |
The Get List Entries (QGYGTLE) API allows requests to get entries from previously opened lists. A list will exist if an initial request has already been made and the list was not closed using the Close List (QGYCLST) API.
Initial requests are made by calling the following APIs:
None.
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 parameter correctly. As a result, the API returns only the data that the area can hold.
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. The minimum length is 8 bytes.
The handle of the request. The value of this determines from which user space to retrieve the information.
Information about the list from which entries are being returned. For a description of the layout of this parameter, see Open list information format.
The number of records in the list (starting with the record indicated in the starting record parameter) to take from the user space and put into the receiver variable. This value must be greater than or equal to zero.
If the value zero is specified, then only the list information is returned and no actual list entries are returned.
The entry in the list that will be the first entry to be put into the receiver variable. The value must be greater than zero or one of the special values of 0 or -1.
The special value of 0 indicates that the list information should be returned to the caller immediately. The special value 0 is only allowed when the number of records to return parameter is zero.
The special value of -1 indicates that the whole list should be built before the list information is returned to the caller.
The following table shows how the number of records to return and the starting record parameters interact with each other. The record parameter is represented by an X. The number of records to return parameter is represented by a Y.
| Starting Record (X) | Number of records to return (Y=0) | Number of records to return (Y>0) |
|---|---|---|
| X = 0 | Immediately return only the list information | Invalid combination. An error message is sent. |
| X = -1 | Return only the list information, but wait until the whole list is built | Wait until the whole list is built and then return the number of records requested from the end of the list. See note. |
| Note: If the receiver variable is not large enough to hold the number of records requested, then only those that will fit into the receiver variable will be returned, but they will always be the last ones in the list. | ||
| X > 0 | Return only the list information, but wait until list entries have been built, as specified in the starting record parameter. | Return the number of list entries specified in the number of records to return parameter starting with the entry specified in the starting record parameter. |
The structure in which to return error information. For the format of the structure, see Error code parameter.
The format of the receiver variable was specified when the list was originally created.
| Message ID | Error Message Text |
|---|---|
| CPF24B4 E | Severe error while addressing parameter list. |
| CPF3C19 E | Error occurred with receiver variable specified. |
| CPF3C90 E | Literal value cannot be changed. |
| CPF3CF1 E | Error code parameter not valid. |
| CPF9872 E | Program or service program &1 in library &2 ended. Reason code &3. |
| GUI0001 E | Invalid handle specified. |
| GUI0002 E | &2 is not valid for length of receiver variable. |
| GUI0006 E | &1 is not valid for starting record number. |
| GUI0027 E | &1 is not valid for number of records to return. |
| GUI0114 E | The list cannot be completed. No server jobs are running or can be started. |
| GUI0115 E | The list has been marked in error. See the previous messages. |
| GUI0118 E | Starting record cannot be 0 when records have been requested. |