Source Clause

This clause specifies the source field (or expression) that provides the contents of a field in your report. The source field is usually outside the REPORT SECTION, but may also be implicitly defined within it.

Source Clause: Coding Rules

• Any valid COBOL identifiers or arithmetic expressions may be used as operands, including any COBOL term that may be the source item of a MOVE or COMPUTE; for example, report writer special registers such as PAGE-COUNTER, GLOBAL or EXTERNAL items, and special compiler registers such as LENGTH OF.

• Each operand may be subscripted and/or qualified if necessary. For example: SOURCE IS MIN-STOCK IN MAIN-RECORD (AREA-NO, DISTRICT-NO)

  The operand may have as many qualifiers, subscripts or indexes as are normally permitted for the subject of a MOVE statement. Relative subscripting and reference modification may be used.

• You must also code a PICTURE clause in the same entry (unlike VALUE, which need not have a PICTURE). The PICTURE used must be compatible with the PICTURE of the operand(s). If you are in any doubt, look at the description of the identifier where it is originally defined in the FILE, WORKING-STORAGE or LINKAGE SECTION of your program. Ensure that its PICTURE is unedited and that you are not attempting to produce a COMPUTATIONAL field from a PICTURE X format. The two PICTUREs may be of unequal length, in which case there will be truncation or space-filling on the right (for a non-numeric field) or truncation or zero-filling on the left (for a numeric field). The rules for the SOURCE statement are exactly those of the MOVE or COMPUTE statements of procedural COBOL.

• The SOURCE IS and SOURCES ARE keywords may be omitted, except when immediately following a VARYING clause. We shall still refer to the clause as a SOURCE clause, however.

• An expression may be any arithmetic expression containing any of the following symbols and keywords:

  Expression	Description
  +	for addition
  -	for subtraction
  *	for multiplication
  /	for division
  **	for forming an exponent
  (and)	to prioritze evaluation or to structure the code for documentation
  SUM	for a total (automatically reset to zero after output)
  COUNT	to show the number of times another REPORT SECTION item has appeared (also reset to zero after output)

  In addition, the expression may have any number of identifiers, and these may be subscripted or qualified. Here are some examples of expressions:

     SOURCE IS NUMBER-ORDERED * UNIT-PRICE / 100 
     SOURCE IS ((SUM OF REP-SALARY) / NUMBER-IN-DEPARTMENT (DEPT-NO))
  

  The rules for forming an expression are exactly as for the COBOL PROCEDURE DIVISION, as described in your COBOL language reference. For more information, see SUM clause. The effect of a potential zero divide or size error depends on the choice of action on overflow. (See OVERFLOW clauses.)

• The ROUNDED phrase may be used in the same entry if you use a numeric PICTURE that has fewer digits to the right of the decimal point than the SOURCE identifier. It will ensure that the value produced is the numerically closer of the two possible values, instead of always truncating the unwanted digits. You can use ROUNDED with a single identifier as well as with an expression. (So you need not code "+ 0" for ROUNDED to be legal.) In the following example: 05 COL 20 PIC 999 SOURCE SALARY ROUNDED.

  if SALARY contains 100.50 or 100.60 or 100.99, the value produced will be 101, not 100.

  For more details of the ROUNDED keyword, see in your COBOL language refer-ence under the COMPUTE verb. ROUNDED is a clause in its own right and thus may be written at any location in the entry. If you have a multiple form of the SOURCE clause, or more than one such clause (see Multiple SOURCES), ROUNDED will affect all of them wherever applicable.

• You can indicate a multiple-choice entry by appending WHEN or UNLESS condition to the SOURCE clause, and then coding further consecutive pairs of SOURCE and WHEN/UNLESS clauses in the same entry (see The Multiple-Choice Form).

Source Clause: Operation

• Rules for Generating Report Field

  The effect of the Source clause is best described by reference to the Cobol Move or Compute statements, because it obeys identical rules:

  Form of Source Clause	Equivalent Procedural Statement
  identifier (without ROUNDED) identifier ROUNDED	MOVE identifier TO report-field ADD ZERO, identifier GIVING report-field ROUNDED
  arithmetic-expression (without ROUNDED)	COMPUTE report-field = expression
  arithmetic-expression ROUNDED	COMPUTE report-field ROUNDED = expression

  The special registers CURRENT-DATE and TIME-OF-DAY of OS/VS COBOL and DOS/VS COBOL make use of the conceptual data items DATE and TIME.

  If the report field has "<" PICTURE symbols, or begins in a variable position, report writer will not store the result directly in the report field, but will use an intermediate area.

• Reference to controls

  If the SOURCE clause refers, directly or indirectly, to a CONTROL operand, and the SOURCE is fetched at CONTROL FOOTING time, the contents of the control identifier before the control break will be used. This means you will obtain before-the-break contents for your control fields in the following report groups:

  • In every CONTROL FOOTING;

  • In the PAGE FOOTING and PAGE HEADING, if the page advance was caused by a CONTROL FOOTING group.

  This rule applies whether the CONTROL operand is used as a SOURCE by itself, or as a subscript, or as part of an expression. It also applies if you refer to the CONTROL operand via a redefinition, or via a group field that contains it, or a subordinate field. This is because the pre-break values are temporarily stored directly back in the control fields outside the REPORT SECTION while CONTROL FOOTING processing is being done.

  One important consequence of this rule is that, if you use fields defined under an FD in the FILE SECTION as controls, your program must not execute any report writer statements - not even a TERMINATE - after the input file releases the buffers. The correct order for "close down" is therefore:

     TERMINATE report 
     CLOSE all report files and input files
  

  See CONTROL clause, and GENERATE statement for further details.

Multiple Sources

If you use the multiple form of the SOURCE clause by writing more than one identifier or expression after the keyword, you will avoid the effort of coding several separate entries. Note the following:

• You may include the keyword NONE to indicate that a particular field is to have no contents stored in it. It is then treated as ABSENT. An example of the use of NONE will be found under the LINE clause (see Multiple LINES Clause).

• Your entry must be subject to at least one of the following:

  • A fixed OCCURS clause (not OCCURS...DEPENDING), or
  • A multiple LINES clause, or
  • A multiple COLUMNS clause.

• The number of terms in your multiple SOURCES must equal the total number of repetitions the entry is subject to in all dimensions, or the number of repetitions of one or more of the inner dimension(s). For example, with the following layout:

    03 LINE OCCURS 4. 
     04 OCCURS 3. 
      05 COLS +2, +1 PIC... SOURCES ARE .....
  

  The number of SOURCES should be either 2 (just the inner dimension), 6 (the product of the inner two dimensions), or 24 (all the repetitions).

• If the terms cover more than one dimension, they are distributed along the innermost dimension, periodically stepping to the next entry in the outer dimension(s). For example:

  

  This technique is useful when your SOURCE items are not already conveniently arranged in a table or when, as in the case above, the order is irregular.

• If there are two or more dimensions and the number of terms matches only the inner dimension(s), the terms are recycled from the first SOURCE operand for each repetition of some outer dimension. For example, in the following case:

    03 LINE OCCURS 4. 
       05 COLS 1, 6, 11 PIC... SOURCES ARE JAN, FEB, MAR.
  

  the values of JAN, FEB and MAR will be repeatedly stored in each line. However, you may vary the contents actually stored by allowing a VARYING operand to advance in step with each occurrence of the outer dimension and by using it as a subscript in the lower-level entry:

  

• If a ROUNDED phrase is present in the entry, every SOURCE item will be rounded.

  The multiple SOURCES may be used as one or more of the alternatives within a multiple-choice entry. You need not use a multiple SOURCES in every alternative:

  

• You may omit the SOURCE keyword, except when immediately following a VARYING clause.

• Other examples of the multiple SOURCES clause will be found under Multiple COLUMNS Clause and Multiple LINES Clause.

Compatibility

All aspects of the following features are unique to new Report Writer:

• SOURCE keyword being optional,
• Arithmetic-expression format,
• ROUNDED phrase,
• Use of SUM or COUNT term as operand,
• Multiple format,
• Multiple-choice format.