Get List Entries (QGYGTLE) API

The Get List Entries (QGYGTLE) API allows requests to get entries from previously opened lists on the iSeries server. 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:

• Open List of Job Log Messages (QGYOLJBL)
• Open List of Messages (QGYOLMSG)
• Open List of Objects (QGYOLOBJ)
• Open List of Printers (QGYRPRTL)
• Open List of Spooled Files (QGYOLSPL)
• Open List of User Certificates (QSYOLUC)
• Open List of Validation List Entries (QSYOLVLE)
• Retrieve Objects Secured by Authorization List (QGYRATLO)

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 parameter correctly. As a result, the API returns only the data that the area can hold.

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. The minimum length is 8 bytes.

Request handle

INPUT; CHAR(4)

The handle of the request. The value of this determines from which user space to retrieve the information.

List information

OUTPUT; CHAR(80)

Information about the list from which entries are being returned. For a description of the layout of this parameter, see Format of Open List Information.

Number of records to return

INPUT; BINARY(4)

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.

Starting record

INPUT; BINARY(4)

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.

Error code

I/O; CHAR(*)

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

Format of Receiver Variable

The format of the receiver variable was specified when the list was originally created.

Error Messages