16.9.13 SQLGetDiagRec, SQLGetDiagRecW
- Organization of this subsection
(1) Function
This ODBC function returns the current values of fields in a diagnostic data structure that is associated with a handle and includes such information as error, warning, and status.
(2) Format
-
For SQLGetDiagRec
SQLRETURN SQLGetDiagRec ( SQLSMALLINT HandleType, /* In */ SQLHANDLE Handle, /* In */ SQLSMALLINT RecNumber, /* In */ SQLCHAR * SQLState, /* Out */ SQLINTEGER * NativeErrorPtr, /* Out */ SQLCHAR * MessageText, /* Out */ SQLSMALLINT BufferLength, /* In */ SQLSMALLINT * TextLengthPtr /* Out */ )
-
For SQLGetDiagRecW
SQLRETURN SQLGetDiagRecW ( SQLSMALLINT HandleType, /* In */ SQLHANDLE Handle, /* In */ SQLSMALLINT RecNumber, /* In */ SQLWCHAR * SQLState, /* Out */ SQLINTEGER * NativeErrorPtr, /* Out */ SQLWCHAR * MessageText, /* Out */ SQLSMALLINT BufferLength, /* In */ SQLSMALLINT * TextLengthPtr /* Out */ )
(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.
Specify 1 or a greater value in this argument.
- SQLState
-
Specifies a pointer to the buffer in which the SQLSTATE code for the diagnostic record indicated by RecNumber is to be returned. This pointer consists of five characters consisting of 2 characters for the class + 3 characters for the subclass.
The information stored in the SQL_DIAG_SQLSTATE diagnostic field is returned.
If NULL is specified in this parameter, the driver sets nothing.
- NativeErrorPtr
-
Specifies a pointer to the buffer in which the native error code specific to the data source is to be returned.
The information stored in the SQL_DIAG_NATIVE diagnostic field is returned.
If NULL is specified in this parameter, the driver sets nothing.
- MessageText
-
Specifies a pointer to the buffer in which the diagnostic message text character string is to be returned.
The information stored in the SQL_DIAG_MESSAGE_TEXT diagnostic field is returned.
If NULL is specified in this parameter, the driver sets nothing.
- BufferLength
-
Specifies the length# of the MessageText buffer.
Although there is no maximum length for a diagnostic message text, specify a value that is at least 512 bytes.
This length includes the null terminating character. SQL_NTS cannot be specified.
- TextLengthPtr
-
Specifies a pointer to the buffer that returns the total valid length# to be returned to MessageText. This length does not include the null terminating character.
- Important
-
If the length# stored here is greater than the value of BufferLength without the length# of the null terminating character, the character string stored in MessageText is truncated to the length# equivalent to BufferLength without the null terminating character, and then the null terminating character is added at the end.
- #
-
The length must be in bytes for SQLGetDiagRec and in characters for SQLGetDiagRecW.
(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:
|
SQL_ERROR |
One of the following errors occurred:
|
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. |
(5) SQLSTATE
This ODBC function does not return SQLSTATE.
The function returns details of errors by using the values defined in (4) Return value.
(6) Notes
-
For details about the error information, see 15.4 Information that is returned in the event of an error.
-
SQLCODE is set in NativeErrorPtr. For details about SQLCODE, see Interpreting SQLCODEs in the manual HADB Messages.
-
The function does not return diagnostic information.