Syntax and options of the COPYTOCOPY control statement

The COPYTOCOPY utility control statement, with its multiple options, defines the function that the utility job performs.

You can create a control statement with the ISPF/PDF edit function. After creating it, save it in a sequential or partitioned data set. When you create the JCL for running the job, use the SYSIN DD statement to specify the name of the data set that contains the utility control statement.

Start of change

Syntax diagram

Read syntax diagramSkip visual syntax diagram COPYTOCOPY LISTlistdef-namefrom-copy-specdata-set-spectable-space-specindex-space-specfrom-copy-specdata-set-specCLONE
table-space-spec
Read syntax diagramSkip visual syntax diagram TABLESPACE database-name. table-space-name DSNUMALLDSNUMinteger
index-space-spec
Read syntax diagramSkip visual syntax diagramINDEXSPACE1database-name.index-space-nameINDEXcreator-id.index-nameDSNUMALLDSNUMinteger2
from-copy-spec
Read syntax diagramSkip visual syntax diagramFROMLASTCOPYFROMLASTFULLCOPYFROMLASTINCRCOPYFROMLASTFLASHCOPY3FROMCOPY4dsnFROMVOLUMECATALOGvolserFROMSEQNOn5
data-set-spec
Read syntax diagramSkip visual syntax diagramCOPYDDN6(ddname17, ddname2, ddname2)RECOVERYDDN(ddname3, ddname4, ddname4)RECOVERYDDN(ddname3, ddname4, ddname4)
Notes:
  • 1 INDEXSPACE is the preferred specification.
  • 2 Not valid for nonpartitioning indexes.
  • 3 FROMLASTFLASHCOPY is not valid with either of the following keywords: INDEXSPACE, INDEX.
  • 4 FROMCOPY is not valid with the LIST keyword.
  • 5 The FROMSEQNO option is required if you are copying an image copy from a tape data set that is not cataloged.
  • 6 You can specify up to three DD names for both the COPYDDN and RECOVERYDDN options combined.
  • 7 Use this option if you want to make a local site primary copy from one of the recovery site copies.
End of change

Option descriptions

LIST listdef-name
Specifies the name of a previously defined LISTDEF list name. The utility allows one LIST keyword for each COPYTOCOPY control statement. Do not specify LIST with either the INDEX or TABLESPACE keywords. Db2 invokes COPYTOCOPY once for the entire list.

This utility does not support lists that specify more than 32,000 objects. Partitions of table spaces or index spaces that are included by the PARTLEVEL keyword count as separate objects.

This utility only processes clone data if the CLONE keyword is specified. The use of CLONED YES on the LISTDEF statement is not sufficient.

The partitions or partition ranges can be specified in a list.

TABLESPACE
Specifies the table space (and, optionally, the database it belongs to) that is to be copied. database-name is the name of the database that the table space belongs to. The default value is DSNDB04.

table-space-name is the name of the table space to be copied.

INDEXSPACE database-name.index-space-name
Specifies the qualified name of the index space that is to be copied; the name is obtained from the SYSIBM.SYSINDEXES table. Define the index space with the COPY YES attribute.

database-name optionally specifies the name of the database that the index space belongs to. The default value is DSNDB04.

index-space-name specifies the name of the index space that is to be copied.

INDEX creator-id.index-name
Specifies the index that is to be copied. Enclose the index name in quotation marks if the name contains a blank.

creator-id optionally specifies the creator of the index. The default value is the user identifier for the utility.

index-name specifies the name of the index that is to be copied.

DSNUM
Identifies a partition or data set, within the table space or the index space, that is to be copied. The keyword ALL specifies that the entire table space or index space is to be copied.

You cannot specify DSNUM for nonpartitioned indexes.

ALL
Specifies that the entire table space or index space is to be copied. You must use ALL for a nonpartitioned secondary index.
integer
Is the number of a partition or data set that is to be copied.

An integer value is not valid for nonpartitioned secondary indexes.

For a partitioned table space or index space, the integer is its physical partition number. The maximum is 4096.

For a nonpartitioned table space, find the integer at the end of the data set name as cataloged in the VSAM catalog. The data set name has the following format: 
catname.DSNDBx.dbname.spacename.y000Z.Annn
In this format:
catname
Is the VSAM catalog name or alias.
x
Is C or D.
dbname
Is the database name.
spacename
Is the table space or index space name.
y
Is I or J.
z
Is 1 or 2.
nnn
Is the data set integer.

Specifying or using the default of DSNUM(ALL) causes COPYTOCOPY to look for an input image copy that was taken at the entire table space or index space level.

FROMLASTCOPY
Specifies the most recent image copy that was taken for the table space or index space that is to be the input to the COPYTOCOPY utility. This could be a full image copy or incremental copy that is retrieved from SYSIBM.SYSCOPY.
FROMLASTFULLCOPY
Specifies the most recent full image copy that was taken for the object, which is to be the input to the COPYTOCOPY job.
FROMLASTINCRCOPY
Specifies the most recent incremental image copy that was taken for the object that is to be the input to COPYTOCOPY job.

FROMLASTINCRCOPY is not valid with the INDEXSPACE or INDEX keyword. If FROMLASTINCRCOPY is specified for an INDEXSPACE or INDEX, COPYTOCOPY uses the last full copy that was taken, if one is available.

FROMLASTFLASHCOPY
Specifies that the most recent FlashCopy® image copy that was taken for the object is to be the input to COPYTOCOPY job.
FROMCOPY dsn
Specifies a particular image copy data set (dsn) as the input to the COPYTOCOPY job. This option is not valid for LIST.

If the image copy data set is a generation data set, then supply a fully qualified data set name, including the absolute generation and version number. If the image copy data set is not a generation data set and more than one image copy data set have the same data set name, use the FROMVOLUME option to identify the data set exactly.

Start of changeIf the image copy is a FlashCopy image copy of a nonpartitioned index (NPI), specify the data set name of the FlashCopy image copy for any one of the pieces. In this case, you must also specify DSNUM ALL, either explicitly or as the default. The resulting sequential image copy or copies will contain the pages from all pieces of the multi-piece NPI. End of change

FROMVOLUME
Identifies the image copy data set.
CATALOG
Identifies the data set as cataloged. Use this option only for an image copy that was created as a cataloged data set. (Its volume serial is not recorded in SYSIBM.SYSCOPY.)

COPYTOCOPY refers to the SYSIBM.SYSCOPY catalog table during execution. If you use FROMVOLUME CATALOG, the data set must be cataloged. If you remove the data set from the catalog after creating it, you must catalog the data set again to make it consistent with the record that appears in SYSIBM.SYSCOPY for this copy.

vol-ser
Identifies the data set by an alphanumeric volume serial identifier of its first volume. Use this option only for an image copy that was created as a noncataloged data set. Specify the first vol-ser in the SYSCOPY record to locate a data set that is stored on multiple tape volumes.If an individual volume serial number contains leading zeros, it must be enclosed in single quotation marks.
FROMSEQNO n
Identifies the image copy data set by its file sequence number. n is the file sequence number.
COPYDDN (ddname1,ddname2)
Specifies a DD name (ddname) or a TEMPLATE name for the primary (ddname1) and backup (ddname2) copied data sets for the image copy at the local site. If ddname2 is specified by itself, COPYTOCOPY expects the local site primary image copy to exist. If it does not exist, error message DSNU1401 is issued and the process for the object is terminated.
Recommendation: Catalog all of your image copy data sets.

You cannot have duplicate image copy data sets. If the DD statement identifies a noncataloged data set with the same name, volume serial, and file sequence number as one that is already recorded in SYSIBM.SYSCOPY, COPYTOCOPY issues a message and no copy is made. If the DD statement identifies a cataloged data set with only the same name, no copy is made. For cataloged image copy data sets, you must specify CATLG for the normal termination disposition in the DD statement; for example, DISP=(MOD,CATLG,CATLG). The DSVOLSER field of the SYSCOPY entry is blank.

When the image copy data set is going to a tape volume, specify VOL=SER parameter in the DD statement.

The COPYDDN keyword specifies either a DD name or a TEMPLATE name specification from a previous TEMPLATE control statement. If utility processing detects that the specified name is both a DD name in the current job step and a TEMPLATE name, the utility uses the DD name.

RECOVERYDDN (ddname3,ddname4)
Specifies a DD name (ddname) or a TEMPLATE name for the primary (ddname3) and backup (ddname4) copied data sets for the image copy at the recovery site. If ddname4 is specified by itself, COPYTOCOPY expects the recovery site primary image copy to exist. If this image copy does not exist, error message DSNU1401 is issued and the process for the object is terminated.

You cannot have duplicate image copy data sets. The same rules apply for RECOVERYDDN as for COPYDDN.

The RECOVERYDDN keyword specifies either a DD name or a TEMPLATE name specification from a previous TEMPLATE control statement. If utility processing detects that the specified name is both a DD name in the current job step and a TEMPLATE name, the utility uses the DD name.

CLONE
Indicates that COPYTOCOPY is to process only image copy data sets that were taken against clone tables or indexes on clone tables. This utility will only process clone data if the CLONE keyword is specified. The use of CLONED YES on the LISTDEF statement is not sufficient.