diff options
| author | jbj <devnull@localhost> | 2001-03-21 18:33:35 +0000 |
|---|---|---|
| committer | jbj <devnull@localhost> | 2001-03-21 18:33:35 +0000 |
| commit | 731946f4b90eb1173452dd30f1296dd825155d82 (patch) | |
| tree | 67535f54ecb7e5463c06e62044e4efd84ae0291d /db/docs/ref/am | |
| parent | 7ed904da030dc4640ff9bce8458ba07cc09d830d (diff) | |
| download | librpm-tizen-731946f4b90eb1173452dd30f1296dd825155d82.tar.gz librpm-tizen-731946f4b90eb1173452dd30f1296dd825155d82.tar.bz2 librpm-tizen-731946f4b90eb1173452dd30f1296dd825155d82.zip | |
Initial revision
CVS patchset: 4644
CVS date: 2001/03/21 18:33:35
Diffstat (limited to 'db/docs/ref/am')
| -rw-r--r-- | db/docs/ref/am/close.html | 43 | ||||
| -rw-r--r-- | db/docs/ref/am/count.html | 28 | ||||
| -rw-r--r-- | db/docs/ref/am/curclose.html | 28 | ||||
| -rw-r--r-- | db/docs/ref/am/curdel.html | 26 | ||||
| -rw-r--r-- | db/docs/ref/am/curdup.html | 34 | ||||
| -rw-r--r-- | db/docs/ref/am/curget.html | 74 | ||||
| -rw-r--r-- | db/docs/ref/am/curput.html | 40 | ||||
| -rw-r--r-- | db/docs/ref/am/cursor.html | 41 | ||||
| -rw-r--r-- | db/docs/ref/am/delete.html | 28 | ||||
| -rw-r--r-- | db/docs/ref/am/error.html | 61 | ||||
| -rw-r--r-- | db/docs/ref/am/get.html | 39 | ||||
| -rw-r--r-- | db/docs/ref/am/join.html | 184 | ||||
| -rw-r--r-- | db/docs/ref/am/open.html | 47 | ||||
| -rw-r--r-- | db/docs/ref/am/opensub.html | 64 | ||||
| -rw-r--r-- | db/docs/ref/am/ops.html | 36 | ||||
| -rw-r--r-- | db/docs/ref/am/partial.html | 134 | ||||
| -rw-r--r-- | db/docs/ref/am/put.html | 36 | ||||
| -rw-r--r-- | db/docs/ref/am/stability.html | 49 | ||||
| -rw-r--r-- | db/docs/ref/am/stat.html | 36 | ||||
| -rw-r--r-- | db/docs/ref/am/sync.html | 38 | ||||
| -rw-r--r-- | db/docs/ref/am/upgrade.html | 50 | ||||
| -rw-r--r-- | db/docs/ref/am/verify.html | 50 |
22 files changed, 1166 insertions, 0 deletions
diff --git a/db/docs/ref/am/close.html b/db/docs/ref/am/close.html new file mode 100644 index 000000000..04b8beacb --- /dev/null +++ b/db/docs/ref/am/close.html @@ -0,0 +1,43 @@ +<!--$Id: close.so,v 10.15 2000/12/18 21:05:13 bostic Exp $--> +<!--Copyright 1997, 1998, 1999, 2000 by Sleepycat Software, Inc.--> +<!--All rights reserved.--> +<html> +<head> +<title>Berkeley DB Reference Guide: Closing a database</title> +<meta name="description" content="Berkeley DB: An embedded database programmatic toolkit."> +<meta name="keywords" content="embedded,database,programmatic,toolkit,b+tree,btree,hash,hashing,transaction,transactions,locking,logging,access method,access methods,java,C,C++"> +</head> +<body bgcolor=white> + <a name="2"><!--meow--></a> +<table><tr valign=top> +<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Access Methods</dl></h3></td> +<td width="1%"><a href="../../ref/am/stat.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../ref/toc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/am/cursor.html"><img src="../../images/next.gif" alt="Next"></a> +</td></tr></table> +<p> +<h1 align=center>Closing a database</h1> +<p>The <a href="../../api_c/db_close.html">DB->close</a> function is the standard interface for closing the database. +By default, <a href="../../api_c/db_close.html">DB->close</a> also flushes all modified records from the +database cache to disk. +<p>There is one flag that you can set to customize <a href="../../api_c/db_close.html">DB->close</a>: +<p><dl compact> +<p><dt><a href="../../api_c/db_close.html#DB_NOSYNC">DB_NOSYNC</a><dd>Do not flush cached information to disk. +</dl> +<b>It is important to understand that flushing cached information +to disk only minimizes the window of opportunity for corrupted data, it +does not eliminate the possibility.</b> +<p>While unlikely, it is possible for database corruption to happen if a +system or application crash occurs while writing data to the database. To +ensure that database corruption never occurs, applications must either: +<ul type=disc> +<li>Use transactions and logging with automatic recovery. +<li>Use logging and application-specific recovery. +<li>Edit a copy of the database, and, once all applications +using the database have successfully called <a href="../../api_c/db_close.html">DB->close</a>, use +system operations (e.g., the POSIX rename system call) to atomically +replace the original database with the updated copy. +</ul> +<table><tr><td><br></td><td width="1%"><a href="../../ref/am/stat.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../ref/toc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/am/cursor.html"><img src="../../images/next.gif" alt="Next"></a> +</td></tr></table> +<p><font size=1><a href="http://www.sleepycat.com">Copyright Sleepycat Software</a></font> +</body> +</html> diff --git a/db/docs/ref/am/count.html b/db/docs/ref/am/count.html new file mode 100644 index 000000000..92282641b --- /dev/null +++ b/db/docs/ref/am/count.html @@ -0,0 +1,28 @@ +<!--$Id: count.so,v 1.3 2000/12/18 21:05:13 bostic Exp $--> +<!--Copyright 1997, 1998, 1999, 2000 by Sleepycat Software, Inc.--> +<!--All rights reserved.--> +<html> +<head> +<title>Berkeley DB Reference Guide: Data item count</title> +<meta name="description" content="Berkeley DB: An embedded database programmatic toolkit."> +<meta name="keywords" content="embedded,database,programmatic,toolkit,b+tree,btree,hash,hashing,transaction,transactions,locking,logging,access method,access methods,java,C,C++"> +</head> +<body bgcolor=white> + <a name="2"><!--meow--></a> +<table><tr valign=top> +<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Access Methods</dl></h3></td> +<td width="1%"><a href="../../ref/am/join.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../ref/toc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/am/curclose.html"><img src="../../images/next.gif" alt="Next"></a> +</td></tr></table> +<p> +<h1 align=center>Data item count</h1> +<p>Once a cursor has been initialized to reference a particular key in the +database, it can be used to determine the number of data items that are +stored for any particular key. The <a href="../../api_c/dbc_count.html">DBcursor->c_count</a> method returns +this number of data items. The returned value is always one, unless +the database supports duplicate data items, in which case it may be any +number of items. +<table><tr><td><br></td><td width="1%"><a href="../../ref/am/join.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../ref/toc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/am/curclose.html"><img src="../../images/next.gif" alt="Next"></a> +</td></tr></table> +<p><font size=1><a href="http://www.sleepycat.com">Copyright Sleepycat Software</a></font> +</body> +</html> diff --git a/db/docs/ref/am/curclose.html b/db/docs/ref/am/curclose.html new file mode 100644 index 000000000..52ccfeb8c --- /dev/null +++ b/db/docs/ref/am/curclose.html @@ -0,0 +1,28 @@ +<!--$Id: curclose.so,v 10.12 2000/12/13 16:48:13 bostic Exp $--> +<!--Copyright 1997, 1998, 1999, 2000 by Sleepycat Software, Inc.--> +<!--All rights reserved.--> +<html> +<head> +<title>Berkeley DB Reference Guide: Closing a cursor</title> +<meta name="description" content="Berkeley DB: An embedded database programmatic toolkit."> +<meta name="keywords" content="embedded,database,programmatic,toolkit,b+tree,btree,hash,hashing,transaction,transactions,locking,logging,access method,access methods,java,C,C++"> +</head> +<body bgcolor=white> + <a name="2"><!--meow--></a> <a name="3"><!--meow--></a> +<table><tr valign=top> +<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Access Methods</dl></h3></td> +<td width="1%"><a href="../../ref/am/count.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../ref/toc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/am/stability.html"><img src="../../images/next.gif" alt="Next"></a> +</td></tr></table> +<p> +<h1 align=center>Closing a cursor</h1> +<p>The <a href="../../api_c/dbc_close.html">DBcursor->c_close</a> function is the standard interface for closing a cursor, +after which the cursor may no longer be used. Although cursors are +implicitly closed when the database they point to are closed, it is good +programming practice to explicitly close cursors. In addition, in +transactional systems, cursors may not exist outside of a transaction and +so must be explicitly closed. +<table><tr><td><br></td><td width="1%"><a href="../../ref/am/count.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../ref/toc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/am/stability.html"><img src="../../images/next.gif" alt="Next"></a> +</td></tr></table> +<p><font size=1><a href="http://www.sleepycat.com">Copyright Sleepycat Software</a></font> +</body> +</html> diff --git a/db/docs/ref/am/curdel.html b/db/docs/ref/am/curdel.html new file mode 100644 index 000000000..b0fe8f957 --- /dev/null +++ b/db/docs/ref/am/curdel.html @@ -0,0 +1,26 @@ +<!--$Id: curdel.so,v 10.11 2000/03/18 21:43:07 bostic Exp $--> +<!--Copyright 1997, 1998, 1999, 2000 by Sleepycat Software, Inc.--> +<!--All rights reserved.--> +<html> +<head> +<title>Berkeley DB Reference Guide: Deleting records with a cursor</title> +<meta name="description" content="Berkeley DB: An embedded database programmatic toolkit."> +<meta name="keywords" content="embedded,database,programmatic,toolkit,b+tree,btree,hash,hashing,transaction,transactions,locking,logging,access method,access methods,java,C,C++"> +</head> +<body bgcolor=white> + <a name="2"><!--meow--></a> <a name="3"><!--meow--></a> +<table><tr valign=top> +<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Access Methods</dl></h3></td> +<td width="1%"><a href="../../ref/am/curput.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../ref/toc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/am/curdup.html"><img src="../../images/next.gif" alt="Next"></a> +</td></tr></table> +<p> +<h1 align=center>Deleting records with a cursor</h1> +<p>The <a href="../../api_c/dbc_del.html">DBcursor->c_del</a> function is the standard interface for deleting records from +the database using a cursor. The <a href="../../api_c/dbc_del.html">DBcursor->c_del</a> function deletes the record +currently referenced by the cursor. In all cases, the cursor position is +unchanged after a delete. +<table><tr><td><br></td><td width="1%"><a href="../../ref/am/curput.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../ref/toc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/am/curdup.html"><img src="../../images/next.gif" alt="Next"></a> +</td></tr></table> +<p><font size=1><a href="http://www.sleepycat.com">Copyright Sleepycat Software</a></font> +</body> +</html> diff --git a/db/docs/ref/am/curdup.html b/db/docs/ref/am/curdup.html new file mode 100644 index 000000000..6c609b2e5 --- /dev/null +++ b/db/docs/ref/am/curdup.html @@ -0,0 +1,34 @@ +<!--$Id: curdup.so,v 11.5 2000/12/19 14:45:39 sue Exp $--> +<!--Copyright 1997, 1998, 1999, 2000 by Sleepycat Software, Inc.--> +<!--All rights reserved.--> +<html> +<head> +<title>Berkeley DB Reference Guide: Duplicating a cursor</title> +<meta name="description" content="Berkeley DB: An embedded database programmatic toolkit."> +<meta name="keywords" content="embedded,database,programmatic,toolkit,b+tree,btree,hash,hashing,transaction,transactions,locking,logging,access method,access methods,java,C,C++"> +</head> +<body bgcolor=white> + <a name="2"><!--meow--></a> <a name="3"><!--meow--></a> +<table><tr valign=top> +<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Access Methods</dl></h3></td> +<td width="1%"><a href="../../ref/am/curdel.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../ref/toc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/am/join.html"><img src="../../images/next.gif" alt="Next"></a> +</td></tr></table> +<p> +<h1 align=center>Duplicating a cursor</h1> +<p>Once a cursor has been initialized (e.g., by a call to <a href="../../api_c/dbc_get.html">DBcursor->c_get</a>), +it can be thought of as identifying a particular location in a database. +The <a href="../../api_c/dbc_dup.html">DBcursor->c_dup</a> function permits an application to create a new cursor that +has the same locking and transactional information as the cursor from +which it is copied, and which optionally refers to the same position in +the database. +<p>In order to maintain a cursor position when an application is using +locking, locks are maintained on behalf of the cursor until the cursor is +closed. In cases when an application is using locking without +transactions, cursor duplication is often required to avoid +self-deadlocks. For further details, refer to +<a href="../../ref/lock/am_conv.html">Access method locking conventions</a>. +<table><tr><td><br></td><td width="1%"><a href="../../ref/am/curdel.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../ref/toc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/am/join.html"><img src="../../images/next.gif" alt="Next"></a> +</td></tr></table> +<p><font size=1><a href="http://www.sleepycat.com">Copyright Sleepycat Software</a></font> +</body> +</html> diff --git a/db/docs/ref/am/curget.html b/db/docs/ref/am/curget.html new file mode 100644 index 000000000..129fa272b --- /dev/null +++ b/db/docs/ref/am/curget.html @@ -0,0 +1,74 @@ +<!--$Id: curget.so,v 10.14 2000/12/18 21:05:13 bostic Exp $--> +<!--Copyright 1997, 1998, 1999, 2000 by Sleepycat Software, Inc.--> +<!--All rights reserved.--> +<html> +<head> +<title>Berkeley DB Reference Guide: Retrieving records with a cursor</title> +<meta name="description" content="Berkeley DB: An embedded database programmatic toolkit."> +<meta name="keywords" content="embedded,database,programmatic,toolkit,b+tree,btree,hash,hashing,transaction,transactions,locking,logging,access method,access methods,java,C,C++"> +</head> +<body bgcolor=white> + <a name="2"><!--meow--></a> <a name="3"><!--meow--></a> +<table><tr valign=top> +<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Access Methods</dl></h3></td> +<td width="1%"><a href="../../ref/am/cursor.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../ref/toc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/am/curput.html"><img src="../../images/next.gif" alt="Next"></a> +</td></tr></table> +<p> +<h1 align=center>Retrieving records with a cursor</h1> +<p>The <a href="../../api_c/dbc_get.html">DBcursor->c_get</a> function is the standard interface for retrieving records from +the database with a cursor. The <a href="../../api_c/dbc_get.html">DBcursor->c_get</a> function takes a flag which +controls how the cursor is positioned within the database and returns the +key/data item associated with that positioning. Similar to +<a href="../../api_c/db_get.html">DB->get</a>, <a href="../../api_c/dbc_get.html">DBcursor->c_get</a> may also take a supplied key and retrieve +the data associated with that key from the database. There are several +flags that you can set to customize retrieval. +<h3>Cursor position flags</h3> +<p><dl compact> +<p><dt><a href="../../api_c/dbc_get.html#DB_FIRST">DB_FIRST</a>, <a href="../../api_c/dbc_get.html#DB_LAST">DB_LAST</a><dd>Return the first (last) record in the database. +<p><dt><a href="../../api_c/dbc_get.html#DB_NEXT">DB_NEXT</a>, <a href="../../api_c/dbc_get.html#DB_PREV">DB_PREV</a><dd>Return the next (previous) record in the database. +<p><dt><a href="../../api_c/dbc_get.html#DB_NEXT_DUP">DB_NEXT_DUP</a><dd>Return the next record in the database, if it is a duplicate data item +for the current key. +<p><dt><a href="../../api_c/dbc_get.html#DB_NEXT_NODUP">DB_NEXT_NODUP</a>, <a href="../../api_c/dbc_get.html#DB_PREV_NODUP">DB_PREV_NODUP</a><dd>Return the next (previous) record in the database that is not a +duplicate data item for the current key. +<p><dt><a href="../../api_c/dbc_get.html#DB_CURRENT">DB_CURRENT</a><dd>Return the record from the database currently referenced by the +cursor. +</dl> +<h3>Retrieving specific key/data pairs</h3> +<p><dl compact> +<p><dt><a href="../../api_c/dbc_get.html#DB_SET">DB_SET</a><dd>Return the record from the database that matches the supplied key. In +the case of duplicates the first duplicate is returned and the cursor +is positioned at the beginning of the duplicate list. The user can then +traverse the duplicate entries for the key. +<p><dt><a href="../../api_c/dbc_get.html#DB_SET_RANGE">DB_SET_RANGE</a><dd>Return the smallest record in the database greater than or equal to the +supplied key. This functionality permits partial key matches and range +searches in the Btree access method. +<p><dt><a href="../../api_c/db_get.html#DB_GET_BOTH">DB_GET_BOTH</a><dd>Return the record from the database that matches both the supplied key +and data items. This is particularly useful when there are large +numbers of duplicate records for a key, as it allows the cursor to +easily be positioned at the correct place for traversal of some part of +a large set of duplicate records. +</dl> +<h3>Retrieving based on record numbers</h3> +<p><dl compact> +<p><dt><a href="../../api_c/db_get.html#DB_SET_RECNO">DB_SET_RECNO</a><dd>If the underlying database is a Btree, and was configured so that it is +possible to search it by logical record number, retrieve a specific +record based on a record number argument. +<p><dt><a href="../../api_c/dbc_get.html#DB_GET_RECNO">DB_GET_RECNO</a><dd>If the underlying database is a Btree, and was configured so that it is +possible to search it by logical record number, return the record number +for the record referenced by the cursor. +</dl> +<h3>Special-purpose flags</h3> +<p><dl compact> +<p><dt><a href="../../api_c/db_get.html#DB_CONSUME">DB_CONSUME</a><dd>Read-and-delete: the first record (the head) of the queue is returned and +deleted. The underlying database must be a Queue. +<p><dt><a href="../../api_c/dbc_get.html#DB_RMW">DB_RMW</a><dd>Read-modify-write: acquire write locks instead of read locks during +retrieval. This can enhance performance in threaded applications by +reducing the chance of deadlock. +</dl> +<p>In all cases, the cursor is repositioned by a <a href="../../api_c/dbc_get.html">DBcursor->c_get</a> operation +to point to the newly-returned key/data pair in the database. +<table><tr><td><br></td><td width="1%"><a href="../../ref/am/cursor.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../ref/toc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/am/curput.html"><img src="../../images/next.gif" alt="Next"></a> +</td></tr></table> +<p><font size=1><a href="http://www.sleepycat.com">Copyright Sleepycat Software</a></font> +</body> +</html> diff --git a/db/docs/ref/am/curput.html b/db/docs/ref/am/curput.html new file mode 100644 index 000000000..0d5ef2725 --- /dev/null +++ b/db/docs/ref/am/curput.html @@ -0,0 +1,40 @@ +<!--$Id: curput.so,v 10.12 2000/12/04 18:05:41 bostic Exp $--> +<!--Copyright 1997, 1998, 1999, 2000 by Sleepycat Software, Inc.--> +<!--All rights reserved.--> +<html> +<head> +<title>Berkeley DB Reference Guide: Storing records with a cursor</title> +<meta name="description" content="Berkeley DB: An embedded database programmatic toolkit."> +<meta name="keywords" content="embedded,database,programmatic,toolkit,b+tree,btree,hash,hashing,transaction,transactions,locking,logging,access method,access methods,java,C,C++"> +</head> +<body bgcolor=white> + <a name="2"><!--meow--></a> <a name="3"><!--meow--></a> +<table><tr valign=top> +<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Access Methods</dl></h3></td> +<td width="1%"><a href="../../ref/am/curget.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../ref/toc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/am/curdel.html"><img src="../../images/next.gif" alt="Next"></a> +</td></tr></table> +<p> +<h1 align=center>Storing records with a cursor</h1> +<p>The <a href="../../api_c/dbc_put.html">DBcursor->c_put</a> function is the standard interface for storing records into +the database with a cursor. In general, <a href="../../api_c/dbc_put.html">DBcursor->c_put</a> takes a key and +inserts the associated data into the database, at a location controlled +by a specified flag. +<p>There are several flags that you can set to customize storage: +<p><dl compact> +<p><dt><a href="../../api_c/dbc_put.html#DB_AFTER">DB_AFTER</a><dd>Create a new record, immediately after the record currently referenced by +the cursor. +<p><dt><a href="../../api_c/dbc_put.html#DB_BEFORE">DB_BEFORE</a><dd>Create a new record, immediately before the record currently referenced by +the cursor. +<p><dt><a href="../../api_c/dbc_put.html#DB_CURRENT_PUT">DB_CURRENT</a><dd>Replace the data part of the record currently referenced by the cursor. +<p><dt><a href="../../api_c/dbc_put.html#DB_KEYFIRST">DB_KEYFIRST</a><dd>Create a new record as the first of the duplicate records for the +supplied key. +<p><dt><a href="../../api_c/dbc_put.html#DB_KEYLAST">DB_KEYLAST</a><dd>Create a new record, as the last of the duplicate records for the supplied +key. +</dl> +<p>In all cases, the cursor is repositioned by a <a href="../../api_c/dbc_put.html">DBcursor->c_put</a> operation +to point to the newly inserted key/data pair in the database. +<table><tr><td><br></td><td width="1%"><a href="../../ref/am/curget.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../ref/toc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/am/curdel.html"><img src="../../images/next.gif" alt="Next"></a> +</td></tr></table> +<p><font size=1><a href="http://www.sleepycat.com">Copyright Sleepycat Software</a></font> +</body> +</html> diff --git a/db/docs/ref/am/cursor.html b/db/docs/ref/am/cursor.html new file mode 100644 index 000000000..529285b4a --- /dev/null +++ b/db/docs/ref/am/cursor.html @@ -0,0 +1,41 @@ +<!--$Id: cursor.so,v 10.15 2000/12/18 21:05:13 bostic Exp $--> +<!--Copyright 1997, 1998, 1999, 2000 by Sleepycat Software, Inc.--> +<!--All rights reserved.--> +<html> +<head> +<title>Berkeley DB Reference Guide: Database cursors</title> +<meta name="description" content="Berkeley DB: An embedded database programmatic toolkit."> +<meta name="keywords" content="embedded,database,programmatic,toolkit,b+tree,btree,hash,hashing,transaction,transactions,locking,logging,access method,access methods,java,C,C++"> +</head> +<body bgcolor=white> + <a name="2"><!--meow--></a> +<table><tr valign=top> +<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Access Methods</dl></h3></td> +<td width="1%"><a href="../../ref/am/close.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../ref/toc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/am/curget.html"><img src="../../images/next.gif" alt="Next"></a> +</td></tr></table> +<p> +<h1 align=center>Database cursors</h1> +<p>A database cursor is a reference to a single key/data pair in the +database. It supports traversal of the database and is the only way to +access individual duplicate data items. Cursors are used for operating +on collections of records, for iterating over a database, and for saving +handles to individual records, so that they can be modified after they +have been read. +<p>The <a href="../../api_c/db_cursor.html">DB->cursor</a> function is the standard interface for opening a cursor +into a database. Upon return the cursor is uninitialized, positioning +occurs as part of the first cursor operation. +<p>Once a database cursor has been opened, there are a set of access method +operations that can be performed. Each of these operations is performed +using a method referenced from the returned cursor handle. +<p><dl compact> +<dt><a href="../../api_c/dbc_close.html">DBcursor->c_close</a><dd>Close the cursor +<dt><a href="../../api_c/dbc_del.html">DBcursor->c_del</a><dd>Delete a record +<dt><a href="../../api_c/dbc_dup.html">DBcursor->c_dup</a><dd>Duplicate a cursor +<dt><a href="../../api_c/dbc_get.html">DBcursor->c_get</a><dd>Retrieve a record +<dt><a href="../../api_c/dbc_put.html">DBcursor->c_put</a><dd>Store a record +</dl> +<table><tr><td><br></td><td width="1%"><a href="../../ref/am/close.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../ref/toc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/am/curget.html"><img src="../../images/next.gif" alt="Next"></a> +</td></tr></table> +<p><font size=1><a href="http://www.sleepycat.com">Copyright Sleepycat Software</a></font> +</body> +</html> diff --git a/db/docs/ref/am/delete.html b/db/docs/ref/am/delete.html new file mode 100644 index 000000000..8ab612fa4 --- /dev/null +++ b/db/docs/ref/am/delete.html @@ -0,0 +1,28 @@ +<!--$Id: delete.so,v 10.14 2000/03/18 21:43:08 bostic Exp $--> +<!--Copyright 1997, 1998, 1999, 2000 by Sleepycat Software, Inc.--> +<!--All rights reserved.--> +<html> +<head> +<title>Berkeley DB Reference Guide: Deleting records</title> +<meta name="description" content="Berkeley DB: An embedded database programmatic toolkit."> +<meta name="keywords" content="embedded,database,programmatic,toolkit,b+tree,btree,hash,hashing,transaction,transactions,locking,logging,access method,access methods,java,C,C++"> +</head> +<body bgcolor=white> + <a name="2"><!--meow--></a> +<table><tr valign=top> +<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Access Methods</dl></h3></td> +<td width="1%"><a href="../../ref/am/put.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../ref/toc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/am/sync.html"><img src="../../images/next.gif" alt="Next"></a> +</td></tr></table> +<p> +<h1 align=center>Deleting records</h1> +<p>The <a href="../../api_c/db_del.html">DB->del</a> function is the standard interface for deleting records from +the database. In general, <a href="../../api_c/db_del.html">DB->del</a> takes a key and deletes the +data item associated with it from the database. +<p>If the database has been configured to support duplicate records, the +<a href="../../api_c/db_del.html">DB->del</a> function will remove all of the duplicate records. To remove +individual duplicate records, you must use a Berkeley DB cursor interface. +<table><tr><td><br></td><td width="1%"><a href="../../ref/am/put.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../ref/toc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/am/sync.html"><img src="../../images/next.gif" alt="Next"></a> +</td></tr></table> +<p><font size=1><a href="http://www.sleepycat.com">Copyright Sleepycat Software</a></font> +</body> +</html> diff --git a/db/docs/ref/am/error.html b/db/docs/ref/am/error.html new file mode 100644 index 000000000..737e6d662 --- /dev/null +++ b/db/docs/ref/am/error.html @@ -0,0 +1,61 @@ +<!--$Id: error.so,v 10.14 2000/12/18 21:05:13 bostic Exp $--> +<!--Copyright 1997, 1998, 1999, 2000 by Sleepycat Software, Inc.--> +<!--All rights reserved.--> +<html> +<head> +<title>Berkeley DB Reference Guide: Error support</title> +<meta name="description" content="Berkeley DB: An embedded database programmatic toolkit."> +<meta name="keywords" content="embedded,database,programmatic,toolkit,b+tree,btree,hash,hashing,transaction,transactions,locking,logging,access method,access methods,java,C,C++"> +</head> +<body bgcolor=white> + <a name="2"><!--meow--></a> +<table><tr valign=top> +<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Access Methods</dl></h3></td> +<td width="1%"><a href="../../ref/am/verify.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../ref/toc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/arch/bigpic.html"><img src="../../images/next.gif" alt="Next"></a> +</td></tr></table> +<p> +<h1 align=center>Error support</h1> +<p>Berkeley DB offers programmatic support for displaying error return values. +<p>The <a href="../../api_c/env_strerror.html">db_strerror</a> interface returns a pointer to the error +message corresponding to any Berkeley DB error return, similar to the ANSI C +strerror interface, but is able to handle both system error returns and +Berkeley DB specific return values. +<p>For example: +<p><blockquote><pre>int ret; +if ((ret = dbp->put(dbp, NULL, &key, &data, 0)) != 0) { + fprintf(stderr, "put failed: %s\n", db_strerror(ret)); + return (1); +} +</pre></blockquote> +<p>There are also two additional error interfaces, <a href="../../api_c/db_err.html">DB->err</a> and +<a href="../../api_c/db_err.html">DB->errx</a>. These interfaces work like the ANSI C X3.159-1989 (ANSI C) printf +interface, taking a printf-style format string and argument list, and +writing a message constructed from the format string and arguments. +<p>The <a href="../../api_c/db_err.html">DB->err</a> function appends the standard error string to the constructed +message, the <a href="../../api_c/db_err.html">DB->errx</a> function does not. These interfaces provide simpler +ways of displaying Berkeley DB error messages. For example, if your application +tracks session IDs in a variable called session_id, it can include that +information in its error messages: +<p>Error messages can additionally be configured to always include a prefix +(e.g., the program name) using the <a href="../../api_c/db_set_errpfx.html">DB->set_errpfx</a> interface. +<p><blockquote><pre>#define DATABASE "access.db" +int ret; +dbp->errpfx(dbp, argv0); +if ((ret = + dbp->open(dbp, DATABASE, DB_BTREE, DB_CREATE, 0664)) != 0) { + dbp->err(dbp, ret, "%s", DATABASE); + dbp->errx(dbp, + "contact your system administrator: session ID was %d", + session_id); + return (1); +} +</pre></blockquote> +<p>For example, if the program was called my_app, and the open call returned +an EACCESS system error, the error messages shown would appear as follows: +<p><blockquote><pre>my_app: access.db: Permission denied. +my_app: contact your system administrator: session ID was 14</pre></blockquote> +<table><tr><td><br></td><td width="1%"><a href="../../ref/am/verify.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../ref/toc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/arch/bigpic.html"><img src="../../images/next.gif" alt="Next"></a> +</td></tr></table> +<p><font size=1><a href="http://www.sleepycat.com">Copyright Sleepycat Software</a></font> +</body> +</html> diff --git a/db/docs/ref/am/get.html b/db/docs/ref/am/get.html new file mode 100644 index 000000000..fda7a8eb2 --- /dev/null +++ b/db/docs/ref/am/get.html @@ -0,0 +1,39 @@ +<!--$Id: get.so,v 10.15 2000/12/18 21:05:13 bostic Exp $--> +<!--Copyright 1997, 1998, 1999, 2000 by Sleepycat Software, Inc.--> +<!--All rights reserved.--> +<html> +<head> +<title>Berkeley DB Reference Guide: Retrieving records</title> +<meta name="description" content="Berkeley DB: An embedded database programmatic toolkit."> +<meta name="keywords" content="embedded,database,programmatic,toolkit,b+tree,btree,hash,hashing,transaction,transactions,locking,logging,access method,access methods,java,C,C++"> +</head> +<body bgcolor=white> + <a name="2"><!--meow--></a> +<table><tr valign=top> +<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Access Methods</dl></h3></td> +<td width="1%"><a href="../../ref/am/upgrade.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../ref/toc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/am/put.html"><img src="../../images/next.gif" alt="Next"></a> +</td></tr></table> +<p> +<h1 align=center>Retrieving records</h1> +<p>The <a href="../../api_c/db_get.html">DB->get</a> function is the standard interface for retrieving records from +the database. In general, <a href="../../api_c/db_get.html">DB->get</a> takes a key and returns the +associated data from the database. +<p>There are a few flags that you can set to customize retrieval: +<p><dl compact> +<p><dt><a href="../../api_c/db_get.html#DB_GET_BOTH">DB_GET_BOTH</a><dd>Search for a matching key and data item, i.e., only return success if both +the key and the data items match those stored in the database. +<p><dt><a href="../../api_c/dbc_get.html#DB_RMW">DB_RMW</a><dd>Read-modify-write: acquire write locks instead of read locks during +retrieval. This can enhance performance in threaded applications by +reducing the chance of deadlock. +<p><dt><a href="../../api_c/db_get.html#DB_SET_RECNO">DB_SET_RECNO</a><dd>If the underlying database is a Btree, and was configured so that it +is possible to search it by logical record number, retrieve a specific +record. +</dl> +<p>If the database has been configured to support duplicate records, +<a href="../../api_c/db_get.html">DB->get</a> will always return the first data item in the duplicate +set. +<table><tr><td><br></td><td width="1%"><a href="../../ref/am/upgrade.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../ref/toc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/am/put.html"><img src="../../images/next.gif" alt="Next"></a> +</td></tr></table> +<p><font size=1><a href="http://www.sleepycat.com">Copyright Sleepycat Software</a></font> +</body> +</html> diff --git a/db/docs/ref/am/join.html b/db/docs/ref/am/join.html new file mode 100644 index 000000000..9d4dcdd09 --- /dev/null +++ b/db/docs/ref/am/join.html @@ -0,0 +1,184 @@ +<!--$Id: join.so,v 10.21 2000/12/18 21:05:13 bostic Exp $--> +<!--Copyright 1997, 1998, 1999, 2000 by Sleepycat Software, Inc.--> +<!--All rights reserved.--> +<html> +<head> +<title>Berkeley DB Reference Guide: Logical join</title> +<meta name="description" content="Berkeley DB: An embedded database programmatic toolkit."> +<meta name="keywords" content="embedded,database,programmatic,toolkit,b+tree,btree,hash,hashing,transaction,transactions,locking,logging,access method,access methods,java,C,C++"> +</head> +<body bgcolor=white> + <a name="2"><!--meow--></a> +<table><tr valign=top> +<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Access Methods</dl></h3></td> +<td width="1%"><a href="../../ref/am/curdup.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../ref/toc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/am/count.html"><img src="../../images/next.gif" alt="Next"></a> +</td></tr></table> +<p> +<h1 align=center>Logical join</h1> +<p>A logical join is a method of retrieving data from a primary database +using criteria stored in a set of secondary indexes. A logical join +requires that your data be organized as a primary database which +contains the primary key and primary data field, and a set of secondary +indexes. Each of the secondary indexes is indexed by a different +secondary key, and, for each key in a secondary index, there is a set +of duplicate data items that match the primary keys in the primary +database. +<p>For example, let's assume the need for an application that will return +the names of stores in which one can buy fruit of a given color. We +would first construct a primary database that lists types of fruit as +the key item, and the store where you can buy them as the data item: +<p><blockquote><pre><b>Primary key:</b> <b>Primary data:</b> +apple Convenience Store +blueberry Farmer's Market +peach Shopway +pear Farmer's Market +raspberry Shopway +strawberry Farmer's Market</pre></blockquote> +<p>We would then create a secondary index with the key <b>color</b>, and, +as the data items, the names of fruits of different colors. +<p><blockquote><pre><b>Secondary key:</b> <b>Secondary data:</b> +blue blueberry +red apple +red raspberry +red strawberry +yellow peach +yellow pear</pre></blockquote> +<p>This secondary index would allow an application to look up a color, and +then use the data items to look up the stores where the colored fruit +could be purchased. For example, by first looking up <b>blue</b>, +the data item <b>blueberry</b> could be used as the lookup key in the +primary database, returning <b>Farmer's Market</b>. +<p>Your data must be organized in the following manner in order to use the +<a href="../../api_c/db_join.html">DB->join</a> function: +<p><ol> +<p><li>The actual data should be stored in the database represented by the +DB object used to invoke this function. Generally, this +DB object is called the <i>primary</i>. +<p><li>Secondary indexes should be stored in separate databases, whose keys +are the values of the secondary indexes and whose data items are the +primary keys corresponding to the records having the designated +secondary key value. It is acceptable (and expected) that there may be +duplicate entries in the secondary indexes. +<p>These duplicate entries should be sorted for performance reasons, although +it is not required. For more information see the <a href="../../api_c/db_set_flags.html#DB_DUPSORT">DB_DUPSORT</a> flag +to the <a href="../../api_c/db_set_flags.html">DB->set_flags</a> function. +</ol> +<p>What the <a href="../../api_c/db_join.html">DB->join</a> function does is review a list of secondary keys, and, +when it finds a data item that appears as a data item for all of the +secondary keys, it uses that data items as a lookup into the primary +database, and returns the associated data item. +<p>If there were a another secondary index that had as its key the +<b>cost</b> of the fruit, a similar lookup could be done on stores +where inexpensive fruit could be purchased: +<p><blockquote><pre><b>Secondary key:</b> <b>Secondary data:</b> +expensive blueberry +expensive peach +expensive pear +expensive strawberry +inexpensive apple +inexpensive pear +inexpensive raspberry</pre></blockquote> +<p>The <a href="../../api_c/db_join.html">DB->join</a> function provides logical join functionality. While not +strictly cursor functionality, in that it is not a method off a cursor +handle, it is more closely related to the cursor operations than to the +standard DB operations. +<p>It is also possible to do lookups based on multiple criteria in a single +operation, e.g., it is possible to look up fruits that are both red and +expensive in a single operation. If the same fruit appeared as a data +item in both the color and expense indexes, then that fruit name would +be used as the key for retrieval from the primary index, and would then +return the store where expensive, red fruit could be purchased. +<h3>Example</h3> +<p>Consider the following three databases: +<p><dl compact> +<p><dt>personnel<dd><ul type=disc> +<li>key = SSN +<li>data = record containing name, address, phone number, job title +</ul> +<p><dt>lastname<dd><ul type=disc> +<li>key = lastname +<li>data = SSN +</ul> +<p><dt>jobs<dd><ul type=disc> +<li>key = job title +<li>data = SSN +</ul> +</dl> +<p>Consider the following query: +<p><blockquote><pre>Return the personnel records of all people named smith with the job +title manager.</pre></blockquote> +<p>This query finds are all the records in the primary database (personnel) +for whom the criteria <b>lastname=smith and job title=manager</b> is +true. +<p>Assume that all databases have been properly opened and have the handles: +pers_db, name_db, job_db. We also assume that we have an active +transaction referenced by the handle txn. +<p><blockquote><pre>DBC *name_curs, *job_curs, *join_curs; +DBC *carray[3]; +DBT key, data; +int ret, tret; +<p> +name_curs = NULL; +job_curs = NULL; +memset(&key, 0, sizeof(key)); +memset(&data, 0, sizeof(data)); +<p> +if ((ret = + name_db->cursor(name_db, txn, &name_curs)) != 0) + goto err; +key.data = "smith"; +key.size = sizeof("smith"); +if ((ret = + name_curs->c_get(name_curs, &key, &data, DB_SET)) != 0) + goto err; +<p> +if ((ret = job_db->cursor(job_db, txn, &job_curs)) != 0) + goto err; +key.data = "manager"; +key.size = sizeof("manager"); +if ((ret = + job_curs->c_get(job_curs, &key, &data, DB_SET)) != 0) + goto err; +<p> +carray[0] = name_curs; +carray[1] = job_curs; +carray[2] = NULL; +<p> +if ((ret = + pers_db->join(pers_db, carray, &join_curs, 0)) != 0) + goto err; +while ((ret = + join_curs->c_get(join_curs, &key, &data, 0)) == 0) { + /* Process record returned in key/data. */ +} +<p> +/* + * If we exited the loop because we ran out of records, + * then it has completed successfully. + */ +if (ret == DB_NOTFOUND) + ret = 0; +<p> +err: +if (join_curs != NULL && + (tret = join_curs->c_close(join_curs)) != 0 && ret == 0) + ret = tret; +if (name_curs != NULL && + (tret = name_curs->c_close(name_curs)) != 0 && ret == 0) + ret = tret; +if (job_curs != NULL && + (tret = job_curs->c_close(job_curs)) != 0 && ret == 0) + ret = tret; +<p> +return (ret); +</pre></blockquote> +<p>The name cursor is positioned at the beginning of the duplicate list +for <b>smith</b> and the job cursor is placed at the beginning of +the duplicate list for <b>manager</b>. The join cursor is returned +from the logical join call. This code then loops over the join cursor +getting the personnel records of each one until there are no more. +<table><tr><td><br></td><td width="1%"><a href="../../ref/am/curdup.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../ref/toc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/am/count.html"><img src="../../images/next.gif" alt="Next"></a> +</td></tr></table> +<p><font size=1><a href="http://www.sleepycat.com">Copyright Sleepycat Software</a></font> +</body> +</html> diff --git a/db/docs/ref/am/open.html b/db/docs/ref/am/open.html new file mode 100644 index 000000000..01c45339e --- /dev/null +++ b/db/docs/ref/am/open.html @@ -0,0 +1,47 @@ +<!--$Id: open.so,v 10.15 2000/12/18 21:05:14 bostic Exp $--> +<!--Copyright 1997, 1998, 1999, 2000 by Sleepycat Software, Inc.--> +<!--All rights reserved.--> +<html> +<head> +<title>Berkeley DB Reference Guide: Opening a database</title> +<meta name="description" content="Berkeley DB: An embedded database programmatic toolkit."> +<meta name="keywords" content="embedded,database,programmatic,toolkit,b+tree,btree,hash,hashing,transaction,transactions,locking,logging,access method,access methods,java,C,C++"> +</head> +<body bgcolor=white> + <a name="2"><!--meow--></a> +<table><tr valign=top> +<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Access Methods</dl></h3></td> +<td width="1%"><a href="../../ref/am/ops.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../ref/toc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/am/opensub.html"><img src="../../images/next.gif" alt="Next"></a> +</td></tr></table> +<p> +<h1 align=center>Opening a database</h1> +<p>The <a href="../../api_c/db_open.html">DB->open</a> function is the standard interface for opening a database, +and takes five arguments: +<p><dl compact> +<p><dt>file<dd>The name of the file to be opened. +<p><dt>database<dd>An optional database name. +<p><dt>type<dd>The type of database to open. This value will be one of the four access +methods Berkeley DB supports: DB_BTREE, DB_HASH, DB_QUEUE or DB_RECNO, or the +special value DB_UNKNOWN, which allows you to open an existing file +without knowing its type. +<p><dt>mode<dd>The permissions to give to any created file. +</dl> +<p>There are a few flags that you can set to customize open: +<p><dl compact> +<p><dt><a href="../../api_c/env_open.html#DB_CREATE">DB_CREATE</a><dd>Create the underlying database and any necessary physical files. +<p><dt><a href="../../api_c/env_open.html#DB_NOMMAP">DB_NOMMAP</a><dd>Do not map this database into process memory. +<p><dt><a href="../../api_c/db_open.html#DB_RDONLY">DB_RDONLY</a><dd>Treat the data base as readonly. +<p><dt><a href="../../api_c/env_open.html#DB_THREAD">DB_THREAD</a><dd>The returned handle is free-threaded, that is, it can be used +simultaneously by multiple threads within the process. +<p><dt><a href="../../api_c/db_open.html#DB_TRUNCATE">DB_TRUNCATE</a><dd>Physically truncate the underlying database file, discarding all +databases it contained. Underlying filesystem primitives are used to +implement this flag. For this reason it is only applicable to the +physical file and cannot be used to discard individual databases from +within physical files. +<p><dt><a href="../../api_c/db_set_feedback.html#DB_UPGRADE">DB_UPGRADE</a><dd>Upgrade the database format as necessary. +</dl> +<table><tr><td><br></td><td width="1%"><a href="../../ref/am/ops.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../ref/toc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/am/opensub.html"><img src="../../images/next.gif" alt="Next"></a> +</td></tr></table> +<p><font size=1><a href="http://www.sleepycat.com">Copyright Sleepycat Software</a></font> +</body> +</html> diff --git a/db/docs/ref/am/opensub.html b/db/docs/ref/am/opensub.html new file mode 100644 index 000000000..066ca4b79 --- /dev/null +++ b/db/docs/ref/am/opensub.html @@ -0,0 +1,64 @@ +<!--$Id: opensub.so,v 10.6 2000/12/18 21:05:14 bostic Exp $--> +<!--Copyright 1997, 1998, 1999, 2000 by Sleepycat Software, Inc.--> +<!--All rights reserved.--> +<html> +<head> +<title>Berkeley DB Reference Guide: Opening multiple databases in a single file</title> +<meta name="description" content="Berkeley DB: An embedded database programmatic toolkit."> +<meta name="keywords" content="embedded,database,programmatic,toolkit,b+tree,btree,hash,hashing,transaction,transactions,locking,logging,access method,access methods,java,C,C++"> +</head> +<body bgcolor=white> +<table><tr valign=top> +<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Access Methods</dl></h3></td> +<td width="1%"><a href="../../ref/am/open.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../ref/toc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/am/upgrade.html"><img src="../../images/next.gif" alt="Next"></a> +</td></tr></table> +<p> +<h1 align=center>Opening multiple databases in a single file</h1> +<p>Applications may create multiple databases within a single physical +file. This is useful when the databases are both numerous and +reasonably small, in order to avoid creating a large number of +underlying files, or when it is desirable to include secondary index +databases in the same file as the primary index database. Multiple +databases are an administrative convenience and using them is unlikely +to effect database performance. To open or create a file that will +include more than a single database, specify a database name when +calling the <a href="../../api_c/db_open.html">DB->open</a> method. +<p>Physical files do not need to be comprised of a single type of database, +and databases in a file may be of any type (e.g., Btree, Hash or Recno), +except for Queue databases. Queue databases must be created one per file +and cannot share a file with any other database type. There is no limit +on the number of databases that may be created in a single file other than +the standard Berkeley DB file size and disk space limitations. +<p>It is an error to attempt to open a second database in a file that was +not initially created using a database name, that is, the file must +initially be specified as capable of containing multiple databases for a +second database to be created in it. +<p>It is not an error to open a file that contains multiple databases without +specifying a database name, however the database type should be specified +as DB_UNKNOWN and the database must be opened read-only. The handle that +is returned from such a call is a handle on a database whose key values +are the names of the databases stored in the database file and whose data +values are opaque objects. No keys or data values may be modified or +stored using this database handle. +<p>Storing multiple databases in a single file is almost identical to +storing each database in its own separate file. The one crucial +difference is how locking and the underlying memory pool services must +to be configured. As an example, consider two databases instantiated +in two different physical files. If access to each separate database +is single-threaded, there is no reason to perform any locking of any +kind, and the two databases may be read and written simultaneously. +Further, there would be no requirement to create a shared database +environment in which to open the databases. Because multiple databases +in a file exist in a single physical file, opening two databases in the +same file requires that locking be enabled, unless access to the +databases is known to be single-threaded, that is, only one of the +databases is ever accessed at a time. (As the locks for the two +databases can only conflict during page allocation, this additional +locking is unlikely to effect performance.) Further, the databases must +share an underlying memory pool so that per-physical-file information +is updated correctly. +<table><tr><td><br></td><td width="1%"><a href="../../ref/am/open.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../ref/toc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/am/upgrade.html"><img src="../../images/next.gif" alt="Next"></a> +</td></tr></table> +<p><font size=1><a href="http://www.sleepycat.com">Copyright Sleepycat Software</a></font> +</body> +</html> diff --git a/db/docs/ref/am/ops.html b/db/docs/ref/am/ops.html new file mode 100644 index 000000000..5daaddd74 --- /dev/null +++ b/db/docs/ref/am/ops.html @@ -0,0 +1,36 @@ +<!--$Id: ops.so,v 10.16 2000/12/18 21:05:14 bostic Exp $--> +<!--Copyright 1997, 1998, 1999, 2000 by Sleepycat Software, Inc.--> +<!--All rights reserved.--> +<html> +<head> +<title>Berkeley DB Reference Guide: Access method operations</title> +<meta name="description" content="Berkeley DB: An embedded database programmatic toolkit."> +<meta name="keywords" content="embedded,database,programmatic,toolkit,b+tree,btree,hash,hashing,transaction,transactions,locking,logging,access method,access methods,java,C,C++"> +</head> +<body bgcolor=white> +<table><tr valign=top> +<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Access Methods</dl></h3></td> +<td width="1%"><a href="../../ref/am_conf/renumber.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../ref/toc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/am/open.html"><img src="../../images/next.gif" alt="Next"></a> +</td></tr></table> +<p> +<h1 align=center>Access method operations</h1> +<p>Once a database handle has been created using <a href="../../api_c/db_create.html">db_create</a>, there +are several standard access method operations. Each of these operations +is performed using a method that is referenced from the returned handle. +The operations are as follows: +<p><dl compact> +<p><dt><a href="../../api_c/db_close.html">DB->close</a><dd>Close the database +<dt><a href="../../api_c/db_cursor.html">DB->cursor</a><dd>Open a cursor into the database +<dt><a href="../../api_c/db_del.html">DB->del</a><dd>Delete a record +<dt><a href="../../api_c/db_get.html">DB->get</a><dd>Retrieve a record +<dt><a href="../../api_c/db_open.html">DB->open</a><dd>Open a database +<dt><a href="../../api_c/db_put.html">DB->put</a><dd>Store a record +<dt><a href="../../api_c/db_stat.html">DB->stat</a><dd>Return statistics about the database +<dt><a href="../../api_c/db_sync.html">DB->sync</a><dd>Flush the underlying cache +<dt><a href="../../api_c/db_upgrade.html">DB->upgrade</a><dd>Upgrade a database +</dl> +<table><tr><td><br></td><td width="1%"><a href="../../ref/am_conf/renumber.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../ref/toc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/am/open.html"><img src="../../images/next.gif" alt="Next"></a> +</td></tr></table> +<p><font size=1><a href="http://www.sleepycat.com">Copyright Sleepycat Software</a></font> +</body> +</html> diff --git a/db/docs/ref/am/partial.html b/db/docs/ref/am/partial.html new file mode 100644 index 000000000..7f3af8f68 --- /dev/null +++ b/db/docs/ref/am/partial.html @@ -0,0 +1,134 @@ +<!--$Id: partial.so,v 10.18 2000/12/18 21:05:14 bostic Exp $--> +<!--Copyright 1997, 1998, 1999, 2000 by Sleepycat Software, Inc.--> +<!--All rights reserved.--> +<html> +<head> +<title>Berkeley DB Reference Guide: Partial record storage and retrieval</title> +<meta name="description" content="Berkeley DB: An embedded database programmatic toolkit."> +<meta name="keywords" content="embedded,database,programmatic,toolkit,b+tree,btree,hash,hashing,transaction,transactions,locking,logging,access method,access methods,java,C,C++"> +</head> +<body bgcolor=white> + <a name="2"><!--meow--></a> +<table><tr valign=top> +<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Access Methods</dl></h3></td> +<td width="1%"><a href="../../ref/am/stability.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../ref/toc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/am/verify.html"><img src="../../images/next.gif" alt="Next"></a> +</td></tr></table> +<p> +<h1 align=center>Partial record storage and retrieval</h1> +<p>It is possible to both store and retrieve parts of data items in all +Berkeley DB access methods. This is done by setting the +<a href="../../api_c/dbt.html#DB_DBT_PARTIAL">DB_DBT_PARTIAL</a> flag in the <a href="../../api_c/dbt.html">DBT</a> structure passed to the +Berkeley DB interface. +<p>The <a href="../../api_c/dbt.html#DB_DBT_PARTIAL">DB_DBT_PARTIAL</a> flag is based on the values of two fields +of the <a href="../../api_c/dbt.html">DBT</a> structure, <b>dlen</b> and <b>doff</b>. The value +of <b>dlen</b> is the number of bytes of the record in which the +application is interested. The value of <b>doff</b> is the offset from +the beginning of the data item where those bytes start. +<p>For example, if the data item were <b>ABCDEFGHIJKL</b>, a <b>doff</b> +value of 3 would indicate that the bytes of interest started at +<b>D</b>, and a <b>dlen</b> value of 4 would indicate that the bytes +of interest were <b>DEFG</b>. +<p>When retrieving a data item from a database, the <b>dlen</b> bytes +starting <b>doff</b> bytes from the beginning of the record are +returned, as if they comprised the entire record. If any or all of the +specified bytes do not exist in the record, the retrieval is still +successful and any existing bytes (and nul bytes for any non-existent +bytes) are returned. +<p>When storing a data item into the database, the <b>dlen</b> bytes +starting <b>doff</b> bytes from the beginning of the specified key's +data record are replaced by the data specified by the <b>data</b> and +<b>size</b> fields. If <b>dlen</b> is smaller than <b>size</b>, the +record will grow, and if <b>dlen</b> is larger than <b>size</b>, the +record will shrink. If the specified bytes do not exist, the record will +be extended using nul bytes as necessary, and the store call will still +succeed. +<p>The following are various examples of the put case for the +<a href="../../api_c/dbt.html#DB_DBT_PARTIAL">DB_DBT_PARTIAL</a> flag. In all examples, the initial data item is 20 +bytes in length: +<p><b>ABCDEFGHIJ0123456789</b> +<p><ol> +<p><li><p><blockquote><pre>size = 20 +doff = 0 +dlen = 20 +data = abcdefghijabcdefghij +<p> +Result: The 20 bytes at offset 0 are replaced by the 20 bytes of data, +i.e., the entire record is replaced. +<p> +ABCDEFGHIJ0123456789 -> abcdefghijabcdefghij +</pre></blockquote> +<p><li><p><blockquote><pre>size = 10 +doff = 20 +dlen = 0 +data = abcdefghij +<p> +Result: The 0 bytes at offset 20 are replaced by the 10 bytes of data, +i.e., the record is extended by 10 bytes. +<p> +ABCDEFGHIJ0123456789 -> ABCDEFGHIJ0123456789abcdefghij +</pre></blockquote> +<p><li><p><blockquote><pre>size = 10 +doff = 10 +dlen = 5 +data = abcdefghij +<p> +Result: The 5 bytes at offset 10 are replaced by the 10 bytes of data. +<p> +ABCDEFGHIJ0123456789 -> ABCDEFGHIJabcdefghij56789 +</pre></blockquote> +<p><li><p><blockquote><pre>size = 10 +doff = 10 +dlen = 0 +data = abcdefghij +<p> +Result: The 0 bytes at offset 10 are replaced by the 10 bytes of data, +i.e., 10 bytes are inserted into the record. +<p> +ABCDEFGHIJ0123456789 -> ABCDEFGHIJabcdefghij0123456789 +</pre></blockquote> +<p><li><p><blockquote><pre>size = 10 +doff = 2 +dlen = 15 +data = abcdefghij +<p> +Result: The 15 bytes at offset 2 are replaced by the 10 bytes of data. +<p> +ABCDEFGHIJ0123456789 -> ABabcdefghij789 +</pre></blockquote> +<p><li><p><blockquote><pre>size = 10 +doff = 0 +dlen = 0 +data = abcdefghij +<p> +Result: The 0 bytes at offset 0 are replaced by the 10 bytes of data, +i.e., the 10 bytes are inserted at the beginning of the record. +<p> +ABCDEFGHIJ0123456789 -> abcdefghijABCDEFGHIJ0123456789 +</pre></blockquote> +<p><li><p><blockquote><pre>size = 0 +doff = 0 +dlen = 10 +data = "" +<p> +Result: The 10 bytes at offset 0 are replaced by the 0 bytes of data, +i.e., the first 10 bytes of the record are discarded. +<p> +ABCDEFGHIJ0123456789 -> 0123456789 +</pre></blockquote> +<p><li><p><blockquote><pre>size = 10 +doff = 25 +dlen = 0 +data = abcdefghij +<p> +Result: The 0 bytes at offset 25 are replaced by the 10 bytes of data, +i.e., 10 bytes are inserted into the record past the end of the current +data (\0 represents a nul byte). +<p> +ABCDEFGHIJ0123456789 -> ABCDEFGHIJ0123456789\0\0\0\0\0abcdefghij +</pre></blockquote> +</ol> +<table><tr><td><br></td><td width="1%"><a href="../../ref/am/stability.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../ref/toc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/am/verify.html"><img src="../../images/next.gif" alt="Next"></a> +</td></tr></table> +<p><font size=1><a href="http://www.sleepycat.com">Copyright Sleepycat Software</a></font> +</body> +</html> diff --git a/db/docs/ref/am/put.html b/db/docs/ref/am/put.html new file mode 100644 index 000000000..993dcbeb0 --- /dev/null +++ b/db/docs/ref/am/put.html @@ -0,0 +1,36 @@ +<!--$Id: put.so,v 10.14 2000/03/18 21:43:08 bostic Exp $--> +<!--Copyright 1997, 1998, 1999, 2000 by Sleepycat Software, Inc.--> +<!--All rights reserved.--> +<html> +<head> +<title>Berkeley DB Reference Guide: Storing records</title> +<meta name="description" content="Berkeley DB: An embedded database programmatic toolkit."> +<meta name="keywords" content="embedded,database,programmatic,toolkit,b+tree,btree,hash,hashing,transaction,transactions,locking,logging,access method,access methods,java,C,C++"> +</head> +<body bgcolor=white> + <a name="2"><!--meow--></a> +<table><tr valign=top> +<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Access Methods</dl></h3></td> +<td width="1%"><a href="../../ref/am/get.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../ref/toc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/am/delete.html"><img src="../../images/next.gif" alt="Next"></a> +</td></tr></table> +<p> +<h1 align=center>Storing records</h1> +<p>The <a href="../../api_c/db_put.html">DB->put</a> function is the standard interface for storing records into +the database. In general, <a href="../../api_c/db_put.html">DB->put</a> takes a key and stores the +associated data into the database. +<p>There are a few flags that you can set to customize storage: +<p><dl compact> +<p><dt><a href="../../api_c/db_put.html#DB_APPEND">DB_APPEND</a><dd>Simply append the data to the end of the database, treating the database +much like a simple log. This flag is only valid for the Queue and Recno +access methods. +<p><dt><a href="../../api_c/db_put.html#DB_NOOVERWRITE">DB_NOOVERWRITE</a><dd>Only store the data item if the key does not already appear in the database. +</dl> +<p>If the database has been configured to support duplicate records, the +<a href="../../api_c/db_put.html">DB->put</a> function will add the new data value at the end of the duplicate +set. If the database supports sorted duplicates, the new data value is +inserted at the correct sorted location. +<table><tr><td><br></td><td width="1%"><a href="../../ref/am/get.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../ref/toc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/am/delete.html"><img src="../../images/next.gif" alt="Next"></a> +</td></tr></table> +<p><font size=1><a href="http://www.sleepycat.com">Copyright Sleepycat Software</a></font> +</body> +</html> diff --git a/db/docs/ref/am/stability.html b/db/docs/ref/am/stability.html new file mode 100644 index 000000000..b5f6d2386 --- /dev/null +++ b/db/docs/ref/am/stability.html @@ -0,0 +1,49 @@ +<!--$Id: stability.so,v 10.20 2000/12/13 16:48:13 bostic Exp $--> +<!--Copyright 1997, 1998, 1999, 2000 by Sleepycat Software, Inc.--> +<!--All rights reserved.--> +<html> +<head> +<title>Berkeley DB Reference Guide: Cursor Stability</title> +<meta name="description" content="Berkeley DB: An embedded database programmatic toolkit."> +<meta name="keywords" content="embedded,database,programmatic,toolkit,b+tree,btree,hash,hashing,transaction,transactions,locking,logging,access method,access methods,java,C,C++"> +</head> +<body bgcolor=white> + <a name="2"><!--meow--></a> <a name="3"><!--meow--></a> +<table><tr valign=top> +<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Transaction Subsystem</dl></h3></td> +<td width="1%"><a href="../../ref/am/curclose.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../ref/toc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/am/partial.html"><img src="../../images/next.gif" alt="Next"></a> +</td></tr></table> +<p> +<h1 align=center>Cursor Stability</h1> +<p>In the absence of locking, no guarantees are made about the stability of +cursors in different processes or threads. However, the Btree, Queue +and Recno access methods guarantee that cursor operations, interspersed +with other cursor or non-cursor operations in the same thread of control +will always return keys in order and will return each non-deleted key/data +pair exactly once. Because the Hash access method uses a dynamic hashing +algorithm, it cannot guarantee any form of stability in the presence of +inserts and deletes unless locking is performed. +<p>If locking was specified when the Berkeley DB file was opened, but transactions +are not in effect, the access methods provide repeatable reads with +respect to the cursor. That is, a <a href="../../api_c/dbc_get.html#DB_CURRENT">DB_CURRENT</a> call on the cursor +is guaranteed to return the same record as was returned on the last call +to the cursor. +<p>With the exception of the Queue access method, in the presence of +transactions, all access method calls between a call to <a href="../../api_c/txn_begin.html">txn_begin</a> +and a call to <a href="../../api_c/txn_abort.html">txn_abort</a> or <a href="../../api_c/txn_commit.html">txn_commit</a> provide degree 3 +consistency (serializable transactions). +<p>The Queue access method permits phantom records to appear between calls. +That is, deleted records are not locked, therefore another transaction may +replace a deleted record between two calls to retrieve it. The record would +not appear in the first call but would be seen by the second call. +<p>For all access methods, a cursor scan of the database performed within +the context of a transaction is guaranteed to return each key/data pair +once and only once, except in the following case. If, while performing +a cursor scan using the Hash access method, the transaction performing +the scan inserts a new pair into the database, it is possible that duplicate +key/data pairs will be returned. +<table><tr><td><br></td><td width="1%"><a href="../../ref/am/curclose.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../ref/toc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/am/partial.html"><img src="../../images/next.gif" alt="Next"></a> +</td></tr></table> +<p><font size=1><a href="http://www.sleepycat.com">Copyright Sleepycat Software</a></font> +</body> +</html> diff --git a/db/docs/ref/am/stat.html b/db/docs/ref/am/stat.html new file mode 100644 index 000000000..3042ccfee --- /dev/null +++ b/db/docs/ref/am/stat.html @@ -0,0 +1,36 @@ +<!--$Id: stat.so,v 10.17 2000/12/18 21:05:14 bostic Exp $--> +<!--Copyright 1997, 1998, 1999, 2000 by Sleepycat Software, Inc.--> +<!--All rights reserved.--> +<html> +<head> +<title>Berkeley DB Reference Guide: Database statistics</title> +<meta name="description" content="Berkeley DB: An embedded database programmatic toolkit."> +<meta name="keywords" content="embedded,database,programmatic,toolkit,b+tree,btree,hash,hashing,transaction,transactions,locking,logging,access method,access methods,java,C,C++"> +</head> +<body bgcolor=white> + <a name="2"><!--meow--></a> +<table><tr valign=top> +<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Access Methods</dl></h3></td> +<td width="1%"><a href="../../ref/am/sync.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../ref/toc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/am/close.html"><img src="../../images/next.gif" alt="Next"></a> +</td></tr></table> +<p> +<h1 align=center>Database statistics</h1> +<p>The <a href="../../api_c/db_stat.html">DB->stat</a> function is the standard interface for obtaining database +statistics. Generally, <a href="../../api_c/db_stat.html">DB->stat</a> returns a set of statistics +about the underlying database, e.g., the number of key/data pairs in +the database, how the database was originally configured, and so on. +<p>There are two flags that you can set to customize the returned statistics: +<p><dl compact> +<p><dt><a href="../../api_c/db_stat.html#DB_CACHED_COUNTS">DB_CACHED_COUNTS</a><dd>Request an approximate key and key/data pair count. As obtaining an +exact count can be very performance intensive for large databases, +it is possible to request a previously cached count. Obviously, the +cached count is only an approximate count, and may be out-of-date. +<p><dt><a href="../../api_c/db_stat.html#DB_RECORDCOUNT">DB_RECORDCOUNT</a><dd>If the database is a Queue or Recno database, or a Btree database that +was configured so that it is possible to search it by logical record +number, return only a count of the records in the database. +</dl> +<table><tr><td><br></td><td width="1%"><a href="../../ref/am/sync.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../ref/toc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/am/close.html"><img src="../../images/next.gif" alt="Next"></a> +</td></tr></table> +<p><font size=1><a href="http://www.sleepycat.com">Copyright Sleepycat Software</a></font> +</body> +</html> diff --git a/db/docs/ref/am/sync.html b/db/docs/ref/am/sync.html new file mode 100644 index 000000000..3d1d61e62 --- /dev/null +++ b/db/docs/ref/am/sync.html @@ -0,0 +1,38 @@ +<!--$Id: sync.so,v 10.15 2000/12/18 21:05:14 bostic Exp $--> +<!--Copyright 1997, 1998, 1999, 2000 by Sleepycat Software, Inc.--> +<!--All rights reserved.--> +<html> +<head> +<title>Berkeley DB Reference Guide: Flushing the database cache</title> +<meta name="description" content="Berkeley DB: An embedded database programmatic toolkit."> +<meta name="keywords" content="embedded,database,programmatic,toolkit,b+tree,btree,hash,hashing,transaction,transactions,locking,logging,access method,access methods,java,C,C++"> +</head> +<body bgcolor=white> + <a name="2"><!--meow--></a> +<table><tr valign=top> +<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Access Methods</dl></h3></td> +<td width="1%"><a href="../../ref/am/delete.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../ref/toc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/am/stat.html"><img src="../../images/next.gif" alt="Next"></a> +</td></tr></table> +<p> +<h1 align=center>Flushing the database cache</h1> +<p>The <a href="../../api_c/db_sync.html">DB->sync</a> function is the standard interface for flushing all modified +records from the database cache to disk. +<p><b>It is important to understand that flushing cached information +to disk only minimizes the window of opportunity for corrupted data, it +does not eliminate the possibility.</b> +<p>While unlikely, it is possible for database corruption to happen if a +system or application crash occurs while writing data to the database. To +ensure that database corruption never occurs, applications must either: +<ul type=disc> +<li>Use transactions and logging with automatic recovery. +<li>Use logging and application-specific recovery. +<li>Edit a copy of the database, and, once all applications +using the database have successfully called <a href="../../api_c/db_close.html">DB->close</a>, use +system operations (e.g., the POSIX rename system call) to atomically +replace the original database with the updated copy. +</ul> +<table><tr><td><br></td><td width="1%"><a href="../../ref/am/delete.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../ref/toc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/am/stat.html"><img src="../../images/next.gif" alt="Next"></a> +</td></tr></table> +<p><font size=1><a href="http://www.sleepycat.com">Copyright Sleepycat Software</a></font> +</body> +</html> diff --git a/db/docs/ref/am/upgrade.html b/db/docs/ref/am/upgrade.html new file mode 100644 index 000000000..21fa87a1e --- /dev/null +++ b/db/docs/ref/am/upgrade.html @@ -0,0 +1,50 @@ +<!--$Id: upgrade.so,v 10.14 2000/12/21 18:37:08 bostic Exp $--> +<!--Copyright 1997, 1998, 1999, 2000 by Sleepycat Software, Inc.--> +<!--All rights reserved.--> +<html> +<head> +<title>Berkeley DB Reference Guide: Upgrading databases</title> +<meta name="description" content="Berkeley DB: An embedded database programmatic toolkit."> +<meta name="keywords" content="embedded,database,programmatic,toolkit,b+tree,btree,hash,hashing,transaction,transactions,locking,logging,access method,access methods,java,C,C++"> +</head> +<body bgcolor=white> + <a name="2"><!--meow--></a> +<table><tr valign=top> +<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Access Method Operations</dl></h3></td> +<td width="1%"><a href="../../ref/am/opensub.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../ref/toc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/am/get.html"><img src="../../images/next.gif" alt="Next"></a> +</td></tr></table> +<p> +<h1 align=center>Upgrading databases</h1> +<p>When upgrading to a new release of Berkeley DB, it may be necessary to upgrade +the on-disk format of already-created database files. <b>Berkeley DB +database upgrades are done in place, and so are potentially +destructive.</b> This means that if the system crashes during the upgrade +procedure, or if the upgrade procedure runs out of disk space, the +databases may be left in an inconsistent and unrecoverable state. To +guard against failure, the procedures outlined in +<a href="../../ref/upgrade/process.html">Upgrading Berkeley DB installations</a> +should be carefully followed. If you are not performing catastrophic +archival as part of your application upgrade process, you should at +least copy your database to archival media, verify that your archival +media is error-free and readable, and that copies of your backups are +stored off-site! +<p>The actual database upgrade is done using the <a href="../../api_c/db_upgrade.html">DB->upgrade</a> +method, or by dumping the database using the old version of the Berkeley DB +software and reloading it using the current version. +<p>After an upgrade, Berkeley DB applications must be recompiled to use the new +Berkeley DB library before they can access an upgraded database. +<b>There is no guarantee that applications compiled against +previous releases of Berkeley DB will work correctly with an upgraded database +format. Nor is there any guarantee that applications compiled against +newer releases of Berkeley DB will work correctly with the previous database +format.</b> We do guarantee that any archived database may be upgraded +using a current Berkeley DB software release and the <a href="../../api_c/db_upgrade.html">DB->upgrade</a> +method, and there is no need to step-wise upgrade the database using +intermediate releases of Berkeley DB. Sites should consider archiving +appropriate copies of their application or application sources if they +may need to access archived databases without first upgrading them. +<table><tr><td><br></td><td width="1%"><a href="../../ref/am/opensub.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../ref/toc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/am/get.html"><img src="../../images/next.gif" alt="Next"></a> +</td></tr></table> +<p><font size=1><a href="http://www.sleepycat.com">Copyright Sleepycat Software</a></font> +</body> +</html> diff --git a/db/docs/ref/am/verify.html b/db/docs/ref/am/verify.html new file mode 100644 index 000000000..5c975dd8c --- /dev/null +++ b/db/docs/ref/am/verify.html @@ -0,0 +1,50 @@ +<!--$Id: verify.so,v 10.3 2000/12/18 21:05:14 bostic Exp $--> +<!--Copyright 1997, 1998, 1999, 2000 by Sleepycat Software, Inc.--> +<!--All rights reserved.--> +<html> +<head> +<title>Berkeley DB Reference Guide: Database verification and salvage</title> +<meta name="description" content="Berkeley DB: An embedded database programmatic toolkit."> +<meta name="keywords" content="embedded,database,programmatic,toolkit,b+tree,btree,hash,hashing,transaction,transactions,locking,logging,access method,access methods,java,C,C++"> +</head> +<body bgcolor=white> + <a name="2"><!--meow--></a> <a name="3"><!--meow--></a> <a name="4"><!--meow--></a> +<table><tr valign=top> +<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Access Methods</dl></h3></td> +<td width="1%"><a href="../../ref/am/partial.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../ref/toc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/am/error.html"><img src="../../images/next.gif" alt="Next"></a> +</td></tr></table> +<p> +<h1 align=center>Database verification and salvage</h1> +<p>The <a href="../../api_c/db_verify.html">DB->verify</a> method is the standard interface for verifying +that a file, and any databases it may contain, are uncorrupted. In +addition, the method may optionally be called with a file stream +argument to which all key/data pairs found in the database are output. +There are two modes for finding key/data pairs to be output: +<p><ol> +<p><li>If the <a href="../../api_c/db_verify.html#DB_SALVAGE">DB_SALVAGE</a> flag is specified, the key/data pairs in the +database are output. When run in this mode, the database is assumed to +be largely uncorrupted. For example, the <a href="../../api_c/db_verify.html">DB->verify</a> method will +search for pages that are no longer linked into the database, and will +output key/data pairs from such pages. However, key/data items that +have been marked as deleted in the database will not be output, as the +page structures are generally trusted in this mode. +<p><li>If both the <a href="../../api_c/db_verify.html#DB_SALVAGE">DB_SALVAGE</a> and <a href="../../api_c/db_verify.html#DB_AGGRESSIVE">DB_AGGRESSIVE</a> flags are +specified, all possible key/data pairs are output. When run in this mode, +the database is assumed to be seriously corrupted. For example, key/data +pairs that have been deleted will re-appear in the output. In addition, +because pages may have been subsequently re-used and modified during +normal database operations after the key/data pairs were deleted, it is +not uncommon for apparently corrupted key/data pairs to be output in this +mode, even when there is no corruption in the underlying database. The +output will almost always have to be edited by hand or other means before +the data is ready for re-load into another database. We recommend that +<a href="../../api_c/db_verify.html#DB_SALVAGE">DB_SALVAGE</a> be tried first, and <a href="../../api_c/db_verify.html#DB_AGGRESSIVE">DB_AGGRESSIVE</a> only tried +if the output from that first attempt is obviously missing data items or +the data is sufficiently valuable that human review of the output is +preferable to any kind of data loss. +</ol> +<table><tr><td><br></td><td width="1%"><a href="../../ref/am/partial.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../ref/toc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/am/error.html"><img src="../../images/next.gif" alt="Next"></a> +</td></tr></table> +<p><font size=1><a href="http://www.sleepycat.com">Copyright Sleepycat Software</a></font> +</body> +</html> |