Control-M/Analyzer

• Overview

• Control-M/Analyzer New Day Procedure

• Invoking Control-M/Analyzer (Runtime Environment)

• Control-M/Restart Support for the Control-M/Analyzer Rollback Facility

Overview

This chapter describes the initialization and customization features that are available for Control‑M/Analyzer.

Control-M/Analyzer New Day Procedure

The Control‑M/Analyzer New Day procedure (CTBNDAY) performs certain automatic functions that start a new day under Control‑M/Analyzer. It performs daily cleanup operations on the Control‑M/Analyzer Active Balancing file and, optionally, other files. It also orders (activates) Control‑M/Analyzer missions.

The New Day procedure can be activated automatically by a scheduler (for example, Control‑M) at a predefined time each day. It can also be activated manually by submitting a job or starting a started task (STC).

The supplied New Day procedure activates program CTMILY. Program CTMILY reads the sequential dataset (or member) referenced by DD statement DAPROG. This dataset contains a list of programs to be activated.

The following table details the normal sequence of programs and utilities activated by the New Day procedure:

Table 211 New Day Procedure Programs and Utilities

The Control‑M/Analyzer New Day procedure usually runs once a day on one or more balancing mission definitions. The New Day procedure places mission entries in the Active Balancing file. Missions are selected according to the working date specified to the New Day procedure.

Reformatting the Active Balancing File – Utility CTBFRM

The New Day procedure activates the CTBFRM utility to clean up and reformat the Active Balancing file. Missions and rules that have already executed and ended OK, and missions whose MAXWAIT parameter has been exceeded, are erased from the file. Unscheduled rules are automatically assigned a MAXWAIT value of 0. After these mission entries are erased, the Active Balancing file is compressed.

Scheduling Balancing Missions

The second function performed by the New Day procedure is the determination of the missions that can potentially be activated on a specific date (that is, which missions are placed in the Active Balancing file).

The missions that are scheduled depend on the working date. For additional information, see Date Control Record.

Date Control Record

The New Day procedure is date‑dependent. The last running date of the New Day procedure is stored in a special Date Control record. The Date Control record is referenced by the DACHK DD statement in the CTBNDAY procedure.

The New Day procedure calls the CTBCHK program to check the Date Control record. The Date Control record is analyzed by the New Day procedure to determine the current running date, the last running date, and possible error situations. Special situations, such as downtime due to hardware failure, must be handled. If necessary, the Date Control record can be manually updated by using a regular editor, for example the ISPF editor.

Format of the Date Control Record

Each Date Control record has 80 characters and contains the following fields:

Table 212 Format of the Date Control Record

The format of the dates is determined by the date standard used at your site.

Use of the Date Control Record by the New Day Procedure

The Date Control record controls New Day procedure workflow. The New Day procedure, in turn, updates the Date Control record during various stages of New Day processing.

The main steps of the New Day procedure are

1. Check the last running date of the New Day procedure (using the CTBCHK internal program).

   • The first date in the Date Control record (columns 1 through 6) is compared to the current working date (at the time of the run).

   • If the current working date is the same as the first date in the Date Control record, a message indicates that the New Day procedure has already run today and the condition code is set to 0004.

   • If the current working date is earlier than the first date of the Date Control record, the New Day procedure stops executing and notifies the user that an attempt was made to run a New Day procedure before its time.

   • If the current working date is later than the first date of the Date Control record (the normal situation), the first date of the Date Control record (columns 1through 6) is updated to the current working date that is then used by all components of the New Day procedure as the current scheduling date.

   • If the New Day procedure did not run for more than one day, a warning message is issued and the New Day procedure attempts to schedule balancing missions for all of the days that have passed since the last scheduling date (according to production parameters).

   The program "asks" the operator a series of questions regarding the computer’s current date. This ensures that an incorrect date was not inadvertently entered during IPL.

2. Placing balancing missions in the Active Balancing file according to the current scheduling date and the last running date (using internal program CTBBAO).

   • Program CTBBAO acts on a userdefined balancing mission table referenced by DD statement DABAL. The program checks whether each mission in the table must be scheduled on one or all the days that have passed since the last original scheduling date (date3 or date5) until the current working date (date1). If a mission must be scheduled, it is placed in the Active Balancing file.

   • For example, if a computer did not operate from the 20th to the 23rd, a mission originally scheduled to run on the 20th did not run. Program CTBBAO determines whether the mission must be retroactively scheduled to run on the logical date of the 20th. For more information, see the RETRO parameter in the mission definition parameters chapter of the ControlM/Analyzer User Guide.

   • When the program finishes processing the mission definitions, the "finish indicator" dates (date3 and date5) are updated to the working date calculated by program CTBCHK (date1).

   • Before program CTBBAO starts operating, it compares date2 with date3 and date4 with date5. If they are not equal it probably means that a previous run of program CTBBAO has abended. The user is notified and the program terminates. To correct the error, you must edit the Date Control record to the correct date values.

     When manually modifying the Date Control record, verify that the same missions are not scheduled to run twice on the same day.

3. Recording the end of the Daily run (using program CTBPDA).

   Program CTBPDA updates the "finish indicator" date (date7) by setting it to the value of the current working date (date1). This is used to indicate that the New Day procedure finished successfully.

4. BMC recommends that the CTBJAFDL utility be run as the last step of the New Day procedure. For more information about this utility, see the INCONTROL for z/OS Utilities Guide.

Invoking Control-M/Analyzer (Runtime Environment)

Control‑M/Analyzer rules are invoked by the Control‑M/Analyzer Runtime environment. Therefore, the Runtime environment must be invoked in order to invoke a Control‑M/Analyzer rule.

The table describes the methods you can use to invoke the Control‑M/Analyzer Runtime environment.

Table 213 Invoking the Control-M/Analyzer Runtime Environment

These methods of rule activation are discussed in the coming topics.

Passing Arguments While Invoking Control-M/Analyzer

Arguments can be passed when directly invoking Control‑M/Analyzer by using procedure CONTROLB. The arguments are specified in the EXEC statement of the job step

//  EXEC CONTROLB,RULE=rule,GROUP=group,MISSION=mission,ARG=arglist

where

• rule is the name of the rule to be invoked.

• group is the group name of the rule to be invoked.

• mission is the mission name of the rule to be invoked.

• arglist contains the arguments, separated by commas, to be passed to the rule.

A maximum of 50 arguments can be parsed in the ARG specification.

The arguments specified in arglist are accessed through System variable RARGnn, where nn is a one- or two-digit number that represents the position of the argument in arglist. To access the value of the first argument in the list, specify RARG01 within a rule. For more information, see Invoking Control-M/Analyzer Using a Direct Call, and Invoking Control-M/Analyzer Using Balancing Missions.

//CHKTAPE   JOB    0,ACCT,CLASS=A,MSGCLASS=X,COND=(0,NE)
//CTB       EXEC   CONTROLB,RULE=RULDSN,ARG='PROD1.COPY.FILE1'
//COPYTAPE  EXEC   PGM=IEBCOPY
//SYSPRINT  DD     SYSOUT=*
//IN        DD     DSN=PROD.COPY.FILE1,DISP=SHR
//OUT       DD     DISP=(NEW,PASS),DSN=COPY.FILE1,
//                 VOL=SER=TAPE18,UNIT=TAPE,
//                 LABEL=(1,SL)
//SYSIN     DD     *
    C   O=OUT,I=IN
//
        LIBRARY : CTB.PROD.RULES                                RULE : RULDSN 
COMMAND ===>                                                    SCROLL===> CRSR
     +--------------------------------------------------------------------------+
       OWNER   M42A                     GROUP PROD1                                
       UPDATED 10/10/00 ‑  12:19:37    BY M42A                                   
       DESC                                                                        
       OPTIONS                                                                     
 
 
=========================================================================== 
       EXECUTE BLOCK1   UPON                                                   C   
       ON DATA                                                                     
       IF       ISDSN('%%RARG01')                                              C   
         DO TERMINAT = OK       COD 0000                                           
       ELSE                                                                        
         DO PRINT    = FILE %%RARG01 DOES NOT EXIST                        F   C   
         DO TERMINAT = NOTOK    COD 0008                                           
 
       =========================================================================== 
       EXECUTE          UPON                                                   C   
       ON                                                                          
     ======= >>>>>>>>>>>> END OF RULE DEFINITION PARAMETERS <<<<<<<<<<<<<<< =====

Invoking Control-M/Analyzer Using a Direct Call

The Control‑M/Analyzer Runtime environment can be invoked by a direct call from any of the following:

• application program

  The name of the rule to be invoked is specified by the application program’s call to ControlM/Analyzer. For additional information, see the section about calling user routines in the ControlM/Analyzer User Guide.

  The syntax is

  Copy

  CALL CONTROLB(<rule name>)

• job step

  The rule to be invoked is specified by the JCL statement of the job step (in the balancing job). This is the most frequently used method.

  The syntax is

  Copy

  // EXEC CONTROLB,RULE=rulename,GROUP=group,ARG=(arg1,...argn)

  The GROUP argument is mandatory only if the rule definition does not contain a value for parameter GROUP. If parameter GROUP is specified in the rule definition, the GROUP argument is optional.

  The ARG specification allows up to 50 arguments. For more information, see Passing Arguments While Invoking Control-M/Analyzer.

• another INCONTROL product

  The rule to be invoked is specified by parameter DO CTBRULE in a ControlM job scheduling definition or a ControlD decollating mission definition.

When Control‑M/Analyzer starts processing, it searches for the specified rule in the libraries referenced by DD statement DABRULE.

If the rule is found, it is invoked. If the rule is not found, a runtime error occurs.

This flexibility allows the Control‑M/Analyzer user to select one or more appropriate points in the life cycle of a particular data source during which balancing activities must be performed. For example:

• ControlM/Analyzer can be invoked before the creation of a report to check the validity of the report job input.

• ControlM/Analyzer can be invoked before updating a database (for example, a DB2 table) or an important file in the system. ControlM/Analyzer checks the validity of the input used for the update.

• After a report is created, it can be checked during the current job before executing other steps in the job and before the report is distributed.

• ControlD can invoke a ControlM/Analyzer rule to validate a decollation process.

• Control-M can invoke Control-M/Analyzer to perform balancing actions that verify the input and/or output of a job run. Job flow can be controlled by Control-M based on the results of these balancing actions.

Invoking Control-M/Analyzer from a Job Step or Application Program

The following parameters can be used to invoke Control‑M/Analyzer from a job step or from an application program:

• RULE

• MISSION

• GROUP

• ARG

Parameters RULE and MISSION cannot be specified together to invoke balancing operations (that is, the user must decide whether Control‑M/Analyzer must be invoked directly or indirectly). Either the mission name or rule name must be specified, but not both.

The group name is determined as follows:

1. If GROUP is specified in the invocation, that group name overrides any other group specification.

2. If GROUP is not specified in the invocation and balancing operations are invoked by a mission, the group name of the mission is used.

3. Otherwise, the group name specified in the rule definition is used as the current group.

Parameters can be passed to a Control‑M/Analyzer rule and accessed by the rule through system variable RARGnn, where nn is a one- or two-digit number that represents the position of the argument in the argument list. To access the value of the first argument in the list, specify RARG01 within a rule.

Invoking Control-M/Analyzer from Control-M

When Control‑M/Analyzer is invoked by Control‑M, it is not necessary to specify scheduling criteria for the rule (that is, there is no need to define a balancing mission). The Control‑M/Analyzer rule is scheduled in accordance with the scheduling criteria specified in the Control‑M job scheduling definition.

However, when invoked by Control‑M, Control‑M/Analyzer must execute each rule for a specific group. The name of the group can be specified by any of the following methods, which are listed in order of decreasing priority. The group name can be specified in

• the GROUP parameter in the ControlM/Analyzer rule

• the GROUP parameter in the ControlM job scheduling mission

• the GROUP=group_name argument in the procedure that invokes ControlM/Analyzer

If a group name is specified by more than one of these methods, the rule is implemented with the group name specified by the method with the highest priority.

Invoking Control-M/Analyzer from Control-D

When Control‑M/Analyzer is invoked by Control‑D, it is not necessary to specify scheduling criteria for the rule (that is, there is no need to define a balancing mission). The Control‑M/Analyzer rule is scheduled in accordance with the scheduling criteria specified in the Control‑D decollating mission definition.

BMC recommends that a group be specified in the Control‑M/Analyzer rule or in the Control‑D decollating mission. When Control‑M/Analyzer is invoked, the name of the group is obtained from one of the following sources, which are listed in order of decreasing priority. The group name can be specified in the GROUP parameter of the

• ControlM/Analyzer rule.

• ControlD decollating mission.

If a group name is specified in both of these parameters, the rule is implemented with the group name specified in Control‑D.

Invoking Control-M/Analyzer Using Balancing Missions

Balancing missions can be used to invoke Control‑M/Analyzer from one of the following:

• application program

• Name of the mission to invoke is specified by a program call to ControlM/Analyzer in the application program. For additional information, see the section about calling user routines in the ControlM/AnalyzerUser Guide.

  Copy

  CALL CONTROLB(<mission>, ...);

• job step

  Name of the mission to be invoked is specified in the JCL statements of the job step that invokes the ControlM/Analyzer Runtime environment.

  Copy

  // EXEC   CONTROLB,
  //    MISSION=DAILYBAL,GROUP=group,ARG=(arg1,...,argn)

The ARG specification allows up to 50 arguments. For more information see Passing Arguments While Invoking Control-M/Analyzer.

When the call or step that invokes Control‑M/Analyzer is invoked, Control‑M/Analyzer first checks each entry in the Active Balancing file to locate the appropriate balancing mission. the following table describes the phases of the Active Balancing file search method.

Table 214 Active Balancing File Search Method Phases

The SCOPE parameter of each eligible mission entry in the Active Balancing file is checked to determine a JOB-STEP match. The SCOPE parameter specifies one of the following options:

Table 215 Values for Parameter SCOPE

The first mission that matches the above criteria is selected for execution. If no matching mission is found, a runtime error occurs.

Control-M/Restart Support for the Control-M/Analyzer Rollback Facility

Rollback Activation using Control-M/Restart

The Control‑M/Analyzer Rollback feature can be activated by Control‑M/Restart. When Control‑M/Restart restarts a job run by Control‑M, the Rollback feature is automatically invoked if Control‑M/Restart User Exit CTRX001Q is installed.

Control-M/Restart Implementation

Perform the following steps to use the Control‑M/Restart to Control‑M/Analyzer Interface:

1. Instal ControlM/Restart Exit CTRX001Q. For more information, see Exits.

2. Follow the instructions in the following section.

Triggering Rollback using Procedure CONTROLR

Each job run by Control‑M has a unique five-character alphanumeric order ID. This order ID is displayed (as OrderID=xxxxx) in the Control‑M Active Environment screen (Screen 3) when command ORDERID is entered on the command line.

Perform the following steps to implement the automatic Rollback facility for jobs restarted by Control‑M/Restart:

1. Pass the ControlM order ID to the ControlM/Analyzer rule that generates the variables that are stored in the ControlM/Analyzer database.

   • You can do this by passing AutoEdit variable %%ORDERID as an argument in the EXEC statement that invokes ControlM/Analyzer. The EXEC statement syntax is

     Copy

     //   EXEC  CONTROLB,RULE=MYRULE,ARG=%%ORDERID

   • For example, if 014OX is the order ID of the ControlM job that invokes ControlM/Analyzer, the EXEC statement that invokes ControlM/Analyzer resolves to

     Copy

     //   EXEC  CONTROLB,RULE=MYRULE,ARG=014OX

2. In the ControlM/Analyzer rule, define a DO REMARK statement that inserts the order ID value in the ControlM/Analyzer activity record.

   • When the order ID value is passed to ControlM/Analyzer, the rule must execute the following statement:

     where %%RARGnn refers to the nth argument passed to the rule.

     For example, use %%RARG01 if %%ORDERID is the first argument. After statement DO REMARK is executed, the activity record for this ControlM/Analyzer execution contains the value: OID=014OX. This value can be displayed in the REMARK field of the ControlM/Analyzer Rule Activity screen (Screen BA).

     Copy

     DO REMARK DATA 'OID=%%RARGnn'

3. The ControlM/Analyzer activity record automatically identifies the generation of database variables that was created by the job that is being restarted by ControlM/Restart.

4. Call User Exit CTRX001Q with the order ID of the job that created the variables that must be rolled back.

   This requirement is automatically satisfied when ControlM/Restart calls User Exit CTRX001Q with the current order ID. This user exit passes the order ID to the Rollback facility. The Rollback facility rolls back database records created during execution of the job whose activity record contains this order ID.

Sample Control-M/Analyzer Rule

The following sample rule illustrates how to use the DO REMARK statement to insert the order ID in the REMARK field of the Control‑M/Analyzer activity record:

Figure 73 Sample Control-M/Analyzer Rule

 OWNER   N52                      GROUP TEST                             
 UPDATED 10/10/00 -  17:29:17    BY N52B                                  
 DESC                                                                      
 OPTIONS                                                                   
 ===========================================================================
 EXECUTE INIT     UPON                                                   C 
 ON DATA                                                                   
 ALWAYS                                                                    
   DO REMARK   = OID=%%RARG01                                              
 ===========================================================================