AT BREAK

#### Search Results

Search

# AT BREAK

#### Structured Mode Syntax

[`AT`] `BREAK` [(r)] [`OF`] operand1 [/n/``]
statement
`END-BREAK`

#### Reporting Mode Syntax

[`AT`] `BREAK` [(r)] [`OF`] operand1 [/n/]
| statement |
`DO` statement `DOEND`

This document covers the following topics:

- AT BREAK Usage

- AT BREAK Syntax Description

- Multiple Break Levels

- AT BREAK Examples

For an explanation of the symbols used in the syntax diagram, see Syntax Symbols.

Related Statements: `ACCEPT/REJECT` | `AT START OF DATA` | `AT END OF DATA` | `BACKOUT TRANSACTION` | `BEFORE BREAK PROCESSING` | `DELETE` | `END TRANSACTION` | `FIND` | `GET` | `GET SAME` | `GET TRANSACTION DATA` | `HISTOGRAM` | `LIMIT` | `PASSW` | `PERFORM BREAK PROCESSING` | `READ` | `RETRY` | `STORE` | `UPDATE`

Belongs to Function Group: Database Access and Update

## AT BREAK Usage

The `AT BREAK` statement is used to cause the execution of one or more statements whenever a change in value of a control field occurs. It is used in conjunction with automatic break processing and is available with the following statements: `FIND`, `READ`, `HISTOGRAM`, `SORT`, `READ WORK FILE`.

The automatic break processing works as follows: Immediately after a record was read by the processing loop, the control field is checked. If a value change is detected in comparison to the previous record, the statements included in the `AT BREAK` statement block are executed. This does not apply to the very first record in the processing loop. In addition, when the processing loop is terminated (as reading of records is complete or due to an `ESCAPE BOTTOM` statement), a final execution of the statements in the `AT BREAK` statement block is triggered.

For further information, see Automatic Break Processing in the Programming Guide.

An `AT BREAK` statement block is only executed if the object which contains the statement is active at the time when the break condition occurs.

It is possible to initiate a new processing loop within an `AT BREAK` condition. This loop must also be closed within the same `AT BREAK` condition.

This statement is non-procedural (that is, its execution depends on an event, not on where in a program it is located).

Natural system functions may be used in conjunction with an `AT BREAK` statement, see Natural System Functions for Use in Processing Loops in the System Functions documentation and Example of System Functions with AT BREAK Statement in the Programming Guide.

For further information, see also the section AT BREAK Statement in the Programming Guide. It covers topics such as:

- Control Break Based on a Database Field

- Control Break Based on a User-Defined Variable

## AT BREAK Syntax Description

Operand Definition Table:

Operand | Possible Structure | Possible Formats | Referencing Permitted | Dynamic Definition
--- | --- | --- | --- | ---
`operand1` |  | S |  |  |  | A | U | N | P | I | F | B | D | T | L |  |  |  | yes | no

Syntax Element Description:

Syntax Element | Description
--- | ---
`(r)` | Reference Notation: By default, the final `AT BREAK` condition (for loop termination) is always related to the outermost active processing loop initiated with a `FIND`, `READ`, `READ WORK FILE`, `HISTOGRAM` or `SORT` statement. With the notation `(r)` you can relate the final break condition of an `AT BREAK` statement to another specific currently open processing loop (that is, the loop in which the `AT BREAK` statement is located or any outer loop). Example:
    ...
    READ ...
      FIND ...
        FIND ...
          AT BREAK ...
            FIND ...
            END-FIND
          END-BREAK
        END-FIND
      END-FIND
    END-READ
    ...
In this example, the final `AT BREAK` condition is related to the `READ` loop initiated in line 0120. It would be possible to have it related to one of the `FIND` loops initiated in line 0130 and 0140, but not to the one initiated in line 0160. If `(r)` is specified for a break hierarchy, it must be specified with the first `AT BREAK` statement and applies also to all `AT BREAK` statements which follow.
`operand1` | Control Field: The field used as the break control field is usually a database field. If a user-defined variable is used, it must be initialized prior to the evaluation of automatic break processing (see `BEFORE BREAK PROCESSING` statement). A specific occurrence of an array can also be used as a control field.
`/n/` | Notation /n/: The notation `/n/` may be used to indicate that only the first `n` positions (counting from left to right) of the control field are to be checked for a change in value. This notation can only be used with operands of format A, B, N or P. A control break occurs when the value of the control field changes, or when all records in the processing loop for which the `AT BREAK` statement applies have been processed.
`statement ...` | Statement(s) to be Executed at Break Condition: In structured mode, you must supply one or several suitable statements, depending on the situation. For an example of a statement, see Examples below.
`END-BREAK` | End of AT BREAK Statement: In structured mode, the Natural reserved word `END-BREAK` must be used to end the `AT BREAK` statement. In reporting mode, use the `DO ... DOEND` statements to supply one or several suitable statements, depending on the situation, and to end the `AT BREAK` statement. If you specify only a single statement, you can omit the `DO ... DOEND` statements. With respect to good coding practice, this is not recommended.
`statement` `DO statement ... DOEND`

## Multiple Break Levels

Multiple `AT BREAK` statements may be specified within a processing loop within the same program module. If multiple `BREAK` statements are specified for the same processing loop, they form a hierarchy of break levels independent of whether they are specified consecutively or interspersed within other statements. The first `AT BREAK` statement represents the lowest control break level, and each additional `AT BREAK` statement represents the next higher control break level.

Every processing loop in a loop hierarchy may have its own break hierarchy attached.

#### Example:

Structured Mode: | Reporting Mode:
--- | ---
       FIND ...
          AT BREAK
          ...
          END-BREAK
          AT BREAK
          ...
          END-BREAK
          AT BREAK
          ...
          END-BREAK
       END-FIND
       ...
       FIND ...
          AT BREAK
             DO
             ...
             DOEND
          AT BREAK
             DO
             ...
             DOEND
       ...

A change in the value of a control field in a break level causes break processing to be activated for that break level and all lower break levels, regardless of the values of the control fields for the lower break levels.

For easier program maintenance, it is recommended to specify multiple breaks consecutively.

See also Example 3 below and the section Multiple Control Break Levels in the Programming Guide.

## AT BREAK Examples

This section covers the following topics:

- Example 1 - AT BREAK

- Example 2 - AT BREAK Using /n/ Notation

- Example 3 - AT BREAK with Multiple Break Levels

For further examples of `AT BREAK`, see Natural System Functions for Use in Processing Loops, Examples ATBEX3 and ATBEX4.

### Example 1 - AT BREAK

    ** Example 'ATBEX1S': AT BREAK (structured mode)
    ************************************************************************
    DEFINE DATA LOCAL
    1 EMPLOY-VIEW VIEW OF EMPLOYEES
      2 CITY
      2 COUNTRY
      2 NAME
    END-DEFINE
    *
    LIMIT 10
    READ EMPLOY-VIEW BY CITY
    AT BREAK OF CITY
        SKIP 1
      END-BREAK
      DISPLAY NOTITLE CITY (IS=ON) COUNTRY (IS=ON) NAME
    END-READ
    *
    END

#### Output of Program ATBEX1S:

            CITY         COUNTRY         NAME
    -------------------- ------- --------------------

    AIKEN                USA     SENKO

    AIX EN OTHE          F       GODEFROY

    AJACCIO                      CANALE

    ALBERTSLUND          DK      PLOUG

    ALBUQUERQUE          USA     HAMMOND
                                 ROLLING
                                 FREEMAN
                                 LINCOLN

    ALFRETON             UK      GOLDBERG

    ALICANTE             E       GOMEZ

Equivalent reporting-mode example: ATBEX1R.

### Example 2 - AT BREAK Using /n/ Notation

    ** Example 'ATBEX2': AT BREAK (with /n/ notation)
    ************************************************************************
    DEFINE DATA LOCAL
    1 EMPLOY-VIEW VIEW OF EMPLOYEES
      2 DEPT
      2 NAME
    END-DEFINE
    *
    LIMIT 10
    READ EMPLOY-VIEW BY DEPT STARTING FROM 'A'
    AT BREAK OF DEPT /4/
        SKIP 1
      END-BREAK
      DISPLAY NOTITLE DEPT NAME
    END-READ
    *
    END

#### Output of Program ATBEX2:

    DEPARTMENT         NAME
       CODE
    ---------- --------------------

    ADMA01     JENSEN
    ADMA01     PETERSEN
    ADMA01     MORTENSEN
    ADMA01     MADSEN
    ADMA01     BUHL
    ADMA02     HERMANSEN
    ADMA02     PLOUG
    ADMA02     HANSEN

    COMP01     HEURTEBISE
    COMP01     TANCHOU

### Example 3 - AT BREAK with Multiple Break Levels

    ** Example 'ATBEX5S': AT BREAK (multiple break levels) (structured mode)
    ************************************************************************
    DEFINE DATA LOCAL
    1 EMPLOY-VIEW VIEW OF EMPLOYEES
      2 CITY
      2 DEPT
      2 NAME
      2 LEAVE-DUE
    1 #LEAVE-DUE-L (N4)
    END-DEFINE
    *
    LIMIT 5
    FIND EMPLOY-VIEW WITH CITY = 'PHILADELPHIA' OR = 'PITTSBURGH'
                     SORTED BY CITY DEPT
      MOVE LEAVE-DUE TO #LEAVE-DUE-L
      DISPLAY CITY (IS=ON) DEPT (IS=ON) NAME #LEAVE-DUE-L
      /*
     AT BREAK OF DEPT
        WRITE NOTITLE /
              T*DEPT OLD(DEPT) T*#LEAVE-DUE-L SUM(#LEAVE-DUE-L) /
      END-BREAK
      AT BREAK OF CITY
        WRITE NOTITLE
              T*CITY OLD(CITY) T*#LEAVE-DUE-L SUM(#LEAVE-DUE-L) //
      END-BREAK
    END-FIND
    *
    END

#### Output of Program ATBEX5:

            CITY         DEPARTMENT         NAME         #LEAVE-DUE-L
                            CODE
    -------------------- ---------- -------------------- ------------

    PHILADELPHIA         MGMT30     WOLF-TERROINE           11
                                    MACKARNESS              27

                         MGMT30                             38

                         TECH10     BUSH                    39
                                    NETTLEFOLDS             24

                         TECH10                             63

    PHILADELPHIA                                           101

    PITTSBURGH           MGMT10     FLETCHER                34

                         MGMT10                             34

    PITTSBURGH                                              34

Equivalent reporting-mode example: ATBEX5R.

### On this page

- AT BREAK Usage
- AT BREAK Syntax Description
- Multiple Break Levels
- AT BREAK Examples