SQLGetDiagRec 函数SQLGetDiagRec Function

符合性Conformance
版本引入了:ODBC 3.0 标准符合性:ISO 92Version Introduced: ODBC 3.0 Standards Compliance: ISO 92

摘要Summary
SQLGetDiagRec返回多个字段包含错误、 警告和状态信息的诊断记录的当前值。SQLGetDiagRec returns the current values of multiple fields of a diagnostic record that contains error, warning, and status information. 与不同SQLGetDiagField,这会返回调用时,每个诊断字段SQLGetDiagRec返回多个常用的字段的诊断记录,包括 SQLSTATE、 本机错误代码,并诊断消息文本中。Unlike SQLGetDiagField, which returns one diagnostic field per call, SQLGetDiagRec returns several commonly used fields of a diagnostic record, including the SQLSTATE, the native error code, and the diagnostic message text.

语法Syntax

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

参数Arguments

HandleTypeHandleType
[输入]描述诊断为其所需的句柄的类型的句柄类型标识符。[Input] A handle type identifier that describes the type of handle for which diagnostics are required. 必须是下列选项之一:Must be one of the following:

  • SQL_HANDLE_DBCSQL_HANDLE_DBC

  • SQL_HANDLE_DBC_INFO_TOKENSQL_HANDLE_DBC_INFO_TOKEN

  • SQL_HANDLE_DESCSQL_HANDLE_DESC

  • SQL_HANDLE_ENVSQL_HANDLE_ENV

  • SQL_HANDLE_STMTSQL_HANDLE_STMT

只能由驱动程序管理器和驱动程序使用 SQL_HANDLE_DBC_INFO_TOKEN 句柄。SQL_HANDLE_DBC_INFO_TOKEN handle is used only by the Driver Manager and driver. 应用程序不应使用此句柄类型。Applications should not use this handle type. 有关 SQL_HANDLE_DBC_INFO_TOKEN 详细信息,请参阅ODBC 驱动程序中开发连接池感知For more information about SQL_HANDLE_DBC_INFO_TOKEN, see Developing Connection-Pool Awareness in an ODBC Driver.

HandleHandle
[输入]所指示的类型的诊断数据结构的句柄HandleType[Input] A handle for the diagnostic data structure, of the type indicated by HandleType. 如果HandleType为 SQL_HANDLE_ENV,处理可以是共享或非共享的环境句柄。If HandleType is SQL_HANDLE_ENV, Handle can be either a shared or an unshared environment handle.

RecNumberRecNumber
[输入]指示从其应用程序查找信息的状态记录。[Input] Indicates the status record from which the application seeks information. 状态记录的编号从 1。Status records are numbered from 1.

SQLStateSQLState
[输出]指向用于返回五个字符的 SQLSTATE 代码 (和终止 NULL) 的诊断记录的缓冲区RecNumber[Output] Pointer to a buffer in which to return a five-character SQLSTATE code (and terminating NULL) for the diagnostic record RecNumber. 前两个字符指示的类;下一步的三个指示子类。The first two characters indicate the class; the next three indicate the subclass. SQL_DIAG_SQLSTATE 诊断字段中包含此信息。This information is contained in the SQL_DIAG_SQLSTATE diagnostic field. 有关详细信息,请参阅SQLSTATEsFor more information, see SQLSTATEs.

NativeErrorPtrNativeErrorPtr
[输出]指向用于返回特定于数据源的本机错误代码的缓冲区。[Output] Pointer to a buffer in which to return the native error code, specific to the data source. SQL_DIAG_NATIVE 诊断字段中包含此信息。This information is contained in the SQL_DIAG_NATIVE diagnostic field.

MessageTextMessageText
[输出]指向在其中返回的诊断消息的文本字符串的缓冲区的指针。[Output] Pointer to a buffer in which to return the diagnostic message text string. SQL_DIAG_MESSAGE_TEXT 诊断字段中包含此信息。This information is contained in the SQL_DIAG_MESSAGE_TEXT diagnostic field. 字符串的格式,请参阅诊断消息For the format of the string, see Diagnostic Messages.

如果MessageText为 NULL, TextLengthPtr仍将返回的字符 (不包括字符数据的 null 终止字符) 总数可用于返回通过指向的缓冲区中MessageTextIf MessageText is NULL, TextLengthPtr will still return the total number of characters (excluding the null-termination character for character data) available to return in the buffer pointed to by MessageText.

BufferLengthBufferLength
[输入]长度 *MessageText以字符为单位的缓冲区。[Input] Length of the *MessageText buffer in characters. 没有诊断消息文本的最大长度。There is no maximum length of the diagnostic message text.

TextLengthPtrTextLengthPtr
[输出]指向用于返回的字符 (不包括所需的 null 终止字符的字符数) 总数的缓冲区可用于在中返回 *MessageText[Output] Pointer to a buffer in which to return the total number of characters (excluding the number of characters required for the null-termination character) available to return in *MessageText. 如果可用于返回的字符数大于BufferLength中的诊断消息正文 *MessageText截断为BufferLength减去 null 终止字符的长度。If the number of characters available to return is greater than BufferLength, the diagnostic message text in *MessageText is truncated to BufferLength minus the length of a null-termination character.

返回Returns

SQL_SUCCESS、 SQL_SUCCESS_WITH_INFO、 SQL_ERROR 或 SQL_INVALID_HANDLE。SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR, or SQL_INVALID_HANDLE.

诊断Diagnostics

SQLGetDiagRec不会为其自身发送诊断记录。SQLGetDiagRec does not post diagnostic records for itself. 它使用了以下返回值来报告其自身执行的结果:It uses the following return values to report the outcome of its own execution:

  • SQL_SUCCESS:该函数成功地返回诊断信息。SQL_SUCCESS: The function successfully returned diagnostic information.

  • SQL_SUCCESS_WITH_INFO:* MessageText缓冲区是否太小而无法保存请求的诊断消息。SQL_SUCCESS_WITH_INFO: The *MessageText buffer was too small to hold the requested diagnostic message. 未不生成任何诊断记录。No diagnostic records were generated. 若要确定发生了截断,应用程序必须进行比较BufferLength可用的字节,这写入的实际数目 *StringLengthPtrTo determine that a truncation occurred, the application must compare BufferLength to the actual number of bytes available, which is written to *StringLengthPtr.

  • SQL_INVALID_HANDLE:指示句柄HandleType处理不是有效的句柄。SQL_INVALID_HANDLE: The handle indicated by HandleType and Handle was not a valid handle.

  • SQL_ERROR:出现下列情况之一:SQL_ERROR: One of the following occurred:

    • RecNumber是负数或 0。RecNumber was negative or 0.

    • BufferLength小于零。BufferLength was less than zero.

    • 使用异步通知时,句柄上的异步操作是不完整。When using asynchronous notification, the asynchronous operation on the handle was not complete.

  • SQL_NO_DATA:RecNumber存在的句柄中指定的诊断记录数大于处理。SQL_NO_DATA: RecNumber was greater than the number of diagnostic records that existed for the handle specified in Handle. 函数还将为任何正返回 SQL_NO_DATA RecNumber如果有没有可供诊断记录处理The function also returns SQL_NO_DATA for any positive RecNumber if there are no diagnostic records for Handle.

注释Comments

应用程序通常会调用SQLGetDiagRec SQL_ERROR 或 SQL_SUCCESS_WITH_INFO 时返回上次调用 ODBC 函数。An application typically calls SQLGetDiagRec when a previous call to an ODBC function has returned SQL_ERROR or SQL_SUCCESS_WITH_INFO. 但是,因为任何 ODBC 函数可以发布零个或多个诊断记录每次调用它,应用程序可以调用SQLGetDiagRec任何 ODBC 函数调用之后。However, because any ODBC function can post zero or more diagnostic records each time it is called, an application can call SQLGetDiagRec after any ODBC function call. 应用程序可以调用SQLGetDiagRec多次诊断数据结构中返回的部分或所有记录。An application can call SQLGetDiagRec multiple times to return some or all of the records in the diagnostic data structure. ODBC 规定可以存放在任何一次的诊断记录数没有限制。ODBC imposes no limit to the number of diagnostic records that can be stored at any one time.

SQLGetDiagRec不能用于诊断数据结构的标头中返回字段。SQLGetDiagRec cannot be used to return fields from the header of the diagnostic data structure. ( RecNumber参数必须是大于 0。)应用程序应调用SQLGetDiagField实现此目的。(The RecNumber argument must be greater than 0.) The application should call SQLGetDiagField for this purpose.

SQLGetDiagRec检索仅最近与中指定的句柄关联的诊断信息处理参数。SQLGetDiagRec retrieves only the diagnostic information most recently associated with the handle specified in the Handle argument. 如果应用程序调用另一个 ODBC 函数,除非SQLGetDiagRecSQLGetDiagField,或SQLError,从前面的调用上的任何诊断信息相同的句柄都将丢失。If the application calls another ODBC function, except SQLGetDiagRec, SQLGetDiagField, or SQLError, any diagnostic information from the previous calls on the same handle is lost.

应用程序可以扫描所有诊断记录的循环,递增RecNumber,只要SQLGetDiagRec返回 SQL_SUCCESS。An application can scan all diagnostic records by looping, incrementing RecNumber, as long as SQLGetDiagRec returns SQL_SUCCESS. 调用SQLGetDiagRec应是非破坏性的标头和记录字段。Calls to SQLGetDiagRec are nondestructive to the header and record fields. 应用程序可以调用SQLGetDiagRec再次在以后从只要为任何其他函数中,除记录检索字段SQLGetDiagRecSQLGetDiagField,或SQLError,已在此期间调用。The application can call SQLGetDiagRec again at a later time to retrieve a field from a record as long as no other function, except SQLGetDiagRec, SQLGetDiagField, or SQLError, has been called in the interim. 应用程序还可以通过调用检索可用的诊断记录的总数的计数SQLGetDiagField若要检索的值 SQL_DIAG_NUMBER 字段中,并调用SQLGetDiagRec相同的次数。The application can also retrieve a count of the total number of diagnostic records available by calling SQLGetDiagField to retrieve the value of the SQL_DIAG_NUMBER field, and then calling SQLGetDiagRec that many times.

诊断数据结构的字段的说明,请参阅SQLGetDiagFieldFor a description of the fields of the diagnostic data structure, see SQLGetDiagField. 有关详细信息,请参阅使用 SQLGetDiagRec 和 SQLGetDiagField实现 SQLGetDiagRec 和 SQLGetDiagFieldFor more information, see Using SQLGetDiagRec and SQLGetDiagField and Implementing SQLGetDiagRec and SQLGetDiagField.

调用而不是以异步方式执行的 API 会生成 HY010"函数序列错误"。Calling an API other than the one that's being executed asynchronously will generate HY010 "Function sequence error". 但是,在异步操作完成之前,无法检索错误记录。However, the error record cannot be retrieved before the asynchronous operation completes.

HandleType 参数HandleType Argument

每个句柄类型可以有与之关联的诊断信息。Each handle type can have diagnostic information associated with it. HandleType自变量表示的句柄类型处理参数。The HandleType argument denotes the handle type of the Handle argument.

某些标头和记录字段不能句柄返回有关环境、 连接、 语句和描述符。Some header and record fields cannot be returned for environment, connection, statement, and descriptor handles. 在"标头字段"和"记录字段"中的部分中指示该字段不适用于这些句柄SQLGetDiagFieldThose handles for which a field is not applicable are indicated in the "Header Fields" and "Record Fields" sections in SQLGetDiagField.

调用SQLGetDiagRec将返回 SQL_INVALID_HANDLE,如果HandleType是 SQL_HANDLE_SENV,表示共享的环境句柄。A call to SQLGetDiagRec will return SQL_INVALID_HANDLE if HandleType is SQL_HANDLE_SENV, which denotes a shared environment handle. 但是,如果HandleType为 SQL_HANDLE_ENV,处理可以是共享或非共享的环境句柄。However, if HandleType is SQL_HANDLE_ENV, Handle can be either a shared or an unshared environment handle.

有关信息For information about 请参阅See
获取诊断记录的字段或诊断标头的字段Obtaining a field of a diagnostic record or a field of the diagnostic header SQLGetDiagField 函数SQLGetDiagField Function

请参阅See Also

ODBC API 参考 ODBC API Reference
ODBC 头文件 ODBC Header Files
示例 ODBC 程序Sample ODBC Program