Retrieve List Attributes (QUIRTVLA) API

Required Parameter Group:

1	Application handle	Input	Char(8)
2	List name	Input	Char(10)
3	Receiver	Output	Char(*)
4	Receiver length	Input	Binary(4)
5	Error code	I/O	Char(*)

Default Public Authority: *USE

Threadsafe: No

The Retrieve List Attributes (QUIRTVLA) API retrieves the following list attributes:

The list contents attribute, indicating whether or not all entries are present in the list, and which entries are missing if it is incomplete

The name of the dialog variable that identifies the program called when the UIM needs to add entries to an incomplete list

The display position attribute, which is the list entry handle for the entry presented at the top-most row of any list area that displays a list

The allow trim attribute, which indicates whether or not the UIM trims a full list when adding new entries

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 by the Open Print Application (QUIOPNPA) API when the application is opened.

List name

INPUT; CHAR(10)

The name of the list whose attributes are 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 the fist time the list's attributes are set with the Set List Attributes (QUISETLA) API.

Receiver

OUTPUT; CHAR(*)

The current attributes of the list. For the format of the receiver variable, see Format of Data Returned.

Receiver length

INPUT; BINARY(4)

The amount of data the application program is prepared to receive. If the length specified is larger than the amount of data available, the receiver is not changed beyond the amount of data available.

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 Data Returned

The format of the data available, returned in the receiver parameter, is as follows:

CHAR(4)

The list contents attribute, indicating whether or not the list contains all or some of the entries available for display or printing. For more information about the meaning of each possible return value, see the Set List Attributes (QUISETLA) API. The following values can be returned in this parameter:

ALL	The list is complete. This value is returned when either the QUISETLA API has not been called to set the list attribute or when ALL is the last list contents attribute specified on a call to the QUISETLA API for the list.
TOP	Only the top part of an incomplete list is available. This value is returned when TOP is the last list contents attribute specified on a call to the QUISETLA API for the list.
BOT	Only the bottom part of an incomplete list is available. This value is returned when BOT is the last list contents attribute specified on a call to the QUISETLA API for the list.
MORE	Only the middle part of an incomplete list is available. This value is returned when MORE is the last list contents attribute specified on a call to the QUISETLA API for the list.

CHAR(10)

The name of the dialog variable identifying the program the UIM calls when more entries are needed in an incomplete list.

CHAR(4)

The display position attribute, which is the list entry handle at the top of the list area on the next panel that displays this list. The UIM does not use the display position attribute for print applications.

The value returned is the handle for a specific entry in the list, or one of the following special values:

TOP	The top entries in the list are displayed.
BOT	The bottom entries in the list are displayed.

If the list entry identified by the display position attribute of a list is removed before the list is displayed on a panel, the UIM adjusts the attribute to display the entry before the one that was removed. The value returned by this API is not meaningful if entries are removed from the list after the display position attribute is retrieved.

CHAR(1)

The allow trim attribute, which indicates whether or not the UIM trims the list when a new list entry causes the list to exceed its maximum size. For additional details, see the Set List Attributes (QUISETLA) API.

One of the following values is returned:

Y	The UIM automatically trims the list.
N	The UIM does not automatically trim the list.

Error Messages

Message ID	Error Message Text
CPF3C90 E	Literal value cannot be changed.
CPF6A0B E	Application handle &3 not valid.
CPF6A0C E	Application domain error for application &1.
CPF6A0F E	Previous error occurred while running application &3.
CPF6A24 E	Parameter &1 not passed correctly.
CPF6A25 E	Return code length of &1 not valid.
CPF6A91 E	List &4 does not exist.
CPF6A92 E	List &4 not active.
CPF9872 E	Program or service program &1 in library &2 ended. Reason code &3.

Message ID

Error Message Text

CPF3C90 E

Literal value cannot be changed.

CPF6A0B E

Application handle &3 not valid.

CPF6A0C E

Application domain error for application &1.

CPF6A0F E

Previous error occurred while running application &3.

CPF6A24 E

Parameter &1 not passed correctly.

CPF6A25 E

Return code length of &1 not valid.

CPF6A91 E

List &4 does not exist.

CPF6A92 E

List &4 not active.

CPF9872 E

Program or service program &1 in library &2 ended. Reason code &3.