Caché MultiValue Query Language (CMQL) Reference
BREAK.ON clause
[Back] [Next]
   
Server:docs2
Instance:LATEST
User:UnknownUser
 
-
Go to:
Search:    

Indicates changes of values with indicator string.
Synopsis
BREAK.ON field ["text'code'"]
Description
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:
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 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
Emulation
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.