dberrhandle

Supplies a user function to handle DB-Library errors.

Syntax

DBERRHANDLE_PROC dberrhandle ( DBERRHANDLE_PROC handler );

where

handler
Is a pointer to the user function that is called whenever DB-Library determines that an error has occurred. DB-Library calls this function with six parameters:
dbproc
Is the affected DBPROCESS. If there is no DBPROCESS associated with this error, this parameter is NULL.
severity
Is the severity of the error (datatype int). Error severities are defined in SQLFRONT.H.
dberr
Is the identifying number of the error (datatype int). Error numbers are defined in SQLFRONT.H.
oserr
Is the error number that describes the cause of the error (datatype int) and is specific to the operating system or network. If there is no relevant operating system error, the value is DBNOERR.
dberrstr
Is a printable description of dberr (datatype char *).
oserrstr
Is a printable description of oserr (datatype char *).

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.

Returns

A pointer to the previously installed error handler. This can be NULL.

Remarks

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(. . .
}

See Also

dbmsghandle; Error Messages