Easytrieve EOF

EOF Is a File-Presence Condition

Easytrieve conditional expressions include field relational, field class, file presence, file relational, and record relational conditions. EOF belongs to file presence. Its documented form is IF, DO WHILE, or DO UNTIL followed by optional NOT, optional EOF, and a file subject. With EOF present, the test is true when the subject is at end-of-file. With NOT, the result reverses.

1
2
3
4
5
6
7
IF EOF FILE2
   DISPLAY 'FILE2 HAS ENDED'
END-IF
 
IF NOT EOF FILE1
   DISPLAY 'FILE1 STILL HAS A CURRENT RECORD'
END-IF

Automatic Input Processing

JOB INPUT PAYFILE normally gives Easytrieve control of retrieval. Before each JOB iteration, the runtime obtains a record. After the last statement, an implied return to JOB requests the next record. When there is no next record, Easytrieve does not enter the JOB body with an EOF flag for PAYFILE; it completes the input activity and invokes FINISH logic. That is why an EOF test cannot become true for the automatic input file itself.

1
2
3
4
5
6
7
JOB INPUT PAYFILE FINISH END-OF-JOB
  WS-COUNT = WS-COUNT + 1
  PRINT PAY-RPT
 
END-OF-JOB. PROC
  DISPLAY 'RECORDS PROCESSED' WS-COUNT
END-PROC

The FINISH procedure runs once after automatic input ends. It is the right location for final counts, trailers, totals, and completion messages. Coding IF EOF PAYFILE inside the ordinary JOB body and expecting it to identify the last record misunderstands the automatic cycle.

Controlled Input and NOT EOF Loops

Controlled input programs explicitly request records with GET or RETRIEVE. They can test EOF and decide what to do next. The safe order depends on the statement and access method: initialize input, retrieve a record, check whether a current record exists or EOF was reached, process only valid data, then retrieve again. Never process the buffer after an unsuccessful retrieval as though it contained a new record.

1
2
3
4
5
GET INPUT-FILE
DO WHILE NOT EOF INPUT-FILE
   PERFORM PROCESS-RECORD
   GET INPUT-FILE
END-DO

This skeleton shows the familiar priming-read pattern. Confirm the exact GET and status conventions for the file type in your Broadcom release. Indexed and database access can return statuses other than ordinary sequential EOF.

Synchronized Multi-File Input

In synchronized JOB INPUT, files advance according to their keys. One secondary file can reach EOF before the primary file. Easytrieve continues JOB iterations driven by remaining data, making IF EOF secondary-file meaningful. Broadcom examples show EOF on one file staying true across later iterations while another file continues.

1
2
3
4
5
6
7
8
9
10
11
JOB INPUT (SORT1 KEY (CUSTOMER-ID), +
           SORT2 KEY (CUSTOMER-ID)) +
     FINISH MERGE-FINISH
 
  IF EOF SORT2
     DISPLAY 'NO MORE SORT2 RECORDS'
  END-IF
 
  IF SORT1 AND NOT SORT2
     PERFORM ONLY-IN-SORT1
  END-IF

IF SORT1 is a presence test for a current SORT1 record. IF NOT SORT2 means no matching SORT2 record is present on this iteration; it is not necessarily identical to EOF SORT2. SORT2 can still have later keys even when it is absent for the current match key.

EOF vs File Absence for the Current Key

This difference is central to match/merge programming. A secondary file can be absent for customer 100 but still contain customer 200. IF NOT FILE2 is true for the current match; IF EOF FILE2 is false because later data remains.

EOF vs FILE-STATUS

EOF is a logical file-presence state. FILE-STATUS records the result of an I/O operation. A nonzero status may mean not found, duplicate key, access error, record-length problem, or another file-specific condition. Do not translate every nonzero status into EOF. Check operation documentation and handle expected EOF or not-found separately from errors.

1
2
3
4
5
6
7
8
9
10
GET PAYMSTR
 
IF EOF PAYMSTR
   DISPLAY 'END OF PAYMSTR'
ELSE
   IF PAYMSTR:FILE-STATUS NOT ZERO
      DISPLAY 'PAYMSTR I/O ERROR' PAYMSTR:FILE-STATUS
      STOP
   END-IF
END-IF

EOF Is Not the Last-Record Test

During normal automatic input, the current record can be the last record without EOF being visible in the JOB body. EOF becomes known only when retrieval attempts to move beyond the end. If logic must identify a final record before processing it, use record-relational conditions where applicable, trailer conventions, look-ahead logic, or FINISH processing. Do not label the current record “last” simply because its key equals a guessed maximum.

Empty Input Files

With automatic input, an empty file produces no ordinary JOB iterations. FINISH behavior and report output then determine whether a zero-record report or completion message is produced. Initialize counters before JOB and inspect them in FINISH. With controlled input, the first retrieval can immediately establish EOF; guard the record buffer before any field reference.

1
2
3
4
5
6
7
8
9
10
11
12
DEFINE WS-COUNT W 7 N VALUE 0
 
JOB INPUT INPUT-FILE FINISH CHECK-EMPTY
  WS-COUNT = WS-COUNT + 1
 
CHECK-EMPTY. PROC
  IF WS-COUNT ZERO
     DISPLAY 'INPUT FILE WAS EMPTY'
  ELSE
     DISPLAY 'INPUT RECORD COUNT' WS-COUNT
  END-IF
END-PROC

EOF Sentinels in Merge Algorithms

Hand-controlled two-file merges often compare current keys. After one file reaches EOF, moving HIGH-VALUES to its work key can make that key sort after every real key, allowing the other file to drain. The sentinel is a work-field technique. Keep a separate EOF state and ensure no real key can equal the sentinel.

1
2
3
4
5
6
7
8
9
10
11
IF EOF FILE-A
   MOVE HIGH-VALUES TO A-WORK-KEY
END-IF
 
IF EOF FILE-B
   MOVE HIGH-VALUES TO B-WORK-KEY
END-IF
 
IF A-WORK-KEY LT B-WORK-KEY
   PERFORM WRITE-A-ONLY
END-IF

EOF with DO WHILE and DO UNTIL

DO WHILE NOT EOF FILE continues while the file is not exhausted. DO UNTIL EOF FILE also expresses a stopping condition, but loop timing and the first retrieval must be planned. A poorly primed loop can process an uninitialized buffer once or process the last record twice. Draw the states—before first GET, current record available, after successful GET, after failed GET—before coding complex controlled input.

EOF and FINISH Procedures

FINISH is part of the JOB lifecycle rather than an EOF figurative value. It gives one controlled location for final totals and cleanup after automatic input. Reports also finish control breaks and pagination at activity completion. Avoid issuing duplicate final lines both in an attempted IF EOF branch and in FINISH.

EOF in Error Recovery

Normal EOF is not an error. Do not display alarming I/O failure messages or force a bad return code merely because sequential processing completed. Conversely, do not hide a true read error as normal EOF. Separate expected exhaustion, not-found statuses in random access, and hardware or data errors. Include file name, operation, status code, and key in diagnostics.

Version and File-Type Considerations

The file-presence syntax is documented in Broadcom Easytrieve Report Generator 11.6 and earlier CA-Easytrieve Plus guides. Whether a particular operation establishes EOF, not found, or another status depends on sequential, synchronized, VSAM, virtual, SQL, and database input modes. Use the file-processing chapter for the actual file type rather than copying a sequential GET loop into random VSAM code.

Common EOF Mistakes

1. Testing EOF inside the automatic input body and expecting a final iteration.
2. Processing the record buffer after a controlled GET reaches EOF.
3. Treating every nonzero FILE-STATUS as EOF.
4. Confusing “file absent for this match key” with “file completely exhausted.”
5. Processing the last record twice in a badly primed loop.
6. Using HIGH-VALUES as if it were the EOF state itself.
7. Failing to handle an input file that is empty from the start.

Explain It Like I'm Five

Imagine reading cards from a box. EOF means you reached into the box and there were no more cards. In automatic mode, Easytrieve hands you each card and stops calling you when the box is empty, then calls your FINISH helper. In controlled mode, you reach into the box yourself, so you must check whether you actually received a card before reading it. A missing card for one customer is not always EOF—the box may contain cards for later customers.

Exercises

1. Write an automatic JOB with a FINISH procedure that reports zero-record input.
2. Write a priming-read controlled loop using NOT EOF.
3. Explain the difference between IF NOT FILE2 and IF EOF FILE2 in a synchronized job.
4. Add FILE-STATUS error handling without classifying every error as EOF.
5. Design a two-file merge sentinel while retaining separate EOF tests.
6. Draw the retrieval states that prevent an off-by-one record-processing error.