Utility parameters on the EXEC statement

The

BMC AMI Copy

EXEC statement includes the following utility parameters:

A Db2 subsystem ID or group attachment name for Db2 data sharing (ssid)
A utility ID (utilID)
An optional parameter that specifies whether this job is a new job, a restart, or a termination—or whether you are checking the current maintenance level of the utility or checking the syntax of the commands in SYSIN (restartParm)
An optional message level parameter (msgLevel)
An optional parameter that specifies an installation options module for the job (optsModule)

The following illustration shows the format of the EXEC statement:

//stepname EXEC PGM=ACPMAIN,REGION=0M,
// PARM='ssid, utilID, restartParm, msgLevel, optsModule',

The parameters are positional and must be specified in the order shown. If you do not specify a value for a parameter, BMC AMI Copy uses the default. If you do not specify a value for a parameter, you must substitute a comma for that parameter if additional parameters follow. The comma indicates that a parameter was omitted.

In this example, the subsystem ID (ssid) and the restart parameter (restartParm) are specified; defaults apply for the utility ID (utilID), the message level (msgLevel), and the installation options module (optsModule) parameters.

Example

// PARM='ssid ,,restartParm'

The EXEC statements contained in the examples in Examples-of-BMC-AMI-Copy-jobs show typical parameter coding for BMC AMI Copy job EXEC statements. If you are using a job that uses a JCL PROC, ensure that quotation marks, commas, and parentheses are correctly used in the EXEC statement. For an example of a job that uses a JCL PROC, see Example-19-Using-a-JCL-PROC-to-run-BMC-AMI-Copy.

Db2 subsystem ID (ssid)

This parameter specifies the ID of the Db2 subsystem where the space resides.

You can also use the group attachment name (Db2 data sharing) in place of the ssid parameter. This allows you to use the same JCL but run on any member of a data sharing group.

If you do not specify this parameter, BMC AMI Copy uses the default subsystem ID from the DSNHDECP module. If DSNHDECP is not available, an S806 abend results.

Utility ID (utilID)

This parameter specifies the ID that uniquely names a utility execution or job step.

If you do not specify this parameter, BMC AMI Copy uses the default, userID.jobName. The rules for utility ID are as follows:

The utility ID is from 1 to 16 characters.
The utility ID consists of alphanumeric characters, plus the following characters: #, $, @, !, ¬, . , and ¢.

When you run multiple BMC AMI Copy jobs concurrently, each job must use a unique utility ID.

Restart parameter (restartParm)

The value that you choose for this parameter determines whether this is:

A new utility execution or job step
An execution or job step you want to restart
An execution or job step you want to terminate

For more information, see Restarting-a-failed-BMC-AMI-Copy-job and Terminating-a-BMC-AMI-Copy-job-during-execution.

Restart parameter values (described in detail later in this section) are also available to:

Perform syntax checking on statements in your SYSIN data set without actually performing any other BMC AMI Copy utility functions
Print control section information to track maintenance that has been applied and list BMC AMI Copy tables names without performing any other processing
Instruct BMC AMI Copy to identify data sharing agents and terminate them

When you use:

RESTART, RESTART(PHASE), NEW/RESTART, or NEW/RESTART(PHASE), and a row already exists in the BMCUTIL table for the same utility ID, the space name from the row in the BMCUTIL table must match the space named in the current SYSIN data set (for the command number in the table). You must also use the same SYSIN options as in the original execution.
NEW/RESET and a row already exists in the BMCUTIL table for the same utility ID, BMC AMI Copy first resets the space status from the row in the BMCUTIL table and then performs the commands for the spaces named in the current SYSIN data set.
NEW, TERM, TERM/RESET, NEW/RESET, or start a new job by leaving the restart parameter blank, you can change the SYSIN options.

The following sections describe each value that you can use with the restart parameter.

Value	Description
MAINT	Specifying MAINT prints control section (CSECT) information that tracks the maintenance applied to BMC AMI Copy. (The information printed is helpful when verifying whether a fix has been applied.) BMC AMI Copy performs no other processing when you specify this restart parameter. Installation option defaults and dynamic allocation defaults are also printed. Specifying the MAINT parameter with MSGLEVEL(1) (see Message level parameter (msgLevel) prints the names of the BMC tables used by BMC AMI Copy. Specifying the MAINT parameter with MSGLEVEL(2) (see Message level parameter (msgLevel)) prints the names of the BMC tables used by BMC AMI Copy, and additionally, prints all rows within those tables.
NEW	Specifying this value starts a new BMC AMI Copy utility execution or job step and allows you to reuse a utility ID that already exists in the BMCUTIL table. Any existing BMC AMI Copy utility with the same ID is replaced. If the utility ID does not already exist, a new utility is started. If you do not use NEW and a utility with the same ID already exists, before you can use that ID again, you must either wait for the existing utility to complete or terminate it. Then, you can restart the utility using the same ID. Important If a failed BMC AMI Copy job changed the space status and you want to restart the job using NEW, you might need to manually restart the space in its original status (by using the Db2 START command). BMC AMI Copy saves the original status in the BMCUTIL table, but restarting with NEW replaces that information. If you restart the job using NEW/RESET instead of NEW, a manual restart is unnecessary. For more information, see Initial-status-considerations-for-copy-jobs. Warning The following conditions apply to NEW: When you use NEW with an active utility ID that already exists in the BMCUTIL table (determined by an MVS enqueue), the new job fails and BMC AMI Copy issues the message BMC30564. If a job using FULL YES and RESETMOD YES fails in the COPY phase, using NEW when you restart the job will cause an entry of ICTYPE T to be made for the space in SYSIBM.SYSCOPY. This prevents BMC AMI Copy from making an incremental copy.
NEW/RESET	Specifying NEW/RESET starts a new BMC AMI Copy utility execution or job step in the same way as NEW. However, when you use NEW/RESET, if a value for the original space status already exists in the BMCUTIL table and if BMC AMI Copy detects that status has changed, BMC AMI Copy first resets the space status to the original value. Warning The following conditions apply to NEW/RESET: When you use NEW/RESET with an active utility ID that already exists in the BMCUTIL table (determined by an MVS enqueue) , the new job fails and BMC AMI Copy issues the message BMC30564. If a job using FULL YES and RESETMOD YES fails in the COPY phase, using NEW/RESET when you restart the job will cause an ICTYPE T entry to be made for the space in SYSIBM.SYSCOPY. This prevents BMC AMI Copy from making an incremental copy.
NEW/RESTART	If the SHRLEVEL value is other than CONCURRENT , specifying NEW/RESTART restarts the utility from the last recorded sync point if the utility ID already exists in the BMCUTIL table. If the utility ID does not exist, this parameter starts the job as a new BMC AMI Copy utility job. For more information, see Restarting-from-the-point-of-failure. Important A sync point is a point within an BMC AMI Copy phase at which a job can be successfully restarted; all of the information necessary for a successful restart is recorded in the BMCUTIL table when a sync point occurs. Warning When you use NEW/RESTART with an active utility ID that already exists in the BMCUTIL table (determined by an MVS enqueue), the new job fails and BMC AMI Copy issues the message BMC30564.
NEW/RESTART(PHASE)	Specifying NEW/RESTART(PHASE) restarts the utility at the beginning of the last incomplete BMC AMI Copy phase if the utility ID already exists. The BMC AMI Copy phases are UTILINIT, COPY, RECALL, MODIFY, and UTILTERM. If the utility ID does not exist, this parameter starts the job as a new copy utility. For more information, see Restarting-from-the-point-of-failure. Important Do not specify NEW/RESTART(PHASE) when restarting a failed incremental image copy job. For more information, see Recommended-practices-for-making-incremental-image-copy-practices.
PARSE	Specifying PARSE causes the commands in SYSIN to be analyzed and creates a parameter list from the information. This process provides syntax checking and wild card expansion without actually running the BMC AMI Copy utility. When you specify the PARSE restart parameter, BMC AMI Copy does not register the utility ID in the BMCUTIL table. Important The BMC160644I message is displayed only if PARSE is specified.
Restart parameter left blank or not specified	When you leave the restart parameter blank or do not specify it, default restart processing is performed. A new BMC AMI Copy utility execution or job step is initiated if the utility ID does not exist in the BMCUTIL table. If the utility ID already exists in the table, an error message is generated. You cannot specify any value (other than blank or not specified) for the restart parameter when Db2 is down because all other values require access to Db2.
RESTART	Specifying RESTART restarts the utility with the failed space. For more information, see Restarting-from-the-point-of-failure.
RESTART(PHASE)	Specifying RESTART(PHASE) restarts the utility at the beginning of the last incomplete BMC AMI Copy phase. For more information, see Restarting-from-the-point-of-failure. Important Do not specify RESTART(PHASE) when restarting an incremental image copy. Use either NEW/RESTART or RESTART. For more information, see Recommended-practices-for-making-incremental-image-copy-practices.
SHOWAGENTS	Specifying SHOWAGENTS instructs BMC AMI Copy to identify any BMC AMI Copy data sharing agents connected to the XCF group. No other processing is done by BMC AMI Copy. Important A subsystem ID is not needed because BMC AMI Copy does not connect to Db2.
TERM	Specifying TERM terminates a stopped or failed utility by removing all sync point and restart information for the utility ID from the BMCUTIL and BMCSYNC tables and from XBM. After removing all sync point and restart information from BMCUTIL, BMC AMI Copy terminates without completing the copy or modify operation. Important If you are making copies and want to terminate a job using TERM, you might need to manually start the space in its original status (by using the Db2 START command). BMC AMI Copy saves the original status in the BMCUTIL table. However, if you terminate the job using TERM/RESET instead of TERM, the space is started automatically and a manual restart is unnecessary. For more information, see Initial-status-considerations-for-copy-jobs. Warning If a copy job using FULL YES and RESETMOD YES fails in the COPY phase, using TERM when you restart the job causes an ICTYPE T entry to be made for the space in SYSIBM.SYSCOPY.
TERM/RESET	Specifying TERM/RESET terminates a stopped or failed utility by removing all sync point and restart information for the utility ID from the BMCUTIL and BMCSYNC tables and from XBM. However, when you use TERM/RESET, BMC AMI Copy resets the status of the space being processed or awaiting restart to the original value before terminating the utility information. Warning If a copy job using FULL YES and RESETMOD YES fails in the COPY phase, using TERM/RESET when you restart the job causes an ICTYPE T entry to be made for the space in SYSIBM.SYSCOPY.
TERMAGENTS	Specifying TERMAGENTS instructs BMC AMI Copy to identify any BMC AMI Copy data sharing agents connected to the XCF group and issue a call to terminate them. No other processing is done by BMC AMI Copy. Note that a subsystem ID is not needed because BMC AMI Copy does not connect to Db2. (For more information, see Copy-registration-in-a-data-sharing-environment-for-SHRLEVEL-CHANGE.)

Message level parameter (msgLevel)

This parameter determines which messages are returned in the print output data set, SYSPRINT.

If you specify the default, MSGLEVEL(0), normal procedural messages associated with the BMC AMI Copy job are returned.
If you specify MSGLEVEL(1), additional messages are returned that you can use to enhance job performance. Additionally, the installation options module settings are displayed.
Specifying MSGLEVEL(1) with the MAINT parameter (see Restart parameter (restartParm)) prints the names of the BMC tables used by BMC AMI Copy.
If you specify MSGLEVEL(2), BMC AMI Copy includes additional performance and diagnostic messages in the output. These additional messages are used for performance analysis and problem determination.

Installation options module parameter (optsModule)

This parameter tells BMC AMI Copy which installation options module to use for the current job.

The following rules apply:

If you do not specify this parameter, BMC AMI Copy uses the installation options module, ACP$OPTS.
If you want to provide the name of one of your own installation options modules and the name is not prefixed with ACP$, BMC AMI Copy adds that prefix for you. The name you provide must have from one to four characters.
If you want to provide the name of one of your own installation options modules and the name includes the prefix ACP$, BMC AMI Copy uses the name as-is. The entire name can contain no more than eight characters.

Note

Do not use the reserved name ACP$AUTH for an installation options module.