SQLError() returns the diagnostic information associated with the most recently called DB2® UDB CLI function for a particular statement, connection or environment handle.
The information consists of a standardized SQLSTATE, an error code, and a text message. Refer to Diagnostics in a DB2 UDB CLI application for more information.
Call SQLError() after receiving a return code of SQL_ERROR or SQL_SUCCESS_WITH_INFO from another function call.
SQLRETURN SQLError (SQLHENV henv,
SQLHDBC hdbc,
SQLHSTMT hstmt,
SQLCHAR *szSqlState,
SQLINTEGER *pfNativeError,
SQLCHAR *szErrorMsg,
SQLSMALLINT cbErrorMsgMax,
SQLSMALLINT *pcbErrorMsg);
| Data type | Argument | Use | Description |
|---|---|---|---|
| SQLCHAR * | szErrorMsg | Output | Pointer to buffer to contain the implementation defined message text. In DB2 UDB CLI, only the DBMS generated messages is returned; DB2 UDB CLI itself does not return any message text describing the problem. |
| SQLCHAR * | szSqlState | Output | SQLSTATE as a string of 5 characters terminated by a null character. The first 2 characters indicate error class; the next 3 indicate subclass. The values correspond directly to SQLSTATE values defined in the X/Open SQL CAE specification and the ODBC specification, augmented with IBM® specific and product specific SQLSTATE values. |
| SQLHDBC | hdbc | Input | Database connection handle. To obtain diagnostic information associated with a connection, pass a valid database connection handle, and set hstmt to SQL_NULL_HSTMT. The henv argument is ignored. |
| SQLHENV | henv | Input | Environment handle. To obtain diagnostic information associated with an environment, pass a valid environment handle. Set hdbc to SQL_NULL_HDBC. Set hstmt to SQL_NULL_HSTMT. |
| SQLHSTMT | hstmt | Input | Statement handle. To obtain diagnostic information associated with a statement, pass a valid statement handle. The henv and hdbc arguments are ignored. |
| SQLINTEGER * | pfNativeError | Output | Native error code. In DB2 UDB CLI, the pfNativeError argument contains the SQLCODE value returned by the Database Management System (DBMS). If the error is generated by DB2 UDB CLI and not the DBMS, this field is set to -99999. |
| SQLSMALLINT * | pcbErrorMsg | Output | Pointer to total number of bytes available to return to the szErrorMsg buffer. |
| SQLSMALLINT | cbErrorMsgMax | Input | Maximum (that is, the allocated) length of the buffer szErrorMsg. The recommended length to allocate is SQL_MAX_MESSAGE_LENGTH + 1. |
The SQLSTATEs are those defined by the X/OPEN SQL CAE and the X/Open SQL CLI snapshot, augmented with IBM specific and product specific SQLSTATE values.
If diagnostic information generated by one DB2 UDB CLI function is not retrieved before a function other than SQLError() is called with the same handle, the information for the previous function call is lost. This is true whether diagnostic information is generated for the second DB2 UDB CLI function call.
To avoid truncation of the error message, declare a buffer length of SQL_MAX_MESSAGE_LENGTH + 1. The message text is never longer than this.
SQLSTATEs are not defined because SQLError() does not generate diagnostic information for itself. SQL_ERROR is returned if argument szSqlState, pfNativeError, szErrorMsg, or pcbErrorMsg is a null pointer.