DISP, the parameter that causes the most trouble

DISP has three parts: what state the dataset is in now, what to do if the step succeeds, and what to do if it fails. Getting it wrong is how jobs delete data they meant to keep, or hang waiting for a file someone else is holding.

DISP=(status, normal end, abnormal end)

StatusNEW · OLD · SHR · MOD

Normal endCATLG · KEEP · DELETE · PASS

Abnormal endCATLG · KEEP · DELETE

Part one: status

Status	Meaning	Locking
NEW	Create it; it must not already exist	Exclusive
OLD	It exists, and I want it to myself	Exclusive
SHR	It exists, and others may read it at the same time	Shared
MOD	Append to it, or create it if absent	Exclusive

Part two and three: what happens afterwards

Value	Effect
CATLG	Keep it and record it in the catalog so it can be found by name
KEEP	Keep it but do not catalog it — you will need UNIT and VOLUME to find it again
DELETE	Remove it
PASS	Keep it available to a later step in this job only

The four patterns that cover almost everything

The DISP patterns worth memorising

* read an existing file, leave it alone
DISP=SHR

* create a permanent output file; clean up if the step fails
DISP=(NEW,CATLG,DELETE)

* read an existing file and delete it when done
DISP=(OLD,DELETE,KEEP)

* temporary file handed to a later step in this job
DISP=(NEW,PASS,DELETE)   then   DISP=(OLD,DELETE)

The rerun problem

DISP=(NEW,CATLG,DELETE) fails on a rerun, because after a successful first run the dataset already exists and NEW insists it must not. Sites solve this in one of three ways, and you should know which one yours uses:

A delete step at the front of the job — usually IDCAMS or IEFBR14 — removing yesterday's output before creating today's.
Generation data groups, where each run creates a new generation and the old ones age out automatically. See the datasets topic.
A date or run-number qualifier in the dataset name so every run writes a different name.

The standard 'delete if it exists' opening step

//STEP005  EXEC PGM=IDCAMS
//SYSPRINT DD SYSOUT=*
//SYSIN    DD *
  DELETE PROD.PAY.CALC
  SET MAXCC=0          <- do not fail if it was not there
/*

DISP patterns, side by side

JCLWhat it means

DISP=SHR

Existing dataset, shared: you and others can read it at the same time.

DISP=OLD

Existing dataset, exclusive: other jobs wait until you finish.

DISP=(NEW,CATLG,DELETE)

Create it; catalog on success; delete if the step abends.

DISP=(MOD,CATLG,CATLG)

Append if it exists, create if not; keep it cataloged either way.

DISP=(OLD,DELETE,KEEP)

Delete after a clean run, but keep it for investigation if the step fails.

Try it yourself

TRY IT YOURSELF

A step creates a report dataset. If the step abends you want it removed. What is the third DISP subparameter?

Show a hint

The third subparameter only applies when the step ends abnormally.

Show the solution

DELETE — for example DISP=(NEW,CATLG,DELETE).