JCL ERROR — the job never ran

What happened

You submitted a job and it ended almost immediately. In SDSF the return-code column shows JCL ERROR instead of a condition code or an abend.

IEFC621I EXPECTED CONTINUATION NOT RECEIVED
IEFC605I UNIDENTIFIED OPERATION FIELD
IEFC452I PAYJOB01 - JOB NOT RUN - JCL ERROR

or, at allocation time:
IEF212I PAYJOB01 STEP020 INFILE - DATA SET NOT FOUND
IEF453I PAYJOB01 - JOB FAILED - JCL ERROR

What it means

Before any program runs, z/OS converts and interprets the JCL, then allocates the datasets each step needs. A JCL ERROR means one of those stages refused it. 'JOB NOT RUN' points to a syntax or procedure problem found when the JCL was read. 'JOB FAILED' usually points to a problem found when setting up a step, such as a dataset that cannot be found. Either way, your program did not get control in the failing step.

Typical causes

• Coding past column 71, so the statement was truncated.
• A missing continuation comma at the end of a parameter list.
• A misspelled keyword or an unbalanced parenthesis or quote.
• A step name or ddname over 8 characters, or starting with a digit.
• A procedure that does not exist in any PROCLIB searched.
• An override naming a step that does not exist, or overrides in the wrong order.
• An input dataset that is not catalogued, or a misspelled dataset name.
• A missing accounting field or other value the site requires on the JOB statement.

Symptoms

• No step ran, or the job stopped at the step with the allocation problem; no program output.
• IEFC or IEF messages in the job log naming a statement number, ddname or dataset.
• Distinguish from an abend (Sxxx or Uxxxx): there the program started and failed.
• Distinguish from a non-zero return code: there the program ran and chose to report a problem.

Where to look

• JESMSGLG for the summary line.
• JESJCL for the expanded JCL with statement numbers, including procedure lines.
• JESYSMSG for allocation messages such as dataset not found.
• The source member, with COLS turned on in the editor.

How to diagnose

1. Read the IEFC or IEF message — it names the statement number, step or ddname.
2. Find that statement number in JESJCL, not in your source; procedures change the numbering.
3. Look at the line above too: a missing comma is reported on the next statement.
4. Check columns 72–80 are clear using COLS.
5. For dataset errors, check the exact name in a dataset list and confirm it is catalogued.
6. Resubmit with TYPRUN=SCAN to validate syntax without running anything (it will not catch allocation problems).

How to fix

Correct the statement and resubmit. Because nothing ran in the failing step, a syntax error found at conversion is normally safe to resubmit from the top. If the job failed at a later step's allocation, earlier steps did run: check what they created or deleted before choosing to restart at the failing step or rerun from the start.

How to prevent

• Run TYPRUN=SCAN or a JCL checker before promoting changes.
• Use standard procedures and symbols rather than hand-coded copies.
• Keep production JCL under change control, reviewed by a second person.
• Use editor profiles that show column boundaries.

Production considerations

Interview question

What is the difference between a JCL ERROR and an abend, and how do you find the cause of a JCL ERROR?