ON-BREAK

Causes the specified action in a tabular report when the value of a field changes (a break occurs). The default action prints the field only when its value changes (PRINT=CHANGE).

Syntax

ON-BREAK [PRINT={ALWAYS|CHANGE|CHANGE/TOP-PAGE|NEVER}]
[SKIPLINES={num_lit|_var|_col}]
[PROCEDURE=procedure_name[(arg1[ ,argi]...)]]
[AFTER=procedure_name[(arg1[ ,argi]...)]]
[BEFORE=procedure_name[(arg1[ ,argi]...)]]
[SAVE=txt_var]
[LEVEL=nn]
[SET=nn]

ON-BREAK has the following qualifiers:

PRINT—Specifies when the break field prints.
- ALWAYS duplicates the break field for each detail group.
- CHANGE prints the value only when it changes. This is the default.
- CHANGE/TOP-PAGE prints the value both when it changes and at the top of each new page.
- NEVER suppresses printing.
SKIPLINES—Specifies how many lines to skip when the value changes.
PROCEDURE—Specifies the procedure to invoke when the value changes. This qualifier cannot be used with either the AFTER or BEFORE qualifiers.
AFTER/BEFORE —Specifies procedures to invoke either after or before the value changes. If no rows are fetched, neither procedure executes. You can only use AFTER and BEFORE within a SELECT paragraph.
Following is the sequence of events:
- SAVE—Indicates a string variable where the previous value of a break field is stored.
- LEVEL—Specifies the level of the break for reports containing multiple breaks. For example, a report sorted by state, county, and city might have three break levels: state is level 1 (the most major), and city is level 3 (the most minor). When a break occurs, other breaks with equal or higher level numbers are cleared. The level number also affects the sequence in which AFTER and BEFORE procedures are processed.
- SET—Assigns a number to the set of leveled breaks in reports with more than one set of independent breaks.

The sequence of events for a query containing ON-BREAK fields is:

Any BEFORE procedures are processed in ascending LEVEL sequence before the first row of the query is retrieved.
When a break occurs in the query, the following happens:
1. AFTER procedures are processed in descending sequence from the highest level to the level of the current break field.
2. SAVE variables are set with the new value.
3. BEFORE procedures are processed in ascending sequence from the current level to the highest level break.
4. Any breaks with the same or higher level numbers are cleared so they do not break on the next value.
5. If a PROCEDURE has been declared, the procedure is invoked.
6. If SKIPLINES was specified, the current line position is advanced.
7. The value is printed (unless PRINT=NEVER was specified).
After the query finishes (at END-SELECT) any AFTER procedures are processed in descending level sequence.

For example:

begin-select
state  (+1,1,2)  on-break level=1  after=state-tot  skiplines=2
county (,+2,14)  on-break level=2  after=county-tot  skiplines=1
city   (,+2,14)  on-break level=3  after=city-tot
...
end-select

Breaks are processed as follows:

When city breaks, the city-tot procedure is executed.
When county breaks, first the city-tot procedure is executed, then the county‑tot procedure is executed.
When state breaks, the city-tot, county-tot, and state-tot procedures are processed in that sequence.

If any BEFORE breaks were indicated, they are processed automatically, after all of the AFTER breaks and in sequence from lower to higher level numbers.

For example:

begin-select
state  (+1,1,2) on-break level=1 before=bef-state after=state-tot
county (,+2,14) on-break level=2 before=bef-cnty after=cnty-tot
city   (,+2,14) on-break level=3 before=bef-city after=city-tot
...
end-select

Now when state breaks, the sequence of procedures executed is as follows:

City-tot
Cnty-tot
State-tot
Bef-state
Bef-cnty
Bef-city

Upon entering the query at BEGIN-SELECT, the three BEFORE procedures are executed in sequence:

Bef-state
Bef-cnty
Bef-city

After the last row is retrieved, at END-SELECT, the three AFTER procedures are executed in sequence:

City-tot
Cnty-tot
State-tot

The SAVE qualifier saves the previous break value in the specified string variable for use in an AFTER procedure. You may want to print the previous break field with a summary line:

print  &state  (+1,1)  on-break  after=state-tot  save=$old-state

The SET qualifier allows you to have sub-reports with leveled breaks. By separating the ON‑BREAKs into sets, the associated leveled breaks in each set will not interfere with each other.

begin-select
state  (+1,1,2)  on-break  set=1  after=state-tot  level=1

SET=1 associates this leveled break with other breaks having the same set number.