Varying Clause

This clause enables you to vary the value of a numeric counter (typically for use elsewhere as a subscript) during the production of a repeating field.

Varying Clause: Coding Rules

• You may write any number of different data-name operands in this clause, each with an optional associated FROM and BY phrase.

• Your entry must also have either an OCCURS clause or a Multiple COLUMNS Clause or a Multiple LINES Clause.

• Your data-names must not be defined already anywhere else in the program and you should not attempt to define them separately. Report writer creates a description for them itself, internally. (This is similar to the way COBOL handles index-names.)

• You can re-use the same data-names in different VARYING clauses, provided that you do not do this when the clauses are nested (enclosed one within the other). For example, you could write VARYING R-LINE on each repeating LINE, and VARYING R-COL on each repeating COLUMN, throughout your program.

• If you intend FROM 1, you may omit the FROM phrase and report writer will infer it. Likewise, if you intend BY 1, you may omit the BY phrase and report writer will infer it. (FROM 1 and BY 1 are the most usual requirements, so these assumptions are convenient.)

• Each expression may be any integer, or an identifier, or an arithmetic expression, provided that the result has an integer value. The expression may contain data-names of an enclosing VARYING clause. It can also use a data-name of the same VARYING clause, but only in its BY expression. It must not contain data-names of an enclosed VARYING clause, or of any other VARYING clause. Thus the following are legal:

  

Varying Clause: Operation

• When report writer is about to produce the first occurrence, it places the FROM value in an internal named data item set up implicitly by the VARYING clause. This is repeated, in the order given in the clause, for any additional data-names that may have been specified in the VARYING clause.

• When report writer is about to produce each of the remaining occurrences, it adds the BY value to the data item. This is also repeated, in the order given in the clause, for any additional data-names that may have been specified in the VARYING clause.

• The VARYING clause enables you to produce different source-items or values in successive appearances of a repeated field. Here are some examples: To generate the numbers 1 through 10 in a line:

  

  To output a two-dimensional array in Working-Storage into a two-dimensional array in your report (for example daily costs for four seven-day weeks):

  

  You could display each week's entries from right to left by writing: VARYING DAY-NO FROM 7 BY -1.

  Now let's display the same entries, except that they are all held in a one-dimensional array of twenty-eight entries. (This example is important.)

  

  As each week is processed, START-DAY-NO takes values 1, 8, 15 and 22. DAY-NO takes the seven values 1 to 7, then 8 to 14, then 15 to 21, then 22 to 28 in turn, each time starting with the new value of START-DAY-NO. In the clause VARYING START-DAY-NO FROM 1 BY 7, the phrase FROM 1 could have been omitted and in the clause VARYING DAY-NO FROM START-DAY-NO BY 1, the phrase BY 1 could have been omitted.

• To "fold round" a large array in boustrophedon ("as the ox turns") sequence (if NO-ACROSS is the horizontal repeat factor):

  

• To produce a pyramid-shaped design:

  

  Note that VARYING can also be used with a multiple COLUMN or LINE, as the following example shows:

  

• To set up a "running index" which continues each time from its latest value, do not code something like VARYING R-WEEK FROM R-WEEK + 1 , but calculate the starting value explicitly.

• To give your counter a series of values, say W-CNT (1), W-CNT (2), which are not formed by simple incrementing, write:

  

By experimenting with the VARYING clause, you will discover many novel and surprising uses.

Compatibility

The VARYING clause is unique to new Report Writer.