Easytrieve File Functions

FILE Declaration Versus Runtime State

Compile time: FILE INFILE FB(lrecl), DEFINE fields, optional FILE attributes for VSAM organization. Runtime: JCL DD assigns dataset. OPEN prepares buffer. READ advances pointer. File functions read that runtime state—they do not replace FILE statement or correct bad JCL. Mismatch between FILE FB length and dataset LRECL surfaces as status errors detectable when program checks status instead of assuming every READ succeeds.

EOF and Loop Control

Sequential JOB INPUT loops until EOF indicates no more records. DO WHILE EOF EQ N with READ inside body is standard pattern. EOF is documented as special file-related value rather than parenthetical function on many releases—still grouped in file function tutorials because behavior is identical from programmer view. Inverting EOF condition causes zero iterations or infinite loop—verify EQ N versus EQ Y semantics in Language Reference for your version. Nested files each maintain separate EOF when multiple FILE definitions active—do not assume global EOF across unrelated inputs.

1
2
3
4
5
6
7
JOB INPUT PAYROLL
  DO WHILE EOF EQ N
     READ PAYROLL
     IF DEPT EQ 911
        PRINT DEPT-RPT
     END-IF
  END-DO

File Status After I/O Verbs

Keyed READ, GET, WRITE, and DELETE on VSAM set status codes consumed by status functions or special registers per manual. NOTFND routes optional lookup miss. DUPKEY triggers duplicate handling. I/O error may warrant DISPLAY status, increment ERROR-COUNT, and ABEND via ABEXIT PARM when threshold exceeded. Pattern: perform READ; IF STATUS-FUNC EQ NOTFND perform default logic; ELSE IF STATUS-FUNC EQ OK continue; ELSE call ERROR-PROC. Exact status literal names vary—copy from Messages and Codes for your release.

Record Count and Reconciliation

Increment WS-COUNT each iteration manually or use count function if documented. Trailer record carries FILE-COUNT from upstream; IF WS-COUNT NE FILE-COUNT flags imbalance. Functions returning system-maintained count may differ from manual counter when READ failures skip increment—document which count is authoritative for audit. Operations teams reconcile spool counts, file counts, and control totals nightly; Easytrieve program should PRINT all three on summary report when file functions support it.

Sequential Versus Indexed Files

Sequential batch relies heavily on EOF. VSAM KSDS adds status after every keyed access—file status functions essential. ESDS sequential browse uses EOF; direct access uses relative or key status. FILE statement attributes determine which verbs and status codes apply. Do not copy VSAM error PROC from colleague's KSDS program into pure FB sequential job without trimming unused branches.

Error PROC Integration

Centralize status handling in ERROR-PROC: DISPLAY file name placeholder, status code, record key fields, SET ABEND flag when severity high. PERFORM ERROR-PROC from multiple READ paths keeps logic consistent. File functions supply parameters ERROR-PROC formats into SYSPRINT line. PARM ABEXIT controls whether runtime aborts on unhandled status— coordinate with operations before enabling in production.

Multiple File Coordination

Matching master and detail files checks EOF on both—IF MASTER-EOF EQ Y AND DETAIL-EOF EQ Y exit merge loop. Premature exit when one file shorter causes orphan detail rows—status and EOF tests must pair with business rules on file synchronization. File functions tied to specific FILE name disambiguate which input exhausted when three FILE definitions read in interleaved pattern.

JCL and DD Relationship

File functions report logical Easytrieve FILE name state; JCL DD maps logical to physical dataset. DISPLAY of DD-related function output helps debug wrong dataset mounted—when function available per manual. Wrong DD still produces records; only validation catches content mismatch. Teach operators to verify DDNAME in listing against JCL when status OK but business totals wrong.

Performance Considerations

Status check per READ is negligible. Logging every OK status to SYSPRINT floods spool—log exceptions only. Count increment is integer add—cheap. Avoid redundant status function calls—store in working field once per READ iteration.

Common File Function Mistakes

• Ignoring status after keyed READ—silent wrong processing.
• Assuming one global EOF for multiple simultaneous files.
• Manual count not incremented on CONTINUE path after validation fail.
• Treating NOTFND as ABEND when business expects miss handling.
• FILE FB mismatch with dataset—status errors ignored until ABEND late in job.
• Confusing FILE statement name with JCL DD name in diagnostics.

Explain It Like I'm Five

File functions ask questions about the storybook you are reading. Are there more pages left—that is EOF? Did the library say book not found when you asked for a title—that is status? How many pages did you read—that is count? The FILE statement describes what each page looks like; file functions tell you what happened while you turn pages.

Exercises

1. Sketch DO WHILE EOF loop with READ and one IF filter.
2. Describe NOTFND versus I/O error handling branches.
3. Explain trailer reconciliation with WS-COUNT and control field.
4. List difference between sequential EOF focus and VSAM status focus.
5. Write ERROR-PROC responsibilities in three bullet points.