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

With IBM® Engineering Workflow Management, 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 Legacy ISPF gateway to support build, deployment, and promotion components that are available with a Developer for IBM Enterprise Platforms client access license.

The Interactive ISPF gateway can be used for Enterprise Extensions build translators only. For more information, see Configuring the Interactive ISPF gateway for Enterprise Extensions build support.

The following explanations describe how to use the Legacy ISPF gateway for build, deployment, and promotion.

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 Legacy ISPF gateway supplied scripts and components. The default settings and procedure for modifying the defaults are described later.

Programs or executable files can be run by using the ISPF gateway or a UNIX System Services command. z/OS UNIX System Services 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 z/OS UNIX System Services. For more information, see Starting the Legacy ISPF gateway from a z/OS UNIX System Services command.

The following components are included with the Legacy ISPF gateway:

Legacy 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:

STEPLIB

By default is set to STEPLIB = 'ISP.SISPLPA:ISP.SISPLOAD'

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.

CGI_ISPCONF

By default is set to CGI_ISPCONF = '/etc/ispf'

CGI_ISPWORK

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 Startispf.sh, which is described later, to read that location before the default ISPF bin path.

For example:

export PATH=/etc/ispf:$PATH  

In the Legacy 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) at http://publibfp.boulder.ibm.com/epubs/pdf/isp2pc00.pdf.

Legacy ISPF gateway startup script: startispf.sh

Shell script to start the Legacy 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 in /usr/lpp/jazz/v7.0.3/buildsystem/buildtoolkit/examples/ispfgateway. As part of standard customization, this script is copied to the Engineering Workflow Management configuration directory, typically /etc/jazz703/ccm by the BLZCPBTK job. Depending on your setup, you might need to modify this shell script to set some environment variables.

PATH

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 startispf.sh 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 startispf.sh script, set the PATH variable to point to the appropriate copy of the ISPF.conf file. Then, use the startispf.sh script that corresponds to the environment needed for a particular project.

Enterprise Extensions build startup script: startbfa.sh

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 startbfa.sh, 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 startbfa.sh 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 team.enterprise.build.ant.myISPFBinPath 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.

Legacy 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:

sysproc=ISP.SISPCLIB 
sysexec=ISP.SISPEXEC 
ispmlib=ISP.SISPMENU 
isptlib=ISP.SISPTENU 
ispplib=ISP.SISPPENU
ispslib=ISP.SISPSLIB 
ispllib=ISP.SISPLOAD

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:

sysproc=ISP.SISPCLIB 
sysexec=ISP.SISPEXEC 
ispmlib=BLZ.SBLZMENU,ISP.SISPMENU 
isptlib=ISP.SISPTENU 
ispplib=ISP.SISPPENU
ispslib=ISP.SISPSLIB 
ispllib=BLZ.SBLZLOAD,ISP.SISPLOAD

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:

sysproc=ISP.SISPCLIB,MYPROJ.MYCLIST 
sysexec=ISP.SISPEXEC,MYPROJ.MYREXX 
ispmlib=BLZ.SBLZMENU,ISP.SISPMENU 
isptlib=ISP.SISPTENU 
ispplib=ISP.SISPPENU
ispslib=ISP.SISPSLIB 
ispllib=BLZ.SBLZLOAD,ISP.SISPLOAD,MYPROJ.LOAD

Note: The ISPF.conf allocations are made only when the call method to run a command is ISPF, and not TSO. This also applies to the allocjob that can be run to provide additional user allocations. The provided allocjob will not be invoked if the call method is TSO.

sysproc=ISP.SISPCLIB,BLZ.SBLZSAMP 
sysexec=ISP.SISPEXEC 
ispmlib=BLZ.SBLZMENU,ISP.SISPMENU 
isptlib=ISP.SISPTENU 
ispplib=ISP.SISPPENU
ispslib=ISP.SISPSLIB 
ispllib=BLZ.SBLZLOAD,ISP.SISPLOAD

sysproc=ISP.SISPCLIB 
sysexec=ISP.SISPEXEC,MY.PROJECT.EXEC 
ispmlib=BLZ.SBLZMENU,ISP.SISPMENU 
isptlib=ISP.SISPTENU 
ispplib=ISP.SISPPENU
ispslib=ISP.SISPSLIB 
ispllib=BLZ.SBLZLOAD,ISP.SISPLOAD

*allocjob = HLQ.test.exec(alocsamp)

         /*REXX*/
         /*************************************************************************/
         /* 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
              Do
                Parse var OUT.I DDN . 12 DISP
                If DDN = ' ' Then
                  DSN.DD# = DSN.DD# "'"DSN"'"
                Else
                Do
                  DD# = Wordpos(DDN,DDS)
                  DSN.DD# = "'"DSN"'"
                End
              End
              Else
                Parse var OUT.I DSN .

              I = I +1

             End
             
             "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)")
             End

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

          Exit

/* 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                                                       
Do                                                                            
  CGI_ISPPREF = '&SYSPREF..P$'D2X(Substr(pid,1,5))||,                         
                         '.P$'D2X(Substr(pid,6))                              
End                                                                           
Else                                                                          
  CGI_ISPPREF = '&SYSPREF..P'D2X(pid)                                         

Starting the Legacy ISPF gateway from a z/OS UNIX System Services 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 Legacy ISPF gateway from the z/OS UNIX System Services command. The BLZGTWY member in hlq.SBLZSAMP is a sample executable file for starting the ISPF gateway. You can run this executable file from z/OS UNIX System Services 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:

Method

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.

Exec

Name of the executable file to run.

Log

Optional. Specifying LOG=YES writes the full ISPF gateway log, which is useful for debugging problems.

Starting the Legacy 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:

The following example shows how to start the TSO time function with a z/OS UNIX System Services command:

Starting the Legacy 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 startispf.sh 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 startispf.sh.
• 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:

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 startispf.sh script the rest of the double quotation marks passed.

Starting the Legacy 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">
     <sequential>
       <exec executable="tso" failonerror="true">
         <arg line="&quot;EXEC 'MYHLQ.SBLZSAMP(BLZGTWY)' 'TSO EX MYHLQ.EXEC(ZIPEXEC) parm1 parm2 parm3'&quot;"/>
       </exec>
     </sequential>
   </macrodef>

 <!-- ZIP -->
 <target name="zip" description="zip ISPF">
   <startBuildActivity label="zip ISPF">
    autoComplete="true"
    buildResultUUID="${buildResultUUID}"
    repositoryAddress="${repositoryAddress}"
    userId="${userId}"
    passwordFile="${passwordFile}"/>
  <zipISPF/>
 </target>

Starting the Legacy 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:

EXEC 'MYHLQ.SBLZSAMP(BLZGTWY)' 'ISPF EX MYHLQ.EXEC(TESTEXEC) LOG=YES'

To run the TSO TIME command through the ISPF gateway, use one of the following commands:

EXEC 'MYHLQ.SBLZSAMP(BLZGTWY)' 'TSO TIME'

or

EXEC 'MYHLQ.SBLZSAMP(BLZGTWY)' 'ISPF TIME'

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.

export TMPDIR=/yourTemporaryDir