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