Updated on 2024-10-14 GMT+08:00

SQLGetDiagRec

Function

SQLGetDiagRec is used to return the current values of multiple fields in a diagnostic record that contains error, warning, and status information.

Prototype

1
2
3
4
5
6
7
8
SQLRETURN  SQLGetDiagRec(SQLSMALLINT    HandleType
                         SQLHANDLE      Handle,
                         SQLSMALLINT    RecNumber,
                         SQLCHAR        *SQLState,
                         SQLINTEGER     *NativeErrorPtr,
                         SQLCHAR        *MessageText,
                         SQLSMALLINT    BufferLength
                         SQLSMALLINT    *TextLengthPtr);

Parameter

Table 1 SQLGetDiagRec parameters

Keyword

Parameter Description

HandleType

A handle-type identifier that describes the type of handle for which diagnostics are desired. The value must be one of the following:

  • SQL_HANDLE_ENV
  • SQL_HANDLE_DBC
  • SQL_HANDLE_STMT
  • SQL_HANDLE_DESC

Handle

A handle for the diagnostic data structure. Its type is indicated by HandleType. If HandleType is SQL_HANDLE_ENV, Handle may be a shared or non-shared environment handle.

RecNumber

Status record from which the application seeks information. RecNumber starts with 1.

SQLState

Output parameter: pointer to a buffer that saves the 5-character SQLSTATE code pertaining to RecNumber.

NativeErrorPtr

Output parameter: pointer to a buffer that saves the native error code.

MessageText

Pointer to a buffer that saves text strings of diagnostic information.

BufferLength

Length of MessageText.

TextLengthPtr

Output parameter: pointer to the buffer, the total number of bytes in the returned MessageText. If the number of bytes available to return is greater than BufferLength, then the diagnostics information text in MessageText is truncated to BufferLength minus the length of the null termination character.

Return Value

  • SQL_SUCCESS indicates that the call succeeded.
  • SQL_SUCCESS_WITH_INFO indicates that some warning information is displayed.
  • SQL_ERROR indicates major errors, such as memory allocation and connection failures.
  • SQL_INVALID_HANDLE indicates that invalid handles were called. This value may also be returned by other APIs.

Precautions

SQLGetDiagRec does not release diagnostic records for itself. It uses the following return values to report execution results:

  • SQL_SUCCESS indicates that the function successfully returns diagnostic information.
  • SQL_SUCCESS_WITH_INFO indicates that the *MessageText buffer is too small to hold the requested diagnostic information. No diagnostic records are generated.
  • SQL_INVALID_HANDLE indicates that the handle indicated by HandType and Handle is an invalid handle.
  • SQL_ERROR indicates that RecNumber is less than or equal to 0 or that BufferLength is smaller than 0.

If an ODBC function returns SQL_ERROR or SQL_SUCCESS_WITH_INFO, the application can call SQLGetDiagRec to obtain the SQLSTATE value. The possible SQLSTATE values are listed as follows:

Table 2 SQLSTATE values

SQLSATATE

Error

Description

HY000

General error.

An error occurred for which there is no specific SQLSTATE.

HY001

Memory allocation error.

The driver is unable to allocate memory required to support execution or completion of the function.

HY008

Operation canceled.

SQLCancel is called to terminate the statement execution, but the StatementHandle function is still called.

HY010

Function sequence error.

The function is called prior to sending data to data parameters or columns being executed.

HY013

Memory management error.

The function fails to be called. The error may be caused by low memory conditions.

HYT01

Connection timeout.

The timeout period expired before the application was able to connect to the data source.

IM001

Function not supported by the driver.

The called function is not supported by the StatementHandle driver.

Example

See Examples.