ASA Programming Guide
ODBC Programming
Errors in ODBC are reported using the return value from each of the ODBC function calls and either the SQLError function or the SQLGetDiagRec function. The SQLError function was used in ODBC versions up to, but not including, version 3. As of version 3 the SQLError function has been deprecated and replaced by the SQLGetDiagRec function.
Every ODBC function returns a SQLRETURN, which is one of the following status codes:
| Status code | Description |
|---|---|
| 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 because of an error. 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 ODBC SDK documentation 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 or SQLGetDiagRec returns the information for one error and removes the information for that error. If you do not call SQLError or SQLGetDiagRec to remove all errors, the errors are removed on the next function call that passes the same handle as a parameter.
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 get any error associated with the environment handle.
Each call to SQLGetDiagRec can pass either an environment, connection or statement handle. The first call passes in a handle of type SQL_HANDLE_DBC to get the error associated with a connection. The second call passes in a handle of type SQL_HANDLE_STMT to get the error associated with the statement that was just executed.
SQLError and SQLGetDiagRec return 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 following code fragment uses SQLError and return codes:
/* Declare required variables */
SQLHDBC dbc;
SQLHSTMT stmt;
SQLRETURN retcode;
UCHAR errmsg[100];
/* code omitted here */
retcode = SQLAllocHandle(SQL_HANDLE_STMT, 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( "Allocation failed", 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;
}The following code fragment uses SQLGetDiagRec and return codes:
/* Declare required variables */
SQLHDBC dbc;
SQLHSTMT stmt;
SQLRETURN retcode;
SQLSMALLINT errmsglen;
SQLINTEGER errnative;
UCHAR errmsg[255];
UCHAR errstate[5];
/* code omitted here */
retcode = SQLAllocHandle(SQL_HANDLE_STMT, dbc, &stmt );
if( retcode == SQL_ERROR ){
SQLGetDiagRec(SQL_HANDLE_DBC, dbc, 1, errstate,
&errnative, errmsg, sizeof(errmsg), &errmsglen);
/* Assume that print_error is defined */
print_error( "Allocation failed", errstate,
errnative, errmsg );
return;
}
/* Delete items for order 2015 */
retcode = SQLExecDirect( stmt,
"delete from sales_order_items where id=2015",
SQL_NTS );
if( retcode == SQL_ERROR ) {
SQLGetDiagRec(SQL_HANDLE_STMT, stmt, recnum,
errstate,
&errnative, errmsg, sizeof(errmsg), &errmsglen);
/* Assume that print_error is defined */
print_error("Failed to delete items", errstate,
errnative, errmsg );
return;
}