Debug Module

Chapter 1: Report Writer

The Report Writer is a special purpose feature which places its emphasis on the organization, format, and contents of an output report. Although a report can be produced using the standard COBOL language, the Report Writer language features provide a more concise facility for report structuring and report production. Much of the Procedure Division programming which would normally be supplied by the programmer is instead provided automatically by the Report Writer Control System (RWCS). Thus the programmer is relieved of writing procedures for moving data, constructing print lines, counting lines on a page, numbering pages, producing heading and footing lines, recognizing the end of logical data subdivisions, updating sum counters, and so on. All these operations are accomplished by the RWCS as a consequence of source language statements that appear primarily in the report section of the data division of the source program.

Although it is a part of the standard COBOL definition, this module is explicity excluded from the X/Open COBOL language definitions and should not be used in a conforming X/Open COBOL source program.

The OS/VS COBOL compiler provides support for Report Writer that is based on the ANSI'68 Standard (even when the mainframe LANGLVL(2) compiler option is used - which normally requests ANSI'74 support). However, there are many cases in which that compiler actually supports a cross between the two COBOL Standards. Therefore, you should not attempt to use your COBOL system with OS/VS COBOL emulation along with any other dialect.

Within this chapter, many of these OS/VS COBOL extensions are indicated by an OSVS bubble. However, for the exact rules for the OS/VS COBOL Report Writer syntax, you should refer to your IBM OS/VS COBOL Language Reference.

1.1 Report Section

The Report Section of a COBOL Data Division contains one or more Report Description entries (RD entries), each of which forms the complete description of a report.

The report named in the RD entry is not assigned directly to an output file. Instead, it is associated with a file-name in the File Section and that file-name is associated with a file when an OPEN statement specifying the file-name is executed. More than one report can be associated with the same file-name and the CODE clause is used to differentiate among the reports. For an external file connector referenced by a file-name, separately compiled programs can specify different reports for the same file-name. This file description entry must specify the name of a report description entry for each report associated with that file-name in this program.

The RD entry contains a set of clauses that names the report and supplies specific information about the format of the printed page and the organization of the subdivisions of the report. An identification code can be given in the RD entry so that each report can be identified separately in an intermediate output file.

Following each RD entry are one or more 01 level-number entries, each followed by a hierarchical structure similar to COBOL record descriptions. Each 01 level-number entry and its subordinate entries describes a report group. Each report group consists of one or more print lines that are regarded as a unit. A report group that is to be printed is printed entirely on one logical page; it is never split across pages.

1.1.1 Report Structure

When structuring a report, major consideration must be given to vertical and horizontal spacing requirements, manipulation of data, and the physical and logical subdivisions of a report.

1.1.1.1 Vertical Spacing

The Report Writer feature allows the user to describe report groups containing multiple lines. The vert ical positioning of the lines on a page is specified by the LINE NUMBER clause that is associated with each line. The NEXT GROUP clause indicates how many lines to space after presenting the last line of the group. The first LINE NUMBER clause of the next group indicates additional spacing information to be used in positioning of that group.

1.1.1.2 Horizontal Spacing

The Report Writer allows the user to position the fields of data on a report line by means of the COLUMN NUMBER clause. The RWCS supplies space fill between all defined fields.

1.1.1.3 Data Manipulation

When the Report Writer feature is used, data movement to a report group is directed by report section clauses rather than Procedure Division statements. The report section clauses that affect the manipulation of data are the SOURCE, SUM, and VALUE clauses.

The SOURCE clause specifies the sending data item of an implicit MOVE statement. The receiving printable item is defined by the description of the report group item in which the SOURCE clause appears.

The SUM clause automatically causes the establishment of a sum counter. The object of the SUM clause names the data item(s) which are added to the sum counter when a GENERATE statement is executed. The moving of the sum counter contents to the receiving printable item, defined by the description of the report group item in which the SUM clause appears, is accomplished automatically when that report group is presented.

The VALUE clause defines a literal that appears in the printable item of a report group each time that report group is to be presented.

In summary, a data item in a report group is presented only if it has a COLUMN NUMBER clause specifying where it is to be presented. The value that is placed in a printable item is determined by the SOURCE, SUM, or VALUE clause stated in the report group description. Under no circumstances can a report group printable item receive a value directly via a Procedure Division statement.

1.1.2 Report Subdivisions

The physical and logical organization of a report interact to determine what is presented on a page.

1.1.2.1 Physical Subdivision of a Report

The PAGE clause specifies the length of the page, the size of the heading and footing areas, and the size of the area in which the detail lines will appear. The RWCS uses the LINE NUMBER and NEXT GROUP clauses to position these report groups, and when necessary, to advance to a new page with automatic production of PAGE HEADING and PAGE FOOTING report groups.

1.1.2.2 Logical Subdivisions of a Report

DETAIL report groups can be structured into a nested set of control groups. Each control group can begin with a CONTROL HEADING report group and end with a CONTROL FOOTING report group.

When nested control groups are defined, the recognition of a change in value of a control data item in a control hierarchy is called a control break and the heading and footing lines associated with the control data-name are called CONTROL HEADING and CONTROL FOOTING report groups.

During the execution of a GENERATE statement, the RWCS uses the control hierarchy to check automatically for control breaks. If a control break has occurred, all controls that are minor to it are considered to have changed, even though they may not in fact have changed. The occurrence of a control break causes the following sequence of events to take place:

1. ALL CONTROL FOOTING report groups are presented up to and including the one at the level at which the control break occurred.

2. ALL CONTROL HEADING report groups are presented from the control break level down to the most minor control.

3. The DETAIL report group named in the GENERATE statement is presented.

1.1.2.3 Procedure Division Report Writer Statements

The Report Writer statements that appear in the Procedure Division are: INITIATE, GENERATE, TERMINATE, SUPPRESS, and USE BEFORE REPORTING.

The INITIATE statement causes the RWCS to perform automatically a number of initialization functions. A report must be initiated before any detail processing can take place.

The GENERATE statement which specifies a data-name causes the named DETAIL report group to be formatted and written to the output device. In addition, it triggers the RWCS to perform the many implicit actions described in the preceding section.

The GENERATE statement which specifies a report-name provides a means of summary reporting. A report produced by this type of statement has all detail print lines suppressed automatically and consists of only the summary totals accumulated during the processing of the DETAIL report group. The RWCS processing for a GENERATE report-name statement is identical to that which occurs for a GENERATE data-name statement, except that the former results in the suppression of detail print lines.

The TERMINATE statement causes the RWCS to perform all of the automatic functions associated with the termination of a report. The TERMINATE statement must be executed before the file containing the report is closed.

The SUPPRESS statement provides the object time facility to suppress the printing of an entire report group.

The BEFORE REPORTING phrase of the USE statement provides a mechanism whereby Procedure Division statement can be executed at specific instances in the automatic procedures performed by the RWCS. The statements in the USE BEFORE REPORTING procedure can alter the contents of the data items that are referenced by SOURCE clauses. Thus control is possible over the contents of data items referenced in report groups that are produced automatically.

1.2 Language Concepts

1.2.1 Report File

A report file is an output file having sequential organization. A report file has a file description entry containing a REPORT clause. The content of a report file consists of records that are written under control of the RWCS.

A report file is named by a file control entry and is described by a file description entry containing a REPORT clause. A report file is referred to and accessed by the OPEN, GENERATE, INITIATE, SUPPRESS, TERMINATE, USE BEFORE REPORTING, and CLOSE statements.

1.2.2 Special Register PAGE-COUNTER

The reserved word PAGE-COUNTER is a name for a page counter that is generated for each RD entry in the report section of the Data Division. The implicit description is PIC 9(6) BINARY. The value in PAGE-COUNTER is maintained by the RWCS and is used by the program to number the pages of a report. PAGE-COUNTER can be referenced only in the SOURCE clause of the Report Section and in Procedure Division statements. (See the section PAGE-COUNTER Rules later in this chapter.)

1.2.3 Special Register LINE-COUNTER

The reserved word LINE-COUNTER is a name for a line counter that is generated for each RD entry in the report section of the data division. The implicit description is PIC 9(6) BINARY. The value in LINE-COUNTER is maintained by the RWCS, and is used to determine the vertical positioning of a report. LINE-COUNTER can be referenced only in the SOURCE clause of the report section and in Procedure Division statements; however, only the RWCS can change the value of LINE-COUNTER. (See the section LINE-COUNTER Rules later in this chapter.)

1.2.4 Special Register PRINT-SWITCH

The reserved word PRINT-SWITCH is a name for a register whose value may be set to non-zero in the course of a USE BEFORE REPORTING declarative procedure. This has the effect of suppressing printing of the corresponding report group.

1.2.5 Subscripting

In the Report Section, neither a sum counter nor the special registers LINE-COUNTER and PAGE-COU NTER can be used as a subscript.

1.3 Environment Division in the Report Writer Module

1.3.1 Input-Output Section

Information concerning the Input-Output Section is located in the chapter Program Definition in your Language Reference.

1.3.2 The File-Control Paragraph

Information concerning the FILE-CONTROL paragraph is located in the chapter Program Definition in your Language Reference.

Function

The file-control entry declares the relevant physical attributes of a report file.

Additional Syntax Rules

1. The OPTIONAL phrase applies only to a report opened in the extend mode. Its specification is required for a report file that is not necessarily present each time the object program is executed.

2. A report file must have sequential organization. Each report file specified in the SELECT clause must have a file description entry containing a REPORT clause in the Data Division of the same program.

1.3.3 The I-O-Control Paragraph

Information concerning the I-O-Control paragraph is located in the chapter Program Definition in your Language Reference.

Additional Syntax Rules

1. A report file can not appear in a SAME clause for which the RECORD phrase is specified.

1.4 Data Division in the Report Writer Module

1.4.1 The File Description Entry

The file description entry furnishes information concerning the physical structure, identification, and record-names pertaining to a given file.

It determines the internal or external attributes of a file connector, of the associated data records, and of the associated data items. The file description entry also determines whether a file-name is a local name or a global name.

General Format

Syntax Rules

1. The level indicator FD identifies the beginning of the file description entry for a report file and must precede the file-name of the report file.

2. The clauses which follow file-name-1 can appear in any order.

3. File-name-1 can only reference a sequential file.

4. No record description entries can follow the file description entry for a report file.

   Record description entries are permitted.

5. The subject of a file description entry that specifies a REPORT clause can be referenced in the procedure division only by the USE statement, the CLOSE statement, or the OPEN statement with the OUTPUT or EXTEND phrase.

General Rules

1. With the exception of the REPORT clause, all clauses in the file description entry for a report file are presented in the sequential I-O module.

2. Details on the REPORT clause are presented below.

1.4.2 The REPORT Clause

The REPORT clause specifies the names of reports that comprise a report file.

General Format

Syntax Rules

1. Each report-name specified in a REPORT clause must be the subject of a RD entry in the report section of the same program. The order of appearance of the report-names is not significant.

2. A report-name must appear in only one REPORT clause.

   A report-name can appear in two REPORT clauses.

3. The subject of a file description entry that specifies a REPORT clause can be referenced in the procedure division only by the USE statement, the CLOSE statement, or the OPEN statement with the OUTPUT or EXTEND phrase.

General Rules

1. The presence of more than one report-name in a REPORT clause indicates that the file contains more than one report.

2. After execution of an INITIATE statement and before the execution of a TERMINATE statement for the same report file, the report file is under the control of the RWCS. While a report file is under the control of the RWCS, no input-output statement can be executed which references that report file.

3. If the associated file connector is an external file connector, every file description entry in the run unit which is associated with that file connector must describe it as a report file.

1.4.3 Report Section

The Report Section is located in the Data Division of a source program. The Report Section describes the reports to be written onto report files. The description of each report must begin with a RD entry and be followed by one or more report group description entries.

General Format

1.4.3.1 Report Description Entry

In addition to naming the report, the RD entry defines the format of each page of the report by specifying the vertical boundaries of the region within which each type of report group can be printed. The RD entry also specifies the control data items. When the report is produced, changes in the values of the control data items cause the detail information of the report to be processed in groups called control groups.

Each report named in the REPORT clause of a file description entry in the file section must be the subject of a RD entry in the report section. Furthermore, each report in the report section must be named in one and only one file description entry.

1.4.3.2 Report Group Description Entry

The rep ort groups that will comprise the report are described following the RD entry. The description of each report group begins with a report group description entry; that is an entry that has a 01 level-number and a TYPE clause. Subordinate to the report group description entry, there can appear group and elementary entries that further describe the characteristics of the report group.

1.4.4 The Report Description Entry

The RD entry names a report, specifies any identifying characters to be appended to each print line in the report and describes the physical structure and organization of that report.

It also determines whether a report-name is a local name or a global name.

General Format

Syntax Rules

1. Report-name-1 must appear in one and only one REPORT clause.

2. The order of appearance of the clauses following report-name-1 is immaterial.

3. Report-name-1 is the highest permissible qualifier that can be specified for LINE-COUNTER, PAGE-COUNTER, and all data-names defined in the report section.

General Rules

1. The CODE clause, the CONTROL clause, and the PAGE clause are resented in alphabetical order below.

2. If the RD entry contains the GLOBAL clause, the special registers LINE-COUNTER and PAGE-COUNTER are global names.

1.4.5 PAGE-COUNTER Rules

1. PAGE-COUNTER is the reserved word used to reference a special register that is automatically created for each report specified in the report section. (See the section Special Register PAGE-COUNTER earlier in this chapter.)

2. In the report section, a reference to PAGE-COUNTER can appear only in a SOURCE clause. In the Procedure Division, PAGE-COUNTER can be used in any context in which a data item with an integer value can appear.

3. If more than one PAGE-COUNTER exists in a program, PAGE-COUNTER must be qualified by a report-name whenever it is referenced in the Procedure Division.

   In the report section an unqualified reference to PAGE-COUNTER is qualified implicitly by the name of the report in whose RD entry the reference is made. Whenever the PAGE-COUNTER of a different report is referenced, PAGE-COUNTER must be explicitly qualified by the report-name associated with the different report.

4. Execution of the INITIATE statement causes the RWCS to set the PAGE-COUNTER of the referenced report to one.

5. PAGE-COUNTER is automatically incremented by one each time the RWCS executes a page advance.

6. PAGE-COUNTER can be altered by Procedure Division statements.

1.4.6 LINE-COUNTER Rules

1. LINE-COUNTER is the reserved word used to reference a special register that is automatically created for each report specified in the Report Section. (See the section Special Register LINE-COUNTER earlier in this chapter.)

2. In the report section a reference to LINE-COUNTER can appear only in a SOURCE clause. In the Procedure Division, LINE-COUNTER can be used in any context in which a data item with an integral value can appear. However, only the RWCS can change the content of LINE-COUNTER.

3. If more than one LINE-COUNTER exists in a program, LINE-COUNTER must be qualified by a report-name whenever it is referenced in the Procedure Division.

   In the Report Section an unqualified reference to LINE-COUNTER is qualified implicitly by the name of the report in whose description entry the reference is made. Whenever the LINE-COUNTER of a different report is referenced, LINE-COUNTER must be explicitly qualified by the report-name associated with the different report.

4. Execution of an INITIATE statement causes the RWCS to set the LINE-COUNTER of the referenced report to zero. The RWCS also automatically resets LINE-COUNTER to zero each time it executes a page advance.

5. The value of LINE-COUNTER is not affected by the processing of nonprintable report groups nor by the processing of a printable report group whose printing is suppressed by means of the SUPPRESS statement.

6. At the time each print line is presented, the value of LINE-COUNTER represents the line number on which the print line is presented. The value of LINE-COUNTER after the presentation of a report group is governed by the presentation rules for the report group. (See the section Presentation Rules Tables later in this chapter.)

1.4.7 The CODE Clause

The CODE clause specifies a two-character literal that identifies each print line as belonging to a specific report.

General Format

Syntax Rules

1. Literal-1 must be a two-character nonnumeric literal.

   Literal-1 may be replaced by a mnemonic-name specified in the special-names paragraph. See the OS/VS COBOL Language Reference for additional details.

2. If the CODE clause is specified for any report in a file, it must be specified for all reports in that file.

General Rules

1. When the CODE clause is specified, literal-1 is automatically placed in the first two character positions of each report writer logical record.

2. The positions occupied by literal-1 are not included in the description of the print line, but are included in the logical record size.

1.4.8 The CONTROL Clause

The CONTROL clause establishes the levels of the control hierarchy for the report.

General Format

Syntax Rules

1. Data-name-1 must not be defined in the Report Section. Data-name-1 can be qualified.

2. Each recurrence of data-name-1 must identify a different data item.

3. Data-name-1 must not have subordinate to it a variable occurrence data item.

General Rules

1. Data-name-1 and the word FINAL specify the levels of the control hierarchy. FINAL, if specified, is the highest control, data-name-1 is the major control, the next recurrence of data-name-1 is an intermediate control, and so on. The last recurrence of data-name-1 is the minor control.

2. The execution of the chronologically first GENERATE statement for a given report causes the RWCS to save the values of all control data items associated with that report. On subsequent executions of all GENERATE statements for that report, control data items are tested by the RWCS for a change of value. A change of value in any control data item causes a control break to occur. This control break is associated with the highest level for which a change of value is noted. (See the section The GENERATE Statement later in this chapter.)

3. The RWCS tests for a control break by comparing the content of each control data item with the prior content of each control data item that was saved when the previous GENERATE statement for the same report was executed. The RWCS applies the inequality relation test as follows:
   1. If the control data item is a numeric data item, the relation test is for the comparison of two numeric operands.

   2. If the control data item is an index data item, the relation test is for the comparison of two index data items.

   3. If the control data item is a data item other than as described in 3a and 3b above, the relation test is for the comparison of two nonnumeric operands.

   The inequality relation test is further explained in the appropriate paragraph. (See the chapter Program Definition in your Language Reference.)

4. FINAL is used when the most inclusive control group in the report is not associated with a control data-name.

1.4.9 The PAGE Clause

The PAGE clause defines the length of a page and the vertical subdivisions within which rep ort groups are presented.

General Format

Syntax Rules

1. The HEADING, FIRST DETAIL, LAST DETAIL, and FOOTING phrases can be written in any order.

2. Integer-1 must not exceed three significant digits in length.

3. Integer-2 must be greater than or equal to one.

4. Integer-3 must be greater than or equal to integer-2.

5. Integer-4 must be greater than or equal to integer-3.

6. Integer-5 must be greater than or equal to integer-4.

7. Integer-1 must be greater than or equal to integer-5.

8. The following rules indicate the vertical subdivision of the page in which each type of report group can appear when the PAGE clause is specified. (See the section Page Regions later in this chapter.)
   1. A report heading report group that is to be presented on a page by itself, if defined, must be defined such that it can be presented in the vertical subdivision of the page that extends from the line number specified by integer-2 to the line number specified by integer-1, inclusive.

      A report heading report group that is not to be presented on a page by itself, if defined, must be defined such that it can be presented in the vertical subdivision of the page that extends from the line number specified by integer-2 to the line number specified by integer-3 minus 1, inclusive.

   2. A page heading report group, if defined, must be defined such that it can be presented in the vertical subdivision of the page that extends from the line number specified by integer-2 to the line number specified by integer-3 minus 1, inclusive.

   3. A control heading or detail report group, if defined, must be defined such that it can be presented in the vertical subdivision of the page that extends from the line number specified by integer-3 to the line number specified by integer-4, inclusive.

   4. A control footing report group, if defined, must be defined such that it can be presented in the vertical subdivision of the page that extends from the line number specified by integer-3 to the line number specified by integer-5, inclusive.

   5. A page footing report group, if defined, must be defined such that it can be presented in the vertical subdivision of the page that extends from the line number specified by integer-5 plus 1 to the line number specified by integer-1, inclusive.

   6. A report footing report group that is to be presented on a page by itself, if defined, must be defined such that it can be presented in the vertical subdivision of the page that extends from the line number specified by integer-2 to the line number specified by integer-1, inclusive.

      A report footing report group that is not to be presented on a page by itself, if defined, must be defined such that it can be presented in the vertical subdivision of the page that extends from the line number specified by integer-5 plus 1 to the line number specified by integer-1, inclusive.

9. All report groups must be described such that they can be presented on one page. The RWCS never splits a multi-line report group across page boundaries.

General Rules

1. The vertical format of a report page is established using the integer values specified in the PAGE clause.
   1. Integer-1 defines the size of a report page by specifying the number of lines available on each page.

   2. HEADING integer-2 defines the first line number on which a report heading or page heading report group can be presented.

   3. FIRST DETAIL integer-3 defines the first line number on which a body group can be presented. Report heading and page heading report groups cannot be presented on or beyond the line number specified by integer-3.

   4. LAST DETAIL integer-4 defines the last line number on which a control heading or detail report group can be presented.

   5. FOOTING integer-5 defines the last line number on which a control footing report group can be presented. Page footing and report footing report groups must follow the line number specified by integer-5.

2. If the PAGE clause is specified the following implicit values are assumed for any omitted phrases:
   1. If the HEADING phrase is omitted, a value of one is assumed for integer-2.

   2. If the FIRST DETAIL phrase is omitted, a value equal to integer-2 is given to integer-3.

   3. If the LAST DETAIL and the FOOTING phrases are both omitted, the value of integer-1 is given to both integer-4 and integer-5.

   4. If the FOOTING phrase is specified and the LAST DETAIL phrase is omitted, the value of integer-5 is given to integer-4.

   5. If the LAST DETAIL phrase is specified and the FOOTING phrase is omitted, the value of integer-4 is given to integer-5.

3. If the PAGE clause is omitted, the report consists of a single page of indefinite length.

4. The presentation rules for each type of report group are specified in the appropriate paragraph. (See the section Presentation Rules Tables later in this chapter.)

1.4.10 Page Regions

Page regions that are established by the PAGE clause are described in the table below.

Table 1-1: Page Regions

1.4.11 The Report Group Description Entry

The report group description entry specifies the characteristics of a report group and of the individual items in a report group.

General Formats

Format 1

Format 2

Format 3

Syntax Rules

All Formats

1. The report group description entry can appear only in the Report Section.

2. Except for the data-name clause, which when present must immediately follow the level-number, the clauses can be written in any sequence.

3. A description of a report group can consist of one, two, three or four hierarchic levels:
   1. The first entry that describes a report group must be a Format 1 entry.

   2. Both Format 2 and Format 3 entries can be immediately subordinate to a Format 1 entry.

   3. At least one Format 3 entry must be immediately subordinate to a Format 2 entry.

   4. Format 3 entries must define elementary data items.

4. In the Report Section, the USAGE clause is used only to declare the usage of printable items.
   1. If the USAGE clause appears in a Format 3 entry, that entry must define a printable item.

   2. If the USAGE clause appears in a Format 1 or Format 2 entry, at least one subordinate entry must define a printable item.

5. An entry that contains a LINE NUMBER clause must not have a subordinate entry that also contains a LINE NUMBER clause.

   However an entry containing the LINE NUMBER NEXT PAGE clause can have a subordinate entry containing a LINE NUMBER clause but without the NEXT PAGE option.

Format 1

6. Data-name-1 is required only when:
   1. A detail report group is referenced by a GENERATE statement.

   2. A detail report group is referenced by the UPON phrase of a SUM clause.

   3. A report group is referenced in a USE BEFORE REPORTING sentence.

   4. The name of a control footing report group is used to qualify a reference to a sum counter.

   If specified, data-name-1 can be referenced only by a GENERATE statement, the UPON phrase of a SUM clause, a USE BEFORE REPORTING sentence, or as a sum counter qualifier.

Format 2

7. The level-number can be any integer from 02 to 48 inclusive.

8. An entry must contain at least one optional clause.

9. Data-name-1 is optional. If present it can be used only to qualify a sum counter reference.

Format 3

10. The level-number can be any integer from 02 to 49 inclusive.

11. In Format 3:
    1. A GROUP INDICATE clause can appear only in a type detail report group.

    2. A SUM clause can appear only in a type control footing report group.

    3. An entry that contains a COLUMN NUMBER clause but no LINE NUMBER clause must be subordinate to an entry that contains a LINE NUMBER clause.

    4. Data-name-1 is optional but can be specified in any entry. Data-name-1 can be referenced only if the entry defines a sum counter.

    5. An entry that contains a VALUE clause must also have a COLUMN NUMBER clause.

12. The following table shows all permissible clause combinations for a Format 3 entry. The table is read from left to right along the selected row.

    An "M" indicates that the presence of the clause is mandatory.

    A "P" indicates that the presence of the clause is permitted, but not required.

    A blank indicates that the clause is not permitted.

    Table 1-2: Permissible Clause Combinations in Format 3 Entries

    PIC	COLUMN	SOURCE	SUM	VALUE	JUST	BLANK WHEN ZERO	GROUP INDICATE	USAGE	SIGN	LINE
    M			M						P	P
    M	M		M			P		P	P	P
    M	P	M			P		P	P	P	P
    M	P	M				P	P	P	P	P
    M	M			M	P		P	P	P	P

General Rules

1. Format 1 is the report group entry. The report is defined by the contents of this entry and all of its subordinate entries.

2. The BLANK WHEN ZERO clause, the JUSTIFIED clause, and the PICTURE clause for the Report Writer module are the same as the BLANK WHEN ZERO clause, the JUSTIFIED clause, and the PICTURE clause in the nucleus. See the chapter Program Definition in your Language Reference for specifications. The other clauses of the report group description entry are presented in alphabetical order later in this chapter.

1.4.12 Presentation Rules Tables

1.4.12.1 Description

The tables and rules on the following pages specify:

1. The permissible combinations of LINE NUMBER and NEXT GROUP clauses for each type of report group.

2. The requirements that are placed on the use of these clauses, and

3. The interpretation that the RWCS gives to these clauses.

1.4.12.2 Organization

There is an individual presentation rules table for each of the following types of report groups: report heading, page heading, page footing, report footing. In addition, detail report groups, control heading report groups, or control footing report groups are treated jointly in the body group presentation rules table. (See the section Body Group Presentation Rules later in this chapter.)

Columns 1 and 2 of a presentation rules table list all of the permissible combinations of LINE NUMBER and NEXT GROUP clauses for the designated report group type. Consequently, for the purpose of identifying the set of presentation rules that apply to a particular combination of LINE NUMBER and NEXT GROUP clauses, a presentation rules table is read from left to right, along the selected row.

The applicable rules columns of a presentation rules table are partitioned into two parts. The first part specifies the rules that apply if the report description contains a PAGE clause, and the second part specifies the rules that apply if the PAGE clause is omitted. The purpose of the rules named in the applicable rules columns is discussed below:

1. Upper limit rules and lower limit rules.

   These rules specify the vertical subdivisions of the page within which the specified report group can be represented.

   In the absence of a PAGE clause the printed report is not considered to be partitioned into vertical subdivisions. Consequently, in the tables no upper limit rule or lower limit rule is specified for a report description in which the PAGE clause is omitted

2. Fit test rules.

   The fit test rules are applicable only to body groups, and hence fit test rules are specified only in the body group presentation rules table. At object time the RWCS applies the fit test rules to determine whether the designated body group can be presented on the page to which the report is currently positioned.

   However, even for body groups there are no fit test rules when the PAGE clause is omitted from the report description entry.

3. First print line position rules.

   The first print line position rules specify where on the report medium the RWCS shall present the first print line of the given report group.

   The presentation rules tables do not specify where on the report medium the RWCS shall present the second and subsequent print lines (if any) of a report group. Certain general rules determine where the second and subsequent print lines of a report group shall be presented. Refer to the LINE NUMBER clause general rules for this information.

4. Next group rules.

   The next group rules relate to the proper use of the NEXT GROUP clause.

5. Final LINE-COUNTER setting rules.

   The terminal values that the RWCS places in LINE-COUNTER after presenting report groups are specified by the final LINE-COUNTER setting rules.

1.4.12.3 Line Number Clause Notation

Column 1 of the presentation rules table uses a shorthand notation to describe the sequence of LINE NUMBER clauses that can appear in the description of a report group. The meaning of the abbreviations used in column 1 is as follows.

1. The letter "A" represents one or more absolute LINE NUMBER clauses, none of which has the NEXT PAGE phrase, that appear in consecutive order in the sequence of LINE NUMBER clauses in the report group description entry.

2. The letter "R" represents one or more relative LINE NUMBER clauses that appear in consecutive order in the sequence of LINE NUMBER clauses in the report group description entry.

3. The letters "NP" represent one or more absolute LINE NUMBER clauses that appear in consecutive order in the sequence of LINE NUMBER clauses in the report group description entry with the phrase NEXT PAGE appearing in the first and only in the first LINE NUMBER clause.

   This entry can appear without a line number.

When two abbreviations appear together, they refer to a sequence of LINE NUMBER clauses that consists of the two specified consecutive sequences. For example "A R" refers to a report group description entry within which the "A" sequence (defined in rule 1 above) is immediately followed by the "R" sequence (defined in rule 2 above).

1.4.12.4 Line Number Clause Sequence Substitutions

Where "A R" is shown to be a permissible sequence in the presentation rules table, "A" is also permissible and the same presentation rules are applicable.

Where "NP R" is shown to be a permissible sequence in the presentation rules table, "NP" is also permissible and the same presentation rules are applicable.

1.4.12.5 Saved Next Group Integer Description

Saved next group integer is a data item that is addressable only by the RWCS. When an absolute NEXT GROUP clause specifies a vertical positioning value which cannot be accommodated on the current page, the RWCS stores that value in saved next group integer. After page advance processing, the RWCS positions the next body group using the value stored in saved next group integer.

1.4.12.6 Report Heading Group Presentation Rules

Table 1-3 points to the appropriate presentation rules for all permissible combinations of LINE NUMBER and NEXT GROUP clauses in a report heading report group. The report heading group presentation rules are as follows:

1. Upper limit rule.

   The first line number on which the report heading report group can be presented is the line number specified by the HEADING phrase of the PAGE clause.

2. Lower limit rules.
   1. The last line number on which the report heading report group can be presented is the line number that is obtained by subtracting 1 from the value of integer-3 of the FIRST DETAIL phrase of the PAGE clause.

   2. The last line number on which the report heading report group can be presented is the line number specified by integer-1 of the PAGE clause.

3. First print line position rules.
   1. The first print line of the report heading report group is presented on the line number specified by the integer of its LINE NUMBER clause.

   2. The first print line of the report heading report group is presented on the line number obtained by adding the integer of the first LINE NUMBER clause and the value obtained by subtracting 1 from the value of integer-2 of the HEADING phrase of the PAGE clause.

   3. The report heading report group is not presented.

   4. The first print line of the report heading report group is presented on the line number obtained by adding the content of its LINE-COUNTER (in this case, zero) to the integer of the first LINE NUMBER clause.

4. Next group rules.
   1. The NEXT GROUP integer must be greater than the line number on which the final print line of the report heading report group is presented. In addition, the NEXT GROUP integer must be less than the line number specified by the value of integer-3 of the FIRST DETAIL phrase of the PAGE clause.

   2. The sum of the NEXT GROUP integer and the line number on which the final print line of the report heading report group is presented must be less than the value of integer-3 of the FIRST DETAIL phrase of the PAGE clause.

   3. NEXT GROUP PAGE signifies that the report heading report group is to be presented entirely by itself on the first page of the report. The RWCS processes no other report group while positioned to the first page of the report.

5. Final LINE-COUNTER setting rules.
   1. After the report heading report group is presented, the RWCS places the NEXT GROUP integer into LINE-COUNTER as the final LINE-COUNTER setting.

   2. After the report heading report group is presented, the RWCS places the sum of the NEXT GROUP integer and the line number on which the final print line of the report heading report group was presented into LINE-COUNTER as the final LINE-COUNTER setting.

   3. After the report heading report group is presented, the RWCS places zero into LINE-COUNTER as the final LINE-COUNTER setting.

   4. After the report heading report group is presented, the final LINE-COUNTER setting is the line number on which the final print line of the report heading report group was presented.

   5. LINE-COUNTER is unaffected by the processing of a non-printable report group.

Table 1-3: Report Heading Group Presentation Rules

1.4.12.7 Page Heading Group Presentation Rules

Table 1-4 below points to the appropriate presentation rules for all permissible combinations of LINE NUMBER and NEXT GROUP clauses in a page heading report group.

Table 1-4 : Page Heading Group Presentation Rules

The page heading group presentation rules are as follows:

1. Upper limit rule.

   If a report heading report group has been presented on the page on which the page heading report group is to be presented, then the first line number on which the page heading report group can be presented is one greater than the final LINE-COUNTER setting established by the REPORT HEADING.

   Otherwise the first line number on which the page heading report group can be presented is the line number specified by the HEADING phrase of the PAGE clause.

2. Lower limit rule.

   The last line number on which the page heading report group can be presented is the line number that is obtained by subtracting one from the value of integer-3 of the FIRST DETAIL phrase of the PAGE clause.

3. First print line position rules.
   1. The first print line of the page heading report group is presented on the line number specified by the integer of its LINE NUMBER clause.

   2. If a report heading report group has been presented on the page on which the page heading report group is to be present, then the sum of the final LINE-COUNTER setting established by the report heading report group and the integer of the first LINE NUMBER clause of the page heading report group defines the line number on which the first print line of the page heading report group is presented.

      Otherwise the sum of the integer of the first LINE NUMBER clause of the page heading report group and the value obtained by subtracting one from the value of integer-2 of the HEADING phrase of the PAGE clause defines the line number on which the first print line of the page heading report group is presented.

   3. The page heading report group is not presented.

4. Final LINE-COUNTER setting rules.
   1. The final LINE-COUNTER setting is the line number on which the final print line of the page heading report group was presented.

   2. LINE-COUNTER is unaffected by the processing of a nonprintable report group.

1.4.12.8 Body Group Presentation Rules

Table 1-5 points to the appropriate presentation rules for all permissible combinations of LINE NUMBER and NEXT GROUP clauses in control heading, detail, and control footing report groups. The body group presentation rules are as follows:

1. Upper limit rule.

   The first line number on which a body group can be presented is the line number specified by the FIRST DETAIL phrase of the PAGE clause.

2. Lower limit rules.

   The last line number on which a control heading report group or detail report group can be presented is the line number specified by the LAST DETAIL phrase of the PAGE clause.

   The last line number on which a control footing report group can be presented is the line number specified by the FOOTING phrase of the PAGE clause.

3. Fit test rules.
   1. If the value in LINE-COUNTER is less than the integer of the first absolute LINE NUMBER clause, then the body group is presented on the page to which the report is currently positioned.

      If the value in LINE-COUNTER is not less than the integer of the first absolute LINE NUMBER clause, the RWCS executes page advance processing. After the page heading report group (if defined) has been processed, the RWCS determines whether the saved next group integer location was set when the final body group was presented on the preceding page. (See final LINE-COUNTER setting rule 6a.)

      If saved next group integer was not set, the body group shall be presented on the page to which the report is currently positioned. If saved next group integer was set, the RWCS moves the saved next group integer into LINE-COUNTER, resets saved next group integer to zero, and reapplies this rule.

   2. If a body group has been presented on the page to which the report is currently positioned, the RWCS computes a trial sum in a work location. The trial sum is computed by adding the content of LINE-COUNTER to the integers of all LINE NUMBER clauses of the report group. If the trial sum is not greater than the body group's lower limit integer, then the report group is presented on the current page. If the trial sum exceeds the body group's lower limit integer, then the RWCS executes page advance processing. After the page heading report group (if defined) has been processed, the RWCS reapplies this rule.

      If no body group has yet been presented on the page to which the report is currently positioned, the RWCS determines whether the saved next group integer location was set when the final body group was presented on the preceding page. (See final LINE-COUNTER setting rule 6a.)

      If saved next group integer was not so set, the body group shall be presented on the page to which the report is currently positioned.

      If saved next group integer was so set, the RWCS moves the saved next group integer into LINE-COUNTER, resets saved next group integer to zero, and computes a trial sum in a work location.

      The trial sum is computed by adding the content of LINE-COUNTER to the integer one and the integers of all but the first LINE NUMBER clause of the body group. If the trial sum is not greater than the body group's lower limit integer, then the body group is presented on the current page. If the trial sum exceeds the body group's lower limit integer, the RWCS executes page advance processing. After the page heading report group (if defined) has been processed, the RWCS presents the body group on that page.

   3. If a body group has been presented on the page to which the report is currently positioned, the RWCS executes page advance processing. After the page heading report group (if defined) has been processed, the RWCS reapplies this rule.

      If no body group has yet been presented on the page to which the report is currently positioned, the RWCS determines whether the saved next group integer location was set when the final body group was presented on the preceding page. (See final LINE-COUNTER setting rule 6a.)

      If saved next group integer was not so set, the body group shall be presented on the page to which the report is currently positioned. If saved next group integer was so set, the RWCS moves the saved next group integer into LINE-COUNTER and resets saved next group integer to zero.

      If then the value in LINE-COUNTER is less than the integer of the first absolute LINE NUMBER clause, the body group shall be presented on the page to which the report is currently positioned. Otherwise the RWCS executes page advance processing. After the page heading report group (if defined) has been processed, the RWCS presents the body group on that page.

4. First print line position rules.
   1. The first print line of the body group is presented on the line number specified by the integer of its LINE NUMBER clause.

   2. If the value in LINE-COUNTER is equal to or greater than the line number specified by the FIRST DETAIL phrase of the PAGE clause, and if no body group has previously been presented on the page to which the report is currently positioned, then the first print line of the current body group is presented on the line immediately following the line indicated by the value contained on LINE-COUNTER.

      If the value in LINE-COUNTER is equal to or greater than the line number specified by the FIRST DETAIL phrase of the PAGE clause, and if a body group has previously been presented on the page to which the report is currently positioned, then the first print line of the current body group is presented on the line that is obtained by adding the content of LINE-COUNTER and the integer of the first LINE NUMBER clause of the current body group.

      If the value in LINE-COUNTER is less than the line number specified by the FIRST DETAIL phrase of the PAGE clause, then the first printer line of the body group is presented on the line specified by the FIRST DETAIL phrase.

   3. The body group is not presented.

   4. The sum of the content of LINE-COUNTER and the integer of the first LINE NUMBER clause defines the line number on which the first print line is presented.

5. Next group rule.

   The integer of the absolute NEXT GROUP clause must specify a line number that is not less than that specified in the FIRST DETAIL phrase of the PAGE clause, and that is not greater than that specified in the FOOTING phrase of the PAGE clause.

6. Final LINE-COUNTER setting rules.
   1. If the body group that has just been presented is a control footing report group and if the control footing report group is not associated with the highest level at which the RWCS detected a control break, then the final LINE-COUNTER setting is the line number on which the final print line of the control footing report group was presented.

      For all other cases, the RWCS makes a comparison of the line number on which the final print line of the body group was presented and the integer of the NEXT GROUP clause. If the former is less than the latter, then the RWCS places the NEXT GROUP integer into LINE-COUNTER as the final LINE-COUNTER setting. If the former is equal to or greater than the latter, then the RWCS places the line number specified by the FOOTING phrase of the PAGE clause into LINE-COUNTER as the final LINE-COUNTER setting; in addition the RWCS places the NEXT GROUP integer into the saved next group integer location.

   2. If the body group that has just been presented is a control footing report group, and if the control footing report group is not associated with the highest level at which the RWCS detected a control break, then the final LINE-COUNTER setting is the line number on which the final print line of the control footing report group was presented.

      For all other cases the RWCS computes a trial sum in a work location. The trial sum is computed by adding the integer of the NEXT GROUP clause to the line number on which the final print line of the body group was presented. If the sum is less than the line number specified by the FOOTING phrase of the PAGE clause, then the RWCS places that sum into LINE-COUNTER as the final LINE-COUNTER setting. If the sum is equal to or greater than the line number specified by the FOOTING phrase of the PAGE clause, then the RWCS places the line number specified by the FOOTING phrase of the PAGE clause into LINE-COUNTER as the final LINE-COUNTER setting.

   3. If the body group that has just been presented is a control footing report group, and if the control footing report group is not associated with the highest level at which the RWCS detected a control break, then the final LINE-COUNTER setting is the line number on which the final print line of the control footing report group was presented.

      For all other cases the RWCS places the line number specified by the FOOTING phrase of the PAGE clause into LINE-COUNTER as the final LINE-COUNTER setting.

   4. The final LINE-COUNTER setting is the line number on which the final print line of the body group was presented.

   5. LINE-COUNTER is unaffected by the processing of a nonprintable body group.

   6. If the body group that has just been presented is a control footing report group, and if the control footing report group is not associated with the highest level at which the RWCS detected a control break, then the final LINE-COUNTER setting is the line number on which the final print line of the control footing report group was presented.

      For all other cases the RWCS places the sum of the line number on which the final print line was presented and the NEXT GROUP integer into LINE-COUNTER as the final LINE-COUNTER setting.

Table 1-5: Body Group Presentation Rules

1.4.12.9 Page Footing Presentation Rules

Table 1-6 below points to the appropriate presentation rules for all permissible combinations of LINE NUMBER and NEXT GROUP clauses in a PAGE FOOTING report group.

Table 1-6 : Page Footing Presentation Rules

The page footing presentation rules are as follows:

1. Upper limit rule.

   The first line number on which the page footing report group can be presented is the line number obtained by adding one to the value of integer-5 of the FOOTING phrase of the PAGE clause.

2. Lower limit rule.

   The last line number on which the page footing report group can be presented is the line number specified by integer-1 of the PAGE clause.

3. First print line position rules.
   1. The first print line of the page footing report group is presented on the line specified by the integer of its LINE NUMBER clause.

   2. The page footing report group is not presented.

4. Next group rules.
   1. The NEXT GROUP integer must be greater than the line number on which the final print line of the page footing report group is presented. In addition, the NEXT GROUP integer must not be greater than the line number specified by integer-1 of the PAGE clause.

   2. The sum of the NEXT GROUP integer and the line number on which the final print line of the page footing report group is presented must not be greater than the line number specified by integer-1 of the PAGE clause.

5. Final LINE-COUNTER setting rules.
   1. After the page footing report group is presented, the RWCS places the NEXT GROUP integer into LINE-COUNTER as the final LINE-COUNTER setting.

   2. After the page footing report group is presented, the RWCS places the sum of the NEXT GROUP integer and the line number on which the final print line of the PAGE FOOTING report group was presented into LINE-COUNTER as the final LINE-COUNTER setting.

   3. After the PAGE FOOTING report group is presented the final LINE-COUNTER setting is the line number on which the final print line of the PAGE FOOTING report group was presented.

   4. LINE-COUNTER is unaffected by the processing of a nonprintable report group.

1.4.12.10 Report Footing Presentation Rules

Table 1-7 points to the appropriate presentation rules for all permissible combinations of LINE NUMBER and NEXT GROUP clauses in a report footing report group. The report footing presentation rules are as follows:

1. Upper limit rules.
   1. If a page footing report group has been presented on the page to which the report is currently positioned, then the first line number on which the report footing report group can be presented is one greater than the final LINE- COUNTER setting established by the page footing report group.

      Otherwise the first line number on which the report footing report group can be presented is the line number obtained by adding one and the value of integer-5 of the PAGE clause.

   2. The first line number on which the report footing report group can be presented, is the line number specified by the HEADING phrase of the PAGE clause.

2. Lower limit rule:

   The last line number on which the report footing report group can be presented is the line number specified by integer-1 of the PAGE clause.

3. First print line position rules:
   1. The first print line of the report footing report group is presented on the line specified by the integer of its LINE NUMBER clause.

   2. If a page footing report group has been presented on the page to which the report is currently positioned, then the sum of the final LINE-COUNTER setting established by the page footing report group and the integer of the first LINE NUMBER clause of the report footing report group defines the line number on which the first print line of the report footing report group is presented. Otherwise the sum of the integer of the first LINE NUMBER clause of the report footing report group, and the line number specified by the value of integer-5 of the FOOTING phrase of the PAGE clause defines the line number on which the first print line of the report footing report group is presented.

   3. The NEXT PAGE phrase in the first absolute LINE NUMBER clause directs that the report footing report group is presented on a page on which no other report group has been presented. The first print line of the report footing report group is presented on the line number specified by the integer of its LINE NUMBER clause.

   4. If LINE IS NEXT PAGE is the only LINE clause in this report group, the first line of the report heading report group is presented on line HEADING integer-2.

   5. The sum of the content of LINE-COUNTER and the integer of the first LINE NUMBER clause defines the line number on which the first print line is presented.

   6. The report footing report group is not presented.

4. Final LINE-COUNTER setting rules.
   1. The final LINE-COUNTER setting is the line number on which the final print line of the report footing report group is presented.

   2. LINE-COUNTER is unaffected by the processing of a nonprintable report group.

Table 1-7: Report Footing Presentation Rules

1.4.13 The COLUMN NUMBER Clause

The COLUMN NUMBER clause identifies a printable item and specifies the position of the item on a print line.

General Format

Syntax Rules

1. The COLUMN NUMBER clause can be specified only at the elementary level in a report group. The COLUMN NUMBER clause, if present, must appear in or be subordinate to an entry that contains a LINE NUMBER clause.

2. Within a given print line, the printable items should be defined in ascending column number order such that each printable item defined occupies a unique sequence of contiguous character positions.

   No restrictions on the sequence of COLUMN NUMBER clauses are enforced.

General Rules

1. The COLUMN NUMBER clause indicates that the object of a SOURCE clause or the object of a VALUE clause or the sum counter defined by a SUM clause is to be presented on the print line. The absence of a COLUMN NUMBER clause indicates that the entry is not to be presented on a print line.

2. Integer-1 specifies the column number of the leftmost character position of the printable item.

3. The RWCS supplies space characters for all positions of a print line that are not occupied by printable items.

4. The leftmost position of the print line is considered to be column number 1.

1.4.14 The DATA-NAME Clause

A data-name specifies the name of the data item being described.

General Format

Syntax Rules

1. In the report section data-name-1 need not appear in a data description entry.

General Rules

1. In the Report Section, data-name-1 must be given in the following cases:
   1. When data-name-1 represents a report group to be referred to by a GENERATE or a USE statement in the procedure division.

   2. When reference is to be made to the sum counter in the procedure division or report section.

   3. When a DETAIL report group is referenced in the UPON phrase of the SUM clause.

   4. When data-name-1 is required to provide sum counter qualification.

1.4.15 The GROUP INDICATE Clause

The GROUP INDICATE clause specifies that the associated printable item is presented only on the first occurrence of its report group after a control break or page advance.

General Format

Syntax Rules

1. The GROUP INDICATE clause must be specified only in a DETAIL report group entry that defines a printable item.

General Rules

1. If a GROUP INDICATE clause is specified, it causes the SOURCE or VALUE clause to be ignored and spaces supplied, except:
   1. On the first presentation of the DETAIL report group in the report, or:

   2. On the first presentation of the DETAIL report group after every page advance, or:

   3. On the first presentation of the DETAIL report group after every control group.

2. If the report description entry specifies neither a PAGE clause nor a CONTROL clause, then a GROUP INDICATE printable item is presented the first time its DETAIL is presented after the INITIATE statement is executed. Thereafter spaces are supplied for indicated items with SOURCE or VALUE clauses.

1.4.16 Level-Number

The level-number indicates the position of a data item in the hierarchical structure of a report group.

General Format

Syntax Rules

1. A level-number is required as the first element in each data description entry.

2. Data description entries subordinate to an RD entry must have level-numbers 01 through 49 only.

General Rules

1. The level-number 01 identifies the first entry in a report group.

2. Multiple level 01 entries subordinate to a report description entry having the level indicator RD do not represent implicit redefinitions of the same area.

1.4.17 The LINE NUMBER Clause

The LINE NUMBER clause specifies vertical positioning information for its report group.

General Format

Syntax Rules

1. Integer-1 and integer-2 must not exceed three significant digits in length.

   Neither integer-1 nor integer-2 can be specified in such a way as to cause any line of a report group to be presented outside the vertical subdivision of the page designated for that report group type, as defined by the PAGE clause. (See the section The PAGE Clause earlier in this chapter.)

   Integer-2 can be zero.

2. Within a given report group description entry, an entry that contains a LINE NUMBER clause must not contain a subordinate entry that also contains a LINE NUMBER clause.

3. Within a given report group description entry, all absolute LINE NUMBER clauses must precede all relative LINE NUMBER clauses.

4. Within a given report group description entry, successive absolute LINE NUMBER clauses must specify integers that are in ascending order. The integers need not be consecutive.

5. If the PAGE clause is omitted from a given report description entry, only relative LINE NUMBER clauses can be specified in any report group description entry in that report.

6. Within a given report group description entry a NEXT PAGE phrase can appear only once and, if present, must be in the first LINE NUMBER clause in that report group description entry.

7. A LINE NUMBER clause with the NEXT PAGE phrase can appear only in the description of body groups and in a REPORT FOOTING report group.

8. Every entry that defines a printable item (see the section The COLUMN NUMBER Clause earlier in this chapter) must either contain a LINE NUMBER clause, or be subordinate to an entry that contains a LINE NUMBER clause.

9. The first LINE NUMBER clause specified in a PAGE FOOTING report group must be an absolute LINE NUMBER clause.

General Rules

1. A LINE NUMBER clause must be specified to establish each print line of a report group.

2. The RWCS affects the vertical positioning specified by a LINE NUMBER clause, before presenting the print line established by that LINE NUMBER clause.

3. Integer-1 specifies an absolute line number. An absolute line number specifies the line number on which the print line is presented.

4. Integer-2 specifies a relative line number. If a relative LINE NUMBER clause is not the first LINE NUMBER clause in the report group description entry, then the line number on which its print line is presented is determined by calculating the sum of the line number on which the previous print line of the report group was presented and integer-2 of the relative LINE NUMBER clause. If integer-2 is zero, the line will be printed on the same line as the previous print line.

   If a relative LINE NUMBER clause is the first LINE NUMBER clause in the report group description entry, then the line number on which its print line is presented is determined by specified rules. (See the section Presentation Rules Tables earlier in this chapter.)

5. The NEXT PAGE phrase specifies that the report group is to be presented beginning on the indicated line number on a new page. (See the section Presentation Rules Tables earlier in this chapter.) You need not specify integer-1 for the NEXT PAGE phrase.

1.4.18 The NEXT GROUP Clause

The NEXT GROUP clause specifies information for vertical positioning of a page following the presentation of the last line of a report group.

General Format

Syntax Rules

1. A report group entry must not contain a NEXT GROUP clause unless the description of that report group contains at least one LINE NUMBER clause.

2. Integer-1 and integer-2 must not exceed three significant digits in length.

3. If the PAGE clause is omitted from the report description entry only a relative NEXT GROUP clause can be specified in any report group description entry in that report.

4. The NEXT PAGE phrase of the NEXT GROUP clause must not be specified in a PAGE FOOTING report group.

5. The NEXT GROUP clause must not be specified in a REPORT FOOTING report group or in a PAGE HEADING report group.

General Rules

1. Any positioning of the page specified by the NEXT GROUP clause takes place after the presentation of the report group in which the clause appears. (See the section Presentation Rules Tables earlier in this chapter.)

2. The RWCS uses the vertical positioning information supplied by the NEXT GROUP clause along with information from the TYPE and PAGE clauses, and the value in LINE-COUNTER, to determine a new value for LINE-COUNTER. (See the section Presentation Rules Tables earlier in this chapter.)

3. The NEXT GROUP clause is ignored by the RWCS when it is specified on a CONTROL FOOTING report group that is at a level other than the highest level at which a control break is detected.

4. The NEXT GROUP clause of a body group refers to the next body group to be presented, and therefore can affect the location at which the next body group is presented. The NEXT GROUP clause of a REPORT HEADING report group can affect the location at which the PAGE HEADING report group is presented. The NEXT GROUP clause of a PAGE FOOTING report group can affect the location at which the REPORT FOOTING report group is presented. (See the section Presentation Rules Tables earlier in this chapter.)

1.4.19 The SIGN Clause

The SIGN clause specifies the position and the mode of representation of the operational sign when it is necessary to describe these properties explicitly.

General Format

Syntax Rules

1. The SIGN clause can be specified only for a numeric data description entry whose PICTURE contains the character "S".

2. The numeric data description entries to which the SIGN clause applies must be described, implicitly or explicitly, as USAGE IS DISPLAY.

3. When the SIGN clause is included in a report group description entry, the SEPA RATE CHARACTER phrase must be specified.

General Rules

1. The optional SIGN clause, if present, specifies the position and the mode of representation of the operational sign for the numeric data description entry to which it applies. The SIGN clause applies only to numeric data description entries whose PICTURE contains the character "S"; The "S" indicates the presence of, but neither the representation nor, necessarily, the position of the operational sign.

2. A numeric data description entry whose PICTURE contains the character "S", but to which no optional SIGN clause applies, has an operational sign, but neither the representation nor, necessarily, the position of the operational sign is specified by the character "S". In this (default) case, General Rule 3 does not apply to such signed numeric data items. The representation of the default operational sign is defined in the section Selection Of Character Representation And Radix in the chapter Concepts of the COBOL Language in your Language Reference.

3. Since a SIGN clause in a report group description entry must specify the SEPARATE CHARACTER phrase, then:
   1. The operational sign will be presumed to be the leading (or, respectively, trailing) character position of the elementary numeric data item; this character position is not a digit position.

   2. The letter "S" in a PICTURE character-string is counted in determining the size of the item (in terms of standard data format characters).

   3. The operational signs for positive and negative are the standard data format characters "+" , and "–", respectively.

4. Every numeric data description entry whose PICTURE contains the character "S" is a signed numeric data description entry. If a SIGN clause applies to such an entry and conversion is necessary for purposes of computation or comparisons, conversion takes place automatically.

1.4.20 The SOURCE Clause

The SOURCE clause identifies the sending data item that is moved to an associated printable item defined in a report group description entry.

General Format

Syntax Rules

1. Identifier-1 can be defined in any section of the data division or be a function-identifier. If identifier-1 is a report section item it must be a:
   1. PAGE-COUNTER, or:

   2. LINE-COUNTER, or:

   3. Sum counter that is part of the report within which the SOURCE clause appears.

2. Identifier-1 specifies the sending data item of the implicit MOVE statement that the RWCS executes to move the content of the data item referenced by identifier-1 to the printable item. Identifier-1 must be defined such that it conforms to the rules for sending items in the MOVE statement. (See the section The MOVE Statement in the chapter Program Definition in your Language Reference.)

General Rules

1. The RWCS formats the print lines of a report group just prior to presenting the report group. (See the section The TYPE Clause later in this chapter.) It is at this time that the implicit MOVE statements specified by SOURCE clauses are executed by the RWCS.

1.4.21 The SUM Clause

The SUM clause establishes a sum counter and names the data items to be summed.

General Format

Syntax Rules

1. The data item that is the subject of the report group description entry in which the SUM clause appears must not be defined as alphabetic. Identifier-1 must reference a numeric data item. If identifier-1 is defined in the report section, identifier-1 must reference a sum counter.

   If the UPON phrase is omitted, any identifiers in the associated SUM clause which are themselves sum counters must be defined either in the same report group that contains this SUM clause or in a report group which is at a lower level in the control hierarchy of this report.

   If the UPON phrase is specified, any identifiers in the associated SUM clause must not be sum counters.

2. Data-name-1 must be the name of a DETAIL report group described in the same report as the CONTROL FOOTING report group in which the SUM clause appears. Data-name-1 can be qualified by a report-name.

3. A SUM clause can appear only in the description of a CONTROL FOOTING report group.

4. Data-name-2 must be one of the data-names specified on the CONTROL clause for this report. Data-name-2 must not be a lower level control than the associated control for the report group in which the RESET phrase appears.

   FINAL, if specified in the RESET phrase, must also appear in the CONTROL clause for this report.

   This rule is not enforced.

5. The highest permissible qualifier of a sum counter is the report-name.

General Rules

1. The SUM clause establishes a sum counter. The sum counter is a numeric data item with an optional sign. At object time, the RWCS adds into the sum counter the value in each data item referenced by identifier-1. This addition is consistent with the rules for arithmetic statements. (See the sections Arithmetic Statements and Overlapping Operands in the chapter Program Definition in your Language Reference.)

2. The size of the sum counter is equal to the number of receiving character positions specified by the PICTURE clause that accompanies the SUM clause in the description of the elementary item.

3. Only one sum counter exists for an elementary report entry regardless of the number of SUM clauses specified in the elementary report entry.

4. If the elementary report entry for a printable item contains a SUM clause, the sum counter serves as a source data item. The RWCS moves the data contained in the sum counter, according to the rules of the MOVE statement, to the printable item for presentation.

5. If a data-name appears as the subject of an elementary report entry that contains a SUM clause, the data-name is the name of the sum counter; the data-name is not the name of the printable item that the entry can also define.

6. It is permissible for Procedure Division statements to alter the contents of sum counters.

7. Addition of the values of the data items referenced by identifiers into sum counters is performed by the report writer control system during the execution of GENERATE and TERMINATE statements. There are three categories of sum counter incrementing called subtotalling, crossfooting, and rolling forward. Subtotalling is accomplished only during execution of GENERATE statements and after any control break processing but before processing of the DETAIL report group. (See the section The GENERATE Statement later in this chapter.) Crossfooting and rolling forward are accomplished during the processing of CONTROL FOOTING report groups. (See the section The TYPE Clause later in this chapter.)

8. The UPON phrase provides the capability to accomplish selective subtotalling for the DETAIL report groups named in the phrase.

9. The RWCS adds each individual addend into the sum counter at a time that depends upon the characteristics of the addend.
   1. When the addend is a sum counter defined in the same CONTROL FOOTING report group, then the accumulation of that addend into the sum counter is termed crossfooting.

      Crossfooting occurs when a control break takes place and at the time the CONTROL FOOTING report group is processed.

      Crossfooting is performed according to the sequence in which sum counters are defined in the CONTROL FOOTING report group. That is, all crossfooting into the first sum counter defined in the CONTROL FOOTING report group is completed, and then all crossfooting into the second sum counter defined in the CONTROL FOOTING report group is completed.

      When one of the addends is the sum counter defined by the data description entry in which that SUM clause appears, the initial value of that sum counter at the time of summation is used in the summing operation.

   2. When the addend is a sum counter defined in a lower level CONTROL FOOTING report group, then the accumulation of that addend into the sum counter is termed rolling forward. A sum counter in a lower level CONTROL FOOTING report group is rolled forward when a control break occurs and at the time that the lower level CONTROL FOOTING report group is processed.

   3. When the addend is not a sum counter the accumulation into a sum counter of such an addend is called subtotalling. If the SUM clause contains the UPON phrase, the addends are subtotalled when a GENERATE statement for the designated DETAIL report group is executed. If the SUM clause does not contain the UPON phrase, the addends which are not sum counters are subtotalled when any GENERATE data-name statement is executed for the report in which the SUM clause appears.

10. If two or more of the identifiers specify the same addend, then the addend is added into the sum counter as many times as the addend is referenced in the SUM clause. It is permissible for two or more of the data-names to specify the same DETAIL report group. When a GENERATE data-name statement for such a DETAIL report group is given, the incrementing occurs repeatedly, as many times as data-name appears in the UPON phrase.

11. The subtotalling that occurs when a GENERATE report-name statement is executed is discussed in the appropriate paragraph. (See the section The GENERATE Statement later in this chapter.)

12. In the absence of an explicit RESET phrase, the report writer control system will set a sum counter to zero at the time that the report writer control system is processing the CONTROL FOOTING report group in which the sum counter is defined. If an explicit RESET phrase is specified, then the report writer control system will set the sum counter to zero at the time that the report writer control system is processing the designated level of the control hierarchy. (See the section The TYPE Clause below.)

    Sum counters are initially set to zero by the report writer control system during the execution of the INITIATE statement for the report containing the sum counter.

1.4.22 The TYPE Clause

The TYPE clause specifies the particular type of report group that is described by this entry and indicates the time at which the report group is to be processed by the RWCS.

General Format

Syntax Rules

1. RH is an abbreviation for REPORT HEADING.
   PH is an abbreviation for PAGE HEADING.
   CH is an abbreviation for CONTROL HEADING.
   DE is an abbreviation for DETAIL.
   CF is an abbreviation for CONTROL FOOTING.
   PF is an abbreviation for PAGE FOOTING.
   RF is an abbreviation for REPORT FOOTING.

2. REPORT HEADING, PAGE HEADING, CONTROL HEADING FINAL, CONTROL FOOTING FINAL, PAGE FOOTING, and REPORT FOOTING report groups can each appear no more than once in the description of a report.

3. PAGE HEADING and PAGE FOOTING report groups can be specified only if a PAGE clause is specified in the corresponding report description entry.

4. Data-name-1, data-name-2, and FINAL, if present, must be specified in the CONTROL clause of the corresponding report description entry.

   This rule is not enforced with regard to FINAL.

   At most, one CONTROL HEADING report group and one CONTROL FOOTING report group can be specified for each data-name or FINAL in the CONTROL clause of the report description entry. However, neither a CONTROL HEADING report group nor a CONTROL FOOTING report group is required for a data-name or FINAL specified in the CONTROL clause of the report description entry.

5. In CONTROL FOOTING, PAGE HEADING, PAGE FOOTING, AND REPORT FOOTING report groups, SOURCE clauses and USE statements must not reference any of the following:
   1. Group data items containing a control data item.

   2. Data items subordinate to a control data item.

   3. A redefinition or renaming of any part of a control data item.

   In PAGE HEADING and PAGE FOOTING report groups, SOURCE clauses and USE statements must not reference control data-names.

6. When a GENERATE report-name statement is specified in the Procedure Division, the corresponding report description entry must include no more than one DETAIL report group. If no GENERATE data-name statements are specified for such a report, a DETAIL report group is not required.

7. The description of a report must include at least one body group.

General Rules

1. DETAIL report groups are processed by the RWCS as a direct result of GENERATE statements. If a report group is other than TYPE DETAIL its processing is an automatic RWCS function.

2. The REPORT HEADING phrase specifies a report group that is processed by the RWCS only once, per report, as the first report group of that report. The REPORT HEADING report group is processed during the execution of the chronologically first GENERATE statement for that report.

3. The PAGE HEADING phrase specifies a report group that is processed by the RWCS as the first report group on each page of that report except under the following conditions:
   1. A PAGE HEADING report group is not processed on a page that is to contain only a REPORT HEADING report group or only a REPORT FOOTING report group.

   2. A PAGE HEADING report group is processed as the second report group on a page when it is preceded by a REPORT HEADING report group that is not to be presented on a page by itself.

   (See the section Presentation Rules Tables earlier in this chapter.)

4. The CONTROL HEADING phrase specifies a report group that is processed by the RWCS at the beginning of a control group for a designated control data-name or, in the case of FINAL, is processed during the execution of the chronologically first GENERATE statement for that report. During the execution of any GENERATE statement at which the RWCS detects a control break, any CONTROL HEADING report groups associated with the highest control level of the break and lower levels are processed.

5. The DETAIL phrase specifies a report group that is processed by the RWCS when a corresponding GENERATE statement is executed.

6. The CONTROL FOOTING phrase specifies a report group that is processed by the RWCS at the end of a control group for a designated control data-name.

   In the case of FINAL, the CONTROL FOOTING report group is processed only once per report as the last body group of that report. During the execution of any GENERATE statement in which the RWCS detects a control break, any CONTROL FOOTING report group associated with the highest level of the control break or more minor levels is presented. All CONTROL FOOTING report groups are presented during the execution of the TERMINATE statement if there has been at least one GENERATE statement executed for the report. (See the section The TERMINATE Statement later in this chapter.)

7. The PAGE FOOTING phrase specifies a report group that is processed by the RWCS as the last report group on each page except under the following conditions:
   1. A PAGE FOOTING report group is not processed on a page that is to contain only a REPORT HEADING report group or only a REPORT FOOTING report group.

   2. A PAGE FOOTING report group is processed as the second to last report group on a page when it is followed by a REPORT FOOTING report group that is not to be processed on a page by itself.

   (See the section Presentation Rules Tables earlier in this chapter.)

8. The REPORT FOOTING phrase specifies a report group that is processed by the RWCS only once per report and as the last report group of that report. The REPORT FOOTING report group is processed during the execution of a corresponding TERMINATE statement, if there has been at least one GENERATE statement executed for the report. (See the section The TERMINATE Statement later in this chapter.)

9. The sequence of steps that the RWCS executes when it processes a REPORT HEADING, PAGE HEADING, CONTROL HEADING, PAGE FOOTING, or REPORT FOOTING report group is described below.
   1. If a USE BEFORE REPORTING procedure references the data-name of the report group, the USE procedure is executed.

   2. If a SUPPRESS statement has been executed or if the report group is not printable, no further processing is done for the report group.

   3. If a SUPPRESS statement has not been executed and the report group is printable, the RWCS formats the print lines and presents the report group according to the presentation rules for that type of report group. (See the section Presentation Rules Tables earlier in this chapter.)

10. The sequence of steps that the RWCS executes when it processes a CONTROL FOOTING report group is described below.

    The GENERATE rules specify that when a control break occurs, the RWCS produces the CONTROL FOOTING report groups beginning at the minor level, and proceeding upwards, through the level at which the highest control break was sensed. In this regard, it should be noted that even though no CONTROL FOOTING report group has been defined for a given control data-name, the RWCS will still have to execute the step described in rule 10f below if a RESET phrase in the report description specifies that control data-name.

    1. Sum counters are crossfooted; that is, all sum counters defined in this report group that are operands of SUM clauses in the same report group are added to their sum counters. (See the section The SUM Clause earlier in this chapter.)

    2. Sum counters are rolled forward; that is, all sum counters defined in the report group that are operands of SUM clauses in higher level CONTROL FOOTING report groups are added to the higher level sum counters. (See the section The SUM Clause earlier in this chapter.)

    3. If a USE BEFORE REPORTING procedure references the data-name of the report group the USE procedure is executed.

    4. If a SUPPRESS statement has been executed or if the report group is not printable, the RWCS next executes the step described in rule 10e below.

    5. If a SUPPRESS statement has not been executed and the report group is printable, the RWCS formats the print lines and presents the report group according to the presentation rules of CONTROL FOOTING report groups.

    6. Then the RWCS resets those sum counters that are to be reset when the RWCS processes this level in the control hierarchy. (See the section The SUM Clause earlier in this chapter.)

11. The DETAIL report group processing that the RWCS system executes in response to a GENERATE data-name statement is described in rules 11a through 11e below.

    When the description of a report includes exactly one DETAIL report group, the detail-related processing that the RWCS executes in response to a GENERATE report-name statement is described in rules 11a through 11e below. These steps are performed as though a GENERATE data-name statement were being executed.

    When the description of a report includes no DETAIL report groups, the detail-related processing that the RWCS executes in response to a GENERATE report-name statement is described in rule 11a below. This step is performed as though the description of the report included exactly one DETAIL report group, and a GENERATE data-name statement were being executed.

    1. The RWCS performs any subtotalling that has been designated for the DETAIL report group. (See the section The SUM Clause earlier in this chapter.)

    2. If a USE BEFORE REPORTING procedure refers to the data-name of the report group, the USE procedure is executed.

    3. If a SUPPRESS statement has been executed or if the report group is not printable no further processing is done for the report group.

    4. If the DETAIL report group is being processed as a consequence of a GENERATE report-name statement, no further processing is done for the report group.

    5. If neither 11c nor 11d above applies, the RWCS formats the print lines and presents the report group according to the presentation rules for DETAIL report groups. (See the section Presentation Rules Tables earlier in this chapter.)

12. When the RWCS is processing a CONTROL HEADING, CONTROL FOOTING, or DETAIL report group, as described in General Rules 9, 10, and 11, the RWCS may have to interrupt the processing of that body group after determining that the body group is to be presented, and execute a page advance ( and process PAGE FOOTING and PAGE HEADING report groups) before actually presenting the body group.

13. During control break processing, the values of control data items that the RWCS used to detect a given control break are referred to as prior values.
    1. During control break processing of a CONTROL FOOTING report group, any references to control data items in a USE procedure or SOURCE clause associated with that CONTROL FOOTING report group are supplied with prior values.

    2. When a TERMINATE statement is executed, the RWCS makes the prior control data item values available to SOURCE clause or USE procedure references in CONTROL FOOTING and REPORT FOOTING report groups as though a control break had been detected in the highest control data-name.

    3. All other data item references in report groups and their USE procedures access the current values that are contained in the data items at the time the report group is processed.

1.4.23 The USAGE Clause

The USAGE clause specifies the format of a data item in the computer storage.

General Format

Syntax Rules

1. The USAGE clause can be written in any data description entry.

2. If the USAGE clause is written in the data description entry for a group item, it can also be written in the data description entry for a subordinate elementary item or group item.

3. The USAGE clause for a report group item can specify only USAGE IS DISPLAY.

General Rules

1. If the USAGE clause is written at a group level, it applies to each elementary item in the group.

2. The USAGE clause specifies the manner in which a data item is represented in the storage of a computer. It does not affect the use of the data item, although the specifications for some statements in the Procedure Division can restrict the USAGE clause of the operands referred to. The USAGE clause can affect the radix or type of character representation of the item.

3. The USAGE IS DISPLAY clause indicates that the format of the data is a standard data format.

4. If the USAGE clause is not specified for an elementary item, or for any group to which the item belongs, the usage is implicitly DISPLAY.

1.4.24 The VALUE Clause

The VALUE clause defines the value of Report Section printable items.

General Format

Syntax Rules

1. A signed numeric literal must have associated with it a signed numeric PICTURE character-string.

2. A numeric literal in a VALUE clause of an item must have a value which is within the range of values indicated by the PICTURE clause, and must not have a value which would require truncation of nonzero digits. A nonnumeric literal in a VALUE clause of an item must not exceed the size indicated by the PICTURE clause.

General Rules

1. The VALUE clause must not conflict with other clauses in the data description of the item or in the data description in the hierarchy of the item. The following rules apply:
   1. If the category of the item is numeric, literal-1 in the VALUE clause must be numeric.

   2. If the category of the item is alphabetic, alphanumeric, alphanumeric edited, or numeric edited, literal-1 in the VALUE clause must be a nonnumeric literal. The literal is aligned in the data item as if the data item had been described as alphanumeric (See the section Standard Alignment Rules in the chapter Concepts of COBOL Language in your Language Reference). Editing characters in the PICTURE clause are included in determining the size of the data item but have no effect on initialization of the data item (see the section The PICTURE Clause in the chapter Program Definition in your Language Reference). Therefore, the value for an edited item must be specified in an edited form.

   3. Initialization is not affected by any BLANK WHEN ZERO or JUSTIFIED clause that can be specified.

2. In the report section, if the elementary report entry containing the VALUE clause does not contain a GROUP INDICATE clause, then the printable item will assume the specified value each time its report group is printed. However, when the GROUP INDICATE clause is also present, the specified value will be presented only when certain object item conditions exist (see the section The GROUP INDICATE Clause in the chapter Segmentation).

1.5 Procedure Division in the Report Writer Module

1.5.1 General Description

The Procedure Division contains declarative procedures when the USE BEFORE REPORTING statement from the report writer module is present in a COBOL source program. Shown below is the general format of the Procedure Division when the USE BEFORE REPORTING statement is present.

1.5.2 The CLOSE Statement

The CLOSE statement terminates the processing of reel/units and files with optional rewind and/or lock or removal where applicable.

General Format

Syntax Rules

1. The files referenced in the CLOSE statement need not all have the same organization or access.

2. The availability of the phrases with the CLOSE statement is dependent on the level of Sequential I-O module supported by the implementation. (See the chapter Program Definition in your Language Reference).

General Rules

Except where otherwise stated in the general rules below, the terms "reel" and "unit" are equivalent and completely interchangeable in the CLOSE statement. Treatment of sequential mass storage files is logically equivalent to the treatment of a file on tape or analogous sequential media. Treatment of a file contained in a multiple file tape environment is logically equivalent to the treatment of a sequential single-reel/unit file if the file is wholly contained on one reel.

1. A CLOSE statement can only be executed for a file in an open mode.

2. For the purpose of showing the effect of various types of CLOSE statements as applied to various storage media, all report files are divided into the following categories:
   1. Non-reel/unit. A file whose output medium is such that the concepts of rewind and reels/units have no meaning.

   2. Sequential single-reel/unit. A sequential file that is entirely contained on one reel/unit.

   3. Sequential multi-reel/unit. A sequential file that is contained on more than one reel/unit.

3. The results of executing each type of CLOSE for each category of file are summarized in the next table.

   Table 1-8 : Relationship of Categories of Files and the Formats of the CLOSE Statements

   CLOSE Statement Format	File Category
   	Non-Reel/Unit	Sequential Single-Reel/Unit	Sequential Multi-Reel/Unit
   CLOSE	C	C,G	A,C,G
   CLOSE WITH LOCK	C,E	C,E,G	A,C,E,G
   CLOSE WITH NO REWIND	C,H	B,C	A,B,C
   CLOSE WITH REEL/UNIT	F	F,G	F,G
   CLOSE REEL/UNIT FOR REMOVAL	F	D,F,G	D,F,G

   The definitions of the symbols in the table are given below.

   1. Effect on Previous Reels/Units for an Output Report File

      All reels/units in the report file prior to the current reel/unit are closed except those reels/units controlled by a prior CLOSE REEL/UNIT statement.

   2. No Rewind of Current Reel

      The reel/unit is left in its current position.

   3. Close Output Report File

      If label records are specified for the report file, the labels are processed according to the implementor's standard label convention. The behavior of the CLOSE statement when label records are specified but not present, or when records are not specified but are present, is undefined. Closing operations specified by the implementor are executed. If label records are not specified for the report file, label processing does not take place but other closing operations specified by the implementor are executed.

   4. Reel/Unit Removal

      The current reel or unit is rewound, when applicable, and the reel or unit is logically removed from the run unit; however, the reel or unit can be accessed again, in its proper order of reels or units in the report file, if a CLOSE statement without the REEL or UNIT phrase is subsequently executed for this report file followed by the execution of an OPEN statement for the report file.

   5. File Lock

      The report file is locked and cannot be opened again during this execution of this run unit.

   6. Close Reel/Unit

      Output Report File (Reel/Unit Media):

      The following operations take place:

      1. The standard ending reel/unit label procedure is executed.

      2. A reel/unit swap. The current volume pointer is updated to point to the new reel/unit.

      3. The standard beginning reel/unit label procedure is executed.

      4. The next executed write operation that references that file directs the next logical data record to the next reel/unit of the file.

      Output Report File (Non-Reel/Unit Media):

      Execution of this statement is considered successful. The file remains in the open mode, and no action takes place except as specified in general rule 4.

   7. Rewind

      The current reel or analogous device is positioned at its physical beginning.

   8. Optional Phrases Ignored

      The CLOSE statement is executed as if none of the optional phrases is present.

4. The execution of the CLOSE statement causes the value of the I/O status associated with file-name-1 to be updated.

5. All reports associated with a report file that have been initiated must be ended with the execution of a TERMINATE statement before a CLOSE statement is executed for that report file.

6. Following the successful execution of a CLOSE statement without the REEL or UNIT phrase, the report file is removed from the open mode, and the report file is no longer associated with the file connector.

7. If more than one file-name-1 is specified in a CLOSE statement, the result of executing this CLOSE statement is the same as if a separate CLOSE statement had been written for each file-name-1 in the same order as specified in the CLOSE statement.

1.5.3 The GENERATE Statement

The GENERATE statement directs the RWCS to p roduce a report in accordance with the Report Description specified in the Report Section of the Data Division.

General Format

Syntax Rules

1. Data-name-1 must name a TYPE D ETAIL report group and can be qualified by a report-name.

2. Report-name-1 can be used only if the referenced report description contains:
   1. A CONTROL clause, and

   2. Not more than one DETAIL report group, and

   3. At least one body group.

General Rules

1. In response to a GENERATE report-name-1 statement, the RWCS performs summary processing. If all of the GENERATE statements that are executed for a report are of the form GENERATE report-name-1, then the report that is produced is called a summary report.

2. In response to a GENERATE data-name-1 statement, the RWCS performs detail processing that includes certain processing that is specific for the DETAIL report group designated by the GENERATE statement. Normally, the execution of a GENERATE data-name-1 statement causes the RWCS to present the designated DETAIL report group.

3. During the execution of the chronologically first GENERATE statement for a given report, the RWCS saves the values in the control data items. During the execution of the second and subsequent GENERATE statements for the same report, and until a control break is detected, the RWCS utilizes this set of control values to determine whether a control break has occurred. When a control break occurs, the RWCS saves the new set of control values, which it thereafter uses to sense for a control break until another control break occurs.

4. During the report presentation, an automatic function of the RWCS is to process PAGE HEADING and PAGE FOOTING report groups, if defined, when the RWCS must advance the report to a new page for the purpose of presenting a body group. (See the section Presentation Rules Tables earlier in this chapter.)

5. When the chronologically first GENERATE statement for a given report is executed, the RWCS processes, in order, the report groups that are named below, provided that such report groups are defined in the report description. The RWCS also processes PAGE HEADING and PAGE FOOTING report groups as described in General Rule 4. The actions taken by the RWCS when it processes each type of report group are explained under the appropriate paragraph. (See the section The TYPE Clause earlier in this chapter.)
   1. The REPORT HEADING report group is processed.

   2. The PAGE HEADING report group is processed.

   3. All CONTROL HEADING report groups are processed from major to minor.

   4. If a GENERATE data-name-1 statement is being executed, the processing for the designated DETAIL report group is performed. If a GENERATE report-name-1 statement is being executed, certain of the steps that are involved in the processing of a DETAIL report group are performed. (See the section The TYPE Clause earlier in this chapter.)

6. When a GENERATE statement other than the chronologically first is executed for a given report, the RWCS performs the steps enumerated below, as applicable. The RWCS also processes PAGE HEADING and PAGE FOOTING report groups as described in General Rule 4. The actions taken by the RWCS when it processes each type of report group are explained under the appropriate paragraph. (See the section The TYPE Clause earlier in this chapter.)
   1. Sense for control break. The rules for determining the equality of control data items are the same as those specified for relation conditions. If a control break has occurred then:
      1. Enable the CONTROL FOOTING USE procedures and CONTROL FOOTING SOURCE clauses to access the control data item values that the RWCS used to detect a given control break. (See the section The TYPE Clause earlier in this chapter.)

      2. Process the CONTROL FOOTING report groups in the order minor to major. Only CONTROL FOOTING report groups that are not more major than the highest level at which a control break occurred are processed.

      3. Process the CONTROL HEADING report groups in the order major to minor. Only the CONTROL HEADING report groups that are not more major than the highest level at which a control break occurred are processed.

   2. If a GENERATE data-name-1 statement is being executed, the processing for the designated DETAIL report group is performed. If a GENERATE report-name-1 statement is being executed, certain of the steps that are involved in the processing of a DETAIL report group are performed. (See the section The TYPE Clause earlier in this chapter.)

7. GENERATE statements for a report can be executed only after an INITIATE statement for the report has been executed and before a TERMINATE statement for the report has been executed.

1.5.4 The INITIATE Statement

The INITIATE statement causes the RWCS to begin the processing of a report.

General Format

Syntax Rules

1. Report-name-1 must be defined by a report description entry in the report section of the Data Division.

General Rules

1. The INITIATE statement performs the following initialization functions for each named report:
   1. All sum counters are set to zero.

   2. LINE-COUNTER is set to zero.

   3. PAGE-COUNTER is set to one.

2. The INITIATE statement does not place the file associated with the report in the open mode; therefore, an OPEN statement with either the OUTPUT phrase or the EXTEND phrase for the file must be executed prior to the execution of the INITIATE statement.

3. A subsequent INITIATE statement for report-name-1 must not be executed unless an intervening TERMINATE statement has been executed for report-name-1.

4. If more than one report-name is specified in an INITIATE statement, the result of executing this INITIATE statement is the same as if a separate INITIATE statement had been written for each report-name in the same order as specified in the INITIATE statement.

1.5.5 The OPEN Statement

See the chapter Program Definition in your Language Reference.

Additional Syntax Rules

1. A report file must have sequential organization.

2. The OPEN statement for a report file must contain only the OUTPUT phrase or the EXTEND phrase.

Additional General Rules

1. The OPEN statement for a report file must be executed prior to the execution of an INITIATE statement for any reports contained in the file.

1.5.6 The SUPPRESS Statement

The SUPPRESS statement causes the RWCS to inhibit the presentation of a report group.

General Format

Syntax Rules

1. The SUPPRESS statement can only appear in a USE BEFORE REPORTING procedure.

General Rules

1. The SUPPRESS statement inhibits presentation only for the report group named in the USE procedure in which the SUPPRESS statement appears.

2. The SUPPRESS statement must be executed each time the presentation of the report group is to be inhibited.

3. When the SUPPRESS statement is executed, the RWCS is instructed to inhibit the processing of the following report group functions:
   1. The presentation of the print lines of the report group.

   2. The processing of all LINE clauses in the report group.

   3. The processing of the NEXT GROUP clause in the report group.

   4. The adjustment of LINE-COUNTER.

4. The SUPPRESS PRINTING function can also be achieved by moving the value 1 to the special register PRINT- SWITCH.

   The statement

        MOVE 1 TO PRINT-SWITCH

   has exactly the same effect as the statement

        SUPPRESS PRINTING 

1.5.7 The TERMINATE Statement

The TERMINATE statement causes the RWCS to complete the processing of the specified reports.

General Format

Syntax Rules

1. Report-name-1 must be defined by a report description entry in the Report Section of the Data Division.

General Rules

1. The TERMINATE statement causes the RWCS to produce all the CONTROL FOOTING report groups beginning with the minor CONTROL FOOTING report group. Then the REPORT FOOTING report group is produced. The RWCS makes the prior set of control data item values available to the CONTROL FOOTING and REPORT FOOTING SOURCE clauses and USE procedures, as though a control break has been sensed in the most major control data-name.

2. If no GENERATE statements have been executed for a report during the interval between the execution of an INITIATE statement and a TERMINATE statement, for that report, the TERMINATE statement does not cause the RWCS to produce any report groups or perform any of the related processing.

3. During report presentation, an automatic function of the RWCS is to process PAGE HEADING and PAGE FOOTING report groups, if defined, when the RWCS must advance the report to a new page for the purpose of presenting a body group. (See the section Presentation Rules Tables earlier in this chapter.)

4. The TERMINATE statement cannot be executed for a report unless the TERMINATE statement was chronologically preceded by an INITIATE statement for that report and for which no TERMINATE statement has yet been executed.

5. If more than one report-name is specified in a TERMINATE statement, the result of executing this TERMINATE statement is the same as if a separate TERMINATE statement had been written for each report-name in the same order as specified in the TERMINATE statement.

6. The TERMINATE statement does not close the file with which the report is associated; a CLOSE statement for the file must be executed. Every report that is in an initiated condition must be terminated before a CLOSE statement is executed for the associated file.

1.5.8 The USE BEFORE REPORTING Statement

The USE BEFORE REPORTING statement specifies Procedure Division statements that are executed just before a report group named in the Report Section of the Data Division of this program, and optionally a contained program, is presented.

General Format

Syntax Rules

1. A USE BEFORE REPORTING statement, when present, must immediately follow a section header in the declaratives portion of the Procedure Division and must appear in a sentence by itself. The remainder of the section must consist of zero, one, or more procedural paragraphs that define the procedures to be used.

2. Identifier-1 must reference a report group. The same identifier-1 must not appear in more than one USE BEFORE REPORTING statement in the same Procedure Division.

3. The GENERATE, INITIATE, or TERMINATE statements must not appear in a paragraph in a USE BEFORE REPORTING procedure. A PERFORM statement in a USE BEFORE REPORTING procedure must not have GENERATE, INITIATE, or TERMINATE statements in its range.

4. A USE BEFORE REPORTING procedure must not alter the value of any control data item.

5. The USE BEFORE REPORTING statement itself is never executed; it merely defines the conditions calling for the execution of the USE procedures.

General Rules

1. A declarative procedure is invoked just before the named report group is produced during the execution of the program. The report group is named by identifier-1 in the USE BEFORE REPORTING statement which prefaces the declarative.

2. Within a declarative procedure, there must be no reference to any nondeclarative procedures.

3. Procedure-names associated with a USE BEFORE REPORTING statement can be referenced in a different declarative section or in a nondeclarative procedure only with a PERFORM statement.

4. In the USE BEFORE REPORTING statement, the designated procedures are executed by the RWCS just before the named report group is produced. (See the section The TYPE Clause earlier in this chapter.)

5. Within a USE procedure, there must not be the execution of any statement that would cause the execution of a USE procedure that had previously been invoked and had not yet returned control to the invoking routine.

6. Special precedence rules are followed when programs are contained within other programs. In applying these rules, only the first qualifying directive will be selected for execution. The declarative which is selected for execution must satisfy the rules for execution of that declarative. The order of precedence for selecting a declarative is:
   1. The declarative within the program that contains the statement which caused the qualifying condition.

   2. The declarative in which the GLOBAL phrase is specified and which is within the program directly containing the program which was last examined for a qualifying declarative.

   3. Any declarative selected by applying rule 6b to each more inclusive containing program until rule 6b is applied to the outermost program. If no qualifying directive is found, none is executed.

Debug Module