The Application Programming Interface › How to Use API Member Names › file_option

file_option

Indicates how the transferred data is to be processed by the receiving system. For file transfers only.

For general transfers, the range of values is as follows:

CREATE

Create a new file on the receiving system.

APPEND

Append the transferred data to an existing file on the receiving system.

REPLACE

Replace an existing file on the receiving system.

For library-type transfers, the range of values is as follows:

CREATE

For systems supporting PDS:

Creates the PDS on the receiving system and adds the transferred members. If the PDS already exists, the transfer fails.

Note: The transfer will not fail if the PDS already exists if CREATEDELETE=YES is specified and the remote z/OS system has been set up to allow the PDS to be recreated through the default table (XCOMDFLT) or destination member (XCOMCNTL).

For systems supporting directories:

If the directory does not exist the reaction depends on the value of CREATE_DIRECTORIES in the global file:

• If CREATE_DIRECTORIES=YES, the transfer creates the directory and adds the transferred members.
• If CREATE_DIRECTORIES=NO, the transfer fails.

ADD/APPEND

For systems supporting PDS:

Adds or replaces transferred members on the receiving system. If the PDS does not exist, the transfer fails.

For systems supporting directories:

The value of CREATE_DIRECTORIES determines the outcome of the transfer on the remote system, as follows:

• If CREATE_DIRECTORIES=YES and the directory does not exist, then the directory is created and the transfer members are added to this directory. If the directory does exist, the transfer members are added to this existing directory.
• If CREATE_DIRECTORIES=NO and the directory does not exist, then the transfer fails. If the directory does exist, then the transfer adds the transfer members to the directory.

REPLACE

Adds or replaces transferred members. If the directory does not exist, the reaction depends on the value of CREATE_DIRECTORIES in the global file:

• If CREATE_DIRECTORIES=YES, the transfer will create the directory and add the transferred members.
• If CREATE_DIRECTORIES=NO, the transfer will fail

Default: CREATE

Note: When creating a file on an IBM mainframe system, some additional information may be necessary. For more information, see the RECORD_FORMAT, BLKSIZE, VOLUME, and UNIT parameters.