INFORMIX-ESQL/C Programmer's Manual Determining SQL Statements

If you do not know the number or data types of values sent to or received from the database server, use a dynamic-management structure. A dynamic-management structure allows you to pass a variable-length list of data to the database server, or receive a variable-length list of data from it.

To execute dynamic SQL statements with unknown columns, you can use either of the following dynamic-management structures in your ESQL/C program:

• A system-descriptor area is a language-independent data structure that is the X/Open standard. You allocate and manipulate it with the SQL statements ALLOCATE DESCRIPTOR, GET DESCRIPTOR, SET DESCRIPTOR, and DEALLOCATE DESCRIPTOR.
• The sqlda structure is a C-language data structure that you manipulate with the same types of C-language statements that you would use to allocate and manipulate other C structures (areas that have the struct data type).

Because this method uses a C-language structure within SQL statements, it is language-dependent and does not conform to X/Open standards.

For a given dynamic SQL statement, the dynamic-management structure can hold any of the following information:

• The number of unknown columns in the statement
• For each unknown value, the data type and length, space for the data, and information about any associated indicator variable (its data type, length, and data)

The ESQL/C program can then use this information to determine a host variable of appropriate length and type to hold the value.

A system-descriptor area is an area of memory declared by ESQL/C to hold data either returned from or sent by a prepared statement. It is the dynamic-management structure that conforms to the X/Open standards.

A system-descriptor area has two parts:

• A fixed-size portion is made up of the COUNT field. This field contains the number of columns described in the system-descriptor area.
• A variable-length portion contains an item descriptor for each value in the system-descriptor area. Each item descriptor is a fixed-size structure.

Figure 15-1 shows what a system-descriptor area looks like for two values.

Figure 15-1 Schematic That Shows System-Descriptor Area for Two Values

Fixed-Length Portion

The fixed-size portion of the system-descriptor area consists of the single field, which Figure 15-2 shows.

An Item Descriptor

Each item descriptor in the system-descriptor area holds information about a data value that can be sent to or received from the database server. Each item descriptor consists of the fields that Figure 15-3 summarizes.

For information on how to use a system-descriptor area to dynamically execute SQL statements, see Chapter 16, Using a System-Descriptor Area.

The sqlda structure is a C structure (defined in the sqlda.h header file) that holds data returned from a prepared statement. Each sqlda structure has three parts:

• A fixed-size portion is made up of the sqld field, which contains the number of columns described in the sqlda structure.
• A variable-length portion contains an sqlvar_struct structure for each column value. Each sqlvar_struct structure is a fixed-size structure.
• Descriptive information is included about the sqlda structure itself. For more information, see Figure 15-8 on page 15-15.

Figure 15-4 shows what an sqlda structure looks like for two values.

Figure 15-4 Schematic That Shows sqlda Structure for Two Values

Figure 15-4 shows the column data in the sqldata fields in a single data buffer. This data can also be stored in separate buffers. For more information, see Allocating Memory for Column Data.

Figure 15-5 describes the fixed-size portion of the sqlda structure, which consists of a single field.

An sqlvar_struct Structure

When all of its components are fully defined, the sqlda structure points to the initial address of a sequence of sqlvar_struct structures that contain the necessary information for each variable in the set. Each sqlvar_struct structure holds a data value that can be sent to or received from the database server. Your program accesses these sqlvar_struct structures through the sqlvar field of sqlda. Figure 15-6 and Figure 15-7 on page 15-13 summarize the variable-sized structure of sqlda.

Figure 15-7 shows the fields in the sqlvar_struct structure.

Descriptive Information

Figure 15-8 summarizes the sqlda fields that describe the sqlda structure itself.

For information on how to use an sqlda structure to dynamically execute SQL statements, see Chapter 17, Using an sqlda Structure.