Report Files and RD Entries


Contents:

Report Files and RD: Keyword Table
Report Files
SELECT and FD: Coding Rules
FILE-CONTROL and FD: Operation
REPORT SECTION and RD
REPORT SECTION and RD: Coding Rules
ALLOW Clause
ALLOW Clause: Coding Rules
ALLOW Clause: Operation
CODE Clause
CODE Clause: Coding Rules
CODE Clause: Operation
CONTROL Clause
CONTROL Clause: Coding Rules
CONTROL Clause: Operation
LINE LIMIT Clause
LINE LIMIT Clause: Coding Rules
LINE LIMIT Clause: Operation
OVERFLOW Clauses
OVERFLOW Clause: Coding Rules
OVERFLOW Clause: Operation
PAGE LIMIT Clause
PAGE LIMIT Clause: Coding Rules
PAGE LIMIT Clause: Operation

This part contains full information about the COBOL Report Writer elements that can appear in the ENVIRONMENT DIVISION and FILE SECTION of your program, and then, in alphabetic order, the clauses that may be used in an RD entry.

Although most of the examples that follow use UPPER-CASE text, you may also use lower-case characters in any of the keywords and operands.

 



Report Files and RD: Keyword Table



The table overleaf lists the major keywords relevant to COBOL Report Writer that may appear in the ENVIRONMENT DIVISION, FILE SECTION, and the RD entry, with a summary of their purposes.  The third and fourth columns tell you whether or not the item is part of the current standard (ANS 85) COBOL and, if so, whether COBOL Report Writer extends the facilities.



      Report Files and RD: Keyword Table

 
 Keyword

 Purpose

  ANS
  85  
 COBOL?
 Extensions to standard       
 COBOL
 SELECT
(in
ENVIRONMENT
DIVISION)








 Associates file
 with external
 medium









  yes











 » MODE clause to direct output
   to Independent Report File
   Handler
 » DUPLICATED clause for
   multiple report files
 » WITH PAGE BUFFER for holding
   page contents before printing
 » WITH RANDOM PAGE for writing
   to a cursor-controlled device
 » FIRST PAGE NO ADVANCING to
   suppress initial page advance
 » TYPE clause to select type
   of output device
 REPORT IS
 / REPORTS
ARE (in FD)
 Associates report
 with file
  yes

 » ALL phrase

 STYLE
 (in FD)

 Invokes a special
 printer facility
 for the file or
 report
  no





 LINE LIMIT
 Gives maximum
 report line width
  no

 GLOBAL

 Makes report
 available to con-
 tained programs
  no



 PAGE LIMIT









 Allocates regions
 of page for diff-
 erent group TYPEs







  yes









 » DE=DETAIL
 » FIRST BODY GROUP=FIRST DETAIL
 » LAST DE OR CH=LAST DETAIL
 » LAST CF=LAST BODY GROUP
          =FOOTING
 » phrases are now positionally
   independent sub-clauses
 » LIMIT, LINE(S) not required
 » FIRST DETAIL/LAST DETAIL
   not required even when
   PAGE HEADING/FOOTING coded
 CONTROL


 Specifies field(s)
 whose change of
 contents triggers
 a control break
  yes


 » REPORT=FINAL
 » controls may overlap

 CODE

 Attaches non-print
 data to report
 records
  yes

 » value may be of any length
 » CODE IS identifier format
 » CODE IS literal format
 OVERFLOW


 Specifies action
 to be taken when
 expression or
 SUM overflows
  no





 ALLOW
 SOURCE SUM
 CORR
 Selects ANS-85 or
 ANS-68 rules for
 SUMming
  no







Report Files




COBOL Report Writer produces output records and writes them automatically to COBOL report files when your program executes a  GENERATE (see 4.2) or  TERMINATE statement (see 4.6).  The report files are described very much like any other output sequential files.  Each must have a SELECT...ASSIGN clause in the ENVIRONMENT DIVISION, and an FD in the FILE SECTION.  They are accessed in the PROCEDURE DIVISION through the OPEN and CLOSE statements.

If the output is to be written to a special medium, or the program is to run in any special environment, or special treatment is to be given to the report data, the MODE clause is used.  This directs report writer to use a specific file handler instead of writing output records in the standard way.

Your program may contain any number of report files and, if required, any number of other files.  As usual, you may code your SELECT...ASSIGN clauses and your FD entries in any order.



a. SELECT...ASSIGN clause:

   Format

 >>--
SELECT-+----------+-file-name-->
            +-
OPTIONAL-+
             +-------------+
             v             |
 >-
ASSIGN+--+assignment-name-+---------------------------+->
         +TO+                +
RESERVE integer-1-+-------++
                                                +-AREA--+
                                                +-AREAS-+
 >--+------------------------------------------------+->
    +-
MODE+--+-+- BATCH-----------------------------+-+
          +IS+ +-mnemonic-name-+-----------------+-+
                               |       +-------+ |
                               |       v       | |
                               +-
USING parameter-+

 >-+----------------------------+--+------------------+->
   +-
DUPLICATED integer-2+-----++  +- WITH PAGE BUFFER-+
                         +TIMES+   +-
WITH RANDOM PAGE-+
 >-+-------------------------------------+-------------->
   +-
TYPE+--++-DEFERRED ----------------+-+
         +IS++-
NONE--------------------+
             +-device-name-+----------++
                           +-
DEFERRED-+

 >+-------------------------++----------------------+-. -><
  +
FIRST PAGE +-NO-+ ADVANCING++other standard clauses+
             +
WITH+

b. FD entry:

   Format

 >>--
FD file-name-+-------------+--+-----------+-->
                  ++--+
EXTERNAL -+  ++--+GLOBAL-+
                   +IS+ +---------+ +IS+
                        v         |
 >-+-
REPORT+--+---+---+-report-name-+-->
   |       +IS+   |   +-
ALL ---------+
   +-
REPORTS +---++ +--------+
             +ARE+  v        |
 >---
STYLE+--++------style-name-+-->
          +IS++------
NORMAL-----+
 >-+--------------------------------+-->
   +-standard
BLOCK CONTAINS clause-+
 >-+---------------------------------+-->
   +-standard
RECORD CONTAINS clause-+
 >-+-------------------------+-->
   +-
RECORDING+----++--+mode-+
              +MODE++IS+
 >-+------------------------+--. -->
   +-other standard clauses-+
 >-+--------------------------+--><
   | +----------------------+ |
   | v                      | |
   +-record-description-entry-+

SELECT and FD: Coding Rules

You may code any other clauses after SELECT and any other clauses except LINAGE in the FD entry that may be appropriate for an output sequential file.  In particular, a FILE STATUS clause may be used to return the status of your report file.  The order of clauses is not significant.

Each report-name is a name of up to 30 characters, formed according to the usual rules for COBOL names.  You might choose names that describes the output produced by the report, such as REPORTS ARE MONTHLY-SALES, END-OF-YEAR-TOTALS.

Each report-name must be the same as the report-name following an RD in your REPORT SECTION.  A report-name may be DBCS.  A report-name may appear only once in an FD entry.  However, it may appear in more than one FD provided that any INITIATE for the report-name has the UPON file-name phrase (see INITIATE Statement) and provided that all the corresponding SELECT statements for these files differ only in their file-name, ASSIGN clause and MODE clause (if present).

If every report is to be written to the same file, you may write REPORTS ARE ALLALL must be the only operand and REPORTS ARE ALL must be the only REPORT(S) clause in the program.

RECORD CONTAINS clause, or a BLOCK CONTAINS clause with the CHARACTERS option, is required if the identifier form of the CODE clause is used in any RD associated with the file.  In all other cases, it is optional.

You should not normally specify a record-description-entry after the FD entry, because report writer relieves you of the need to code any WRITE statements for the report files.  Your program may WRITE records to a report file independently of report writer, provided that there is no MODE clause in the corresponding SELECT and no CODE clause in the RD, and in this case you will of course need to specify at least one 01-level record description following the FD entry.

   An explicit WRITE to the report file may be necessary in rare instances, such as when a downstream program will read your report file and it requires a header or trailer which must not have a carriage control character in its first byte.  (Otherwise, a REPORT HEADING or REPORT FOOTING could be used for this purpose: even if there are non-DISPLAY fields to be written, they could be handled using a SOURCE referencing them as a large group field.)  An  Independent Report File Handler may also be used to manipulate the output for this purpose (see 5.3).

If you do code a record description after the FD entry, and you wish to obtain fixed-length records, you should code a RECORD CONTAINS clause, even if you have also specified RECORDING MODE IS F.  The integer of the RECORD CONTAINS clause should agree with the size of your record.

The MODE clause is used to indicate that each line of the report is to be passed to an Independent Report File Handler, instead of being written directly to a print file.  The mnemonic-name consists of up to four alphanumeric characters .  No check is made on the availability of the file handler until execution time.  The file handler may be either the basic file handler PRNT, a user-written, or a built-in file handler.  File handlers extend the uses of report writer beyond output to "batch" files.  They have two chief uses: (a) they allow the output to be sent to any kind of new physical device without changes to the program and (b) they allow a "back-end" software routine to perform any additional processing on the output.  File handlers are described in a later section (see 5.3) where the supplied file handlers are also listed.

The DUPLICATED, WITH RANDOM PAGE, and WITH PAGE BUFFER features cannot be implemented at run time by direct output and require a file handler to be present (although their processing is handled entirely by the run time system and not by the file handler itself).  So if any of these clauses is present, but no MODE clause has been coded, the precompiler will assume an implicit MODE PRNT clause to be present.  The same assumption is made if any report associated with the file has a CODE clause (except when all such reports have a CODE clause and they are all of the same length), see CODE clause.

If the MODE clause is present, or is assumed implicitly for the reasons given in the preceding paragraph, the following restrictions apply:

No record descriptions may follow the FD entry for that file, as you cannot WRITE directly to a file that is processed by an Independent Report File Handler, see Independent Report File Handlers.

The EXTERNAL and GLOBAL attributes have no effect.  (Note that a report may still be GLOBAL, even though its corresponding file is not.  Use of the MODL file handler also allows a report file to be treated as global (see 5.3.10).

The clauses RESERVE integer-1 AREA(S), PADDING CHARACTER, RECORD DELIMITER, and PASSWORD of the SELECT...ASSIGN clause and the clauses BLOCK CONTAINS integer RECORDS, LABEL RECORD(S) IS/ARE data-name, RECORD IS VARYING..., CODE-SET, and VALUE OF... of the FD are not processed by the file handler and are treated as documentary only.

No USE AFTER STANDARD ERROR/EXCEPTION PROCEDURE Declarative section should be coded for the file.

The CANCEL and STOP RUN statements cannot be relied on to CLOSE files implicitly, as allowed under ANS 85 for regular files.

The device-name of the TYPE clause gives the make and model of the output device, or some other symbolic name.  The TYPE clause enables the precompiler, or the run time system, to select the correct sequence of control characters to produce the desired special effect on the target device.  (See STYLE Clause.)  Apart from the reserved name NONE (meaning that no particular device is to be assumed) and TEST (a specially reserved name), there is a set of special character values associated with each device-name and each of the special effects available from the device.  The physical values of these characters and the method by which they are inserted into the output is highly machine- and device-dependent, but quite transparent to the program.  Device-names are described in Installation and Operation.

   DEFERRED means that any styles used are to be interpreted at run time, rather than stored explicitly when the program is precompiled.  This enables the same program to operate with a number of different output devices without re-compilation.

   If DEFERRED alone is given, the program will determine the target device at run time from the operating environment.  It is then assumed that there may be an implicit style at the FD and the RD levels at run time (unless STYLE NONE is specified) and provision is made for them.

   If both a type-name and DEFERRED are present, all styles will still be interpreted at run time, but the target device-name will be not need to be passed to the program at run time.  The precompiler does not check that the given device-name exists.  This enables you (on a Personal Computer) to use a symbolic device-name of your own choosing (for example TYPE IS PRINTER1) and create its Printer Description File later before execution, based on the one for an existing device.

   DEFERRED is also implied if PAGE BUFFER is coded, since the page buffer routine must know which characters are printable and which are control characters.  DEFERRED may also be forced by any particular STYLE if the implementation decides that the routines required to effect it cannot be included at precompilation time.

   If TYPE is not coded, the precompiler will assume a default device-name, chosen by the user at customization time, which may be absent, i.e. NONE.

   If the device-name is NONE, any STYLE clause applying to this file, other than NORMAL, will be rejected, whether it is in the corresponding FD, any report assigned to the file, or in a report group description.

The STYLE clause in the FD causes one or more styles to take effect for the file as a whole, currently on a Personal Computer only.  Usually this means that a certain sequence of control characters will be sent to the printer just after the OPEN is executed and another sequence just before the CLOSE is executed.  If no STYLE clause is coded, an implicit style for the file may take effect, if this has been defined in the Printer Description File.  STYLE NORMAL ensures that no style takes effect at the file level.  Full details are given in the next part (see STYLE Clause).


FILE-CONTROL and FD: Operation

If you specify more than one report-name in the same REPORTS ARE clause, you will be able to generate report data either consecutively or concurrently for the same file.  (REPORT IS and REPORTS ARE are interchangeable, however many report-names follow.)  Tips on creating more than one report concurrently will be found later (see 5.1.4 - Concurrent Reports).

The USING phrase indicates that the file handler is to be passed the parameters you specify in addition to the parameters normally passed automatically to the file handler on each call.  The additional parameters will be first in the list of parameters passed.  Only user-written file handlers may employ additional parameters, and their associated documentation should specify the exact number and size of the additional parameters required because, unless these are correct, unpredictable results may occur.  Each parameter may be an identifier or literal or any other item that would normally be allowed in the USING phrase of a CALL statement, including their additional keywords such as LENGTH OF, ADDRESS OF, BY CONTENT, or BY REFERENCE.

The DUPLICATED clause indicates that integer-2 copies of the report writer Report Control Areas are to be created.  For example, if you code DUPLICATED 4 TIMES, four copies of PAGE-COUNTER, LINE-COUNTER, control-break areas, total fields, and other internal registers or locations used by report writer will be set up under that report-name.  Each copy controls a totally separate report, passed to a different physical file (although only one FD entry is needed).  This enables you to produce several separate reports that share an identical or similar layout without having to re-code several similar Report Descriptions.

The WITH PAGE BUFFER clause indicates that the Page Buffer facility is to be available to the file handler.  This enables you to use the SET PAGE TO HOLD / RELEASE, SET LINE, and SET COLUMN statements (see Report Writer SET Statements) to build up your page in random fashion.  A full explanation of Independent Report File Handlers and all related clauses is given in a later part (see Independent Report File Handlers).

The WITH RANDOM PAGE clause indicates that the SET LINE and SET COLUMN statements may be used (see Report Writer SET Statements) to build up your page in random fashion.  This clause is used when the output device is one which outputs data page by page rather than line by line (such as a visual display, or laser or page printer) and can change its "current position" to anywhere on the page.  It is similar to WITH PAGE BUFFER, except that the buffer is in the device itself rather than in the program.

If you require normal output to a standard file, you may write MODE IS BATCH.  This prevents any use of a file handler.  MODE IS BATCH cannot be used if a DUPLICATED or WITH PAGE BUFFER clause has been coded.

If you do not code a RECORD CONTAINS clause or a BLOCK CONTAINS clause with the CHARACTERS option, report writer will calculate the logical record length for the report file from the longest actual line found in all the Report Descriptions associated with the file (rounded up to a multiple of 4).  The length of the CODE field, where appropriate, and carriage control character are also added.

If you do code a RECORD CONTAINS clause (or, in its absence, a BLOCK CONTAINS clause with the CHARACTERS option), the integer specified will be used as the logical record length for the report file.  The same integer, after subtracting the length of the CODE field, if appropriate, is also used to calculate a provisional value for the maximum line width for any report associated with the file (up to the default maximum established on customization), in case you omit the LINE LIMIT clause in an RD entry.

If you write RECORDING MODE IS V for a standard batch file (one not produced by a file handler), report writer will write variable-length records to your report file, truncating them, where possible, immediately after the last field in the line.  If you also coded an optional RECORD CONTAINS clause with the format RECORD CONTAINS lower-integer TO higher-integer CHARACTERS, the lower-integer is used as a minimum length for all report records written to the file.

If you specify a RECORDING MODE clause for a file that uses an Independent Report File Handler, the recording mode you specify will be placed in report writer's File Control Area for the report file, and the file handler may choose whether to act on it or to ignore it.  The records passed to a file handler are always variable-length, irrespective of the RECORDING MODE.  The file handler may process them in this form or output them as fixed-length records.  The built-in PRNT file handler ignores the RECORDING MODE and uses the record format specified, or implied, at run time.

You may specify EXTERNAL or GLOBAL for a file that has a REPORT(S) clause.  It is not necessary for a report file to be GLOBAL in order for it to have a GLOBAL report associated with it.

If you write FIRST PAGE NO ADVANCING, the usual form feed is not issued at the start of the first page after execution of the OPEN for the file.  Instead, the program assumes that the paper is already positioned on line 1 of the page.  This feature is useful for printing on pre-numbered forms when you do not want the first page to be wasted.  (You may also eliminate all form feeds using the MODE NOPF (see 5.3).)  FIRST PAGE WITH ADVANCING (the normal default) is provided for symmetry.

 



REPORT SECTION and RD



Each of your Report Descriptions is placed in the REPORT SECTION.  The ANS standards require this to be the last SECTION of the DATA DIVISION, positioned immediately before PROCEDURE DIVISION.  However, the precompiler allows REPORT SECTION to appear anywhere in the DATA DIVISION after FILE SECTION.

Just as the FILE SECTION consists of a series of FD entries, each with record descriptions headed by an 01-level entry to follow, so the REPORT SECTION consists of RD entries, each followed by Report Group Descriptions headed by an 01-level entry.

Your program may produce any number of reports, each with its own Report Description.  Each Report Description consists of an RD entry followed by any number of Report Group Descriptions (although there are restrictions according to TYPE; see TYPE Clause).  The order in which they are coded is immaterial.  If several of the reports have strong similarities, you should define the report only once and make use of the DUPLICATED clause.



   
Format
                        +----------------------+
                        v                      |
 >>--
REPORT SECTION . ---report-description-entry---><

  where report-description-entry is defined as follows:

   Format

 >>--
RD report-name-+-----------+-->
                    ++--+
GLOBAL -+
                     +IS+
 >--+-----------------------+---------------------->
    +-
ALLOW SOURCE SUM CORR-+

 >--+-------------+-->
    +-
CODE clause-+

 >--+----------------+-->
    +-
CONTROL clause-+

 >--+-------------------+--->
    +-
LINE LIMIT clause-+

 >--+--------------------+-->
    +-
PAGE LIMIT clauses-+

                  +--------+
                  v        |
 >---
STYLE+--+-+--style-name--+->
          +IS+ +----
NORMAL----+

 >--+---------------------+-+-----------------+-
. ->
    +-
SUM OVERFLOW clause-+ +-OVERFLOW clause-+
    +----------------------+
    v                      |
 >--report-group-description--><


REPORT SECTION and RD: Coding Rules

All other DATA DIVISION sections, if present, should precede REPORT SECTION.

Each report-name must be unique and must be the same as one of the report-names specified in the REPORT clause of one or more FD entries.  (If a report-name appears in more than one FD, the UPON phrase of INITIATE is required, see INITIATE statement.)  This correspondence is used to determine where the output is to be written.  Each report-name introduced in the FD must match a report-name of an RD.

The clauses of the RD may be written in any order; the order is not significant.

Each RD entry is followed by at least one Report Group Description.  These define all the report groups (sets of one or more report lines) that may be produced in the report.  They are fully described in the next part (see TYPE Clause).

If GLOBAL is specified, the report is available to any program contained in the current program, in the following senses:

An INITIATE, GENERATE, or TERMINATE for the GLOBAL report-name may be issued from within a contained program, provided that the contained program itself does not have a locally-defined report of the same name.  The contained program need not contain a REPORT SECTION.

GENERATE for any of the DETAIL report groups of the GLOBAL report may be issued from within a contained program, provided that the contained program itself does not have a locally-defined report and DETAIL group with the same names.  If a GLOBAL report and a locally-defined report have different names but share DETAIL groups with the same name, these may be distinguished as usual by means of the IN/OF report-name qualifier.

The special registers PAGE-COUNTER, LINE-COUNTER, LINE-LIMIT, and CODE-VALUE of the GLOBAL report, together with any sum-counters, may be accessed as GLOBAL items.  Other report fields are not globally accessible.

   The CONTROL and SOURCE fields, or any other data items used during the processing of the GLOBAL report, are those that are accessible to the containing - not the contained - program.  Thus, SOURCE items must normally also be GLOBAL if you wish to set up values in them and print them from within a contained program.

   If a contained program contains a GLOBAL report with an identical report-name, this will override the scope of original GLOBAL report until the end of the contained program.  Similarly, a DETAIL group in a GLOBAL report of a contained program may override an identically-named one in the containing program.

   The program in which the GLOBAL report is defined must receive control at least once before the report can be accessed, even though it need not itself contain any procedural statements referring to the GLOBAL report.

The STYLE clause causes one or more styles to take effect for the report as a whole.  Usually this means that a certain control sequence will be sent to the printer just after the INITIATE is executed and another control sequence just before the TERMINATE is executed.  If no STYLE clause is coded, an implicit style for the report may take effect, if this has been defined for the output device.  STYLE NORMAL ensures that no style takes effect at the report level.  Full details are given in the next part (see STYLE Clause).

The Formats and Rules for the other clauses in the RD are given in the sections that follow.

 



ALLOW Clause



This clause enables you to select whether the ANS-68 or the ANS-85 standard rules should be used for the formation of totals.



   
Format

 >>--
ALLOW-+----+-SOURCE SUM CORR--><
           +-
NO-+


ALLOW Clause: Coding Rules

The COBOL Report Writer software, as supplied, assumes:

            ALLOW SOURCE NO SUM CORR

   because it is based on the ANS 85 standard.  You will need to code this clause only if you need to override the normal default, or if your program is to be portable and it is important to document which standard you are assuming.


ALLOW Clause: Operation

ALLOW SOURCE SUM CORR causes SOURCE SUM correlation to take effect throughout the report.  The correlation between SOURCE items in a DETAIL and SUM clauses in a CONTROL FOOTING group is the main distinguishing feature of the ANS-68 standard.  It is the only important case where the same code may give different results under the '68 and the '85 standards..  It will be important for you to understand the effect of SOURCE SUM correlation if your report has:

 ¶   more than one DETAIL group, and

 ¶   a SUM clause referring to a data item that is defined in a section of your DATA DIVISION (other than the REPORT SECTION).

   For full details, see SUM Clause.

If you code the word NO the effect is reversed.

 



CODE Clause



This clause can be used to prefix non-printable fields to the report records.  Such information is typically of use to de-spooling software and special device handlers.



   
Format

 >>-+-
CODE+--+--+-+-literal-------+-><
    |     +IS+  | +-mnemonic-name-+
    ++----+
CODE-+ +-identifier----+
     +WITH+


CODE Clause: Coding Rules

The forms CODE IS and WITH CODE are synonymous.

The CODE clause is not permitted if the associated FD entry is followed by a record description entry.  This is because it would be illogical to WRITE independently to the file if there is also a CODE.  See 2.2.2 and the rest of this section for further details.

The literal, if coded, must be a non-numeric literal.

If an identifier operand is used, it must represent a group field or a non-edited alphanumeric elementary field.  The associated FD entry for the file must then have either a BLOCK CONTAINS clause with the CHARACTERS option or a RECORD CONTAINS clause, or both.

If a mnemonic-name operand is coded, there must be an entry in SPECIAL-NAMES of the form:

      literal IS mnemonic-name

   where literal is non-numeric.  The value of literal is then used as the CODE value.  If you require compatibility with ANS-68 report writer, one character is the norm.  For ANS-85 compatibility, you should code a two-character literal.

If your report file description has a RECORD or BLOCK CONTAINS integer CHARACTERS clause and there is no MODE clause after SELECT, the size of the CODE, plus the maximum line width, must not be greater than the number of CHARACTERS specified.

Not all RD entries associated with the same report file need have a CODE clause and all the CODE clauses need not specify an operand of the same length.  However, if the report file does not use a user-written file-handler that might ascribe some meaning to different lengths of CODE, it may be impossible to recognize the CODE at the front of each records and decide how long it is.


CODE Clause: Operation

The presence of a CODE clause implicitly establishes the special register CODE-VALUE in the Report Control Area.  You may alter the contents of CODE-VALUE at any time.  If there are several CODE clauses in different RDs within your program, you must qualify CODE-VALUE by the report-name.

If you do not specify a MODE clause after the SELECT for the corresponding report file, the value of the CODE is prefixed to every record written by report writer to the report file.    The CODE is placed after any line feed, carriage return, or other control characters:

ccc  CODE print data ...


   If the length of the CODE is not the same for every report being written to the file, or if some of the reports have no CODE, then a MODE PRNT clause is assumed in default, causing the built-in PRNT file handler to be invoked.

If you do specify a MODE clause after the SELECT, CODE-VALUE will be passed to the Independent Report File Handler in the Report Control Area.  Built-in file-handlers (PRNT, MODL, NOPF) treat the CODE in the authodox way just described, but a user-written file handler may interpret CODE-VALUE in any desired way.  Hence, your own user-written file handler may use the CODE clause for the passing of any additional information that is required by the file handler but does not necessarily appear in the report line itself.  See Independent Report File Handlers for more information.

If a literal or mnemonic-name is used, the size of CODE-VALUE is the length of literal, and CODE-VALUE is preset to the value of literal.

If an identifier is used, the length of CODE-VALUE is the (maximum) record length given in the RECORD CONTAINS clause, minus the LINE LIMIT.  The current value of identifier is stored in CODE-VALUE at the start of the processing for each DETAIL or CONTROL HEADING for the report.  This does not occur if the current group is a CONTROL FOOTING, so as to ensure that only pre-control-break values will be used.  In the following example (assuming ADV is in effect)  the size of CODE-VALUE is 140 minus 132 = 8 bytes, and the field WC-ACCOUNT-REF is moved to CODE-VALUE at the start of each non-CF body group:

 
       FD  REPORT-FILE
           RECORD CONTAINS 140 CHARACTERS
           REPORT IS MAIN-ACCOUNTS.
       ...
       RD  MAIN-ACCOUNTS
           LINE LIMIT IS 132
           CODE IS WS-ACCOUNT-REF ...

 




CONTROL Clause



This clause should be coded in your RD if your report has additional lines, such as total lines and subheadings, that are to be produced upon a change of value in one or more "key" fields (known as control fields or simply controls).



   
Format

 >>-+-
CONTROL+----++-+--------+-+------------+-><
    |        +-IS-+| +-
REPORT-+ | +--------+ |
    +-
CONTROLS+---++ +- FINAL--+ | v        | |
              +ARE+             +-control-id-+

CONTROL Clause: Coding Rules

As the format shows, you may code either the special keyword REPORT (or its equivalent, FINAL), or a list of identifiers (control-ids), or both.  Commas are optional but helpful separators here, but you should code at least one space or new line between the operands.  At least one operand must be coded.

REPORT, if present, must appear first in the list of control-ids.  You may omit REPORT even if you refer to it in the Report Description.  FINAL is an alternative name for REPORT.

Each control-id must be REPORT/FINAL or the name of an unedited data item in the DATA DIVISION of your program.  It must not be a special register in the REPORT SECTION, such as PAGE-COUNTER.  You may include qualifiers and subscripts if necessary.  A PICTURE of a control-id should not have a "V" (implied decimal point) symbol.

You cannot use the same control-id more than once in the same CONTROL clause (unless a redefinition is used), but you can use the same control-id in different RDs.

Control-ids are required to be either group items or unedited alphanumeric or numeric DISPLAY items with a maximum size.  Thus edited items and items with a USAGE of COMPUTATIONAL or INDEX are prohibited.  If you would like to use such an item as a control without restrictions on its format, you can simply REDEFINE it or use a group level item containing only the item in question:

 
            05  MONTH-X.
              07  MONTH      PIC 99  COMP.
            05  next-item ...

        RD ...  CONTROL IS MONTH-X.


It is acceptable for your control fields to overlap.  The following usage is therefore allowed:

 
         03  ACCOUNT-CODE.
           05  BRANCH              PIC 99.
           05  FILLER              PIC XX.

           ... CONTROLS ARE BRANCH, ACCOUNT-CODE ...


Coding the CONTROL clause enables you to include some additional elements in your report description, namely:

 ¶   You can specify a CONTROL HEADING and/or a CONTROL FOOTING group for each control-id, if needed.  (See TYPE Clause.)

 ¶   You can code PRESENT/ABSENT AFTER clauses (formerly known as GROUP INDICATE) with any of the control-ids as operand to cause report fields, lines etc. to appear or disappear after a change in its value.  (See PRESENT AFTER Clause.)

 ¶   You can defer the RESETting (zeroing) of a total field until after a change in a higher control.  (See SUM Clause.)


CONTROL Clause: Operation

You code a CONTROL clause when your report has a structure based on changes in the value of one or more "key" or control fields, whose names you list in the CONTROL(S) clause.  Report writer does not sort your data (to do that you could use COBOL SORT) but, assuming that your data is sequenced according to the control fields, report writer can perform certain actions automatically, such as the production of a CONTROL FOOTING and a CONTROL HEADING group when its contents change.  It is also possible for a single CONTROL FOOTING group to be used for more than one level of control.  (See TYPE Clause.)

   In the following diagram, there are two levels of control.  Two CONTROL HEADING groups and one CONTROL FOOTING have been coded.  (There is no CONTROL FOOTING FOR YEAR.)  The "boxes" around each of these groups shows their extent.

   We have used some abbreviations in the following code - for example omitting the SOURCE and TYPE keywords - to save space.  To shorten it further, you could abbreviate CONTROL HEADING FOR YEAR and CONTROL FOOTING FOR YEAR as CH YEAR and CF YEAR.

      SPORTS CLUB NEW MEMBERS

   
YEAR: 1991

  
MONTH: JAN

         J.J. CODER
         K. ANALYST
      
-----              ----
  
JAN TOTAL:                2

  
MONTH: FEB

         C. HACKER
         V. PROGRAMMER
         J.C. USER
      
-----              ----
  
FEB TOTAL:                3

 ... etc ...             ... etc ...

   
YEAR: 1992

 ... etc ...             ... etc ...

RD  ...
     CONTROLS ARE YEAR, MONTH.

 01  CONTROL HEADING FOR YEAR.
   03  LINE + 2.
     05  COL 3    VALUE "YEAR:".
     05  COL + 2  PIC 9(4)  SOURCE YEAR.

 01  CONTROL HEADING FOR MONTH.
   03  LINE + 1.
     05  COL 2    VALUE "MONTH:".
     05  COL + 2  PIC XXX   SOURCE MONTH.

*Your CONTROL FOOTING may have underlines etc.
*Include them all in the CF group!

 01  NEW-MEMBER DETAIL.
   03 ...

 01  CONTROL FOOTING FOR MONTH.
   03  LINE COLS 5 20
       "-----" "----".
   03  LINE.
       05  COL 2    PIC XXX MONTH.
       05  COL + 2  "TOTAL:".
       05  COL 20   PIC ZZZ9
           COUNT OF NEW-MEMBER.


   The preceding diagram illustrates the following important points:

Your CONTROL HEADING and CONTROL FOOTING groups are coded as separate 01-level report groups.

You can lay out CH and CF groups exactly as you like, just as you would for a DETAIL; report writer imposes no pre-defined format on any groups.

If you need a different CONTROL HEADING at more than one level (YEAR and MONTH in our example), you must code a new group for each level.  This means that all groups may have different layouts.  In this example, this applies also to the CONTROL FOOTING groups.  (However, you can if you wish use the same group description for both levels by coding TYPE CF FOR YEAR, MONTH.)

Report writer produces your CONTROL HEADING group at the start of each new value of the control.  Similarly, it produces your CONTROL FOOTING group at the end of each new value of the control.

CONTROL FOOTING groups are produced using the control values that existed before the control break.  (See next item below for a fuller description of this.)

Both the CONTROL HEADING and the CONTROL FOOTING groups are optional for each control-id.  You may code just a CONTROL HEADING group, or just a CONTROL FOOTING group, or neither.

The reserved word REPORT (or FINAL) is a special case representing the highest possible controlIt is not a data-name.  Include this as the first of your set of controls if you need special action to be taken once only at the beginning and end of the report; for example, if you require grand totals to be produced for the entire report.

Report writer keeps an internal copy of the pre-break contents of each control so that it may detect changes in the controls, known as control breaks.  Ignoring the special case REPORT or FINAL for the moment, whenever your program issues a GENERATE statement, the CONTROL clause causes report writer to compare the contents of each control with its contents when the previous GENERATE was executed.  The first control is examined first, then the second and so on.  If no changes are found in any of the controls, no special action is taken.  As soon as a change is found in a control, no further controls are examined.  A break in a higher control always implies a break in all the lower controls , whether their contents have actually changed or not.  (Obviously, 1991's JANUARY is a different month from 1992's JANUARY.)  If you have more than one control, they must therefore have a hierarchy.  Here are some examples:

    Structure of your data:              Format of the CONTROL clause:

    MONTH within YEAR                    CONTROLS ARE YEAR, MONTH
    CITY within COUNTY within STATE      CONTROLS ARE STATE, COUNTY, CITY

   Your control-names must exist somewhere as data-names in the program outside the REPORT SECTION.  For example, if in the last case the data-names in your file layout are actually written CUST-STATE, CUST-COUNTY, CUST-CITY, then your CONTROL clause would have to be written: CONTROLS ARE CUST-STATE, CUST-COUNTY, CUST-CITY.

When a control break is detected, if your report has CONTROL FOOTING groups, each control field is first saved in a temporary holding area and is then overwritten with the contents it had before the break for the duration of the production of the CONTROL FOOTINGs.  This means that your program will use the before-the-break contents of any CONTROL field (for example in a SOURCE, or a PRESENT WHEN) in the following TYPEs of group:

a CONTROL FOOTING;

a PAGE HEADING or PAGE FOOTING, when the page advance was caused by a CONTROL FOOTING;

and in the following situations:

when it is used as a SOURCE or SUM operand, either as it is or as a subscript or qualifier, or as part of an expression;

when it is used as part of a condition;

when it appears in a parameter to a FUNCTION;

when it is referenced implicitly, that is, via a redefinition, or via a group field or subordinate field or an intersecting field.

   Only control fields exhibit their before-the-break values when referenced at CONTROL FOOTING time.  To obtain the before-the-break value of a field other than a control field, you should use a Declarative procedure to save its current value (see USE BEFORE REPORTING Directive, Operation).

   After the lowest-level CONTROL FOOTING has been produced, and before any CONTROL HEADING or DETAIL groups are output, the current contents of all controls are restored .  For a full description of the steps, see GENERATE Statement.

Report writer will not detect a control break until your program issues a GENERATE.  If a control field in your input data changes several times but no GENERATE is issued during that time, no control breaks will be detected.

Your CONTROL identifiers need not be chosen just from ready-made locations in your input files or database.  You may also "manufacture" them in WORKING-STORAGE.  As a simple example, you may wish to print subtotals by quarter, although your main input gives just the months:

 
       RD  ...
           CONTROL IS W-QUARTER ...
       ...
           COMPUTE W-QUARTER = (F-MONTH-NO + 2) / 3

You cannot define more than one CONTROL HEADING or CONTROL FOOTING for a given control-id in your report.  However, cases sometimes occur when you would like two CONTROL FOOTING report groups for the same level of control.  You may achieve this referring to the same control field under a different name, as in the following case, where we must have two groups because the second part begins on a new page:

 
           05  W-ACCT-NO-1     PIC X(6).
           05  W-ACCT-NO-2     REDEFINES W-ACCT-NO-1    PIC X(6).
      *
       REPORT SECTION.
       RD  ...
           CONTROLS ARE W-ACCT-NO-1 W-ACCT-NO-2 ...
           ...
       01  GRP-A    TYPE CF FOR W-ACCT-NO-2.
         03  LINE + 3.   ...
           ...
       01  GRP-B    TYPE CF FOR W-ACCT-NO-1.
         03  LINE NEXT PAGE.   ...

   Here, the two controls W-ACCT-NO-1 and W-ACCT-NO-2 are physically the same field.  Consequently, there will be a break in the higher control whenever there is a break in the lower control, and the two CONTROL FOOTING groups, GRP-A and GRP-B, will always appear together in that order.

Report writer will consider a control break to have taken place if there is any change in the bit-pattern of the control field.  For example, if the field is packed decimal (COMPUTATIONAL-3), a value of (hex) 123C and (hex) 123F will be considered different, even though they both represent the same numeric value.  If this property is undesirable, your program should MOVE such a field to a DISPLAY field and use the DISPLAY field as the control field.

If your program has several Report Descriptions, each report is processed independently of the others.  You can decide separately for each report whether it will have a CONTROL clause and which controls to specify.  When you issue a GENERATE for a report that has controls, report writer examines the controls for that report only, ignoring all the others.

Non-Hierarchical Control Structures.

   In some report structures, there may appear to be controls which are in parallel rather than hierarchical arrangement.  For example:

                  Department #
                       |
                      / \
          Student Id.     Teacher Id.

   The organization of records in your file might be:

    Department A:
       STUDENT record #1
       STUDENT record #2
       STUDENT record #3
       ... etc ...
       TEACHER record #1
       TEACHER record #2
       TEACHER record #3
       ... etc ...
    Department B:
       ... etc ...

   As you see, there is no hierarchical relationship between STUDENTs and TEACHERs.  You might wish to print a CONTROL FOOTING group for the STUDENT records in each Department and a CONTROL FOOTING group of quite different appearance for the STUDENT records.  To achieve this you must regard the two different CONTROL FOOTING groups as different versions of the same CONTROL FOOTING and use  PRESENT/ABSENT WHEN clauses to distinguish them (see 3.18).  Make the STUDENT-TEACHER indicator an extra lower control.  Here is a skeleton solution:

 
       RD  ACADEMIC-LIST ...
           CONTROLS ARE DEPARTMENT-NO STU-TEA-FLAG.
       ...
       01  CF FOR STU-TEA-FLAG.
         03  PRESENT WHEN STU-TEA-FLAG = "S".
           05  LINE + 2   ... <layout for STUDENTs>
         03  PRESENT WHEN STU-TEA-FLAG = "T".
           05  LINE + 2   ... <layout for TEACHERs>

There may be other purposes for specifying an item as a control.  You might include it for the following reasons:

To trigger a PRESENT AFTER clause (or a GROUP INDICATE clause), or the RESET phrase of the SUM clause.

To force a control break even though a lower control has not changed.  You might want to output just monthly totals over several years' data.  If you then declare MONTH as a control you must include YEAR too as a higher control, because it is quite possible for JANUARY 1991 to be followed immediately by JANUARY 1992 if you happen to have no data for FEBRUARY to DECEMBER 1991.  (Note: in this example, you could also solve the problem by having just one control, YEAR-MONTH, if they are contiguous.)

Because you may want to use the field as a SOURCE at CONTROL FOOTING time and you want to obtain the previous value of the field.  (See item 2 above.)  For example, you might have both CUSTOMER-NUMBER and CUSTOMER-NAME.  By making CUSTOMER-NAME a control field following CUSTOMER-NUMBER (the "true" control field), you can be sure that you will see only the pre-break values of CUSTOMER-NAME at Control Footing time.

For documentary purposes.  The lowest-level controls need not be used at all in the program.




LINE LIMIT Clause



This clause indicates the maximum number of columns likely to be required for the longest line of your report.  It enables report writer to check that all of your report fields appear within the limits of the report line, and to warn you if there is any danger of data being lost beyond the right-hand extremity of the lines.



   
Format

 >>--
LINE LIMIT +--+-+-integer----+-><
               +IS+ +-identifier-+


LINE LIMIT Clause: Coding Rules

The value coded gives the maximum line width, in other words the greatest number of print columns required for your report.  You may simply enter the column width of your printer, for example: LINE LIMIT IS 132 or, if your report is clearly designed to take up less than this number of columns, use that value instead.

The identifier form of the clause is used if you wish the width of your report line to assume different values at different times.  This form of the clause takes effect only when you use either the  REPEATED Clause (see 3.19), or the  WRAP Clause (see 3.28).  The identifier must be an unedited numeric field.

If the FD entry for the corresponding report file contains a BLOCK or RECORD CONTAINS integer CHARACTERS clause (other than BLOCK CONTAINS 0 CHARACTERS), the value of integer, and the size of any CODE field, must not be less the LINE LIMIT, or its default value (see item 3 in the section below).


LINE LIMIT Clause: Operation

If any report field extends beyond the maximum line width given in your LINE LIMIT clause, report writer will signal a fault, either at compile time or, if that is not foreseeable, at run time.

If you use the identifier form of the clause, report writer evaluates its contents dynamically at INITIATE time and uses that as the value for the clause.  For the purpose of checking the validity of COLUMN numbers, it will use the default maximum value described below.  The value set up by the identifier is used at run time for the following purposes:

to vary the number of REPEATED groups that may be placed side-by-side (see REPEATED Clause),

as one means of adjusting the right margin when the WRAP clause is used to produce line wrap round (see WRAP Clause),

to check for (illegal) line overflow in variable-position report fields when the WRAP clause is not used.

If you omit the LINE LIMIT clause, report writer will assume a default value of the maximum line width.  This is set to 256 in the report writer software as supplied but this default may be changed by customization to any other value (see Installation and Operation).

The LINE LIMIT need not be the same as logical record length of the report file.  The latter is established from the computed maximum length of the lines of the report, or from the RECORD or BLOCK CONTAINS clauses if present (see 2.2.3).

An internal special register with the reserved name LINE-LIMIT is established in the Report Control Area, containing the value specified in the LINE LIMIT clause, or its default value.




OVERFLOW Clauses



The OVERFLOW clause tells report writer how to protect your program from arithmetic errors, such as zero divide, that would cause an elementary COBOL program to fail.  The SUM OVERFLOW clause tells report writer what action to take if a total field overflows - an event which is more likely to happen than with other report fields.  It may be difficult to estimate the number of digits needed for totals, since this will depend on the number and content of items to be accumulated into the totals.  Use these clauses if you need to change the standard action.



   
Format a

 >>--
OVERFLOW+---------++--++- OMITTED--------------+-><
             +PROCEDURE++IS++-
STANDARD -------------+
                            +-
REPLACE BY literal-1-+
                            +-
STOP literal-2-------+

   Format b

 >>--
SUM-OVERFLOW +---------++--++-OMITTED--------------+-> <
                 +PROCEDURE++IS++-
STANDARD -------------+
                                +-
REPLACE BY literal-1-+
                                +-
STOP literal-2-------+


OVERFLOW Clause: Coding Rules

The OVERFLOW (format a) and SUM OVERFLOW clauses (format b) are distinct clauses and you may choose a different option for each.

If your program contains no SUM clauses, the SUM OVERFLOW clause is not required.  Similarly, if your program has no clauses of the form SOURCE arithmetic-expression , the OVERFLOW clause is not required.  In either case, the clause may nevertheless be coded and it then has no effect.

Use the OMITTED option if your report uses arithmetic expressions or has a SUM clause respectively but there is no likelihood of a size error.

Use the REPLACE BY option if your report may be sensitive to improbable values in the user's data and you would like to show on the report exactly where errors have occurred.  REPLACE BY can be followed by either a numeric or a non-numeric literal-1, whatever the PICTURE of your report field.

Use the STOP option only if SUM or arithmetic overflow is extremely unlikely but potentially damaging and you are content for your program to execute an "emergency" COBOL STOP in such a case.


OVERFLOW Clause: Operation

The OVERFLOW clause takes effect if your program contains clauses of the form SOURCE arithmetic-expression.  On each occasion that the expression is evaluated a check may be made in case the result is too large for the report field.  Also, if any expression involves a division step there could be a zero divide error, such as FIELD-A / FIELD-B when FIELD-B contains zero.

The SUM OVERFLOW clause takes effect if your program contains SUM clauses.  On each addition, a check may be performed for size error.  This clause does not affect any of the other functions of the SUM clause, such as the resetting (zeroing) of the totals.  The default in each case is STANDARD (see below).

If you choose the OMITTED option the effect is as follows:

   OVERFLOW: Report writer will not perform any checks for arithmetic overflow.  This will save a small overhead on the evaluation of expressions.  If a size error occurs, then at best your report field will have some high-order digits truncated.  If a zero divide error occurs, your program will fail at run time .

   SUM OVERFLOW: Report writer will not perform any checks for SUM overflow.  This will save a small overhead on totalling.  If a size error occurs, at least one top digit will be truncated and lost from the total field.

If you choose the STANDARD option, the effect is as follows:

   OVERFLOW: Report writer will always check for size error, or zero divide, when it evaluates each SOURCE expression.  If this happens, your report field will be blank and a run time error 10 will be indicated.

   SUM OVERFLOW: Report writer will check for size error on each addition into a total field.  If this happens, a run time error 11 will be indicated.  No adding will take place into your total field and you will obtain the total up to the point just after the last valid addition.

If you code the REPLACE BY option, the effect is as follows:

   OVERFLOW: Report writer will check for a size error or zero divide and, if this occurs, it will place your specified literal-1 in the SOURCE report field instead of the erroneous value.

   SUM OVERFLOW: Report writer will check for a size error and, if this occurs, it will place your specified literal-1 in the SUM report field instead of the erroneous value.

   In either case, if you choose a numeric literal-1, this value will be stored according to the rules of the MOVE statement.  If you choose a non-numeric literal-1, the literal will be stored, as for a MOVE, in your report field, treated as though it were redefined as an unedited alphanumeric field (PIC X...).  For example, if overflow occurs and your report field is defined as:

 
        05  COL 20   PIC ZZZ9.99  SOURCE NUM-ORDERED * UNIT-PRICE.

   and your RD contains the clause: OVERFLOW PROCEDURE IS REPLACE BY ZERO, the following will appear:
   0.00
   and if your RD contains the clause: OVERFLOW PROCEDURE IS REPLACE BY ALL "?", the following will appear:
???????

If you code the STOP option, report writer will execute a COBOL STOP literal-2 as soon as an error is detected.




PAGE LIMIT Clause



The PAGE LIMIT clause should be coded if your report is to be divided into pages.  It also allows you to sub-divide the page into regions for the headings, main data, and footings.



   
Format

 >>-+----------------------+->
    +-
HEADING IS integer-1-+

 >-+------------------------------------+->
   +-
FIRST-+-DETAIL -----++--+integer-2--+
           +-
DE---------++IS+
           +-
BODY GROUP-+

 >-+------------------------------------------------------+>
   +-
LAST-+-DETAIL ++-------------------++--++integer-3---++
          +-
DE----++ OR+CONTROL HEADING+++IS++identifier-1+
                      +-
CH ------------+

 >-+---------------------------------------------------+->
   +-
LAST-+-CONTROL FOOTING-+-+-IS-+integer-4--------+-+
   |      +-
CF--------------+ |    ++-PLUS-+integer-5+
   |      +-
BODY GROUP------+ |     +- + --+
   +-
FOOTING------------------+

 >-
PAGE-+------------+-integer-6-+-------+-><
        +-LIMIT IS---+           +-LINE--+
        +-LIMITS ARE-+           +-LINES-+


PAGE LIMIT Clause: Coding Rules

The format above gives you choices of keywords, and in each case the different keywords have the same meaning.  Traditionally, the sub-clauses were referred to as the HEADING , FIRST DETAIL, LAST DETAIL, and FOOTING phrases.  We also usually refer to the whole clause as the PAGE LIMIT clause, even though the word LIMIT is optional.

Each of the sub-clauses is optional, but none of the first four sub-clauses may be present without the PAGE LIMIT sub-clause.  You may code the sub-clauses in any order , and they may appear anywhere in the RD statement.  The order shown follows a natural progression from the top to the bottom of the page and is therefore recommended for maximum lucidity.

The values of integer-1, integer-2, integer-3, and integer-4 (if you code their sub-clauses), and integer-6 represent the start and finish points of various regions of your page, working down from the top to the bottom.  Ensure that the regions start and finish in the order shown in the diagram below (see 2.9.3).  Any two integers may be equal.  All integers must lie between 1 and 9999 inclusive.

If you use the identifier form of the LAST DETAIL sub-clause, the identifier used must be an unedited numeric field and its value at every generation of your report must lie between the FIRST DETAIL and LAST CONTROL FOOTING positions, inclusive.

By using the + integer-5 form of the LAST CONTROL FOOTING sub-clause, you specify the extra lines to be made available to CONTROL FOOTING groups.  Ensure that you cannot exceed the PAGE LIMIT: that is, the LAST DETAIL value (identifier-1 or integer-3) + the LAST CF offset (integer-5) must be not greater than the PAGE LIMIT (integer-6 ).

The FIRST four PAGE LIMIT sub-clauses may all be omitted.  Here are some guidelines on their use:

HEADING is never required.  However, if your report has a PAGE HEADING that begins with a relative LINE, you may use HEADING as an anchor point for the start of that group.

FIRST DETAIL should be coded if you have a PAGE HEADING group, especially one that might vary in depth, and you want the body of the page to follow at a fixed position underneath it.

LAST DETAIL should be coded if you have a PAGE FOOTING group and want the body of the page to end short of the line preceding it or if you want to use LAST DETAIL in conjunction with LAST CF as described in the next paragraph.  Use the LAST DETAIL identifier form if you want to vary the logical page depth dynamically.

LAST CF (or LAST CONTROL FOOTING, or FOOTING) should be coded if you have CONTROL FOOTING groups and want to leave some space before the PAGE FOOTING begins.  (If the option is not in effect, this may be provided automatically - see item 7 in the next section.)

If you omit the PAGE LIMIT clause, your report will consist of one continuous stream of output without page breaks.  Your Report Group Descriptions will then not be able to contain absolute LINE (see LINE Clause), or NEXT GROUP (see NEXT GROUP Clause), PAGE HEADING and FOOTING groups, or any form of any clause that makes use of the keyword PAGE.


PAGE LIMIT Clause: Operation

The PAGE LIMIT clause enables report writer to assign regions to your page.  The following diagram shows how the various regions are mapped onto your page:

        Regions of the Page

 

////////////// optional blank space ////////////
________________________________________________
                     PAGE
                    HEADING
________________________________________________
    DETAIL and CONTROL HEADING groups
                   v
                   v  CONTROL FOOTING groups
    body           v            v
     of            v            v
    page           v            v
                   v            v
                   v            v
________________________________________________
                                v
                                v
                                v
________________________________________________

                     PAGE
                    FOOTING

------------------------------------------------
////////////// optional blank space ////////////
< Top of physical
 page (logical LINE 1)

< HEADING integer-1
  reserved for PH

< FIRST DETAIL
  integer-2

  reserved for
  body groups
  (CH,DE,CF)


< LAST DETAIL
  integer-3
  for CF only

< FOOTING (=LAST CF)
  integer-4
  reserved for PF


< PAGE LIMIT

< Bottom of page

   Each of your groups will be checked to fit into its appropriate region.  (The REPORT HEADING and REPORT FOOTING groups are special cases.)  The fitting of groups on the page is described in detail in the next part (see LINE Clause).

If you code a HEADING sub-clause, its value will be used in the case where you have a PAGE HEADING or a REPORT HEADING group whose first LINE clause is relative .  Those groups will then be positioned relative to the value of HEADING minus 1.  (Compare the different rule for the positioning of a relative first LINE clause in a body group at FIRST DETAIL, see LINE Clause.)

The region between FIRST DETAIL and LAST CONTROL FOOTING inclusive is the body of the page.  Apart from the optional REPORT HEADING and REPORT FOOTING groups, which may appear anywhere on the page, only body groups (CONTROL HEADING, DETAIL, and CONTROL FOOTING) will appear in this region.  However, if a PAGE HEADING group encroaches into the FIRST DETAIL position, a diagnostic message (096) will be issued and the first body group will appear immediately after the PAGE HEADING group (as though the FIRST DETAIL were absent - see below).

CONTROL HEADING and DETAIL groups are not allowed to appear below the LAST DETAIL position.  If LAST DETAIL is above LAST CONTROL FOOTING, your CONTROL FOOTING groups will thereby have extra space available to them.  This extra space reduces the likelihood of the displeasing effect that results when they are forced to the top of a page.  (See LINE Clause for more details.)  You can imply this spacing by making LAST DETAIL fall short of PAGE LIMIT (or short of the line before the PAGE FOOTING if you have one).  An alternative way to indicate this extra space is to code: LAST CONTROL FOOTING IS +integer-5.

If you code the identifier form of the LAST DETAIL sub-clause, report writer will take the contents of the identifier at the start of each GENERATE and use that as the value for the sub-clause.

If you use the relative form of the LAST CONTROL FOOTING sub-clause (with +), the number of lines you specify will be added to the LAST DETAIL value to give the LAST CONTROL FOOTING value.  For example: LAST CONTROL FOOTING + 3 specifies that 3 extra lines are to be available during the page fit for CONTROL FOOTING groups, regardless of any variations in an identifier operand of LAST DETAIL.

If you omit any of the first four optional sub-clauses, and report writer needs their values, it will infer default values according to the following rules:

no HEADING:

no FIRST DETAIL:












no LAST DETAIL:
















 no LAST CONTROL
 FOOTING:






















 = 1; that is, the top of the logical page.

 a. If there is no PAGE HEADING, the value of HEADING
     is the default; hence, if HEADING is allowed to
     default to 1, the body of the report will begin
     at the top of the page.

  b. If there is a PAGE HEADING, then the line immed-
     iately following the PAGE HEADING group, that is,
     the body of the report, will start immediately
     after the PAGE HEADING.  If your PAGE HEADING
     varies in size, you may deliberately omit FIRST
     DETAIL, and the body of your page will adjust
     itself to take up all the space available.

  a. If there is a LAST CONTROL FOOTING (other than
     the + form), LAST DETAIL takes the same value,
     that is, all your body groups will be allowed to
     come down to the LAST CONTROL FOOTING position.

  b. If there is a LAST CONTROL FOOTING with the
     + integer-5 form, then (first line of the PAGE
     FOOTING) - 1 - integer-5 is used; that is, report
     writer will use as much of the page as possible,
     allowing for any PAGE FOOTING, and leave
     integer-5 extra lines for the CONTROL FOOTING
     group(s).

  c. If there is no LAST CONTROL FOOTING, then the
     same default is used as for LAST CONTROL FOOTING
     (see next).

 1. If the option is in effect    |
     and there is a LAST DETAIL,this value is also
     used for the LAST CONTROL FOOTING.  In all other
     cases:

  2. If there is no PAGE FOOTING, then the PAGE LIMIT
     is used; that is, your CONTROL FOOTING groups
     will be allowed to come down to the bottom of
     the page.  (If you use the identifier form of
     LAST DETAIL, there is an exception to this rule:
     LAST CONTROL FOOTING will be the same as LAST
     DETAIL.)

  3. If there is a PAGE FOOTING group, then the last
     line before the PAGE FOOTING is used.  (If the
     PAGE FOOTING is a relative group, this is
     calculated by placing the last line of the PAGE
     FOOTING at the PAGE LIMIT.)  Note that this
     default action differs from ANS COBOL, where
     LAST CONTROL FOOTING defaults to LAST DETAIL,
     if you specify it.  This extension has the
     advantage that the LAST CONTROL FOOTING sub-
     clause can be omitted in most cases without
     misalignment of CONTROL FOOTING groups or
     wastage of space at the bottom of the page.

The following examples show some possible forms of this clause:

 
                PAGE LIMIT 60.

   This form is valid for all situations because of the defaults.  All your body groups will fit between your PAGE HEADING (or line 1 in its absence) and your PAGE FOOTING (or line 60 in its absence).

 
                FIRST DE 5
                  LAST CF +3
                  PAGE LIMIT 60.

   This reserves lines 1-4 for the PAGE HEADING and, if your report has no PAGE HEADING, they will be left blank.  Your CONTROL FOOTING groups may come down to the line before any PAGE FOOTING, or line 60 if there is no PAGE FOOTING, but CONTROL HEADING and DETAIL groups must end 3 lines before that point.

 
                LAST DETAIL WS-PAGE-SIZE
                  PAGE LIMIT 60.

   Here the value of WS-PAGE-SIZE will be used as the lower limit for all body groups (since the identifier form of LAST DETAIL causes LAST CONTROL FOOTING to default to LAST DETAIL instead of to PAGE LIMIT).