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
	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

Keyword		Usage
Name	Value	Datasets	POSIX	Read	Write
clientcp	<codepage>	X	X	X	X
estsize		X	X	X
filetag	`use \| create \| use.create \| u \| c \| uc`		X	X	X
jesincsysin		X		X
linerule	`cr \| crlf \| crnl \| l4 \| lf \| nl \| rdw \| mfrdw \| flexible \| 0xbb[bb..] \| none`	X	X	X	X
mode	`binary \| text`	X	X	X	X
notify		X	X	X	X
overflow	`error \| flow \| trunc \| wrap`	X			X
pad	`<pad_char> \| 0xbb`	X		X	X
replace	`reuse \| realloc`	X	X		X
servercp	<codepage>	X	X	X	X
technique	<technique_string>	X	X	X	X
trtab	`STANDARD \| translate_table_dsname`	X	X	X	X
trim		X		X
utfbom	`keep \| remove`	X	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.

filetag

(new in 8.0.0) The values use and create may be specfied, and both values may be specified separated by a period. Alternatively u and c may be used, either alone or together as filetag=uc. The default is NOfiletag.

When use is specified, existing UNIX file tags will be respected when converting files, and these transfer options will be displayed. This option affects both reading and writing of existing UNIX files that have file tags.

When create is specified, UNIX files that are written will be tagged according to the mode and codepage settings in effect, replacing any existing file tags.

When both use and create are specified, existing file tags will be respected. New or untagged UNIX files that are written will be tagged according to the mode and codepage settings in effect. Existing file tags will not be replaced when writing.

Note: If NOfiletag is in effect (the default and prior to 8.0.0), then existing file tags will result in filesystem autoconversion IF _BPXK_AUTOCVT=ON/ALL or equivalent are set in the current execution environment. Any such autoconversion will not be made visible by Co:Z SFTP in "Transfer options" messages, and may occur in addition to translations made by CO:Z SFTP based on mode and codepage settings, possibly with unexpected results. If filetag is specified with either or both values, then file system autoconversion will not occur. Refer to IBM documention for more information on z/OS UNIX autoconversion.

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. This only supports Variable Format Record Sequential Files containing normal data records.

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 data sets or files to be replaced. The default, if not specified, is replace=reuse, which allows for replacement. If the target is a data set, the existing data set will be cleared but the original allocation options will be preserved. replace=realloc can be set to cause the existing data set to be deleted and reallocated using the allocation option settings currently in force. NOreplace can be set to prevent an existing dataset or file from being replaced.

When using cozsftp, setting NOreplace and replace=realloc with lzopts only applies to get commands.

NOreplace and replace=realloc for a put command requires that the server be running Co:Z SFTP Server. For other SFTP servers, these options are not supported.

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

Note 2: The mkdir command cannot be used to replace an existing PDS, even if replace=realloc.

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.

utfbom

For text-mode data set and POSIX file transfers, setting this option to remove will cause Co:Z to remove the Byte Order Mark (BOM) from the incoming data stream if it is present. In order for this option to take effect, the source code page must be UTF-8. The default, if not specified, is keep.

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

Name	Value	Notes
interimlogging	interval[.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). See below for more information on the message format. `.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` Additional notes on the format of messages written to the Co:Z SFTP log file: Message Format: ZosSmf119Record[I]: <sending\|receiving> <file or dataset name> <percent transferred> <bytes transferred> bytes transferred in <seconds> seconds (<transfer rate>) The initial message will show "0 bytes", followed by zero or more subsequent messages with a transferred percentage less than or equal to 99%. Ending with a completion message with 100% or "failed" instead of "100%". Progress messages are based on the "estimated size" of the file or dataset, which may be either unknown or inaccurate. For example, the estimated size may be unknown for downloads where the remote server does not provide the file size. In this case, the interim messages will show the transferred percentage as "--%". The estimated size will be inaccurate for z/OS datasets because the estimate is based on allocation extents. If the estimate is too small, the transferred percentage will not be accurate, but will always be less than or equal to 99% until completed.
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, Notice, Info, Debug, Trace, Fine).
maxcscnt	`nnnn`	Sets 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.
mkdirdsn		If active (the default), a mkdir or lmkdir command issued for the data set space will cause a PDS or PDSE to be created (depending on the value of the `dsntype` option. If inactive, nothing is created.
reqexits	`exit[.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.
servertimeout	`nnnn`	(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`.
smf	U83 \| U84	If 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

Note: If a local data set is referenced in a Co:Z SFTP batch job by //DD:MYDD, then dynamic allocation options do not apply. In this case, options may be specified on the JCL DD statement.

The usage columns below describe when the option (if active) will apply during dataset transfer, as indicated by an X. A T is indicated for options that apply only to reading cataloged tape data sets. These options will only be used when allocating the tape data set if the "label" option is set. This can be useful for overriding DCB information or specifying DCB information for non-labeled tapes.

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

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. Starting in Co:Z 7.0.0, data sets that are dynamically allocated for write will use the SVC99 text unit DALCDISP=DELETE if conddisp=delete is set. This will request that the operating system delete the dataset in the case that the job abnormally terminates.
Co:Z SFTP does not currently support lrecl=32768 (X) processing; the maximum value that can be specified for data set allocation is lrecl=32760. Co:Z SFTP can read existing data sets with lrecl values up to 32767 for records formats such as RECFM=VBS that support this for legacy purposes.
Starting in Co:Z 6.0.0, the default is to use gdgnt for relative GDG references, which means that these references will use the current state for resolution. Only users who use the same GDG more than once in the same job might be affected by this change. For example:
GDGNT : (0) always refers to the latest generation
NOGDGNT : If job creates (+1), then later (+1) refers to it
Also new to Co:Z 6.0.0 is the ispfenq option. This is not a real BPXWDYN keyword, but it can be used when writing to PDS and PDSE members so that they will be allocated with DISP=SHR and will use ENQ semantics that are compatible with ISPF. The default is NOispfenq. This option is ignored with RECFM=U or RECFM=VBS. In addition, when writing to a PDS member, a limit of 16MB of data is imposed since output data is buffered to avoid an indeterminant length ISPF dataset-level ENQ. This limitation does not apply to PDSEs.
Starting in Co:Z 6.1.0, the following BPXWDYN options will also be used when opening existing cataloged tape data sets if the label option is specified: recfm, lrecl, blksize, label, trtch, unit. These are marked "T" in the following table.
Beginning with Co:Z 6.2.0, the ispfstats option was added which is also not a real BPXWDYN keyword. When both ispfstats and ispfenq are enabled then ISPF statistics will be created or updated when writing PDS or PDSE members with RECFM=F,FB,FBS,V,or VB. The default is NOispfstats.
The option gdgplusstat was added to Co:Z 7.0.1. This is not a real BPXWDYN parameter, but it controls how status is reported on a //HLQ.GDG(+n) data set. This keyword if specified can be: dir, file, or notfound to indicate whether the status reported for a "(+n)" relative GDG reference is a file, a directory, or a non-existent file respectively. The default if not specified is dir if GDGNT is set (the default), or file otherwise.

Table B.3. BPXWDYN options

Keyword		Usage
Name	Value	Read	Write New	Write Existing	Sysout
blksize	<numeric>	T	X		X
bufno	<numeric>	X	X	X
conddisp	`catlg \| delete`	X	X	X	X
copies	<numeric>				X
dataclas	<alphanum>		X
dest	`dest[.user]`				X
dir	<numeric>		X
disp	`old \| shr \| mod \| new`	X	X	X
dsntype	`library[.1\|.2] \| pds \| large \| extreq \| extpref \| basic`		X
dsorg	`ps \| po \| da`		X
eattr	`opt \| no`		X
forms	<alphanum>				X
gdgnt	(default; see note above)	X	X	X
gdgplusstat	(default; see note above)		X	X
hold					X
ispfenq	(default; see note above)		X	X
ispfstats	(default; see note above)		X	X
label	`nl \| sl \| nsl \| sul \| blp \| ltm \| al \| aul`	T	X
like	<Dataset Name>		X
lrecl	<numeric>	T	X		X
maxgens	<numeric>		X
maxvol	<numeric>		X
mount		X	X	X
mgmtclas	<alphanum>		X
norecall		X		X
outdes	<alphanum>				X
recfm	<alphanum>	T	X		X
release		X	X	X
retpd	<numeric>		X
sequence	<numeric>		X
space	`blk.primary[.secondary] \| trk.primary[.secondary] \| cyl.primary[.secondary]`		X
spin	unalloc				X
storclas	<alphanum>		X
sysout	<sysout_class>				X
trtch	`noncomp \| comp \| c \| e \| et \| t`	T	X
ucount	<numeric>	X	X	X
unit	<alphanum>	T	X
vol	<alphanum>		X
writer	<alphanum>				X

Prev		Next
sftp-server	Contents	Appendix C. Session config files

Prev		Next
sftp-server	Home	Appendix C. Session config files

Components

Downloads

Documentation

License/Support

Co:Z Documentation :: Co:Z SFTP - User's Guide V 8.1.0