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