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)
- 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)
- date of last change (LAST-CHANGE-DATE)
- transfer of protection attributes (PROTECTION)
- 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 (e.g. with FTAM partners), 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 (e.g. with FTAM partners), 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 (this is only possible with SAM files in BS2000).
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 permitted in BS2000 partners if:
the send file is a SAM file,
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.
DATA-TYPE = *USER
The send file contains structured binary data of variable record length. 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).
Only SAM files and PLAM library members can be transferred with DATA-TYPE=*CHARACTER.
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.
Any file that is not a SAM file or a PLAM library member is always transferred as a binary file.
TRANSPARENT =
Specifies if the file is to be converted to a transparent format.
If a file is received in transparent format then openFT (BS2000) ≥ V6.0 automatically sets it up with its original attributes.
TRANSPARENT = *NO
No transparent format should be generated.
TRANSPARENT = *YES
The file should be sent transparently. openFT will reject the transfer of a file in transparent format in the following cases:
with simultaneous specification of WRITE-MODE=*EXT (FTR2042 or FTR2166)
if a file in transparent format is to be picked up and the partner system doesn’t support this function (FTR2040),
if the receive file is a library member (FTR2087 or FTR2210).
if a file is transferred in transparent format to a library member (FTR2216 or FTR2096).
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.
This entry is valid if the user has the appropriate authorization for the entry.
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 Request (&00). File structure error(&02) or
% FTR2210 Request (&00). Remote system: File structure error(&02)
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.
Binary files with fixed record lengths (in which the file consists of records of equal lengths) can only be transferred to an FTAM partner if this supports variable length records for binary files.
RECORD-FORMAT = *VARIABLE
The data is transferred in variable length records.
Binary files in user format (in which a record consists of a record length field and the data itself) can only be transferred in the form of variable length records to an FTAM partner if this supports variable length records for binary files.
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 (as SAM-U files in BS2000 systems).
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.
PROTECTION =
Controls the transfer of protection attributes if the partner is a BS2000 system.
PROTECTION = *STD
Only the default file attributes are transferred (behavior up to V10).
PROTECTION =*SAME
The protection attributes USER-ACCESS, ACCESS, BASIC-ACL, EXPIRATION-DATE, FREE-FOR-DELETION and DESTROY are additionally transferred. This requires openFT as of V11 to be used in the partner system.
If the openFT instances of the two partners are using different versions, only those file attributes are transferred that are supported in both versions.
In all cases, the following requirements apply
the openft protocol is used for transfer
the source and target file are DMS files
the target file is not a file generation
the target file is created or overwritten
the transfer is not carried out in transparent mode.
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.
LAST-CHANGE-DATE =
Controls whether the last change date of the send file (i.e. date+time) is accepted for the receive file.
LAST-CHANGE-DATE = *STD
The current time is accepted as the change date of the receive file. This corresponds to the behavior up to openFT V11.0.
LAST-CHANGE-DATE = *SAME
The change date of the send file is accepted as the change date of the receive file. This function is supported only for the openFT protocol. In BS2000 systems it is also necessary to use OSD V8.0 or higher.
If the target system does not support acceptance of the change date or if no modification date is sent be the source system, no request with LAST-CHANGE-DATE=*SAME is executed and an error is reported.
If acceptance of the change date matches the default behavior of the target system, the parameter is ignored.
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 (CANCEL-FILE-TRANSFER command), or you can get information on the status of the FT request (SHOW-FILE-TRANSFER 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 SHOW-FILE-TRANSFER).
If the file transfer was successful, openFT outputs an the following asynchronous message as a result message (if the user process is still active and allows asynchronous messages):
% FTR0005 Request (&00). File '(&02)' transferred
Command return codes
For a list of the possible return codes, see the tables in chapter “Command return codes for file transfer and file management”.