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 <span><code class="classname">DB</code> structure</span> 39 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_errcall()</code> 52 53 </p> 54 <p> 55 Defines the function that is called when an error message is 56 issued by DB. The error prefix and message are passed to 57 this callback. It is up to the application to display this 58 information correctly. 59 </p> 60 </li> 61 <li> 62 <p> 63 <code class="methodname">set_errfile()</code> 64 </p> 65 <p> 66 Sets the C library <code class="literal">FILE *</code> to be used for 67 displaying error messages issued by the DB library. 68 </p> 69 </li> 70 <li> 71 <p> 72 <code class="methodname">set_errpfx()</code> 73 74 </p> 75 <p> 76 Sets the prefix used for any error messages issued by the 77 DB library. 78 </p> 79 </li> 80 <li> 81 <p> 82 <code class="methodname">err()</code> 83 </p> 84 <p> 85 Issues an error message. The error message is sent to the 86 callback function as defined by <code class="methodname">set_errcall</code>. 87 If that method has not been used, then the error message is sent to the 88 file defined by 89 <span><code class="methodname">set_errfile()</code>.</span> 90 91 If none of these methods have been used, then the error message is sent to 92 standard error. 93 </p> 94 <p> 95 The error message consists of the prefix string 96 (as defined by <code class="methodname">set_errpfx()</code>), 97 an optional <code class="literal">printf</code>-style formatted message, 98 the error message, and a trailing newline. 99 </p> 100 </li> 101 <li> 102 <p> 103 <code class="methodname">errx()</code> 104 </p> 105 <p> 106 Behaves identically to <code class="methodname">err()</code> except 107 that the DB message text associated with the supplied error 108 value is not appended to the error string. 109 </p> 110 </li> 111 </ul> 112 </div> 113 <p> 114 In addition, you can use the <code class="methodname">db_strerror()</code> 115 function to directly return the error string that corresponds to a 116 particular error number. 117 </p> 118 <p> 119 For example, to send all error messages for a given database handle 120 to a callback for handling, first create your callback. Do something like this: 121 </p> 122 <a id="c_db8"></a> 123 <pre class="programlisting">/* 124 * Function called to handle any database error messages 125 * issued by DB. 126 */ 127void 128my_error_handler(const char *error_prefix, char *msg) 129{ 130 /* 131 * Put your code to handle the error prefix and error 132 * message here. Note that one or both of these parameters 133 * may be NULL depending on how the error message is issued 134 * and how the DB handle is configured. 135 */ 136} </pre> 137 <p> 138 And then register the callback as follows: 139 </p> 140 <a id="c_db9"></a> 141 <pre class="programlisting">#include <db.h> 142#include <stdio.h> 143 144... 145 146DB *dbp; 147int ret; 148 149/* 150 * Create a database and initialize it for error 151 * reporting. 152 */ 153ret = db_create(&dbp, NULL, 0); 154if (ret != 0) { 155 fprintf(stderr, "%s: %s\n", "my_program", 156 db_strerror(ret)); 157 return(ret); 158} 159 160/* Set up error handling for this database */ 161dbp->set_errcall(dbp, my_error_handler); 162dbp->set_errpfx(dbp, "my_example_program"); </pre> 163 <p> 164 And to issue an error message: 165 </p> 166 <a id="c_db10"></a> 167 <pre class="programlisting">ret = dbp->open(dbp, 168 NULL, 169 "mydb.db", 170 NULL, 171 DB_BTREE, 172 DB_CREATE, 173 0); 174if (ret != 0) { 175 dbp->err(dbp, ret, 176 "Database open failed: %s", "mydb.db"); 177 return(ret); 178}</pre> 179 <span> 180 181 </span> 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="CoreDBAdmin.html">Prev</a> </td> 188 <td width="20%" align="center"> 189 <a accesskey="u" href="DB.html">Up</a> 190 </td> 191 <td width="40%" align="right"> <a accesskey="n" href="CoreEnvUsage.html">Next</a></td> 192 </tr> 193 <tr> 194 <td width="40%" align="left" valign="top">Administrative Methods </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"> Managing Databases in Environments</td> 199 </tr> 200 </table> 201 </div> 202 </body> 203</html> 204