Get subcommand—Copy files
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.
- 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
- See Specifying data sets and files for more information about naming conventions.
- See CD subcommand—Change the directory on the remote host and ACCt subcommand—Supply account information for more information about working directories.
- Get can be used with the PROXy subcommand to transfer files from a host on a primary connection to a host on a secondary connection. See PROXy subcommand—Execute FTP subcommand on secondary control connections for more information.
- See Using z/OS UNIX System Services named pipes for more information about storing data into named pipes.
- See LOCSIte subcommand—Specify site information to the local host and the UNIXFILETYPE (FTP client and server) statement information in z/OS Communications Server: IP Configuration Reference for more details about the UNIXFILETYPE configuration option.