DISP Values

Purpose

DISP (Disposition) values define how a dataset is treated before and after job execution. These values control whether a dataset is created, accessed, or modified during job execution, and determine what happens to the dataset after normal completion or abnormal termination of the job.

Key Benefit:

DISP values provide complete control over dataset lifecycle management, allowing for proper resource allocation, access control, and cleanup processes in JCL jobs.

DISP Parameter Structure

The DISP parameter can specify up to three subparameters that indicate the dataset's status and disposition:

jcl

1
2
3
//ddname DD DSN=dataset.name,
//        DISP=(status,normal-termination,abnormal-termination),
//        ...other parameters...

status: Required - Specifies the dataset's initial status (NEW, OLD, SHR, or MOD)
normal-termination: Optional - Defines what happens to the dataset after successful step completion (CATLG, KEEP, DELETE, PASS, or UNCATLG)
abnormal-termination: Optional - Defines what happens if the step fails (CATLG, KEEP, DELETE, or UNCATLG)

Status Values (First Position)

Value	Description	Common Uses
`NEW`	Creates a new dataset	Creating output files, temporary datasets, or allocating new permanent datasets
`OLD`	Requests exclusive use of an existing dataset	Updating datasets or ensuring exclusive access during critical operations
`SHR`	Requests shared use of an existing dataset	Reading datasets that may be accessed by other jobs concurrently
`MOD`	Requests to append to an existing dataset or create it if not found	Appending to logs, reports, or other sequential files; fallback creation of datasets

Normal/Abnormal Termination Values (Second/Third Position)

Value	Description	Common Uses
`CATLG`	Catalogs the dataset in the system catalog	Making datasets permanently available to later jobs by name alone
`KEEP`	Retains the dataset but does not catalog it	Retaining datasets that are referenced by volume and dataset name
`DELETE`	Removes the dataset	Removing temporary datasets or cleaning up after processing
`PASS`	Passes the dataset to subsequent steps in the same job	Intermediate datasets used between job steps (only valid for normal termination)
`UNCATLG`	Removes dataset entry from catalog but keeps the dataset	Removing catalog entries while retaining the physical dataset

Common DISP Combinations

Combination	Description	Example Usage
`DISP=(NEW,CATLG,DELETE)`	Create a new dataset, catalog it if successful, delete it if job fails	Standard approach for creating new permanent datasets
`DISP=(NEW,DELETE)`	Create a temporary dataset that is deleted after the step	For short-lived intermediate files
`DISP=(NEW,PASS)`	Create a dataset and pass it to subsequent steps	Creating multi-step processing pipelines
`DISP=OLD`	Access an existing dataset exclusively (implied KEEP disposition)	Updating or processing an existing dataset
`DISP=SHR`	Access an existing dataset in shared mode (implied KEEP disposition)	Reading datasets that might be accessed by other jobs
`DISP=(MOD,CATLG,CATLG)`	Append to an existing dataset or create it if not found	For log files or cumulative reports
`DISP=(OLD,KEEP,KEEP)`	Process an existing dataset, keeping it regardless of outcome	When dataset must be preserved even if processing fails

Usage Examples

Creating a New Permanent Dataset

jcl

1
2
3
4
5
6
7
8
9
10
//STEP1    EXEC PGM=IEBGENER
//SYSPRINT DD SYSOUT=*
//SYSIN    DD DUMMY
//SYSUT1   DD *
This is sample data to be written to the new dataset.
/*
//SYSUT2   DD DSN=USER.NEW.DATASET,
//            DISP=(NEW,CATLG,DELETE),
//            SPACE=(TRK,(1,1)),
//            DCB=(RECFM=FB,LRECL=80,BLKSIZE=27920)

This example creates a new permanent dataset. If the step completes successfully, the dataset is cataloged. If the step fails, the dataset is deleted.

Processing an Existing Dataset

jcl

1
2
3
4
5
6
7
8
//STEP2    EXEC PGM=MYPGM
//SYSPRINT DD SYSOUT=*
//INPUT    DD DSN=USER.EXISTING.DATASET,
//            DISP=SHR
//OUTPUT   DD DSN=USER.PROCESSED.DATASET,
//            DISP=(NEW,CATLG,DELETE),
//            SPACE=(CYL,(5,2)),
//            DCB=(RECFM=FB,LRECL=100,BLKSIZE=32700)

This example shows reading from an existing dataset in shared mode while creating a new output dataset.

Using MOD for Appending Data

jcl

1
2
3
4
5
6
7
8
//STEP3    EXEC PGM=IEBGENER
//SYSPRINT DD SYSOUT=*
//SYSIN    DD DUMMY
//SYSUT1   DD *
This data will be appended to the existing file.
/*
//SYSUT2   DD DSN=USER.LOG.FILE,
//            DISP=(MOD,CATLG,CATLG)

This example appends data to an existing file. If the file doesn't exist, it creates a new one. The dataset is cataloged regardless of step completion status.

Temporary Dataset with PASS

jcl

1
2
3
4
5
6
7
8
9
10
11
12
13
//STEP1    EXEC PGM=SORT
//SORTIN   DD DSN=USER.INPUT.DATA,
//            DISP=SHR
//SORTOUT  DD DSN=&&TEMP,
//            DISP=(NEW,PASS),
//            SPACE=(CYL,(10,5)),
//            DCB=(RECFM=FB,LRECL=80,BLKSIZE=27920)
//SYSIN    DD *
  SORT FIELDS=(1,10,CH,A)
/*
//STEP2    EXEC PGM=MYPGM
//INPUT    DD DSN=&&TEMP,
//            DISP=(OLD,DELETE)

This example creates a temporary dataset in STEP1 and passes it to STEP2, which processes it and then deletes it. Note the use of && to identify a temporary dataset.

Validation Rules and Restrictions

NEW datasets requirements: When DISP=NEW, you must include the SPACE parameter for DASD datasets.
MOD behavior: For a MOD dataset that doesn't exist, the system treats it as NEW and creates the dataset.
PASS limitations: PASS can only be specified for normal termination and is only valid within the same job.
DELETE restrictions: System datasets and datasets with expiration dates cannot be deleted without additional authorization.
Default dispositions: If dispositions are omitted, the system uses:
- For NEW: Default is (NEW,DELETE,DELETE)
- For OLD/SHR/MOD: Default is (status,KEEP,KEEP)

DISP and Resource Management

DISP values play a crucial role in system resource management:

Resource Consideration	Impact	Best Practice
Dataset Contention	OLD causes exclusive locks, potentially causing job waits	Use SHR for read-only access whenever possible
Disk Space Usage	Failure to DELETE temporary datasets can waste disk space	Always specify DELETE for abnormal termination with NEW temporary datasets
Catalog Management	Excessive CATLG/UNCATLG operations can impact catalog performance	Use efficient cataloging strategies for high-volume jobs
Job Interdependencies	Improper disposition can cause downstream job failures	Consider the entire job stream when setting dispositions

Common Issues and Troubleshooting

Issue	Possible Causes	Solutions
Dataset not found	Using DISP=OLD or SHR for a dataset that doesn't exist	Verify dataset name Use DISP=MOD with appropriate dispositions if the dataset might not exist Create the dataset in a previous step
Dataset in use by another job	Using DISP=OLD when another job has the dataset allocated	Use DISP=SHR if read-only access is sufficient Implement job scheduling to avoid contention Add retry logic if updates are required
Dataset already exists	Using DISP=NEW for an existing dataset	Use a previous step to check/delete existing dataset Use DISP=MOD if appending is acceptable Use a unique naming convention
Dataset not catalogued	Missing CATLG disposition or step failure	Ensure CATLG disposition is specified for both normal and abnormal termination if appropriate Add explicit IDCAMS step to catalog datasets
Unexpected dataset deletion	Inappropriate DELETE disposition	Review disposition for critical datasets Use KEEP or CATLG for abnormal termination for important datasets

Best Practices

Always specify all three disposition parameters for critical datasets to ensure proper handling in both success and failure scenarios.
Use SHR instead of OLD whenever exclusive access is not required to minimize contention.
Properly manage temporary datasets with DELETE dispositions to avoid wasting disk space.
Be careful with DELETE dispositions on production datasets to avoid data loss.
Consider using MOD for datasets that may or may not exist to create more resilient JCL.
Use PASS for intermediate datasets within a job to simplify JCL and improve efficiency.
Include both normal and abnormal disposition to ensure proper dataset handling in all scenarios.
Use consistent disposition conventions across related jobs to simplify maintenance.
Document any unusual disposition strategies in JCL comments.

JES2 vs JES3 Considerations

DISP parameter behavior is generally the same in both JES2 and JES3 environments, but there are some considerations:

Feature	JES2	JES3
Dataset allocation	Performed at step execution time	Can be performed during job setup phase (with //*MAIN SETUP statements)
Dataset contention handling	Handles contention at step execution time	Can manage dataset conflicts across multiple jobs with its Global Resource Serialization features
PASS behavior	Standard implementation	Enhanced control with additional JES3 control statements

Note:

With z/OS 2.5, JES3 is being phased out in favor of JES2, making JES2-specific behaviors the standard moving forward.

Related Concepts

DISP Parameter - Main parameter that contains the disposition values
DSN Parameter - Dataset name specification that works with DISP
SPACE Parameter - Required for NEW datasets on DASD
UNIT Parameter - Specifies the device type for the dataset
VOLUME Parameter - Specifies the volume(s) for the dataset
Cataloged Procedures - Often contain standard DISP settings