Your browser does not allow this site to store cookies and other data. Some functionality on this site may not work without them. See Privacy Policy for details on how we would use cookies.

SSH Tectia

Advice String

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

/ftadv:advstr/realfilename

where advstr is the advice string and realfilename is the dataset name or a filename to be further processed by the server.

The advice string is a sequence of name=value pairs delimited by commas. Some names have a one-letter abbreviation for easier usability.

The advice string names and abbreviations are as follows:

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]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 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 SSH 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 SSH Tectia client tools for z/OS server or client program to convert between the line delimiter conventions.

SSH 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, SSH 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.

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

SSH 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 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]Note

When SSH Tectia client tools for 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]Note

The line delimiter information is always given to the host that is capable of performing the conversion, in these cases the z/OS host.

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 Dataset and HFS File System Access.

The first translate table dataset that is found is used to perform the code conversion.

[Note]Note

The translate table must translate line delimiters into EBCDIC NL characters. See TRANSFER_FORMAT=transfer_format, F=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]Note

The codeset 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.

Default: none

KEYLEN=key_length

Specifies the length in bytes of the keys used in the dataset.

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.

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

Default: none

PRIMARY_SPACE=primary_space

Primary space allocation for a dataset.

Default: none

SECONDARY_SPACE=secondary_space

Secondary space allocation for a dataset.

Default: none

DATACLAS=data_class

Specifies the data class of a dataset.

Default: none

MGMTCLAS=management_class

Specifies the management class of a dataset.

Default: none

STORCLAS=storage_class

Specifies the storage class of system managed storage.

Default: none

VOLUMES=volumes

A plus sign (+) separated list of volumes a dataset will (or does, if it already exists) reside on.

Default: none

UNIT=unit

The name of device or group of devices that the dataset will (or does, if it already exists) reside on (maximum length of 8). 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

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.

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

Example Advice Strings

The following examples show advice strings for various situations.

Example 1

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.

/ftadv:D=IBM-1047,C=ISO8859-1,F=line/__personal.cntl/idlist
Example 2

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.

/ftadv:F=line,E=SFTP,A=___USR1.%T.TCPXLBIN+___TCPIP.%T.TCPXLBIN/__DATA1.FILE1
Example 3

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.

/ftadv:X=bin,T=HFS,F=stream/profcopy
Example 4

The next example uses the named file transfer profile myprofile. The advice string also sets the dataset codeset to ISO8859-15. This value overwrites the value specified in the profile.

/ftadv:P=myprofile,d=iso8859-15/testfile
[Note]Note

Advice strings can also be used with directory names in file transfer GUIs. With advice strings, file transfer can be controlled in the GUI. For example in the Windows GUI, if you use the directory /ftadv:P=WIN/____path/to/current/directory/, all file transfers to and from the directory /path/to/current/directory use the advice string /ftadv:P=WIN/. This means that all file transfers use the named profile WIN (see File Transfer Profiles). Note also that the HFS root directory must be given as ____ (four underscores) because of the naming convention introduced in the product.

[Note]Note

Advice string parameters are case-insensitive, with the exception of file transfer profile names. For example, P=win and P=WIN point to different profiles.

Example 5

This example uses the LIKE attribute when creating an MVS PS data set with the name "userid.TEST.CPY1". The server copies RECFM, LRECL, and BLKSIZE from the PDS "COMP.DATA.CNTL".

/ftadv:like=___COMP.DATA.CNTL,t=PS/__TEST.CPY1

This example uses the LIKE attribute when creating a PDSE, "COMP.CODE". The record characteristics are copied from a PDS, "COMP.SOURCE". The PDSE is created when adding the first member, PRG1. The new PDS is estimated to need 15 MB space.

/ftadv:like=___COMP.SOURCE,t=POE,size=15000000/____COMP.CODE(PRG1)

===AUTO_SCHEMA_MARKUP===