Dovetailed Technologies

3. Examples

This section contains examples of using the Co:Z Batch utility. The RUNSHELL member of the Co:Z Toolkit Sample JCL also contains sample COZBATCH job steps.

  1. Run the user's default shell, which is normally /bin/sh. The shell is run as a "login" shell so that before reading input from STDIN, the shell will have executed /etc/profile and the user's .profile if present. All output: messages, stdout, and stderr will go to a dynamically allocated SYSOUT file.

    //  EXEC PGM=COZBATCH
    //STDIN     DD *
    env
    // 

  2. Run the user's default shell, but this time direct messages, stdout, and stderr to separate DDs.

    //  EXEC PGM=COZBATCH
    //STDIN     DD *
    env
    //SYSOUT    DD SYSOUT=*
    //STDOUT    DD SYSOUT=*
    //STDERR    DD SYSOUT=*
    // 

  3. Run the /bin/sh shell explicity, but not as a login shell. The leading "/" is required to delineate LE runtime options. The output from this execution will display only a few environment variables, since the sytem and user profiles are not executed.

    //  EXEC PGM=COZBATCH,PARM='/ /bin/sh'
    //STDIN     DD *
    env

  4. Run a login shell with tracing of shell commands. Also enable COZBATCH debug-level logging. This example can be very useful for debugging issues with profile and shell scripts.

    //  EXEC PGM=COZBATCH,PARM='/-LD /bin/sh -Lx'
    //STDIN     DD *
    my-cmd arg1 arg2
    ...
    

  5. Run the /bin/cat> program explicity, which will copy the input from STDIN to STDOUT

    //  EXEC PGM=COZBATCH,PARM='//bin/cat'
    //STDIN     DD *
    xxxx
    yyyyy
    zzz
    //STDOUT    DD SYSOUT=*
    //

  6. Use DD STDENV to have LE present environment variables. Additional environment variables are set using PARM=, which allows for the substitution of JCL "SET" or "PROC" variables. Since a program name is not specified, the user's default login shell is executed and will read input from STDIN.

    // SET MACLIB=SYS1.MACLIB
    // SET AMACLIB=SYS1.AMACLIB
    //*
    //   EXEC PGM=COZBATCH,
    //    PARM='/ TDIR=/usr/local/bin MACLIB=&MACLIB AMACLIB=&AMACLIB'
    //STDENV    DD *
    ADIR=foo
    //STDIN     DD *
    echo ls ADIR=$ADIR
    ls $ADIR
    echo ls TDIR=$TDIR
    ls $TDIR
    echo MACLIB=$MACLIB AMACLIB=$AMACLIB
    env
    //

  7. In a situation where you have several JCL SET or PROC variables that need to be used as environment variables, you can be limited by the evil 100-character JCL PARM= limit. COZBATCH allows you to have multiple steps that concatenate these variables to a temp dataset that is eventually passed into a COZBATCH step that uses them in a shell script. The DD name for the file used to save these arguments is SAVEARGS.

    Note that steps that have neither a STDIN DD nor name an explicit program to execute will actually not run anything, but simply set and save arguments.

    // SET PRFX=SYS1.INSTALL.FOOBAR.LONGNAME.DEMO
    // SET MACLIB=&PRFX..MACLIB
    // SET AMACLIB=&PRFX..AMACLIB
    // SET AMODGEN=&PRFX..AMODGEN
    // SET LINKLIB=&PFX..LINKLIB
    //*
    //EX1      EXEC PGM=COZBATCH,PARM='/MACLIB=&MACLIB AMACLIB=&AMACLIB'
    //SAVEARGS DD   DSN=&&MYTEMP1,DISP=(NEW,PASS)
    //*
    //EX2      EXEC PGM=COZBATCH,PARM='/AMACLIB=&AMODGEN'
    //SAVEARGS DD   DSN=&&MYTEMP1,DISP=(OLD,PASS)
    //*
    //EX3      EXEC PGM=COZBATCH,PARM='/LINKLIB=&LINKLIB'
    //SAVEARGS DD   DSN=&&MYTEMP1,DISP=(OLD,PASS) 
    //STDIN    DD   *
    echo MACLIB=$MACLIB
    echo AMACLIB=$AMACLIB
    echo AMODGEN=$AMODGEN
    echo LINKLIB=$LINKLIB
    //*

  8. The special PARM= variable $? maybe be used to specify a return code for the step, overriding the use of the program or shell's exit code. In the special case where a program or STDIN DD is not present, a program or shell is not executed - but this feature will still set the return code.

    // SET MYRC=8
    //SETRC1 EXEC PGM=COZBATCH,PARM='/ $?=&MYRC'
    //*
    //SETRC2 EXEC PGM=COZBATCH,PARM='/ FOO=BAR $?=&MYRC'
    //STDIN     DD   *
    env
    // 

  9. Unlike BPXBATCH or BPXBATSL, arguments specified to the program on the PARM= keyword may be quoted.

    //  EXEC PGM=COZBATCH,
    //    PARM='/"TDIR=&TDIR" "FIL=&FIL" /bin/sh -c "cd $TDIR; pax -rvf $FIL"' 

  10. Since COZBATCH executes a shell in the original address space, it is easy to write shell scripts inline in your JCL that use DD statements. The synergy of features allows you to fully and easily exploit z/OS Unix in batch job steps.

    // SET TCHOME="/usr/local/tomcat"
    // SET INSTJCL=TOMCAT.INSTALL.JCL
    //*
    //INSTALL EXEC PGM=COZBATCH,PARM='/TCHOME=&TCHOME'
    //PAX     DD   DSN=&INSTJCL(PAXBIN),DISP=SHR
    //STDIN DD *
    cd $TCHOME
    if [[ $(ls | wc -l) -gt 0 ]]; then
      echo directory $TCHOME is not empty!
      exit 8
    fi
    pax -rvf //DD:PAX
    //

  11. COZBATCH can be used with the Co:Z toolkit fromdsn and todsn shell commands. For additional information see the Dataset Pipes Command Reference.

    //REGEX   EXEC PGM=COZBATCH
    //IN      DD   DSN=SYS1.MACLIB(ACB),DISP=SHR
    //OUT     DD   DSN=&&TEMP,DISP=(NEW,PASS),
    //             SPACE=(CYL,(1,1)),
    //             DCB=(LRECL=80,RECFM=FB)
    //STDIN   DD   *
    # Copy lines matching a regular expression to DD:OUT
    fromdsn //DD:IN | grep BLKSIZE | todsn //DD:OUT
    //

  12. COZBATCH can be used with Co:Z SFTP to script a batch SFTP client job to download a file to a z/OS dataset. In order to use this example, additional configuration is required for the SFTPPROC and shell script variables. Refer to Using the Co:Z SFTP client in batch in the Co:Z SFTP User's Guide for best practices as well as more examples.

    //PROCLIB JCLLIB ORDER='COZUSER.COZ.SAMPJCL'
    //* 
    //*********************************************************************
    //* Use the sftp_get.sh script to retrieve a remote file to a local
    //* dataset. 
    //*********************************************************************
    //SFTPGET EXEC PROC=SFTPPROC 
    //SFTPIN DD * 
    cert="MY-RING:RSA-CERT" 
    user=myuser
    host=myhost 
    lzopts="mode=text" 
    lfile=//DD:MYDD 
    rfile=/etc/profile 
                                                                
    . $script_dir/sftp_get.sh 
    
    //MYDD  DD DSN=COZUSER.SFTPGET.DATA,DISP=(MOD,KEEP), 
    //        DCB=(LRECL=80,RECFM=FB),SPACE=(CYL,(3,1)) 
    //* 
    

  13. With z/OS 2.1 or later, COZBATCH automatically exports all JES symbols as environment variables to the target shell or program.

    // EXPORT SYMLIST=(MYDSN,MYVOL)
    // SET MYDSN=MYID.SOME.DSN
    // SET MYVOL=SYS001
    //*
    //SYMEX EXEC PGM=COZBATCH
    //STDIN DD *
    env | grep "JES_"
    //* 
    

    The above job will display environment variables something like:

    JES_SYS_CORR_CURRJOB=S0000434DTLZOS01CC27C5EA.......:
    JES_MYDSN=MYID.SOME.DSN
    JES_MYVOL=SYS001
    

    See also the jessym command which can be used to work with JES symbols from within a z/OS Unix shell.

  14. With Co:Z Toolkit for z/OS release 4.0 and later, COZBATCH can be used with z/OS OpenSSH to script an ssh client job. In order to use this example, additional configuration is required for the SSHPROC and shell script variables. Refer to the SSHSAMP JCL member found in the sample JCL shipped with the Co:Z Toolkit for configuration instructions as well as more examples

    //PROCLIB JCLLIB ORDER='COZUSER.COZ.SAMPJCL'
    //*********************************************************************
    //* Use the ssh_pubkey.sh script to connect to a remote system 
    //* and append a public key to a user's authorized_keys file.
    //* See that script for details and additional variables that can be
    //* set for more customization.  This example uses a password
    //* (via SSH_ASKPASS) for authentication.
    //*********************************************************************
    //SSHKEY EXEC PROC=SSHPROC 
    //SSHIN DD * 
    pwdsn="HLQ.COZ.SAMPJCL(PASS)" 
    user=myuser 
    host=myhost
    pubkey="/zos/home/user/.ssh/id_rsa.pub" 
                                                  
     . $script_dir/ssh_pubkey.sh 
    //* 
    

Copyright© 2009-2017 Dovetailed Technologies, LLC. All rights reserved.
Co:Z® is a registered trademark of Dovetailed Technologies, LLC.