Getting Started

This chapter includes the following topics:

Introduction

Control-M JCL Verify validates JCL jobs and issues validation reports. Control-M JCL Verify validates:

  • JCL jobs

    • Members that include JCL statements are analyzed to ensure that the JCL statements are valid.

  • JCL procedures

    • Members that include JCL procedures are analyzed to ensure that the JCL procedures are valid.

    • Reformatting and enforcement processes can be applied to JCL procedures.

  • Control-M job definitions

    • Members, which Control-M job definitions refer to by MEMNAME and MEMLIB, are analyzed to ensure that the JCL statements are valid.

    • In-stream JCL statements, which are included in the job definition itself, are analyzed to ensure that they are valid.

  • For handling of Control-M conditional JCL statements, see the description of the CTMCJCLI parameter in Customizing Control-M JCL Verify in the INCONTROL for z/OS Installation Guide: Customizing.

Control-M JCL Verify verifies the following issues:

  • Basic JCL syntax

  • JES2 and JES3 statements

  • Syntax of IBM utilities

    Syntax check of the IDCAMS ALLOCATE command is limited to the most important parameters.

  • DB2 subsystem, plan status, and program existence as specified in the TSO DSN command

    (SYSTEM, PLAN, PROGRAM, LIBRARY, and CP parameters)

  • Dataset verification (except for ADRDSSU), including allocation (conditional and unconditional) and space check for SMS and non-SMS datasets

    Space check is not performed for datasets allocated through the IDCAMS utility.

  • Job flow and dependencies

  • Dataset access privileges

  • Load module existence

Control-M JCL Verify ensures that JCL statements comply with enterprise standards using the following rule-based processes:

  • Reformatting

  • Enforcement

  • Site standards

Control-M JCL Verify consists of the following features:

  • A batch utility (CTJVER) for verifying JCL jobs and Control-M job definitions

  • A batch utility (CTJENR) for reformatting or enforcement of JCL jobs

  • A batch utility (CTJPLAN) for verifying Control-M jobs that are scheduled for submission

  • An edit macro, which can be invoked from ISPF, for verifying a job being edited

  • New Control-M JCL Verify JV option available from the IOA Primary Option Menu

  • New line options and commands for invoking Control-M JCL Verify from Control-M panels

  • A Control-M JCL Verify application program interface (API) for performing JCL verification from user applications

  • A batch utility (CTJMRFLW) for dependency awareness verification

The utility verifications are available for each one of the above features.

Methods for running Control-M JCL Verify

You can run the Control-M JCL Verify product through several different interfaces and utilities:

Tab.JV.1.1 Methods for running Control-M JCL Verify

Method

Description

Further information

CTJVER utility

Verifies a JCL job before it is submitted, even jobs referred to from or contained inside Control-M definitions. CTJVER can either verify a single job or work in mass mode, verifying many jobs together.

CTJVER - JCL Job Pre-Submission Verification in the INCONTROL for z/OS Utilities Guide

CTJENR utility

Performs reformatting or enforcement of JCL jobs. CTJENR can either process a single job or multiple jobs.

CTJENR - JCL Job Reformatting and Enforcement in the INCONTROL for z/OS Utilities Guide

CTJXVER edit macro

A macro that you invoke from the ISPF editor to verify a JCL job before it is submitted, as well as to perform reformatting and enforcement of JCL jobs.

CTJXVER Edit Macro

IOA and Control-M user interface

Control-M JCL Verify can be invoked from the IOA Primary Option Menu for verifying, reformatting, or enforcing JCL jobs. When Control-M is installed, Control-M JCL Verify can be invoked from several Control-M user interface panels.

Online JCL Processing from IOA and Control-M Interfaces

Control-M JCL Verify Application Program Interface (CTJAPI)

An open interface between the application environment and Control-M JCL Verify, which enables your application program to access Control-M JCL Verify services and to extract data into your own programs.

The Control-M JCL Verify Application Program Interface (API)

Additional utilities can be used to run or access Control-M JCL Verify in special cases. The CTJMRFLW utility validates JCL job work flows through the verification of the job order and dependencies. The CTJPLAN utility verifies JCL jobs that are scheduled for submission. For more information about these utilities, see the INCONTROL for z/OS Utilities Guide.

The verification process

The verification process consists of the following steps:

Initialization

In the initialization step, the IOA and basic environment for Control-M JCL Verify is created.

This step includes:

  • setting the Control-M JCL Verify functionality by specifying

    • the installation parameters

    • the parameters supplied during runtime

  • initializing the security

  • collecting resources that are required for JCL verification

Since the required resources are common for all Control-M JCL Verify users, JCL verification performance is usually significantly increased

  1. by creating the Control-M JCL Verify Shared Object and loading the site standards rules to the common area (see Improving Performance)

  2. identifying JES2 PROCLIBs by

    1. determining whether PROCLIBs defined in JES are in use

    2. determining whether mandatory PROCLIBs are in use

    3. checking CTJPRC for predefined PROCLIBs. For more details on the CTJPRC member, see CTJPRC format.

    If the mandatory JES2 PROCLIBs DD statements do not exist, the Control-M JCL Verify initialization will fail, and the verification will be stopped.

  3. loading site related information into the shared objects

Verification

The verification consists of the following stages:

JCL and syntax verification

In this stage, the validity of the following items is verified:

  • the JCL used in the job

  • the syntax of the JES2 or JES3 statements

  • the syntax of the following IBM utilities: IEBGENER, IEBCOPY, IEHPROGM, IEHLIST, ADRDSSU, IDCAMS, SORT, ICEMAN, SYNCSORT, and IKJEFT01.

  • the syntax of the aliases of the above IBM utilities. Aliases can be defined in the CTJALUT member. For more information, see Using Aliases for Utility Names.

  • DB2 subsystem, plan status, and program existence as specified in the TSO DSN command

The verification process continues to the next stage if there are no JCL errors and no JES2 or JES3 syntax errors that would cause JES2 or JES3 to reject the job.

Environment verification

In this stage, the validity of the following items is verified in the environment where the job is executed:

File Access

The File Access Validation determines whether the user has access to the dataset required by the job being verified.

The user being checked, who might not necessarily be the one performing the verification, is determined by the following criteria:

  • the user that is specified by the USER keyword in the JOB statement

  • in Control-M, the user that is specified by the OWNER field in the job definition

  • in the CTJVER utility, the user that is specified by the USER statement

  • in ISPF, the user that is specified in the CTJXVER P edit macro window (see Verification mode)

  • the user that performs the verification

The authority validations checks are based on the DISP keyword in the DD statement as listed below:

  • DISP=SHR - required read permission

  • DISP=OLD - required update permission

  • DISP=NEW - required create permission

  • DISP=MOD and the file exists - required update permission

  • DISP=MOD and the file is new - required create permission

  • DISP=(…,DELETE) - required delete permission

  • DISP=(…,UNCATLG) - required uncatalog permission

The READ, UPDATE, CREATE, DELETE and UNCATLG permissions are logical and depend on the security package that is installed and on the z/OS release.

Dataset verification

Based on the DISP, UNIT, and VOL DD statement keywords, Control-M JCL Verify validates that the

  • file exists

  • file is cataloged

  • file exists in the correct volume

  • volume has sufficient space for allocating the new datasets, based on the SPACE DD statement keyword

If the UNIT type is a removable type (like tape or cartridge) or if the file is migrated (by IBM/DFHSM or another product), Control-M JCL Verify cannot validate that the file exists on the correct volume and cannot verify the file attributes.

A temporary dataset, starting with a prefix of &&* and followed by a number, is used when the DSN keyword does not exist in the JCL DD statement.

In this case, the %%$DDDSN variable shows this temporary value.

Copy 
                4 //NDSNDEV  DD  DISP=(NEW,PASS),
                  //         DCB=(LRECL=0080,BLKSIZE=3120,RECFM=FB,DSORG=PS),   
                  //         SPACE=(TRK,(0001,0001),RLSE),                      
                  //         MGMTCLAS=TOTO                                      
CTJDSIW         4 WARNING: SPECIFIED MGMTCLAS TOTO does not exist. DSN=&&*00000001
Conditional dataset references

References to datasets (for example, allocation, creation, deletion) from conditional steps (that is, steps with COND= parameter or within an IF/THEN/ELSE block) may be considered conditional as the dataset reference may or may not occur due to return codes or abends from preceding steps.

Control-M JCL Verify can issue warning messages when a dataset reference might be invalid, depending on whether the preceding conditional reference has occurred or not.

Conditional dataset reference warnings can be optionally enabled using the CNDALC parameter in CTJPARM:

  • When CNDALC=N (the default) is used, Control-M JCL Verify considers all steps as if they always run, regardless of being conditional or not.

  • When CNDALC=Y, Control-M JCL Verify considers all the dataset references in conditional steps as references that may or may not occur and issues warning messages when the current step relies on it (because dataset status is in doubt).

Example 1:

Copy 
//MYJOB JOB 
//STEP1 EXEC PGM=IEFBR14
//STEP2 EXEC PGM=IEFBR14,COND=(0,GT,STEP1)
//DD1   DD  DSN=DSN1,DISP=(NEW,CATLG)
//STEP3 EXEC PGM=IEFBR14
//DD2   DD  DSN=DSN1,DISP=OLD

STEP2 is a conditional step and has COND= parameter. Dataset references made by this step are considered conditional. This step allocates a new dataset DSN1 (DD1), which is later referenced (with DISP=SHR) by STEP3 (DD2).

DD2 may or may not be valid, depending on whether STEP2 was executed or not (that is, it may not be valid if STEP2 was not executed and DSN1 was not created by it). Control-M JCL Verify can optionally issue a warning message saying “DSN1 may not exist”.

Copy 
CTJDC1W     WARNING: DSN WITH DISP=OLD MAY NOT EXIST. DSN=DSN1

Example 2:

Copy 
//MYJOB JOB 
//STEP1 EXEC PGM=IEFBR14
//STEP2 EXEC PGM=IEFBR14,COND=(0,GT,STEP1)
//DD1   DD  DSN=DSN1,DISP=(OLD,DELETE)
//STEP3 EXEC PGM=IEFBR14
//DD2   DD  DSN=DSN1,DISP=(NEW,CATLG)

STEP2 (the conditional step) deletes dataset DSN1. A later step in the job, STEP3, re-creates DSN1, which may or may not be valid, depending on whether STEP2 was executed or not (that is, it may not be valid if STEP2 was not executed and DSN1 already exists).

Control-M JCL Verify can optionally issue a warning message saying “DSN1 may already exist”.

Copy 
CTJDC0W     WARNING: DSN WITH DISP=NEW MAY ALREADY EXIST. DSN=DSN1

Example 3:

Copy 
//MYJOB JOB 
//STEP1 EXEC PGM=IEFBR14
//STEP2 EXEC PGM=IEFBR14,COND=(0,GT,STEP1)
//DD1   DD  DSN=DSN1,DISP=(NEW,CATLG) 
//STEP3 EXEC PGM=IEFBR14
//DD2   DD  DSN=DSN1,DISP=(NEW,CATLG) 

Both STEP2 (the conditional step) and STEP3 create dataset DSN1. Dataset creation in STEP3 (DD2) may or may not be valid, depending on whether STEP2 was executed or not (that is, it may not be valid if STEP2 was executed and already created DSN1).

With CNDALC=N (the default), the following error message will be issued, indicating that the dataset already exists (as both steps are considered unconditional).

Copy 
CTJD02W     WARNING: DSN with DISP=NEW already exists. DSN=

With CNDALC=Y, the following warning message will be issued, indicating that dataset creation may fail as DSN1 may already exist.

Copy 
CTJDC0W     WARNING: DSN WITH DISP=NEW MAY ALREADY EXIST. DSN=DSN1

For all disk space calculations, Control-M JCL Verify considers all steps as unconditional and assumes that the space used by all the datasets is allocated/released by all steps.

Program existence

The name of the module in the EXEC PGM= statement is verified that it exists in the STEPLIB, JOBLIB, or LINKLIST libraries.

Note:

  • Control-M JCL Verify checks program existence using IBM search order rules. To perform this check the Control-M JCL Verify monitor requires read access for all STEPLIBs and JOBLIBs.

  • You can add libraries to the standard search order using the CTJLINK member. For more information, see CTJLINK: User Link Libraries for Program Existence Check.

Dependencies and job flow verification

In addition to single job verification, Control-M JCL Verify can validate work flows through the verification of the job order and dependencies. Control-M JCL Verify can verify a mixture of Control-M schedule definition and regular JCL jobs.

A procedure, named CTJMRFLW, invokes Control-M to determine the job order and job dependencies. Then, after arranging the jobs and schedule definitions in the order as they are intended to run, CTJMRFLW invokes Control-M JCL Verify for the job flow verification. At each stage of the job flow, Control-M JCL Verify examines the datasets of the previously verified jobs to determine if those datasets still exist or were deleted, and, based on the dependencies, verifies the job flow.

The CTJMRFLW can manage up to 10,000 accumulated datasets that are used by all the jobs that are verified in the execution. The limitation in this utility is not based on the maximum jobs number, but from the number of all the datasets that are processed by all the jobs in the execution.

To verify the current job's datasets, the status of the datasets are determined by the following factors:

  • the entire job flow hierarchy to which the job belongs

  • the previous instances of the datasets

  • all the verified jobs at the parallel hierarchic level, whether they are directly or indirectly related to the job

In some situations, where the results of the dependence analysis might be ambiguous, warning messages are displayed and the user must investigate the situation.

For example, if two jobs are both directly dependent on a previous job, by definition these two jobs will run on the same level of hierarchy, which is lower than the previous job. Even though it is certain that these two jobs will run after the higher-level job, it is not certain in what order the two equal-level jobs will run. The warning messages alert the user to investigate whether the actual order of the jobs will be problematic or not.

Even though that Control-M arranges the JCLs for Control-M JCL Verify, there is a chance that datasets will be allocated or handled besides these JCLs.

For more information about the CTJMRFLW utility, see CTJMRFLW - Job Flow Verification in the INCONTROL for z/OS Utilities Guide.

Scheduled JCL job verification

To verify JCL jobs that are scheduled for submission, you can use a procedure that includes running the CTJPLAN utility. The procedure requires that Control-M is installed. The procedure involves using the CTMRPLN and CTJVER utilities.

The procedure can verify jobs referred to from Control-M job definitions that will be ordered on the specified date. The procedure can either verify a single table or work in mass mode, verifying many jobs together (for example, verifying all the jobs in a library).

For more information about the CTJPLAN utility, see CTJPLAN - Scheduled JCL Job Verification in the INCONTROL for z/OS Utilities Guide.

Reformatting, enforcement, and site standards rule-based processing

The reformatting, enforcement, and site standards features ensure that JCL statements comply with required enterprise standards. The user defines rules that specify the required formats, values, or standards, and then runs Control-M JCL Verify to apply the rules.

The rules are defined and created through the Control-M JCL Verify rules definition (JR screen) and are loaded through the Control-M JCL Verify monitor.

The processing can be performed for each JCL statement.

Termination

Sets the following return codes based on the verification results:

  • Return code 4

    The results contain only failures (for example, file not found) that are caused by the current environment and can be set correctly before the job is executed.

  • Return code 8

    The results contain failures (for example, a JCL error) that require changes in the JCL.

  • Return code 12

    The results contain failures that are caused by the Control-M JCL Verify input, which stops the verification process.

  • Return code 16 and above

    The results contain failures that are caused by Control-M JCL Verify processing errors (for example, REGION is too small).

Print the verification results or prepare the results in a buffer, which can be accessed by a user application with the Control-M JCL Verify application program interface (CTJAPI).

If there are no more verification requests, perform a cleanup and then release all resources.

Installation

Follow the installation as described in the INCONTROL for z/OS Installation Guide: Installing.

The IOA Security interface must be installed to allow the Control-M JCL Verify monitor (CTJMON) to utilize the requester user ID when processing requests. If the IOA Security interface is not installed, CTJMON's own user is used for processing requests, and this might cause inaccurate authorization verifications or even a security breach. For more information about implementing IOA Security, see the INCONTROL for z/OS Installation Guide: Installing.

JES2/3 Predefined PROCLIBs

Member CTJPRC in the CTJ PARM library defines the libraries in which procedures are searched for during Control-M JCL Verify processing.

Control-M JCL Verify searches for procedures referenced by jobs being processed using the following default search order:

  1. Procedures libraries defined in the CTJPRC member

  2. Procedures libraries defined in JES

The above default search order can be adjusted using the PRCONOR parameter in CTJPARM. PRCONOR controls the procedures concatenation order.

  • Procedure libraries are defined in the JES initialization parameters using:

    • PROCLIB(lib-name) statements in JES2

    • DYNALLOC,DDN=IATPLBxx,DSN=lib-name statements in JES3

  • Procedures libraries can also be defined directly in the JES procedure using DD cards concatenation.

Since Control-M JCL Verify automatically detects only those libraries defined in JES, in certain cases you will need to define procedure libraries explicitly in the CTJPRC member. See When to use CTJPRC.

The libraries defined in the CTJPRC member are associated with DD card names and are concatenated on top of the libraries defined in JES with the same DD card name. Several DD card names can be used to match the DD card names in JES.

For a detailed description of the correct syntax, see CTJPRC format.

JES3 consideration

The DYNALLOC statements for the IATPLBxx libraries are only processed by the JES3 Global processor, but are ignored by the JES3 Local processor.

As a result, Control-M JCL Verify is unable to automatically detect the procedure libraries defined on JES3 Local processors and all the procedures libraries for the local JES3 processors must be explicitly defined in this member (see When to use CTJPRC).

Related CTJPARM parameters

The following CTJPARM parameters influence the procedures libraries concatenation and search order:

  • PRCONOR - Determines the concatenation order of the libraries defined in CTJPRC in relation to the libraries defined in JES.

    Valid values:

    • T – the allocation for the DD’s from the CTJPRC member are at the TOP of PROCLIBS for JES

    • B – the allocation for the DD’s from the CTJPRC member are at the BOTTOM of PROCLIBS for JES

    • O – the allocation for the DD’s from the CTJPRC member will OVERRIDE the PROCLIBS for JES

  • PRDEFDD - Determines the default DD card name association from which the procedure libraries are searched.

When to use CTJPRC

The CTJPRC member must be used to define procedure libraries for Control-M JCL Verify in the following cases:

  • When procedure libraries are defined in the JES procedure using direct DD concatenation.

  • Such libraries are not automatically detected by Control-M/ JCL Verify and therefore must be explicitly defined in the CTJPRC member. The libraries must be defined in the same concatenation order and with the same DD card name association as in the JES procedure.

  • When a procedure library, which is not one of the standard system procedure libraries, is defined in JES it must be added to the top of the procedures search order. This library can be used as a staging library in which procedures can be verified before they are introduced into the system.

  • When Control-M JCL Verify is used on a JES3 Local processor, all the procedure libraries must be defined in the respective CTJPRC for the LPAR.

CTJPRC format

  • JES2/3 PROCLIB DD name in position 1

  • Procedure library name follows after at least one blank. The library name must be a valid DSNAME.

  • "*" (asterisk) in position 1 is a comment line.

The following system symbol can be embedded within the library name:

  • &SYSNAME

  • &USERID

  • &SYSPLEX

  • &SMFID

a period ('.') must follow after the system name if the library name has a suffix qualifier following the system name. For example: SYS2.&SYSNAME..PROCLIB

Following are the sample CTJPRC members that are in the CTJ PARM library:

Fig.JV.1.1 Sample CTJPRC member for JES2

Copy 
**===================================================================****
  CTJPRC sample for JES2                                           **
**===================================================================**
PROC00         SYS2.&SYSNAME..PROCLIB                                  
PROC00         SYS1.PROCLIB                                            
*                                                                      
PROC01         USER.PROCLIB                                            

Fig.JV.1.2 Sample CTJPRC member for JES3

Copy 
**===================================================================****
  CTJPRC sample for JES3                                           **
**===================================================================**
IATPLBST       SYS2.&SYSNAME..PROCLIB                                  
IATPLBST       SYS1.PROCLIB                                            
                                                                       
IATPLB01       USER.PROCLIB                                            

Customization

Follow the instructions for customizations described in the INCONTROL for z/OS Installation Guide: Customizing - Customizing Control-M JCL Verify

Restrictions

Control-M JCL Verify and CTJXVER, the Control-M JCL Verify edit macro, can verify any sequential or member of a partitioned dataset (PDS/PDSE). The dataset must have a record length of 80 and a fixed record format (FB/F).

Note that Control-M JCL Verify always evaluates system symbols. However, when submitting a JCL in JES, the evaluation of system symbols is dependent on the JES CLASS definition that is defined by the SYSSYM parameter, which must be set to ALLOW. When using system symbols in a JCL, ensure that the properties of the JOBCLASS allow system symbol evaluation.