ODBC API Incompatibilities With Previous Versions of TimesTen

There are changes introduced in the TimesTen 18.1 release that impact ODBC applications used with previous versions of TimesTen.

These topics are covered:

• Overview of ODBC API Incompatibilities

• ODBC 3.5 Function Signatures That Have Changed

• ODBC 2.5 Function Signatures That Have Changed

• ODBC Data Types That Have Changed

Overview of ODBC API Incompatibilities

The TimesTen driver is ODBC-compliant; however, beginning in Release 18.1, more recent ODBC header files are provided in the include directory of the TimesTen installation on Linux and UNIX platforms.

Changes were also made to update some ODBC types and functions to make them 64-bit compatible.

These and other changes may necessitate code changes on any platform. ODBC changes requiring code updates for ODBC applications fall into the following categories:

• ODBC function changes

  • Function signature changes: A number of function signatures have changed for 64-bit programming.

  • Changes to the size of option or attribute values: This refers to values of connection options, statement options, column attributes, or driver and data source information, either passed or returned. These are now 64-bit values in the circumstances indicated below.

• ODBC data type changes

Tip:

Even if none of the required code changes applies to your applications, you should recompile and relink existing ODBC applications the first time you use a TimesTen 22.1 release.

If your existing TimesTen ODBC application uses features described in the sections that follow, you must update the application as necessary:

ODBC 3.5 Function Signatures That Have Changed

There are ODBC 3.5 functions with changes requiring code updates.

In previous releases, TimesTen provided partial support for ODBC 3.5 functionality, including:

• Handle allocation methods

• Diagnostic records

• Wide character functions

• Attribute set and get functions for handles

• SQLColAttribute

• Miscellaneous functions that map directly to 2.5 functionality such as SQLCloseCursor and SQLEndTran

The functions listed in Table 10-16 have changes to the signature or changes to the size of attribute values, requiring code updates for ODBC 3.5 applications, as indicated. Sizes of attribute values apply to values of connection and statement attributes, either passed or returned.

Note:

• Signature changes apply to either 64-bit or 32-bit environments. Size changes in option and attribute values apply only to 64-bit environments.

• TimesTen ODBC does not return values for options or attributes related to features that TimesTen does not support. For example: SQL_ATTR_ASYNC_ENABLE, SQL_ATTR_ENLIST_IN_DTC, SQL_ATTR_CURSOR_SCROLLABLE, SQL_ATTR_CURSOR_SENSITIVITY, SQL_ATTR_FETCH_BOOKMARK_PTR, SQL_ATTR_METADATA_ID, SQL_ATTR_RETRIEVE_DATA, SQL_ATTR_SIMULATE_CURSOR, SQL_ATTR_USE_BOOKMARKS.

Table 10-16 Changes in ODBC 3.5 Functions

Function	Signature Changes	Size Changes in Option and Attribute Values
SQLColAttribute SQLColAttributeW	N/A	On UNIX platforms: For the following FieldIdentifier values, a 64-bit value is returned in *NumericAttributePtr: SQL_DESC_AUTO_UNIQUE_VALUE SQL_DESC_CASE_SENSITIVE SQL_DESC_CONCISE_TYPE SQL_DESC_COUNT SQL_DESC_DISPLAY_SIZE SQL_DESC_FIXED_PREC_SCALE SQL_DESC_LENGTH SQL_DESC_NULLABLE SQL_DESC_NUM_PREC_RADIX SQL_DESC_OCTET_LENGTH SQL_DESC_PRECISION SQL_DESC_SCALE SQL_DESC_SEARCHABLE SQL_DESC_TYPE SQL_DESC_UNNAMED SQL_DESC_UNSIGNED SQL_DESC_UPDATABLE
SQLGetConnectAttr SQLGetConnectAttrW	*ValuePtr must be SQLUINTEGER or SQLULEN, depending on the attribute you are getting. Note: TimesTen-specific attributes (prefixed with TT_) remain the same data types.	On UNIX platforms: For the following attributes, a 64-bit value is returned in *ValuePtr: SQL_ATTR_ASYNC_ENABLE SQL_ATTR_ENLIST_IN_DTC SQL_ATTR_ODBC_CURSORS SQL_ATTR_QUIET_MODE
SQLGetStmtAttr SQLGetStmtAttrW	*ValuePtr must be SQLUINTEGER or SQLULEN, depending on the attribute you are getting. Note: TimesTen-specific attributes (prefixed with TT_) remain the same data types.	On UNIX platforms: For the following attributes, a 64-bit value is returned in *ValuePtr: SQL_ATTR_APP_PARAM_DESC SQL_ATTR_APP_ROW_DESC SQL_ATTR_ASYNC_ENABLE SQL_ATTR_CONCURRENCY SQL_ATTR_CURSOR_SCROLLABLE SQL_ATTR_CURSOR_SENSITIVITY SQL_ATTR_CURSOR_TYPE SQL_ATTR_ENABLE_AUTO_IPD SQL_ATTR_FETCH_BOOKMARK_PTR SQL_ATTR_ROWS_FETCHED_PTR SQL_ATTR_IMP_PARAM_DESC SQL_ATTR_IMP_ROW_DESC SQL_ATTR_KEYSET_SIZE SQL_ATTR_MAX_LENGTH SQL_ATTR_MAX_ROWS SQL_ATTR_METADATA_ID SQL_ATTR_NOSCAN SQL_ATTR_PARAM_BIND_OFFSET_PTR SQL_ATTR_PARAM_BIND_TYPE SQL_ATTR_PARAM_OPERATION_PTR SQL_ATTR_PARAM_STATUS_PTR SQL_ATTR_PARAMS_PROCESSED_PTR SQL_ATTR_PARAMSET_SIZE SQL_ATTR_QUERY_TIMEOUT SQL_ATTR_RETRIEVE_DATA SQL_ATTR_ROW_ARRAY_SIZE SQL_ATTR_ROW_BIND_OFFSET_PTR SQL_ATTR_ROW_NUMBER SQL_ATTR_ROW_OPERATION_PTR SQL_ATTR_ROW_STATUS_PTR SQL_ATTR_SIMULATE_CURSOR SQL_ATTR_USE_BOOKMARKS
SQLSetConnectAttr SQLSetConnectAttrW	*ValuePtr must be SQLUINTEGER or SQLULEN, depending on the attribute you are setting. Note: TimesTen-specific attributes (prefixed with TT_) remain the same data types.	On UNIX platforms: For the following attributes, a 64-bit value is passed in *ValuePtr: SQL_ATTR_ASYNC_ENABLE SQL_ATTR_ENLIST_IN_DTC SQL_ATTR_ODBC_CURSORS SQL_ATTR_QUIET_MODE
SQLSetStmtAttr SQLSetStmtAttrW	*ValuePtr must be SQLUINTEGER or SQLULEN, depending on the attribute you are setting. Note: TimesTen-specific attributes (prefixed with TT_) remain the same data types.	On UNIX platforms: For the following attributes, a 64-bit value is passed in *ValuePtr: SQL_ATTR_APP_PARAM_DESC SQL_ATTR_APP_ROW_DESC SQL_ATTR_ASYNC_ENABLE SQL_ATTR_CONCURRENCY SQL_ATTR_CURSOR_SCROLLABLE SQL_ATTR_CURSOR_SENSITIVITY SQL_ATTR_CURSOR_TYPE SQL_ATTR_ENABLE_AUTO_IPD SQL_ATTR_FETCH_BOOKMARK_PTR SQL_ATTR_IMP_PARAM_DESC SQL_ATTR_IMP_ROW_DESC SQL_ATTR_KEYSET_SIZE SQL_ATTR_MAX_LENGTH SQL_ATTR_MAX_ROWS SQL_ATTR_METADATA_ID SQL_ATTR_NOSCAN SQL_ATTR_PARAM_BIND_OFFSET_PTR SQL_ATTR_PARAM_BIND_TYPE SQL_ATTR_PARAM_OPERATION_PTR SQL_ATTR_PARAM_STATUS_PTR SQL_ATTR_PARAMS_PROCESSED_PTR SQL_ATTR_PARAMSET_SIZE SQL_ATTR_QUERY_TIMEOUT SQL_ATTR_RETRIEVE_DATA SQL_ATTR_ROW_ARRAY_SIZE SQL_ATTR_ROW_BIND_OFFSET_PTR SQL_ATTR_ROW_NUMBER SQL_ATTR_ROW_OPERATION_PTR SQL_ATTR_ROW_STATUS_PTR SQL_ATTR_ROWS_FETCHED_PTR SQL_ATTR_SIMULATE_CURSOR SQL_ATTR_USE_BOOKMARKS

ODBC 2.5 Function Signatures That Have Changed

There are ODBC 2.5 functions with changes requiring code updates.

The functions listed in Table 10-17 have changes to the signature or changes to the size of option or attribute values, requiring code updates for ODBC 2.5 applications, as indicated. Sizes of option or attribute values apply to values of connection options, statement options, column attributes, or driver and data source information, either passed or returned.

Table 10-17 Changes in ODBC 2.5 Functions

Function	Signature Changes	Size Changes in Option and Attribute Values
SQLColAttributes SQLColAttributesW	N/A	On Linux and UNIX platforms: For the following fDescType values, a SQLLEN value is returned in *pfDesc: SQL_COLUMN_COUNT SQL_COLUMN_DISPLAY_SIZE SQL_COLUMN_LENGTH SQL_DESC_AUTO_UNIQUE_VALUE SQL_DESC_CASE_SENSITIVE SQL_DESC_CONCISE_TYPE SQL_DESC_FIXED_PREC_SCALE SQL_DESC_SEARCHABLE SQL_DESC_UNSIGNED SQL_DESC_UPDATABLE
SQLGetConnectOption SQLGetConnectOptionW	The Value parameter must be SQLUINTEGER or SQLULEN, depending on the option you are getting. Note: TimesTen-specific options (prefixed with TT_) remain the same data types.	On Linux and UNIX platforms: For the option SQL_ATTR_QUIET_MODE, an HWND value (void * pointer to a window) is returned in Value.
SQLGetInfo SQLGetInfoW	N/A	On Linux and UNIX platforms: For the following InfoType values, a SQLPOINTER value is returned in *InfoValuePtr: SQL_DRIVER_HDBC SQL_DRIVER_HENV SQL_DRIVER_HSTMT
SQLGetStmtOption	The Value parameter must be SQLUINTEGER or SQLULEN, depending on the option you are getting. Note: TimesTen-specific options (prefixed with TT_) remain the same data types.	On Linux and UNIX platforms: For the following options, a SQLPOINTER value is returned in Value: SQL_KEYSET_SIZE SQL_MAX_LENGTH SQL_MAX_ROWS SQL_ROWSET_SIZE
SQLParamOptions	On Linux and UNIX platforms: The crow and pirow parameters are now declared as SQLULEN.	N/A
SQLSetConnectOption SQLSetConnectOptionW	The Value parameter must be SQLUINTEGER or SQLULEN, depending on the option you are setting. Note: TimesTen-specific options (prefixed with TT_) remain the same data types.	On Linux and UNIX platforms: For the option SQL_ATTR_QUIET_MODE, an HWND value (void * pointer to a window) is passed in Value.
SQLSetPos	TimesTen does not support scrollable cursors. This function returns a "Driver not capable" error (S1C00). Note: The ODBC definition of SQLSETPOSIROW, the data type for the irow parameter, has changed. (See the next section, ODBC Data Types That Have Changed.)	N/A
SQLSetStmtOption	The Value parameter must be SQLUINTEGER or SQLULEN, depending on the option you are setting. Note: TimesTen-specific options (prefixed with TT_) remain the same data types.	On Linux and UNIX platforms: For the following options, a SQLPOINTER value is passed in Value: SQL_KEYSET_SIZE SQL_MAX_LENGTH SQL_MAX_ROWS SQL_ROWSET_SIZE

ODBC Data Types That Have Changed

There are changes to data types that require code updates for ODBC applications.

Table 10-18 ODBC 2.5 Data Types That Have Changed

Data Types	Explanation
HANDLE HINSTANCE	On Linux and UNIX platforms: These data types have been redefined as (void *).
SQLROWCOUNT SQLROWSETSIZE SQLTRANSID	These data types have been deprecated. Use SQLULEN instead.
SQLROWOFFSET	This data type has been deprecated. Use SQLLEN instead.
SQLSETPOSIROW	On Linux and UNIX platforms: This data type has been redefined as SQLULEN. It is advisable to use SQLULEN directly instead.