Since the SFTP server decodes the name for the dataset, the filename
in the request can be used to convey other information. The following
filename convention is used: any filename that starts with
/ftadv: has the format
The advice string is a sequence of name=value pairs delimited by commas.
Some names have a one-letter abbreviation for easier usability.
-
TRANSFER_MODE=transfer_mode, X=transfer_mode The transfer mode specifies whether codeset and line delimiter conversions
are performed. Possible values are:
X=bin: Codeset and line delimiter conversions are not performed.
X=text: Codeset and line delimiter conversions are performed.
Default: none
Note: If TRANSFER_MODE is not given but both TRANSFER_CODESET
and TRANSFER_FILE_CODESET or TRANSFER_TRANSLATE_TABLE are present
conversions are performed.
-
TRANSFER_FORMAT=transfer_format, F=transfer_format The byte stream consists of the bytes that are transferred as payload in
the SFTP protocol packets. The byte stream has one of the following
formats: stream, line, or record. All three
formats may have data consisting of text, non-text data, or a mixture of
these.
When writing an MVS dataset, a record that is longer than the maximum or
fixed record length will cause an error unless RECORD_TRUNCATE is
set to YES, in which case it will be truncated. When writing to
datasets with fixed record lengths, short records will be filled with binary
zeroes if you use the record transfer format and with blanks if you use the
line transfer format.
F=stream: The stream transfer format contains the data bytes of
the dataset but no structural information. If a dataset with a fixed record
length is transferred with the stream format and recreated with the same
record length, the record structure will be preserved. Variable length
records will not be recreated properly if transferred with the stream format.
F=line: The line transfer format is record-based. It uses
delimiter characters to mark the end of a record. The delimiter character
may be a Carriage Return or a Newline. When writing to or reading from
datasets with ASA control characters, a Form Feed is also treated as a
delimiter. The table below shows the values of these characters in EBCDIC
and ASCII. Data sent to SSH Tectia Server for IBM z/OS in the line transfer format must be
in EBCDIC or must be converted to EBCDIC during the transfer.
Delimiter EBCDIC ASCII
Name Dec Oct Hex Name Dec Oct Hex
\r Carriage Return CR 13 015 0x0D CR 13 015 0x0D
\n Newline NL 21 025 0x15 LF 10 012 0x0A
\f Form Feed FF 12 014 0x0C FF 12 014 0x0C
|
Note that ASCII does not have a NL character, instead LF is used to
delimit lines.
Avoid conversions that transform an ASCII Line Feed (LF/10/012/0x0A)
into an EBCDIC Line Feed (LF/37/045/0x25) or an EBCDIC Newline
(NL/21/025/0x15) into an ASCII Next Line (NEL/133/0205/0x85).
Be aware that sending a double delimiter, e.g. \r\n
or \n\r, to SSH Tectia Server for IBM z/OS will result in two
records. The transfer-line-delimiter and
file-line-delimiter advice string attributes can be used to
cause the SSH Tectia Server for IBM z/OS server or client program to convert between the
line delimiter conventions.
SSH Tectia Server for IBM z/OS sends \n as the Server Newline Convention
in the server initialization SFTP protocol message.
When transferring line format data to and from MVS files with ASA line
printer control characters, SSH Tectia Server for IBM z/OS will convert between the
control characters and line delimiter characters, as described in the
IBM document z/OS C/C++ Programming Guide, SC09-4765-03, Chapter
8.
To transfer records without changing the ASA code, use the stream
or record transfer format, or define the dataset using a DD card
and specify RECFM=FB or RECFM=VB.
Datasets transferred in the line transfer format and recreated on a
mainframe will not necessarily be identical.
F=record: The record transfer format is record-based. Each record
is preceded by a length field consisting of a 4-byte big-endian binary
integer, which indicates the number of data bytes in the record. Note that
the format is not the same as the record descriptor word in datasets with
RECFM=V or VB.
A dataset that is transferred with the record transfer format can be
recreated as any dataset type.
Default: line.
-
RECORD_TRUNCATE=yesno, U=yesno When a record truncation occurs while writing an MVS dataset, the system
will continue writing the dataset if RECORD_TRUNCATE is set to YES;
and the system will abort the transfer if RECORD_TRUNCATE is set to
NO or omitted.
Record truncation will occur if the length of a transferred record (after
codeset and line delimiter conversion) is larger than the maximum record
length of the dataset. Truncation can occur only when the transfer format is
LINE or RECORD. Note that the STREAM format does
not have any concept of records in transferred data and it will fill out
all records to their maximum length.
In the LINE transfer format, the length of a transferred record is
the number of characters up to a newline character.
In the RECORD format, the length of a transferred record is given
by the 4 byte binary length field which precedes the record.
The maximum length of a data set record depends on the dataset organization:
F and FB - LRECL
V and VB - LRECL-4
U - BLKSIZE
VSAM - MAXRECLEN
|
When SSH Tectia Server for IBM z/OS aborts writing a dataset because of record truncation, it
will complete the write operation during which the system observed the
truncation. It will write to disk one or more records, at least one of which
is truncated. The dataset is left on the system.
SSH Tectia Server for IBM z/OS may write a large amount of data in one write operation,
typically 32kB. Several records may be written in the last operation, some
of them truncated. Small files may be written to the end of the file, and
thus the resulting data set will be equivalent to one written with setting
RECORD_TRUNCATE=yes.
Note that some file transfer client programs do not always show the error or
warning messages from the server. Using the verbose mode (--verbose,
-v) may show more messages from the server.
Note: When SSH Tectia Server for IBM z/OS writes a dataset with
RECORD_TRUNCATE=yes, data loss may occur.
-
TRANSFER_FILE_CODESET=codeset, D=codeset The data in the dataset has the specified codeset. codeset
is the codeset name that is known to the iconv function of the
system performing the conversion. The available codesets can be listed by
invoking the iconv command at a USS prompt with the -l
option:
> iconv -l
Default: none
-
TRANSFER_CODESET=codeset, C=codeset During the transfer the data has the specified codeset. codeset
is the codeset name that is known to the iconv function
of the system performing the conversion. The available codesets can be
listed by invoking the iconv command at a USS prompt with the
-l option:
> iconv -l
Default: none
In the following example, a Windows SFTP client puts a file to a z/OS
dataset and gets a dataset from z/OS:
sftp> sput file.txt /ftadv:C=ISO8859-1,D=IBM-1047/__DATASET.TXT
sftp> sget /ftadv:D=IBM-1047,C=ISO8859-1/__DATASET.TXT file.txt
In sput, the Windows client tells the z/OS server that the
codeset during the transfer is ISO8859-1 and that the server should
store the dataset with the IBM-1047 codeset. In sget, the
Windows client tells the z/OS server that the codeset in the dataset is
IBM-1047 and it should be converted to ISO8859-1 before transferring the
data to the Windows client.
In the following example, a z/OS SFTP client puts a dataset to a Windows
file and gets a file from Windows:
sftp> sput /ftadv:C=ISO8859-1,D=IBM-1047/__DATASET.TXT file.txt
sftp> sget file.txt /ftadv:C=ISO8859-1,D=IBM-1047/__DATASET.TXT
In sput, the z/OS client is told that codeset in the dataset is
IBM-1047 and it should be converted to ISO8859-1 before transferring the
data to the Windows server. In sget, the z/OS client is told
that the file has the ISO8859-1 codeset during the transfer and the
dataset should be stored with the IBM-1047 codeset.
Note that the codeset information is always given to the host that is
capable of performing the conversion, in these cases z/OS.
-
TRANSFER_TRANSLATE_TABLE=translate_table, E=translate_table translate_table is the name of the table that specifies the codeset
conversion. If set, this attribute overrides the transfer codeset and file
codeset attributes. The table is always applied in the normal
direction, that is, the first character array is used for incoming
(from the line to the dataset) data and the second array for outgoing
data. If the opposite translation is needed, e.g. the dataset contains
ASCII and should be transferred as EBCDIC, the users (or their system
programmer) can prepare a table dataset with the character arrays in
reversed order (e.g. with the system utility CONVXLAT or by editing an
existing translate dataset).
-
TRANSFER_TRANSLATE_DSN_TEMPLATES=dsn_templates, A=dsn_templates dsn_templates specifies the search templates for the translate
table. Write '%T' to show the point where the translate table name (see above)
is to be inserted. Delimit the templates with a plus character. The data set name
templates must not contain slashes, instead they must be preceded by
two or three underscores. See Section Dataset Access.
The first translate table dataset that is found is used to perform the code
conversion.
Note: The translate table must translate line delimiters into EBCDIC NL
characters. See Section Transfer Format.
Default: none
-
TRANSFER_FILE_LINE_DELIMITER=line_delimiter, J=line_delimiter The transfer file line delimiter specifies the newline convention used
in the (source or destination) file. Possible values are:
J=mvs: The line delimiter used in the file is NL (\n, 0x0a).
J=unix: The line delimiter used in the file is NL (\n, 0x0a).
J=dos: The line delimiter used in the file is LFNL (\r\n, 0x0d0a).
J=mac: The line delimiter used in the file is LF (\r, 0x0d).
Default: none
-
TRANSFER_LINE_DELIMITER=line_delimiter, I=line_delimiter The transfer line delimiter specifies the newline convention used during
the file transfer. Possible values are:
I=mvs: The line delimiter during the transfer is NL (\n, 0x0a).
I=unix: The line delimiter during the transfer is NL (\n, 0x0a).
I=dos: The line delimiter during the transfer is LFNL (\r\n, 0x0d0a).
I=mac: The line delimiter during the transfer is LF (\r, 0x0d).
Default: none
In the following example, a Windows SFTP client puts a file to a z/OS
dataset and gets a dataset from z/OS:
sftp> sput file.txt /ftadv:I=dos,J=mvs/__DATASET.TXT
sftp> sget /ftadv:I=dos,J=mvs/__DATASET.TXT file.txt
In sput, the Windows client tells the z/OS server that the line
delimiter during the transfer is LFNL and that the server should store
the dataset with the NL line delimiter. In sget, the Windows
client tells the z/OS server that the line delimiter in the dataset is
NL and it should be converted to LFNL before transferring the data to
the Windows client.
In the following example, z/OS SFTP client puts a dataset to a Windows
file and gets a file from Windows:
sftp> sput /ftadv:I=dos,J=mvs/__DATASET.TXT file.txt
sftp> sget file.txt /ftadv:I=dos,J=mvs/__DATASET.TXT
In sput, the z/OS client is told that the line delimiter in the
dataset is NL and it should be converted to LFNL before transferring the
data to the Windows server. In sget, the z/OS client is told
that the file has the LFNL line delimiter during the transfer and the
dataset should be stored with the NL line delimiter.
Note that the line delimiter information is always given to the host
that is capable of performing the conversion, in these cases the z/OS
host.
-
TYPE=file_type, T=file_type The file type specifies the type of the dataset when the dataset is created.
T=hfs: The type of the created dataset is HFS.
T=po: The type of the created dataset is PDS.
T=poe: The type of the created dataset is PDSE.
T=vsam: The type of the created dataset is VSAM.
T=ps: The type of the created dataset is PS.
Default: po, if dataset name includes member, otherwise ps
-
RECFM=file_org, O=file_org file_org specifies the dataset organization. Possible values are all
valid combinations of the following letters:
F Fixed
V Variable
U Undefined
B Blocked
S Spanned or standard
M Machine line printer codes
A ASA line printer codes
|
Default: vb
-
LRECL=file_reclen, R=file_reclen Maximum record length or fixed record length.
Default: 4096, for VSAM, 80, if dataset organization is F or FB, otherwise 1024
-
BLKSIZE=file_blocklen, B=file_blocklen Maximum block size.
Default: none
-
SIZE=file_size, L=file_size Size estimate in bytes for dataset allocation.
Default: 1000000
-
DIRECTORY_SIZE=directory_size, M=directory_size Number of 256-byte records in the directory.
Default: 10
-
KEYOFF=key_offset Specifies the key offset. The position of the first byte of the key in
records of the specified VSAM dataset.
This option is not supported by the SSH Tectia Server for IBM z/OS file transfer client applications.
Default: none
-
KEYLEN=key_length Specifies the length in bytes of the keys used in the dataset.
This option is not supported by the SSH Tectia Server for IBM z/OS file transfer client applications.
Default: none
-
SPACE_UNIT=space_unit Unit of space allocation for a dataset.
Possible values are:
SPACE_UNIT=blks: Allocation unit is blocks.
SPACE_UNIT=cyls: Allocation unit is cylinders.
SPACE_UNIT=trks: Allocation unit is tracks.
SPACE_UNIT=avgreclen: Allocation unit is average record length.
This option is not supported by the SSH Tectia Server for IBM z/OS file transfer client applications.
Default: none
-
SPACE_UNIT_LENGTH=space_unit_length The size of the allocation unit if allocation unit (SPACE_UNIT) is set
to blocks (blks) or average record length (avgreclen).
This option is not supported by the SSH Tectia Server for IBM z/OS file transfer client applications.
Default: none
-
PRIMARY_SPACE=primary_space Primary space allocation for a dataset.
This option is not supported by the SSH Tectia Server for IBM z/OS file transfer client applications.
Default: none
-
SECONDARY_SPACE=secondary_space Secondary space allocation for a dataset.
This option is not supported by the SSH Tectia Server for IBM z/OS file transfer client applications.
Default: none
-
DATACLAS=data_class Specifies the data class of a dataset.
This option is not supported by the SSH Tectia Server for IBM z/OS file transfer client applications.
Default: none
-
MGMTCLAS=management_class Specifies the management class of a dataset.
This option is not supported by the SSH Tectia Server for IBM z/OS file transfer client applications.
Default: none
-
STORCLAS=storage_class Specifies the storage class of system managed storage.
This option is not supported by the SSH Tectia Server for IBM z/OS file transfer client applications.
Default: none
-
VOLUMES=volumes A plus sign (+) separated list of volumes a dataset will (or does, if
it already exists) reside on.
This option is not supported by the SSH Tectia Server for IBM z/OS file transfer client applications.
Default: none
-
UNIT=unit The type of device or group of devices that the dataset will (or does, if it already
exists) reside on (maximum length of 8). If an element exceeds its
maximum allowable length, it is truncated to that length.
It is also possible to specify a device address, although there is no need
for device addresses in this release. Precede a four digit address with an underscore.
This option is not supported by the SSH Tectia Server for IBM z/OS file transfer client applications.
Default: none
-
LIKE=like Specifies the name of a model dataset from which the RECFM,
BLKSIZE, and LRECL attributes are to be copied. The name
must be the full DSN of a cataloged dataset and must be preceded with three
underscores.
You must include the TYPE attribute when using LIKE unless
you are creating a PS data set and the model is a PS data set.
This option is not supported by the SSH Tectia Server for IBM z/OS file transfer client applications.
Default: none
-
REFDD=refdd Specifies the name of the JCL DD statement from which the attributes
are to be copied.
Note: The REFDD option is not available anymore in SSH Tectia Server for IBM z/OS
5.2.2 and later. REFDD is replaced by LIKE.
This option is not supported by the SSH Tectia Server for IBM z/OS file transfer client applications.
Default: none
-
PROFILE=file_transfer_profile, P=file_transfer_profile The file transfer profile specifies the named profile used for the
file transfer. The profile name is case-sensitive. With special
profile name P=% no profiles are used. This also prevents
profile matching based on file name.
Default: none
Below is an example of a filename that requests the transfer of a PDS member
with the line transfer format and codeset conversion from EBCDIC to an ASCII
codeset.
The following example requests the transfer of a dataset with the line
transfer format and codeset conversion using the translate table
USR1.SFTP.TCPXLBIN, if it exists, or TCPIP.SFTP.TCPXLBIN.
Different combinations of underscore and slash ("__", "_/",
"/_", or "//") in front of the filename indicate that the
file is an MVS dataset.
The example below names an HFS file to be transferred without changes.
Transfer mode is set to binary (X=bin) to avoid conversion and to
override any defaults set in the matching file transfer profiles or
environment files.
