Site Command

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. See Dataset and HFS File System 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 `F\|transfer_format=``FORMAT`.

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 z/OS SFTP client puts a dataset to a Windows file and gets a file from Windows:

sftp> lsite C=ISO8859-1 D=IBM-1047
sftp> sput //DATASET.TXT file.txt
sftp> sget file.txt //DATASET.TXT

The lsite command tells the z/OS client that codeset during transfer is ISO8859-1 and that the dataset is stored on the client with the IBM-1047 codeset. In sput, this means that the client converts the codeset from IBM-1047 to ISO8859-1 before sending the data. In sget, this means that the client converts the codeset from ISO8859-1 to IBM-1047 upon receiving 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 `s` (set user ID), is not allowed with command `site chmod`, because this command affects FTP-SFTP conversion performed by the FTP proxy. However, the `s` permission is allowed in the `sftpg3 chmod` command.

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 client tools for 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 Tectia client tools for z/OS will result in two records. The transfer-line- delimiter and file-line-delimiter advice string attributes can be used to cause the Tectia client tools for z/OS server or client program to convert between the line delimiter conventions.
Tectia client tools for 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, Tectia client tools for 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.

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 I and J must be specified for line delimiter conversion to happen.

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 `NL` (no label) and `BLP` (bypass label processing), which can be specified in JCL, are not allowed for this attribute in Tectia.

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. For detailed information on this attribute, see Low-Level Access.

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 client tools for 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.

Tectia client tools for 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 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 client tools for z/OS writes a dataset with `record_truncate=yes`, data loss may occur.

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 `transfer_mode` is not given but both `transfer_codeset` and `transfer_file_codeset` or `transfer_translate_table` are present conversions are performed.

File Transfers between z/OS Machines

When datasets are transferred between z/OS machines, the destination dataset is by default allocated with the same attributes as the source dataset. The attributes for the destination dataset can be overridden with the Site commands.

	Note
	If you change the dataset record format from VB to FB during transfer, you have to specify both `BLKsize` and `LRecl` for the destination dataset. Otherwise, an error may occur if the block size does not match the record length.

	Note
	Tectia Server for IBM z/OS does not support dataset allocation of `LARGE`, `EXTENDED`, or `COMPRESSED` formats. However, transfer is possible to pre-allocated datasets of these types.