Easytrieve Arrays Overview

Why Arrays Matter in Easytrieve Programs

Batch jobs rarely process only scalar fields. Payroll reads twelve month-to-date buckets. Inventory extracts compare quantities across warehouse slots. Validation programs scan every character in an account number. Without arrays you would copy-paste DEFINE lines RATE-01 through RATE-12 and duplicate logic twelve times—unmaintainable when rates change. OCCURS collapses repetition into one definition and one loop. Arrays also bridge to TABLE statement loading: many shops load reference data into OCCURS working storage, then LOOKUP or sequential INDEX walks during JOB processing. Report writers print one element per detail line by incrementing INDEX inside a DO loop. Understanding arrays is prerequisite for table performance tuning and for PARSE-style character walks documented elsewhere in this tutorial series.

Core Syntax: OCCURS and INDEX

DECLARE creates the repeated structure; INDEX creates the subscript controller. Both appear on DEFINE in the Library or inside an activity before first reference. The INDEX field is typically a small numeric working storage field—often type N length 2 or 4—defined on the same line or immediately after the OCCURS field. Before you MOVE AMOUNT TO TOTAL-PAY(INDEX) style logic, you assign INDEX. Reference syntax uses the element field name directly once INDEX holds the desired occurrence number. Occurrence numbers start at 1 unless your shop documents otherwise—test with DISPLAY or a small test job when migrating from another language.

1
2
3
4
5
6
7
8
9
10
DEFINE RATE      W  3 P 2 OCCURS 12 INDEX RATE-SUB
DEFINE RATE-SUB  W  2 N   VALUE 1
 
JOB INPUT MASTER
  DO WHILE RATE-SUB LE 12
     IF RATE(RATE-SUB) GT 0
        PAY = PAY + RATE(RATE-SUB)
     END-IF
     RATE-SUB = RATE-SUB + 1
  END-DO

Arrays on FILE Versus Working Storage

FILE arrays map directly from the record layout: if the copybook shows five line items of twenty bytes each, OCCURS 5 on the line group matches the physical record. Working storage arrays are independent of any file—you load them with MOVE, READ into a buffer, or TABLE load. Choose W for simple JOB counters unless report spooling of W fields affects your design; see the working storage tutorial for W versus S trade-offs.

Relationship to TABLE and LOOKUP

TABLE statement loads keyed reference data into memory the product manages. OCCURS arrays are developer-managed structures you index yourself. Some programs combine both: TABLE holds the corporate rate file, while an OCCURS array holds twelve computed values for the current employee. LOOKUP searches TABLE keys; arrays use INDEX walks or stored key parallel fields. Beginners should learn DEFINE OCCURS first, then TABLE, because many maintenance programs still use hand-loaded OCCURS arrays for small code tables under fifty rows where TABLE overhead is unnecessary.

Size Limits and FLDMAX

Each field—including the entire OCCURS group—must fit within maximum field length controlled by the FLDMAX installation option. If one element is 100 bytes and OCCURS is 200, the product allocates 20,000 bytes for that field group. Exceeding FLDMAX causes compile or allocation errors. Dimension planning page walks formulas; for now remember that wide elements times high occurrence counts consume real memory in the address space. Batch REGION and Easytrieve work file settings interact with large arrays the same way large TABLE definitions do.

One-Byte OCCURS Character Arrays

A powerful idiom overlays a string buffer with OCCURS 80 INDEX CX where each element is one byte type A. Set CX from 1 upward to examine CH(CX) or the equivalent element name your DEFINE uses. This pattern replaces missing PARSE statement functionality for comma-separated values, fixed-format sign positions, and delimiter hunting. The PARSE patterns tutorial shows full examples; arrays overview introduces the concept because it is often a beginner's first OCCURS use case outside numeric tables.

1
2
3
4
5
6
DEFINE WORK-LINE  W 80 A
DEFINE CH         W  1 A OCCURS 80 INDEX CX
DEFINE CX         W  2 N VALUE 1
 
* Overlay: redefine WORK-LINE as byte array via matching length OCCURS
* Walk CX from 1 to 80 to inspect each character

Common Beginner Mistakes

• Referencing an array element without setting INDEX first—reads occurrence 0 or stale subscript.
• Assuming COBOL parentheses syntax works in Easytrieve source.
• OCCURS count that does not match physical record length on FILE layouts.
• INDEX field too small to hold maximum occurrence—N 1 0 cannot exceed nine.
• Mixing INDEX fields between two arrays—each OCCURS should have a dedicated subscript.
• Declaring varying-length fields with OCCURS where product restrictions forbid the combination.

Arrays Versus Simple Field Lists

Defining RATE-01, RATE-02, RATE-03 without OCCURS is valid for three fixed slots when no loop will ever run. Arrays win when count exceeds a handful or when logic is uniform across elements. Migration from COBOL often starts as separate fields; refactoring to OCCURS reduces LINE and PRINT duplication in reports. Cost: slightly harder debugging until you DISPLAY INDEX and element together in test output.

Testing Array Logic

1. Compile a minimal JOB with OCCURS 3 and DISPLAY each element after setting INDEX 1, 2, 3.
2. Verify FILE array layout against a hex dump of one input record.
3. Run loop with INDEX increment until upper bound; confirm no overrun on last iteration.
4. Compare sum-in-loop result against manual calculation for three known elements.
5. Review FLDMAX with operations if compile rejects large OCCURS.

Explain It Like I'm Five

An array is a row of numbered boxes with the same label. Instead of saying "open box number three" with special punctuation, Easytrieve gives you a pointer dial called INDEX. Turn the dial to 3, then the program knows you mean the third box. All boxes are the same size and sit next to each other in memory. You can have a row of boxes in a file record or a row you built yourself in working storage for homework the job is doing right now.

Exercises

1. Declare RATE with OCCURS 6 INDEX R-IDX in working storage and initialize INDEX to 1.
2. Write a DO loop that adds every RATE element into a TOTAL field.
3. Sketch a FILE layout with three 20-byte line items as one OCCURS group.
4. List two differences between Easytrieve INDEX and COBOL subscripts.
5. Estimate byte size for OCCURS 100 of a 5-byte packed field.