Get subcommand

Purpose

Use the Get subcommand to copy a file from the remote host to your local host.

Format


>>-Get--foreign_file--+------------+--+------------+-----------><
                      '-local_file-'  '-(--REPLACE-'

Parameters

foreign_file

Specifies the name of the file to be retrieved from the remote host.

local_file

Specifies the name of the local file created as a result of the Get subcommand.

If the current local working directory is a PDS, local_file is the name of the member in the PDS. If the current local working directory is a data set prefix, the local file is a sequential data set with the local_file name appended to the current local working directory. If the current local working directory is a z/OS® UNIX file system directory, the local file is a z/OS UNIX file in that directory.

You can override the use of the current local working directory in the local file name by specifying the local_file value as a complete data set name enclosed in single quotation marks (’). If local_file is not specified, the local_file name is the same as the foreign_file name.

The following apply when the local_file value specifies a new file in a z/OS UNIX directory:

The UNIXFILETYPE configuration option specifies whether the FTP client creates a regular file or a named pipe.
The UMASK configuration option specifies the file permissions of the new file or named pipe.

Rule: When the local_file value specifies an existing named pipe in a z/OS UNIX directory, you must configure UNIXFILETYPE FIFO before you start the file transfer.

(REPLACE

Causes the local_file value on your local host to be overwritten if the value is an existing MVS™ data set or z/OS UNIX regular file. If the MVS data set or z/OS UNIX regular file already exists, and you do not use the (REPLACE parameter, the existing data set is not overwritten. A message informing you of this is displayed.

If the local_file value is an existing MVS data set and you specify the (REPLACE option, the data in the file is overwritten, but not reallocated; the local data set retains its existing characteristics.

If the local_file value is an existing z/OS UNIX named pipe, the (REPLACE option is not allowed.

Results:

FTP uses either the characteristics of the local file, if it exists, or uses the values specified with the LOCSIte subcommand. Characteristics of the transmitted (foreign file) data set are unknown.
When you use the Get subcommand, FTP might truncate data records and you might lose data, if one of the following occurs:
- If you are creating a new data set at the client and the value of LRecl, as shown by the LOCSTat command, is a value less than the LRecl of a received data set, then FTP truncates the received data set.
- If the data set name already exists at the receiving site and the logical record length (LRecl) of the data set at the receiving site is less than the LRecl of the transmitted data set, then FTP truncates the transmitted data set.
  You could also encounter truncated data records or lost data when you use the Get subcommand with the REPLACE option.
  A Get subcommand that the system issues for the following foreign files erases the contents of the existing local data set:
  - An empty foreign file
  - A foreign file that does not exist
  - A foreign file that another process holds
- If FTP does not support directory content transfers in partitioned data sets, it is not possible to FTP load modules.
- If the data set is migrated, it is replaced regardless of the replace option.
When the local file is a named pipe on your local host, the following apply:
- FTP cannot open the file until you start a process to read from the named pipe. If FTP is the first process to open the named pipe, it blocks until another process opens the named pipe for reading, or until the FIFOOPENTIME timer expires.
- The remote file is appended to the local file.
If the name specified for local_file is not acceptable to your local host, the file is not transferred.
To get a file from the remote host, you must have a defined working directory on that host and you must have read privileges to the files in this working directory.
If the data set has been preallocated, you must specify DSORG=PS on the DCB statement in the JCL.
When a PDS or PDSE member is transmitted, the user data associated with the PDS member is also transferred to the directory on the target host if the following conditions are true;
- Data is in block or compressed data transfer mode
- Data has a representation type of EBCDIC
- Transfer is from one MVS directory to another
No PDS directory information is transferred if the member is null (empty).