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.

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 subclauses), 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. 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 OSVS option is not in effect, this may be provided automatically - see item 7 in the next section below.)

• 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:

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 3.10 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	= 1; that is, the top of the logical page
  no First Detail	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. If there is a PAGE HEADING, then the line immediately 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.
  no Last Detail	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. 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 integer5 extra lines for the CONTROL FOOTING group(s). If there is no LAST CONTROL FOOTING, then the same default is used as for LAST CONTROL FOOTING (see next)
  no Last Control Footing	If the OSVS option is in effect and there is a LAST FOOTING: DETAIL, this value is also used for the LAST CONTROL FOOTING. In all other cases: 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.) 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:

• 

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

• 

  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.

• 

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

Compatibility

• The alternative spellings DE for DETAIL, FIRST BODY GROUP for FIRST DETAIL, LAST DETAIL OR CONTROL HEADING / CH, LAST CONTROL FOOTING / CF, and LAST BODY GROUP are unique to new Report Writer.

• The concept that each keyword may introduce a clause in its own right is unique to new Report Writer. OS/VS and DOS/VS COBOL require the keyword PAGE to appear first and do not allow different phrases of the PAGE LIMIT clause to be separated by another clause.

• OS/VS and DOS/VS COBOL require the keyword LINE or LINES.

• The defaults assumed by OS/VS and DOS/VS COBOL are not sufficient to allow omission of the clauses in most cases as they are with new Report Writer. Where new Report Writer's defaults are different from those of OS/VS COBOL and DOS/VS, no undetectable incompatibility will result, because in these cases the different defaults assumed by OS/VS and DOS/VS COBOL cause compilation errors.