请使用本指南配合 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 事件。