A cleanup job must remove yesterday’s work file before the next run, or a setup step must allocate an empty data set with the correct attributes. IEFBR14 lets z/OS perform those actions through DD allocation and disposition processing, but the result depends entirely on the JCL you code.
What IEFBR14 actually does
IEFBR14 is an IBM-supplied program that returns control to the operating system without processing application records. Its usefulness comes from what z/OS does around program execution. Before the program receives control, the system interprets the DD statements and allocates their resources. When the step ends, the system applies each data set’s disposition.
That makes IEFBR14 a small vehicle for testing JCL, allocating an empty non-VSAM data set, or requesting disposition processing for an existing data set. It does not format records, copy members, or issue catalog commands of its own. The z/OS JCL utilities guide compares it with IEBGENER, IEBCOPY, IDCAMS, and other programs.
Why DD statements still perform work
A job step has three useful stages for this pattern:
- Allocation: z/OS resolves the DSN, DISP status, storage choices, space, and data-set attributes before IEFBR14 runs.
- Execution: IEFBR14 receives control and returns without reading or writing the data set.
- Disposition: z/OS applies the normal or abnormal action from DISP when the step ends.
If allocation fails because a data set already exists, is missing, is in use, or has invalid attributes, IEFBR14 might never receive control. A deletion or catalog failure can also occur during end-of-step processing. Therefore, “IEFBR14 returns zero” does not mean every surrounding request succeeded.
DISP fields that control the result
The common form is DISP=(status,normal-disposition,abnormal-disposition). The first field describes the data set when the step begins. The second and third fields tell z/OS what to do after normal and abnormal termination.
| Field | Typical values | Meaning in this pattern |
|---|---|---|
| Status | NEW, OLD, SHR, MOD | NEW requests creation. OLD requests exclusive use of an existing data set. SHR requests shared use. MOD extends an existing sequential data set and can be treated as new in some allocation cases. |
| Normal disposition | CATLG, KEEP, DELETE, UNCATLG, PASS | Action after a normal step end. CATLG keeps and catalogs; DELETE releases the data set. |
| Abnormal disposition | DELETE, KEEP, CATLG, UNCATLG | Action after abnormal termination. Coding it explicitly prevents a default from deciding an unwanted result. |
DISP=(NEW,CATLG,DELETE) means create now, catalog after normal termination, and delete after abnormal termination.Create a sequential data set with IEFBR14
This example allocates a cataloged fixed-block sequential data set. Replace the job card, high-level qualifier, space values, and storage choices with standards approved at your site.
//ALLOCPS JOB (ACCT),'ALLOCATE',CLASS=A,MSGCLASS=X
//STEP01 EXEC PGM=IEFBR14
//OUTFILE DD DSN=USERID.APP.INPUT,
// DISP=(NEW,CATLG,DELETE),
// SPACE=(TRK,(5,2)),
// DCB=(DSORG=PS,RECFM=FB,LRECL=80,BLKSIZE=0)
NEW asks for a new data set. CATLG keeps it and adds the catalog entry after normal termination. DELETE removes a partly created data set if the step ends abnormally. BLKSIZE=0 lets the system select a suitable block size.
On an SMS-managed system, ACS routines and a data class can supply storage and data-set attributes. Do not copy a UNIT, volume serial, storage class, or data class from another installation without checking local rules. The JCL DD statement guide explains the broader parameter context.
Create a traditional PDS
A traditional partitioned data set needs partitioned organization and directory space. The third SPACE quantity below reserves directory blocks.
//ALLOCPDS JOB (ACCT),'ALLOCATE',CLASS=A,MSGCLASS=X
//STEP01 EXEC PGM=IEFBR14
//JCLLIB DD DSN=USERID.APP.JCL,
// DISP=(NEW,CATLG,DELETE),
// SPACE=(TRK,(5,2,20)),
// DCB=(DSORG=PO,RECFM=FB,LRECL=80,BLKSIZE=0),
// DSNTYPE=PDS
The values are examples, not capacity advice. Estimate primary and secondary space from expected content, and choose a directory quantity based on expected members. A full PDS directory prevents new members even when unused data space remains.
Create a PDSE
Use DSNTYPE=LIBRARY to request a PDSE. IBM documents that PDSE allocation also needs partitioned organization or a positive directory-space quantity, whether supplied in JCL, a data class, or installation defaults.
//ALLOCPDE JOB (ACCT),'ALLOCATE',CLASS=A,MSGCLASS=X
//STEP01 EXEC PGM=IEFBR14
//SRCLIB DD DSN=USERID.APP.SOURCE,
// DISP=(NEW,CATLG,DELETE),
// SPACE=(TRK,(5,2,1)),
// DCB=(DSORG=PO,RECFM=FB,LRECL=80,BLKSIZE=0),
// DSNTYPE=LIBRARY
A PDSE directory grows as needed, so its directory-space value is not a fixed member limit like a PDS directory. Your storage policy can still change which explicit attributes are required.
Delete an existing non-VSAM data set
For a cataloged sequential data set, PDS, or PDSE that must exist, request exclusive control and DELETE for both outcomes:
//DELETE JOB (ACCT),'DELETE',CLASS=A,MSGCLASS=X
//STEP01 EXEC PGM=IEFBR14
//OLDDS DD DSN=USERID.APP.OLD.DATA,
// DISP=(OLD,DELETE,DELETE)
OLD requires the existing data set and exclusive use. If the catalog cannot locate it, another job holds an incompatible enqueue, or security rejects the request, allocation fails. Repeating this job after a successful deletion normally fails because the named data set is gone.
Understand the MOD-and-delete pattern
Some shops use DISP=(MOD,DELETE,DELETE) in cleanup steps. For a sequential data set, MOD can request append access when it exists and can be treated as a new allocation when it does not. The pattern can therefore create a missing data set and then delete it.
//CLEANUP EXEC PGM=IEFBR14
//OLDDS DD DSN=USERID.APP.WORK.DATA,
// DISP=(MOD,DELETE,DELETE),
// SPACE=(TRK,(1,1))
Do not use this as the main VSAM delete method
VSAM data sets have catalog structures and components managed by Access Method Services. Use IDCAMS DELETE with the correct entry type and controls instead of treating a cluster like an ordinary non-VSAM DD allocation. The VSAM IDCAMS command guide shows DELETE, LISTCAT, DEFINE, and REPRO patterns.
That boundary also corrects a risky shortcut in the old version of this article. An IEFBR14 DD disposition is not a substitute for understanding the VSAM cluster, alternate indexes, paths, catalog entries, or active use.
Temporary data sets and PASS
A temporary data set name begins with two ampersands and normally exists only within the job. Use PASS when a later step needs the allocation, then allow the receiving step or end-of-job processing to delete it.
//MAKEWK EXEC PGM=IEFBR14
//WORK DD DSN=&&WORK,
// DISP=(NEW,PASS,DELETE),
// SPACE=(TRK,(2,1)),
// DCB=(RECFM=FB,LRECL=80,BLKSIZE=0)
//USEWK EXEC PGM=MYPROG
//INPUT DD DSN=&&WORK,DISP=(OLD,DELETE,DELETE)
PASS makes the data set available to a later step in the same job; it does not catalog the temporary name for unrelated jobs.
Cataloged and uncataloged data sets
A cataloged DSN can normally be located by name. An uncataloged data set might require volume and unit information so allocation can find the physical entry. DELETE can remove the data set and its catalog relationship when the request is resolved correctly, while UNCATLG removes the catalog entry but keeps the data set.
GDG considerations
A generation data set is governed by its GDG base and catalog rules. Relative names such as BASE.NAME(+1), (0), and (-1) do not all mean the same thing, and end-of-job catalog processing can affect how a new generation becomes current. Use a fully reviewed GDG pattern and check whether your task is creating a generation, deleting one generation, or deleting the base. Do not use a simple IEFBR14 example to delete a GDG base.
See the Generation Data Group guide before changing production generations.
Return codes, allocation errors, and disposition failures
If IEFBR14 receives control, it normally returns without application processing. Many failures associated with the step are produced by allocation or disposition services, not by business logic inside the program. Review JES messages for the DD name and data set involved.
| Symptom | Likely area | What to check |
|---|---|---|
| New data set already exists | Allocation | DSN, catalog entry, DISP=NEW, rerun cleanup, and naming logic. |
| Existing data set not found | Allocation | Catalog lookup, qualifier, GDG reference, volume details, and whether a prior cleanup ran. |
| Data set in use | Serialization | OLD versus SHR and the job or subsystem holding the conflicting enqueue. |
| Space or attribute error | Allocation | SPACE, DCB, DSNTYPE, SMS classes, and site defaults. |
| Delete rejected | Disposition | Authorization, retention or expiration controls, catalog state, volume state, and JES messages. |
Common IEFBR14 mistakes
- Reading
DISP=(NEW,CATLG,DELETE)as three unrelated options instead of status, normal action, and abnormal action. - Omitting the abnormal disposition and accepting an unintended default.
- Using OLD for a cleanup that is expected to tolerate a missing data set.
- Adding a copied UNIT, VOL=SER, STORCLAS, or DATACLAS without checking local storage policy.
- Allocating a PDS without directory space or confusing PDS and PDSE requirements.
- Assuming IEFBR14 performs record I/O or writes an empty record.
- Using a non-VSAM deletion pattern for a VSAM cluster.
- Checking only a step code and ignoring allocation, catalog, and disposition messages.
Safe pre-submission checklist
- Confirm the exact DSN and whether it is sequential, PDS, PDSE, VSAM, temporary, or a generation.
- Decide whether the data set must already exist or must be new.
- Read all three DISP positions aloud as status, normal action, and abnormal action.
- Use storage attributes approved for the target system.
- For deletion, confirm authorization, retention rules, catalog state, and active users.
- Run LISTCAT or another read-only check first when the target is uncertain.
- After submission, read allocation and disposition messages, not only the program return code.
Related JCL guides
Review the JCL tutorial for JOB, EXEC, and DD basics. Use the DD statement examples for parameter syntax, the JCL data-set protection guide for retention and security context, and the IDCAMS guide for VSAM and catalog commands.
Official IBM references
- IBM reusable JCL for creating a data set
- IBM reusable JCL sample collection
- IBM disposition processing with DISP
- IBM DD DISP parameter reference
- IBM defining a PDSE
- IBM Access Method Services commands
IEFBR14 FAQ
What is IEFBR14 used for?
IEFBR14 is commonly used to make z/OS process DD allocation and disposition requests without running application record logic. Typical tasks are allocating an empty non-VSAM data set, deleting an existing non-VSAM data set, and testing whether JCL resources can be allocated.
Does IEFBR14 create a data set?
IEFBR14 does not create it through program logic. A DD statement with a status such as NEW causes z/OS allocation services to create the data set before the program runs. DISP and the storage attributes determine what is kept after the step.
How do I delete a non-VSAM data set with IEFBR14?
For a cataloged data set that must exist, a common pattern is DISP=(OLD,DELETE,DELETE). OLD requests exclusive access, and both termination dispositions request deletion. Verify the DSN, data-set type, authority, and local retention policy first.
Can I delete a VSAM cluster with IEFBR14?
Use IDCAMS DELETE as the normal method for a VSAM cluster. Access Method Services understands VSAM components and catalog entries, while a simple IEFBR14 DD disposition does not express the same catalog operation.
No comments:
Post a Comment