Configuring the ISPF gateway for build, deployment, and promotion support

With IBM® Engineering Workflow Management (EWM), you can run programs and executable files as part of build, deployment, and promotion. If these programs or executable files are ISPF-based, they must be started through the ISPF gateway. How these programs and executable files are run depends on the environment from which they are started. You can configure the ISPF gateway to support build, deployment, and promotion components that are available with a Developer for IBM Enterprise Platforms client access license.

The ISPF gateway enables client applications to connect to a z/OS® host and run TSO and ISPF commands. The ISPF gateway is installed as part of ISPF as load modules and files in the HFS. These files are typically installed in /usr/lpp/ispf/bin. The build, deployment, and promotion components are created as part of the SMP/E installation. Depending on your setup, extra modifications might be required of the ISPF gateway supplied scripts and components. The default settings and procedure for modifying the defaults are described later.

The following table shows how programs or executable files can be run during build, deployment, and promotion, and the available support for them.
Table 1. Starting commands for EWM components
Definition Command Started from
Build translator ISPF command or executable file ISPF gateway
TSO command or executable file ISPF gateway
Build definition Pre-build command line UNIX System Services (USS) command
Post-build command line UNIX System Services (USS) command
Package definition Package pre-command ISPF gateway
Package post-command ISPF gateway
Deployment definition Deploy pre-command ISPF gateway
Deploy post-command ISPF gateway
Rollback pre-command ISPF gateway
Rollback post-command ISPF gateway
Promotion definition Pre-build command line UNIX System Services (USS) command
Post-build command line UNIX System Services (USS) command
Programs or executable files can be run by using the ISPF gateway or a UNIX System Services (USS) command. USS commands cannot start ISPF commands, and they can only start limited TSO commands. Commands started through the ISPF gateway have the full set of ISPF and TSO APIs available. Pre-build and post-build commands for build and promotion definitions are started through USS. For more information, see Starting the ISPF gateway from a USS command.

The following components are included with the ISPF gateway:

ISPF gateway environment file: ISPZXENV
ISPF gateway environment file that contains customizable settings for the ISPF gateway.
The ISPZXENV file is provided as part of z/OS. By default this file is installed into /usr/lpp/ispf/bin. However, this directory is marked READ only after installation. This environment file is run by the ISPF gateway to get the value of certain environment variables necessary for the ISPF gateway to run. Default variables include the following:
Note: You can add more system load libraries to this STEPLIB allocation. For example, DB2®.SDSNLOAD, if you have programs or executable files that start Db2 functions such as BIND.
By default is set to CGI_ISPCONF = '/etc/ispf'
By default is set to CGI_ISPWORK = '/var/ispf'

To set variables to non-default values, copy ISPZXENV to a writable configuration directory, such as /etc/ispf and set the variables to your required values. You must then alter your path environment variable in, which is described later, to read that location before the default ISPF bin path.

For example:
export PATH=/etc/ispf:$PATH  

In the ISPF gateway work directory, by default /var/ispf, you must have an existing directory created called WORKAREA, which has read and write permissions for all users. Temporary directories of the format /var/ispf/WORKAREA/<userid>/* are created when the ISPF gateway is used. If you are using the default ISPF gateway installation as provided by ISPF, this directory is typically in /var/ispf/WORKAREA. If the directory does not exist, follow the instructions in the chapter that is titled, Installing and customizing the gateway in ISPF Planning and Customizing (GC19-3623).

ISPF gateway startup script:
Shell script to start the ISPF gateway for deployment and promotion.
In order to start the ISPF gateway, Engineering Workflow Management provides a shell script that is called from the deployment and promotion Ant tasks. This script is installed into /usr/lpp/jazz/v7.0.1/buildsystem/buildtoolkit/examples/ispfgateway. As part of standard customization, this script is copied to the Engineering Workflow Management configuration directory, typically /etc/jazz701/ccm by the BLZCPBTK job. Depending on your setup, you might need to modify this shell script to set some environment variables.
The PATH variable must point to the ISPF gateway home directory:
export PATH=$PATH:/usr/lpp/ispf/bin             
If you modified ISPZXENV you might need to set the PATH to:
export PATH=$PATH:/etc/ispf:/usr/lpp/ispf/bin

If you use different library concatenations in ISPF.conf, configure your installation to support multiple projects and streams by creating multiple copies of the script, ISPF.conf file, and ISPZXENV file. In each copy of the ISPZXENV file, set the CGI_ISPFCONF variable to point to the location of the related ISPF.conf file. Then, in each copy of the script, set the PATH variable to point to the appropriate copy of the ISPF.conf file. Then, use the script that corresponds to the environment needed for a particular project.

Enterprise Extensions build startup script:
Shell script to start the Rational® Build Agent by using an Enterprise Extensions build.
Enterprise Extensions builds provide a mechanism to start a build that in turn starts a program. The program can be an ISPF command or executable file or a TSO command or executable file. If an ISPF allocated library object is being started by the build , you must configure the build to provide access to the required object. In, you must list the location of the ISPF-supplied files so the Rational Build Agent can start the ISPF gateway. By default these files are in /usr/lpp/ispf and are specified in using variable _CMDSERV_BASE_HOME. If you have the ISPF gateway binary files installed in another location, you must change this variable. For example:
# Specify the home directory for the ISPF programs.
export _CMDSERV_BASE_HOME=/usr/lpp/ispf                   

ISPF programs and executable files must be allocated in the ISPF gateway configuration file (ISPF.conf) as described later. The Rational Build Agent also requires access to the ISPF.conf. Access is set in the ISPF gateway environment file (ISPZXENV). If you plan to use the ISPF capabilities in the builds and you do not use the default location /usr/lpp/ispf/bin, you must create a copy of ISPZXENV in a writeable configuration directory and point the Rational Build Agent to that location. Set the build property to the directory location that contains the ISPZXENV file. You can edit the value or add the property by using the Properties tab in your build definition. For more information, see Managing z/OS builds

ISPF gateway configuration file: ISPF.conf
ISPF gateway configuration file that contains customizable settings for the ISPF gateway.
The ISPF.conf file is provided as part of z/OS. The ISPF gateway configuration file provides the allocations that are required to start an ISPF session in a created task. The ISPF.conf file performs a similar function to a logon procedure that allocates the ISPF environment for a logged on ISPF user. In order for the build, deployment, and promotion functions to start modules to perform specific tasks, the modules must be made available in the ISPF concatenations. By default these allocations are set up as follows:
For deployment and promotion to work, add the Engineering Workflow Management product load library (hlq.SBLZLOAD) and product message library (hlq.SBLZMENU) to the ISPLLIB and ISPMLIB concatenation. The modified allocations look similar to this example:
During build, promotion, or deployment, if you run your own programs or REXX executable files and those programs or executable files are called as an ISPF command, for example TSO DOSTUFF, that is not fully qualified, such as EX 'MYPROJ.MYREXX(DOSTUFF)', add the programs or executable files to the ISPF concatenation in the ISPF.conf file. In the ISPF.conf file, make load module data sets available in the ISPLLIB concatenation, and make executable files available in the SYSPROC or SYSEXEC concatenations. For example:

Running interpretive deployment modules

If you want to add your own deployment processes or functions, you can run interpretive versions of the deployment modules. The deployment component runs the following programs:
Table 2. Programs run by the deployment component. This table describes the programs that are run during deployment and what those programs do.
Program Function Description
BLZPKGZP Deployment packaging Using the manifest file create a .zip file of the specified contents.
BLZBKPZP Deployment backup Using the package file, make backup copies of the modules the deployment overwrites.
BLZDEPZP Deployment Using the deployment manifest file, deploy the contents of the specified .zip file.
The Engineering Workflow Management deployment tasks call these programs to perform the described function. If you want to modify these programs you can do so by modifying the supplied samples that are in library hlq.SBLZSAMP and then point to the modified version in the ISPF.conf. So if you make the modifications directly in hlq.SBLZSAMP your ISPF.conf allocations are similar to this example:
ISPF checks the ISPLLIB concatenation first unless the command has percent symbol % prefix; therefore, you must rename or remove the modules you changed from the hlq.SBLZLOAD data set.

Adding your own EXEC libraries to ISPF gateway configuration file

For Enterprise Extensions builds, if you use the ISPF call method, you must also add your own library of executable files to the SYSEXEC or SYSPROC concatenations in the ISPF.conf. If you specified an executable file name or specified a SELECT CMD(executable file), then ISPF requires access to the required executable file in the appropriate concatenation. You must modify the ISPF.conf to include any required executable file libraries, for example:

For more information about the ISPF gateway, see the chapter titled, TSO/ISPF client gateway in ISPF Planning and Customizing in ISPF Planning and Customizing (GC19-3623).

Running the ISPF Gateway with multi-threaded dependency builds

If the ISPF gateway is going to be run as part of a build that utilizes multiple processes for compilation activities there may be some issues with enqueues on ISPTLIB. This is an issue that is documented in section Protecting table resources in z/OS V2R2 ISPF Dialog Developer's Guide and Reference. Normally with JCL, to stop these enqueues occurring, a temporary data set is allocated as the first data set in the ISPTLIB allocation so that the enqueue is made on the first data set, and that first data set is unique to the JCL being run.

The same issue can occur when running the ISPF Gateway processes in a multi-threaded build mode, or if concurrent builds are run using build agents running with the same user credentials. In order to get around this issue, it is necessary to reallocate ISPTLIB so that the first data set allocated is a unique temporary data set. To do this the ISPF Gateway provides a mechanism to call your own exec to perform other additional allocations. In the ISPF.conf file discussed previously, there is a commented out directive:
*allocjob = HLQ.test.exec(alocsamp)

Direct the allocjob to a physical exec data that contains a REXX exec to do the allocations. The following example REXX can be used to allocate a new temporary data set and concatenate it in front of your existing ISPTLIB concatenation. In additional see member ISPZISP2 in the Supplied ISPF samples data set, by default ISP.SISPSAMP, for other examples of using this exec.

To ensure uniqueness in the temporary data set name, you need to use the TEMPDSFORMAT(UNIQUE) system option in the ALLOCxx member in PARMLIB. Otherwise, the generated temporary data set name may not be unique. To check what options are in effect, use the DALLOC,OPTION operator command.

         /* This is a sample test exec job for the "TSO/ISPF Client Gateway"      */
         /*  may be invoked by ISPF.conf for additional ISPF dataset              */
         /*  concatentations.                                                     */
         /*  Customize accordingly if required.                                   */
         /*                                                                       */
             parse arg $args
             parse var $args USERID
             say '*************************************** '
             say 'Running allocation job'
             say 'USERID = 'USERID
             say '*************************************** '

          /* Work out current allocation using LISTA */
             x = outtrap('out.','*','concat')
             "lista status sysnames"
             lc = rc
             x = outtrap('off')

          /* Specify DDNAMES you need to reallocate  */
             DDS = 'ISPTLIB'
             DD# = O
             DSN. = ''

             I = 2
             Do While I <= OUT.0                                         /* @01c */                                  
              If Substr (OUT.I,1,1) = ' ' Then
                Parse var OUT.I DDN . 12 DISP
                If DDN = ' ' Then
                  DSN.DD# = DSN.DD# "'"DSN"'"
                  DD# = Wordpos(DDN,DDS)
                  DSN.DD# = "'"DSN"'"
                Parse var OUT.I DSN .

              I = I +1

             "FREE FILE(ISPTLIB)"

             Call BPXWDYN ("alloc FI(ISPTLIB) cyl space(1,1) RTDSN(DSN)"||,
                           " blksize(27920) lrecl(80) dsorg(po) recfm(f,b) dir(1) new")
             Do i = 1 to Words(DSN.1)
               Call BPXWDYN("alloc FI(TMP00001) dsn("Word(DSN.1,i)") shr")
               Call BPXWDYN("concat ddlist(ISPTLIB,TMP00001)")

             Say 'ISPTLIB : Reallocated with following concatenation -'
             LISTA ST SY HI


In addition, when running in multi-threaded mode, several temporary ISPF data sets need to be created. The unique identifier that the ISPF Gateway generates is not unique enough when running in multi-threaded mode. However, some changes can be made to create a unique prefix that ISPF can use. In ISPZXENV, instead of setting the CGI_ISPPREF environment variable to &SYSPREF..ISPF.VCMISPF, a prefix can be generated. It is based on the PID (Process Identifier) of the ISPF Gateway process that is running. Add the following code to replace the setting of CGI_ISPPREF.

Note: If you do not already have a tailored copy of ISPZXENV, see the section above, ISPF gateway environment file: ISPZXENV for instructions on how to create one.

/* Running multithreaded we get issues with ISPF.VCMISPF not being unique */  
/* Use a hex representation of the PID to uniquelly create ISPF.VCMISPF   */  
address syscall 'getpid' ; pid = retval                                       
Say 'Pid:'pid                                                                 
If Length(Pid) > 7 Then                                                       
  CGI_ISPPREF = '&SYSPREF..P$'D2X(Substr(pid,1,5))||,                         
  CGI_ISPPREF = '&SYSPREF..P'D2X(pid)                                         

Starting the ISPF gateway from a USS command

If you need to add a build or promotion definition pre-build or post-build command, and that command requires TSO or ISPF services, start the ISPF gateway from the USS command. The BLZGTWY member in hlq.SBLZSAMP is a sample executable file for starting the ISPF gateway. You can run this executable file from USS command invocation points or from an XML file containing Ant macros. Using the instructions contained in the BLZGTWY member, you might need to customize the /tmp directory specification and the PATH variable to point to where you installed the ISPF gateway code.

The sample executable file BLZGTWY accepts the following parameters:
Invocation method, either TSO or ISPF. The TSO method only allocates SYSPROC and SYSEXEC from the ISPF.conf file. The ISPF method allocates all the ISPF concatenation from the ISPF.conf file.
Name of the executable file to run.
Optional. Specifying LOG=YES writes the full ISPF gateway log, which is useful for debugging problems.

Starting the ISPF gateway from pre- or post-build and pre- or post-promotion commands

To run your own executable file from a pre- or post-build and pre- or post-promotion command, you must call the BLZGTWY executable file and pass your own executable file as a parameter. BLZGTWY starts the ISPF gateway by passing your executable file to be run in a full ISPF environment. In the following examples, BLZGTWY is located in the supplied SBLZSAMP library. The following example shows how to start the BLZGTWY executable file in a post-build command:
Starting the ISPF gateway with a build command
The following example shows how to start the TSO time function with a USS command:
Starting the TSO time function with a USS command

Starting the ISPF gateway from pre- or post-deployment commands

The running of executable files from deployment differs from build and promotion in that it starts the ISPF gateway directly by using the shell command. The executable files passed through the pre- and post-deployment commands must be in a certain format. This is true for all of the deployment commands:
  • Load pre-command
  • Load post-command
  • Deploy pre-command
  • Deploy post-command
  • Rollback pre-command
  • Rollback post-command
The following rules apply when calling deployment commands:
  • The command to be run must exist in a library that is allocated to SYSPROC, SYSEXEC, or ISPLLIB in the ISPF.conf that deployment uses.
  • You can pass up to 10 parameters to the command being called.
  • You cannot use double quotation marks in the command.
  • Single quotes in the original command are removed.
  • The parameters are enclosed in double quotation marks by the
  • The REXX executable file must strip the double quotation marks that are passed through in the arguments.
The following example shows how to run executable files from a post-deployment command:
Running executable files from a post-deployment command
The following example shows how the REXX executable file must parse the argument passed to it:
/* REXX */ 
  Arg Parms 
  Parse var Parms '"'Parm1'" "'Parm2'" "'Parm3'"' .         
The example code accepts three parameters, and the final period (.) discards from the script the rest of the double quotation marks passed.

Starting the ISPF gateway from a build.xml Ant script

Another method for using BLZGTWY is to call the ISPF gateway directly from Ant for Enterprise Extensions xml scripts. For example,you can create a build.xml file to build your zComponent projects. The following example shows how to create an Ant xml target using BLZGTWY to run another REXX executable file:
 <!-- Macro definition for ZIP command -->
   <macrodef name="zipISPF">
       <exec executable="tso" failonerror="true">
         <arg line="&quot;EXEC 'MYHLQ.SBLZSAMP(BLZGTWY)' 'TSO EX MYHLQ.EXEC(ZIPEXEC) parm1 parm2 parm3'&quot;"/>

 <!-- ZIP -->
 <target name="zip" description="zip ISPF">
   <startBuildActivity label="zip ISPF">

Starting the ISPF gateway from TSO for testing purposes

The following example starts the ZIPEXEC file through the ISPF gateway and passes three parameters. You can test the ISPF gateway invocation from ISPF option 6. For example, to run the TESTEXEC executable file through the ISPF gateway with logging turned on, use the following command:
To run the TSO TIME command through the ISPF gateway, use one of the following commands:
The TSO or ISPF parameters that are passed indicate to the ISPF gateway what to allocate, which is either the required TSO allocations or the full ISPF allocations.

Troubleshooting the ISPF gateway configuration

Verify that the ISPF gateway is properly configured. Any user IDs that run Engineering Workflow Management functions that use the ISPF gateway must have the required permissions that are described in ISPF Planning and Customizing (GC19-3623).

The Engineering Workflow Management script uses UNIX System Services commands that need access to the /tmp directory. The build user ID that starts the script must have access to the /tmp directory. You can override the use of /tmp as the temporary directory by adding the following line to /etc/jazz701/ccm/
export TMPDIR=/yourTemporaryDir
where yourTemporaryDir is a directory with write access for build users.