Easytrieve LOOKUP — Decode Codes and Reference Data

LOOKUP as a Design Pattern

LOOKUP is not a fourth-generation mystery feature—it is disciplined reference-data design. You separate codes on transaction files from descriptions on table files. Transaction FILE definitions stay lean; TABLE definitions hold the decode dictionary. Activity logic bridges them with SEARCH. That separation lets operations update department names in a maintenance file without touching payroll extraction logic, as long as department numbers on input remain stable. Instream tables trade that flexibility for compile-time simplicity: ten status codes embedded in source are perfect until someone adds an eleventh code and requires a recompile.

Minimum LOOKUP Recipe

1. Library: FILE name TABLE with ARG and DESC.
2. Library: table rows INSTREAM or external file reference.
3. Library: working-storage fields for key and result.
4. Activity: SEARCH table WITH key GIVING result.
5. Activity: IF table / IF NOT table for success and failure paths.
6. Report or DISPLAY: print result alongside input code.

Department Code Lookup

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
DEFINE DEPT-DESC W 25 A
 
FILE DEPTLKP TABLE INSTREAM
  ARG   1  3 N
  DESC  5 25 A
100     FINANCE
200     LEGAL
417     DATA CENTER OPS
903     OPERATIONS
ENDTABLE
 
JOB INPUT EMPFILE
  SEARCH DEPTLKP WITH EMP-DEPT GIVING DEPT-DESC
  IF NOT DEPTLKP
     DEPT-DESC = '** INVALID DEPT **'
  END-IF
  PRINT EMPLIST

EMP-DEPT on the input file carries numeric department. SEARCH copies the matching DESC into DEPT-DESC for LINE printing. The visible asterisk default makes invalid codes obvious on the listing—better than a blank column that hides data quality problems until an auditor asks questions.

Zip Code to Post Office Lookup

Broadcom JOB Activities documentation includes a zip decode example. Geographic reference tables often use numeric ARG for zip and alphanumeric DESC for city or post office name. Keys must sort numerically ascending—zip 02108 before 10001. Leading zeros in alphanumeric ARG definitions require consistent padding in both table maintenance and input fields or searches fail on otherwise valid zips.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
DEFINE POST-OFFICE W 20 A
 
FILE ZIPTABLE TABLE 5000
  ARG   1  5 N
  DESC  7 20 A
 
JOB INPUT PERSNL
  IF STATE = 'DC' 'IL'
     SEARCH ZIPTABLE WITH ZIP GIVING POST-OFFICE
     IF NOT ZIPTABLE
        POST-OFFICE = 'BAD ZIP CODE'
     END-IF
     PRINT STATERPT
  END-IF

Conditional JOB logic limits lookup to states where zip decode matters for the report. FILE TABLE 5000 reserves space for five thousand zip rows loaded from an external maintenance dataset at JOB initiation—typical when postal reference data is too large for INSTREAM but still manageable in memory.

Class and Product Code Lookup

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

PROGRAM activities support quick lookup tests before embedding SEARCH in production JOB logic. DISPLAY writes to SYSPRINT so developers verify table content without running full batch JCL. Replace DISPLAY with PRINT or file WRITE in production; gate diagnostic DISPLAY behind a debug W flag if you keep it for troubleshooting.

Lookup Failure Handling Strategies

INSTREAM Versus External Lookup Tables

Choose INSTREAM when codes are few, change rarely, and shipping them inside the program object is acceptable. Choose external FILE TABLE when operations maintains reference data as a sequential dataset—department reorganizations, new product lines, expanded zip lists. External tables need sorted maintenance jobs upstream of Easytrieve. Document the dataset name in run books and version control the generator JCL that rebuilds ARG/DESC files after spreadsheet edits.

SCREEN Activity Lookup

Online inquiry programs SEARCH tables in BEFORE-SCREEN or AFTER-SCREEN procedures. Operator enters customer type code; AFTER-SCREEN SEARCHes TYPE-TAB and MOVEs description to an output-only screen field before redisplay. Same SEARCH syntax as batch; presence test still required. Pseudo-conversational CICS deployments may SEARCH on each resumed task—keep tables INSTREAM or small external to avoid reloading large reference files every transaction unless INITIATION loads them once per screen open.

Chained and Nested Lookups

One input code may drive a chain: SEARCH region table for region name, then SEARCH state table within region for tax description. Each step needs its own IF test. Avoid assuming first lookup success implies second will succeed—use independent error handling per table. When chains grow beyond three tables, evaluate whether a single denormalized maintenance file or SQL join simplifies maintenance.

LOOKUP Versus SQL FILE

TABLE LOOKUP keeps reference data inside Easytrieve memory with binary search speed and no Db2 plan bind. SQL FILE reaches shared tables with SQL verbs—better when HR maintains departments in Db2 and twelve applications need the same names. Hybrid programs are common: INSTREAM status decode for ten batch codes plus occasional SQL FILE read for employee master details. Document which codes live where so new developers do not duplicate tables in Db2 and Easytrieve divergently.

Operations and Maintenance Discipline

• Sort external table files ascending by ARG before every production load.
• Reject duplicate ARG values in maintenance validation.
• Version-control INSTREAM table edits with program source.
• Reconcile exception report volumes after reference file updates.
• Size max-entries above peak row count with headroom for growth.

Common LOOKUP Mistakes

• Printing GIVING result without IF test when code validity is required.
• Unpadded alphanumeric keys mismatching table ARG format.
• Recompiling program when external table would avoid compile for code adds.
• Using LOOKUP keyword in source instead of SEARCH.
• Searching ordinary input FILE instead of TABLE file.

Explain It Like I'm Five

LOOKUP is asking a helper book what a secret code means. You whisper the code number; the helper finds the page and tells you the real words. If the code is not in the book, you say unknown instead of guessing. SEARCH is how you ask; the TABLE is the helper book you filled in during Library time.

Exercises

1. Build department INSTREAM table and JOB with default literal on IF NOT.
2. Write PROGRAM DISPLAY test for three class codes including one missing key.
3. Design exception report PRINT for failed status lookups only.
4. Compare maintenance effort for INSTREAM versus external table when codes change monthly.
5. Sketch SCREEN AFTER-SCREEN lookup when operator enters branch code.