An enhanced sftp client (cozsftp) for z/OS is also included in the Co:Z toolkit. This client can be used to initiate transfers with a remote host and supports the same set of file transfer options as the Co:Z SFTP server. The cozsftp command is installed in the $COZ_HOME/bin directory.
$ export PATH=/opt/dovetail/coz/bin:$PATH 
$ cozsftp user@host
Co:Z sftp version: 1.1.0 (5.0p1) 2008-10-20
Copyright (C) Dovetailed Technologies, LLC. 2008. All rights reserved.
Connecting to host...
user@host's password: *****
cozsftp>OpenSSH SFTP logging is enabled by setting the -v option on the command line. The logging level can be raised by increasing the
number of v options from -v to -vvv. Additionally, the COZ_LOG environment variable
can be used to set logging options for the Co:Z extension library used to add z/OS support to the
cozsftp command. The default setting for COZ_LOG is I.
To change this default for all users, modify /etc/ssh/cozsftp_client.rc as needed. Individual users can override this setting by exporting COZ_LOG on the
command line or in the copy of cozsftp_client.rc in their individual .ssh directory.
Client logging information is sent to stderr. In order to capture logging information in a file, use the following:
$ export COZ_LOG=D; cozsftp -vvv user@hostname 2>&1 | tee ~/cozsftp-output.log
The Co:Z client loglevel can also be set using the lzopts command described in the next section.
See Section B.2, “Miscellaneous options” for additional information.
For information on setting these logging options in batch, see the section called “Logging in batch”.
The enhanced client introduces two new commands:
lzopts [-a] [option=value,...]
The lzopts command is used to set local (client) file transfer options. These options are set prior to initiating file/dataset transfers from z/OS to a remote host.
zopts [-a] [option=value,...]
The zopts command is used to set server file transfer options -- if the server is a Co:Z SFTP server. The zopts command is functionally equivalent to the ls /+<option_list> command used by existing clients to set Co:Z sftp-server file transfer options.
Multiple options can be set by separating the option=value pairs with commas. An error is returned if one or more of the options was incorrectly specified, but the remaining options are set as requested.
The active options and their settings can be displayed by issuing the commands without
arguments. The -a option can be specified to list all
available options, even those that are not active.
The client performs some shell-like processing of its commands. In general, this is not an issue for the setting of options, but if the supplied option value contains a hash symbol (#), the option=value pair must be quoted, either with single or double quotes. For example:
cozsftp> lzopts "dataclas=#MYCLASS"
![[Note]](images/note.gif) | Note |
|---|---|
For compatibility with z/OS OpenSSH SFTP, the cozsftp command
recognizes the following additional subcommands:
ascii and binary. these subcommands are treated as synonyms for
|
Client session options are determined in the following priority order:
The
fixed:section of/etc/ssh/cozsftp_config(highest priority and non-modifiable)The first matching pattern (if any) from
$HOME/.ssh/cozsftp_configThe first matching pattern (if any) from
/etc/ssh/cozsftp_configPrevious interactive commands:
lzopts(described below) in the same sessionThe environment variable
SFTP_ZOS_OPTIONSThe
default:section of/etc/ssh/cozsftp_config(lowest priority)
For a list of available options, see Appendix B, Co:Z SFTP options.
For a description of the cozsftp_config file format, including
how to specify file name patterns, see Appendix C, Session config files.
cozsftp> lzopts mode=textclientcp=IBM-1047 loglevel=I mode=text servercp=IBM-1047
cozsftp> lzopts lrecl=80,recfm=fb,space=trk.3.2
lrecl=80,recfm=fb,space=trk.3.2cozsftp> lzopts -a
clientcp=IBM-1047 linerule=flexible loglevel=I lrecl=80
mode=text overflow=wrap recfm=fb servercp=IBM-1047
space=trk.3.2 NOallowmount NOblksize NObufno
NOcopies NOdataclas NOdest NOdir
NOdisp NOdsorg NOforms NOgdgnt
NOhold NOlabel NOlike NOmaxvol
NOmgmtclas NOnorecall NOoutdes NOrelease
NOretpd NOsequence NOshowall NOspin
NOstorclas NOsysout NOtrim NOtrtch
NOucount NOunit NOvol NOwriterThe enhanced Co:Z SFTP client can connect to any sftp server, including a Co:Z SFTP server. In this case, there are two sets of transfer options in effect; the enhanced client's and the server's. Client side (local) options are controlled via the lzopts command. Server side (remote) options are controlled via the zopts command.
When transferring POSIX files between a z/OS server and z/OS client, using
the default mode=binary transfer option both locally and remotely
will usually yield the desired results. If codepage translations need to take place,
the desired clientcp, servercp and mode=text
can be set either locally (via lzopts command) or remotely
(via the zopts command). The other side can be left in
mode=binary.
When transferring datasets between a z/OS server and z/OS client, it is generally
recommended that linerule=rdw be used for binary transfers so that
record mode boundaries are preserved.
Starting with Co:Z SFTP version 5.5.0, new dsput and dsget commands may be used to transfer z/OS datasets and automatically set local and remote transfer options so that new target dataset are allocated with attributes matching the source dataset. See the section called “Transferring Datasets Between Co:Z Systems” for details on these commands.
When converting from dataset to POSIX file between a z/OS server and z/OS client, the transfer options should be set where the dataset resides.
The Co:Z implementation of sftp accepts two prefix strings to identify
MVS datasets as absolute paths. The first (//) is consistent
with IBM's common usage. A secondary form (/-/) is also available.
The sftp lcd command can be used to navigate around the
z/OS dataset space. Using the dataset prefix // or
/-/, the dataset space can be entered. Once there, traversal
up and down various dataset levels can be performed similarly to hierarchical
file systems.
Partitioned datasets are treated as directories as well. Once a PDS is made the current working directory, its members can be listed and retrieved like normal files.
Just as listing the entire catalog from the root is not allowed, it is not possible to make the catalog root the current working directory. As such, the command lcd // will fail.
cozsftp> lcd //usercozsftp> lpwd Local working directory: //USER.COZ.TESTJCL cozsftp> lcd ..
cozsftp> lpwd Local working directory: //USER.COZ
The get and put commands are used to
transfer datasets and PDS members.
Any options previously set via the lzopts are in effect for any given transfer.
$ cozsftp user@linux.com
cozsftp> lzopts
PDS members can be transferred between Co:Z z/OS systems using the get and put command, but the target PDS must already exist. The following examples show how to transfer an individual member or all members of the source PDS. NOTE: Starting with Co:Z version 5.5.0, two new commands dsget and dsput were introduced to make it easier to transfer data sets between two z/OS systems running Co:Z. See the section called “Transferring Datasets Between Co:Z Systems”. Note that dsget and dsput can be used to transfer program objects between z/OS systems, something that is not supported with the standard get and put commands.
cozsftp> put //COZUSER.SRC.PDS(MYJCL) //COZUSER.TGT.PDS(MYJCL)
In release 2.4.0, support was added to allow multiple files to be downloaded to new generations of a GDG.
cozsftp> lzopts gdgnt
cozsftp> lpwd Local working directory: //USER.COZ.TESTJCL cozsftp> put ONETEST /tmp/ONETEST
In release 2.4.0, support was added to allow all generations of a GDG to be uploaded in one put commmand.
cozsftp> ls -alf //coz.test.gdg
Volume Referred Ext Tracks Used Recfm Lrecl BlkSz Dsorg Dsname
GDG COZ.TEST.GDG
VPWRKA 2013/06/04 1 1 1 U 0 6144 PS COZ.TEST.GDG.G0003V00
VPWRKA 2013/06/04 1 1 1 U 0 6144 PS COZ.TEST.GDG.G0004V00
VPWRKC 2013/06/04 1 1 1 U 0 6144 PS COZ.TEST.GDG.G0005V00
VPWRKB 2013/06/04 1 1 1 U 0 6144 PS COZ.TEST.GDG.G0006V00
cozsftp> put //coz.test.gdg(*) /tmp
Uploading //COZ.TEST.GDG.G0003V00 to /tmp/G0003V00
ZosDataset[I]: Opening dataset COZ.TEST.GDG.G0003V00 for read with options: shr
//COZ.TEST.GDG.G0003V00 20% 10KB 10.0KB/s 00:03 ETA
ZosDataset[I]: Closing dataset //COZ.TEST.GDG.G0003V00 - 2 records read, 10248 bytes sent
Uploading //COZ.TEST.GDG.G0004V00 to /tmp/G0004V00
ZosDataset[I]: Opening dataset COZ.TEST.GDG.G0004V00 for read with options: shr
//COZ.TEST.GDG.G0004V00 20% 10KB 10.0KB/s 00:03 ETA
ZosDataset[I]: Closing dataset //COZ.TEST.GDG.G0004V00 - 2 records read, 10248 bytes sent
Uploading //COZ.TEST.GDG.G0005V00 to /tmp/G0005V00
ZosDataset[I]: Opening dataset COZ.TEST.GDG.G0005V00 for read with options: shr
//COZ.TEST.GDG.G0005V00 0% 5 0.0KB/s 2:43:49 ETA
ZosDataset[I]: Closing dataset //COZ.TEST.GDG.G0005V00 - 1 records read, 5 bytes sent
Uploading //COZ.TEST.GDG.G0006V00 to /tmp/G0006V00
ZosDataset[I]: Opening dataset COZ.TEST.GDG.G0006V00 for read with options: shr
//COZ.TEST.GDG.G0006V00 0% 5 0.0KB/s 2:43:49 ETA
ZosDataset[I]: Closing dataset //COZ.TEST.GDG.G0006V00 - 1 records read, 5 bytes sent
Starting with 5.5.0, two z/OS systems running Co:Z can transfer data sets more easily with the new interactive commands dsget and dsput. These commands enable the transfer of datasets without having to specify allocation parameters. These commands can also be used to transfer PDSE program objects, something that is not possible with the standard get and put commands.
This feature was introduced in several phases. In order to use the following features, both the Co:Z SFTP client and server must be at the level (or newer) that introduces the feature:
Version 5.5.0 introduces support for sequential data sets only. The source data set must be a sequential data set. The target data set (if it exists) must be a sequential data set. Relative GDGs are NOT supported.
Version 6.0.0 introduces support for partitioned data sets (both PDS and PDSE). Client DD names are not supported for either the source or target (note that DD names are never supported on the server). The IBM utility IEBCOPY is used to unload the source PDS(E) and to load the target PDS(E). If IEBCOPY completes with a non-zero return code, the dsget/dsput operation will fail and the IEBCOPY error message(s) will be written to the log (either the client or server, depending on where the error occurs). Note that IEBCOPY does not preserve generations for V2 PDSE data sets. Relative GDGs are now supported for sequential data sets.
Version 6.2.0 introduces support for individual members of partitioned data sets (both PDS and PDSE). The source member is specified with the standard member syntax as a suffix to the data set name, enclosed in parentheses. The target data set must be specified without a member name. If the source data set is a PDSE, the member and its aliases are copied. If the source data set is a PDS, only the member is copied.
See cozsftp(1) for the command reference.
Co:Z SFTP version: 5.5.0 (6.4p1) 2019-01-10
Copyright (C) Dovetailed Technologies, LLC. 2008-2019. All rights reserved.
cozsftp> dsput //COZ.TEST.PS //COZ.TEST.PS.COPY
ZosSettings[I]: Transfer options: *linerule=l4,*mode=binary[binary]
ZosDataset[I]: Opening dataset COZ.TEST.PS for read with options: shr
Uploading //COZ.TEST.PS to //COZ.TEST.PS.COPY
//COZ.TEST.PS 100% 1227KB 1.2MB/s 00:00
ZosDataset[I]: Closing dataset //COZ.TEST.PS - 100 records read, 1256400 bytes sent
cozsftp> dsget -d //COZ.TEST.PS.COPY //COZ.TEST.PS
Fetching //COZ.TEST.PS.COPY to //COZ.TEST.PS
ZosSettings[I]: Transfer options: *blksize=25120,*dsorg=PS,*linerule=l4,*lrecl=12560,
*mode=binary[binary],*recfm=FB,*replace=realloc[reuse],
*space=cyl.2.2
ZosDataset[I]: Opening dataset COZ.TEST.PS for write with options:
blksize(25120) dsorg(PS) lrecl(12560) recfm(F,B)
cyl space(2,2) new catalog
//COZ.TEST.PS 100% 1227KB 1.2MB/s 00:00
ZosDataset[I]: Closing dataset //COZ.TEST.PS - 1256400 bytes received, 100 records written
Co:Z SFTP version: 6.0.0 (6.4p1) 2020-02-14 Copyright (C) Dovetailed Technologies, LLC. 2008-2020. All rights reserved. cozsftp> dsput //COZ.LLIB //COZ.LLIB.COPY Uploading //COZ.LLIB to //COZ.LLIB.COPY ZosSettings[I]: Transfer options: gdgnt,*linerule=l4,*mode=binary[binary] ZosDataset[I]: Opening dataset COZ.LLIB for read ZosDataset[I]: Closing dataset //COZ.LLIB - 296 records read, 1145668 bytes sent
Co:Z SFTP version: 6.0.0 (6.4p1) 2020-02-14
Copyright (C) Dovetailed Technologies, LLC. 2008-2020. All rights reserved.
cozsftp> lzopts loglevel=D
loglevel=D
cozsftp> dsget //COZ.SAMPJCL //COZ.SAMPJCL.COPY
Fetching //COZ.SAMPJCL/ to //COZ.SAMPJCL.COPY
ZosSettings[I]: Transfer options: gdgnt,*linerule=l4,*mode=binary[binary]
ZosDataset[I]: Opening dataset COZ.SAMPJCL.COPY for write
ZosDataset[I]: Closing dataset //COZ.SAMPJCL.COPY - 86804 bytes received, 25 records written
Iebcopy[D]: 1 IEBCOPY MESSAGES AND CONTROL STATEMENTS PAGE 1
Iebcopy[D]: -IEB1135I IEBCOPY FMID HDZ2230 SERVICE LEVEL UA92265 DATED 20170618 DFSMS
Iebcopy[D]: IEB1035I GOETZE *OMVSEX 10:33:26 FRI 10 JUL 2020 PARM='WORK=2M'
Iebcopy[D]: -*OMVSEX COPY INDD=SYS00017,OUTDD=SYS00018 GENERATED STATEMENT
Iebcopy[D]: 0IEB1013I COPYING FROM PDSU INDD=SYS00017 VOL= DSN=SYS20192.T103325.RA000
Iebcopy[D]: IEB1014I TO PDS OUTDD=SYS00018 VOL=VPWRKC DSN=COZ.SAMPJCL.COPY
Iebcopy[D]: IEB167I FOLLOWING MEMBER(S) LOADED FROM INPUT DATA SET REFERENCED BY SYS00017
Iebcopy[D]: IEB154I @@README HAS BEEN SUCCESSFULLY LOADED
Iebcopy[D]: IEB154I COZCFGD HAS BEEN SUCCESSFULLY LOADED
Iebcopy[D]: IEB154I COZPROC HAS BEEN SUCCESSFULLY LOADED
Iebcopy[D]: IEB154I DTLSPAWN HAS BEEN SUCCESSFULLY LOADED
Iebcopy[D]: IEB154I GPGDSN HAS BEEN SUCCESSFULLY LOADED
Iebcopy[D]: IEB154I GREPDSN HAS BEEN SUCCESSFULLY LOADED
Iebcopy[D]: IEB154I OFFLDSMF HAS BEEN SUCCESSFULLY LOADED
Iebcopy[D]: IEB154I RACDCERT HAS BEEN SUCCESSFULLY LOADED
Iebcopy[D]: IEB154I RUNLNCH HAS BEEN SUCCESSFULLY LOADED
Iebcopy[D]: IEB154I RUNLNCHK HAS BEEN SUCCESSFULLY LOADED
Iebcopy[D]: IEB154I RUNLNCHP HAS BEEN SUCCESSFULLY LOADED
Iebcopy[D]: IEB154I RUNSFTP HAS BEEN SUCCESSFULLY LOADED
Iebcopy[D]: IEB154I RUNSFTPK HAS BEEN SUCCESSFULLY LOADED
Iebcopy[D]: IEB154I RUNSFTPS HAS BEEN SUCCESSFULLY LOADED
Iebcopy[D]: IEB154I RUNSHELL HAS BEEN SUCCESSFULLY LOADED
Iebcopy[D]: IEB154I SFTPIND HAS BEEN SUCCESSFULLY LOADED
Iebcopy[D]: IEB154I SFTPPROC HAS BEEN SUCCESSFULLY LOADED
Iebcopy[D]: IEB154I SFTPSAMP HAS BEEN SUCCESSFULLY LOADED
Iebcopy[D]: IEB154I SSHIND HAS BEEN SUCCESSFULLY LOADED
Iebcopy[D]: IEB154I SSHPROC HAS BEEN SUCCESSFULLY LOADED
Iebcopy[D]: IEB154I SSHSAMP HAS BEEN SUCCESSFULLY LOADED
Iebcopy[D]: IEB154I WGET2DSN HAS BEEN SUCCESSFULLY LOADED
Iebcopy[D]: IEB1098I 22 OF 22 MEMBERS LOADED FROM INPUT DATA SET REFERENCED BY SYS00017
Iebcopy[D]: IEB144I THERE ARE 12 UNUSED TRACKS IN OUTPUT DATA SET REFERENCED BY SYS00018
Iebcopy[D]: IEB149I THERE ARE 8 UNUSED DIRECTORY BLOCKS IN OUTPUT DIRECTORY
Iebcopy[D]: IEB147I END OF JOB - 0 WAS HIGHEST SEVERITY CODE
Co:Z SFTP version: 6.2.0 (7.6p1) 2020-08-15 Copyright (C) Dovetailed Technologies, LLC. 2008-2020. All rights reserved. cozsftp> lzopts loglevel=D
MVS datasets can be listed using the sftp lls command. Partitioned datasets are treated as directories with their members as entries.
When listing z/OS datasets locally with the lls command, catalog
search filter keys are in effect for any wildcard requests. The catalog search wildcards
*, **, and % used in the examples below
are described in the IBM manual DFSMS: Managing Catalogs - SC26-7409.
Note that this is different behavior from sftp clients that connect to the Co:Z sftp-server
and list datasets with the ls. In that case, regular file globbing rules are in
effect.
cozsftp> lcd //USER cozsftp> lls -al
... cozsftp> lcd //user.coz.sampjcl
This section describes how to use the enhanced client with POSIX files (HFS, zFS) on z/OS. Standard sftp implementations (including z/OS OpenSSH) support only binary mode file transfers. The Co:Z implementation provides binary transfer mode by default, but also supports text mode transfers. Text mode transfers are controlled via the following options:
mode: when set totextcauses file transfers to be text based.clientcpandservercp: When text mode is active, these settings determine the codepage translation that will take place. The default client code page isISO8859-1. The default server code page is the current z/OS locale.linerule: When text mode is active, this setting determines how line separators are converted between the client and server.
The get and put commands are used to
transfer POSIX files (either on HFS or zFS filesystems).
The options (listed above) that have been previously set via the lzopts are in effect for any given transfer. All other options (used for dataset support) are ignored for POSIX file transfers.
$ cozsftp user@linux.comcozsftp>
cozsftp> put sftp-server.log /tmp
Uploading sftp-server.log to /tmp/sftp-server.log
sftp-server.log 100% 127 0.1KB/s 00:00
ZosPosixFile[I]: Closing file sftp-server.log - 127 bytes read, 127 bytes sent
ZosSmf119Record[I]: SMF Type119 recording not enabled; SMF recording disabled
The cozsftp client command can be conveniently used in a z/OS batch job without user interaction. The COZBATCH batch utility, also installed as part of the Co:Z toolkit, makes it easy to run cozsftp (or other Unix shell scripts) directly as z/OS batch jobs.
The authentication with the remote system must be set up so as not to require any user interaction. There are three ways to do this with OpenSSH:
Use the
SSH_ASKPASSenvironment variable to point to a program that will read a password.Use an OpenSSH public/private keypair.
Use a RACF Digital Certificate.
For details on these three authentication options, see Appendix F, Client Authentication Mechanisms. Note that instructions in this appendix must be followed in order to run the examples described below.
When sftp is run in batch mode, it is important to know that sftp will abort if any of the supplied commands fail (i.e. complete with a non-zero return code). This behavior is different from an interactive sftp session, where a failed command will report an error, but the session will continue. In cases where a failed command is expected or acceptable (e.g. rm old_file, where old_file may not exist) it is useful to direct batch mode sftp to continue processing. To do this, prefix the command with a dash (-):
-rm old_file
A sample SFTPPROC and batch scripts (installed in <COZ_HOME>/samples/sftp_batch)
are distributed with the Co:Z toolkit to simplify maintenance and support of batch jobs using the Co:Z SFTP client. Using these samples
achieves the following:
COZBATCH customized for running CO:Z SFTP
installation default options separated from individual JCL members
standards defined for a set of variables controlling connection, authentication, options and filenames
unix shell script logic separated into separate reusable script files
![[Caution]](images/caution.gif) | NOTE: |
|---|---|
| The scripts below are designed to be "dotted in" to the COZBATCH job step STDIN DD. As such, only a single script invocation is supported per job step. |
The reusable script files that are distributed with the Co:Z toolkit are the following:
sftp_connect.sh - Connect to a remote system using the Co:Z toolkit cozsftp command. This script connects a cozsftp client to a remote system running sshd and prepares it to accept batch subcommands. This is the script that we recommend that most customers use.
sftp_get.sh, sftp_put.sh - Get or put a single file to/from a remote system to/from a local (z/OS) file using the cozsftp command. cozsftp transfer options (lzopts) can be specified to customize the transfer. Please note: Due to the lack of flexibility in these two scripts, we recommend that most customers use the more flexible
sftp_connect.shscript above.sftp_cat.sh - Get multiple files from a remote system and concatenate them to a local (z/OS) file using the cozsftp command. This script connects a cozsftp client to a remote system running sshd and issues an ls command to get a list of files to get. Each of these files is then retrieved and written to the specified local file on z/OS. cozsftp transfer options (lzopts) can be specified to customize the transfer.
The standard set of variables to control connection, authentication, options and filenames are defined in the table below. Variables used by all scripts are required for sftp_connect.sh. sftp_cat.sh, sftp_get.sh, and sftp_put.sh invoke sftp_connect.sh to establish a connection with the remote host. Some variables are used only for specific scripts as noted in the Script column.
Using the sample SFTPPROC and scripts, the following batch job conditionally creates a directory on the remote system and transfers a data set to it:
//PROCLIB JCLLIB ORDER='COZUSER.COZ.SAMPJCL' //* //********************************************************************* //* Use the sftp_connect.sh script to connect to a remote system //* and send sftp commands. This example uses a ssh key stored in a //* SAF digital certificate //********************************************************************* //SFTPCONN EXEC PROC=SFTPPROC //SFTPIN DD *
| | All of the input to SFTPIN is processed by the z/OS UNIX shell, and therefore normal shell script quoting and interpolation rules apply. |
| | The symbols "<< EOB" followed by an ending EOB define a
|
| | If an SFTP command fails in batch mode, the script will exit at the
point of failure with a non-zero return code. In this case, if the target of the
mkdir command already exists, the command will fail. Prefixing
the command with a dash |
If you only need to download a remote file, you can use the somewhat simpler sftp_get.sh script:
//PROCLIB JCLLIB ORDER='COZUSER.COZ.SAMPJCL'
//*
//*********************************************************************
//* Use the sftp_get.sh script to retrieve a remote file to a local
//* data set. This example uses a password (via the SSH_ASKPASS
//* protocol) to connect to the remote system
//*********************************************************************
//SFTPGET EXEC PROC=SFTPPROC
//SFTPIN DD *
pwdsn="COZUSER.COZ.SAMPJCL(PW)"
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))
//*
The sections below describe the SFTPPROC, installation default options, and a few more examples.
The SFTPPROC sample JCL distributed with the Co:Z toolkit can be used as a tailorable model for customizing COZBATCH for using CO:Z SFTP.
//********************************************************************* //* //* PROC for executing the Co:Z SFTP client (cozsftp) in batch //* //* Tailor the proc for your installation: //* 1.) Tailor LIBRARY with the PDSE that contains the //* COZ load module. //* 2.) Tailor SFTPIND= to point to SAMPJCL member that contains //* site specific shell variable settings for running the //* Co:Z SFTP batch scripts //* 3.) Review the Co:Z SFTP batch scripts (located in //* $COZHOME/samples/sftp_batch) for additional shell variables //* to set for individual jobs to get, put, connect, etc... //********************************************************************* //EXSFTP PROC ARGS=, < [-L<log_opt>]
| | COZBATCH logging may be added to ARGS for problem diagnosis. |
| | Defines the member that contains the installation CO:Z SFTP defaults. These defaults can be overriden in individual jobs as necessary. |
| | Defines the program to execute as COZBATCH, a utility similar to IBM's BPXBATCH. COZBATCH runs a Unix login shell in the original address space. |
| | Ensures that the site specific installation defaults are included first in STDIN, before any job specific commands. |
| | Defines a name for STDIN allowing jobs using this proc to include commands in STDIN. |
The SFTPIND sample JCL member distributed with the Co:Z toolkit can be used as a tailorable model for CO:Z SFTP installation defaults.
############################################################################### # Co:Z SFTP Batch Script Settings # The shell variables below can be set to site specific values, but may # be overridden in individual jobs. ############################################################################### # # CONFIGURATION VARIABLES: # # cozbin_dir - May be set to the absolute path of the installed Co:Z Toolkit # "bin" directory. If not set, this directory must be present in # the current user's PATH environment variable. # script_dir - May be set to the absolute path of the directory containing the # sftp_batch scripts (including this file). All scripts are # assumed to be in this directory. If not set, this directory must # be present in the current user's PATH environment variable. # cozbin_dir="/usr/local/coz/bin"
| | Defines a variable for the location of the cozsftp executable. This variable is used by the sftp batch scripts to execute the cozsftp command. |
| | Defines a variable for the location of the sample or customized version of the sftp batch scripts. This variable is used in all jobs executing the sftp batch scripts. |
| | Sets global installation options as necessary. Note that the sftp_opts variable is appended as each option is added. Jobs using SFTPPROC can reset or append to these options using this variable. |
Co:Z SFTP Client logging is described earlier in this chapter (Section 4.2, “Co:Z SFTP client logging”). This section describes how to set these options in batch.
OpenSSH SFTP logging is enabled by passing the -v option on the sftp command. This can be done in batch by appending the desired -v option to the sftp_opts variable in the STDIN section of the job:
//SFTPIN DD * sftp_opts="$sftp_opts -vvv"
Co:Z SFTP client logging is enabled by exporting the COZ_LOG variable in the STDIN section of the job.
//SFTPIN DD * export COZ_LOG=T
COZBATCH logging is enabled by adding a parameter to the EXEC statement for the SFTPRPOC.
The following example uses the -LD command switch to set the
default logging level to "Debug" for COZBATCH. The t option is also used to
prefix all messages with a timestamp.
//SFTPGET EXEC PROC=SFTPPROC,
ARGS='-LD,t'
//SFTPIN DD *
Finally, it is often very helpful to see details about the Unix System Service shell script processing of the
input to COZBATCH. This can be controlled by explicitly requesting a login shell (/bin/sh -L) along with the
trace option (-x). The following example sets both the COZBATCH logging level to "Debug" and these shell
options:
//SFTPGET EXEC PROC=SFTPPROC,
ARGS='-LD,t /bin/sh -L -x'
//SFTPIN DD *
The SFTPSAMP sample JCL distributed with the Co:Z toolkit can be used as a tailorable model for writing batch jobs using CO:Z SFTP.
//SFTPSAMP JOB (),'DOVETAIL',MSGCLASS=H,NOTIFY=&SYSUID
//PROCLIB JCLLIB ORDER='COZUSER.COZ.SAMPJCL'
//*
//*********************************************************************
//*
//* Batch job containing examples of running cozsftp in batch
//*
//* 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 SFTPPROC procedure has been installed.
//*
//*********************************************************************
//*
//*********************************************************************
//* Use the sftp_connect.sh script to connect to a remote system
//* and send sftp commands. This example uses a ssh key stored in a
//* SAF digital certificate
//*********************************************************************
//SFTPCONN EXEC PROC=SFTPPROC
//SFTPIN DD *
cert="MY-RING:RSA-CERT"
user=myuser
host=myhost
. $script_dir/sftp_connect.sh << EOB
lzopts mode=text
-mkdir incoming # use the "-" prefix in case directory already exists
put mydata.txt incoming
EOB
//*
//*********************************************************************
//* Use the sftp_get.sh script to retrieve a remote file to a local
//* dataset. This example uses a user ssh key stored in a SAF
//* digital certificate
//*********************************************************************
//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))
//*
//*********************************************************************
//* Use the sftp_put.sh script to send a local file to a remote
//* file. This example uses a password (via the SSH_ASKPASS protocol)
//* to connect to the remote system
//*********************************************************************
//SFTPPUT EXEC PROC=SFTPPROC
//SFTPIN DD *
pwdsn="COZUSER.COZ.SAMPJCL(PW)"
user=myuser
host=myhost
lzopts="mode=text"
lfile=/etc/profile
rfile=/home/myuser/zprofile.txt
# Don't try to use our public key even if we have a default one
# This would not normally be a required setting
sftp_opts="$sftp_opts -oPubkeyAuthentication=no"
. $script_dir/sftp_put.sh
//*
//*********************************************************************
//* Use the sftp_cat.sh script to retrieve multiple files from a remote
//* system and concatenate them to a local dataset. This example uses
//* z/OS OpenSSH defaults for public/private key authentication
//* (because neither the "cert" or "pwdsn" variables are defined)
//*********************************************************************
//SFTPCAT EXEC PROC=SFTPPROC
//SFTPIN DD *
user=myuser
host=myhost
lzopts="mode=text"
ldsn="//DD:MYDD"
rpat=/home/myuser/doc/*.txt
. $script_dir/sftp_cat.sh
/*
//MYDD DD DSN=COZUSER.SFTPCAT.DATA,DISP=(MOD,KEEP),
// DCB=(LRECL=80,RECFM=FB),SPACE=(CYL,(3,1))
//
| | Each step in this sample job uses the SFTPPROC. |
| | Each step uses SFTPIN defined by the SFTPPROC. |
| | Sets all variables required for sftp_get.sh. Note that some required variables are in the installation global defaults. Global variables may be optionally overriden here before calling the shell script. |
| | Executes sftp_get.sh to get a file from the remote system saving it in the data set defined by //MYDD. |
In release 2.4.0, support was added to allow multiple files to be downloaded using a wild-card pattern (*) to a single DD if the DD was allocated with DISP=MOD.
//SFTPGET EXEC PROC=SFTPPROC //SFTPIN DD * user=myuser host=myhost pwdsn="COZUSER.COZ.SAMPJCL(PW)" lzopts="mode=text" lfile=//DD:MYDD
| | The |
| | The get command uses a wild-card (*) pattern to select any file
in the |
| | The underlying get subcommand generated by the sftp_get.sh
script will be:
|
In release 7.0.0,
support was added to allow basic if/then/else command processing in the Co:Z SFTP client.
This section shows usage examples, but additional information can be found in the cozsftp command reference.
In the following example, a remote file remote.data will be downloaded only if it exists.
The job step will get a return code 0 if either the remote file doesn't exist, or if it does and it is downloaded successfully.
//SFTPCND1 EXEC PROC=SFTPPROC //SFTPIN DD * user=myuser host=myhost . $script_dir/sftp_connect.sh <<EOD lzopts mode=text,recfm=vb,lrecl=2048,space=cyl.1.1 %if cd /remote/dir ls remote.data %then get remote.data //HLQ.MY.LOCAL %fi EOD //
In this next example, a file is uploaded in an %if block but if that fails an %else block
is used to attempt to put it to an alternate directory.
//SFTPCND2 EXEC PROC=SFTPPROC //SFTPIN DD * user=myuser host=myhost . $script_dir/sftp_connect.sh <<EOD lzopts mode=text %if cd /remote/dir put //HLQ.MY.LOCAL remote.data %else cd /remote/alt/dir put //HLQ.MY.LOCAL remote.data %fi EOD //
In the following example, several put commands are executed in an %if block.
The block will terminate if any of these should fail, but the get command following the block will still be attempted.
The exit code will be zero even if a command in the %if block fails.
//SFTPCND3 EXEC PROC=SFTPPROC //SFTPIN DD * user=myuser host=myhost . $script_dir/sftp_connect.sh <<EOD lzopts mode=text cd /remote/dir %if put //HLQ.MY.LOCAL1 remote1.data put //HLQ.MY.LOCAL2 remote2.data put //HLQ.MY.LOCAL3 remote3.data %fi lzopts recfm=fb,lrecl=80,space=trk.3.3 get remote4.data //HLQ.MY.LOCAL4 EOD //
