MGet subcommand

Purpose

Use the MGet subcommand to copy multiple files from a remote host to your local host and create a corresponding number of local files.

Format


         .--------------.                   
         V              |                   
>>-MGet----foreign_file-+--+------------+----------------------><
                           '-(--REPLACE-'

Parameters

foreign_file: Specifies the name of the file to be retrieved from the remote host.
Because more than one file can be copied with the MGet subcommand, the foreign_file parameter of the MGet subcommand can be repeated many times, with each foreign_file separated by a blank space. You can use special characters for pattern matching when specifying the foreign_file with the MGet subcommand. These characters are dependent on the foreign host FTP server.
REPLACE: Causes a data set on your local host to be overwritten if it already exists. If the data set 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 data set already exists and you specify the REPLACE parameter, the data in the file is overwritten, but the file is not reallocated; the local data set retains its existing characteristics.

Restriction: If you have configured UNIXFILETYPE=FIFO, the REPLACE parameter is not allowed.

Examples

The following is a sample entry and response that displays after using the MGet subcommand for multiple z/OS® UNIX files.

cd '/u/user121/ftp.example'
 
 >>>CWD '/u/user121/ftp.example'
 250 HFS directory /u/user121/ftp.example is the current working directory
 Command:
 mget file1 file2 file3
 >>>PORT 9,67,112,25,4,90
  200 Port request OK.
 >>>NLST file1
 125 List started OK
 250 List completed successfully.
 >>>PORT 9,67,112,25,4,91
 200 Port request OK.
 >>>NLST file2
 125 List started OK
 250 List completed successfully.
 >>>PORT 9,67,112,25,4,92
 200 Port request OK.
 >>>NLST file3
 125 List started OK
 250 List completed successfully.
 >>>PORT 9,67,112,25,4,93
 200 Port request OK.
 >>>RETR file1
 125 Sending data set /u/user121/ftp.example/file1
 250 Transfer completed successfully.
 3464 Bytes transferred in 1.031 seconds.  Transfer rate 3.36 kbytes/sec.
 >>>PORT 9,67,112,25,4,94
 200 Port request OK.
 >>>RETR file2
 125 Sending data set /u/user121/ftp.example/file2
 250 Transfer completed successfully.
 3993 Bytes transferred in 0.923 seconds.  Transfer rate 4.33 kbytes/sec.
 >>>PORT 9,67,112,25,4,95
 200 Port request OK.
 >>>RETR file3
 125 Sending data set /u/user121/ftp.example/file3
 250 Transfer completed successfully.
 3993 Bytes transferred in 0.791 seconds.  Transfer rate 5.05 kbytes/sec.
 Command:

The following is a sample entry and response that displays after using the MGet subcommand using a wildcard character in the file name.

Command:
mget file*
>>>PORT 9,67,113,57,5,123
200 Port request OK.
>>>NLST file*
125 List started OK
250 List completed successfully.
Mget file1 (Yes|No|Quit|Stop prompting)? s
>>>PORT 9,67,113,57,5,124
200 Port request OK.
>>>RETR file1
125 Sending data set /u/user31/file1
250 Transfer completed successfully.
164 bytes transferred in 0.310 seconds.  Transfer rate 0.53 Kbytes/sec.
>>>PORT 9,67,113,57,5,125
200 Port request OK.
>>>RETR file2
125 Sending data set /u/user31/file2
250 Transfer completed successfully.
164 bytes transferred in 0.270 seconds.  Transfer rate 0.61 Kbytes/sec.
>>>PORT 9,67,113,57,5,126
200 Port request OK.
>>>RETR file3
125 Sending data set /u/user31/file3
250 Transfer completed successfully.
164 bytes transferred in 0.280 seconds.  Transfer rate 0.59 Kbytes/sec.
Command:

Results:

When you use the MGet subcommand, FTP might truncate data records and you might lose data 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, FTP truncates the received data set.
- The data set name already exists at the client and the logical record length (LRecl) of the data set at the client is less than the LRecl of the transmitted data set, FTP truncates the transmitted data set.
  You can encounter this situation when you use MGet with the REPLACE option.
If the name specified for foreign_file is not acceptable to your local host, the file is not transferred. To 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 you specify one or more incorrect foreign files with the MGet subcommand, an error message specifying the incorrect foreign file is displayed. All correct foreign files are retrieved, regardless of any incorrect foreign files, and do not need to be reissued.
z/OS UNIX file names require special handling for certain special characters. Except for single quote (’), double quote (”), or blank ( ), all special characters that the operating system requires to be preceded by an escape character in commands issued to the shell must be preceded by the backslash (\) escape character.
The MGet subcommand is not applicable to generation data groups (GDGs).
The MGet subcommand 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.
If the data set is migrated, it is replaced regardless of the replace option.
The MGet subcommand removes all directory information from remote file names. This causes all the files to be saved in the same z/OS UNIX file system directory when transferring into a z/OS UNIX file system. The directory structure of the remote host will not be preserved.
If the LISTSUBdir option is not specified on the SITE subcommand and the LISTSUBDIR statement is not specified in the server FTP.DATA file, the default is as if LISTSUBdir option was specified on the SITE subcommand.
If the z/OS FTP server has the NOLISTSUBdir option specified on the SITE subcommand or has LISTSUBDIR FALSE specified in the server FTP.DATA file, an mget * command gets only the files in the current directory.
The LISTSUBdir option applies to z/OS UNIX file operations only; MVS™ data set operations are not affected.
When UNIXFILETYPE=FIFO is configured and the local directory is a z/OS UNIX directory, the following apply:
- New files are created as named pipes.
- Transfers into existing z/OS UNIX regular files will fail.
- Whether the named pipe is new or existing, FTP cannot write to the named pipe until another process on the z/OS client host opens the named pipe for reading. The z/OS FTP client waits up to the number of seconds specified by the FIFOOPENTIME value for another process to open the named pipe.
- FTP waits up to the number of seconds specified by the FIFOIOTIME value for each write to the named pipe to complete. The client does not block during writes unless it writes to the named pipe much faster than the named pipe reader reads from the pipe. If the client cannot write any data to the named pipe for the number of seconds specified by the FIFOIOTIME value, it fails the file transfer.
- Data that is transferred into an existing named pipe is appended to the contents of the named pipe.

Guideline: When you transfer files into a z/OS UNIX directory, the configured UMASK value determines the new file permissions. Code the UMASK statement in the FTP.DATA file or issue the LOCSIte UMASK subcommand to configure the UMASK value.