Character Data and the SQLDA
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:
/*
** Assume 'sqlda' is a pointer to a dynamically allocated SQLDA
*/
sqlda->sqlvar[0].sqltype = IISQ_CHA_TYPE;
sqlda->sqlvar[0].sqllen = 5;
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:
char buf[6];
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:
sqlda->sqlvar[0].sqltype = IISQ_VCH_TYPE;
sqlda->sqlvar[0].sqllen = 100;
assumes that up to 100 bytes of data can be copied, such as in the declaration:
varchar struct {
short len;
char buf[100];
} vch;
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:
exec sql execute statement_name USING DESCRIPTOR
descriptor_name;
exec frs putform form_name USING DESCRIPTOR
descriptor_name;
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:
sqlda->sqlvar[0].sqltype = IISQ_CHA_TYPE;
sqlda->sqlvar[0].sqllen = 0;
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.