dberrhandle

Description

Install a user function to handle DB-Library errors.

Syntax

int (*dberrhandle(handler))()
 
int          (*handler)();

Parameters

handler

A pointer to the user function that will be called whenever DB-Library determines that an error has occurred. DB-Library calls this function with six parameters shown in Table 2-17.

**Table 2-17: Error handler parameters**
Parameter	Meaning
dbproc	The affected DBPROCESS. If there is no DBPROCESS associated with this error, this parameter will be NULL.
severity	The severity of the error (datatype int). Error severities are defined in syberror.h.
dberr	The identifying number of the error (datatype int). Error numbers are defined in sybdb.h.
oserr	The operating-system-specific error number that describes the cause of the error (datatype int). If there is no relevant operating system error, the value of this parameter will be DBNOERR.
dberrstr	A printable description of dberr (datatype char *).
oserrstr	A printable description of oserr (datatype char *).

The error handler must return one of the four values listed in Table 2-18, directing DB-Library to perform particular actions:

**Table 2-18: Error handler returns**
Return	Action
INT_EXIT	Print an error message and abort the program. DB-Library will also return an error indication to the operating system. (Note to UNIX programmers: DB-Library will not leave a core file.
INT_CANCEL	Return FAIL from the DB-Library routine that caused the error. Returning INT_CANCEL on timeout errors will kill the dbproc.
INT_TIMEOUT	Cancel the operation that caused the error but leave the dbproc in working condition. This return value is meaningful only for timeout errors (SYBETIME). In any other case, this value will be considered an error, and will be treated as an INT_EXIT.
INT_CONTINUE	Continue to wait for one additional timeout period. At the end of that period, call the error handler again. This return value is meaningful only for timeout errors (SYBETIME). In any other case, this value will be considered an error, and will be treated as an INT_EXIT.

If the error handler returns any value besides these four, the program will abort.

Error handlers on the Windows platform must be declared with CS_PUBLIC, as shown in the example below. For portability, callback handlers on other platforms should be declared CS_PUBLIC as well.

The following example shows a typical error handler routine:

#include   <sybfront.h>

#include  <sybdb.h>

#include  <syberror.h>

int CS_PUBLIC err_handler(dbproc, severity, dberr,

oserr, dberrstr, oserrstr)

DBPROCESS    *dbproc;

 int          severity;

 int          dberr;

 int          oserr;

 char         *dberrstr;

 char         *oserrstr;

      if ((dbproc == NULL) || (DBDEAD(dbproc)))

           return(INT_EXIT);

      else

           printf("DB-Library error:\n\t%s\n",

                dberrstr);

           if (oserr != DBNOERR)

                printf("Operating-system \

                     error:\n\t%s\n", oserrstr);

           return(INT_CANCEL);

Returns

A pointer to the previously installed error handler. This pointer is NULL if no error handler was installed before.

Usage

dberrhandle installs an error-handler function that you supply. When a DB-Library error occurs, DB-Library will call this error handler immediately. You must install an error handler to handle DB-Library errors properly.

If an application does not call dberrhandle to install an error-handler function, DB-Library ignores error messages. The messages are not printed.

The user-supplied error handler will completely determine the response of DB-Library to any error that occurs. It must tell DB-Library whether to:

Abort the program, or
Return an error code and mark the DBPROCESS as “dead” (making it unusable), or
Cancel the operation that caused the error, or
Keep trying (in the case of a timeout error).

If the user does not supply an error handler (or passes a NULL pointer to dberrhandle), DB-Library will exhibit its default error-handling behavior: It will abort the program if the error has made the affected DBPROCESS unusable (the user can call DBDEAD to determine whether or not a DBPROCESS has become unusable). If the error has not made the DBPROCESS unusable, DB-Library will simply return an error code to its caller.

You can “de-install” an existing error handler by calling dberrhandle with a NULL parameter. You can also, at any time, install a new error handler. The new handler will automatically replace any existing handler.

If the program refers to error severity values, its source file must include the header file called syberror.h.

See Errors for a list of DB-Library errors.
Another routine, dbmsghandle, installs a message handler that DB-Library calls in response to the server error messages.
If the application provokes messages from DB-Library and the server simultaneously, DB-Library calls the server message handler before it calls the DB-Library error handler.

The DB-Library/C error value SYBESMSG is generated in response to a server error message, but not in response to a server informational message. This means that when a server error occurs, both the server message handler and the DB-Library/C error handler are called, but when the server generates an informational message, only the server message handler is called.

If you have installed a server message handler, you may want to write your DB-Library error handler so as to suppress the printing of any SYBESMSG error, to avoid notifying the user about the same error twice.

Table 2-19 provides information on when DB-Library/C calls an application’s message and error handlers:

**Table 2-19: Common errors**
Error or message	Message handler called?	Error handler called?
SQL syntax error.	Yes.	Yes (SYBESMSG). (Code your handler to ignore the message.)
SQL print statement.	Yes.	No.
SQL raiserror.	Yes.	No.
Server dies.	No.	Yes (SYBESEOF). (Code your handler to exit the application.)
Timeout from the server. The default timeout period is infinite. The error handler will not receive timeout notifications unless a timeout period is specified with dbsettime.	No.	Yes (SYBETIME). (To wait for another timeout period, code your handler to return -INT_CONTINUE.)
Deadlock on query.	Yes. (Code your handler to test for deadlock. See the dbsetuserdata for an example.)	Yes (SYBESMSG). (Code your handler to ignore the message.)
Timeout on login.	No.	Yes (SYBEFCON, SYBECONN).
Login fails (dbopen).	Yes.	Yes (SYBEPWD). (Code your handler to exit the application.)
Use database message.	Yes. (Code your handler to ignore the message.)	No.
Incorrect use of DB-Library/C calls, such as not calling dbresults when required.	No.	Yes (SYBERPND, ...) Yes (SYBERPND, .)
Fatal Server error (severity greater than 16).	Yes. (Code your handler to exit the application.)	Yes (SYBESMSG).