Host structure support in the declare section of C and C++ embedded SQL applications

A host structure contains a list of host variables that can be referred to by embedded SQL statements. With host structure support, the C or C++ precompiler allows host variables to be grouped into a single host structure.

Host structure support provides a shorthand for referencing that same set of host variables in an SQL statement.

For example, the following host structure can be used to access some of the columns in the STAFF table of the SAMPLE database:

   struct tag
      {
        short id;
        struct
        {
          short length;
          char  data[10];
        } name;
        struct
        {
          short   years;
          double salary;
        } info;
      } staff_record;

The fields of a host structure can be any of the valid host variable types. Valid types include all numeric, character, and large object types. Nested host structures are also supported up to 25 levels. In the example shown previously, the field info is a sub-structure, whereas the field name is not, as it represents a VARCHAR field. The same principle applies to LONG VARCHAR, VARGRAPHIC and LONG VARGRAPHIC. Pointer to host structure is only supported when it is not nested within another structure.

There are two ways to reference the host variables grouped in a host structure in an SQL statement:

The host structure name can be referenced in an SQL statement.
```
   EXEC SQL SELECT id, name, years, salary
        INTO :staff_record
        FROM staff
        WHERE id = 10;
```
The precompiler converts the reference to staff_record into a list, separated by commas, of all the fields declared within the host structure. Each field is qualified with the host structure names of all levels to prevent naming conflicts with other host variables or fields. This is equivalent to the following method.
Fully qualified host variable names can be referenced in an SQL statement.
```
   EXEC SQL SELECT id, name, years, salary
        INTO :staff_record.id, :staff_record.name, 
             :staff_record.info.years, :staff_record.info.salary
        FROM staff
        WHERE id = 10;
```
References to field names must be fully qualified, even if there are no other host variables with the same name. Qualified sub-structures can also be referenced. In the preceding example, :staff_record.info can be used to replace :staff_record.info.years, :staff_record.info.salary.

Because a reference to a host structure (first example) is equivalent to a comma-separated list of its fields, there are instances where this type of reference might lead to an error. For example:

   EXEC SQL DELETE FROM :staff_record;

Here, the DELETE statement expects a single character-based host variable. By giving a host structure instead, the statement results in a precompile-time error:

   SQL0087N  Host variable "staff_record" is a structure used where structure 
   references are not permitted.

Other uses of host structures, which can cause an SQL0087N error to occur, include PREPARE, EXECUTE IMMEDIATE, CALL, indicator variables and SQLDA references. Host structures with exactly one field are permitted in such situations, as are references to individual fields (second example).