Easytrieve VSAM File Processing

VSAM Organizations and FILE Types

Misdeclaring KSDS as SEQUENTIAL still opens the cluster if JCL is VSAM, but keyed READ semantics and duplicate key handling will not match your data model. LISTCAT from IDCAMS shows which organization the DSN uses—verify before coding FILE.

Sample FILE Declarations

1
2
3
4
5
6
7
8
9
10
11
* Keyed employee master
FILE EMPMAST INDEXED UPDATE FB(200 1800)
 
* Entry-sequenced audit trail browse
FILE AUDIT SEQUENTIAL FB(100 1800)
 
* Relative slot file
FILE SLOTS RELATIVE UPDATE FB(50 1800)
 
* Password-protected cluster (legacy VS syntax)
FILE SECURE VS (PASSWORD 'PRODKEY' UPDATE)

FB record format is typical for VSAM fixed-length records. Key fields in DEFINE must align with KSDS key length and position defined at cluster creation—not chosen arbitrarily in Easytrieve alone. For INDEXED files, the key field position and length must match the VSAM define unless your release documents alternate key support through specific parameters.

JCL DD for VSAM

VSAM datasets use DD DSN=cluster.name, DISP=SHR for shared read, DISP=OLD for exclusive update, and AMP='AMORG=VSAM' on many systems. The DD name typically matches Easytrieve file-name for maintainability. PATH or alternate allocation exists on some platforms; z/OS batch uses standard DD. Ensure BUFNI and BUFND in IDCAMS match concurrency when multiple steps share the cluster DISP=SHR.

1
2
3
//EMPMAST DD DSN=PROD.PAYROLL.EMPLOYEE.KSDS,
//            DISP=SHR,
//            AMP=('AMORG=VSAM')

Browse Versus Random Access

GET on INDEXED or ESDS VSAM performs sequential browse through the cluster—next record in key or entry order. READ with a key value performs random retrieval into the buffer for lookup during transaction edit. Production jobs often JOB INPUT sequential transactions and READ EMPMAST when TRAN-EMP-NO changes. Automatic JOB INPUT on INDEXED VSAM with UPDATE may issue GET HOLD in batch so you can update the current browse record—except CICS where HOLD rules differ. Know which verb your activity uses before writing maintenance logic.

UPDATE, CREATE, and RESET

UPDATE on FILE permits changing existing VSAM records through WRITE, DELETE, or equivalent paths your release documents. Without UPDATE, jobs should be read-only browse. CREATE allows defining new clusters or files when JCL and catalog rules permit—more common for output sequential than KSDS in Easytrieve report jobs. RESET on FILE controls whether uninitialized numeric fields zero on retrieval—important when partial records or sparse RRDS slots return empty data.

PASSWORD and Security

Password-protected VSAM clusters require PASSWORD on FILE or within VS(...). Operations rotate passwords outside Easytrieve source; use secure parameter libraries where site standards allow. RACF dataset profiles still govern who can run the job; Easytrieve PASSWORD satisfies VSAM cluster-level protection.

VSAM Versus QSAM in the Same Job

Mixed jobs are normal: QSAM extract in, VSAM master lookup, QSAM errors out. Each FILE declares its own type. Do not point INDEXED FILE at a QSAM DD or SEQUENTIAL FILE at KSDS expecting the access method to adapt. Secondary READ against VSAM while QSAM is automatic input is a standard pattern taught in indexed and multiple-files pages.

Online CICS Considerations

Easytrieve screen programs on CICS access VSAM through the same FILE declarations but HOLD and GET rules change: NOHOLD is default; HOLD prevents browse GET—use READ to update. Called programs must stay conversational when using CALL. Batch tutorials on this site focus on z/OS batch; coordinate with your CICS systems group for file sharing and transaction routing.

Diagnostics and FILE-STATUS

STATUS on READ or GET captures VSAM return codes in FILE-STATUS when enabled. Duplicate key, not found, and end-of-file conditions branch differently for INDEXED versus SEQUENTIAL browse. Constants such as DUPLICATE and EOF appear in condition expressions—see constants chapter for file-specific tests rather than guessing numeric codes.

When to Choose Each VSAM Type

• KSDS (INDEXED): primary key lookup—employee ID, account number, policy key.
• ESDS (SEQUENTIAL): append-only log, sequential audit, no random key path needed.
• RRDS (RELATIVE): fixed slot by record number—table slots, ring buffers, direct index.

Common VSAM Mistakes

• FILE type mismatch with actual cluster organization.
• Key field DEFINE length/position differs from IDCAMS define.
• UPDATE missing on salary or status maintenance job.
• DISP=SHR on output update file causing record lock conflicts.
• Using GET for keyed random access instead of READ.
• Wrong PASSWORD after cluster security rotation.

Explain It Like I'm Five

VSAM is three kinds of magic filing cabinets. KSDS has name tabs on folders—you ask for "employee 12345" and get that folder. ESDS is a diary where new pages are added at the back and you read page after page in order. RRDS is a row of numbered pigeonholes—you ask for hole number 7. Easytrieve FILE tells the program which kind of cabinet each name uses. UPDATE is permission to rewrite a card inside; PASSWORD is the cabinet lock combination.

Exercises

1. Map a KSDS cluster to FILE INDEXED with UPDATE and FB lengths.
2. Write JCL DD with DISP=SHR and AMP for VSAM input.
3. Contrast when you GET versus READ on the same INDEXED file.
4. List three symptoms of wrong key DEFINE on KSDS.
5. Choose ESDS versus KSDS for an append-only application log and justify.