The solidDB ODBC Driver supports all C data types in keeping with the need for character SQL type conversion to and from all C types.
The C data type is specified in the following functions:
▪ SQLBindCol and SQLGetData functions with the TargetType argument.
▪ SQLBindParameter with the ValueType argument.
▪ SQLSetDescField to set the SQL_DESC_CONCISE_TYPE field of an ARD1 or APD2
▪ SQLSetDescRec with the Type argument, SubType argument (if needed), and the DescriptorHandle argument set to the handle of an ARD or APD.
– ARD: Application Row Descriptors contain information about application variables that are bound to columns returned by an SQL statement. The information includes the addresses, lengths, and C data types of the bound variables.
– APD: Application Parameter Descriptors contain information about application variables that are bound to the parameter markers ("?") used in an SQL statement, for example:
SELECT * FROM table1 WHERE id = ?
The information in the descriptors includes the addresses, lengths, and C data types of the bound variables.
The following table contains these columns:
C type identifiers
The first column shows the C type identifiers that are passed to functions like SQLBindCol to indicate the type of the variable that will be bound to the column. In the following example, SQL_C_DECIMAL is a C type identifier:
// Bind MySharedVariable to column 1 of the result set. // (Column 1 is a DECIMAL column.) The C Type Identifier // SQL_C_DECIMAL shows that the variable MySharedVariable is of a // type equivalent to DECIMAL. SQLBindCol(..., 1, SQL_C_DECIMAL, &MySharedVariable, ...);
ODBC C data type
The second columns shows the ODBC C data type that is associated with each C type identifier. This ODBC C data type is a "typedef" that you use to define variables in your ODBC program. This helps insulate your program from platform-specific requirements. For example, if you have a column of type SQL FLOAT and you want to bind a variable to that column, you can declare your variable to be of type SQLFLOAT in the following way:
SQLFLOAT MySharedVariable; // Can be bound to a column of type SQL FLOAT.
C Type
The third column contains an example of a C type definition that corresponds to the ODBC C data type "typdef". The examples in this column show the most frequently used definitions on 32-bit platforms.
The data types specified in this column are not platform-independent; they are examples.
// A portable way to declare a variable that will be bound // to a column of type SQL FLOAT. SQLFLOAT MySharedSQLFLOATVariable = 0.0; // A non-portable way to declare a variable that will be bound // to a column // of type SQL INTEGER. This declaration works properly on most // 32-bit platforms, but might fail on 64-bit platforms. long int MySharedSQLINTEGERVariable = 0; // Bind MySharedSQLFLOATVariable to column 1 of the result set. SQLBindCol(..., 1, SQL_C_DOUBLE, &MySharedSQLFLOATVariable, ...); // Bind MySharedSQLINTEGERVariable to column 2 of the result set. SQLBindCol(..., 2, SQL_C_SLONG, &MySharedSQLINTEGERVariable, ...);
The C Type Identifier and the ODBC C Type do not always have similar names. The C Type Identifier has a name based on the C language data type (for example, "float"), while the ODBC C Typedef has a name that is based on the SQL data type. Since C-language "float" corresponds to SQL "REAL", the table lists "SQL_C_FLOAT" as the C Type Identifier that corresponds to the ODBC C Typedef "SQLREAL".
C vs ODBC naming correspondence
The following table describes the correspondence between the naming in C and in ODBC:
1 The values of the year, month, day, hour, minute, and second fields in the datetime C data types must conform to the constraints of the Gregorian calendar. (See Constraints of the Gregorian calendar.)
2 The value of the fraction field is the number of nanoseconds (billionths of a second) and ranges from 0 through 999,999,999 (1 less than 1 billion). For example, the value of the fraction field for a half-second is 500,000,000, for a thousandth of a second (one millisecond) is 1,000,000, for a millionth of a second (one microsecond) is 1,000, and for a billionth of a second (one nanosecond) is 1.
3 In ODBC 2.x, the C date, time, and timestamp data types are SQL_C_DATE, SQL_C_TIME, and SQL_C_TIMESTAMP.
4 A number is stored in the val field of the SQL_NUMERIC_STRUCT structure as a scaled integer, in little endian mode (the leftmost byte being the least-significant byte). For example, the number 10.001 base 10, with a scale of 4, is scaled to an integer of 100010. Because this is 186AA in hexadecimal format, the value in SQL_NUMERIC_STRUCT would be "AA 86 01 00 00 ... 00", with the number of bytes defined by the SQL_MAX_NUMERIC_LEN #define.
5 The precision and scale fields of the SQL_C_NUMERIC data type are never used for input from an application, only for output from the driver to the application. When the driver writes a numeric value into the SQL_NUMERIC_STRUCT, it will use its own driver-specific default as the value for the precision field, and it will use the value in the SQL_DESC_SCALE field of the application descriptor (which defaults to 0) for the scale field. An application can provide its own values for precision and scale by setting the SQL_DESC_PRECISION and SQL_DESC_SCALE fields of the application descriptor.
6 The DECIMAL and NUMERIC data types take up more than one byte/character. The data types will actually be declared as arrays based on the precision required for the column. For example, a column of type SQL DECIMAL(10,4) might be declared as SQL_DECIMAL[13] to take into account the 10 digits, the sign character, the decimal point character, and the string terminator.
7 _int64 might not be supplied by some compilers.
8 SQL_C_SHORT, SQL_C_LONG, and SQL_C_TINYINT have been replaced in ODBC by signed and unsigned types: SQL_C_SSHORT and SQL_C_USHORT, SQL_C_SLONG and SQL_C_ULONG, and SQL_C_STINYINT and SQL_C_UTINYINT. An ODBC 3.x driver that should work with ODBC 2.x applications should support SQL_C_SHORT, SQL_C_LONG, and SQL_C_TINYINT, because when they are called, the Driver Manager passes them through to the driver.
9 solidDB does not support unsigned SQL data types. You can bind an unsigned C data type to a signed SQL column, but you should not do this unless the values stored in the SQL column and the C variable are within the valid range for both data types. For example, since signed TINYINT columns hold values from -128 to +127, while unsigned SQL_C_UTINYINT variables hold values from 0 to 255, you can only store values between 0 and +127 in the column and bound variable if you want the values to be interpreted properly.
64-bit integer structures
On Microsoft C compilers, the C data type identifiers SQL_C_SBIGINT and SQL_C_UBIGINT are defined as _int64. When a non-Microsoft C compiler is used, the C type might differ. If the compiler in use is supporting 64-bit integers natively, then define the driver or application ODBCINT64 as the native 64-bit integer type. If the compiler in use does not support 64-bit integers natively, define the following structures to ensure access to these C types:
Because a 64-bit integer is aligned to the 8-byte boundary, be sure to align these structures to an 8-byte boundary.
solidDB supports signed BIGINT, but not unsigned BIGINT.
Default C data types
In applications that specify SQL_C_DEFAULT in SQLBindCol, SQLGetData, or SQLBindParameter, the driver assumes that the C data type of the output or input buffer corresponds to the SQL data type of the column or parameter to which the buffer is bound.
Important To avoid compatibility problems when using different platforms, we strongly recommend that you avoid using SQL_C_DEFAULT. Instead, specify the C type of the buffer in use.
Drivers cannot always determine the correct default C type for these reasons:
▪ The DBMS might have promoted an SQL data type of a column or a parameter; in this case, the driver is unable to determine the original SQL data type and consequently, cannot determine the corresponding default C data type.
▪ The DBMS determined whether the data type of a column or parameter is signed or unsigned; in this case, the driver is unable to determine this for a particular SQL data type and consequently, cannot determine this for the corresponding default C data type.
The SQL_C_TCHAR type identifier is used for Unicode purposes. Use this identifier in applications that transfer character data and are compiled to use both ASCII and Unicode character sets. Note that the SQL_C_TCHAR is not a type identifier in the conventional sense; instead, it is a macro contained in the header file for Unicode conversion. SQL_C_CHAR or SQL_C_WCHAR replaces SQL_C_TCHAR depending on the setting of the UNICODE #define.