XCPYDYNM (dynamic image copy data set allocation) automation control point

Use the XCPYDYNM automation control point to control the following aspects of the image copy process:

Whether to exclude the copying of a particular object (if it matches a wildcard naming pattern)
Whether to perform a full image copy as opposed to an incremental one
The name of the image copy data set

The automation control point uses the following process:

Defines a data set with the requested name.
Deletes the image copy by setting DISP to D (not performed with BMC AMI Reorg).
Switches to a new tape volume by setting FSEQ to a value of 1 (not performed with BMC AMI Reorg).

The product invokes this automation control point as each table space is selected for image copy processing. (For tape copies, DD names and drives have already been determined at this point). (SPE2005) The XCPYDYNM is not invoked if +OVERRIDEOUTPUT(NO) and the OUTPUT statement is complete.

Variables

The following table describes the variables used in the XCPYDYNM automation control point:

Variable name	Contents	Possible values
changed	Total number of 4-KB pages that have been modified since the last copy, provided that real-time statistics are available for the table space This field is derived from the COPYUPDATEDPAGES column of the SYSTABLESPACESTATS table.	Not applicable
changes	An indicator of whether rows have been changed since the last copy, provided that real-time statistics are available for the table space This field is derived from the COPYCHANGES column of the SYSTABLESPACESTATS table.	Y (indicating that changes have been made) N (indicating that there have been no changes since the last copy)
cpyddnam	Value of the COPYDDN or RECOVERYDDN keywords of the COPY utility statements This is not the ddname that the utility writes to SYSCOPY.	Not applicable
dataclas	SMS data class	Not applicable
dbname	Database name as it appears on the COPY statement	Not applicable
disp	Disposition for the image copy data set	K (keep) C (catalog) D (delete)
dsname	Image copy data set name This variable is required. Important The variable has a maximum of 44 characters. You can optionally suffix the data set name with (+1) to indicate a generation data group (GDG) data set. The base GDG must exist in this case. If the copy is a Flashcopy from BMC AMI Reorg, then two bytes must be available for the .D added to the data entry of the VSAM copy data set.	Not applicable
dsnum	Data set number (partition number) as it appears on the COPY statement	0 or a positive integer representing the partition number If DSNUM ALL is specified, this value is 0.
dstype	Table space type	SI (simple) SG (segmented) PT (partitioned)
empty	Number of empty 4-KB pages	Not applicable
expdt	Expiration date for the image copy	A value in the format YYYYMMDD
from_ic	If copying FROMSYSCOPY, the 44-byte data set name of the source image copy Otherwise, the value is blank.	Not applicable
fseq	Tape file sequence number	Set to 1 to start a new volume
full	Type of image copy as specified on the COPY statement Important If this variable is N and the object is in a restricted state (that is, if the restrict variable is Y) then the automation control point must change full to Y. For BMC AMI Reorg, the value of full is always Y.	Y (yes, full image copy) N (no, incremental copy)
full_days	Number of days since the last FULL YES image copy as recorded in SYSIBM.SYSCOPY	0 through 255 If restrict=Y, then full_days=0.
full_hours	Number of hours since the last FULL YES image copy as recorded in SYSIBM.SYSCOPY Important This value will not be accurate if it exceeds 48. In other words, after two days, the hours value is not exact. The automation control point does not round the minute value. The value of this variable is the change in the hour value of the time since the last full image copy.	0 through 255 If restrict=Y, then full_hours=0.
function	Name of the utility that is about to be processed	RGTS (Reorg)
gdglimit	Number passed as the LIMIT keyword of a DEFINE GDG AMS command (for a GDG data set for which a GDG base does not exist) SeeAdditional considerations	Not applicable
icbackup	Image copy backup type This type corresponds to the COPYDDN or RECOVERYDDN DD statements.	Blank (local primary) LB (local backup) RP (remote primary) RB (remote backup) FC (Flashcopy)
incr_count	Number of successive incremental image copies recorded in SYSIBM.SYSCOPY since the last full copy of the table space being processed	0 through 255 If restrict=Y, then incr_count=0.
ixname	Name of the index being copied, in the form creator.ixname	Not applicable
lpart	Logical partition number for the copy DB2 posts copies to SYSIBM.SYSCOPY based on the physical partition number rather than the logical partition number. The user makes all specifications based on the logical partition number. The automation control point sets the dsnum variable to the physical partition number.	Not applicable
maxvol	For DASD allocation, the number of volumes used to satisfy the original space request in excess of 500 cylinders The maximum value is 59.	The primary variable divided by 500, rounded up to the next whole number For example, for a data set with a size of 2100 cylinders, maxvol would be 2100 divided by 500 (4.2), rounded up to 5.
media	Type of media in use You cannot change this variable.	D (disk) T (tape)
mgmtclas	SMS management class	Not applicable
otype	Object type being copied	T (table space) I (index)
pagesize	Size of a data page, expressed in kilobytes	Positive integer followed by K
parts	Total number of partitions in the table space	0 or a positive integer 0 indicates that an object is not partitioned
ppart	Physical partition number DB2 posts copies to SYSIBM.SYSCOPY based on the physical partition number rather than the logical partition number. The user makes all specifications based on the logical partition number. The automation control point sets the dsnum variable to the physical partition number.	Should always match the value of dsnum
primary	For DASD allocation, the primary space allocation to use SeeAdditional considerations	Not applicable
rc	Return code for this automation control point	SeeReturn codes
restrict	Whether the current object is in a DB2 restricted state Important For BMC AMI Reorg, this value is always Y. When a database object is restricted, it is usually due to one or more of the following reasons: The table space is in COPY pending (COPYP) status. The table space has no prior full image copy. The full_force variable is Y.	N (object is not in a restricted state) Y (object is in a restricted state)
retpd	Retention period, in days	Not applicable
secondary	For DASD allocation, the secondary space allocation to use When the automation control point receives control, the value for this variable is half the value of the primary variable. The value for this variable must be greater than 0. A value of 0 produces unpredictable results.	Not applicable
shrlevel	Access mode as specified on the COPY statement	C (SHRLEVEL CHANGE) R (SHRLEVEL REFERENCE)
size	Total number of 4-KB pages in the table space, obtained from the high-used RBA (HURBA) of the VSAM data set for the table space If the dsnum variable is 0 and the parts variable is not 0, the size variable will contain the sum of the HURBAs from all partitions.	Not applicable
spaceunit	Space allocation unit of the primary and secondary variables This variable is set to cylinders if the primary variable is greater than 10 cylinders; otherwise spaceunit is set to tracks. If you require allocations in blocks, use the XSUTDYNM automation control point instead of the XCPYDYNM automation control point.	C (cylinders) T (tracks)
stmt	SYSIN statement number	Not applicable
storclas	SMS storage class	Not applicable
tapedd	DD name for the tape unit, if applicable You cannot change this value.	Not applicable
tsname	Name of the table or index space being copied	Not applicable
tstype	Type of table space being copied	PRT (partitioned) SEG (segmented) SIM (simple) PBG (partition-by-growth) PBR (range-partitioned) LOB XML ' ' (blank - unknown)
unitname	Name of the image copy unit You cannot change this value.	Not applicable
vcatname	High-level qualifier for the object being processed	Not applicable

Return codes

The XCPYDYNM automation control point returns the following return codes:

Return code	Description
0	(default value) Signifies normal completion No action is required.
Any other value	Abnormal termination Set the return code to any non-zero value to cancel the entire job.

Restrictions

The BMC AMI Utilities products support only dynamic allocation of copy data sets. If you specify copy DD statements in your JCL, the BMC AMI Utilities products ignore them.

Additional considerations

Review the following information before using this automation control point.

Additional variable information

gdglimit

Example:

If dsname is set to 'A.B(+1)' but A.B is not defined in the catalog, then the automation control point generates and executes the following command:

DEFINE GDG(NAME(A.B) LIMIT(gdglimit))

Statements that precede the number with a letter N define the GDG with the attribute NOSCRATCH. The maximum number of GDGs in this case is 99. The following are valid examples of NOSCRATCH GDG limits:

gdglimit = 'N94'

gdglimit = 'N2'

gdglimit = 'N10'

gdglimit = 'N1' /* the minimum */

gdglimit = 'N99' /* the maximum */

primary

When this automation control point receives control, the primary variable contains a value derived from the following logic:

if full=y then
       if size > 1800        /* greater than 10 cyls*/
          then primary = min(size/180,500)
          /* the lesser of size in cylinders or 500*/
       else
          primary=size/12
else      /* full=n */
       if changed > 1800
         /* greater than 10 cyls changed */
         then primary =min(changed/180,500)
         /* the lesser of changed in cylinders or 500*/
       else primary = changed/12

DASD allocation

When the value of the media variable is D, the automation control point performs DASD allocation.

Space	The following considerations apply to space aspects of DASD data set allocation: When allocating a DASD data set, the primary, secondary, spaceunit, maxvol, and unitname variables are important. With the exception of unitname, these variables have initial values when the utility calls the automation control point. In most cases, you do not need to change any of these values. You must always supply unitname if is it not already supplied by XCPYMDIA. Space allocation calculations are based on 3390 device geometry, which assumes twelve 4-KB records per track and 15 tracks per cylinder (180 records per cylinder ). The RLSE operand is always used to release unused space after the copy.
Disposition	All disk allocations will use an abnormal disposition of DELETE. If the job fails due to an out-of-space condition, the abnormal disposition takes place and the data set is deleted, provided that the utility parameter +ONERROR (ABEND) is in effect. If the job is restarted, the job might fail again. In this case, you must add space or redirect the copy to an available DASD pool.
Full variable	Because the number of pages to be copied can differ drastically, the following DASD space allocation variables depend on the setting of the full variable: primary, secondary, spaceunit, and maxvol. If you change the full variable without changing these variables, the product will recalculate these variables based on the new value for full. If, however, you change any of these variables, the utility uses the values for all of the variables without recalculation.

Tape or VTS allocation

The automation control point performs tape or VTS allocation when the value of the media variable is T.

You cannot include the DISP and DSNAME parameters on your DD statement. The DD name can be any name. All other DD parameters are valid. For example:

//DD1 DD UNIT=(TAPE,,DEFER),VOL=PRIVATE
//DD2 DD UNIT=(TAPE,,DEFER),VOL=PRIVATE

Tape selection	The copy function of the utility employs two methods for tape DD selections. The first method relies on tape availability within the job step. When multiple tape drives are allocated to the job, the copy function multi-tasks on tape drives based solely on drive availability.
Tape pools	The second method for tape DD selections relies on special coded DD names (tape pools). Use this method if you want to separate the local backups from recovery backups. Because the separation is based on backup types, the first two characters of the DD name for the TAPEDD are used to designate the backup type pool. This method ensures that one type of backup image copies are not mixed with another backup type. This method is useful if one copy is kept in the data center and a backup copy is sent offsite. The four types of copies are LP (local primary image copy), LB (local backup image copy), RP (remote primary image copy), and RB (remote backup image copy). Example: This example uses the following COPY statement to copy all table spaces in database PROD1: COPY TABLESPACE PROD1.% SHRLEVEL CHANGE The product uses the following version of the XCPYDYNM automation control point: /* rexx / gdglimit = 5 / If defining a new GDG, keep 5 generations / dsname = 'BKUPCOPY'.'dbname'.'tsname'.'icbackup'(+1)' dsname = space(dsname) / remove all blanks from the name */ say dsname rc = 0 Assuming that a primary and backup tape unit and recovery tape unit are defined, this combination copies all table spaces in database PROD1 to each of the three tape units. Each data set on the tape will have a GDG name. Table space PROD1.ABCD would result in the following image copy data set names: BKUPCOPY.PROD1.ABCD.LP.G0001V01 BKUPCOPY.PROD1.ABCD.LB.G0001V01 BKUPCOPY.PROD1.ABCD.RP.G0001V01 If the GDG does not exist, it will be dynamically defined (with an IDCAMS DEFINE operation).
Skipping a table space	XCPYDYNM is called for each copy of a table space. If the copy statement specifies COPYDDN(COPY1,COPY2), then XCPYDYNM is called twice per table space: once with icbackup = 'LP' and once with icbackup = 'LB'. To skip a table space, you must set the variable disp to D for both calls.
Controlling tape volumes	One problem with copying to tape is exceeding the maximum number of tape volumes that the operating system allows. One way to prevent this is to use the VOLUME keyword on the tape DD statement. For example, to allow up to 20 volumes for a single data set, use the following DD statement: //BIGBIGTP DD UNIT=(TAPE,,DEFER),VOL=(,,,20)

Managing the DB2 catalog

Some of the variables in this automation control point are set based on analysis of the SYSIBM.SYSCOPY DB2 catalog table. XCPYDYNM can use these variables to determine whether to perform a full or incremental copy.

The key variable to watch is restrict. When restrict is Y, it indicates that a full copy is required and that an incremental copy is not allowed.

When restrict is N, you can use other variables to determine whether you want an incremental copy. This determination is based solely on the number of days since the last full image copy (indicated by the full_days variable).

If the last copy was a FULL YES copy and the table space is not in COPYP state, then restrict is set to N, and full_days is the number of days between the last image copy and the day of the current run.

If the table space is in COPYP, or if no full image copy exists in the DB2 catalog (as specified with FULL YES), then DB2 requires that a full image copy be taken. In this case, the value of restrict is Y and full_days is 0.

If the table space is not in COPYP, and the latest image copies are incremental copies (as specified with FULL NO), then the value of restrict is N and full_days contains the number of days between the last full image copy and the current date.

MVS catalog

How image copies are cataloged in the MVS catalog is extremely important when using tape for copies (and to a lesser extent when using DASD). The BMC AMI Utilities copy function provides some significant facilities that might affect how you design your XCPYDYNM automation control point. When using tape for copies, consider the following issues:

The number of data sets (files) per tape volume
The number of tape volumes per data set
How the data sets are catalogued

When referring to cataloguing image copy data sets, it does not matter whether the reference is to the DB2 catalog or the MVS catalog. If the copies are cataloged in the MVS catalog, the way SYSIBM.SYSCOPY is updated changes. The volume serial number of the copy is not recorded in the DB2 catalog if the data set is cataloged in the MVS catalog. However, when the copy is retrieved, for example, to run a DB2 recovery, DB2 accesses the data set using the list of volumes as they are cataloged and the file sequence number of the data set (which is also stored in both catalogs).

When stacking a large number of table space copies on tape, finding a specific data set might take a long time if there is a large number of files on the tape and a large number of volumes on which the data set is cataloged.

How the

BMC AMI Utilities

copy function catalogs tape copies

The BMC AMI Utilities copy function catalogues each data set with only the volumes that actually contain the data set. If a single table space copy spans multiple volumes, the copy function catalogs each of the volume serial numbers that contain the data set, starting with the first volume on which the data set resides.

In terms of the XCPYDYNM automation control point, you do not need to be concerned about the number of different volumes that are used for copying a stack of table spaces. It might make sense to direct very large table spaces to their own volumes, but you do not need to try to fit a set of copies onto a single tape volume. This philosophy results in using fewer tapes overall to keep the set of copies, and copies will probably run more quickly.

DSNUTILB processing of objects not supported by BMC AMI Reorg

BMC AMI Reorg calls IBM DSNUTILB to process objects that BMC AMI Reorg cannot process. The DSNUTILB utility processing routine then generates the SYSIN statements that it needs to reorganize the objects.

BMC AMI Reorg creates DB2 TEMPLATE statements for any copy data sets that need to be created. In those cases, the XCPYDYNM function variable is set to UTLB, and DSNUTILB calls XCPYDYNM to obtain the data set name and data set attributes needed for the TEMPLATE statements. The DSNUTILB utility processing routine then attaches DSNUTILB to process the objects.

Important

For FUNCTION = UTLB calls, the dsname variable can contain variable symbols that are supported by the DB2 TEMPLATE statement. For example, XCPYDYNM could set the dsname variable to HLQ .DB.TS.P&PA.