16.9.12 SQLGetDiagField, SQLGetDiagFieldW

Organization of this subsection

(1) Function
(2) Format
(3) Arguments
(4) Return value
(5) SQLSTATE
(6) Notes

(1) Function

This ODBC function returns the current value of a field in a diagnostic data structure that contains such information as error, warning, and status.

To Page Top

(2) Format

For SQLGetDiagField

SQLRETURN SQLGetDiagField
(
  SQLSMALLINT     HandleType,          /* In */
  SQLHANDLE       Handle,              /* In */
  SQLSMALLINT     RecNumber,           /* In */
  SQLSMALLINT     DiagIdentifier,      /* In */
  SQLPOINTER      DiagInfoPtr,         /* Out */
  SQLSMALLINT     BufferLength,        /* In */
  SQLSMALLINT   * StringLengthPtr      /* Out */
)

For SQLGetDiagFieldW

SQLRETURN SQLGetDiagFieldW
(
  SQLSMALLINT     HandleType,          /* In */
  SQLHANDLE       Handle,              /* In */
  SQLSMALLINT     RecNumber,           /* In */
  SQLSMALLINT     DiagIdentifier,      /* In */
  SQLPOINTER      DiagInfoPtr,         /* Out */
  SQLSMALLINT     BufferLength,        /* In */
  SQLSMALLINT   * StringLengthPtr      /* Out */
)

To Page Top

(3) Arguments

HandleType

Specifies one of the following handle types:

SQL_HANDLE_ENV: Environment handle
SQL_HANDLE_DBC: Connection handle
SQL_HANDLE_STMT: Statement handle
SQL_HANDLE_DESC: Descriptor handle

Handle

Specifies a handle value.

Specify a value that was output by *OutputHandlePtr of SQLAllocHandle before this function is executed.

RecNumber

Specifies the diagnostic information (status record) number from which the application is to acquire information.

If the application is to acquire the value of the diagnostic header field (the value indicating the diagnostic header field is to be set in DiagIdentifier), this argument is ignored.

If the application is to acquire any other value, specify 1 or a greater value in this argument.

DiagIdentifier

Specifies a required diagnostic field identifier. The two principal types are header fields and record fields. For details about the attributes that can be specified, see 16.18 Attributes that can be specified in DiagIdentifier of SQLGetDiagField and SQLGetDiagFieldW.

DiagInfoPtr

Specifies a pointer to the buffer in which the diagnostic information is to be returned. The data type depends on the value of DiagIdentifier.

BufferLength

Specifies the length of DiagInfoPtr.

This length includes the null terminating character.

Specify the following value depending on the type of DiagInfoPtr:

Type of DiagIdentifier value	Type of DiagInfoPtr value	Value to be specified in BufferLength
Value defined in 16.18 Attributes that can be specified in DiagIdentifier of SQLGetDiagField and SQLGetDiagFieldW	Character string or binary	Length of `DiagInfoPtr` (in bytes) `SQL_NTS` cannot be specified.
Integer	None (ignored)

Type of DiagIdentifier value

Type of DiagInfoPtr value

Value to be specified in BufferLength

Value defined in 16.18 Attributes that can be specified in DiagIdentifier of SQLGetDiagField and SQLGetDiagFieldW

Character string or binary

Length of DiagInfoPtr (in bytes)

SQL_NTS cannot be specified.

Integer

None (ignored)

StringLengthPtr

Specify this argument only when DiagInfoPtr is character string data.

Specifies a pointer to the buffer that stores the total number of valid bytes to be returned to DiagInfoPtr. This total number of bytes does not include the number of bytes in the null terminating character.

Important: If the total length (in bytes) of the character string stored here that is to be set in DiagInfoPtr is greater than the value of BufferLength without the length of the null terminating character, the character string stored in DiagInfoPtr is truncated to the length equivalent to BufferLength without the null terminating character, and then the null terminating character is added at the end.

To Page Top

(4) Return value

This ODBC function returns SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR, SQL_INVALID_HANDLE, or SQL_NO_DATA. This function does not set SQLSTATE but provides the following execution results as return values:

Return value	Meaning
`SQL_SUCCESS`	The processing was successful.
`SQL_SUCCESS_WITH_INFO`	One of the following errors occurred: The size of `DiagInfoPtr` was too small for the acquired value, resulting in truncation. You can determine the truncated size by comparing `BufferLength` and `StringLengthPtr`. A character code that cannot be converted was detected during conversion of character encoding, and was replaced with the specified character.
`SQL_ERROR`	One of the following errors occurred: An invalid value was specified in `DiagIdentifier`. One of the values listed below was specified in `DiagIdentifier`, but `Handle` was not a statement handle: • `SQL_DIAG_CURSOR_ROW_COUNT` • `SQL_DIAG_DYNAMIC_FUNCTION` • `SQL_DIAG_DYNAMIC_FUNCTION_CODE` • `SQL_DIAG_ROW_COUNT` A value indicating a diagnostic record field was specified in `DiagIdentifier`, but the value specified in `RecNumber` was less than or equal to `0`. The data type of the requested field was character string, but `BufferLength` satisfied all the following conditions: • Less than `0` • Not `SQL_NTS` • Not the results of `SQL_LEN_BINARY_ATTR(length)` macro An invalid value (`SQL_NTS`) was specified in `BufferLength`.
`SQL_INVALID_HANDLE`	The handle indicated by `HandleType` and `Handle` is not a valid handle.
`SQL_NO_DATA`	`RecNumber` is greater than the number of diagnostic records in the handle specified by `Handle` or there was no diagnostic record that could be read in the handle specified by `Handle`.

To Page Top

(5) SQLSTATE

This ODBC function does not return SQLSTATE.

The function returns details of errors by using the values defined in (4) Return value.

To Page Top

(6) Notes

For details about the error information, see 15.4 Information that is returned in the event of an error.
The function does not return diagnostic information.

To Page Top