JCL and batch basics: JOB/EXEC/DD statements, return codes, submitting from USS, and reading output

What it is

Job Control Language (JCL) describes a unit of batch work as a small, fixed structure. A JOB statement names the job and carries accounting/class information. One or more EXEC statements each name a program (or a cataloged procedure) to run as a step. DD (Data Definition) statements attach the datasets, USS files, or in-stream data that step's program reads or writes, under the ddnames the program expects (for example SYSIN for command input, SYSPRINT for a report). IBM's introductory mainframe curriculum teaches this structure together with JES and SDSF (System Display and Search Facility).

Each step produces a condition code (its return code) when it finishes. By long-standing convention across IBM utilities and most well-behaved programs, 0 means completed successfully, 4 means a warning (the step did something, but flag it), 8 means an error significant enough that later steps should usually be skipped, and 12 or higher means a serious or terminal error. JCL can use a step's COND= parameter, or the newer IF/THEN/ELSE JCL constructs, to run or skip later steps based on an earlier step's return code — the batch equivalent of checking $?, declared in the JCL. Note that COND= states when a step is bypassed, the inverse of an if. An abend (abnormal end, shown as a system code such as S0C7 or S806, or a user code Unnnn) is not a return code: the step has no RC, and later steps are skipped unless they specify COND=EVEN/ONLY or test ABEND in an IF.

From a z/OS UNIX shell, submit filename reads a dataset or USS file containing JCL and hands it to JES for execution, and prints the job name and job ID JES assigned. Output can then be read interactively through SDSF, the ISPF-integrated tool for browsing a job's spool output and condition codes, or programmatically through the z/OSMF jobs REST API, which returns status and spool content as structured HTTP responses — the more agent-friendly of the two (see the z/OSMF article).

Why it matters

An agent that submits batch work needs to check the actual condition codes of every step, not just "the submit command succeeded" (submission only means JES accepted the job; the job itself can still fail every step), and needs a way to fetch the resulting spool output that does not require driving a terminal emulator.

How to apply

• Check each step's return code and look for abends or a JCL ERROR (job never ran), not just the job's overall completion status, before treating a submitted job as successful.
• Prefer submit plus the z/OSMF jobs REST API (or SDSF) to retrieve status and spool output programmatically, rather than scraping a 3270 screen.
• Read a job's DD statements before assuming what dataset or file a given step actually touched — the program's own default filenames are irrelevant once a DD statement overrides them.

Pitfalls

• Treating RC=4 as a failure across the board; many utilities use it for benign warnings, and some for meaningful ones — the specific program's documentation decides which.
• Assuming a job with RC=0 on every step did what was intended; a return code reports the program's own success signal, not whether the business outcome was correct.