SQLGetDiagRec 函数

  • 项目

一致性
引入的版本：ODBC 3.0 标准符合性：ISO 92

摘要
SQLGetDiagRec 返回包含错误、警告和状态信息的诊断记录的多个字段的当前值。 与每次调用返回一个诊断字段的 SQLGetDiagField 不同， SQLGetDiagRec 返回诊断记录的多个常用字段，包括 SQLSTATE、本机错误代码和诊断消息文本。

语法

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

参数

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感知。

Handle
[输入]诊断数据结构的句柄，由 HandleType 指示的类型。 如果 HandleType 为SQL_HANDLE_ENV， 则 Handle 可以是共享或非共享环境句柄。

RecNumber
[输入]指示应用程序从中查找信息的状态记录。 状态记录从 1 开始编号。

SQLState
[输出]指向缓冲区的指针，该缓冲区将返回一个五个字符的 SQLSTATE 代码， (并终止诊断记录 RecNumber 的 NULL) 。 前两个字符指示 类：接下来的三个表示子类。 此信息包含在“SQL_DIAG_SQLSTATE诊断”字段中。 有关详细信息，请参阅 SQLSTATEs。

NativeErrorPtr
[输出]指向缓冲区的指针，该缓冲区将返回特定于数据源的本机错误代码。 此信息包含在“SQL_DIAG_NATIVE诊断”字段中。

MessageText
[输出]指向要在其中返回诊断消息文本字符串的缓冲区的指针。 此信息包含在“SQL_DIAG_MESSAGE_TEXT诊断”字段中。 有关字符串的格式，请参阅 诊断消息。

如果 MessageText 为 NULL， 则 TextLengthPtr 仍将返回字符总数， (不包括可在 MessageText 指向的缓冲区中返回的字符数据的 null 终止字符) 。

BufferLength
[输入]*MessageText 缓冲区的长度（以字符为单位）。 诊断消息文本没有最大长度。

TextLengthPtr
[输出]指向缓冲区的指针，该缓冲区返回的总字符数 (不包括在 *MessageText 中可返回的 null 终止字符) 所需的字符数。 如果可返回的字符数大于 BufferLength，则 *MessageText 中的诊断消息文本将被截断为 BufferLength 减去 null 终止字符的长度。

返回

SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_ERROR、SQL_NO_DATA或SQL_INVALID_HANDLE。

诊断

SQLGetDiagRec 不会自行发布诊断记录。 它使用以下返回值来报告其自己的执行结果：

  • SQL_SUCCESS：函数已成功返回诊断信息。

  • SQL_SUCCESS_WITH_INFO：*MessageText 缓冲区太小，无法保存请求的诊断消息。 未生成任何诊断记录。 若要确定发生截断，应用程序必须将 BufferLength 与写入 *TextLengthPtr 的实际可用字节数进行比较。

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

  • SQL_ERROR：发生了以下情况之一：

    • RecNumber 为负数或 0。

    • BufferLength 小于零。

    • 使用异步通知时，对句柄的异步操作未完成。

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

注释

当对 ODBC 函数的上一次调用返回SQL_ERROR或SQL_SUCCESS_WITH_INFO时，应用程序通常会调用 SQLGetDiagRec 。 但是，由于任何 ODBC 函数在每次调用时都可以发布零条或更多条诊断记录，因此应用程序可以在调用任何 ODBC 函数后调用 SQLGetDiagRec 。 应用程序可以多次调用 SQLGetDiagRec 以返回诊断数据结构中的部分或全部记录。 ODBC 对可以随时存储的诊断记录数没有限制。

SQLGetDiagRec 不能用于从诊断数据结构的标头返回字段。 (RecNumber 参数必须大于 0.) 应用程序应为此调用 SQLGetDiagField 。

SQLGetDiagRec 仅检索最近与 Handle 参数中指定的句柄关联的诊断信息。 如果应用程序调用另一个 ODBC 函数（ SQLGetDiagRec、 SQLGetDiagField 或 SQLError 除外），则在同一句柄上以前调用的任何诊断信息都将丢失。

只要 SQLGetDiagRec 返回SQL_SUCCESS，应用程序就可以通过循环递增 RecNumber 来扫描所有诊断记录。 对 SQLGetDiagRec 的调用对标头和记录字段没有破坏性。 只要在此期间没有调用除 SQLGetDiagRec、SQLGetDiagField 或 SQLError 以外的其他函数（SQLGetDiagRec、SQLGetDiagField 或 SQLError），应用程序就可以在以后再次调用 SQLGetDiagRec 以从记录中检索字段。 应用程序还可以通过调用 SQLGetDiagField 来检索SQL_DIAG_NUMBER字段的值，然后多次调用 SQLGetDiagRec 来检索可用的诊断记录总数。

有关诊断数据结构的字段的说明，请参阅 SQLGetDiagField。 有关详细信息，请参阅 使用 SQLGetDiagRec 和 SQLGetDiagField 和 实现 SQLGetDiagRec 和 SQLGetDiagField。

调用异步执行的 API 以外的 API 将生成 HY010“函数序列错误”。 但是，在异步操作完成之前，无法检索错误记录。

HandleType 参数

每个句柄类型都可以具有与之关联的诊断信息。 HandleType 参数表示 Handle 参数的句柄类型。

不能为环境、连接、语句和描述符句柄返回某些标头和记录字段。 字段不适用的句柄在 SQLGetDiagField 的“标头字段”和“记录字段”部分中指示。

如果 handleType SQL_HANDLE_SENV，则对 SQLGetDiagRec 的调用将返回SQL_INVALID_HANDLE，这表示共享环境句柄。 但是，如果 HandleType 为SQL_HANDLE_ENV， 则 Handle 可以是共享环境句柄，也可以是非共享环境句柄。

有关以下方面的信息 请参阅
获取诊断记录的字段或诊断标头的字段 SQLGetDiagField 函数

另请参阅

ODBC API 参考
ODBC 头文件
示例 ODBC 程序