Get List Entry (QUIGETLE) API

The Get List Entry (QUIGETLE) API accesses an entry in a list and optionally updates the corresponding dialog variables to the values in the list entry.

The entry accessed depends on the positioning option parameter and the value of the current entry pointer for the list. On return to the application program, the current entry pointer in the list points to the entry retrieved, except when retrieving the extended action entry. The extended action entry is a pseudo list entry that can be retrieved using this API, and can be updated using the Update List Entry (QUIUPDLE) API.

If requested, the corresponding dialog variables contain the values from the list entry retrieved.

If an error variable corresponding to a field in the list entry is specified in the variable record, identified by the variable record name parameter, it is set according to the error state of the corresponding dialog variable.

Authorities and Locks

None.

Required Parameter Group

Application handle

INPUT; CHAR(8)

The application handle assigned by the UIM and returned to the application program by the Open Display Application (QUIOPNDA) or Open Print Application (QUIOPNPA) API when the application is opened.

Variable buffer

OUTPUT; CHAR(*)

The program buffer into which dialog variable values are copied. The dialog variables are copied in the order specified in the variable record definition.

If the variable record name parameter specifies the name of a variable record defined in the panel group for this open application, dialog variables are copied into the variable buffer from the application variable pool after the list entry is retrieved. This parameter does the same job as using the Get Dialog Variable (QUIGETV) API immediately after the QUIGETLE API.

The variable buffer must be large enough to contain all the variables specified in the variable record definition.

Variable buffer length

INPUT; BINARY(4)

The length of the variable buffer. The buffer must be large enough to contain all the dialog variables in the variable record definition, which is specified in the variable record name parameter.

Variable record name

INPUT; CHAR(10)

The name of the variable record that determines which dialog variables are copied between the application variable pool and the variable buffer. The variable record must be defined in the panel group for the open application. The following special value can be used:

*NONE

The QUIGETV API is not done during the QUIGETLE API; the parameter for the variable buffer is ignored when this value is used.

List name

INPUT; CHAR(10)

The name of the list from which an entry is retrieved. If the list is not currently active in the open application, an error is reported. A list is made active the first time an entry is inserted with the Add List Entry (QUIADDLE) API or Add List Multiple Entries (QUIADDLM) API, or when the list attributes are set with the Set List Attributes (QUISETLA) API.

Positioning option

INPUT; CHAR(4)

The placement of the current entry pointer to the list entry specified. If a positioning error occurs, the current list position is not changed. One of the following values must be specified to set the entry pointer to the appropriate position:

Value	Pointer Position
BOT	The bottom of the list. A special position just after the last list entry in a list that is complete at the bottom.
FRST	The first entry in the currently built list. If the list is empty, an error is reported.
FSLT	The entire list is searched in a forward direction to locate an entry satisfying the condition specified by the selection criteria parameter. If the list is empty, an error is reported. The current entry pointer for the list entry is repositioned at the first entry in the list and the search proceeds forward, including the first entry. The search does not wrap. Note that if the list is incomplete at the top, the incomplete list processing program will not be called to complete the list at the top. It will start searching from the first entry in the currently built list. The incomplete list processing program will be called to fill in the entries at the bottom if the list is incomplete at the bottom.
HNDL	The list entry specified by the selection handle parameter.
LAST	The last entry in the currently built list. If the list is empty, an error is reported.
LSLT	The entire list is searched in a backward direction to locate an entry satisfying the condition specified by the selection criteria parameter. If the list is empty, an error is reported. The current list entry pointer is repositioned to the last entry in the list and the search proceeds backward, including the last entry. The search does not wrap. Note that if the list is incomplete at the bottom, the incomplete list processing program will not be called to complete the list at the bottom. It will start searching from the last entry in the currently built list. The incomplete list processing program will be called to fill in the entries at the top if the list is incomplete at the top.
NEXT	The current entry pointer is advanced one entry, pointing to the next entry in the list.
NSLT	The list is searched in a forward direction to locate an entry satisfying the condition specified by the selection criteria parameter. The search starts with the entry after the current list entry pointer and does not wrap.
PREV	The current entry pointer is moved back one entry, pointing to the previous entry in the list.
PSLT	The list is searched in a backward direction to locate an entry satisfying the condition specified by the selection criteria parameter. The search starts with the entry before the current list entry pointer and does not wrap.
SAME	The current entry pointer remains unchanged, pointing to the same entry in the list.
TOP	The top of the list. A special position just prior to the first list entry in a list that is complete at the top.

Note: After running the QUIGETLE API once with the positioning option parameter of FSLT or LSLT, the application program should change the positioning option parameter to NSLT or PSLT. It does this to avoid repeatedly positioning at the beginning or end of the list and searching the same list entries.

Copy option

INPUT; CHAR(1)

Determines whether or not the data values in the list entry are copied into the corresponding dialog variables when positioning is complete. One of the following values must be specified:

Y	The data values in the current list entry after the positioning operations are performed are copied into corresponding dialog variables. This value must be specified if the variable record name parameter specifies the name of a variable record defined in the panel group for the open application. This value is not allowed when the current entry is positioned to TOP or BOT.
N	The data values in the current list entry after positioning the list are not copied into corresponding dialog variables.

Selection criteria

INPUT; CHAR(20)

The selection criteria used when positioning the list by variable selection. Positioning by variable selection allows the application program to search forward to find the next entry, or backward to find a previous entry satisfying a given condition. The search is not dependent on sorted list entries, but the application program might need to build the list in sorted order to get a consistent result when application comparison operators are other than equal (EQ) or not equal (NE).

This parameter is only used when one of the following values is specified for the positioning option parameter: FSLT, LSLT, NSLT, or PSLT. It is ignored if any other value is specified.

The relational condition defined by this parameter must exist between the value of a dialog variable and that dialog variable's corresponding value in a list entry when selection positioning is performed.

The first 10 characters of this parameter must contain a comparison operator. The operator must be left-adjusted and padded with blanks.

One of the following values must be specified for the comparison operator:

EQ	The list entry value equals the dialog variable value.
NE	The list entry value is not equal to the dialog variable value.
GT	The list entry value is greater than the dialog variable value.
LT	The list entry value is less than the dialog variable value.
GE	The list entry value is greater than or equal to the dialog variable value.
LE	The list entry value is less than or equal to the dialog variable value.

The second 10 characters of this parameter must contain the name of the dialog variable used in the comparison. The dialog variable name specified must be defined in the list being searched.

Selection handle

INPUT; CHAR(4)

The list entry handle used when positioning the current entry pointer to a specific entry. This parameter is used only when the positioning option parameter has the value HNDL; it is ignored if any other value is specified.

The following special value can be specified:

EXTE	Retrieves the contents of the extended action entry. The contents of the extended action entry are copied to the associated dialog variables in the variable pool. However, the current entry pointer for the list is not changed when the extended action entry is retrieved.

A list entry handle uniquely distinguishes an entry until it is removed from the list, even if other entries are inserted and removed from the list.

Extend option

INPUT; CHAR(1)

Indicates whether or not an incomplete list is automatically extended in the attempt to retrieve the requested list entry. The list can be extended when one of the following values is specified for the positioning option parameter: NEXT, PREV, TOP, BOT, NSLT, PSLT, FSLT, or LSLT. This parameter is ignored and the list is not extended if any other value is specified for the positioning option parameter.

One of the following values must be specified:

Y	The list is extended, if necessary, to find the requested list entry.
N	The list is not extended to find the requested list entry. This option can be used if the program calling the QUIGETLE API needs to process only entries already in the list.

List entry handle

OUTPUT; CHAR(4)

The list entry handle from the current entry pointer in the list. This value is the handle of the entry to which the list was last positioned by this API. The following special values may be returned:

TOP	The current entry pointer is positioned at the top of the list.
BOT	The current entry pointer is set at the bottom of the list.

Error code

I/O; CHAR(*)

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

Error Messages