Easytrieve KSDS File Processing

KSDS Structure and Easytrieve Mapping

IDCAMS defines a KSDS cluster with KEYS(length offset) and RECORDSIZE. The index component stores keys pointing to data records. Easytrieve does not redefine the VSAM key in a separate clause—you declare the key as an ordinary field at the matching offset in the FILE layout. If EMP-NO is bytes 1–9 numeric and IDCAMS KEYS(9 0), your DEFINE or implicit field EMP-NO 1 9 N must align. Misaligned keys cause READ to miss rows or WRITE to corrupt data. INDEXED on FILE tells the product to use keyed access methods; omitting INDEXED on a KSDS DD is a common beginner error inherited from ESDS templates.

FILE INDEXED UPDATE Declaration

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
FILE MASTER INDEXED UPDATE FB(200 2000)
CUST-KEY   1 10 A
CUST-NAME 11 30 A
BALANCE   41  7 P 2
 
FILE TRANS   SEQUENTIAL FB(80 800)
TXN-KEY    1 10 A
TXN-AMT   11  5 P 2
 
JOB INPUT TRANS
  MOVE TXN-KEY TO CUST-KEY
  READ MASTER
  IF MASTER-PRESENCE
     ADD TXN-AMT TO BALANCE
     WRITE MASTER
  END-IF

MASTER is INDEXED UPDATE: keyed READ finds the row matching CUST-KEY, fields update in the buffer, WRITE rewrites the held record. TRANS is sequential ESDS or QSAM input. JOB INPUT walks TRANS; each iteration READs MASTER by key moved from TXN-KEY. MASTER-PRESENCE (or FILE-STATUS tests) confirms the key existed before you add to BALANCE. Without UPDATE on MASTER, WRITE may fail or be rejected at compile depending on mode.

Keyed READ Versus GET Browse

READ is the precision tool for one key. START plus GET loops walk a key range—useful for listing accounts from 100000 through end of file. JOB INPUT on INDEXED file in batch implies sequential browse with hold for update, not random READ per record unless your logic issues READ inside the loop. Choose JOB INPUT NULL plus explicit GET or READ when mixing patterns.

HOLD, NOHOLD, and Batch Update

FILE UPDATE enables rewrite paths. In non-CICS environments, GET may implicitly HOLD the record for update. NOHOLD on GET releases the hold when you only read. Explicit HOLD documents intent. Automatic JOB INPUT on VSAM INDEXED with UPDATE uses GET HOLD except CICS—your loop body can modify fields and WRITE without a separate READ when processing every master row sequentially. CICS: default NOHOLD on GET; browse with HOLD blocks update—use READ for keyed update per Broadcom screen and file chapters.

WRITE, DUPLICATE, and DELETE

1
2
3
4
5
6
7
8
9
10
11
12
FILE ITEMS INDEXED UPDATE
ITEM-KEY  1  8 A
ITEM-DESC 9 40 A
 
ADD-ITEM. PROC
  MOVE NEW-KEY TO ITEM-KEY
  MOVE NEW-DESC TO ITEM-DESC
  WRITE ITEMS STATUS
  IF DUPLICATE ITEMS
     DISPLAY 'KEY ALREADY EXISTS' NEW-KEY
  END-IF
END-PROC

WRITE without a prior READ on an existing key attempts insert. DUPLICATE status signals the key is already in the index—handle with IF DUPLICATE file-name and branch to error report or UPDATE path. DELETE removes the record identified by key or the held browse record depending on grammar and position. Always STATUS on critical WRITE and DELETE when you trap errors in procedures instead of letting the runtime ABEND.

CREATE INDEXED Clusters

FILE NEWMAST INDEXED CREATE FB(150 1500) with key field at correct offset builds a new dataset when the program runs. RESET with CREATE on mainframe VSAM overwrites REUSE clusters. Operations often pre-define the cluster in IDCAMS and use REPRO or initial load jobs; Easytrieve CREATE suits smaller in-program loads. Match CISZ and KEYS to catalog definitions. PASSWORD on FILE supplies VSAM password at open; NOVERIFY relaxes certain open errors only when policy allows.

Alternate Indexes

VSAM alternate indexes (AIX) let you READ by secondary key while the base cluster remains KSDS. Easytrieve FILE still describes the base record layout; JCL may point the DD at the AIX path with appropriate AMP parameters per site. Secondary key fields must be defined in the record. Exact AIX DD naming varies by installation—coordinate with storage administrators rather than assuming one universal DD pattern.

KSDS Versus ESDS Decision Guide

• Use KSDS when programs READ by business key or update scattered rows.
• Use ESDS when every run scans the full file once in arrival order.
• KSDS costs index space; ESDS is simpler for append-only logs.
• Duplicate key protection is inherent to KSDS INSERT paths.
• Large sequential-only reports on KSDS still work via GET browse but may be slower than ESDS extract.

FILE-STATUS and Error Constants

CODE STATUS on READ, GET, WRITE sets FILE-STATUS. Compare to constants NOTFOUND, DUPLICATE, EOF, and release-specific VSAM codes in IF procedures. Indexed file function chapter documents file-status helpers. Trapping NOTFOUND after READ prevents updating a blank buffer when the transaction key has no master row—report exception instead of writing garbage.

Common KSDS Mistakes

• FILE SEQUENTIAL on a KSDS cluster.
• Key field offset does not match IDCAMS KEYS.
• WRITE insert without DUPLICATE check.
• UPDATE omitted on FILE but WRITE in loop.
• CICS GET HOLD browse expecting rewrite.
• READ without moving key from transaction buffer first.

Testing KSDS Logic

1. Copy production master to test cluster with same KEYS definition.
2. READ known key; verify all fields match reference display.
3. READ missing key; confirm NOTFOUND branch.
4. WRITE duplicate key; confirm DUPLICATE trap.
5. Batch JOB INPUT UPDATE: modify field, WRITE, re-READ key, confirm persistence.

Explain It Like I'm Five

A KSDS is a library with a catalog card for every book. Each card shows the book title number (the key) and where the book sits. Easytrieve asks the librarian for one book by number with READ, or walks shelf order starting at a number with START and GET. If you try to add a second book with the same number, the librarian says duplicate. UPDATE on FILE is your permission slip to change or remove books on the shelf, not just read them.

Exercises

1. Declare INDEXED UPDATE master and sequential TRANS; READ and add amount.
2. Add DUPLICATE handling on WRITE insert procedure.
3. Write START plus GET loop for keys from LOW-KEY upward.
4. Document key offset alignment with a sample IDCAMS KEYS line.
5. Contrast batch GET HOLD with CICS READ update in one paragraph.