C host variable types

Only a limited number of C data types are supported as host variables. Also, certain host variable types do not have a corresponding C type.

Macros defined in the sqlca.h header file can be used to declare host variables of the following types: NCHAR, VARCHAR, NVARCHAR, LONGVARCHAR, LONGNVARCHAR, BINARY, LONGBINARY, DECIMAL, FIXCHAR, NFIXCHAR, DATETIME (SQLDATETIME), BIT, BIGINT, or UNSIGNED BIGINT. They are used as follows:

EXEC SQL BEGIN DECLARE SECTION;
DECL_NCHAR                 v_nchar[10];
DECL_VARCHAR( 10 )         v_varchar;
DECL_NVARCHAR( 10 )        v_nvarchar;
DECL_LONGVARCHAR( 32768 )  v_longvarchar;
DECL_LONGNVARCHAR( 32768 ) v_longnvarchar;
DECL_BINARY( 4000 )        v_binary;
DECL_LONGBINARY( 128000 )  v_longbinary;
DECL_DECIMAL( 30, 6 )      v_decimal;
DECL_FIXCHAR( 10 )         v_fixchar;
DECL_NFIXCHAR( 10 )        v_nfixchar;
DECL_DATETIME              v_datetime;
DECL_BIT                   v_bit;
DECL_BIGINT                v_bigint;
DECL_UNSIGNED_BIGINT       v_ubigint;
EXEC SQL END DECLARE SECTION;

The preprocessor recognizes these macros within a declaration section and treats the variable as the appropriate type. It is recommended that the DECIMAL (DT_DECIMAL, DECL_DECIMAL) type not be used since the format of decimal numbers is proprietary.

The following table lists the C variable types that are allowed for host variables and their corresponding embedded SQL interface data types.

C data type

Embedded SQL interface type

Description

short              si;
short int          si;

DT_SMALLINT

16-bit signed integer.

unsigned short int usi;

DT_UNSSMALLINT

16-bit unsigned integer.

long              l;
long int          l;

DT_INT

32-bit signed integer.

unsigned long int ul;

DT_UNSINT

32-bit unsigned integer.

DECL_BIGINT       ll;

DT_BIGINT

64-bit signed integer.

DECL_UNSIGNED_BIGINT ull;

DT_UNSBIGINT

64-bit unsigned integer.

float f;

DT_FLOAT

4-byte floating point.

double d;

DT_DOUBLE

8-byte floating point.

char a[n]; /*n>=1*/

DT_STRING

Null-terminated string, in CHAR character set. The string is blank-padded if the database is initialized with blank-padded strings. This variable holds n-1 bytes plus the null terminator.

char *a;

DT_STRING

Null-terminated string, in CHAR character set. This variable points to an area that can hold up to 32766 bytes plus the null terminator.

DECL_NCHAR a[n]; /*n>=1*/

DT_NSTRING

Null-terminated string, in NCHAR character set. The string is blank-padded if the database is initialized with blank-padded strings. This variable holds n-1 bytes plus the null terminator.

DECL_NCHAR *a;

DT_NSTRING

Null-terminated string, in NCHAR character set. This variable points to an area that can hold up to 32766 bytes plus the null terminator.

DECL_VARCHAR(n) a;

DT_VARCHAR

Varying length character string, in CHAR character set, with 2-byte length field. Not null-terminated or blank-padded. The maximum value for n is 32765 (bytes).

DECL_NVARCHAR(n) a;

DT_NVARCHAR

Varying length character string, in NCHAR character set, with 2-byte length field. Not null-terminated or blank-padded. The maximum value for n is 32765 (bytes).

DECL_LONGVARCHAR(n) a;

DT_LONGVARCHAR

Varying length long character string, in CHAR character set, with three 4-byte length fields. Not null-terminated or blank-padded.

DECL_LONGNVARCHAR(n) a;

DT_LONGNVARCHAR

Varying length long character string, in NCHAR character set, with three 4-byte length fields. Not null-terminated or blank-padded.

DECL_BINARY(n) a;

DT_BINARY

Varying length binary data with 2-byte length field. The maximum value for n is 32765 (bytes).

DECL_LONGBINARY(n) a;

DT_LONGBINARY

Varying length long binary data with three 4-byte length fields.

char            a; /*n=1*/ 
DECL_FIXCHAR(n) a;

DT_FIXCHAR

Fixed length character string, in CHAR character set. Blank-padded but not null-terminated. The maximum value for n is 32767 (bytes).

DECL_NCHAR       a; /*n=1*/
DECL_NFIXCHAR(n) a;

DT_NFIXCHAR

Fixed length character string, in NCHAR character set. Blank-padded but not null-terminated. The maximum value for n is 32767 (bytes).

DECL_DATETIME a;

DT_TIMESTAMP_STRUCT

SQLDATETIME structure

Character sets

For DT_FIXCHAR, DT_STRING, DT_VARCHAR, and DT_LONGVARCHAR, character data is in the application's CHAR character set, which is usually the character set of the application's locale. An application can change the CHAR character set either by using the CHARSET connection parameter, or by calling the db_change_char_charset function.

For DT_NFIXCHAR, DT_NSTRING, DT_NVARCHAR, and DT_LONGNVARCHAR, data is in the application's NCHAR character set. By default, the application's NCHAR character set is the same as the CHAR character set. An application can change the NCHAR character set by calling the db_change_nchar_charset function.

For more information about locales and character sets, see Understanding locales.

For more information about changing the CHAR character set, see CharSet connection parameter [CS] or db_change_char_charset function.

For more information about changing the NCHAR character set, see db_change_nchar_charset function.

Data lengths

Regardless of the CHAR and NCHAR character sets in use, all data lengths are specified in bytes.

If character set conversion occurs between the server and the application, it is the application's responsibility to ensure that buffers are sufficiently large to handle the converted data, and to issue additional GET DATA statements if data is truncated.

Pointers to char

The database interface considers a host variable declared as a pointer to char (char * a) to be 32767 bytes long. Any host variable of type pointer to char used to retrieve information from the database must point to a buffer large enough to hold any value that could possibly come back from the database.

This is potentially quite dangerous because someone could change the definition of the column in the database to be larger than it was when the program was written. This could cause random memory corruption problems. It is better to use a declared array, even as a parameter to a function, where it is passed as a pointer to char. This technique allows the embedded SQL statements to know the size of the array.

Scope of host variables

A standard host-variable declaration section can appear anywhere that C variables can normally be declared. This includes the parameter declaration section of a C function. The C variables have their normal scope (available within the block in which they are defined). However, since the SQL preprocessor does not scan C code, it does not respect C blocks.

As far as the SQL preprocessor is concerned, host variables are global to the source file; two host variables cannot have the same name.

Discuss this page in DocCommentXchange.
Send feedback about this page using email.