1<?xml version="1.0" encoding="UTF-8" standalone="no"?> 2<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> 3<html xmlns="http://www.w3.org/1999/xhtml"> 4 <head> 5 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> 6 <title>DbEnv::set_errcall()</title> 7 <link rel="stylesheet" href="apiReference.css" type="text/css" /> 8 <meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /> 9 <link rel="start" href="index.html" title="Berkeley DB C++ API Reference" /> 10 <link rel="up" href="env.html" title="Chapter 5. The DbEnv Handle" /> 11 <link rel="prev" href="envevent_notify.html" title="DbEnv::set_event_notify()" /> 12 <link rel="next" href="envset_errfile.html" title="DbEnv::set_errfile()" /> 13 </head> 14 <body> 15 <div class="navheader"> 16 <table width="100%" summary="Navigation header"> 17 <tr> 18 <th colspan="3" align="center">DbEnv::set_errcall()</th> 19 </tr> 20 <tr> 21 <td width="20%" align="left"><a accesskey="p" href="envevent_notify.html">Prev</a> </td> 22 <th width="60%" align="center">Chapter 5. 23 The DbEnv Handle 24 </th> 25 <td width="20%" align="right"> <a accesskey="n" href="envset_errfile.html">Next</a></td> 26 </tr> 27 </table> 28 <hr /> 29 </div> 30 <div class="sect1" lang="en" xml:lang="en"> 31 <div class="titlepage"> 32 <div> 33 <div> 34 <h2 class="title" style="clear: both"><a id="envset_errcall"></a>DbEnv::set_errcall()</h2> 35 </div> 36 </div> 37 </div> 38 <pre class="programlisting">#include <db_cxx.h> 39 40void DbEnv::set_errcall(void (*db_errcall_fcn) 41 (const Dbenv *dbenv, const char *errpfx, const char *msg));</pre> 42 <p> 43 When an error occurs in the Berkeley DB library, 44 45 <span> 46 an exception is thrown 47 </span> 48 or an error return value is returned by the interface. In some cases, 49 however, the <span class="bold"><strong>errno</strong></span> value may be 50 insufficient to completely describe the cause of the error, especially 51 during initial application debugging. 52 </p> 53 <p> 54 The <code class="methodname">DbEnv::set_errcall()</code> and 55 <a class="xref" href="envset_errcall.html" title="DbEnv::set_errcall()">DbEnv::set_errcall()</a> methods 56 are used to enhance the mechanism for reporting error messages to the 57 application. In some cases, when an error occurs, Berkeley DB will 58 call <span class="bold"><strong>db_errcall_fcn</strong></span> with additional 59 error information. It is up to the <span class="bold"><strong>db_errcall_fcn</strong></span> function to display the error 60 message in an appropriate manner. 61 </p> 62 <p> 63 Setting <span class="bold"><strong>db_errcall_fcn</strong></span> to NULL 64 unconfigures the callback interface. 65 </p> 66 <p> 67 Alternatively, you can use the 68 <span> 69 <a class="xref" href="envset_error_stream.html" title="DbEnv::set_error_stream()">DbEnv::set_error_stream()</a> 70 and 71 <a class="xref" href="dbset_error_stream.html" title="Db::set_error_stream()">Db::set_error_stream()</a> 72 methods to display the additional information via an output stream, or the 73 </span> 74 75 <a class="xref" href="dbset_errfile.html" title="Db::set_errfile()">Db::set_errfile()</a> or 76 <a class="xref" href="envset_errfile.html" title="DbEnv::set_errfile()">Db::set_errfile()</a> 77 methods to display the additional information via a C library <code class="literal">FILE *</code>. 78 <span>You should not mix these approaches.</span> 79 </p> 80 <p> 81 This error-logging enhancement does not slow performance or 82 significantly increase application size, and may be run during normal 83 operation as well as during application debugging. 84 </p> 85 <p> 86 The <code class="methodname">DbEnv::set_errcall()</code> method configures operations performed 87 using the specified <a class="link" href="env.html" title="Chapter 5. The DbEnv Handle">DbEnv</a> handle, not all 88 operations performed on the underlying database environment. 89 </p> 90 <p> 91 The <code class="methodname">DbEnv::set_errcall()</code> method may be called at any time during the 92 life of the application. 93 </p> 94 <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"> 95 <h3 class="title">Note</h3> 96 <p> 97 Berkeley DB is not re-entrant. Callback functions should not attempt to make library 98 calls (for example, to release locks or close open handles). Re-entering Berkeley DB is 99 not guaranteed to work correctly, and the results are undefined. 100 </p> 101 </div> 102 <div class="sect2" lang="en" xml:lang="en"> 103 <div class="titlepage"> 104 <div> 105 <div> 106 <h3 class="title"><a id="id1670569"></a>Parameters</h3> 107 </div> 108 </div> 109 </div> 110 <div class="sect3" lang="en" xml:lang="en"> 111 <div class="titlepage"> 112 <div> 113 <div> 114 <h4 class="title"><a id="id1670301"></a>db_errcall_fcn</h4> 115 </div> 116 </div> 117 </div> 118 <p> 119 The <span class="bold"><strong>db_errcall_fcn</strong></span> parameter is the 120 application-specified error reporting function. The function takes 121 three parameters: 122 </p> 123 <div class="itemizedlist"> 124 <ul type="disc"> 125 <li> 126 <p> 127 <code class="literal">dbenv</code> 128 </p> 129 <p> 130 The <span class="bold"><strong>dbenv</strong></span> parameter is the enclosing 131 database environment. 132 </p> 133 </li> 134 <li> 135 <p> 136 <code class="literal">errpfx</code> 137 </p> 138 <p> 139 The <span class="bold"><strong>errpfx</strong></span> parameter is the prefix 140 string (as previously set by 141 <a class="xref" href="dbset_errpfx.html" title="Db::set_errpfx()">Db::set_errpfx()</a> or 142 <a class="xref" href="envset_errpfx.html" title="DbEnv::set_errpfx()">DbEnv::set_errpfx()</a>). 143 </p> 144 </li> 145 <li> 146 <p> 147 <code class="literal">msg</code> 148 </p> 149 <p> 150 The <span class="bold"><strong>msg</strong></span> parameter is the error 151 message string. 152 </p> 153 </li> 154 </ul> 155 </div> 156 </div> 157 </div> 158 <div class="sect2" lang="en" xml:lang="en"> 159 <div class="titlepage"> 160 <div> 161 <div> 162 <h3 class="title"><a id="id1671195"></a>Class</h3> 163 </div> 164 </div> 165 </div> 166 <p> 167 <a class="link" href="env.html" title="Chapter 5. The DbEnv Handle">DbEnv</a> 168 </p> 169 </div> 170 <div class="sect2" lang="en" xml:lang="en"> 171 <div class="titlepage"> 172 <div> 173 <div> 174 <h3 class="title"><a id="id1670298"></a>See Also</h3> 175 </div> 176 </div> 177 </div> 178 <p> 179 <a class="xref" href="env.html#envlist" title="Database Environments and Related Methods">Database Environments and Related Methods</a> 180 </p> 181 </div> 182 </div> 183 <div class="navfooter"> 184 <hr /> 185 <table width="100%" summary="Navigation footer"> 186 <tr> 187 <td width="40%" align="left"><a accesskey="p" href="envevent_notify.html">Prev</a> </td> 188 <td width="20%" align="center"> 189 <a accesskey="u" href="env.html">Up</a> 190 </td> 191 <td width="40%" align="right"> <a accesskey="n" href="envset_errfile.html">Next</a></td> 192 </tr> 193 <tr> 194 <td width="40%" align="left" valign="top">DbEnv::set_event_notify() </td> 195 <td width="20%" align="center"> 196 <a accesskey="h" href="index.html">Home</a> 197 </td> 198 <td width="40%" align="right" valign="top"> DbEnv::set_errfile()</td> 199 </tr> 200 </table> 201 </div> 202 </body> 203</html> 204