SQLGetDiagRec －获取诊断记录的多个字段设置

用途

规范：

DB2 CLI 5.0

ODBC 3.0

SQLGetDiagRec() 返回包含错误、警告和状态信息的诊断记录的 SQLSTATE 字段当前值。

在调用此函数之前，必须使用 SQLAllocHandle() 分配连接句柄。

语法

SQLRETURN   SQLGetDiagRec    (SQLSMALLINT       HandleType,
                              SQLHANDLE         Handle,
                              SQLSMALLINT       RecNumber,
                              SQLCHAR           *SQLState,
                              SQLINTEGER        *NativeErrorPtr,
                              SQLCHAR           *MessageText,
                              SQLSMALLINT       BufferLength,
                              SQLSMALLINT       *TextLengthPtr);

函数自变量

表 68. SQLGetDiagRec 自变量

数据类型	自变量	使用	描述
SQLSMALLINT	`HandleType`	输入	句柄类型标识，它描述期望诊断的句柄的类型。可以是 SQL_HANDLE_STMT 或 SQL_HANDLE_DBC。
SQLHANDLE	`Handle`	输入	具有 `HandleType` 所指示类型的诊断数据结构的句柄。
SQLSMALLINT	`RecNumber`	输入	指示应用程序从中查找信息的状态记录。状态记录必须是 1。
SQLCHAR	`SQLState`	输出	指向一个缓冲区的指针，关于诊断记录 `RecNumber` 的 5 字符 SQLSTATE 代码将在这个缓冲区中返回。前两个字符指示类；接着的 3 个字符指示子类。
SQLINTEGER	`NativeErrorPtr`	输出	指向一个缓冲区的指针，特定于数据源的本机错误码将在此缓冲区中返回。
SQLCHAR	`MessageText`	输出	指向一个缓冲区的指针，错误消息正文将在此缓冲区中返回。`SQLGetDiagRec()` 返回的字段包含在一个文本字符串中。
SQLINTEGER	`BufferLength`	输入	`MessageText` 缓冲区的长度（以字节计）。
SQLSMALLINT	`TextLengthPtr`	输出	指向一个缓冲区的指针，可以在 `MessageText` 中返回的总字节数（不包括 null 终止符所需的字节数）将在此缓冲区中返回。如果可供返回的字节数大于 `BufferLength`，则 `MessageText` 中的错误消息正文被截断为 `BufferLength` 减去 null 终止字符的长度。

用法

应用程序通常在先前 DB2 CLI 函数调用返回除 SQL_SUCCESS 外的任何内容时调用 SQLGetDiagRec()。

SQLGetDiagRec() 返回包含诊断数据结构记录的多个字段的字符串。

在 DB2 Everyplace 的版本 8.1 扩展了 SQLGetDiagRec() 的功能。现在可以返回下列 SQLSTATE：57011、HY024、HY092、HY000 和 HY012。有关这些 SQLSTATE 的更多信息，请参阅SQLState 列表。

SQLGetDiagRec() 只检索最近与 Handle 自变量中指定的句柄相关联的诊断信息。如果应用程序调用除 SQLGetDiagRec() 外的任何函数，则对同一句柄的先前调用所返回的任何诊断信息丢失。

HandleType 自变量

每种句柄类型都可以有与之相关联的诊断信息。HandleType 自变量指示 Handle 的句柄类型。DB2 Everyplace 支持语句句柄和连接句柄。

返回码

SQL_SUCCESS
SQL_SUCCESS_WITH_INFO
SQL_ERROR
SQL_INVALID_HANDLE

诊断

SQLGetDiagRec() 不向自己公布错误值。它使用下列返回值来报告它自己的执行结果：

SQL_SUCCESS

函数成功返回了诊断信息。

SQL_SUCCESS_WITH_INFO

MessageText 缓冲区太小，无法存放请求的诊断消息。未生成诊断记录。要确定是否发生了截断，应用程序必须将 BufferLength 与可用的实际字节数作比较（该字节数被写至 StringLengthPtr）。

SQL_INVALID_HANDLE

HandleType 和 Handle 指示的句柄不是有效的句柄。

SQL_ERROR

发生了下列其中一种情况：

RecNumber 是负数或 0。
BufferLength 小于 0。

SQL_NO_DATA

RecNumber 大于对 Handle 中指定的句柄存在的诊断记录数。如果没有 Handle 的诊断记录，则此函数还对任何正的 RecNumber 返回 SQL_NO_DATA。

限制

无。

相关参考

SQLGetDiagRec － 获取诊断记录的多个字段设置

SQLGetDiagRec －获取诊断记录的多个字段设置