Easytrieve Variable Scope

Program-Wide Library Scope

The library section is the default global dictionary. FILE statements and following field lines define input and output record variables visible to every JOB, SORT, SCREEN, and PROC unless a more specific rule overrides behavior. DEFINE WS-TOTAL W 9 P 2 in the library is visible in all activities. This is the closest Easytrieve comes to global scope—one name, one allocation for the run.

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 GRAND-TOT S 9 P 2
 
JOB INPUT PERSNL
  GRAND-TOT = GRAND-TOT + GROSS
END-JOB
 
JOB INPUT BONUS-FILE
  GRAND-TOT = GRAND-TOT + BONUS-AMT
END-JOB

GRAND-TOT persists across both JOB activities because library working storage scope spans the program. Confirm that is intended—sometimes a RESET W field per JOB is safer.

Activity-Local Scope

DEFINE inside a JOB, SORT, or SCREEN activity creates variables whose declarations must appear before first reference in that activity source. The DEFINE keyword is mandatory. These fields still live in the program dictionary but teach beginners to treat them as local intent—used only in that activity block. Defining TEMP-HOLD after first use causes compile errors.

1
2
3
4
5
6
7
JOB INPUT PERSNL
  DEFINE TEMP-HOLD W 7 P 2
  TEMP-HOLD = GROSS * 1.5
  IF TEMP-HOLD GT LIMIT
     DISPLAY NAME TEMP-HOLD
  END-IF
END-JOB

FILE Scope and Multiple Files

Each FILE has its own field namespace. NAME on PERSNL and NAME on BONUS-FILE are different variables unless you synchronize them intentionally. When both files are active in one JOB, qualify: PERSNL:NAME versus BONUS:NAME. Unqualified NAME resolves using library search rules—current FILE context and WORK—and errors if ambiguous.

WORK Qualifier Scope

WORK: limits the name to working storage explicitly. Use it in maintenance-sensitive code even when the compiler could infer the reference—auditors see intent immediately. Spacing around the colon is flexible per Broadcom syntax examples.

1
2
3
4
5
6
7
8
9
10
11
12
FILE PERSNL FB(150 1800)
STATUS 120 1 A
 
DEFINE STATUS W 1 A VALUE 'N' RESET
 
JOB INPUT PERSNL
  IF WORK:STATUS EQ 'Y'
     DISPLAY 'PROCESS FLAG ON'
  END-IF
  IF PERSNL:STATUS EQ 'A'
     DISPLAY 'ACTIVE EMPLOYEE ON FILE'
  END-IF

Overlay Scope

Overlay variables share parent scope. HIRE-MM on DATE-OF-HIRE is visible wherever the parent file buffer is active. Overlays do not create a separate WORK allocation—they are alternate names for byte ranges inside FILE or parent DEFINE storage.

PROC Scope

PROCs do not declare separate variable dictionaries. PERFORM CALC-NET sees library fields and any activity DEFINE already processed above the PERFORM call. Classic Easytrieve PROCs lack formal parameters—use working storage fields as implicit inputs and outputs. Scope discipline means naming WS-IN and WS-OUT clearly and documenting which PROC mutates which globals.

Report Procedure Scope

Report procedures reference fields in active files and working storage. When referencing CONTROL or total fields, Broadcom uses SUMFILE data automatically so totals match printed reports. LEVEL and BREAK-LEVEL are meaningful in report PROC scope during control report formatting—not generic batch JOB scope. DISPLAY in report PROC writes only to the associated report.

1
2
3
4
5
BEFORE-BREAK. PROC
  IF DEPT HIGHEST-BREAK
     DISPLAY 'BREAKING ON DEPT'
  END-IF
END-PROC

SQL and Nullable Variable Scope

SQL INCLUDE brings host variables into program scope. NULLABLE generates indicator variables tied to nullable columns—IF PHONE NULL tests indicator scope, not random bytes. Manual indicators must be paired in scope with their host variables in every SELECT INTO list they accompany.

MACRO and Copy Scope

Macros expand at compile time, injecting DEFINE and logic into the including program. Expanded fields obey the same scope rules as handwritten source. Macro parameters using & names are compile-time text substitution—not runtime variables. Beginners should not confuse &MACVAR with W fields.

Designing Scope Boundaries

• Put shared counters and totals in library S fields with documented cross-JOB intent.
• Put single-JOB scratch in activity DEFINE or W fields with RESET.
• Qualify every multi-file reference in synchronized JOB input.
• Prefix WORK-only flags with WS- or use WORK: in IF tests.
• Keep report annotations in S fields referenced only from report PROCs.

Common Scope Mistakes

1. Activity DEFINE after first reference.
2. Unqualified NAME with two active files.
3. Assuming PROC has private locals without separate DEFINE.
4. Using LEVEL in batch JOB expecting report values.
5. Expecting activity DEFINE to hide library field—name collision still errors.
6. Macro parameter &NAME mistaken for runtime variable.

Explain It Like I'm Five

Scope is which box a label points to and which rooms can see that label. Library labels are on the main hallway—everyone can use them. Activity labels must be put on the box before you use them in that room. If two boxes have the same sticker, you write the room name on the sticker too: PERSNL:NAME or WORK:NAME.

Exercises

1. Write synchronized JOB references with file qualifiers on both files.
2. Define activity-local TEMP before use; move DEFINE after use to see compile error.
3. Document which PROCs modify GRAND-TOT library variable.
4. Explain overlay scope relative to parent DATE field.
5. List three system fields and valid scope contexts for each.