ODBC Thread Safety (4)

ODBC in Multi-Threaded Environments (Thread Safety)

Handle States

ODBC handles (environment, connection, statement) carry state information between calls to ODBC functions. Uncontrolled accesses to a shared handle by more than one thread can cause this state information to be lost or misconstrued. This section documents the standard types of state information carried by ODBC handles between function calls. Some ODBC drivers may carry additional or extended state that should be documented by the driver

This article is based on ODBC 2.5 and only concerns itself with the basic handles - environment, connection and statement. ODBC 3.0 introduced additional types of handles. In general, state information carried in the new ODBC 3.0 handles can be derived from the information below.

ODBC Handle States

All Handles
- Error status - each ODBC function may return error status that is stored in the referenced handle. Error status is retrieved with the SQLError function.
Environment Handle
- * List of connection handles - each currently allocated connection handle is stored in a list in the environment handle.
Connection Handle
- Connection options - set by SQLSetConnectOption.
- Connection-level statement options - set by SQLSetConnectOption.
- Connected - if connected, to what datasource, user id, etc.
- Browse process - during a SQLBrowseConnect sequence, the progress of the browsing is stored.
- Transactions - if not autocommit, transactions are at the connect level.
- * List of statement handles - each currently allocated statement handle is stored in a list in the connection handle.
Statement Handle
- Prepared statement - after a SQLPrepare, SQLExecDirect or catalog function, information about the prepared statement.
- Cursor position - positioning of cursor and current keyset for SQLFetch, SQLExtendedFetch, etc.
- Bind parameters - information about bound parameters from SQLBindParameter.
- Bind columns - information about bound columns from SQLBindCol.
- Put data - positioning in parameters and in sequence of SQL_NEED_DATA, SQLParamData and SQLPutData.
- Get data - positioning in columns and in sequence of SQLGetData.
- Cursor name - set with SQLSetCursorName function.
- Statement options - set with SQLSetStmtOptions and SQLSetConnectOptions.
- * Transactions - if autocommit.

* These states should be protected by a thread-safe ODBC Driver

The next section, Effective Use of ODBC in Multi-Threaded Environments, provides application techniques for sharing ODBC handles between threads.

Return to Contents Page: ODBC Thread Safety Return to Issues Page