home *** CD-ROM | disk | FTP | other *** search
/ NeXTSTEP 3.3 (Developer) / NeXT_Developer-3.3.iso / NextLibrary / Documentation / Sybase / DBLIB / Section2 / dberrhandle.nr < prev    next >
Encoding:
Text File  |  1993-04-22  |  4.1 KB  |  135 lines
  1. .Na "dberrhandle" 
  2. .Aa
  3. .Fu
  4. Install a user function to handle \*L errors.
  5. .Ih "error handler, installing"
  6. .Ih "\*L errors"
  7. .Ih "errors, \*L"
  8. .Sy
  9. .Sf "int (*dberrhandle(handler))()"
  10. .Sp "int" "(*handler)()"
  11. .Co
  12. .Bl
  13. \f2dberrhandle()\f1 installs an error-handler function that you supply.
  14. When a \*L error occurs, \*L will call this
  15. error handler immediately. 
  16. You must install an error handler
  17. in order to handle \*L errors properly.
  18. .Bl
  19. The user-supplied error handler will completely determine the response
  20. of \*L to any error that occurs.
  21. It must tell \*L whether to:
  22. .in +5n
  23. .Bl *
  24. abort the program,
  25. .Bl *
  26. return an error code, \f2or\f1
  27. .Bl *
  28. keep trying (in the case of a timeout error).
  29. .in -5n
  30. .Bl
  31. If the user does not supply an error handler (or passes a NULL pointer
  32. to \f2dberrhandle()\fP), \*L will exhibit its default error-handling
  33. behavior:  It will abort the program if the error 
  34. has made the affected DBPROCESS unusable (the user can call \f2DBDEAD()\fP
  35. to determine whether or not a DBPROCESS has become unusable). If the error
  36. has not made the DBPROCESS unusable, \*L will simply return an error code
  37. to its caller.
  38. .Bl
  39. You can de-install an existing error handler by calling \f2dberrhandle()\f1 with a 
  40. NULL parameter.
  41. You can also, at any time, install a new error handler.
  42. The new handler will automatically replace any existing handler.
  43. .Bl
  44. If the program refers to error severity values, its source file must include the header
  45. file \f2syberror.h\f1.
  46. .Bl
  47. See the \f2errors\f1 manual page for a list of \*L errors.
  48. .Bl
  49. Another routine, \f2dbmsghandle()\f1, installs a message handler that \*L calls
  50. in response to \*S error messages.
  51. If the application provokes messages from \*L and \*S simultaneously,
  52. \*L calls the \*S message handler before it calls the \*L error handler.
  53. .Bl
  54. The \*L error value SYBESMSG is always generated in response to a \*S message.
  55. If you have installed a \*S message handler, you may want to write your \*L error handler
  56. so as to suppress the printing of any SYBESMSG error, to avoid notifying
  57. the user about the same error twice.
  58. .Bz
  59. .Pa
  60. .Pi handler
  61. A pointer to the user function that will be called whenever
  62. \*L determines that an error has occurred. \*L calls this function
  63. with six parameters:
  64. .sp
  65. .in +10n
  66. .ta +10n
  67. .ti -10n
  68. \f2dbproc\f1    The affected DBPROCESS. If there is no DBPROCESS associated with this error, 
  69. this parameter will be NULL.
  70. .sp 0.5v
  71. .ti -10n
  72. \f2severity\f1    The severity of the error (datatype \f2int\f1).
  73. Error severities are defined in \f2syberror.h\f1.
  74. .sp 0.5v
  75. .ti -10n
  76. \f2dberr\f1    The identifying number of the error (datatype \f2int\f1).
  77. Error numbers are defined in \f2sybdb.h\f1.
  78. .sp 0.5v
  79. .ti -10n
  80. \f2oserr\f1    The operating-system-specific error number that describes the cause 
  81. of the error (datatype \f2int\f1).
  82. If there is no relevant operating-system error, the value of this parameter will be DBNOERR.
  83. .sp 0.5v
  84. .mc |
  85. .ti -10n
  86. \f2dberrstr\f1    A printable description of \f2dberr\f1 (datatype \f2char *\f1).
  87. .sp 0.5v
  88. .ti -10n
  89. \f2oserrstr\f1    A printable description of \f2oserr\f1 (datatype \f2char *\f1).
  90. .sp
  91. .mc
  92. .in -10n
  93. The error handler must return one of the following three values, directing \*L
  94. to perform particular actions:
  95. .sp
  96. .in +17n
  97. .ta +17n
  98. .ti -17n
  99. INT_EXIT    Print an error message and abort the program.
  100. \*L will also return
  101. an error indication to the operating system.
  102. (Note to UNIX programmers: \*L will not leave a core file.)
  103. .sp 0.5v
  104. .ti -17n
  105. INT_CANCEL    Return FAIL from the \*L routine that caused the error, 
  106. and set the global \*L error number.
  107. .sp 0.5v
  108. .ti -17n
  109. INT_CONTINUE    Continue to wait for one additional timeout period.
  110. At the end of that period, call the error handler again.
  111. This return value is meaningful only for timeout
  112. errors (SYBETIME). In any other case, this value
  113. will be considered an error, and will be treated
  114. as an INT_EXIT.
  115. .sp
  116. .in -17n
  117. If the error handler returns any value besides these three, the program will abort.
  118. .sp
  119. The following example shows a typical error handler routine:
  120. .ta +4n +4n +4n +4n +4n +4n
  121. .SD
  122. .mc |
  123. .so dberrhandle.ex
  124. .mc
  125. .ED
  126. .in -.375i
  127. .Re
  128. .br
  129. A pointer to the previously-installed error handler.
  130. This may be NULL.
  131. .Sa
  132. DBDEAD,
  133. dbmsghandle, 
  134. errors
  135.