Supplies a user function to handle DB-Library errors.
DBERRHANDLE_PROC dberrhandle ( DBERRHANDLE_PROC handler );
where
The error handler must return one of the following three values, directing DB-Library to perform particular actions:
| Value | Action |
|---|---|
| INT_EXIT | Prints an error message and exits the application. DB-Library also returns an error to the operating system. With the Windows operating system, this value is considered an error and is treated as an INT_CANCEL. |
| INT_CANCEL | Returns FAIL from the DB-Library function that caused the error. For timeout errors (SQLETIME) only, DB-Library will call dbcancel in an attempt to cancel the current command batch and flush any pending results. If this dbcancel attempt also times out, the connection is broken. |
| INT_CONTINUE | Continues to wait for one additional timeout period, and then calls the error handler again. This return value is meaningful only for timeout errors (SQLETIME). In any other case, this value is considered an error and is treated as an INT_CANCEL. |
If the error handler returns any value besides these three, the program continues.
The following example shows a typical error-handling routine:
#include <sqlfront.h>
#include <sqldb.h>
int err_handler(dbproc, severity, dberr, oserr, dberrstr, oserrstr)
DBPROCESS *dbproc;
int severity;
int dberr;
int oserr;
char *dberrstr;
char *oserrstr;
{
printf("DB-Library error:\n\t%s\n", dberrstr);
if (severity == EXCOMM && (oserr != DBNOERR || oserrstr))
printf(Net-Lib error %d: %s\n"' oserr, oserrstr);
if (oserr != DBNOERR)
printf("Operating-system error:\n\t%s\n", oserrstr);
if (dbproc == NULL) || (DBDEAD(dbproc))
return(INT_EXIT);
else
return(INT_CANCEL);
}
Important Do not call any DB-Library functions from within the error handler, because infinite recursive calls to the error handler can result.
A pointer to the previously installed error handler. This can be NULL.
When a DB-Library error occurs, DB-Library immediately calls this error handler. You must install an error handler to handle DB-Library errors properly.
Since the error handler is a call-back function, special consideration is required when compiling these functions for the Windows operating system. For more information, see Building Applications. The user-supplied error handler completely determines the response of DB-Library to any error that occurs. It must tell DB-Library which action to take:
If the user does not supply an error handler (or passes a null pointer to dberrhandle), DB-Library exhibits its default error-handling behavior: it returns FAIL from the DB-Library function that caused the error and program execution continues.
Another function, dbmsghandle, installs a message handler that DB-Library calls in response to SQL Server messages. If an application causes messages to occur from DB-Library and SQL Server simultaneously, DB-Library calls the SQL Server message handler before it calls the DB-Library error handler.
The error-handling function should not call any DB-Library functions. Since calls to DB-Library functions can themselves generate errors, calls from within an error handler could result in infinite recursion. If your error handler must call a DB-Library function, it should set the error-handler to a null value, and then restore it when it exits.
The following code fragment shows this technique:
int err_handler (dbproc, . . .
{
// Set the error handler to NULL to prevent infinite recursion.
dberrhandle(NULL);
// Call other DB_Library functions as necessary.
.
.
.
// Reset the error handler to this function.
dberrhandle(err_handler);
return(. . .
}