Easytrieve Variables Overview

Variables Come From Field Definitions

Nothing is a variable until DEFINE or FILE gives it a name, location, length, and type. FILE PAY-GROSS 94 4 P 2 declares a packed variable on the input buffer. DEFINE WS-FLAG W 1 A declares a one-byte working storage variable. Assignment NET-PAY = GROSS - TAX requires NET-PAY defined first. Easytrieve enforces declare-before-use more strictly in activities than in library sections where DEFINE may be omitted after FILE.

1
2
3
4
5
6
7
8
9
10
11
12
13
FILE PERSNL FB(150 1800)
NAME   17 20 A
GROSS  94  4 P 2
 
DEFINE WS-COUNT W 5 N RESET VALUE 0
DEFINE NET-PAY  W 7 P 2
 
JOB INPUT PERSNL
  WS-COUNT = WS-COUNT + 1
  NET-PAY = GROSS - DEDUCT
  IF NET-PAY LT 0
     NET-PAY = 0
  END-IF

Variable Families

FILE Variables

FILE variables mirror record layouts on disk or tape. Each READ or automatic JOB INPUT loads the buffer. You may define only the columns you need—not every byte in the physical record. Misaligned lengths shift every following variable. OUTPUT FILE variables change only when your logic assigns them before PUT or WRITE. VALUE does not preload FILE variables from compile-time literals.

Working Storage Variables

W and S variables live outside the file buffer. Use them for counters, scratch math, flags, derived amounts, and report annotations. Broadcom recommends S unless you understand W spooling. W variables referenced in REPORT copy to work files at PRINT. S variables remain in static storage until the formatter reads them during printing.

Overlay Variables

Overlays are variables that share storage with a parent. DEFINE HIRE-MM DATE-OF-HIRE 2 N creates a variable view into the parent bytes. Changing HIRE-MM changes DATE-OF-HIRE. Overlays are variables structurally but not separate allocations.

Qualifiers and Name Uniqueness

Field names must be unique within each FILE and within working storage. The same name on FILE and working storage requires qualification: PERSNL:STATUS versus WORK:STATUS. Library section searches current FILE and WORK when unqualified references fail or collide. Explicit qualifiers make audits easier for beginners.

1
2
3
IF WORK:ECHO-SW EQ 'Y'
   DISPLAY PERSNL:NAME
END-IF

Assignment Updates Variables

Assignment and MOVE change variable contents. NET-PAY = GROSS - DEDUCT updates NET-PAY. MOVE SPACES TO OUT-NAME clears a character variable. Figurative constants follow MOVE rules for nullable fields. Arithmetic with NULL operands errors per nullable assignment tables—guard SQL variables before math.

VALUE, RESET, and Default Variables

VALUE on DEFINE sets initial content for working storage variables at allocation. RESET on W variables reloads initial value at JOB, SCREEN, or SORT start. Without VALUE, numeric W and S default to zero; alphabetic default to blanks. FILE variables have no VALUE default from dataset—they reflect whatever was read.

System Variables

Easytrieve provides system-defined fields for reports and runtime: LEVEL and BREAK-LEVEL during control reports, TALLY for control break counts, LINE-COUNT and PAGE-NUMBER, FILE-STATUS per file, SYSDATE and SYSTIME, RETURN-CODE, and others in Symbols documentation. You do not DEFINE these—they exist by product rules when referenced in supported contexts.

Variables in Expressions and Conditions

Variables appear in arithmetic expressions, relational IF tests, field-class conditions, DUPLICATE and EOF tests, and REPORT LINE lists. Type matters: quantitative variables need decimal positions for signed math and SUM. Comparing alphabetic variables to numeric literals triggers conversion rules that beginners should avoid by matching types.

Variables vs Constants

User variables can change during the run. VALUE-initialized fields are variables by definition but constant by team convention. System constants ZERO SPACE EOF are not variables—you do not DEFINE them. See constants chapter pages for figurative and reserved value behavior.

Beginner Mental Model

1. Define the variable before use.
2. Know whether it lives on FILE or in WORK storage.
3. Choose W or S before using the variable on reports.
4. Qualify ambiguous names.
5. Test NULL before math on SQL variables.
6. Compute derived variables before PRINT when reports depend on them.

Common Variable Mistakes

1. Using undefined names in JOB logic.
2. Expecting FILE variables to retain VALUE from DEFINE.
3. Accumulating grand totals in W fields then sorting report work files.
4. Same name on FILE and W without WORK: qualifier.
5. Treating overlays as independent copies.
6. Arithmetic on nullable variables without IF NULL.

Explain It Like I'm Five

Variables are labeled boxes. FILE boxes get filled when a new card arrives from the file pile. WORK boxes sit on your desk for counting and scratch notes. Some labels need a file name or WORK written before them so you open the right box. Some boxes are windows into a bigger box—that is an overlay. You must make the box before you put anything inside.

Exercises

1. Classify ten field names as FILE, W, S, overlay, or system.
2. Write qualified references when STATUS exists on FILE and in WORK.
3. Define NET-PAY and derive it from FILE variables.
4. Explain why VALUE does not apply to input FILE GROSS.
5. List three system variables and when each is meaningful.