READ is how Easytrieve pulls a specific record into a file buffer when you know where to look. On INDEXED VSAM KSDS files, READ uses the key value already placed in the key field—employee number, account ID, policy key—and returns the matching row for MOVE, IF, PRINT, or WRITE. GET walks the file record by record; READ jumps directly when the key is known. Transaction edit jobs JOB INPUT a sequential change file and READ the master for each key change. Inquiry screens READ once before populating map fields. Beginners treat READ like COBOL READ without testing not-found and corrupt reports with blank master names. STATUS sets FILE-STATUS for operations-grade branching. This page covers statement format, keyed lookup flow, READ versus GET and JOB INPUT, duplicate keys, update pairing with WRITE, relative slot READ, and CICS differences from batch HOLD behavior.
123456789READ file-name [STATUS] [options per release] * Keyed lookup pattern: MOVE TRAN-KEY TO MAST-KEY READ MASTER STATUS IF NOT MASTER PUT ERRFILE GOTO JOB END-IF
File-name matches a Library FILE declaration. Optional STATUS sets FILE-STATUS after the operation. Additional options vary by release and file type—consult INDEXED and RELATIVE chapters for GENERIC duplicate handling or slot-specific forms. SQL files use FETCH, not READ.
Successful READ loads the retrieved record into the file's record buffer. DEFINE fields for that file reflect the new contents. Failed or not-found READ means buffer fields are not valid business data—IF NOT file-name and FILE-STATUS tests are mandatory before PRINT or arithmetic. Key field itself is usually part of the buffer layout and should be populated before READ for indexed retrieval.
FILE MASTER INDEXED declares VSAM KSDS semantics. DEFINE places the primary key at the offset and length IDCAMS used at cluster creation. MOVE transaction key to master key, READ MASTER, branch on success. Salary maintenance: READ, MOVE new salary, WRITE. Balance inquiry: READ, PRINT fields, no WRITE. Key alignment errors mimic not-found for valid keys—verify DEFINE against copybook and LISTCAT before blaming READ.
| Need | Use | Why |
|---|---|---|
| One known key from transaction | READ | Direct retrieval |
| Full master scan in key order | GET | Sequential browse |
| Automatic batch walk with update | JOB INPUT + GET HOLD | Browse each record |
STATUS on READ sets FILE-STATUS to the access method return code. Pattern: READ MASTER STATUS; IF FILE-STATUS NE 0 handle error. Without STATUS, unsatisfactory completion may raise a diagnostic and terminate the step. Production jobs log FILE-STATUS on error files for help desk correlation with VSAM LISTCAT and JCL DISP issues.
IF NOT file-name tests file presence after READ—standard not-found guard. When KSDS allows duplicate keys, first READ may return first duplicate; release-documented GENERIC or DUPLICATE paths retrieve additional rows under same key. Design loops to process all duplicates when business rules require, not only the first match.
FILE UPDATE authorizes maintenance. READ positions buffer for rewrite; MOVE changes; WRITE applies. Batch indexed browse may use GET HOLD instead of READ when walking entire file. CICS: Broadcom documents READ for update when GET HOLD is restricted. Pair READ-WRITE with STATUS on both verbs in critical financial jobs.
RELATIVE RRDS uses record number. Set relative record field, READ SLOTTAB, test active flags in buffer before using data. Empty slots may read zeros—distinguish unwritten slots with application flags rather than assuming READ failure.
JOB INPUT automatic file cannot also be READ in ways that conflict with automatic positioning— use secondary READ for lookup masters while transactions are automatic input. READ the master; never assume master is automatic input in same activity unless intentionally designed as JOB INPUT INDEXED walk.
READ is asking the librarian for one book when you know its call number. You write the number on the slip (MOVE to key field), hand it over (READ), and get that book—or empty hands if it does not exist (IF NOT). GET is walking shelf by shelf reading every book in order. Use READ when you have the number; use GET when you need to visit every shelf.
1. READ on INDEXED file retrieves by:
2. After READ you should test:
3. STATUS on READ:
4. READ differs from GET primarily when:
5. READ is invalid for: