dberrhandle

DB Library for C

DB Library for C

dberrhandle

Supplies a user function to handle DB-Library errors.

Syntax

DBERRHANDLE_PROC dberrhandle ( DBERRHANDLE_PROC handler );

Arguments

handler

Is a pointer to the user function 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 (data type int). Error severities are defined in Sqlfront.h.

dberr

Is the identifying number of the error (data type int). Error numbers are defined in Sqlfront.h.

oserr

Is the error number that describes the cause of the error (data type 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 (data type char *).

oserrstr

Is a printable description of oserr (data type 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 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.

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.

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:

  • Cancel the application.

  • Return an error code.

  • Keep trying (in the case of a time-out error).

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

See Also

dbmsghandle

Error Messages