Line Clause

The LINE clause positions a line vertically on the page.

Line Clause: Coding Rules

• Here is a list of the alternative forms:

  • LINE + integer-1. This is the relative form. PLUS may be written in place of +. It indicates that the line should advance integer lines from the previous position. LINE + 0 or LINE + ZERO is allowed, indicating that no advance is to take place. The result is that the line overprints the previous line. You may write "+" with or without a space on either side.

  • LINE integer-2. This is the absolute form. It indicates that the line will appear on that fixed position on the page. The first line on the logical page is LINE 1, corresponding to position reached on issuing a form feed. The highest line number allowed is given by the PAGE LIMIT operand. This absolute form is allowed only if you have a PAGE LIMIT clause in your RD.

  • LINE integer-2 ON NEXT PAGE. This is similar to format b but the ON NEXT PAGE phrase forces a page advance to occur before the line is output, irrespective of whether the group containing it would fit on the current page.

  • LINE ON NEXT PAGE forces the line to be output in the FIRST DETAIL position on the next page (for a body group) or the HEADING position (for a REPORT HEADING or REPORT FOOTING group).

  • LINES ARE integer-1 integer-2 ... is the multiple form of the clause. It enables you to save coding effort by describing several lines in the same clause. You may also write LINES + integer, + integer etc (the relative form) and may combine both forms in the same clause. You may also write ON NEXT PAGE after the last operand, in which case this phrase applies to the first line in the set.

• LINE alone is shorthand for LINE + 1.

• The first LINE clause in each group determines whether the group as a whole is to be relative or absolute. If the first LINE clause is relative, the group is a relative group and all the other LINE clauses must be relative. So the entire group can be positioned anywhere on the page, within the permitted upper and lower limits for the group:

  

  If the first LINE clause is absolute, the group is an absolute group and any of the remaining LINE clauses may be absolute or relative . For example, the following two arrangements of LINE clauses within a group are equivalent:

  

  Using relative lines has the advantage that you can adjust the position of the entire group by changing just the first LINE number.

• If a group has absolute LINE clauses, except where NEXT PAGE is used, the integers must be in increasing order. Except in the case of LINE + 0, no lines may overlap. (If you place PRESENT WHEN condition clauses on the LINE entries, then mutually exclusive lines may have the same line numbers. See PRESENT WHEN clause.)

• A LINE need not contain any COLUMN entries (whether actual or implied by default). The result is a blank line containing no data. For example:

  

  This causes the PAGE HEADING to occupy lines 2 to 4, although data is written only on line 2.

• One LINE clause must not be subordinate to another LINE clause. If this rule is broken, a warning message will be issued and the previous line will be terminated; for example:

  

• The ON NEXT PAGE phrase may be coded only in the first LINE clause of a report group, except when the report group entry has a MULTIPLE PAGE clause (or when this is assumed, as in the case of REPORT HEADING and REPORT FOOTING) where there is no restriction. (See MULTIPLE PAGE clause.) This permits such groups to occupy several pages.

Line Clause: Operation

If a group is absolute, its first LINE clause indicates the starting position of the group (see rule 3 above). The following two paragraphs cover the relative case.

Positioning of relative body groups (CH, DE, and CF)

If the group is the first body group on the page, the first line of the group is positioned at the FIRST DETAIL position, irrespective of the integer of the LINE clause. If you did not code a FIRST DETAIL sub-clause in your RD, the first line will appear one line after the PAGE HEADING group, if there is one, or at the HEADING position if not. Subsequent lines in the group are positioned relative to each other.

If the group is not the first body group on the page, then the first line of the group is positioned relative to LINE-COUNTER, which normally contains the last line position of the preceding body group. (But note that a NEXT GROUP clause or an alteration to the value of LINE-COUNTER in the PROCEDURE DIVISION can affect this positioning.)

Page-Fit Test for Body Groups

When a report has a PAGE LIMIT clause, report writer performs a page-fit test before outputting any body group (CONTROL HEADING, DETAIL, or CONTROL FOOTING). This is to ensure that none of the lines of the group will be output unless all the lines of the group will fit in the region of the page reserved for its type of body group. (See PAGE LIMIT Clause: Operation.) The type of page-fit test performed will depend on whether the group is absolute or relative.

In all cases, remember that LINE-COUNTER contains the current vertical position, normally the position of the line last written before this group was generated.

Absolute Page-Fit Test for Body Groups

If the first LINE is absolute, report writer takes the first LINE number as the starting position of the group. (If any of the absolute LINE clauses are conditional, then this "first line" need not be the first LINE number coded; if all absolute lines are ABSENT, the group will be treated as null or relative, as the case may be.) If LINE-COUNTER is positioned at a line above the starting line position of the group, report writer will not skip to a new page. In all other cases, a page advance takes place (see item 5 below) and the group is printed at the line specified on a fresh page. The next diagram illustrates this process:

Relative Page-Fit Test for Body Groups

When all the LINE clauses in the group are relative, report writer computes the total of all the integers of the LINE + clauses. This gives the total size of the group. If the group contains LINE entries that have a condition attached, as from a PRESENT WHEN/AFTER clause, or from an OCCURS ... DEPENDING clause, all these clauses are evaluated first, so that the actual number of lines about to be produced is known. The value LINE-COUNTER + total-size-of-group is the last line on which the group would appear if it were produced on the current page. If this last line position is beyond the lower permitted limit of the group, the group cannot fit on the page and a page advance takes place.

As shown by the diagram and rules under PAGE LIMIT clause, and GROUP LIMIT clause, the lower permitted limit of the group is given by:

• The report group's own GROUP LIMIT clause, if there is one, or
• The RD's LAST DETAIL, if the group is a DETAIL or CONTROLHEADING
• The RD's LAST CONTROL FOOTING if the group is a CONTROLFOOTING.

The LAST DETAIL and LAST CONTROL FOOTING sub-clauses need not be explicitly specified in your RD, as report writer will assume defaults for them, as outlined under PAGE LIMIT Clause (see above).

The following diagram shows an example of a page-fit test:

Positioning of relative non-body groups (RH, PH, PF, and RF)

• TYPE RH and PH: relative to HEADING minus 1. (However, in the case of the first PH group when there is a RH group also on the first page, it is relative to the last line of the RH group.)

• TYPE PF: relative to LAST CONTROL FOOTING.

• TYPE RF: relative to HEADING minus 1. (However, in the case where the RF group does not begin on a new page, it is relative to the last line of the PF group, if there is one, or to LAST CONTROL FOOTING, if there is no PF group.)

Page advance processing

When report writer executes a page advance, it does the following:

• If you defined a PAGE FOOTING, this is output.
• PAGE-COUNTER is incremented by 1.
• An advance is made to the top of the next page. In "batch" printing aform feed is output, but with an Independent Report File Handler theaction may vary (see Independent Report File Handlers). LINE-COUNTER is then set to zero.
• If you defined a PAGE HEADING, this is output.

Multiple Lines Clause

By writing several integer or + integer terms in a LINE clause, you save time in defining a group of lines that all have a similar layout. Note the following points:

• A multiple LINES clause is functionally equivalent to a LINE with an OCCURS clause; for example:

  • You may use a VARYING clause to vary an internal counter that may be used as a subscript in a SOURCE clause within the scope of the LINE clause.
  • A simple (single-operand) VALUE, SOURCE, SUM, or FUNCTION is repeated in every occurrence of the line.
  • You may use a multiple VALUE or SOURCE clause to place a different value in a report field in each occurrence of the multiple LINE.
  • You may place a data-name at the start of the entry and SUM it into another entry to produce a total of all the (multiple) entries.

• However, in contrast to the OCCURS clause, the intervals between the lines defined by a multiple LINES clause need not be regular.

• Your multiple LINES clause will be syntactically correct if it would be correct when written as a series of LINE clauses in separate entries.

• Here are some examples of the multiple LINES clause:

     a.03 LINES 1, 3, 4.
     b.03 LINE NUMBERS ARE +2, +1, +1 COL 6 VALUE "----".
  

  Here the ON NEXT PAGE phrase applies to the first of the three lines: c.03 LINES 1, +2, +2 ON NEXT PAGE.

• The multiple LINES clause is useful in lines, such as headings, that have stacked text. Consider the following example in conjunction with the description under Multiple SOURCES and Multiple VALUES:

  

  Of course, you do not have to code the multiple VALUES in a "stacked" format like this, but it is suggested to aid readability.

Compatiblity

• Only new Report Writer provides the following features:
• Use of + as alternative to PLUS,
• The multiple format,
• LINE PLUS ZERO as alternative to LINE PLUS 0,
• Blank entry with LINE clause only to provide blank line,
• Absolute LINE allowed to follow relative LINE,
• Absolute LINEs may advance to new pages within RH, RF, and bodygroups.