一致性
推出版本：ODBC 3.0 标准合规：ISO 92
总结
SQLGetDiagRec 返回包含错误、警告和状态信息的诊断记录多个字段的当前值。 与每次调用返回一个诊断字段的 SQLGetDiagField 不同， SQLGetDiagRec 返回多个常用的诊断记录字段，包括 SQLSTATE、本地错误代码和诊断消息文本。
Syntax
SQLRETURN SQLGetDiagRec(
SQLSMALLINT HandleType,
SQLHANDLE Handle,
SQLSMALLINT RecNumber,
SQLCHAR * SQLState,
SQLINTEGER * NativeErrorPtr,
SQLCHAR * MessageText,
SQLSMALLINT BufferLength,
SQLSMALLINT * TextLengthPtr);
Arguments
HandleType
[输入]描述需要诊断的句柄类型的句柄类型标识符。 必须是以下选项之一：
SQL_HANDLE_DBC
SQL_HANDLE_DBC_INFO_TOKEN
SQL_HANDLE_DESC
SQL_HANDLE_ENV
SQL_HANDLE_STMT
SQL_HANDLE_DBC_INFO_TOKEN句柄仅由驱动程序管理器和驱动程序使用。 应用程序不应使用此句柄类型。 有关SQL_HANDLE_DBC_INFO_TOKEN的更多信息，请参见 《ODBC司机中 Connection-Pool 意识的培养》。
处理
[输入]诊断数据结构的句柄，由 HandleType指示的类型。 如果 HandleType SQL_HANDLE_ENV，Handle 可以是共享环境句柄，也可以是未共享的环境句柄。
RecNumber
[输入]指示应用程序从中查找信息的状态记录。 状态记录从 1 开始编号。
SQLState
[输出]指向一个缓冲区，返回诊断记录 RecNumber的五字符SQLSTATE代码（终止NULL）。 前两个字符表示该职业;接下来的三个代表子职业。 这些信息包含在SQL_DIAG_SQLSTATE诊断领域。 有关详细信息，请参阅 SQLSTATEs。
NativeErrorPtr
[输出]指向一个缓冲区，返回针对数据源的本地错误码。 这些信息包含在SQL_DIAG_NATIVE诊断领域。
MessageText
[输出]指向一个缓冲区，返回诊断消息文本字符串。 这些信息包含在SQL_DIAG_MESSAGE_TEXT诊断领域。 关于字符串的格式，请参见 诊断消息。
如果 MessageText 是 NULL，TextLengthPtr 仍然会返回 MessageText 指向的缓冲区中可返回的字符总数（不含字符数据的 null-终止字符）。
BufferLength
[输入]*MessageText 缓冲区的字符长度。 诊断消息文本没有最大长度限制。
文本长度
[输出]指向缓冲区，返回* MessageText中可返回的字符总数（不含空终止字符的字符数）。 如果可返回的字符数大于 BufferLength， 则*MessageText 中的诊断消息文本会被截断为 BufferLength 减去空终止字符长度。
Returns
SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_ERROR、SQL_NO_DATA或SQL_INVALID_HANDLE。
诊断
SQLGetDiagRec 不会为自己发布诊断记录。 它使用以下返回值报告其自己的执行结果：
SQL_SUCCESS：函数已成功返回诊断信息。
SQL_SUCCESS_WITH_INFO：*MessageText 缓冲区太小，无法容纳请求的诊断消息。 未生成诊断记录。 为了确定是否发生了截断，应用程序必须将 缓冲长度 与实际可用字节数进行比较，实际字节数写入 *TextLengthPtr。
SQL_INVALID_HANDLE：HandleType 和 Handle 指示的句柄不是有效的句柄。
SQL_ERROR：发生以下事件之一：
RecNumber 是负数或0。
缓冲长度 小于零。
使用异步通知时，句柄上的异步操作未完成。
SQL_NO_DATA：RecNumber 大于 句柄中指定的句柄存在的诊断记录数。 如果 Handle没有诊断记录，则函数还会返回任何正 RecNumber 的SQL_NO_DATA。
Comments
应用程序通常在之前对ODBC函数的调用返回SQL_ERROR或 SQL_SUCCESS_WITH_INFO时调用 SQLGetDiagRec 。 然而，由于任何 ODBC 函数每次调用时都可以发布零条或多个诊断记录，应用程序可以在调用 ODBC 函数后调用 SQLGetDiagRec 。 应用程序可以多次调用 SQLGetDiagRec ，返回诊断数据结构中的部分或全部记录。 ODBC 对任何一次可存储的诊断记录数量没有限制。
SQLGetDiagRec 不能用于返回诊断数据结构头部的字段。 （ RecNumber 参数必须大于 0。）应用程序应为此调用 SQLGetDiagField 。
SQLGetDiagRec 只检索与 Handle 参数中指定的句柄最近关联的诊断信息。 如果应用程序调用了除 SQLGetDiagRec、 SQLGetDiagField 或 SQLError 以外的其他 ODBC 函数，之前同一句柄上调用中的任何诊断信息都会丢失。
应用程序可以通过循环扫描所有诊断记录，递增 RecNumber，只要 SQLGetDiagRec 返回 SQL_SUCCESS。 调用 SQLGetDiagRec 对头部和记录字段不破坏。 应用程序可以在之后再次调用 SQLGetDiagRec 以从记录中检索字段，只要期间除了 SQLGetDiagRec、 SQLGetDiagField 或 SQLError 外，没有其他函数被调用。 应用程序还可以通过调用 SQLGetDiagField 获取 SQL_DIAG_NUMBER 字段的值，然后多次调用 SQLGetDiagRec 来获取可用诊断记录的总数。
关于诊断数据结构字段的描述，请参见 SQLGetDiagField。 有关详细信息，请参阅 使用 SQLGetDiagRec 和 SQLGetDiagField，实现 SQLGetDiagRec 和 SQLGetDiagField。
调用非异步执行的 API 将生成 HY010“函数序列错误”。 但是，在异步操作完成之前，无法检索错误记录。
HandleType 参数
每个句柄类型都可以具有与之关联的诊断信息。 HandleType 参数表示 Handle 参数的句柄类型。
对于环境、连接、语句和描述符句柄，无法返回某些标头和记录字段。 那些字段不适用的句柄在 SQLGetDiagField 的“头字段”和“记录字段”部分中标注。
调用 SQLGetDiagRec 时，如果 HandleType 是 SQL_HANDLE_SENV，则返回 SQL_INVALID_HANDLE，表示共享环境的句柄。 然而，如果 HandleType 是SQL_HANDLE_ENV的， Handle 可以是共享环境的句柄，也可以是非共享环境的句柄。
相关函数
| 有关以下内容的信息 | 请参阅 |
|---|---|
| 获取诊断记录字段或诊断头字段 | SQLGetDiagField 函数 |