XULDDYNM (unload data set and discards) automation control point
Variables
The following table describes the variables used in the XULDDYNM automation control point:
Variable name | Contents | Possible values | Notes |
|---|---|---|---|
alloc_syspunch | Whether to allocate a SYSPUNCH or SYSCNTL data set |
| This variable only applies if no SYSPUNCH or SYSCNTL JCL DD or OUTPUT statement is provided when generating the Load statement. This variable determines whether a generated data set name should be dynamically allocated (see notes for dsname). The default for this variable is N (no). |
dataclas | For SMS-managed data sets, value of DATACLAS | Not applicable | When the automation control point sets the dataclass variable, it ignores the unitname variable. The value of these variables are passed to the XSUTDYNM automation control point for further analysis if needed. |
dbid | Database ID | Not applicable | |
dbname | Database name | Not applicable | |
disp | Disposition for the unload data set This variable corresponds to the NORMAL DISP DD specification. |
| If the value of disp for each unload output DD is D, then the utility skips the entire unload operation without any additional warning. In this case, BMC recommends that you include the say statement in your automation control point to write a message to the CDBPRINT output listing. |
dsname | Unload data set name | Maximum of 44 characters | This variable is required. When generating a Load statement and alloc_syspunch is set to 'Y', the data set name returned by this variable is dynamically allocated if no SYSPUNCH or SYSCNTL JCL DD or OUTPUT statement is provided. You can specify a generation data group (GDG) data set by suffixing the name with (+1). (Any other value such as (+2) or (+01) is an error.) |
dsnum | Partition number | Not applicable | |
expdt | Expiration date | Not applicable | |
fseq | For VTS units, the next physical file sequence number | Not applicable | The automation control point can inspect or reset this variable. A value of 1 indicates that the data set should start on a new volume. The automation control point will ignore a change to this variable except for a value of 1. If the tapedd variable contains the value NONE, then the value of this variable will be 0. |
format | Format for the unload operation as indicated on the unload statement |
| |
gdglimit | Number passed as the LIMIT keyword of a DEFINE GDG command This variable applies for GDG data sets when a GDG base data set does not exist. | Not applicable | |
has_vars | Whether the table being unloaded has variable-length records |
| |
icdsn | Image copy data set name used when unloading from an image copy | Maximum of 44 characters | |
lob_columns | Number of LOB columns | Not applicable | |
lobocol# | Column number, when lobotype is O | Not applicable | |
lobotype | LOB unload type |
D is the default | |
lobs_size | Size of all LOBs, in megabytes | Not applicable | |
maxvol | For DASD allocation, the number of volumes used to satisfy the original space request in excess of 500 cylinders | 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. The maximum value for this variable is 59. | |
media | Media type for the unload data set |
| This variable is required. |
mgmtclas | For SMS-managed data sets, the value of MANAGEMENTCLAS | Not applicable | |
obid | Object ID of the referenced table name | Not applicable | |
parts | Total number of partitions in the table space | 0 or a positive integer 0 indicates that an object is not partitioned | |
primary | For DASD allocation, the primary space allocation to use | Not applicable | |
rc | Return code for the automation control point | SeeReturn codes | |
recfm | Record format for the unload data set |
| This variable is applicable to the DSNTIAUL and EXTERNAL output formats only, but the automation control point validates it for all the output formats. You can use this variable as an alternative or as an override to the PAD/NOPAD keyword specification on the UNLD DATA statement. |
recsize | Output record size | Not applicable | |
retpd | Retention period for the unload data set | Not applicable | |
rows | Number of rows in the table | Not applicable | |
rowsfrom | Source for the rows and size variables |
| |
secondary | For DASD allocation, the secondary space allocation to use When the automation control point receives control, this value for this variable is half the value of the primary variable. | Not applicable | The value for this variable must be greater than 0. A value of 0 produces unpredictable results. |
size | Estimate of the space needed for the output data set, based on information about the data that will be sent to the resulting file | Not applicable | |
spaceunit | Space allocation unit of the primary and secondary variables |
| |
spanned | Whether the output data set is in spanned-record format |
| |
stmt | Statement number | Not applicable | |
storclas | For SMS-managed data sets, the value of STORCLAS | Not applicable | |
tapedd | For VTS units, the DD name of the VTS unit allocated If tapedd='NONE', you cannot use VTS. | Not applicable | |
tapesize | Number of 4-KB pages scheduled for a specific VTS unit The automation control point can use this value to set fseq to 1, starting a new volume. | Not applicable | |
tbname | Table name as it appears on the unload statement | Not applicable | |
tbcreator | Creator or owner of the table | Not applicable | |
tsname | Table space name | Not applicable | |
type | Type of data set being allocated |
| |
unitname | If media=D, the DASD unit name | A valid DASD unit name (such as SYSDA) | |
vcatname | High-level qualifier for the object being processed | Not applicable | If partitions of the same table space have different VCAT names, this value might not be correct. |
Return codes
The XULDDYNM 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
You cannot use this feature if your unload output is directed to specific volumes on either disk or tape (for example, if you name a specific volser in a DD statement).
Additional considerations
Review the following information before using this automation control point.
Real-time statistics (RTS) and the sizing variables
When RTS are available (rowsfrom='RTS'), BMC AMI Unload has accurate estimates for the rows, size, primary, and secondary variables. When RTS are not available (rowsfrom='PGS'), BMC AMI Unload must estimate these variables from allocated pages. To prevent under allocation, BMC AMI Unload assumes that the data pages are compressed and that they contain 255 rows per page. If RTS is not current for the object, BMC AMI Unload might overestimate the values for these variables.
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.
Additional variable information
The following table summarizes which type of allocation the XULDDYNM variables apply to and whether XULDDYNM can change their values:
Variable name | XULDDYNM can change | Applies to DASD allocation | Applies to VTS allocation |
|---|---|---|---|
dataclas | Yes | Yes | Not applicable |
dbname | Not applicable | Not applicable | Not applicable |
disp | Yes | Yes | Yes |
dsname | Must set | Yes | Yes |
dsnum | Not applicable | Not applicable | Not applicable |
format | Not applicable | Not applicable | Not applicable |
fseq | Yes | Not applicable | Yes |
gdglimit | Yes | yes | Yes |
icdsn | Yes | Not applicable | Not applicable |
maxvol | Yes | Yes | Not applicable |
media | Yes | Yes | Yes |
mgmgclas | Yes | Yes | Not applicable |
part | Not applicable | Not applicable | Not applicable |
parts | Not applicable | Not applicable | Not applicable |
primary | Yes | Yes | Not applicable |
rc | Yes | Not applicable | Not applicable |
recfm | Not applicable | Not applicable | Not applicable |
secondary | Yes | Yes | Not applicable |
size | Not applicable | Not applicable | Not applicable |
spaceunit | Not applicable | Not applicable | Not applicable |
storclas | Yes | Yes | Not applicable |
tapedd | Yes | Not applicable | Yes |
tapesize | Not applicable | Not applicable | Yes |
tapevols | Not applicable | Not applicable | Yes |
tbcreator | Not applicable | Not applicable | Not applicable |
tbname | Not applicable | Not applicable | Not applicable |
tsname | Not applicable | Not applicable | Not applicable |
unitname | Yes | Yes | Not applicable |
vcatname | Not applicable | Not applicable | Not applicable |
Changing media
You can change the media variable from T (tape) to D (disk) but not from D to T. Unloading to tape requires the XULDMDIA allocation control point.
Mixing allocation methods
You can mix statically-allocated (specified with a DD statement) and dynamically-allocated copy and unload data sets when using multiple copy and unload statements in a single job step. However, a single copy or unload statement cannot have both statically-allocated and dynamically-allocated data sets.
Dynamic discard processing
For BMC AMI Unload, if a DISCARDDN DD statement is not present in the primary JCL, BMC AMI Unload calls XULDDYNM, and automatically allocates a discard data set. In addition, variables are populated as follows:
- BMC AMI Unload passes the name of the first table in the list of tables from which discards occur
- The rowsource variable contains the value DISC
- The recfm variable contains the value VB
For BMC AMI Reorg or BMC AMI Reorg AUX YES, the utility invokes XULDDYNM and automatically allocates a discard data set when either of the following conditions exists:
- The DISCARD FROM TABLE clause is present in the SYSIN command statement.
The reorganization materializes pending limit key changes, and rows exist after the new last limit key.
Limit keys are altered during the reorganization and rows exist after the new last limit key. In this case, BMC AMI Reorg deletes the rows found after the new last limit key.
If you specify DISCARDDN, do not specify a DD name in your JCL to correspond to the DISCARDDN option. For an example, see the following figure:
// NOTIFY=&SYSUID,PRTY=9,REGION=0M
//********************************************************************
//*
//* REORG WITH DISCARDS TO A DYNAMICALLY DEFINED DATASET. THE
//* AUTOMATION EXIT XULDDYNM MUST EXIST IN THE 'NGT.EXITS'
//* AUTOMATION EXIT LIBRARY.
//*
//********************************************************************
//JOBLIB DD DISP=SHR,DSN=NGT.PROD.LOAD
// DD DISP=SHR,DSN=DSN810.SDSNLOAD
// DD DISP=SHR,DSN=DSN810.SDSNEXIT
//*
//REORGGL EXEC PGM=NGTUTIL,PARM='DSN8,,NORESTART'
//NGTEXEC DD DISP=SHR,DSN=NGT.EXITS
//SYSERROR DD SYSOUT=*
//SUMMARY DD SYSOUT=*
//SORTOUT DD SYSOUT=*
//SYSPRINT DD SYSOUT=*
//RUNSTATS DD SYSOUT=*
//SYSOUT DD SYSOUT=*
//**
//** SYSIN STATEMENT(S)
//**
//JOURNAL DD DUMMY
//SYSIN DD *
REORG TABLESPACE DBA123.GENLEDGR
DISCARDDN(SYSDISC) FORMAT(EXTERNAL)
DISCARD FROM TABLE DBA123.GL_REGION_101
WHERE(ZIP < 77999)
//**
//** GLOBAL PARMS
//**
//UTLPARMS DD *
+WORKPREFIX(DBA123.WORK)
//*********************************************************************
Note the following information about this figure:
- The job uses automation exits. (See the NGTAUTO DD statement.)
- The REORG TABLESPACE statement contains a DISCARDDN keyword that contains a DD name (SYSDISC) that is not specified in a DD statement in the JCL.
- The REORG TABLESPACE statement contains a DISCARD FROM TABLE clause.