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

Copy 
//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

Copy 
//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:

  • R (Real)—The CONTROLR step uncatalogs data sets and performs GDG adjustment, and so on.

  • S (Simulated)—CONTROLR operates in Simulation mode. Reports are produced to show which data sets are uncataloged, how GDG adjustments are performed, from which step the job is restarted, and so on. However, no actual processing takes place and the job is terminated immediately after the CONTROLR step.

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:

  • R (Restart)—Control-M/Restart performs a restart.

  • 2 (Prevent-NCT2)—Control-M/Restart Prevent-NCT2 processing (data set cleanup prior to, and as part of, the original run).

  • C (Cleanup)—Control-M/Restart performs a data set cleanup only.

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:

  • SYSOUT option—Specifies if and when to read the SYSDATA. Valid values are:

  • — R – Read all SYSDATA of previous runs of the same job order ID. If no SYSDATA is found for the job, the CONTROLR step abends with a user abend code or a condition code depending on the value of the ABNDTYP parameter in the CTRPARM member.

  • — B – Bypass the reading of all SYSDATA of previous runs of the same job order ID. This value is used for Prevent NCT2 runs. It is not intended for job restarts. If this value is used for restart runs, functionality of the restart is severely limited: CONTROLR step does not perform condition code recapture or GDG adjustment.

  • >— C – Read all the SYSDATA of previous runs of the same job order ID if found. If no SYSDATA is found for this job, the CONTROLR step continues to execute; however, the CONTROLR step does not perform condition code recapture or GDG adjustment.

  • NJE Indicator—Indicates whether the job runs at the same NJE node as Control-M (local) or at a different NJE node than Control-M (remote). This determines the source of SYSDATA.

  • — L (Local) – Job runs at the same NJE node as Control-M (local node).

  • — N (NJE) – Job runs at a different NJE node than Control-M (remote node).

from

Restart from procstep.pgmstep

Specifies the pgmstep (or optionally the procstep.pgmstep) at which the restart of the job is to be attempted.

  • procstep—Optional. If specified, it must be from 1 through 8 characters.

  • pgmstep—Mandatory. Valid values are from 1 through 8 characters, preceded by a period (".").

Copy 
ARM='RR,GL04RUN,0004F,RL,.GLSTEP01,,ACS'

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.

  • procstep—Optional.

  • pgmstep—If specified, this value must be from 1 through 8 characters, preceded by a period (".").

Copy 
PARM='RR,GL04RUN,0004F,RL,.GLSTEP01,.GLSTEP05,ACS'

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

  • A—Perform abend code recapture.

  • N—Do not perform abend code recapture.

  • R—Reset abend steps.

  • D—Perform or do not perform abend code recapture depending on the default defined in the Control-M/Restart PARM library. When no default is defined in the Control-M/Restart PARM library, the default is A (perform the recapture).

Condition code recapture instruction. Must be one of the following

  • C—Perform condition code recapture.

  • N—Do not perform condition code recapture.

  • R—Reset condition code steps.

  • D—Perform or do not perform condition code recapture depending on the default defined in the Control-M/Restart PARM library. When no default is defined in the Control-M/Restart PARM library, the default is C (perform the recapture).

Step adjustment instruction. Must be one of the following

  • S—Perform step adjustment if necessary.

  • N—Do not perform step adjustment.

  • D—Perform or do not perform step adjustment depending on the default defined in the Control-M/Restart PARM library. When no default is defined in the Control-M/Restart PARM library, the default is S (perform the step adjustment).

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:

  • procstep—Eight-character name (trailing blanks required) of a procedure step whose condition code is overridden. Optional, but required if the step is in a procedure.

  • pgmstep—Eight-character name (trailing blanks required) of the program step whose condition code is overwritten. Mandatory.

  • code—Four-character numeric condition code used to override any condition code from the same step in the previous run.

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:

Copy 
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

Copy 
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:

Copy 
EXCLUDE DSN SYS1.PROCLIB

Mask characters are supported as follows:

? represents any one character. For example

Copy 
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

Copy 
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

Copy 
EXCLUDE USER.TAPEGDG
EXCLUDE USER.TAPEGDG*

Do not use

Copy 
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:

Copy 
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:

Copy 
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.

Copy 
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:

Copy 
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.

Copy 
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:

Copy 
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:

Copy 
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.

Example 1

Set trace levels 1,4 and 7 on when the job is restarted:

Copy 
TRCREST 1,4,7

Example 2

Set trace levels 1,4 and 7 on when running in Prevent NCT2 mode:

Copy 
TRCNCT2 1,4,7

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

Copy 
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

Copy 
UNITNAME ACL DEVICE TAPE

There is a group of DASD devices defined as DISK01, DISK02 and DISK03. Specify

Copy 
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

Copy 
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.