The purpose of this document is to describe the Job Control Language (JCL) used on IBM mainframes.

Forward

I originally wrote this document in 1991 and even then JCL was considered an obscure topic that few understood, yet it remains at the core of many major enterprise applications. I have made some updates but many of the references are dated. A quick Google search will find the current documentation.

A number of the parameters are site specific so you will need to consult your local system administrator and modify accordingly.

The IBM mainframe operating system has had several names, such as: MVS, MVS/XA, MVS/ESA, OS/390, zOS. For the purpose of this document these are equivalent.

Paul Shipley,

16 July, 2011

Introduction

IBM Job Control Language (JCL) remains one of the most obscure parts of the use of IBM and compatible mainframes. The reason for this are many:

• JCL has remained largely unchanged since it was originally released in the mid-1960’s as part of the System/360. This system used punched cards for all input and printed or punched output. Jobs were queued by physically placing them in a central card reader! Much of the terminology of JCL still refers to cards even though IBM no longer supports card readers.

• Many of the options available are either obsolete or seldom used, yet they are given equal weight in the IBM manuals.

• IBM provides no standard way of testing or debugging JCL.

• Few people understand JCL well.

   

The aim of this paper is to highlight some of the important points to using JCL without repeating all of the work of other sources.

JCL Syntax

There are only three main statements (or cards in IBM terminology) that are used frequently. There are several more statements which are seldom used. The following are some points which are of interest when using JCL.

JOB Card

The JOB Card commences a new job. If it is invalid then the job fails without any programs being executed.

Two parameters on the JOB Card can cause problems.

The Region Parameter:- specifies the maximum amount of system memory to be available to any programs executed. This can also be specified on the EXEC Card for a particular program, however the value specified on the JOB Card overrides that on the EXEC Card. Normally there is no reason for using the Region Parameter on the EXEC Card as this only causes confusion.

The Cond Parameter:- has the same function as for the EXEC Card however the condition specified on the JOB Card is evaluated first. Normally if the COND Parameter is coded on the JOB Card it would not be coded on any of the EXEC cards.

Syntax

//jobname JOB ‘account code’, ‘programmer name’,

// CLASS=class,MSGCLASS=msgclass,

// REGION=region,MSGLEVEL=(statements,messages),

// NOTIFY=userid

EXEC Card

The EXEC Card causes the execution of a program or procedure.

Syntax

Execute Program

//stepname EXEC PGM=program-name[,COND=(code,operator)][,PARM=‘parm’]

Execute Procedure

//stepname EXEC PROC=procedure-name[,symbolic-parm=‘value’,…]

// [,PARM.proc-step=‘parm’,…]

Where

Reproduced from Figure 15-1 MVS/XA JCL Reference

DD Card

The DD (Data Definition) Card is the most frequently used JCL statement. It is also the source of most of the confusion.

Temporary Data Sets

There are two types of Data Sets: Permanent and Temporary. The data set name (DSN) distinguishes the two types. Permanent data sets you should already be familiar with, since your PDSs are permanent.

Temporary data sets are created during a job and can be given a name starting with two ampersands (eg: &&TEMP). The disposition for this type of data set should be (NEW,PASS) and the data set will be automatically deleted at the end of the job. This type of data set is useful for passing intermediate data from one step to another.

The data set name parameter (ie: DSN=) can be omitted in which case the data set is given a unique name by the system. The disposition should be (NEW,DELETE) and the data set will be deleted at the end of the step. This type of data set is useful for work files.

Do not try to catalog these data sets!

A single ampersand can be used instead of the double ampersand, but this can cause confusion with symbolic parameters and should be avoided.

Device Specification

The UNIT parameter specifies the type of device that a data set can be located on. UNIT never needs to be specified if the data set has been cataloged since on of the items in the catalog is the device type. UNIT should not specified for VSAM or SYSOUT data sets.

Valid values for UNIT are:

Space Allocation

When creating a new data set on disk, allocation information must be given via the SPACE parameter. The information that is required is allocation quantity, the primary and secondary allocations, the number of directory blocks for a PDS, and Optionally some extra sub-parameters.

The allocation quantity should always be tracks (TRK) or cylinders (CYL). Allocations of more than 15 tracks should be in cylinders (1 cylinder = 15 tracks). It is possible to specify the quantity in blocks, however since space on the disk is allocated in tracks, MVS has to calculate the tracks required for the number of blocks specified. This method can result in inefficient allocations.

The primary allocation should be the expected largest size of the data set plus ten percent. The secondary allocation would normally be set to twenty percent of the primary. Specifying a secondary larger than the primary is a problem waiting to occur! MVS attempts to allocate the primary before the step commences execution, so if the space is not available the job abends immediately. Secondary allocations are made as they are needed. If the space for a secondary allocation is not available then the job abends. This could occur after significant processing, which would be lost. Also do not rely on having all 15 secondaries, since there may not be enough space on the disk.

When allocating PDS (DSORG=PO) specify a directory allocation. One directory block can provided for six members with ISPF statistics or eighteen without.

Coding the optional release (RLSE) sub-parameter will cause any unused space at the end of the data set to be freed and returned to the system when the step closes the data set. This is usually a good idea however there are a number of limitations. RLSE works only when a data set is opened for output and is closed normally. RLSE does not work if the data set is being shared. RLSE does not work if the job abends without closing the data set.

Data Control Block (DCB)

The DCB has a large number of sub-parameters which are not always required.

For a data set being created by the job (DISP=NEW) a DCB is almost always required. If the data set already exists (eg: it has been cataloged) then a DCB should not be specified.

The DCB can be modelled on an existing data set by specifying the existing data set name in the new data sets DCB parameter. For example DCB=(dsname) or DCB=(*.ddname) where the ddname is a data set specified in another DD within the job step.

The data set organization (DSORG) specifies the structure of the data set. There are three common values:

PS Physical Sequential

PO Partitioned Organization

DA Direct Access

The record format (RECFM) specifies the structure of the records within the data set. There are two common values:

FB Fixed length, Blocked

VB Variable length, Blocked

The logical record length (LRECL) specifies the maximum length of the records in the data set, which can range from 1 to the block size. For variable length records the LRECL must be four bytes larger than the required length so that MVS can write the record length information.

For sequential data sets the block size (BLKSIZE) can be calculated by the following formulas:

For Fixed length, Blocked data sets

BLKSIZE = LRECL * INT(23,476 / LRECL)

For Variable length, Blocked data sets

BLKSIZE = ((AvRecL+4) * INT(23,468/(AvRecL+4)) + 4

where AvRecl is the average record length

For 80 byte record partitioned data sets the block size should be specified as 3840 bytes.

Syntax Terms

Read from cataloged data set

//ddname DD DSN=dsname,DISP=SHR

Write to cataloged data set

//ddname DD DSN=dsname,DISP=OLD

There is some confusion regarding the use SHR and OLD dispositions as they are some times equated with Read and Write attributes on other machines (ie: Bull), however this is completely incorrect. A data set with SHR can be written to! However OLD should always be specified when updating a data set.

Note that SAS will not write to a SAS data set unless OLD is specified.

Use cataloged tape data set

//ddname DD DSN=dsname,DISP=OLD,UNIT=(,,DEFER)

Specifying DEFER delays mounting of the tape until it is opened by the job. Normally MVS will mount all tapes at the start of each step. If the tape is then not used (due to an error perhaps) it would have been mounted unnecessarily.

For tapes DISP=OLD should be specified since tapes can not be shared!

Note that UNIT=CART is not required in this case since the catalog identifies the data set as being on tape.

Use uncatalogued non-IBM ASCII tape data set

//ddname DD DSN=dsname,

// DISP=(OLD,KEEP),

// UNIT=(CART,,DEFER),

// VOL=SER=(volser[,volser,…]),

// LABEL=(l,SL,EXPDT=98000),

// DCB=(DSORG=PS,RECFM=recfm,

// BLKSIZE=blksize,LRECL=lrecl,OPTCD=Q

For non-IBM tapes (which are usually in ASCII) extra information needs to be specified.

Tapes from other sites are never cataloged locally so the Volume Serial (volser) needs to be specified. If the data set spans more than one tape then all of the volsers must be specified. Failing to specify all of the volsers will result in truncation.

To indicate that the tape is from another site requires that EXPDT 98000 be specified. This informs CA-1 (formally UCC-1) not to check for the tape in its data base. Failing to do this may result in an abend.

IBM mainframes always use the EBCDIC character set unless OPTCD=Q is specified. This causes a EBCDIC / ASCII conversion during input/output. This option can only be specified for tape data sets.

In this example the external tape is really a 3480 cartridge (UNIT=CART).

Create temporary sequential data set

//ddname DD DSN=&&ddname,

// DISP=(NEW,DELETE,DELETE),

// UNIT=unit,[VOL=SER=volser,]

// SPACE=(size,(primary,secondary)[,RLSE]),

// DCB=(DSORG=PS,RECFM=recfm,BLKSIZE=blksize,LRECL=lrecl)

The data set is temporary due to the double ampersand name and is physical sequential because the DSORG has been specified as PS.

Create temporary partitioned data set

//ddname DD DSN=&&ddname,

// DISP=(NEW,PASS,DELETE),

// UNIT=unit,[VOL=SER=volser,]

// SPACE=(size,(primary,secondary,directory)),

// DCB=(DSORG=PO,RECFM=recfm,BLKSIZE=blksize,LRECL=lrecl)

This is the same as the example above except that the DSORG has been specified as PO making the data set partitioned. A directory allocation is therefore required.

Create tape data set

//ddname DD DSN=dsname,

// DISP=(NEW,CATLG,DELETE)

// UNIT=(CART,,DEFER),

// LABEL=(1,SL,RETPD=days),

// DCB=(DSORG=PS,RECFM=recfm,BLKSIZE=blksize,LRECL=lrecl)

Create very large tape data set

//ddname DD DSN=dsname,

// DISP=(NEW,CATLG,DELETE)

// UNIT=(CART,,DEFER),

// VOL=(PRIVATE,RETAIN,,scratch-count),

// LABEL=(1,SL,RETPD=days),

// DCB=(DSORG=PS,RECFM=recfm,BLKSIZE=blksize,LRECL=Ireel)

MVS has a default maximum of five volumes for a new data set. If you reach this maximum you will get a very strange message indicating that you have reached the end of file on a data set which is being output to! To overcome this the scratch-count value should be increased to its next value, which is twenty. The following table shows the valid values for the scratch­count.

Create tape data set in ASCII format for use by non—IBM computer

//ddname DD DSN=dsname,

// DISP=(NEW,KEEP,DELETE),

// UNIT=(CART,,DEFER),

// LABEL=(1,SL,RETPD=2),

// DCB=(DSORG=PS,RECFM=recfm

// BLKSIZE=blksize,LRECL=lrecl,OPTCD=Q)

Note: Many non-IBM computers have block size limits and other restrictions, check with their system programmers.

Delete Disk Data Set

The following JCL will delete a disk data set without abending if it does not exist.

//stepname EXEC PGM=IEFBR14

//ddname DD DSN=dsname,

// DISP=(MOD,DELETE),

// UNIT=DISK,

// SPACE=(TRK,0)

Delete Tape Data Set

//stepname EXEC PGM=IEFBR14

//ddname DD DSN=dsname,

// DISP=(MOD,DELETE),

// UNIT=(CART,,DEFER),

// LABEL=(1,SL,RETPD=0)

Print output

//ddname DD SYSOUT=msgclass[,DEST=dest][,COPIES=copies][,OUTLIM=lines]

JES2 cards

Control statements for Job Entry System 2 (JES2) are sometimes required. There are three statements commonly used.

Route card

The route card is normally used to redirect the output of a job from the node that it is executing on to another.

Syntax

/*ROUTE PRINT node

Where

node The machine to receive the output (N12)

XEQ card

The execute (XEQ) card redirects the execution of a job from the node where it was submitted to another.

Syntax

/*XEQ node

Where

node The machine to execute the job (VIC9)

JOBPARM card

The job parameters (JOBPARM) card is used to control JES2 related job parameters. The most useful of these controls the maximum number of lines which can be produced by the job.

Syntax

/*JQBPARM LINES=lines

Where

lines The maximum number of lines, in thousands (10) [10=10,000 lines]

JCL Utilities

IEBGENER / ICEGENER

These utilities copy sequential data sets or PDS members, however ICEGENER is based on DFSORT and executes twice as fast. The input is read from SYSUT1 and can be either a sequential data set or a concatenation of data sets. The output is written to SYSUT2 which must be a sequential data set or PDS member. These utilities can not process an entire partitioned data set, see IEBCOPY to do this.

Example 1: Copy Disk to Disk

//stepname EXEC PGM=ICEGENER

//SYSIN DD DUMMY

//SYSPRINT DD SYSOUT=*

//SYSUT1 DD DSN=dsname,DISP=SHR

//SYSUT2 DD DSN=dsname,DISP=OLD

Example 2: Concatenate many members to one tape data set

//stepname EXEC PGM=ICEGENER

//SYSIN DD DUMMY

//SYSPRINT DD SYSOUT=*

//SYSUT1 DD DSN=dsname(member),DISP=SHR

// DD DSN=dsname(member),DISP=SHR

// DD DSN=dsname(member),DLSP=SHR

//SYSUT2 DD DSN=dsname,

// DISP = (NEW, CATLG, DELETE),

// UNIT= (CART, ,DEFER),

// LABEL=(1 ,SL,RETPD=days),

//………..DCB=(*.SYSUT1)

IEBCOPY

This utility can process entire partitioned data sets at once. It has two main uses: to copy members from one PDS to another, and to compress a PDS. DM5/OS can also be used to compress a PDS.

Example 1: Copy all members from one PDS to another

//stepname EXEC PGM=IEBCOPY

//SYSUT1 DD DSN=dsname,DISP=OLD

//SYSUT2 DD DSN=dsnaine,DISP= OLD

//SYSPRINT DD SYSOUT=*

//SYSIN DD DATA

COPY OUTDD=SYSUT2,INDD=SYSUT1

/*

Note: Any identically named members already existing in SYSUT1 will NOT be copied to SYSUT2. To replace members with the same name use INDD=((SYSUT1,R)).

Example 2: Copy all members from two PDSs to one

//stepname EXEC PGM=IEBCOPY

//INDD1 DD DSN=dsname,DISP=OLD

//INDD2 DD DSN=dsname,DISP=OLD

//OUTDD1 DD DSN=dsname,DISP=OLD

//SYSPRINT DD SYSOUT=*

//SYSIN DD DATA

COPY OUTDD=OUTDD1,INDD=((INDD1,R),(INDD2,R))

/*

Example 3: Copy selected members, with replacement

//stepname EXEC PGM=IEBCOPY

//SYSUT1 DD DSN=dsname,DISP=OLD

//SYSUT2 DD DSN=dsname,DISP=OLD

//SYSPRINT DD SYSOUT=*

//SYSIN DD DATA

COPY OUTDD=SYSUT2,INDD=((SYSUT1,R))

SELECT MEMBER=(member[,member]…)

/*

Example 4: Compress two PDSs

//stepname EXEC PGM=IEBCOPY

//PDS1 DD DSN=dsname,DISP=OLD

//PDS2 DD DSN=dsname,DISP=OLD

//SYSPRINT DD SYSOUT=*

//SYSIN DD DATA

COPY OUTDD=PDS1,INDD=PDS1

COPY OUTDD=PDS2,INDD=PDS2

/*

IDCAMS

IDCAMS is IBM’s Access Method Services utility and has a large number of facilities. This section explains some of the non-VSAM functions, the VSAM functions are explained in a later section.

IDCAMS has three types of useful non—VSAM functions.

• Data sets and PDS members can be renamed or deleted.

• Data sets and PDS members can be dumped to a print file.

• Generation Data Groups (GDG) can be defined or deleted.

Syntax: Data set management

//stepname EXEC PGM=IDCAMS

//SYSPRINT DD SYSOUT=*

//SYSIN DD DATA

DELETE dsname /* delete a data set */

DELETE dsname(member) /* delete a member */

DELETE gdg-base GDG PURGE /* delete a GDG base */

ALTER dsname NEWNAME(dsname) /* rename a data set */

ALTER dsname(member) NEWNAME(dsname(member)) /* rename a member */

LISTCAT ENTRIES(dsname) ALL /* data set information */

/*

Syntax: Dump records from a data set

//stepname EXEC PGM=IDCAMS

//SYSPRINT DD SYSOUT=*

//ddname DD DSN=dsname,DISP=SHR

//SYSIN DD DATA

PRINT INFILE(ddname)

[COUNT(record-count) –

[SKIP(skip-count) -]

[CHARACTER | HEX | DUMP]

/*

Where

Syntax: Create Generation Data Group (GDG)

//stepname EXEC PGM=IDCAMS

//SYSPRINT DD SYSOUT=*

//SYSIN DD DATA

DEFINE GDG (NAME(gdg-base) LIMIT(limit) NOEMPTY SCRATCH)

/*

Where

DFSORT

This utility sorts data sets into the order specified by the FIELDS parameter. The data is sorted from the SORTIN file to the SORTOUT file. You can not sort a data set back to itself. If this is necessary you must sort to a temporary data set and then copy the data back to the original.

Syntax

//stepname EXEC PGM=SORT

//SYSOUT DD SYSOUT=*

//SORTIN DD DSN=dsname,DISP=OLD

//SORTOUT DD DSN=dsname,DISP=OLD

//SYSIN DD DATA

SORT FIELDS=(start,length,CH,order[,…]),

FILESZ=Esize,DYNALLOC=(SYSDA,3)

/*

Where

IKJEFT01 (Batch TSO)

Most TSQ commands can be executed from a batch job by using this utility. Commands will not work if they perform full screen I/O (eg: ISPF). There are some commands that just do not work in this mode, however all of the common commands will work correctly. There is little point using this utility to run programs which can be run in batch directly, such as SAS and Natural.

Syntax

//stepname EXEC PGM=IKJET01

//SYSTSPRT DD SYSOUT=*

//SYSTSIN DD DATA

TSO-commands

/*

JCL Procedures

JCL Procedures perform a similar function to copy books in Cobol. The JCL contained in the procedure library is copied to the job and any parameters are substituted when the procedure is referenced. A number of procedures have been predefined as part of MVS, further procedures have been created to user applications.

Procedures Libraries (PROCLIBs)

In order to use a procedure it must be made available to the job. There are three ways this can occur.

• The procedure is defined in one of the MVS system PROCLIBs, such as SYS1.PROCLIB.

• The procedure is defined in a user PROCLIB which has been made available to the job by a DD statement following the JOB card. This is not part of standard JCL, but is performed by EasyProc which is a third-party enhancement product. There can be more than one user PROCLIB defined, but they all must end with ‘.PROCLIB’. Refer to following examples.

• The procedure is defined as part of the JCL.

The first two types are known as ‘Cataloged Procedures’, while the later type is an ‘Instream Procedure’. Apart from the use of the PEND statement when using Instream Procedures, there are no syntax differences between the two types.

Example 1: Using system procedure

//jobname JOB ‘account code’,‘programmer name’,

// CLASS=class,MSGCLASS=msgclass,

// REGION=4M,MSGLEVEL=(2,0),

// NOTIFY=userid

//*

//stepname EXEC PROC = SAS,

// PARM=’MACRO DQUOTE NOTEXT82′

//SYSIN DD DSN=dsname(member),DISP=SHR

Example 2: Using a user procedure library

//jobname JOB ‘account code’,‘programmer name’,

// CLASS=class,MSGCLASS=msgclass,

// REGION=4M,MSGLEVEL=(2,0),

// NOTIFY=userid

//*

//PROCLIB DD DSN=dsna1ne,DISP=SHR

// DD DSN=dsname,DISP=SHR

//*

//stepname EXEC PROC=procname

Example 3: An Instream procedure

//jobname JOB ‘account code’,‘programmer name’,

// CLASS=class,MSGCLASS=msgclass,

// REGION=4M,MSGLEVEL=(2,0),

// NOTIFY=userid

//*

//procname PROC

//stepname EXEC PGM=program

//ddname DD DSN=dsname,DISP=SHR

//ddname DD SYSOUT=*

// PEND

//*

//stepname EXEC PROC =procname

Symbolic Parameters

Procedures are usually made more general by using symbolic parameters to substitute for common and/or important values within the procedure. Some of the values that can be substituted by symbolic parameters are: Data set names, Member names, Parameters, Unit names, Volume serial numbers, etc. The only item that can not be substituted is the program name on an EXEC card.

Example: Symbolic parameters with a Instream procedure

//jobname JOB ‘account code’,‘programmer name’,

// CLASS=class,MSGCLASS=msgclass,

// REGION=4M,MSGLEVEL=(2,0),

// NOTIFY=userid

//*

//procname PROC DSN=‘dsname’,SYS=‘class’
//stepname EXEC PGM=program

//ddnamel DD DSN=&DSN,DISPSHR

//ddname2 DD SYSOUT=(&SYS)

// PEND

//*

//stepname EXEC PROC=procname,SYS=‘value’

Limitations of Procedures

There are two main limitations when using procedures, nesting and instream data.

A procedure can not refer to another procedure. This mainly caused problems when trying to use system procedures within user procedures. For example, from within a user procedure you can not call the SAS procedure. The solution is to copy the system procedure into the user procedure and edit it to suit. Of course this can cause problems when the system procedure is updated, since those changes may have to be reflected into the user procedure.

A procedure can not contain instream data (ie: DD DATA) This mainly causes problems with control information for utilities such as DFSQRT and IEBCOPY. The solution is to create a data set to contain the control information and refer to the member in the JCL.

Procedure Overrides

Overrides provide a way of changing a procedure for the duration of a job. Any DD statement maybe changed by using overrides, as follows.

Example: Override ddname1

//jobname JOB ‘account code’,‘programmer name’,

// CLASS=class,MSGCLASS=msgclass,

// REGION=4M,MSGLEVEL=(2,0),

// NOTIFY=userid

//*

//procname PROC

//procstep EXEC PGM=program

//ddnamel DD DSN=dSname,DISPSHR

//ddname2 DD SYSOUT=*

// PEND

//*

//stepname EXEC PROC=procname

//procstep.ddname1 DD DSN=dsname,DJSP SHR

Resources

Website

https://paulshipley.id.au

Reference

The following references provide more detailed information and definitions about MVS JCL.

Practical MVS JCL For Today’s Programmer, James G. Janossy, 1987, John Wiley & Sons Inc, ISBN 0-471-83648-6

MVS/Extended Architecture JCL Reference, International Business Machines Corporation, 1985-1989, GC28-1352-4

MVS/Extended Architecture JCL User’s Guide, International Business Machines Corporation, 1985-1989, GC28-1351-4

The following references provide information about utilities and other facilities.

Janossy, Ch 17 JCL Tools: Compiler, Sort, VSAM, And Utility JCL

MVS/Extended Architecture Data Administration:Utilities, International Business Machines Corporation, 1982-1984, GC26-4018-1

SAS Companion for the MVS Environment, Version 6, SAS Institute Inc, 1990, ISBN 1-55544-398-2

The following references provide information about system abends and messages.

Janossy, Appendix F System Completion Codes and Subcodes

MVS/Extended Architecture Message Library: System Codes, International Business Machines Corporation,1982-1986, GC28-1157-4

MVS/Extended Architecture Message Library: System Messages Volume 1 ADY-IEB, International Business Machines Corporation, 1982-1989, GC28-1376-7

MVS/Extended Architecture Message Library: System Messages Volume 2 IEC-ITV, International Business Machines Corporation, 1982-1989, GC28-1377-7

The following references provide information about Virtual Storage Access Method (VSAM).

Janossy, Chapter 11 AMP: Access Method (VSAM) Parameter

Practical VSAM for Today’s Programmers, James G. Janossy & Richard E. Guzik, 1988, John Wiley & Sons, ISBN 0-471-85107-8

About the author

Paul Shipley has been a software developer for over twenty years and has done a bit of just about everything. He is a co-author of Photoshop Elements 2: Zero to Hero (ISBN 1 904344 23 2).

— End of Document —