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>DB->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="db.html" title="Chapter��2.�� The DB Handle" /> 11 <link rel="prev" href="dbset_encrypt.html" title="DB->set_encrypt()" /> 12 <link rel="next" href="dbset_errfile.html" title="DB->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">DB->set_errcall()</th> 19 </tr> 20 <tr> 21 <td width="20%" align="left"><a accesskey="p" href="dbset_encrypt.html">Prev</a>��</td> 22 <th width="60%" align="center">Chapter��2.�� 23 The DB Handle 24 </th> 25 <td width="20%" align="right">��<a accesskey="n" href="dbset_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="dbset_errcall"></a>DB->set_errcall()</h2> 35 </div> 36 </div> 37 </div> 38 <pre class="programlisting">#include <db.h> 39 40void 41DB->set_errcall(DB *, void (*db_errcall_fcn) 42 (const DB_ENV *dbenv, const char *errpfx, const char *msg)); </pre> 43 <p> 44 When an error occurs in the Berkeley DB library, 45 <span> 46 a Berkeley DB error 47 </span> 48 49 or an error return value is returned by the interface. In some cases, 50 however, the <span class="bold"><strong>errno</strong></span> value may be 51 insufficient to completely describe the cause of the error, especially 52 during initial application debugging. 53 </p> 54 <p> 55 The <a class="xref" href="envset_errcall.html" title="DB_ENV->set_errcall()">DB_ENV->set_errcall()</a> and 56 <code class="methodname">DB->set_errcall()</code> methods are used to enhance the mechanism for 57 reporting error messages to the application. In some cases, when an 58 error occurs, Berkeley DB will call <span class="bold"><strong>db_errcall_fcn()</strong></span> 59 with additional error information. It is up to the 60 <span class="bold"><strong>db_errcall_fcn()</strong></span> function to display the error 61 message in an appropriate manner. 62 </p> 63 <p> 64 Setting <span class="bold"><strong>db_errcall_fcn</strong></span> to NULL 65 unconfigures the callback interface. 66 </p> 67 <p> 68 Alternatively, you can use the 69 70 71 <a class="xref" href="dbset_errfile.html" title="DB->set_errfile()">DB->set_errfile()</a> or 72 <a class="xref" href="envset_errfile.html" title="DB_ENV->set_errfile()">DB->set_errfile()</a> 73 methods to display the additional information via a C library <code class="literal">FILE *</code>. 74 75 </p> 76 <p> 77 This error-logging enhancement does not slow performance or 78 significantly increase application size, and may be run during normal 79 operation as well as during application debugging. 80 </p> 81 <p> 82 For <a class="link" href="db.html" title="Chapter��2.�� The DB Handle">DB</a> handles opened 83 inside of Berkeley DB environments, calling the 84 <code class="methodname">DB->set_errcall()</code> 85 method affects the entire environment and is equivalent to calling the 86 <a class="xref" href="envset_errcall.html" title="DB_ENV->set_errcall()">DB_ENV->set_errcall()</a> 87 method. 88 </p> 89 <p> 90 When used on a database that was <span class="emphasis"><em>not</em></span> opened in 91 an environment, the <code class="methodname">DB->set_errcall()</code> 92 method configures operations performed using the specified 93 <a class="link" href="db.html" title="Chapter��2.�� The DB Handle">DB</a> handle, not all operations 94 performed on the underlying database. 95 </p> 96 <p> 97 The <code class="methodname">DB->set_errcall()</code> method may be called at any time during the 98 life of the application. 99 </p> 100 <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"> 101 <h3 class="title">Note</h3> 102 <p> 103 Berkeley DB is not re-entrant. Callback functions should not attempt to make library 104 calls (for example, to release locks or close open handles). Re-entering Berkeley DB is 105 not guaranteed to work correctly, and the results are undefined. 106 </p> 107 </div> 108 <div class="sect2" lang="en" xml:lang="en"> 109 <div class="titlepage"> 110 <div> 111 <div> 112 <h3 class="title"><a id="id1645477"></a>Parameters</h3> 113 </div> 114 </div> 115 </div> 116 <div class="sect3" lang="en" xml:lang="en"> 117 <div class="titlepage"> 118 <div> 119 <div> 120 <h4 class="title"><a id="id1645495"></a>db_errcall_fcn</h4> 121 </div> 122 </div> 123 </div> 124 <p> 125 The <span class="bold"><strong>db_errcall_fcn</strong></span> parameter is the 126 application-specified error reporting function. The function takes 127 three parameters: 128 </p> 129 <div class="itemizedlist"> 130 <ul type="disc"> 131 <li> 132 <p> 133 <code class="literal">dbenv</code> 134 </p> 135 <p> 136 The <span class="bold"><strong>dbenv</strong></span> parameter is the enclosing 137 database environment. 138 </p> 139 </li> 140 <li> 141 <p> 142 <code class="literal">errpfx</code> 143 </p> 144 <p> 145 The <span class="bold"><strong>errpfx</strong></span> parameter is the prefix 146 string (as previously set by 147 <a class="xref" href="dbset_errpfx.html" title="DB->set_errpfx()">DB->set_errpfx()</a> or 148 <a class="xref" href="envset_errpfx.html" title="DB_ENV->set_errpfx()">DB_ENV->set_errpfx()</a> ). 149 </p> 150 </li> 151 <li> 152 <p> 153 <code class="literal">msg</code> 154 </p> 155 <p> 156 The <span class="bold"><strong>msg</strong></span> parameter is the error 157 message string. 158 </p> 159 </li> 160 </ul> 161 </div> 162 </div> 163 </div> 164 <div class="sect2" lang="en" xml:lang="en"> 165 <div class="titlepage"> 166 <div> 167 <div> 168 <h3 class="title"><a id="id1645638"></a>Class</h3> 169 </div> 170 </div> 171 </div> 172 <p> 173 <a class="link" href="db.html" title="Chapter��2.�� The DB Handle">DB</a> 174 </p> 175 </div> 176 <div class="sect2" lang="en" xml:lang="en"> 177 <div class="titlepage"> 178 <div> 179 <div> 180 <h3 class="title"><a id="id1645692"></a>See Also</h3> 181 </div> 182 </div> 183 </div> 184 <p> 185 <a class="xref" href="db.html#dblist" title="Database and Related Methods">Database and Related Methods</a> 186 </p> 187 </div> 188 </div> 189 <div class="navfooter"> 190 <hr /> 191 <table width="100%" summary="Navigation footer"> 192 <tr> 193 <td width="40%" align="left"><a accesskey="p" href="dbset_encrypt.html">Prev</a>��</td> 194 <td width="20%" align="center"> 195 <a accesskey="u" href="db.html">Up</a> 196 </td> 197 <td width="40%" align="right">��<a accesskey="n" href="dbset_errfile.html">Next</a></td> 198 </tr> 199 <tr> 200 <td width="40%" align="left" valign="top">DB->set_encrypt()��</td> 201 <td width="20%" align="center"> 202 <a accesskey="h" href="index.html">Home</a> 203 </td> 204 <td width="40%" align="right" valign="top">��DB->set_errfile()</td> 205 </tr> 206 </table> 207 </div> 208 </body> 209</html> 210