docs: state the real HY008 contract on all 32 entry points

Every one claimed the state could not arise, on one of two false grounds: that
"the Backend trait is synchronous", which says nothing about another thread
cancelling, or that it was (DM)-handled, which the spec contradicts -- the
HY008 row carries no (DM) marker on any of these pages.

Each now names which of the row's two clauses applies, in one of three shapes:
the call reclassifies (18), it is connection-level and has no token to observe
(6), or it makes no fallible backend call for a cancellation to be reported
through (8). SQLDescribeCol and SQLColAttribute get their own wording: they do
reach a fallible call, but its map_err replaces any error with 07009, so a
cancellation is indistinguishable from a bad column number by the time core
sees it.

Classifying each function rather than pattern-matching turned up one the design
missed: SQLDescribeParam makes a fallible backend call and has a token in
reach, so it is wired here rather than documented as exempt.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: maltesander

AGENTS.md

@@ -610,6 +610,26 @@ mechanism:
   cross-thread branch, so a merely-idle statement's data-at-execution state
   is occasionally left uncleared where it strictly could have been —
   harmless, and explicitly spec-legal.
+- **A cancelled call reports `HY008`, and the token is minted per execution.**
+  `Backend::cancel` signals; `Backend::is_cancelled` observes. They are a pair —
+  a backend implementing the first and not the second still cancels the work,
+  but the application sees whatever SQLSTATE the driver's error mapping
+  produced instead of "operation canceled". Core asks `is_cancelled` **only
+  after a backend call returned an error**: the spec permits a cancelled
+  execution to finish anyway ("it is possible for the execution to succeed and
+  return SQL_SUCCESS while the cancel is also successful"), so `Ok` is never
+  reclassified. The single implementation is `crate::cancel`.
+
+  `mint_cancel_token` builds a **new** token at every statement-producing call,
+  and the cursor-consuming calls read that execution's token rather than
+  minting one. An earlier revision created one token per statement and never
+  replaced it, which left a cancelled statement permanently unusable —
+  `Backend::cancel` marks the token, and the next execution reused it. The spec
+  requires the opposite ("After the statement has been canceled, the
+  application can call SQLExecute or SQLExecDirect again"), and the outcome
+  that rule was protecting against is itself spec-mandated: "a call to
+  SQLCancel when no processing is being done on the statement ... has is [sic]
+  no effect at all."
 - **Every lock in the crate is imported from `src/sync.rs`**, never directly
   from `std::sync`, so that building a test with `--cfg loom` swaps every one
   of them for loom's instrumented equivalent. A lock imported around that

CHANGELOG.md

@@ -797,6 +797,19 @@ Everything a driver has to change for the catalog rework, in one place.
 
 ### Fixed
 
+- The 32 `HY008` doc comments across `src/ffi/` claimed the state could not
+  arise, on one of two false grounds: that "the `Backend` trait is synchronous"
+  — which says nothing about another thread cancelling — or that it was
+  `(DM)`-handled, which the spec contradicts, since its `HY008` row carries no
+  `(DM)` marker on any of these pages. Each now states which of the row's two
+  clauses applies and why, in one of three shapes: the call reclassifies, it is
+  connection-level and has no token to observe, or it makes no fallible backend
+  call for a cancellation to be reported through.
+
+- `SQLDescribeParam` now returns `HY008` on a cross-thread cancel.
+  `Backend::describe_param` is a fallible backend call, so a backend answering
+  it over the wire could be cancelled mid-lookup and reported `HY000`.
+
 - `SQLAllocHandle` returned a bare `SQL_ERROR` with no diagnostic for
   `SQL_HANDLE_DESC` and `SQL_HANDLE_DBC_INFO_TOKEN`. It now posts `HYC00`, which
   this function's diagnostics table lists un-annotated for exactly that case.

src/ffi/connect.rs

@@ -52,8 +52,11 @@ use crate::utf16::{utf16_to_string, write_utf16};
 /// - 28000: Invalid authorization specification — may be returned by the backend via `B::connect`.
 /// - HY000: General error — returned for any backend error with no specific SQLSTATE.
 /// - HY001: Memory allocation failure — not returned here (Rust panics on alloc failure).
-/// - HY008: Operation cancelled (async) — (driver-manager-handled; not returned here);
-///   the `Backend` trait has no async connection path.
+/// - HY008: Operation canceled; not returned here. Cancelling a connection-level call needs
+///   `SQLCancelHandle` on a connection handle, which this driver does not export, so no cancel
+///   token exists for this call to observe — `SQLCancel` takes a statement handle and cannot
+///   reach one. The asynchronous clause is likewise inapplicable: core never returns
+///   `SQL_STILL_EXECUTING`.
 /// - HY009: Invalid use of null pointer — returned when `in_connection_string` is null.
 /// - HY010: Function sequence error (async in progress) — (driver-manager-handled; not returned here).
 /// - HY013: Memory management error — not returned here (Rust panics on alloc failure).
@@ -207,8 +210,11 @@ pub unsafe fn sql_driver_connect_w<B: Backend>(
 /// - 28000: Invalid authorization specification — may be returned by the backend via `B::connect`.
 /// - HY000: General error — returned for any backend error with no specific SQLSTATE.
 /// - HY001: Memory allocation failure — (driver-manager-handled; not returned here).
-/// - HY008: Operation cancelled (async) — (driver-manager-handled; not returned here);
-///   the `Backend` trait has no async connection path.
+/// - HY008: Operation canceled; not returned here. Cancelling a connection-level call needs
+///   `SQLCancelHandle` on a connection handle, which this driver does not export, so no cancel
+///   token exists for this call to observe — `SQLCancel` takes a statement handle and cannot
+///   reach one. The asynchronous clause is likewise inapplicable: core never returns
+///   `SQL_STILL_EXECUTING`.
 /// - HY010: Function sequence error (async in progress) — (driver-manager-handled; not returned here).
 /// - HY013: Memory management error — not returned here (Rust panics on alloc failure).
 /// - HY090: Invalid string or buffer length — returned when `name_length1`, `name_length2`, or
@@ -370,8 +376,11 @@ pub unsafe fn sql_connect_w<B: Backend>(
 /// - 28000: Invalid authorization specification — may be returned by the backend via `B::connect`.
 /// - HY000: General error — returned for any backend error with no specific SQLSTATE.
 /// - HY001: Memory allocation failure — not returned here (Rust panics on alloc failure).
-/// - HY008: Operation cancelled (async) — (driver-manager-handled; not returned here);
-///   the `Backend` trait has no async connection path.
+/// - HY008: Operation canceled; not returned here. Cancelling a connection-level call needs
+///   `SQLCancelHandle` on a connection handle, which this driver does not export, so no cancel
+///   token exists for this call to observe — `SQLCancel` takes a statement handle and cannot
+///   reach one. The asynchronous clause is likewise inapplicable: core never returns
+///   `SQL_STILL_EXECUTING`.
 /// - HY009: Invalid use of null pointer — returned when `in_connection_string` is null.
 /// - HY010: Function sequence error (async in progress) — (driver-manager-handled; not returned here).
 /// - HY013: Memory management error — not returned here (Rust panics on alloc failure).
@@ -683,7 +692,11 @@ fn read_dsn_keys(dsn: &str) -> Vec<(String, String)> {
 ///   which is not currently tracked. Deferred.
 /// - HY000: General error — returned for any backend `disconnect` error with no specific SQLSTATE.
 /// - HY001: Memory allocation failure — not returned here (Rust panics on alloc failure).
-/// - HY008: Operation cancelled (async) — not returned here (the `Backend` trait is synchronous).
+/// - HY008: Operation canceled; not returned here. Cancelling a connection-level call needs
+///   `SQLCancelHandle` on a connection handle, which this driver does not export, so no cancel
+///   token exists for this call to observe — `SQLCancel` takes a statement handle and cannot
+///   reach one. The asynchronous clause is likewise inapplicable: core never returns
+///   `SQL_STILL_EXECUTING`.
 /// - HY010: Function sequence error (async in progress) — (driver-manager-handled; not returned here).
 /// - HY013: Memory management error — not returned here (Rust panics on alloc failure).
 /// - HY117: Connection suspended due to unknown transaction state — (driver-manager-handled; not returned here).

src/ffi/connect_attr.rs

@@ -155,7 +155,11 @@ fn validate_txn_isolation<B: Backend>(
 /// - HY000 General error: returned for unexpected internal errors.
 /// - HY001 Memory allocation error: not returned; Rust panics on allocation
 ///   failure, which is caught by `panic_safe` and converted to `SQL_ERROR`/HY000.
-/// - HY008 Operation canceled: not returned; the `Backend` trait is synchronous.
+/// - HY008: Operation canceled; not returned here. Cancelling a connection-level call needs
+///   `SQLCancelHandle` on a connection handle, which this driver does not export, so no cancel
+///   token exists for this call to observe — `SQLCancel` takes a statement handle and cannot
+///   reach one. The asynchronous clause is likewise inapplicable: core never returns
+///   `SQL_STILL_EXECUTING`.
 /// - HY009 Invalid use of null pointer: HY009 is not applicable here:
 ///   `SQL_ATTR_CURRENT_CATALOG` is the only string attribute handled, and null
 ///   means "clear the catalog" (a valid operation).

src/ffi/cursor.rs

@@ -44,7 +44,10 @@ static CURSOR_NAME_COUNTER: AtomicU32 = AtomicU32::new(1);
 /// - HY000 (general error): returned via `OdbcError::general` for unexpected failures.
 /// - HY001 (memory allocation error): not applicable; Rust allocation panics are caught by
 ///   `panic_safe`.
-/// - HY008 (operation canceled): (driver-manager-handled; not returned here)
+/// - HY008: Operation canceled; not returned here. This call makes no fallible backend call —
+///   `StatementBackend::column_count` returns a plain `i16` — so there is no error for a
+///   cancellation to be reported through. The asynchronous clause is inapplicable: core never
+///   returns `SQL_STILL_EXECUTING`.
 /// - HY010 (function sequence error): returned with SQLSTATE `HY010` when no result set is
 ///   available (statement not yet executed). The `(DM)` variants (async in progress, etc.) are
 ///   driver-manager-handled; not returned here.
@@ -208,7 +211,10 @@ pub unsafe fn sql_row_count<B: Backend>(
 /// - HY000 (general error): returned via `OdbcError::general` for unexpected failures.
 /// - HY001 (memory allocation error): not applicable; Rust allocation panics are caught by
 ///   `panic_safe`.
-/// - HY008 (operation canceled): (driver-manager-handled; not returned here)
+/// - HY008: Operation canceled; not returned here. This call makes no fallible backend call —
+///   `SQLMoreResults` is a core stub that reports `SQL_NO_DATA` without asking the backend — so
+///   there is no error for a cancellation to be reported through. The asynchronous clause is
+///   inapplicable: core never returns `SQL_STILL_EXECUTING`.
 /// - HY010 (function sequence error): (driver-manager-handled; not returned here)
 /// - HY013 (memory management error): not applicable; Rust memory access cannot fail silently.
 /// - HY117 (connection suspended): (driver-manager-handled; not returned here)
@@ -684,7 +690,10 @@ pub unsafe fn sql_set_cursor_name_w<B: Backend>(
 /// - HY000 (general error): returned via `OdbcError::general` for unexpected failures.
 /// - HY001 (memory allocation error): not applicable; Rust allocation panics are caught by
 ///   `panic_safe`.
-/// - HY008 (operation canceled): (driver-manager-handled; not returned here)
+/// - HY008: Operation canceled; not returned here. This call makes no fallible backend call —
+///   `SQLBulkOperations` reports `HYC00` without asking the backend — so there is no error for a
+///   cancellation to be reported through. The asynchronous clause is inapplicable: core never
+///   returns `SQL_STILL_EXECUTING`.
 /// - HY010 (function sequence error): (driver-manager-handled; not returned here)
 /// - HY011 (attribute cannot be set now): not applicable.
 /// - HY013 (memory management error): not applicable; Rust memory access cannot fail silently.
@@ -786,7 +795,10 @@ pub unsafe fn sql_bulk_operations<B: Backend>(
 /// - HY000 (general error): returned via `OdbcError::general` for unexpected failures.
 /// - HY001 (memory allocation error): not applicable; Rust allocation panics are caught by
 ///   `panic_safe`.
-/// - HY008 (operation canceled): (driver-manager-handled; not returned here)
+/// - HY008: Operation canceled; not returned here. This call makes no fallible backend call —
+///   `SQLSetPos` reports `HYC00` without asking the backend — so there is no error for a
+///   cancellation to be reported through. The asynchronous clause is inapplicable: core never
+///   returns `SQL_STILL_EXECUTING`.
 /// - HY010 (function sequence error): (driver-manager-handled; not returned here)
 /// - HY011 (attribute cannot be set now): not applicable.
 /// - HY013 (memory management error): not applicable; Rust memory access cannot fail silently.

src/ffi/execute.rs

@@ -70,7 +70,13 @@ use crate::utf16::utf16_to_string;
 /// - 44000: WITH CHECK OPTION violation — propagated from backend.
 /// - HY000: General error — propagated from backend.
 /// - HY001: Memory allocation error — propagated from backend.
-/// - HY008: Operation canceled — (driver-manager-handled; not returned here).
+/// - HY008: Operation canceled. The row's first clause — asynchronous processing, then the
+///   function called again — is not applicable: core implements no asynchronous execution and
+///   never returns `SQL_STILL_EXECUTING`. The second clause, `SQLCancel` called on the
+///   statement "from a different thread in a multithread application", **is returned by this
+///   driver**: the row carries no `(DM)` marker, and when a backend call fails with
+///   `Backend::is_cancelled` reporting its token signalled, core reports `HY008` in place of
+///   the backend's own SQLSTATE.
 /// - HY009: Invalid use of null pointer — fails if `StatementText` is null (checked here).
 /// - HY010: Function sequence error — (DM cases for async/NEED_DATA: driver-manager-handled; not
 ///   returned here); fails if the connection is not open (checked here).
@@ -270,7 +276,13 @@ pub unsafe fn sql_exec_direct_w<B: Backend>(
 /// - 42S22: Column not found — propagated from backend.
 /// - HY000: General error — propagated from backend.
 /// - HY001: Memory allocation error — propagated from backend.
-/// - HY008: Operation canceled — (driver-manager-handled; not returned here).
+/// - HY008: Operation canceled. The row's first clause — asynchronous processing, then the
+///   function called again — is not applicable: core implements no asynchronous execution and
+///   never returns `SQL_STILL_EXECUTING`. The second clause, `SQLCancel` called on the
+///   statement "from a different thread in a multithread application", **is returned by this
+///   driver**: the row carries no `(DM)` marker, and when a backend call fails with
+///   `Backend::is_cancelled` reporting its token signalled, core reports `HY008` in place of
+///   the backend's own SQLSTATE.
 /// - HY009: Invalid use of null pointer — fails if `StatementText` is null (checked here).
 /// - HY010: Function sequence error — (DM cases for async/NEED_DATA: driver-manager-handled; not
 ///   returned here); fails if the connection is not open (checked here).
@@ -433,7 +445,13 @@ pub unsafe fn sql_prepare_w<B: Backend>(
 /// - 44000: WITH CHECK OPTION violation — propagated from backend.
 /// - HY000: General error — propagated from backend.
 /// - HY001: Memory allocation error — propagated from backend.
-/// - HY008: Operation canceled — (driver-manager-handled; not returned here).
+/// - HY008: Operation canceled. The row's first clause — asynchronous processing, then the
+///   function called again — is not applicable: core implements no asynchronous execution and
+///   never returns `SQL_STILL_EXECUTING`. The second clause, `SQLCancel` called on the
+///   statement "from a different thread in a multithread application", **is returned by this
+///   driver**: the row carries no `(DM)` marker, and when a backend call fails with
+///   `Backend::is_cancelled` reporting its token signalled, core reports `HY008` in place of
+///   the backend's own SQLSTATE.
 /// - HY010: Function sequence error — (DM cases for async/NEED_DATA: driver-manager-handled; not
 ///   returned here); fails if no SQL has been prepared (checked here); fails if
 ///   the connection is not open (checked here).

src/ffi/fetch.rs

@@ -133,7 +133,13 @@ unsafe fn report_rows_fetched_only<B: Backend>(stmt: &StatementHandle<B>, count:
 /// - 40003 (statement completion unknown): propagated from the backend.
 /// - HY000 (general error): propagated from the backend.
 /// - HY001 (memory allocation error): not returned; Rust panics on allocation failure.
-/// - HY008 (operation canceled): not applicable; the `Backend` trait is synchronous.
+/// - HY008: Operation canceled. The row's first clause — asynchronous processing, then the
+///   function called again — is not applicable: core implements no asynchronous execution and
+///   never returns `SQL_STILL_EXECUTING`. The second clause, `SQLCancel` called on the
+///   statement "from a different thread in a multithread application", **is returned by this
+///   driver**: the row carries no `(DM)` marker, and when a backend call fails with
+///   `Backend::is_cancelled` reporting its token signalled, core reports `HY008` in place of
+///   the backend's own SQLSTATE.
 /// - HY010 (function sequence error): returned when `stmt.statement` is `None`, i.e. no
 ///   result set is open. (DM) variants (async context, `SQLExtendedFetch` mixing) are
 ///   driver-manager-handled; not returned here.
@@ -347,7 +353,13 @@ pub unsafe fn sql_fetch<B: Backend>(statement_handle: *mut c_void) -> SqlReturn
 /// - 40001, 40003: delegated to `sql_fetch`.
 /// - HY000 (general error): propagated from the backend.
 /// - HY001 (memory allocation error): not returned; Rust panics on allocation failure.
-/// - HY008 (operation canceled): not applicable; the `Backend` trait is synchronous.
+/// - HY008: Operation canceled. The row's first clause — asynchronous processing, then the
+///   function called again — is not applicable: core implements no asynchronous execution and
+///   never returns `SQL_STILL_EXECUTING`. The second clause, `SQLCancel` called on the
+///   statement "from a different thread in a multithread application", **is returned by this
+///   driver**: the row carries no `(DM)` marker, and when a backend call fails with
+///   `Backend::is_cancelled` reporting its token signalled, core reports `HY008` in place of
+///   the backend's own SQLSTATE.
 /// - HY010 (function sequence error): delegated to `sql_fetch` for `SQL_FETCH_NEXT`. (DM)
 ///   variants are driver-manager-handled; not returned here.
 /// - HY013 (memory management error): not returned.
@@ -502,7 +514,13 @@ pub unsafe fn sql_fetch_scroll<B: Backend>(
 /// - HY003 (program type out of range): returned both when `target_type` is not a recognized C
 ///   data type, and via `write_column_value`'s numeric-pivot catch-all for a `CDataType` with no
 ///   numeric arm. (DM) variants (column 0 with wrong bookmark type) are driver-manager-handled.
-/// - HY008 (operation canceled): not applicable; the `Backend` trait is synchronous.
+/// - HY008: Operation canceled. The row's first clause — asynchronous processing, then the
+///   function called again — is not applicable: core implements no asynchronous execution and
+///   never returns `SQL_STILL_EXECUTING`. The second clause, `SQLCancel` called on the
+///   statement "from a different thread in a multithread application", **is returned by this
+///   driver**: the row carries no `(DM)` marker, and when a backend call fails with
+///   `Backend::is_cancelled` reporting its token signalled, core reports `HY008` in place of
+///   the backend's own SQLSTATE.
 /// - HY009 (invalid use of null pointer): not checked; `target_value_ptr` null is not
 ///   validated. (DM) — driver-manager-handled.
 /// - HY010 (function sequence error): driver-manager-handled; not returned here.