The CONTROLR Step and Control Parameters
This chapter includes the following topics:
Overview
The CONTROLR step is a special processing step that is automatically generated by Control-M/Restart and inserted into the JCL of the job when Control-M/Restart processing is requested. The CONTROLR step provides the necessary instructions for the appropriate Control-M/Restart processing of the job.
The particular instructions included in the CONTROLR step depend not only on the type of processing requested, but on relevant parameters that can be taken from any of various sources:
-
the CTRPARM and CTMPARM members in the IOA PARM library
These are described in the customization section of the INCONTROL for z/OS Installation Guide.
-
members in the Control-M/Restart PARM library
Table25 describes the members that can be found in this library.
Table 25 Control-M/Restart PARM Library Members
Member
Description
$DEFAULT
Parameters defined in this member apply to all jobs processed by Control-M/Restart
Local members
A local member and the parameters it contains are dedicated to, and apply to, a particular job. Parameters in a local member override parameters in the $DEFAULT member for the particular job.
$EXCLUDE
This member is used to indicate DD statements and data set names to be excluded from Control-M/Restart processing.
$KEEP
This member is used to indicate the names of data sets that must not be deleted by Control-M/Restart.
The parameters of the $DEFAULT (and local) members, and the format of the $EXCLUDE member, are described below.
-
Job scheduling definitions
Parameters in a job scheduling definition override corresponding defaults specified in the CTRPARM member in the IOA PARM library, and override defaults specified in the $DEFAULT member or local members in the Control-M/Restart PARM library.
-
Special DDstatements placed in the JCL for specific job steps
These are relevant only to those specific steps of the job and override all other corresponding instructions.
-
Windows and screens used to enter manual requests
These parameters override any previously specified parameters, except those specified in special DDstatements placed in specific JCL jobs steps in the job.
Although generation of the CONTROLR step is automatic, manual adjustment of the CONTROLR step is permitted.
This chapter contains a description of the CONTROLR step, followed by a description of the control parameters specified in the Control-M/Restart PARM library.
CONTROLR step
The CONTROLR step JCL is listed in Figure 5.
Figure 5 CONTROLR Step JCL
//CONTROLR PROC ARCHF=NULLFILE,PRM=
//CONTROLR EXEC PGM=CTRCTR,PARM='&PRM'
//STEPLIB DD DSN=IOA.PROD.LOAD,DISP=SHR
//DAARCH DD DISP=SHR,DSN=&ARCHF
//DACTRCTL DD DSN=CTR.PROD.CTR.PARM,DISP=SHR
//SYSPRINT DD SYSOUT=*
//DATRACE DD SYSOUT=*
//CDAMSNAP DD SYSOUT=*
//SYSABEND DD SYSOUT=*
//DASTAT DD DISP SHR=SHR,DSN=&STATFIL
//DALIST DD SYSOUT=*
Files referenced by CONTROLR step DD statements are described in Table 26.
Table 26 Files Referenced by CONTROLR Step DD Statements
File |
Description |
---|---|
DAARCH |
Relevant only for restarts For a non-NJE job (meaning, the system in which Control-M processes the job for submission is not a node in an NJE network, and the job is not sent to another node for execution), this data set contains a set of pointers to the archived SYSDATA. For an NJE job (meaning the job is sent to another node for execution), this file contains the actual SYSDATA of all the previous runs of this job. |
DACTRCTL |
Control-M/Restart PARM library, which contains control parameter members. A concatenation of libraries can be specified. Control-M/Restart checks the library for the $DEFAULT member. The member, if it exists, contains control parameters that apply to all jobs. Control-M/Restart retrieves these processing control parameters (and prints the contents of the member to make known the defaults being used). Regardless of whether the $DEFAULT member was found, Control-M/Restart then checks the library for a local member for the job (that is, a member with the same name as the job). If a local member for the job is found, Control-M/Restart retrieves control parameter instructions from that member (and prints the contents of the member). If the same parameters exist in both the $DEFAULT member and the local member, the values in the local member supersede the values in the $DEFAULT member. Control parameters that can be defined in the Control-M/Restart PARM library are described in Control parameters in the Control-M/Restart PARM library. |
SYSPRINT |
File or printer to which messages and reports of the CONTROLR step are written |
DATRACE |
File or printer to which debugging messages are written if problems are encountered in the CONTROLR step. If necessary, BMC Customer Support can provide instructions on how to activate debugging messages. |
CDAMSNAP |
File or printer to which error messages are written if the CONTROLR step encounters a problem in dynamically allocating the archived (compressed) SYSDATA of the previous runs of the restarted job |
DASTAT |
Control-M Statistics file, which is used to hold statistics needed by the Data Set Cross-reference facility |
DALIST |
File containing the list of data sets. The list is generated by the Control-M/Restart Data Set Cross-reference utility. |
Note the following points about the CONTROLR step:
-
for Restarts
-
The CONTROLR step is inserted as the first step of the job to be restarted. Information is inserted in the PARM operand of the CONTROLR step describing how the job is to be restarted (from step, to step, and so on).
-
If the job is sent to another node for execution, then for proper analysis of the job, the output must return to the submitting node.
-
-
for Data Set Cleanup
-
If the NCAT2 parameter in the CTRPARM member in the IOA PARM library is set to YES, Control-M/Restart performs data set cleanup for original job runs. The CONTROLR step deletes and uncatalogs the old data sets, unless the data set name is specified in an EXCLUDE DSN statement in a member in the Control-M/Restart PARM library. This prevents DUPLICATE DATASET ON VOLUME and NOT CATLGD 2 errors.
-
The PREVENT-NCT2 parameter in the Control-M job scheduling definition overrides the site-defined default in the NCAT2 parameter.
-
For data set cleanup of non-rerun and non-restarted jobs, the CONTROLR step is inserted as the first step in the job stream and the edited job JCL is submitted. The CONTROLR step performs the necessary data set cleanup (including step adjustment, if necessary) and then stops. No further job steps are executed.
-
Parameters passed to the CONTROLR step
The EXEC statement of the CONTROLR step contains a PARM parameter that is used to pass information between the Control-M monitor and the CONTROLR step. This information is inserted into the PARM operand by Control-M/Restart logic in the Control-M monitor.
It is possible to use the CTMX002 Control-M user exit and the CTMSE02 Control-M security exit to modify values passed to the CONTROLR step using the PARM operand.
PARM operand information is necessary for the operation of Control-M/Restart facilities that are activated during the execution of the CONTROLR step.
The format of the EXEC statement is
//CONTROLR EXEC CONTROLR,
// PARM='type,mem,orderid,sysopt,from,to,recapt/adjust,trc,stepcc'
CONTROLR is the default procedure name for the CONTROLR step. This default can be modified using the CTRPROC Control-M/Restart parameter in the CTRPARM member in the IOA PARM library. For more information, see the Control-M/Restart installation procedure in the INCONTROL for z/OS Installation Guide.
The parameters specified in the CONTROLR step PARM field are described in Table 27.
Table 27 Parameters Specified in the CONTROLR Step PARM Field
Parameter |
Description |
---|---|
type |
Mode and operation to be performed. Mandatory. This parameter consists of two single-character values: mode and operation. Mode must be one of the following:
This mode can be used by the Control-M/Restart Simulation facility and when manually creating JCL to run the CONTROLR step. Operation must be one of the following:
All combinations of mode and operation are valid. |
mem |
Control parameter member name. Optional. However, this parameter is normally inserted automatically during job submission. This parameter specifies the name of a user-defined library member that contains control parameters for a specific job. //CONTROLR EXEC CONTROLR,PARM='R2,AP04RUN,,BL,.STEP1,,ACS' This parameter must be a valid member name from 1 through 8 characters. The default value of this parameter (that is automatically inserted during job submission) is the member name that contains the job JCL, meaning, the value displayed in the MEMNAME fields in the Control-M Zoom screen, or the NAME field in the Control-M Active Environment screen. This parameter can be overridden by a member name specified in the Confirm Restart window or the Rerun Restart window. |
orderid |
Order ID. The order ID is a unique Control-M job order identifier that is used by Control-M/Restart to provide unique access to the SYSDATA of all previous runs of the job to be restarted. For more information, see ORDERID. Normally, this parameter is automatically inserted during restart job submission. Optional. If specified, orderid must be a valid 5-character Control-M order ID. If not specified, a comma must be specified instead. //CONTROLR EXEC CONTROLR,PARM='RR,,0004F,RL,.STEP1,,ACS' If this parameter is not specified, the sysopt (Read SYSDATA Indicator) parameter must be specified as BL or BN. |
sysopt |
Read SYSDATA Indicator. Specifies how the SYSDATA is to be processed by Control-M/Restart. Mandatory. This parameter consists of two 1-character values:
|
from |
Restart from procstep.pgmstep Specifies the pgmstep (or optionally the procstep.pgmstep) at which the restart of the job is to be attempted.
Copy
|
to |
Optional. Restart to procstep.pgmstep. This parameter specifies the pgmstep (or optionally the procstep.pgmstep) at which the restarted job terminates processing. If this parameter is not specified, the job is executed until the last step.
Copy
|
recapt/adjust |
Instructions for abend code recapture, condition code recapture, and step adjustment for the current restart of the job. Mandatory. This parameter consists of three 1-character values: Abend code recapture instruction. Must be one of the following
Condition code recapture instruction. Must be one of the following
Step adjustment instruction. Must be one of the following
|
trc |
Diagnostic tracing levels. Control-M passes the current diagnostic tracing levels to Control-M/Restart. The tracing levels can be set or changed using F CONTROLM, TRACE commands. For more information, see the INCONTROL for z/OS Administrator Guide. |
stepcc |
Assigns a specific condition code to a step during restart (regardless of the step’s condition code from the previous job run). Optional. This parameter consists of three values totaling 20 characters:
|
Control parameters in the Control-M/Restart PARM library
Control parameter members are defined in the Control-M/Restart PARM library. This library is referenced by the DACTRCTL DD statement of the CONTROLR step. Parameters defined in the $DEFAULT member apply to all jobs. Parameters defined in a local member apply to the specific job.
[NO]CHKSEC parameters
These parameters determine if Control-M/Restart performs preliminary security checks that can inform you of potential security problems before you run the job. In no case, is security authorization bypassed.
If the CHKSEC parameter is specified, Control-M/Restart checks if the job has security authorization to access all the data sets in the DD statements of the job. If there is a security problem, Control-M/Restart issues warnings that the job is subject to a security failure by MVS.
If the NOCHKSEC parameter is specified, Control-M/Restart does not run a preliminary security check.
These parameters override the default value set by the CHKSEC parameter in the CTRPARM member in the IOA PARM library.
Security checks must not be performed:
TRCNCT2 1,4,7
EXCLUDE DSN parameter
The EXCLUDE DSN parameter is used to exclude data sets (databases, SYS1 files, and so on) from data set cleanup processing.
The format of the EXLUDE DSN parameter is
EXCLUDE DSN dataset
where dataset is the data set name, prefix, suffix or mask
For example, assume that DSN SYS1.PROCLIB is to be excluded from processing by Control-M/Restart:
EXCLUDE DSN SYS1.PROCLIB
Mask characters are supported as follows:
? represents any one character. For example
EXCLUDE DSN SYS?.PROCLIB
* represents any number of characters (including no characters). A supplied data set name ending with * acts as a prefix. For example
EXCLUDE DSN SYS1*
Any number of EXCLUDE DSN statements can be specified.
When excluding GDG data sets, specify qualifiers in the base portion of the data set name only. Do not specify the last qualifier, that is, GnnnVmm.
For example, if you want to exclude all data sets in the Generation Data Group USER.TAPEGDG, use one of the following
EXCLUDE USER.TAPEGDG
EXCLUDE USER.TAPEGDG*
Do not use
EXCLUDE USER.TAPEGDG.G*
MSGLVL_STD/MSGLVL_FULL parameters
Message level parameters determine the level at which certain Control-M/Restart messages are logged (meaning, whether these messages are logged for each occurrence or only their first occurrence during a run of step CONTROLR). Either of two optional message parameters can be specified.
Table 28 MSGLVL_STD/MSGLVL_FULL Parameters
Parameter |
Description |
---|---|
MSGLVL_FULL |
Indicates that messages are logged for each occurrence |
MSGLVL_STD |
Indicates that messages are logged for the first occurrence only. When the same message is subsequently issued (meaning, for the same operation on the same data set in subsequent steps of the job), the message is not logged. |
If neither parameter is specified, the default value is determined by the MSGLVL parameter in the CTRPARM member in the IOA PARM library, as described in Table 29.
Table 29 Effect of the MSGLVL parameter on message level parameters
Parameter |
Description |
---|---|
MSGLVL=S |
Default value is MSGLVL_STD |
MSGLVL=F |
Default value is MSGLVL_FULL |
If the MSGLVL parameter is not defined in the CTRPARM member, the default is MSGLVL_STD.
Report each message for the first occurrence only:
MSGLVL_STD
NONRESTARTABLE_STEP parameter
This parameter indicates that restart does not begin at the specified steps. It is generally used to prevent restart from certain steps when automatic Restart Step Adjustment is performed. It applies to all occurrences of the specified step, regardless of which job is being run.
To specify this parameter, use one of the following formats:
NONRESTARTABLE_STEP [procstep_name].pgmstep_name
NONRESTART_STEP [procstep_name].pgmstep_name
If procstep_name is blank (or the step is not part of a procedure), the period preceding pgmstep_name must still be specified.
Both procstep_name and pgmstep_name support masking. For example: NONRESTARTABLE_STEP .NR*
As an alternative, the CTRNORST special DD statement can be included in the JCL for a job step in a job. This DD statement prevents restart from the specified job step only for the particular job. For more information see Indicating non-restartable steps: CTRNORST DD.
NONRESTARTABLE_STEP PROC01.STEP02
If, during automatic step adjustment, Control-M/Restart arrives at the PROC01.STEP02 step, it does not allow restart from that step, because this parameter defined that step as a non-restartable step. Instead, Control-M/Restart continues rolling back to the previous restartable step. If step adjustment continues to the first job step and no restart step is found, Control-M/Restart fails the job’s restart. This failure is accompanied by the CTR184S error message.
NONRESTARTABLE_PGM parameter
This parameter indicates that restart does not begin at certain steps, specified by program name. It is generally used to prevent restart from certain steps when automatic Restart Step Adjustment is performed. It applies to all occurrences of the specified program to be executed, regardless of which job is being run.
To specify this parameter, use one of the following formats:
NONRESTARTABLE_PGM program_name
NONRESTART_PGM program_name
The program_name supports masking. For example: NONRESTARTABLE_PGM NR*
As an alternative, the CTRNORST special DD statement can be included in the JCL for a job step in a job. This DD statement prevents restart from the specified job step only for the particular job. For more information see Indicating non-restartable steps: CTRNORST DD.
NONRESTARTABLE_PGM IEFBR14
If, during automatic step adjustment, Control-M/Restart arrives at the step that executes program IEFBR14, it does not allow restart from that step, because this parameter defined that step as a non-restartable step. Instead, Control-M/Restart continues rolling back to the previous restartable step. If step adjustment continues to the first job step and no restart step is found, Control-M/Restart fails the job’s restart. This failure is accompanied by the CTR184S error message.
[RESET/NO]RECAPTCC/[RESET/NO]RECAPTABEND Parameters
These parameters allow, prevent, or reset automatic condition and abend code recapture.
If recapture of completion codes (Cnnnn) is not desired, statement NORECAPTCC is specified.
If reset of completion codes (Cnnnn) is desired, statement RESETRECAPTCC is specified.
If recapture of abend codes (Unnnn and Snnn) is not desired, statement NORECAPTABEND is specified.
If reset of abend codes (Unnnn and Snnn) is desired, statement RESETRECAPTABEND is specified.
RECAPTCC and RECAPTABEND, which permit recapture of the respective codes, are the defaults and do not need to be explicitly specified.
Abend codes are not recaptured:
NORECAPTABEND
[NO]STEPADJUST parameters
The STEPADJUST parameter permits Automatic Step Adjustment to be performed; the NOSTEPADJUST parameter prevents Automatic Step Adjustment from being performed. As the default, STEPADJUST, which permits Automatic Step Adjustment, does not need to be explicitly specified. If Automatic Step Adjustment is not desired, NOSTEPADJUST is specified.
Step adjustment is accompanied by the CTR183I and CTR039I messages. If step adjustment continues to the first job step and no restart step is found, Control-M/Restart fails the job’s restart. This failure is accompanied by the CTR184S error message.
If step adjustment is needed, but step adjustment is disabled, job restart is terminated with a non-zero return code.
Step adjustment is not performed:
NOSTEPADJUST
TRCREST and TRCNCT2 parameters
These parameters determine the trace level with which the CONTROLR step is run during Control-M/Restart processing.
Note: Do not use this parameter unless instructed to do so by BMC Customer Support.
Table 30 TRCEST and TRCNCT Parameters
Parameter |
Description |
---|---|
TRCREST |
Determines the trace level when Control-M/Restart performs a restart |
TRCNCT2 |
Determines the trace level when Control-M/Restart performs Prevent NCT2 processing |
Up to eight 1-digit values (1 through 8), separated by commas, can be specified for each of these parameters. Each value represents a particular trace level that is to be set to on. If a parameter is omitted, no trace level is set to on for that parameter.
UNITNAME parameter
This parameter allows you to associate a site-defined esoteric unit name with the basic device type (tape or DASD). This informs Control-M/Restart of the type of processing to perform on data sets allocated to that unit.
This parameter may not be necessary. Control-M/Restart usually recognizes esoteric names defined during system I/O initialization. If, however, your site uses products that allow dynamic definition of esoteric unit names, it may be necessary to add these definitions so that Control-M/Restart can recognize the unit names.
The format of the UNITNAME parameter is
UNITNAME unit DEVICE TAPE for tape devices
UNITNAME unit DEVICE DASD for DASD devices
where unit is the site-defined esoteric unit name
Any number of UNITNAME statements can be specified.
The site has defined unit name ACL for tape devices with automatic cartridge loaders. Specify
UNITNAME ACL DEVICE TAPE
There is a group of DASD devices defined as DISK01, DISK02 and DISK03. Specify
UNITNAME DISK0* DEVICE DASD
Format of the $EXCLUDE member
The $EXLUDE member is used to identify data set names and DD statements to be excluded from Control-M/Restart processing.
The format used to specify data set name statements in this member is the same format used to specify data set name statements in the $DEFAULT member.
DD statements are specified in this member in the format shown in Table 31.
Table 31 DD Statements in $EXCLUDE Member
Column #s |
Item |
---|---|
01 through 08 |
job name |
09 through 16 |
procstep name |
17 through 24 |
pgmstep name |
25 through 32 |
DD name |
33 through 80 |
Comments (optional) |
DD statement example
Figure 6 $EXCLUDE Member DD Statement Example
JOB1 PROC1 STEP1 DD1 USED TO EXCLUDE DD1 FROM CTR
JOB2 PROC2 STEP2 DD2 USED TO EXCLUDE DD2 FROM CTR
JOB3 PROC3 STEP3 DD3 USED TO EXCLUDE DD3 FROM CTR
JOB4 PROC4 STEP4 DD4 USED TO EXCLUDE DD4 FROM CTR
JOB5 PROC5 STEP5 DD5 USED TO EXCLUDE DD5 FROM CTR
JOB6 PROC6 STEP6 DD6 USED TO EXCLUDE DD6 FROM CTR
* * * SYSABEND
In the example in Figure 6, the first-specified statement excludes the DD name DD1 from the processing of the STEP1 program step in the PROC1 procedure step for the JOB1 job.
Format of the $KEEP member
The $KEEP member is used to identify the DD statements relating to data sets that must not be scratched during Control-M/Restart processing.
If the JCL of a job contains a DD statement in which the parameter DISP is set to NEW, and the corresponding data set already exists when Control-M/Restart is invoked, Control-M/Restart automatically changes the value of the DISP parameter to OLD.
DD statements are specified in this member in the format shown in Table 32.
Table 32 DD Statements in $KEEP member
Column #s |
Item |
---|---|
01 through 08 |
job name |
09 through 16 |
procstep name |
17 through 24 |
pgmstep name |
25 through 32 |
DD name |
33 through 80 |
comments (optional) |
The $KEEP member is useful in specifying DD names of checkpoint data sets. When Control-R/RESTART recognizes an existing checkpoint data set specified with DISP=NEW, Control-R does not delete it but changes its disposition to DISP=OLD, enabling the restarted job to use the checkpoint data written by the failed job and to resume processing from the interruption point.