|
| Communication |  |
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.
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.
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.
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.
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.
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.
The physical and logical organization of a report interact to determine
what is presented on a page.
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.
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:
- ALL CONTROL FOOTING report groups are presented up to and including
the one at the level at which the control break occurred.
- ALL CONTROL HEADING report groups are presented from the control
break level down to the most minor control.
- The DETAIL report group named in the GENERATE statement is presented.
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.
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.
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.)
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.)
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.
In the Report Section, neither a sum counter nor the special registers
LINE-COUNTER and PAGE-COU
NTER can be used as a subscript.
Information concerning the Input-Output Section is located in the
chapter Program Definition in your Language Reference.
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
- 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.
- 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.
Information concerning the I-O-Control paragraph is located in the
chapter Program Definition in your Language Reference.
Additional Syntax Rules
- A report file can not appear in a SAME clause for which the RECORD
phrase is specified.
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
- 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.
- The clauses which follow file-name-1 can appear in any order.
- File-name-1 can only reference a sequential file.
- No record description entries can follow the file description entry
for a report file.
Record description entries are permitted.
- 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
- 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.
- Details on the REPORT clause are presented below.
The REPORT clause specifies the names of reports that comprise a report
file.
General Format
Syntax Rules
- 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.
- A report-name must appear in only one REPORT clause.
A report-name can appear in two REPORT clauses.
- 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
- The presence of more than one report-name in a REPORT clause
indicates that the file contains more than one report.
- 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.
-
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.
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
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.
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.
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
- Report-name-1 must appear in one and only one REPORT clause.
- The order of appearance of the clauses following report-name-1 is
immaterial.
- 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
- The CODE clause, the CONTROL clause, and the PAGE clause are resented
in alphabetical order below.
-
If the RD entry contains the GLOBAL clause, the
special registers LINE-COUNTER and PAGE-COUNTER are global names.
- 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.)
- 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.
- 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.
- Execution of the INITIATE statement causes the RWCS to set the
PAGE-COUNTER of the referenced report to one.
- PAGE-COUNTER is automatically incremented by one each time the RWCS
executes a page advance.
- PAGE-COUNTER can be altered by Procedure Division statements.
- 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.)
- 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.
- 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.
- 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.
- 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.
- 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 specifies a two-character literal that identifies each
print line as belonging to a specific report.
General Format
Syntax Rules
- 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.
- If the CODE clause is specified for any report in a file, it must be
specified for all reports in that file.
General Rules
- When the CODE clause is specified, literal-1 is automatically placed
in the first two character positions of each report writer logical
record.
- 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 establishes the levels of the control hierarchy for
the report.
General Format
Syntax Rules
- Data-name-1 must not be defined in the Report Section. Data-name-1
can be qualified.
- Each recurrence of data-name-1 must identify a different data item.
- Data-name-1 must not have subordinate to it a variable occurrence
data item.
General Rules
- 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.
- 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.)
- 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:
- If the control data item is a numeric data item, the relation
test is for the comparison of two numeric operands.
- If the control data item is an index data item, the relation test
is for the comparison of two index data items.
- 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.)
- FINAL is used when the most inclusive control group in the report is
not associated with a control data-name.
The PAGE clause defines the length of a page and the vertical
subdivisions within which rep
ort groups are presented.
General Format
Syntax Rules
- The
HEADING,
FIRST DETAIL,
LAST DETAIL, and
FOOTING phrases can be written in any order.
- Integer-1 must not exceed three significant digits in length.
- Integer-2 must be greater than or equal to one.
- Integer-3 must be greater than or equal to integer-2.
- Integer-4 must be greater than or equal to integer-3.
- Integer-5 must be greater than or equal to integer-4.
- Integer-1 must be greater than or equal to integer-5.
- 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 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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
- The vertical format of a report page is established using the integer
values specified in the PAGE clause.
- Integer-1 defines the size of a report page by specifying the
number of lines available on each page.
- HEADING integer-2 defines the first line number on which a report
heading or page heading report group can be presented.
- 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.
- LAST DETAIL integer-4 defines the last line number on which a
control heading or detail report group can be presented.
- 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.
- If the PAGE clause is specified the following implicit values are
assumed for any omitted phrases:
- If the HEADING phrase is omitted, a value of one is assumed for
integer-2.
- If the FIRST DETAIL phrase is omitted, a value equal to integer-2
is given to integer-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.
- If the FOOTING phrase is specified and the LAST DETAIL phrase is
omitted, the value of integer-5 is given to integer-4.
- If the LAST DETAIL phrase is specified and the FOOTING phrase is
omitted, the value of integer-4 is given to integer-5.
- If the PAGE clause is omitted, the report consists of a single page
of indefinite length.
- 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 that are established by the PAGE clause are described in
the table below.
Table 1-1: Page Regions
| Report Groups that can be represented in
the Region |
First line no. of the Region |
Last line no. of the Region |
Report heading described with NEXT GROUP
NEXT PAGE
Report footing described with LINE integer-1 NEXT PAGE |
integer-2 |
integer-1 |
Report heading not described with NEXT
GROUP NEXT PAGE
Page heading |
integer-2 |
integer-3 minus 1 |
Control footing
Detail |
integer-3 |
integer-4 |
| Control footing |
integer-3 |
integer-5 |
Page footing
Report footing not described with LINE integer-1 NEXT PAGE |
integer-5 plus 1 |
integer-1 |
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
- The report group description entry can appear only in the Report
Section.
- Except for the data-name clause, which when present must immediately
follow the level-number, the clauses can be written in any sequence.
- A description of a report group can consist of one, two, three or
four hierarchic levels:
- The first entry that describes a report group must be a Format 1
entry.
- Both Format 2 and Format 3 entries can be immediately subordinate
to a Format 1 entry.
- At least one Format 3 entry must be immediately subordinate to a
Format 2 entry.
- Format 3 entries must define elementary data items.
- In the Report Section, the USAGE clause is used only to declare the
usage of printable items.
- If the USAGE clause appears in a Format 3 entry, that entry must
define a printable item.
- If the USAGE clause appears in a Format 1 or Format 2 entry, at
least one subordinate entry must define a printable item.
- 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
- 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
- The level-number can be any integer from 02 to 48 inclusive.
- An entry must contain at least one optional clause.
- Data-name-1 is optional. If present it can be used only to qualify a
sum counter reference.
Format 3
- The level-number can be any integer from 02 to 49 inclusive.
- 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.
- 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
- Format 1 is the report group entry. The report is defined by the
contents of this entry and all of its subordinate entries.
- 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.
The tables and rules on the following pages specify:
- The permissible combinations of LINE NUMBER and NEXT GROUP clauses
for each type of report group.
- The requirements that are placed on the use of these clauses, and
- The interpretation that the RWCS gives to these clauses.
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:
- 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
- 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.
- 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.
- Next group rules.
The next group rules relate to the proper use of the NEXT GROUP
clause.
- 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.
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.
- 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.
- 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.
- 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).
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.
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.
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:
- 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.
- Lower limit rules.
- 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.
- 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.
- First print line position rules.
- 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.
- 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.
- The report heading report group is not presented.
- 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.
- Next group rules.
- 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.
- 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.
- 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.
- Final LINE-COUNTER setting rules.
- After the report heading report group is presented, the RWCS
places the NEXT GROUP integer into LINE-COUNTER as the final
LINE-COUNTER setting.
- 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.
- After the report heading report group is presented, the RWCS
places zero into LINE-COUNTER as the final LINE-COUNTER setting.
- 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.
- LINE-COUNTER is unaffected by the processing of a non-printable
report group.
Table 1-3: Report Heading Group Presentation Rules
| ** |
Applicable Rules*** |
| If the PAGE Clause is
specified |
If the PAGE Clause is
omitted |
| Sequence of LINE NUMBER Clauses* |
NEXT GROUP Clause |
Upper Limit |
Lower Limit |
First Print Line Position |
Next Group |
Final LINE COUNTER Setting |
First Print Line Position |
Final LINE COUNTER Setting |
| AR |
Absolute |
1 |
2a |
3a |
4a |
5a |
Illegal Combination+ |
| AR |
Relative |
1 |
2a |
3a |
4b |
5b |
Illegal Combination+ |
| AR |
NEXT PAGE |
1 |
2b |
3a |
4c |
5c |
Illegal Combination+ |
| AR |
|
1 |
2a |
3a |
|
5d |
Illegal Combination+ |
| R |
Absolute |
1 |
2a |
3b |
4a |
5a |
Illegal Combination++ |
| R |
Relative |
1 |
2a |
3b |
4b |
5b |
3b |
5b |
| R |
NEXT PAGE |
1 |
2b |
3b |
4c |
5c |
Illegal Combination++ |
| R |
|
1 |
2a |
3b |
|
5d |
3d |
5d |
| |
|
|
|
3c |
|
5e |
3c |
5e |
| * |
See the section LINE NUMBER Clause
Notation for a description of the abbreviations used in column 1. |
| ** |
A blank entry in column 1 or column 2
indicates that the named clause is totally absent from the report group
description entry. |
| *** |
A blank entry in an applicable rules
column indicates the absence of the named rule for the given combination
of LINE NUMBER and NEXT GROUP clauses. |
| + |
See the section The LINE NUMBER Clause. |
| ++ |
See the section The NEXT GROUP Clause. |
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
| ** |
Applicable Rules*** |
| If the PAGE clause is specified**** |
| Sequence of LINE NUMBER clauses* |
NEXT GROUP clause |
Upper Limit |
Lower Limit |
First Print Line Position |
Next Group |
Final LINE- COUNTER Setting |
| AR |
|
1 |
2 |
3a |
|
4a |
| R |
|
1 |
2 |
3b |
|
4a |
| |
|
|
|
3c |
|
4b |
| * |
See the section LINE NUMBER Clause
Notation for a description of the abbreviations used in column 1.
|
| ** |
A blank entry in column 1 or column 2
indicates that the named clause is totally absent from the report group
description entry. |
| *** |
A blank entry in an applicable rules
column indicates the absence of the named rule for the given combination
of LINE NUMBER and NEXT GROUP clauses. |
| **** |
If the PAGE clause is omitted from the
report description entry, then a page heading report group can not be
defined. (See the section The TYPE clause.) |
The page heading group presentation rules are as follows:
- 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.
- 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.
- First print line position rules.
- 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.
- 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.
- The page heading report group is not presented.
- Final LINE-COUNTER setting rules.
- The final LINE-COUNTER setting is the line number on which the
final print line of the page heading report group was presented.
- LINE-COUNTER is unaffected by the processing of a nonprintable
report group.
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:
- 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.
- 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.
- Fit test rules.
- 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.
- 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.
- 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.
- First print line position rules.
- The first print line of the body group is presented on the line
number specified by the integer of its LINE NUMBER clause.
- 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.
- The body group is not presented.
- 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.
- 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.
- Final LINE-COUNTER setting rules.
- 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.
- 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.
- 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.
- The final LINE-COUNTER setting is the line number on which the
final print line of the body group was presented.
- LINE-COUNTER is unaffected by the processing of a nonprintable
body group.
- 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
| ** |
Applicable Rules*** |
| If the PAGE Clause is
specified |
If the PAGE Clause is
omitted |
| Sequence of LINE NUMBER Clauses* |
NEXT GROUP Clause |
Upper Limit |
Lower Limit |
Fit Test |
First Print Line Position |
Next Group |
Final LINE COUNTER Setting |
First Print Line Position |
Final LINE COUNTER Setting |
| AR |
Absolute |
1 |
2 |
3a |
4a |
5 |
6a |
Illegal Combination+ |
| AR |
Relative |
1 |
2 |
3a |
4a |
|
6b |
Illegal Combination+ |
| AR |
NEXT PAGE |
1 |
2 |
3a |
4a |
|
6c |
Illegal Combination+ |
| AR |
|
1 |
2 |
3a |
4a |
|
6d |
Illegal Combination+ |
| R |
Absolute |
1 |
2 |
3b |
4b |
5 |
6a |
Illegal Combination+ |
| R |
Relative |
1 |
2 |
3b |
4b |
|
6b |
4d |
6f |
| R |
NEXT PAGE |
1 |
2 |
3b |
4b |
|
6c |
Illegal Combination+ |
| R |
|
1 |
2 |
3b |
4b |
|
6d |
4d |
6f |
| NP R |
Absolute |
1 |
2 |
3c |
4a |
5 |
6a |
Illegal Combination+ |
| NP R |
Relative |
1 |
2 |
3c |
4a |
|
6b |
Illegal Combination+ |
| NP R |
NEXT PAGE |
1 |
2 |
3c |
4a |
|
6c |
Illegal Combination+ |
| NP R |
|
1 |
2 |
3c |
4a |
|
6d |
Illegal Combination+ |
| |
|
|
|
|
4c |
|
6e |
4c |
6e |
| * |
See the section LINE NUMBER Clause
Notation for a description of the abbreviations used in column 1. |
| ** |
A blank entry in column 1 or column 2
indicates that the named clause is totally absent from the report group
description entry. |
| *** |
A blank entry in an applicable rules
column indicates the absence of the named rule for the given combination
of LINE NUMBER and NEXT GROUP clauses. |
| + |
See the section The LINE NUMBER Clause. |
| ++ |
See the section The NEXT GROUP Clause. |
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
| ** |
Applicable Rules*** |
| If the PAGE clause is
specified**** |
| Sequence of LINE NUMBER clauses* |
NEXT GROUP clause |
Upper Limit |
Lower Limit |
First Print Line Position |
Next Group |
Final LINE-COUNTER Setting |
| AR |
Absolute |
1 |
2 |
3a |
4a |
5a |
| AR |
Relative |
1 |
2 |
3a |
4b |
5b |
| AR |
|
1 |
2 |
3a |
|
5c |
| |
|
|
|
3b |
|
5d |
| * |
See the section LINE NUMBER Clause
Notation for a description of the abbreviations used in column 1 |
| ** |
A blank entry in column 1 or column 2
indicates that the named clause is totally absent from the report group
description entry. |
| *** |
A blank entry in an applicable rules
column indicates the absence of the named rule for the given combination
of LINE NUMBER and NEXT GROUP clauses. |
| **** |
If the PAGE clause is omitted from the
report description entry, then a page footing report group can not be
defined. (See the section The TYPE clause.) |
The page footing presentation rules are as follows:
- 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.
- 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.
- First print line position rules.
- The first print line of the page footing report group is
presented on the line specified by the integer of its LINE NUMBER
clause.
- The page footing report group is not presented.
- Next group rules.
- 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.
- 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.
- Final LINE-COUNTER setting rules.
- After the page footing report group is presented, the RWCS places
the NEXT GROUP integer into LINE-COUNTER as the final LINE-COUNTER
setting.
- 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.
- 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.
- LINE-COUNTER is unaffected by the processing of a nonprintable
report group.
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:
- Upper limit rules.
- 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.
- 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.
- 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.
- First print line position rules:
- The first print line of the report footing report group is
presented on the line specified by the integer of its LINE NUMBER
clause.
- 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.
- 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.
- 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.
- 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.
- The report footing report group is not presented.
- Final LINE-COUNTER setting rules.
- The final LINE-COUNTER setting is the line number on which the
final print line of the report footing report group is presented.
- LINE-COUNTER is unaffected by the processing of a nonprintable
report group.
Table 1-7: Report Footing Presentation Rules
| ** |
Applicable Rules*** |
| If the PAGE Clause is
specified |
If the PAGE Clause is
omitted |
| Sequence of LINE NUMBER Clauses* |
NEXT GROUP Clause |
Upper Limit |
Lower Limit |
First Print Line Position |
Next Group |
Final LINE COUNTER Setting |
First Print Line Position |
Final LINE COUNTER Setting |
| AR |
|
1a |
2 |
3a |
|
4a |
Illegal Combination+ |
| R |
|
1a |
2 |
3b |
|
4a |
3d |
4a |
| NP R |
|
1b |
2 |
3c |
|
4a |
Illegal Combination+ |
| |
|
|
|
3e |
|
4b |
3e |
4b |
| * |
See the section LINE NUMBER Clause
Notation for a description of the abbreviations used in column 1. |
| ** |
A blank entry in column 1 or column 2
indicates that the named clause is totally absent from the report group
description entry. |
| *** |
A blank entry in an applicable rules
column indicates the absence of the named rule for the given combination
of LINE NUMBER and NEXT GROUP clauses. |
| + |
See the section The LINE 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
- 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.
- 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
- 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.
- Integer-1 specifies the column number of the leftmost character
position of the printable item.
- The RWCS supplies space characters for all positions of a print line
that are not occupied by printable items.
- The leftmost position of the print line is considered to be column
number 1.
A data-name specifies the name of the data item being described.
General Format
Syntax Rules
- In the report section data-name-1 need not appear in a data
description entry.
General Rules
- In the Report Section, data-name-1 must be given in the following
cases:
- When data-name-1 represents a report group to be referred to by a
GENERATE or a USE statement in the procedure division.
- When reference is to be made to the sum counter in the procedure
division or report section.
- When a DETAIL report group is referenced in the UPON phrase of
the SUM clause.
- When data-name-1 is required to provide sum counter
qualification.
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
- The GROUP INDICATE clause must be specified only in a DETAIL report
group entry that defines a printable item.
General Rules
- If a GROUP INDICATE clause is specified, it causes the SOURCE or
VALUE clause to be ignored and spaces supplied, except:
- On the first presentation of the DETAIL report group in the
report, or:
- On the first presentation of the DETAIL report group after every
page advance, or:
- On the first presentation of the DETAIL report group after every
control group.
- 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.
The level-number indicates the position of a data item in the
hierarchical structure of a report group.
General Format
Syntax Rules
- A level-number is required as the first element in each data
description entry.
- Data description entries subordinate to an RD entry must have
level-numbers 01 through 49 only.
General Rules
- The level-number 01 identifies the first entry in a report group.
- Multiple level 01 entries subordinate to a report description entry
having the level indicator RD do not represent implicit redefinitions of
the same area.
The LINE NUMBER clause specifies vertical positioning information for
its report group.
General Format
Syntax Rules
- 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.
- 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.
- Within a given report group description entry, all absolute LINE
NUMBER clauses must precede all relative LINE NUMBER clauses.
- 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.
- 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.
- 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.
- 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.
- 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.
- The first LINE NUMBER clause specified in a PAGE FOOTING report group
must be an absolute LINE NUMBER clause.
General Rules
- A LINE NUMBER clause must be specified to establish each print line
of a report group.
- The RWCS affects the vertical positioning specified by a LINE NUMBER
clause, before presenting the print line established by that LINE NUMBER
clause.
- Integer-1 specifies an absolute line number. An absolute line number
specifies the line number on which the print line is presented.
- 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.)
- 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.
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
- 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.
- Integer-1 and integer-2 must not exceed three significant digits in
length.
- 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.
- The NEXT PAGE phrase of the NEXT GROUP clause must not be specified
in a PAGE FOOTING report group.
- The NEXT GROUP clause must not be specified in a REPORT FOOTING
report group or in a PAGE HEADING report group.
General Rules
- 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.)
- 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.)
- 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.
- 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.)
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
- The SIGN clause can be specified only for a numeric data description
entry whose PICTURE contains the character "S".
- The numeric data description entries to which the SIGN clause applies
must be described, implicitly or explicitly, as USAGE IS DISPLAY.
- When the SIGN clause is included in a report group description entry,
the SEPA
RATE CHARACTER phrase must be specified.
General Rules
- 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.
- 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 sectionSelection Of Character Representation And
Radix in the chapter Concepts of the COBOL Language in your
Language Reference.
- Since a SIGN clause in a report group description entry must specify
the SEPARATE CHARACTER phrase, then:
- 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.
- The letter "S" in a PICTURE character-string is counted
in determining the size of the item (in terms of standard data
format characters).
- The operational signs for positive and negative are the standard
data format characters "+" , and "–",
respectively.
- 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.
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
- 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:
- PAGE-COUNTER, or:
- LINE-COUNTER, or:
- Sum counter that is part of the report within which the SOURCE
clause appears.
- 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
- 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.
The SUM clause establishes a sum counter and names the data items to be
summed.
General Format
Syntax Rules
- 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.
- 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.
- A SUM clause can appear only in the description of a CONTROL FOOTING
report group.
- 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.
- The highest permissible qualifier of a sum counter is the
report-name.
General Rules
- 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.)
- 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.
- Only one sum counter exists for an elementary report entry regardless
of the number of SUM clauses specified in the elementary report entry.
- 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.
- 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.
- It is permissible for Procedure Division statements to alter the
contents of sum counters.
- 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.)
- The UPON phrase provides the capability to accomplish selective
subtotalling for the DETAIL report groups named in the phrase.
- The RWCS adds each individual addend into the sum counter at a time
that depends upon the characteristics of the addend.
- 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.
- 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.
- 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.
- 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.
- 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.)
- 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.
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
- 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.
- 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.
- PAGE HEADING and PAGE FOOTING report groups can be specified only if
a PAGE clause is specified in the corresponding report description
entry.
- 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.
- In CONTROL FOOTING, PAGE HEADING, PAGE FOOTING, AND REPORT FOOTING
report groups, SOURCE clauses and USE statements must not reference any
of the following:
- Group data items containing a control data item.
- Data items subordinate to a control data item.
- 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.
- 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.
- The description of a report must include at least one body group.
General Rules
-
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.
- 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.
- 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:
- 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.
- 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.)
- 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.
- The
DETAIL phrase specifies a report group that is processed by the
RWCS when a corresponding GENERATE statement is executed.
- 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.)
- 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:
- 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.
- 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.)
- 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.)
- 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.
- If a USE BEFORE REPORTING procedure references the data-name of
the report group, the USE procedure is executed.
- If a
SUPPRESS statement has been executed or if the report group is
not printable, no further processing is done for the report group.
- 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.)
- 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.
- 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.)
- 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.)
- If a USE BEFORE REPORTING procedure references the data-name of
the report group the USE procedure is executed.
- 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.
- 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.
- 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.)
- 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.
- The RWCS performs any subtotalling that has been designated for
the DETAIL report group. (See the section The SUM Clause
earlier in this chapter.)
- If a USE BEFORE REPORTING procedure refers to the data-name of
the report group, the USE procedure is executed.
- If a SUPPRESS statement has been executed or if the report group
is not printable no further processing is done for the report group.
- 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.
- 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.)
- 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.
- 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.
- 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.
- 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.
- 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.
The USAGE clause specifies the format of a data item in the computer
storage.
General Format
Syntax Rules
- The USAGE clause can be written in any data description entry.
- 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.
- The USAGE clause for a report group item can specify only USAGE IS
DISPLAY.
General Rules
- If the USAGE clause is written at a group level, it applies to each
elementary item in the group.
- 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.
- The USAGE IS DISPLAY clause indicates that the format of the data is
a standard data format.
- 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.
The VALUE clause defines the value of Report Section printable items.
General Format
Syntax Rules
- A signed numeric literal must have associated with it a signed
numeric PICTURE character-string.
- 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
- 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:
- If the category of the item is numeric, literal-1 in the VALUE
clause must be numeric.
- 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.
- Initialization is not affected by any BLANK WHEN ZERO or
JUSTIFIED clause that can be specified.
- 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).
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.
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
- The files referenced in the CLOSE statement need not all have the
same organization or access.
- 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.
- A CLOSE statement can only be executed for a file in an open mode.
- 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:
- Non-reel/unit. A file whose output medium is such that the
concepts of rewind and reels/units have no meaning.
- Sequential single-reel/unit. A sequential file that is entirely
contained on one reel/unit.
- Sequential multi-reel/unit. A sequential file that is contained
on more than one reel/unit.
- 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.
- 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.
- No Rewind of Current Reel
The reel/unit is left in its current position.
- 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.
- 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.
- File Lock
The report file is locked and cannot be opened again during this
execution of this run unit.
- Close Reel/Unit
Output Report File (Reel/Unit Media):
The following operations take place:
- The standard ending reel/unit label procedure is executed.
- A reel/unit swap. The current volume pointer is updated to
point to the new reel/unit.
- The standard beginning reel/unit label procedure is executed.
- 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.
- Rewind
The current reel or analogous device is positioned at its
physical beginning.
- Optional Phrases Ignored
The CLOSE statement is executed as if none of the optional
phrases is present.
- The execution of the CLOSE statement causes the value of the I/O
status associated with file-name-1 to be updated.
- 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.
- 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.
- 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.
The GENERATE statement directs the RWCS to produce a report in
accordance with the Report Description specified in the Report Section of
the Data Division.
General Format
Syntax Rules
- Data-name-1 must name a TYPE D
ETAIL report group and can be qualified by a report-name.
- Report-name-1 can be used only if the referenced report description
contains:
- A CONTROL clause, and
- Not more than one DETAIL report group, and
- At least one body group.
General Rules
- 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.
- 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.
- 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.
- 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.)
- 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.)
- The REPORT HEADING report group is processed.
- The PAGE HEADING report group is processed.
- All CONTROL HEADING report groups are processed from major to
minor.
- 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.)
- 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.)
- 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:
- 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.)
- 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.
- 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.
- 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.)
- 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.
The INITIATE statement causes the RWCS to begin the processing of a
report.
General Format
Syntax Rules
- Report-name-1 must be defined by a report description entry in the
report section of the Data Division.
General Rules
- The INITIATE statement performs the following initialization
functions for each named report:
- All
sum counters are set to zero.
- LINE-COUNTER is set to zero.
- PAGE-COUNTER is set to one.
- 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.
- A subsequent INITIATE statement for report-name-1 must not be
executed unless an intervening TERMINATE statement has been executed for
report-name-1.
- 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.
See the chapter Program Definition in your Language
Reference.
Additional Syntax Rules
- A report file must have sequential organization.
- The OPEN statement for a report file must contain only the OUTPUT
phrase or the EXTEND phrase.
Additional General Rules
- 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.
The SUPPRESS statement causes the RWCS to inhibit the presentation of a
report group.
General Format
Syntax Rules
- The SUPPRESS statement can only appear in a USE BEFORE REPORTING
procedure.
General Rules
- The SUPPRESS statement inhibits presentation only for the report
group named in the USE procedure in which the SUPPRESS statement
appears.
- The SUPPRESS statement must be executed each time the presentation of
the report group is to be inhibited.
- When the SUPPRESS statement is executed, the RWCS is instructed to
inhibit the processing of the following report group functions:
- The presentation of the print lines of the report group.
- The processing of all LINE clauses in the report group.
- The processing of the NEXT GROUP clause in the report group.
- The adjustment of LINE-COUNTER.
-
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
The TERMINATE statement causes the RWCS to complete the processing of
the specified reports.
General Format
Syntax Rules
- Report-name-1 must be defined by a report description entry in the
Report Section of the Data Division.
General Rules
- 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.
- 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.
- 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.)
- 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.
- 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.
- 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.
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
- 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.
- 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.
- 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.
- A USE BEFORE REPORTING procedure must not alter the value of any
control data item.
- The USE BEFORE REPORTING statement itself is never executed; it
merely defines the conditions calling for the execution of the USE
procedures.
General Rules
- 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.
- Within a declarative procedure, there must be no reference to any
nondeclarative procedures.
- 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.
- 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.)
- 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.
- 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:
- The declarative within the program that contains the statement
which caused the qualifying condition.
- 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.
- 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.
Copyright © 1999 MERANT International Limited. All rights reserved.
This document and the proprietary marks and names
used herein are protected by international law.
|
| Communication | |