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>Error Reporting Functions</title> 7 <link rel="stylesheet" href="gettingStarted.css" type="text/css" /> 8 <meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /> 9 <link rel="start" href="index.html" title="Getting Started with Berkeley DB" /> 10 <link rel="up" href="DB.html" title="Chapter��2.��Databases" /> 11 <link rel="prev" href="CoreDBAdmin.html" title="Administrative Methods" /> 12 <link rel="next" href="CoreEnvUsage.html" title="Managing Databases in Environments" /> 13 </head> 14 <body> 15 <div class="navheader"> 16 <table width="100%" summary="Navigation header"> 17 <tr> 18 <th colspan="3" align="center">Error Reporting Functions</th> 19 </tr> 20 <tr> 21 <td width="20%" align="left"><a accesskey="p" href="CoreDBAdmin.html">Prev</a>��</td> 22 <th width="60%" align="center">Chapter��2.��Databases</th> 23 <td width="20%" align="right">��<a accesskey="n" href="CoreEnvUsage.html">Next</a></td> 24 </tr> 25 </table> 26 <hr /> 27 </div> 28 <div class="sect1" lang="en" xml:lang="en"> 29 <div class="titlepage"> 30 <div> 31 <div> 32 <h2 class="title" style="clear: both"><a id="dbErrorReporting"></a>Error Reporting Functions</h2> 33 </div> 34 </div> 35 </div> 36 <p> 37 To simplify error reporting and handling, the 38 39 <span><code class="classname">Db</code> class</span> 40 41 offers several useful methods. 42 43 44 45 46 </p> 47 <div class="itemizedlist"> 48 <ul type="disc"> 49 <li> 50 <p> 51 <code class="methodname">set_error_stream()</code> 52 53 </p> 54 <p> 55 Sets the 56 <span>C++ <code class="classname">ostream</code></span> 57 58 to be used for displaying error messages issued by the DB library. 59 </p> 60 </li> 61 <li> 62 <p> 63 <code class="methodname">set_errcall()</code> 64 65 </p> 66 <p> 67 Defines the function that is called when an error message is 68 issued by DB. The error prefix and message are passed to 69 this callback. It is up to the application to display this 70 information correctly. 71 </p> 72 </li> 73 <li> 74 <p> 75 <code class="methodname">set_errfile()</code> 76 </p> 77 <p> 78 Sets the C library <code class="literal">FILE *</code> to be used for 79 displaying error messages issued by the DB library. 80 </p> 81 </li> 82 <li> 83 <p> 84 <code class="methodname">set_errpfx()</code> 85 86 </p> 87 <p> 88 Sets the prefix used for any error messages issued by the 89 DB library. 90 </p> 91 </li> 92 <li> 93 <p> 94 <code class="methodname">err()</code> 95 </p> 96 <p> 97 Issues an error message. The error message is sent to the 98 callback function as defined by <code class="methodname">set_errcall</code>. 99 If that method has not been used, then the error message is sent to the 100 file defined by 101 102 <span> 103 <code class="methodname">set_errfile()</code> or <code class="methodname">set_error_stream()</code>. 104 </span> 105 If none of these methods have been used, then the error message is sent to 106 standard error. 107 </p> 108 <p> 109 The error message consists of the prefix string 110 (as defined by <code class="methodname">set_errpfx()</code>), 111 an optional <code class="literal">printf</code>-style formatted message, 112 the error message, and a trailing newline. 113 </p> 114 </li> 115 <li> 116 <p> 117 <code class="methodname">errx()</code> 118 </p> 119 <p> 120 Behaves identically to <code class="methodname">err()</code> except 121 that the DB message text associated with the supplied error 122 value is not appended to the error string. 123 </p> 124 </li> 125 </ul> 126 </div> 127 <p> 128 In addition, you can use the <code class="methodname">db_strerror()</code> 129 function to directly return the error string that corresponds to a 130 particular error number. 131 </p> 132 <p> 133 For example, to send all error messages for a given database handle 134 to a callback for handling, first create your callback. Do something like this: 135 </p> 136 <a id="c_db8"></a> 137 <pre class="programlisting">/* 138 * Function called to handle any database error messages 139 * issued by DB. 140 */ 141void 142my_error_handler(const char *error_prefix, char *msg) 143{ 144 /* 145 * Put your code to handle the error prefix and error 146 * message here. Note that one or both of these parameters 147 * may be NULL depending on how the error message is issued 148 * and how the DB handle is configured. 149 */ 150} </pre> 151 <p> 152 And then register the callback as follows: 153 </p> 154 <a id="cxx_db9"></a> 155 <pre class="programlisting">#include <db_cxx.h> 156... 157 158Db db(NULL, 0); 159std::string dbFileName("my_db.db"); 160 161try 162{ 163 // Set up error handling for this database 164 db.set_errcall(my_error_handler); 165 db.set_errpfx("my_example_program"); </pre> 166 <p> 167 And to issue an error message: 168 </p> 169 <a id="cxx_db10"></a> 170 <pre class="programlisting"> // Open the database 171 db.open(NULL, dbFileName.c_str(), NULL, DB_BTREE, DB_CREATE, 0); 172} 173 // Must catch both DbException and std::exception 174 catch(DbException &e) 175 { 176 db.err(e.get_errno(), "Database open failed %s", 177 dbFileName.c_str()); 178 throw e; 179 } 180 catch(std::exception &e) 181 { 182 // No DB error number available, so use errx 183 db.errx("Error opening database: %s", e.what()); 184 throw e; 185 } </pre> 186 <span> 187 188 </span> 189 </div> 190 <div class="navfooter"> 191 <hr /> 192 <table width="100%" summary="Navigation footer"> 193 <tr> 194 <td width="40%" align="left"><a accesskey="p" href="CoreDBAdmin.html">Prev</a>��</td> 195 <td width="20%" align="center"> 196 <a accesskey="u" href="DB.html">Up</a> 197 </td> 198 <td width="40%" align="right">��<a accesskey="n" href="CoreEnvUsage.html">Next</a></td> 199 </tr> 200 <tr> 201 <td width="40%" align="left" valign="top">Administrative Methods��</td> 202 <td width="20%" align="center"> 203 <a accesskey="h" href="index.html">Home</a> 204 </td> 205 <td width="40%" align="right" valign="top">��Managing Databases in Environments</td> 206 </tr> 207 </table> 208 </div> 209 </body> 210</html> 211