Occurs Clause

The OCCURS clause is used to show regular repetition of a field or a group of fields in a horizontal dimension, and a line or group of lines in a vertical dimension.

Occurs Clause: Coding Rules

• The Occurs clause must not be used at the 01-level.

• You may use the Occurs clause at any of these levels:

  • Below the Line level in an elementary entry. Your field will be repeated horizontally the number of times indicated by the operand.

    

  • Below the Line level in a group entry. The whole group of fields will be repeated horizontally the number of times indicated by the operand.

    

  • At the Line level. The line will be repeated vertically the number of times indicated by the operand.

    

  • Below the 01-level but above the LINE level. The whole group of lines will be repeated vertically the number of times indicated by the operand.

    

    These four levels are known as axes. Any fields in your group can be repeated in this way on any of the four axes, and you may have repetition on up to four axes by nesting the OCCURS clauses. Each of your report groups may have any number of OCCURS clauses, provided that the nesting limit of four is never exceeded at any one time.

  • You may use STEP, WIDTH, or DEPTH to specify the distance between the start of successive repetitions. Its operand indicates the number of columns or lines between the start of one item and the start of its successor:

    

    Integer-3 of the STEP phrase must be at least as large as the field itself. WIDTH and DEPTH are alternative keywords with the same meaning as STEP. WIDTH may be used only in the horizontal direction and DEPTH may be used only in the vertical direction. You can write the documentary words COLUMNS or LINES after integer-3 to make the direction explicit. The STEP, WIDTH, or DEPTH phrase may be coded anywhere within the entry.

  • A STEP phrase is expected if your repeating entry is absolute. (It is absolute if you write COLUMN integer or LINE integer or, in the case of a group field, if the first COLUMN or LINE in the group is absolute.) However, if you omit STEP, a minimum value will be assumed, equal to the (maximum) size of the report field, with a cautionary message.

  • If your field is relative, the STEP phrase is optional. If you omit it the distance between repetitions is the physical size of the field, which may vary at run time if there are "<" PICTURE symbols or if the field is a group field containing entries with a PRESENT WHEN clause.

  • As the examples above illustrate, the VALUE clause is allowed within an entry subject to an OCCURS clause.

  • You must code the DEPENDING ON phrase if the number of occurrences is variable. The expression can be any COBOL numeric identifier or arithmetic expression that has an integer value. The data items used in your expression can come from anywhere in your program. They need not appear elsewhere as report fields and need not reside in the same "record" as the SOURCE fields.

  • Integer-1 in the format above and the TO keyword are used only in conjunction with DEPENDING ON. Integer-1 must be less than integer-2 and may be zero. If you omit integer-1 TO and write OCCURS integer-2 TIMES DEPENDING ON, this is taken to mean OCCURS 0 TO integer-2 TIMES DEPENDING ON.

Occurs Clause: Operation

• You should use the OCCURS clause for source-code reduction when you need to obtain automatic repetition either horizontally or vertically within a report group. The effect is as though you had coded every entry individually.

• You may use a single-operand VALUE to place the same contents in each repetition.

• If you use a SOURCE clause within an entry subject to OCCURS, the same SOURCE operand will be used to set up each occurrence. However, you may allow the effective SOURCE operand to vary by use of the VARYING clause and making use of the VARYING data-name as its subscript or as a term in the SOURCE operand. (See VARYING clause for full details and examples.)

• You may also use a multiple SOURCES (see SOURCE clause) or multiple VALUES (see Multiple VALUES) to place different contents in each repetition. The following sample layout shows both methods of combining both SOURCE and VALUE clauses with OCCURS:

  

  Notice how the series of row-heading items (NORTH, EAST, etc.) is handled: the enclosing OCCURS at the LINE level simply steps through each item in the series in turn.

• If a PRESENT WHEN clause is coded in the same entry as an OCCURS clause, the PRESENT WHEN applies separately to each occurrence. If the STEP phrase is not used, an entry that is ABSENT will not take up any space, as in the case below where non-negative values are to be skipped:

  

  The effect is similar in the horizontal direction:

  

  However, if a STEP phrase is used, the spacing - in whichever direction - is regular and even entries that are ABSENT take up their usual space:

  

Use of Occurs...Depending On

• If your report group has an OCCURS clause with a DEPENDING ON phrase, report writer will evaluate the associated identifier or expression at run time on each separate occasion when the report group is about to be generated. If its value is outside the range of integer-1 TO integer-2 in your OCCURS clause, this is not an error condition, and report writer will assume the maximum number, integer-2.

• Now that the actual number of repeats is known, report writer creates only that number of occurrences, treating your clause as though you had written a fixed OCCURS clause with that number as the integer. This is an important notion. Here are some of its consequences:

  • If your OCCURS ... DEPENDING is in the horizontal direction and is followed by an absolute COLUMN clause, the space not filled by excess occurrences will be blank:

    

  • If your OCCURS ... DEPENDING is in the horizontal direction and is followed by a relative COLUMN, it is positioned relative to the last actual occurrence:

    

  • If your OCCURS ... DEPENDING is in the vertical direction and is followed by an absolute LINE, excess occurrences will be blank:

    

  • If your OCCURS ... DEPENDING is in the vertical direction and is followed by a relative LINE, no line positions will be occupied by the unused occurrences, and the line that follows will be relative to the last actual occurrence.

    

    The page-fit test allows only for the occurrences that are actually present. So, if the group as a whole is relative, you will have a "best fit". For instance, if you GENERATE the above group and only three lines are available to it, the group will fit on the page.

  • You may code several entries with OCCURS ... DEPENDING in the same report line and nest horizontal and vertical repetitions to produce many varied and useful effects. The DEPENDING expression is re-evaluated each time the item is about to be output, so you may alter the size and shape of your report fields dynamically and automatically. You may also use OCCURS ... DEPENDING in a horizontal or vertical group entry.

Compatibility

The use of the OCCURS clause in the report section, and the optional phrases, are unique to new Report Writer.