The following chapters describe how to use sftp with dataset support. The examples below assume that you have installed and configured the Co:Z toolkit on your z/OS and target systems, and have properly configured the sftp sshd subsystem.
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.
File transfer options are set with the special ls 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 /+.
The following table describes the general transfer options. The usage columns describe when the option (if active) will apply during transfer.
Table 3.1. General transfer options
| Keyword | Usage | ||||
|---|---|---|---|---|---|
| Name | Value | Datasets | POSIX | Read (Get) | Write (Put) |
| clientcp | <codepage> | X | X | X | X |
| linerule | cr | crlf | crnl | lf | nl | rdw | ibmrdw | mfrdw | flexible | none | X | X | X | X |
| mode | binary | text | X | X | X | X |
| overflow | error | flow | trunc | wrap | X | X | ||
| pad | <pad_char> | X | X | ||
| servercp | <codepage> | X | X | X | X |
| trim | X | X | |||
clientcpSpecifies the name of the client codepage used when performing text mode transfers.
Data will be converted between the server codepage (servercp) and this code page.
The codepage must either be a single byte codepage or any multi-byte codepage that has single-byte
line terminators (e.g. UTF-8). The z/OS Unix command iconv -l lists
the available codepages. The default, if not specified, is ISO8859-1.
lineruleThe values cr, crlf, crnl,
lf, nl specify that, for text mode transfers, lines
will be terminated with the given characters in the client codepage. flexible
may be used when writing to files or datasets to indicate that any combination of cr,
lf, or newline will be recognized as a line terminator. rdw specifies that
a 4 byte, big endian length will prefix each record, which ibmrdw specifies
that IBM-style RDWs are used as prefixes. mfrdw indicates that Micro-focus
file and records headers are used. The default is flexible for writing
and lf for reading.
modeSpecifies whether transfers are as-is (binary) or subject
to codepage/linerule/overflow/pad processing (text). The default is binary.
overflowFor text-mode dataset write processing, controls the treatment of lines longer than the maximum dataset record length.
padFor text-mode dataset write processing, specifies the character to use when padding lines into fixed-length dataset records. If not specified, the default is a space character in the server codepage.
servercpSpecifies the name of the server codepage used when performing text mode transfers. Data will be converted between the client codepage (clientcp) and this code page. The default, if not specified, is default codepage for the server's process.
trimFor text-mode dataset read transfers, enabling this options will cause pad characters to be trimmed from the dataset records as they are read.
The following table describes the miscellaneous options. These options do not apply to transfer operations, but affect the behaviour of the sftp-server.
Table 3.2. Miscellaneous options
| Keyword | ||
|---|---|---|
| Name | Value | Notes |
| loglevel | E | W | N | I | D | T | F | Sets the logging level of the Co:Z sftp-server. The UPPER CASE values correspond to the list: (Error, Warning, Info, Notice, Debug, Trace, Fine). |
| showall | If active, all options will be shown on option display (ls /+).
Inactive options are shown with a prefix of | |
The following table describes options that apply when transferring MVS datasets. The z/OS BPXWDYN service is used for dataset allocation and these options correspond to keywords available with BPXWDYN with similar syntax except that:
keyword=value is used rather than keyword(value)
periods are used in place of commas
other minor differences as described below
The usage columns below describe when the option (if active) will apply during dataset transfer (these options never apply during POSIX file transfers). For more information on BPXWDYN, see Using REXX and z/OS UNIX System Services - SA22-7806
Table 3.3. BPXWDYN options
| Keyword | Usage | ||||
|---|---|---|---|---|---|
| Name | Value | Read | Write New | Write Existing | Sysout |
| allowmount | X | X | X | ||
| blksize | <numeric> | X | X | ||
| bufno | <numeric> | X | X | X | |
| copies | <numeric> | X | |||
| dataclas | <alphanum> | X | |||
| dest | dest[.user] | X | |||
| dir | <numeric> | X | |||
| disp | old | shr | mod | new | X | X | X | |
| dsorg | ps | po | da | X | |||
| forms | <alphanum> | X | |||
| gdgnt | X | ||||
| hold | X | ||||
| label | nl | sl | nsl | sul | blp | ltm | al | aul | X | |||
| like | <Dataset Name> | X | |||
| lrecl | <numeric> | X | X | ||
| maxvol | <numeric> | X | |||
| mgmtclas | <alphanum> | X | |||
| norecall | X | X | |||
| outdes | <alphanum> | X | |||
| recfm | <alphanum> | X | X | ||
| release | X | X | X | ||
| retpd | <numeric> | X | |||
| sequence | <numeric> | X | |||
| space | [blk. | trk. | cyl.]primary[.secondary] | X | |||
| spin | X | ||||
| storclas | <alphanum> | X | |||
| sysout | <sysout_class> | X | |||
| trtch | noncomp | comp | c | e | et | t | X | |||
| ucount | <numeric> | X | X | X | |
| unit | <numeric> | X | |||
| vol | <alphanum> | X | |||
| writer | <alphanum> | X | |||
sftp> ls /+mode=text/+mode=text sftp> ls /+
/+/clientcp=ISO8859-1 /+/error.log /+/mode=text /+/servercp=IBM-1047
sftp> ls /+lrecl=80,recfm=fb,space=trk.3.2
/+lrecl=80,recfm=fb,space=trk.3.2sftp> ls /+showallNOallowmount NOblksize NObufno NOcopies NOdataclas NOdest NOdir NOdisp NOdsorg NOforms NOgdgnt NOhold NOlabel NOlike NOmaxvol NOmgmtclas NOnorecall NOoutdes NOrelease NOretpd NOsequence NOspin NOstorclas NOsysout NOtrim NOtrtch NOucount NOunit NOvol NOwriter clientcp=ISO8859-1 error.log linerule=flexible lrecl=80 mode=text overflow=wrap recfm=FB servercp=IBM-1047 showall space=TRK.3.2 sftp> ls noshowall,norecfm
noshowall,norecfm sftp> ls clientcp=ISO8859-1 error.log lrecl=80 mode=text servercp=IBM-1047 space=TRK.3.2
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 Chapter 2, Installation and Customization
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.
$ 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*
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 IBM's ported tools version) 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 to text causes
file transfers to be text based.
clientcp and servercp: When text mode
is active, these settings determine the codepage translation that will take place.
The default client code page is ISO8859-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>