2. JCL Syntax

Syntax Rules

General JCL command format

//name operation parameter1,parameter2 Comments

where;
name : is not to exceed 8 characters
operation : generally begins in column 12
parameter : generally begins in column 17
comments : are separated from the parameters by a blank

Parameters are broadly classified into 2 categories viz. Positional and Keyword.

A positional parameter is identified by its position relative to other parameters in the operand field.

Rule 1 : All positional parameters are coded first in the operand field and in their proper sequence.

e.g. : p1,p2,p3
p1,p3,p2 illegal because they are not in sequence.

A keyword parameter is identified by a keyword followed by an equal sign (=) and variable information.

Rule 2 : A keyword parameter follows positional parameter and can be coded in any order.

e.g. : p1,p2,p3,k1=,k2=,k3=
p1,p2,p2,k3=,k2=,k1=

Both are valid.

Note : All parameters are separated by commas with no intervening spaces.

Rule 3 : The absence of positional parameter is noted by a comma(,) coded in its place, except for the last or remainder of the positional parameter are not present. The placeholder commas do not need to be coded.

e.g. : p1,,p3,k1=,k2=,k3= place holder comma required
p1,k1=,k2=,k3=

Rule 4 : Both positional parameters and variable information for keyword parameters may be composed of subparameters. The subparameters may be either positional or keyword. Subparameters must be coded as a list. The list must be enclosed in paranthesis unless only one subparameter is coded. When only one subparameter is coded the paranthesis are optional.

e.g : p1,(sp1,sp2),p3,k1=(sk1,sk2),k2=,k3=
p1,(sp1),p3,k1=(sk1),k2=,k3=
or p1,sp1,p3,k1=sk1,k2=,k3=

Rules for continuation : The JCL statement can be continued in a simple way. The statement must be interrupted at a comma. This means that the last valid character of the line must be a comma followed by atleast one blank. Then the statement can be continued into the next line by coding two slashes at the beginning of the line and continuing the parameter field starting anywhere between positions 4 and 16 (4 and 16 included). Note that the comma which indicates continuation, is not an extraneous character but part of the statement.


//dd1 dd dsn=da0001t.empfile,disp=(new,catalg,delete),
// unit=sysda,space=(trk,(5,1)),dcb=(lrecl=80,recfm=fb,blksize=800)
//dd1 dd dsn=da0001t.empfile,disp=(new,catalg,delete),
// unit=sysda,space=(trk,(5,
// 1)),dcb=(lrecl=80,recfm=fb,blksize=800)
//



Eg. 2.1 Examples of valid continuation

Job Statement

The job statement identifies job to the O/S with the job name operand.

The format of the JOB statement is :

//jobname JOB parameters

Note that jobname cannot exceed 8 characters and is usually the userid (loginid)

//da0001ta JOB parameters

Loginid is generally 7 characters, so you need to add a suffix lest the system prompts you to enter the character when a job is submitted to the system for execution.

When a job is submitted to the system, a job number is also assigned so that the job can be further identified. This way jobs with the same name can be uniquely identified. Jobs with the same name cannot execute simultaneously. If several jobs with the same name are submitted they execute sequentially even if additional jobs could be executing. Jobs waiting to run because of this time conflict are shown in hold status.

Remark : 1 A JOB statement must be at the beginning of every job submitted to the system for execution.
2 A JOB statement must have a name. The absence of a jobname will result in a JCL error.

The rest of the JOB statement contains postional parameters followed by keyword.

Accounting Information parameter :

It is a positional parameter. If present (it normally is), it must be the first in the parameter field. It can have a maximum of 142 characters (including parenthesis and commas but not apostrophes) . It is used to tie the resources used by the job to the appropriate account.

//jobname JOB ([account-number][,additional-accounting-information]),parameters

The account-number is an alphanumeric field from 1 to 4 characters long (many installations permit the use of more than 4 characters.

Additional-accounting-information is installation dependent. Many of the fields are not very important and are not often used. Note that except for the account number, all other subparameters can be supplied through the /*JOBPARM JES2 control statement. (JES2 control statements are not covered in this book, refer to IBM Manual.

e.g :
//da0001ta JOB LA2719,parameters

LA2719 is the account number for the training dept. This varies from project to project. Therefore, consult the right person.

If any portion of the field contains a special character other than a “,” (comma) or a “-“ (hyphen), the portion must be enclosed in apostrophes. If an ampersand or quotes is used in the accounting field, code two consecutive ampersands or quotes.

e.g. :1

//da0001ta JOB ‘LA2719,TRG’
or //da0001ta JOB (LA2719,TRG)

e.g. :2

//da0001ta JOB (LA2719,’P&&G’)

The system assumes a single ampersand.




Remark: An installation has the option of making the account number mandatory and most installations do. If so, its absence will cause a JCL error.

If the account number is incorrectly specified, in this case its not JCL error. However when job is submitted to the system for execution, we get the message JOB NOT RUN in the sysout.

Programmer’s Name :

Following the accounting information parameter, another positional parameter, the programmer’s name can be coded. The installation determines if this parameter is required or not. If required, it must be coded immediately after the accounting information, and its omission will cause a JCL error. The programmer’s name cannot exceed 20 characters. If it contains any special characters other than a hyphen and a period in the middle or the beginning (but not at the end) of the name, the name must be enclosed in apostrophes. The apostrophes are not added to the length of the name. If a name contains an apostrophe (e.g., D’COSTA), two apostrophes must be coded. They count as one character in the length of the name.

e.g. : 1

//da0001ta JOB LA2719,Pai,parameters

e.g. : 2

//da0001ta JOB LA2719,’D’’COSTA’,parameters

Note : Accounting information and Programmer’s name are the only two positional parameters in the JOB statement, what follows after that are keyword parameters.


MSGLEVEL parameter :

This parameter specifies whether the submitted JCL and/or JCL-related messages should be shown on the job’s output.

General syntax

MSGLEVEL=([jcl][,messages]) Keyword parameter
Jcl - 0, 1, or 2

0 - only the JOB statement will be shown
1 - All JCL will be shown
• instream
• expanded cataloged procedures
• symbolic parameter substitutions
2 - All JCL will be shown, but not expanded procedure listing.

Messages – 0 or 1
0 - No messages will be shown i.e information about step completion.
1 – All messages will be shown viz allocation and termination messages.
The messages subparameter can be thought of as On (1) or Off (0) .

Remark:

1. If the entire parameter or either of the two fields is omitted, an installation-defined default is assumed.
MSGLEVEL=1 ------------------MSGLEVEL=(1,default)
MSGLEVEL=(,1) ------------------MSGLEVEL=(default,1)
Parameter omitted ------------------ MSGLEVEL=(default,default)

2. If the job encounter an ABEND failure, the second field always defaults to 1 even if coded as 0

TheMSGCLASS parameter :

This parameter assigns a sysout class to the Job log. The job log consists of what is what is known as system or JES datasets:
• JES2 or JES3 log
• JCL and its associated messages
• Allocation and Termination messages

MSGCLASS - indicates the format of output
- specifies output class for
job log (collection of all operations)
list (collection of all printed output like compiled listing)

General Syntax

MSGCLASS=class Keyword parameter
Class - A character from A to Z or a number from 0 to 9 (in all 36 classes)

MSGLEVEL parameter indicates whether or not one wishes to print the JCL statements and allocation messages. The MSGLEVEL can save paper. After a job is debugged, there may be no need to print all the JCL and allocation messages each time it runs. To reduce printing to a minimum, one may wish to MSGLEVEL=(0,0).

All datasets to be printed must have a class. This is normally called the output class, sysout class or message class. Sysout datasets created by the executing programs are assigned a class by the SYSOUT DISTINCT statement. After the job terminates, the sysout datasets, which are saved on the spool pack , will be selected and printed by a JES2 or JES3 component called a printer. There are several printers available, and each one is assigned one or more sysout classes (from 1 t0 36). The sysout class can be thought of as a print-scheduling class.

Remark : If the MSGCLASS parameter is omitted, an installation-defined default will be used.

The Class Parameter :

This parameter assigns a class to a job.

General Syntax

CLASS=jobclass Keyword parameter
Jobclass – A letter from A to Z or a number from 0 to 9 ( in all 36 classes)

The jobclass affects job’s processing in these ways :
• When job is submitted, it is placed in an input queue where it waits to be executed. Queues can be thought of as waiting lines for jobs. Each job class has its own input queue
• Job waits in the input queue until it is selected by an initiator to be processed. Each initiator is set to a list of job classes that it can select from.

Simply put Jobclass identifies the nature of the job
- short running or long running
- resource utilization

Each installation group jobs that have like characterstics into classes. By segregrating jobs with similar characterstics, an installation can maintain a good mix of the jobs running at a given moment. This maintains system throughput and efficient use of resources.

Let us look at the sample table below

Class Code Run Time (in minutes) Tape Disk Production Test
1 5 X X X
2 >5 X X X
A 5 X X X
B <5 X X X
C >5 X X X

Table 2.1

In the sample table, the job classes were separated by
- Production vs Test
- Tape vs disk
- expected run time

The example shows some of the characteristics an installation may look at, but certainly not all. Also, resources used by a job may be critical at one installation, but not at another. What is important is that one should follow installation’s standard.




For e.g. Suppose the default Class is A

This Job statement
//DA0001TA JOB LA2719,PCS,MSGCLASS=A,MSGLEVEL=(1,1)

is equivalent to
//DA0001TA JOB LA2719,PCS,MSGCLASS=A,MSGLEVEL=(1,1),CLASS=A

Remark :
Frequently, installations develop a testing class structure that favors short-running jobs with minimal resource requirements and penalize long-running jobs with heavy resource demands. This is achieved by assigning the class used by trivial jobs to many initiators and class used by heavy jobs to few. To keep people honest, the CLASS parameter in a testing environment is often tied to several other parameters such as TIME,PRTY, REGION, etc. For example, a job coding CLASS=A can be given TIME=(0,5),PRTY=6. Note that the values assigned to these parameters is not shown in the output. However, if any of these parameters were coded in the JOB statement, they would be ignored.

Most installation assigns a default job class if the Class parameter is omitted.

The PRTY parameter

This parameter determines the scheduling priority of a job in relation to other jobs in the job input queue of the same class.

General Syntax

PRTY=priorty - keyword parameter
Priorty – a number from 0 to 15 for JES2 or 0 to 14 for JES3

The PRTY parameter is used to define the job’s input class selection priority :
• The higher the number, the better (greater) the priority
• The PRTY parameter simply controls the job’s position in the input queue. It has no affect on the job’s performance.
• Jobs with higher priorities will be selected before job’s will lower priority
• A job’s priority does not affect its performance. Once the job is selected for execution, the priority function is finished.
• Two jobs having same job class and same priority will be executed in sequence

Comparing the PRTY parameter of two jobs belonging to different classes is meaningless.

Remark :
This parameter is of seldom use in a testing environment. Since high priorty would be used by practically all users negating the very purpose the parameter,. Therefore, in most installation the PRTY, whether coded or not, will default to an installation-defined value or will be supplied by the CLASS parameter.


The TIME Parameter

This parameter specifies the total amount of CPU time that all steps in a job can use collectively.

General Syntax

TIME=([minutes][,seconds] | [1440]) keyword parameter

minutes - a number from 1 to 1439
seconds - a number from 1 to 59
1440 - The job will not be timed for CPU. It was also not “time out” (S522 ABEND failure) when a single wait state exceeds the installation-defined limit (often 10 to 20 minutes). Note that TIME=1440 is rarely used, and most installation disallow its use in a testing environment. TIME=1440 should be used by an on-line system like CICS OR ADS/O.

When the TIME parameter is omitted, an installation-defined default will be used. This default is usually very high and unlikely to cause an S322 ABEND failure unless the program goes into an endless loop.

If the TIME parameter is also coded in the JOB statement, both will be in effect and either can cause a S322 ABEND failure. It is not advisable to use them both.

CPU time is the amount of time that the computer devoted to the job after it was selected for processing. It is not the amount of time it was in the machine.

TIME parameter puts an upper limit on the amount of CPU time that a job may use.
e.g : TIME=(3,20).

All the steps in the job are allowed collectively 3 minutes and 20 seconds of CPU time. If this amount is exceeded, the result will be a S322 ABEND failure.

If the TIME parameter is coded using only minutes, seconds defaults to zero. For example, TIME=5 is the same as TIME=(6,0).

If the TIME parameter is coded using only seconds, minutes defaults to zero. For example, TIME=(,6) is the same as TIME=(0,6).

The TIME parameter is intended almost exclusively for a testing environment and should be coded to preempt the program going into CPU loop.

The TIME parameter can also be supplied by the CLASS parameter. When the TIME parameter is omitted and the CLASS parameter does not supply it, the job will not be timed for CPU time. However each step will be individually timed (TIME parameter at EXEC statement or its installation-defined default), unless it contains TIME=1440.

Remark:
It is possible for a job to get more CPU time than that is specified in the TIME parameter by a maximum 10.5 seconds. This is due to the fact that the system checks for violations every 10.5 seconds.



The REGION parameter

This parameter specifies the limit of available storage for each of the steps in the job within the job’s address space. i.e., the amount of storage the job is allocated. Or, in other words, it specfies the amount of storage needed by the step (within the job) with the highest storage requirements.

General Syntax

REGION=value{K|M} keyword parameter
Value – 1 to 2096128 if K (1024 bytes) is used. It should be an even number, it will be rounded to the next higher even number.

Value – 1 to 2047 if M (1024K or 1048576 bytes) is used. M is not available to MVS/SP, only to MVS/XA and MVS/ESA

When a job is selected by an initiator for execution, it is given an address space of 16 MB ( minus what MVS/SP uses) .Incase of MVS/XA, job is given an address space of 2GB. And all of it is available to the job’s steps. However a step normally requires only a small fraction of this huge storage, below the 16M line. An ordinary COBOL or any other language program seldom needs more than 1000k. This is normally what the value in the REGION parameter represents in the installations. Few jobs like CICS, IMS, DB2 need storage above the 16M line. An ordinary batch job seldom has such high requirements and, as a result confined to storage below the 16M line. Storage availability below this line varies in different installations, but is generally around 8MB in MVS/SP and around 9 MB in MVS/XA. Storage above the 16M line can be acquired by coding a value higher than 16M. However, it may be restricted by the installation to only those jobs that need it.

E.g 1.
Assume REGION=1000K was coded in the JOB statement. All the steps in the job are limited to this value. If more storage is needed, the usual result is S878 or S80A or S804 ABEND failure. If one of these failures occurs, the user must increase the value in the REGION parameter.

E.g 2.
REGION=10M
When the amount of storage requested in the REGION parameter is higher than the address space can provide, an S822 ABEND failure will result.

Note that for job run under MVS/SP, the entire address space is limited to 16M, of which usually less than 8M is available to the user. In case of MVS/XA, the entire address space is limited to 2G, of which usually around 9M is available to the user.

E.g 3.
REGION=0K (or 0M) is coded the entire address space except for those areas used by MVS/SP (or MVS/XA) is available.

The ADDRSPC parameter

This parameter specifies if the job will use real or virtual storage.

General syntax

ADDRSPC={VIRT|REAL}
VIRT – The REGION will be virtual storage and is the default
REAL – The REGION will be real storage.

Remark:
This is the rarely used parameter because of the default. Note that ADDRSPC=REAL is a parameter that is disallowed in practically all installation because it can cause serious performance problems for other jobs.

The NOTIFY parameter

This parameter informs a TSO user when his or his job terminates.

General Syntax

NOTIFY=userid keyword parameter
Userid – A name from 1 to 7 character, identifying a valid TSO user.

E.g NOTIFY=DA0001T

If coded, a message will appear on the user’s TSO terminal indicating if the job abended or got a JCL error. If the job terminates while the user was logged off, the message will appear when the user logs on. If the NOTIFY parameter is omitted, no message will appear when the job terminates.

Remark :
You can also code NOTIFY=&SYSUID instead of your userid.

The RESTART parameter

This parameter requests that a job begin its execution with a step other than the first one.

General Syntax

RESTART={stepname|procexec.stepname| *} keyword parameter

Stepname – The name of the step where execution is to begin.
Procexec.stepname – The name of the EXEC statement invoking a procedure and the name of the step within the procedure where execution is to begin

Note : Procedures will be covered on day 4.

* - indicates that execution of the job is to begin with the first step and is the default.

Things to avoid :
• Duplicate name for EXEC statements invoking procedure. If RESTART=procsexec.stepname is used, the first procexec found will be used.
• Duplicate stepnames within procedure. If RESTART=procsexec.stepname is used, the first stepname within procexec found will be used.
• Duplicate stepnames. If RESTART=stepname is used, the first stepname found will be used.
• EXEC statements (invoking procedures or any step) without names. No restart is possible
• Creating and passing temporary datasets. Such datasets are always deleted by the time the job terminates and, therfore unavailable for restarting.
• Creating and passing nontemporary datasets. If such a dataset is not received and assigned a permanent disposition, Job Termination will delete it, making restart impossible


The TYPRUN parameter

This parameter requests special processing for the job.

General Syntax

TYPRUN={HOLD|JCLHOLD|SCAN|COPY} keyword parameter

HOLD - Job will held (and not executed temporarily) until the operator uses a command to release. A job will be held in the input queue only if syntactically correct
JCLHOLD (JES2 only) – Job will held (and not executed) until the operator uses a command to release it. Note the job will be held in queue if it is syntactically incorrect. Rarely used

SCAN – Job will be scanned for all syntactical JCL errors but will not execute.

COPY (JES2 only)- Job will be printed. No execution and no syntax checking takes place. Rarely used.

Back to JCL Index
Back to home page