诊断记录和字段

适用于：SQL Server Azure SQL 数据库 Azure SQL 托管实例 Azure Synapse Analytics Analytics 平台系统（PDW）

诊断记录与 ODBC 环境、连接、语句或描述符句柄关联。 当任何 ODBC 函数产生的返回代码不是 SQL_SUCCESS 或 SQL_INVALID_HANDLE 时，该函数调用的句柄就有相关联的诊断记录，其中包含信息性或错误性消息。 这些记录会一直保留，直到要通过该句柄调用其他函数，那时，记录就会被丢弃。 与一个句柄任一次调用相关联的诊断记录数目不受限制。

有两种类型的诊断记录：标题和状态。 标题记录为记录 0；状态记录为记录 1 及更大数字。 诊断记录包含适用于标题记录和状态记录的不同字段。 ODBC 组件还可以定义自己的诊断记录字段。

标题记录中的字段包含有关函数执行的一般信息，包括返回代码、行计数、状态记录数和所执行的语句的类型。 除非 ODBC 函数返回 SQL_INVALID_HANDLE，否则，总是会创建标题记录。 有关标头记录中字段的完整列表，请参阅 SQLGetDiagField。

状态记录中的字段包含关于 ODBC 驱动程序管理器、驱动程序或数据源返回的特定错误或警告的信息，包括 SQLSTATE、本机错误号、诊断消息、列号和行号。 仅当函数返回 SQL_ERROR, SQL_SUCCESS_WITH_INFO、SQL_NO_DATA、SQL_NEED_DATA 或 SQL_STILL_EXECUTING 时，才会创建状态记录。 有关状态记录中字段的完整列表，请参阅 SQLGetDiagField。

SQLGetDiagRec 将检索单个诊断记录及其 ODBC SQLSTATE、本机错误号和诊断消息字段。 此功能类似于 ODBC 2。xSQLError 函数。 ODBC 3 中最简单的错误处理函数。x 将从 RecNumber 参数设置为 1 开始重复调用 SQLGetDiagRec，并将 RecNumber 递增 1，直到 SQLGetDiagRec 返回SQL_NO_DATA。 这相当于 ODBC 2。x 应用程序调用 SQLError ，直到它返回SQL_NO_DATA_FOUND。

ODBC 3.x 支持比 ODBC 2 更多的诊断信息。x. 此信息存储在使用 SQLGetDiagField 检索的诊断记录中的其他字段中。

SQL Server Native Client ODBC 驱动程序具有可通过 SQLGetDiagField 检索的特定于驱动程序的诊断字段。 这些特定于驱动程序的字段的标签在 sqlncli.h 中定义。 使用这些标签检索与每个诊断记录关联的 SQL Server 状态、严重级别、服务器名称、过程名称和行号。 此外，sqlncli.h 包含驱动程序用来标识 Transact-SQL 语句的代码的定义，如果应用程序调用将 DIagIdentifier 设置为SQL_DIAG_DYNAMIC_FUNCTION_CODE的 SQLGetDiagField。

SQLGetDiagField 由 ODBC 驱动程序管理器使用它从基础驱动程序缓存的错误信息进行处理。 在成功连接之前，ODBC 驱动程序管理器不会缓存特定于驱动程序的诊断字段。 SQLGetDiagField 在成功完成连接之前调用它以获取特定于驱动程序的诊断字段时，将返回SQL_ERROR。 如果 ODBC 连接函数返回 SQL_SUCCESS_WITH_INFO，则该连接函数特定于驱动程序的诊断字段尚不可用。 只有在连接函数之后进行另一个 ODBC 函数调用后，才能开始 调用特定于驱动程序的诊断字段的 SQLGetDiagField 。

SQL Server Native Client ODBC 驱动程序报告的大多数错误只能使用 SQLGetDiagRec 返回的信息进行有效诊断。 不过，在有些情况下，特定于驱动程序的诊断字段返回的信息对于诊断错误非常重要。 使用 SQL Server Native Client ODBC 驱动程序为应用程序编写 ODBC 错误处理程序时，最好也使用 SQLGetDiagField 检索至少SQL_DIAG_SS_MSGSTATE和SQL_DIAG_SS_SEVERITY驱动程序特定的字段。 如果可以在 SQL Server 代码中的多个位置引发特定错误，SQL_DIAG_SS_MSGSTATE向Microsoft支持工程师指示错误，这有时有助于诊断问题。

另请参阅

处理错误和消息