1<!--$Id: error.so,v 11.17 2001/06/19 19:45:47 bostic Exp $--> 2<!--Copyright (c) 1997,2008 Oracle. All rights reserved.--> 3<!--See the file LICENSE for redistribution information.--> 4<html> 5<head> 6<title>Berkeley DB Reference Guide: Tcl error handling</title> 7<meta name="description" content="Berkeley DB: An embedded database programmatic toolkit."> 8<meta name="keywords" content="embedded,database,programmatic,toolkit,btree,hash,hashing,transaction,transactions,locking,logging,access method,access methods,Java,C,C++"> 9</head> 10<body bgcolor=white> 11<table width="100%"><tr valign=top> 12<td><b><dl><dt>Berkeley DB Reference Guide:<dd>Tcl API</dl></b></td> 13<td align=right><a href="../tcl/program.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../toc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../tcl/faq.html"><img src="../../images/next.gif" alt="Next"></a> 14</td></tr></table> 15<p align=center><b>Tcl error handling</b></p> 16<p>The Tcl interfaces to Berkeley DB generally return TCL_OK on success and throw 17a Tcl error on failure, using the appropriate Tcl interfaces to provide 18the user with an informative error message. There are some "expected" 19failures, however, for which no Tcl error will be thrown and for which 20Tcl commands will return TCL_OK. These failures include times when a 21searched-for key is not found, a requested key/data pair was previously 22deleted, or a key/data pair cannot be written because the key already 23exists.</p> 24<p>These failures can be detected by searching the Berkeley DB error message that 25is returned. For example, use the following to detect that an attempt 26to put a record into the database failed because the key already 27existed:</p> 28<blockquote><pre>% berkdb open -create -btree a.db 29db0 30% db0 put dog cat 310 32% set ret [db0 put -nooverwrite dog newcat] 33DB_KEYEXIST: Key/data pair already exists 34% if { [string first DB_KEYEXIST $ret] != -1 } { 35 puts "This was an error; the key existed" 36} 37This was an error; the key existed 38% db0 close 390 40% exit</pre></blockquote> 41<p>To simplify parsing, it is recommended that the initial Berkeley DB error name 42be checked; for example, <a href="../../api_c/dbc_put.html#DB_KEYEXIST">DB_KEYEXIST</a> in the previous example. 43To ensure that Tcl scripts are not broken by upgrading to new releases 44of Berkeley DB, these values will not change in future releases of Berkeley DB. 45There are currently only three such "expected" error returns:</p> 46<blockquote><pre>DB_NOTFOUND: No matching key/data pair found 47DB_KEYEMPTY: Nonexistent key/data pair 48DB_KEYEXIST: Key/data pair already exists</pre></blockquote> 49<p>Finally, sometimes Berkeley DB will output additional error information when 50a Berkeley DB error occurs. By default, all Berkeley DB error messages will be 51prefixed with the created command in whose context the error occurred 52(for example, "env0", "db2", and so on). There are several ways to 53capture and access this information.</p> 54<p>First, if Berkeley DB invokes the error callback function, the additional 55information will be placed in the error result returned from the command 56and in the errorInfo backtrace variable in Tcl.</p> 57<p>Also, the two calls to open an environment and open a database take an 58option, <b>-errfile filename</b>, which sets an output file to which 59these additional error messages should be written.</p> 60<p>Additionally, the two calls to open an environment and open a database 61take an option, <b>-errpfx string</b>, which sets the error prefix to 62the given string. This option may be useful in circumstances where a 63more descriptive prefix is desired or where a constant prefix indicating 64an error is desired.</p> 65<table width="100%"><tr><td><br></td><td align=right><a href="../tcl/program.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../toc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../tcl/faq.html"><img src="../../images/next.gif" alt="Next"></a> 66</td></tr></table> 67<p><font size=1>Copyright (c) 1996,2008 Oracle. All rights reserved.</font> 68</body> 69</html> 70