HP OpenVMS Systems Documentation

HP COBOL
User Manual

HP COBOL allows 48 levels of OCCURS nesting. If you want to define a two-dimensional table, you define another one-dimensional table within each element of the one-dimensional table. To define a three-dimensional table, you define another one-dimensional table within each element of the two-dimensional table, and so on.

A two-dimensional table is shown in Example 4-4.

01  2D-TABLE-X.
    05  LAYER-Y OCCURS 2 TIMES.
        10  LAYER-Z OCCURS 2 TIMES.
            15  CELLA PIC X.
            15  CELLB PIC X.

The organization of this two-dimensional table is shown in Figure 4-4.

Figure 4-4 Organization of a Two-Dimensional Table

Example 4-5 shows a three-dimensional table.

01 TABLE-A.
    05  LAYER-B OCCURS 2 TIMES.
        10  ITEMC PIC X.
        10  ITEMD PIC X OCCURS 3 TIMES.
        10  ITEME OCCURS 2 TIMES.
            15  CELLF PIC X.
            15  CELLG PIC X OCCURS 3 TIMES.

The organization of this three-dimensional table is shown in Figure 4-5.

Figure 4-5 Organization of a Three-Dimensional Table

To define a variable-length table, use Format 2 of the OCCURS clause (refer to the HP COBOL Reference Manual). Options allow you to define single or multiple keys, or indexes, or both.

Example 4-6 illustrates how to define a variable-length table.

It uses from two to four occurrences depending on the integer value assigned to NUM-ELEM. You specify the table's minimum and maximum size with the OCCURS (minimum size) TO (maximum size) clause. The minimum size value must be equal to or greater than zero and the maximum size value must be greater than the minimum size value. The DEPENDING ON clause is also required when you use the TO clause.

The data-name of an elementary, unsigned integer data item is specified in the DEPENDING ON clause. Its value specifies the current number of occurrences. The data-name in the DEPENDING ON clause must be within the minimum to maximum range.

Unlike fixed-length tables, you can dynamically alter the number of element occurrences in variable-length tables.

By generating the variable-length table in Example 4-6, you are, in effect, saying: "Build a table that can contain at least two occurrences, but no more than four occurrences, and set its present number of occurrences equal to the value specified by NUM-ELEM."

01  NUM-ELEM PIC 9.
       .
       .
       .
01  VAR-LEN-TABLE.
    05  TAB-ELEM OCCURS 2 TO 4 TIMES DEPENDING ON NUM-ELEM.
        10 A PIC X.
        10 B PIC X.

The compiler maps the table elements into memory, following mapping rules that depend on the use of COMP, COMP-1, COMP-2, POINTER, and INDEX data items in the table element, the presence or absence of the SYNCHRONIZED (SYNC) clause with those data items, and the -align flag (on the Tru64 UNIX operating system) or the /ALIGNMENT qualifier (on the OpenVMS Alpha and I64 operating systems).

The HP COBOL compiler allocates storage for data items within records according to the rules of the Major-Minor Equivalence technique. This technique ensures that identically defined group items have the same structure, even when their subordinate items are aligned. Therefore, group moves always produce predictable results. For more information, refer to the description of record allocation in the HP COBOL Reference Manual.

Example 4-7 shows how to describe a sample record in a table.

01 TABLE-A.
    03 GROUP-G PIC X(5) OCCURS 5 TIMES.

Figure 4-6 shows how the table defined in Example 4-7 is mapped into memory.

Figure 4-6 Memory Map for Sample Record Description Example

Alphanumeric data items require 1 byte of storage per character. Therefore, each occurrence of GROUP-G occupies 5 bytes. The first byte of the first element is automatically aligned at the left record boundary and the first 5 bytes occupy all of word 1 and part of 2. A memory longword is composed of 4 bytes. Succeeding occurrences of GROUP-G are assigned to the next 5 adjacent bytes so that TABLE-A is composed of five 5-byte elements for a total of 25 bytes. Each table element, after the first, is allowed to start in any byte of a word with no regard for word boundaries.

4.1.4.1 Using the SYNCHRONIZED Clause

By default, the HP COBOL compiler tries to allocate a data item at the next unassigned byte location. However, you can align some data items on a 2-, 4-, or 8-byte boundary by using the SYNCHRONIZED clause. The compiler may then have to skip one or more bytes before assigning a location to the next data item. The skipped bytes, called fill bytes, are gaps between one data item and the next.

The SYNCHRONIZED clause explicitly aligns COMP, COMP-1, COMP-2, POINTER, and INDEX data items on their natural boundaries: one-word COMP items on 2-byte boundaries, longword items on 4-byte boundaries, and quadword items on 8-byte boundaries. Thus the use of SYNC can have a significant effect on the amount of memory required to store tables containing COMP and COMP SYNC data items.

Example 4-8 describes a table containing a COMP SYNC data item. Figure 4-7 illustrates how it is mapped into memory.

01 A-TABLE.
   03 GROUP-G OCCURS 4 TIMES.
      05 ITEM1 PIC X.
      05 ITEM2 PIC S9(5) COMP SYNC.

Figure 4-7 Memory Map for Record Description Containing a COMP SYNC Item

Because a 5-digit COMP SYNC item requires one longword (or 4 bytes) of storage, ITEM2 must start on a longword boundary. This requires the addition of 3 fill bytes after ITEM1, and each GROUP-G occupies 8 bytes. In Example 4-8, A-TABLE requires 32 bytes to store four elements of 8 bytes each.

If, in the previous example, you define ITEM2 as a COMP data item of the same size without the SYNC clause, the storage required will be considerably less. Although ITEM2 will still require one longword of storage, it will be aligned on a byte boundary. No fill bytes will be needed between ITEM1 and ITEM2, and A-TABLE will require a total of 20 bytes.

If you now add a 3-byte alphanumeric item (ITEM3) to Example 4-8 and locate it between ITEM1 and ITEM2 (see Example 4-9), the new item occupies the space formerly occupied by the 3 fill bytes. This adds 3 data bytes without changing the table size, as Figure 4-8 illustrates.

01 A-TABLE.
   03 GROUP-G OCCURS 4 TIMES.
      05 ITEM1 PIC X.
      05 ITEM3 PIC XXX.
      05 ITEM2 PIC 9(5) COMP SYNC.

Figure 4-8 Memory Map for Example on Adding an Item Without Changing the Table Size

If, however, you place ITEM3 after ITEM2, the additional 3 bytes add their own length plus another fill byte. The additional fill byte is added after the third ITEM3 character to ensure that all occurrences of the table element are mapped in an identical manner. Now, each element requires 12 bytes, and the complete table occupies 48 bytes. This is illustrated by Example 4-10 and Figure 4-9.

01 A-TABLE.
   03 GROUP-G OCCURS 4 TIMES.
      05 ITEM1 PIC X.
      05 ITEM2 PIC 9(5) COMP SYNC.
      05 ITEM3 PIC XXX.

Note that GROUP-G begins on a 4-byte boundary because of the way HP COBOL allocates memory.

Figure 4-9 Memory Map for Example on How Adding 3 Bytes Adds 4 Bytes to the Element Length