access.break-on Modifier/Access: Verbs

access.break-on

Command access.break-on Modifier/Access: Verbs
Applicable release versions: AP, R83
Category Access: Verbs (152)
Description creates a visual "break" in output data when the value in the current output field is different from the previous value.

The "break-on" modifier groups items in a listing according to the value of the break-on attr.name(s). attr.name indicates the attribute on which a break will occur.

During the list or sort operation, a control-break occurs whenever there is a change in the value of the specified attribute. Value comparison is made on a left-to-right, character-by-character basis, with a maximum of the first 24 characters being used in the comparison only.

When a control-break occurs, it prints a preceding blank line, a line with three asterisks (***) displayed in the break-on attribute column (i.e., the attribute whose value has changed, thus causing the break), and a following blank line. If the optional text string is specified, the processed text string will be substituted for the asterisks.

Up to 15 control-breaks may be specified, the hierarchy of the breaks being specified by the sequence of the break-on modifiers in the Access sentence, the first being the highest level.

For multiple control-breaks, output proceeds from the lowest level break to the highest level. The data associated with the lowest level control-break are printed on the current page (even if the end of the page has been reached). If multiple breaks occur, normal pagination proceeds on the second and subsequent data lines, unless an option prevents this.

Headings and output control options may be specified for control-breaks. A user-generated heading can be specified to be printed in place of the default control break heading ("***") by following the break-on attr.name with the desired heading, enclosed in double quote marks ("). Within the heading, output control options may be specified, enclosed in single quote marks ('). The text, if specified, replaces the default asterisk field ("***") in the attr.name column when the control-break printout line occurs.

If the "det-supp" modifier is specified in the sentence, then the attribute value will display on the break line, unless a text string was specified.

Options are used to modify some of the actions taken at control-break time, and are specified as one or more characters. If options are used without accompanying text, they must be enclosed in single quotes within double quotes (e.g., "'v'" ).

If the "total" modifier is specified in the sentence, subtotals are also output at each control break, as well as columnar totals.

The data associated with the break-on attribute may be suppressed in the detail lines by using a max length of zero in the attribute-defining item (line 10 in the attribute-defining item). If suppression of the data associated with the control break is desired at total time, it must be done with an f;"" in attribute 7 (the output-conversion attribute) of the attribute-defining item associated with the control break.

In generating the value for comparison, correlatives in the attribute-defining item are processed but conversions are not.
Syntax break-on attr.name {"{text}{'options'}"}
Options b Outputs the value causing the break in either the heading or footing output field where the 'b' option is found in the heading or footing option string. It is not meaningful to specify this option within more than one break-on specification.

d Suppresses the break data line if only one detail line has been output since the last control break.

l Suppresses the blank line preceding the break data line. This option is ignored when the 'u' option is used.

n Resets the page counter to one on each break.

p Issues a form feed (page eject) after the data associated with this break has been output.

r Inhibits page "rollover". Outputs any occurrence of one or more control break lines at the end of the page, rather than at the top of the next page, thus forcing all the data associated with this break to be current on the same page.

u Underlines all total fields.

v Outputs the value causing the control break in the break-on label.

'' (two single quotes) Inserts a single quote in text.
Example
sort invoices by date break-on date 

sort sales by salesman break-on salesman "'bp'"
Purpose
Related access.by-dsnd
access.by
access.det-supp
processing.codes
access.attr.name
access.total
access.roll-on
access.modifiers
access.footing
basic.footing
basic.heading