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

Overview

The Control-M JCL Verify Application Program Interface (CTJAPI) is an open interface between the application environment and Control-M JCL Verify. CTJAPI enables your application program to interface with Control-M JCL Verify so that you can access services and extract data from Control-M JCL Verify into your own programs.

A sample ENDEVOR exit 4 that invokes JCL Verify using the CTJAPI macro is provided in the CTJAPIA member in the IOA SAMPLE library.

Functions

The following CTJAPI functions are available:

  • initialize the Control-M JCL Verify environment

  • perform JCL verification

  • reformat JCL statements

  • enforce values for variables used in JCL

  • perform cleanup when terminating the Control-M JCL Verify environment

CTJAPI macro keywords and program requirements

The CTJAPI macro is the interface service API for Control-M JCL Verify. It allows the user to define the communication block and call CTJAPI to perform the requests.

The macro automatically changes keywords that must be in uppercase. For example, jobname is changed to JOBNAME.

Examples of the CTJAPI macro for verification, reformat, or enforcement are shown in Fig.JV.8.1 or Fig.JV.8.2 respectively and the macro keywords are described in the table Tab.JV.8.1.

The program must be defined as AMODE31 and RMODE31.

When assembling the program, the IOA MAC library must be concatenated to SYSLIB.

The program must be link-edited as non-authorized, AMODE(31).

The following DD must be available when executing the program:

Copy 
//DAPARM   DD DISP=SHR,DSN=ilprefa.PARM  
//         DD DISP=SHR,DSN=ilprefa.IOAENV

Examples of programs that use the CTJAPI macro can be found at the end of this chapter and in the CTJAPIA member in the IOA.SAMPLE library.

Tab.JV.8.1 Macro keywords

Keyword

Description

Func

Positional parameter that describes the required service. There are no defaults. Mandatory. Valid values:

  • INIT - Initializes the Control-M JCL Verify environment. See notes above.

When Func is INIT, the block is reformatted and the fields, if not set, will contain X'00'.

When a keyword is not used, the macro does not change the related field. The defaults from CTJPARM member will be used.

  • SCAN - performs JCL validation

  • END - performs cleanup when terminating the interface. See note in JMSG

  • APID - generates the API Communication Area DSECT. It can also be specified as a positional parameter (CTJAPI APID)

  • ENF - performs enforcement

  • REF - performs reformatting

  • ENFREF - performs both enforcement and reformatting

DSECT

Defines the CTJAPI block as a DSECT. Valid values:

  • Y - Yes

  • N - No

FA

Whether to verify file access privileges. Valid values:

  • Y - Yes

  • N - No

  • D - as Defined by the DSNACCSS parameter in the CTJPARM member. Default

FV

Whether to perform dataset verification. The dataset is verified whether it is cataloged and whether it is in the volume as specified in the DD statement or in the catalog. Valid values are:

  • Y - Yes

  • N - No

  • S - exclude SPACE check

  • U - perform file validation, without issuing any relevant messages, recommended for use with the Utility validation (UT=Y)

  • D - as Defined by the DSNEXIST parameter in the CTJPARM member. Default

CTM

Whether to resolve Control-M AutoEdit variables in the job. Valid values are:

  • Y - Yes.

  • N - No

  • D - as Defined by the CTMVARS parameter in the CTJPARM member. Default

STDR

Whether to use the Control-M JCL Verify rules to verify site standards. Valid values:

  • Y - Yes

  • N - No

  • D - as Defined by the STDR parameter in the CTJPARM member. Default

ENV

Whether to use, in addition to the GENERAL rules, rules that are defined for specific environments for the site standard verifications. Valid values are:

  • Y - Yes

  • N - No

  • D - empty - only GENERAL rules are used. Default

JCL#

Address of a 4-byte field containing the number of JCL statements passed to CTJAPI, in binary format (DS F).

JCL@

Address of buffer containing the JOB to be verified.

Only one job can be verified. In case the buffer contains more than one job only the first job will be handled.

JES

Whether to verify that the JES2 or JES3 statements are correct. Valid values are:

  • Y - Yes

  • N - No

  • D - as Defined by the JESTTMNT parameter in the CTJPARM member. Default

JMSG

Get the Control-M JCL Verify messages for the job from the message buffer. For verification, specify Y. For enforcement/reformatting, to perform SAV=Y, specify JMSG=N. See Tab.JV.8.2 "ENF and REF parameters" below. Valid values:

  • Y - Yes

  • N - No

After the scan is completed the following fields are set:

  • JAPIJMSG@ - address of message buffer. The address of the buffer is above the BAR, meaning that the address is to a double-word address area.

  • JAPIJMSG# - number of messages in buffer

  • JAPIJMSGT – TCB token used to free the buffer

Each message is 256 bytes long. The actual text starts in position 3 and is 132 bytes long.

The calling program is responsible for releasing the message buffer.

LIB

Address of a 44-byte field containing the DSNAME of a library containing the JCL member(s) to be verified. Mandatory.

MEMBER

Address of an 8-byte field containing the name of the member, or masking of the members (* or ?) to be verified. If * or null is specified then all members in the library will be verified.

MCT

MCT address. Mandatory. Valid values:

  • (R12) - Default

  • =0 - MCT field is set to 0 and the API module will initialize the IOA environment

  • Null - the MCT field will not be changed

  • address of MCT block

  • (Rx) - address of MCT block in any register 2 to 12

ME

Module existence. The module in EXEC PGM=module_name is existence is verified.

  • If the PGM is not found, a warning message will be issued.

  • If the PGM is found, an information message that contains from where the PGM (DD name or LINKLIST and library name)

Valid values:

  • Y - Yes

  • N - No

  • D - as Defined by the PGMCHECK parameter in the CTJPARM member. Default

ML

The minimum level of message severity to be issued. Valid values are:

  • I - Information - all messages are issued.

  • W - Warning messages and errors are issued.

  • E - only Error messages are issued

  • D - as Defined by the MSGLEVEL parameter in the CTJPARM member. Default

JMSG=Y all messages will be available

RAREA

Label of CTJAPI communication block. Mandatory. Valid values:

  • APID - the default name when creating a CTJAPI block using: CTJAPI APID

USER

Address of an 8-byte field containing the user ID to be used in the file access privileges (FA) verifications. Valid values are:

  • user_ID

  • *DEFAULT - use the default user ID (either the user invoking the CTJVER utility, or in the case of a Control-M job definition, the Control-M owner - as specified in the OWNER field in the job definition)

The USER is used in all the statements that follows it until a new USER is specified). If the USER statement is omitted, then USER=*DEFAULT.

If the JOB statement contains USER=, then this user is used.

UT

Whether to verify the syntax of the IBM utilities (for details, see JCL and syntax verification) and the DB2 related validation.

Valid values are:

  • Y - Yes

  • N - No

  • D - as Defined by the SUPUTIL parameter in the CTJPARM member. Default

  • If the existence and the attributes of the datasets used in the IBM utilities must be verified, set FV=Y or FV=U, as described above in this table for the FV parameter.

  • DB2 validation requires additional steps. See the "Enabling DB2 Support" section in the INCONTROL for z/OS Installation Guide: Installing.

ODATE

Address of a 6-byte field containing the Control-M Order Date, in character format. The user can change the date. If it is left blank, the default is the current date. The format of it is: YYMMDD

ODATE is used during Control-M AutoEdit variable resolution.

NODE

Used for remote processing. Address of an 8-byte field containing NODE name of IOAGATE running on a remote sysplex. For more details, see Tab.JV.3.1 CTJMON routing parameters in Defining the target CTJMON where the processing will be submitted.

IE

Used for remote processing. Address of an 8-byte field containing the QNAME of a CTJMON running on the target sysplex.

For more details, see Tab.JV.3.1 CTJMON routing parameters in Defining the target CTJMON where the processing will be submitted.

SYS

Used for remote processing. Address of an 8-byte field containing the MVS system name of the target system in the target SYSPLEX.

For more details, see Tab.JV.3.1 CTJMON routing parameters in Defining the target CTJMON where the processing will be submitted.

AR

Specifies whether Auto Routing will be enabled (Y) or not (N) or

whether the default (D) (AROUTE parameter in CTJPARM) Auto Routing will be used.

CNDALC

Specifies whether conditional dataset allocation verification feature will be used. Valid values: Y | N | D (D=use CNDALC setting in CTJPARM).

PROCDD

Address of an 8-byte field containing the name of a predefined DD card from which the procedures are resolved when the JCLs are verified. For example, PROC01.

The DD card must be predefined in JES PROCLIB or in the CTJPRC member and will be the only procedure library searched.

For more information, see JES2/3 Predefined PROCLIBs.

LINKDD

Address of an 8-byte field containing the identifier of statements in the CTJLINK member which define load module libraries to be searched during program existence check. See CTJLINK: User Link Libraries for Program Existence Check.

The Control-M JCL Verify Application Program Interface provides the ENF function for enforcement, the REF function for reformatting, or the ENFREF function for both. Additional parameters are listed in the following table.

These functions are invoked by specifying FUNC=ENF, FUNC=REF, or FUNC=ENFREF.

Tab.JV.8.2 ENF and REF parameters

Parameter

Description

CTM

Whether to resolve Control-M AutoEdit variables. Valid values are:

  • Y - Yes

  • N - No. Default

LIB

Address of a 44-byte field which specifies the library where the JCL is located. Mandatory.

MEM

Address of an 8-byte field which specifies the member where the JCL is located. Optional. Supports masking (* and ?).

NODE

Name of the remote verification node. See Tab.JV.8.1 "Macro keywords" above.

SYS

Remote MVS system name. See Tab.JV.8.1 "Macro keywords" above.

IE

CTJMON QNAME. See Tab.JV.8.1 "Macro keywords" above.

OVR

Whether to override the existing member. Valid values are:

  • Y - Yes. You must also specify JMSG=N,SAV=Y.

  • N - No. Default

SAV

Whether to save changed JCL. Valid values are:

  • Y - Yes. You must also specify JMSG=N.

  • N - No. Default

JMSG

Whether to return the message buffer. IF SAV=Y is specified then JMSG=N must be specified.

SAVLIB

Address of an 8-byte field which specifies the library where the JCL will be saved.

SAVMEM

Address of an 8-byte field which specifies the member where the JCL will be saved. Optional. (Applicable for one member only).

CTJAPI Return Codes

The return code from the INIT function is in Register 15. A value of 0 indicates successful initialization.

The return code is placed in the JAPIRC field after the END function.

Return code values for the utilities involved can be found in the INCONTROL for z/OS Utilities Guide:

  • Verification values are listed in CTJVER Return Codes.

  • Enforcement/reformat values are listed in CTJENR Return Codes.

CTJAPI message buffer

The application program can access the verification report after the CTJAPI SCAN call is completed. The following fields in the CTJAPI block are set:

  • JAPIJMSG@ - address of message buffer. The address of the buffer is above the BAR, meaning that the address is to a double-word address area. The program must issue the SAM64 instruction prior to accessing the messages, and SAM31 to revert to 31-bit mode after moving the message(s) to below the bar.

  • JAPIJMSG# - number of messages in buffer

  • JAPIJMSGT - TCB token used to free the buffer

The following example releases the 64 bit buffer:

Copy 
*
FREE OUTPUT BUFFER
*
MVC JOBSTEP_TTOKEN,JAPIJMSGT GET TCB TOKEN
IARV64 REQUEST=DETACH, FREE MEMORY OBJECT X
COND=YES, CONDITIONAL REQUEST X
TTOKEN=JOBSTEP_TTOKEN, RELATE THE STOR TO TCB X
MATCH=SINGLE, X
MEMOBJSTART=JAPIJMSG@, AREA ADDRESS X
MF=(E,RV64PRMS) POINTER TO THE PARAMETERS AREA

Each message is 256 bytes long. The actual text starts in position 3 and is 132 bytes long.

The internal messages in the following table indicate the record types in the message buffer.

The calling program is responsible for releasing the message buffer. See Fig.JV.8.1 CTJAPI Macro Example - Verification in The Control-M JCL Verify Application Program Interface (API).

Tab.JV.8.3 Internal messages

Message

Description

CTJ100I

Reserved for future use.

CTJ101I

Indicates an original JCL statement or comment in the verified member.

CTJ102I

Indicates a JCL statement or comment that was added to expand the JCL procedure in the verified member. The source of the addition is indicated by one of the following symbols, which starts the JCL text, as follows:

  • xx - JCL statement from a JCL PROCEDURE or INCLUDE member

  • xx* - JCL comment from a JCL PROCEDURE or INCLUDE member

  • ++ - JCL statement from an instream JCL PROCEDURE

  • ++* - JCL comment from an instream JCL PROCEDURE

CTJ103I

Indicates an IBM message that normally appears in the JESJCL or JESYSMSG when the JOB is submitted and executed.

CTJ104I

Indicates a SYSIN record.

CTJ105I

Indicates a "//SYSIN DD" statement, which Control-M JCL Verify generates when simulating JES2 or JES3. When the job is submitted, an asterisk is added as follows: //SYSIN    DD *

CTJ106I

Reserved for future use.

CTJ107I

Reserved for future use.

CTJ108I

Reserved for future use.

CTJ109I

A null (//) JCL statement indicates the end of a job.

An example of using CTJAPI for enforcement and reformatting is shown in the following figure.

Fig.JV.8.1 CTJAPI Macro Example - Verification

Copy 
CTJAPIA   CSECT     CTJAPIA   AMODE 31  
CTJAPIA   RMODE 31  
.
.         PERFORM HOUSEKEEPING ETC.
.
.
*        INITIALIZATION
*
INIT     CTJAPI INIT,RAREA=APIJ,MCT=0
*
*        PERFORM JCL VERIFICATION
*
         CTJAPI SCAN,RAREA=APIJ,JMSG=Y, CALL CTJAPI VERIFY             X
               LIB=FILDSN,              FOR THIS PDS....               X
               MEMBER=FILDSMEM,         AND MEMBER,WITH PARMS          X
               FV=Y,                    PERFORM FILE VERIFICATION      X
               FA=Y                     CHECK FILE ACCESS              
*
*        FREE OUTPUT BUFFER 
*
         MVC   JOBSTEP_TTOKEN,JAPIJMSGT  GET TCB TOKEN                       
         IARV64 REQUEST=DETACH,    FREE MEMORY OBJECT                  X
               COND=YES,           CONDITIONAL REQUEST                 X
               TTOKEN=JOBSTEP_TTOKEN, RELATE THE STOR TO TCB           X
               MATCH=SINGLE,                                           X
               MEMOBJSTART=JAPIJMSG@, AREA ADDRESS                     X
               MF=(E,RV64PRMS)     POINTER TO THE PARAMETERS AREA 
* 
*        TERMINATION
*
END      CTJAPI END,RAREA=APIJ
         MVC    MYRC,JAPIRC        SAVE RC 
.
.        PERFORM PROGRAM TERMINATION
.       
.

*
*        DATA AREAS
*
JOBSTEP_TTOKEN DS CL16            TCB TOKEN                             
         IARV64 MF=(L,RV64PRMS)   IARV64 PARAMETERS - LIST FORM                   
FILDSN   DC   CL44’MY.JCL.PDS’    DSNAME
FILDSMEM DC   CL8’JOB1’           MEMBER
MYRC     DS   F                   RETURN CODE    
APIJ          CTJAPI APID

Fig.JV.8.2 CTJAPI Macro Example - Enforcement

Copy 
CTJAPIA   CSECT     
CTJAPIA   AMODE 31  
CTJAPIA   RMODE 31  
.
.         PERFORM HOUSEKEEPING ETC.
.
.
*        INITIALIZATION
*
INIT     CTJAPI INIT,RAREA=APIJ,MCT=0
*
*        PERFORM ENFORCEMENT. REPLACE THE MEMBER AFTER ENFORCEMENT
* 
         CTJAPI ENF,RAREA=APIJ,JMSG=N, CALL CTJAPIENFORCE              X
               LIB=FILDSN,              FOR THIS PDS....               X
               MEMBER=FILDSMEM,         AND MEMBER,WITH PARMS          X
               SAV=Y,                   SAVE CHANGED MEMBER IN SAME PDSX
               OVR=Y                    REPLACE MEMBER               
* 
*        TERMINATION
*
END      CTJAPI END,RAREA=APIJ
         MVC   MYRC,JAPIRC              SAVE RC
.
.        PERFORM PROGRAM TERMINATION
.       
.

*
*        DATA AREAS
*
FILDSN   DC   CL44’MY.JCL.PDS’    DSNAME
FILDSMEM DC   CL8’JOB1’           MEMBER 
MYRC     DS   F                   RETURN CODE    
APIJ          CTJAPI APID