Unlike standard FTP, SFTP has no site command for setting platform specific options. Co:Z SFTP file transfer options are set with a special ls command request of the form: ls /+<name=value>. They can be cleared with a request of the form: ls /+NO<name>.
Multiple options can be set by separating the key=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 options directory /+/ is a pseudo directory on the server,
and it is possible to make it the working directory via the cd /+
command. From this directory, options may be set and listed without the /+
prefix.
The active options and their settings can be displayed by issuing the command ls /+.
Co:Z SFTP server file transfer options may be specified interactively or via configuration files. The active options are determined in the following priority order:
The
fixed:section of/etc/ssh/cozsftp_server_config(highest priority and non-modifiable)The first matching pattern (if any) from
$HOME/.ssh/cozsftp_server_configThe first matching pattern (if any) from
/etc/ssh/cozsftp_server_configPrevious interactive commands:
ls /+(described below) in the same sessionThe environment variable
SFTP_ZOS_OPTIONSThe
default:section of/etc/ssh/cozsftp_server_config(lowest priority)
For a list of available options, see Appendix B, Co:Z SFTP options.
For a description of the cozsftp_server_config file format, including
how to specify file name patterns, see Appendix C, Session config files.
All examples in the following sections can be run by most sftp clients, either from z/OS or from other platforms (Windows, linux, etc..). Note: There are some differences in the way clients interact with the server, so the output shown in the examples below (performed with the OpenSSH sftp client) may not match your output exactly.
sftp> ls /+mode=text/+mode=text sftp> ls /+
/+/clientcp=iso8859-1 /+/error.log /+/loglevel=I /+/mode=text /+/servercp=IBM-1047 /+/trim
sftp> ls /+lrecl=80,recfm=fb,space=trk.3.2
/+lrecl=80,recfm=fb,space=trk.3.2sftp> ls /+showallNOblksize NObufno clientcp=ISO8859-1 conddisp=catlg NOcopies NOdataclas NOdest NOdir NOdisp NOdsntype NOdsorg error.log estsize NOforms NOgdgnt NOhold NOjesjobname NOjesjobwait jeslrecl=80 jesowner=KIRK jesrecfm=f jesstatus=* NOlabel NOlike linerule=flexible loglevel=I lrecl=80 NOmaxvol NOmgmtclas mode=text NOmount NOnorecall NOoutdes overflow=wrap NOpad recfm=fb NOrelease replace NOreqexits NOreset NOretpd NOsequence servercp=IBM-1047 showall smf space=trk.3.2 NOspin NOstorclas NOsysout trim NOtrtch NOucount NOunit NOvol NOwriter sftp> ls noshowall,norecfm
noshowall,norecfm sftp> ls clientcp=ISO8859-1 error.log loglevel=I lrecl=80 mode=text servercp=IBM-1047 space=trk.3.2 trim
Most implementations of the sftp specification, including OpenSSH, do not allow for transmission of detailed information from the server to the client in the event of an error. Adding dataset transfers to the mix only increases the need for better error reporting. To help alleviate this problem, the Co:Z sftp implementation provides a comprehensive logging facility that can be enabled and tuned by each user session.
Several of the above option listing examples show error.log as one
of the options. This is actually an alias for the running session's log file, which is
usually written to the /tmp directory (See the section called “Co:Z SFTP Server logging”
for more information on where this file is written). This alias can be used to easily retrieve
the log at anytime and examine it from the client.
This feature makes it possible to examine detailed error information from the client
without having to abandon the active sftp session. Users of graphical clients such as
winSCP and gFTP see an even greater advantage in that
the error.log file can be viewed simply by selecting the file and transferring it in
view mode.
sftp> rm //user.coz.sampjcl
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,
as not all sftp clients will allow double slash characters to be sent.
The sftp cd 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 cd // will fail.
sftp> cd //user
The get and put commands are used to
transfer datasets and PDS members. By default, the transfer mode is binary, and
when storing new datasets, the DCB defaults are determined by the system and are often RECFM=U.
Any options previously set via the ls /+option=value are in effect for any given transfer.
![[Note]](images/note.gif) | Note |
|---|---|
When using the z/OS datasets must be read or written sequentially, starting with the beginning of the datasets. SFTP clients that attempt to read or write non-sequentially will fail with an error: ZosDataset[E]: dataset read(or write) error: seek not allowed. |
$ sftp user@zos.com
sftp> ls /+
sftp> get //user.coz.sampjcl(cozproc) cozproc.txt
... sftp> ls /+mode=text,lrecl=80,recfm=fb
MVS datasets can be listed using the sftp ls command. Partitioned datasets are treated as directories with their members as entries.
In order to support existing sftp clients, several considerations have to be made when listing datasets:
The ls lists multiple dataset levels (by default), and therefore can return a large amount of information. As such, listings that would involve searching the entire catalog, such as ls // or ls //A* are not allowed. Furthermore, because of the way sftp clients interact with the server, the following style of command is not supported: ls //USER.LVL1*. However, the same effect can be produced by either using directory notation for searching the catalog (ls //USER/LVL1*) or changing to the desired level and issuing a relative listing command:
cd //USER ls LVL1*
Note Wildcard support for listing datasets is dependent on client support, since it is up to the client to read the "directory" and filter matches. Where possible, dataset names are treated as case insensitive. A get or put can specify the name in either lower or upper case and it will be found. However, any globbed (wildcard) ls command requires upper case characters. Individual datasets can be listed in either upper or lower case. To be safe, it is a good idea to use upper case on all list requests.
As mentioned above, partitioned datasets (PDS) are treated as directories. the long list form ls -l can be used to list member statistics, if statistics exist.
The ls accepts dataset names prefixed either by
//or/-/. The second form should be used for the few sftp clients that do not allow a double slash to sent to the server.
sftp> cd //USER sftp> ls -alCouldn't stat remote file: No such file or directory Can't ls: "//" not found sftp> cd //user sftp> ls co*
Can't ls: "//USER/co*" not found sftp>
... sftp> cd //user.coz.sampjcl
This section describes how to use the Co:Z implementation of sftp 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 ls /+option=value are in effect for any given transfer. All other options (used for dataset support) are ignored for POSIX file transfers.
sftp> ls /+mode=text,clientcp=UTF-8
sftp> put sftp-server.rc .ssh
Uploading sftp-server.rc to /home/user/.ssh/sftp-server.rc
sftp-server.rc 100% 234 0.2KB/s 00:00
sftp>This section describes how to use Co:Z SFTP to submit jobs, query job status and access spool files on z/OS. Future releases of Co:Z SFTP will also support enhanced job cancel and purge facilities.
Note: Co:Z JES spool access supports both JES2 and JES3, but is currently limited to the primary JES subsystem.
To query the status of z/OS jobs, you simply list the "//-JES" pseudo-directory:
sftp> cd //-JES/+jesowner=goetze sftp> ls -al JOBNAME JOBID OWNER STATUS CLASS GOETZEB JOB00601 GOETZE OUTPUT A RC=0000 GOETZE TSU00505 GOETZE OUTPUT TSU RC=0000 GOETZE TSU00515 GOETZE ACTIVE TSU sftp> ls /+jesstatus=active
/+jesowner=goetze sftp> ls -al JOBNAME JOBID OWNER STATUS CLASS GOETZE TSU00515 GOETZE ACTIVE TSU
Co:Z SFTP uses the unauthorized "Extended Status" subsystem interface to obtain job status. This facility is only available if you are running z/OS 1.9 or later. A SAF(RACF) SECLABEL dominance check may be used by the IBM extended status subsystem interface to control access to this facility; refer to RACF or your security product documentation for more information.
Job spool files may be transferred using normal SFTP "get" commands from your SFTP client.
sftp> cd //-JES sftp> ls -al JOBNAME JOBID OWNER STATUS CLASS KIRKL JOB00434 KIRK OUTPUT A RC=0000 TOMCAT JOB00561 KIRK ACTIVE A KIRK TSU00560 KIRK OUTPUT TSU RC=0000 KIRK TSU00562 KIRK ACTIVE TSU sftp> cd JOB00434Fetching //-JES.JOB00434/jesysmsg to jesysmsg sftp> get logdef.sysprint Fetching //-JES.JOB00434/logdef.sysprint to logdef.sysprint
Using the jesincsysin option (available on z/OS 1.10 or later):
sftp> ls /+jesincsysin
Co:Z SFTP uses the unauthorized interface to the JES "Spool Browse" facility, which is only available if you are running z/OS 1.9 or later. As with IBM FTP, the SAF(RACF) JESSPOOL resource class is used to control access to spool files throuh the Spool Browse facility.
Jobs may be submitted to the JES internal reading using SFTP "put" commands from your SFTP client into a special pseudo-directory named "//-JES.INTRDR".
sftp> ls /+mode=text /+mode=text sftp> get //kirk.test.jcl(sleep3) jcl.txt
Here's a similar example, using the Windows sftp client PuTTY psftp to non-interactively download some JCL, submit it, wait for it to run, and then download the output:
C:\Users\kirk> type psftp-input.txt ls /+mode=text,jesjobwait get //kirk.test.jcl(sleep3) jcl.txt cd //-jes.intrdr put jcl.txt myjob dir cd myjob dir get all sleep3.log C:\Users\kirk> psftp -b psftp-input.txt kirk@zos.myco.com Using username "kirk". Remote working directory is /u/kirk Listing directory /+mode=text,jesjobwait jesjobwait mode=text remote://KIRK.COZ.TESTJCL(SLEEP3) => local:jcl.txt Remote directory is now //-JES.INTRDR local:jcl.txt => remote://-JES.INTRDR.MYJOB Listing directory //-JES.INTRDR ALIAS JOBNAME JOBID OWNER STATUS CLASS COMPL MYJOB SLEEP3 JOB03165 KIRK INPUT A Remote directory is now //-JES.INTRDR.MYJOB Listing directory //-JES.INTRDR.MYJOB DSID STEPNAME PROCSTEP DDNAME C OWNER RECFM LRECL BYTES 102 UNIX SYSOUT H KIRK FBA 121 311 2 JES2 JESMSGLG H KIRK FA 133 1064 3 JES2 JESJCL H KIRK V 136 247 4 JES2 JESYSMSG H KIRK VA 137 1044 remote://-JES.INTRDR.MYJOB.ALL => local:sleep3.joblog
The following table describes options that affect JES submit, status, and spool file transfer.
