XCPYMDIA (copy media selection) automation control point
Use the XCPYMDIA automation control point to control the routing of image copies to disk or tape devices.
The product invokes this automation control point at the following point:
- For BMC AMI Reorg, at the beginning of the copy phase
- For BMC AMI Load, during pre-processing
(SPE2005) The XCPYMDIA is not invoked if +OVERRIDEOUTPUT(NO) and the OUTPUT statement is complete.
Variables
The following table describes the variables used in the XCPYMDIA automation control point:
Variable name | Contents | Possible values |
|---|---|---|
changed | The 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. |
|
chkrba | The value of CHKRBA that is being used | Not applicable |
cpyddam | The value of the COPYDDN or RECOVERYDDN keywords of the COPY utility statements This name 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 |
|
dsname | Image copy data set name This variable is required. | 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 |
|
empty | Number of empty 4-KB pages | Not applicable |
expdt | Expiration date for the image copy | Not applicable |
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 |
|
full_days | Number of days since the last FULL YES image copy as recorded in SYSIBM.SYSCOPY | 0 through 255 If restrict=Y, full_days=0. |
full_hours | Number of hours since the last FULL YES image copy as recorded in SYSIBM.SYSCOPY | 0 through 255 If restrict=Y, 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) | Not applicable |
icbackup | Image copy backup type This type corresponds to the COPYDDN or RECOVERYDDN DD statements. |
|
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, 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. You make 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 |
|
mgmtclas | SMS management class | Not applicable |
otype | Object type being copied |
|
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. You make all specifications based on the logical partition number. The automation control point sets the dsnum variable to the physical partition number. | Same as the value of dsnum |
primary | For DASD allocation, the primary space allocation to use | Not applicable |
restrict | Whether the current object is in a DB2 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 |
|
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. |
|
stmt | SYSIN statement number | Not applicable |
storclas | SMS storage class | Not applicable |
tapedd | DD for tape unit | Not applicable |
tsname | Name of the table or index space being copied | Not applicable |
tstype | Type of table space being copied |
|
unittype | Unit type | Not applicable |
vcatname | High-level qualifier for the object being processed | Not applicable |
Lastmediacall | Whether this is the last time to call XCPYMDIA |
|
Return codes
The XCPYMDIA 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. |
Additional considerations
Review the following information before using this automation control point.
gdglimit | |
media | The media variable is set once for each ICBACKUP. If you are using primary and recovery image copies (for example, an LP and an RP copy), one copy can be on DASD and the other can be on tape. This consideration applies to both table space and index copies. |
media, tapedd, and unittype | XCPYMDIA uses the media variable and can set the unittype variable when dynamically allocating DASD. If not dynamically allocating, XCPYMDIA uses a preset DD name (for example, //LP1) and the DD statement determines the unit type. For tape, XCPYMDIA uses preset DDs unless the tapedd variable is set. If the tapedd variable is set, DDs for tape devices must be allocated in the tape server. You can allocate tape devices in the tape server either by using the XSVRJCL automation control point to define DDs for LP, LB, RP and RB; or by performing the allocation in the XCPYINIT automation control point. |
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 |