Host structures in PL/I, C, and COBOL

A host structure is a PL/I structure, C structure, or COBOL group that is referred to in an SQL statement.

Host structures are defined by statements of the host language, as explained in Overview of programming applications that access DB2® for z/OS® data. As used here, the term host structure does not include an SQLCA or SQLDA.

In Java and REXX, there is no equivalent to a 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 names a host structure. If S1 designates a host structure, S2 must be a small integer variable or an array of small integer variables. S1 is the host structure and S2 is its indicator array.

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

In PL/I, for example, if V1, V2, and V3 are declared as the variables within the structure S1, the following two statements are equivalent:

   EXEC SQL FETCH CURSOR1 INTO :S1;
   EXEC SQL FETCH CURSOR1 INTO :V1, :V2, :V3;

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

In addition to structure references, individual host variables or indicator variables in PL/I, C, and COBOL can be referred to by qualified names. The qualified form is a host identifier followed by a period and another host identifier. The first host identifier must name a structure, and the second host identifier must name a host variable at the next level within that structure.

In PL/I, C, and COBOL, the syntax of host-variable is:


>>-:-+------------------+-host-identifier----------------------->
     '-host-identifier.-'                   

>--+------------------------------------------------------+----><
   | .-INDICATOR-.                                        |   
   '-+-----------+-:-+------------------+-host-identifier-'   
                     '-host-identifier.-'

In general, a host-variable in an expression must identify a host variable (not a structure) described in the program according to the rules for declaring host variables. However, there are a few SQL statements that allow a host variable in an expression to identify a structure, as specifically noted in the descriptions of the statements.

The following examples show references to host variables and host structures:

  :V1   :S1.V1   :S1.V1:V2   :S1.V2:S2.V4