COPY command and keyword definitions

Required keywords are described first, followed by optional keywords.

COPY

The COPY command initiates volume copies and in parallel, backs up the source ICF catalogs that point to data sets on the source volumes being cloned.

Required: Yes
Restrictions: None

CATWORK-DSN ( mask )

Specifies a mask used to derive data sets names for catalog backup data sets dynamically allocated during the COPY step.

The mask must include an asterisk (*) as one qualifier. Db2 Cloning Tool will create data sets by substituting two eight-byte qualifiers in place of the provided asterisk. Hence, because 17 bytes (8+the dot+8) of the name will be generated, the user is responsible for the resolved names not exceeding 44 characters (e.g., CATWORK-DSN(CKZ.CATWORK.*) will cause data sets to be created such as: CKZ.CATWORK.UCATBKUP.BKP00001

The asterisk in the mask does not need to be the lowest level qualifier. (e.g., CATWORK(CKZ.CWORK.*.DATA)

Default: None
Required: Required if USERCATALOGS, USERCATALOGS-NOBACKUP, USERCATALOGS-BACKUPFIRST, or USERCATALOGS-DDN is specified.
Restrictions: None
Short form: CWDSN

JOURNAL-DSN ( data set name )

or JOURNAL-DDN ( ddname )

Optional syntax is: JRNL-DSN or JRNL-DDN

This parameter supplies either the data set name of the Db2 Cloning Tool journal file, or a DD name assumed via the JCL to point at a journal data set.

If multiple Db2 Cloning Tool setups are used for different volume groups, DO NOT use the same journal data set. Each Db2 Cloning Tool 'application' needs a different journal data set.

The journal is used to pass information between Db2 Cloning Tool steps (e.g., from the COPY step to the RENAME step). Therefore, as noted in the JCL comments, it must be cataloged in the COPY step when first created, and referenced as OLD in subsequent steps.

Do not delete the data set in the last step, in case restarts or reruns need journal information. It is preferable to delete and replace the data set only at the fresh start of a COPY.

Default: None
Required: Yes
Restrictions: None
Short form: JRNL-DSN JRNL-DDN

USERCATALOGS ( sourcecat1 [ ( sourcevolser1 ) ] targetcat1 [ ( targetvolser1 ) ] … [ , sourcecatn [ ( sourcevolsern ) ] targetcatn [ ( targetvolsern ) ] ] )

This parameter specifies the source ICF catalogs that data sets from source (from) volumes are cataloged in, and the corresponding target catalog that renamed volume data sets are to be cataloged in.

ICF catalog names are specified in pairs of source and target. For each renamed data set, the USERCATALOGS list is searched for the catalog the source volume data set was cataloged in. The renamed data set is cataloged in the corresponding target catalog.

The source ICF catalogs specified must include all ICF catalogs that any data set being copied and renamed could be cataloged in.

Target ICF catalogs that are used to catalog the renamed data sets cannot reside on a target volume during the timeframe from the volume copy through the completion of the RENAME step, unless the TARGET-UCATS-ON-TARGET-VOLUMES(Y) keyword of the COPY command is specified. If desired, you can move the target ICF catalog(s) from the target volume prior to the volume copy, and move the target ICF catalog(s) back to the target volume after the RENAME has completed.

If you specify the sourcevolser with the source ICF catalog name, the source catalog will be backed up from its copy on the corresponding target volume. The sourcevolser that is specified is the source volume where the source ICF catalog resides. The volume where the source ICF catalog resides must be included as one of the source volumes being copied. The VOLSER of the source ICF catalog is specified because when Db2 Cloning Tool does the volume pairing, there is no guarantee the source volume will be paired to the same target volume for every cloning. Db2 Cloning Tool uses the volume pairing information to determine the target volume VOLSER that corresponds with the specified source volume VOLSER.

The targetvolser value can be specified with the target ICF catalog name to indicate the target volume that corresponds with the location of the copied source ICF catalog. This value is only used if TARGET-UCATS-ON-TARGET-VOLUMES(Y) has been specified. The targetvolser value is used with some cloning scenarios when the volume pairing is not done via a COPY command to allow the proper renaming of the cloned ICF catalogs.

Default: None
Required: Yes
Restrictions: Mutually exclusive with NOUSERCATALOGS, USERCATALOGS-BACKUPFIRST, USERCATALOGS-NOBACKUP, and USERCATALOGS-DDN.
Short form: UCATS

USERCATALOGS-NOBACKUP ( sourcecat1 [ ( sourcevolser1 ) ] targetcat1[ ( targetvolser1 ) ] … [ , sourcecatn [ ( sourcevolsern ) ] targetcatn [ ( targetvolsern ) ] ] )

This parameter specifies source catalogs that data sets from source (from) volumes are cataloged in, and the corresponding target catalog that renamed volume data sets are to be cataloged in.

ICF catalog names are specified in pairs of source and target. For each renamed data set, the USERCATALOGS list is searched for the ICF catalog the source volume data set was cataloged in. The renamed data set is cataloged in the corresponding target catalog.

The source ICF catalogs specified must include all ICF catalogs that any data set being copied and renamed could be cataloged in.

The source catalogs will not be backed up by COPY. The source catalogs will be backed up when UCATOPTIONS BACKUP is run. The backup of the source catalogs with UCATOPTIONS BACKUP must happen prior to running the RENAME command. If VOLSER is specified for the source catalog, UCATOPTIONS BACKUP will make its backup from the copies of the source catalogs on the target volumes.

Note: The ICF catalog backup can be postponed until after COPY by using the USERCATALOGS-NOBACKUP keyword. However, if you choose to postpone the backup, the source ICF catalog information being backed up needs to be in synchronization with the contents of the copied volumes. If USERCATALOGS-NOBACKUP is used (so the source ICF catalogs are backed up after COPY by UCATOPTIONS BACKUP), the user must ensure that the source ICF catalogs are logically at the same point in time as when the volumes were copied.

If VOLPAIRSDEVN-NOCLIP or VOLPAIRSDEVN-NOCLIP-DDN are used with USERCATALOGS-NOBACKUP, VOLOPTIONS TARGETOFFLINECLIP must be run before UCATOPTIONS BACKUP which must be run before the RENAME command.

Default: None
Required: Yes
Restrictions: Mutually exclusive with NOUSERCATALOGS, USERCATALOGS, USERCATALOGS-DDN, and USERCATALOGS-BACKUPFIRST.
Short form: UCATSNB

USERCATALOGS-BACKUPFIRST ( sourcecat1 targetcat1 … [ , sourcecatn targetcatn ] )

This parameter specifies source ICF catalogs that data sets from source (from) volumes are cataloged in, and the corresponding target catalog that renamed volume data sets are to be cataloged in.

The source ICF catalogs specified must include all ICF catalogs that any data set being copied and renamed could be cataloged in.

The source ICF catalogs will be backed up before the target volumes are processed by the COPY command.

Default: None
Required: Yes
Restrictions: Mutually exclusive with NOUSERCATALOGS, USERCATALOGS, USERCATALOGS-DDN, and USERCATALOGS-NOBACKUP.
Short form: UCATSBF

USERCATALOGS-DDN(ddname)

This parameter specifies the DD name which points to a file containing user catalog pairs. The pairs are the same format as in the USERCATALOGS keyword.

USERCATALOGS-DDN must have an LRECL of 80, and must not contain sequence numbers in columns 73 - 80.

Default: None
Required: Yes
Restrictions: Mutually exclusive with USERCATALOGS, NOUSERCATALOGS, USERCATALOGS-NOBACKUP, and USERCATALOGS-BACKUPFIRST.
Short form: UCATSDDN

NOUSERCATALOGS

Specifies that the COPY will not include the backing up of any ICF catalogs.NOUSERCATALOGS is intended to be used for the following cases:

When creating a copy of the source volumes where the target volumes are strictly for backup purposes (there is no intent of renaming the data sets on the target volumes).
When performing a volume cloning using interim volumes. Refer to Cloning scenarios for more information about this type of cloning.

RENAME is not possible when NOUSERCATALOGS is used.

Default: None
Required: No
Restrictions: Mutually exclusive with USERCATALOGS, USERCATALOGS-DDN, USERCATALOGS-NOBACKUP and USERCATALOGS-BACKUPFIRST.
Short form: NOUCATS

FROM-STORAGEGROUP ( storgrp1 | storgrpmask1 …[ , storgrpn | storgrpmaskn ] )

Specifies the input volumes to be copied from one or more SMS storage group definitions or storage groups matching a mask. All volumes from the storage groups specified will be copied, except any volumes excluded via the EXCLUDE-FROM-VOLSER parameter.

An input (source) storage group may only be specified or referred to once per execution. Db2 Cloning Tool will match source volumes with target volumes, in keeping with the requirement that each pair is in the same ESS subsystem and LSS (if ESS FlashCopy® V1, same partition if RVA), same track format, same volume size, and the target volume size is equal to or greater than the source volume size.

If KEEP-VOLUMES-SEQUENCE(Y) is specified, make sure to specify the desired source and target volume pairs so that they have the same sequence number. The assignment of sequence numbers is described in detail in How Db2 Cloning Tool pairs volumes when the KEEP-VOLUMES-SEQUENCE keyword is specified.

Default: None
Required: Required only if DATA-MOVER(PGM(ADRDSSU)) or DATA-MOVER(PGM(EMCSNAP)) is specified (FlashCopy or SnapShot).
Restrictions: Valid only with DATA-MOVER(PGM(ADRDSSU)) and DATA-MOVER(PGM(EMCSNAP))
Short form: FRS

FROM-USER-STORAGEGROUP ( storgrp1 | storgrpmask1 …[ storgrpn | storgrpmaskn ] )

or FROMUSERSTORAGEGROUP

Specifies the input volumes to be copied from one or more user storage group definitions or storage groups matching a mask. All online volumes from the storage groups specified will be copied, except any volumes excluded via the EXCLUDE-FROM-VOLSER parameter.

An input (source) storage group may only be specified or referred to once per execution. Db2 Cloning Tool will match source volumes with target volumes, in keeping with the requirement that each pair is in the same ESS subsystem and LSS (if ESS FlashCopy V1, same partition if RVA), same track format, same volume size, and the target volume size is equal to or greater than the source volume size.

Default: None
Required: Required only if DATA-MOVER(PGM(ADRDSSU)) or DATA-MOVER(PGM(EMCSNAP)) is specified (FlashCopy or SnapShot).
Restrictions: Valid only with DATA-MOVER(PGM(ADRDSSU)) and DATA-MOVER(PGM(EMCSNAP))
Short form: FRUS

FROM-VOLSER ( volser1 | volmask1 …[ , volsern | volmaskn ] )

Optional syntax: FROMVOLSER

Specifies the input volumes to be copied, either by discrete volume serial numbers or volume serial masks (e.g., TSO*). See the EXCLUDE-FROM-VOLSER keyword to exclude VOLSERs from a list.

Db2 Cloning Tool will match source volumes with target volumes, in keeping with the requirement that each pair is in the same ESS subsystem and LSS (if ESS FlashCopy V1, same partition if RVA), same track format, same volume size, and the target volume size is equal to or greater than the source volume size.

Default: None
Required: Required only if DATA-MOVER(PGM(ADRDSSU)) or DATA-MOVER(PGM(EMCSNAP)) is specified (FlashCopy or SnapShot).
Restrictions: If DATA-MOVER(PGM(NONE)) is used, a volume mask cannot be specified.
Short form: FRV

FROM-VOLSER-DDN( ddname )

Optional syntax: FROMVOLSERDDN

This parameter specifies the DD name that points to a file containing FROM VOLSER volumes. The volumes are the same format as in the FROM-VOLSER keyword.

FROM-VOLSER-DDN must have an LRECL of 80, and must not contain sequence numbers in columns 73 - 80.

Default: None
Required: Required only if DATA-MOVER(PGM(ADRDSSU)) or DATA-MOVER(PGM(EMCSNAP)) is specified (FlashCopy or SnapShot).
Restrictions: If DATA-MOVER(PGM(NONE)) is used, a volume mask cannot be specified.
Short form: FRVDDN

TO-STORAGEGROUP ( storgrp1 | storgrpmask1 …[ , storgrpn | storgrpmaskn ] )

Optional syntax: TOSTORAGEGROUP

Specifies that output volumes needed to pair with input volumes are to be selected from one or more SMS storage groups or storage groups matching a mask. All volumes from the storage groups specified are target candidates, except any volumes excluded via the EXCLUDE-TO-VOLSER parameter.

If FROM-USER-STORAGEGROUP is used, but FROM-STORAGEGROUP or TO-USER-STORAGEGROUP are not used, Db2 Cloning Tool will attempt to match volumes using the same positioned storage group names that are listed in TO-STORAGEGROUP. If KEEP-VOLUMES-SEQUENCE(Y) is also specified, then each FROM-USER-STORAGEGROUP volume will be paired with the TO-STORAGEGROUP volume that has the same positioned storage group name. If that is not possible, then a pairing error occurs.

If FROM-STORAGEGROUP is used, Db2 Cloning Tool will attempt to match volumes using the same positioned storage group names listed in TO-STORAGEGROUP. If a hardware difference or other issue results in a FROM-STORAGEGROUP volume that does not match its TO-STORAGEGROUP counterpart, the TO-STORAGEGROUP volume is skipped. Db2 Cloning Tool then attempts to match the FROM-STORAGEGROUP volume with the next TO-STORAGEGROUP volume in the list. If KEEP-VOLUMES-SEQUENCE(Y) is also specified, then each FROM-STORAGEGROUP volume is paired with the TO-STORAGEGROUP volume that has the same positioned storage group name. If that is not possible, then a pairing error occurs.

Default: None
Required: Required only if DATA-MOVER(PGM(ADRDSSU)) or DATA-MOVER(PGM(EMCSNAP)) is specified (FlashCopy or SnapShot).
Restrictions: Valid only with DATA-MOVER(PGM(ADRDSSU)) and DATA-MOVER(PGM(EMCSNAP))
Short form: TOS

TO-USER-STORAGEGROUP ( storgrp1 | storgrpmask1 …[ , storgrpn | storgrpmaskn ] )

Optional syntax: TOUSERSTORAGEGROUP

Specifies that output volumes needed to pair with input volumes are to be selected from one or more user storage groups or storage groups matching a mask. All online volumes from the storage groups specified are target candidates, except any volumes excluded via the EXCLUDE-TO-VOLSER parameter.

If FROM-STORAGEGROUP is used but FROM-USER-STORAGEGROUP or TO-STORAGEGROUP are not used, Db2 Cloning Tool will attempt to match volumes using the same positioned storage group names that are listed in TO-STORAGEGROUP. If KEEP-VOLUMES-SEQUENCE(Y) is also specified, then each FROM-USER-STORAGEGROUP volume is paired with the TO-STORAGEGROUP volume that has the same positioned storage group name. If that is not possible, then a pairing error occurs.

If FROM-USER-STORAGEGROUP is used, Db2 Cloning Tool attempts to match volumes using the same positioned storage group names listed in TO-USER-STORAGEGROUP. If the FROM-USER-STORAGEGROUP volume does not match its TO-USER-STORAGEGROUP counterpart because of hardware differences or other issues, the TO-USER-STORAGEGROUP volume is skipped. Db2 Cloning Tool then attempts to match the FROM-USER-STORAGEGROUP volume with the next TO-USER-STORAGEGROUP volume in the list. If KEEP-VOLUMES-SEQUENCE(Y) is also specified, then each FROM-USER-STORAGEGROUP volume is paired with the TO-USER-STORAGEGROUP volume that has the same positioned storage group name. If that is not possible, then a pairing error occurs.

Default: None
Required: Required only if DATA-MOVER(PGM(ADRDSSU)) or DATA-MOVER(PGM(EMCSNAP)) is specified (FlashCopy or SnapShot).
Restrictions: Valid only with DATA-MOVER(PGM(ADRDSSU)) and DATA-MOVER(PGM(EMCSNAP))
Short form: TOUS

TO-VOLSER ( volser1 | volmask1 …[ , volsern | volmaskn ] )

Optional syntax: TOVOLSER

Specifies target volumes to be paired with input volumes.

Default: None
Required: Required only if DATA-MOVER(PGM(ADRDSSU)) or DATA-MOVER(PGM(EMCSNAP)) is specified (FlashCopy or SnapShot).
Restrictions: If DATA-MOVER(PGM(NONE)) is used, a volume mask cannot be specified.
Short form: TOV

TO-VOLSER-DDN( ddname )

Optional syntax: TOVOLSERDDN

This parameter specifies the DD name that points to a file containing to volser volumes. The volumes are the same format as in the TO-VOLSER keyword.

TO-VOLSER-DDN must have an LRECL of 80, and must not contain sequence numbers in columns 73-80.

Default: None
Required: Required only if DATA-MOVER(PGM(ADRDSSU)) or DATA-MOVER(PGM(EMCSNAP)) is specified (FlashCopy or SnapShot).
Restrictions: If DATA-MOVER(PGM(NONE)) is used, a volume mask cannot be specified. Mutually exclusive with TO-VOLSER.
Short form: TOVDDN

USERSGDEFS-DDN ( ddname )

Specifies a DD name which points to a file containing the user storage group definitions that will be used by the FROM-USER-STORAGEGROUP and TO-USER-STORAGEGROUP keywords. The USERSGDEFS-OFFSET keyword is used to specify the offsets of the fields within the records.

The file must have an LRECL of 80. A comment record is denoted by a blank or * in column 1 or a /* in columns 1 and 2.

Default: None
Required: Required only if FROM-USER-STORAGEGROUP or TO-USER-STORAGEGROUP are specified.
Restrictions: Used only if FROM-USER-STORAGEGROUP or TO-USER-STORAGEGROUP are specified.

USERSGDEFS-OFFSETS ( INCLEXCL(nn), SGNAME(nn), VOLSER(nn) )

Specifies the offsets in the record that the fields will be found. These fields are used for the user storage group definitions that will be used by the FROM-USER-STORAGEGROUP and TO-USER-STORAGEGROUP keywords.

The offsets specified can be from 1 to 72 inclusive, with 1 being the first character position in the record.

INCLEXCL specifies the offset where the 1-character include/exclude indicator can be found. A value of blank or I indicates an include definition. A value of E or X indicates an exclude definition.

SGNAME specifies the offset where the 8-character storage group name can be found.

VOLSER specifies the offset where the 6-character volser or volser mask can be found.

For example: Using USERSGDEFS-OFFSETS( VOLSER(1), INCLEXCL(8), SGNAME(10) ) and USERSGDEFS-DDN file containing the records:

SRC00*   SGSRC01
SRC006 E SGSRC01
TGT01* I SGTGT01
TGT02* I SGTGT01
TGT015 X SGTGT01
TGT025 X SGTGT01

FROM-USER-STORAGEGROUPS( SGSRC01 ) would resolve to all online DASD volumes that match the mask SRC00* except for SRC006 which would be excluded.

TO-USER-STORAGEGROUPS( SGTGT01 ) would resolve to all online DASD volumes that match the masks TGT01* and TGT02* except that TGT015 and TGT025 would be excluded.

Default: None
Required: Required only if FROM-USER-STORAGEGROUP or TO-USER-STORAGEGROUP are specified.
Restrictions: Used only if FROM-USER-STORAGEGROUP or TO-USER-STORAGEGROUP are specified.

VOLPAIRS ( sourcevolser1 targetvolser1 … [ , sourcevolsern targetvolsern ] )

Optional syntax:

VOLPAIRS-DDN( ddname ) |
VOLPAIRSDEVN ( sourcevolser1 targetvolser1 devn1 … [ , sourcevolsern targetvolsern devnn ] )
VOLPAIRSDEVN-DDN( ddname ) |
VOLPAIRSDEVN-NOCLIP ( sourcevolser1 targetvolser1 devn1 … [ , sourcevolsern targetvolsern devnn ] )
VOLPAIRSDEVN-NOCLIP-DDN ( ddname )

VOLPAIRS specifies volume pairs where the target volumes have been created by the user before the Db2 Cloning Tool COPY command is executed. Target volumes must have the desired internal VOLSER (not the VOLSER of the source volume) and be online. Discrete VOLSERs only, no masking allowed. Short form is VP.

VOLPAIRS-DDN specifies a DD name which points to a file containing the volume pairs. The pairs are the same format as in the VOLPAIRS keyword. VOLPAIRS-DDN must have an LRECL of 80, and must not contain sequence numbers in columns 73-80.

VOLPAIRSDEVN specifies volume pairs with the device number of the target volume where target volumes have been created by the user before the Db2 Cloning Tool copy command is executed. Target volumes must be offline and the internal VOLSER must match the corresponding source VOLSER specified. Db2 Cloning Tool will re-label the specified device (devn) to the corresponding target VOLSER and vary the volume online. Short form is VPD.

VOLPAIRSDEVN-DDN specifies a DD name which points to a file containing the volume pairs. The pairs are the same format as in the VOLPAIRSDEVN keyword. VOLPAIRSDEVN-DDN must have an LRECL of 80, and must not contain sequence numbers in columns 73-80.

VOLPAIRSDEVN-NOCLIP specifies volume pairs with the device number of the target volume where target volumes have been created by the user before the Db2 Cloning Tool COPY command is executed. Target volumes must be offline and the internal VOLSER must match the corresponding source VOLSER specified. COPY will not re-label the specified device (devn) or vary the volume online. The VOLOPTIONS TARGETOFFLINECLIP command can be used to re-label the specified target devices and vary the volumes online. The re-label and vary online of the target volumes with VOLOPTIONS TARGETOFFLINECLIP must happen prior to running the RENAME command. If VOLPAIRSDEVN-NOCLIP or VOLPAIRSDEVN-NOCLIP-DDN are used with USERCATALOGS-NOBACKUP, VOLOPTIONS TARGETOFFLINECLIP must be run before UCATOPTIONS BACKUP which must be run before the RENAME command.

VOLPAIRSDEVN-NOCLIP-DDN specifies a ddname which points to a file containing the volume pairs. The pairs are the same format as in the VOLPAIRSDEVN-NOCLIP keyword. VOLPAIRSDEVN-NOCLIP-DDN must have an LRECL of 80, and must not contain sequence numbers in columns 73-80.

Default: None
Required: One of the VOLPAIRS keywords is required only if DATA-MOVER(PGM(NONE)) is specified.
Restrictions: Valid only with DATA-MOVER(PGM(NONE)).
Short form: FRV

BASE-JOURNAL-DDN ( ddname )

This parameter supplies the DD name of a Db2 Cloning Tool base journal file that (via JCL) points to a journal data set. The base journal data set is created by the primary COPY step and will be used by the RENAME step. Use this keyword when the cloning scenario has multiple COPY steps and information must be passed between COPY steps.

Default: None
Required: No
Restrictions: None
Short form: BASE-JRNL-DDN

CATWORK-ATTR ( catalog backup allocation attributes )

Specifies allocation attributes used when catalog backup data sets are dynamically allocated. Unless unusual attributes are desired for a specific Db2 Cloning Tool COPY, these attributes can be globally specified in the HLQ?.SCKZPARM. CKZINI member, :COPY_OPTIONS section, CATWORK-ATTR token. Allocation attributes are specified in TSO allocate syntax (e.g., UNIT(SYSDA) SPACE(1 1) TRACKS, etc.).

The attributes that can be specified include:

DATACLAS(data class name)
EATTR(NO|OPT)
MAXVOLS(maximum number of volumes)
MGMTCLAS(management class name)
SPACE(quantity increment)
STORCLAS(storage class name)
TRACKS/CYLINDERS UNIT(unit)
VOLUME(serial)

If an initial attempt running COPY fails because a catalog backup data set exceeds extents, increase the allocation and run again. Once successful, examine the space actually used and decrease if desired. To accommodate a future increase in the size of catalogs, leave the allocation with room to spare.

Default: UNIT( SYSALLDA ) SPACE( 10 10 ) CYLINDERS
Required: No.
Restrictions: None
Short form: CWATTR

DATA-MOVER ( [ PGM( ADRDSSU | EMCSNAP | NONE ) ]

For ADRDSSU:

[ , CHECKVTOC ]

[ , CONSISTENT( NO | YES ) ]

[ , COPYCMDLIMIT( nnn | 24 ) ]

[ , DSSPARM( ABEND=nnn [ , AMSGCNT=nnnn ] | SDUMP=nnn [ , SMSGCNT=nnnn ] ) ]

[ , FASTREP( PREF | REQ | NONE ) ]

[ , FCNOCOPY ]

[ , FCSETGTOK ]

[ , FCTOPPRCPRIMARY [ (PRESMIRREQ | PRESMIRPREF | PRESMIRNONE ) ]

[ , FCTOXRCPRIMARY ]

[ , INCREMENTAL( NO | YES ) ]

[ , NOCONCURRENT ] )

For EMCSNAP:

[ , BACKGROUNDCOPY( NO | YES ) ]

[ , CHECKONLINEPATHSTATUS( NO | YES ) ]

[ , CONSISTENT( NO | YES ) ]

[ , DIFFERENTIAL( NO | YES ) ]

[ , MAXIMUM-SUBTASKS( number1, number2 ) ] )

In all cases, specifies the program to be used to initiate copies and copy options.

ADRDSSU specifies that COPY is to initiate FlashCopy or SnapShot 'under the covers' via execution of DSS. It is the default and therefore the PGM(ADRDSSU) keyword can be omitted. Db2 Cloning Tool invokes DSS 'under the covers' to initiate volume copies with the COPY FULL option. Users should be acquainted with the DSS rules governing copy full operations (IBM® publication Advanced Copy Services, Combining Storage Control Copy Operations).

For a COPY FULL operation, DSS determines by the device types of the volumes to be copied what copy mechanism is to be used. Db2 Cloning Tool pairs volumes, so that FlashCopy or SnapShot should be used, and confirms at the time of the COPY step that conflicting relationships do not exist. However, because of the small window between Db2 Cloning Tool volume pairing and relationship validation, DSS errors and associated messages may need to be examined.

Db2 Cloning Tool COPY command supplies the ADMINISTRATOR operand when invoking DFSMSdss. To avoid WTORs, ADRDSSU ADMINISTRATOR is used to gain permission to overlay the target volume VTOCIX and/or VVDS during the COPY process.

Because the ADMINISTRATOR operand is generated, the user ID running COPY must have READ access to FACILITY class profile STGADMIN.ADR.STGADMIN.COPY.

EMCSNAP specifies that COPY is to initiate EMC SNAP ‘under the covers' via EMC TimeFinder/Clone Mainframe Snap Facility's volume level support. Db2 Cloning Tool invokes EMC TimeFinder/Clone 'under the covers' to initiate volume copies using SNAP VOLUME commands. Users should be acquainted with the EMC rules governing SNAP VOLUME operations (EMC publication TimeFinder/Clone Mainframe SNAP Facility Product Guide).

Db2 Cloning Tool pairs volumes, so that EMC TimeFinder/Clone volume snap should be used, and confirms at the time of the COPY step that conflicting relationships do not exist. However, because of the small window between Db2 Cloning Tool volume pairing and relationship validation, EMC TimeFinder/Clone volume snap errors and associated messages may need to be examined.

NONE specifies that no DATA-MOVER is to be invoked by COPY. NONE infers that volume copies have been created by the user prior to the execution of Db2 Cloning Tool. When NONE is specified, COPY still captures necessary catalog information, and if VOLPAIRSDEVN or VOLPAIRSDEVN-DDN is specified, clips and varies target volumes online.

The following parameters are for ADRDSSU:

CHECKVTOC (DSS parameter): Specifies that a VTOC analysis of the source volume be performed during copy processing.

CONSISTENT (Db2 Cloning Tool parameter): Indicates to use a FlashCopy Consistency Group (YES) or not (NO). The default is NO. This does not apply when FASTREP(NONE or PREF) is also specified. To establish a Consistency Group, a FCCGFREEZE parameter is added to each COPY statement passed to ADRDSSU. This will cause I/O activity to the FlashCopy source volumes to be held (frozen). Once all the COPY statements have been processed by ADRDSSU, a CGCREATE command is passed to ADRDSSU. This will cause I/O activity to be resumed on the "frozen" FlashCopy source volumes. The number of volumes being copied will affect the amount of time the I/O activity to the source volumes will be held. If this time exceeds the smallest Consistency Group timer value defined for a LSS, the target volumes will not be consistent.

COPYCMDLIMIT( nnn | 24 ) (Db2 Cloning Tool parameter): Specifies the maximum COPY FULL commands built by Db2 Cloning Tool for each DSS execution. 24 is the default if omitted. If the number of volumes to be copied exceeds the COPYCMDLIMIT, Db2 Cloning Tool will invoke DSS as many times as necessary. Adjusting this value may affect the performance of ESS copy initiations.

DSSPARM (DSS parameter): This parameter can be used to pass execution parameters to ADRDSSU. This parameter is intended for diagnostic purposes and can be used to gather more information when ADRDSSU has problems. The parameter values should be: ABEND=nnn[,AMSGCNT=nnnn] or SDUMP=nnn[,SMSGCNT=nnnn]. These parameters are described in the DFSMS Storage Administration Reference manual in the section “How to Control DFSMSdss through PARM Information in the EXEC Statement”.

FASTREP (DSS parameter): Indicates if fast replication is preferred (PREF), required (REQ), or not required (NONE). Db2 Cloning Tool will set up the source/target pairs for a fast replication if PREF or REQ is specified. Db2 Cloning Tool will allow a ‘normal' copy if NONE is specified. If the level of ADRDSSU indicates it supports this keyword, the keyword will be passed to ADRDSSU.

FCNOCOPY: (DSS parameter) Indicates that no background copy should be done for the volume pair. This applies to ESS devices only.

Note: When using FCNOCOPY, you must terminate the FlashCopy source and target relationship at the completion of the backup. Either use the DFSMSdss DUMP parameter FCWITHDRAW, or use COPYCHECK WITHDRAW. Following the withdraw, some of the tracks on the volume may contain data from the source volume, while other tracks may contain residual data that was on the target volume before the copy. This situation can cause problems when trying to access the target volume if the VTOC locations of the source and target volumes were different before the copy.

FCSETGTOK (DSS parameter): Indicates that a FlashCopy target volume can also be a space efficient volume. This does not apply when FASTREP(NONE) is also specified. The physical background copy option is not permitted for space efficient FlashCopy. Because of this, the FCNOCOPY keyword must also be specified with the FCSETGTOK keyword.

FCTOPPRCPRIMARY [ (PRESMIRREQ | PRESMIRPREF | PRESMIRNONE ) ] (DSS parameter): Indicates that a FlashCopy target volume can also be a PPRC primary volume. This applies to ESS devices only. This does not apply when FASTREP(NONE) is also specified.

IBM Remote Pair FlashCopy (also known as Preserve Mirror) can be specified by including one of the optional keywords. Preserve Mirror mirrors the FlashCopy command that is issued at the local site to the remote site. This allows FlashCopy operations to occur to PPRC primary volumes without affecting the PPRC duplex state. IBM Remote Pair FlashCopy must be installed in the storage controller along with the corresponding software support in z/OS®. In addition, both the source and target volumes being PPRC primary volumes and in the same storage controller and their corresponding PPRC secondary volumes being in the same storage controller.

Specify one of the following use this functionality:

PRESMIRREQ (short form: PMR): Require the use of Preserve Mirror. If a Preserve Mirror operation cannot be accomplished, the FlashCopy operation will not be completed.
PRESMIRPREF (short form: PMP): Prefer the use of Preserve Mirror. If a Preserve Mirror operation cannot be accomplished, the FlashCopy operation is still performed.
PRESMIRNONE (short form: PMN): Do not use Preserve Mirror.

When any of these options is specified, they will be used as part of the source to target volume pairing criteria. The specified option will also be passed to ADRDSSU as part of the generated copy commands. For additional information about Preserve Mirror, refer to the documentation for your version of z/OS.

FCTOXRCPRIMARY (DSS parameter): Indicates that a FlashCopy target volume can also be an XRC primary volume. This keyword is applicable only for DATA-MOVER PGM(ADRDSSU). This does not apply when FASTREP(NONE) is also specified.

INCREMENTAL (Db2 Cloning Tool parameter): Indicates that a full volume Incremental FlashCopy relationship is to be established (YES) or not (NO). The default is NO. This does not apply when FASTREP(NONE or PREF) is also specified. Volumes will be paired using an existing Incremental FlashCopy relationship if possible. INCREMENTAL(YES) cannot be used with FCNOCOPY.

NOCONCURRENT (DSS parameter): Specifies that the CONCURRENT option will not be supplied to ADRDSSU. This will prevent ADRDSSU from using Concurrent Copy when doing the volume copies.

The following parameters are for EMCSNAP:

BACKGROUNDCOPY: Indicates if background copy should be done (YES), or not (NO), for the volume pair. The default is YES.

CHECKONLINEPATHSTATUS: Indicates if a check that paths from other CPUs to the target devices are offline before performing a volume snap (YES) or not (NO). The default is NO.

CONSISTENT: Indicates to use Enginuity Consistency Assist (ECA) for consistent SNAP VOLUME operations (YES) or not (NO). The default is NO.

DIFFERENTIAL: Indicates to use the Enginuity Differential Snap feature for SNAP VOLUME operations (YES) or not (NO). The default is NO.

MAXIMUM-SUBTASKS ( number1, number2 ): Sets an absolute maximum number of subtasks that can be attached and used. SNAP automatically limits the number of subtasks based on the requests specified and the low and high region available. SNAP never exceeds the limits specified in this parameter. number1 is the limit of the number of individual requests that can be processed simultaneously. The minimum value you can specify is two (2). The maximum value you can specify is 9999. number2 is the limit of the number of individual activities that can be performed within a single request, typically as the result of wildcarding. The minimum value you can specify is two (2). The maximum value you can specify is 9999. If not specified, the EMC system defaults are used.

Default: For PGM, the default is ADRDSSU. For COPYCMDLIMIT, the default is 24. For FASTREP, the default is REQ. For INCREMENTAL, the default is NO. For BACKGROUNDCOPY, the default is YES. For CHECKONLINEPATHSTATUS, the default is NO. For CONSISTENT, the default is NO. For DIFFERENTIAL, the default is NO.
Required: No
Restrictions: INCREMENTAL(YES) is mutually exclusive with FCNOCOPY.
Short form(s): DM, CHECK, CCL, FR, FCNC, FCTOPPRCP, NOCC

EXCLUDE-FROM-VOLSER ( volser1 | volmask1 …[ volsern | volmaskn ] )

Optional syntax: EXCLUDEFROMVOLSER

Specifies volumes or volumes matching a mask, to be excluded from being specified for either the FROM-VOLSER parameter, or the FROM-STORAGEGROUP parameter.

Default: None
Required: No
Restrictions: Not valid with VOLPAIRS, VOLPAIRS-DDN, VOLPAIRSDEVN, VOLPAIRSDEVN-DDN, VOLPAIRSDEVN-NOCLIP, or VOLPAIRSDEVN-NOCLIP-DDN.
Short form: EXCFRV

EXCLUDE-TO-VOLSER ( volser1 | volmask1 …[ volsern | volmaskn ] )

Optional syntax: EXCLUDETOVOLSER

Specifies volumes or volumes matching a mask, to be excluded (not selected as targets) from being specified for either the TO-VOLSER parameter or the TO-STORAGEGROUP parameter.

If the 'eliminated' target volumes cause there to be more source volumes than targets, the COPY will fail.

If the 'eliminated' target volumes still leave at least as many target volumes as source volumes, the pairing will continue as usual.

Default: None
Required: No
Restrictions: Not valid with VOLPAIRS, VOLPAIRS-DDN, VOLPAIRSDEVN, VOLPAIRSDEVN-DDN, VOLPAIRSDEVN-NOCLIP, or VOLPAIRSDEVN-NOCLIP-DDN.
Short form: EXCTOV

KEEP-VOLUMES-SEQUENCE( Y | N )

Specifies whether source volumes are to be paired with specific target volumes. During the pairing process, Db2 Cloning Tool checks the volume sequence numbers of source and target volumes. The assignment of volume sequence numbers is described in detail in How Db2 Cloning Tool pairs volumes when the KEEP-VOLUMES-SEQUENCE keyword is specified. If Y or YES is specified, then target and source volumes will be paired only if their sequence numbers are the same. If N or NO is specified, or no KEEP-VOLUMES-SEQUENCE parameter is specified, then the sequence numbers of source and target volumes are not used for their pairing. In this case, source and target volumes that have different sequence numbers can be paired if other required conditions are true.

Default: N
Required: No
Restrictions: Mutually exclusive with VOLPAIR, VOLPAIRS-DDN, VOLPAIRSDEVN, VOLPAIRSDEVN-DDN, VOLPAIRSDEVN-NOCLIP, and VOLPAIRSDEVN-NOCLIP-DDN
Short form: KVS

SIMULATE

For DATAMOVER(PGM(ADRDSSU), SIMULATE specifies that the COPY step is to perform all functions except actual initiation of copies. This option is recommended for new Db2 Cloning Tool setups or when modifications to the setup are made.

SIMULATE will verify syntax, match source to target volumes, display DSS COPY FULL commands (but not initiate the copies), and back up user catalogs. User catalogs are backed up to enable the SIMULATE option of the RENAME step.

Note that in the process of pairing volumes, the logic is exercised to assure that the same ESS subsystem, LSS (FlashCopy V1), and volume size requirements permit all source volumes to be paired with targets. If discrete volumes are specified, and one-for-one pairing is desired, the simulated COPY FULL commands will verify whether pairing requirements were satisfied for a one-for-one pairing.

For DATAMOVER(PGM(NONE), SIMULATE specifies that the COPY step checks syntax, and backs up the source ICF Catalogs for input to RENAME SIMULATE.

Default: None.
Required: No
Restrictions: None.
Short form: SIM

SOURCESONLINE( Y | N )

Db2 Cloning Tool COPY command will expect to locate the source volumes online. If N is specified, Db2 Cloning Tool COPY will not expect to find all the source volumes online.

Note: If N is specified and the source volumes are not online, the source user catalogs must still be available to the Db2 Cloning Tool COPY command.

Default: Y
Required: No.
Restrictions: Valid only with VOLPAIRS, VOLPAIRS-DDN, VOLPAIRSDEVN, VOLPAIRSDEVN-DDN, VOLPAIRSDEVN-NOCLIP, or VOLPAIRSDEVN-NOCLIP-DDN
Short form: SRCON

TARGETSONLINE( Y | N )

If Y is specified, Db2 Cloning Tool COPY will expect to locate the target volumes online. If N is specified, Db2 Cloning Tool COPY will not expect to find all the target volumes online.

Default: Y
Required: No
Restrictions: Valid only with VOLPAIRS or VOLPAIRS-DDN.
Short form: TGTON

TARGETSUONLINE( Y | N )

If Y is specified, Db2 Cloning Tool COPY will expect to locate the target user catalogs. It will check that the security product will allow ALTER access to the target user catalogs.

If N is specified, Db2 Cloning Tool COPY will not check for the existence / availability of the target user catalogs. Db2 Cloning Tool RENAME will check that the target catalogs are available and will do the RACF® checks.

Default: Y
Required: No.
Short form: TGTUON

TARGET-UCATS-ON-TARGET-VOLUMES( Y | N )

Specifies that there are target ICF catalogs that reside on the target volumes, and you want the target ICF catalogs to remain on the target volumes after the RENAME step. If Y is specified, when the RENAME step completes, the target ICF catalogs will reside on target volumes.

Default: N
Required: No
Restrictions: None
Short form: TUOTV

TARGET-VOLS-SHOULD-BE-EMPTY( Y | N )

Performs a check during the volume pairing process to ensure the target volumes are empty before issuing FlashCopy or SnapShot. In the event a subsequent RENAME fails and the COPY must be rerun, Db2 Cloning Tool will not clean off the target volumes if 'Y' was specified for this parameter. Either initialize the target volumes or change this keyword to 'N'.

Default: N
Required: No
Restrictions: Not valid with VOLPAIRS, VOLPAIRS-DDN, VOLPAIRSDEVN, VOLPAIRSDEVN-DDN, VOLPAIRSDEVN-NOCLIP, or VOLPAIRSDEVN-NOCLIP-DDN.
Short form: TVE

Offline Volumes (with DATA-MOVER(PGM(ADRDSSU)) or PGM(EMCSNAP))

Source volumes:

Discrete VOLSER specification: Must be found online, or COPY terminates with a return code 8.
VOLSER mask specification: At least one online volume must be found that matches the mask, or COPY terminates with a return code 8.
Storage group specification: At least one volume associated with the storage group must be online, or COPY terminates with a return code 8. A warning, return code 4, is generated if at least one volume is not found. Note that Db2 Cloning Tool cannot tell the difference between a non-existent volume and an offline volume.

Target volumes (no matter how they are specified) :

If enough online volumes can be found to pair with source volumes, COPY will proceed.
If target volumes are not found, but not needed, COPY will not complain.
If fewer target volumes are found than needed to pair with source volumes, COPY will terminate with a return code 8.
Because in some cases Db2 Cloning Tool cannot distinguish between a non-existent volume and an offline volume, messages refer to these volumes as 'not found'.