Supplies a user function to handle DB-Library errors.
DBERRHANDLE_PROC dberrhandle ( DBERRHANDLE_PROC handler );
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 Microsoft 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 time-out errors (SQLETIME) only, DB-Library calls 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 time-out period, and then calls the error handler again. This return value is meaningful only for time-out 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.
Because the error handler is a callback 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 Microsoft® 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. Because 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(. . .
}
| dbmsghandle | Error Messages |