ASA Programming Guide
Embedded SQL Programming
The SQL descriptor area (SQLDA)
Each sqlvar structure in the SQLDA describes a host variable. The fields of the sqlvar structure have the following meanings:
sqltype The type of the variable that is described by this descriptor (see Embedded SQL data types).
The low order bit indicates whether NULL values are allowed. Valid types and constant definitions can be found in the sqldef.h header file.
This field is filled by the DESCRIBE statement. You can set this field to any type when supplying data to the database server or retrieving data from the database server. Any necessary type conversion is done automatically.
sqllen The length of the variable. What the length actually means depends upon the type information and how the SQLDA is being used.
For DECIMAL types, this field is divided into two 1-byte fields. The high byte is the precision and the low byte is the scale. The precision is the total number of digits. The scale is the number of digits that appear after the decimal point.
For LONG VARCHAR and LONG BINARY data types, the array_len field of the DT_LONGBINARY and DT_LONGVARCHAR data type structure is used instead of the sqllen field.
For more information on the length field, see SQLDA sqllen field values.
sqldata A four-byte pointer to the memory occupied by this variable. This memory must correspond to the sqltype and sqllen fields.
For storage formats, see Embedded SQL data types.
For UPDATE and INSERT commands, this variable is not involved in the operation if the sqldata pointer is a null pointer. For a FETCH, no data is returned if the sqldata pointer is a null pointer. In other words, the column returned by the sqldata pointer is an unbound column.
If the DESCRIBE statement uses LONG NAMES, this field holds the long name of the result set column. If, in addition, the DESCRIBE statement is a DESCRIBE USER TYPES statement, then this field holds the long name of the user-defined data type, instead of the column. If the type is a base type, the field is empty.
sqlind A pointer to the indicator value. An indicator value is a short int. A negative indicator value indicates a NULL value. A positive indicator value indicates that this variable has been truncated by a FETCH statement, and the indicator value contains the length of the data before truncation. A value of -2 indicates a conversion error if the CONVERSION_ERROR database option is set to OFF.
For more information, see Indicator variables.
If the sqlind pointer is the null pointer, no indicator variable pertains to this host variable.
The sqlind field is also used by the DESCRIBE statement to indicate parameter types. If the type is a user-defined data type, this field is set to DT_HAS_USERTYPE_INFO. In such a case, you may wish to carry out a DESCRIBE USER TYPES to obtain information on the user-defined data types.
sqlname A VARCHAR-like structure, as follows:
struct sqlname {
short int length;
char data[ SQL_MAX_NAME_LEN ];
};It is filled by a DESCRIBE statement and is not otherwise used. This field has a different meaning for the two formats of the DESCRIBE statement:
SELECT LIST The name buffer is filled with the column heading of the corresponding item in the select list.
BIND VARIABLES The name buffer is filled with the name of the host variable that was used as a bind variable, or "?" if an unnamed parameter marker is used.
On a DESCRIBE SELECT LIST command, any indicator variables present are filled with a flag indicating whether the select list item is updatable or not. More information on this flag can be found in the sqldef.h header file.
If the DESCRIBE statement is a DESCRIBE USER TYPES statement, then this field holds the long name of the user-defined data type instead of the column. If the type is a base type, the field is empty.