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-COUNTER 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 report 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
- TheGROUP 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 section
Selection 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 DETAIL 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 © 2001 Micro Focus International Limited. All rights reserved.
This document and the proprietary marks and names
used herein are protected by international law.