Dovetailed Technologies

Appendix B. Co:Z SFTP options

B.1 General transfer options

The following table describes the general transfer options. The usage columns describe when the option (if active) will apply during transfer. Usage Read means using Co:Z SFTP (server or client) to read a z/OS file. Usage Write means using Co:Z SFTP (server or client) to write a z/OS file.

[Note]Note

Options that have a blank value column are on/off options. They are activated by supplying the option name by itself (no values allowed) and deactivated by prefixing the option name with the prefix NO. For example: trim and notrim.

Table B.1. General transfer options

KeywordUsage
NameValueDatasetsPOSIXReadWrite
clientcp<codepage>XXXX
estsize XXX 
jesincsysin X X
linerulecr | crlf | crnl | l4 | lf | nl | rdw | mfrdw | flexible | 0xbb[bb..] | noneXXXX
modebinary | textXXXX
notifyXXXX
overflowerror | flow | trunc | wrapX X
pad<pad_char> | 0xbbX XX
replace XX X
servercp<codepage>XXXX
technique<technique_string>XXXX
trtabSTANDARD | translate_table_dsnameXXXX
trim X X

clientcp

Specifies 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. For the Co:Z SFTP server the default is ISO8859-1. For the Co:Z SFTP client, the default is the default locale codeset of the client's process (some variant of EBCDIC).

A TranslationException is logged when the transferred file is malformed. When possible, the offset of the last successfully translated byte is captured in the error log message.

estsize

When estsize (the default) is enabled, Co:Z SFTP returns the actual size for Unix files and an estimated size for MVS data sets. When estsize is disabled (NOestsize), the size returned is zero and SSH_FILEXFER_ATTR_SIZE is off indicating that the attribute size is not present. This has the effect of telling the client on a file read that there is no estimated size.

jesincsysin

When option jesincsysin is enabled, concatenated spool file downloads will include SYSIN spool files. In addition, the separator between spool files will be annotated with the [step.[procstep.]]ddname. This option is a convenient way to download all job input and output.

linerule

The 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 IBM-style RDWs are used as prefixes. l4 specifies that each record is delimited (preceded) by a four byte length of the record that follows. Note: Unlike the rdw option, this length value does not include the size of the length field. mfrdw indicates that Micro-focus file and records headers are used.

0xbb[bb..] may be used to specify a sequence of one or more bytes in the source codepage. none should be used when no line terminators are to be recognized/used.

The default is flexible for writing and lf for reading.

mode

Specifies whether transfers are as-is (binary) or subject to codepage/linerule/overflow/pad processing (text). The default is binary.

notify

Specifies whether a message should be written to the console on completion of a put or get command by the Co:Z SFTP server and client. Notifications are also written on completion of a remove or rename command on the server. The default is NOnotify. In order to enable this option, a valid message template must be defined in the site-wide server or client configuration. For addition information, see Section C.1, “Specifying notification (immutable) options”. Notifications are disabled if the Co:Z SFTP server log file has been redirected to /dev/console due to the potential for recursive logging.

overflow

For text-mode dataset write processing, controls the treatment of lines longer than the maximum dataset record length. The default is wrap. When set to error, an error is returned if the source line is longer than the maximum record length. When set to flow, source lines longer than the maximum record length are flowed across subsequent records. For fixed record formats, the pad character is used to complete the final record resulting from the source line. When set to trunc, source lines longer than the maximum record length are truncated. When set to wrap, source lines longer than the maximum record length are broken into multiple records.

pad

For text-mode dataset write processing, specifies the character to use when padding lines into fixed-length dataset records. For text-mode dataset read processing, this character also identifies the character to be trimmed if the trim is enabled. If given as 0xbb, it specifies (in hex) a single-byte character in the source codepage. If not specified, the default is a space character in the local z/OS codepage.

replace

This setting allows for existing datasets or files to be replaced. The default, if not specified, is replace, which allows for replacement. NOreplace can be set to prevent an existing dataset or file from being replaced.

When using cozsftp, setting NOreplace with lzopts only applies to get commands.

NOreplace for a put command requires that the server be running Co:Z SFTP Server. For other SFTP servers, this option is not supported.

Note: If NOreplace is set, you may not create PDS members, regardless of whether the member exists, and you may also not write to GDG datasets using a positive (+n) relative reference.

servercp

Specifies 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. For the Co:Z SFTP server the default is default locale codeset of the server's process (some variant of EBCDIC). For the Co:Z SFTP client the default is ISO8859-1.

A TranslationException is logged when the transferred file is malformed. When possible, the offset of the last successfully translated byte is captured in the error log message.

technique

Specifies the Codepage conversion technique string. Used to override the default Unicode Services value of LMREC. For more information, see IBM's Unicode Services User's Guide and Reference (SA22-7649).

trtab

Specifies the translate table to use for text mode transfers. This option overrides the clientcp/servercp/technique options if also given. If STANDARD, the translate table TCPIP.STANDARD.TCPXLBIN is used. If a dataset name is supplied, it is expected to be in the format produced by the TSO CONVXLAT command. Only single byte translations are supported. Specifically, the dataset DCB must be LRECL=256,RECFM=F and contain two translation table records. The first record is an ASCII-to-EBCDIC mapping; the second record is an EBCDIC-to-ASCII mapping. Additional comment records (starting with * in the first column) are allowed.

trim

For text-mode dataset read transfers, enabling this options will cause pad characters to be trimmed from the dataset records as they are read. The default, if not specified, is trim.

B.2 Miscellaneous options

The following table describes the miscellaneous options. These options do not apply to transfer operations, but affect the behavior of Co:Z SFTP.

Table B.2. Miscellaneous options

NameValueNotes
interimlogginginterval[.log | .sock | .both]Sets the interval in seconds for logging interim messages and/or records for the progress of a file transfer. By default, the interval is set to zero (disabling interim logging). If this option is specified with a positive integer value for interval an interim record will be written both to the real-time Co:Z SMF API and as a summary message to the Co:Z client or server log approximately every interval seconds.

The interval option may optionally be followed by one of the following:

.log - interval log messages are only written to the Co:Z SFTP log file (stderr). For the Co:Z SFTP server, this is normally routed to the session log file. The log message is an (I)nformational message, if written, so the loglevel must be set to I or a more detailed level for it to be seen).

.sock - interval log records are only written to the Co:Z SMF real-time interface socket. If this Unix domain socket (a Unix path) has not been created, then it is ignored. Refer to Using the Real-Time Co:Z SMF Interface for additional information on the real-time interface.

.both - interval logs messages and records will both be recorded. This is the default sub-option if not specified.

Note: When Co:Z SFTP client is running interactively (not in batch), the Progress meter must be disabled (using the progress subcommand) in order to write interim records or log messages.

The recommended interval is two minutes or more. For example, to set a 3 minute interval, use:

interimlogging=180

loglevelE|W|N|I|D|T|FSets the logging level of the Co:Z sftp-server. The UPPER CASE values correspond to the list: (Error, Warning, Notice, Info, Debug, Trace, Fine).
maxcscntnnnnSets the maximum number of CatalogSearch entries returned for a given dataset level search. The default is 2000. Use caution when specifying a large maximum value, as it may cause Co:Z SFTP to run out of memory.
reqexitsexit[.exit]...(server only) For each required exit listed, the corresponding loadmodule must be available and loaded. If not, an error message will be written to the log and the server session immediately terminated. The exit names that may be specified are: CZCHKCMD, CZCHKIP, CZCHKPWD, and CZPOSTPR. Installations that use exits will typically set this option in the fixed: section of /etc/ssh/cozsftp_server_config. Additionally, users should not have write access to individual sftp-server.rc files in order to prevent users from overriding installation exits with their own exits. See the Sitewide server configuration section for information on managing individual sftp-server.rc files.
servertimeoutnnnn(server only) Sets a server side timeout value where nnnn is minutes. If the client is inactive longer than nnnn minutes, the server terminates the session. By default, no timeout value is configured.

To configure this option globally, set this option in the fixed: section of /etc/ssh/cozsftp_server_config. This option may not be set or changed once the session has started.

showall If active, all options will be shown on option display (ls /+). Inactive options are shown with a prefix of NO.
smfU83 | U84If active (the default, smf=U84), SMF 119 records will be written and IEFU84 called (when available) for file transfer events. If a failure occurs because SMF is disabled, this option will be automatically set to NOsmf and no further attempts will be made. To completely disable SMF recording supply "nosmf" in one of the config files: Appendix C, Session config files. This option may not be set or changed after the session has started.
ssh-le-options (Co:Z SFTP client only) This option may be used to supply z/OS Language Environment options for the z/OS OpenSSH ssh command when it is invoked by cozsftp.

This option may not be set or changed once the session has started.

Referring to IBM APAR OA34819, we suggest that customers adopt the value for this setting that is in the sample cozsftp_config file supplied with the distribution.

unixls If active (NOT the default), a UNIX long form listing is returned on client requests for directory listings of data sets. This format is incorrectly expected by many clients, particularly GUI clients, that do not fully adhere to the SFTP specification (refer to Client Compatibility). For many clients, setting this option
  • improves directory listings of data sets by identifying partition data sets as directories enabling double click to navigate to the members

  • shows jobs displayed by //-JES as directories enabling double click to navigate to the spool files

  • lists /+ output correctly

For clients where /+ does not work by default, the option must be enabled in one of the config files, Appendix C, Session config files.

Values returned in the listing for Owner, Group and Access are generally placeholder values because they are not available on z/OS. A dash will be displayed for Owner and Group. Access will be displayed as "-rw-r--r--" for files and "drw-r--r--" for directories. Last Modified is returned as "Jan 1 1970" when a valid date is not available. Some clients display this date; however, some display a date with the year 1899.


B.3 Dataset allocation options

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 (none of these options, with the exception of conddisp, apply during POSIX file transfers). For more information on BPXWDYN, see Using REXX and z/OS UNIX System Services - SA22-7806

[Note]Note

The conddisp option is not a BPXWDN keyword, but is supported by Co:Z SFTP to handle dataset / POSIX file deletion in the result of a transfer error. If this option is set to delete, Co:Z SFTP server will attempt to delete any file or dataset that is being written to (on the client or the server) if the transfer is interrupted. In the OpenSSH sftp client, a Ctrl-C (SIG-INT) is caught in the client and it just closes the file, so there is no way for the server to see this as an interruption. In this case, it is still the client's responsibility to clean up the file.

Table B.3. BPXWDYN options

KeywordUsage
NameValueReadWrite NewWrite ExistingSysout
blksize<numeric> X X
bufno<numeric>XXX
conddispcatlg | deleteXXXX
copies<numeric> X
dataclas<alphanum> X
destdest[.user] X
dir<numeric> X
dispold | shr | mod | newXXX
dsntypelibrary | pds | large | extreq | extpref | basic X
dsorgps | po | da X
forms<alphanum> X
gdgnt  X
hold  X
labelnl | sl | nsl | sul | blp | ltm | al | aul X
like<Dataset Name> X
lrecl<numeric> X X
maxvol<numeric> X
mount XXX
mgmtclas<alphanum> X
norecall X X
outdes<alphanum> X
recfm<alphanum> X X
release XXX
retpd<numeric> X
sequence<numeric> X
spaceblk.primary[.secondary] | trk.primary[.secondary] | cyl.primary[.secondary] X
spinunalloc X
storclas<alphanum> X
sysout<sysout_class> X
trtchnoncomp | comp | c | e | et | t X
ucount<numeric>XXX
unit<alphanum> X
vol<alphanum> X
writer<alphanum> X

Copyright© 2009-2017 Dovetailed Technologies, LLC. All rights reserved.
Co:Z® is a registered trademark of Dovetailed Technologies, LLC.