The optional entries permit you to set special conditions for the operation and time frame of your file transfers. The optional entries deal with the type of data transfer:
compressed (COMPRESS)
encrypted (DATA-ENCRYPTION)
coding of the send file (DATA-TYPE)
write rules for the receive file (WRITE-MODE)
maximum record length (RECORD-SIZE)
tabulator expansion (TABULATOR)
- priority with which the file transfer (PRIORITY)
- time when the file transfer is to start (START)
- abortion of the file transfer (CANCEL)
- format of the target file (TARGET-FILE-FORMAT)
- encoding mode for file name and follow-up processing (FILE-NAME-ENCODING)
COMPRESS =
Defines whether the data in the send file is to be transferred in compressed form.
COMPRESS = *NONE
The data in the send file is transferred uncompressed.
COMPRESS = *BYTE-REPETITION
The data in the send file is transferred in compressed form. Compression affects consecutive bytes with identical contents. If file transfer in compressed form is not possible, the data is transferred in uncompressed form.
COMPRESS = *ZIP
The data in the send file is transferred in compressed form. Compression affects consecutive bytes with identical contents. If file transfer in compressed form is not possible, the data is transferred in uncompressed form.
WRITE-MODE =
Determine how the data is to be written into the receive file. Three options are available. You can
overwrite an already existing file in the receiving system.
set up a new file in the receiving system. If a file with the same name already exists in the receiving system, it will not be overwritten.
attach the transferred file to a file which already exists in the receiving system.
WRITE-MODE = *REPLACE-FILE
Overwrites the receive file from start of file. If the receive system already contains a file with this name, this file and where necessary its file attributes are overwritten. The previous contents of this file are thus completely erased. If the destination does not already exist, it is newly created.
WRITE-MODE = *NEW-FILE
Writes the receive file from start of file. If the receive system already contains a file with this name, this file is not overwritten and the send file is not transferred.
It should be noted that the receive file can already exist following the abortion of a file transfer request. It is not deleted in this case. If a new attempt is made, the request is rejected in the case of WRITE-MODE=*NEW-FILE, as the file already exists.
WRITE-MODE = *EXTEND-FILE
The receive file is extended from the end of file and written to end of file from this point. If the receive system does not yet include a file with this name, a new receive file is created. If the partner is a BS2000 system, then it depends on the system characteristic whether a request with the specification WRITE-MODE=EXTEND-FILE will be accepted or not.
The specification WRITE-MODE=*EXTEND-FILE is not permitted when transferring an entire PO or PDSE data set.
The specification WRITE-MODE=EXTEND-FILE is permitted in other cases only if:
send file and receive file have the same record formats,
for send files and receive files with fixed-length records the record length is the same, and
the buffer of the receive file can accept the largest record in the send file.
If a file transfer with WRITE-MODE=EXTEND-FILE is aborted permanently, the receive file retains the contents it had at the moment the transfer was terminated.
DATA-TYPE =
Coding used for data in the send file.
DATA-TYPE = *NOT-SPECIFIED
For openFT partners:
The specification is interpreted in the same way as DATA-TYPE=*BINARY if the partner system is an openFT (BS2000) system and the transferred file is neither a POSIX file nor a library member. Otherwise the specification is interpreted in the same way as DATA-TYPE=*CHARACTER.
For FTAM partners:
The send file type is unknown and is defined by the send system.
In z/OS, the specification is interpreted as DATA-TYPE = *CHARACTER.
DATA-TYPE = *USER
The send file contains structured binary data of variable record length. On Unix and Windows systems, a 2-byte field specifying the record length precedes each record. The maximum record length is 32767 bytes.
DATA-TYPE = *CHARACTER(...)
The send file is transferred as a text file. The receive system stores the file in its character code as text (i.e. a code conversion is performed on the file if necessary).
DATA-TYPE = *BINARY(...)
The send file is transferred as a binary file. The receive system stores the file as it was supplied by the send system. No code conversion takes place.
TRANSPARENT =
Specifies if the file is to be converted to a transparent format.
TRANSPARENT = *NO
No transparent format should be generated. If a file in transparent format is sent to a system that supports transparent transfer, then the file is automatically set up there again with its original attributes.
TRANSPARENT = *YES
This specification is only of use to retrieve files from a partner system that supports transparent transfer. z/OS can then act as temporary storage for such files. The partner system converts the send file into a transparent format and flags it internally as a text or binary file.
If a transparent file is to be returned to the partner, this must always take the form of a binary file with TRANSPARENT=*NO. The partner system automatically recognizes that it has received a transparent file and creates the file again with its original attributes. In the case of send requests, TRANSPARENT=*YES is ignored.
PRIORITY =
Priority with which the file transfer is initiated relative to other file transfers to the same remote system.
PRIORITY = *NORMAL
The file transfer has normal priority.
PRIORITY = *HIGH
The file transfer has high priority.
Requests with high priority executed via openFT protocols can interrupt normal priority requests for the time it takes to terminate those high priority requests. The interrupted requests are then restarted.
PRIORITY = *LOW
The file transfer has low priority.
START =
Time when the file transfer is to start. The application of the operand is accurate to approximately 5 minutes.
START = *SOON
The file transfer starts as soon as the resources required are available.
START = *EARLIEST(...)
The file transfer starts as soon as the resources required are available and not prior to the time specified. Up to this point the file transfer request is kept in a HOLD state. The date and time specified must not be further ahead than 22 days and 14 hours at the most. If the date and time specified have already passed, the file transfer is executed as if START=*SOON had been specified.
DATE =
Day when the file transfer is to be initiated.
DATE = *TODAY
The file transfer is initiated at the earliest on the day the command is issued.
DATE = *TOMORROW
The file transfer is initiated at the earliest on the day following issue of the command.
DATE = <date 8..10>
The file transfer is initiated on the calendar day specified. If the year is defined by four digits, it must be a year between 1960 and 2059. If only two digits are entered, an internal procedure extends the figure to four digits to denote a year between 1960 and 2059.
TIME = 00:00 / <time 1..8>
The file transfer is initiated at the earliest on the day following issue of the command.
CANCEL =
Specifies whether and when the file transfer is to be aborted. The application of the operand is accurate to approximately 5 minutes.
CANCEL = *NO
The file transfer is not to be deliberately aborted.
CANCEL = *AT(...)
The file transfer is to be aborted at a specific point in time.
The time specified must not
have already passed,
be more than 22 days and 14 hours after the specified start time,
be before or the same as the time specified in the START operand.
DATE =
Day when the file transfer is to be aborted.DATE = *TODAY
The file transfer is aborted on the day the command is issued.DATE = *TOMORROW
The file transfer is aborted on the day following issue of the command.DATE = <date 8..10>
The file transfer is aborted on the calendar day specified. If the year is defined by four digits, it must be a year between 1960 and 2059. If only two digits are entered, an internal procedure extends the figure to four digits to denote a year between 1960 and 2059.
TIME = 23:59 / <time 1..8>
The file transfer is aborted at the specified time on the chosen calendar day.
DATA-ENCRYPTION =
Determines whether or not the file transfer is to be encrypted.
DATA-ENCRYPTION = *NO
The file contents are not transmitted in encrypted form.
DATA-ENCRYPTION = *YES
The file contents are transmitted in encrypted form. If encryption is not available in the local system, the request is rejected with the error message FTR2111. If the partner system does not permit encryption, the request is rejected with the error message FTR2113.
DATA-ENCRYPTION = *ONLY-DATA-INTEGRITY
The data integrity of the transferred file content is checked using cryptographic means. In the case of openFT partners, this ensures that malevolent attempts to manipulate data during transfer are detected. If an error occurs, openFT performs a restart for asynchronous transfer requests.
If the partner system does not support data integrity checking (e.g. openFT < V8.1), the request is rejected.
In the case of requests with data encryption (*YES), data integrity is also automatically checked. Transfer errors in the network are automatically detected by the checking mechanisms of the transfer protocols used. Data integrity checking is not necessary for this.
RECORD-SIZE =
Maximum record length of the data that is to be transferred. If the maximum record length is specified explicitly then this value is used even if the record length is known from the catalog. If a record is transferred that exceeds this maximum record size, the request is aborted with
FTR2087 OPENFT: Request >>1<<. File structure error >>2<<
RECORD-SIZE = *NOT-SPECIFIED
The maximum record length is automatically determined from the catalog.
RECORD-SIZE = <integer 1..32756>
Maximum record length of the data that is to be transferred.
RECORD-FORMAT =
Indicates how the data is transferred on a file transfer to or from a partner.
RECORD-FORMAT = *STD
The record format specification is unchanged.
RECORD-FORMAT = *FIXED
The data is transferred in fixed length records.
RECORD-FORMAT = *VARIABLE
The data is transferred in variable length records.
RECORD-FORMAT = *UNDEFINED
The record length used for data transfer is not mapped to the real system. This means that the record length used for transfer is not identical to the record length in the real file.
In the case of text files, each record is terminated with an end-of-record character both during transfer and then in the real system. Binary files are stored as bit strings in the real system.
TABULATOR =
Specifies whether tab expansion is activated.
TABULATOR = *AUTO
The system uses tab expansion as required.
TABULATOR = *ON
Tab expansion is activated.
TABULATOR = *OFF
Tab expansion is deactivated.
TARGET-FILE-FORMAT =
This operand allows the format of the target file to be specified.
TARGET-FILE-FORMAT = *SAME
The format of the target file is to be the same as that of the send file.
TARGET-FILE-FORMAT = *BLOCK-ORIENTED
The file is to be stored with a block structure. As of openFT V11.0, support is only offered for creating a block-structure file in BS2000 and in PAM format. Creation of a blockstructure file in the remote system is only supported with the openFT protocol. Transfer must be performed in binary format. If the file type is specified neither in the command (DATA-TYPE) nor in the file catalog, binary transfer is automatically assumed.
The PAM file created depends on the pubset type (PAMKEY, DATA, DATA-4K). Each of the blocks is completely filled with the binary data stream received. If the data originally comes from a PAM file, the PAM keys are lost during transfer, and the file structure may be lost if the formats of the sending and receiving pubsets differ.
If openFT V10 is running on the receiving system, the file is created as a sequential file with an undefined record format. If older openFT versions are used in the receiving system, the request is rejected.
TARGET-FILE-FORMAT = *SEQUENTIAL (...)
The format of the target file is to be sequential. This also makes it possible to read blockstructure files and index sequential files sequentially. The reading of PAM files and ISAM files in BS2000 is supported in openFT version 11.0:
A PAM file is mapped to a binary sequential file with an undefined record format. The transfer is compatible with standard FTP transfer in BS2000.
An ISAM file is mapped to the corresponding sequential format (fixed or variable record format). The contents of the ISAM keys is retained in the records, but the key positions are lost.
Specifying *SEQUENTIAL for a sequential send file has no effect.
RECORD-FORMAT =
The record format can be specified for a sequential target file.
RECORD-FORMAT = *SAME
The record format of the target file is to be the same as that of the send file.
RECORD-FORMAT = *UNDEFINED
The record format of the target file is to be undefined. The record structure of the send file is lost. At least one block is written for each transfer unit on target systems running BS2000 or z/OS. This can significantly increase the required disk storage space, for instance if the send file is made up of variable length records.
FILE-NAME-ENCODING =
Specifies the encoding mode for file name and follow-up processing.
FILE-NAME-ENCODING = *TRANSPARENT
Specification of the remote file name and follow-up processing for the remote system in transparent mode (compatible to the previous versions).
FILE-NAME-ENCODING = *CHARACTER
Specification of the remote file name and follow-up processing for the remote system in character mode. They are interpreted according to the character code of the remote system, i.e. for Unix partners according to the openFT operating parameter option (ftmodo -fnccs) that has been set there.
FILE-NAME-ENCODING=*CHARACTER is only permitted for openFT partners as of openFT V12.1.
If the FT request is free of errors from the perspective of the local system, then the FT system outputs the following report as an FT request confirmation:
FTR0000 OPENFT: Request (&00) accepted
(&00) in this case, is the Identification of the FT request that assigns the local FT system to each FT request. Using this FT request ID, you can cancel the FT request (NCANCEL command), or you can get information on the status of the FT request (NSTATUS
command). The FT request ID may consist of a maximum of ten decimals. You can, of course, access your FT requests, even if you do not know the FT request ID (see the information following Description of the short output of NSTATUS).
If the local system cannot accept the request, it issues the relevant error message (e.g. due to a syntax error in the command or because the user is not authorized to access the send or receive file). The FT messages are explained in the manual "openFT (z/OS) - Installation and Operation".
If the request has been accepted by the local system but cannot be executed, you will find the relevant error message in the result list, provided you have specified that a result list is to be created (see the LISTING parameter).
Information on the asynchronous messages issued by the local system on termination of the file transfer request is given in the section “Messages and return codes automaticallyissued by openFT (z/OS)”.
If neither a result list nor asynchronous messages provide information on the success or failure of the request, you can use the logging function to determine whether the request has been completed.