Using the User Interface Manager (UIM) Exit Programs

Through panel definitions and APIs, an application program can cause the UIM to call other application programs as part of normal panel management. These programs are divided into two classes: programs called through the CALL dialog command and programs called as exit programs.

This section describes the different exits and CALL situations. The UIM does not require a program to follow prescribed actions in its operating environment; attempts to use these exit programs for purposes other than the intended purpose may cause problems for applications and their users.

The CALL dialog command is provided so that an application can link programs and panels without a command interface.

The CALL dialog command causes program calls to handle one of the following requests:

• Function keys
• Menu items
• Action list options
• Pull-down field choices

Exit programs allow applications to perform functions for which the UIM does not provide generic support. Exit program capability exists for the following purposes:

• Action list update processing
• Application formatting of data
• Conditioning panel items
• Cursor-sensitive prompting
• General panel checking
• Incomplete list processing
• Text area data

Calling a UIM Exit Program

All programs are specified by naming a dialog variable, which identifies the program to call. For the incomplete list exit program, the dialog variable name is specified on the call to the Set List Attributes (QUISETLA) API. For all other exit and CALL programs, the dialog variable name is specified as a parameter to the CALL dialog command in the tag language source.

The UIM uses the current value of the dialog variable to identify the program to call. Depending on the definition of the dialog variable, there are three different ways to call the program:

Call by address

When the dialog variable specified is defined with BASETYPE=PTR on the class definition (CLASS) tag, the program is called by address.

It is the responsibility of the application program to ensure that the pointer is set correctly.

Call by name

When the dialog variable specified is defined with BASETYPE='CHAR 20' on the CLASS tag, the program is called by name. It is the responsibility of the application program to ensure that the variable contains the object and library name of the program called.

Extended program model (EPM) call

When the dialog variable specified is defined with BASETYPE='CHAR 130' on the CLASS tag, the program is called in the extended program model (EPM) environment. This type of call is used when the target program is written in an EPM language such as Pascal or ILE C. It is the responsibility of the application program to ensure that the variable contains the appropriate information for calling an entry point for an EPM environment.

The UIM can call programs in the Integrated Language Environment^(R) (ILE) model using call by address or call by name. Only the main entry point of the program can be used.

Using a Parameter Interface

When a UIM application is opened, the calling program must specify whether all application programs, called as an exit program or using the CALL dialog command, are passed a single or multiple parameter interface.

When a single parameter is passed, that parameter is a space pointer to a structure containing information for the type of exit or CALL function.

The single parameter interface is used by programs written in languages that can efficiently process data structures. Passing a single parameter is more efficient than passing multiple parameters, and any extensions to the interface are accessible without changing the parameter list of the program being called.

When the single parameter interface is chosen, the structure passed contains a field indicating the level of the structure. Beginning in Version 2 Release 2 (V2R2) of the i5/OS^(TM) operating system, the structure level is set to two. All parameters and values of a structure are passed when the structure level is equal to or greater than one, unless the parameter description notes otherwise. For more information about choosing the interface level for exit programs, see Open Display Application (QUIOPNDA) API and Open Print Application (QUIOPNPA) API.

The interface with multiple parameters is available for programs written in languages that cannot efficiently process data structures. When multiple parameters are passed, each parameter is a space pointer to a piece of information necessary for the type of exit or CALL function.

When the multiple parameter interface is chosen by the program opening the UIM application, the program must also choose which interface level to use. The interface level defines the number of parameters passed for a given type of exit or CALL function. This interface allows the parameter interfaces to be extended in the future with upward compatibility for existing application exit programs.

Because the application handle is passed, programs can use dialog variables to access common information. It is more efficient to place one pointer variable that points to a structure or array into the variable pool than to place all the variables from the structure or array into the variable pool.

Handling Messages

After the UIM calls an application program or runs a control language (CL) command, it handles messages sent to the UIM. There are two kinds of messages: transient and user.

Transient

Messages sent by the general exit program are moved to an internal UIM message queue if the exit program returns control to the UIM by sending CPF6A02 or CPF6A03 as a status or escape message. Escape messages are changed to diagnostic messages when they are moved from one message queue to another. These messages are referred to as transient messages. When the panel is redisplayed by the UIM and the exit program returns control to the UIM as described above, the transient messages are shown on the message line of the panel. Any escape message will cancel the action as CPF6A02 does, but messages will become user messages not transient. When the message is seen on the panel and the to program is QUIMGFLW, then the message is transient; otherwise, it's a user message.

When certain dialog commands are subsequently performed for the panel, in most cases, transient messages are removed from the UIM's internal message queue and no longer appear in the job log. These messages are not removed if the next dialog command performed is HELP, PRINT, PAGEUP, or PAGEDOWN (if paging the message line).

User

Messages sent by other types of exit programs or by a CL command are moved to the call message queue identified on the call to the Display Panel (QUIDSPP) API. This is also true if the general exit program returns control to the UIM by sending any escape message, other the CPF6A02 or CPF6A03. Escape messages are changed to diagnostic messages when they are moved from one message queue to another. These messages are referred to as user messages. When the panel is redisplayed by the UIM, the user messages are shown on the message line of the panel.

When certain dialog commands are subsequently performed for the panel, the UIM no longer displays the user messages on the panel, see the Application Design Programming book. The UIM never changes or removes messages from the call message queue. It is the responsibility of the application program to remove these messages from the call message queue as appropriate.

The following table shows how the UIM handles messages sent by exit programs.

Messages and exit programs

Escape messages and other accompanying messages are displayed on the panel message line. If the program is sent an escape message to be resent to the UIM, it needs to do the following:

1. Receive the escape message and save its message reference key.
2. Move all INFO, COMP, and DIAG messages to the previous program message queue.
3. Perform any cleanup processing required for the application program.
4. Resend the escape message using its message reference key.

Whenever an escape message is sent to the UIM from the program or a CL command, the message indicates that the function performed was unsuccessful. The UIM then takes whatever action is appropriate for the unsuccessful function. Usually this will be a redisplay of the panel.