Display Panel (QUIDSPP) API

The Display Panel (QUIDSPP) API displays a panel and waits for the user to press either a function key or the Enter key.

The values for all I/O fields in the panel definition are taken from dialog variables in the variable pool. If the panel contains list areas, these values are also taken from list entries in the lists associated with the open application.

The application program can also control which list entry is initially displayed at the top of a list area by using the Set List Attributes (QUISETLA) API. If the panel contains a list area displaying an incomplete list and if the list does not have enough entries to fill the list area, the UIM calls the program identified by the program dialog variable parameter of the QUISETLA API to add more list entries. The program is called repeatedly until the requested number of entries is added or until the list is marked as complete.

If the panel contains an extended action list area and if the list is not currently active in the open application, the list is activated by the QUIDSPP API.

Any information the user enters into input fields on the panel is validated according to the specifications of the tag language, then saved in the corresponding dialog variables and list entries.

Control returns to the application program only after all necessary functions are completed as defined by UIM processing rules and tag language specifications. The application program can retrieve dialog variables and list entries after the QUIDSPP API returns to determine what values were specified by the user.

The QUIDSPP API can be called with a long or short argument list. For the short argument list, arguments must be passed to the QUIDSPP API with the required parameters described below. For the long argument list, arguments must be passed to the QUIDSPP API with all the required and optional parameters described below.

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 when the application is opened.

Function requested

OUTPUT; BINARY(4)

The function requested by the user. Only special UIM-defined functions and functions using the RETURN dialog command are returned to the application program. Any other functions requested by the user are either handled by the UIM or rejected. If they are rejected, an error message is displayed on the panel.

The RETURN dialog command can be specified as follows:

• On the ACTION attribute of the key list item (KEYI), pull-down field choice (PDFLDC), or menu item (MENUI) UIM tags
• On the ENTER and SELECT attributes of the display panel (PANEL) UIM tag

The RETURN dialog command returns numbers from 1 through 32 767. The return values for UIM-defined functions are as follows:

0	The enter function is requested. This value is returned in the following situations: When the user has entered options in the list for a panel with a list area of ACTOR=CALLER. When enter has been pressed in a text area and the text area exit program has sent message CPF6A07 to end the enter function and return to the application program.
-4	The exit function is requested.
-8	The cancel function is requested.
-10	The prompt function is requested. This value is returned only for a panel with an ACTOR=CALLER list area, and only when the user has entered options in the list.
-20	No function was requested before the time specified on the wait time parameter has ended. This value is returned only when the wait time parameter specifies a time-out value.

Panel name

INPUT; CHAR(10)

The name of the panel to display. The panel must be defined in the panel group for the open application.

Redisplay option

INPUT; CHAR(1)

Indicates whether or not the panel is formatted and displayed as a first-time display or as a redisplay.

One of the following values must be used:

Y

The panel is formatted as a redisplay. If the panel has not been displayed in the application before, processing for the first-time display is done and this parameter is ignored. Cursor positioning that is controlled by the program is ignored when the redisplay option is used. Cursor positioning controlled by action list processing is supported when the redisplay option is used. Dialog variables are edited for a new displayable value only if the variable pool contains a value more current than the value from the last time the panel was displayed. When VARUPD=NO is processed, the panel is redisplayed with values entered in input fields but not stored in the variable pool.

N

The panel is formatted as a first-time display. The panel is displayed with the first conditioned-on item at the top of each pageable data and menu area. Pageable information areas are positioned at the first line of text. All dialog variables displayed on the screen are edited to produce a displayable value.

Error code

I/O; CHAR(*)

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

Optional Parameter Group 1

User task

INPUT; CHAR(1)

Indicates whether or not this panel is the logical start of a new user task. The value used determines whether or not the UIM returns to the application program when the EXIT dialog command is requested by a lower level program, such as an action on the KEYI tag.

The user task has no effect on UIM operations when the EXIT dialog command is specified directly in the definition of this panel as the function key, pull-down choice, or menu item action.

One of the following values must be specified:

N	This panel is the logical start of a new user task. If the user generates the EXIT dialog command at a lower call level (for example, by pressing the exit function key on a panel displayed by a list action from the original panel), this panel is redisplayed without returning control to the application program.
O	This panel is not the start of a new user task. If the user generates the EXIT dialog command at a lower call level, control returns to the application program with an indication that the exit function was requested. This is the default value when a short argument list is passed to the QUIDSPP API.

Call stack counter

INPUT; BINARY(4)

A number identifying the location in the program stack of the call message queue for the UIM to use. This parameter is used with the call message queue parameter.

Any nonnegative number can be specified for the relative program call number.

0	The message queue of the program specified in the call message queue parameter. This is the default value when a short argument list is passed to the QUIDSPP API.
1	The message queue of the program that calls the program specified in the call message queue parameter is used for messages displayed to the user.
n	The message queue of the nth program up the stack from the program specified in the call message queue parameter is used for messages displayed to the user.

Call message queue

INPUT; CHAR(*)

The name of the message queue for the UIM to use, or the name of the program to start counting from when using a value other than zero for the call stack counter parameter. The program you specify must be in the call stack. The UIM will:

• Receive a message from this queue to initially display on the message line of the panel. This is done using the value passed for the message reference key parameter.
• Move to this message queue all completion, information, diagnostic, and escape messages sent to the UIM by programs or commands called to process an action defined in the panel. Note that escape messages are changed to diagnostic messages when they are moved.

The following special value can be used:

*CALLER

The application program calling the QUIDSPP API is the starting point for identifying the call message queue. This is the default value when a short argument list is passed to the QUIDSPP API. This parameter can be from 1 to 256 characters in length. The length of call message queue parameter specifies this parameter's length. If the length of call message queue parameter is not used, then the length of this parameter is assumed to be 10 characters. If further qualification is needed to identify the call, the call qualification parameter can be used.

Message reference key

INPUT; CHAR(4)

The messages in the call message queue that are displayed on the panel. The call message queue is identified by the call stack counter parameter and the call message queue parameter. This parameter must be set to the message reference key for the first (oldest) message on the call message queue that should be displayed on the panel. One of the following special values can be used:

(blank)	No messages are shown to the user on the initial panel, even if there are messages in the call message queue. This is the default value when a short argument list is passed to the Display Panel (QUIDSPP) API.
FRST	All new messages in the call message queue, starting with the first new message in the queue, are presented on the initial panel.

Cursor position option

INPUT; CHAR(1)

The rules that determine the initial position of the cursor when the panel is displayed. This parameter controls only the initial cursor placement when the panel is displayed by the QUIDSPP API. When a panel is redisplayed by the UIM or by the application program, the cursor remains where it was left by the user.

One of the following values must be used:

A	Cursor positioning for action list processing is performed. This value is used when the panel is redisplayed after action list processing when ACTOR=CALLER is on the list area (LIST) tag. The cursor and list are positioned as defined by the last list entry and error list entry parameters.
D	Default cursor positioning is performed. The specific cursor position depends on whether or not any variables or list entries associated with the panel are marked in error. This is the default value when a short argument list is passed to the display panel (QUIDSPP) API.
P	Cursor positioning that is controlled by the program is performed. The cursor is positioned using the current value of the dialog variables associated with the CSRVAR, CSRPOS, CSRLST, and CSREID attributes of the panel definition (PANEL) tag. Cursor positioning controlled by the program is allowed only for a panel containing all four cursor positioning attributes. With cursor positioning controlled by the program, each pageable, nonlist area is repositioned to make sure that the first input field in error is visible, but the cursor is not positioned at the first input field in error. If the value of any of the dialog variables for cursor position identified in the panel definition is unusable, the cursor defaults to the first input field on the panel.

Last list entry

INPUT; CHAR(4)

The list entry handle for the last action list entry that had an action processed.

This information is used to position the cursor. Cursor positioning for action list processing must be specified in the cursor position option parameter or this parameter is ignored. One of the following special values can be used:

EXTE	The last list action processed is for the extended action entry.
NONE	The application is providing no value for this parameter. This is the default value when a short argument list is passed to the Display Panel (QUIDSPP) API.

Error list entry

INPUT; CHAR(4)

The list entry handle for the first and only list entry that had an error while processing list actions. This parameter is also set when action list processing is stopped because a user pressed F3 (Exit) or F12 (Cancel). This information displays the correct page of list information.

Cursor positioning for action list processing must be specified in the cursor position option parameter, or this parameter is ignored.

One of the following special values can be used:

EXTE	The extended action entry is in error; the UIM does not reposition the list.
NONE	The application is providing no value for this parameter. This is the default value when a short argument list is passed to the Display Panel (QUIDSPP) API.

Wait time

INPUT; BINARY(4)

The number of seconds to wait for data to become available from the work station. After this amount of time, the keyboard locks, control returns to the application, and the function requested parameter returns an indication that the wait time ended. Because the wait time ended, input dialog variables associated with the panel are not updated. The number of seconds specified should be a positive integer.

One of the following special values can be used:

-1	The UIM waits indefinitely until data becomes available from the work station. This is the default value when a short argument list is passed to the Display Panel (QUIDSPP) API.
0	The UIM does not wait for data to become available from the work station. The panel is displayed with the keyboard locked, and control returns immediately to the application with an indication in the function requested parameter that the wait time ended.

Optional Parameter Group 2

Length of call message queue name

INPUT; BINARY(4)

The length of the call message queue name. Valid values for this parameter range from 1 to 256. If the value is not valid, an error will occur.

The default value for this parameter is 10.

Call qualification

INPUT; CHAR(20)

The name of the module and bound program that contain the procedure. This value is used to further qualify the procedure identified in the call message queue parameter. The first 10 characters specify the module name, and the second 10 characters specify the bound program name. When the call qualification parameter is specified, the call stack will be searched only for a procedure within a bound program.

If this parameter is not used, only the call message queue parameter will be used to identify the call.

The special value of *NONE can be used for the module or bound program name, or for both. When *NONE is specified for one of the names, then that name will not be used when searching for the qualified procedure. If *NONE is specified for both names, only the call message queue parameter will be used to identify the call. Original program model (OPM) programs should specify *NONE for both names.

Error Messages