Status of this Function since DB2 CLI Version 5
| Note: |
In ODBC version 3, SQLError() has been deprecated and replaced with SQLGetDiagRec() and SQLGetDiagField(); see SQLGetDiagRec - Get Multiple Fields Settings of Diagnostic Record and SQLGetDiagField - Get a Field of Diagnostic Data for more information. Although this version of DB2 CLI continues to support SQLError(), we recommend that you begin using SQLGetDiagRec() in your DB2 CLI programs so that they conform to the latest standards. See DB2 CLI Functions Deprecated for Version 5 for more information on this and other deprecated functions. |
Purpose
| Specification: | DB2 CLI 1.1 | ODBC 1.0 | ISO CLI |
SQLError() returns the diagnostic information (both errors and warnings) associated with the most recently invoked DB2 CLI function for a particular statement, connection or environment handle.
The information consists of a standardized SQLSTATE, native error code, and a text message. Refer to Diagnostics for more information.
Call SQLError() after receiving a return code of SQL_ERROR or SQL_SUCCESS_WITH_INFO from another function call.
| Note: | Some database servers may provide product-specific diagnostic information after returning SQL_NO_DATA_FOUND from the execution of a statement. |
Syntax
SQLRETURN SQLError (SQLHENV henv,
SQLHDBC hdbc,
SQLHSTMT hstmt,
SQLCHAR FAR *szSqlState,
SQLINTEGER FAR *pfNativeError,
SQLCHAR FAR *szErrorMsg,
SQLSMALLINT cbErrorMsgMax,
SQLSMALLINT FAR *pcbErrorMsg);
Function Arguments
| Data Type | Argument | Use | Description |
|---|---|---|---|
| SQLHENV | henv | input | Environment handle. To obtain diagnostic information associated with an environment, pass a valid environment handle. Set hdbc and hstmt to SQL_NULL_HDBC and SQL_NULL_HSTMT respectively. |
| 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. |
| 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. |
| 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. |
| SQLINTEGER * | pfNativeError | output | Native error code. In DB2 CLI, the pfNativeError argument will contain the SQLCODE value returned by the DBMS. If the error is generated by DB2 CLI and not the DBMS, then this field will be set to -99999. |
| SQLCHAR * | szErrorMsg | output | Pointer to buffer to contain the implementation defined message
text. If the error is detected by DB2 CLI, then the error message would
be prefaced by:
[IBM][CLI Driver]to indicate that it is DB2 CLI that detected the error and there is no database connection yet. If the error is detected while there is a database connection, then the error message returned from the DBMS would be prefaced by: [IBM][CLI Driver][DBMS-name] where DBMS-name is the name returned by SQLGetInfo() with SQL_DBMS_NAME information type. For example,
If the DBMS-name is not regcognized then DB2 CLI will treat it as a DB2 Universal Database version 5 data source. If the error is generated by the DBMS, the IBM defined SQLSTATE will be appended to the text string. |
| SQLSMALLINT | cbErrorMsgMax | input | The maximum (that is, the allocated) length of the buffer szErrorMsg. The recommended length to allocate is SQL_MAX_MESSAGE_LENGTH + 1. |
| SQLSMALLINT * | pcbErrorMsg | output | Pointer to total number of bytes available to return to the szErrorMsg buffer. This does not include the null termination character. |
Usage
The SQLSTATEs are those defined by the X/OPEN SQL CAE and the X/Open SQL CLI CAE, augmented with IBM specific and product specific SQLSTATE values.
To obtain diagnostic information associated with:
If diagnostic information generated by one DB2 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 or not diagnostic information is generated for the second DB2 CLI function call.
Multiple diagnostic messages may be available after a given DB2 CLI function call. These messages can be retrieved one at a time by repeatedly calling SQLError(). For each message retrieved, SQLError() returns SQL_SUCCESS and removes it from the list of messages available. When there are no more messages to retrieve, SQL_NO_DATA_FOUND is returned, the SQLSTATE is set to "00000", pfNativeError is set to 0, and pcbErrorMsg and szErrorMsg are undefined.
Diagnostic information stored under a given handle is cleared when a call is made to SQLError() with that handle, or when another DB2 CLI function call is made with that handle. However, information associated with a given handle type is not cleared by a call to SQLError() with an associated but different handle type: for example, a call to SQLError() with a connection handle input will not clear errors associated with any statement handles under that connection.
SQL_SUCCESS is returned even if the buffer for the error message (szErrorMsg) is too short since the application will not be able to retrieve the same error message by calling SQLError() again. The actual length of the message text is returned in the pcbErrorMsg.
To avoid truncation of the error message, declare a buffer length of SQL_MAX_MESSAGE_LENGTH + 1. The message text will never be longer than this.
| Note: | The defined value of SQL_MAX_MESSAGE_LENGTH has been increased since DB2 CLI Version 1. |
Return Codes
SQL_NO_DATA_FOUND is returned if no diagnostic information is available for the input handle, or if all of the messages have been retrieved via calls to SQLError().
Diagnostics
SQLSTATEs are not defined, since SQLError() does not generate diagnostic information for itself.
Restrictions
Although ODBC also returns X/Open SQL CAE SQLSTATEs, only DB2 CLI (and the DB2 ODBC driver) returns the additional IBM defined SQLSTATEs. The ODBC Driver Manager also returns SQLSTATE values with a prefix of IM. These SQLSTATES are not defined by X/Open and are not returned by DB2 CLI. For more information on ODBC specific SQLSTATEs refer to ODBC 3.0 Software Development Kit and Programmer's Reference.
Because of this, you should only build dependencies on the standard SQLSTATEs. This means any branching logic in the application should only rely on the standard SQLSTATEs. The augmented SQLSTATEs are most useful for debugging purposes.
| Note: | It may be useful to build dependencies on the class (the first 2 characters) of the SQLSTATEs. |
Refer to SQLGetDiagRec - Get Multiple Fields Settings of Diagnostic Record.
References