JCL Procedures

INTRODUCTION TO JCL PROCEDURES LAST PRINTED: 20/06/02

1. INTRODUCTION 2

1.1. Types of Procedure 21.1.1. Instream Procedures 21.1.2. Catalogued Procedures 2

1.2. Invoking a Procedure 2

1.3. Procedure Limitations. 3

1.4. JCLLIB Statement. 3

2. EXAMPLE 1 4

3. MODIFYING A PROCEDURE 6

3.1. Symbolic Parameters 6

3.2. Example 2 7

3.3. Modifying the EXEC Statement 10

3.4. Modifying DD Statements 10

3.5. Adding and amending DD statements, 12

3.6. Concatenated DD statements 12

3.7. Job log output 12

4. EXERCISE 1 14

5. EXERCISE 2 14

6. FLOW DIAGRAM 15

IT TRAINING 1


1. Introduction

A JCL procedure is a series of JCL statements very similar to those that you have already met. JCL statements are placed in a procedure and the statements are obeyed by specifying the name of the procedure on the EXEC statement. Projects use procedures as they may simplify the JCL that is submitted on a regular basis. Procedures can be modified when executed, so several programmers can use the same procedure thus saving duplication and testing. Procedures are modified by passing parameters, amending and/or adding additional DD statements.

1.1.Types of Procedure

Procedures can be either INSTREAM or CATALOGUED.

1.1.1. Instream Procedures

Instream procedures consist of EXEC and DD JCL statements placed within a job immediately after the JOB statement. They are contained within two special JCL statements PROC and PEND. PROC indicates the start of the instream procedure and contains the procedure name and details of parameters to be found within the procedure. PEND indicates the end of the instream procedure; nothing else is on this card. Instream procedures are used for testing a procedure before it becomes a catalogued procedure.

1.1.2. Catalogued Procedures

A catalogued procedure is held in a catalogued procedure library, that is a library defined to the system as one that contains catalogued procedures. At the Norwich Union there are NU.PROCLIB, SYS1.PROCLIB, SYS2.PROCLIB and SYS3.PROCLIB. A catalogued procedure has a PROC statement like instream procedures, but no PEND statement.

1.2. Invoking a Procedure

Procedures are invoked by the EXEC JCL statement in either of the following forms -

//STRDAILY EXEC PROC=TRDAILY

OR

//STRDAILY EXEC TRDAILY

- Where TRDAILY is the name of a procedure.

IT TRAINING 2


1.3.Procedure Limitations.

Certain statements cannot appear within procedures, these are: -

(1) An EXEC statement referring to a procedure, that is, only programs can be executed within a procedure.

(2) DD statements defining instream data e.g. DD * or DD DATA

(3) A JOB statement

(4) A JOBLIB statement

(5) A delimiter statement i.e. a card containing just /* in COLS 1 & 2

(6) A null statement i.e. a card just containing // in COLS 1 & 2

(7) JES2 statements e.g. /*JOBPARM

Note the following limitations apply –

there can be a maximum of 15 instream procedures within one job

a maximum of 255 job steps are allowed within one job (including all steps within any procedures called by that job)

1.4.JCLLIB Statement.

To use a catalogued procedure that does not reside in a system library you can use the JCLLIB statement to identify the relevant procedure library.

The JCLLIB statement is coded after the JOB statement and before the first EXEC statement. For example:

//SMITHFJ@ JOB .... //LIB1 JCLLIB ORDER=NUTSO.SMITHFJ.PROCLIB //.. //SPROC1 EXEC procname //..

IT TRAINING 3


2. Example 1

The following is an example of an instream procedure called TRCRE, if it were a catalogued procedure, the line containing PEND would be omitted.

//NUTRD14B JOB F-ZZZZZ-NUTR-TTT,// JCL.G-TS,// CLASS=A,// MSGCLASS=X,// NOTIFY=NUTRD14//*//******************************************************************************//* *//* JOB: PROCEDURE TRCRE FREQUENCY: WEEKLY *//* *//* STEP: PTRA040 PURPOSE: RUNS MAINFILE FORMAT *//* PROG TRA040 *//* *//* STEP: PTRA020 PURPOSE: RUNS MAINFILE PRINT *//* PROG TRA020 *//* *//******************************************************************************//*//TRCRE PROC//*//******************************************************************************//* *//* STEP: PTRA040 PROGRAM: TRA040 *//* *//* PURPOSE: PRODUCES MAINFILE FORMAT FROM *//* 80 BYTE RECORDS *//* *//******************************************************************************//*//PTRA040 EXEC PGM=TRA040//STEPLIB DD DSN=NUTRD.NUTRD14.LOAD,// DISP=SHR//CR01 DD DSN=NUTRD.MASTER.DATA(CTRACCS),// DISP=SHR//UT11 DD DSN=NUTRD14.TESTFILE,// DISP=(NEW,CATLG,DELETE),// UNIT=DEVPOOL,// SPACE=(TRK,(2,1),RLSE),// DCB=(RECFM=VB,LRECL=1328,BLKSIZE=0)//LP11 DD SYSOUT=X

IT TRAINING 4


//*//******************************************************************************//* *//* STEP: PTRA020 PROGRAM: TRA020 *//* *//* PURPOSE: PRINTS MAINFILE *//* *//******************************************************************************//*//PTRA020 EXEC PGM=TRA020//STEPLIB DD DSN=NUTRD.NUTRD14.LOAD,// DISP=SHR//UT01 DD DSN=NUTRD14.TESTFILE,// DISP=SHR//LP11 DD SYSOUT=X// PEND//*//******************************************************************************//* *//* STEP: STRCRE PROCEDURE TRCRE *//* *//* PURPOSE: RUNS TRA040AND/OR TRA020 *//* *//******************************************************************************//*//STRCRE EXEC TRCRE

Note stepnames within a procedure begin with a ‘P’

IT TRAINING 5


3. Modifying a procedure

A procedure can be modified by: -

(1) Using symbolic parameters

(2) Amending EXEC statements within the procedure

(3) Overriding parameters on the procedure's DD statements

(4) Providing Additional DD statements.

3.1.Symbolic Parameters

A symbolic parameter is represented within a procedure by an & followed by 1 - 7 alphanumeric or national (£#@) characters. The first character must not be numeric. A symbolic parameter cannot be the same name as a JCL parameter that can be coded on the EXEC statement e.g. &COND is not allowed. A symbolic parameter is defined on the PROC statement; therefore it is easy to see what symbolic parameters are used in a procedure. These parameters can be given a default value. This is the value that will be used if a value is not given when the procedure is executed. When the system finds a symbolic parameter in a procedure it substitutes the value that has been assigned to it. This value can be assigned on the procedure call or omitted in which case the default value as defined on the PROC statement is taken. Referring to EXAMPLE 1 symbolic parameters could be used for the dataset produced in step PTRA040 and for the SYSOUT parameter. These would be defined on the PROC statement e.g.If we use two symbolic parameters as below//TRCRE PROC DSN1=,SOUT=X

Then in step PTRA040 //UT11 DD DSN=NUTRD14.TESTFILE,// DISP=(NEW,CATLG,DELETE),

would become//UT11 DD DSN=&DSN1,// DISP=(NEW,CATLG,DELETE),

and in step PTRA020//UT01 DD DSN=NUTRD14.TESTFILE,// DISP=SHR

would become//UT01 DD DSN=&DSN1,// DISP=SHRand//LP11 DD SYSOUT=X

would become//LP11 DD SYSOUT=&SOUT

IT TRAINING 6


Example 2 shows the complete procedure with symbolic parameters.

3.2.Example 2

//NUTRD14B JOB F-ZZZZZ-NUTR-TTT,// JCL.G-TS,// CLASS=A,// MSGCLASS=X,// NOTIFY=NUTRD14//*//******************************************************************************//* *//* JOB: PROCEDURE TRCRE FREQUENCY: WEEKLY *//* *//* STEP: PTRA040 PURPOSE: RUNS MAINFILE FORMAT *//* PROG TRA040 *//* *//* STEP: PTRA020 PURPOSE: RUNS MAINFILE PRINT *//* PROG TRA020 *//* *//******************************************************************************//*//TRCRE PROC DSN1=, SOUT=X//*//******************************************************************************//* *//* STEP: PTRA040 PROGRAM: TRA040 *//* *//* PURPOSE: PRODUCES MAINFILE FORMAT FROM *//* 80 BYTE RECORDS *//* *//******************************************************************************//*//PTRA040 EXEC PGM=TRA040//STEPLIB DD DSN=&DSN1,// DISP=SHR//CR01 DD DSN=NUTRD.MASTER.DATA(CTRACCS),// DISP=SHR//UT11 DD DSN=NUTRD14.TESTFILE,// DISP=(NEW,CATLG,DELETE),// UNIT=DEVPOOL,// SPACE=(TRK,(2,1),RLSE),// DCB=(RECFM=VB,LRECL=1328,BLKSIZE=0)//LP11 DD SYSOUT=&SOUT

IT TRAINING 7


//*//******************************************************************************//* *//* STEP: PTRA020 PROGRAM: TRA020 *//* *//* PURPOSE: PRINTS MAINFILE *//* *//******************************************************************************//*//PTRA020 EXEC PGM=TRA020//STEPLIB DD DSN=NUTRD.NUTRD14.LOAD,// DISP=SHR//UT01 DD DSN=NUTRD14.TESTFILE,// DISP=SHR//LP11 DD SYSOUT=&SOUT// PEND//*

Note - Both parameters are defined on the PROC statement. The DSN1 parameter is not given a default value, as this procedure is designed to be used by several people, it is impossible to give a meaningful value. The SOUT parameter has been given a default value of X.

To execute this procedure the following could be coded

Example A

//******************************************************************************//* *//* STEP: STRCRE PROCEDURE TRCRE *//* *//* PURPOSE: RUNS TRA040AND/OR TRA020 *//* *//******************************************************************************//*//STRCRE EXEC TRCRE,// DSN1=’NUTRD14.TESTFILE’,// SOUT=A

The values for DSN1 and SOUT are assigned on the procedure execute statement. The name for DSN1 must be enclosed in quotes. Quotes are necessary if a value contains any of the characters . , + or *

Example B//******************************************************************************//* *//* STEP: STRCRE PROCEDURE TRCRE *

IT TRAINING 8


//* *//* PURPOSE: RUNS TRA040AND/OR TRA020 *//* *//******************************************************************************//*//STRCRE EXEC TRCRE,// DSN1=’NUTRD14.TESTFILE’

A value is assigned to DSN1. The default value of X is used for SOUT.

Note - a value for a parameter cannot be continued onto another line. Continuation can only take place after a complete parameter followed by a comma.

Default values for parameters can be nullified by coding parameter= on the procedure call e.g. nullify the SOUT parameter of our procedure in Example 1 code//******************************************************************************//* *//* STEP: STRCRE PROCEDURE TRCRE *//* *//* PURPOSE: RUNS TRA040AND/OR TRA020 *//* *//******************************************************************************//*//STRCRE EXEC TRCRE,// DSN1=’NUTRD14.TESTFILE’,// SOUT=

Care must be taken when nullifying symbolic parameters that represent positional parameters. for example the procedure TRDAILY contains the following statement,

//TRDAILY PROC SOUT=A::

//LP11 DD DUMMY,// SYSOUT=&SOUT

It is decided to include a symbolic parameter so that DUMMY can be optional.A way to do this would be to code

//TRDAILY PROC SOUT=A,// TYPE=DUMMY

::

//LP11 DD &TYPE,// SYSOUT=&SOUT

If TYPE is nullified to omit the use of DUMMY as follows

//STRDAILY EXEC TRAILY,

IT TRAINING 9


// TYPE=

after substitution the DD statement would be

//LP11 DD ,SYSOUT=A

The comma will cause a JCL error. To overcome this problem, the procedure should be coded

//LP11 DD &TYPE.SYSOUT=&SOUT

The EXEC statement can be

//STRDAILY TRDAILY,// TYPE='DUMMY',// SOUT=Xor//STRDAILY TRDAILY// TYPE=,// SOUT=X

The symbolic parameter has been followed by a full stop, not a comma, the full stop marks the end of the symbolic parameter.

3.3.Modifying the EXEC Statement

To add, nullify or amend a parameter on an EXEC statement within a procedure code -

parameter.procstepname=value on the EXEC statement for the procedure.

Examples

(1) To add a PARM parameter to program TRA040 in our procedure Example 2 code

//STRCRE EXEC TRCRE,// PARM.PTRA040=010483

(2) To nullify the COND parameter in step PTRA090 of procedure TRDAILY code

//STRDAILY EXEC TRDAILY,// COND.PTRA090=

To amend an existing value use (1) above.

3.4.Modifying DD Statements

The format for modifying DD statements is as follows

IT TRAINING 10


//procedure step name.ddname DD parameter=value.

These statements follow the statement that executes the procedure. They have to be in the same order as they appear in the procedure.

More than one parameter on a DD statement can be changed and more than one DD statement changed. Subparameters e.g. BLKSIZE can be amended in the same way as parameters. It is not necessary to redefine all the DCB parameter, only the subparameter(s) that require amendment. As before when nullifying a parameter the = sign should not be followed by a value. If the parameter is not present on the DD statement it will be added.

Examples (Refer to Procedure Example 2)

(A) To change the volume serial number of UT11 DD statement of step PTRA040 code -

//STRCRE EXEC TRCRE,// DSN1='NUTRD.NUTRD07.MAINFILE'//PTRA040.UT11 DD VOL=SER=NUD102

If the VOL parameter had not been coded on that statement, this parameter would be added.

(B) To add a SYSIN DD statement to step PTRA040 of TRCRE code –

//STRCRE EXEC TRCRE,// DSN1='NUTRD14.TESTFILE'//PTRA040.SYSIN DD *14.03.83/*

This is the only way to add instream data to a procedure.

(C) To amend DD statement UT11 to write to a tape and to change the blocksize code

//STRCRE TRCRE,DSN1='NUTRD.NUTRD15.TESTFILE'//PTRA040.UT11 DD UNIT=CART,// VOL=,// SPACE=,// DCB=BLKSIZE=32760

BLKSIZE and UNIT have been amended, VOL and SPACE have been nullified since these parameters are not needed for cartridge datasets.

(D) To add an OUTLIM parameter to both LP11 DD statements code

//STRCRE TRCRE,DSN1='NUTRD15.TESTFILE'//PTRA040.LP11 DD OUTLIM=2000//PTRA020.LP11 DD OUTLIM=2000

IT TRAINING 11


3.5.Adding and amending DD statements,

1) The amended DD statements follow the procedure EXEC statement.2) These DD statements must be in the same order as their corresponding DD statements

within the procedure.3) Additional DD statements follow any modifying DD statements for that procedure step.

3.6.Concatenated DD statements

Care must be taken when modifying or adding to concatenated DD statements within procedures. The order of the DD statements is important. To add a third load library to two concatenated libraries the system must be informed that the two libraries are to be retained by coding blank DD statements.

For example if a procedure TRDAILY contains the following -

//PTRA090 EXEC PGM=TRA090//STEPLIB DD DSN=NUTRD.MASTER.LOAD,// DISP=SHR// DD DSN=NUTRD.NUTRD01.LOAD,// DISP=SHR//UT01 DD DSN=NUTRD.SM.MAINFILE,// DISP=SHR

- and it is required to add another load library, code

//STRDAILY EXEC TR DAILY//PTRA090.STEPLIB DD// DD// DD DSN=NU.LINKLIB,// DISP=SHR

If it is necessary to amend the second library, code

//STRDAILY EXEC TRDAILY//PTRA090.STEPLIB DD// DD DSN=NUTRD.NUTRD14.LOAD

3.7.Job log output

In a job that uses JCL procedures, the job log will list the procedure statements after the procedure execute statement. This listing will distinguish between the original job

IT TRAINING 12


statements, procedure statements, amended procedure statements and comments. Columns 1 and 2 will contain -

Catalogued InstreamProcedure Procedure

Coded in job // //Procedure not amended XX ++Amended procedure X/ +/

Comment lines have *** in columns 1-3 for both procedure types.See following example.

MSGLEVEL can be coded on the JOB statement, if not coded the default value of MSGLEVEL=(1,1) is used. This causes all JCL statements in the job stream and all JCL statements in any catalogued procedures executed to be printed, also all allocation messages are printed. To suppress printing the JCL from the catalogued procedures code MSGLEVEL=(2,1)

Then only the JCL in the input stream and the allocation messages will be printed.

IT TRAINING 13


4. Exercise 1

Write an instream procedure, TRPROC, to run the suite in the following diagram.

Steps are required for

(a) IDCAMS delete output serial datasets from all reporting programs

(b) PTRA0040n

(c) PTRA025

Use symbolic parameters for the following

(i) Input dataset for PTRA040n.

(ii) Output serial file(UT11) from PTRA040n, later input(UT01) to PTRA025

(iii) LP11 dataset from PTRA040n

(iv) LP11 dataset from PTRA025

(v) Output class for joblog MSGCLASS, default to V

NOTE: - Remember that PTRA040 needs to have a date and vat rate passed as PARM parameters Steps should only run if all earlier steps are successful. See Attached Flow diagram on the next page.

5. EXERCISE 2

(a) Extract the PROC from exercise 1 into a separate piece of JCL

(b) Create a new piece of JCL to run the procedure, with a JCLLIB ORDER statement and the required EXEC statement and parameter values only after the jobcard.

IT TRAINING 14


6. Flow Diagram

IT TRAINING 15

IDCAMSDELETE

PTRA040 UT11

PTRA040 LP11

PTRA020 LP11

PTRA040n NUTRD.MAPC.TESTDATA (PTRA040) UT01

PTRA040 UT11

PTRA040 LP11

PTRA025

PTRA020 LP11

C SYSIN

DATE &VAT RATEPARM

Documents

JCL Procedures