Control-M Utilities

Some utilities prefixed by IOA replace corresponding utilities prefixed by CTM in previous versions. In such cases, the old utilities are supported for your convenience; however, you should use the IOA utilities.

CTMAESIM – Test AutoEdit Syntax

The CTMAESIM utility simulates the actions of the Control-M submission mechanism. It checks AutoEdit syntax and JCL setup. A command specified in an input statement determines how the simulation works. The utility scans an entire JCL member to find all the AutoEdit errors in the member. For more information, see the JCL and AutoEdit facility chapter in the Control-M for z/OS User Guide.

CTMAESIM Parameters

The utility receives the following parameters using DD statement DASIM.

Either JCL Library Mode parameters or Scheduling Mode parameters (but not both) must be specified to run the utility. These parameters determine the mode in which the utility operates. In addition, other general simulation parameters are specified.

Table 85 CTMAESIM JCL Library Mode Parameters

Table 86 CTMAESIM Scheduling Mode Parameters

Table 87 CTMAESIM Parameters

Any number of members can be submitted for testing in one simulation run.

If multiple members are specified, not all parameters need to be specified for each member. The first member always requires a complete set of parameters. Subsequent members require specification of the member name, command, and any parameter statements whose values differ from the values of the preceding member. For all unspecified parameters, the simulation uses the corresponding value provided for the preceding member as the default.

Activating the CTMAESIM Utility

You can activate the utility either through a batch JCL or invoking it from another program.

CTMAESIM from Batch JCL

The following is a sample batch JCL used to invoke CTMAESIM:

// .... JOB ....
// EXEC CTMAESIM
//DASIM DD *

Invocation of CTMAESIM from another program

The following is sample code used to invoke CTMAESIM from another program:

    CALL  CTMAES,(DUMMY)
...
DUMMY    DC    F'0'

When you invoke CTMAESIM from another program, observe the following conventions:

• The procedure that executes the invoking program must allocate all the files that are necessary to execute AutoEdit simulation.

• There must be no conflict between the DDnames required by the program and by AutoEdit simulation (for example, the DDname SYSPRINT).

• Because CTMAES is an authorized module, you must ensure that any program that calls it must also be authorized and resides in an authorized library.

• All the loadlibs in the STEPLIB concatenation must be authorized.

• INCLUDE the CTMAES module from the IOA loadlib in the link-edit step.

• Prior to calling CTMAES, the invoking program must be placed into AMODE 31.

• The calling program must be in RMODE 24.

• The module must not be linked as RENT (re–enterable) or REUS (reusable).

• Even though CTMAES does not require any parameters, when invoked from a high-level language such as COBOL or PL/1, it must be called with a dummy parameter containing zeros (0).

CTMAESIM Return Codes

Table 88 CTMAESIM Return Codes

Examples for CTMAESIM

// . . . JOB . . .
//    EXEC CTMAESIM,RDR=INTRDR
//DASIM DD *
USERID   SY01
WDATE    060600
ODATE    060600
$SIGN    2
MEMBER    JOBDAY01
LIBRARY    SYS3.CTM.JOBS
SUBMIT
OWNER    SY01
WDATE    060600
ODATE    060600
MEMBER    JOBWEKLY
LIBRARY    SYS3.CTM.JOBS
SUBMIT

// . . . JOB . . .
// . . . EXEC CTMAESIM,RDR=INTRDR
//DASIM DD *
ODATE    060600
SCHEDLIB    SYS3.CTM.JOBS
TABLE    DEFSCHED3
JOB    TAPE01
LIST
JOB    TAPE02
LIST
TABLE    DEFSCHD4
JOB    JOB1
LIST

CTMAPI - Control-M Application Program Interface

The Control-M Application Program Interface (CTMAPI) is an open interface between the application environment and Control-M. CTMAPI enables application programs to interface with Control-M, allowing access to IOA and Control-M services and enabling you to extract data from Control-M into your own programs.

CTMAPI is accessible from all application environments. It can be called from the following programs or environments:

• High Level Language or Assembler programs, running under various environments, such as CICS, IMS, or the like

• a batch job or step

• REXX or CLIST

CTMAPI supports various types of services, but not all of them are supported under all environments. Some of the functions can be executed using existing IOA or Control-M utilities. For example, CTMJOB can be used to order jobs. Other functions, such as the Status request or AJF Action requests, cannot be processed by means of any other existing program or utility.

Future enhancements will be provided first to the API, rather than to the appropriate utility. Therefore, BMC recommends that you use CTMAPI for all requests, even functions that are supported using other utilities.

For a detailed description of CTMAPI see , The Control-M Application Program Interface (CTMAPI) in the Control-M for z/OS User Guide.

CTMBGRP – Convert Regular Scheduling Tables to Group Scheduling Tables — Replaced

This utility has been replaced by the CTMBTBL utility, described in CTMBTBL – Convert Tables to SMART Tables. BMC recommends that you no longer use the CTMBGRP utility.

CTMBTBL – Convert Tables to SMART Tables

The CTMBTBL utility automatically converts tables to SMART Tables.

During conversion to a SMART table, the following actions are automatically performed by the utility:

• A SMART Table Entity is created for the table.

• A table name is defined and added (in protected mode) to the TABLE field in each job scheduling definition.

• The format of the regular job scheduling definitions is modified to match the format of job scheduling definitions in SMART Tables (meaning, the SCHEDULE RBC field is added to, and supported in, the job scheduling definitions).

• By default, the value of parameter MAXWAIT is obtained from the SMART Table definition. However, if parameter RBCMAXWT in member CTMPARM of the IOA PARM library is set to N (No), the value of this parameter is obtained from the job definition.

• Basic scheduling criteria specified in a job definition are converted to a TBL Level RBC in the SMART table.

• If a job in a regular table is using a CTM Level RBC, the regular table is not converted to a SMART table and an appropriate message is issued.

CTMBTBL Statements and Parameters

The utility receives parameters using DD statement SYSIN. All utility messages are written to the SYSPRINT file.

CTMBTBL Statements

The required data sets are referenced by the following DD statements:

Table 89 CTMBTBL Required Data Sets

Keywords in the SYSIN statements must be specified beginning in column 1 and the keywords must appear in the exact sequence indicated.

CTMBTBL Parameters

Table 90 CTMBTBL Required Keywords

Multiple tables can be converted in a single run of the utility by passing multiple sets of IN or OUT lines. These sets can be separated by one or more comment lines.

WARNING!: If the output table (OUT-TABLE) already exists, it will be overwritten when the CTMBTBL utility creates a new output table.

Activating the CTMBTBL Utility (and Example)

A job to activate the utility can be found in member CTMBTBL in the Control-M JCL library.

CTMBTBL Return Codes

Table 91 CTMBTBL Return Codes

CTMBLDAE – Build AutoEdit Symbols Member

The CTMBLDAE utility automatically builds AutoEdit symbol members using regular and periodic IOA calendars as input. For more information about types of AutoEdit symbols and instructions, see the JCL and AutoEdit facility chapter in the Control-M for z/OS User Guide.

For every scheduled date in the specified calendar, the CTMBLDAE utility creates one line in an AutoEdit member. The content of this line is determined according to a user-defined "generation (GEN) card." The GEN card is a string used to create records in the output member (one record for each scheduled date in the calendar).

CTMBLDAE Parameters

The parameters for the CTMBLDAE utility are specified in blocks in the SYSIN file. Blocks consist of the following mandatory parameters (described below):

CALLIB=input-calendar-librar

ALMEM=input-calendar-member

OUTLIB=output-library

OUTMEM=[/]output-member

GEN=string

ENDCAL

• More than one block of parameters can be specified.

• Each parameter must be specified in each block. However, the parameters in each block can be specified in any order.

  In a parameter block, each parameter is specified only once. However, if a parameter is specified more than once in a block, only the last occurrence of the parameter in the block is accepted.

• If more than one parameter block is specified, each parameter block must be delimited by parameter ENDCAL.

• Comment lines can be specified by coding * in column 1.

• Parameter lines must not contain any TSO line numbers (in column 73 - 80).

Blocks of parameters are specified in the following format:

Table 92 CTMBLDAE Parameters

If the user specifies the same output member (meaning, the same OUTLIB or OUTMEM combination) in more than one block, normally only the results of the last occurrence of that member are saved.

To retain the results of all occurrences of that output member, use the expression PARM=MERGE in the JCL EXEC statement. If you use this statement, the results of each occurrence of the output member are concatenated in the member.

If the OUTMEM parameter is specified using the format OUTMEM=/member-name, the expression PARM=MERGE is ignored for the block.

Activating the CTMBLDAE Utility

Activate the utility using the CTMBLDAE member in the Control-M JCL library.

CTMBLDAE Return Codes

Table 93 CTMBLDAE Return Codes

Examples for CTMBLDAE

//SYSIN    DD    *
CALLIB=CTM.PROD.CAL
CALMEM=PAYROLL
OUTLIB=CTM.PROD.SYMBOLS
OUTMEM=PAYCHECK
GEN=%%DATE_TYPE_OF_ODAT=REGULAR
//

-----S-------------S-------------S-------------S-------------S-------------S    
    1 2 3 4 5 6 7 8 9 + 1 2 3 4 5 6 7 8 9 + 1 2 3 4 5 6 7 8 9 +
09    Y    Y    Y    Y
-----S-------------S-------------S-------------S-------------S-------------S    

%%DATE_TYPE_OF_000908=REGULAR
%%DATE_TYPE_OF_000915=REGULAR
%%DATE_TYPE_OF_000922=REGULAR
%%DATE_TYPE_OF_000929=REGULAR

//JCL JOB
//* %%LIBSYM CTM.PROD.SYMBOLS %%MEMSYM RLPREVD
//    EXEC PGM=RLPGM
//SYSUT1  DD  DSN=PREFIX.%%RL%%ODATE,DISP=SHR
//SYSUT2  DD  DSN=PREFIX.RL%%ODATE,DISP=(NEW,CATLG)

%%RESOLVE OFFCALLIB=CTM.PROD.CAL
CALMEM=RLRUN
OUTLIB=CTM.PROD.SYMBOLS
OUTMEM=RLPREVD
GEN=%%RLODAT=RLPREV

 -----S-------------S-------------S-------------S-------------S-------------S
    1 2 3 4 5 6 7 8 9 + 1 2 3 4 5 6 7 8 9 + 1 2 3 4 5 6 7 8 9 +
09    Y    Y    Y    Y
-----S-------------S-------------S-------------S-------------S-------------S

%%RL990907=RL000831
%%RL990914=RL000907
%%RL990921=RL000914
%%RL990928=RL000921
%%RL991005=RL000928

//SYSUT1    DD  DSN=PREFIX.RL000907,DISP=SHR
//SYSUT2    DD  DSN=PREFIX.RL000914,DISP=(NEW,CATLG)

//SYSIN    DD    *
CALLIB=CTM.PROD.CAL
CALMEM=PAYROLL
OUTLIB=CTM.PROD.SYMBOLS
OUTMEM=PAYCHECK
GEN=%%DATE_TYPE_OF_ODAT=REGULAR
ENDCAL
CALLIB=CTM.PROD.CAL
CALMEM=PAYROLL
OUTLIB=CTM.PROD.SYMBOLS
OUTMEM=PAYCHECK
GEN=%%DATE_TYPE_OF_$ODAT=REGULAR
ENDCAL
CALLIB=CTM.PROD.CAL
CALMEM=PAYROLL
OUTLIB=CTM.PROD.SYMBOLS
OUTMEM=PAYCHECK
GEN=%%DATE_TYPE_OF_ODAT_NEXT=REGULAR
ENDCAL
//

-----S-------------S-------------S-------------S-------------S-------------S
    1 2 3 4 5 6 7 8 9 + 1 2 3 4 5 6 7 8 9 + 1 2 3 4 5 6 7 8 9 +
09    Y    Y    Y    Y
-----S-------------S-------------S-------------S-------------S-------------S    

%%DATE_TYPE_OF_000908=REGULAR
%%DATE_TYPE_OF_000915=REGULAR
%%DATE_TYPE_OF_000922=REGULAR
%%DATE_TYPE_OF_000929=REGULAR
%%DATE_TYPE_OF_20000908=REGULAR
%%DATE_TYPE_OF_20000915=REGULAR
%%DATE_TYPE_OF_20000922=REGULAR
%%DATE_TYPE_OF_20000929=REGULAR
%%DATE_TYPE_OF_000908_000915=REGULAR
%%DATE_TYPE_OF_000915_000922=REGULAR
%%DATE_TYPE_OF_000922_000929=REGULAR

CTMBLT – Create Tables

The CTMBLT utility automatically builds Control-M tables containing job scheduling definitions according to a set of specified input statements, and optionally orders or forces them.

The utility builds tables that can contain multiple job scheduling definitions. At least one table must be defined in each library specified. At least one job scheduling definition must be defined in each table. For SMART Tables, the scheduling definition for the table must be defined for the jobs in the table as a whole.

For a description of other output files created by the utility see Activating the CTMBLT Utility.

CTMBLT Parameters

The CTMBLT utility receives parameters from an input file referenced by the DAINPRM DD statement. The syntax of the input statements is:

Figure 21 CTMBLT Input Syntax

[{LIBRARY=libraryname}
{MEM-OVERWRITE=Y|N|ADD|ADDG|ORDER|FORCE}
{RECOVER_AFTER_ABEND=Y|N}
{ADD-GLOBAL=Y|N|G|J}
{OPTION=opt}
[
{Super Global Parameter Statements}
TABLE=tablename
{Global Parameter Statements}
[
     {TABLE-ENTITY=table-entity-name| GROUP-ENTITY=group-entity-name}
     MEMNAME=jobname
     {Optional Local Parameter Statements}
     {SCHEDULE-RBC=rbcname}
]
]
]

The parameters specified in the input file are divided into the following groups:

• General Parameters

  • These parameters specify scheduling library names (LIBRARY), table names (TABLE), job or SMART Table Entity scheduling definition names, (MEMNAME and TABLE-ENTITY) and rule-based calendars (SCHEDULE-RBC).

  • This set of parameters also contains the following control parameters: MEM-OVERWRITE, ADD-GLOBAL, and OPTION. These control parameters can be specified any number of times, in any order, anywhere in the input stream. Each control parameter applies to the table definition in which it is embedded, taking effect from the point where it is encountered, and all subsequent table definitions, until a new value for the parameter is specified.

• Job Scheduling Definition Parameters

  • These parameters correspond to the parameters of the job scheduling definition screen. They can be defined in the ways shown in the following table:

Table 94 CTMBLT Job Scheduling Definition Parameters

The sequence in which the parameters appear in the input file is important as it determines

• which job and SMART Table Entity scheduling definitions belong in which table, and which tables belong in which library

• whether job scheduling definition parameters are interpreted as Super Global, Global or Local

  When duplicate parameters are specified as Global or Super Global parameters, only the last takes effect.

• Special Parameters

  • MODEL – By using this parameter when creating a new job scheduling definition, you can significantly reduce the number of job scheduling parameters you need to code. You achieve this by specifying an existing job scheduling definition to serve as a model or skeleton. When you do, the effect is as if you had effectively specified every possible CTMBLT job scheduling parameter, with values corresponding to those contained in the job scheduling definition of the model.

    MODEL must be the first parameter specified in the job scheduling definition; it must be specified immediately after the MEMNAME or TABLE-ENTITY (SMART Table Entity) parameters.

    You cannot specify MODEL as a global or super-global parameter.

    MODEL fields supplied for multiple value fields (for example, IN and OUT) are always retained in the output job definition – the values provided by input parameters (LOCALs, and GLOBALs/SUPER GLOBALs if ADD-GLOBAL=Y) are added to the output job definition.

    After specifying MODEL, you can specify any number of job scheduling parameters to modify or add to the model definition, subject to the following restrictions:

    • Job scheduling parameters specified after MODEL must be consistent with the model. If, for example, the model definition contains DAYS values and you wish to specify DATES parameters, then precede the DATES parameters with the OPTION=/DATES statement. For more information, see "OPTION" in CTMBLT General Parameters.

    • If the model you specify contains an RBC which is not defined in the SMART Table Entity to which the current job belongs, CTMBLT will accept the model, but will produce an error message after displaying the job scheduling definition.

    • If the model you specify contains an RBC, but the current job does not belong to a SMART Table, the RBC is ignored.

    • You can only specify a model SMART Table Entity following a TABLE-ENTITY (SMART Table Entity) general parameter.

  • JCL – This parameter is used to build in-line JCL statements to replace the JCL member specified in the MEMLIB parameter.

  • APPL-FORM, APPL-TYPE, APPL-VER, CM-VER – These parameters are used when defining jobs as distributed (non-mainframe) job definitions. For information about the proper usage of these parameters, consult the relevant Control-M User Guide.

  • DEFTYPE – This parameter is used to specify that a job definition is to be built for use on a distributed platform only.

The parameters of the input file are described below, according to SMART Table.

CTMBLT General Parameters

Table 95 CTMBLT Parameters

CTMBLT Job Scheduling Definition Parameters

These parameters correspond to the parameters of the Control-M job scheduling definition screen. For a detailed description of what each parameter does, refer to the job production parameters chapter in the Control-M for z/OS User Guide. For a brief description of each parameter, see Job Scheduling Definition Parameter Tables.

Some parameters, including DATES, IN, CONTROL, RESOURCE, OUT, CODES, MAIL-TO, and MAIL-CC, can be repeated by specifying more than one value for the parameter.

Calling the CTMBLT Utility from another program

The CTMBLT utility can be called from another program. The calling program passes required control statements to the CTMBLT utility using a table residing in memory (rather than from a data set referenced by the DAINPRM DD statement). The CTMBLT utility can also pass back to the calling program replies on the activities it performed.

To call CTMBLT from another program and pass a table of control statements residing in memory to the CTMBLT utility, specify the following parameters in the calling statement:

Table 96 CTMBLT Calling Parameters

Table 97 shows the CTMBAPI parameters used when requesting replies from CTMBLT and programs that it calls.

Table 97 CTMBAPI Parameters Used by CTMBLT

For example, in Assembler the following statement format is used:

CALL    CTMBLT,(cnt,line#,taddress,altaddr,replyaddr)

If the CTMBLT utility cannot build a table, a non-zero return code is placed in register 15 (R15) and an error message is written to the file referenced by DD statement DAPRINT.

Building Tables in Memory Followed by Immediate Ordering

The CTMBLT utility can create tables in memory (instead of in a scheduling library) and order or force them.

This functionality enables users to order or force jobs to the Active Jobs file without saving Control-M job scheduling definitions in a scheduling library.

To create tables in memory and then order or force them, specify the same parameters as when creating tables in a library.

However, note the following point about the syntax:

MEM-OVERWRITE={ORDER|FORCE}[({SDATE|WDATE|yymmdd[/WAIT]})]

The MEM-OVERWRITE statement must be specified in this syntax. An order or force action must be specified, followed, optionally, by one of the following date references (in parentheses):

• SDATE – Current system date

• WDATE – Current Control-M working date (default)

• yymmdd – Any valid 6-character date

• You can also specify a future date. The date may be optionally followed by the /WAIT option, for example, MEM-OVERWRITE=ORDER(yymmdd/WAIT). This causes the job execution to be delayed until the date yymmdd specified, even if all other required run-time criteria (conditions, resources, and so on) are available.

• Users who want to save the resultant Control-M job scheduling definitions in a scheduling library can do so by coding OPTION=S. For detail, see Table 95 in CTMBLT General Parameters.

This capability is provided only when invoking CTMBLT services in conversational (BAPI) mode, either

• through the CTMAPI application program interface (for details, see Appendix A in the Control-M for z/OS User Guide) or

• by providing a reply area (for details, see Calling the CTMBLT Utility from another program)

Activating the CTMBLT Utility

A sample job to activate the utility can be found in the CTMBLT member CTMBLT in the Control-M JCL library.

Considerations (CTMBLT)

The file referenced by DD statement DAPRINT holds all messages produced by the utility. This file can alternatively be specified as a data set instead of a sysout print file.

The file referenced by DD statement DATABERR holds parameters from the file referenced by DD statement DAINPRM that could not be processed due to syntax errors or other errors. Statement DATABERR is optional. Omitting this DD statement improves the performance (meaning, reduces the elapse time) of the utility; therefore, for very large runs of the CTMBLT utility, consider removing this statement from the JCL.

Parameters in the file referenced by DD statement DAINPRM can be specified either as in-stream data or as 80-byte card image data.

It is unnecessary to specify DD statements for scheduling libraries because the utility dynamically allocates job-scheduling libraries according to the LIBRARY parameter. A DASCHD DD statement is required when the LIBRARY parameter is not specified as the first input parameter of the utility. For example

CALL    CTMBLT,(cnt,line#,taddress,altaddr,replyaddr)

Use of this DD statement is also recommended in any of the following situations:

• The CTMBLT utility creates a single job-scheduling library.

• Many members are created within the library.

CTMBLT Return Codes

Table 98 CTMBLT Return Codes

Examples for CTMBLT

IN=(condname,date,condname,date...)
MAIL-TO=(email-address1,email-address2,...)

SETVAR=%%A=%%ODAT
SETVAR=%%B=53

//DAINPRM    DD *
    LIBRARY=CTM.PROD.SCHEDULE
    MEM-OVERWRITE=N
    ADD-GLOBAL=Y
    TABLE=INITJOBS
          TABLE=INIT-JOBS-1
          MEMLIB=GENERAL
          MEMNAME=PNADCICW
                OWNER=OPSUSER
          DESC='CO - POST ONLINE COPY IMAGE FOR PHASE3'
                IN=(PNADCICW-OK,PREV)
                OUT=(PNADCICW-OK,ODAT,+)
          MEMNAME=PNADCIC1
                OWNER=OPSUSER
                OUT=(PNADCIC1-OK,ODAT,+)
    TABLE=PRDDAILY
          MEMNAME=CHKACC
                MEMLIB=GENERAL
                OWNER=OPSUSER
                TASKTYP=JOB
                TABLE=CHECK-ACCOUNTS
                WDAYS=(2,3,4,5)
                IN=(PNADCICW-OK,ODAT)
                ONPGM
                    STEP=ANYSTEP
                    CODES=NOTOK
                    DO=SYSOUT
                       SYSOUT-OP=C
                       SYSOUT-FRM=R
                       SYSOUT-PRM=M
                SHOUT-WHEN=NOTOK
                    DEST=OPER-12
                    MSG='JOB CHKACC HAS AN ERROR CHECK IT'
                    URG=U
                CTBSTART
                    CTBS-TYPE=RULE
                    CTBS-NAME=CHKBRL
                    CTBS-ARGS='1 TO 45 CHARS'
                CTBEND
                    CTBE-TYPE=MISSION
                    CTBE-NAME=ENDMI1
                    CTBE-ARGS='1 TO 45 CHARS'

//DAINPRM    DD  *
LIBRARY=name1
MEM-OVERWRITE=ORDER(WDATE)
ADD-GLOBAL=Y
TABLE=TABLE1
      TABLE=TABLE1
      MEMLIB=GENERAL
      MEMNAME=MYMEM1
      OWNER=CTMBLT
      DESC='ORDER JOB MYMEM1’
      DAYS=ALL
      OUT=(MYMEM1-OK,ODAT,+)
LIBRARY=name2
MEM-OVERWRITE=FORCE
TABLE=TABLE2
      TABLE=TABLE2
      MEMLIB=GENERAL
      MEMNAME=MYMEM2
      OWNER=CTMBLT
      DESC='FORCE JOB MYMEM2'
      IN=(MYMEM1-OK,ODAT)
//

           CALL    CTMBLT,(FOUR,0,TBLADDR,ALTDDP,RPLYP)
           LTR     R15,R15    
           BNZ     error-routine
           ...
FOUR DC    H'4'                           4 PARAMETERS
TBLADDR    DC    A(INCORETB)
ALTDDP     DC    A(ALTDDL)
ALTDDL     DC    CL8' '
           DC    CL8' '
           DC    CL8' '
           DC    CL8'ERROR'
*
RPLYP      DS    6A                       (see CTMBAPI details)
           DC    A(RPLYAREA)              BAPIRPLS
           DC    A(RPLYAREA+(10*64)-1)    BAPIRPLE
           DS    F                        BAPIRPL#
           DS    A
           DS    26C
           DS    H                        BAPIRSN
           DS    H                        BAPIURC
           DS    XLn                      (n=remaining length)
RPLYAREA   DS    10CL64              (see CTMBAPO for details) Room for 10 replies
*
INCORETB   DS    0CL80  TABLE OF CTMBLT CARD-IMAGE CONTROL STMTS
           DC    CL80’LIBRARY=*INCORE* `
           DC    CL80’MEM-OVERWRITE=FORCE `
           DC    CL80’TABLE=MYTABLE `
           DC    CL80’MEMLIB=GENERAL
           DC    CL80’MEMNAME=MYJOB `
           DC    CL80’END `    (a linecount parameter is not necessary)

MEM-OVERWRITE=Y
ADD-GLOBAL=Y
      DOCLIB=SUPER.GLOBAL.DOCLIB              SUPER GLOBAL
      APPL=SUPER-GLOBAL-APPL                  SUPER GLOBAL
      ONPGM    SUPER GLOBAL    
        STEP=ANYSTEP                          SUPER GLOBAL
        CODES=C0008                           SUPER GLOBAL    
        DO=COND                               SUPER GLOBAL    
        CONDS=(SUPER-GLOBAL-COND,ODAT,+)      SUPER GLOBAL
TABLE=@INITJOB
      OWNER=GLBLOWN
      SCHEDULE-RBC=X
      ADJUST-CONDS=Y
      PRIORITY=GL
      MEMLIB=GLBL-MEMLIB
      APPL=GLOBAL-APPL
      OVERLIB=OVER.LIB.GLOBAL
      ONPGM
        STEP=ANYSTEP
        CODES=C0000
        DO=COND
        CONDS=(GLOBAL-COND,ODAT,+)
      CONTROL=(CONTROL-RESOURCE,E)
      RESOURCE=(QUANTIT-RESGLOBL,0009)
TABLE-ENTITY=TABLE-ENTITY1
   TASKTYP=TBC             cyclic smart table
   ONPGM
   STEP=GROUPEND                    ON TABLE-END
   CODES=NOTOK
   DO=SHOUT
   MSG='TABLE-ENT SHOUT'
   DEST=OPER-2,URG=U
SCHEDULE-RBC=RBC1
WDAYS=6
 EXT-SHIFT=+7
 CONFCAL=GRPDCAL
SCHEDULE-RBC=RBC3
 DATES=(1010,0202,0909)
 MAXWAIT=03
SCHEDULE-RBC=RBC4
 DAYS=10
 WDAYS=0
SCHEDULE-RBC=X
SCHEDULE-RBC=*END
***=== SMART Table ENTITY (NON-RBC) DEFINITIONS ==
  ADJUST-CONDS=Y
  IN=(TABLE-IN-COND,ODAT)
  OUT=(TABLE-OUT-COND,ODAT,+)
  MAXRERUN-CYC=9999
  CYCLIC-TYPE=S
  TOLERANCE=0999
  CYC-RUNTIME=1030,000
  CYC-RUNTIME=1520,000
  CYC-RUNTIME=1310,000
  CYC-RUNTIME=2015,000
  CYC-RUNTIME=1155,000
  ONPGM
   STEP=GROUPEND                    ON TABLE-END
   CODES=OK
   DO=SHOUT
   MSG='FIRST MSG'
   DEST=OPER-1,URG=V
 SHOUT-WHEN=OK
   MSG=SHOUT-WHEN
   DEST=OPER-3
*
   MEMNAME=PNADCICW
      DAYS=+15
      DCAL=CALENDR
      OWNER=MKGRP
      MEMLIB=GENERAL-LIB
      MAXRERUN=233
      INTERVAL=1440
      IN=(PNADCICW,PREV)
      OUT=(PNADCICW-OK,ODAT,+)
      RBC-RELATION=A
      SCHEDULE-RBC=RBC1
      RESOURCE=(JOB-RESOURCE,0099)
      SCHEDULE-RBC=RBC3
      SCHEDULE-RBC=*
   MEMNAME=PNADCICX
      APPL=LOCAL-APPL
      IN=(PNADCICX,PREV)
      OUT=(PNADCICX-OK,ODAT,+)
      SCHEDULE-RBC=RBC1
   MEMNAME=ANOTHER
      MEMLIB=GENERAL
      IN=(ANOTHER,ODAT)
TABLE=@INITJO2
      MEMLIB=GLBL-MEMLIB2    GLOBAL
TABLE-ENTITY=TABLE-ENTITY2
SCHEDULE-RBC=RBC8
  DAYS=5
  DCAL=GRPDCAL
SCHEDULE-RBC=RBC9
    PERIOD=L2P3
    DCAL=PERCAL2
 SCHEDULE-RBC=RBC10
    DATES=(1111,1212,0808)
SCHEDULE-RBC=*END
    DOCMEM=TABLE2
MEMNAME=PNADCCW2
SCHEDULE-RBC=RBC8
    SCHEDULE-RBC=RBC9
MEMNAME=PNADCCX2
    IN=(PNADCICW,PREV)
    SCHEDULE-RBC=RBC10
MEMNAME=ANOTHER
      IN=(ANOTHER,ODAT)
TABLE=@INITJO3    === NOT A SMART TABLE ===    
      GROUP=GLBL-TABLE3       GLOBAL
      MEMLIB=GLBL-MEMLIB3     GLOBAL
      DAYS=5
MEMNAME=PNADCCW3
      GROUP=INIT-JOBS
      DESC='THIS IS A BATCH JOB/TABLE GENERATION'
      OUT=(PNADCICW-OK,ODAT,+)
MEMNAME=PNADCCX3
      IN=(PNADCICW,PREV)
      PREVENT-NCT2=L
***  ======= SPECIFIY NEW SET OF SUPER GLOBALS ==========
TABLE=*END
 ADD-GLOBAL=Y
      DOCLIB=SUPER.GLOBAL.DOCLIB2    SUPER GLOBAL
      APPL=SUPER-GLOBAL-APPL2        SUPER GLOBAL    
TABLE=@INITJPB
OWNER=GLBLOWN9
      GROUP=GLBL-TABLE9
      SCHEDULE-RBC=X
MEMLIB=GLBL-MEMLIB
      OVERLIB=OVER.LIB.GLOBAL9
      CONTROL=(CONTROL-RESOURCE9,E)
TABLE-ENTITY=TABLE-ENTITY1
SCHEDULE-RBC=RBC1
  WDAYS=6
SCHEDULE-RBC=RBC4
  WDAYS=0
SCHEDULE-RBC=X
SCHEDULE-RBC=*END
OUT=(TABLE-OUT-COND,ODAT,+)
MEMNAME=PNADCICW
      MEMLIB=GENERAL-LIB
      MAXRERUN=233
      INTERVAL=1440
      INTERVAL-TYP=E
      IN=(PNADCICW,PREV)
     RBC-RELATION=A
     SCHEDULE-RBC=RBC1
     RESOURCE=(JOB-RESOURCE,0099)
    SCHEDULE-RBC=*
  MEMNAME=PNADCICX
      APPL=LOCAL-APPL
      IN=(PNADCICX,PREV)
     SCHEDULE-RBC=RBC1
  MEMNAME=ANOTHER
IN=(ANOTHER,ODAT)    

LIBRARY=SCHED.LIBB
   TABLE=TABLEB
      MEMNAME=JOBB
         MODEL=(SCHED.LIBA,TABLEA,JOBA)
         OVERLIB=JCL.OVERLIBB

LIBRARY=QUEST.CTMBLT.AUTO.AFTERBLT.SCHEDULE
MEM-OVERWRITE=Y
TABLE=BLTTBLS2
TABLE-ENTITY="BLTTBLS2"
GROUP="GROUPBLT"
TASKTYP="TBC"
MAXWAIT="10"
TIMEFROM="0000"
TIMEUNTIL="2359"
CONFIRM="N"
DUE-OUT="1200"
SAC="N"
OWNER="Q82"
PRIORITY="*6"
REMOVEATONCE="Y"
DAYSKEEPNOK="03"
ADJUST-CONDS="D"
DESC="TABLE MUST BE FORCED!"
APPL="APPL-SMART-SAVE-TEST"
DOCMEM="BLTTBLS2"
DOCLIB="IOAQ.V7H2X5.CTM.OPR.DOC"
INTERVAL-TYP="E"
MAXRERUN-CYC="9999"
CYCLIC-TYPE="S"
TOLERANCE="0999"
CYC-RUNTIME="1030,000"
CYC-RUNTIME="1520,000"
CYC-RUNTIME="1310,000"
CYC-RUNTIME="2015,000"
CYC-RUNTIME="1155,000"
END    

OPTION=/DAYS
DAYS=
WDAYS=2

OPTION=/WDAYS
WDAYS=
DAYS=20

OPTION=/DATES
DATES=1112

OPTION=/DAYS
DAYS=24

OPTION=/DAYS
DAYS=

OPTION=/DAYS
DAYS=
OPTION=O
OPTION=/DATES
DATES=0202

Job Scheduling Definition Parameter Tables

The following parameters can be defined as Local or Global parameters using the CTMBLT utility. For complete descriptions of these parameters, see the Job Production parameters chapter in the Control-M for z/OS User Guide.

Note that in the following tables:

• + in column M indicates that multiple occurrences of the parameter are allowed.

• ++ in column M indicates that multiple occurrences are allowed and that ADD-GLOBAL=Y/N is relevant for this parameter.

• The USAGE column indicates special usage information. Possible values in this column and their meanings are listed below:

  • 1 - The parameter can appear in a job scheduling definition of a SMART Table.

  • 2 - The parameter can appear in the SMART Table Entity of a SMART Table.

  • 3 - The parameter can appear in a rule-based calendar definition.

  • 4 - The parameter cannot appear in a table that schedules jobs individually.

  • 5 - When the parameter is defined as a Global and/or Super Global parameter, it is ignored when the SMART Table Entity is built.

  • 6 - The Control-M job scheduling definition screen (screen 2) does not contain a corresponding parameter. Therefore, the parameter remains in effect only until the job definition is edited. This parameter is primarily used to perform on-the-fly ordering (see Building Tables in Memory Followed by Immediate Ordering).

Table 99 CTMBLT General Job Parameters

Table 100 CTMBLT Scheduling Parameters

Table 101 CTMBLT Runtime Parameters

Table 102 CTMBLT Post-Processing Parameters

Table 103 CTMBLT Special Parameters

a These parameters are for use in jobs defined on a distributed platform (for example, UNIX or SAP) only. For details on their meaning, use, format, and valid values, see the relevant guide.

CTMBLWK - Add or Update Local Workload Policies

The CTMBLWK utility enables you to add new Local Workload Policies or update existing Local Workload Policies without having to access Workload Management in the Control-M Online facility. For more information about Workload Policies, see Managing Workload Using Workload Policies.

The following JCL sample for running CTMBLWK can be found in the CTM JCL library:

//%JOBNAME% JOB %JOBCARD%                                              
//         JCLLIB  ORDER=%ILPREFA%.PROCLIB                             
//         INCLUDE MEMBER=IOASET                                       
//CTMBLWK  EXEC PGM=CTMBLWK                                            
//         INCLUDE MEMBER=&IOAENV                                      
//SYSPRINT DD SYSOUT=*                                                 
//DAWKLD   DD DISP=SHR,DSN=%ILPREFA%.PARM(CTMWKLDT)   <== CHOOSE ONE    
//DAWKLD   DD DISP=SHR,DSN=%ILPREFA%.IOAENV(CTMWKLDT) <== OPTION FOR DAWKLD        
//SYSIN    DD DISP=SHR,DSN=YOUR.INPUT.DSN(YOURMEM)    <== TAILOR OR CHOOSE THE      
//SYSIN    DD *                                       <== OTHER SYSIN OPTION
W.NAME=JUSTAJOBS
W.STATUS=A
F.MEMNAME=A*
R.TYPE=S
R.SINGDUAL=S
R.SEPOST=JUSTBJOBS
R.PERIOD_TYPE=WDAYS
R.WDAYS=ALL;
                                                                   
W.NAME=JUSTBJOBS
W.STATUS=A
F.MEMNAME=B*
R.TYPE=J
R.LIMIT=0100
R.PERIOD_TYPE=WDAYS
R.WDAYS=SUN,MON;

//SYSABEND DD SYSOUT=*

This JCL sample contains the definitions of two Workload Policies:

• JUSTAJOBS : This Workload Policy states that, based on the defined filters, jobs in members that begin with the letter A cannot run when jobs associated with the JUSTBJOBS Workload policy (that is, jobs in members that begin with the letter B) are running.

• JUSTBJOBS: This Workload Policy states that, based on the defined filters, jobs in members that begin with the letter B can run only on Sunday and Monday and are limited to a maximum of 100 jobs that can run in parallel.

CTMBLWK DD Statements

Data sets required by CTMBLWK are referenced by the following DD statements:

CTMBLWK Parameters

CTMBLWK input parameters that you define through a SYSIN statement are divided into the following categories, listed in the order that they must appear:

• General Workload parameters, which begin with the W. prefix

• Filter parameters, which begin with the F. prefix

• Rule parameters, which begin with the R. prefix

The last parameter line of each Workload Policy must end with a semicolon (;).

General Workload Parameters

The following table lists the general Workload parameters that you define with a W. prefix, in the order that they must appear:

Filter Parameters

Workload Policy Filter parameters define a combination of job attributes that determine which jobs are included in the Workload Policy. The following table lists the filter parameters that you define with an F. prefix:

Rule Parameters

Workload Policy Rule parameters enable you to define rules to apply to the jobs in the Workload Policy for controlling the job load during specific periods of time. You must define at least one rule in each Workload Policy. The following table lists the rule parameters that you define with an R. prefix:

CTMBLWK Return Codes

CTMCAJF – Maintain the Active Jobs File

The CTMCAJF utility performs special maintenance functions on the Active Jobs file. The operator is warned in advance when the file is nearly full. The operator can use the CTMCAJF utility to perform any of the following actions:

• Compress the file.

• Delete entries from the Status screen.

• Activate the AJF Space Reuse facility if requested.

• Change the size of the file by copying the file to a different size file.

CTMCAJF Statements and Parameters

The utility receives parameters, that designate the required function, using DD statement DACOPPRM (or SYSIN). Any of the following functions can be requested:

Table 104 CTMCAJF Parameters

SELECT/IGNORE Statements for CTMCAJF

SELECT/IGNORE statements are optional and can only be specified for COMPRESS and CLEANUP functions. They identify jobs that are deleted or not deleted, as follows:

Table 105 CTMCAJF SELECT/IGNORE Statements

Up to 500 SELECT/IGNORE statements can be specified. Jobs are handled according to the first statement for which the criteria are met.

One or more of the parameters described in Table 106 can be specified in any SELECT/IGNORE statement (in any order).

Table 106 CTMCAJF SELECT/IGNORE Statement Parameters

Specifying AutoEdit Variables and Functions for CTMCAJF

AutoEdit variables can be specified for any of the above parameters. These variables are especially useful for specifying relative date ranges in the FROM and TO parameters.

AutoEdit functions can be used to set variables and these variables can then be used in the parameters of the utility. The lines in which the variables are set must have an asterisk (*) in the first column of the line. Such lines are resolved by the AutoEdit facility and are interpreted as comments by the utility. Regular comments can also be specified in lines with an asterisk in the first column.

For example,

*  IGNORE MEMBERS PREFIXED WITH BR14 that WERE ORDERED
*  WITHIN THE LAST THREE DAYS.
*  %%SET %%F = %%CALCDATE %%DATE -3    IGNORE MEMBER BR14*    FROM %%F

The following AutoEdit terms cannot be used in the input for this utility:

• %%ODATE

• %%OYEAR

• %%OMONTH

• %%ODAY

• %%OWDAY

• %%INCLIB

• %%INCMEM

File Statements for CTMCAJF

File statements are mandatory for COPY functions. They cannot be specified for COMPRESS or CLEANUP functions. OLDAJF and NEWAJF statements must be specified for COPY functions:

Table 107 CTMCAJF File Statements

Compressing the Active Jobs File

The Active Jobs file often contains entries for jobs that are no longer needed (jobs with a status of DELETED or ENDED OK). Compression makes room in the Active Jobs file by physically removing these unneeded entries from the file. Removed entries are no longer displayed in the Status screen.

The compression function can also run in simulation mode. This can be done by specifying the SIMULATION statement after the COMPRESS statement. When running in simulation mode, the compress function only lists the jobs that would be removed from the active jobs file if 'real' compression were run, and does not actually remove any of them.

Cleaning the Active Jobs File

Normally, the Active Jobs file is cleaned (meaning, unneeded job entries are deleted) once a day by the New Day procedure. By default, all jobs with status ENDOK that are not being held are deleted during this cleanup. The defaults can be overridden by using SELECT/IGNORE statements (that select or ignore jobs for deletion).

The CTMCAJF utility can be run as often as necessary to clean the Active Jobs file.

Unlike the cleanup performed by the New Day procedure, the cleanup function of the CTMCAJF utility does not actually delete the unneeded jobs. Instead, it marks the job entries as deleted so that they are ignored by Control-M and so that, by default, the job entries do not appear in the Status screen. (To display these logically deleted jobs in the Active Environment Status screen, specify Y (Yes) in the DELETED field in the Show Screen Filter window (3.SHOW) of the Status screen.)

Logically deleted jobs are physically deleted the next time the New Day procedure or COMPRESS function is run.

When the CTMCAJF utility is run to clean up the Active Jobs file, it applies the cleanup criteria of the New Day procedure in addition to the cleanup criteria specified with the utility. If the cleanup criteria of the New Day procedure are not desired when running the CTMCAJF utility, they are overridden by SELECT/IGNORE statements specified in the utility.

Changing the size of the Active Jobs File

To change the size of the Control-M Active Jobs file, perform the following steps:

1. Enter ICE and select Customization.

2. In the Customization screen, set Product ID to CTM.

3. Select "Customize Control-M Dataset Parameters."

4. Select step "Control-M Dataset Parameters," update the AJFSIZE parameter and exit the step.

5. Select step "Save Parameters into Product Libraries."

6. Select step "Format the Active Jobs File," and reply Y (Yes) when asked to replace existing copy of the job.

7. Change the dsname, unit and volser as required and run the job. This step allocates and formats a new Active Jobs file and its associated BKP file.

8. Run the CTMCAJF utility. The utility copies the current Active Jobs file to new Active Jobs file.

9. Rename the old Active Jobs file.

10. Rename the new Active Jobs file to the former name of the old file.

Activating the COMPRESS function

//COMP    EXEC CTMCAJF    COMPRESS
//

Activating the COMPRESS function in simulation mode

//COMP EXEC CTMCAJF    COMPRESS    SIMULATION
//

Activating the CLEANUP function

//CLEANUP EXEC CTMCAJF    CLEANUP
//

Activating the COPY function (Active Jobs File)

//COPY EXEC CTMCAJF,
//    OLDAJF='CTM.PROD.CKP',    OLD ACTIVE JOBS FILE
//    NEWAJF='CTM.PROD.NEWCKP'    NEW ACTIVE JOBS FILE
COPY
//

A sample job to activate the COPY function of the utility can be found in member CTMCAJF2 in the Control-M JCL library.

CTMCAJF Return Codes

Table 108 CTMCAJF Return Codes

Examples for CTMCAJF

//COMP EXEC CTMCAJF    COMPRESS    IGNORE STATUS WAITSCHED    SELECT GROUP NIGHT-BATCH

//COMP EXEC CTMCAJF    COMPRESS    SELECT GROUP G1    SELECT GROUP G2    SELECT GROUP G3    IGNORE GROUP *

//COMP EXEC CTMCAJF    COMPRESS    IGNORE MEMBER A622451C    SELECT MEMBER *

CTMCRES – Copy or Resize the Control-M Resources File

The CTMCRES utility copies the contents of the Control-M Resources file to another file that may or may not be the same size, or converts a non-supported version (earlier than 6.x.x) IOA Conditions/Resources file to the current version of the Control-M Resources file. For more information, see the CONVERT parameter in Table 109.

A sample JCL to execute the utility can be found in member CTMCRES in the Control-M JCL library.

Parameters and DDNAMEs for CTMCRES

The utility accepts one parameter using PARM of the EXEC statement, as follows:

Table 109 CTMCRES Parameters

The following DD statements must be changed to correctly point to the old and new files:

Table 110 CTMCRES Statements

How to Change the Size of a Control-M Resources File

To change the size of an existing Control-M Resources file perform the following steps:

1. Enter ICE and select Customization.

2. In the Customization screen, set Product ID to CTM.

3. Select major step "Customize Control-M Dataset Parameters," and then minor step "Control-M Datasets Parameters."

4. Change parameters RESBQNT#, RESQNT# and/or RESCNTL# (depending on which part of the file is enlarged), and exit the step. For more information about these parameters, see the Control-M installation chapter in the INCONTROL for z/OS Installation Guide.

5. Perform step "Save Parameters into Product Libraries."

6. Perform step "Format the Resource File" and submit the job. This job allocates and formats a new Control-M Resources file (make sure you use a different name for the newly-formatted file that the DARESF DDstatement points to).

7. Run the CTMCRES utility, specifying the original Control-M Resources file in the DAOLDRES DDstatement and the newly-created Control-M Resources file in the DARESF DDstatement. This utility copies the original Control-M Resources file to the new file.

8. Rename the original Control-M Resources file using any new name, and then rename the new Control-M Resources file to the original file name.

9. Resume all activities that use the new file (that is, start Control-M monitor, reenter the IOA online environment, and so on.)

CTMCRES Return Codes

Table 111 CTMCRES Return Codes

CTMCSMF, CTMRSMF – Extract performance statistics

Control-M has the capability of gathering performance statistics from various Control-M components. These statistics are accumulated in the IBM System Management Facility (SMF) database. The CTMRSMF utility extracts these statistics records from SMF and creates a Comma Separated Values (.CSV) file which can be used to produce user-generated reports.

To accumulate meaningful performance data in the SMF database you must set appropriate parameters (PFMINT, PFMSMF) in the CTMPARM member of the IOA PARM library and appropriate trace levels. You can also dynamically accumulate these statistics using the Control-M PREFDATA command. For more information on the parameters, see the INCONTROL for z/OS Installation Guide. For more information on setting trace levels and using the PERFDATA command, see the INCONTROL for z/OS Administrator Guide.

Preparing the CTMCSMF utility

You need to prepare the CTMCSMF member before executing the CTMCSMF utility for the first time. All subsequent uses of the utility can use the same version of the CTMCSMF member. Use the following procedure to prepare the job in the CTMCSMF member, located in the Control-M JCL library:

• Specify the SMF input file by entering the site dependent SMF data set name in the CTMCSMF member in the IOA PROCLIB library. See the comments in the CTMCSMF member for more information on the changes needed.

• Modify the CTMCSMF member in the Control-M JCL library, as specified within the member. Specifically the following control statements need to be modified for your site:

• INDD(INDD,OPTIONS(DUMP))

• OUTDD(DUMPOUT,TYPE(??))

• For more information on these control statements, refer to the IBM System Management Facility documentation.

Extracting performance data to a .CSV file

Use the following procedure to generate a .CSV file containing Control-M performance statistics:

1. Run the job in CTMCSMF member in the Control-M JCL library. This job executes the IBM IFASMFDP utility to extract the Control-M performance statistics from the SMF database.

2. Run the job in the CTMRSMF member in the Control-M JCL library to convert the output from the CTMCSMF utility into a .CSV file.

CTMCSMF, CTMRSMF Parameters

The only parameters necessary to execute the CTMCSMF utility are control statements for the IBM IFASMFDP utility described in Preparing the CTMCSMF utility. The CTMRSMF procedure does not require any control statements.

Activating the CTMCSMF, CTMRSMF Utilities

To extract performance data from the SMF database to a .CSV file, run the following jobs in sequence:

1. Run the job in the CTMCSMF member in the Control-M JCL library

2. Run the job in the CTMRSMF member in the Control-M JCL library

CTMCSMF, CTMRSMF Output

The result of running these two utilities is a .CSV file containing Control-M performance statistics. You can use the .CSV file as input to spreadsheet type programs to select and analyze the performance data. You can also send the .CSV file to BMC Technical Support upon request.

For a detailed explanation of the structure of the performance trace record, see the INCONTROL for z/OS Administrator Guide, "Understanding the performance trace record."

Table 112 shows sample records from a .CSV file.

Table 112a Sample .csv output (columns 1 to 7)

Table 112b Sample .csv output (columns 8 to 14)

1. The scope of FUNC RELATED: # varies, according to the application. For the Control-M monitor, task CTMSUB, it refers to the number of jobs processed. For the Application Server, task CTWDET, it refers to the number of updates sent per detection cycle.

2. The scope of FUNC RELATED: AVG # varies, according to the application. For the Control-M monitor, task CTMSUB, it refers to the average number of jobs processed per CTM cycle. For the Application Server, task CTWDET, it refers to the average number of updates sent per detection cycle.

CTMCSMF, CTMRSMF Return Codes

Table 113 CTMCSMF, CMTRSMF Return Codes

TMDSR - Recovery report for SYSOUT actions

The CTMDSR utility enables you to generate a recovery report that lists SYSOUT actions or DO SYSOUT actions with an indeterminate end status. Such SYSOUT actions might exist when Control-M runs in multi-SPY mode and the Control-M Monitor terminates abnormally.

In multi-SPY mode, SYSOUT actions are performed asynchronously. This can result in an update of job status to ENDED OK or ENDED NOTOK before the SYSOUT action has been performed. If the Control-M monitor terminates abnormally during that time, the job remains in ENDED status even though the SYSOUT action has not been performed. Note that if the job is in the post-processing phase during the abnormal termination of Control-M, the job will complete during the Control-M recovery process.

The CTMDSR utility detects SYSOUT actions with an indeterminate end status based on the messages in the IOA Log.

The following JCL sample for running CTMDSR can be found in the CTM JCL library:

//*********************************************************************
//*                            CTMDSR JOB                             *
//*                                                                   *
//*   THIS JOB RUNS THE CTMDSR UTILITY, TO CHECK THE IOA LOG FOR      *
//*   'SYSOUT' ACTIONS THAT MIGHT NOT HAVE COMPLETED BEFORE AN        *
//*   ABNORMAL TERMINATION OF THE CONTROL-M MONITOR.                  *
//*                                                                   *
//*   INPUT:                                                          *
//*   ======                                                          *
//*   SYSIN DD CARD -> REPSTART YYMMDDHHMM                            *
//*                    REPEND   YYMMDDHHMM                            *
//*                                                                   *
//*   REPSTART REPRESENTS THE START TIME, AND REPEND REPRESENTS THE   *
//*   END TIME. ENSURE THAT BOTH PARAMETERS APPEAR ON CONSECUTIVE     *
//*   LINES, WITH NO LINES IN BETWEEN.                                *
//*   WHEN THE DD CARD IS MISSING THE DEFAULT VALUES WILL BE USED.    *
//*                                                                   *
//*   DEFAULT VALUES:                                                 *
//*   REPSTART 0001010000 (BEGINNING OF THE YEAR 2000)                *
//*   REPEND CURRENT DATE AND TIME                                    *
//*                                                                   *
//*                                                                   *
//*   OUTPUT:                                                         *
//*   =======                                                         *
//*   THE PROGRAM PRINTS A REPORT OF ALL THE 'SYSOUT' ACTIONS THAT    *
//*   MIGHT NOT HAVE COMPLETED BEFORE AN ABNORMAL TERMINATION         *
//*   OF THE CONTROL-M MONITOR.                                       *
//*                                                                   *
//*   REQUIRED DD CARDS:                                              *
//*   ==================                                              *
//*   DALOG, DAREPORT                                                 *
//*                                                                   *
//*********************************************************************
//*
//         JCLLIB  ORDER=xxxx.xxxx.PROCLIB    <== Update the environment prefix    
//         INCLUDE MEMBER=IOASET
//CTMDSR   EXEC PGM=CTMDSR
//         INCLUDE MEMBER=&IOAENV
//DALOG    DD DISP=SHR,DSN=&DBPREFA..LOG
//DAREPORT DD SYSOUT=*
//SYSABEND DD SYSOUT=*
//SYSIN    DD *
REPSTART YYMMDDHHMM         <== Update the date & time the report start
REPEND   YYMMDDHHMM         <== Update the date & time the report end

CTMDSR DD Statements

Data sets required by CTMDSR are referenced by the following DD statements:

Table 113a CTMDSR Required Data Sets

The CTMDSR utility receives input through the PARM of the EXEC statement or through the DD statement SYSIN.

To define the start time and end time of the report, you can choose between the following parameters:

Table 113b CTMDSR Parameters

CTMDSR generates the following output in the DAREPORT DD:

• Utility messages

• Recovery report of SYSOUT or DO SYSOUT actions with indeterminate end status

Here is an example of a CTMDSR report:

             Recovery Report for SYSOUT Actions
             ----------------------------------                 
From:  01/01/20,10:00                                               
Until: 01/01/20,11:00                                               
Log file: IOAA.MODM1.DB.LOG                                         
                                                                    
Jobname    JobID      Option          FromClass    ToClass   Dest    
---------------------------------------------------------------------
MU1S2I3    J0028950   D-Delete                                       
MU1S26Q    J0028954   C-ChangeClass   X            D                
MU1S37C    J0028956   R-Release                                     
MU1S40C    J0028958   R,C,N           X            A         U1234  
---------------------------------------------------------------------
End of report                                                        
Number of SYSOUT actions in the report: 4  

In this report:

• Options can be any of the following:

  • C — changing the SYSOUT class

  • D — deleting the sysout

  • N — changing the SYSOUT destination

  • R — releasing the SYSOUT

• SYSOUT actions from the same class can be combined in one request. For example, R,C,N (as in the last record in the sample report above). For more information see Multiple SYSOUT Operations in the Control-M for z/OS User Guide.

CTMDSR Return Codes

Table 113c CTMDSR Return Codes

CTMDSRN – Distributed system job submission from mainframe

The CTMDSRN utility executes scripts on distributed system platforms and saves the results in a file on the mainframe. The utility supports Control-M/Agent version 8.0.00 and higher but only with protocol version 10.

Activating the CTMDSRN Utility

The following DD statements are used to activate the utilities:

• STDOUT - output stream of a script

• STDIN - input stream.

• SYSPRINT - diagnostic and trace messages of the utility

• SCRIPT - refer to the file where the script to be run is located (optional)

• SYSIN - input parameters

• DEFPARMS - refers to the file with the default parameters

CTMDSRN Parameters

The CTMDSRN utility receives the following parameters from the DEFPARMS input file referenced by the SYSIN DD statement:

Table 114 CTMDSRN input parameters (referenced by SYSIN DD)

All parameters begin with a hyphen (-). The utility ignores a parameter if it is unknown. There can be more than one parameter per line. A parameter and its value are separated with spaces. A value ends when the next parameter begins or at the end of the file. Input parameters can be coded in positions 1 – 72.

If the values for the -options, -cmd, -script_name parameters contain spaces or shell meta-characters, they must be enclosed in single ( ' ) or double ( " ) quotation marks. If an enclosing character is part of the option, prefix the character with the command line escape character, back slash ( \ ).

SUBMITDS default parameter member

The DEFPARMS DD statement refers to a member that contains the default parameters for the CTMDSRN utility.

The sample default member, SUBMITDS, located in the Control-M PARM library, shows the following structure:

• Values in the file are separated with commas (and spaces following the commas).

• Lines with an asterisk (*) character in the 1st column are interpreted as comments.

• Each parameter begins in column 1 on a new line. The rest of the line, after the comma is ignored and can be used for a comment.

• Parameters use positions from 1 to 71.

• Values cannot be continued on the next line.

Figure 27 Sample default member, SUBMITDS

PORT=1111,                             Default CTM/Agent port.
SCRIPT_PREFIX=CTMMF,                   Script name prefix
SCRIPT_TYPE=bat,                       Default script type.
MF_HOST_NAME=tlv3,                     MF host name
A2ETBL=<name>,                         ASCII to EBCDIC table name
E2ATBL=<name>,                         EBCDIC to ASCII table name

The parameters in SUBMITDS are decribed in the following table:

Table 115 Description of sample default member, SUBMITDS

DSHOSTS host and agent parameter member

The DSHOSTS member, located in the Control-M PARM library, specifies the host and agent parameters.

The CTMDSRN utility searches DSHOSTS for the logical host name defined in the HOST parameter. If the host name is found, the utility retrieves the definition of this logical host name to run a script or command there.

The CTMDSRN utility uses the value of the PORT parameter specified in DSHOSTS. If no value is specified, CTMDSRN uses the default value defined in SUBMITDS.

Every host definition begins with the HOST field and ends at either the beginning of the next definition or the end of the file.

In general, every field in the host definitions must be defined in the positions from 1 to 71. Each definition begins on a new line and ends with a space. The free space in the line can be used for a comment.

The DIRECTORY field is an exception to the above rule. The value of this field can use several lines, but cannot contain any comments. If the 72nd position on a line of this field contains a character, the character is included in the value and the value continues onto the next line, starting from the 1st position.

The field names are case insensitive, but their values are case sensitive.

Lines with an asterisk character (*) in the 1st column are interpreted as comments.

Empty lines are ignored.

Table 116 Structure of DSHOSTS member

Figure 28 Example of a DSHOSTS member

host = ds_host_alias                  logical host name
real_host = ds_host_name.domain       real host name  
agentname = agent_name                agent name      
default_user = userds                 DS user         
directory = home/userDS/scripts/abcdef/dfdfd/ertrehyfgbnfb/ertretret/tyt
sdsdsd
port = 1111                           Port            

Security and user exits

Security exit CTMSE06 and user exit CTMX006 are used to verify that the specified user is allowed to submit scripts and commands on the specified host.

The $$STRDS.qname.ds_user.hostname security entity must be defined for a user to be given the permission for submitting scripts. Host name in the entity must be an actual host name, which is listed in the DSHOSTS table.

All entities must be defined in the SAF (System Authorization Facility) class that accepts long entity names. The name of this class must be assigned to the IOAXCLAS parameter of the SECPARM member in the IOA PARM library. All entities must be defined in upper case.

For example, to permit a mainframe user, USERA, to submit scripts on a host, HOSTB, using a distributed systems user, DSUSERA, use the following commands:

• For RACF

  Copy

  PERMIT $$STRDS.qname.DSUSERA.HOSTB  ACCESS(READ) ID(USERA) CLASS(XFACILIT)

• For TOP SECRET

  Copy

  TSS PERMIT(USERA) IBMFAC($$STRDS.qname.DSUSERA.HOSTB) ACC(READ)

• For ACF2

  Copy

  SET RESOURCE(CMF)
                          COMP
                      $KEY($$STRDS.qname.DSUSERA.HOSTB) TYPE(CMF) UID(USERA) ALLOW

CTMDSRN Return Codes

Table 117 CTMDSRN Return Codes

Example for CTMDSRN

//DSRUN PROC REG=0M,OUT=’*’
// EXEC PGM=CTMDSRN,REGION=&REG
//SYSPRINT DD SYSOUT=&OUT
//STDOUT DD DSN=SCRIPTOUT,DISP=(,CATLG),SPACE=(TRK,(100,10),RLSE)
//STDIN DD DSN=STDIN,DISP=SHR
//DAPARM DD DSN=IOAP.V900.PARM,DISP=SHR
//    DD DSN=IOAP.V900.IOAENV,DISP=SHR
//DAALOCIN DD DSN=IOAP.V900.IOAENV(ALCMONM), DISP=SHR
// PEND
//*
// EXEC DSRUN
//SCRIPT DD DSN=IOAP.V900.SCRIPTS(script),DISP=SHR
//SYSIN DD *
-script_name filename
-script_type bat
-j run_filename
-cmdid 0bgel
-host hostid
//

Control-M Agent requirements

The Control-M Agent requirements are described in the following list:

• A separate dedicated agent must be used with this utility. The agent cannot be shared with a Control-M/Server.

• The agent must be version 8 or higher and must use protocol version level 10.

• The agent must be configured in one of the following ways:

  • UNIX - add in CONFIG.dat - AGENT_TO_SERVER_CONNECT N

  • WINDOWS - in the registry, under the agent CONFIG key, add a new string value with the name AGENT_TO_SERVER_CONNECT and value N

In addition, the following changes in the agent configuration must be performed:

1. Run ctmagcfg - the Agent Configuration Utility.

2. Select 3: Primary Control-M/Server Host.

3. Define the mainframe hostname.

4. Select option 7: Advanced parameters.

5. Ensure that Protocol Version is [10]. If not, change it.

6. Select r: Return to the main menu.

7. Save.

8. Quit the Agent Configuration Utility.

CTMEVRT – Retrieve lost DSNEVENTs from SMF

The CTMEVRT utility is used in a process for recovering DSNEVENTs that were not handled during a CMEM outage or Control-O outage.

In general, the recovery process consists of the following stages:

1. The CTMEVRT utility reads SMF records and creates the DAEVENTS file, which contains a list of DSNEVENTs that occurred during the outage period.

2. The user edits the extracted DAEVENTS file as required.

3. The edited DAEVENTS file serves as the input to the CTMEVEX utility, which executes the actions of the CMEM/Control-O rules that were not handled during the CMEM/Control-O outage.

This utility creates a list of extracted DSNEVENTs that occurred during the time of the CMEM/Control-O outage. It accomplishes this by retrieving DSNEVENTs from the SMF records written during the outage and cross-referencing them with the CMEM/Control-O rules list.

The following JCL sample for running CTMEVRT and recovering CMEM events can be found in the CTM JCL library. It uses the CTMEVRT procedure in the IOA PROC library:

//*                                                                     
//* CONTROL-M CMEM: RECOVER LOST DSNEVENTS FROM SMF                     
//*                                                                     
//*  This is the first stage:                                           
//*      Read SMF records to retrieve missed CMEM DSNEVENTs             
//*                                                                     
//*  This utility creates a list of extracted DSNEVENTs that occurred   
//*  during the time of the CMEM outage. It accomplishes this by reading
//*  the SMF records written during the CMEM outage and                 
//*  cross-referencing them with the CMEM rules list.                   
//*                                                                     
//*  The next stage is manually reviewing DAEVENTS.                     
//*  The third stage is running CTMEVEX.                                
//*                                                                     
//         JCLLIB  ORDER=IOAP.V900.PROCLIB                              
//         INCLUDE MEMBER=IOASET                                        
//CTMEVRT  EXEC CTMEVRT                                                 
//DASMF    DD   DISP=SHR,DSN=SMF.DATASET        <==== SMF DATA SET NAME 
//DAEVENTS DD   DSN=&OLPREFM..CTMEVRT.EVENTS,                           
//           DISP=(,CATLG,DELETE),                                      
//           UNIT=&DBUNITM,                                             
//           SPACE=(TRK,(200,100))                                      
//SYSIN    DD   *                                                       
INCLTIME=2016/01/30,11:00-2016/01/30,11:30                              
SYSID=SYSA                                                              

A similar JCL sample for running CTOEVRT and recovering Control-O events can be found in the CTO JCL library. It uses the CTOEVRT procedure in the IOA PROC library. CTOEVRT was introduced in Control-O version 9.0.20.100 and can be applied to prior versions through APAR WM10166.

To enable DSNEVENTs extraction from the SMF, the following SMF record types must be collected continuously: 14, 15, 17, 30, 61, 64, 65, and 119 (z/OS Communication Server FTP records subtype 70).

For examples of a recovery scenario, see the Control-M Event Manager (CMEM) chapter in the Control-M for z/OS User Guide or the Overview of the Rule Parameters chapter in the Control-O for z/OS User Guide.

Input to CTMEVRT

The following input is relevant for CTMEVRT:

• SYSIN parameters - to identify the system, and time duration involved in the CMEM outage or Control-O outage and required for the DSNEVENT recovery

• DACTMLST DD - specifies the relevant CMEM rule list

• DARULLST - specifies the relevant IOA and CTO rule list (Control-O only)

• DASMF DD - specifies the SMF records that were written during the outage

• CTM PARM member DSNEVEXL - contains a list of datasets and jobs to be excluded from DAEVENTS output events list (Optional; member exists by default, but can be removed)

SYSIN parameters

Table 120a SYSIN parameters

DACTMLST DD

The DACTMLST DD statement, which is mandatory for CMEM, specifies the CMEM rule list. By default, this DACTMLST DD statement is identical to the DACTMLST DD statement in the CMEM or Control-O monitor procedure, but can be modified if necessary.

DARULLST DD

The DARULLST DD statement, which is mandatory for Control-O, specifies the Control-O rule list. It can be modified, if necessary.

DASMF DD

DASMF DD statement specifies the SMF records written during the outage by the required LPAR. Mandatory.

The records can be provided to the utility by using a sequential file (either a single file or a concatenation of multiple files) containing the SMF data or by using the SUBSYS=(LOGR,IFASEXIT) interface to the SMF log streams.

//DASMF    DD DSNAME=logstream.name,  
//            LRECL=32756,RECFM=VB,   
//            BLKSIZE=32760,  
//            SUBSYS=(LOGR,IFASEXIT)

There is no problem of over-supplying SMF records (for example, including 5 hours of SMF when the outage lasted only 25 minutes). Events are selected for the period specified using the INCLTIME statement.

DSNEVEXL member

The DSNEVEXL member, located in the CTM PARM library, contains a list of dataset name masks and job name masks to be excluded from all DAEVENTS list outputs. Optional; member exists by default but can be removed.

The member contains EXCLJOB and EXCLDSN statements for permanently excluding job and dataset names that are common in SMF files, but are irrelevant to the DSNEVENT recovery process (for example, temporary data sets). Excluding these job and data set names results in better utility run times. These EXCLJOB and EXCLDSN statements are in addition to the ones provided in the SYSIN statement.

Each EXCLJOB and EXCLDSN statement is listed on a separate line, starting at position 1. The rest of the line, after the job or dataset name mask is ignored and can be used as a comment. Any line beginning with an * will be treated as a comment.

The following is the default content of the DSNEVEXL member:

***********************************************************************
*                                                                     *
*            JOB AND DATA SET NAMES EXCLUDE LIST FOR                  *
*                     UTILITY CTMEVRT                                 *
*                                                                     *
* Each line in the file represents a separate exclusion case.         *
*                                                                     *
* Lines with * in 1st column are considered a comment.                *
*                                                                     *
* Possible statements are:                                            *
* EXCLJOB - Specifying a job name or job name mask                    *
* EXCLDSN - Specifying a data set name or data set name mask          *
*                                                                     *
* Each parameter begins in column 1 on a new line. The rest of        *
* the line, after the job or data set name is ignored and can be      *
* used for a comment.                                                 *
*                                                                     *
* Parameters use positions from 1 to 71.                              *
*                                                                     *
* Values cannot be continued on the next line.                        *
*                                                                     *
***********************************************************************
EXCLDSN=SYS*.T*.RA000.*                TEMPORARY DATA SETS

DAEVENTS DD

The DAEVENTS DD statement specifies the dataset that will contain the extracted DSNEVENTs.

DAREPORT DD

The DAREPORT DD statement specifies the parameters for the dataset containing the report of the successful or failed execution of the CTMEVRT utility. In addition, the report contains error messages, and statistics.

DAERR DD

The DAERR DD statement specifies the parameters for the dataset containing the error messages produced while CTMEVRT was handling the CMEM or Control-O rules' DO actions.

Output from CTMEVRT

CTMEVRT generates the following output:

• DAEVENTS DD - list of the extracted DSNEVENTs, to be used, after being manually reviewed and edited by the user, as the input to the CTMEVEX utility

• DAREPORT DD - report of successful execution, error messages, and statistics

• DAERR DD – report of any errors encountered while handling the DO actions of the CMEM/Control-O rules.

DAEVENTS file

The DAEVENTS file, the output generated by CTMEVRT, lists the extracted DSNEVENTs. The DAEVENTS file is used as the input to the CTMEVEX utility, which executes the DSNEVENTs’ DO actions. However, first the user must review and edit, if necessary, the list of DSNEVENTs, making sure that the actions to be executed are still required and will not interfere with current CMEM/Control-O processing. Special attention must be given to duplicate actions (marked with *DUP*); for example, making sure that duplicate forced jobs are appropriate.

The user can use a regular editor, to review and edit the DAEVENTS file. The user can prevent DSNEVENTs from being executed by removing them from the file or, preferably, commenting them out by inserting an asterisk at the beginning of the line.

Since the report will include DSNEVENTs that occurred prior to the CMEM/Control-O outage, it is the user's responsibility to remove DSNEVENTs that had already been handled by CMEM or Control-O.

The DAEVENTS file

• is a sequential dataset in readable format that can be modified by the user

• is sorted in chronological order

• treats any line beginning with an * as a comment

• begins with a headline that has column headers which are described in the following table:

Table 120b Column headers for the DAEVENTS file

Limitations

CTMEVRT has the following limitations:

• Events that occurred in jobs that ran with MSGLEVEL other than 1, which would not have been caught by CMEM or Control-O, will be caught by CTMEVRT as SMF has no indication of MSGLEVEL. In general, this is not a problem since rules would not be written for such jobs.

• CTMEVRT-CTMEVEX process carries out only the DO COND and DO FORCEJOB options. All other DO actions are listed, but are commented with (*) Unsupported action - not executed.

• DO COND with CONDOPT “?” will be ignored, as well as DO FORCEJOB with DATE set to anything other than a specific date, ODAT, or DATE.

• CTMEVRT cannot consider scheduling criteria and/or IN conditions for Control-O rules. These actions are commented with (!) Sched / IN conditions in the rule. You will need to manually review these actions.

• CTMEVRT cannot figure out whether conditions of a preceding IF, WHILE, or TERMINAT statement were met or not. These actions are commented with (?) Conditional-IF/WHILE/TERM precedes. You will need to manually review these actions

• CTMEVRT cannot consider PRIORITY and CONTINUE SEARCH parameters of Control-O rules. Note that these parameters could affect other active rules. Therefore, if you have rules with CONTINUE SEARCH = N, locate and manually review rules that might not get control.

• NCT2 events will not be caught since they are not reported by any standard SMF record. The report will issue a warning message if a rule for NCT2 event was found in definitions.

• Dataset deletion by IDCAMS and IKJEFT01 SYSIN is recognized by CMEM/Control-O as DISP=KEEP. The utility will recognize these events as DISP=SCRATCH.This limitation is documented in Control-O manuals.

• When JCL allocates a dataset, without opening or cataloging it, CMEM/Control-O recognizes a DISP=K event; but in such case, CTMEVRT does not recognize the event.

• CMEM/Control-O cannot detect new dataset creation when the dataset is passed to a subsequent step (that is, DISP=(..,PASS,..)). The utility will report such events.

• For batch jobs, the utility will require STEP-END SMF record in order to avoid a wrong DISP assignment caused by not seeing the entire picture (for example, seeing DISP=CATLG but missing the deletion at step termination). In special cases, the DSNEVENT will be listed with a comment that the step has not ended. This will allow the user to manually review the dataset’s disposition.

• CMEM/Control-O cannot detect data sets created using DEFINE by IDCAMS; the utility will list such events as DISP=C.

CTMEVRT Return Codes

Table 120c CTMEVRT Return Codes

CTMEVEX – Execute the actions of DSNEVENTs retrieved from SMF

The CTMEVEX utility is used in a process for recovering DSNEVENTs that were not handled during a CMEM outage or Control-O outage.

In general, the recovery process consists of the following stages:

1. The CTMEVRT utility reads SMF records and creates the DAEVENTS file, which contains a list of DSNEVENTs that occurred during the outage period.

2. The user edits the extracted DAEVENTS file as required.

3. The edited DAEVENTS file serves as the input to the CTMEVEX utility, which executes the actions of the CMEM/Control-O rules that were not handled during the CMEM/Control-O outage.

After reviewing and editing, if necessary, the list of the extracted events and the actions that would consequently be triggered, the user runs CTMEVEX on the LPAR that experienced the CMEM/Control-O outage. The CTMEVEX utility executes the rules’ DO COND actions using IOACND and the DO FORCEJOB actions using CTMJOB.

The CTMEVEX utility performs the execution process in the following stages:

1. Reading the DAEVENTS file and converting it to commands.

2. IOACND executes the DO COND commands.

3. CTMJOB executes the DO FORCEJOB commands.

The following JCL sample for running CTMEVEX can be found in the CTM JCL library. It uses the CTMEVEX procedure in the IOA PROC library:

//*                                                                     
//* CONTROL-M CMEM and Control-O: RECOVER LOST DSNEVENTS FROM SMF       
//*                                                                     
//*  This is the third stage:                                           
//*           Execute the extracted DSNEVENTs actions                   
//*                                                                     
//*  This utility executes the DO actions of the events extracted       
//*  by CTMEVRT in the previous stage.                                  
//*  CTMEVEX executes the rules DO COND actions using IOACND and the    
//*  DO FORCEJOB actions using CTMJOB.                                  
//*                                                                     
//*  The CTMEVEX utility performs the execution process in the following
//*  stages:                                                            
//*  1. Reading the DAEVENTS file and converting it to commands.        
//*  2. IOACND executes the DO COND commands.                           
//*  3. CTMJOB executes the DO FORCEJOB commands.                       
//*                                                                     
//* ** Prior to running this step please review the extracted **        
//* ** events and their matching DO actions as listed in the  **        
//* ** DAEVENTS DD. Make sure that the actions to be executed **        
//* ** are still required and will not interfere with current  **       
//* ** CMEM/Control-O processing.                              **        
//*                                                                     
//*                                                                     
//* 1. CONVERT EVENTS DO ACTIONS TO COMMANDS                            
//CTMEVEX  EXEC CTMEVEX,SIMULATE='YES'                                  
//DAEVENTS DD   DISP=SHR,DSN=&OLPREFM..CTMEVRT.EVENTS                   
//DACNDIN  DD   DISP=(,PASS),SPACE=(CYL,(2,1)),DSN=&&DACNDIN            
//DAJOB    DD   DISP=(,PASS),SPACE=(CYL,(2,1)),DSN=&&DAJOB              
//* 2. EXECUTE CONDITION COMMANDS                                       
//IOACND   EXEC IOACND,COND=(0,NE,CTMEVEX.CTMEVEX)                      
//DACNDIN  DD   DSN=&&DACNDIN,DISP=(SHR,DELETE)                         
//* 3. EXECUTE FORCEJOB COMMANDS                                        
//CTMJOB   EXEC PGM=CTMJOB,PARM='NODACHK',COND=(0,NE,CTMEVEX.CTMEVEX)   
//         INCLUDE MEMBER=&IOAENV                                       
//DAALOCIN DD   DISP=SHR,DSN=&DAALOCIN(ALCMJOBP)                        
//DAJOB    DD   DSN=&&DAJOB,DISP=(SHR,DELETE)                           

The DO actions are processed based on the ODATE of the date and time on which the event occurred (taken from the generated events file) and not based on the actual machine date/time at the utility execution (this would allow the conditions and jobs to be processed with the ODATE they were supposed to be associated with if CMEM/Control-O was up and running when the event occurred).

A simulation mode is provided through the SIMULATE parameter. When running in simulation mode the utility lists the commands to IOACND and CTMJOB but does not execute them (in simulation mode the converter step ends with return code 4 that prevents the IOACND and CTMJOB steps from running due to their COND definition).

For examples of a recovery scenario, see the Control-M Event Manager (CMEM) chapter in the Control-M for z/OS User Guide or the Overview of the Rule Parameters chapter in the Control-O for z/OS User Guide.

Input to CTMEVEX

The following input is relevant for CTMEVEX:

• DAEVENTS DD - statement specifies the (optionally edited) DAEVENTS dataset containing the list of the extracted DSNEVENTs. Mandatory.

• SIMULATE - parameter that determines whether to run CTMEVEX in simulation mode or not. Valid Values: YES/NO. Default is YES.

Output from CTMEVEX

CTMEVEX generates the following output:

• DAREPORT DD - Action conversion utility output

• DAIOACND DD - If CTMEVEX is run in simulation mode, this output file contains the commands for IOACND

• DACTMJOB DD - If CTMEVEX is run in simulation mode, this output file contains the commands for CTMJOB

• DAPRINT DD - If CTMEVEX is not run in simulation mode, this output file contains the IOACND output

• SYSPRINT DD - If CTMEVEX is not run in simulation mode, this output file contains the CTMJOB output

CTMEVEX Return Codes

Table 120d CTMEVEX Return Codes

CTMHCLN – Maintain the History Jobs File

The CTMHCLN utility performs special maintenance functions on the History Jobs file. The operator is warned in advance when the file is nearly full. The operator can use the CTMHCLN utility to delete entries from the Status screen.

SELECT/IGNORE Statements for CTMHCLN

The utility receives parameters in the form of SELECT/IGNORE statements that designate the required function, using DD statement DAFRMIN (or SYSIN). They identify jobs that are deleted or not deleted, as follows:

Table 118 CTMHCLN SELECT/IGNORE Statements

Up to 500 SELECT/IGNORE statements can be specified. Jobs are handled according to the first statement for which the criteria are met.

One or more of the parameters described in Table 119 can be specified in any SELECT/IGNORE statement (in any order).

Table 119 CTMHCLN SELECT/IGNORE Parameters

Specifying AutoEdit Variables and Functions for CTMHCLN

AutoEdit variables can be specified for any of the above parameters. These variables are especially useful for specifying relative date ranges in the FROM and TO parameters.

AutoEdit functions can be used to set variables and these variables can then be used in the parameters of the utility. The lines in which the variables are set must have an asterisk (*) in the first column of the line. Such lines are resolved by the AutoEdit facility and are interpreted as comments by the utility. Regular comments can also be specified in lines with an asterisk in the first column.

Activating the CTMHCLN Utility

A sample job to activate the utility can be found in the CTMHCLN member in the Control-M JCL library.

CTMHCLN Return Codes

Table 120 CTMHCLN Return Codes

Examples for CTMHCLN

The following examples demonstrate several maintenance functions that you can perform on the History Jobs file using the CTMHCLN utility:

• Delete jobs belonging to groups G1, G2, and G3 regardless of their retention criteria, and process all other jobs according to their retention criteria:

  Copy

  SELECT GROUP G1
  SELECT GROUP G2
  SELECT GROUP G3

• Delete all jobs with odate from 010118 to 250118, and ignore all other jobs:

  Copy

  SELECT FROM 010118 TO 250118
  IGNORE MEMBER *

• Delete all jobs with prefix MYTAB and status ENDOK, and ignore all other jobs:

  Copy

  SELECT MEMBER MYTAB* STATUS ENDOK
  IGNORE MEMBER *

• Delete all jobs with prefix JOB regardless of their retention criteria, and process all other jobs according to their retention criteria. However, do this in Simulation mode, without making changes to the History Jobs file.

  Copy

  SIMULATION
  SELECT MEMBER JOB*

CTMHCOP – Copy or Expand History Jobs File

The CTMHCOP utility copies the History Jobs file to a new History Jobs file. The utility can be used to change the size of the file by copying the file to a different size file.

Statements and Parameters for CTMHCOP

The utility receives a parameter, which designates the required function, using the DACOPPRM DD statement (or SYSIN). The following function can be requested:

Table 121 CTMHCOP Parameter

File Statements for CTMHCOP

File statements are mandatory for the COPY function. OLDHST and NEWHST statements must be specified as follows:

Table 122 CTMHCOP File Statements

Changing the Size of the History Jobs File

To change the size of the Control-M History Jobs file, perform the following steps:

1. Enter ICE and select Customization.

2. In the Customization screen, set Product ID to CTM.

3. Select "Customize Control-M Dataset Parameters."

4. Select step "Control-M Dataset Parameters," update the HSTSIZE parameter, and exit the step.

5. Select step 3, "Save Parameters into Product Libraries."

6. Select step 7, "Format the History Jobs File," and reply Y (Yes) when asked to replace existing copy.

7. Edit the FORMHST member, changing the dsname, unit, and volser as required and run the job.

8. Run the CTMHCOP utility. The utility copies the current History Jobs file to new History Jobs file.

9. Rename the old History Jobs file.

10. Rename the new History Active Jobs file to the former name of the old file.

Activating the COPY Function

A sample job to activate the utility can be found in the CTMHCOP member in the Control-M JCL library.

CTMHCOP Return Codes

Table 123 CTMHCOP Return Codes

CTMJNM – Print the daily job counts

The CTMJNM utility is used to print the daily job counts accumulated in the CTM STAT file by Control-M Monitor.

The utility does not have any input parameters.

The DD statement DASTAT defines the CTM STAT file where the daily job counts are accumulated by Control-M Monitor

The following rules are used for establishing the job count:

1. Count all jobs that reside in the AJF for a specific date - both jobs that were left from previous day and jobs ordered during the day.

2. SMART table entries (group elements) are not counted.

3. Jobs with Time Zone are counted only if the current date is between their ODATE and ODATE+MAXWAIT (if they are pre-ordered or kept a day after their MAXWAIT expired, they are not counted for those days).

4. Jobs that are deleted during the day (AJF Space Re-Use) are counted.

   The utility's report is produced in the SYSPRINT DD statement. Following is an example of the report. The report starts at the date when the corresponding Control-M began scheduling jobs and finishes at the current date.

   Copy

   DATE       , COUNTER
   13/10/2016 , 00000036
   14/10/2016 , 00000029
   15/10/2016 , 00000025
   16/10/2016 , 00000000
   17/10/2016 , 00000000
   18/10/2016 , 00000030
   19/10/2016 , 00000028
   20/10/2016 , 00000036
   21/10/2016 , 00000000
   22/10/2016 , 00000000

CTMJOB – Order Jobs to the Active Jobs File

The CTMJOB utility is a job ordering utility that can be invoked from a job step or by calling the program from a TSO environment and/or application program, such as batch or CICS.

Job ordering instructions are passed to CTMJOB using one of the following:

• DDstatement DAJOB.

  When ordering jobs using DDstatement DAJOB, job orders can be specified using one of the following methods:

  • By concatenating tables in the JCL (Method 1)

    This method requires that the user specify the name of a table and library directly in the JCL, in the format.

    DSN=sched_library(table)

    For example

    Figure 29 DD Statement DAJOB Method 1 Example

    Copy

    //DAJOB      DD  DISP=SHR,DSN=sched_library(table1)
    //           DD  DISP=SHR,DSN=sched_library(table2)
    //           DD  DISP=SHR,DSN=sched_library(table3)

  • As ORDER control statements (Method 2)

    Figure 30 DD Statement DAJOB Method 2, Example 1

    Copy

      //DAJOB      DD  DISP=SHR,DSN=parm_library(member)

    where member contains ORDER, SELECT, IGNORE statements

    Figure 31 DD Statement DAJOB Method 2, Example 2

    Copy

    //DAJOB      DD  *
        ORDER . . .
        [SELECT RBC rbcname1]
        [IGNORE RBC rbcname2]
            .
            .
            .

    The format of these statements is described in Format of the ORDER, SELECT, and IGNORE Statements for CTMJOB.

  Method2 provides the following advantages over Method1:

  • Changes required can be made to the member in the PARM library without changing the JCL.

  • Individual jobs can be specified.

  • An entire library can be specified in one order statement.

• PARM parameter in an EXEC statement in the JCL. This method can only be used to order a single table or job. For more information, see Activating the CTMJOB Utility.

By default, the CTMJOB utility stops running when a User Daily job discovers an error in one of the job scheduling definitions. Alternately, if your INCONTROL administrator sets the CNTERCRD parameter to Y (Yes) in the CTMPARM member of the IOA PARM library, the CTMJOB utility continues processing job scheduling definitions after an error occurs. In either case, the message JOB536S is issued. If the job scheduling definition that contains an error belongs to a SMART Table Entity or to a job belonging to a SMART Table, and the processing continues, the utility skips the entire SMART Table and continue processing the next job or SMART Table.

The CTMJOB utility can also be used to order tables with a particular ODATE (for example, to emulate a User Daily job with a specific date) by setting the target date to the desired ODATE for the jobs to be ordered. All other dates must be set for one day earlier. For more information about tables with a particular ODATE, see the discussion of alternative methods of job ordering in the Control-M chapter in the INCONTROL for z/OS Administrator Guide.

032100      032000  032000     032000  032000     032000

Format of the ORDER, SELECT, and IGNORE Statements for CTMJOB

ORDER, SELECT and IGNORE statements must be in the following format:

ORDER{DSN=schedlib|DDNAME=dd|DD=dd},{MEMBER=table|MEM=table}
    [,TABLE=table}[,JOB=jobnm][,ODATE=date|DATE=date]
    [,ODATEOPT={VALUE|VAL|RUN}][,FORCE][,UFLOW][,INTOTBL=table rba],
    [DUP|NODUP],[NEWT]
[SELECT RBC rbcname1]
[IGNORE RBC rbcname2]

To order an entire library with one order statement use the following format:

ORDER DSN=sched.library MEMBER=*

At least one ORDER statement must be specified. SELECT RBC and IGNORE RBC statements are optional. Multiple statements of each type are permitted.

An ORDER statement can be written from column 1 through column 72 only. If you try to continue beyond column 72, the CTMJOB utility fails and the error message JOBL34E is issued. If you want to use a very long ORDER statement, insert a minus sign (-) preceded by a space at the end of the line, before you reach column 72, and continue the statement on the next line. If you do so, the program will treat the contents of the two lines as one long line.

For example, the following would be treated as one line:

ORDER DSNAME=long_data set_name, -
MEMBER=member_name

CTMJOB Parameters

Table 124 CTMJOB Parameters

SELECT and IGNORE RBC Logic (CTMJOB)

By default, all rule-based calendars for the SMART Table Entity in the specified SMART Table are examined for scheduling eligibility. Therefore, to ignore specific rule-based calendars and select all others, you need only specify the appropriate IGNORE RBC statement. For an illustration, see Example 1 in the topic SELECT and IGNORE RBC Examples for CTMJOB.

If a rule-based calendar name matches more than one SELECT RBC or IGNORE RBC statement, the first statement that matches the RBC name is applied.

To select specific RBCs and ignore all others, first indicate the specific RBCs to be selected in SELECT RBC statements and then specify a generic IGNORE RBC statement as the last statement in that SELECT RBC or IGNORE RBC block. For an illustration, see Example 2 in the topic SELECT and IGNORE RBC Examples for CTMJOB.

The scheduling of specific jobs depends on whether optional keyword FORCE is specified in the preceding ORDER statement:

• If FORCE is not specified, RBCs specified in an IGNORE RBC statement are treated as if their basic scheduling criteria are not satisfied, that is, no jobs are scheduled according to these rule-based calendars.

  A job is scheduled when either of the following is true for the scheduling definition of the job:

  • O (Or) is specified for parameter RELATIONSHIP; and the basic scheduling criteria and/or the scheduling criteria of a selected RBC associated with the job are satisfied.

  • A (And) is specified for parameter RELATIONSHIP; and both the basic scheduling criteria and the criteria of a selected RBC are satisfied.

    If no RBC is specified for a job, the scheduling of that job is dependent only on the basic scheduling criteria of the job.

• If FORCE is specified, a job is scheduled if either of the following conditions exists:

  • At least one of the selected RBCs is associated with the job.

    or

  • No RBCs were specified in the job scheduling definition.

SELECT and IGNORE RBC Examples for CTMJOB

ORDER DSN=mylib,MEMBER=sample
IGNORE RBC ACCT*

ORDER DSN=mylib,MEMBER=sample
SELECT RBC ACCT1
SELECT RBC ACCT2
IGNORE RBC *

Activating the CTMJOB Utility

Figure 32 CTMJOB Activation

//S1 EXEC   PGM=CTMJOB,PARM=’NODACHK’
//STEPLIB   DD  DISP=SHR,DSN=ioa.loadlib
//DAPARM    DD  DISP=SHR,DSN=IOA.Vxxx.PARM
//          DD  DISP=SHR,DSN=IOA.Vxxx.IOAENV
//DAALOCIN  DD  DISP=SHR,DSN=ioa.v600.IOAENV(ALCMJOBP)
//SYSPRINT  DD  message file
//DAJOB     DD  tables or ORDER statements

Examples for CTMJOB

• The following example shows how to specify job order statements using the PARM statement in the EXEC statement:

  Copy

  //ORDERJOB EXEC   PGM=CTMJOB,
  //       PARM='ORDER DSN=IOA.PROD.SCHEDULE TABLE=TABLE1 JOB=SORT ODATE=070700'

• The following example shows how to invoke CTMJOB from an Assembler program, specify the call as shown below:

  Copy

  LOAD    EP=CTMJOB
  
  CALL    CTMJOB,(JOBPARM),VL
  DELETE  EP=CTMJOB
          .
          .
  JOBPARM  DC   Y(L'ORDERREQ)
  ORDERREQ DC   C'ORDER DSN=IOA.PROD.SCHEDULE TABLE=TABLE1 JOB=SORT DATE=070700'

• The following example shows how to invoke the CTMJOB utility from TSO, issue the following command:

  Copy

  CALL 'ioa.prod.load(CTMJOB)' 'ORDER DSN=IOA.PROD.SCHEDULE TABLE=TABLE1
  JOB=SORT,DATE=070700'

• The following example shows how to specify job order statements using the DAJOB DDstatement:

  Copy

  //ORDERJOB EXEC  PGM=CTMJOB
  //ORDERDD  DD    DSN=IOA.PROD.SCHEDULE DISP=SHR
  //DAJOB    DD    *
    ORDER  DDNAME=ORDERDD MEMBER=TABLE1 FORCE
    ORDER  DDNAME=ORDERDD MEMBER=TABLE2
    ORDER  DDNAME=ORDERDD MEMBER=TABLE3 JOB=JOB1
    . . .
  //

• The following example shows how to force a job using the PARM statement in the EXEC statement:

  Copy

  //FORCEJOB EXEC PGM=CTMJOB,
  // PARM=’ORDER DSN=IOA.PROD.SCHEDULE TABLE=TABLE2 JOB=SORT ODATE=070700 FORCE’

• To invoke the CTMJOB utility from a CICS application, parameters are passed to the API CTMCIOR using a COMMAREA described by the DSECT CTMCIAOR. The API and DSECT can be found in the IOA CICSSAMP library. Program CTMCIOR passes the parameters to the CTMJOB utility.

• The following example shows how the API is called from a CICS application using fields defined in the DSECT:

  Figure 33 CTMJOB – Example

  Copy

  PARMAREA DS    (CMORDLEN)C
  PARMARLN EQU   *-PARMAREA
           MVC   CMORDDSN,DSNAME    PARAMETERS
           MVC   CMORDTBL,TBLNAME
           MVC   CMORDJOB,JOBNAME
           MVC   CMORDDAT,DATE
           EXEC  CICS LINK PROGRAM (‘CTMCIOR’)        *
                 COMMAREA (PARMAREA)                  *
           LENGTH (=Y(PARMARLN))
              . . .
  DSNAME   DC    CL44’CTM.PROD.SCHEDULE’
  TBLNAME  DC    CL8’DEFSCHD1’
  JOBNAME  DC    CL8’JOBA’
  DATE     DC    CL6’090600’

CTMJOB Return Codes

Table 125 CTMJOB Utility Return Codes

CTMJSA – Job Statistics Accumulation

The CTMJSA utility maintains the Control-M Statistics file by updating various job statistics (start/end time, elapsed time, CPU/SRB time, and so on) and tape drive usage statistics (when the AUTOTAPE parameter in the CTMPARM member in the IOA PARM library is set to Y) and deleting inactive/obsolete records or job occurrences. The CTMJSA utility scans the IOA log file for various messages (such as SPY281I, SPY28GI, SEL208, and SEL219) to obtain the necessary statistical information. By default, only jobs that ended OK within a specified date range participate in the update process. Statistical records may also be deleted from the Statistics file according to various criteria. Refer to the CLEANUP parameter in Table 126 in CTMJSA Parameters.

A number of features that significantly improve production handling and flow rely on Statistics file data. Therefore, it is important to run CTMJSA at regular intervals. BMC recommends that CTMJSA be run at least once a day during New Day processing.

Control-M can accumulate data for up to 200 runs (occurrences) of each job on a single statistical record. See the STENT# parameter in the CTMPARM member in the IOA PARM library. By default, statistical data is not accumulated in the following cases:

• The job finished with a status of NOTOK.

• For jobs rerun using a DO RERUN statement, statistics are not accumulated for any but the last job run.

• Dummy jobs.

These defaults can be overridden with the use of the INCLUDE parameter (see below).

When the accumulation of statistical information has been properly automated, the information can be effectively used for the following facilities and reports:

• Online display of job statistics (JOBSTAT command in screen 2, S option in screen3)

• Simulation and forecasting

• Automatic Tape Drive Resource adjustment

• Deadline scheduling

• SHOUT processing that uses job elapsed times (EXECTIME)

• QUIESCE facility (planned shutdown)

• KSL reports

CTMJSA Parameters

The following parameters can be specified for the CTMJSA utility:

Table 126 CTMJSA Parameters