Co:Z Toolkit User's Guide

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 -sr`
// 
    

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

We are running on:  Linux 2.6.15-27-k7
      

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.

In this example the Co:Z Launcher is used to offload processing of z/OS SMF data to a Linux system.

//USERC4  JOB (),'DOVETAIL',MSGCLASS=H,NOTIFY=&SYSUID 
//PROCLIB JCLLIB ORDER='USER.COZ.SAMPJCL' 
//* 
//*********************************************************************
//* 
//* This Co:Z example dumps SMF records to a temporary dataset then
//* remotely processes the records.  The sample program smfp.c 
//* reports statistics on the number and types of SMF records
//* processed.  It can easily be modified to perform other processing,
//* or replaced by a SAS program.
//* 
//* Tailor the proc and job for your installation: 
//* 1.) Modify the Job card per your installation's requirements 
//* 2.) Modify the PROCLIB card to point to this PDS, or wherever 
//*     the COZPROC procedure has been installed. 
//* 3.) Modify the SMF dataset names for your installation.
//* 4.) Compile the remote SMF processing program "smfp.c" on the 
//*     target system:
//*         gcc -o smfp smfp.c.  
//*     Ensure that the executable (smfc) is in the path.
//*
//* When executed, smfp will write a report to stdout similar to the
//* following:
//*
//*                         ------ Length ------
//*Type    Count     Pct    Min     Max      Avg
//*   2        1       0     14      14       14
//*   3        1       0     14      14       14
//*   4        1       0    291     291      291
//*   5        1       0    142     142      142
//*  20        3       0     87      88       87
//*  30      129       2    394    1337      928
//*  42     6304      97    192   19768      467
//*  80        5       0    351     376      360
//*  89        2       0    362    4018     2190
//* 177        1       0     47      47       47
//*
//*6448 SMF records processed
//*
//*********************************************************************
//*
//DUMPSMF  EXEC PGM=IFASMFDP
//SYSPRINT DD   SYSOUT=*                                          
//SMFDATA  DD   DISP=SHR,DSN=SYS1.SMF.DATA                      
//SMFOUT   DD   SYSOUT=*                                          
//OUTDD    DD   DSN=&&SMFUNLD,DISP=(NEW,PASS),
//         UNIT=SYSDA,SPACE=(CYL,(20,20))                                  
//ADUPRINT DD   SYSOUT=*                                          
//SYSIN    DD   *                                                 
    INDD(SMFDATA,OPTIONS(DUMP))                                   
    OUTDD(OUTDD,TYPE(000:255))                                    
/*                                                                
//RUNCOZ EXEC PROC=COZPROC,ARGS='user@linux1.myco.com'
//SMFUNLD  DD   DSN=&&SMFUNLD,DISP=(OLD,DELETE,DELETE) 
//STDIN    DD   * 
fromdsn -b -l rdw //DD:SMFUNLD | smfp
//