Coding Report Group Descriptions

A Report Group Description is a REPORT SECTION data structure beginning with an 01-level entry and including any number of lower entries. It may consist of the 01-level report group entry only. You may code any number of Report Group Descriptions after your RD entry.

report group coding

where report-group-entry is defined as follows:

report group entry

Report Groups: Coding Rules

Level-numbers are used, as in any DATA DIVISION record, to establish a hierarchy of group levels above the elementary level. The level-number at the start of each report group must be 01. (It may be written without the leading 0, but we shall still refer to it as the 01-level.) Choose your lower level-numbers exactly as you would for any other COBOL logical record. (Note that OS/VS and DOS/VS COBOL Report Writer uses the TYPE, LINE, and COLUMN clauses themselves, rather than the level-numbers, to establish hierarchy.
You need not place data-names on your report group entries except in the following cases, where they are required:
- On the 01-level entry of a DETAIL group, or any other group that may be referred to in the USE BEFORE REPORTING header of a Declarative SECTION (see USE BEFORE REPORTING directive). When a data-name is used at the 01-level, it gives a name to the entire report group and is called the report-group-name or group-name. The group-name must be unique within an RD, but you may re-use the name in another RD.
- On a numeric entry referred to in a SUM clause or term. (See SUM clause.)
On any entry at any level that is referred to in a COUNT clause or term. (See COUNT clause.)

In all other cases it is preferable to omit data-names since an unnecessary dataname may mislead the program-reader into thinking that it is referred to in one of the ways above. It may also impede the precompiler's optimization. Data-names may be DBCS
The following general-purpose DATA DIVISION clauses can be used in a report group. The first four may be used at both group and elementary levels (not the 01 -level in the case of OCCURS). PICTURE and VALUE are allowed only at the elementary level.
- Blank when Zero
- Just/Justified
- Occurs
- Sign
- Pic/Picture
- Value/Values
But the following cannot be used in a report group:
- only Usage other than Display, such as Computational
- Redefines
- Synchronized/Sync
- Renames
- 88-level entries
In addition to the general DATA DIVISION clauses, report groups may contain special-purpose clauses that describe the position and contents of fields. The first four clauses, TYPE, NEXT GROUP, GROUP LIMIT, and REPEATED, can appear only at the 01-level. The special-purpose clauses are:
- Type - indicates the type of group
- Next Group - creates extra space between groups
- Group limit - gives a special lower limit for the group
- Repeated - places groups side-by-side
- Line - gives the vertical position
- Multiple page - enables a report group to span several pages
- Column - gives the horizontal position
- Source - used to capture a data field by name
- Sum - used to produce a total
- Count - used to produce a count
- Function - invokes a special formatting routine
- Wrap - allows data to continue on a new line
- Varying - provides conters for a repeating entry
- Style - produces special printer effects
- Present/Absent when/after - controls whether or not an item, line or group is output
- Group indicate - an older form of Present After
The clauses PICTURE, COLUMN, SOURCE, VALUE, SUM, COUNT, and FUNCTION can appear only at the elementary level.
For every entry with a COLUMN clause, there must be a LINE clause either at the same level as or at a higher level. If a given report line contains only one elementary field (and provided the entry is not a multiple-choice entry, see PRESENT WHEN clause), you may combine the LINE and the COLUMN clauses in the same entry, for instance:

03 LINE 5 COL 60 VALUE "QUARTERLY REPORT"

There is no limit to the number of elementary fields a report line may contain. If the report line contains several elementary fields, you must code all the COLUMN entries within the line at a lower level than the LINE entry, for example:
```
  03 LINE 5.
   05 COL 60 VALUE "QUARTERLY REPORT".
   05 COL 90 VALUE "1997".
```
Not all the COLUMN clauses within a LINE need be at the same level, since some or all elementary entries might be contained within non-LINE group entries; for example:
```
 03 LINE 5.
   05 COL 60 VALUE "QUARTERLY REPORT".
   05 PRESENT WHEN YEAR NOT = SPACES.
     07 COL 90 VALUE "YEAR:".
     07 COL +2 PIC X(4) SOURCE YEAR.
```
A LINE clause must not be subordinate to another LINE clause. (If this rule is violated, the nested LINE entries will be treated as though they were defined at the same level as the first.)
If a given report group contains several lines, you must give all the LINE entries in that group a level-number other than 01. If the group contains only a single report line, you may code the LINE clause in the 01-level entry; for instance:
```
01 ORDER-LINE TYPE DE LINE + 1.
     05 ...`
```
You may choose only one of five clauses: SOURCE, VALUE, SUM, COUNT, and FUNCTION to supply the contents of an elementary item automatically, bearing in mind that SOURCE or VALUE can be repeated several times in a multiple-choice entry (see The Multiple-Choice Form), and SUM (see SUM clause) or COUNT (see COUNT clause) can be used as special operators in terms in an arithmetic expression (see SOURCE clause).
If there is no SOURCE, VALUE, SUM/COUNT, or FUNCTION clause in an elementary item, the following conditions must be met:
- The entry must have a data-name (following the level-number).
- The entry must have a COLUMN clause.
- If the COLUMN clause is relative, the item must have a fixed horizontal position (that is, it must follow an item with a fixed end-column, unless it is first in the line).
The item must have a PICTURE with none of the features that are unique to the REPORT SECTION (that is, "<" or ">" symbols or general insertion characters). Report writer will then expect you to fill in the report field independently with some COBOL procedural statement.

As an example, in the following case: 05 R-PRIOR-CUST-NO COL 20 PIC 9(7).

the only way this item can receive a value is through a COBOL MOVE, ADD, ACCEPT, or other procedural statement, which is outside the scope of report writer and is left to you. Report writer will ensure that the report field is not overwritten by any other field, so any value stored in the item R-PRIOR-CUST-NO will remain there and will appear whenever the enclosing group is produced. Note that you should not attempt to change the value of a group field, such as a report line, in this way.
You may code the clauses of any report group entry in any order, except in the case of a multiple-choice entry, where each SOURCE, VALUE, or FUNCTION operand is immediately followed by WHEN condition. Details of this combination are given later (see PRESENT AFTER clause).
However, you may code the SUM clause more than once in the same entry. You may also code a SOURCE, VALUE, or FUNCTION clause and its associated PRESENT/ABSENT WHEN/AFTER clause more than once in a multiple-choice entry. All other clauses may appear no more than once in an entry.

Compatibility

The COUNT, GROUP LIMIT, VARYING, PRESENT/ABSENT WHEN/AFTER, FUNCTION, REPEATED, MULTIPLE PAGE, STYLE, and WRAP clauses are provided by new Report Writer only.
Only new Report Writer allows the SIGN clause in the REPORT SECTION.
Only new Report Writer allows the BLANK WHEN ZERO and JUSTIFIED clauses in a group entry.
OS/VS and DOS/VS COBOL do not use level-numbers, apart from 01-level, to establish hierarchy and rely instead on the keywords TYPE, LINE, and COLUMN.
OS/VS and DOS/VS COBOL allow just three hierarchic levels within the Report Group descriptions.
OS/VS and DOS/VS COBOL do not permit REPORT SECTION entries to be the subject of non-Report Writer procedural statements.