Easytrieve Array Access

How INDEX Selects an Element

DEFINE declares RATE W 3 P 2 OCCURS 12 INDEX R-IDX. R-IDX is an ordinary numeric field. When R-IDX holds 5, statements referencing RATE use the fifth three-byte packed element. Changing R-IDX to 6 switches active element without renaming fields. The INDEX field can appear in expressions: R-IDX = R-IDX + 1 increments subscript. Some shops store INDEX in a packed field for performance; N 2 0 is typical for small tables.

1
2
3
4
5
R-IDX = 4
IF RATE GT 0
   PAY = PAY + RATE
END-IF
MOVE RATE TO WS-HOLD-RATE

Access in MOVE, IF, and Assignment

MOVE supports element-to-element, literal-to-element, and element-to-scalar copies. IF compares element to literal or other fields when INDEX is set. Assignment statements using = follow same rules. Group MOVE into entire OCCURS structure may move all occurrences when source and target definitions match—verify Language Reference for your release before relying on group MOVE instead of element loops. Partial group overlays use parent field names from DEFINE hierarchy.

FILE Repeating Group Access

After READ or GET, FILE LINE-ITEM OCCURS 8 INDEX L-SUB reflects input buffer content. Set L-SUB from 1 to LINE-COUNT from record header before processing valid lines. MOVE LINE-ITEM to working storage element copies one line. Do not process slots above COUNT—accessing unused occurrences reads residual buffer data from prior records if buffer was not cleared. WRITE path sets INDEX for each line being output then WRITE record.

1
2
3
4
5
6
7
8
JOB INPUT INVOICE
  L-SUB = 1
  DO WHILE L-SUB LE INV-LINE-COUNT
     IF LINE-ITEM NE SPACES
        PERFORM PROCESS-LINE
     END-IF
     L-SUB = L-SUB + 1
  END-DO

WORK Qualifier and Name Clashes

When FILE and working storage share a name, qualify working storage with WORK: prefix in statements that need the W array. Unqualified names may resolve to FILE field per product name resolution rules. Arrays in working storage often use WS- or WK- prefixes to avoid clashes—shop standard beats fighting qualifier rules in every line.

Nested Array Access Order

For outer ROW OCCURS 5 INDEX R and inner COL OCCURS 10 INDEX C, set R first, then C, then reference inner element. Changing R without resetting C may leave column index from prior row—reset C to 1 when starting new row unless algorithm scans full matrix with single nested loop. Document loop order in comments for nested walks.

Bounds and Valid Index Range

Valid INDEX range is 1 through OCCURS count for standard one-based usage. Loops DO WHILE IDX LE MAX should use MAX equal to OCCURS value. Using INDEX from input COUNT field without IF COUNT LE OCCURS risks overrun when file has bad data. Defensive code compares COUNT to maximum before loop. Test jobs deliberately pass COUNT greater than OCCURS to verify guard logic.

Character Array Byte Access

One-byte OCCURS over a buffer uses same INDEX walk. Set CX to position of delimiter found, MOVE substring using length override from start through CX. Access pattern CH at INDEX compares single character to comma or space. This is element access on smallest dimension—critical for parsing tutorials.

Arrays in Report Statements

PRINT field on LINE prints current element when INDEX set in BEFORE-LINE or detail procedure. Printing entire array on one line requires multiple PRINT columns with INDEX changed between statements or multiple LINE entries in loop via PERFORM. TITLE and HEADING do not subscript—only data fields on LINE use INDEX context.

Debugging Access Problems

1. DISPLAY INDEX and element value together in test SYSPRINT output.
2. Verify INDEX immediately before statement that uses element—not ten lines earlier.
3. Check separate INDEX fields not overwritten by nested PERFORM.
4. Hex-dump FILE record when FILE array values look shifted—dimension not access bug.
5. Trace PERFORM stack when INDEX changes unexpectedly.

Common Access Mistakes

• Stale INDEX from prior loop iteration processing wrong element.
• Using FILE field when W array intended without WORK: qualifier.
• INDEX increment after last element causing silent out-of-range reference.
• Assuming COBOL (3) syntax works without INDEX assignment.
• Nested loops with wrong inner or outer INDEX update order.

Explain It Like I'm Five

Access means pointing at one box in the row. You turn the INDEX dial to the box number, then read or write that box. If you forget to turn the dial, you might read box 7 when you meant box 2. Two rows of boxes need two dials—one for which shelf, one for which box on the shelf. Always look at the dial before opening a box.

Exercises

1. Write IF that tests element 1 of FLAG array without hard-coding duplicate DEFINE.
2. MOVE element 3 to element 4 using hold field and two INDEX settings.
3. Add COUNT guard before loop through FILE OCCURS lines.
4. Explain WORK: when FILE and W share NAME field.
5. Display debugging plan for wrong tax rate from array.