Berkeley DB Reference Guide: Tcl

Tcl error handling

The Tcl interfaces to Berkeley DB generally return TCL_OK on success and throw a Tcl error on failure, using the appropriate Tcl interfaces to provide the user with an informative error message. There are some "expected" failures, however, for which no Tcl error will be thrown and for which Tcl commands will return TCL_OK. These failures include when a searched-for key is not found, a requested key/data pair was previously deleted, or a key/data pair cannot be written because the key already exists.

These failures can be detected by searching the Berkeley DB error message that is returned. For example, to detect that an attempt to put a record into the database failed because the key already existed:

% berkdb open -create -btree a.db
db0
% db0 put dog cat
0
% set ret [db0 put -nooverwrite dog newcat]
DB_KEYEXIST: Key/data pair already exists
% if { [string first DB_KEYEXIST $ret] != -1 } {
	puts "This was an error; the key existed"
}
This was an error; the key existed
% db0 close
0
% exit

To simplify parsing, it is recommended that the initial Berkeley DB error name be checked, e.g., DB_KEYEXIST in the above example. These values will not change in future releases of Berkeley DB to ensure that Tcl scripts are not broken by upgrading to new releases of Berkeley DB. There are currently only three such "expected" error returns. They are:

DB_NOTFOUND: No matching key/data pair found
DB_KEYEMPTY: Non-existent key/data pair
DB_KEYEXIST: Key/data pair already exists

Finally, in some cases, when a Berkeley DB error occurs Berkeley DB will output additional error information. By default, all Berkeley DB error messages will be prefixed with the created command in whose context the error occurred (e.g., "env0", "db2", etc.). There are several ways to capture and access this information.

First, if Berkeley DB invokes the error callback function, the additional information will be placed in the error result returned from the command and in the errorInfo backtrace variable in Tcl.

Also the two calls to open an environment and open a database take an option, -errfile filename, which sets an output file to which these additional error messages should be written.

Additionally the two calls to open an environment and open a database take an option, -errpfx string, which sets the error prefix to the given string. This option may be useful in circumstances where a more descriptive prefix is desired or where a constant prefix indicating an error is desired.

Copyright Sleepycat Software