HP 3000 Manuals HP 3000 Manuals
BREAK WHEN
The BREAK WHEN statement provides a general mechanism for automatic
summary level breaks. The DETAIL LINE statement causes the execution of
the statement. If the break condition is true, all summary levels from
the BREAK level and up are triggered. This causes TRAILER and HEADER
sections to be printed.
The BREAK WHEN statement can occur anywhere in the report description.
There can only be one BREAK statement per summary level, either BREAK IF
or BREAK WHEN. There is no BREAK statement for the report level.
Syntax
BREAK break_level WHEN control_expr [CHANGES]
BREAK break_level WHEN num_ctl_expr [CHANGES] BY num_by_expr
Parameters
break_level The summary level triggered if the break condition is
satisfied. This value must be in the range [0, 9]; a
level of zero causes the statement to be ignored.
control_expr A numeric or string expression. When BREAK WHEN is
num_ctl_expr evaluated, the value of this expression is recorded.
Then this value is compared at the next DETAIL LINE to
see if any change has occurred. A break occurs occur if
a change takes place.
num_by_expr A numeric expression indicating how much the control
expression must change before a break occurs. See below
for exact details about how this works. The control
expression must be numeric to use a BY clause.
Examples
100 BREAK 1 WHEN Salesman$ CHANGES
100 BREAK 3 WHEN Region CHANGES
100 BREAK N WHEN Product CHANGES BY Base_product_num
The BEGIN REPORT statement sets all BREAK WHEN statements to busy, unless
the break_level is zero. When the report ends, the lines are no longer
busy. The level expression is evaluated only during BEGIN REPORT. In
addition, the BY clause value is evaluated only during BEGIN REPORT. The
control expression is evaluated during DETAIL LINE, TRIGGER BREAK, and
BEGIN REPORT.
The DETAIL LINE statement checks all BREAK statements when its total-flag
is nonzero. The BREAK statements are evaluated in summary level order,
from one to nine. The control expression of the BREAK WHEN statement is
evaluated at this time. Conditions for satisfying a break are given
below. The LASTBREAK function is set as soon as a break condition is
found. DETAIL LINE remembers the lowest level broken and triggers the
TRAILER and HEADER sections from that level through nine. First, the
TRAILERS are triggered from the highest existing level descending to the
lowest level broken. Next, the HEADERS are triggered from the lowest
level broken up to the highest existing level.
When BEGIN REPORT executes, the level expressions for all BREAK
statements are evaluated first. A second pass is made for BREAK WHEN
statements. During this pass, the control expression is evaluated and
the result put into OLDCV (or OLDCV$) for the break level. Then, if
present, the BY clause is evaluated and its value recorded. This value
is used when a break occurs at the current level.
The TRIGGER BREAK statement also evaluates the BREAK WHEN control
expressions for all broken levels. This is to update the OLDCV and
OLDCV$ values for all broken levels. These evaluations are done before
the actual break occurs.
All OLDCV values are updated when a break occurs. The values are updated
between the printing of the TRAILER sections and the HEADER sections.
Satisfying a BREAK WHEN Condition
There are two forms of the BREAK WHEN statement; both have a control
expression. The statements differ in what changes can be specified for
the control expression.
String Control Variables. When the report is activated via BEGIN REPORT,
the value of the control expression is recorded. With each DETAIL LINE,
the current value of the control expression is compared to the recorded
value in OLDCV$. If the two values are not the same, the break level is
triggered.
After any break at the specified level, the new value of the control
expression is recorded in place of the old value, OLDCV$. This process
takes place after all trailers have been output, but before headers are
printed.
Examples
BREAK 3 WHEN Sales_Office$ CHANGES
In this example, a break at level 3 occurs whenever the control
expression Sales_Office$ changes value.
Numeric Control Variables. Numeric control expressions have an optional
BY clause in the BREAK WHEN statement. If the BY clause is not present
or evaluates to zero, the statement works exactly as it does with a
string control expression. That is, a break is triggered whenever the
control expression in OLDCV changes value.
The BY clause establishes a limit value that the control expression must
exceed before a break occurs. The numeric expression in the BY clause
determines the increment by which the limit changes after a break.
However, the limit is NOT set by adding the BY expression to the control
expression.
When a BEGIN REPORT executes, the control expression is recorded and the
BY clause is evaluated. At this time, a break limit is set up as well.
This limit is set up in the following manner:
* If the BY expression is positive, the limit is set to the multiple of
the BY clause closest to, but still greater than, the control
expression.
* If the BY expression is negative, the limit is set to the multiple of
the BY clause closest to, but still less than, the control
expression.
At each DETAIL LINE, the control expression is compared to the limit
value. If the control expression is greater than or equal to the limit
(less than or equal if BY was negative), a break is triggered. After the
trailers print, but before the headers are output, a new limit is
established using the rules above. The BY clause is not reevaluated;
only the limit is changed.
The break limit is reevaluated at any break at the BREAK WHEN level.
This can be caused by breaking at this level or a lower level from a
DETAIL LINE or a TRIGGER BREAK statement.
Examples
BREAK N WHEN Product_no CHANGES
BREAK 8 WHEN Profits CHANGES BY 100000
BREAK A(1) WHEN Sales CHANGES BY -50
In the first example, a break takes place when the control PRODUCT_NO
changes value. It does not matter how much it changes, nor whether it
gets larger or smaller.
In the second example, a break occurs when the variable PROFITS exceeds a
multiple of one hundred thousand. Assuming that PROFITS has an initial
value of 50000, the first break limit is 100000. If PROFITS then changes
to 235000, break level 8 is triggered; the next break limit is set to
300000, the next multiple larger than PROFITS.
The third example is similar to the second, except that the BY clause is
negative. If SALES has an initial value of 480, the break limit is set
to 450 (not 430). If SALES gets larger, no break ever occurs. Only when
SALES becomes 450 or less does the break occur. For example, if SALES
drops to 220, a break occurs and the new limit is set to 200. It is
important to remember that this is the multiple of a BY clause.
Control Expression Storage Requirements
The control expression for BREAK WHEN statements is kept by the OLDCV
function. The data space required to contain this expression is
determined during BEGIN REPORT, when the values are first examined. The
space for OLDCV and OLDCV$ are allocated as follows:
* For numeric variables and array elements, space is allocated based on
the data type of the variable. There should be no way to get an
error with OLDCV in this case.
* For other numeric space is allocated based on the data type returned
when the expression is initially examined. Thus, if BEGIN REPORT
finds an INTEGER expression, space is allocated for an INTEGER. If
the expression later returns a REAL outside the INTEGER range, an
error occurs.
* For other string variables and array elements, space for OLDCV$ is
allocated based on the maximum length of the string variable. Thus,
the value of the string may be shorter than the space allocated.
* For string expressions including substrings, space for OLDCV$ is
allocated based on the actual length of the evaluated expression.
This could cause a string overflow if a later evaluation returns a
longer string.
A BY clause stores two values: the BY value itself, and the limit, which
causes a break. Both of these values are stored in REAL or DECIMAL,
depending on the option in the report subunit.