Exit Program for General Panel Checking

A general exit program may be specified on the USREXIT attribute of the panel definition (PANEL) tag. This attribute specifies the name of a dialog variable identifying the program to call.

The UIM calls the program:

• After any necessary validity checking is done by the UIM

  For a VARUPD=YES attribute on the key item (KEYI) or pull-down field choice (PDFLDC) tags, the UIM has already performed validity checking on all displayed values. If errors are found, the UIM does not call the exit program. The current panel is automatically redisplayed with the appropriate message and error highlighting.

  For a VARUPD=NO attribute, the UIM saves all values from entry fields in their displayed form and does not update the dialog variables. The exit program does not have access to these values.

• After the UIM determines what function to perform

  For some dialog commands, the UIM does not call the exit program. For more information about when the UIM calls the exit program, see Application Display Programming manual.

  Any errors detected during function determination cause the UIM to redisplay the panel without calling the exit program.

• Before the UIM performs the determined function, including dialog variable substitution in command strings specified in the CMD dialog command.

The UIM calls the general exit program and passes information about the function. The exit program performs its task and returns control to the UIM through a normal return or by sending a CPF6A02 or CPF6A03 status message. These messages are transient messages.

If the exit program returns control by sending a CPF6A02 status or escape message, the UIM does not perform the determined function. The panel is redisplayed and any previous messages sent to the UIM are shown.

If the exit program returns control by sending a CPF6A03 status or escape message, the UIM continues performing the determined function. Any previous messages sent to the UIM by the general exit program are shown if and when the function completes. These messages are transient messages.

If the exit program returns control by sending any escape message other than CPF6A02 or CPF6A03, the UIM does not perform the determined function. The panel is redisplayed and any previous messages sent to the UIM are shown. These messages are user messages.

If the exit program returns control normally or sends a non-escape message other than CPF6A02 or CPPF6A03, the UIM continues performing the determined function.

Messages sent to the UIM are displayed only once. They are cleared when the next dialog command is performed, excluding the HELP, PRINT, and PAGEUP or PAGEDOWN (only if paging the message line) dialog commands. If the exit program marks dialog variables in error, the exit program or other application code is responsible for resetting the dialog variables when the variable is no longer incorrect.

The general exit program allows applications to perform extended validity checking on field values. However, other functions are possible because the exit program has access to panel information used by the UIM to perform a specified function. The exit program can prevent the UIM from processing the function. For example, the exit program could intercept a function key, perform some other function, and tell the UIM to not process the function key. While the UIM does not prevent this type of thing, it is the application developer's responsibility to understand enough about UIM processing to ensure that things work properly.

The action performed by the UIM is determined before the exit program is called. Some actions, such as whether or not to perform the action list processing, depend on the contents of dialog variables or list entries. Changes to these variables or list entries do not cause the UIM to evaluate the determined action again.

Dialog variable substitution into command strings is not done until after the exit program is called; changing dialog variables can affect the final, submitted command.

The exit and cancel flags for the job are not reset before the exit program is called, and they are not checked after the exit program returns control to the UIM. Therefore, exit and cancel flags should not be turned on by the exit program.

Authorities and Locks

None.

Required Parameter Group

General panel checking information

INPUT; CHAR(*)

A structure that provides information related to the user request. For details, see Single Parameter Structure.

Type of call

INPUT; BINARY(4)

This parameter must be set to the following value:

4	Processes a general panel exit.

Application handle

INPUT; CHAR(8)

The application handle of the application that is currently being processed by the UIM.

Panel name

INPUT; CHAR(10)

The name of the panel that is currently being processed by the UIM.

Function key pressed

INPUT; BINARY(4)

The function key that is pressed:

1-24	A function key (F1-F24) is pressed.
26	The Enter key is pressed.
28	The Page Up key is pressed.
29	The Page Down key is pressed.
31	The Home key is pressed.

The general exit program is not called for any other keys.

Function key qualifier

INPUT; BINARY(4)

Provides information about the function that will be performed unless the exit program returns through a CPF6A02 message:

-1	Submits a command from the command line.
-2	Performs list action processing. The ACTOR attribute of the list area (LIST) tag determines whether the processing is to be performed by the UIM or by the application program displaying the panel.
-3	Processes a menu item selection.
-4	The Enter key is pressed and there is no function for the UIM to perform. The default enter action specified on the ENTER attribute of the display panel (PANEL) tag will be performed.
-5	Processes a cursor-sensitive prompt function.
-6	Processes a selection from a pull-down choice. This value is used only when the interface level is two or greater.
-7	Processes the default selection action specified on the SELECT attribute of the PANEL tag because the Enter key was pressed or the user selected one or more entries in an action list or selection list, and there was no function for the UIM to perform.

Option number

INPUT; BINARY(4)

When the parameter for the function key qualifier indicates that the UIM is processing a menu item, this parameter is set to the option number of the menu item selected by the user.

When the parameter for the function key qualifier indicates that the UIM is processing a pull-down choice, this parameter is set to the option number of the pull-down choice selected by the user.

For all other values for the function key qualifier, this parameter is not set.

Pull-down field name

INPUT; CHAR(10)

The name of the pull-down field from which the pull-down choice is selected. If the pull-down field does not have a name, this parameter is set to blanks.

For all other values of the function key qualifier, this parameter is not set.

This parameter is available only when the interface level is set to two or greater.

Single Parameter Structure

For detailed descriptions of the fields in this table, see Field Descriptions.

Field Descriptions

Application handle. The application handle of the application that is currently being processed by the UIM.

Function key pressed. The function key that is pressed:

The general exit program is not called for any other keys.

Function key qualifier. Provides information about the function that will be performed unless the exit program returns through a CPF6A02 message:

Option number. When the field for the function key qualifier indicates that the UIM is processing a menu item, this field is set to the option number of the menu item selected by the user.

When the field for the function key qualifier indicates that the UIM is processing a pull-down choice, this field is set to the option number of the pull-down choice selected by the user.

For all other values for the function key qualifier, this field is not set.

Panel name. The name of the panel that is currently being processed by the UIM.

Pull-down field name. The name of the pull-down field from which the pull-down choice is selected. If the pull-down field does not have a name, this field is set to blanks.

For all other values of the function key qualifier, this field is not set.

This field is available only when the field for the structure level is set to two or greater.

Reserved. A reserved field.

Structure level. The interface level supported by this structure, indicating which fields and values are available for the current interface level.

Type of call. This field must be set to the following value:

[ Back to top | User Interface Manager APIs | APIs by category ]