Utility parameters on the EXEC statement
// 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,
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.
The EXEC statements contained in the examples in Examples-of-BMC-AMI-Copy-jobs show typical parameter coding for
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,
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,
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
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
utility functions
- Print control section information to track maintenance that has been applied and list
tables names without performing any other processing
- Instruct
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,
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 . (The information printed is helpful when verifying whether a fix has been applied.) 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 . Specifying the MAINT parameter with MSGLEVEL(2) (see Message level parameter (msgLevel)) prints the names of the BMC tables used by , and additionally, prints all rows within those tables. |
NEW | Specifying this value starts a new utility execution or job step and allows you to reuse a utility ID that already exists in the BMCUTIL table. Any existing 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. |
NEW/RESET | Specifying NEW/RESET starts a new 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 detects that status has changed, first resets the space status to the original value. |
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 utility job. For more information, see Restarting-from-the-point-of-failure. |
NEW/RESTART(PHASE) | Specifying NEW/RESTART(PHASE) restarts the utility at the beginning of the last incomplete phase if the utility ID already exists. The 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. |
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 utility. When you specify the PARSE restart parameter, does not register the utility ID in the BMCUTIL table. |
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 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 phase. For more information, see Restarting-from-the-point-of-failure. |
SHOWAGENTS | Specifying SHOWAGENTS instructs to identify any data sharing agents connected to the XCF group. No other processing is done by . |
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, terminates without completing the copy or modify operation. |
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, resets the status of the space being processed or awaiting restart to the original value before terminating the utility information. |
TERMAGENTS | Specifying TERMAGENTS instructs to identify any data sharing agents connected to the XCF group and issue a call to terminate them. No other processing is done by . Note that a subsystem ID is not needed because 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
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
.
- If you specify MSGLEVEL(2),
includes additional performance and diagnostic messages in the output. These additional messages are used for performance analysis and issue determination.
Installation options module parameter (optsModule)
This parameter tells
which installation options module to use for the current job.
The following rules apply:
- If you do not specify this parameter,
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$,
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$,
uses the name as-is. The entire name can contain no more than eight characters.