Easytrieve Table Definition

FILE TABLE Declaration Skeleton

1
2
3
4
5
6
7
8
9
10
11
DEFINE WS-NAME    W  30 A
DEFINE WS-CODE    W   4 A
 
FILE STATES TABLE INSTREAM
ARG   1  2 A
DESC  4 20 A
AL ALABAMA
AK ALASKA
AZ ARIZONA
AR ARKANSAS
ENDTABLE

FILE STATES names the table file used in SEARCH STATES. TABLE marks searchable reference data. INSTREAM loads following rows at compile. ARG 1 2 A is a two-byte alphanumeric key starting column one on each instream line. DESC 4 20 A is twenty bytes from column four for state name. Data rows place keys in ARG columns and descriptions in DESC columns—spacing must match definitions exactly. ENDTABLE ends the instream section.

ARG Definition — Field by Field

ARG syntax follows FILE field definition pattern: ARG start-column length type. Start column is one-based position within the logical table row. Length is byte count for the search key. Type A is alphanumeric; N numeric; P packed with optional decimals; other types follow FILE rules where supported. SEARCH WITH operand must match ARG length and compatible type— a WITH field of three bytes against ARG 1 4 A leaves the fourth byte undefined in comparison. Numeric ARG with leading zeros in instream data must match how transaction files store codes—pad or define consistently.

DESC Definition — Returned Payload

DESC uses the same start-length-type syntax for the value SEARCH copies to GIVING on success. Often DESC holds human-readable text, but numeric rates or dates are valid when GIVING target matches. DESC is not searched—only ARG participates in binary search. Multiple conceptual columns in reference data must be packed into one DESC layout or split across multiple tables if you need separate SEARCH calls per attribute.

ARG Versus DESC — Side-by-Side

ENDTABLE Source Format Rules

ENDTABLE is not optional for instream tables. Broadcom requires the terminator in columns one through eight with column nine blank—same discipline as other Easytrieve special names. Rows after ENDTABLE belong to program structure again, not table data. Omitting ENDTABLE confuses the compiler about where data ends; misplaced ENDTABLE truncates rows silently. In code reviews, verify ENDTABLE alignment with the same care as JOB and REPORT headers.

External Table Definition

1
2
3
FILE DEPTREF TABLE 500
ARG   1  3 N
DESC  5 25 A

DEPTREF has no INSTREAM keyword. TABLE 500 reserves space for five hundred entries—adjust for peak row count plus growth. JCL allocates a sequential reference file to DD name matching DEPTREF. At JOB initiation Easytrieve reads rows until EOF or entry limit. Row layout in the file must match ARG 1 3 N and DESC 5 25 A positions. Operations maintains DEPTREF outside compile cycles; developers change max-table-entries when capacity planning demands.

Preparing External Reference Files

1. Extract reference rows from source of truth system.
2. Sort by ARG key ascending in a preprocessing job—DFSORT on key fields matching ARG layout.
3. Deduplicate ARG collisions; reject file if duplicates remain.
4. Validate record length equals maximum ARG and DESC span in FILE define.
5. Load test SEARCH in QA with production row counts below max-table-entries.

max-table-entries Explained

Length and Type Constraints

• ARG and DESC each maximum 254 bytes on table files.
• Nullable fields cannot be GIVING targets for SEARCH results.
• Varying-length fields are invalid in table search roles.
• WITH and GIVING working storage fields must match ARG/DESC lengths at compile time.
• Instream row lines must span at least highest ARG/DESC end column.

Instream Row Authoring Tips

Use fixed columns in the editor—monospace alignment prevents keys drifting into DESC territory. For numeric ARG, right-align or zero-fill consistently with transaction file definitions. Comment in source above large instream blocks listing owner team and last verification date. When tables exceed roughly one screen of rows, consider external files so diffs stay readable in version control.

1
2
3
4
5
6
7
FILE ERRMSG TABLE INSTREAM
ARG   1  4 A
DESC  6 50 A
E001 Invalid department code submitted
E002 Pay amount exceeds policy maximum
E003 Employee record not found on master
ENDTABLE

Definition in Macros

Shared code tables belong in macros included by many programs. Place entire FILE TABLE block through ENDTABLE inside one macro—splitting ARG from rows across macros breaks compile expectations. Consumers invoke macro name in Library; each program SEARCH uses the table file name declared in the macro. Change once, recompile dependents.

Compile and Load Errors — Definition Side

Explain It Like I'm Five

Defining a table is writing the rules for a cheat sheet before you fill in answers. ARG tells where the secret code sits on each line and how long it is. DESC tells where the plain-English answer sits and how long that answer can be. INSTREAM means you type the cheat sheet lines right into your program homework. External means the teacher hands you a printed cheat sheet at the door. ENDTABLE is writing THE END so the computer knows you finished the list. You must number codes from smallest to biggest without repeating a code, or the computer's quick lookup trick breaks.

Exercises

1. Define a five-row currency TABLE INSTREAM with ARG 1 3 A and DESC 5 30 A.
2. Convert the instream table to external TABLE 10 with JCL DD notes in comments.
3. Identify three layout bugs in a deliberately misaligned sample instream block.
4. Write DFSORT control card sketch to sort external reference by numeric ARG key.
5. Document max-table-entries choice for a table growing ten rows per year from 400 base.