1 Version 4.0 -- 5/1/89 dberrhandle
______________________________________________________________________
NAME: dberrhandle
FUNCTION:
Install a user function to handle DB-Library errors.
SYNTAX:
int (*dberrhandle(handler))()
int (*handler)();
COMMENTS:
o dberrhandle() installs an error-handler function that you
dberrhandle Version 4.0 -- 5/1/89 2
______________________________________________________________________
supply. When a DB-Library error occurs, DB-Library will call
this error handler immediately. You must install an error
handler in order to handle DB-Library errors properly.
o 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:
o abort the program,
o return an error code, or
o keep trying (in the case of a timeout error).
o 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
3 Version 4.0 -- 5/1/89 dberrhandle
______________________________________________________________________
unusable, DB-Library will simply return an error code to its
caller.
o You can de-install an existing error handler by calling dber-
rhandle() with a NULL parameter. You can also, at any time,
install a new error handler. The new handler will automati-
cally replace any existing handler.
o If the program refers to error severity values, its source file
must include the header file syberror.h.
o See the errors manual page for a list of DB-Library errors.
o Another routine, dbmsghandle(), installs a message handler that
DB-Library calls in response to SQL Server error messages. If
the application provokes messages from DB-Library and
SQL Server simultaneously, DB-Library calls the SQL Server mes-
sage handler before it calls the DB-Library error handler.
o The DB-Library error value SYBESMSG is always generated in
dberrhandle Version 4.0 -- 5/1/89 4
______________________________________________________________________
response to a SQL Server message. If you have installed a
SQL 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.
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:
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.
5 Version 4.0 -- 5/1/89 dberrhandle
______________________________________________________________________
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 following three
values, directing DB-Library to perform particular actions:
INT_EXIT Print an error message and abort the pro-
gram. DB-Library will also return an error
indication to the operating system. (Note
to UNIX programmers: DB-Library will not
dberrhandle Version 4.0 -- 5/1/89 6
______________________________________________________________________
leave a core file.)
INT_CANCEL Return FAIL from the DB-Library routine that
caused the error, and set the global
DB-Library error number.
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 (SYBE-
TIME). 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 three,
the program will abort.
The following example shows a typical error handler routine:
7 Version 4.0 -- 5/1/89 dberrhandle
______________________________________________________________________
#include <sybfront.h>
#include <sybdb.h>
#include <syberror.h>
int 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);
dberrhandle Version 4.0 -- 5/1/89 8
______________________________________________________________________
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 may be
NULL.
SEE ALSO:
DBDEAD, dbmsghandle, errors