The SQL Reference Guide discusses the legal values of the sqlvar array. The describe and prepare into statements assign type, length, and name information into the SQLDA. This information refers to the result columns of a prepared select statement, the fields of a form, or the columns of a table field. When the program uses the SQLDA to retrieve or set Ingres data, it must assign the type and length information that now refers to the variables being pointed at by the SQLDA.

The type codes shown in SQLDA Structure Usage are the types that describe Ingres result fields and columns. For example, the SQL types long varchar, date, decimal and money do not describe a program variable, but rather data types that are compatible with the C types char and double. When these types are returned by the describe statement, the type code must be changed to a compatible C or SQL/C type.

The following table describes the type codes to use with C variables that will be pointed at by the sqldata pointers:

One-byte integer data types are specified as a char variable with no specified array dimension. Do not confuse this data type with string data types that are specified as a char variable with a fixed array dimension.

You can specify nullable data types (those variables that are associated with a null indicator) by assigning the negative of the type code to the sqltype field. If the type is negative, a null indicator must be pointed at by using the sqlind field.

As with regular embedded SQL statements, there are special rules for C character data. The describe statement returns IISQ_CHA_TYPE for fixed length character strings (char), IISQ_VCH_TYPE for varying length character strings (varchar),and IISQ_LVCH_TYPE for long strings (long varchar). For example, two columns of type char(5) and varchar(100) return types and lengths IISQ_CHA_TYPE:5 and IISQ_VCH_TYPE:100. The lengths specify the maximum lengths for both columns and do not include the C null terminator.

A column of type long varchar will return IISQ_LVCH_TYPE: 0. The length returned is zero because this character type may be of any size up to 2 gigabytes. Long varchar is an Ingres SQL datatype, so when using the SQLDA to retrieve or set data of a long varchar column into a host variable, IISQ_CHA_TYPE or IISQ_VCH_TYPE must be used. For information on how to specify user-defined data handlers for retrieving or setting large object data through the SQLDA, see Data Handlers and the SQLDA in this chapter.

When using the SQLDA to retrieve character data, the length you supply for fixed length C char variables must include the space for the null terminator. As with normal retrieval of character data, the data is copied (up to the specified length) and a null terminator is then added.

For example, the type specification:

assumes that 5 bytes of data can be copied, and that there is one extra byte for the null terminator, such as in the declaration:

If there are more than five bytes to copy, the data is truncated at five bytes and the null terminator is put into the sixth byte. If there are less than five bytes to copy, fewer bytes are copied and a null terminator is added. This rule is identical to the normal rule of character retrieval. The specified length must be at least 2 because one character and the terminating null are retrieved. If the length is exactly 1, data is overwritten.

If you may be retrieving character data with embedded nulls (such as binary streams of data), then you must use the embedded SQL/C varchar storage class. You can also use varchar variables to retrieve any character data even if there are no embedded nulls. The Dynamic SQL rules for retrieving into varchar variables are the same as the normal retrieval rules: the runtime system sets the 2-byte length field of the varchar data to the amount of data that was copied. The length specified in the sqllen field must be the size of the fixed length data buffer in the varchar variable.

For example, the type specification:

assumes that up to 100 bytes of data can be copied, such as in the declaration:

In the case of varchar, the data is not null-terminated.

You can also use the SQLDA to set Ingres data, as in the statements:

When setting character data using pointers to fixed C char data, the data must be null-terminated, and the length specified in sqllen is ignored. It is good programming style to set the length to zero. For example, the type specification:

can refer to the any C string value.

When setting character data using pointers to varchar variables, the sqllen must specify the size of the fixed size data array, and the 2-byte length field must specify the current length of data.

The describe statement may return any of the three binary types: IISQ_BYTE_TYPE, IISQ_VBYTE_TYPE or IISQ_LBYTE_TYPE. However, only IISQ_BYTE_TYPE AND IISQ_VBYTE_TYPE can be used when actually sending and retrieving data. The long byte data type must be changed to byte or varbyte if it is less than 32K, or else replaced by a data handler reference type.

In order to fill an element of the sqlvar array, you must set the type information and assign a valid address to sqldata. The address can be that of a dynamically allocated data area or a legal variable address. The address should always be cast to a pointer to a character (char *), as that is the base type of the sqldata field.

For example, the following fragment sets the type information and points at a dynamically allocated 4-byte integer and an 8-byte nullable floating-point variable.

You can replace the three calls to the calloc allocation routine by references to program variables, such as:

Of course, in the latter case, it is appropriate to maintain a pool of available variables to use, such as arrays of differently typed variables.

When pointing at character data, you should allocate sqllen bytes plus one for the null, as in:

When pointing at varchar data, you should allocate sqllen bytes plus two (or sizeof(short)) for the 2-byte length field. For example:

You may also set the SQLVAR to point to a data handler for large object columns. For details, see Advanced Processing in this chapter.