home *** CD-ROM | disk | FTP | other *** search
/ NeXTSTEP 3.3 (Developer) / NeXT_Developer-3.3.iso / usr / sybase / doc / dberrhandle.man < prev    next >
Encoding:
Text File  |  1993-04-22  |  6.9 KB  |  177 lines
  1.  
  2.   1                       Version 4.0 -- 5/1/89              dberrhandle
  3.   ______________________________________________________________________
  4.  
  5.   NAME:  dberrhandle
  6.  
  7.   FUNCTION:
  8.        Install a user function to handle DB-Library errors.
  9.  
  10.   SYNTAX:
  11.        int (*dberrhandle(handler))()
  12.  
  13.        int       (*handler)();
  14.  
  15.   COMMENTS:
  16.  
  17.        o dberrhandle()  installs  an  error-handler  function  that  you
  18.  
  19.  
  20.  
  21.  
  22.  
  23.  
  24.   dberrhandle             Version 4.0 -- 5/1/89                        2
  25.   ______________________________________________________________________
  26.          supply.  When a DB-Library error occurs, DB-Library  will  call
  27.          this  error  handler  immediately.  You  must  install an error
  28.          handler in order to handle DB-Library errors properly.
  29.  
  30.        o The user-supplied error handler will completely  determine  the
  31.          response  of DB-Library to any error that occurs.  It must tell
  32.          DB-Library whether to:
  33.             o abort the program,
  34.  
  35.             o return an error code, or
  36.             o keep trying (in the case of a timeout error).
  37.  
  38.        o If the user does not supply an error handler (or passes a  NULL
  39.          pointer  to dberrhandle()), DB-Library will exhibit its default
  40.          error-handling behavior:  It will  abort  the  program  if  the
  41.          error  has  made  the affected DBPROCESS unusable (the user can
  42.          call DBDEAD() to determine  whether  or  not  a  DBPROCESS  has
  43.          become  unusable).  If  the  error  has  not made the DBPROCESS
  44.  
  45.  
  46.   3                       Version 4.0 -- 5/1/89              dberrhandle
  47.   ______________________________________________________________________
  48.          unusable, DB-Library will simply return an error  code  to  its
  49.          caller.
  50.  
  51.        o You can de-install an existing error handler by  calling  dber-
  52.          rhandle()  with  a  NULL parameter.  You can also, at any time,
  53.          install a new error handler.  The new  handler  will  automati-
  54.          cally replace any existing handler.
  55.        o If the program refers to error severity values, its source file
  56.          must include the header file syberror.h.
  57.  
  58.        o See the errors manual page for a list of DB-Library errors.
  59.        o Another routine, dbmsghandle(), installs a message handler that
  60.          DB-Library  calls in response to SQL Server error messages.  If
  61.          the  application  provokes   messages   from   DB-Library   and
  62.          SQL Server simultaneously, DB-Library calls the SQL Server mes-
  63.          sage handler before it calls the DB-Library error handler.
  64.  
  65.        o The DB-Library error value  SYBESMSG  is  always  generated  in
  66.  
  67.  
  68.   dberrhandle             Version 4.0 -- 5/1/89                        4
  69.   ______________________________________________________________________
  70.          response to a SQL Server message.   If  you  have  installed  a
  71.          SQL Server   message  handler,  you  may  want  to  write  your
  72.          DB-Library error handler so as to suppress the printing of  any
  73.          SYBESMSG  error,  to  avoid  notifying  the user about the same
  74.          error twice.
  75.  
  76.   PARAMETERS:
  77.        handler -  A pointer to the user function  that  will  be  called
  78.            whenever  DB-Library  determines  that an error has occurred.
  79.            DB-Library calls this function with six parameters:
  80.  
  81.            dbproc    The affected DBPROCESS. If there  is  no  DBPROCESS
  82.                      associated  with this error, this parameter will be
  83.                      NULL.
  84.  
  85.            severity  The severity of the error  (datatype  int).   Error
  86.                      severities are defined in syberror.h.
  87.  
  88.  
  89.  
  90.   5                       Version 4.0 -- 5/1/89              dberrhandle
  91.   ______________________________________________________________________
  92.            dberr     The identifying number of the error (datatype int).
  93.                      Error numbers are defined in sybdb.h.
  94.  
  95.            oserr     The  operating-system-specific  error  number  that
  96.                      describes  the  cause  of the error (datatype int).
  97.                      If there is no relevant operating-system error, the
  98.                      value of this parameter will be DBNOERR.
  99.            dberrstr  A printable description of dberr (datatype char *).
  100.  
  101.            oserrstr  A printable description of oserr (datatype char *).
  102.  
  103.            The error handler must return  one  of  the  following  three
  104.            values, directing DB-Library to perform particular actions:
  105.  
  106.            INT_EXIT         Print an error message and  abort  the  pro-
  107.                             gram.   DB-Library will also return an error
  108.                             indication to the operating  system.   (Note
  109.                             to  UNIX  programmers:  DB-Library  will not
  110.  
  111.  
  112.   dberrhandle             Version 4.0 -- 5/1/89                        6
  113.   ______________________________________________________________________
  114.                             leave a core file.)
  115.  
  116.            INT_CANCEL       Return FAIL from the DB-Library routine that
  117.                             caused   the   error,  and  set  the  global
  118.                             DB-Library error number.
  119.            INT_CONTINUE     Continue to wait for one additional  timeout
  120.                             period.  At the end of that period, call the
  121.                             error handler again.  This return  value  is
  122.                             meaningful  only  for  timeout errors (SYBE-
  123.                             TIME). In any other case, this value will be
  124.                             considered  an error, and will be treated as
  125.                             an INT_EXIT.
  126.  
  127.            If the error handler returns any value besides  these  three,
  128.            the program will abort.
  129.  
  130.            The following example shows a typical error handler routine:
  131.  
  132.  
  133.  
  134.   7                       Version 4.0 -- 5/1/89              dberrhandle
  135.   ______________________________________________________________________
  136.            #include <sybfront.h>
  137.            #include <sybdb.h>
  138.            #include <syberror.h>
  139.  
  140.            int err_handler(dbproc, severity, dberr, oserr, dberrstr, oserrstr)
  141.            DBPROCESS       *dbproc;
  142.            int             severity;
  143.            int             dberr;
  144.            int             oserr;
  145.            char            *dberrstr;
  146.            char            *oserrstr;
  147.            {
  148.                if ((dbproc == NULL) || (DBDEAD(dbproc)))
  149.                    return(INT_EXIT);
  150.                else
  151.                {
  152.                    printf("DB-Library error:\n\t%s\n", dberrstr);
  153.  
  154.  
  155.  
  156.   dberrhandle             Version 4.0 -- 5/1/89                        8
  157.   ______________________________________________________________________
  158.  
  159.                    if (oserr != DBNOERR)
  160.                        printf("Operating-system error:\n\t%s\n", oserrstr);
  161.  
  162.                    return(INT_CANCEL);
  163.                }
  164.            }
  165.  
  166.  
  167.   RETURNS:
  168.        A pointer to the previously-installed error handler.  This may be
  169.        NULL.
  170.  
  171.   SEE ALSO:
  172.        DBDEAD, dbmsghandle, errors
  173.  
  174.  
  175.  
  176.  
  177.