HP 3000 Manuals

Data Division in the Report Writer Module [ Micro Focus COBOL Language Reference - Additional Topics ] MPE/iX 5.0 Documentation

Micro Focus COBOL Language Reference - Additional Topics

Data Division in the Report Writer Module

The File Description Entry

Function.

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

For ANS85 only: 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.

For OSVS and MF only: 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.

The REPORT Clause

Function.

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.

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. For ANS85 only: 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.

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.

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.

Report Group Description Entry.

The report 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.

The Report Description Entry

Function.

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.

For ANS85 only: 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
presented in alphabetical order below.

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

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.

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.)

The CODE Clause

Function.

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.

For OSVS only: 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.

The CONTROL Clause

Function.

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:

a. If the control data item is a numeric data item, the
relation test is for the comparison of two numeric
operands.

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

c. 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.

The PAGE Clause

Function.

The PAGE clause defines the length of a page and the vertical
subdivisions within which report 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.)

a. 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.

b. 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.

c. 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.

d. 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.

e. 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.

f. 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.

a. Integer-1 defines the size of a report page by specifying
the number of lines available on each page.

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

c. 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.

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

e. 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:

a. If the HEADING phrase is omitted, a value of one is assumed
for integer-2.

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

c. 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.

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

e. 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.)

Page Regions

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

Table 1-1 : Page Regions

The Report Group Description Entry

Function.

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:

a. The first entry that describes a report group must be a
Format 1 entry.

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

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

d. 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.

a. If the USAGE clause appears in a Format 3 entry, that entry
must define a printable item.

b. 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.

For OSVS only: 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:

* A detail report group is referenced by a GENERATE statement.

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

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

* 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:

* A GROUP INDICATE clause can appear only in a type detail
report group.

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

* 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.

* 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.

* 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 | GROUP | USAGE | SIGN | LINE |
| | | | | | | WHEN | INDICATE| | | |
| | | | | | | ZERO | | | | |
| | | | | | | | | | | |
---------------------------------------------------------------------------------------------------------------
| | | | | | | | | | | |
| 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.

MPE/iX 5.0 Documentation