Basic Language Elements › Host Variables › Host Structures

Host Structures

Host structures are allowed in COBOL and PL/I but not in Assembler.

You can qualify a host variable by a group name, for example:

:GROUPNAME.VARNAME

In this example, GROUPNAME is the host structure name and is used to qualify a host variable name. Host structure names may also be used in certain contexts to represent a list of the elementary items that they contain.

A host structure is a group whose subordinate levels are elementary data items. Host structures have a maximum of two levels, even though the structure could possibly itself occur within a multilevel structure. An exception is that the declaration of a varying-length character string variable requires another level, which must be level-49. In COBOL, for example:

 01 GROUPX.
     02 SUBGROUP.
         03 C1   PIC X(4).
         03 C2   PIC X(5).
         03 C3.
             49  C3LENGTH  PIC S9(4) COMP.
             49  C3STRING  PIC X(30).
         03 C4   PIC X(10).

In the previous example, SUBGROUP is a valid host structure, because there is only one level subordinate to it, except for the varying-length variable. GROUPX is not a valid host structure, because it has more than one level beneath it.

Specifying a host structure is a short-hand for specifying a list of the elementary items it contains. For example:

 EXEC SQL
 SELECT COL1, COL2, COL3, COL4
   INTO :SUBGROUP
   FROM TABLEX
 END-EXEC

Is equivalent to:

 EXEC SQL
 SELECT COL1, COL2, COL3, COL4
   INTO :SUBGROUP.C1, :SUBGRO.C2, :SUBGROUP.C3, :SUBGROUP.C4
   FROM TABLEX
 END-EXEC

The Preprocessor does this expansion whenever a host variable is specified which qualifies as a valid host structure.

The form of a host structure reference is identical to the form of a host variable reference. The reference :S1:S2 is a host structure reference if S1 designates a host structure. If S1 designates a host structure, S2 must be defined as a vector of small integer variables, as for example in COBOL:

     03 S2    PIC S9(4) COMP OCCURS 6 TIMES.

As just shown, S1 is the main structure and S2 is its indicator structure.

A host structure may be referenced in any context where a list of host variables may be referenced. A host structure reference is equivalent to a reference to each of the host variables contained within the structure in the order in which they are defined in the host language structure declaration. The nth variable of the indicator structure is the indicator variable for the nth variable of the main structure.

If the main structure has x more variables than the indicator structure, the last x variables of the main structure do not have indicator variables. If the main structure has x less variables than the indicator structure, the last x variables of the indicator structure are ignored. These rules also apply if a reference to a host structure includes an indicator variable (not a structure) or if a reference to a host variable (not a structure) includes an indicator structure. If an indicator structure or variable is not specified, no variable of the main structure has an indicator variable.