Report Group Descriptions
This part describes in detail every aspect of the Report Group Descriptions that follow your RD entry in the REPORT SECTION. After the next section, the
sections are in alphabetical order for easy reference.
Your RD entry may be followed by any number of Report Group Descriptions, but there is a limit to the number each TYPE other than DETAIL. Each Report Group Description begins with a 01 level-number entry in the A-margin. More information about report groups follows or may be found later in this part (see TYPE Clause).
Report Groups: Keyword Table
where report-group-entry is defined as follows:
where multiple-choice is defined as follows:
You need not place data-names on your report group entries except in the following cases, where they are required: On the 01-level entry of a DETAIL group, or any other group that may be referred to in the USE BEFORE REPORTING header of a Declarative SECTION (see USE BEFORE REPORTING Directive ). When a data-name is used at the 01-level, it gives a name to the entire report group and is called the report-group-name or group-name. The group-name must be unique within an RD, but you may re-use the name in another RD. On a numeric entry referred to in a SUM clause or term. (See SUM Clause.) On any entry at any level that is referred to in a COUNT clause or term. (See COUNT Clause.) In all other cases it is preferable to omit data-names since an unnecessary data-name may mislead the program-reader into thinking that it is referred to in one of the ways above. It may also impede the precompiler's optimization.
The following general-purpose DATA DIVISION clauses can be used in a report group. The first four may be used at both group and elementary levels (not the 01
-level in the case of OCCURS). PICTURE and VALUE are allowed only at the elementary level.
but the following cannot be used in a report group:
any USAGE other than DISPLAY, such as:
In addition to the general DATA DIVISION clauses, report groups may contain special-purpose clauses that describe the position and contents of fields. The first four clauses, TYPE, NEXT GROUP, GROUP LIMIT, and REPEATED, can appear only at the 01-level. The special-purpose clauses are:
The clauses PICTURE, COLUMN, SOURCE, VALUE, SUM, COUNT, and FUNCTION can appear only at the elementary level. For every entry with a COLUMN clause, there must be a LINE clause either at the same level as or at a higher level. If a given report line contains only one elementary field (and provided the entry is not a multiple-choice entry, see PRESENT WHEN Clause), you may combine the LINE and the COLUMN clauses in the same entry, for instance:
There is no limit to the number of elementary fields a report line may contain. If the report line contains several elementary fields, you must code all the COLUMN entries within the line at a lower level than the LINE entry, for example:
Not all the COLUMN clauses within a LINE need be at the same level, since some or all elementary entries might be contained within non-LINE group entries; for example:
A LINE clause must not be subordinate to another LINE clause. (If this rule is violated, the nested LINE entries will be treated as though they were defined at the same level as the first.) If a given report group contains several lines, you must give all the LINE entries in that group a level-number other than 01. If the group contains only a single report line, you may code the LINE clause in the 01-level entry; for instance:
You may choose only one of five clauses: SOURCE, VALUE, SUM, COUNT, and FUNCTION to supply the contents of an elementary item automatically, bearing in mind that (a) SOURCE or VALUE can be repeated several times in a multiple-choice entry (see Multiple-Choice Form), and (b) SUM (see SUM Clause) or COUNT (see COUNT Clause) can be used as special operators in terms in an arithmetic expression (see SOURCE Clause). If there is no SOURCE, VALUE, SUM/COUNT, or FUNCTION clause in an elementary item, the following conditions must be met: The entry must have a data-name (following the level-number). The entry must have a COLUMN clause. If the COLUMN clause is relative, the item must have a fixed horizontal position (that is, it must follow an item with a fixed end-column, unless it is first in the line). The item must have a PICTURE with none of the features that are unique to the REPORT SECTION (that is, "<" or ">" symbols or general insertion characters). Report writer will then expect you to fill in the report field independently with some COBOL procedural statement. As an example, in the following case
the only way this item can receive a value is through a COBOL MOVE, ADD, ACCEPT, or other procedural statement, which is outside the scope of report writer and is left to you. Report writer will ensure that the report field is not overwritten by any other field, so any value stored in the item R-PRIOR-CUST-NO will remain there and will appear whenever the enclosing group is produced. Note that you should not attempt to change the value of a group field, such as a report line, in this way. You may code the clauses of any report group entry in any order, except in the case of a multiple-choice entry, where each SOURCE, VALUE, or FUNCTION operand is immediately followed by WHEN condition. Details of this combination are given later (see 3.18).
However, you may code the SUM clause more than once in the same entry. You may also code a SOURCE, VALUE, or FUNCTION
clause and its associated PRESENT/ABSENT WHEN/AFTER clause more than once in a multiple-choice entry. All other
clauses may appear no more than once in an entry.
BLANK WHEN ZERO Clause: Coding Rules If you code BLANK WHEN ZERO in an elementary entry, the entry must have a numeric PICTURE. If you code it in a group level entry, it applies to all the numeric elementary entries within the group. (This clause is usually referred to as the BLANK WHEN ZERO clause, even though the word WHEN is optional.)
You may use BLANK WHEN ZERO even if your field is not in a fixed position. It is also permitted with a variable-length field (PICTURE symbol "<"), in which case a zero value in a variable part has a length of zero.
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:
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:
If you code a COLUMN entry at the same level as the preceding LINE:
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 WHEN/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 all PRESENT WHEN and PRESENT AFTER clauses (see 3.17 and 3.18). If this rule is broken, report writer will diagnose this with 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 + 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"
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 3.4.4). COLUMN RIGHT and COLUMN CENTER are used if you wish to specify the right-hand 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
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 below (see 3.4.4). The CENTER or RIGHT option is required if you need to center or right-align 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:
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 SOURCE SUM correlation (see 3.23.5). 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 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
A multiple COLUMNS clause is functionally equivalent to an ordinary COLUMN clause used in conjunction with an OCCURS clause (see 3.14); 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:
Use of COLUMN-COUNTER COLUMN-COUNTER indicates the current horizontal position within a line. At each stage during the processing of a line, it contains the most recent rightmost column number on which data was placed in the line. It may also be incremented by an "empty" (unprintable) entry containing only a COLUMN clause. Regardless of the number of reports and report lines it contains, each program has just one COLUMN-COUNTER. Report writer uses COLUMN-COUNTER as a place-keeper and internal subscript while assembling variable-length or variable-position fields in a report line. For the sake of efficiency, it does not initialize or update COLUMN-COUNTER in a report line consisting of fixed-length, fixed-position fields, unless you explicitly refer to it in an item in the line. You may use COLUMN-COUNTER in the condition of a PRESENT WHEN clause (see 3.18), or as the operand of a SOURCE clause (see 3.21), or as a parameter to a FUNCTION (see 3.7). It cannot be used in your PROCEDURE DIVISION, because the generating of each line is an indivisible operation. COLUMN-COUNTER may be used to simplify the conditions that would otherwise be required to string together a series of conditional fields:
If your current group is a REPEATED group (see 3.19), or if you use the SET COLUMN statement of the Page Buffer feature (see SET Statements), you should bear in mind that COLUMN-COUNTER is relative to the left-hand boundary of the group. So it does not include the extra left-hand margin used to offset your REPEATED groups or the extra margin you create with SET COLUMN. COLUMN-COUNTER should not be used in a condition where the field is to be totalled using the SUM clause, because COLUMN-COUNTER is not updated when totalling is performed at the start of processing for the group.
COUNT Clause: Coding Rules Each data-name must be the name of any REPORT SECTION entry other than an RD. It may even be the data-name of a group entry that contains the COUNT clause. You may place the COUNT clause in a different report group from the item counted (rolling forward) or in the same group (cross-footing). As with the SUM clause, if the COUNT clause appears in a multiple CONTROL FOOTING, all but the lowest level total is formed by rolling forward the next-lower total. Unlike the situation with the SUM clause, the item counted need not be a numeric field. Like the SUM clause, you may use the COUNT clause in two ways: As a clause in its own right. You write the clause in place of a SOURCE, VALUE, or FUNCTION clause. For example:
As a term in an expression used as a SOURCE operand; for example:
You may combine SUM and COUNT terms in the same expression. For example, the following will give you the average value of all the instances of a numeric field:
COUNT Clause: Operation
The item referenced may be at any level; for example: A 01-level entry: you will obtain the number of appearances of a particular group. A LINE entry: you will count the number of appearances of that particular LINE. A COLUMN entry: you will obtain a count of appearances of that particular elementary item. Assuming that you do not use the RESET phrase, when your COUNT field has been output the count returns to zero. Hence, you will always obtain the count of the number of appearances of the item since the last time the count was output. You may use the RESET ON phrase to delay the resetting of the count to zero until a higher-level control break occurs, in exactly the same way as you can with the SUM clause. If the item counted is one that repeats several times because of an OCCURS or REPEATED clause, the count will include each repetition. An OCCURS ... DEPENDING will count just the number of items actually output. A PRESENT clause (or the equivalent) is also taken into account, so that items "not present" do not contribute to the count. You may count more than one item by writing more than one data-name as an operand in the clause. The counts are then simply consolidated internally.
(The COUNT clause is really a special variant of the SUM clause, so other points of interest can be found under SUM Clause.)
FUNCTION Clause: Coding Rules Function-name must be alphanumeric and must be either a standard supplied function name or a user-written one. It may begin with a numeric character. A full list of standard function names is given below, and you or any other person may add new ones to the list at any time. The FUNCTION clause may be used only at the elementary level, in place of SOURCE, SUM, or VALUE. It is permissible for the entry to have no COLUMN or PICTURE clause, i.e. the entry may be a dummy. You may use it in a multiple-choice entry, if so desired. The number of parameters you need, if any, and their formats are stated below (see 3.7.4) for each built-in function. User-written functions should also have a description that tells you this information. Some functions take no parameters while others allow either a fixed or a variable number. Each parameter may be any identifier. It may also be an integer, literal, or arithmetic expression, for example:
in which case the parameter is given to the Function routine as a one-word signed binary field. You cannot use SUM or COUNT terms in the expression. Neither can you use LENGTH OF, ADDRESS OF, BY CONTENT, or BY REFERENCE, as part of a parameter. The FUNCTION keyword may also be used in the format FUNCTION IS function-name (...) in a SOURCE clause or in a condition in a PRESENT WHEN clause. In such cases function-name is a COBOL intrinsic function and is not part of the FUNCTION clause described here.
If you code an edited PICTURE (numeric or alphanumeric) with the FUNCTION clause, report writer invokes the function routine using an internal intermediate field that has the unedited equivalent of your PICTURE. This is obtained by removing all insertion characters, including any decimal point. Also any "Z" or "*" symbol or floating sign or currency symbols are converted to an equivalent number of "9" symbols. The "<" symbol is also removed. For example, if your entry is as follows:
Report writer will provide the function routine with an intermediate field with a PICTURE of 9999V99 as a parameter for receiving the output value. Report writer then executes a MOVE from the intermediate field to your original report field. This means that all functions, including user-written ones, can operate with edited report fields, without function routine developers needing to allow for the many possible edited formats.
One of the parameters report writer passes to the function routine is the size in bytes of the report field, if any, to be output. If the PICTURE is edited, this size is the size of
the intermediate field. Using the case given in the previous paragraph, for instance, the function routine will be told that the size is 6. The Function
routine may decide to produce different formats for the output report field, depending on the number of bytes implied by this size. It may also simply truncate the output value (on the left
or the right) down to the number of characters required. This can give you freedom to choose from many possible PICTUREs to use with a function. For example, if DATE is used, and today's
date is 5th January, 1997:
PICTURE 99/99/99 will give you:
PICTURE 99BXXXB9(4) will give you:
PICTURE <99BX(9)B<9999 will give you:
Functions cannot detect the kind of PICTURE symbols used. For example PICTURE XXBXXBXX produces the same result as PICTURE 99B99B99.
Number of parameters: 0 or 1.
If no parameter is supplied, the date will be the current date at the start of the run. If one parameter is supplied, it must be either a 7-digit
date held in a PIC S9(7) COMP-3 (packed) format in the form ccyyddds (s = sign), or a 5-digit date held in a PIC S9(5) COMP-3
(packed) format in the form yyddds (in which case the current century is assumed).
DAY (Day-of-Week) returns the alphabetic day-of-the-week represented by the given date. Number of parameters: 0 or 1.
If no parameter supplied, the current date is used. If one parameter is supplied, it may be either a 7-digit date held in a
PIC S9(7) COMP-3 (packed) format in the form ccyyddds (s = sign), or a 5-digit date held in a PIC S9(5) COMP-3 (packed) format
in the form yyddds (when the current century is assumed), or a two- or four-byte (PIC S9(9) COMP or PIC S9(4) COMP) location containing a value from 1 (= Monday) to 7 (= Sunday),
or a one-byte (PIC 9 DISPLAY) location containing a value from 1 to 7.
DAYSIN (Days Elapsed Since Base Date) converts a binary number of days since the base date (see below) to a date in the same format as for DATE. Number of parameters: 1. The parameter must be the number of days since the base date inclusive, held as one fullword binary (such as PIC S9(9) COMP). The base date is January 1st 1601, i.e. 584,693 days since absolute year zero (ignoring calendar reforms). A zero value means December 31 1600. A negative value gives a date before December 31 1600. You may change the base date by re-compiling the source of the FUNCTION supplied with this product, in which case your new function should have a different name to avoid incompatibility.
MDAYS (Days Elapsed - US Format) converts a binary number of days since the base date, as defined under DAYSIN above, to a date in the same format as MDATE, that is, month/day/year. This function is otherwise identical to DAYSIN. See MDATE above for more information on report field lengths.
Number of parameters: 0 or 1
If no parameter is supplied, the current month is returned. If a parameter is supplied, it should be either a 7-digit date held in a PIC S9(7)
COMP-3 (packed) format in the form ccyyddds (s = sign), or a 5-digit date held in a PIC S9(5) COMP-3 (packed) format in the form
yyddds (when the current century is assumed), or a two-byte (PIC 99 DISPLAY) location containing a value from 01 to 12, or a four-byte binary (PIC S9(9) COMP) location containing
a value from 1 to 12.
MOVE (Save Register) copies any report writer special register to a specified working location. This is a dummy function which requires no report field and may be coded without a COLUMN or PICTURE clause. (If the entry is not a dummy, the field will be space-filled.) Number of parameters: 2. Parameter 1 is any numeric special register, typically LINE-COUNTER or COLUMN-COUNTER. It may also be a user-defined data-name specified in a VARYING clause. Parameter 2 is any half-word binary location (PIC S9(4) COMP) to receive the contents of parameter 1. This FUNCTION is used to capture on the fly the contents of a register whose value is constantly changing. The following sample code prints up to 12 monthly payments to print side-by-side showing only those which are not zero and, by storing each value of the VARYING subscript R-MONTH in LAST-MONTH for those occurrences selected, it is able to state which month was the last to be printed.
RYDATE (Real YDATE) is similar to YDATE (see below) without the optional parameter, except that the current date is always fetched. Compare RMDATE.
Number of parameters: 1 The parameter may be either a state number with PICTURE 99 (DISPLAY) ranging from 01 (ALABAMA) to 51 (WYOMING), in alphabetical order of their full names, or a two-character standard abbreviation e.g. "AL" or "WY". The report-field length must be at least 14. If it is less than 20, then DISTRICT OF COLUMBIA is rendered as D.C.
Number of parameters: none
YDATE (Date Reversed) returns a date in any one of a number of display formats in the order year/month/day. Apart from this order, it is similar to DATE and MDATE.
Number of parameters: 1.
The single parameter must contain the ZIP code in the format S9(9) COMP-3. This is then output in the form nnnnn-nnnn, but the final -nnnn is left blank
if the last four digits are 9999.
GROUP LIMIT Clause: Coding Rules Your integer must not be greater than the lower limit (LAST DETAIL, LAST CONTROL FOOTING, or PAGE LIMIT) that would normally apply without the clause (see PAGE LIMIT Clauses ). Code this clause only at the 01-level in a body group (DETAIL or CH/CF). Your group's first LINE clause must be relative.
This clause is especially useful in a CONTROL HEADING, which might appear misplaced if it appeared near the bottom of the page like the DETAIL and CONTROL FOOTING groups.
JUSTIFIED Clause: Coding Rules If you code JUSTIFIED RIGHT in an elementary entry, the entry must have an alphanumeric PICTURE. This clause acts on elementary-level fields, but you may also code it in a group-level entry, including 01, where it applies to all the alphanumeric elementary entries in the group.
The JUSTIFIED clause takes effect when your alphanumeric SOURCE field is of a different size from the PICTURE. The padding out with spaces or the truncation (if the PICTURE is smaller than the field) then takes place on the left instead of the right. In the following example, we want to output either MONTH-NUMBER (2 characters) in columns 12 and 13 or YEAR-NUMBER (4 characters) in columns 10 through 13:
LINE Clause The LINE clause positions a line vertically on the page.
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:
|