Set List Attributes (QUISETLA) API

The Set List Attributes (QUISETLA) API sets the following list attributes:

• The list contents attribute, which indicates 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 the UIM calls when additional entries are needed in an incomplete list
• The display position attribute, which is the list entry handle for the entry presented at the top row of a list area displaying the list
• An attribute indicating whether or not the UIM trims the list if the maximum list size is exceeded when adding a new entry to the list

If the QUISETLA API has not been called for a list since the first entry was inserted, the list contents default value is ALL and the list is complete. An error message is displayed if the user attempts to page beyond either end of the list. The UIM does not call a program for more entries or return to the program that called the Display Panel (QUIDSPP) API.

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 changed. If the list is not currently active in the open application, it is activated by this API.

List contents

INPUT; CHAR(4)

Indicates whether or not the list contains all or some of the entries available. One of the following values must be specified:

SAME	This list contents attribute of the list is not changed.
ALL	The entire list has been built. A message is displayed if the user attempts to page beyond the top or the bottom of the list.
TOP	Only the top part of the list is built. A message is displayed if the user attempts to page beyond the beginning of the list. If the user attempts to page beyond the bottom of the list, the program specified by the program dialog variable parameter is called by the UIM, with parameters indicating the need for more entries at the bottom of the list.
BOT	Only the bottom part of the list is built. A message is displayed if the user attempts to page beyond the bottom of the list. If the user attempts to page beyond the top of the list, the program specified by the program dialog variable parameter is called by the UIM, with parameters indicating the need for more entries at the top of the list.
MORE	Only the middle of the list is built. If the user attempts to page beyond either the top or the bottom the list, the program specified by the program dialog variable parameter is called by the UIM, with parameters indicating the need for more entries at the top or bottom of the list. If the application program marks the list complete in a given direction, the application program cannot subsequently mark the list incomplete in that same direction.

Program dialog variable

INPUT; CHAR(10)

The name of a dialog variable in an open application. This dialog variable contains information identifying the program called by the UIM when more entries must be added to an incomplete list. The dialog variable must be defined and set properly according to the rules used for the CALL dialog command.

For a description of the CALL dialog command, see the Application Display Programming book. For a description of the interface between the UIM and the incomplete list exit program, see Using the User Interface Manager exit programs.

The following special value can be used:

*SAME

The program dialog variable is not changed.

Display position attribute

INPUT; CHAR(4)

The list entry that should be positioned at the top of the list area on the next panel that displays this list. The UIM does not use the display position attribute when printing the list.

The value specified must be the list entry handle currently existing in the list or one of the following special values:

SAME	The display position attribute of the list is not changed.
TOP	The entries at the top of the list should be positioned at the top of the list area on the next panel.
BOT	The bottom n entries of the list should be displayed in the list area on the next panel, where n is the number of list entries that can be displayed in the current view of the list. If the list contains fewer than n list entries, the complete list is 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 automatically adjusts the attribute to display the entry before the one removed. If there is no previous entry in the list, the attribute is set at the top of the list, and the next panel displaying the list shows the first entry in the list.

During incomplete list extension, the application program must specify SAME for the display position attribute.

Allow trim attribute

INPUT; CHAR(1)

Indicates whether or not the UIM should trim the list during the Add List Entry (QUIADDLE) or the Add List Multiple Entries (QUIADDLM) API if adding the new entry exceeds the maximum list size. The UIM trims only lists that have been marked as incomplete by using the QUISETLA API. When the UIM removes the list entry, the UIM marks the list incomplete in the direction from which the entry was removed, regardless of whether or not the list was previously incomplete in this direction.

If an application is adding an entry to the bottom of the list when the maximum size list is reached, the UIM removes the first list entry and marks the list incomplete at the top. The incomplete list exit program of the application must be prepared to add list entries in either direction of an incomplete list.

When the incomplete list exit program is called to add list entries, the QUIADDLE or QUIADDLM API can be called to add entries in the middle of the list. If the entries are added to the middle of the list when the list is complete; trimming does not take place and an error is reported indicating that the maximum list size has been reached.

One of the following values must be specified:

S	The allow trim attribute of the list should not be changed.
Y	The UIM automatically trims the list.
N	The UIM does not automatically trim 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