BREAK.ON field ["text'code'"]
BREAK.ON and BREAK-ON are synonyms.
The BREAK.ON clause displays the values of field, and inserts a break indicator in the display at each point where the field value changes. By default, this break indicator consists of a new line with *** indicating a change in field values. You can supply a string as the break indicator.
You can specify multiple BREAK.ON clauses to insert breaks for multiple levels of sorting.
The BREAK.ON clause differs from the BREAK.SUP clause in two ways:
BREAK.ON always displays the break field values. BREAK.SUP does not display the break field values unless you specify this field as a display column.
BREAK.ON indicates a field value change either with *** (the default) or a user-specified break string. BREAK.SUP indicates a field value change with a blank line.
Multiple CMQL clauses may be specified in any order. The order of application of CMQL clauses is always the same. The BREAK.ON clause is applied after the WITH clause, the SAMPLED clause (if present), and the SAMPLE clause (if present).
The following example displays the a break indicator each time the F1 field value changes:
LIST VOC BREAK.ON F1 WHERE FILENAME >= "A"
It lists output such as the following:
VOC......... F1............. A K *** ABORT V *** AFTER K ALL K ALL.MATCH K AN K AND K ANY K ARE K AS K ASC K ASD K *** ASSIGN V
The optional "text'code'" parameter allows you to specify how BREAK.ON values are displayed. Like the HEADING codes, the outer quotes specify a literal and the inner nested quotes specify letter code characters. Both are optional.
The "text" value, if specified, is substituted for the *** default value change marker.
The 'B' letter code supplies the current field value to the HEADING clause.
The 'D' letter code suppresses the value change marker when a break occurs after a unique field value. The value change marker is displayed when there are more than one fields with the same value. If you also specify DET-SUPP, the 'D' letter code is overridden and performs no operation.
The 'L' letter code suppresses a blank line before the value change marker.
The 'P' letter code specifies that each change in the field value should force a page break. 'N' is a synonym for 'P'.
The 'S' letter code suppresses the value change marker. Changes in value are separated by a blank line.
The 'V' letter code supplies the current field value as the value change marker string.
The following example shows the use of the "text'code'" parameters:
LIST VOC BY F1 BREAK.ON F1 "New Value'PB'" HEADING "F1='B'"
In this case, the VOC is sorted by F1 values. The literal New Value replaces *** as the F1 field value change indicator. Each time the F1 field value changes, the 'P' letter code issues a page break. The 'B' letter code supplies the current F1 field value to the page header.
You can use a FMT clause to format the break on field display column. The integer specifies the width of the display column. The letters L or R specify left justification or right justification. If neither is specified, the default is left justification.
The following example shows the use of the FMT clause:
LIST VOC WITH F4 BY F4 BREAK.ON F4 "Next Value'P'" FMT "5R"
In this case, those records with F4 field values are sorted and displayed, with a break each time the F4 value changes. The FMT clause specifies a width of 5 characters, right justified. This formatting affects both the display of the F4 values and the display of the “Next Value” change marker.
BREAK.ON can be used with AVG, ENUM, PERCENT, or TOTAL to return a calculated value for each distinct field value.
The following example uses BREAK.ON with the ENUM clause to return counts of the number of occurrences of each distinct non-null value for F4, and the final count of all F4 values. The initial F4 count of 0 records indicated that there are one or more records which have no value (null) for F4:
SORT VOC BY F4 BREAK.ON F4 ENUM F4 DET-SUPP
The following example is almost identical to the previous one. The WITH clause eliminates F4 count of 0 records displayed by the previous example:
SORT VOC BY F4 WITH F4 BREAK.ON F4 ENUM F4 DET-SUPP
The following example uses two BREAK.ON clauses. The first inserts a break at each change in the F1 value, the second inserts a break at each change in the F4 value within the same F1 values:
LIST VOC BY F1 BY F4 BREAK.ON F1 BREAK.ON F4
UniData emulation BREAK.ON display differs in several details. At a New Value break, UniData provides as a break indicator an asterisk underline, then displays the breaking value underneath. When providing a total, UniData displays a “======” underline, then displays the total value underneath. UniData labels the total value with the word “TOTAL” by default.