From 780b92ada9afcf1d58085a83a0b9e6bc982203d1 Mon Sep 17 00:00:00 2001 From: Lorry Tar Creator Date: Tue, 17 Feb 2015 17:25:57 +0000 Subject: Imported from /home/lorry/working-area/delta_berkeleydb/db-6.1.23.tar.gz. --- docs/programmer_reference/tcl_error.html | 93 +++++++++++++++++++------------- 1 file changed, 56 insertions(+), 37 deletions(-) (limited to 'docs/programmer_reference/tcl_error.html') diff --git a/docs/programmer_reference/tcl_error.html b/docs/programmer_reference/tcl_error.html index 4b328a96..dd1ce597 100644 --- a/docs/programmer_reference/tcl_error.html +++ b/docs/programmer_reference/tcl_error.html @@ -14,7 +14,7 @@
-

Library Version 11.2.5.3

+

Library Version 12.1.6.1

@@ -22,9 +22,7 @@ - +
Prev Chapter 21.  - Berkeley DB Extensions: Tcl - Chapter 21.  Berkeley DB Extensions: Tcl  Next
@@ -38,18 +36,23 @@
-

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 times 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, use the following to detect that an attempt -to put a record into the database failed because the key already -existed:

+

+ 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 times + 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, use the following + 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
@@ -63,30 +66,46 @@ 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; for example, DB_MULTIPLE in the previous example. -To ensure that Tcl scripts are not broken by upgrading to new releases -of Berkeley DB, these values will not change in future releases of Berkeley DB. -There are currently only three such "expected" error returns:

+

+ To simplify parsing, it is recommended that the initial + Berkeley DB error name be checked; for example, DB_MULTIPLE + in the previous example. To ensure that Tcl scripts are not + broken by upgrading to new releases of Berkeley DB, these + values will not change in future releases of Berkeley DB. + There are currently only three such "expected" error + returns: + 

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

Finally, sometimes Berkeley DB will output additional error information when -a Berkeley DB error occurs. By default, all Berkeley DB error messages will be -prefixed with the created command in whose context the error occurred -(for example, "env0", "db2", and so on). 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.

+

+ Finally, sometimes Berkeley DB will output additional error + information when a Berkeley DB error occurs. By default, all + Berkeley DB error messages will be prefixed with the created + command in whose context the error occurred (for example, + "env0", "db2", and so on). 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. +

-- cgit v1.2.1