XSUTDBMG (database manager) automation control point

Use the XSUTDBMG automation control point to control allocation and processing of VSAM work data sets that BMC AMI Utilities use internally.

The product invokes this automation control point at startup.

Variables

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

Related topics

Automation-control-points

Data-set-allocation-automation-control-points 



Variable name

Contents

Possible values

Notes

calltype

Type of database call

  • A (allocate)
  • X (extend)


changedsn

Whether the work data set name can be changed

  • Y (yes)
  • N (no)


dataclas

SMS data class

Not applicable


dsname

NGTVSAM data set name

Not applicable


dsnum

Number of work files to preallocate

Not applicable

dssize

Size limit for preallocated work files

Value in tracks

mgmtclas

SMS management class

Not applicable


newvol

A list of volumes used to extend the data set named in the dsname variable

Not applicable

primary

Primary track allocation

Not applicable


secondary

Secondary track allocation

Not applicable

The value for secondary must be greater than 0. Using a value of 0 for this variable will produce unpredictable results.

storclas

SMS storage class

Not applicable


unitname

Device type for allocation of the work data set

  • Esoteric unit name, such as SYSALLDA
  • Specific DASD device


usespace

Whether to specify primary or secondary space on the IDCAMS DEFINE statement

This variable is valid only when using the data class OVERRIDE SPACE YES attribute.

  • Y (yes, default)
  • N (no)

volumes

A list of volumes that the original IDCAMS DEFINE operation uses.

Not applicable

Return codes

The XSUTDBMG 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 rc variable to any non-zero value to cancel the entire job.

Usage considerations

Review the following information before using this automation control point.

Work file considerations

At the start of all BMC AMI Utilities processing, the utility creates VSAM work files. The work files use the following suffixes:

  • .WK00001, which indicates a scratch file that the utility uses for processing.
  • .RGTS001, which indicates a copy file that the utility uses for processing.

As these files grow to their maximum allocated sizes, the utility generates additional files, numbered serially, as needed (for example, RGTS002, RGTS003, RGTS004).

Important

To avoid space allocation problems, BMC recommends that you define these work files with small primary allocations and large secondary allocations. BMC AMI Utilities processing generally needs the secondary allocation only when operating on very large table spaces.

The space requirements for these files are the same as those for the VSAM table space.

The utility deletes .WK0000n files at the successful completion of a job.

The .RGTS00n file is the temporary image copy file for BMC AMI Reorg processing and is only generated when Reorg processing is active. BMC AMI Reorg deletes this file at the successful completion of a job.

dsnum and dssize variables

The following considerations apply to the dsnum and dssize variables:

  • The utility uses the dsnum and dssize variables to control the preallocation, maximum file size, and parallel use of large work files.
  • Setting a value greater than 1 for dsnum during the allocation of a work file enables 4-byte track addressing, which greatly increases the maximum size of each work file data set.

  • When dsnum is set to a value greater than one (n) for a particular work-file allocation, the utility allocates n+1 work files. The utility uses multiple work files in parallel to reduce contention.

    You can specify a value for dssize to limit the maximum size of the initial n work files, preventing the initial allocation from being too large. The dssize variable does not limit data sets n+1 and greater.

usespace variable

Set the usespace variable to N to specify dataclas on the IDCAMS DEFINE without specifying primary or secondary. Do not also set primary or secondary as those values would contradict the DATACLAS SPACE OVERRIDE.

volumes and newvol variables

The volumes and newvol variables have slightly different purposes, both related to the management of any work data sets:

  • The utility uses the volumes variable to set one or more volumes for use by the IDCAMS DEFINE statement, which creates VSAM work data sets.
  • The utility uses the newvol variable to set one or more volumes for use by the IDCAMS ALTER ADDVOLUMES statement, which extends VSAM work data sets.
Example

If the volumes variable is set with the following statement, then processing will define the data set on three different volumes:

volumes = '*,*,*'

If the variable newvol is set with the following statement, the utility will use just one volume for extension (which is likely sufficient if the volumes variable is set to four or more volumes):

newvol = '*'

If you want to use three additional volumes for extension of the work data sets, you would specify the following newvol statement:

newvol = '*,*,*'

Important

In a non-SMS installation, provide specific volume names for volumes and newvol variables.

newvol variable on extend calls

The newvol variable can be printed out any time, but it might also be changed when work data sets are extended.


 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*