This is a simple example of how to use the Co:Z Launcher to run commands on a remote Linux server.

//COZCB1  JOB (),'COZ'
//STEP1   EXEC PROC=COZPROC,
//        ARGS='myuid@linux1.myco.com'
//STDIN   DD *                        
# This is input to the remote shell
echo "We are running on: " `uname`
// 
    

In this example, the following output will be written to the //STDOUT DD:

We are running on:  Linux
      

The exit code from the remote program (bash) will be adopted as the return code for the batch job step; in this case: "0". Log messages from the Co:Z Toolkit are written to //SYSOUT DD:

fromdsn(DD:STDIN)[N]: 2 records/160 bytes read; 75 bytes written in 0 milliseconds.       
todsn(DD:STDERR)[N]: 0 bytes read; 0 records/0 bytes written in 0.072 seconds (0.000 Bytes/Sec
todsn(DD:STDOUT)[N]: 39 bytes read; 1 records/38 bytes written in 0.074 seconds (527.027 Bytes
CoZLauncher[N]: myuid@linux1.myco.com target command '<default shell>' ended with RC=0       
      

In this example we use the Co:Z Launcher to send commands to a target Linux server which reads a PDS member from the launching z/OS system.

//COZCB2  JOB (),'COZ' 
//STEP1   EXEC PROC=COZPROC, 
//        ARGS='myuid@linux1.myco.com' 
//STDIN   DD * 
fromdsn '//sys1.maclib(acb)' | grep BLKSIZE 
// 
    

In this example, the following output will be written to the //STDOUT DD:

&BLKSIZE=0,&LRECL=0,&BUFSP=0,                           -00001600
BLKSIZE=&BLKSIZE,LRECL=&LRECL,                          -01700000
BLKSIZE=&BLKSIZE,LRECL=&LRECL,                          -02406800
      

In this example we use the Co:Z Launcher to send commands to a Linux server which reads data from an //INPUT DD in the launching job step and writes PGP encrypted output data to //OUTPUT DD.

  
//COZCB3  JOB (),'COZ' 
//STEP1   EXEC PROC=COZPROC, 
//        ARGS='myuid@linux1.myco.com' 
//STDIN   DD * 
fromdsn -l rdw -k //DD:INPUT   \ 
  | gpg -r key-1 --batch --output=- --encrypt=- \ 
  | todsn -b //DD:OUTPUT 
/* 
//INPUT DD DISP=SHR,DSN=KIRK.CLEARTEXT.DATA 
//OUTPUT DD DSN=KIRK.ENCRYPT,DISP=(NEW,PASS), 
//          SPACE=(CYL,(1,1),RLSE), 
//          DCB=(RECFM=U,BLKSIZE=4096) 
    

In this example, the following log message will be written:

fromdsn(DD:STDIN)[N]: 3 records/240 bytes read; 106 bytes written in 0 milliseconds.                       
fromdsn(DD:INPUT)[N]: 78 records/6240 bytes read; 6552 bytes written in 0 milliseconds.                    
todsn(DD:OUTPUT)[N]: 2034 bytes read; 2 records/2034 bytes written in 0.038 seconds (52.272 KByt
todsn(DD:STDOUT)[N]: 0 bytes read; 0 records/0 bytes written in 0.708 seconds (0.000 Bytes/sec).           
todsn(DD:STDERR)[N]: 0 bytes read; 0 records/0 bytes written in 0.706 seconds (0.000 Bytes/sec).           
CoZLauncher[N]: myuid@linux1.myco.com target command '<default shell>' ended with RC=0
      

Note that the data is encrypted during transfer automatically by the SSH tunnel used by Co:Z to communicate between the target server and the launching batch job. Also note that the file is never stored on disk on the target server.

Decrypting is just as easy:

fromdsn -b  //DD:INPUT   \
 | gpg -r key-1 --batch --output=- --decrypt=- \
 | todsn -l rdw  //DD:OUTPUT 
      

In this example the Co:Z Launcher is used to run a script on a server which downloads a tab-delimited file from the Internet and converts selected fields to SQL statements which are written to a temporary MVS dataset. A second step in the job runs the DB2 batch SPUFI utility to load the data to a DB2 table.

//COZCB4  JOB (),'COZ'
//********************************************************************** 
//* STEP1: Launch a remote script to ftp download a tab-delimited 
//* text file.  Use selected columns to generate DB2 INSERT statments 
//* which are written to an MVS temporary dataset. 
//* 
//STEP1   EXEC PROC=COZPROC,ARGS='cozcb4@dmz1.myco.com' 
//STDIN   DD * 
wget -O- ftp://ftp.visi.com/users/juan/ContactingCongress.db.txt | 
awk -F "\t" -v sq="'" '{ 
  if (NR == 1)  #skip header/empty table 
    print "DELETE FROM CONGRESS;" 
  else { 
    print "INSERT INTO CONGRESS VALUES(" 
    print sq $1 sq ", " 
    print sq $2 sq ", " 
    print sq $4 sq ", " 
    print sq $5 sq ", " 
    print sq $3 sq 
    print ");" 
  } 
'} 
//STDOUT DD DSN=&&SPUFIN,DISP=(NEW,PASS),SPACE=(CYL,(2,1)), 
//       DCB=(RECFM=FB,LRECL=80) 
//********************************************************************** 
/* STEP2: Run DB2 "SPUFI" in batch to execute the insert statements 
/* to reload a DB2 table 
/* 
//STEP2    EXEC PGM=IKJEFT01,DYNAMNBR=20,COND=(0,NE) 
//SYSTSPRT DD SYSOUT=* 
//SYSPRINT DD SYSOUT=* 
//SYSTSIN  DD * 
DSN SYSTEM(DBS1) 
RUN PROGRAM(DSNTEP2) PLAN(DSNTEP71) LIB('DB2V810.RUNLIB.LOAD') 
END 
//SYSIN    DD DSN=&&SPUFIN,DISP=(OLD,DELETE) 
// 
    

In environments where the z/OS mainframe is not connected to the Internet, the target server may be deployed in a DMZ which is only accessible in one direction from the z/OS host using SSH. Only the target process started by the Co:Z launcher (and its children) have access to redirected I/O resources in the launching Co:Z job step.

This example also demonstrates how open source Linux tools (wget, awk) may be used to access and transform data for use within the z/OS environment.