Multi-threading Issues in the Adapter and Client Applications

[This is preliminary documentation and subject to change.]

Since the ODBC Driver Manager is thread-safe, the adapter is inherently thread-safe.

The only exception to this is where an SQLCancel is invoked on synchronously executing the statement handle hStmt object from a different thread. The Driver Manager uses critical sections (non-reentrant pieces of code) on the environment handle hEnvs, the connection handle hDbcs, and hStmts to guarantee synchronous operation on these objects.

An action on one of these objects causes the Driver Manager to enter a critical section for that object. In the case of SQLCancel, the Driver Manager enters a "cancel-in-progress" critical section. This prevents SQLCancel from being reentered before the first one is completed. The adapter's SQLCancel is then invoked.

If there is no simultaneous action on the statement handle, the SQLCancel is treated as an SQLFreeStmt or SQL_CLOSE operation. The adapter returns SQL_SUCCESS_WITH_INFO with a SQLSTATE of 01S05. This causes the Driver Manager to return SQL_SUCCESS to the application.

If there was simultaneous action on the statement handle, the return code from the original thread's ODBC function determines if the SQLCancel was successful.

The adapter's SQLCancel is implemented as follows:

1. In the adapter, each statement has a critical section.
2. This critical section is entered on all ODBC functions that take a statement handle (except SQLCancel), and is left upon exit.
3. The SQLCancel code inspects this critical section to determine if it has been entered (non-zero owning thread). This is the test for determining if an SQLFreeStmt/SQL_CLOSE needs to be called.
4. If there is activity on the statement, the adapter sets a CANCEL flag on the statement handle, which the original thread periodically checks for to determine if it needs to cancel the operation, however it deems appropriate.

The ODBC 2.0 Programmer's Reference and SDK Guide suggests two techniques for writing thread-safe multithreaded ODBC applications:

• Have multiple statement handles on a single connection handle, with a single thread per statement handle.
• Have multiple connection handles, with a single statement handle per connection handle and a single thread per connection handle.

The application must know which operations are being performed on an object. For example, if a thread does an SQLFetch on a statement handle, begins to process the data, and a second thread does an SQLFetch on the same statement handle into the same buffer, the first thread might get columns from the first row of the rowset mixed with columns from the second row.

Also, the application must be particularly careful in performing SQLFreeStmts. For example, if an application attempts to perform an operation on a statement handle that is being freed, it blocks on the statement handle. When it unblocks, it fails with an access violation because the statement handle no longer exists. The application must ensure that the statement handle is inactive before calling SQLFreeStmt, SQL_DROP, or SQLDisconnect.

See Also

ODBC Handles