JCL Tutorial

Understanding the DISP Parameter

Progress0 of 0 lessons

What is the DISP Parameter?

The DISP (Disposition) parameter is one of the most critical parameters in JCL. It controls how a dataset is treated before, during, and after job execution. The DISP parameter has three positional subparameters:

Status: How the dataset should be treated at the beginning of the job step
Normal Disposition: What to do with the dataset after successful job step completion
Abnormal Disposition: What to do with the dataset if the job step fails

Proper use of the DISP parameter is essential for preventing accidental data loss and ensuring datasets are correctly managed throughout the job's execution.

DISP Parameter Syntax

The basic syntax for the DISP parameter is:

jcl

1
DISP=(status,normal-disp,abnormal-disp)

If you only need to specify the status, you can use the abbreviated form:

jcl

1
DISP=status

If you need status and normal disposition but not abnormal:

jcl

1
DISP=(status,normal-disp)

Status Subparameter Options

The first subparameter specifies the status of the dataset at the beginning of the job step:

Status	Description
NEW	A new dataset is to be created in this step. The dataset does not exist yet.
OLD	The dataset already exists and exclusive use is required. No other job can access this dataset while this job is using it.
SHR	The dataset already exists and can be shared with other jobs. Multiple jobs can read the dataset concurrently.
MOD	If the dataset exists, it will be opened for additions (data appended to the end). If it doesn't exist, it will be created (treated like NEW).

Normal and Abnormal Disposition Options

The second and third subparameters control what happens to the dataset after the step completes:

Disposition	Description
DELETE	The dataset will be deleted at the end of the step.
KEEP	The dataset will be kept, but not cataloged. Most useful for temporary or non-cataloged datasets.
CATLG	The dataset will be kept and cataloged (entry added to system catalog).
UNCATLG	The dataset will be kept but removed from the catalog.
PASS	The dataset will be passed to subsequent steps in the same job. Only valid for normal disposition.

Basic DISP Examples

Creating a New Dataset

jcl

1
2
3
4
5
//STEP01   EXEC PGM=MYPROG
//DD1      DD DSN=MY.NEW.DATASET,
//            DISP=(NEW,CATLG,DELETE),
//            SPACE=(TRK,(10,5)),
//            DCB=(RECFM=FB,LRECL=80,BLKSIZE=27920)

This example creates a new dataset. If the step completes successfully, it will be cataloged. If the step fails, it will be deleted.

Reading an Existing Dataset

jcl

1
2
3
//STEP01   EXEC PGM=MYPROG
//DD1      DD DSN=MY.EXISTING.DATASET,
//            DISP=SHR

This example opens an existing dataset for shared access. No disposition is specified, so the dataset remains as is after the step.

Updating an Existing Dataset

jcl

1
2
3
//STEP01   EXEC PGM=MYPROG
//DD1      DD DSN=MY.EXISTING.DATASET,
//            DISP=OLD

This example opens an existing dataset for exclusive access. The dataset will remain as is after the step.

Advanced DISP Examples

Temporary Dataset

jcl

1
2
3
4
5
6
7
8
//STEP01   EXEC PGM=MYPROG
//DD1      DD DSN=&&TEMP,
//            DISP=(NEW,PASS),
//            SPACE=(TRK,(5,2)),
//            DCB=(RECFM=FB,LRECL=80,BLKSIZE=27920)
//STEP02   EXEC PGM=MYSECONDPROG
//DD2      DD DSN=&&TEMP,
//            DISP=(OLD,DELETE)

This example creates a temporary dataset (note the && prefix) in STEP01 and passes it to STEP02, which then deletes it after processing. Temporary datasets are automatically deleted at the end of the job.

Appending to an Existing Dataset

jcl

1
2
3
//STEP01   EXEC PGM=MYPROG
//DD1      DD DSN=MY.LOG.DATASET,
//            DISP=(MOD,CATLG,KEEP)

This example opens a dataset in MOD status to append data to the end of it. If the step is successful, the updated dataset will be cataloged. If the step fails, the dataset will be kept but not recataloged.

Dataset Generation Groups (GDG)

jcl

1
2
3
4
5
6
7
//STEP01   EXEC PGM=MYPROG
//DD1      DD DSN=MY.GDG.DATASET(+1),
//            DISP=(NEW,CATLG,DELETE),
//            SPACE=(TRK,(10,5)),
//            DCB=(RECFM=FB,LRECL=80,BLKSIZE=27920)
//DD2      DD DSN=MY.GDG.DATASET(0),
//            DISP=SHR

This example creates a new generation (+1) of a Generation Data Group (GDG) while also referencing the current generation (0) for reading. GDGs are used to manage multiple versions of a dataset.

Conditional Dataset Processing

jcl

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
//JOBNAME  JOB (ACCT),'NAME',CLASS=A,MSGCLASS=X
//*
//STEP01   EXEC PGM=IDCAMS
//SYSPRINT DD SYSOUT=*
//SYSIN    DD *
  IF MAXCC = 0 THEN DO
    DELETE MY.EXISTING.DATASET
  END
/*
//STEP02   EXEC PGM=MYPROG
//DD1      DD DSN=MY.EXISTING.DATASET,
//            DISP=(NEW,CATLG,DELETE),
//            SPACE=(TRK,(10,5)),
//            DCB=(RECFM=FB,LRECL=80,BLKSIZE=27920)
//*
//STEP03   EXEC PGM=MYOTHERPROG,COND=(4,LT)
//DD1      DD DSN=MY.EXISTING.DATASET,
//            DISP=(OLD,KEEP,KEEP)
//*

This advanced example shows conditional processing with IDCAMS to delete a dataset if it exists, then creates it in STEP02, and finally processes it in STEP03 only if previous steps had a return code less than 4. The final step uses DISP=(OLD,KEEP,KEEP) for defensive programming.

Common DISP Combinations and Their Uses

DISP Combination	Typical Use Case
DISP=(NEW,CATLG,DELETE)	Creating a new permanent dataset
DISP=(NEW,PASS)	Creating a temporary dataset for use in later steps
DISP=SHR	Reading an existing dataset that others may also need to access
DISP=OLD	Updating an existing dataset with exclusive access
DISP=(MOD,CATLG,KEEP)	Appending to an existing dataset
DISP=(OLD,DELETE)	Processing a dataset and then deleting it

DISP Parameter Best Practices

Preventing Data Loss

Always specify all three disposition parameters for critical datasets
Use KEEP instead of DELETE for abnormal disposition if data is valuable
Be cautious with DELETE - especially for production datasets
Consider using DISP=SHR instead of OLD when read-only access is sufficient

Performance Considerations

Use PASS for temporary datasets instead of CATLG/DELETE
Minimize the use of DISP=OLD to avoid resource contention
Consider using MOD for log files instead of reading, appending, and rewriting
Use GDGs for datasets that require periodic updates

Error Handling

Use appropriate abnormal dispositions based on recovery needs
Consider using KEEP for abnormal disposition to aid in debugging
For NEW datasets, use DELETE for abnormal disposition to clean up partial files
For critical updates, consider backing up the dataset before processing

Documentation

Add comments to explain unusual DISP parameter choices
Document the purpose of each dataset in the JCL
Include DISP handling in recovery procedures
Maintain consistency in DISP usage across related jobs

Frequently Asked Questions

What is the DISP parameter in JCL?

The DISP (Disposition) parameter in JCL controls how a dataset is treated before, during, and after job execution. It has three positional subparameters: status (how the dataset should be treated at the beginning), normal disposition (what to do after successful completion), and abnormal disposition (what to do if the job step fails).

What are the possible status values for the DISP parameter?

There are four possible status values for the DISP parameter:

NEW - Create a new dataset
OLD - Exclusive access to an existing dataset
SHR - Shared access to an existing dataset
MOD - Append to an existing dataset or create if it doesn't exist

What is the difference between OLD and SHR in JCL?

OLD provides exclusive access to a dataset, meaning no other job can access the dataset while your job is using it. This is necessary when you need to update the dataset. SHR provides shared access, allowing multiple jobs to read the dataset concurrently, which is more efficient when you only need to read data.

What happens when I use DISP=(NEW,CATLG,DELETE)?

DISP=(NEW,CATLG,DELETE) creates a new dataset. If the step completes successfully, the dataset will be cataloged in the system catalog. If the step fails, the dataset will be deleted. This is a common disposition for creating new permanent datasets.

How do I create a temporary dataset in JCL?

To create a temporary dataset in JCL, use an ampersand prefix in the dataset name (e.g., DSN=&&TEMP) and DISP=(NEW,PASS) to create and pass it to subsequent steps. Temporary datasets are automatically deleted at the end of the job.

jcl

1
2
3
4
//DD1 DD DSN=&&TEMP,
//        DISP=(NEW,PASS),
//        SPACE=(TRK,(5,2)),
//        DCB=(RECFM=FB,LRECL=80,BLKSIZE=27920)

What is DISP=MOD used for in JCL?

DISP=MOD is used to append data to an existing dataset. If the dataset already exists, new data will be added at the end. If the dataset does not exist, it will be created (similar to NEW). This is commonly used for log files or datasets that accumulate data over time.

When should I use DISP=PASS in JCL?

DISP=PASS should be used when you need to create a dataset in one step and use it in subsequent steps within the same job. It's more efficient than cataloging and then referencing the cataloged dataset, especially for temporary datasets. The dataset is automatically deleted at the end of the job unless it's explicitly kept with another disposition.

DD Statement JCL Procedures