SQLGetDiagRec() - Get multiple field settings of diagnostic record

SQLGetDiagRec() returns the current values of multiple fields of a diagnostic record that contains error, warning, and status information. SQLGetDiagRec() also returns several commonly used fields of a diagnostic record, including the SQLSTATE, the native error code, and the error message text.

ODBC specifications for SQLGetDiagRec()

Table 1. SQLGetDiagRec() specifications
ODBC specification level In X/Open CLI CAE specification? In ISO CLI specification?
3.0 Yes Yes

Syntax

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

Function arguments

The following table lists the data type, use, and description for each argument in this function.

Table 2. SQLGetDiagRec() arguments
Data type Argument Use Description
SQLSMALLINT HandleType input Specifies a handle type identifier that describes the type of handle that you diagnose. This argument must specify one of the following values:
  • SQL_HANDLE_ENV for environment handles
  • SQL_HANDLE_DBC for connection handles
  • SQL_HANDLE_STMT for statement handles
SQLHANDLE Handle input Specifies a handle for the diagnostic data structure. This handle must be the type of handle that the HandleType argument indicates.
SQLSMALLINT RecNumber input Indicates the status record from which the application seeks information. Status records are numbered from 1.
SQLCHAR * SQLState output Points to a buffer in which the five-character SQLSTATE, which corresponds to the diagnostic record that is specified in the RecNumber argument, is returned. The first two characters of this SQLSTATE indicate the class; the next three characters indicate the subclass.
SQLINTEGER * NativeErrorPtr output Points to a buffer in the native error code, which is specific to the data source, is returned.
SQLCHAR * MessageText output Points to a buffer in which the error message text is returned. The fields returned by SQLGetDiagRec() are contained in a text string.
SQLSMALLINT BufferLength input Length (in bytes) of the buffer that the MessageText argument specifies.
SQLSMALLINT * TextLengthPtr output Pointer to a buffer that contains the total number of bytes that are available in the buffer that the MessageText argument points to. The total number of available bytes does not include the number of bytes for nul-termination characters. If the number of bytes available to return is greater than the value that the BufferLength argument specifies, the error message text in the buffer is truncated to the value specified for the BufferLength argument minus the length of a nul-termination character.

Usage

An application typically calls SQLGetDiagRec() when a previous call to a Db2 ODBC function has returned anything other than SQL_SUCCESS. However, because any function can post zero or more errors each time it is called, an application can call SQLGetDiagRec() after any function call. An application can call SQLGetDiagRec() multiple times to return some or all of the records in the diagnostic data structure.

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

An application can scan all diagnostic records by looping while it increments RecNumber as long as SQLGetDiagRec() returns SQL_SUCCESS.

Calls to SQLGetDiagRec() are nondestructive to the diagnostic record fields. 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() (or the ODBC 2.0 SQLGetDiagRec() function), has been called in the interim.

Return codes

After you call SQLGetDiagRec(), it returns one of the following values:
  • SQL_SUCCESS
  • SQL_SUCCESS_WITH_INFO
  • SQL_INVALID_HANDLE
  • SQL_ERROR
For a description of each of these return code values, see the Diagnostics.

Diagnostics

SQLGetDiagRec() does not post error values. It uses the function return codes to report diagnostic information. When you call SQLGetDiagRec(), these return codes represent the diagnostic information:
  • SQL_SUCCESS: The function successfully returned diagnostic information.
  • SQL_SUCCESS_WITH_INFO: The buffer that to which the MessageText argument points is too small to hold the requested diagnostic message. No diagnostic records are generated. To determine whether truncation occurred, compare the value specified for the BufferLength argument to the actual number of bytes available, which is written to the buffer to which the TextLengthPtr argument points.
  • SQL_INVALID_HANDLE: The handle indicated by HandleType and Handle is not a valid handle.
  • SQL_ERROR: One of the following occurred:
    • The RecNumber argument is negative or 0.
    • The BufferLength argument is less than zero.
  • SQL_NO_DATA: The RecNumber argument is greater than the number of diagnostic records that exist for the handle that is specified in the Handle argument. The function also returns SQL_NO_DATA for any positive value for the RecNumber argument if no diagnostic records are produced for the handle that theHandle argument specifies.

Example

Refer to the DSN8O3VP sample application or online in the data set DSN1310.SDSNSAMP