Host structures

A host structure is a COBOL group, PL/I, C, or C++ structure, or RPG data structure that is referenced in an SQL statement. In Java™ and REXX, there is no equivalent to a host structure.

Host structures are defined by statements of the host language, as explained in the Embedded SQL programming topic collection. As used here, the term host structure does not include an SQLCA or SQLDA.

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 either 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 referenced 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 C, for example, if V1, V2, and V3 are declared as variables within the structure S1, the statement:

   EXEC SQL FETCH CURSOR1 INTO :S1;

is equivalent to:

   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 if a reference to a host variable includes an indicator array. If an indicator array or indicator variable is not specified, no variable of the host structure has an indicator variable.

In addition to structure references, individual host variables in the host structure or indicator variables in the indicator array can be referenced 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 host structure, and the second host identifier must name a host variable within that host structure.

The general form of a host variable or host structure reference is:


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

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

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.

The following C example shows a references to host structure, host indicator array, and a host variable:

  struct { char empno[7];
                  struct           { short int firstname_len;
                                     char firstname_text[12];
                                   } firstname;
                  char midint,
                  struct           { short int lastname_len;
                                     char lastname_text[15];
                                   } lastname;
                  char workdept[4];
         } pemp1;
  short ind[14];
  short eind
  struct { short  ind1;
           short  ind2;
         } indstr;

    .....
  strcpy(pemp1.empno,"000220");
  .....
  EXEC SQL
    SELECT *
      INTO :pemp1:ind
      FROM corpdata.employee
      WHERE empno=:pemp1.empno;

In the example above, the following references to host variables and host structures are valid:

  :pemp1   :pemp1.empno   :pemp1.empno:eind   :pemp1.empno:indstr.ind1

For more information about how to refer to host structures in C, C++, COBOL, PL/I, and RPG, see the Embedded SQL programming topic collection.