|
| Communication | |
The Report Writer is a special purpose feature which places its emphasis
on the organization, format, and contents of an output report. Although a
report can be produced using the standard COBOL language, the Report Writer
language features provide a more concise facility for report structuring and
report production. Much of the Procedure Division programming which would
normally be supplied by the programmer is instead provided automatically by
the Report Writer Control System (RWCS). Thus the programmer is relieved of
writing procedures for moving data, constructing print lines, counting lines
on a page, numbering pages, producing heading and footing lines, recognizing
the end of logical data subdivisions, updating sum counters, and so on. All
these operations are accomplished by the RWCS as a consequence of source
language statements that appear primarily in the report section of the data
division of the source program.
Although it is a part of the
standard COBOL definition, this module is explicity excluded from the X/Open
COBOL language definitions and should not be used in a conforming X/Open
COBOL source program.
The OS/VS COBOL compiler
provides support for Report Writer that is based on the ANSI'68 Standard
(even when the mainframe LANGLVL(2) compiler option is used - which normally
requests ANSI'74 support). However, there are many cases in which that
compiler actually supports a cross between the two COBOL Standards.
Therefore, you should not attempt to use your COBOL system with OS/VS COBOL
emulation along with any other dialect.
Within this chapter, many of
these OS/VS COBOL extensions are indicated by an OSVS bubble. However, for
the exact rules for the OS/VS COBOL Report Writer syntax, you should refer to
your IBM OS/VS COBOL Language Reference.
The Report Section of a COBOL Data Division contains one or more Report
Description entries (RD entries), each of which forms the complete
description of a report.
The report named in the RD entry is not assigned directly to an output
file. Instead, it is associated with a file-name in the File Section and that
file-name is associated with a file when an OPEN statement specifying the
file-name is executed. More than one report can be associated with the same
file-name and the CODE clause is used to differentiate among the reports. For
an external file connector referenced by a file-name, separately compiled
programs can specify different reports for the same file-name. This file
description entry must specify the name of a report description entry for
each report associated with that file-name in this program.
The RD entry contains a set of clauses that names the report and supplies
specific information about the format of the printed page and the
organization of the subdivisions of the report. An identification code can be
given in the RD entry so that each report can be identified separately in an
intermediate output file.
Following each RD entry are one or more 01 level-number entries, each
followed by a hierarchical structure similar to COBOL record descriptions.
Each 01 level-number entry and its subordinate entries describes a report
group. Each report group consists of one or more print lines that are
regarded as a unit. A
report group that is to be printed is printed entirely on one logical
page; it is never split across pages.
When structuring a report, major consideration must be given to vertical
and horizontal spacing requirements, manipulation of data, and the physical
and logical subdivisions of a report.
The Report Writer feature allows the user to describe report groups
containing multiple lines. The vert ical positioning of the lines on a page
is specified by the LINE NUMBER clause that is associated with each line. The
NEXT GROUP clause indicates how many lines to space after presenting the last
line of the group. The first LINE NUMBER clause of the next group indicates
additional spacing information to be used in positioning of that group.
The Report Writer allows the user to position the fields of data on a
report line by means of the COLUMN NUMBER clause. The RWCS supplies space
fill between all defined fields.
When the Report Writer feature is used, data movement to a report group is
directed by report section clauses rather than Procedure Division statements.
The report section clauses that affect the manipulation of data are the
SOURCE, SUM, and VALUE clauses.
The SOURCE clause specifies the sending data item of an implicit MOVE
statement. The receiving printable item is defined by the description of the
report group item in which the SOURCE clause appears.
The SUM clause automatically causes the establishment of a sum counter.
The object of the SUM clause names the data item(s) which are added to the
sum counter when a GENERATE statement is executed. The moving of the sum
counter contents to the receiving printable item, defined by the description
of the report group item in which the SUM clause appears, is accomplished
automatically when that report group is presented.
The VALUE clause defines a literal that appears in the printable item of a
report group each time that report group is to be presented.
In summary, a data item in a report group is presented only if it has a
COLUMN NUMBER clause specifying where it is to be presented. The value that
is placed in a printable item is determined by the SOURCE, SUM, or VALUE
clause stated in the report group description. Under no circumstances can a
report group printable item receive a value directly via a Procedure Division
statement.
The physical and logical organization of a report interact to determine
what is presented on a page.
The PAGE clause specifies the length of the page, the size of the heading
and footing areas, and the size of the area in which the detail lines will
appear. The RWCS uses the LINE NUMBER and NEXT GROUP clauses to position
these report groups, and when necessary, to advance to a new page with
automatic production of PAGE HEADING and PAGE FOOTING report groups.
DETAIL report groups can be structured into a nested set of control
groups. Each control group can begin with a CONTROL HEADING report group and
end with a CONTROL FOOTING report group.
When nested control groups are defined, the recognition of a change in
value of a control data item in a control hierarchy is called a control break
and the heading and footing lines associated with the control data-name are
called CONTROL HEADING and CONTROL FOOTING report groups.
During the execution of a GENERATE statement, the RWCS uses the control
hierarchy to check automatically for control breaks. If a control break has
occurred, all controls that are minor to it are considered to have changed,
even though they may not in fact have changed. The occurrence of a control
break causes the following sequence of events to take place:
- ALL CONTROL FOOTING report groups are presented up to and including the
one at the level at which the control break occurred.
- ALL CONTROL HEADING report groups are presented from the control break
level down to the most minor control.
- The DETAIL report group named in the GENERATE statement is presented.
The Report Writer statements that appear in the Procedure Division are:
INITIATE, GENERATE, TERMINATE, SUPPRESS, and USE BEFORE REPORTING.
The INITIATE statement causes the RWCS to perform automatically a number
of initialization functions. A report must be initiated before any detail
processing can take place.
The GENERATE statement which specifies a data-name causes the named DETAIL
report group to be formatted and written to the output device. In addition,
it triggers the RWCS to perform the many implicit actions described in the
preceding section.
The GENERATE statement which specifies a report-name provides a means of
summary reporting. A report produced by this type of statement has all detail
print lines suppressed automatically and consists of only the summary totals
accumulated during the processing of the
DETAIL report group. The RWCS processing for a GENERATE report-name
statement is identical to that which occurs for a GENERATE data-name
statement, except that the former results in the suppression of detail print
lines.
The TERMINATE statement causes the RWCS to perform all of the automatic
functions associated with the termination of a report. The TERMINATE
statement must be executed before the file containing the report is closed.
The SUPPRESS statement provides the object time facility to suppress the
printing of an entire report group.
The BEFORE REPORTING phrase of the USE statement provides a mechanism
whereby Procedure Division statement can be executed at specific instances in
the automatic procedures performed by the RWCS. The statements in the USE
BEFORE REPORTING procedure can alter the contents of the data items that are
referenced by SOURCE clauses. Thus control is possible over the contents of
data items referenced in report groups that are produced automatically.
A report file is an output file having sequential organization. A report
file has a file description entry containing a REPORT clause. The content of
a report file consists of records that are written under control of the RWCS.
A report file is named by a file control entry and is described by a file
description entry containing a REPORT clause. A report file is referred to
and accessed by the OPEN, GENERATE, INITIATE, SUPPRESS, TERMINATE, USE BEFORE
REPORTING, and CLOSE statements.
The reserved word PAGE-COUNTER is a name for a page counter that is
generated for each RD entry in the report section of the Data Division. The
implicit description is PIC 9(6) BINARY. The value in PAGE-COUNTER is
maintained by the RWCS and is used by the program to number the pages of a
report. PAGE-COUNTER can be referenced only in the SOURCE clause of the
Report Section and in Procedure Division statements. (See the section PAGE-COUNTER
Rules later in this chapter.)
The reserved word LINE-COUNTER is a name for a line counter that is
generated for each RD entry in the report section of the data division. The
implicit description is PIC 9(6) BINARY. The value in LINE-COUNTER is
maintained by the RWCS, and is used to determine the vertical
positioning of a report. LINE-COUNTER can be referenced only in the
SOURCE clause of the report section and in Procedure Division statements;
however, only the RWCS can change the value of LINE-COUNTER. (See the section
LINE-COUNTER Rules later in this chapter.)
The reserved word PRINT-SWITCH is a name for a register whose value may be
set to non-zero in the course of a USE BEFORE REPORTING declarative
procedure. This has the effect of suppressing printing of the corresponding
report group.
In the Report Section, neither a sum counter nor the special registers
LINE-COUNTER and PAGE-COU
NTER can be used as a subscript.
Information concerning the Input-Output Section is located in the chapter
Program Definition in your Language Reference.
Information concerning the FILE-CONTROL paragraph is located in the
chapter Program Definition in your Language Reference.
Function
The file-control entry declares the relevant physical attributes of a
report file.
Additional Syntax Rules
- The OPTIONAL phrase applies only to a report opened in the extend mode.
Its specification is required for a report file that is not necessarily
present each time the object program is executed.
- A report file must have sequential organization. Each report file
specified in the SELECT clause must have a file description entry containing
a REPORT clause in the Data Division of the same program.
Information concerning the I-O-Control paragraph is located in the chapter
Program Definition in your Language Reference.
Additional Syntax Rules
- A report file can not appear in a SAME clause for which the RECORD
phrase is specified.
The file description entry furnishes information concerning the physical
structure, identification, and record-names pertaining to a given file.
It determines the internal or
external attributes of a file connector, of the associated data records, and
of the associated data items. The file description entry also determines
whether a file-name is a local name or a global name.
General Format
Syntax Rules
- The level indicator FD identifies the beginning of the file description
entry for a report file and must precede the file-name of the report file.
- The clauses which follow file-name-1 can appear in any order.
- File-name-1 can only reference a sequential file.
- No record description entries can follow the file description entry for
a report file.
Record description entries
are permitted.
- The subject of a file description entry that specifies a REPORT clause
can be referenced in the procedure division only by the USE statement, the
CLOSE statement, or the OPEN statement with the OUTPUT or EXTEND phrase.
General Rules
- With the exception of the REPORT clause, all clauses in the file
description entry for a report file are presented in the sequential I-O
module.
- Details on the REPORT clause are presented below.
The REPORT clause specifies the names of reports that comprise a report
file.
General Format
Syntax Rules
- Each report-name specified in a REPORT clause must be the subject of a
RD entry in the report section of the same program. The order of appearance
of the report-names is not significant.
- A report-name must appear in only one REPORT clause.
A report-name can appear in two
REPORT clauses.
- The subject of a file description entry that specifies a REPORT clause
can be referenced in the procedure division only by the USE statement, the
CLOSE statement, or the OPEN statement with the OUTPUT or EXTEND phrase.
General Rules
- The presence of more than one report-name in a REPORT clause indicates
that the file contains more than one report.
- After execution of an INITIATE statement and before the execution of a
TERMINATE statement for the same report file, the report file is under the
control of the RWCS. While a report file is under the control of the RWCS,
no input-output statement can be executed which references that report file.
-
If the associated file
connector is an external file connector, every file description entry in the
run unit which is associated with that file connector must describe it as a
report file.
The Report Section is located in the Data Division of a source program.
The Report Section describes the reports to be written onto report files. The
description of each report must begin with a RD entry and be followed by one
or more report group description entries.
General Format
In addition to naming the report, the RD entry defines the
format of each page of the report by specifying the vertical boundaries
of the region within which each type of report group can be printed. The RD
entry also specifies the control data items. When the report is produced,
changes in the values of the control data items cause the detail information
of the report to be processed in groups called control groups.
Each report named in the REPORT clause of a file description entry in the
file section must be the subject of a RD entry in the report section.
Furthermore, each report in the report section must be named in one and only
one file description entry.
The rep
ort groups that will comprise the report are described following the RD
entry. The description of each report group begins with a report group
description entry; that is an entry that has a 01 level-number and a TYPE
clause. Subordinate to the report group description entry, there can appear
group and elementary entries that further describe the characteristics of the
report group.
The RD entry names a report, specifies any identifying characters to be
appended to each print line in the report and describes the physical
structure and organization of that report.
It also determines whether a
report-name is a local name or a global name.
General Format
Syntax Rules
- Report-name-1 must appear in one and only one REPORT clause.
- The order of appearance of the clauses following report-name-1 is
immaterial.
- Report-name-1 is the highest permissible qualifier that can be specified
for LINE-COUNTER, PAGE-COUNTER, and all data-names defined in the report
section.
General Rules
- The CODE clause, the CONTROL clause, and the PAGE clause are resented in
alphabetical order below.
-
If the RD entry contains the
GLOBAL clause, the special registers LINE-COUNTER and PAGE-COUNTER are
global names.
-
PAGE-COUNTER is the reserved word used to reference a special register
that is automatically created for each report specified in the report
section. (See the section Special Register PAGE-COUNTER earlier in
this chapter.)
- In the report section, a reference to PAGE-COUNTER can appear only in a
SOURCE clause. In the Procedure Division, PAGE-COUNTER can be used in any
context in which a data item with an integer value can appear.
- If more than one PAGE-COUNTER exists in a program, PAGE-COUNTER must be
qualified by a report-name whenever it is referenced in the Procedure
Division.
In the report section an unqualified reference to PAGE-COUNTER is
qualified implicitly by the name of the report in whose RD entry the
reference is made. Whenever the PAGE-COUNTER of a different report is
referenced, PAGE-COUNTER must be explicitly qualified by the report-name
associated with the different report.
- Execution of the INITIATE statement causes the RWCS to set the
PAGE-COUNTER of the referenced report to one.
- PAGE-COUNTER is automatically incremented by one each time the RWCS
executes a page advance.
- PAGE-COUNTER can be altered by Procedure Division statements.
-
LINE-COUNTER is the reserved word used to reference a special register
that is automatically created for each report specified in the Report
Section. (See the section Special Register LINE-COUNTER earlier in
this chapter.)
- In the report section a reference to LINE-COUNTER can appear only in a
SOURCE clause. In the Procedure Division, LINE-COUNTER can be used in any
context in which a data item with an integral value can appear. However,
only the RWCS can change the content of LINE-COUNTER.
- If more than one LINE-COUNTER exists in a program, LINE-COUNTER must be
qualified by a report-name whenever it is referenced in the Procedure
Division.
In the Report Section an unqualified reference to LINE-COUNTER is
qualified implicitly by the name of the report in whose description entry
the reference is made. Whenever the LINE-COUNTER of a different report is
referenced, LINE-COUNTER must be explicitly qualified by the report-name
associated with the different report.
- Execution of an INITIATE statement causes the RWCS to set the
LINE-COUNTER of the referenced report to zero. The RWCS also automatically
resets LINE-COUNTER to zero each time it executes a page advance.
- The value of LINE-COUNTER is not affected by the processing of
nonprintable report groups nor by the processing of a printable report group
whose printing is suppressed by means of the SUPPRESS statement.
- At the time each print line is presented, the value of LINE-COUNTER
represents the line number on which the print line is presented. The value
of LINE-COUNTER after the presentation of a report group is governed by the
presentation rules for the report group. (See the section Presentation
Rules Tables later in this chapter.)
The CODE clause specifies a two-character literal that identifies each
print line as belonging to a specific report.
General Format
Syntax Rules
- Literal-1 must be a two-character nonnumeric literal.
Literal-1 may be replaced by a
mnemonic-name specified in the special-names paragraph. See the OS/VS
COBOL Language Reference for additional details.
- If the CODE clause is specified for any report in a file, it must be
specified for all reports in that file.
General Rules
- When the CODE clause is specified, literal-1 is automatically placed in
the first two character positions of each report writer logical record.
- The positions occupied by literal-1 are not included in the description
of the print line, but are included in the logical record size.
The CONTROL clause establishes the levels of the control hierarchy for the
report.
General Format
Syntax Rules
- Data-name-1 must not be defined in the Report Section. Data-name-1 can
be qualified.
- Each recurrence of data-name-1 must identify a different data item.
- Data-name-1 must not have subordinate to it a variable occurrence data
item.
General Rules
- Data-name-1 and the word
FINAL specify the levels of the control hierarchy. FINAL, if specified,
is the highest control, data-name-1 is the major control, the next
recurrence of data-name-1 is an intermediate control, and so on. The last
recurrence of data-name-1 is the minor control.
- The execution of the chronologically first GENERATE statement for a
given report causes the RWCS to save the values of all control data items
associated with that report. On subsequent executions of all GENERATE
statements for that report, control data items are tested by the RWCS for a
change of value. A change of value in any control data item causes a control
break to occur. This control break is associated with the highest level for
which a change of value is noted. (See the section The GENERATE
Statement later in this chapter.)
- The RWCS tests for a control break by comparing the content of each
control data item with the prior content of each control data item that was
saved when the previous GENERATE statement for the same report was executed.
The RWCS applies the inequality relation test as follows:
- If the control data item is a numeric data item, the relation test is
for the comparison of two numeric operands.
- If the control data item is an index data item, the relation test is
for the comparison of two index data items.
- If the control data item is a data item other than as described in 3a
and 3b above, the relation test is for the comparison of two nonnumeric
operands.
The inequality relation test is further explained in the appropriate
paragraph. (See the chapter Program Definition in your Language
Reference.)
- FINAL is used when the most inclusive control group in the report is not
associated with a control data-name.
The PAGE clause defines the length of a page and the vertical subdivisions
within which rep
ort groups are presented.
General Format
Syntax Rules
- The
HEADING,
FIRST DETAIL,
LAST DETAIL, and
FOOTING phrases can be written in any order.
- Integer-1 must not exceed three significant digits in length.
- Integer-2 must be greater than or equal to one.
- Integer-3 must be greater than or equal to integer-2.
- Integer-4 must be greater than or equal to integer-3.
- Integer-5 must be greater than or equal to integer-4.
- Integer-1 must be greater than or equal to integer-5.
- The following rules indicate the vertical subdivision of the page in
which each type of report group can appear when the PAGE clause is
specified. (See the section Page Regions later in this chapter.)
- A report heading report group that is to be presented on a page by
itself, if defined, must be defined such that it can be presented in the
vertical subdivision of the page that extends from the line number
specified by integer-2 to the line number specified by integer-1,
inclusive.
A report heading report group that is not to be presented on a page by
itself, if defined, must be defined such that it can be presented in the
vertical subdivision of the page that extends from the line number
specified by integer-2 to the line number specified by integer-3 minus 1,
inclusive.
- A page heading report group, if defined, must be defined such that it
can be presented in the vertical subdivision of the page that extends from
the line number specified by integer-2 to the line number specified by
integer-3 minus 1, inclusive.
- A control heading or detail report group, if defined, must be defined
such that it can be presented in the vertical subdivision of the page that
extends from the line number specified by integer-3 to the line number
specified by integer-4, inclusive.
- A control footing report group, if defined, must be defined such that
it can be presented in the vertical subdivision of the page that extends
from the line number specified by integer-3 to the line number specified
by integer-5, inclusive.
- A page footing report group, if defined, must be defined such that it
can be presented in the vertical subdivision of the page that extends from
the line number specified by integer-5 plus 1 to the line number specified
by integer-1, inclusive.
- A report footing report group that is to be presented on a page by
itself, if defined, must be defined such that it can be presented in the
vertical subdivision of the page that extends from the line number
specified by integer-2 to the line number specified by integer-1,
inclusive.
A report footing report group that is not to be presented on a page by
itself, if defined, must be defined such that it can be presented in the
vertical subdivision of the page that extends from the line number
specified by integer-5 plus 1 to the line number specified by integer-1,
inclusive.
- All report groups must be described such that they can be presented on
one page. The RWCS never splits a multi-line report group across page
boundaries.
General Rules
- The vertical format of a report page is established using the integer
values specified in the PAGE clause.
- Integer-1 defines the size of a report page by specifying the number
of lines available on each page.
- HEADING integer-2 defines the first line number on which a report
heading or page heading report group can be presented.
- FIRST DETAIL integer-3 defines the first line number on which a body
group can be presented. Report heading and page heading report groups
cannot be presented on or beyond the line number specified by integer-3.
- LAST DETAIL integer-4 defines the last line number on which a control
heading or detail report group can be presented.
- FOOTING integer-5 defines the last line number on which a control
footing report group can be presented. Page footing and report footing
report groups must follow the line number specified by integer-5.
- If the PAGE clause is specified the following implicit values are
assumed for any omitted phrases:
- If the HEADING phrase is omitted, a value of one is assumed for
integer-2.
- If the FIRST DETAIL phrase is omitted, a value equal to integer-2 is
given to integer-3.
- If the LAST DETAIL and the FOOTING phrases are both omitted, the value
of integer-1 is given to both integer-4 and integer-5.
- If the FOOTING phrase is specified and the LAST DETAIL phrase is
omitted, the value of integer-5 is given to integer-4.
- If the LAST DETAIL phrase is specified and the FOOTING phrase is
omitted, the value of integer-4 is given to integer-5.
- If the PAGE clause is omitted, the report consists of a single page of
indefinite length.
- The presentation rules for each type of report group are specified in
the appropriate paragraph. (See the section Presentation Rules Tables
later in this chapter.)
Page regions that are established by the PAGE clause are described in the
table below.
Table 1-1: Page Regions
Report Groups that can be represented in the
Region |
First line no. of the Region |
Last line no. of the Region |
Report heading described with NEXT GROUP NEXT
PAGE
Report footing described with LINE integer-1 NEXT PAGE |
integer-2 |
integer-1 |
Report heading not described with NEXT GROUP
NEXT PAGE
Page heading |
integer-2 |
integer-3 minus 1 |
Control footing
Detail |
integer-3 |
integer-4 |
Control footing |
integer-3 |
integer-5 |
Page footing
Report footing not described with LINE integer-1 NEXT PAGE |
integer-5 plus 1 |
integer-1 |
The report group description entry specifies the characteristics of a
report group and of the individual items in a report group.
General Formats
Format 1
Format 2
Format 3
Syntax Rules
All Formats
- The report group description entry can appear only in the Report
Section.
- Except for the data-name clause, which when present must immediately
follow the level-number, the clauses can be written in any sequence.
- A description of a report group can consist of one, two, three or four
hierarchic levels:
- The first entry that describes a report group must be a Format 1
entry.
- Both Format 2 and Format 3 entries can be immediately subordinate to a
Format 1 entry.
- At least one Format 3 entry must be immediately subordinate to a
Format 2 entry.
- Format 3 entries must define elementary data items.
- In the Report Section, the USAGE clause is used only to declare the
usage of printable items.
- If the USAGE clause appears in a Format 3 entry, that entry must
define a printable item.
- If the USAGE clause appears in a Format 1 or Format 2 entry, at least
one subordinate entry must define a printable item.
- An entry that contains a LINE NUMBER clause must not have a subordinate
entry that also contains a LINE NUMBER clause.
However an entry containing
the LINE NUMBER NEXT PAGE clause can have a subordinate entry containing a
LINE NUMBER clause but without the NEXT PAGE option.
Format 1
- Data-name-1 is required only when:
- A detail report group is referenced by a GENERATE statement.
- A detail report group is referenced by the UPON phrase of a SUM
clause.
- A report group is referenced in a USE BEFORE REPORTING sentence.
- The name of a control footing report group is used to qualify a
reference to a sum counter.
If specified, data-name-1 can be referenced only by a GENERATE
statement, the UPON phrase of a SUM clause, a USE BEFORE REPORTING
sentence, or as a sum counter qualifier.
Format 2
- The level-number can be any integer from 02 to 48 inclusive.
- An entry must contain at least one optional clause.
- Data-name-1 is optional. If present it can be used only to qualify a sum
counter reference.
Format 3
- The level-number can be any integer from 02 to 49 inclusive.
- In Format 3:
- A GROUP INDICATE clause can appear only in a type detail report group.
- A SUM clause can appear only in a type control footing report group.
- An entry that contains a COLUMN NUMBER clause but no LINE NUMBER
clause must be subordinate to an entry that contains a LINE NUMBER clause.
- Data-name-1 is optional but can be specified in any entry. Data-name-1
can be referenced only if the entry defines a sum counter.
- An entry that contains a VALUE clause must also have a COLUMN NUMBER
clause.
- The following table shows all permissible clause combinations for a
Format 3 entry. The table is read from left to right along the selected row.
An "M" indicates that the presence of the clause is mandatory.
A "P" indicates that the presence of the clause is permitted,
but not required.
A blank indicates that the clause is not permitted.
Table 1-2: Permissible Clause Combinations in Format 3 Entries
PIC |
COLUMN |
SOURCE |
SUM |
VALUE |
JUST |
BLANK WHEN ZERO |
GROUP INDICATE |
USAGE |
SIGN |
LINE |
M |
|
|
M |
|
|
|
|
|
P |
P |
M |
M |
|
M |
|
|
P |
|
P |
P |
P |
M |
P |
M |
|
|
P |
|
P |
P |
P |
P |
M |
P |
M |
|
|
|
P |
P |
P |
P |
P |
M |
M |
|
|
M |
P |
|
P |
P |
P |
P |
General Rules
- Format 1 is the report group entry. The report is defined by the
contents of this entry and all of its subordinate entries.
- The BLANK WHEN ZERO clause, the JUSTIFIED clause, and the PICTURE clause
for the Report Writer module are the same as the BLANK WHEN ZERO clause, the
JUSTIFIED clause, and the PICTURE clause in the nucleus. See the chapter
Program Definition in your Language Reference for
specifications. The other clauses of the report group description entry are
presented in alphabetical order later in this chapter.
The tables and rules on the following pages specify:
- The permissible combinations of LINE NUMBER and NEXT GROUP clauses for
each type of report group.
- The requirements that are placed on the use of these clauses, and
- The interpretation that the RWCS gives to these clauses.
There is an individual presentation rules table for each of the following
types of report groups: report heading, page heading, page footing, report
footing. In addition, detail report groups, control heading report groups, or
control footing report groups are treated jointly in the body group
presentation rules table. (See the section Body Group Presentation Rules
later in this chapter.)
Columns 1 and 2 of a presentation rules table list all of the permissible
combinations of LINE NUMBER and NEXT GROUP clauses for the designated report
group type. Consequently, for the purpose of identifying the set of
presentation rules that apply to a particular combination of LINE NUMBER and
NEXT GROUP clauses, a presentation rules table is read from left to right,
along the selected row.
The applicable rules columns of a presentation rules table are partitioned
into two parts. The first part specifies the rules that apply if the report
description contains a PAGE clause, and the second part specifies the rules
that apply if the PAGE clause is omitted. The purpose of the rules named in
the applicable rules columns is discussed below:
- Upper limit rules and lower limit rules.
These rules specify the vertical subdivisions of the page within which
the specified report group can be represented.
In the absence of a PAGE clause the printed report is not considered to
be partitioned into vertical subdivisions. Consequently, in the tables no
upper limit rule or lower limit rule is specified for a report description
in which the PAGE clause is omitted
- Fit test rules.
The fit test rules are applicable only to body groups, and hence fit
test rules are specified only in the body group presentation rules table.
At object time the RWCS applies the fit test rules to determine whether the
designated body group can be presented on the page to which the report is
currently positioned.
However, even for body groups there are no fit test rules when the PAGE
clause is omitted from the report description entry.
- First print line position rules.
The first print line position rules specify where on the report medium
the RWCS shall present the first print line of the given report group.
The presentation rules tables do not specify where on the report medium
the RWCS shall present the second and subsequent print lines (if any) of a
report group. Certain general rules determine where the second and
subsequent print lines of a report group shall be presented. Refer to the
LINE NUMBER clause general rules for this information.
- Next group rules.
The next group rules relate to the proper use of the NEXT GROUP clause.
- Final LINE-COUNTER setting rules.
The terminal values that the RWCS places in LINE-COUNTER after
presenting report groups are specified by the final LINE-COUNTER setting
rules.
Column 1 of the presentation rules table uses a shorthand notation to
describe the sequence of LINE NUMBER clauses that can appear in the
description of a report group. The meaning of the abbreviations used in
column 1 is as follows.
- The letter "A" represents one or more absolute LINE NUMBER
clauses, none of which has the NEXT PAGE phrase, that appear in consecutive
order in the sequence of LINE NUMBER clauses in the report group description
entry.
- The letter "R" represents one or more relative LINE NUMBER
clauses that appear in consecutive order in the sequence of LINE NUMBER
clauses in the report group description entry.
- The letters "NP" represent one or more absolute LINE NUMBER
clauses that appear in consecutive order in the sequence of LINE NUMBER
clauses in the report group description entry with the phrase NEXT PAGE
appearing in the first and only in the first LINE NUMBER clause.
This entry can appear without
a line number.
When two abbreviations appear together, they refer to a sequence of LINE
NUMBER clauses that consists of the two specified consecutive sequences. For
example "A R" refers to a report group description entry within
which the "A" sequence (defined in rule 1 above) is immediately
followed by the "R" sequence (defined in rule 2 above).
Where "A R" is shown to be a permissible sequence in the
presentation rules table, "A" is also permissible and the same
presentation rules are applicable.
Where "NP R" is shown to be a permissible sequence in the
presentation rules table, "NP" is also permissible and the same
presentation rules are applicable.
Saved next group integer is a data item that is addressable only by the
RWCS. When an absolute NEXT GROUP clause specifies a vertical positioning
value which cannot be accommodated on the current page, the RWCS stores that
value in saved next group integer. After page advance processing, the RWCS
positions the next body group using the value stored in saved next group
integer.
Table 1-3 points to the appropriate presentation rules for all permissible
combinations of LINE NUMBER and NEXT GROUP clauses in a report heading report
group. The report heading group presentation rules are as follows:
- Upper limit rule.
The first line number on which the report heading report group can be
presented is the line number specified by the HEADING phrase of the PAGE
clause.
- Lower limit rules.
- The last line number on which the report heading report group can be
presented is the line number that is obtained by subtracting 1 from the
value of integer-3 of the FIRST DETAIL phrase of the PAGE clause.
- The last line number on which the report heading report group can be
presented is the line number specified by integer-1 of the PAGE clause.
- First print line position rules.
- The first print line of the report heading report group is presented
on the line number specified by the integer of its LINE NUMBER clause.
- The first print line of the report heading report group is presented
on the line number obtained by adding the integer of the first LINE NUMBER
clause and the value obtained by subtracting 1 from the value of integer-2
of the HEADING phrase of the PAGE clause.
- The report heading report group is not presented.
- The first print line of the report heading report group is presented
on the line number obtained by adding the content of its LINE-COUNTER (in
this case, zero) to the integer of the first LINE NUMBER clause.
- Next group rules.
- The NEXT GROUP integer must be greater than the line number on which
the final print line of the report heading report group is presented. In
addition, the NEXT GROUP integer must be less than the line number
specified by the value of integer-3 of the FIRST DETAIL phrase of the PAGE
clause.
- The sum of the NEXT GROUP integer and the line number on which the
final print line of the report heading report group is presented must be
less than the value of integer-3 of the FIRST DETAIL phrase of the PAGE
clause.
- NEXT GROUP PAGE signifies that the report heading report group is to
be presented entirely by itself on the first page of the report. The RWCS
processes no other report group while positioned to the first page of the
report.
- Final LINE-COUNTER setting rules.
- After the report heading report group is presented, the RWCS places
the NEXT GROUP integer into LINE-COUNTER as the final LINE-COUNTER
setting.
- After the report heading report group is presented, the RWCS places
the sum of the NEXT GROUP integer and the line number on which the final
print line of the report heading report group was presented into
LINE-COUNTER as the final LINE-COUNTER setting.
- After the report heading report group is presented, the RWCS places
zero into LINE-COUNTER as the final LINE-COUNTER setting.
- After the report heading report group is presented, the final
LINE-COUNTER setting is the line number on which the final print line of
the report heading report group was presented.
- LINE-COUNTER is unaffected by the processing of a non-printable report
group.
Table 1-3: Report Heading Group Presentation Rules
** |
Applicable Rules*** |
If the PAGE Clause is specified |
If the PAGE Clause is omitted |
Sequence of LINE NUMBER Clauses* |
NEXT GROUP Clause |
Upper Limit |
Lower Limit |
First Print Line Position |
Next Group |
Final LINE COUNTER Setting |
First Print Line Position |
Final LINE COUNTER Setting |
AR |
Absolute |
1 |
2a |
3a |
4a |
5a |
Illegal Combination+ |
AR |
Relative |
1 |
2a |
3a |
4b |
5b |
Illegal Combination+ |
AR |
NEXT PAGE |
1 |
2b |
3a |
4c |
5c |
Illegal Combination+ |
AR |
|
1 |
2a |
3a |
|
5d |
Illegal Combination+ |
R |
Absolute |
1 |
2a |
3b |
4a |
5a |
Illegal Combination++ |
R |
Relative |
1 |
2a |
3b |
4b |
5b |
3b |
5b |
R |
NEXT PAGE |
1 |
2b |
3b |
4c |
5c |
Illegal Combination++ |
R |
|
1 |
2a |
3b |
|
5d |
3d |
5d |
|
|
|
|
3c |
|
5e |
3c |
5e |
* |
See the section LINE NUMBER Clause
Notation for a description of the abbreviations used in column 1. |
** |
A blank entry in column 1 or column 2
indicates that the named clause is totally absent from the report group
description entry. |
*** |
A blank entry in an applicable rules column
indicates the absence of the named rule for the given combination of LINE
NUMBER and NEXT GROUP clauses. |
+ |
See the section The LINE NUMBER Clause. |
++ |
See the section The NEXT GROUP Clause. |
Table 1-4 below points to the appropriate presentation rules for all
permissible combinations of LINE NUMBER and NEXT GROUP clauses in a page
heading report group.
Table 1-4 : Page Heading Group Presentation Rules
** |
Applicable Rules*** |
If the PAGE clause is specified**** |
Sequence of LINE NUMBER clauses* |
NEXT GROUP clause |
Upper Limit |
Lower Limit |
First Print Line Position |
Next Group |
Final LINE- COUNTER Setting |
AR |
|
1 |
2 |
3a |
|
4a |
R |
|
1 |
2 |
3b |
|
4a |
|
|
|
|
3c |
|
4b |
* |
See the section LINE NUMBER Clause
Notation for a description of the abbreviations used in column 1. |
** |
A blank entry in column 1 or column 2
indicates that the named clause is totally absent from the report group
description entry. |
*** |
A blank entry in an applicable rules column
indicates the absence of the named rule for the given combination of LINE
NUMBER and NEXT GROUP clauses. |
**** |
If the PAGE clause is omitted from the report
description entry, then a page heading report group can not be defined. (See
the section The TYPE clause.) |
The page heading group presentation rules are as follows:
- Upper limit rule.
If a report heading report group has been presented on the page on which
the page heading report group is to be presented, then the first line
number on which the page heading report group can be presented is one
greater than the final LINE-COUNTER setting established by the REPORT
HEADING.
Otherwise the first line number on which the page heading report group
can be presented is the line number specified by the HEADING phrase of the
PAGE clause.
- Lower limit rule.
The last line number on which the page heading report group can be
presented is the line number that is obtained by subtracting one from the
value of integer-3 of the FIRST DETAIL phrase of the PAGE clause.
- First print line position rules.
- The first print line of the page heading report group is presented on
the line number specified by the integer of its LINE NUMBER clause.
- If a report heading report group has been presented on the page on
which the page heading report group is to be present, then the sum of the
final LINE-COUNTER setting established by the report heading report group
and the integer of the first LINE NUMBER clause of the page heading report
group defines the line number on which the first print line of the page
heading report group is presented.
Otherwise the sum of the integer of the first LINE NUMBER clause of
the page heading report group and the value obtained by subtracting one
from the value of integer-2 of the HEADING phrase of the PAGE clause
defines the line number on which the first print line of the page heading
report group is presented.
- The page heading report group is not presented.
- Final LINE-COUNTER setting rules.
- The final LINE-COUNTER setting is the line number on which the final
print line of the page heading report group was presented.
- LINE-COUNTER is unaffected by the processing of a nonprintable report
group.
Table 1-5 points to the appropriate presentation rules for all permissible
combinations of LINE NUMBER and NEXT GROUP clauses in control heading,
detail, and control footing report groups. The body group presentation rules
are as follows:
- Upper limit rule.
The first line number on which a body group can be presented is the line
number specified by the FIRST DETAIL phrase of the PAGE clause.
- Lower limit rules.
The last line number on which a control heading report group or detail
report group can be presented is the line number specified by the LAST
DETAIL phrase of the PAGE clause.
The last line number on which a control footing report group can be
presented is the line number specified by the FOOTING phrase of the PAGE
clause.
- Fit test rules.
- If the value in LINE-COUNTER is less than the integer of the first
absolute LINE NUMBER clause, then the body group is presented on the page
to which the report is currently positioned.
If the value in LINE-COUNTER is not less than the integer of the first
absolute LINE NUMBER clause, the RWCS executes page advance processing.
After the page heading report group (if defined) has been processed, the
RWCS determines whether the saved next group integer location was set
when the final body group was presented on the preceding page. (See final
LINE-COUNTER setting rule 6a.)
If saved next group integer was not set, the body group shall be
presented on the page to which the report is currently positioned. If
saved next group integer was set, the RWCS moves the saved next group
integer into LINE-COUNTER, resets saved next group integer to zero, and
reapplies this rule.
- If a body group has been presented on the page to which the report is
currently positioned, the RWCS computes a trial sum in a work location.
The trial sum is computed by adding the content of LINE-COUNTER to the
integers of all LINE NUMBER clauses of the report group. If the trial sum
is not greater than the body group's lower limit integer, then the report
group is presented on the current page. If the trial sum exceeds the body
group's lower limit integer, then the RWCS executes page advance
processing. After the page heading report group (if defined) has been
processed, the RWCS reapplies this rule.
If no body group has yet been presented on the page to which the
report is currently positioned, the RWCS determines whether the saved
next group integer location was set when the final body group was
presented on the preceding page. (See final LINE-COUNTER setting rule
6a.)
If saved next group integer was not so set, the body group shall be
presented on the page to which the report is currently positioned.
If saved next group integer was so set, the RWCS moves the saved next
group integer into LINE-COUNTER, resets saved next group integer to zero,
and computes a trial sum in a work location.
The trial sum is computed by adding the content of LINE-COUNTER to the
integer one and the integers of all but the first LINE NUMBER clause of
the body group. If the trial sum is not greater than the body group's
lower limit integer, then the body group is presented on the current
page. If the trial sum exceeds the body group's lower limit integer, the
RWCS executes page advance processing. After the page heading report
group (if defined) has been processed, the RWCS presents the body group
on that page.
- If a body group has been presented on the page to which the report is
currently positioned, the RWCS executes page advance processing. After the
page heading report group (if defined) has been processed, the RWCS
reapplies this rule.
If no body group has yet been presented on the page to which the
report is currently positioned, the RWCS determines whether the saved
next group integer location was set when the final body group was
presented on the preceding page. (See final LINE-COUNTER setting rule
6a.)
If saved next group integer was not so set, the body group shall be
presented on the page to which the report is currently positioned. If
saved next group integer was so set, the RWCS moves the saved next group
integer into LINE-COUNTER and resets saved next group integer to zero.
If then the value in LINE-COUNTER is less than the integer of the
first absolute LINE NUMBER clause, the body group shall be presented on
the page to which the report is currently positioned. Otherwise the RWCS
executes page advance processing. After the page heading report group (if
defined) has been processed, the RWCS presents the body group on that
page.
- First print line position rules.
- The first print line of the body group is presented on the line number
specified by the integer of its LINE NUMBER clause.
- If the value in LINE-COUNTER is equal to or greater than the line
number specified by the FIRST DETAIL phrase of the PAGE clause, and if no
body group has previously been presented on the page to which the report
is currently positioned, then the first print line of the current body
group is presented on the line immediately following the line indicated by
the value contained on LINE-COUNTER.
If the value in LINE-COUNTER is equal to or greater than the line
number specified by the FIRST DETAIL phrase of the PAGE clause, and if a
body group has previously been presented on the page to which the report
is currently positioned, then the first print line of the current body
group is presented on the line that is obtained by adding the content of
LINE-COUNTER and the integer of the first LINE NUMBER clause of the
current body group.
If the value in LINE-COUNTER is less than the line number specified by
the FIRST DETAIL phrase of the PAGE clause, then the first printer line
of the body group is presented on the line specified by the FIRST DETAIL
phrase.
- The body group is not presented.
- The sum of the content of LINE-COUNTER and the integer of the first
LINE NUMBER clause defines the line number on which the first print line
is presented.
- Next group rule.
The integer of the absolute NEXT GROUP clause must specify a line number
that is not less than that specified in the FIRST DETAIL phrase of the PAGE
clause, and that is not greater than that specified in the FOOTING phrase
of the PAGE clause.
- Final LINE-COUNTER setting rules.
- If the body group that has just been presented is a control footing
report group and if the control footing report group is not associated
with the highest level at which the RWCS detected a control break, then
the final LINE-COUNTER setting is the line number on which the final print
line of the control footing report group was presented.
For all other cases, the RWCS makes a comparison of the line number on
which the final print line of the body group was presented and the
integer of the NEXT GROUP clause. If the former is less than the latter,
then the RWCS places the NEXT GROUP integer into LINE-COUNTER as the
final LINE-COUNTER setting. If the former is equal to or greater than the
latter, then the RWCS places the line number specified by the FOOTING
phrase of the PAGE clause into LINE-COUNTER as the final LINE-COUNTER
setting; in addition the RWCS places the NEXT GROUP integer into the
saved next group integer location.
- If the body group that has just been presented is a control footing
report group, and if the control footing report group is not associated
with the highest level at which the RWCS detected a control break, then
the final LINE-COUNTER setting is the line number on which the final print
line of the control footing report group was presented.
For all other cases the RWCS computes a trial sum in a work location.
The trial sum is computed by adding the integer of the NEXT GROUP clause
to the line number on which the final print line of the body group was
presented. If the sum is less than the line number specified by the
FOOTING phrase of the PAGE clause, then the RWCS places that sum into
LINE-COUNTER as the final LINE-COUNTER setting. If the sum is equal to or
greater than the line number specified by the FOOTING phrase of the PAGE
clause, then the RWCS places the line number specified by the FOOTING
phrase of the PAGE clause into LINE-COUNTER as the final LINE-COUNTER
setting.
- If the body group that has just been presented is a control footing
report group, and if the control footing report group is not associated
with the highest level at which the RWCS detected a control break, then
the final LINE-COUNTER setting is the line number on which the final print
line of the control footing report group was presented.
For all other cases the RWCS places the line number specified by the
FOOTING phrase of the PAGE clause into LINE-COUNTER as the final
LINE-COUNTER setting.
- The final LINE-COUNTER setting is the line number on which the final
print line of the body group was presented.
- LINE-COUNTER is unaffected by the processing of a nonprintable body
group.
- If the body group that has just been presented is a control footing
report group, and if the control footing report group is not associated
with the highest level at which the RWCS detected a control break, then
the final LINE-COUNTER setting is the line number on which the final print
line of the control footing report group was presented.
For all other cases the RWCS places the sum of the line number on
which the final print line was presented and the NEXT GROUP integer into
LINE-COUNTER as the final LINE-COUNTER setting.
Table 1-5: Body Group Presentation Rules
** |
Applicable Rules*** |
If the PAGE Clause is specified |
If the PAGE Clause is omitted |
Sequence of LINE NUMBER Clauses* |
NEXT GROUP Clause |
Upper Limit |
Lower Limit |
Fit Test |
First Print Line Position |
Next Group |
Final LINE COUNTER Setting |
First Print Line Position |
Final LINE COUNTER Setting |
AR |
Absolute |
1 |
2 |
3a |
4a |
5 |
6a |
Illegal Combination+ |
AR |
Relative |
1 |
2 |
3a |
4a |
|
6b |
Illegal Combination+ |
AR |
NEXT PAGE |
1 |
2 |
3a |
4a |
|
6c |
Illegal Combination+ |
AR |
|
1 |
2 |
3a |
4a |
|
6d |
Illegal Combination+ |
R |
Absolute |
1 |
2 |
3b |
4b |
5 |
6a |
Illegal Combination+ |
R |
Relative |
1 |
2 |
3b |
4b |
|
6b |
4d |
6f |
R |
NEXT PAGE |
1 |
2 |
3b |
4b |
|
6c |
Illegal Combination+ |
R |
|
1 |
2 |
3b |
4b |
|
6d |
4d |
6f |
NP R |
Absolute |
1 |
2 |
3c |
4a |
5 |
6a |
Illegal Combination+ |
NP R |
Relative |
1 |
2 |
3c |
4a |
|
6b |
Illegal Combination+ |
NP R |
NEXT PAGE |
1 |
2 |
3c |
4a |
|
6c |
Illegal Combination+ |
NP R |
|
1 |
2 |
3c |
4a |
|
6d |
Illegal Combination+ |
|
|
|
|
|
4c |
|
6e |
4c |
6e |
* |
See the section LINE NUMBER Clause
Notation for a description of the abbreviations used in column 1. |
** |
A blank entry in column 1 or column 2
indicates that the named clause is totally absent from the report group
description entry. |
*** |
A blank entry in an applicable rules column
indicates the absence of the named rule for the given combination of LINE
NUMBER and NEXT GROUP clauses. |
+ |
See the section The LINE NUMBER Clause. |
++ |
See the section The NEXT GROUP Clause. |
Table 1-6 below points to the appropriate presentation rules for all
permissible combinations of LINE NUMBER and NEXT GROUP clauses in a PAGE
FOOTING report group.
Table 1-6 : Page Footing Presentation Rules
** |
Applicable Rules*** |
If the PAGE clause is
specified**** |
Sequence of LINE NUMBER clauses* |
NEXT GROUP clause |
Upper Limit |
Lower Limit |
First Print Line Position |
Next Group |
Final LINE-COUNTER Setting |
AR |
Absolute |
1 |
2 |
3a |
4a |
5a |
AR |
Relative |
1 |
2 |
3a |
4b |
5b |
AR |
|
1 |
2 |
3a |
|
5c |
|
|
|
|
3b |
|
5d |
* |
See the section LINE NUMBER Clause
Notation for a description of the abbreviations used in column 1 |
** |
A blank entry in column 1 or column 2
indicates that the named clause is totally absent from the report group
description entry. |
*** |
A blank entry in an applicable rules column
indicates the absence of the named rule for the given combination of LINE
NUMBER and NEXT GROUP clauses. |
**** |
If the PAGE clause is omitted from the report
description entry, then a page footing report group can not be defined. (See
the section The TYPE clause.) |
The page footing presentation rules are as follows:
- Upper limit rule.
The first line number on which the page footing report group can be
presented is the line number obtained by adding one to the value of
integer-5 of the FOOTING phrase of the PAGE clause.
- Lower limit rule.
The last line number on which the page footing report group can be
presented is the line number specified by integer-1 of the PAGE clause.
- First print line position rules.
- The first print line of the page footing report group is presented on
the line specified by the integer of its LINE NUMBER clause.
- The page footing report group is not presented.
- Next group rules.
- The NEXT GROUP integer must be greater than the line number on which
the final print line of the page footing report group is presented. In
addition, the NEXT GROUP integer must not be greater than the line number
specified by integer-1 of the PAGE clause.
- The sum of the NEXT GROUP integer and the line number on which the
final print line of the page footing report group is presented must not be
greater than the line number specified by integer-1 of the PAGE clause.
- Final LINE-COUNTER setting rules.
- After the page footing report group is presented, the RWCS places the
NEXT GROUP integer into LINE-COUNTER as the final LINE-COUNTER setting.
- After the page footing report group is presented, the RWCS places the
sum of the NEXT GROUP integer and the line number on which the final print
line of the PAGE FOOTING report group was presented into LINE-COUNTER as
the final LINE-COUNTER setting.
- After the PAGE FOOTING report group is presented the final
LINE-COUNTER setting is the line number on which the final print line of
the PAGE FOOTING report group was presented.
- LINE-COUNTER is unaffected by the processing of a nonprintable report
group.
Table 1-7 points to the appropriate presentation rules for all permissible
combinations of LINE NUMBER and NEXT GROUP clauses in a report footing report
group. The report footing presentation rules are as follows:
- Upper limit rules.
- If a page footing report group has been presented on the page to which
the report is currently positioned, then the first line number on which
the report footing report group can be presented is one greater than the
final LINE- COUNTER setting established by the page footing report group.
Otherwise the first line number on which the report footing report
group can be presented is the line number obtained by adding one and the
value of integer-5 of the PAGE clause.
- The first line number on which the report footing report group can be
presented, is the line number specified by the HEADING phrase of the PAGE
clause.
- Lower limit rule:
The last line number on which the report footing report group can be
presented is the line number specified by integer-1 of the PAGE clause.
- First print line position rules:
- The first print line of the report footing report group is presented
on the line specified by the integer of its LINE NUMBER clause.
- If a page footing report group has been presented on the page to which
the report is currently positioned, then the sum of the final LINE-COUNTER
setting established by the page footing report group and the integer of
the first LINE NUMBER clause of the report footing report group defines
the line number on which the first print line of the report footing report
group is presented. Otherwise the sum of the integer of the first LINE
NUMBER clause of the report footing report group, and the line number
specified by the value of integer-5 of the FOOTING phrase of the PAGE
clause defines the line number on which the first print line of the report
footing report group is presented.
- The NEXT PAGE phrase in the first absolute LINE NUMBER clause directs
that the report footing report group is presented on a page on which no
other report group has been presented. The first print line of the report
footing report group is presented on the line number specified by the
integer of its LINE NUMBER clause.
- If LINE IS NEXT PAGE is the only LINE clause in this report group, the
first line of the report heading report group is presented on line HEADING
integer-2.
- The sum of the content of LINE-COUNTER and the integer of the first
LINE NUMBER clause defines the line number on which the first print line
is presented.
- The report footing report group is not presented.
- Final LINE-COUNTER setting rules.
- The final LINE-COUNTER setting is the line number on which the final
print line of the report footing report group is presented.
- LINE-COUNTER is unaffected by the processing of a nonprintable report
group.
Table 1-7: Report Footing Presentation Rules
** |
Applicable Rules*** |
If the PAGE Clause is specified |
If the PAGE Clause is omitted |
Sequence of LINE NUMBER Clauses* |
NEXT GROUP Clause |
Upper Limit |
Lower Limit |
First Print Line Position |
Next Group |
Final LINE COUNTER Setting |
First Print Line Position |
Final LINE COUNTER Setting |
AR |
|
1a |
2 |
3a |
|
4a |
Illegal Combination+ |
R |
|
1a |
2 |
3b |
|
4a |
3d |
4a |
NP R |
|
1b |
2 |
3c |
|
4a |
Illegal Combination+ |
|
|
|
|
3e |
|
4b |
3e |
4b |
* |
See the section LINE NUMBER Clause
Notation for a description of the abbreviations used in column 1. |
** |
A blank entry in column 1 or column 2
indicates that the named clause is totally absent from the report group
description entry. |
*** |
A blank entry in an applicable rules column
indicates the absence of the named rule for the given combination of LINE
NUMBER and NEXT GROUP clauses. |
+ |
See the section The LINE NUMBER Clause. |
The COLUMN NUMBER clause identifies a printable item and specifies the
position of the item on a print line.
General Format
Syntax Rules
- The COLUMN NUMBER clause can be specified only at the elementary level
in a report group. The COLUMN NUMBER clause, if present, must appear in or
be subordinate to an entry that contains a LINE NUMBER clause.
- Within a given print line, the printable items should be defined in
ascending column number order such that each printable item defined occupies
a unique sequence of contiguous character positions.
No restrictions on the
sequence of COLUMN NUMBER clauses are enforced.
General Rules
- The COLUMN NUMBER clause indicates that the object of a SOURCE clause or
the object of a VALUE clause or the sum counter defined by a SUM clause is
to be presented on the print line. The absence of a COLUMN NUMBER clause
indicates that the entry is not to be presented on a print line.
- Integer-1 specifies the column number of the leftmost character position
of the printable item.
- The RWCS supplies space characters for all positions of a print line
that are not occupied by printable items.
- The leftmost position of the print line is considered to be column
number 1.
A data-name specifies the name of the data item being described.
General Format
Syntax Rules
- In the report section data-name-1 need not appear in a data description
entry.
General Rules
- In the Report Section, data-name-1 must be given in the following cases:
- When data-name-1 represents a report group to be referred to by a
GENERATE or a USE statement in the procedure division.
- When reference is to be made to the sum counter in the procedure
division or report section.
- When a DETAIL report group is referenced in the UPON phrase of the SUM
clause.
- When data-name-1 is required to provide sum counter qualification.
The GROUP INDICATE clause specifies that the associated printable item is
presented only on the first occurrence of its report group after a control
break or page advance.
General Format
Syntax Rules
- The
GROUP INDICATE clause must be specified only in a DETAIL report group
entry that defines a printable item.
General Rules
- If a GROUP INDICATE clause is specified, it causes the SOURCE or VALUE
clause to be ignored and spaces supplied, except:
- On the first presentation of the DETAIL report group in the report,
or:
- On the first presentation of the DETAIL report group after every page
advance, or:
- On the first presentation of the DETAIL report group after every
control group.
- If the report description entry specifies neither a PAGE clause nor a
CONTROL clause, then a GROUP INDICATE printable item is presented the first
time its DETAIL is presented after the INITIATE statement is executed.
Thereafter spaces are supplied for indicated items with SOURCE or VALUE
clauses.
The level-number indicates the position of a data item in the hierarchical
structure of a report group.
General Format
Syntax Rules
- A level-number is required as the first element in each data description
entry.
- Data description entries subordinate to an RD entry must have
level-numbers 01 through 49 only.
General Rules
- The level-number 01 identifies the first entry in a report group.
- Multiple level 01 entries subordinate to a report description entry
having the level indicator RD do not represent implicit redefinitions of the
same area.
The LINE NUMBER clause specifies vertical positioning information for its
report group.
General Format
Syntax Rules
- Integer-1 and integer-2 must not exceed three significant digits in
length.
Neither integer-1 nor integer-2 can be specified in such a way as to
cause any line of a report group to be presented outside the vertical
subdivision of the page designated for that report group type, as defined
by the PAGE clause. (See the section The PAGE Clause earlier in
this chapter.)
Integer-2 can be zero.
- Within a given report group description entry, an entry that contains a
LINE NUMBER clause must not contain a subordinate entry that also contains a
LINE NUMBER clause.
- Within a given report group description entry, all absolute LINE NUMBER
clauses must precede all relative LINE NUMBER clauses.
- Within a given report group description entry, successive absolute LINE
NUMBER clauses must specify integers that are in ascending order. The
integers need not be consecutive.
- If the PAGE clause is omitted from a given report description entry,
only relative LINE NUMBER clauses can be specified in any report group
description entry in that report.
- Within a given report group description entry a
NEXT PAGE phrase can appear only once and, if present, must be in the
first LINE NUMBER clause in that report group description entry.
- A LINE NUMBER clause with the NEXT PAGE phrase can appear only in the
description of body groups and in a REPORT FOOTING report group.
- Every entry that defines a printable item (see the section The
COLUMN NUMBER Clause earlier in this chapter) must either contain a LINE
NUMBER clause, or be subordinate to an entry that contains a LINE NUMBER
clause.
- The first LINE NUMBER clause specified in a PAGE FOOTING report group
must be an absolute LINE NUMBER clause.
General Rules
- A LINE NUMBER clause must be specified to establish each print line of a
report group.
- The RWCS affects the vertical positioning specified by a LINE NUMBER
clause, before presenting the print line established by that LINE NUMBER
clause.
- Integer-1 specifies an absolute line number. An absolute line number
specifies the line number on which the print line is presented.
- Integer-2 specifies a relative line number. If a relative LINE NUMBER
clause is not the first LINE NUMBER clause in the report group description
entry, then the line number on which its print line is presented is
determined by calculating the sum of the line number on which the previous
print line of the report group was presented and integer-2 of the relative
LINE NUMBER clause. If integer-2 is zero, the line will be printed on the
same line as the previous print line.
If a relative LINE NUMBER clause is the first LINE NUMBER clause in the
report group description entry, then the line number on which its print
line is presented is determined by specified rules. (See the section Presentation
Rules Tables earlier in this chapter.)
- The NEXT PAGE phrase specifies that the report group is to be presented
beginning on the indicated line number on a new page. (See the section Presentation
Rules Tables earlier in this chapter.) You need not specify integer-1
for the NEXT PAGE phrase.
The NEXT GROUP clause specifies information for vertical positioning of a
page following the presentation of the last line of a report group.
General Format
Syntax Rules
- A report group entry must not contain a NEXT GROUP clause unless the
description of that report group contains at least one LINE NUMBER clause.
- Integer-1 and integer-2 must not exceed three significant digits in
length.
- If the PAGE clause is omitted from the report description entry only a
relative NEXT GROUP clause can be specified in any report group description
entry in that report.
- The NEXT PAGE phrase of the NEXT GROUP clause must not be specified in a
PAGE FOOTING report group.
- The NEXT GROUP clause must not be specified in a REPORT FOOTING report
group or in a PAGE HEADING report group.
General Rules
- Any positioning of the page specified by the NEXT GROUP clause takes
place after the presentation of the report group in which the clause
appears. (See the section Presentation Rules Tables earlier in this
chapter.)
- The RWCS uses the vertical positioning information supplied by the NEXT
GROUP clause along with information from the TYPE and PAGE clauses, and the
value in LINE-COUNTER, to determine a new value for LINE-COUNTER. (See the
section Presentation Rules Tables earlier in this chapter.)
- The NEXT GROUP clause is ignored by the RWCS when it is specified on a
CONTROL FOOTING report group that is at a level other than the highest level
at which a control break is detected.
- The NEXT GROUP clause of a body group refers to the next body group to
be presented, and therefore can affect the location at which the next body
group is presented. The NEXT GROUP clause of a REPORT HEADING report group
can affect the location at which the PAGE HEADING report group is presented.
The NEXT GROUP clause of a PAGE FOOTING report group can affect the location
at which the REPORT FOOTING report group is presented. (See the section Presentation
Rules Tables earlier in this chapter.)
The SIGN clause specifies the position and the mode of representation of
the operational sign when it is necessary to describe these properties
explicitly.
General Format
Syntax Rules
- The SIGN clause can be specified only for a numeric data description
entry whose PICTURE contains the character "S".
- The numeric data description entries to which the SIGN clause applies
must be described, implicitly or explicitly, as USAGE IS DISPLAY.
- When the SIGN clause is included in a report group description entry,
the SEPA
RATE CHARACTER phrase must be specified.
General Rules
- The optional SIGN clause, if present, specifies the position and the
mode of representation of the operational sign for the numeric data
description entry to which it applies. The SIGN clause applies only to
numeric data description entries whose PICTURE contains the character "S";
The "S" indicates the presence of, but neither the representation
nor, necessarily, the position of the operational sign.
- A numeric data description entry whose PICTURE contains the character "S",
but to which no optional SIGN clause applies, has an operational sign, but
neither the representation nor, necessarily, the position of the operational
sign is specified by the character "S". In this (default) case,
General Rule 3 does not apply to such signed numeric data items. The
representation of the default operational sign is defined in the 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 p
roduce a report in accordance with the Report Description specified in
the Report Section of the Data Division.
General Format
Syntax Rules
- Data-name-1 must name a TYPE D
ETAIL report group and can be qualified by a report-name.
- Report-name-1 can be used only if the referenced report description
contains:
- A CONTROL clause, and
- Not more than one DETAIL report group, and
- At least one body group.
General Rules
- In response to a GENERATE report-name-1 statement, the RWCS performs
summary processing. If all of the GENERATE statements that are executed for
a report are of the form GENERATE report-name-1, then the report that is
produced is called a
summary report.
- In response to a GENERATE data-name-1 statement, the RWCS performs
detail processing that includes certain processing that is specific for the
DETAIL report group designated by the GENERATE statement. Normally, the
execution of a GENERATE data-name-1 statement causes the RWCS to present the
designated DETAIL report group.
- During the execution of the chronologically first GENERATE statement for
a given report, the RWCS saves the values in the control data items. During
the execution of the second and subsequent GENERATE statements for the same
report, and until a control break is detected, the RWCS utilizes this set of
control values to determine whether a control break has occurred. When a
control break occurs, the RWCS saves the new set of control values, which it
thereafter uses to sense for a control break until another control break
occurs.
- During the report presentation, an automatic function of the RWCS is to
process PAGE HEADING and PAGE FOOTING report groups, if defined, when the
RWCS must advance the report to a new page for the purpose of presenting a
body group. (See the section Presentation Rules Tables earlier in
this chapter.)
- When the chronologically first GENERATE statement for a given report is
executed, the RWCS processes, in order, the report groups that are named
below, provided that such report groups are defined in the report
description. The RWCS also processes PAGE HEADING and PAGE FOOTING report
groups as described in General Rule 4. The actions taken by the RWCS when it
processes each type of report group are explained under the appropriate
paragraph. (See the section The TYPE Clause earlier in this
chapter.)
- The REPORT HEADING report group is processed.
- The PAGE HEADING report group is processed.
- All CONTROL HEADING report groups are processed from major to minor.
- If a GENERATE data-name-1 statement is being executed, the processing
for the designated DETAIL report group is performed. If a GENERATE
report-name-1 statement is being executed, certain of the steps that are
involved in the processing of a DETAIL report group are performed. (See
the section The TYPE Clause earlier in this chapter.)
- When a GENERATE statement other than the chronologically first is
executed for a given report, the RWCS performs the steps enumerated below,
as applicable. The RWCS also processes PAGE HEADING and PAGE FOOTING report
groups as described in General Rule 4. The actions taken by the RWCS when it
processes each type of report group are explained under the appropriate
paragraph. (See the section The TYPE Clause earlier in this
chapter.)
- Sense for control break. The rules for determining the equality of
control data items are the same as those specified for relation
conditions. If a control break has occurred then:
- Enable the CONTROL FOOTING USE procedures and CONTROL FOOTING SOURCE
clauses to access the control data item values that the RWCS used to
detect a given control break. (See the section The TYPE Clause
earlier in this chapter.)
- Process the CONTROL FOOTING report groups in the order minor to
major. Only CONTROL FOOTING report groups that are not more major than
the highest level at which a control break occurred are processed.
- Process the CONTROL HEADING report groups in the order major to
minor. Only the CONTROL HEADING report groups that are not more major
than the highest level at which a control break occurred are processed.
- If a GENERATE data-name-1 statement is being executed, the processing
for the designated DETAIL report group is performed. If a GENERATE
report-name-1 statement is being executed, certain of the steps that are
involved in the processing of a DETAIL report group are performed. (See
the section The TYPE Clause earlier in this chapter.)
- GENERATE statements for a report can be executed only after an INITIATE
statement for the report has been executed and before a TERMINATE statement
for the report has been executed.
The INITIATE statement causes the RWCS to begin the
processing of a report.
General Format
Syntax Rules
- Report-name-1 must be defined by a report description entry in the
report section of the Data Division.
General Rules
- The INITIATE statement performs the following initialization functions
for each named report:
- All
sum counters are set to zero.
- LINE-COUNTER is set to zero.
- PAGE-COUNTER is set to one.
- The INITIATE statement does not place the file associated with the
report in the open mode; therefore, an OPEN statement with either the OUTPUT
phrase or the EXTEND phrase for the file must be executed prior to the
execution of the INITIATE statement.
- A subsequent INITIATE statement for report-name-1 must not be executed
unless an intervening TERMINATE statement has been executed for
report-name-1.
- If more than one report-name is specified in an INITIATE statement, the
result of executing this INITIATE statement is the same as if a separate
INITIATE statement had been written for each report-name in the same order
as specified in the INITIATE statement.
See the chapter Program Definition in your Language
Reference.
Additional Syntax Rules
- A
report file must have sequential organization.
- The OPEN statement for a report file must contain only the OUTPUT phrase
or the EXTEND phrase.
Additional General Rules
- The OPEN statement for a report file must be executed prior to the
execution of an INITIATE statement for any reports contained in the file.
The SUPPRESS statement causes the RWCS to inhibit the presentation of a
report group.
General Format
Syntax Rules
- The SUPPRESS statement can only appear in a USE BEFORE REPORTING
procedure.
General Rules
- The SUPPRESS statement inhibits presentation only for the report group
named in the USE procedure in which the SUPPRESS statement appears.
- The SUPPRESS statement must be executed each time the presentation of
the report group is to be inhibited.
- When the SUPPRESS statement is executed, the RWCS is instructed to
inhibit the processing of the following report group functions:
- The presentation of the print lines of the report group.
- The processing of all LINE clauses in the report group.
- The processing of the NEXT GROUP clause in the report group.
- The adjustment of LINE-COUNTER.
-
The
SUPPRESS PRINTING function can also be achieved by moving the value 1
to the
special register
PRINT- SWITCH.
The statement
MOVE 1 TO PRINT-SWITCH
has exactly the same effect as the statement
SUPPRESS PRINTING
The TERMINATE statement causes the RWCS to complete the
processing of the specified reports.
General Format
Syntax Rules
- Report-name-1 must be defined by a report description entry in the
Report Section of the Data Division.
General Rules
- The TERMINATE statement causes the RWCS to produce all the CONTROL
FOOTING report groups beginning with the minor CONTROL FOOTING report group.
Then the REPORT FOOTING report group is produced. The RWCS makes the prior
set of control data item values available to the CONTROL FOOTING and REPORT
FOOTING SOURCE clauses and USE procedures, as though a control break has
been sensed in the most major control data-name.
- If no GENERATE statements have been executed for a report during the
interval between the execution of an INITIATE statement and a TERMINATE
statement, for that report, the TERMINATE statement does not cause the RWCS
to produce any report groups or perform any of the related processing.
- During report presentation, an automatic function of the RWCS is to
process PAGE HEADING and PAGE FOOTING report groups, if defined, when the
RWCS must advance the report to a new page for the purpose of presenting a
body group. (See the section Presentation Rules Tables earlier in
this chapter.)
- The TERMINATE statement cannot be executed for a report unless the
TERMINATE statement was chronologically preceded by an INITIATE statement
for that report and for which no TERMINATE statement has yet been executed.
- If more than one report-name is specified in a TERMINATE statement, the
result of executing this TERMINATE statement is the same as if a separate
TERMINATE statement had been written for each report-name in the same order
as specified in the TERMINATE statement.
- The TERMINATE statement does not close the file with which the report is
associated; a CLOSE statement for the file must be executed. Every report
that is in an initiated condition must be terminated before a CLOSE
statement is executed for the associated file.
The USE BEFORE REPORTING statement specifies Procedure Division statements
that are executed just before a report group named in the Report Section of
the Data Division of this program, and optionally a contained program, is
presented.
General Format
Syntax Rules
- A USE BEFORE REPORTING statement, when present, must immediately follow
a section header in the declaratives portion of the Procedure Division and
must appear in a sentence by itself. The remainder of the section must
consist of zero, one, or more procedural paragraphs that define the
procedures to be used.
- Identifier-1 must reference a report group. The same identifier-1 must
not appear in more than one USE BEFORE REPORTING statement in the same
Procedure Division.
- The GENERATE, INITIATE, or TERMINATE statements must not appear in a
paragraph in a USE BEFORE REPORTING procedure. A PERFORM statement in a USE
BEFORE REPORTING procedure must not have GENERATE, INITIATE, or TERMINATE
statements in its range.
- A USE BEFORE REPORTING procedure must not alter the value of any control
data item.
- The USE BEFORE REPORTING statement itself is never executed; it merely
defines the conditions calling for the execution of the USE procedures.
General Rules
- A declarative
procedure is invoked just before the named report group is produced
during the execution of the program. The report group is named by
identifier-1 in the USE BEFORE REPORTING statement which prefaces the
declarative.
- Within a declarative procedure, there must be no reference to any
nondeclarative procedures.
- Procedure-names associated with a USE BEFORE REPORTING statement can be
referenced in a different declarative section or in a nondeclarative
procedure only with a PERFORM statement.
- In the USE BEFORE REPORTING statement, the designated procedures are
executed by the RWCS just before the named report group is produced. (See
the section The TYPE Clause earlier in this chapter.)
- Within a USE procedure, there must not be the execution of any statement
that would cause the execution of a USE procedure that had previously been
invoked and had not yet returned control to the invoking routine.
- Special precedence rules are followed when programs are contained within
other programs. In applying these rules, only the first qualifying directive
will be selected for execution. The declarative which is selected for
execution must satisfy the rules for execution of that declarative. The
order of precedence for selecting a declarative is:
- The declarative within the program that contains the statement which
caused the qualifying condition.
- The declarative in which the GLOBAL phrase is specified and which is
within the program directly containing the program which was last examined
for a qualifying declarative.
- Any declarative selected by applying rule 6b to each more inclusive
containing program until rule 6b is applied to the outermost program. If
no qualifying directive is found, none is executed.
Copyright © 1999 MERANT International Limited. All rights reserved.
This document and the proprietary marks and names
used herein are protected by international law.
|
| Communication | |