JCL setup

This topic describes the changes required for the EXEC card and DD names that are used by BMC AMI Utilities. Some products might use additional DD names.

Tip

If you are using JCL procedures (PROCS) to run your BMC AMI Utilities, you might require only the following changes to implement those products:

Change the program name
Change the STEBLIB in PROCS

The following figure shows a sample of basic JCL for running BMC AMI Utilities. Numbered lines are described following the figure. The JCL is grouped to show related elements. The order of the DD statements is not significant.

PTF BQU2361 applied
PTF not applied

//jobname JOB REGION=0M
//*
//********************************************************************
//* REQUIRED STATEMENTS - MINIMUM FOR RUNNING A UTILITY
//********************************************************************
//UTILSTEP EXEC PGM=NGTUTIL,PARM='DB2B,MYREORG,RESTART'
//STEPLIB DD DSN=NGT.UTILITY,DISP=SHR
//SYSPRINT DD SYSOUT=*
//SYSIN DD *
  <utility-control-statements>
  <utility-control-statements>
  <utility-control-statements>
//********************************************************************
//* GLOBAL PARAMETERS - USE TO OVERRIDE INSTALLATION OPTIONS
//********************************************************************
//UTLPARMS DD DSN=NGT.CNTL(PARMS ),DISP=SHR
//*
//********************************************************************
//* SPECIFIC UTILITY PARAMETERS - USE TO OVERRIDE INSTALLATION OPTIONS
//********************************************************************
//xxxPARMS DD DSN=NGT.CNTL(PARMSxxx),DISP=SHR
//*
//********************************************************************
//* AUTOMATION SUPPORT (OPTIONAL)
//********************************************************************
//NGTAUTO DD DSN=NGT.REXX.EXEC,DISP=SHR
//*
//********************************************************************
//* REPORT OUTPUT FILES (OPTIONAL)
//********************************************************************
//CDBPRINT DD SYSOUT=*
//CDBPRIN2DD SYSOUT=*
//SUMMARY   DD SYSOUT=*
//RUNSTATS DD SYSOUT=*
//SYSTSPRT DD SYSOUT=*
//SYSERROR DD SYSOUT=*
//*
//********************************************************************
//* DIAGNOSTIC RESOURCES (OPTIONAL)
//********************************************************************
//LOGPDS DD DSN=NGT.LOGPDS,DISP=SHR
//*
//********************************************************************
//* EDITPROC SUPPORT (OPTIONAL)
//********************************************************************
//EDITPLIB DD DSN=USER.EDIT.PROC.LIB,DISP=SHR
//*
//********************************************************************
//* AGING REPORT (OPTIONAL)
//********************************************************************
//AGEREPRT       DD SYSOUT=*

//jobname JOB REGION=0M
//*
//********************************************************************
//* REQUIRED STATEMENTS - MINIMUM FOR RUNNING A UTILITY
//********************************************************************
//UTILSTEP EXEC PGM=NGTUTIL,PARM='DB2B,MYREORG,RESTART'
//STEPLIB DD DSN=NGT.UTILITY,DISP=SHR
//SYSPRINT DD SYSOUT=*
//SYSIN DD *
  <utility-control-statements>
  <utility-control-statements>
  <utility-control-statements>
//********************************************************************
//* GLOBAL PARAMETERS - USE TO OVERRIDE INSTALLATION OPTIONS
//********************************************************************
//UTLPARMS DD DSN=NGT.CNTL(PARMS ),DISP=SHR
//*
//********************************************************************
//* SPECIFIC UTILITY PARAMETERS - USE TO OVERRIDE INSTALLATION OPTIONS
//********************************************************************
//xxxPARMS DD DSN=NGT.CNTL(PARMSxxx),DISP=SHR
//*
//********************************************************************
//* AUTOMATION SUPPORT (OPTIONAL)
//********************************************************************
//NGTAUTO DD DSN=NGT.REXX.EXEC,DISP=SHR
//*
//********************************************************************
//* REPORT OUTPUT FILES (OPTIONAL)
//********************************************************************
//CDBPRINT DD SYSOUT=*
//SUMMARY   DD SYSOUT=*
//RUNSTATS DD SYSOUT=*
//SYSTSPRT DD SYSOUT=*
//SYSERROR DD SYSOUT=*
//*
//********************************************************************
//* DIAGNOSTIC RESOURCES (OPTIONAL)
//********************************************************************
//LOGPDS DD DSN=NGT.LOGPDS,DISP=SHR
//*
//********************************************************************
//* EDITPROC SUPPORT (OPTIONAL)
//********************************************************************
//EDITPLIB DD DSN=USER.EDIT.PROC.LIB,DISP=SHR
//*
//********************************************************************
//* AGING REPORT (OPTIONAL)
//********************************************************************
//AGEREPRT       DD SYSOUT=*

The line numbers in the following table refer to basic JCL for BMC AMI Utilities.

Line no.

Name

Description

JOB name

(optional) Job statement name according to your installation standards

Include the REGION parameter on either your JOB statement or your EXEC statement to specify the region size (the amount of virtual storage that the product uses).

For the best performance, BMC recommends that you specify REGION=0M to allocate the optimal amount available virtual storage to the product job. If your data center does not permit you to specify REGION=0M, specify the amount that allows the most virtual storage both above and below the 16-megabyte line. Using a region size that is less than optimal risks the following issues:

Running less efficiently, which could result in additional CPU and elapsed time
Encountering memory failures or jobs that fail when you implement new versions

EXEC statement

Step name according to your installation standards

You specify the positional parameters for BMC AMI Utilities required to run those products via the PARM= clause. You can use the following positional parameters:

(required) SSIDThe target Db2 subsystem you wish to run against.
UIDThis identifier is logged in BMC AMI Utilities NGTCKPT control data sets and is used with other information as part of an enqueuing mechanism across your system with other BMC AMI Utilities jobs. The default UID is the jobname specified on the JOB card (not userid.jobname, which the Db2 default). The example in Basic JCL uses the default jobname.
(optional) Restart parameter
You can omit a restart parameter (in which case the default value is RESTART), or use one of following restart parameters:

RESTART

BMC AMI Utilities restart if a prior run with the same UID failed, or treat this run as if the run had never started (that is, started at the beginning).

RESTART(PHASE)

This is equivalent to RESTART.

You can specify this parameter to maintain compatibility with the Db2 RESTART(PHASE) parameter.

Example

The input control stream is a set of 500 COPY statements and the run terminated after 100 had finished. If you specified RESTART, the product restarts at COPY 101 and continues.

QUICKEXIT

TERM can be used as a synonym for QUICKEXIT.

If a prior run with the same UID failed, QUICKEXIT completes the failed run in the most efficient manner.

QUICKEXIT backs out to a point of consistency, or restarts and completes the failed run, and then terminates. If the prior run did not fail, it terminates. You can use this option to clean up work data sets and free up the UID for use by another job.

The return code (rc variable) from a job with a restart parameter value of QUICKEXIT can take the following values:

rc=0, if all objects completed
rc=4, if any object was not processed
rc=8, if QUICKEXIT failed, or the UID was not found
rc=16, if QUICKEXIT failed while in the copy phase of reorganization

Example

You run the following statement: REORG TABLESPACE DB1.%, and DB1 contains table spaces TS1 and TS2.

The return code varies depending on the QUICKEXIT run scenario:

QUICKEXIT run scenario	Return code
The reorganization has failed while processing TS1. TS2 had not yet started. +CLEANUP(NO) was specified. The UID is restartable. You submit QUICKEXIT and it runs successfully, that is: It removes TS1 from the MATRIX/UTIL/SYNC. It cleans up work data sets. It removes the UID.	The return code is 4 because the reorganization for TS1 and TS2 did not complete. Table spaces T1 and T2 are considered to be excluded.
The reorganization completed for TS1, but failed while processing TS2 during the copy phase.	If you submit QUICKEXIT, it must finish the copy, as the reorganization has already completed. Unlike in the previous scenario, you cannot simply remove the TS2 from the MATRIX/UTIL/SYNC and clean up the work data sets.
QUICKEXIT completes the copy it will then remove the object from the MATRIX/UTIL/SYNC, clean up the work data sets, and get rid of the UID, and the job ends with rc=0.	The return code is 0 because all the object completed.
If QUICKEXIT cannot complete the copy, the job ends with rc=16.	The return code is 16 because the copy phase is SMC (Step Must Complete).

NORESTART

QUICKEXIT completes any prior product with the same UID and the job starts from the beginning.

NORESTART runs only if BMC AMI Utilities can ensure that ignoring a restart will not damage your Db2 data.

TESTUID

BMC AMI Utilities attempt to locate an existing product ID (UID) for the named Db2 subsystem (in SSID). If the UID does exist, NGTUTIL exits with RC=1. If the UID does not exist, NGTUTIL exits with RC=0. The process of verifying the UID does not execute the product.

Important

When you perform a TESTUID, you must use the same Db2 SSID that you originally used to execute the product.

FORCEID

Cleans up and removes the product from the BMC AMI Utilities checkpoint, and deletes work data sets that conform to the +WORKPREFIX naming convention

This parameter also deletes process members from the BMC AMI Utilities checkpoint.

Important

When you perform a FORCEID, you must use the same Db2 subsystem ID that you originally used to execute the product.
Before using FORCEID, review the NGTDISP output and do not use FORCEID for a UID that is in a MUSTCOMPLETE state.
Perform QUICKEXIT and manual product cleanup before using FORCEID. Use FORCEID only as a last resort.

Warning

Seek instructions from BMC Customer Support before using FORCEID.

MAINT

Tells BMC AMI Utilities to print a report listing the fixes installed on the target Db2 subsystem

The job then ends without affecting any product that is running.

Following these three parameters you can specify the BMC PLUS JCL parameters that would follow. They will be tolerated and ignored with one exception, you can specify a DOPTS member to be used by ACPMAIN when it is called by BMC AMI Load or BMC AMI Reorg. The position is important, three commas would be needed. For example SSID,UID,RESTART,,,ACP$OPTS.

STEPLIB DD

(required) STEPLIB or JOBLIB to access the BMC AMI Utilities load library

Important

This library must be APF-authorized.

SYSPRINT DD

(required) SYSPRINT statement to capture product output

From SYSPRINT, the product output is transferred to the CDBPRINT DD data set. The SYSPRINT data set is cleared and released following each step of BMC AMI Utilities.

The SYSPRINT data set provides a valuable diagnostic tool if errors occur. However, some BMC AMI Utilities employ parallel processing, which can result in overlapping outputs in SYSPRINT. The SUMMARY DD statement contains a more readable analysis of the product execution.

SYSPRIN2(PTF BQU2361 applied)

BMC AMI Utilities use SYSPRIN2 to duplicate SYSPRINT messages. If specified, output from the BMC utility can be viewed when you run utility prior to utility completion.

SYSIN DD

(required) The control statements for the products you are executing, for example, Reorg, Load, or Unload.

For more information about SYSIN statements, see SYSIN-statements-other-than-BMC-AMI-Utilities-product-statements.

You can concatenate multiple statements in one SYSIN file, but each statement must process a different object. Each statement must begin on a new line. Alternatively, you can specify +SYSINORDER(HONOR) to process the objects in a single thread, rather than in parallel.

SYSIN is limited to 2 MB.

Example

REORG TABLESPACE dbase1.ts% RTS
REORG TABLESPACE dbase2.% RTS
EXCLUDE TABLESAPCE dbase2.tspace1
REORG TABLESPACE dbase3.tspace9

UTLPARMS DD

(optional) Specifies general execution parameters

For a list of global parameters, see Global-parameters-UTLPARMS.

If you do not specify UTLPARMS, BMC AMI Utilities use the values that were defined during configuration for the specific Db2 subsystem.

Specific utility parameters

(optional) Contains parameters for a particular product

There is one DD statement for each product.

BMC AMI Utilities first read the global parameters from the //UTLPARMS DD statement. Parameters from each of the //xxxPARMS DD statements specify options unique to the product.

If you do not specify parameters for a product, BMC AMI Utilities use the values that were defined during configuration for the specific Db2 subsystem. For more information about these parameters, see the space for the specific BMC AMI Utility.

NGTAUTO DD

(optional) Overrides the data set name for the NGTAUTO PDS that was specified during configuration for the Db2 subsystem

Alternatively, CDBEXEC DD can be specified.

CDBPRINT DD

(optional) CDBPRINT data set

SYSPRINT output routinely goes to CDBPRINT unless CDBPRINT is already allocated. The report output for all BMC AMI Utilities is written to CDBPRINT. All other products report their output to SYSPRINT and then copy the output to CDBPRINT. You do not need to supply this DD unless there are specific situations in which you do not want to dynamically allocate this file.

CDBPRIN2 DD(PTF BQU2361 applied)

(optional) CDBPRIN2 data set

CDBPRIN2 allows you to monitor the progress of BMC AMI Utilities while running in a worklist using Execution JCL. The CDBPRINT output is echoed to CDBPRIN2. Add the CDBPRIN2 DD if you want multiple copies of the CDBPRINT output or to monitor the progress of BMC AMI Utilities.

SUMMARY DD ¹

(optional) SUMMARY statement to capture product output

Compared with SYSPRINT, SUMMARY contains a more organized analysis of the product execution. It includes reports printed at the conclusion of a product run, and does not reflect output overlapped from parallel processing. If this DD statement is specified, summary reports are not printed to SYSPRINT. Instead, they are printed to SUMMARY as each product statement completes. If this DD statement is omitted, the summary reports are printed to SYSPRINT.

RUNSTATS DD¹

(optional) RUNSTATS report

RUNSTATS contains a report showing RUNSTATS values, and messages affirming update of the Db2 Catalog with these values. This report is printed for any product that also updates Catalog RUNSTATS values, such as REORG and LOAD.

Important

If this DD statement is omitted, there is no RUNSTATS report on any statement (including SYSPRINT and SUMMARY).

SYSTSPRT DD

(optional) SYSTSPRT data set

Any messages sent to TSO are also sent to SYSTSPRT. This may include output from automation control points. REXX Displays from automation control points are only sent back to the job if the you have selected Journal level output. If you have selected Journal level output, these displays are sent to CDBPRINT unless this SYSTSPRT DD is included. If SYSTSPRT DD is included, these displays are sent to SYSTSPRT.

SYSERROR DD¹

(optional) Error messages

If this DD statement is not specified, error messages appear only in SYSPRINT. However, if SYSERROR is specified, error messages appear in SYSERROR and SYSPRINT.

LOGPDS DD

(optional) Overrides the data set name for the Log PDS that was specified during configuration for this Db2 subsystem

The Log PDS contains diagnostic information if BMC AMI Utilities abend. For more information, see LOGPDS.

EDITPLIB DD

(optional) You can supply an //EDITPLIB to point BMC AMI Utilities to the Edit Proc library when the following conditions exist:

An Edit Proc is defined on an object that a product is operating against
The Edit Proc is in a load library that is not directly loadable, such as STEPLIB or LINKLIB

If EDITPLIB is allocated, BMC AMI Utilities attempt to load the Edit Proc from this library. If it cannot, BMC AMI Utilities perform an SVC 8 and attempt to let z/OS find the Edit Proc.

AGEREPRT DD

(optional) Aging reports for BMC AMI Utilities

Aging reports for BMC AMI Utilities list the product IDs that are pending deletion.

¹ (PTF BQU1353 applied) This DD is always automatically allocated.

JCL setup

On this page