MVSGet subcommand

Purpose

Use the MVSGet subcommand to transfer MVS™ data sets from a z/OS® FTP server to a z/OS FTP client without knowing the details of the server data set allocation. The MVS data set can be one of the following data set types:

z/OS physical sequential data set
z/OS PDS or library
z/OS generation data set reference

For a physical sequential data set, MVSGet works like a combination of the LOCSite and Get subcommands. For a partitioned data set, MVSGet works like a combination of the LOCSite, LMkir (like <remote directory>, and MGet * subcommands. All the data set members are transferred. Regardless of the type of data set that is transferred, FTP reconfigures the client to allocate the local data set with the same attributes as the remote data set.

Format


>>-MVSGet--remote_mvs_dataset--+-------------------+------------>
                               '-local_mvs_dataset-'   

>--+-------------+---------------------------------------------><
   '-(REAllocate-'

Parameters

remote_mvs_dataset: Specifies the name of the data set to be retrieved from the remote MVS host. If the server working directory is a data set prefix, the remote file is a data set with the remote_mvs_dataset name appended to the server working directory. You can override the server working directory in the remote file name by specifying the remote_mvs_dataset value as a complete data set name that is enclosed in single quotation marks.
local_mvs_dataset: Specifies the name of the local MVS data set that is created as a result of the MVSGet subcommand. If the local working directory is a data set prefix, the local file is a data set with thelocal_mvs_dataset name appended to the local working directory. You can override the local working directory in the local file name by specifying the local_mvs_dataset value as a complete data set name that is enclosed in single quotation marks. If the local_mvs_dataset parameter is not specified, the value is the same as the remote_mvs_dataset value.
REAllocate: Causes the MVS data set on your local MVS host to be deleted and reallocated with the attributes of the remote MVSdata set, if the local MVS data set is an existing data set. If the MVS data set already exists and you do not use the REAllocate parameter, the existing data set is not deleted and reallocated, the MVSGet subcommand fails, and a message is displayed.

The following example shows using the MVSGet subcommand to retrieve a PDS data set.

mvsget 'user1.remote.pds' 'user1.local.pds' (REAllocate                         
EZA1701I >>> XDSS 'user1.remote.pds'                                            
200-LASTREF=2011/12/16 DSEMPTY=FALSE                                            
200 SITE PDSTYPE=PDS RECFM=VB BLKSIZE=6233 DIRECTORY=27 LRECL=256 PRIMARY=1 SECO
NDARY=1 TRACKS EATTR=SYSTEM                                                     
EZZ9815I local site variables have changed                                      
EZA2245I "USER1.LOCAL.PDS" created.                                             
EZA2081I Local directory name set to partitioned data set USER1.LOCAL.PDS       
EZA1701I >>> PWD                                                                
257 "'USER1.'" is working directory.                                            
EZA1701I >>> CWD 'user1.remote.pds'                                             
250 The working directory "USER1.REMOTE.PDS" is a partitioned data set          
EZA1701I >>> PORT 127,0,0,1,4,5                                                 
200 Port request OK.                                                            
EZA1701I >>> NLST *                                                             
125 List started OK.                                                            
250 List completed successfully.                                                
EZA1701I >>> PORT 127,0,0,1,4,6                                                 
200 Port request OK.                                                            
EZA1701I >>> RETR NEW1                                                          
125 Sending data set USER1.REMOTE.PDS(NEW1)                                     
250 Transfer completed successfully.                                            
EZA1617I 134 bytes transferred in 0.010 seconds. 
Transfer rate 13.40 Kbytes/sec. 
EZA1701I >>> PORT 127,0,0,1,4,7 
200 Port request OK.                                                            
EZA1701I >>> RETR NEW2                                                          
125 Sending data set USER1.REMOTE.PDS(NEW2)                                     
250 Transfer completed successfully.                                                    
EZA1617I 134 bytes transferred in 0.010 seconds. 
Transfer rate 13.40 Kbytes/sec.                                                                               
EZA2581I Local HFS directory is /u/user1.                                      
EZA1701I >>> CWD 'USER1.'                                                       
250 "USER1." is working directory name prefix
EZA2108I Confidence=High for MVSGET of USER1.LOCAL.PDS

The following example shows using the proxy MVSGet subcommand to transfer a library between two servers.

proxy mvsget 'user.linklibe' 'user1.local.pdse' (REAllocate                     
EZA1701I >>> PWD                                                                
257 "'USER2.'" is working directory. 
EZA1701I >>> XDSS 'user.linklibe'                                               
200-LASTREF=2011/12/16 DSEMPTY=FALSE                                            
200 SITE PDSTYPE=PDSE RECFM=U BLKSIZE=32760 DIRECTORY=3 LRECL=256 PRIMARY=20 SEC
ONDARY=1 CYLINDERS EATTR=SYSTEM                                                 
EZA1701I >>> XDSS 'user1.local.pdse'                                            
200-LASTREF=2011/12/16 DSEMPTY=FALSE                                            
200 SITE PDSTYPE=PDSE RECFM=U BLKSIZE=32760 DIRECTORY=3 LRECL=256 PRIMARY=20 SEC
ONDARY=1 CYLINDERS EATTR=SYSTEM                                                 
EZA1701I >>> DELE 'user1.local.pdse'                                            
250 USER1.LOCAL.PDSE deleted.                                                   
EZA1701I >>> SITE PDSTYPE=PDSE RECFM=U BLKSIZE=32760 DIRECTORY=3 LRECL=256 PRIMA
RY=20 SECONDARY=1 CYLINDERS EATTR=SYSTEM                                        
200 SITE command was accepted                                                   
EZA1701I >>> MKD 'user1.local.pdse'                                             
257 "'USER1.LOCAL.PDSE'" created.                                               
EZA1701I >>> CWD 'user1.local.pdse'                                        
250-The working directory may be a load library                            
250 The working directory "USER1.LOCAL.PDSE" is a partitioned data set     
EZA1701I >>> PWD                                                           
257 "'USER1.'" is working directory.                                       
EZA1701I >>> CWD 'user.linklibe'                                           
250-The working directory may be a load library                            
250 The working directory "USER.LINKLIBE" is a partitioned data set        
EZA1701I >>> XLMT QUERY 0 *                                                
250 PDSE 12787712 - send next command for load module transfer             
EZA1701I >>> XLMT PDSE 12787712                                            
250 PDSE 12787712 - send next command for load module transfer             
EZA1701I >>> PASV                                                          
227 Entering Passive Mode (127,0,0,1,4,19)                                 
EZA1701I >>> PORT 127,0,0,1,4,19                                           
200 Port request OK.                                                       
EZA1701I >>> RETR load module                                              
125-Transferring load module                                               
125 DCB 32768 32760                                                        
EZA1701I >>> XLMT DCB 32768 32760                              
                                                               
250 DCB saved, send next command for load module transfer      
EZA1701I >>> STOR load module                                  
125 Transferring load module                                   
250 Transfer completed successfully.                           
250 Transfer completed successfully.                           
EZA1701I >>> CWD 'USER2.'                                      
250 "USER1." is working directory name prefix                  
EZA1701I >>> CWD 'USER1.'                                      
250 "USER1." is working directory name prefix

Restrictions:

The MVSGet subcommand supports only these data set types.
- z/OS physical sequential data set
- z/OS PDS or library data set
- z/OS generation data set reference
The MVSGet subcommand does not support transfer of an empty PDS or library. You can use the LMkdir subcommand with the (like parameter for that purpose.
The MVSGet subcommand supports checkpointing for block mode restart of an interrupted file transfer. However, if you transfer a PDS or library data set, the target data set is deleted if the transfer fails. You cannot use the REStart subcommand to restart these transfers.
The target generation data set must be a positive reference and cannot be a library data set.
If the source data set is a PDS, the target generation data set must be referenced with its absolute name.
The MVSGet subcommand does not support specifying the local data set as a ddname.
If the source data set is in physical sequential extended format, the target data set is allocated as if the DSNTYPE parameter with SYSTEM value was configured. If the system default DSNTYPE value is not EXTREQ or EXTPREF, the source data set might exceed the architecture size limitation of the system default DSNTYPE value and the transfer fails.
FTP can determine only approximate values for the primary allocation, secondary allocation, and space type, but it uses an allocation that is large enough to contain the data. For complete control over the initial allocation, use the LOCSIte subcommand with the Get subcommand instead of the MVSGet subcommand.
If the target tape data set does not exist on the tape volume, the transfer sometimes succeeds with the MVSGet subcommand. However, the MVSGet subcommand does not support reallocating an existing tape data set.
For PDS and library data sets, FTP must read the directory of the source data set at least twice when using the MVSGet subcommand.

Results:

If the target local data set already exists on the FTP client without REALLOCATE specified, the MVSGet subcommand fails.
FTP ignores the GLob subcommand toggle when using the MVSGet subcommand. MVSGet works as if the GLob subcommand is always toggled on.
The MVSGet subcommand of a PDS or library data set gets the data set as a whole data set and gets all the members of it to the local PDS or library data set. The MVSGet subcommand is not prompted before transferring each member, regardless of whether the PROMpt subcommand toggle is set to interactive mode.
If an FTP file transfer ends prematurely for a physical sequential data set, the new data set that is created on the local host is disposed according to the CONDDISP configuration on the local host. See LOCSIte subcommand—Specify site information to the local host or CONDDISP (FTP client and server) statement in z/OS Communications Server: IP Configuration Reference for more information about the CONDDISP configuration option. However, if you transfer a PDS or library data set, the new data set that is created on the local host is deleted regardless of the CONDDISP configuration if the transfer ends prematurely.
The MVSGet subcommand changes the FTP client configuration so that the subcommand can allocate the local data set as the remote data set.
The MVSGet subcommand can determine only an approximate size of the source data set when allocating the target data set, but the target data set is large enough to complete the transfer. For complete control over the initial allocation, use the LOCSIte subcommand with the Get subcommand.
If the remote source data set is migrated, the server inspects the AUTORECALL setting to decide whether to recall the data set or to fail the request. If AUTORECALL is set to true, FTP attempts to recall the data set; otherwise, it fails the request. Similarly, if the remote data set is not mounted, the server inspects the AUTOMOUNT setting to decide whether to mount the data set or to fail the request. If AUTOMOUNT is set to true, the server attempts to mount the data set; otherwise, it fails the request. You can change the AUTOMOUNT and AUTORECALL settings of the server with the SITE subcommand. Choosing AUTOMOUNT or AUTORECALL can cause a long delay because the server waits for the data set to become available.

Requirements:

The local and remote data sets must be MVS data sets.
The remote FTP server must be z/OS V2R1 Communications Server or later releases.
Users must have READ access to the source data set and ALTER access to the target data set to use the MVSGet subcommand.

Guidelines:

An FTP client can specify one or more of the Storage Management Subsystem (SMS) classes to manage characteristics that are associated with or assigned to data sets. See “Specifying values for new data sets - Storage Management System(SMS)” in z/OS Communications Server: IP Configuration Guide for more information about SMS classes.
The MVSGet subcommand can determine only an approximate size of the source data set when allocating the target data set. For complete control over the initial allocation, use the LOCSIte subcommand with the Get subcommand.
The MVSGet subcommand changes the FTP client configuration as if the user issued the LOCSIte and LCd subcommands. Restart the FTP client to reinstate the initial configuration or use the LOCSIte and LCd subcommands to configure the client.