Hitachi

Hitachi Advanced Database Application Development Guide


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

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

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

(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