340 lines
14 KiB
HTML
340 lines
14 KiB
HTML
|
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
||
|
|
<html>
|
||
|
|
<head>
|
||
|
|
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
|
||
|
|
<meta name="Copyright" content="Copyright (c) 2006 by IBM Corporation">
|
||
|
|
<title>Using the User Interface Manager (UIM) Exit Programs</title>
|
||
|
|
<!-- All rights reserved. Licensed Materials Property of IBM -->
|
||
|
|
<!-- US Government Users Restricted Rights -->
|
||
|
|
<!-- Use, duplication or disclosure restricted by -->
|
||
|
|
<!-- GSA ADP Schedule Contract with IBM Corp. -->
|
||
|
|
<link rel="stylesheet" type="text/css" href="../rzahg/ic.css">
|
||
|
|
</head>
|
||
|
|
<body>
|
||
|
|
<a name="Top_Of_Page"></a>
|
||
|
|
<!--Java sync-link-->
|
||
|
|
<script type="text/javascript" language="Javascript" src="../rzahg/synch.js">
|
||
|
|
</script>
|
||
|
|
|
||
|
|
<h2>Using the User Interface Manager (UIM) Exit Programs</h2>
|
||
|
|
|
||
|
|
<p>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.</p>
|
||
|
|
|
||
|
|
<p>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.</p>
|
||
|
|
|
||
|
|
<p>The CALL dialog command is provided so that an application can link programs
|
||
|
|
and panels without a command interface.</p>
|
||
|
|
|
||
|
|
<p>The CALL dialog command causes program calls to handle one of the following
|
||
|
|
requests:</p>
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li>Function keys</li>
|
||
|
|
|
||
|
|
<li>Menu items</li>
|
||
|
|
|
||
|
|
<li>Action list options</li>
|
||
|
|
|
||
|
|
<li>Pull-down field choices</li>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<p>Exit programs allow applications to perform functions for which the UIM does
|
||
|
|
not provide generic support. Exit program capability exists for the following
|
||
|
|
purposes:</p>
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li>Action list update processing</li>
|
||
|
|
|
||
|
|
<li>Application formatting of data</li>
|
||
|
|
|
||
|
|
<li>Conditioning panel items</li>
|
||
|
|
|
||
|
|
<li>Cursor-sensitive prompting</li>
|
||
|
|
|
||
|
|
<li>General panel checking</li>
|
||
|
|
|
||
|
|
<li>Incomplete list processing</li>
|
||
|
|
|
||
|
|
<li>Text area data</li>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<h3><a name="HDRCALLUIM">Calling a UIM Exit Program</a></h3>
|
||
|
|
|
||
|
|
<p>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.</p>
|
||
|
|
|
||
|
|
<p>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:</p>
|
||
|
|
|
||
|
|
<dl compact>
|
||
|
|
<dt><strong>Call by address</strong></dt>
|
||
|
|
|
||
|
|
<dd>When the dialog variable specified is defined with BASETYPE=PTR on the
|
||
|
|
class definition (CLASS) tag, the program is called by address.
|
||
|
|
|
||
|
|
<p>It is the responsibility of the application program to ensure that the
|
||
|
|
pointer is set correctly.</p>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><strong>Call by name</strong></dt>
|
||
|
|
|
||
|
|
<dd>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.</dd>
|
||
|
|
|
||
|
|
<dt><strong>Extended program model (EPM) call</strong></dt>
|
||
|
|
|
||
|
|
<dd>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.</dd>
|
||
|
|
</dl>
|
||
|
|
|
||
|
|
<p>The UIM can call programs in the Integrated Language Environment<SUP>(R)</SUP> (ILE) model
|
||
|
|
using call by address or call by name. Only the main entry point of the program
|
||
|
|
can be used.</p>
|
||
|
|
|
||
|
|
<h3><a name="Header_100">Using a Parameter Interface</a></h3>
|
||
|
|
|
||
|
|
<p>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.</p>
|
||
|
|
|
||
|
|
<p>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.</p>
|
||
|
|
|
||
|
|
<p>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.</p>
|
||
|
|
|
||
|
|
<p>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<SUP>(TM)</SUP> 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
|
||
|
|
<a href="quiopnda.htm">Open Display Application (QUIOPNDA) API</a> and <a href=
|
||
|
|
"quiopnpa.htm">Open Print Application (QUIOPNPA) API</a>.</p>
|
||
|
|
|
||
|
|
<p>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.</p>
|
||
|
|
|
||
|
|
<p>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
|
||
|
|
<strong>interface level</strong> 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.</p>
|
||
|
|
|
||
|
|
<p>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.</p>
|
||
|
|
|
||
|
|
<h3><a name="Header_101">Handling Messages</a></h3>
|
||
|
|
|
||
|
|
<p>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:
|
||
|
|
<strong>transient</strong> and <strong>user</strong>.</p>
|
||
|
|
|
||
|
|
<h4><a name="Header_102">Transient</a></h4>
|
||
|
|
|
||
|
|
<p>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 <strong>transient</strong> 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.</p>
|
||
|
|
|
||
|
|
<p>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).</p>
|
||
|
|
|
||
|
|
<h4><a name="Header_103">User</a></h4>
|
||
|
|
|
||
|
|
<p>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 <strong>user</strong> messages.
|
||
|
|
When the panel is redisplayed by the UIM, the user messages are shown on the
|
||
|
|
message line of the panel.</p>
|
||
|
|
|
||
|
|
<p>When certain dialog commands are subsequently performed for the panel, the
|
||
|
|
UIM no longer displays the user messages on the panel, see the <a href=
|
||
|
|
"../books/sc415715.pdf" target="_blank">Application Design
|
||
|
|
Programming</a><img src="wbpdf.gif" alt="Link to PDF"> 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.</p>
|
||
|
|
|
||
|
|
<p>The following table shows how the UIM handles messages sent by exit
|
||
|
|
programs.<br>
|
||
|
|
</p>
|
||
|
|
|
||
|
|
<p><strong><a name="Table_2-1">Messages and exit
|
||
|
|
programs</a></strong><br>
|
||
|
|
</p>
|
||
|
|
|
||
|
|
<table border>
|
||
|
|
<tr>
|
||
|
|
<th align="left" valign="top" width="20%">Exit program</th>
|
||
|
|
<th align="left" valign="top" width="45%">Action when messages are sent to the
|
||
|
|
UIM</th>
|
||
|
|
<th align="left" valign="top" width="45%">Escape message difference</th>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">CALL Program for a Function Key</td>
|
||
|
|
<td align="left" valign="top">All messages<sup>1</sup> sent by the
|
||
|
|
exit program become <strong>user</strong> messages.</td>
|
||
|
|
<td align="left" valign="top">None</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">CALL Program for a Menu Item</td>
|
||
|
|
<td align="left" valign="top">All messages<sup>1</sup> sent by the
|
||
|
|
exit program become <strong>user</strong> messages.</td>
|
||
|
|
<td align="left" valign="top">None</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">CALL Program for Action List Option
|
||
|
|
and Pull-Down Field Choice</td>
|
||
|
|
<td align="left" valign="top">All messages<sup>1</sup> sent by the
|
||
|
|
exit program become <strong>user</strong> messages.</td>
|
||
|
|
<td align="left" valign="top">Escape messages stop action or choice
|
||
|
|
processing and the panel is redisplayed. The option or choice is highlighted
|
||
|
|
and any user messages are displayed.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">Exit Program for General Panel
|
||
|
|
Checking</td>
|
||
|
|
<td align="left" valign="top">All messages<sup>1</sup> sent by the
|
||
|
|
exit program become <strong>transient</strong> messages only if the exit
|
||
|
|
program returns control to the UIM by sending CPF6A02 or CPF6A03 as a status or
|
||
|
|
escape message.</td>
|
||
|
|
<td align="left" valign="top">CPF6A02 ends the user action. Other
|
||
|
|
messages sent are displayed as transient messages. CPF6A03 does not end the
|
||
|
|
user action. Other messages sent are displayed as transient messages. Escape
|
||
|
|
messages other than CPF6A02 and CPF6A03 ends the user action. Other messages
|
||
|
|
sent are displayed as user messages. See the section for this exit program for
|
||
|
|
details.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">Exit Program for Action List Option or
|
||
|
|
Pull-Down Field Choice</td>
|
||
|
|
<td align="left" valign="top">All messages<sup>1</sup> sent by the
|
||
|
|
exit program become <strong>user</strong> messages.</td>
|
||
|
|
<td align="left" valign="top">Escape messages stop action or choice
|
||
|
|
processing and the panel is redisplayed. The option or choice is highlighted
|
||
|
|
and any user messages are displayed.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">Exit Program for Incomplete List</td>
|
||
|
|
<td align="left" valign="top">All messages<sup>1</sup> sent by the
|
||
|
|
exit program become <strong>user</strong> messages only if the exit program
|
||
|
|
returns control to the UIM by sending CPF6A05 as a status or escape
|
||
|
|
message.</td>
|
||
|
|
<td align="left" valign="top">If an escape message other than
|
||
|
|
CPF6A05 is sent the UIM cannot complete the list and will send CPF6A95 as an
|
||
|
|
escape message to the application.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">Exit Program for Application Formatted
|
||
|
|
Data</td>
|
||
|
|
<td align="left" valign="top">All<sup>1</sup> but escape messages
|
||
|
|
sent by the exit program are ignored.</td>
|
||
|
|
<td align="left" valign="top">Escape messages cause the UIM to not
|
||
|
|
call this exit program again until another display panel is done for the panel.
|
||
|
|
Dialog variables pointing to the exit program have to be set again. The escape
|
||
|
|
message will be displayed on the panel as a user message.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">Exit Program for a Cursor-Sensitive
|
||
|
|
Prompt</td>
|
||
|
|
<td align="left" valign="top">All messages<sup>1</sup> sent by the
|
||
|
|
exit program become <strong>user</strong> messages.</td>
|
||
|
|
<td align="left" valign="top">None</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">Exit Program for Text Area Data</td>
|
||
|
|
<td align="left" valign="top">All messages<sup>1</sup> sent by the
|
||
|
|
exit program become <strong>user</strong> messages.</td>
|
||
|
|
<td align="left" valign="top">CPF6A07 causes the UIM to end the
|
||
|
|
display of this text area panel and return to the display panel caller. See the
|
||
|
|
section for this exit program for details.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top" colspan="3"><sup>1</sup> Messages refer to
|
||
|
|
ESCAPE, INFO, COMP, and DIAG messages.<br>
|
||
|
|
</td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
|
||
|
|
<p>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:</p>
|
||
|
|
|
||
|
|
<ol>
|
||
|
|
<li>Receive the escape message and save its message reference key.</li>
|
||
|
|
|
||
|
|
<li>Move all INFO, COMP, and DIAG messages to the previous program message
|
||
|
|
queue.</li>
|
||
|
|
|
||
|
|
<li>Perform any cleanup processing required for the application program.</li>
|
||
|
|
|
||
|
|
<li>Resend the escape message using its message reference key.</li>
|
||
|
|
</ol>
|
||
|
|
|
||
|
|
<p>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.</p>
|
||
|
|
|
||
|
|
<hr>
|
||
|
|
<center>
|
||
|
|
<table cellpadding="2" cellspacing="2">
|
||
|
|
<tr align="center">
|
||
|
|
<td valign="middle" align="center"><a href="#Top_Of_Page">Top</a> | <a href=
|
||
|
|
"uim1.htm">User Interface Manager APIs</a> | <a href="aplist.htm">APIs by
|
||
|
|
category</a></td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
</center>
|
||
|
|
</body>
|
||
|
|
</html>
|
||
|
|
|