Get List Multiple Entries (QUIGETLM) API

The Get List Multiple Entries (QUIGETLM) API accesses one or more entries in a list and updates the corresponding dialog variables with the values contained 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 last entry retrieved, except when retrieving the extended action entry. The extended action entry can be retrieved using this API, and can be updated using the Update List Entry (QUIUPDLE) API.

When the operation completes successfully, the corresponding dialog variables contain the values from the last list entry retrieved.

If an error variable corresponding to a field in the list entry is specified in the variable record, which is 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) API 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.

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 list entry is retrieved.

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

When the number of records parameter is greater than 1, the size of the variable buffer must be at least equal to the value specified on the number of records parameter multiplied by the value specified on the record size parameter.

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 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 special value of *NONE may not be used with the QUIGETLM API.

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) 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)

Sets 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 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.
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.
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 QUIGETLM 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. Y must be used if the number of records parameter is greater than 1. 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 using comparison operators other than equal (EQ) or not equal (NE).

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

The relational condition defined by this parameter must exist between the dialog variable value 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 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 content 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. If any other value is specified for the positioning option parameter, this parameter is ignored and the list is not extended.

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.

Number of records

INPUT; BINARY(4)

The total number of entries to retrieve from the list. The following special value can be used:

1	Only one entry is retrieved from the list. The record size and record count parameters are ignored when this value is used.

When this parameter is greater than 1, the variable buffer must contain space for all the entries retrieved from the list.

When this parameter is greater than 1 (multiple entries are being retrieved), the positioning option parameter must have one of the following values: NEXT, PREV, NSLT, PSLT, FSLT, or LSLT.

Record size

INPUT; BINARY(4)

The size of each record within the variable buffer when multiple records are retrieved from the list. This parameter also calculates the offset of each record after the first one.

When the number of records parameter is 1, this parameter is ignored.

Record count

OUTPUT; BINARY(4)

The number of list entries actually retrieved. When the number of records parameter is 1, this parameter is ignored.

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