occurs clause

The OCCURS Clause Variable

In CobolScript, the OCCURS clause variable is a special type of variable, either elementary or group item, that defines arrays of each of its subvariables. The OCCURS clause syntax excels over other types of array definition syntax when defining record arrays; this is because arrays of records fit naturally within the syntax of an OCCURS clause group item definition.

The syntax of an OCCURS clause group item variable definition is:

<level-number> <variable-name> OCCURS <n> TIMES.

<elementary-item-definition> or <group-item-definition>.

.

.

.

The syntax of an OCCURS clause elementary item variable definition is:

<level-number> <variable-name> OCCURS <n> TIMES PIC <picture-clause>

VALUE <value-literal>.

An OCCURS clause variable is defined the same way as its underlying form (elementary or group item), except for the OCCURS clause. This clause is initiated by the OCCURS keyword; in the case of the OCCURS group item, it indicates that the subvariables that comprise this group are recurring. In the case of the OCCURS elementary item, it indicates that this particular variable is recurring. In either case, the number of times the OCCURS variable(s) recur is indicated by a positive (strictly greater than zero) integer value n, which can either be a numeric literal or a numeric variable.

When referencing an OCCURS variable, you must use an index to indicate which of the recurring variables you mean. The index must be an integer with a value from 1 to n. So, if the OCCURS variable is defined using either of these forms:

1 occurs_variable OCCURS 10 TIMES.

5 component_1 PIC 99.

5 component_2.

10 component_2_1 PIC XX.

10 component_2_2 PIC 99.

or,

1 component_1 OCCURS 10 TIMES PIC 99.

Then, component_1 is a recurring variable (along with component_2 and its subvariables in the group item example), and its index can be any number or variable with an integer value from 1 to 10, inclusive. So, to reference the third OCCURS variable of component_1 in a statement, we would use the syntax:

component_1(3)

or, alternatively:

component_1(integer_variable)

where integer_variable is an integer numeric variable that is equal to 3 at the time it is referenced. We can also use the syntax:

component_1(expression)

where expression is any valid mathematical expression that evaluates to a positive integer, such as the following expression, which again assumes a value of 3 for integer_variable:

component_1(((2^2)+integer_variable)%3)

The group item component_2 and its two subvariables, component_2_1 and component_2_2, can be referenced the same way as component_1; thus, all of the following forms are permissible:

component_2(3)

component_2_1(3)

component_2_1(integer_variable)

component_2_2( ((2^2)+integer_variable)%3 )

Specifying a VALUE clause for an elementary item that recurs initializes all OCCURS elements to the value-literal. For example, in the gldi below, component_1(1) through component_1(5) will have initial values of 05, and component_2_1(1) through component_2_1(5) will have initial values of `me`. Specifying a value clause for an OCCURS elementary data item has the same net effect, as in the second OCCURS clause definition below:

1 occurs_variable OCCURS 10 TIMES.

5 component_1 PIC 99 VALUE 5.

5 component_2.

10 component_2_1 PIC XX VALUE `me`.

10 component_2_2 PIC 99.

or,

1 component_1 OCCURS 10 TIMES PIC 99 VALUE 5.

Ü

Note that CobolScript Standard Edition only permits single-level OCCURS clauses. In other words, two-dimensional and higher arrays are not supported by the Standard Edition. This means that an OCCURS clause gldi that has any OCCURS clause subvariables is not permitted in the Standard Edition. See below for an explanation of multidimensional array usage in CobolScript Professional Edition.

Multidimensional Arrays Using CobolScript Professional

If you are programming with CobolScript Professional Edition, you can define OCCURS clause variables that contain other OCCURS clause subvariables. This type of variable is also known as a multidimensional array because its individual elements comprise an array that has more than one index argument, or dimension. Let’s take a look at a basic multidimensional array definition using CobolScript Professional:

1 day_of_week OCCURS 7 TIMES.

5 hour_of_day OCCURS 24 TIMES.

10 fahr_temp PIC ---9 VALUE –300.

10 barom_pressure PIC 99.99 VALUE 0.

In the definition above, 168 total instances of the fahr_temp and barom_pressure variables are created and initialized. Each elemental variable corresponds to a temperature and barometric pressure reading for a specific hour of the day on a specific day of the week. The value in a specific element is referenced using a two-argument array reference with the dimensions separated by commas, as in the following statement:

DISPLAY fahr_temp(1, 13).

This statement corresponds to displaying the temperature value for 1:00 PM on Sunday, assuming Sunday is treated as the first day of the week.

The same range of argument syntax is permissible in multidimensional arrays as in one-dimensional arrays, so that the following are all valid references, assuming var_idx1 and var_idx2 are both properly defined:

fahr_temp(7, var_idx2)

hour_of_day(6+1, var_idx2)

barom_pressure(var_idx1, var_idx2)

fahr_temp(var_idx1+1, var_idx2-1)

Additional array dimensions are declared using additional nested OCCURS clauses:

1 a OCCURS occurs_num TIMES.

5 b PIC X VALUE `b`.

5 c.

10 d PIC 9 VALUE 1.

10 e PIC XX VALUE `ee`.

5 f OCCURS 2 TIMES PIC XX VALUE `ff`.

5 g OCCURS 3 TIMES.

10 h PIC XX VALUE `hh`.

10 i OCCURS 4 TIMES.

20 j PIC X VALUE `j`.

20 k PIC X VALUE `k`.

20 l OCCURS 2 TIMES PIC XX VALUE `ll`.

20 m OCCURS 2 TIMES.

30 n PIC X VALUE `n`.

Referencing syntax for variables with more than two dimensions is just an extension of the two dimension case, with additional commas separating the additional array dimensions:

MOVE `p` TO n(1,2,3,1).

DISPLAY `n(1,2,3,1) after move = ` & n(1, 1+1, occurs_num-1, 1).

There is no technical limit to the number of array dimensions that can be used in CobolScript Professional; however, the limit on the number of variables that may be declared in a single program creates a practical upper bound on the number of array dimensions. At any rate, careful programming will rarely warrant the use of more than three dimensions. Although exceptions may apply in certain mathematical programming cases, and in cases involving intentional denormalizing of data constructs, very large dimension arrays should generally be avoided in order to keep your programs comprehensible.