Column Clause

The COLUMN clause specifies the horizontal positioning of a field in the report line.

Column Clause: Coding Rules

• COLUMN with no operands is shorthand for COLUMN + 1.

• For every entry with a COLUMN clause, there must be a LINE clause at the same or a higher level. So you may write:

  05 LINE 5 COL 20 VALUE "TITLE PAGE".

  provided that there are no other entries within LINE 5. If the line has two or more fields, you must then create a new level, as with:

   05 LINE 6.
     07 COL 5 VALUE "REPORT XYZ".
     07 COL 72 VALUE "ANNUAL RETURNS".
  

  If you code a COLUMN entry at the same level as the preceding LINE:

   05 LINE 6 COL 5 VALUE "REPORT XYZ".
   05 COL 72 VALUE "ANNUAL RETURNS".
  

  then Report Writer will diagnose this as invalid but will allow it as stated.

• COLUMN may be the only clause in an entry. The result is a blank field whose only purpose is to shift the current horizontal position COLUMN-COUNTER) to the right. A blank field (absolute or relative) occupies one column's width in addition to the usual spacing for the COLUMN. It is therefore equivalent to coding a VALUE consisting of a single space alongside the COLUMN clause (although doing so would be less efficient). For example, COL + 4 coded alone in an entry shifts the current horizontal position four (not three) columns right. (See the discussion in the next section).

• The size of your item is calculated from the PICTURE clause or the size of the VALUE "literal", and is used in combination with your COLUMN clause to check that: (a) the line width is not exceeded (see LINE LIMIT clause and, if you are using automatic line wrap, see WRAP clause), and (b) no two items overlap (unless they both carry a PRESENT AFTER clause). If two or more items overlap in whole or in part, report writer will diagnose this as invalid but will allow the COLUMN positions and field sizes as coded. The later-coded entry will then overwrite the earlier-coded entry at run time by the number of overlapping columns and data will be lost. No run time error occurs.

• Within each LINE, any absolute COLUMN numbers should be in ascending order, after the evaluation of any PRESENT WHEN clause and any PRESENT AFTER clause. If this rule is broken, report writer will issue a Warning (message 250) but will allow the COLUMN positions as coded.

• The RIGHT and CENTER phrases cannot be coded with the + (relative) form of this clause.

• You may write "+" with or without a space on either side.

Column Clause: Operation

The COLUMN clause positions your elementary field horizontally. Here is a list of the options:

• COLUMN + integer-1. This is the relative form. It indicates that the horizontal position within the line is to be moved integer column positions from the last character of the preceding field to the first character of this field. Note that the "gap" before the field will be one less than the value of the integer. For example:

  COLUMN + 1 = "no gap"

  COLUMN + 2 = "one space before field", and so on.

  If you use COLUMN + integer in the first field of a line, it is treated as though you had written the absolute form, COLUMN integer-1, since the initial value of the horizontal position is zero.

• COLUMN integer-2. This is the absolute form. It indicates that the left-hand column of the field must appear on that fixed position within the line. Remember that the first column in the line is COLUMN 1. LINE LIMIT is the highest possible value of integer.

• COLUMNS integer-1 integer-2. This is the multiple form of the clause. It reduces your coding effort by including several operands in the same clause. The relative multiple form, COLUMNS + integer, + integer ..., is also allowed and you may combine both forms in the same clause. Multiple COLUMNS are described in more detail below (see Multiple COLUMNS Clause).

• COLUMN RIGHT and COLUMN CENTER are used if you wish to specify the righthand or center position of the field as alternative anchoring points, to save you the effort of "counting out" the length of the field to establish its left-hand column when you already know its center point or right-hand column. COLUMN LEFT, the normal alignment, is provided for syntactic completeness.

  If you specify COLUMN CENTER and the field is an even number of column positions wide, the extra character position goes to the right of the central column. The following example shows the allowable alternatives for a six-character field starting in column 1:

  

  You will get a ragged left-hand side in the case of COLUMN RIGHT and centralization with ragged left and right , in the case of COLUMN CENTER. By successively generating the following entry on different lines with different values: 05 COL RIGHT 15 PIC 9<9(6) SOURCE POPULATION-COUNT. You will obtain:

  

  The following, generated several times with a different CITY:

  

  gives you, for example:

  

  Note that RIGHT and CENTER may also be used with the multiple format of the COLUMN clause discussed in 3.4.4 Multiple COLUMNS Clause). The CENTER or RIGHT option is required if you need to center or rightalign a variable-length field - (see "<" and ">" symbols) for full details. The output in the box above could also have been produced using a SOURCE item thus: 05 COL CENTER 20 PIC <X(20) SOURCE CITY-NAME.

• If an elementary item has no COLUMN clause then, if the OSVS precompiler option is in effect or a data-name is present, the item will not appear in the report. It is then termed an unprintable item. Unprintable items are used chiefly for summing in the following cases:

  For Subtotalling and SOURCE SUM Correlation. A SOURCE clause may be written as an unprintable item because a SUM of a certain data item is required but its individual values are not:

  

  For rolling forward of certain values into totals. This is report writer principal way of forming totals. This time the unprintable item has a data-name and the data-name is summed:

  

  For forming totals that are not printed directly but used indirectly:

  

  Further examples may be found in SUM Clause.

• If the precompiler option OSVS is not in effect, and any elementary entry beneath the LINE level has no COLUMN clause, then COLUMN + 1 is assumed for the entry, provided that the level-number is not followed by a data-name. Thus, you could omit both COLUMN clauses in the following fragment:

  

Multiple Columns Clause

You may use the multiple form of the COLUMN clause by placing several integer or + integer terms after the keyword. This reduces the effort needed to code several adjacent entries that have a similar format. Note the following points: A multiple COLUMNS clause is functionally equivalent to an ordinary COLUMN clause used in conjunction with an OCCURS clause; for example:

• You may use VARYING to vary a counter that is used as a subscript in a SOURCE clause.
• You may use a simple (single-operand) VALUE, SOURCE, SUM, or FUNCTION clause to place the same value repeatedly in each instance of the field.
• You may use a multiple VALUE or SOURCE clause to place a different value in each instance of the field.
• You may place a data-name at the start of the entry and SUM the data-name in another entry to produce a total of the instances or occurrences collectively or individually. To form individual totals, there must be another multiple or occurring COLUMN clause in the entry with the SUM clause.

Unlike the method of repetition using the OCCURS clause, the intervals between the entries defined by a multiple COLUMNS clause need not be regular.

Your multiple COLUMNS clause will be syntactically correct if it would be correct when written as a series of separate COLUMN entries.

Here are some examples of the multiple COLUMNS clause:

The following diagram and corresponding code illustrates the usefulness of the multiple COLUMNS clause:

Compatibility

Only new Report Writer has the following features:

• Abbreviation of keyword as COL,
• Relative form (+ or PLUS),
• CENTER and RIGHT options,
• Multiple format,
• Blank entry when COLUMN clause present alone.