ODBC诊断

请使用本指南配合 Microsoft ODBC 驱动 17 或 18。 它描述的是 ODBC 诊断约定;并不会定义特定于版本的原生错误映射。

ODBC函数返回描述该调用结果的代码。 诊断记录提供了更多细节。 应用程序接口(API)可以报告来自驱动程序管理器、驱动程序、数据源或多个组件的记录。 不要把返回码、SQLSTATE、本地错误码和消息视为可以相互替代的内容。

解释返回码

在处理输出或决定是否重试前,先检查返回码。 对于 SQL_ERROR 和 SQL_SUCCESS_WITH_INFO,从函数使用的句柄获取诊断结果。 当功能契约允许时,其他返回码也可以包含诊断记录。

返回代码 含义与响应
SQL_SUCCESS 函数成功完成。 检查该函数的输出约定。
SQL_SUCCESS_WITH_INFO 该函数已完成,但有警告信息。 检索每条诊断记录,并检查输出是否完整、已转换或被截断。
SQL_ERROR 此函数失败。 在调用同一句柄上的另一个函数之前,先检索所有诊断记录。
SQL_INVALID_HANDLE 该函数检测到空句柄或错误类型的句柄。 ODBC不提供该返回代码的诊断记录。 查看函数参考,了解其他句柄要求。
SQL_NO_DATA 该操作已无更多可用数据。 检查函数引用,因为含义和任何状态记录都依赖于函数。

有关完整返回代码约定的更多信息,请参见ODBC 返回代码。

检索所有诊断记录

从记录编号 1 开始,为状态记录调用 SQLGetDiagRec。 继续直到函数返回 SQL_NO_DATA,或通过调用 SQLGetDiagField 来 SQL_DIAG_NUMBER读取首部记录0的记录计数。 SQLGetDiagRec 返回记录的SQLSTATE、本地错误代码和消息文本。 需要其他头部或记录字段时使用 SQLGetDiagField 。

不要在第一条记录后停下来。 ODBC组件可以添加包含自身层信息的状态记录,同时保留来自其他组件的诊断数据。 记录顺序和内容有助于识别错误的来源。

请及时收集这些记录。 使用相同句柄的后续 ODBC 调用会替换其诊断区域,但调用 SQLGetDiagRec、SQLGetDiagField 和旧版 SQLError 函数除外。 在新代码中使用 SQLGetDiagRec 和 SQLGetDiagField。

当其消息缓冲区过小时,SQLGetDiagRec 可以返回 SQL_SUCCESS_WITH_INFO。 记录被返回,但其消息文本被截断。 检查报告的文本长度,如果需要全文,请用更大的缓冲区取回消息。 不要把这个返回 SQLGetDiagRec 码和原ODBC函数的返回码混淆。

有关诊断检索的更多信息,请参见 诊断记录、使用 SQLGetDiagRec 和 SQLGetDiagField 以及 SQLGetDiagRec 和 SQLGetDiagField 参考。

在 C++ 中收集诊断记录

使用这个 C++11 辅助工具,同时使用已有的 ODBC 句柄。 它调用 SQLGetDiagRecW 来收集 SQLSTATE、本地错误代码和 Unicode 消息文本并存储在内存中,但不会记录这些消息。

#ifdef _WIN32
#include <windows.h>
#endif
#include <sql.h>
#include <sqlext.h>
#include <algorithm>
#include <limits>
#include <stdexcept>
#include <string>
#include <utility>
#include <vector>

struct DiagnosticRecord {
    std::string sqlstate;
    SQLINTEGER native_error;
    std::vector<SQLWCHAR> message;
    bool message_truncated;
};

std::vector<DiagnosticRecord> ReadDiagnostics(SQLSMALLINT type, SQLHANDLE handle) {
    const SQLSMALLINT limit = (std::numeric_limits<SQLSMALLINT>::max)();
    std::vector<DiagnosticRecord> records;
    for (SQLINTEGER number = 1; ; ++number) {
        if (number > limit) {
            throw std::runtime_error("Diagnostic record number exceeds SQLSMALLINT.");
        }
        SQLWCHAR state[6] = {};
        SQLINTEGER native = 0;
        std::vector<SQLWCHAR> message(256);
        auto read = [&]() {
            return SQLGetDiagRecW(type, handle, static_cast<SQLSMALLINT>(number),
                state, &native, message.data(),
                static_cast<SQLSMALLINT>(message.size()), nullptr);
        };

        SQLRETURN result = read();
        if (result == SQL_NO_DATA) {
            return records;
        }
        if (result == SQL_SUCCESS_WITH_INFO) {
            message.resize(limit);
            result = read(); // Retrieve the same record, not the next one.
        }
        if (result != SQL_SUCCESS && result != SQL_SUCCESS_WITH_INFO) {
            throw std::runtime_error("SQLGetDiagRecW couldn't retrieve a diagnostic record.");
        }
        message.erase(std::find(message.begin(), message.end(), SQLWCHAR{0}), message.end());
        records.push_back({
            std::string(state, state + 5),
            native,
            std::move(message),
            result == SQL_SUCCESS_WITH_INFO
        });
    }
}

辅助工具会以 SQLGetDiagRecW 可接受的最大正缓冲区长度重试一个截断消息。 如果消息仍然不适合,它会保留可用的文本并设置 message_truncated。 它会继续到下一条记录,而不是把截断视为诊断列表的末尾。 如果检索失败或记录编号超出 API 的 SQLSMALLINT 范围,它会抛出异常。

每个消息包含 SQLWCHAR 个代码单元,不包括空终止符。 不要把它们重新解释为 wchar_t,因为不同类型可能有不同的宽度。 当你需要处理或显示消息时,将它们转换为应用程序使用的文本编码。

在返回错误或警告的操作之后立即调用辅助函数。 该片段假设 statement 是一个有效且已准备好的语句句柄,并且异步执行被禁用:

#include <iostream>

SQLRETURN ExecuteWithDiagnostics(SQLHSTMT statement) {
    SQLRETURN result = SQLExecute(statement);
    if (result == SQL_ERROR || result == SQL_SUCCESS_WITH_INFO) {
        const auto records = ReadDiagnostics(SQL_HANDLE_STMT, statement);
        for (const auto& record : records) {
            std::cerr << "SQLExecute: SQLSTATE=" << record.sqlstate
                      << " native_error=" << record.native_error
                      << " message_truncated=" << record.message_truncated << '\n';
        }
    } else if (result == SQL_INVALID_HANDLE) {
        throw std::runtime_error("SQLExecute returned SQL_INVALID_HANDLE.");
    }
    return result;
}

包装器保留原始返回码,包括 SQL_SUCCESS_WITH_INFO。 将相同的模式应用于其他ODBC调用,使用与该操作相关的句柄类型和句柄。 根据该函数的约定处理其他返回代码。

输出故意省略 record.message。 如果你需要日志中的消息文本,写入前请根据应用的数据策略进行脱敏处理。 帮助程序不会对内存中保存的消息进行清理。

阅读诊断字段

这些字段回答不同的问题:

领域 它告诉你什么
SQLSTATE 一个五字符代码,用于识别一种标准化的诊断状况。 它的类别是前两个字符。
本地错误代码 一个特定于数据源或ODBC组件的值。 它不是通用的错误编号,也不应该假设它是 SQL Server 的错误编号。
消息文本 便于阅读的说明。 用 SQLSTATE 和本地错误码一起阅读;不要把它当作一个稳定的机器可读约定来解析。

驱动程序管理器、驱动程序和数据源各自可以生成诊断结果。 添加记录的组件不得替换或掩盖其他组件的错误或警告。 原生错误代码可能不可用,或者对组件生成的诊断没有有用的意义。 有关组件规则的更多信息,请参见 诊断处理规则。 有关 SQLSTATE 类和值的更多信息,请参见 SQLSTATEs。

将记录与函数返回码和操作一起使用。 例如,SQL_SUCCESS_WITH_INFO 表示该函数已完成,但并不保证每个输出值都是完整的。 截断警告要求你检查返回的数据长度,并决定是否检索剩余数据。 更多信息请参见 数据长度、缓冲区长度和截断。

收集可靠的证据

对于支持案例,记录函数名称、句柄类型、返回码以及所有诊断记录。 包括驱动程序和驱动程序管理器版本、操作系统、架构和数据源类型。 在保存或共享输出之前,先编辑凭据、访问令牌、连接字符串机密、查询文本、参数值以及个人或受控的数据。 诊断消息和跟踪日志可以包含应用数据。

将跟踪范围限制在你所需的最短复现过程内。 日志存储在仅运行该应用的账户可访问的目录中,并使用显式日志路径而非共享或临时默认。 复制结束后停止跟踪,等不需要时再移除该跟踪文件。

选择描摹图层

应用诊断和追踪回答了不同的问题:

层 它捕获的内容 将其用于
应用程序诊断 来自单个ODBC呼叫的返回代码和诊断记录 识别失败或返回警告的函数,并保留其所有诊断字段。
ODBC 驱动管理器跟踪 应用程序、驱动程序管理器和驱动程序之间的ODBC API调用 看看应用程序发出了哪些调用,以及返回了哪些返回代码。 跟踪参数可以暴露敏感值。
驱动程序特定跟踪 内部驱动程序事件,前提是驱动程序记录了受支持的控件 调查 API 追踪无法显示的驱动程序行为。 不要假设驱动程序管理器跟踪会启用此功能。

在 Windows 上,ODBC 驱动程序管理器支持通过 ODBC 数据源管理员中的追踪选项卡以及 SQL_ATTR_TRACE 和 SQL_ATTR_TRACEFILE 属性进行追踪。 追踪默认是按用户进行的。 全机追踪需要本地管理员权限,并且可以捕获以其他本地身份运行的应用程序的调用。 更倾向于按用户追踪,问题复现结束后立即停止。 更多信息请参见 设置追踪选项、 启用追踪和 SQLSetConnectAttr。

在 Linux 和 macOS 上,请参阅在 Linux 和 macOS 上使用 ODBC 驱动程序进行数据访问跟踪,了解 unixODBC 驱动程序管理器配置。

现有的 Linux 和 macOS 编程指南 保留了一项历史声明,即在 ODBC 驱动程序 17.3 之前,内置诊断(BID)跟踪未经过验证。 那条说明并没有描述当前驱动特有的追踪控制。 unixODBC 过程捕获的是驱动程序管理器的 API 调用,而不是 BID 事件。