SQLGetDiagRec--Get multiple fields settings of diagnostic record

Purpose

Specification:

DB2 CLI 5.0

ODBC 3.0

SQLGetDiagRec() returns the current value of the SQLSTATE field of a diagnostic record that contains error, warning, and status information.

A connection handle must be allocated using SQLAllocHandle() before calling this function.

Syntax

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

Function arguments

Table 68. SQLGetDiagRec arguments

Data type	Argument	Use	Description
SQLSMALLINT	`HandleType`	input	A handle-type identifier that describes the type of handle for which diagnostics are desired. Can be SQL_HANDLE_STMT or SQL_HANDLE_DBC.
SQLHANDLE	`Handle`	input	A handle for the diagnostic data structure, of the type indicated by `HandleType`.
SQLSMALLINT	`RecNumber`	input	Indicates the status record from which the application seeks information. Status records must be 1.
SQLCHAR	`SQLState`	output	Pointer to a buffer in which to return a 5 character SQLSTATE code pertaining to the diagnostic record `RecNumber`. The first two characters indicate the class; the next three indicate the subclass.
SQLINTEGER	`NativeErrorPtr`	output	Pointer to a buffer in which to return the native error code, specific to the data source.
SQLCHAR	`MessageText`	output	Pointer to a buffer in which to return the error message text. The fields returned by `SQLGetDiagRec()` are contained in a text string.
SQLINTEGER	`BufferLength`	input	Length (in bytes) of the `MessageText` buffer.
SQLSMALLINT	`TextLengthPtr`	output	Pointer to a buffer in which to return the total number of bytes (excluding the number of bytes required for the null termination character) available to return in `MessageText`. If the number of bytes available to return is greater than `BufferLength`, then the error message text in `MessageText` is truncated to `BufferLength` minus the length of the null termination character.

Usage

An application typically calls SQLGetDiagRec() when a previous call to a DB2 CLI function returns anything other than SQL_SUCCESS.

SQLGetDiagRec() returns a character string containing multiple fields of the diagnostic data structure record.

The functionality of SQLGetDiagRec() is extended in Version 8.1 of DB2 Everyplace. The following SQLSTATEs can now be returned : 57011, HY024, HY092, HY000, HY012. See SQLState listing for more information about these SQLSTATEs.

SQLGetDiagRec() retrieves only the diagnostic information most recently associated with the handle specified in the Handle argument. If the application calls any function, except SQLGetDiagRec(), any diagnostic information from the previous calls on the same handle is lost.

HandleType argument

Each handle type can have diagnostic information associated with it. The HandleType argument denotes the handle type of Handle. DB2 Everyplace supports statement handles and connection handles.

Return codes

SQL_SUCCESS
SQL_SUCCESS_WITH_INFO
SQL_ERROR
SQL_INVALID_HANDLE

Diagnostics

SQLGetDiagRec() does not post error values for itself. It uses the following return values to report the outcome of its own execution:

SQL_SUCCESS

The function successfully returned diagnostic information.

SQL_SUCCESS_WITH_INFO

The MessageText buffer is too small to hold the requested diagnostic message. No diagnostic records are generated. To 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

The handle indicated by HandleType and Handle is not a valid handle.

SQL_ERROR

One of the following situations occurred:

RecNumber is negative or 0.
BufferLength is less than zero.

SQL_NO_DATA

RecNumber is greater than the number of diagnostic records that existed for the handle specified in Handle. The function also returns SQL_NO_DATA for any positive RecNumber if there are no diagnostic records for Handle.

Restrictions

None.

Related reference