DISP is a three-part promise about dataset existence relative to your step. The first subparameter, called the disposition status, states what must be true before the step begins. The second subparameter is normal disposition: what should happen if the step ends successfully. The third is abnormal disposition: what should happen if the step fails. VSAM does not change that grammar, but it does change how you should choose values because VSAM clusters are catalog objects with SHAREOPTIONS, passwords, and integrity flags that sequential files do not mimic. This page walks through NEW, OLD, SHR, and MOD from a VSAM perspective, explains why define jobs and application jobs pick different patterns, and highlights abnormal disposition decisions that storage teams care about during incident review.
Think of the comma-separated triple as before, after success, and after failure. If you omit the third position, the system applies defaults that might not match your recovery intent. For scratch VSAM test files, operators might want DELETE on both success and failure so disk does not fill with half-built experiments. For production financial ledgers, abnormal DELETE would be unacceptable; KEEP or CATLG preserves the dataset for VERIFY and forensic analysis. Always write DISP with the failure story in mind, not only the happy path. Incident postmortems repeatedly show that the abnormal clause was left as default DELETE on a dataset that investigators needed later.
| Status | Meaning for VSAM learners |
|---|---|
| NEW | Ask the system to allocate a dataset that does not exist yet for this DD. For VSAM clusters, the supported path is normally IDCAMS DEFINE, not NEW on a random DD. NEW appears for VSAM in specialized SMS or reuse patterns your site must document. |
| OLD | The dataset must already exist and be cataloged (unless uncataloged patterns apply). Typical for production jobs referencing stable VSAM masters. |
| SHR | The dataset must exist; concurrent read sharing is requested subject to VSAM SHAREOPTIONS, security, and program OPEN mode. |
| MOD | Exists-or-extend style semantics for sequential datasets; for VSAM, only use when your access path and site standards explicitly call for MOD (often ESDS append discussions). |
OLD and SHR dominate application JCL for existing clusters. NEW appears in specialized constructs such as SMS-managed definitions or reallocation scenarios your site documents; it is not the teaching default for hand-built KSDS files. When you see MOD in VSAM discussions, slow down and read the entire DD block: MOD interacts with sequential expectations unless a documented VSAM pattern applies. If you are unsure, ask a mentor to point to a working example from your change library rather than improvising from a blog post written for UNIX pipelines.
CATLG adds or replaces catalog information when a step creates a dataset that should remain known to the system. For VSAM created through IDCAMS DEFINE, the catalog update already happened inside IDCAMS, so follow-on DDs use OLD rather than repeating CATLG logic. KEEP leaves the dataset as-is on volume when the step completes; for VSAM this is typical when the cluster already existed and you only read or updated it. DELETE removes the dataset and uncatalogs it when permitted; useful for temporary VSAM clusters built in test jobs with explicit naming. PASS passes a temporary or multi-step handle to later steps in the same job; VSAM rarely uses PASS compared to sequential temp pipelines, but certification exams still expect you to recognize the keyword.
OLD asserts exclusive use compatible with your program opening for input or output according to rules. SHR advertises willingness to participate in shared reader scenarios. VSAM still enforces SHAREOPTIONS defined at cluster creation time. If SHAREOPTIONS forbids cross-region sharing you attempt anyway, OPEN fails or queues depending on settings. Therefore DISP=SHR is not a bypass switch; it is a JCL hint aligned with cooperative reading. Production schedulers sometimes standardize on SHR for read-only extract steps to allow multiple concurrent readers where RACF permits, but each shop documents the pattern in its standards manual.
IDCAMS steps often allocate SYSPRINT and SYSIN with simple DISP patterns because those are utility datasets, not VSAM clusters. The DEFINE itself manipulates the catalog without a DD named after your cluster in the same way an application does. After define completes, a separate job step referencing DSN=your.cluster uses DISP=OLD or SHR to attach to the cataloged object. Mixing these roles in one step is possible for advanced pipelines but confuses tracing when something fails. Separate steps clarify which program owns the return code you are staring at during a bridge call.
12345//S1 EXEC PGM=CUSTSUM //CUSTMAST DD DSN=PROD.SALES.CUSTOMER.KSDS, // DISP=(SHR,KEEP,KEEP) //RPTOUT DD SYSOUT=*
SHR states that the cluster must already exist and that the job participates in shared reader expectations. KEEP on both normal and abnormal dispositions leaves the master cataloged whether the step ends cleanly or abends, which is typical when the file is not scratch. If you copied a template that said DELETE in the second position here, you would delete a production master after a successful run—always read all three DISP positions with the DD name before submit.
When a VSAM step abends mid-update, the catalog may mark the cluster for integrity review. Your abnormal disposition does not replace VERIFY or backup procedures, but it influences whether the dataset remains addressable immediately after failure. KEEP leaves it cataloged for diagnostics. DELETE might be appropriate for idempotent scratch builds. CATLG on abnormal is less common for VSAM than for sequential creates but appears in specialized pipelines. Coordinate with DBAs and storage engineers because regulatory environments often require retention of failed intermediate files for audit trails.
DISP is three answers to three questions about your toy box. Before play, do you need a brand new empty box, one that already has toys, or a box many kids can look at together? After play goes well, should the box stay on the shelf, be thrown away, or be labeled for the library? If play crashes and blocks spill everywhere, should grownups still keep the box for fixing later, or throw it away because it was only practice cardboard? Picking the wrong answers in the wrong order is how toys disappear permanently.
1. A program only reads a cataloged KSDS. Which DISP status is most common?
2. Why is DISP=(NEW,CATLG) a poor default for creating a production KSDS?
3. What does the abnormal disposition in DISP=(OLD,DELETE,DELETE) emphasize?