C data types for CLI applications

You can use SQL data types with Call Level Interface (CLI) applications, the corresponding symbolic name of the CLI application, and the default C symbolic name. A C symbolic name corresponds to a C data type.

The following table lists the generic type definitions for each symbolic C type that is used in CLI applications.

C symbolic data type
This column contains C symbolic names, defined as integer values. These values are used in various function arguments to identify the C data type shown in the last column.
C type
This column contains C defined types, defined in sqlcli.h using a C typedef statement. The values in this column should be used to declare all CLI related variables and arguments, in order to make the application more portable. See Table 3 for a list of additional symbolic data types used for function arguments.
Base C type
This column is shown for reference only. All variables and arguments should be defined using the symbolic types in the previous column since the base C type is platform dependent. Some of the values are C structures that are described in Table 2.
Table 1. C data types
C symbolic data type C type Base C type
SQL_C_BINARY SQLCHAR unsigned char
SQL_C_BINARYXML SQLCHAR unsigned char
SQL_C_BIT SQLCHAR unsigned char or char (Value 1 or 0)
SQL_C_BLOB_LOCATOR a SQLINTEGER 32-bit integer
SQL_C_CLOB_LOCATOR a SQLINTEGER 32-bit integer
SQL_C_CHAR SQLCHAR unsigned char
SQL_C_CURSORHANDLE SQLINTEGER 32-bit integer
SQL_C_DBCHAR SQLDBCHAR wchar_t
SQL_C_DBCLOB_LOCATOR SQLINTEGER 32-bit integer
SQL_C_DECIMAL64 SQLDECIMAL64 see Table 2
SQL_C_DECIMAL128 SQLDECIMAL128 see Table 2
SQL_C_DOUBLE SQLDOUBLE double
SQL_C_FLOAT SQLREAL float
SQL_C_LONG SQLINTEGER 32-bit integer
SQL_C_NUMERIC b SQL_NUMERIC_STRUCT see Table 2
SQL_C_SBIGINT SQLBIGINT 64-bit integer
SQL_C_SHORT SQLSMALLINT 16-bit integer
SQL_C_TINYINT SQLSCHAR signed char (Range -128 to 127)
SQL_C_TYPE_DATE DATE_STRUCT see Table 2
SQL_C_TYPE_TIME TIME_STRUCT see Table 2
SQL_C_TYPE_TIMESTAMP TIMESTAMP_STRUCT see Table 2
SQL_C_TYPE_TIMESTAMP_EXT TIMESTAMP_STRUCT_EXT see Table 2
SQL_C_TYPE_TIMESTAMP_EXT_TZ TIMESTAMP_STRUCT_EXT_TZ see Table 2
SQL_C_UBIGINT SQLUBIGINT unsigned 64-bit integer
SQL_C_ULONG SQLUINTEGER unsigned 32-bit integer
SQL_C_USHORT SQLUSMALLINT unsigned 16-bit integer
SQL_C_UTINYINT SQLUCHAR unsigned char
SQL_C_WCHAR SQLWCHAR wchar_t
SQL_C_TYPE_TIMESTAMP_EXT TIMESTAMP_STRUCT_EXT See Table 2
  • a LOB Locator Types.
  • b Windows only.
Note: SQL file reference data types (used in embedded SQL) are not needed in CLI.
Note: You use the SQL_C_BINARYXML C data type with the binary XML data transmission format, which is supported by Db2® CLI . The Db2 server must also be at a level that supports the binary XML format.
Table 2. C structures
C type Generic structure Windows structure
DATE_STRUCT 
 
typedef struct DATE_STRUCT
  {
    SQLSMALLINT   year;
    SQLUSMALLINT   month;
    SQLUSMALLINT   day;
  } DATE_STRUCT;
 
 
typedef struct tagDATE_STRUCT
  {
    SWORD   year;
    UWORD   month;
    UWORD   day;
  } DATE_STRUCT;
TIME_STRUCT 
 
typedef struct TIME_STRUCT
  {
    SQLUSMALLINT   hour;
    SQLUSMALLINT   minute;
    SQLUSMALLINT   second;
  } TIME_STRUCT;
 
 
typedef struct tagTIME_STRUCT
  {
    UWORD   hour;
    UWORD   minute;
    UWORD   second;
  } TIME_STRUCT;
TIMESTAMP_STRUCT 
 
typedef struct TIMESTAMP_STRUCT
  {
    SQLUSMALLINT   year;
    SQLUSMALLINT   month;
    SQLUSMALLINT   day;
    SQLUSMALLINT   hour;
    SQLUSMALLINT   minute;
    SQLUSMALLINT   second;
    SQLINTEGER    fraction;
  } TIMESTAMP_STRUCT;
 
 
typedef struct tagTIMESTAMP_STRUCT
  {
    SWORD   year;
    UWORD   month;
    UWORD   day;
    UWORD   hour;
    UWORD   minute;
    UWORD   second;
    UDWORD  fraction;
  } TIMESTAMP_STRUCT;
TIMESTAMP_STRUCT_EXT 
typedef  struct TIMESTAMP_STRUCT_EXT
  {
    SQLSMALLINT    year;
    SQLUSMALLINT   month;
    SQLUSMALLINT   day;
    SQLUSMALLINT   hour;
    SQLUSMALLINT   minute;
    SQLUSMALLINT   second;
    SQLUINTEGER fraction;
 /* 1-9 digits */
    SQLUINTEGER   fraction2; 
/* 10-12 digits */
  } 
TIMESTAMP_STRUCT_EXT;
 (No Windows structure. Only a generic structure.)
TIMESTAMP_STRUCT_EXT _TZ 
 typedef struct TIMESTAMP_STRUCT
  {
    SQLSMALLINT   year;
    SQLUSMALLINT  month;
    SQLUSMALLINT  day;
    SQLUSMALLINT  hour;
    SQLUSMALLINT  minute;
    SQLUSMALLINT  second;
    SQLUINTEGER   fraction;
    SQLUINTEGER   fraction2;
    SQLSMALLINT timezone_hour;  
/*-12 to 14*/
    SQLUSMALLINT timezone_minute; 
/*-59 to 59*/
  } 
TIMESTAMP_STRUCT_EXT_TZ;
 (No Windows structure. Only a generic structure.)
SQLDECIMAL64 
typedef struct tagSQLDECIMAL64 
  {
    union {
    SQLDOUBLE dummy;
    SQLCHAR dec64
     [SQL_DECFLOAT16_
       COEFFICIENT_LEN];
    } udec64;
  } SQLDECIMAL64;
 (No Windows structure. Only a generic structure.)
SQLDECIMAL128 
typedef struct tagSQLDECIMAL128 
  {
    union {
    SQLDOUBLE dummy;
    SQLCHAR dec128
     [SQL_DECFLOAT34_
       COEFFICIENT_LEN];
    } udec128;
  } SQLDECIMAL128;
(No Windows structure. Only a generic structure.)
SQL_NUMERIC_STRUCT (No generic structure. Only a Windows structure.) 
 
typedef struct tagSQL_NUMERIC_STRUCT
  {
    SQLCHAR   precision;
    SQLCHAR   scale;
    SQLCHAR   sign; a
    SQLCHAR   
        val[SQL_MAX_NUMERIC_LEN];b c
  } SQL_NUMERIC_STRUCT;
See Table 3 for more information about the SQLUSMALLINT C data type.
  • a Sign field: 1 = positive, 2 = negative
  • b 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.
  • c 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 uses its own default as the value for the precision field, and it uses 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.
As well as the data types that map to SQL data types, there are also C symbolic types used for other function arguments such as pointers and handles. Both the generic and ODBC data types are shown in the following table.
Note: There are two kinds of drivers that ship with the product: the CLI driver, and the 64-bit ODBC driver. The 64-bit ODBC Driver handles the differences with type definitions between various ODBC Managers.
Table 3. C Data types and base C data types
Defined C type Base C type Typical usage
SQLPOINTER void * Pointer to storage for data and parameters.
SQLHANDLE
  1. 1. void *
  2. 32-bit integer
 The handle that references all 4 types of handle information.
  1. 64-bit value for Windows 64-bit ODBC Driver and UNIX 64-bit ODBC Driver
  2. 32-bit value for all 32-bit platforms and 64-bit CLI Drivers
SQLHENV
  1. 1. void *
  2. 32-bit integer
 The handle that references environment information.
  1. 64-bit value for Windows 64-bit ODBC Driver and UNIX 64-bit ODBC Driver
  2. 32-bit value for all 32-bit platforms and 64-bit CLI Drivers
SQLHDBC
  1. 1. void *
  2. 32-bit integer
 The handle that references database connection information.
  1. 64-bit value for Windows 64-bit ODBC Driver and UNIX 64-bit ODBC Driver
  2. 32-bit value for all 32-bit platforms and 64-bit CLI Drivers
SQLHSTMT
  1. 1. void *
  2. 32-bit integer
 The handle that references statement information.
  1. 64-bit value for Windows 64-bit ODBC Driver and UNIX 64-bit ODBC Driver
  2. 32-bit value for all 32-bit platforms and 64-bit CLI Drivers
SQLUSMALLINT unsigned 16-bit integer The function input argument for unsigned short integer values.
SQLUINTEGER unsigned 32-bit integer The function input argument for unsigned long integer values.
SQLRETURN 16-bit integer The return code from CLI functions.
SQLULEN
  1. unsigned 64-bit integer
  2. unsigned 32-bit integer
  1. The function input or output argument for unsigned 64-bit integer values (64-bit ODBC driver).
  2. The function input or output argument for unsigned 32-bit integer values (all other drivers).
SQLLEN
  1. 64-bit integer
  2. 32-bit integer
  1. The function input or output argument for 64-bit integer values (64-bit ODBC driver).
  2. The function input or output argument for 32-bit integer values (all other drivers).
SQLSETPOSIROW
  1. 64-bit integer
  2. 16-bit integer
  1. The function input or output argument for 64-bit integer values (Windows 64-bit ODBC driver).
  2. The function input or output argument for 16-bit integer values (all other drivers).