Easytrieve Table Indexing

ARG Is the Index Key

Every TABLE file has exactly one ARG definition describing where the search key sits in each table row. DESC holds payload data returned on match but is not part of the index. Think of ARG as the primary key in a miniature keyed table Easytrieve manages for you. SEARCH WITH compares your search-field to ARG values using the indexed order. Misaligned ARG—wrong start position or length—indexes garbage bytes and every lookup fails or matches wrong rows.

1
2
3
4
5
6
7
8
FILE STATTAB TABLE INSTREAM
  ARG   1  1 A
  DESC  3 15 A
A       ACTIVE
I       INACTIVE
P       PENDING
S       SUSPENDED
ENDTABLE

Single-character status codes index alphabetically: A, I, P, S. WITH STATUS must be one-byte alphanumeric matching ARG layout.

When Indexing Happens

Ascending Order as Index Invariant

Index structure assumes monotonic ascending ARG. Maintenance teams must sort before load. Instream authors must type rows in order. Validation utilities can read a maintenance file and compare each ARG to the prior row, flagging inversions before production JCL runs. One inversion near the middle of a ten-thousand-row table can make half of valid keys unreachable to binary search—a failure mode that looks like bad input data instead of bad index data.

Composite Key Indexing

Business keys often combine region, branch, and product code. TABLE allows one ARG field spanning the concatenated bytes—not three separate SEARCH calls on three ARG columns.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
DEFINE COMP-KEY W 9 A
 
FILE PRODTAB TABLE INSTREAM
  ARG   1  9 A
  DESC 11 30 A
EAST01ABC WIDGET STANDARD
EAST01XYZ WIDGET PREMIUM
WEST02ABC GADGET STANDARD
ENDTABLE
 
MOVE REGION TO COMP-KEY POS 1
MOVE BRANCH TO COMP-KEY POS 3
MOVE PROD   TO COMP-KEY POS 6
SEARCH PRODTAB WITH COMP-KEY GIVING PROD-DESC

Composite ARG sorts lexicographically on the full nine bytes. EAST01ABC precedes EAST01XYZ; WEST02ABC follows all EAST keys. WITH field must match nine-byte layout exactly. Padding rules apply—shorter branch codes need consistent spaces or zeros in COMP-KEY construction.

Numeric Versus Alphanumeric Index Keys

Numeric ARG indexes by numeric value. Alphanumeric indexes by character collating sequence. Choose ARG type to match how input keys are stored. Department 417 as numeric ARG sorts before 903; as alphanumeric '417' and '903' still sort correctly but '0417' and '417' differ. Index compare uses declared length—truncated keys on input never match padded table ARG.

max-entries and Index Capacity

1
2
3
FILE ZIPTABLE TABLE 5000
  ARG   1  5 N
  DESC  7 20 A

FILE TABLE 5000 reserves memory for five thousand rows at initiation. The index contains at most that many entries. If maintenance delivers six thousand zips, the last thousand are dropped at load—SEARCH returns NOT FOUND for those keys with no diagnostic unless you compare load counts. Size max-entries above current row count with growth headroom; document peak historical counts.

Index and Memory Relationship

Each indexed row consumes memory for ARG, DESC, and internal structure. Large DESC fields multiply footprint: ten thousand rows with two-hundred-byte descriptions differ materially from ten thousand rows with twenty-byte descriptions. Indexing does not spill to disk mid-job—entire table must fit available region. Programs with many large external tables can face storage abends at initiation before first SEARCH.

What Is Not Indexed

• DESC field text—cannot SEARCH by description.
• Ordinary FILE input records—use GET sequential processing.
• Partial ARG substrings—WITH must match full ARG length.
• Duplicate ARG values—index assumes uniqueness.

Reindexing in Practice

Easytrieve does not support online reindex during a run. To change table content for external tables, replace maintenance file and rerun JOB—initiation rebuilds index. INSTREAM changes require recompile. Operations schedule reference file regeneration; developers recompile when instream codes change. There is no REINDEX verb.

Comparing to Db2 and VSAM Indexes

Index Validation Checklist

1. Confirm ARG start and length match maintenance file layout.
2. Verify ascending ARG order and no duplicates.
3. Test smallest, largest, and median keys after load.
4. Compare external row count to max-entries reservation.
5. Document composite key padding rules for operations.

Common Indexing Mistakes

• ARG position mismatch with maintenance file columns.
• Composite key built with wrong MOVE positions before SEARCH.
• max-entries too low truncating high keys.
• Duplicate ARG after spreadsheet merge.
• Attempting SEARCH on DESC or partial key.

Explain It Like I'm Five

Table indexing is putting flashcards in alphabetical order by the word on the front. The word on the front is ARG; the answer on the back is DESC. Easytrieve stacks the cards in order once so finding a word is fast. If two cards have the same front word or the stack is out of order, the fast-finding trick breaks.

Exercises

1. Design composite ARG for region plus branch plus dept nine-byte key.
2. Write validation pseudocode comparing each ARG to prior row.
3. Calculate memory estimate for 8000 rows with 50-byte DESC.
4. List differences between TABLE ARG index and Db2 primary key.
5. Determine max-entries for zip table given peak row history.