SQLGetDiagRec - 返回诊断信息（简洁）

SQLGetDiagRec() 返回与最近调用的 Db2 for i CLI 函数相关的诊断信息，适用于特定语句、连接或环境句柄。

该信息由标准化 SQLSTATE ，错误代码和文本消息组成。有关更多信息，请参阅 Db2 for i CLI 应用程序中的诊断。

从另一个函数调用接收到 SQL_ERROR 或 SQL_SUCCESS_WITH_INFO 返回码后，调用 SQLGetDiagRec() 。

注: 在从语句处理返回 SQL_NO_DATA_FOUND 之后，某些数据库服务器可能会提供特定于产品的诊断信息。

Unicode (UTF-16) 等效: 此函数还可以与 Unicode (UTF-16) 字符集配合使用。相应的 Unicode 函数是 SQLGetDiagRecW() 。有关 DB2® CLI 的 Unicode 支持的更多信息，请参阅 Db2 for i CLI 中的 Unicode 。

语法

SQLRETURN SQLGetDiagRec (SQLSMALLINT  hType,
                        SQLINTEGER    handle,
                        SQLSMALLINT   recNum,
                        SQLCHAR       *szSqlState,
                        SQLINTEGER    *pfNativeError,
                        SQLCHAR       *szErrorMsg,
                        SQLSMALLINT   cbErrorMsgMax,
                        SQLSMALLINT   *pcbErrorMsg);

函数自变量

表 1. SQLGetDiagRec参数
数据类型	自变量	使用	描述
SQLSMALLINT	hType	输入	句柄类型。
SQLINTEGER	句柄	输入	需要诊断信息的句柄。
SQLSMALLINT	recNum	输入	如果存在多个错误，那么这指示应该检索哪个错误。如果请求了头信息，那么必须为 0。第一个错误记录是数字 1。
SQLCHAR *	szSqlState	输出	SQLSTATE 作为由空字符终止的 5 字符组成的字符串。前 2 个字符指示错误类; 下一个 3 指示子类。这些值直接对应于 X/Open SQL CAE 规范和 ODBC 规范中定义的 SQLSTATE 值，并使用特定于 IBM® 和特定于产品的 SQLSTATE 值进行扩充。
SQLINTEGER *	pfNativeError	输出	错误代码。在 Db2 for i CLI 中，pfNativeError 参数包含数据库管理系统 (DBMS) 返回的 SQLCODE 值。如果错误由 Db2 for i CLI 而不是 DBMS 生成，那么此字段设置为 -99999。
SQLCHAR *	szErrorMsg	输出	指向缓冲区的指针，以包含实现定义的消息文本。在 Db2 for i CLI 中，仅返回 DBMS 生成的消息; Db2 for i CLI 本身不会返回任何描述问题的消息文本。
SQLSMALLINT	cbErrorMsgMax	输入	缓冲区的最大（即分配的）长度 szErrorMsg. 建议分配的长度为 SQL_MAX_MESSAGE_LENGTH + 1。
SQLSMALLINT *	pcbErrorMsg	输出	指向返回 szErrorMsg 缓冲区的可用字节总数的指针。这不包括空终止字符。

用法

SQLSTAT 是由 X/OPEN SQL CAE 和 X/Open SQL CLI 快照定义的那些 SQL STAT ，使用特定于 IBM 的 SQLSTATE 值和特定于产品的 SQLSTATE 值进行扩充。

如果在使用同一句柄调用除 SQLGetDiagRec() 以外的函数之前未检索到一个 Db2 for i CLI 函数生成的诊断信息，那么先前函数调用的信息将丢失。无论是否为第二次 Db2 for i CLI 函数调用生成诊断信息，都是如此。

在给定的 Db2 for i CLI 函数调用之后，可能会有多条诊断消息可用。可以通过重复调用 SQLGetDiagRec()来一次检索这些消息。当没有信息可检索时，将返回 SQL_NO_DATA_FOUND，SQLSTATE 设置为 "00000"，pfNativeError 设置为 0、以及 pcbErrorMsg 和 szErrorMsg 未定义。

当使用给定句柄对 SQLGetDiagRec() 进行调用时，或者当使用该句柄进行另一个 Db2 for i CLI 函数调用时，将清除存储在该句柄下的诊断信息。但是，通过调用具有关联但不同的句柄类型的 SQLGetDiagRec() ，不会清除与给定句柄类型相关联的信息。例如，使用连接句柄输入调用 SQLGetDiagRec() 不会清除与该连接下的任何语句句柄关联的错误。

即使错误消息的缓冲区（szErrorMsg）太短，也会返回 SQL_SUCCESS，因为应用程序无法通过再次调用 SQLGetDiagRec() 来获取相同的错误消息。消息文本的实际长度将在 pcbErrorMsg 中返回。

为避免截断第一级错误消息，请声明缓冲区长度 SQL_MAX_MESSAGE_LENGTH + 1。要避免截断第二级错误消息，请将缓冲区的大小设置为大于 SQL_MAX_MESSAGE_LENGTH 的值。

返回码

SQL_SUCCESS
SQL_ERROR
SQL_INVALID_HANDLE
SQL_NO_DATA_FOUND

如果没有可用于输入句柄的诊断信息，或者通过调用 SQLGetDiagRec()检索了所有消息，那么将返回 SQL_NO_DATA_FOUND。

如果自变量 szSqlState， pfNativeError， szErrorMsg 或 pcbErrorMsg 是空指针，那么将返回 SQL_ERROR。

诊断

未定义 SQLSTAT ，因为 SQLGetDiagRec() 不会为其自身生成诊断信息。

限制

虽然 ODBC 也会返回 X/Open SQL CAE SQLSTAT ，但只有 Db2 for i CLI 会返回其他 IBM 定义的 SQLSTAT。除标准值外， ODBC 驱动程序管理器还会返回 SQLSTATE 值。有关特定于 ODBC 的 SQLSTAT 的更多信息，请参阅 Microsoft ODBC Programmer 's Reference。

因此，您只应该构建对标准 SQLSTAT 的依赖关系。这意味着应用程序中的任何分支逻辑都应仅依赖于标准 SQLSTAT。扩充的 SQLSTAT 对于调试目的最有用。

引用

SQLGetDiagField - 返回诊断信息（可扩展）