Return 16

JCL is a staple language for Systems Programmers, and arguably the most important part of any JCL is the job card – we can’t run a JCL without one.

The reason a lot of people call it a ‘Job card’ (you might also hear other terms like Job statement) is because MVS programming used to be done on punch cards. If you’ve never heard of a punch card, IBM has a nice history lesson on them.

To have a valid job card, you need at minimum a job name and the JOB keyword. That would look something like this:

//SAMPJOB JOB

But that gives us and JES absolutely no information about the job, which is where the positional and keyword parameters come in. They can be used to provide extra information such as the account that is running the job, who to notify upon job completion, what initiator class the job should use, and many other options [1]. A more realistic job card would be something like this:

//JOBNUM1 JOB 504,SMITH PAYROLL,
//        CLASS=X, NOTIFY=&SYSUID,
//        REGION=0M

After the job statement, there are two positional parameters: Job accounting information (in our example, that is 504) and the programmer name field (in our example, SMITH PAYROLL). These positional parameters are not required unless your site has made it a rule.
Then, we get to the Keyword parameters. Unlike the positional, these keyword parameters can go in any order because they all start with ‘keyword=’ and value is provided after. The most commonly used keyword parameters are:

CLASS – which JES initiator class the job should run under. Available initiators can be checked by going to the SDSF INIT panel. Sites usually assign initiators to specific batches- for example, class L might be for long-running jobs or class O might be for overnight jobs. Check with someone at your site if you’re unsure what your classes are for.

MSGCLASS – where the job output is printed to. Every system should have a class A by default, which points to the JES spool. If your site has other printers set up you may want to code in a different value.

MSGLEVEL – the amount of detail in the job output. E.g., MSGLEVEL=(N1,N2). N1 can be a value from 0-2 and N2 can be a value from 0-1 where the higher the number you specify the more detail is provided. More about what exactly these values print can be found here. The system default is (1,1).

NOTIFY – the UID to notify with a TSO interrupt on job completion or failure this can be hardcoded, e.g., NOTIFY=TSOUSR1 or the &SYSUID variable can be used like in the above example. &SYSUID will substitute in the UID of the user that submits the job.

REGION – the amount of central or virtual storage your job can use. Often, you will see REGION=0M which means the job is allowed to use as much storage as it needs. If your job does not have enough storage, e.g., if you limit it to REGION=24M and it needs more storage to perform the work, you may see an abend such as ‘S878’.

TIME – the maximum amount of time (in minutes) the job can use the CPU. If the job runs for longer than the allowed time, it will be cancelled by JES. You will often see TIME=NOLIMIT or TIME=1440, which means the job can use unlimited time/24 hours (1440 minutes). If you job does not have enough time to execute, you may see an abend such as ‘S322’

TYPRUN – Another useful parameter you may see in jobs is TYPRUN. For example,

//JOBNUM1 JOB 504,SMITH PAYROLL,
//        CLASS=X, NOTIFY=&SYSUID,
//        REGION=0M, TYPRUN=SCAN

TYPRUN=SCAN will only read the job when you submit it, it will not execute any steps. This is useful for checking syntax and allocations before you run your job for real.

PRTY – If you have a particularly important job that you want to have precedence over other jobs on the spool you might give it a PRTY (Priority) value. The valid values you can give it for JES2 are 0-15 (JES3 is 0-14) with 15 being the highest priority. A users TSO session and other started tasks execute under PRTY 15. JES uses priority to decide job execution order when jobs have the same class.

An example job card with all the parameters we discussed:

//JOBNUM1 JOB 504,SMITH PAYROLL, CLASS=A, MSGCLASS=A, //        MSGLEVEL(2,1), NOTIFY=&SYSUID, REGION=0M,
//        TIME=1440, PRTY=9, TYPRUN=HOLD

TYPRUN of hold here will submit the job, but the job will not begin executing until we go to SDSF and release it by putting an ‘A’ in the NP column beside the job.

There are many more parameters available, but most of the time you can just leave them out and let the system use default values – unless you have a specific reason for controlling some aspect of a job. IBM provides a full list of them.

Resources:
[1] IBM – JCL Statements