Group data items are items that themselves contain items. They are used to name a collection of related items. Group data items can contain only data items and other group items.

Group items are aligned on an 8-bit byte boundary.

The following diagrams illustrate the syntax for group items:

<group data item>

──<group item name>─┬───────────┬─ GROUP ─┬────────────────────────┬────►
                    └─<comment>─┘         ├─ <encryption clause> ──┤                                                         ├─ <occurs clause> ──────┤
                                          ├─ REQUIRED ─────────────┤
                                          └─ <stored clause> ──────┘
        ┌◄─────── ; ───────┐
►─  (  ─┴─┬─<data item>──┬─┴─┬─────┬─  )  ─────────────────────────────►
          └─<group item>─┘   └─ ; ─┘

►─┬───────────────────────┬────────────────────────────────────────────┤
  ├─<encryption clause> ──┤
  ├─<occurs clause> ──────┤
  ├─ REQUIRED ────────────┤
  └─<stored clause> ──────┘

<encryption clause>

 ─/1\─ DATAENCRYPT ─────┬────────────────────────────┬────────────────┤     
                        └─ = ─┬─ FALSE ──────────────┤      
                              └─ TRUE ───────────────┘                          

<occurs clause>

── OCCURS <unsigned integer> ─┬─────────┬──────────────────────────────►
                              └─ TIMES ─┘

►─┬──────────────────────────────────────┬─────────────────────────────┤
  └─ DEPENDING ON ─┬─<numeric item name>─┤
                   └─<real item name>────┘

<stored clause>

── STORED ── DEPENDING ON ─┬─<Boolean item name>─┬─────────────────────┤
                           └─<field bit name>────┘

The elements of the syntax diagrams are explained in the following text.

Group Item Name

A group item name is an identifier that names the item. The group item name cannot exceed 30 characters.

DATAENCRYPT Option

The DATAENCRYPT option enables you to encrypt a group item within an Enterprise Database Server database. This prevents any kind of tool that can read files from a disk from accessing the data in clear text.

If a record contains an item with the DATAENCRYPT option set, its record size is larger than normal due to the encryption algorithm.

You can only specify the DATAENCRYPT option for an entire group; you cannot specify the DATAENCRYPT option for individual items within a group. When the DATAENCRYPT option is set for a group, each item within the group is encyrypted.

If there are any items with the DATAENCRYPT option in the data set, these items will be encrypted and moved to the end of the record. This is done to maximize the performance and minimize the disk usage. The record size will be increased and the size will depend on the encryption algorithm specified. The encrypted data will always be different in each record even if the records contain the same original (unencrypted) value.

If there are any Filler data items along with the items with DATAENCRYPT option in the data set, the Filler in the record is located after all non-encrypted data items and encrypted data items. When substituting a filler item with new data items type, a reorganization is required.

A reorganization must be performed when changing the DATAENCRYPT option from TRUE to FALSE or FALSE to TRUE.

The key items in a set or subset can have the DATAENCRYPT option specified but not the key items in an Access. The key data cannot contain encrypted data items. For more information about using the DATAENCRYPT option with key items, refer to Sets, Subsets, and Accesses.

Occurs Clause

The occurs clause is used to establish an ordered collection of items, all of which have identical attributes. The unsigned integer following the OCCURS keyword controls the number of times the group item is repeated. The value of the unsigned integer must not exceed 1023. Whenever an item within the occurs clause is referenced, its name must be followed by a subscript enclosed within parentheses. Valid subscripts range from 1 to the value of the unsigned integer. Only one occurs clause can be specified for each data item.

Items declared within an occurs clause must not specify NULL, REQUIRED, SIZE, or STORED. Group items using the occurs clause must not be keys, key data, or the object of the VERIFY ON clause for verified links.

The following two forms of the occurs clause are provided:

When the DEPENDING ON clause does not appear, the amount of space the group item occupies is fixed. Space is allocated for each occurrence, whether it contains a value. For example: X DATA SET~ (~ A ALPHA(3) REQUIRED;~ G GROUP~ (~ G1 ALPHA(5) INITIALVALUE BLANKS;~ G2 BOOLEAN;~ ) OCCURS 10 TIMES;~ );

The DEPENDING ON clause is used to conserve disk space. The user work area always contains a fully expanded version of the record. However, the record is compacted when it is stored on disk.

The item following DEPENDING ON controls the number of occurrences of the group item which is stored. Extra processor time is required to compact the record when it is stored and to expand the record when it is retrieved.

DEPENDING ON can only be used with group items declared in compact data sets.

When a record is created, the occurring group item and the numeric item following DEPENDING ON are initialized normally. When the record is stored, the value of the numeric item following DEPENDING ON is examined. The number of occurrences stored on disk is the number contained in the numeric item or the maximum defined by DASDL, whichever is smaller. If N occurrences are to be stored, the first N occurrences of the group item are moved to the system buffer and then to disk. If the value of the numeric item is 0 (zero), no occurrences are stored. When a record is retrieved, the occurrences stored on disk are moved to the user work area, and the remaining occurrences in the user work area are initialized to HIGH-VALUE.

No data compaction results if OCCURS DEPENDING ON is used outside compact data sets or in remaps. COBOL programs use the depending item for index checking. For example:

D COMPACT DATA SET
 (
  N NUMBER(3);
  A GROUP
    (
     F FIELD(15);
     R REAL;
    ) OCCURS 100 TIMES DEPENDING ON N;
  );

If N contains the value 30, the first 30 occurrences of A are stored on disk. The remaining 70 occurrences are not stored and contain the null value (all bits on).

The item following DEPENDING ON must be a nonsubscripted numeric item or real item with no fractional part. It must contain a positive integer. The system automatically makes the item required. The item can be used as a record key.

Several items using the OCCURS or SIZE options can depend on a single numeric item. The declaration of the numeric item must precede the declaration of the occurring group item on which it depends. However, the item declarations need not be adjacent. For example:

D COMPACT DATA SET
  (
   N NUMBER(3);
   A ALPHA(100) SIZE DEPENDING ON N;
   B BOOLEAN OCCURS 100 TIMES DEPENDING ON N;
   G GROUP
    (
     X REAL(S5,2);
     Y ALPHA(15);
    ) OCCURS 100 TIMES DEPENDING ON N;
   );

Occurring group items can contain data items and group items which themselves include the occurs clause. Whenever an item within an occurring group item is referenced, its name must be followed by one or more subscripts enclosed within parentheses.

The number of subscripts specified must match the number of occurs clauses which apply to the item. The first (leftmost) subscript in a subscript list applies to the outermost occurs clause, the second subscript applies to the next to outermost occurs clause, and so on.

Example

In the following data set declaration there are two occurrences of A:

A(1)   A(2)

There are six occurrences of B:

B(1,1)   B(1,2)   B(1,3)
B(2,1)   B(2,2)   B(2,3)

There are 24 occurrences of C:

C(1,1,1)   C(1,1,2)   C(1,1,3)   C(1,1,4)
C(1,2,1)   C(1,2,2)   C(1,2,3)   C(1,2,4)
C(1,3,1)   C(1,3,2)   C(1,3,3)   C(1,3,4)
C(2,1,1)   C(2,1,2)   C(2,1,3)   C(2,1,4)
C(2,2,1)   C(2,2,2)   C(2,2,3)   C(2,2,4)
C(2,3,1)   C(2,3,2)   C(2,3,3)   C(2,3,4)

X DATA SET
 (
  N NUMBER(3);
  G GROUP
   (
    A ALPHA(20);
    H GROUP
     (
      B ALPHA(5);
      C ALPHA(10) OCCURS 4 TIMES;
     ) OCCURS 3 TIMES;
    ) OCCURS 2 TIMES;
 );

REQUIRED Keyword

The database administrator can ensure that the items within a group are assigned a value using the REQUIRED keyword. Specifying REQUIRED for the group is equivalent to specifying REQUIRED for each item within the group for which REQUIRED is valid. Items declared within a required group must not specify occurs or stored clauses.

Stored Clause

The stored clause is used to conserve disk space. The user work area always contains a fully expanded version of the record; however, the record is compacted when it is stored on disk. The system automatically compacts records by eliminating group items which the user indicates should not be stored. The user controls whether the group item is stored on disk by assigning a value to the Boolean item following DEPENDING ON. Extra processor time is required to compact the record when it is stored and to expand the record when it is retrieved.

Group items which include the stored clause cannot be keys, key data, or the object of the VERIFY ON clause for verified links. The REQUIRED option must not be specified for stored items. The stored clause can be used only with items declared in compact data sets.

Both the items in the group and the Boolean item are initialized normally when the record is created. When the record is stored, the value of the Boolean item is examined. This value controls whether the group item is stored. The system does not examine the contents of the group item; only the value of the Boolean item is significant. If the value of the Boolean item is TRUE, the contents of the group item are moved to the system buffer and then to disk. If the Boolean item contains the value FALSE, the group item is not stored. When the record is retrieved, the group items stored on disk are moved to the user work area, and the remaining group items are assigned HIGH-VALUE.

Items declared within a stored group must not specify NULL, REQUIRED, SIZE, or STORED.

The item following DEPENDING ON must be a nonsubscripted Boolean item or field bit name. If several Boolean items are required, a field item is normally used to conserve space. Several items using the STORED DEPENDING ON option can depend upon a single Boolean item. The declaration of the Boolean item must precede the declaration of the group item, but need not be adjacent to it. For example:

C COMPACT DATA SET
 (
  B BOOLEAN INITIALVALUE TRUE;
  G GROUP
   (
    A ALPHA(10);
    R REAL;
   ) STORED DEPENDING ON B;
  F FIELD(10) STORED DEPENDING ON B;
 );

Examples That Illustrate the Group Data Items

Example 1

The following example uses a group item identified as G:

D DATA SET
 (
  A ALPHA(10);
  G GROUP
   (
    N NUMBER(S5,2);
    B BOOLEAN OCCURS 10 TIMES;
   );
  R REAL;
 );

Example 2

The following example uses a group item identified as NAME GROUP:

MAILING-LIST DATA SET
 (
  NAME GROUP
   (
    FIRST-NAME  ALPHA(15);
    MIDDLE-NAME ALPHA(1);
    LAST-NAME   ALPHA(20);
   );
  MAIL-ADDRESS GROUP
   (
    SUBSIDIARY ALPHA(20);
    LOCATION GROUP
     (
      BLDG ALPHA(4);
      DEPT ALPHA(4);
      ROOM FIELD(12);
     );
   );
 );