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>Tcl error handling</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="Berkeley DB Programmer's Reference Guide" /> 10 <link rel="up" href="tcl.html" title="Chapter��20.�� Berkeley DB Extensions: Tcl" /> 11 <link rel="prev" href="tcl_program.html" title="Tcl API programming notes" /> 12 <link rel="next" href="tcl_faq.html" title="Tcl FAQ" /> 13 </head> 14 <body> 15 <div class="navheader"> 16 <table width="100%" summary="Navigation header"> 17 <tr> 18 <th colspan="3" align="center">Tcl error handling</th> 19 </tr> 20 <tr> 21 <td width="20%" align="left"><a accesskey="p" href="tcl_program.html">Prev</a>��</td> 22 <th width="60%" align="center">Chapter��20.�� 23 Berkeley DB Extensions: Tcl 24 </th> 25 <td width="20%" align="right">��<a accesskey="n" href="tcl_faq.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="tcl_error"></a>Tcl error handling</h2> 35 </div> 36 </div> 37 </div> 38 <p>The Tcl interfaces to Berkeley DB generally return TCL_OK on success and throw 39a Tcl error on failure, using the appropriate Tcl interfaces to provide 40the user with an informative error message. There are some "expected" 41failures, however, for which no Tcl error will be thrown and for which 42Tcl commands will return TCL_OK. These failures include times when a 43searched-for key is not found, a requested key/data pair was previously 44deleted, or a key/data pair cannot be written because the key already 45exists.</p> 46 <p>These failures can be detected by searching the Berkeley DB error message that 47is returned. For example, use the following to detect that an attempt 48to put a record into the database failed because the key already 49existed:</p> 50 <pre class="programlisting">% berkdb open -create -btree a.db 51db0 52% db0 put dog cat 530 54% set ret [db0 put -nooverwrite dog newcat] 55DB_KEYEXIST: Key/data pair already exists 56% if { [string first DB_KEYEXIST $ret] != -1 } { 57 puts "This was an error; the key existed" 58} 59This was an error; the key existed 60% db0 close 610 62% exit</pre> 63 <p>To simplify parsing, it is recommended that the initial Berkeley DB error name 64be checked; for example, <a href="../api_reference/C/dbcput.html#dbcput_DB_KEYEXIST" class="olink">DB_MULTIPLE</a> in the previous example. 65To ensure that Tcl scripts are not broken by upgrading to new releases 66of Berkeley DB, these values will not change in future releases of Berkeley DB. 67There are currently only three such "expected" error returns:</p> 68 <pre class="programlisting">DB_NOTFOUND: No matching key/data pair found 69DB_KEYEMPTY: Nonexistent key/data pair 70DB_KEYEXIST: Key/data pair already exists</pre> 71 <p>Finally, sometimes Berkeley DB will output additional error information when 72a Berkeley DB error occurs. By default, all Berkeley DB error messages will be 73prefixed with the created command in whose context the error occurred 74(for example, "env0", "db2", and so on). There are several ways to 75capture and access this information.</p> 76 <p>First, if Berkeley DB invokes the error callback function, the additional 77information will be placed in the error result returned from the command 78and in the errorInfo backtrace variable in Tcl.</p> 79 <p>Also, the two calls to open an environment and open a database take an 80option, <span class="bold"><strong>-errfile filename</strong></span>, which sets an output file to which 81these additional error messages should be written.</p> 82 <p>Additionally, the two calls to open an environment and open a database 83take an option, <span class="bold"><strong>-errpfx string</strong></span>, which sets the error prefix to 84the given string. This option may be useful in circumstances where a 85more descriptive prefix is desired or where a constant prefix indicating 86an error is desired.</p> 87 </div> 88 <div class="navfooter"> 89 <hr /> 90 <table width="100%" summary="Navigation footer"> 91 <tr> 92 <td width="40%" align="left"><a accesskey="p" href="tcl_program.html">Prev</a>��</td> 93 <td width="20%" align="center"> 94 <a accesskey="u" href="tcl.html">Up</a> 95 </td> 96 <td width="40%" align="right">��<a accesskey="n" href="tcl_faq.html">Next</a></td> 97 </tr> 98 <tr> 99 <td width="40%" align="left" valign="top">Tcl API programming notes��</td> 100 <td width="20%" align="center"> 101 <a accesskey="h" href="index.html">Home</a> 102 </td> 103 <td width="40%" align="right" valign="top">��Tcl FAQ</td> 104 </tr> 105 </table> 106 </div> 107 </body> 108</html> 109