Easytrieve BREAK-LEVEL Reserved Word

Definition and Purpose

BREAK-LEVEL is a system-defined numeric field maintained by the Easytrieve report writer during CONTROL break processing. You do not code DEFINE BREAK-LEVEL in your Library. The product sets BREAK-LEVEL when a control break occurs to reflect the highest break level involved in that break event. Purpose: let one shared BEFORE-BREAK procedure distinguish a minor department change from a region rollover that also closes every department and branch underneath. Without BREAK-LEVEL you might display "department totals" when the region itself is ending—a misleading heading on an executive summary.

Think of CONTROL fields stacked like nested folders: REGION is the outer folder, BRANCH is inside it, DEPT is inside branch. When only DEPT changes, the outer folders stay open. When REGION changes, every inner folder must close first. BREAK-LEVEL answers how far up the stack the closing action reached on this particular record boundary.

Version Introduced and Reserved Status

The BREAK-LEVEL system field is documented in Broadcom 11.6 report processing and CONTROL statement reference alongside LEVEL. The reserved-word status for migration appears on the New Reserved Words list when moving from CA Easytrieve 6.4 to 11.6 function mode. Before 11.x, some shops used BREAK-LEVEL as a working storage field name for entirely different purposes—storing a counter, a code from a flat file, or a converted COBOL name. Those definitions now collide with the language keyword and system symbol. Inventory DEFINE and FILE field lists before enabling function mode compile.

Can BREAK-LEVEL Be Used as a Variable Name?

No. Reserved status means you cannot declare a field, file label, or procedure name BREAK-LEVEL. The compiler treats the token as the system field or keyword. If your copybook contains BREAK-LEVEL 5 N or similar, replace it before migration. Common safe renames include WS-BREAK-LEVEL-NUM, RPT-HIGH-BREAK, or BRK-LVL-OUT depending on shop naming standards. Qualification does not help—you cannot write WORK:BREAK-LEVEL as a user field because the base name itself is reserved.

You can reference BREAK-LEVEL in IF tests, DISPLAY statements, MOVE to other fields, and TITLE or LINE items when you need the numeric level on output. You cannot assign to BREAK-LEVEL to fake break processing—the report writer owns its value during CONTROL events.

How BREAK-LEVEL Differs from LEVEL

LEVEL tells you which break level the current BEFORE-BREAK or AFTER-BREAK invocation is formatting—level 1 is the lowest CONTROL field, higher numbers are more major, and FINAL handling applies at end of report. BREAK-LEVEL tells you the highest control field that broke on this boundary. On a region change, multiple LEVEL passes may run in sequence while BREAK-LEVEL stays at the region's level until processing completes for that boundary. Beginners often conflate them; use LEVEL to specialize logic inside one pass and BREAK-LEVEL to detect multi-level closes.

HIGHEST-BREAK Alternative Syntax

Broadcom documents an alternative on mainframe and UNIX: instead of comparing BREAK-LEVEL to a numeric constant, test IF region-name HIGHEST-BREAK or IF branch-name HIGHEST-BREAK on a CONTROL field. That style survives when you add or remove CONTROL fields without renumbering literal level constants in procedures. IF BRANCH BREAK is equivalent to IF LEVEL equals branch's assigned level; IF BRANCH HIGHEST-BREAK parallels BREAK-LEVEL tests for whether branch was the outermost breaker. Pick one style per program for readability—mixed numeric and HIGHEST-BREAK in the same procedure confuses reviewers.

Example: Messages Before Subtotals

The following pattern comes from Broadcom CONTROL Reports documentation. REGION and BRANCH are CONTROL fields with BRANCH the lower level. BEFORE-BREAK runs before subtotal lines print. When only branch breaks, BREAK-LEVEL is 1. When region also breaks, BREAK-LEVEL is 2 and both branch and region subtotals appear. When FINAL runs, BREAK-LEVEL can reflect the grand total pass.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
REPORT PAY-RPT
  SEQUENCE REGION BRANCH
  CONTROL REGION BRANCH
  LINE REGION BRANCH NAME PAY-GROSS
 
BEFORE-BREAK. PROC
  IF LEVEL = 1
     IF BREAK-LEVEL = 1
        DISPLAY '*** BRANCH TOTALS ***'
     ELSE-IF BREAK-LEVEL = 2
        DISPLAY '*** BRANCH AND REGION TOTALS ***'
     ELSE-IF BREAK-LEVEL = 3
        DISPLAY '*** BRANCH, REGION, AND FINAL TOTALS ***'
     END-IF
  END-IF
END-PROC

Walk through sorted input mentally: consecutive records share region and branch until a branch code changes—BREAK-LEVEL 1, branch subtotal only. When region code changes on the next record, branch subtotal for the old branch, region subtotal, and BREAK-LEVEL 2 messaging apply. DISPLAY lines help operators align paper totals with console diagnostics during test runs; production reports often MOVE literals into TITLE lines instead.

Migration Issues from Legacy Field Names

Migration scanners should flag DEFINE BREAK-LEVEL, FILE field BREAK-LEVEL, and PROC labels if your release treats labels as reserved collisions. Error messages may cite unexpected keyword or duplicate symbol. Fix by renaming and recompiling all impacted copybooks in the same change window—partial renames leave link-edit success but wrong data if two modules disagree on layout. Document renames in your program header comment block for auditors comparing 6.4 and 11.6 listings.

• Search libraries for BREAK-LEVEL in columns 12–72 of DEFINE and FILE lines.
• Check generated SQL or DCLGEN imports that might echo COBOL names literally.
• Retest all CONTROL reports—not only those referencing the old user field.
• Compare subtotal banners against golden output; BREAK-LEVEL logic may be new.

Prerequisites for Correct BREAK-LEVEL Values

BREAK-LEVEL is meaningful only when CONTROL fields are declared in major-to-minor order, input records are sequenced on those fields, and PRINT feeds the report writer in that order. Unsorted files produce chaotic break sequences—BREAK-LEVEL still updates but subtotals no longer match business groups. Use SORT activity or presorted extracts. Quantitative fields belong on LINE with SUM, not on CONTROL. NOPRINT on a break level suppresses subtotal lines but does not skip BEFORE-BREAK—your DISPLAY may still run.

Common BREAK-LEVEL Mistakes

• Defining a user field named BREAK-LEVEL on 11.6.
• Testing BREAK-LEVEL outside report procedures where it is unset.
• Assuming BREAK-LEVEL equals LEVEL on every boundary—they diverge on multi-level breaks.
• Hard-coding level numbers after CONTROL field list changes without retesting.
• Ignoring sorted input requirement and blaming BREAK-LEVEL for wrong totals.

Explain It Like I'm Five

Imagine sorting your toys into big boxes (regions), smaller boxes inside (branches), and little bags (departments). When you finish one bag and start another, that is a small break. When you close a whole small box, that is a bigger break. BREAK-LEVEL tells you whether you only changed bags or you also closed a bigger box. The Easytrieve robot keeps that number for you so your program can say the right sentence before printing subtotals. You cannot name your own toy BREAK-LEVEL because that is the robot's special word.

Exercises

1. Draw a three-level CONTROL hierarchy and write expected BREAK-LEVEL for each boundary type.
2. Rewrite one IF BREAK-LEVEL test using HIGHEST-BREAK on a field name.
3. List three safe rename targets for a legacy DEFINE BREAK-LEVEL field.
4. Explain in one paragraph why unsorted input breaks BREAK-LEVEL messaging.
5. Add a BEFORE-BREAK DISPLAY that runs only when BREAK-LEVEL is 2 in a two-field CONTROL report.