Initialize the sqlda structure

To send or receive column values in the database, your program must initialize the sqlda structure so that it describes the unknown columns of the prepared statement.

To initialize the sqlda structure, you must perform the following steps:
  • Set the sqlvar field to the address of the initialized sqlvar_struct structures.
  • Set the sqld field to indicate the number of unknown columns (and associated sqlvar_struct structures).

In addition to allocating memory for the sqlda structure (see Allocate memory for the sqlda structure), the DESCRIBE...INTO statement also initializes this structure with information about the prepared statement. The information that DESCRIBE...INTO can provide depends on which SQL statement it has described.

If the prepared statement is a SELECT (with no INTO TEMP clause), INSERT, or EXECUTE FUNCTION statement, the DESCRIBE...INTO statement can determine information about columns in the column list. Therefore, the DESCRIBE...INTO statement takes the following actions to initialize an sqlda structure:
  • It allocates memory for the sqlda structure. For more information, see Allocate memory for the sqlda structure.
  • It sets the sqlda.sqld field, which contains the number of sqlvar_struct structures initialized with data. This value is the number of columns and expressions in the column list (SELECT and INSERT) or the number of returned values (EXECUTE FUNCTION).
  • It allocates memory for component sqlvar_struct structures, one sqlvar_struct structure for each column or expression in the column list (SELECT and INSERT) or for each of the returned values (EXECUTE FUNCTION).
  • It sets the sqlda.sqlvar field to the initial address of the memory that DESCRIBE allocates for the sqlvar_struct structures.
  • It describes each unknown column in the prepared SELECT (without an INTO TEMP), EXECUTE FUNCTION, or INSERT statement. The DESCRIBE...INTO statement initializes the fields of the sqlvar_struct structure for each column, as follows:
    • It initializes the sqltype, sqllen, and sqlname fields (for CHAR type data or for the qualifier of DATETIME or INTERVAL data) to provide information from the database about the column.

      For most data types, the sqllen field holds the length, in bytes, of the column. If the column is a collection type (SET, MULTISET, or LIST), a row type (named or unnamed), or an opaque type, the sqllen field is zero.

    • It initializes the sqldata and sqlind fields to null.

    For descriptions of these fields, see Fields in the sqlvar_struct structure.

Important: Unlike with a system-descriptor area, DESCRIBE with an sqlda pointer does not allocate memory for the column data (the sqldata fields). Before your program receives column values from the database server, it must allocate this data space.

For more information, see Allocate memory for column data.

The DESCRIBE statement provides information about the columns of a column list. Therefore, you usually use DESCRIBE...INTO after a SELECT (without an INTO TEMP clause), INSERT, or EXECUTE FUNCTION statement was prepared. The DESCRIBE...INTO statement not only initializes the sqlda structure, but also returns the type of SQL statement prepared. For more information, see Determine the statement type.

The following DESCRIBE statement also allocates memory for an sqlda structure and for two sqlvar_struct data structures (one for the customer_num column and another for the company column) and then initializes the pointer da_ptr->sqlvar with the initial address of the memory that is allocated to the sqlvar_struct structure: 
EXEC SQL prepare st_id 
   'select customer_num, company from customer 
   where customer_num = ?';
EXEC SQL describe st_id into da_ptr;

The preceding DESCRIBE...INTO statement returns an SQLCODE value of 0 to indicate that the prepared statement was a SELECT statement.

The following figure shows a sample sqlda structure that this DESCRIBE...INTO statement might initialize.
Figure 1: Sample sqlda Structure for Two Columns


If some other SQL statement was prepared, the DESCRIBE...INTO statement cannot initialize the sqlda structure. To send or receive column values in the database, your program must perform this initialization explicitly, as follows:
  • Allocate memory for component sqlvar_struct structures, one sqlvar_struct structure for each column.
    You can use system memory-allocation functions such as malloc() or calloc() and assign the address to sqlvar, as follows: 
    da_ptr->sqlvar = (struct sqlvar_struct *)
   calloc(count, sizeof(struct sqlvar_struct));
  • Perform the following tasks to describe each unknown column:
    • Set the sqlda.sqld field, which contains the number of sqlvar_struct structures initialized with data. This value is the number of unknown columns in the prepared statement.
    • Initialize the fields of each sqlvar_struct structure.

      Set the sqltype, sqllen, and sqlname fields (for CHAR type data or for the qualifier for DATETIME or INTERVAL data) to provide information about a column to the database server.

    To provide the column data, your program must also allocate space for this data and set the sqldata field of each sqlvar_struct structure to the appropriate location within this space. For more information, see Allocate memory for column data. If you send column data to the database server, be sure to set the sqlind field appropriately.

If you use the sqlda structure to define input parameters, you cannot use a DESCRIBE statement to initialize the sqlda structure. Your code must explicitly set the appropriate fields of the sqlda structure to define the input parameters. (See Specify input parameter values.)