The Site commands are the recommended way for controlling file transfer when both the client and server host are running Tectia.
For command descriptions, see the site and
lsite command in sftpg3(1) and the
--dst-site
and --src-site
options
in scpg3(1).
When giving the command, either the abbreviation or the full command can be used. For example, the following two commands accomplish the same thing:
sftp> site X=bin sftp> site transfer_mode=bin
The available SITE parameters are:
A|transfer_translate_dsn_templates=
TEMPLATES
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 dataset name templates must not contain slashes, instead
they must be preceded by two or three underscores.
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 |
Default: none
automount=YES|NO|IMMED
If set to YES
and a normal allocation fails because a
dataset is not online, Tectia will allocate it and request the system to mount
it. This requires that the user has read permission to the
SSZ.MOUNT
facility.
If set to NO
, offline datasets are not
mounted automatically.
If set to IMMED
, Tectia will not attempt the normal
allocation, it will request the system to mount the dataset immediately.
Default: no
AUTOMount
Equal to automount=yes
.
autorecall=YES|NO
Defines whether datasets migrated by a storage manager are recalled automatically.
Default: yes
AUTORecall
Equal to autorecall=yes
.
B|BLKsize|BLOCKSIze=
SIZE
Maximum block size.
Default: none
BLocks
Specifies that the space allocation unit is blocks. Equal to
space_unit=blks
.
C|transfer_codeset=
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> site C=ISO8859-1 D=IBM-1047 sftp> sput file.txt //DATASET.TXT sftp> sget //DATASET.TXT file.txt
The site command tells the z/OS server that the codeset during transfer is ISO8859-1 and that the dataset is stored on the server with the IBM-1047 codeset. In sput, this means that the server converts the codeset from ISO8859-1 to IBM-1047 upon receiving the data. In sget, this means that the server converts the codeset from IBM-1047 to ISO8859-1 before sending the data.
Note | |
---|---|
The codeset information is always given to the host that is capable of performing the conversion, in this case the z/OS host. |
chmod
[-R
] [-f
] [-v
] OCTAL-MODE
[file
...]
chmod
[-R
] [-f
] [-v
] [ugoa
] [+-=
] [rwx
] [file
...]
With Unix files, sets file permissions of the specified file or files to the bit
pattern OCTAL-MODE
(with 3 digits) or changes
permissions according to the symbolic mode [ugoa][+-=][rwx]
.
Use only one of the following combinations: r|w|x|rw|rx|wx|rwx
.
Note | |
---|---|
Permission bit |
The chmod
subcommand must be the only or the last
part in the site command.
Options:
-R
Recursively changes files and directories.
-f
Uses silent mode (error messages are suppressed).
-v
Uses verbose mode (lists every file processed).
CONDdisp=CATLG|UNCATLG|KEEP|DELETE
Specifies the disposition of the output file when a file transfer ends prematurely (the client or server are alive but disconnected from the other end; for example, when pressing the CTRL+C in the client).
Note | |
---|---|
If the client (when transferring to local or client side) or the server (when transferring to remote or server side) dies, they will have no control over the disposition. |
The options have the following effects, depending of the file type (MVS or HFS):
CATLG
: an MVS dataset is retained and its
name is cataloged. An HFS file is retained.
UNCATLG
: the name of an MVS dataset is
removed from the catalog but it is retained. An HFS file is retained.
KEEP
: an MVS dataset is retained (if
cataloged it will be still cataloged, if uncataloged it will be still
uncataloged). An HFS file is retained.
DELETE
: the name of an MVS dataset is
removed from the catalog and the space allocated for it is released. An HFS
file is deleted.
Default: CATLG
CYlinders
Specifies that the space allocation unit is cylinders. Equal to
space_unit=cyls
.
D|transfer_file_codeset=
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
DATAClass|dataclas=
CLASS
Specifies the data class of a dataset.
Default: none
dataset_sequence_number=
NUMBER
Identifies the relative position of a dataset on a tape volume.
Default: System default
defer=YES|NO
Specify whether dataset allocation is postponed from allocation phase to opening the dataset.
If set to yes
dataset allocation is postponed
until dataset is opened.
If set to no
dataset is allocated in allocation phase.
Default: no
defer
Specifies that dataset allocation is postponed until dataset is
opened. Equal to
defer=yes
.
E|transfer_translate_table=
TABLE
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).
expiry_date=
YYDDD|YYYYDDD
Specifies the expiration date for a new dataset. On and after this date, the operating system can delete or write over the dataset.
Default: System default
F|transfer_format=
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 Tectia ConnectSecure 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
Tectia ConnectSecure will result in two records. The transfer-line-
delimiter
and file-line-delimiter
advice string
attributes can be used to cause the Tectia ConnectSecure server or client program
to convert between the line delimiter conventions.
Tectia ConnectSecure 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, Tectia ConnectSecure 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
.
file_status=NEW|MOD|SHR|OLD
Defines the status of a dataset. If entered, the value will be used
when allocating the dataset. This attribute corresponds to the first value
in the DISP
parameter of the JCL DD statement.
Default: NEW
for datasets that will be created,
SHR
for datasets that will be read only, otherwise
OLD
.
fixrecfm=
LENGTH
The dataset organization is set to FB
and the
fixed record length is set to LENGTH
.
Default: none
I|transfer_line_delimiter=
CONVENTION
The transfer line delimiter specifies the newline convention used in the data that is transferred over the connection. Possible values are:
I=mvs
: The line delimiter on the connection is NL (\n
, 0x15
). If the data
is converted from EBCDIC to ASCII, the NL becomes a LF (\n
, 0x0A
).
I=mvs-ftp
: When writing to a dataset, only the LF (\n
, 0x0A
)
control codes are considered as an End Of Line. Any CR
(\r
, 0x0D
) codes are preserved as data in the record.
When writing datasets with ASA printer control characters, the first character on each line is used as the ASA character.
Do not use this when reading datasets.
I=unix
: The line delimiter on the connection is LF (\n
, 0x0A
).
I=dos
: The line delimiter on the connection is CRLF (\r\n
, 0x0D 0x0A
).
I=mac
: The line delimiter on the connection is CR (\r
, 0x0D
).
Default: none
Note | |
---|---|
The line delimiter information should be given to the host that is capable of performing the conversion, like a host with a Tectia. |
J|transfer_file_line_delimiter=
CONVENTION
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
, 0x15
). When
writing to a dataset, also the CR (\r
, 0x0D
) code is considered as the End of Line.
J=mvs-ftp
: When reading MVS datasets, each record in the dataset is
treated as a line. The transfer line delimiter is appended to the
record. Any control characters in the record data are preserved.
When reading datasets with printer control characters, the control characters are preserved in the output.
If codeset conversion is specified either by the translation table
(set by the site parameter E
), or by the both site parameters of
C
and D
, the appended delimiter is the delimiter specified in the
transfer site parameter I
, in the codeset site parameter C
, or
in the translation table site parameter E
. If no codeset
conversion is requested, the delimiter is defined by the codeset of
the dataset. By default it is EBCDIC.
You can specify codesets by using the parameter D
without the
parameter C
. For example, to have a DOS delimiter in the Unicode
(x'000D000A'
), appended to the records, set the site parameters
"I=DOS,J=MVS-FTP,D=UCS-2
", and to have a Unix delimiter in the
ISO Latin 1 (x'0A'
), set the "I=UNIX,J=MVS-FTP,D=ISO8859-1
".
Do not use this when writing datasets.
J=unix
: The line delimiter used in the file is LF (\n
, 0x0A
).
J=dos
: The line delimiter used in the file is CRLF (\r\n
, 0x0D 0x0A
).
J=mac
: The line delimiter used in the file is CR (\r
, 0x0D
).
Default: none
Note | |
---|---|
The line delimiter information should be given to the host that is capable of performing the conversion, like a host with a Tectia. Line delimiter conversion is implemented for single byte codesets only. Both parameters of |
In the following example, a z/OS Tectia SFTP client sends a dataset to a Windows host and copies the file back from Windows. The codeset is also converted:
sftp> lsite I=dos J=mvs sftp> lsite C=IBM-437 D=IBM-1047 sftp> sput //DATASET.TXT file.txt sftp> sget file.txt //DATASET.COPY.TXT
In the sput command, the z/OS client inserts a NL (0x15
) character
after each record. The line delimiter conversion converts all NL:s to
CRLF (0x0D 0x0A
) characters, which remain unchanged in the codeset
conversion.
In the sget command, the CRLF line delimiters are converted to LF characters, which are converted to NL characters in the codeset conversion. Each NL character (and CR character, if there are any in the data) causes the current record to be written out and a new record started.
keylen=
LENGTH
Specifies the length in bytes of the keys used in the dataset.
Default: none
keyoff=
OFFSET
Specifies the key offset. The position of the first byte of the key in records of the specified VSAM dataset.
Default: none
L|size=
SIZE
Size estimate in bytes for dataset allocation.
Default: 1000000
label_type=SL|NSL|SUL|LTM|AL|AUL
The type of the label for the dataset. This attribute corresponds to
the first value in the LABEL
parameter of the JCL DD
statement.
Note | |
---|---|
The values |
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 dataset and the model is
a PS dataset.
Default: none
M|DIrectory|directory_size=
SIZE
Number of 256-byte records in the directory.
Default: 10
MGmtclass|mgmtclas=
CLASS
Specifies the management class of a dataset.
Default: none
NOAUTOMount
Equal to automount=no
.
NOAUTORecall
Equal to autorecall=no
.
NORMdisp=CATLG|UNCATLG|KEEP|DELETE
Specifies the dataset disposition to be used after a file transfer
that ends normally. This attribute corresponds to the second value in the
DISP
parameter of the JCL DD statement.
Default: CATLG
NOTRAILingblanks
Equal to trailing_blanks=no
.
NOTRUNcate
Equal to record_truncate=no
.
O|RECfm=
RECFM
RECFM
specifies the dataset organization.
The 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
P|profile=
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
PRImary|primary_space=
SPACE
Primary space allocation for a dataset.
Default: none
R|LRecl=
LENGTH
Maximum record length or fixed record length.
Default: 4096
, for VSAM, 80
, if
dataset organization is F or FB, otherwise 1024
retention_period=
DAYS
The retention period in days. After the retention period, the dataset expires and the operating system can delete or write over the dataset.
Default: System default
S|staging=NO|YES
Specify whether staging is to be used in the SFTP server when accessing a file or dataset.
If set to no
, staging is not used.
If set to yes
, staging is used, when needed.
If this parameter is not set, the server decides whether staging will be used or not.
SECondary|secondary_space=
SPACE
Secondary space allocation for a dataset.
Default: none
space_unit=
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.
Default: none
space_unit_length=
LENGTH
When space_unit=blks
or space_unit=avgreclen
,
specifies the size of the space allocation unit.
Default: 100 with space_unit=avgreclen
, none with space_unit=blks
STOrclass|storclas=
CLASS
Specifies the storage class of system managed storage.
Default: none
svc99_text_units=
STRING
Dynamic allocation arguments that override or are added to arguments from other file transfer attributes.
Default: none
T|type=
TYPE
The file type specifies the type of the dataset when the dataset is created. The available values are:
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=esds
: The type of the created dataset is VSAM ESDS.
T=ksds
: The type of the created dataset is VSAM KSDS.
T=rrn
: The type of the created dataset is VSAM RRN.
T=ps
: The type of the created dataset is PS.
Default: po
, if dataset name includes member, otherwise ps
TRacks
Specifies that the space allocation unit is tracks. Equal to
space_unit=trks
.
trailing_blanks=YES|NO
Specify whether to preserve trailing blanks in a transferred dataset.
If set to yes
trailing blanks will be transferred.
This can be used, for example, to preserve the structure of fixed format
datasets.
If set to no
trailing blanks will be stripped.
Default: no
TRAILingblanks
Equal to trailing_blanks=yes
.
TRUNcate
Equal to record_truncate=yes
.
U|record_truncate=YES|NO
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 dataset record depends on the dataset organization:
F and FB - LRECL V and VB - LRECL-4 U - BLKSIZE VSAM - MAXRECLEN
When Tectia ConnectSecure 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.
Tectia ConnectSecure 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 dataset 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 Tectia ConnectSecure writes a dataset with
|
unit=
UNIT
The name of device or group of devices that the dataset will reside on
(or does reside on, if it already exists). The maximum length of
UNIT
is 8 characters. If the value exceeds the
maximum length, it is truncated to 8 characters.
It is also possible to specify a device address. Precede a four digit address with an underscore.
Default: none
unit_count=
NUMBER
Specifies the number of devices for the dataset. This attribute
corresponds to the second value in the UNIT
parameter of
the JCL DD statement.
Default: System default
unit_parallel=YES|NO
Asks the system to mount all the volumes for the dataset in parallel.
This attribute corresponds to the character 'P
' in the
second value in the UNIT
parameter of the JCL DD statement.
Default: System default
volumes=
VOLUMES
A plus sign (+) separated list of volumes a dataset will reside on (or does reside on, if it already exists).
Default: none
volume_count=
NUMBER
Specifies the maximum number of volumes that an output dataset
requires. This attribute corresponds to the volume count value in the
VOLUME
parameter of the JCL DD statement.
Default: System default
X|transfer_mode=
MODE
The transfer mode specifies whether codeset and line delimiter conversions are performed. The available 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 |