Execute ISPF Dialog Application

Function:

The "Execute ISPF Dialog Application" tool lets you integrate an ISPF dialog application directly as an AWM application. The ISPF application runs in a user server of the z/Server environment on the remote system. Only the UI is executed on the client side.

Modeling tools of type "Execute ISPF Dialog Application" requires a z/Server installation on z/OS.

Tool Attributes:

Attribute	Type	Description
Invocation Form [M]	Selection	Specifies how the ISPF application is called. Permitted values are REXX, CMD or PGM.
Program Name [M]	String	Name of the ISPF application.

Tool Parameter

Tool input and output parameters have to be defined corresponding to the expected input and output parameters of the attached ISPF tool.

Relationship: Used Panel

Attribute	Type	Description
Panel Name [M]	Execute ISPF Dialog	References a tool for an ISPF panel included in the dialog application.

Further Information:

Calling an ISPF dialog application can be modeled in a number of ways:

REXX (called as a REXX subroutine)
CMD (called using an ISPF service Select CMD(...))
PGM (called using the ISPF service Select PGM(...) Parm(...))

When attaching ISPF dialog tools, the ISPF dialog application runs on z/OS in a separate ISPF batch environment managed by the Micro Focus z/Server. ISPF panel fields are directly exchanged with AWM-modeled dialog fields.

An ISPF tool which displays at least one ISPF panel has to be defined in the AWM model using the tool descriptor "Execute ISPF Dialog".

The advantage of this approach is that the attached ISPF tool which implements the dialog application, does not need to be changed.

Customization is only necessary in the ISPF panels called in the attached application. The ISPF panels are extended by calls to the REXX procedure TAUZCDIF, which handles the communication between the ISPF dialog application and the client dialogs.

The REXX procedure TAUZCDIF can be called in three ISPF panel sections:

INIT section
REINIT section
PROC section

Calling TAUZCDIF in the INIT or REINIT section is used to pass the values of the panel fields and ISPF variables relevant for the dialog between the ISPF application and the client dialog in both directions.

Calling TAUZCDIF in the PROC section is only used for ISPF table processing.

The extension of the ISPF panel in the INIT or REINIT section has the following format:

VGET(TAUTODIA) SHARED                                                
IF (&tautodia = 'Y')    
    
   VGET(TAUERR) SHARED                                             
   &taupanel = '<panel name>'                                             
   &taucurs = .CURSOR                                                
   &tauttl = '<panel title>’                                      
   &taups = 'I'                                                      
   &tauparms = ‘<var1> <var2> … <varn>’ 
   *REXX(*,TAUPANEL,TAURESP,TAUPS,TAUPARMS,TAUCURS,TAUERR,TAUTTL,    
         (TAUZCDIF))                                                 
   IF (&tauerr ^= &z)                                                
      VGET(TAUTOZCP) SHARED                                          
      &tautozcp = '&tautozcp &tauerr'                                
      VPUT(TAUTOZCP) SHARED

The ISPF panel extension starts with a VGET statement of the shared pool variable TAUTODIA which is set to ‘Y’ by the ISPF dialog tool adapter TAUZCIFD.

Some special variables are defined and explained in the table below.

The REXX procedure TAUZCDIF is only called from the z/Server and invoked from AWM. This means that the ISPF dialog application still works in an ISPF online session invoked in a 3270 emulator session.

It is important that all ISPF variables which are not fields in the BODY section of the panel are explicitly passed to the panel REXX: this means particularly the special variables explained below but also all other ISPF variables which are not declared as input or output fields in the panel’s BODY section but whose values are to be passed to the Client dialog.

The * in the parameter list of the TAUZCDIF call ensures that all ISPF variables defined as input or output fields in the panel’s BODY section are passed to the Client dialog.

Note: If the panel contains a MODEL section, only the ISPF variables of the MODEL section are passed by the * parameter to the panel REXX. In this case, all other ISPF variables of the BODY section have to be explicitly passed to the panel REXX as well.

The special variable TAUERR is fetched from the ISPF shared pool before calling the panel REXX, so that dialog error conditions detected in a preceding dialog step can be passed to the panel REXX. The panel REXX sends the error message to the client and the user is informed of the error by an error message dialog.

The call to the panel REXX TAUZCDIF is followed by a check that the special variable TAUERR has some content. If it does, the content is concatenated to the actual content of the ISPF variable TAUTOZCP which contains error messages from the tool execution and is evaluated by the tool adapter TAUZCIFD.

Special variable	Description
TAUPANEL	Name of the panel
TAUPS	Panel section (I, R or P)
TAURESP	ISPF variable in which the dialog response (Enter or PF3) is returned
TAUCURS	Name of the field in which the cursor is positioned
TAUTTL	Title of the panel
TAUERR	ISPF variable containing error messages from the dialog tool
TAUPARMS	List of names of all variables to be passed to the SWT dialog. The special variable TAUPARMS contains a list of variable names whose values are passed to the Client dialog in the sequence in which they are written in the TAUPARMS string

On the client side, a standard input dialog corresponding to the ISPF panel must be defined in the AWM model as a tool of type "Execute ISPF Dialog".

The panel fields defined for a tool of type "Execute ISPF Dialog" must correspond exactly to the variables defined under TAUPARMS in the extended ISPF panel. The extension of the ISPF panel in the PROC section of a non TBDISPL panel has the following format:

IF (&tautodia = 'Y')                
   IF (&TAURESP = 'Exit')           
      .RESP = END

An AWM feature can be used to generate all the AWM model components, which are necessary to model a tool of type "Execute ISPF Dialog Application", from an XML file. See ISPF Panel Model Generator for more information.