WRITE creates a new logical record in VSAM. For a KSDS, that means VSAM inserts the record into key sequence, which may consume free space in control intervals or trigger splits when the file is full. For an RRDS, WRITE places data into a slot according to relative addressing rules your program sets before the verb. For an ESDS, WRITE appends after the current high-used position unless your design uses a more specialized pattern documented by storage. This page contrasts WRITE with REWRITE so beginners stop using the wrong verb, explains OPEN mode prerequisites, walks duplicate key handling on UNIQUEKEY clusters, and reminds you that FILE STATUS after WRITE is as important as after READ when loads must be restartable. None of this replaces your compiler manual; it orients you before you read the formal syntax pages.
| Verb | What VSAM does |
|---|---|
| WRITE | Creates a new logical record; VSAM inserts into KSDS order or appends ESDS; allocates RRDS slot when inserting. |
| REWRITE | Replaces the record at the current VSAM position after a successful read-for-update style path. |
If your specification says “update the customer email field,” that is almost always REWRITE after READ, not WRITE. If the specification says “add a brand new customer row,” that is WRITE with a fresh key. Using WRITE for maintenance updates is how duplicate key incidents enter change-of-address jobs that ran fine in unit test with empty files.
1234567MOVE NEW-CUST-ID TO CUST-KEY MOVE NEW-CUST-NAME TO CUST-NAME WRITE CUST-RECORD END-WRITE IF WS-FS NOT = '00' PERFORM HANDLE-WRITE-ERROR END-IF
END-WRITE is optional in some dialects when no phrases follow; including it clarifies scope for nested programs. HANDLE-WRITE-ERROR should branch on duplicate versus space failures differently: duplicates may mean upstream feed resent a row, while space failures may trigger extend or operator notification. Always log the key value on failure for replay analysis but redact personally identifiable information per privacy policy.
DEFINE CLUSTER with UNIQUEKEY forbids two records with the same primary key. NONUNIQUEKEY allows duplicates and shifts responsibility to program logic for disambiguation, often using browse sequences. When WRITE hits a duplicate on a unique cluster, treat it as a data quality defect unless the job is idempotent by design. When duplicates are allowed, decide whether WRITE always adds another duplicate row or whether the business prefers REWRITE to the first duplicate; that decision belongs in the functional spec, not in the mind of whichever programmer touched the file last year.
RRDS WRITE often targets a slot chosen by moving a value into RELATIVE KEY before WRITE. Writing into an occupied slot may replace or fail depending on define options and program pattern; empty slots versus deleted slots have nuanced semantics documented in VSAM materials. Beginners should build tiny sandbox files and log FILE STATUS for each experiment rather than inferring behavior from forum posts written for different z/OS levels.
Heavy random INSERT workloads cause CI splits and eventually CA splits, which show up as elapsed time spikes, not as COBOL compile warnings. Capacity planning ties WRITE rates back to FREESPACE and CI sizing chosen at DEFINE time. When loads slow mysteriously mid-job, ask storage for LISTCAT statistics and SMF before blaming COBOL.
Initial load programs often sort input into key order and may use different OPEN modes or utility paths than nightly incremental jobs that insert straggler rows. Sorting before WRITE reduces random insert cost when the job can be organized that way. Conversely, message-driven inserts cannot be sorted globally because time order is business meaning; those jobs rely on FREESPACE and CI tuning instead. Document which pattern each job implements so operators know whether a spike is expected seasonal load or a regression.
If a long WRITE loop fails halfway, determine whether partial commits are acceptable. VSAM does not give you SQL SAVEPOINT semantics in pure COBOL; you must track the last successfully written key in a checkpoint dataset and skip those keys on restart. Coordinate checkpoint file placement with disaster recovery so the restart file survives the same outage that killed the primary job.
WRITE is adding a brand new name tag toy to the shelf in the right alphabetical spot. If that name tag already exists and the shelf rule says no doubles, the librarian shakes their head—that is duplicate key. REWRITE is polishing an old toy that is already in your hand after you took it off the shelf to look at it. You cannot polish a toy you never picked up, and you cannot add a duplicate tag when the rule says one tag only.
1. To change an existing KSDS record payload while keeping the same key, use:
2. WRITE on a unique KSDS when the key already exists typically:
3. ESDS records are generally placed: