Repeated fields: the OCCURS option

The OCCURS option specifies that the indicated number of entries for the field are to be generated in a map, and that the map definition is to be generated in such a way that the fields are addressable as entries in a matrix or an array.

About this task

Sometimes a screen contains a series of identical fields that you want to treat as an array in your program. Suppose, for example, that you need to create a display of 40 numbers, to be used when a clerk assigns an unused telephone number to a new customer. (The idea is to give the customer some choice.) You also want to highlight numbers which have been in service recently, to warn the customer of the possibility of calls to the previous owner.

You can define the part of your screen which shows the telephone numbers with a single field definition:

TELNO    DFHMDF POS=(7,1),LENGTH=9,ATTRB=NORM,OCCURS=40

This statement generates 40 contiguous but separate display fields, starting at position (7,1) and proceeding across the rows for as many rows as required (five, in our case). We have chosen a length that (with the addition of the attributes byte) divides the screen width evenly, so that our numbers appear in vertical columns and are not split across row boundaries. The attributes you specify, and the initial value as well, apply to each field.

The description of these fields in the symbolic map looks like this in COBOL:

       02 TELNOG    OCCURS 40.
          03 FILLER PICTURE X(2).
          03 TELNOA    PICTURE X.
          03 TELNOO  PIC X(9).

This structure lets you fill the map from an array in your program (or any other source) as follows:

           PERFORM MOVENO FOR I FROM 1 THROUGH 40.
           ...
       MOVENO.
           MOVE AVAIL-NO (I) TO TELNOO (I).
           IF DAYS-SINCE-USE (I) < 90, MOVE DFHBMBRY to TELNOA (I).

(DFHBMBRY is a CICS®-supplied constant for setting the field intensity to bright; we explain more in Attribute value definitions: DFHBMSCA.)

Labels for OCCURS fields vary slightly for the different languages that CICS supports, but the function is the same.

Each element of an array created by the OCCURS option is a single map field. If you need to repeat a series of fields (an array of structures, in other words), you cannot use OCCURS. To use such an array in a program, you must define all the fields individually, without OCCURS, to produce the necessary physical map. Then you can modify the resulting symbolic map, replacing the individual field definitions with an array whose elements are the structure you need to repeat. You must ensure that the revised symbolic map has the same field structure as the original. An alternative is to use SDF II, which allows you to define such an array directly.