How the driver classifies and reports responses

graph TD
    A["Response from the service or dropped connection"] --> B{"HTTP status"}
    B -->|"2xx"| C{"Shape matches the request?"}
    C -->|"yes"| D["Result: rows, count, or affected records"]
    C -->|"no"| X["08S01: response unusable"]
    B -->|"401, 403 with challenge"| H["Ask for code or identity, send the request again once"]
    B -->|"4xx with database messages"| E["one diagnostic record per message with number and SQLSTATE"]
    B -->|"other 4xx, 5xx, 504"| F["one diagnostic record with the HTTP status as the number"]
    A -->|"connection dropped"| W["retry where harmless; otherwise 08S01"]

Figure: The driver decides first by the HTTP status, then by the shape that's to be expected for the request made. The content and shape of a success are described in How an OData service becomes a relational ODBC model.

An HTTP response isn't automatically a result in the ODBC sense: it can carry data, a rejection by the service, database messages, or a shape that the driver can't make use of. This page specifies, for every class of response, which return value the application receives, which diagnostic records (SQLSTATE, native error number, text) are created, and what state the statement and connection are in afterward.

• Success only with a matching shape: a 200 with unreadable or unexpected content isn't a success.
• Database messages as over a direct connection: number, SQLSTATE, and text per message.
• No invented results: a response that broke off or was truncated by the service isn't reported as complete.

A response that has one of these shapes but carries one field more than expected counts as matching: the driver skips unknown fields and annotations. That keeps it compatible with later versions of a service, but has a consequence that's listed under Limits.

Why 08S01 for an unusable response. ODBC has no SQLSTATE of its own for “the peer isn't responding according to the protocol”. 08S01 (“Communication link failure”) tells the application what to do: the statement itself isn't wrong, the peer is; a retry with the same statement can succeed once the service responds correctly again. The message distinguishes this case from a network failure.

ODBC reports a warning as SQL_SUCCESS_WITH_INFO with a diagnostic record of class 01. This driver generates warnings only itself:

Informational messages from the database on success don't reach the application. If the database sends a message with a successful statement (in SQL Server, for example PRINT or RAISERROR with severity up to 10), the application receives SQL_SUCCESS_WITH_INFO with this message through the SQL Server driver. Through this driver, SQL_SUCCESS arrives without it: the data service Wkl.Data.Gateway passes messages on only with a rejection, and the driver reads none in a successful response. An accompanying informational message with a rejection (SQLSTATE 01000), by contrast, appears as a further diagnostic record of the error.

If the connection drops without a response, the driver retries after 1 and after 3 seconds: reads always, changes and custom statements read as a whole with the same Idempotency-Key. Not retried are an exceeded time limit, the commit of a transaction, and a streamed custom statement; with RETRY=OFF, nothing at all. When this is safe for which service is described under Commitments per kind of service.

The text of a diagnostic record follows the display language of the Windows user the application runs as: German, Slovenian, or else English; so do the driver's dialogs. What counts is Windows, not a language that an application such as Office sets for itself. The SQLSTATE and the native error number are the same in every language – an application that evaluates errors checks those, not the text. Messages of the service and of the database are passed on unchanged, in the language they were written in there. The trace's own lines stay German; a diagnostic record appears there (DIAG) as the application received it. An application that reads messages narrow (SQLGetDiagRecA) receives them in its ANSI code page; Slovenian letters (č, š, ž) exist only in code page 1250 (Central European), the ANSI code page of a Slovenian Windows.

• "The service cut the result off after N rows" – what to do
• "The service redirects to …" – what to do
• How an OData service becomes a relational ODBC model
• How the driver translates statements: Database messages – how Access, DAO, and ADO.NET show the records
• Limits: Differences from ODBC Driver 18
• Turn on tracing – find the message behind an error