HP 3000 Manuals

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

Micro Focus COBOL Language Reference - Additional Topics

Procedure Division in the Report Writer Module

General Description

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

The CLOSE Statement

Function.

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

General Format.

Syntax Rules.

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

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

General Rules.

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

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

2. For the purpose of showing the effect of various types of CLOSE
statements as applied to various storage media, all report files
are divided into the following categories:

a. Non-reel/unit. A file whose output medium is such that the
concepts of rewind and reels/units have no meaning.

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

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

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

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

-------------------------------------------------------------------------------------------------
| | |
| | File Category |
| CLOSE Statement | |
| Format | |
| | |
-------------------------------------------------------------------------------------------------
| | | | |
| | Non-Reel/Unit | Sequential | Sequential |
| | | Single- | Multi- |
| | | Reel/Unit | 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 | F | D,F,G | D,F,G |
| REMOVAL | | | |
| | | | |
-------------------------------------------------------------------------------------------------

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

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

B. No Rewind of Current Reel

The reel/unit is left in its current position.

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

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

E. File Lock

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

F. Close Reel/Unit

Output Report File (Reel/Unit Media):

The following operations take place:

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

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

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

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

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

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

G. Rewind

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

H. Optional Phrases Ignored

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

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

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

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

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

The GENERATE Statement

Function.

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

General Format.

Syntax Rules.

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

2. Report-name-1 can be used only if the referenced report
description contains:

a. A CONTROL clause, and

b. Not more than one DETAIL report group, and

c. At least one body group.

General Rules.

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

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

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

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

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

a. The REPORT HEADING report group is processed.

b. The PAGE HEADING report group is processed.

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

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

6. When a GENERATE statement other than the chronologically first is
executed for a given report, the RWCS performs the steps
enumerated below, as applicable. The RWCS also processes PAGE
HEADING and PAGE FOOTING report groups as described in General
Rule 4. The actions taken by the RWCS when it processes each type
of report group are explained under the appropriate paragraph.
(See the section The TYPE Clause earlier in this chapter.)

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

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

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

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

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

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

The INITIATE Statement

Function.

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

General Format.

Syntax Rule.

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

General Rules.

1. The INITIATE statement performs the following initialization
functions for each named report:

a. All sum counters are set to zero.

b. LINE-COUNTER is set to zero.

c. PAGE-COUNTER is set to one.

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

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

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

The OPEN Statement

See the chapter Program Definition in your Language Reference.

Additional Syntax Rules.

1. A report file must have sequential organization.

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

Additional General Rule.

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

Function.

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

General Format.

Syntax Rule.

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

General Rules.

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

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

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

a. The presentation of the print lines of the report group.

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

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

d. The adjustment of LINE-COUNTER.

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

Function.

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

General Format.

Syntax Rule.

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

General Rules.

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

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

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

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

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

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

The USE BEFORE REPORTING Statement

Function.

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 is presented.

General Format.

Syntax Rules.

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

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

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

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

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

General Rules.

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

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

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

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

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

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

a. The declarative within the program that contains the
statement which caused the qualifying condition.

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

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

MPE/iX 5.0 Documentation