Easytrieve GET Statement

Statement Format

1
2
3
4
5
6
7
8
9
10
GET file-name [PRIOR] [HOLD | NOHOLD] [STATUS]
 
* Forward read with status:
GET PERSNL STATUS
 
* Controlled loop with EOF test:
GET MASTER
IF EOF MASTER
  STOP
END-IF

File-name must match a FILE in the Library section and must not be SQL. PRIOR, HOLD/NOHOLD, and STATUS are optional and independent: you can combine PRIOR with STATUS when the access method supports backward reads.

What GET Changes in Memory

After a successful GET, the file's record buffer holds the retrieved record. Fields defined under that FILE (or macro) now reflect the new record. A failed or end-of-file condition means you must not treat those fields as valid business data. File presence tests (IF file-name) and IF EOF file-name are the standard guards Broadcom documents for GET-based logic.

Automatic Input Versus GET

To turn off automatic input entirely, code JOB INPUT NULL. Without STOP or TRANSFER somewhere in that activity, a NULL-input JOB can loop forever—pair GET loops with clear exit conditions.

PRIOR — Reading Backward

GET PRIOR places the previous sequential record into the buffer. If direction reverses from forward GET to GET PRIOR, you receive the record immediately before the one currently in the buffer. If you reverse from PRIOR back to plain GET, you receive the record immediately after the current buffer contents. When PRIOR is used and file position is not yet established, Easytrieve places the last record of the file in the buffer. If the operating system access method does not support previous-record retrieval, execution fails—do not assume every sequential dataset allows PRIOR.

Restrictions with POINT: you cannot issue GET PRIOR after POINT, and you cannot issue GET after POINT PRIOR. Positioning and GET direction must stay consistent with Broadcom POINT rules.

HOLD and NOHOLD

Outside CICS, when FILE specifies UPDATE, Easytrieve automatically holds records so you can update them. NOHOLD overrides that automatic hold when you want to browse without locking. HOLD requests an explicit hold for update; it is invalid if UPDATE is not on the FILE statement. HOLD keeps position for a possible update—you are not forced to rewrite. Records release when the update completes or a commit point occurs; RELEASE can free a hold early.

In CICS, NOHOLD is the default. If you specify HOLD, you cannot browse with GET—an execution error occurs. For CICS updates, Broadcom directs you to READ rather than held GET browse patterns.

STATUS and FILE-STATUS

STATUS asks Easytrieve to set the file's FILE-STATUS field with the I/O return code instead of only failing hard. Test zero versus non-zero for most programs; detailed codes are in the system-defined fields appendix. FILE-STATUS is not defined unless you specify a file type parameter on FILE—another reason to code SEQUENTIAL or INDEXED explicitly when you need status. Without STATUS, a non-zero operating-system status usually produces a diagnostic message.

1
2
3
4
5
6
7
8
9
FILE PERSNL INDEXED
%PERSNL
PROGRAM NAME MYPROG
  GET PERSNL STATUS
  IF PERSNL:FILE-STATUS NE 0
    DISPLAY PERSNL:FILE-STATUS
  ELSE
    DISPLAY HEX PERSNL
  END-IF

EOF Testing Pattern

1
2
3
4
5
6
7
8
9
10
FILE MASTER FB(80 800)
* field definitions...
 
JOB INPUT NULL NAME READ-MASTER
  GET MASTER
  IF EOF MASTER
    STOP
  END-IF
  * process MASTER fields here
  GOTO JOB

With GET PRIOR, EOF means you reached the beginning of the file, not the end—adjust messages and counters accordingly. Skipping the EOF test is the most common beginner GET bug: fields appear blank or stale from the prior successful read.

GET Versus READ Versus JOB INPUT

• JOB INPUT — automatic forward sequential priming of one (or synchronized) files.
• GET — explicit sequential next/prior into buffer; controlled loops and secondary files.
• READ — keyed or positioned retrieval patterns (especially important under CICS update rules).

Choose JOB INPUT for the classic report loop over one master. Choose GET when logic must interleave two files, skip automatic priming, or live in PROGRAM. Choose READ when access is by key rather than pure sequential next.

Secondary File Example

1
2
3
4
5
6
7
8
9
10
11
12
FILE PRIMARY FB(100 1000)
* primary fields...
FILE LOOKUP FB(40 400)
* lookup fields...
 
JOB INPUT PRIMARY NAME JOIN-LIKE
  GET LOOKUP
  IF EOF LOOKUP
    * handle missing secondary stream
  ELSE
    * compare keys / PRINT
  END-IF

Primary advances automatically each JOB iteration; LOOKUP advances only when you GET it. For true key matching at scale, prefer synchronized JOB INPUT with KEY clauses—but GET secondary remains common for simple enrichment and small reference files.

Testing GET Logic

1. Run GET loop on empty file; confirm EOF path STOPs without processing.
2. Verify STATUS path displays non-zero when DD is missing.
3. Attempt GET on automatic input file; confirm compile or runtime rejection.
4. On a supporting file type, reverse with GET PRIOR and validate order.
5. In CICS test regions, confirm HOLD browse rules versus READ update.

Common GET Mistakes

• GET on automatic input file.
• No EOF test after GET.
• GET on SQL FILE.
• Assuming PRIOR works on every sequential access method.
• GET PRIOR after POINT or GET after POINT PRIOR.
• JOB INPUT NULL without STOP—runaway activity.
• Expecting FILE-STATUS without coding file type on FILE.

Explain It Like I'm Five

Imagine a stack of flashcards. GET takes the next card and puts it on the table so you can read it. GET PRIOR puts the previous card back on the table instead. If the automatic teacher (JOB INPUT) is already flipping the main stack for you, you are not allowed to flip that same stack yourself—you can only flip a second stack. When there are no cards left, you must notice (EOF) and stop asking for more, or you will stare at an empty table.

Exercises

1. Write JOB INPUT NULL with GET and EOF STOP for a master file.
2. Explain why GET cannot target automatic input.
3. Describe HOLD versus NOHOLD outside CICS.
4. Add STATUS and a non-zero FILE-STATUS DISPLAY.
5. Design primary automatic + secondary GET processing.