Programming Interfaces Guide
CHAPTER 4. ODBC Programming
The previous example did not check for any errors. Errors in ODBC are reported using the return value from each of the ODBC API function calls and the SQLError function.
Every ODBC API function returns a RETCODE, which is one of the following status codes:
SQL_SUCCESS No error.
SQL_SUCCESS_WITH_INFO The function completed, but a call to SQLError will indicate a warning. The most common case for this status is that a value being returned is too long for the buffer provided by the application.
SQL_ERROR The function did not complete due to an error. You can call SQLError to get more information on the problem.
SQL_INVALID_HANDLE An invalid environment, connection, or statement handle was passed as a parameter. This often happens if a handle is used after it has been freed, or if the handle is the null pointer.
SQL_NO_DATA_FOUND There is no information available. The most common use for this status is when fetching from a cursor; it indicates that there are no more rows in the cursor.
SQL_NEED_DATA Data is needed for a parameter. This is an advanced feature described in the help file under SQLParamData and SQLPutData.
Every environment, connection, and statement handle can have one or more errors or warnings associated with it. Each call to SQLError returns the information for one error and removes the information for that error. If you do not call SQLError to remove all errors, the errors are removed on the next function call that passes the same handle as a parameter.
The following program fragment uses SQLError and return codes:
HDBC dbc;
HSTMT stmt;
RETCODE retcode;
UCHAR errmsg[100];
. . .
retcode = SQLAllocStmt( dbc, &stmt );
if( retcode == SQL_ERROR ) {
SQLError( env, dbc, SQL_NULL_HSTMT, NULL, NULL,
errmsg, sizeof(errmsg), NULL );
/* Assume that print_error is defined */
print_error( "Failed SQLAllocStmt", errmsg );
return;
}
/* Delete items for order 2015 */
retcode = SQLExecDirect( stmt,
"delete from sales_order_items
where id=2015", SQL_NTS );
if( retcode == SQL_ERROR ) {
SQLError( env, dbc, stmt, NULL, NULL,
errmsg, sizeof(errmsg), NULL );
/* Assume that print_error is defined */
print_error( "Failed to delete items", errmsg );
return;
}
. . .
Note that each call to SQLError passes three handles for an environment, connection, and statement. The first call uses SQL_NULL_HSTMT to get the error associated with a connection. Similarly, a call with both SQL_NULL_DBC and SQL_NULL_HSTMT will get any error associated with the environment handle.
The return value from SQLError may seem confusing. It returns SQL_SUCCESS if there is an error to report (not SQL_ERROR), and SQL_NO_DATA_FOUND if there are no more errors to report.
The examples pass the null pointer for some of the parameters to SQLError. The help file contains a full description of SQLError and all its parameters.