Notes on JCL Introduction

Notes on JCL -- Introduction

JCL, or "Job Control Language", is the mini-language used to communicate with MVS. With JCL, we specify which programs to execute, and in what order, and we list the data sets and other facilities used

by each. We can request resources (time, memory, disk space), and we

can place conditions on the execution at each step.

The JCL taught in this course is oriented to JCL as used at

N.I.U. There may be minor differences between our JCL and the JCL

used at other installations. For instance, names of libraries and JCL

procedures and group names used with the UNIT parameter of the DD

statement may vary somewhat from site to site.

In particular, we may not be using SMS ("Storage Management Subsystem"). If we were using SMS, we would be studying and using a

somewhat different collection of parameters for DD statements. With

SMS installed, essentially all data sets are automatically catalogued.

------

JCL is written in 80-column lines; the length and the format are

holdovers from punch-card days. (It is common to refer to JCL

statements as "cards".) There are only a few major kinds of JCL

statements:

//jobname JOB ,...... one per job, beginning it

//[stepname] EXEC ...... one per step

//ddname DD ...... many

// null, one ending the job

//* comment line

/* delimiter; has other formats

//[name] PROC used in defining procedures

//[name] PEND used in defining procedures

//[name] JCLLIB used in calling procedures

(and some minor ones: SET, IF, INCLUDE, etc.; and some major ones

we do not discuss in this course: CNTL, ENDCNTL, OUTPUT, etc.).

We also sometimes use a JES2 statement, JOBPARM:

/*JOBPARM ...

Here JES2 is version 2 of JES, or "Job Entry System". N.I.U. uses

JES2, but JES3 is also out and in use. (JES2 and JES3 are apparently

intended for different system configurations.) Some JES statements

are included in the JCL manuals.

There are many more options available in JCL than we cover in

detail in this course. (In many cases, these are old options which

have been retained for backwards compatibility.) For information on

JCL, consult the course notes and (especially) the JCL Language

Reference and the JCL Programming Guide.

We do not use columns 73-80. These were formerly used for

sequence numbers on punched cards.

Column 72 is used only to indicate the continuation of an

interrupted parameter to the next line. At the end of a complete parameter, all that is needed to continue the statement to the next line is the comma that separates it from the next parameter. The continuation on the next line begins anywhere in columns 4 through 16. Occasionally, though, we may need to break a parameter (perhaps a long DSN or PARM) in its middle. If so: be sure column 71 does not contain an apostrophe, and continue the parameter in column 16 of the next line.

For example:

//S1 EXEC PGM=IEFBR14,PARM='This is a long parameter within apost

// rophes, continued in column 16 of the next line.'

Comment lines begin with //* and the comments can use columns

4-80. In addition, comments can be put on any line by skipping at

least one space after the end of the statement on that line. (The

latter is not recommended.)

The last line in a job is a "null statement", which has // in

columns 1 and 2 and is otherwise blank. Anything following it is

ignored until the next JOB statement is encountered.

JCL is written primarily in upper-case letters, but lower-case

can be used in comments, in the user name on the JOB statement, etc.

In general a job is organized as follows:

//jobname JOB ,......

(possibly a /*JOBPARM statement)

(possibly a // JCLLIB statement)

(possibly a //JOBLIB DD statement)

//* (probably some comments)

//stepname1 EXEC ......

// (various DDs for the step)

//* (probably some comments)

// (probably more of the same)

There can be as many as 255 steps in a job. Note: a step may

call a procedure which itself may have steps. The limit of 255 steps

includes steps of procedures.

Names of steps, job, etc., are usually 1-8 characters long,

using (upper case) alphabetic, numeric or national ($, @, #)

characters, and not beginning with a numeral.

The output produced when a job is run includes various kinds of

overhead output, such as the JES job log, a listing of statement

images (included the expanded forms of procedures) and system messages. All of this precedes the output produced by each step.

Notes on JCL -- JOB statement

Each job to be run on MVS begins with a JOB statement:

//jobname JOB ,'user name'[,optional keyword parameters] comments

Here "jobname" is a name for the job: 1 to 8 characters,

alphanumeric or national ($, @, #), not beginning with a numeral.

This is a required positional parameter that starts in column 3.

In N.I.U.'s CSCI courses, the job name is of the form

"KCnumberX" where X is a letter.

The space before the comma after JOB represents accounting

information which is omitted at N.I.U. (at least in CSCI courses).

The "user name" is 1 to 20 characters long; if it contains an

apostrophe, use 2 apostrophes, as in 'O''DONNELL'. This is a

positional parameter and is required at N.I.U.

Optional keyword parameters are separated by commas.

------

TIME parameter:

TIME=(m,s)

TIME=m

This is the estimated maximum time for the entire job to run,

"m" minutes and "s" seconds, where m is between 1 and 1439 and s is

between 0 and 59.

Notice that we can code TIME=(0,5) as TIME=(,5), and we can code TIME=(3,0) asTIME=3.

If we code TIME=0, results are unpredictable. If we code

TIME=1440, which literally amounts to 24 hours, we are asking to use

the processor for an unlimited amount of time. Avoid both of these

extremes.

There is normally a default value for TIME.

Note: We may also have TIME on EXEC statements.

REGION parameter:

REGION=nK

REGION=nM

This is the amount of space (memory, not disk space) needed for

the entire job, measured in kilobytes (K) or megabytes (M). At any installation, there should bea default value for REGION.

It is useful to remember that this does not by itself allocate

any memory; it requests a maximum amount. The programs being executed

must be loaded into memory as part of this total, and may request

memory dynamically (using GETMAIN, etc.).

With REGION=nK, "n" should be a multiple of 4; otherwise it is

rounded up to the next multiple of 4. "n" is limited to values 1

through 2097128.

With REGION=nM, "n" is limited to values 1 through 2047.

Obviously, we cannot request more space than is available. With

"n" = 0, we are requesting all available space and the results are

unpredictable.

Note: We may also have REGION on EXEC statements.

------

COND parameter:

COND=(m,operator)

COND=((m1,operator1),(m2,operator2)[,etc.])

Here "m" is a value, 0 through 4095, and "operator" is one of the

following:

GT greater than

GE greater than or equal to

EQ equal to

NE not equal to

LT less than

LE less than or equal to

Each step in a job has a return code (RC) value, 0 to 4095. If

the RC from any step in the job satisfies the test specified in COND,

the job terminates at that point. A trick for remembering this is

"If it's true, then we're through."

Example: COND=(16,LT)

Here the job will terminate if any step has a return code greater

than 16.

We can have a compound test; the separate tests are combined with

"OR".

Example: COND=((143,EQ),(259,EQ))

This means that if any step has RC = 143 or 259, then the job

terminates.

Note: We may also have COND on EXEC statements, and it is much

more common to do so. If we have a COND on both the JOB statement and

on an EXEC statement, then either may terminate the step. If the JOB

COND is satisfied by the return code from a step, then all subsequent

steps are canceled and the job ends. If the JOB COND is not satisfied

but the EXEC COND is satisfied, then that step is canceled and

subsequent steps may still occur.

------

MSGCLASS parameter:

MSGCLASS=class

Here "class" is one character, A through Z or 0 through 9.

This assigns the job log to an output class.

At N.I.U., this is assigned automatically as a default:

U for output sent to the terminal (as a Jnnnn.X file), or

A for output sent to the printer.

------

MSGLEVEL parameter:

MSGLEVEL=([statements][,messages])

This indicates what information is put into the job log.

Here "statements" may be

0 -- only the JOB statement

1 -- all JCL and procedure statements

2 -- only JCL statements

and "messages" may be

0 -- only JCL messages

1 -- JCL, JES and operator messages

At N.I.U., this is assigned automatically as a default.

------

TYPRUN parameter:

TYPRUN=SCAN

This will cause the system to scan the JCL for syntax errors

without executing it or allocating resources. It is not guaranteed to catch all possible errors. (For instance, perhaps a job requestsmore space, or more contiguous space, than is available on a givenoccasion. This cannot be detected in advance of trying to fulfill the

request.)

TYPRUN has other options as well.

------

Concluding notes:

There are more optional keyword parameters for the JOB statement,

such as CLASS (assigning the job to a jop class) and RESTART (restart

a job--presumaby ABENDED--at a given step, presumably after correcting

whatever went wrong in the previous attempt. There is no need to

worry about these at present.

Notes on JCL -- EXEC statement

Each step in a job begins with an EXEC statement, which requests

the execution of either a program (load module) or a JCL procedure.

//stepname EXEC PGM=programname[,optional keyword parameters]

//stepname EXEC PROC=procname

//stepname EXEC procname

Here "stepname" is a name for the step: 1 to 8 characters,

alphanumeric or national ($, @, #), not beginning with a numeral.

This is a required positional parameter that starts in column 3.

The name of the program or procedure is also 1 to 8 characters,

alphanumeric or national ($, @, #), not beginning with a numeral.

Optional keyword parameters are separated by commas.

------

TIME parameter:

TIME=(m,s)

TIME=m

This is the estimated maximum time for the entire job to run,

"m" minutes and "s" seconds, where m is between 1 and 1439 and s is

between 0 and 59.

If we code TIME=0, results are unpredictable. If we code

TIME=1440, which literally amounts to 24 hours, we are asking to use

the processor for an unlimited amount of time. Avoid both of these

extremes.

Note: We may also have TIME on the JOB statement, which will

override the TIME limit on any EXEC statements.

------

REGION parameter:

REGION=nK

REGION=nM

This is the amount of space (memory, not disk space) needed for

the entire job, measured in kilobytes (K) or megabytes (M). The

default at N.I.U. is REGION=128K. At any installation, there should bea default.

It is useful to remember that this does not by itself allocate

any memory; it requests a maximum amount. The programs being executed

must be loaded into memory as part of this total, and may request

memory dynamically (using GETMAIN, etc.).

With REGION=nK, "n" should be a multiple of 4; otherwise it is

rounded up to the next multiple of 4. "n" is limited to values 1

through 2097128.

With REGION=nM, "n" is limited to values 1 through 2047.

Obviously, we cannot request more space than is available. With

"n" = 0, we are requesting all available space and the results are

unpredictable.

Note: We may also have a REGION on the JOB statement, which will

override the REGION limit on any EXEC statements. It may be better to

specify it on each step, as the REGION for the whole job must be as

large as the largest REGION needed by any step, and that amount would

then be reserved for the entire duration of the job.

------

COND parameter:

COND=(m,operator,stepname)

COND=(m,operator,stepname.procstepname)

COND=(m,operator)

COND=((m1,operator1,stepname1),(m2,operator2,stepname2)[,etc.])

COND=ONLY

COND=EVEN

In the second case above, we are referring to the return code of

a step within a procedure which is called in an earlier job step. For

instance, if STEP3 calls IGYWCG, which has a GO step, we could have

COND=(0,LT,STEP3.GO).

Here "m" is a value, 0 through 4095, and "operator" is one of the

following:

GT greater than

GE greater than or equal to

EQ equal to

NE not equal to

LT less than

LE less than or equal to

Each step in a job has a return code (RC) value, 0 to 4095.

(Normally lower values are considered better.) If the RC from any

step in the job satisfies the test specified in COND in the following

step's EXEC statement, then the following step is bypassed. The job

may continue if there are more steps.

A trick for remembering this is "If it's true, then we're

through." Remember that the test is a test for whether to stop;

the default action is to go ahead and execute the step.

We can have a compound test; the separate tests are combined

with "OR". Notice that this is a serious limitation on the flow of

control in JCL; not all compound conditions can be used with COND.

Example: Suppose STEP3 has COND=((143,EQ,STEP1),(259,EQ,STEP2)).

This means that if STEP1 has RC = 143 or STEP2 has RC = 259, then

STEP3 is skipped.

There can be up to 8 tests (counting EVEN or ONLY). Use the

outer parentheses if more than one test is involved.

If "stepname" is omitted, then the test applies to the return

code from all previous steps. Thus COND=(4,LT) means that the step

will be skipped if any previous step has RC = 5 or more.

COND=ONLY means that the step will be executed only if a

previous step ABENDed.

COND=EVEN means that the step will be executed even if a previous

step terminated abnormally. This is equivalent to COND=(0,GT).

Example: Suppose STEP6 has COND=((4,LT,STEP1),(8,LT),ONLY). Then

STEP6 will be skipped if STEP1 had RC = 5 or more, or if any previous

step had RC = 9 or more, or if any previous step ABENDed.

If a COND refers to a previous step which was bypassed, then the

test involving that step is not performed.

A COND on the first step in the job is meaningless unless it is

COND=ONLY, in which case that step will not be executed.

If no COND is coded, the step is executed, by default, but if

a step ABENDs, the subsequent steps will not be executed unless

COND=EVEN has been coded.

As a procedure may have more than one step itself, we may need

to specify both, as in this example: If STEP2 calls a procedure

which has steps COB and LOAD, then STEP3 might have a COND such as

COND=(4,LT,STEP2.COB).

Note: We may also have COND on the JOB statement, although it is not especially common to do so. If we have a COND on both theJOB statement and on an EXEC statement, then either may terminatethe step. If the JOB COND is satisfied by the return code from astep, then all subsequent steps are canceled and the job ends. Ifthe JOB COND is not satisfied but the EXEC COND is satisfied, thenthat step is canceled and subsequent steps may still occur.

Note: The most recent version of JCL includes an IF-THEN-ELSE

structure to enrich the programmer's control of job flow.

Note: If a step terminates before the program involved has

control--during space allocation or scheduling, for instance--or if it

is canceled by the operator, then it is possible or likely that

subsequent job steps will not be executed, regardless of CONDs.

------

PARM parameter:

PARM='string'

PARM=(string)

PARM=string

PARM=&SymbolicParameter

PARM is used to pass information to the program being executed

by this step. If the step executes a procedure containing several

steps, we may have PARM.procstepname='string', etc. The default is

a null string.

The information to be passed must not be more than 100

characters; notice that this may require continuation to the next line,breaking at a comma and enclosing with parentheses. The 100 characters do not include the enclosing parentheses or apostrophes.

Enclosing parentheses or apostrophes are not always needed.

Examples: PARM='ABC,125,George'

PARM=(ABC,125,George)

PARM=(O''Brien,732,'A&B')

PARM=MAP

The string may contain several expressions separated by commas;

the commas are included in the 100 character limit.

The string provided in PARM is passed to the called program.

Accessing it depends on the language in use; in general, we have a

binary numeric field (the length of the string) and the address of

the string itself, i.e., a copy of it stored in memory.

In executing a COBOL program, we may have both user parameters

(to go to our called COBOL program) and run-time parameters (to be

used by SCEERUN, which is linked to it). The format for this is:

PARM='User Parameters/Run-time Parameters'

Notice the slash in the middle.

If we had no user parameters, we could have:

PARM='/Run-time Parameters'

An example of a run-time parameter is TERMTHDACT(DUMP).

If we are using the LOADER, we might have even more:

PARM='Loader parameters/User Parameters/Run-Time Parameters'

------

Concluding note:

There are more optional keyword parameters for the EXEC state-

ment.

Notes on JCL -- DD statement

Each step in a job may contain a number of DD statements.

//DDname DD *

//DDname DD DATA,DLM=xy

//DDname DD SYSOUT=class

//DDname DD [various parameters]

Here "DDname" is a name for the data set: 1 to 8 characters,

alphanumeric or national ($, @, #), not beginning with a numeral.

This is a required positional parameter that starts in column 3.

Various DDnames have special meanings and should be avoided.

Three of the above formats are specialized:

(1) DD * is used to indicate in-stream data in 80-column lines,

terminated by a line starting /*.

Example:

//INFILE DD *

This is a line of data.

So is this one.

(2) DD DATA,DLM=xy is similar but is used when the in-stream data

may include JCL lines beginning with // or /*. "DLM=xy" means that

the in-stream data will be terminated by two characters xy in

columns 1 and 2. If the two characters are at all unusual, they

may be enclosed in quotation marks, as in DLM='xy'.

Example:

//INFILE DD DATA DLM=HH

//This is a line of data starting with //.

/*So is this one, starting with /*.

One common place to use DD DATA is in the JCL for the C compiler,

as C code may (and should) contain comment lines beginning with /*.

If we have in-stream data that contains lines starting with /*

but not //, we can use DD DATA without a delimiter. The in-stream