16.9.13 SQLGetDiagRec, SQLGetDiagRecW

(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.

To Page Top

(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 */
  )

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.

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.

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 MessageText was too small for the diagnostic message text, resulting in truncation. You can determine the truncated size by comparing BufferLength and TextLengthPtr. 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: The value specified in RecNumber is less than or equal to 0. The value specified in BufferLength is less than 0. 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.

• SQLCODE is set in NativeErrorPtr. For details about SQLCODE, see Interpreting SQLCODEs in the manual HADB Messages.

• The function does not return diagnostic information.

To Page Top