Easytrieve TABLE — Reference Data and In-Memory Lookup

Where TABLE Fits in a Program

TABLE definitions live in the Library section alongside other FILE statements. They are not coded inside JOB loops like GET or PRINT. Think of a table as a miniature dictionary the compiler or runtime loads once; your activity logic queries it many times per run. Instream tables ship inside the program object—ideal for ten to five hundred static codes. External tables read a maintenance file at initiation—better when operations updates reference data without recompiling Easytrieve source. Either way, only two field roles exist on the table file: ARG holds the search key layout; DESC holds the text or values returned when SEARCH succeeds.

FILE TABLE Syntax

1
2
3
4
5
6
7
8
9
10
DEFINE CODE          W   4 A
DEFINE DESCRIPTION   W  40 A
FILE CLASSES TABLE INSTREAM
ARG   1  4 A
DESC 10 40 A
1011     ENGLISH I
1012     ENGLISH II
1013     ENGLISH III
1014     ENGLISH IV
ENDTABLE

FILE CLASSES names the table. TABLE marks the file as searchable reference data. INSTREAM tells the compiler to read the following rows as table content. ARG 1 4 A defines a four-byte alphanumeric key starting at position one of each instream row. DESC 10 40 A defines a forty-byte description beginning at column ten. Data rows follow the layout—keys left-aligned in the ARG area, descriptions in the DESC columns. ENDTABLE must appear in columns one through eight with column nine blank, per Broadcom source format rules.

ARG Versus DESC — Roles Compared

SEARCH compares the WITH operand to ARG using a logical compare—data types are treated as alphanumeric for matching purposes even when ARG is defined numeric. The GIVING result receives the DESC bytes from the matched row. Length mismatches between GIVING and DESC, or varying-length fields, cause compile errors. Nullable fields are invalid for table search results.

Instream Versus External Tables

External tables use FILE TABLENAME TABLE without INSTREAM, pointing to a sequential dataset through normal JCL DD allocation. At JOB initiation Easytrieve reads rows into memory until the file ends or the entry limit is reached. Exceeding max-table-entries produces a table overflow error—size the limit above expected row count with margin for growth. Macros containing tables must include the entire definition from FILE through ENDTABLE as one unit.

Sorting and Duplicate Rules

SEARCH performs a binary search, so ARG values must be in ascending order when the table is built. An instream table with keys 105, 101, 110 may compile but SEARCH returns wrong matches or misses keys entirely. Duplicate ARG values are prohibited—two rows with department 903 make the table invalid for binary search semantics. Data quality checks belong in the process that builds external table files: sort by key ascending, deduplicate, then feed Easytrieve.

SEARCH Statement

1
2
3
4
5
6
7
8
PROGRAM NAME MYPROG
  MOVE '1012' TO CODE
  SEARCH CLASSES WITH CODE GIVING DESCRIPTION
  IF CLASSES
    DISPLAY DESCRIPTION
  ELSE
    DISPLAY 'CLASS NOT FOUND'
  END-IF

SEARCH names the TABLE file, WITH supplies the search key field, GIVING names the target that receives DESC on success. Code SEARCH anywhere in PROGRAM, JOB, or SCREEN activities. Issue multiple SEARCH calls against different tables in one pass over input. Always follow SEARCH with IF table-file or IF NOT table-file—the presence test is how Easytrieve signals match versus no match, not EOF semantics.

Practical Decode Pattern in JOB

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
FILE PAYROLL FB(80)
  DEPT   1  3 N
  GROSS 10  5 P 2
FILE DEPTNAMES TABLE INSTREAM
ARG   1  3 N
DESC  5 20 A
901   HUMAN RESOURCES
902   FINANCE
903   OPERATIONS
ENDTABLE
JOB INPUT PAYROLL NAME DEPT-RPT
  SEARCH DEPTNAMES WITH DEPT GIVING WS-DEPT-NAME
  IF NOT DEPTNAMES
    WS-DEPT-NAME = 'UNKNOWN DEPT'
  END-IF
  PRINT RPT1

Each payroll record triggers SEARCH on department code. Failure path assigns a default label so the report still prints. Success path leaves WS-DEPT-NAME ready for LINE or DISPLAY in report procedures. Beginners sometimes skip the IF NOT test and print garbage descriptions—always branch on presence when business rules require valid codes.

Performance and Memory

Binary search is O(log n) per lookup—excellent for thousands of keys per millions of input records. Memory holds the entire table for the run; extremely large reference files belong in a database ACCESS path instead. Instream tables increase load module size slightly but avoid runtime I/O to a separate dataset. External tables add one sequential read at startup—usually negligible compared to main file processing.

TABLE Versus LOOKUP Tutorial Naming

This site's LOOKUP statement page teaches the same SEARCH mechanism under the verb name many shops use conversationally. TABLE emphasizes the FILE parameter and data definition side; LOOKUP emphasizes the application pattern. Both pages are complementary—master TABLE definition here, then read LOOKUP for additional error-handling and SQL comparison material.

Common TABLE Mistakes

• Unsorted ARG keys in instream or external data.
• Duplicate ARG values in the same table.
• WITH or GIVING field length mismatch versus ARG or DESC.
• Missing ENDTABLE after instream rows.
• Using SEARCH without IF table presence test.
• Defining TABLE fields longer than 254 bytes.
• Expecting a standalone TABLE statement keyword—use FILE TABLE.

Explain It Like I'm Five

A TABLE is a cheat sheet the computer memorizes before work starts. Each line has a secret code on the left and the plain answer on the right. When your program sees code 903, it looks up the cheat sheet and finds OPERATIONS. The cheat sheet must be in order from smallest code to biggest, and you cannot have two identical codes. ENDTABLE tells the computer the cheat sheet lines are finished. SEARCH is you asking: what answer goes with this code?

Exercises

1. Write an instream day-of-week table with ARG 1 1 A and seven DESC rows ending ENDTABLE.
2. Add SEARCH and IF NOT handling for an invalid department code.
3. List three differences between INSTREAM and external TABLE loading.
4. Explain why duplicate ARG keys break binary search.
5. Convert a five-row external table design to INSTREAM for a test compile.