SQLError() - Retrieve error information

SQLError() is a deprecated function and is replaced by SQLGetDiagRec().

ODBC Specifications for SQLError()

Table 1. SQLError() specifications
ODBC specification level In X/Open CLI CAE specification? In ISO CLI specification?
1.0 (Deprecated) Yes Yes

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

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

Table 2. SQLError() 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 ODBC, the pfNativeError argument contains the SQLCODE value returned by the database management system. If the error is generated by Db2 ODBC and not the database management system, then this field is set to -99999.
SQLCHAR * szErrorMsg output Pointer to buffer to contain the implementation defined message text. If the error is detected by Db2 ODBC, then the error message is prefaced by: 
[DB2 for z/OS][CLI Driver]
This preface indicates that Db2 ODBC detected the error and a connection to a database has not yet been made.

The error location, ERRLOC x:y:z, keyword value is embedded in the buffer also. This is an internal error code for diagnostics.

If the error is detected during a database connection, then the error message returned from the database management system is prefaced by: 
[DB2 for z/OS][CLI Driver][database server-name]
database management system-name is the name that is returned by SQLGetInfo() with SQL_database management system_NAME information type.
For example,
  • DB2
  • DB2/6000
  • Vendor

Vendor indicates a non-IBM DRDA database management system.

If the error is generated by the database management system, the IBM-defined SQLSTATE is appended to the text string.
SQLSMALLINT cbErrorMsgMax input The maximum (that is, the allocated) length, in bytes, 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 nul-terminator.