diff options
Diffstat (limited to 'libdb/docs/ref')
351 files changed, 0 insertions, 51016 deletions
diff --git a/libdb/docs/ref/am/close.html b/libdb/docs/ref/am/close.html deleted file mode 100644 index 0554abec5..000000000 --- a/libdb/docs/ref/am/close.html +++ /dev/null @@ -1,44 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Database close</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Access Methods</dl></h3></td> -<td align=right><a href="../../ref/am/sync.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/am/second.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Database close</h1> -<p>The <a href="../../api_c/db_close.html">DB->close</a> method 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: -<p><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 (for example, the POSIX rename system call) to -atomically replace the original database with the updated copy. -</ul> -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/am/sync.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/am/second.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/libdb/docs/ref/am/count.html b/libdb/docs/ref/am/count.html deleted file mode 100644 index 91d5cf773..000000000 --- a/libdb/docs/ref/am/count.html +++ /dev/null @@ -1,29 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Access Methods</dl></h3></td> -<td align=right><a href="../../ref/am/join.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.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 refer to 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 width="100%"><tr><td><br></td><td align=right><a href="../../ref/am/join.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.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/libdb/docs/ref/am/curclose.html b/libdb/docs/ref/am/curclose.html deleted file mode 100644 index ff7cd2f13..000000000 --- a/libdb/docs/ref/am/curclose.html +++ /dev/null @@ -1,29 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Cursor close</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Access Methods</dl></h3></td> -<td align=right><a href="../../ref/am/count.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/am_misc/align.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Cursor close</h1> -<p>The <a href="../../api_c/dbc_close.html">DBcursor->c_close</a> method 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 width="100%"><tr><td><br></td><td align=right><a href="../../ref/am/count.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/am_misc/align.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/libdb/docs/ref/am/curdel.html b/libdb/docs/ref/am/curdel.html deleted file mode 100644 index 102e42db9..000000000 --- a/libdb/docs/ref/am/curdel.html +++ /dev/null @@ -1,27 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Access Methods</dl></h3></td> -<td align=right><a href="../../ref/am/curput.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.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> method 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> method deletes the record -to which the cursor currently refers. In all cases, the cursor position -is unchanged after a delete. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/am/curput.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.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/libdb/docs/ref/am/curdup.html b/libdb/docs/ref/am/curdup.html deleted file mode 100644 index e88790d89..000000000 --- a/libdb/docs/ref/am/curdup.html +++ /dev/null @@ -1,35 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Access Methods</dl></h3></td> -<td align=right><a href="../../ref/am/curdel.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.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 (for example, 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> method 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 width="100%"><tr><td><br></td><td align=right><a href="../../ref/am/curdel.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.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/libdb/docs/ref/am/curget.html b/libdb/docs/ref/am/curget.html deleted file mode 100644 index 374d74745..000000000 --- a/libdb/docs/ref/am/curget.html +++ /dev/null @@ -1,135 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Access Methods</dl></h3></td> -<td align=right><a href="../../ref/am/cursor.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.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> method 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> method 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 to which the cursor currently refers. -</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. -<p><dt><a href="../../api_c/db_get.html#DB_GET_BOTH_RANGE">DB_GET_BOTH_RANGE</a><dd>Return the smallest record in the database greater than or equal to the -supplied key and data items. -</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 to which the cursor refers. -</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. -<p>The following is a code example showing a cursor walking through a -database and displaying the records it contains to the standard -output: -<p><blockquote><pre>int -display(database) - char *database; -{ - DB *dbp; - DBC *dbcp; - DBT key, data; - int close_db, close_dbc, ret; -<p> - close_db = close_dbc = 0; -<p> - /* Open the database. */ - if ((ret = db_create(&dbp, NULL, 0)) != 0) { - fprintf(stderr, - "%s: db_create: %s\n", progname, db_strerror(ret)); - return (1); - } -<p> - /* Turn on additional error output. */ - dbp->set_errfile(dbp, stderr); - dbp->set_errpfx(dbp, progname); -<p> - /* Open the database. */ - if ((ret = - dbp->open(dbp, NULL, database, NULL, DB_UNKNOWN, DB_RDONLY, 0)) != 0) { - dbp->err(dbp, ret, "%s: DB->open", database); - goto err; - } -<p> - /* Acquire a cursor for the database. */ - if ((ret = dbp->cursor(dbp, NULL, &dbcp, 0)) != 0) { - dbp->err(dbp, ret, "DB->cursor"); - goto err; - } -<p> - /* Initialize the key/data return pair. */ - memset(&key, 0, sizeof(key)); - memset(&data, 0, sizeof(data)); -<p> - /* Walk through the database and print out the key/data pairs. */ - while ((ret = dbcp->c_get(dbcp, &key, &data, DB_NEXT)) == 0) - printf("%.*s : %.*s\n", - (int)key.size, (char *)key.data, - (int)data.size, (char *)data.data); - if (ret != DB_NOTFOUND) { - dbp->err(dbp, ret, "DBcursor->get"); - goto err; - } -<p> -err: if (close_dbc && (ret = dbcp->c_close(dbcp)) != 0) - dbp->err(dbp, ret, "DBcursor->close"); - if (close_db && (ret = dbp->close(dbp, 0)) != 0) - fprintf(stderr, - "%s: DB->close: %s\n", progname, db_strerror(ret)); - return (0); -}</pre></blockquote> -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/am/cursor.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.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/libdb/docs/ref/am/curput.html b/libdb/docs/ref/am/curput.html deleted file mode 100644 index d96a3e5db..000000000 --- a/libdb/docs/ref/am/curput.html +++ /dev/null @@ -1,91 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Access Methods</dl></h3></td> -<td align=right><a href="../../ref/am/curget.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.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> method 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 to which the cursor -refers. -<p><dt><a href="../../api_c/dbc_put.html#DB_BEFORE">DB_BEFORE</a><dd>Create a new record, immediately before the record to which the cursor -refers. -<p><dt><a href="../../api_c/dbc_get.html#DB_CURRENT">DB_CURRENT</a><dd>Replace the data part of the record to which the cursor refers. -<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. -<p>The following is a code example showing a cursor storing two data items -in a database that supports duplicate data items: -<p><blockquote><pre>int -store(dbp) - DB *dbp; -{ - DBC *dbcp; - DBT key, data; - int ret; -<p> - /* - * The DB handle for a Btree database supporting duplicate data - * items is the argument; acquire a cursor for the database. - */ - if ((ret = dbp->cursor(dbp, NULL, &dbcp, 0)) != 0) { - dbp->err(dbp, ret, "DB->cursor"); - goto err; - } -<p> - /* Initialize the key. */ - memset(&key, 0, sizeof(key)); - key.data = "new key"; - key.size = strlen(key.data) + 1; -<p> - /* Initialize the data to be the first of two duplicate records. */ - memset(&data, 0, sizeof(data)); - data.data = "new key's data: entry #1"; - data.size = strlen(data.data) + 1; -<p> - /* Store the first of the two duplicate records. */ - if ((ret = dbcp->c_put(dbcp, &key, &data, DB_KEYFIRST)) != 0) - dbp->err(dbp, ret, "DB->cursor"); -<p> - /* Initialize the data to be the second of two duplicate records. */ - data.data = "new key's data: entry #2"; - data.size = strlen(data.data) + 1; -<p> - /* - * Store the second of the two duplicate records. No duplicate - * record sort function has been specified, so we explicitly - * store the record as the last of the duplicate set. - */ - if ((ret = dbcp->c_put(dbcp, &key, &data, DB_KEYLAST)) != 0) - dbp->err(dbp, ret, "DB->cursor"); -<p> -err: if ((ret = dbcp->c_close(dbcp)) != 0) - dbp->err(dbp, ret, "DBcursor->close"); -<p> - return (0); -}</pre></blockquote> -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/am/curget.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.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/libdb/docs/ref/am/cursor.html b/libdb/docs/ref/am/cursor.html deleted file mode 100644 index 89b3035a3..000000000 --- a/libdb/docs/ref/am/cursor.html +++ /dev/null @@ -1,50 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Cursor 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> -<a name="2"><!--meow--></a> -<table width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Access Methods</dl></h3></td> -<td align=right><a href="../../ref/am/second.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.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>Cursor operations</h1> -<p>A database cursor refers 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> method 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, records may be retrieved (<a href="../../api_c/dbc_get.html">DBcursor->c_get</a>), -stored (<a href="../../api_c/dbc_put.html">DBcursor->c_put</a>), and deleted (<a href="../../api_c/dbc_del.html">DBcursor->c_del</a>). -<p>Additional operations supported by the cursor handle include duplication -(<a href="../../api_c/dbc_dup.html">DBcursor->c_dup</a>), equality join (<a href="../../api_c/db_join.html">DB->join</a>), and a count of -duplicate data items (<a href="../../api_c/dbc_count.html">DBcursor->c_count</a>). Cursors are eventually closed -using <a href="../../api_c/dbc_close.html">DBcursor->c_close</a>. -<!--$Id$--> -<p><table border=1 align=center> -<tr><th>Database Cursors and Related Methods</th><th>Description</th></tr> -<tr><td><a href="../../api_c/db_cursor.html">DB->cursor</a></td><td>Create a cursor handle</td></tr> -<tr><td><a href="../../api_c/dbc_close.html">DBcursor->c_close</a></td><td>Close a cursor</td></tr> -<tr><td><a href="../../api_c/dbc_count.html">DBcursor->c_count</a></td><td>Return count of duplicates</td></tr> -<tr><td><a href="../../api_c/dbc_del.html">DBcursor->c_del</a></td><td>Delete by cursor</td></tr> -<tr><td><a href="../../api_c/dbc_dup.html">DBcursor->c_dup</a></td><td>Duplicate a cursor</td></tr> -<tr><td><a href="../../api_c/dbc_get.html">DBcursor->c_get</a></td><td>Retrieve by cursor</td></tr> -<tr><td><a href="../../api_c/dbc_get.html">DBcursor->c_pget</a></td><td>Retrieve by cursor</td></tr> -<tr><td><a href="../../api_c/dbc_put.html">DBcursor->c_put</a></td><td>Store by cursor</td></tr> -</table> -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/am/second.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.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/libdb/docs/ref/am/delete.html b/libdb/docs/ref/am/delete.html deleted file mode 100644 index 80061cf77..000000000 --- a/libdb/docs/ref/am/delete.html +++ /dev/null @@ -1,29 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Access Methods</dl></h3></td> -<td align=right><a href="../../ref/am/put.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.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>Deleting records</h1> -<p>The <a href="../../api_c/db_del.html">DB->del</a> method 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> method will remove all of the duplicate records. To remove -individual duplicate records, you must use a Berkeley DB cursor interface. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/am/put.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.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/libdb/docs/ref/am/get.html b/libdb/docs/ref/am/get.html deleted file mode 100644 index 4be6b6de5..000000000 --- a/libdb/docs/ref/am/get.html +++ /dev/null @@ -1,40 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Access Methods</dl></h3></td> -<td align=right><a href="../../ref/am/opensub.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.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> method 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, that is, 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 width="100%"><tr><td><br></td><td align=right><a href="../../ref/am/opensub.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.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/libdb/docs/ref/am/join.html b/libdb/docs/ref/am/join.html deleted file mode 100644 index fb3022b8c..000000000 --- a/libdb/docs/ref/am/join.html +++ /dev/null @@ -1,191 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Equality 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><a name="3"><!--meow--></a><a name="4"><!--meow--></a> -<table width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Access Methods</dl></h3></td> -<td align=right><a href="../../ref/am/curdup.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.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>Equality Join</h1> -<p>Berkeley DB supports "equality" (also known as "natural"), joins on secondary -indices. An equality join is a method of retrieving data from a primary -database using criteria stored in a set of secondary indices. It -requires the data be organized as a primary database which contains the -primary key and primary data field, and a set of secondary indices. -Each of the secondary indices 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><p><table border=1> -<tr><th>Primary key:</th><th>Primary data:</th></tr> -<tr> <td align=left>apple</td> <td align=left>Convenience Store</td> </tr> -<tr> <td align=left>blueberry</td> <td align=left>Farmer's Market</td> </tr> -<tr> <td align=left>peach</td> <td align=left>Shopway</td> </tr> -<tr> <td align=left>pear</td> <td align=left>Farmer's Market</td> </tr> -<tr> <td align=left>raspberry</td> <td align=left>Shopway</td> </tr> -<tr> <td align=left>strawberry</td> <td align=left>Farmer's Market</td> </tr> -</table></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><p><table border=1> -<tr><th>Secondary key:</th><th>Secondary data:</th></tr> -<tr> <td align=left>blue</td> <td align=left>blueberry</td> </tr> -<tr> <td align=left>red</td> <td align=left>apple</td> </tr> -<tr> <td align=left>red</td> <td align=left>raspberry</td> </tr> -<tr> <td align=left>red</td> <td align=left>strawberry</td> </tr> -<tr> <td align=left>yellow</td> <td align=left>peach</td> </tr> -<tr> <td align=left>yellow</td> <td align=left>pear</td> </tr> -</table></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> method: -<p><ol> -<p><li>The actual data should be stored in the database represented by the -<a href="../../api_c/db_class.html">DB</a> object used to invoke this function. Generally, this -<a href="../../api_c/db_class.html">DB</a> object is called the <i>primary</i>. -<p><li>Secondary indices should be stored in separate databases, whose keys -are the values of the secondary indices 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 indices. -<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> method. -</ol> -<p>What the <a href="../../api_c/db_join.html">DB->join</a> method 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><p><table border=1> -<tr><th>Secondary key:</th><th>Secondary data:</th></tr> -<tr> <td align=left>expensive</td> <td align=left>blueberry</td> </tr> -<tr> <td align=left>expensive</td> <td align=left>peach</td> </tr> -<tr> <td align=left>expensive</td> <td align=left>pear</td> </tr> -<tr> <td align=left>expensive</td> <td align=left>strawberry</td> </tr> -<tr> <td align=left>inexpensive</td> <td align=left>apple</td> </tr> -<tr> <td align=left>inexpensive</td> <td align=left>pear</td> </tr> -<tr> <td align=left>inexpensive</td> <td align=left>raspberry</td> </tr> -</table></blockquote> -<p>The <a href="../../api_c/db_join.html">DB->join</a> method provides equality 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 <a href="../../api_c/db_class.html">DB</a> operations. -<p>It is also possible to do lookups based on multiple criteria in a single -operation. For example, 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 indices, 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><p><ul type=disc> -<li>key = SSN -<li>data = record containing name, address, phone number, job title -</ul> -<p><dt>lastname<dd><p><ul type=disc> -<li>key = lastname -<li>data = SSN -</ul> -<p><dt>jobs<dd><p><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 to which the handle txn refers. -<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)) != 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)) != 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 join method. This code then loops over the join cursor getting -the personnel records of each one until there are no more. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/am/curdup.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.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/libdb/docs/ref/am/open.html b/libdb/docs/ref/am/open.html deleted file mode 100644 index 1509add32..000000000 --- a/libdb/docs/ref/am/open.html +++ /dev/null @@ -1,48 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Database open</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Access Methods</dl></h3></td> -<td align=right><a href="../../ref/am/ops.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.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>Database open</h1> -<p>The <a href="../../api_c/db_open.html">DB->open</a> method 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_set_flags.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 read-only. -<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 width="100%"><tr><td><br></td><td align=right><a href="../../ref/am/ops.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.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/libdb/docs/ref/am/opensub.html b/libdb/docs/ref/am/opensub.html deleted file mode 100644 index f725307ac..000000000 --- a/libdb/docs/ref/am/opensub.html +++ /dev/null @@ -1,78 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Access Methods</dl></h3></td> -<td align=right><a href="../../ref/am/open.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.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>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 mixture of types, 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 identical to storing each -database in a separate file with the exception of some configuration -information and the likely need for locking and a shared underlying -memory pool. -<p>There are four types of configuration information which must be specified -consistently for all databases in a file, rather than differing on a -per-database basis. They are: byte order, checksum and encryption -behavior, and page size. When creating additional databases in a file, -any of these configuration values specified must be consistent with the -existing databases in the file or an error will be returned. -<p> -An additional 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. -<p>Because multiple databases in a file exist in a single physical file, -opening two databases in the same file requires locking be enabled -(unless access to the databases is known to be single-threaded, that -is, only one of the databases is ever read or written at a time). -As the locks for the two databases can only conflict during page -allocation, this additional locking is unlikely to effect performance. -<p>Also, because multiple databases in a file exist in a single physical -file, opening two databases in the same file requires the databases -share an underlying memory pool so that per-physical-file information -common between the two databases is updated correctly. -<p>In summary, applications opening multiple databases in a single file, -will almost certainly need to create a shared database environment. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/am/open.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.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/libdb/docs/ref/am/ops.html b/libdb/docs/ref/am/ops.html deleted file mode 100644 index 1a209ce4b..000000000 --- a/libdb/docs/ref/am/ops.html +++ /dev/null @@ -1,88 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Access Methods</dl></h3></td> -<td align=right><a href="../../ref/am_conf/renumber.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.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 referred to by the returned handle. -Generally, the database will be opened using <a href="../../api_c/db_open.html">DB->open</a>. If the -database is from an old release of Berkeley DB, it may need to be upgraded to -the current release before it is opened using <a href="../../api_c/db_upgrade.html">DB->upgrade</a>. -<p>Once a database has been opened, records may be retrieved (<a href="../../api_c/db_get.html">DB->get</a>), -stored (<a href="../../api_c/db_put.html">DB->put</a>), and deleted (<a href="../../api_c/db_del.html">DB->del</a>). -<p>Additional operations supported by the database handle include -statistics (<a href="../../api_c/db_stat.html">DB->stat</a>), truncation (<a href="../../api_c/db_truncate.html">DB->truncate</a>), -version upgrade (<a href="../../api_c/db_upgrade.html">DB->upgrade</a>), verification and salvage -(<a href="../../api_c/db_verify.html">DB->verify</a>), flushing to a backing file (<a href="../../api_c/db_sync.html">DB->sync</a>), -and association of secondary indices (<a href="../../api_c/db_associate.html">DB->associate</a>). Database -handles are eventually closed using <a href="../../api_c/db_close.html">DB->close</a>. -<!--$Id$--> -<p><table border=1 align=center> -<tr><th>Databases and Related Methods</th><th>Description</th></tr> -<tr><td><a href="../../api_c/db_associate.html">DB->associate</a></td><td>Associate a secondary index</td></tr> -<tr><td><a href="../../api_c/db_close.html">DB->close</a></td><td>Close a database</td></tr> -<tr><td><a href="../../api_c/db_cursor.html">DB->cursor</a></td><td>Create a cursor handle</td></tr> -<tr><td><a href="../../api_c/db_del.html">DB->del</a></td><td>Delete items from a database</td></tr> -<tr><td><a href="../../api_c/db_err.html">DB->err</a></td><td>Error message with error string</td></tr> -<tr><td><a href="../../api_c/db_err.html">DB->errx</a></td><td>Error message</td></tr> -<tr><td><a href="../../api_c/db_fd.html">DB->fd</a></td><td>Return a file descriptor from a database</td></tr> -<tr><td><a href="../../api_c/db_get.html">DB->get</a></td><td>Get items from a database</td></tr> -<tr><td><a href="../../api_c/db_get_byteswapped.html">DB->get_byteswapped</a></td><td>Return if the underlying database is in host order</td></tr> -<tr><td><a href="../../api_c/db_get_type.html">DB->get_type</a></td><td>Return the database type</td></tr> -<tr><td><a href="../../api_c/db_join.html">DB->join</a></td><td>Perform a database join on cursors</td></tr> -<tr><td><a href="../../api_c/db_key_range.html">DB->key_range</a></td><td>Return estimate of key location</td></tr> -<tr><td><a href="../../api_c/db_open.html">DB->open</a></td><td>Open a database</td></tr> -<tr><td><a href="../../api_c/db_get.html">DB->pget</a></td><td>Get items from a database</td></tr> -<tr><td><a href="../../api_c/db_put.html">DB->put</a></td><td>Store items into a database</td></tr> -<tr><td><a href="../../api_c/db_remove.html">DB->remove</a></td><td>Remove a database</td></tr> -<tr><td><a href="../../api_c/db_rename.html">DB->rename</a></td><td>Rename a database</td></tr> -<tr><td><a href="../../api_c/db_set_alloc.html">DB->set_alloc</a></td><td>Set local space allocation functions</td></tr> -<tr><td><a href="../../api_c/db_set_append_recno.html">DB->set_append_recno</a></td><td>Set record append callback</td></tr> -<tr><td><a href="../../api_c/db_set_bt_compare.html">DB->set_bt_compare</a></td><td>Set a Btree comparison function</td></tr> -<tr><td><a href="../../api_c/db_set_bt_minkey.html">DB->set_bt_minkey</a></td><td>Set the minimum number of keys per Btree page</td></tr> -<tr><td><a href="../../api_c/db_set_bt_prefix.html">DB->set_bt_prefix</a></td><td>Set a Btree prefix comparison function</td></tr> -<tr><td><a href="../../api_c/db_set_cache_priority.html">DB->set_cache_priority</a></td><td>Set the database cache priority</td></tr> -<tr><td><a href="../../api_c/db_set_cachesize.html">DB->set_cachesize</a></td><td>Set the database cache size</td></tr> -<tr><td><a href="../../api_c/db_set_dup_compare.html">DB->set_dup_compare</a></td><td>Set a duplicate comparison function</td></tr> -<tr><td><a href="../../api_c/db_set_encrypt.html">DB->set_encrypt</a></td><td>Set the database cryptographic key</td></tr> -<tr><td><a href="../../api_c/db_set_errcall.html">DB->set_errcall</a></td><td>Set error message callback</td></tr> -<tr><td><a href="../../api_c/db_set_errfile.html">DB->set_errfile</a></td><td>Set error message FILE</td></tr> -<tr><td><a href="../../api_cxx/db_set_error_stream.html">Db::set_error_stream</a></td><td>Set error message output stream</td></tr> -<tr><td><a href="../../api_c/db_set_errpfx.html">DB->set_errpfx</a></td><td>Set error message prefix</td></tr> -<tr><td><a href="../../api_c/db_set_feedback.html">DB->set_feedback</a></td><td>Set feedback callback</td></tr> -<tr><td><a href="../../api_c/db_set_flags.html">DB->set_flags</a></td><td>General database configuration</td></tr> -<tr><td><a href="../../api_c/db_set_h_ffactor.html">DB->set_h_ffactor</a></td><td>Set the Hash table density</td></tr> -<tr><td><a href="../../api_c/db_set_h_hash.html">DB->set_h_hash</a></td><td>Set a hashing function</td></tr> -<tr><td><a href="../../api_c/db_set_h_nelem.html">DB->set_h_nelem</a></td><td>Set the Hash table size</td></tr> -<tr><td><a href="../../api_c/db_set_lorder.html">DB->set_lorder</a></td><td>Set the database byte order</td></tr> -<tr><td><a href="../../api_c/db_set_pagesize.html">DB->set_pagesize</a></td><td>Set the underlying database page size</td></tr> -<tr><td><a href="../../api_c/db_set_paniccall.html">DB->set_paniccall</a></td><td>Set panic callback</td></tr> -<tr><td><a href="../../api_c/db_set_q_extentsize.html">DB->set_q_extentsize</a></td><td>Set Queue database extent size</td></tr> -<tr><td><a href="../../api_c/db_set_re_delim.html">DB->set_re_delim</a></td><td>Set the variable-length record delimiter</td></tr> -<tr><td><a href="../../api_c/db_set_re_len.html">DB->set_re_len</a></td><td>Set the fixed-length record length</td></tr> -<tr><td><a href="../../api_c/db_set_re_pad.html">DB->set_re_pad</a></td><td>Set the fixed-length record pad byte</td></tr> -<tr><td><a href="../../api_c/db_set_re_source.html">DB->set_re_source</a></td><td>Set the backing Recno text file</td></tr> -<tr><td><a href="../../api_c/db_stat.html">DB->stat</a></td><td>Return database statistics</td></tr> -<tr><td><a href="../../api_c/db_sync.html">DB->sync</a></td><td>Flush a database to stable storage</td></tr> -<tr><td><a href="../../api_c/db_truncate.html">DB->truncate</a></td><td>Empty a database</td></tr> -<tr><td><a href="../../api_c/db_upgrade.html">DB->upgrade</a></td><td>Upgrade a database</td></tr> -<tr><td><a href="../../api_c/db_verify.html">DB->verify</a></td><td>Verify/salvage a database</td></tr> -</table> -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/am_conf/renumber.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.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/libdb/docs/ref/am/put.html b/libdb/docs/ref/am/put.html deleted file mode 100644 index 689a62d75..000000000 --- a/libdb/docs/ref/am/put.html +++ /dev/null @@ -1,37 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Access Methods</dl></h3></td> -<td align=right><a href="../../ref/am/get.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.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> method 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> method 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 width="100%"><tr><td><br></td><td align=right><a href="../../ref/am/get.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.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/libdb/docs/ref/am/second.html b/libdb/docs/ref/am/second.html deleted file mode 100644 index 82edaf22c..000000000 --- a/libdb/docs/ref/am/second.html +++ /dev/null @@ -1,218 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Secondary indices</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Access Methods</dl></h3></td> -<td align=right><a href="../../ref/am/close.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.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>Secondary indices</h1> -<p>A secondary index, put simply, is a way to efficiently access records -in a database (the primary) by means of some piece of information other -than the usual (primary) key. In Berkeley DB, this index is simply another -database whose keys are these pieces of information (the secondary -keys), and whose data are the primary keys. Secondary indices can be -(and often are) created manually by the application; there is no -disadvantage, other than complexity, to doing so. However, when the -secondary key can be mechanically derived from the primary key and datum -that it points to, as is frequently the case, Berkeley DB can automatically -and transparently manage secondary indices. -<p>As an example of how secondary indices might be used, consider a -database containing a list of students at a college, each of whom has -a unique student ID number. A typical database would use the student -ID number as the key; however, one might also reasonably want to be -able to look up students by last name. To do this, one would construct -a secondary index in which the secondary key was this last name. -<p>In SQL, this would be done by executing something like the following: -<p><blockquote><pre>CREATE TABLE students(student_id CHAR(4) NOT NULL, - lastname CHAR(15), firstname CHAR(15), PRIMARY KEY(student_id)); -CREATE INDEX lname ON students(lastname);</pre></blockquote> -<p>In Berkeley DB, this would work as follows: -<pre><p><blockquote>struct student_record { - char student_id[4]; - char last_name[15]; - char first_name[15]; -}; -<p> -void -second() -{ - DB *dbp, *sdbp; - int ret; - <p> - /* Open/create primary */ - if ((ret = db_create(&dbp, dbenv, 0)) != 0) - handle_error(ret); - if ((ret = dbp->open(dbp, NULL, - "students.db", NULL, DB_BTREE, DB_CREATE, 0600)) != 0) - handle_error(ret); - <p> - /* - * Open/create secondary. Note that it supports duplicate data - * items, since last names might not be unique. - */ - if ((ret = db_create(&sdbp, dbenv, 0)) != 0) - handle_error(ret); - if ((ret = sdbp->set_flags(sdbp, DB_DUP | DB_DUPSORT)) != 0) - handle_error(ret); - if ((ret = sdbp->open(sdbp, NULL, - "lastname.db", NULL, DB_BTREE, DB_CREATE, 0600)) != 0) - handle_error(ret); - <p> - /* Associate the secondary with the primary. */ - if ((ret = dbp->associate(dbp, NULL, sdbp, getname, 0)) != 0) - handle_error(ret); -} -<p> -/* - * getname -- extracts a secondary key (the last name) from a primary - * key/data pair - */ -int -getname(dbp, pkey, pdata, skey) - DB *dbp; - const DBT *pkey, *pdata; - DBT *skey; -{ - /* - * Since the secondary key is a simple structure member of the - * record, we don't have to do anything fancy to return it. If - * we have composite keys that need to be constructed from the - * record, rather than simply pointing into it, then the user's - * function might need to allocate space and copy data. In - * this case, the DB_DBT_APPMALLOC flag should be set in the - * secondary key DBT. - */ - memset(skey, 0, sizeof(DBT)); - skey->data = ((struct student_record *)pdata->data)->last_name; - skey->size = sizeof((struct student_record *)pdata->data)->last_name; - return (0); -}</blockquote></pre> -<p>From the application's perspective, putting things into the database -works exactly as it does without a secondary index; one can simply -insert records into the primary database. In SQL one would do the -following: -<p><blockquote><pre>INSERT INTO student - VALUES ("WC42", "Churchill ", "Winston ");</pre></blockquote> -<p>and in Berkeley DB, one does: -<p><blockquote><pre>struct student_record s; -DBT data, key; -<p> -memset(&key, 0, sizeof(DBT)); -memset(&data, 0, sizeof(DBT)); -memset(&s, 0, sizeof(struct student_record)); -key.data = "WC42"; -key.size = 4; -memcpy(&s.student_id, "WC42", sizeof(s.student_id)); -memcpy(&s.last_name, "Churchill ", sizeof(s.last_name)); -memcpy(&s.first_name, "Winston ", sizeof(s.first_name)); -data.data = &s; -data.size = sizeof(s); -if ((ret = dbp->put(dbp, txn, &key, &data, 0)) != 0) - handle_error(ret);</pre></blockquote> -<p>Internally, a record with secondary key "Churchill" is inserted into -the secondary database (in addition to the insertion of "WC42" into the -primary, of course). -<p>Deletes are similar. The SQL clause: -<p><blockquote><pre>DELETE FROM student WHERE (student_id = "WC42");</pre></blockquote> -<p>looks like: -<p><blockquote><pre>DBT key; -<p> -memset(&key, 0, sizeof(DBT)); -key.data = "WC42"; -key.size = 4; -if ((ret = dbp->del(dbp, txn, &key, 0)) != 0) - handle_error(ret);</pre></blockquote> -<p>Deletes can also be performed on the secondary index directly; a delete -done this way will delete the "real" record in the primary as well. If -the secondary supports duplicates and there are duplicate occurrences of -the secondary key, then all records with that secondary key are removed -from both the secondary index and the primary database. In -SQL: -<p><blockquote><pre>DELETE FROM lname WHERE (lastname = "Churchill ");</pre></blockquote> -<p>In Berkeley DB: -<p><blockquote><pre>DBT skey; -<p> -memset(&skey, 0, sizeof(DBT)); -skey.data = "Churchill "; -skey.size = 15; -if ((ret = sdbp->del(sdbp, txn, &skey, 0)) != 0) - handle_error(ret);</pre></blockquote> -<p>Gets on a secondary automatically return the primary datum. If -<a href="../../api_c/db_get.html">DB->pget</a> or <a href="../../api_c/dbc_get.html">DBcursor->c_pget</a> is used in lieu of <a href="../../api_c/db_get.html">DB->get</a> -or <a href="../../api_c/dbc_get.html">DBcursor->c_get</a>, the primary key is returned as well. Thus, the -equivalent of: -<p><blockquote><pre>SELECT * from lname WHERE (lastname = "Churchill ");</pre></blockquote> -<p>would be: -<p><blockquote><pre>DBT data, pkey, skey; -<p> -memset(&skey, 0, sizeof(DBT)); -memset(&pkey, 0, sizeof(DBT)); -memset(&data, 0, sizeof(DBT)); -skey.data = "Churchill "; -skey.size = 15; -if ((ret = sdbp->pget(sdbp, txn, &skey, &pkey, &data, 0)) != 0) - handle_error(ret); -/* - * Now pkey contains "WC42" and data contains Winston's record. - */</pre></blockquote> -<p>To create a secondary index to a Berkeley DB database, open the database that -is to become a secondary index normally, then pass it as the "secondary" -argument to the <a href="../../api_c/db_associate.html">DB->associate</a> interface for some primary database. -<p>After a <a href="../../api_c/db_associate.html">DB->associate</a> call is made, the secondary indices become -alternate interfaces to the primary database. All updates to the -primary will be automatically reflected in each secondary index that -has been associated with it. All get operations using the -<a href="../../api_c/db_get.html">DB->get</a> or <a href="../../api_c/dbc_get.html">DBcursor->c_get</a> interfaces on the secondary index -return the primary datum associated with the specified (or otherwise -current, in the case of cursor operations) secondary key. The -<a href="../../api_c/db_get.html">DB->pget</a> and <a href="../../api_c/dbc_get.html">DBcursor->c_pget</a> interfaces also become usable; -these behave just like <a href="../../api_c/db_get.html">DB->get</a> and <a href="../../api_c/dbc_get.html">DBcursor->c_get</a>, but return -the primary key in addition to the primary datum, for those applications -that need it as well. -<p>Cursor get operations on a secondary index perform as expected; although -the data returned will by default be those of the primary database, a -position in the secondary index is maintained normally, and records will -appear in the order determined by the secondary key and the comparison -function or other structure of the secondary database. -<p>Delete operations on a secondary index delete the item from the primary -database and all relevant secondaries, including the current one. -<p>Put operations of any kind are forbidden on secondary indices, as there -is no way to specify a primary key for a newly put item. Instead, the -application should use the <a href="../../api_c/dbc_put.html">DBcursor->c_put</a> or <a href="../../api_c/db_put.html">DB->put</a> methods -on the primary database. -<p>Any number of secondary indices may be associated with a given primary -database, up to limitations on available memory and the number of open -file descriptors. -<p>Note that although Berkeley DB guarantees that updates made using any -<a href="../../api_c/db_class.html">DB</a> handle with an associated secondary will be reflected in the -that secondary, associating each primary handle with all the appropriate -secondaries is the responsibility of the application and is not enforced -by Berkeley DB. It is generally unsafe, but not forbidden by Berkeley DB, to modify -a database that has secondary indices without having those indices open -and associated. Similarly, it is generally unsafe, but not forbidden, -to modify a secondary index directly. Applications that violate these -rules face the possibility of outdated or incorrect results if the -secondary indices are later used. -<p>If a secondary index becomes outdated for any reason, it should be -discarded using the <a href="../../api_c/db_remove.html">DB->remove</a> method and a new one created -using the <a href="../../api_c/db_associate.html">DB->associate</a> method. If a secondary index is no -longer needed, all of its handles should be closed using the -<a href="../../api_c/db_close.html">DB->close</a> method, and then the database should be removed using -a new database handle and the <a href="../../api_c/db_remove.html">DB->remove</a> method. -<p>Closing a primary database handle automatically disassociates all -secondary database handles associated with it. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/am/close.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.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/libdb/docs/ref/am/stat.html b/libdb/docs/ref/am/stat.html deleted file mode 100644 index 0ce878962..000000000 --- a/libdb/docs/ref/am/stat.html +++ /dev/null @@ -1,33 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Access Methods</dl></h3></td> -<td align=right><a href="../../ref/am/delete.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/am/truncate.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> method 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, for example, the number of key/data pairs -in the database, how the database was originally configured, and so -on. -<p>There is one flag you can set to customize the returned statistics: -<p><dl compact> -<p><dt><a href="../../api_c/db_stat.html#DB_FAST_STAT">DB_FAST_STAT</a><dd>Return only information that can be acquired without traversing the -entire database. -</dl> -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/am/delete.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/am/truncate.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/libdb/docs/ref/am/sync.html b/libdb/docs/ref/am/sync.html deleted file mode 100644 index c65efc609..000000000 --- a/libdb/docs/ref/am/sync.html +++ /dev/null @@ -1,39 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Access Methods</dl></h3></td> -<td align=right><a href="../../ref/am/verify.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.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>Flushing the database cache</h1> -<p>The <a href="../../api_c/db_sync.html">DB->sync</a> method 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: -<p><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 (for example, the POSIX rename system call) to -atomically replace the original database with the updated copy. -</ul> -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/am/verify.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.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/libdb/docs/ref/am/truncate.html b/libdb/docs/ref/am/truncate.html deleted file mode 100644 index 401562feb..000000000 --- a/libdb/docs/ref/am/truncate.html +++ /dev/null @@ -1,25 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Database truncation</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Access Methods</dl></h3></td> -<td align=right><a href="../../ref/am/stat.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.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>Database truncation</h1> -<p>The <a href="../../api_c/db_truncate.html">DB->truncate</a> method is the standard interface for emptying a -database of all records. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/am/stat.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.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/libdb/docs/ref/am/upgrade.html b/libdb/docs/ref/am/upgrade.html deleted file mode 100644 index 3d0d8e892..000000000 --- a/libdb/docs/ref/am/upgrade.html +++ /dev/null @@ -1,51 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Database upgrade</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Access Methods</dl></h3></td> -<td align=right><a href="../../ref/am/truncate.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.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>Database upgrade</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 offsite! -<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 width="100%"><tr><td><br></td><td align=right><a href="../../ref/am/truncate.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.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/libdb/docs/ref/am/verify.html b/libdb/docs/ref/am/verify.html deleted file mode 100644 index ede6efdc2..000000000 --- a/libdb/docs/ref/am/verify.html +++ /dev/null @@ -1,51 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Access Methods</dl></h3></td> -<td align=right><a href="../../ref/am/upgrade.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.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>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 reused 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 reload 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 width="100%"><tr><td><br></td><td align=right><a href="../../ref/am/upgrade.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.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/libdb/docs/ref/am_conf/bt_compare.html b/libdb/docs/ref/am_conf/bt_compare.html deleted file mode 100644 index 6f485e88f..000000000 --- a/libdb/docs/ref/am_conf/bt_compare.html +++ /dev/null @@ -1,94 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Btree comparison</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Access Methods</dl></h3></td> -<td align=right><a href="../../ref/am_conf/malloc.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/am_conf/bt_prefix.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Btree comparison</h1> -<p>The Btree data structure is a sorted, balanced tree structure storing -associated key/data pairs. By default, the sort order is lexicographical, -with shorter keys collating before longer keys. The user can specify the -sort order for the Btree by using the <a href="../../api_c/db_set_bt_compare.html">DB->set_bt_compare</a> method. -<p>Sort routines are passed pointers to keys as arguments. The keys are -represented as <a href="../../api_c/dbt_class.html">DBT</a> structures. The routine must return an integer -less than, equal to, or greater than zero if the first argument is -considered to be respectively less than, equal to, or greater than the -second argument. The only fields that the routines may examine in the -<a href="../../api_c/dbt_class.html">DBT</a> structures are <b>data</b> and <b>size</b> fields. -<p>An example routine that might be used to sort integer keys in the database -is as follows: -<p><blockquote><pre>int -compare_int(dbp, a, b) - DB *dbp; - const DBT *a, *b; -{ - int ai, bi; -<p> - /* - * Returns: - * < 0 if a < b - * = 0 if a = b - * > 0 if a > b - */ - memcpy(&ai, a->data, sizeof(int)); - memcpy(&bi, b->data, sizeof(int)); - return (ai - bi); -}</pre></blockquote> -<p>Note that the data must first be copied into memory that is appropriately -aligned, as Berkeley DB does not guarantee any kind of alignment of the -underlying data, including for comparison routines. When writing -comparison routines, remember that databases created on machines of -different architectures may have different integer byte orders, for which -your code may need to compensate. -<p>An example routine that might be used to sort keys based on the first -five bytes of the key (ignoring any subsequent bytes) is as follows: -<p><blockquote><pre>int -compare_dbt(dbp, a, b) - DB *dbp; - const DBT *a, *b; -{ - int len; - u_char *p1, *p2; -<p> - /* - * Returns: - * < 0 if a < b - * = 0 if a = b - * > 0 if a > b - */ - for (p1 = a->data, p2 = b->data, len = 5; len--; ++p1, ++p2) - if (*p1 != *p2) - return ((long)*p1 - (long)*p2); - return (0); -}</pre></blockquote> -<p>All comparison functions must cause the keys in the database to be -well-ordered. The most important implication of being well-ordered is -that the key relations must be transitive, that is, if key A is less -than key B, and key B is less than key C, then the comparison routine -must also return that key A is less than key C. In addition, comparisons -will only be able to return 0 when comparing full length keys; partial -key comparisons must always return a result less than or greater than 0. -<p>It is reasonable for a comparison function to not examine an entire key -in some applications, which implies that partial keys may be specified -to the Berkeley DB interfaces. When partial keys are specified to Berkeley DB, -interfaces which retrieve data items based on a user-specified key (for -example, <a href="../../api_c/db_get.html">DB->get</a> and <a href="../../api_c/dbc_get.html">DBcursor->c_get</a> with the <a href="../../api_c/dbc_get.html#DB_SET">DB_SET</a> -flag), will not modify the user-specified key by returning the actual -key stored in the database. The actual key can be retrieved by calling -the <a href="../../api_c/dbc_get.html">DBcursor->c_get</a> method with the <a href="../../api_c/dbc_get.html#DB_CURRENT">DB_CURRENT</a> flag. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/am_conf/malloc.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/am_conf/bt_prefix.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/libdb/docs/ref/am_conf/bt_minkey.html b/libdb/docs/ref/am_conf/bt_minkey.html deleted file mode 100644 index f52c8c1d2..000000000 --- a/libdb/docs/ref/am_conf/bt_minkey.html +++ /dev/null @@ -1,54 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Minimum keys per page</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Access Methods</dl></h3></td> -<td align=right><a href="../../ref/am_conf/bt_prefix.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/am_conf/bt_recnum.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Minimum keys per page</h1> -<p>The number of keys stored on each page affects the size of a Btree and -how it is maintained. Therefore, it also affects the retrieval and search -performance of the tree. For each Btree, Berkeley DB computes a maximum key -and data size. This size is a function of the page size and the fact that -at least two key/data pairs must fit on any Btree page. Whenever key or -data items exceed the calculated size, they are stored on overflow pages -instead of in the standard Btree leaf pages. -<p>Applications may use the <a href="../../api_c/db_set_bt_minkey.html">DB->set_bt_minkey</a> method to change the minimum -number of keys that must fit on a Btree page from two to another value. -Altering this value in turn alters the on-page maximum size, and can be -used to force key and data items which would normally be stored in the -Btree leaf pages onto overflow pages. -<p>Some data sets can benefit from this tuning. For example, consider an -application using large page sizes, with a data set almost entirely -consisting of small key and data items, but with a few large items. By -setting the minimum number of keys that must fit on a page, the -application can force the outsized items to be stored on overflow pages. -That in turn can potentially keep the tree more compact, that is, with -fewer internal levels to traverse during searches. -<p>The following calculation is similar to the one performed by the Btree -implementation. (The <b>minimum_keys</b> value is multiplied by 2 -because each key/data pair requires 2 slots on a Btree page.) -<p><blockquote><pre>maximum_size = page_size / (minimum_keys * 2)</pre></blockquote> -<p>Using this calculation, if the page size is 8KB and the default -<b>minimum_keys</b> value of 2 is used, then any key or data items -larger than 2KB will be forced to an overflow page. If an application -were to specify a <b>minimum_key</b> value of 100, then any key or data -items larger than roughly 40 bytes would be forced to overflow pages. -<p>It is important to remember that accesses to overflow pages do not perform -as well as accesses to the standard Btree leaf pages, and so setting the -value incorrectly can result in overusing overflow pages and decreasing -the application's overall performance. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/am_conf/bt_prefix.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/am_conf/bt_recnum.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/libdb/docs/ref/am_conf/bt_prefix.html b/libdb/docs/ref/am_conf/bt_prefix.html deleted file mode 100644 index 537f3eef3..000000000 --- a/libdb/docs/ref/am_conf/bt_prefix.html +++ /dev/null @@ -1,68 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Btree prefix comparison</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Access Methods</dl></h3></td> -<td align=right><a href="../../ref/am_conf/bt_compare.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/am_conf/bt_minkey.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Btree prefix comparison</h1> -<p>The Berkeley DB Btree implementation maximizes the number of keys that can be -stored on an internal page by storing only as many bytes of each key as -are necessary to distinguish it from adjacent keys. The prefix -comparison routine is what determines this minimum number of bytes (that -is, the length of the unique prefix), that must be stored. A prefix -comparison function for the Btree can be specified by calling -<a href="../../api_c/db_set_bt_prefix.html">DB->set_bt_prefix</a>. -<p>The prefix comparison routine must be compatible with the overall -comparison function of the Btree, since what distinguishes any two keys -depends entirely on the function used to compare them. This means that -if a prefix comparison routine is specified by the application, a -compatible overall comparison routine must also have been specified. -<p>Prefix comparison routines are passed pointers to keys as arguments. The -keys are represented as <a href="../../api_c/dbt_class.html">DBT</a> structures. The prefix comparison -function must return the number of bytes of the second key argument that -are necessary to determine if it is greater than the first key argument. -If the keys are equal, the length of the second key should be returned. -The only fields that the routines may examine in the <a href="../../api_c/dbt_class.html">DBT</a> -structures are <b>data</b> and <b>size</b> fields. -<p>An example prefix comparison routine follows: -<p><blockquote><pre>u_int32_t -compare_prefix(dbp, a, b) - DB *dbp; - const DBT *a, *b; -{ - size_t cnt, len; - u_int8_t *p1, *p2; -<p> - cnt = 1; - len = a->size > b->size ? b->size : a->size; - for (p1 = - a->data, p2 = b->data; len--; ++p1, ++p2, ++cnt) - if (*p1 != *p2) - return (cnt); - /* - * They match up to the smaller of the two sizes. - * Collate the longer after the shorter. - */ - if (a->size < b->size) - return (a->size + 1); - if (b->size < a->size) - return (b->size + 1); - return (b->size); -}</pre></blockquote> -<p>The usefulness of this functionality is data-dependent, but in some data -sets can produce significantly reduced tree sizes and faster search times. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/am_conf/bt_compare.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/am_conf/bt_minkey.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/libdb/docs/ref/am_conf/bt_recnum.html b/libdb/docs/ref/am_conf/bt_recnum.html deleted file mode 100644 index d9bbedd5a..000000000 --- a/libdb/docs/ref/am_conf/bt_recnum.html +++ /dev/null @@ -1,106 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Retrieving Btree records by logical record number</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Access Methods</dl></h3></td> -<td align=right><a href="../../ref/am_conf/bt_minkey.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/am_conf/h_ffactor.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Retrieving Btree records by logical record number</h1> -<p>The Btree access method optionally supports retrieval by logical record -numbers. To configure a Btree to support record numbers, call the -<a href="../../api_c/db_set_flags.html">DB->set_flags</a> method with the <a href="../../api_c/db_set_flags.html#DB_RECNUM">DB_RECNUM</a> flag. -<p>Configuring a Btree for record numbers should not be done lightly. -While often useful, it may significantly slow down the speed at which -items can be stored into the database, and can severely impact -application throughput. Generally it should be avoided in trees with -a need for high write concurrency. -<p>To retrieve by record number, use the <a href="../../api_c/db_get.html#DB_SET_RECNO">DB_SET_RECNO</a> flag to the -<a href="../../api_c/db_get.html">DB->get</a> and <a href="../../api_c/dbc_get.html">DBcursor->c_get</a> methods. The following is an example of -a routine that displays the data item for a Btree database created with -the <a href="../../api_c/db_set_flags.html#DB_RECNUM">DB_RECNUM</a> option. -<p><blockquote><pre>int -rec_display(dbp, recno) - DB *dbp; - db_recno_t recno; -{ - DBT key, data; - int ret; -<p> - memset(&key, 0, sizeof(key)); - key.data = &recno; - key.size = sizeof(recno); - memset(&data, 0, sizeof(data)); -<p> - if ((ret = dbp->get(dbp, NULL, &key, &data, DB_SET_RECNO)) != 0) - return (ret); - printf("data for %lu: %.*s\n", - (u_long)recno, (int)data.size, (char *)data.data); - return (0); -}</pre></blockquote> -<p>To determine a key's record number, use the <a href="../../api_c/dbc_get.html#DB_GET_RECNO">DB_GET_RECNO</a> flag -to the <a href="../../api_c/dbc_get.html">DBcursor->c_get</a> method. The following is an example of a routine that -displays the record number associated with a specific key. -<p><blockquote><pre>int -recno_display(dbp, keyvalue) - DB *dbp; - char *keyvalue; -{ - DBC *dbcp; - DBT key, data; - db_recno_t recno; - int ret, t_ret; -<p> - /* Acquire a cursor for the database. */ - if ((ret = dbp->cursor(dbp, NULL, &dbcp, 0)) != 0) { - dbp->err(dbp, ret, "DB->cursor"); - goto err; - } -<p> - /* Position the cursor. */ - memset(&key, 0, sizeof(key)); - key.data = keyvalue; - key.size = strlen(keyvalue); - memset(&data, 0, sizeof(data)); - if ((ret = dbcp->c_get(dbcp, &key, &data, DB_SET)) != 0) { - dbp->err(dbp, ret, "DBC->c_get(DB_SET): %s", keyvalue); - goto err; - } -<p> - /* - * Request the record number, and store it into appropriately - * sized and aligned local memory. - */ - memset(&data, 0, sizeof(data)); - data.data = &recno; - data.ulen = sizeof(recno); - data.flags = DB_DBT_USERMEM; - if ((ret = dbcp->c_get(dbcp, &key, &data, DB_GET_RECNO)) != 0) { - dbp->err(dbp, ret, "DBC->c_get(DB_GET_RECNO)"); - goto err; - } -<p> - printf("key for requested key was %lu\n", (u_long)recno); -<p> -err: /* Close the cursor. */ - if ((t_ret = dbcp->c_close(dbcp)) != 0) { - if (ret == 0) - ret = t_ret; - dbp->err(dbp, ret, "DBC->close"); - } - return (ret); -}</pre></blockquote> -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/am_conf/bt_minkey.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/am_conf/h_ffactor.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/libdb/docs/ref/am_conf/byteorder.html b/libdb/docs/ref/am_conf/byteorder.html deleted file mode 100644 index b7dd1f51e..000000000 --- a/libdb/docs/ref/am_conf/byteorder.html +++ /dev/null @@ -1,38 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Selecting a byte order</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Access Methods</dl></h3></td> -<td align=right><a href="../../ref/am_conf/cachesize.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/am_conf/dup.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Selecting a byte order</h1> -<p>Database files created by Berkeley DB can be created in either little- or -big-endian formats. The byte order used for the underlying database -is specified by calling the <a href="../../api_c/db_set_lorder.html">DB->set_lorder</a> method. If no order -is selected, the native format of the machine on which the database is -created will be used. -<p>Berkeley DB databases are architecture independent, and any format database can -be used on a machine with a different native format. In this case, as -each page that is read into or written from the cache must be converted -to or from the host format, and databases with non-native formats will -incur a performance penalty for the run-time conversion. -<p><b>It is important to note that the Berkeley DB access methods do no data -conversion for application specified data. Key/data pairs written on a -little-endian format architecture will be returned to the application -exactly as they were written when retrieved on a big-endian format -architecture.</b> -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/am_conf/cachesize.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/am_conf/dup.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/libdb/docs/ref/am_conf/cachesize.html b/libdb/docs/ref/am_conf/cachesize.html deleted file mode 100644 index 8264f9d9d..000000000 --- a/libdb/docs/ref/am_conf/cachesize.html +++ /dev/null @@ -1,86 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Selecting a cache size</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Access Methods</dl></h3></td> -<td align=right><a href="../../ref/am_conf/pagesize.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/am_conf/byteorder.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Selecting a cache size</h1> -<p>The size of the cache used for the underlying database can be specified -by calling the <a href="../../api_c/db_set_cachesize.html">DB->set_cachesize</a> method. -Choosing a cache size is, unfortunately, an art. Your cache must be at -least large enough for your working set plus some overlap for unexpected -situations. -<p>When using the Btree access method, you must have a cache big enough for -the minimum working set for a single access. This will include a root -page, one or more internal pages (depending on the depth of your tree), -and a leaf page. If your cache is any smaller than that, each new page -will force out the least-recently-used page, and Berkeley DB will re-read the -root page of the tree anew on each database request. -<p>If your keys are of moderate size (a few tens of bytes) and your pages -are on the order of 4K to 8K, most Btree applications will be only -three levels. For example, using 20 byte keys with 20 bytes of data -associated with each key, a 8KB page can hold roughly 400 keys (or 200 -key/data pairs), so a fully populated three-level Btree will hold 32 -million key/data pairs, and a tree with only a 50% page-fill factor will -still hold 16 million key/data pairs. We rarely expect trees to exceed -five levels, although Berkeley DB will support trees up to 255 levels. -<p>The rule-of-thumb is that cache is good, and more cache is better. -Generally, applications benefit from increasing the cache size up to a -point, at which the performance will stop improving as the cache size -increases. When this point is reached, one of two things have happened: -either the cache is large enough that the application is almost never -having to retrieve information from disk, or, your application is doing -truly random accesses, and therefore increasing size of the cache doesn't -significantly increase the odds of finding the next requested information -in the cache. The latter is fairly rare -- almost all applications show -some form of locality of reference. -<p>That said, it is important not to increase your cache size beyond the -capabilities of your system, as that will result in reduced performance. -Under many operating systems, tying down enough virtual memory will cause -your memory and potentially your program to be swapped. This is -especially likely on systems without unified OS buffer caches and virtual -memory spaces, as the buffer cache was allocated at boot time and so -cannot be adjusted based on application requests for large amounts of -virtual memory. -<p>For example, even if accesses are truly random within a Btree, your -access pattern will favor internal pages to leaf pages, so your cache -should be large enough to hold all internal pages. In the steady state, -this requires at most one I/O per operation to retrieve the appropriate -leaf page. -<p>You can use the <a href="../../utility/db_stat.html">db_stat</a> utility to monitor the effectiveness of -your cache. The following output is excerpted from the output of that -utility's <b>-m</b> option: -<p><blockquote><pre>prompt: db_stat -m -131072 Cache size (128K). -4273 Requested pages found in the cache (97%). -134 Requested pages not found in the cache. -18 Pages created in the cache. -116 Pages read into the cache. -93 Pages written from the cache to the backing file. -5 Clean pages forced from the cache. -13 Dirty pages forced from the cache. -0 Dirty buffers written by trickle-sync thread. -130 Current clean buffer count. -4 Current dirty buffer count. -</pre></blockquote> -<p>The statistics for this cache say that there have been 4,273 requests of -the cache, and only 116 of those requests required an I/O from disk. This -means that the cache is working well, yielding a 97% cache hit rate. The -<a href="../../utility/db_stat.html">db_stat</a> utility will present these statistics both for the cache -as a whole and for each file within the cache separately. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/am_conf/pagesize.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/am_conf/byteorder.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/libdb/docs/ref/am_conf/dup.html b/libdb/docs/ref/am_conf/dup.html deleted file mode 100644 index d349c4d36..000000000 --- a/libdb/docs/ref/am_conf/dup.html +++ /dev/null @@ -1,76 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Duplicate data items</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Access Methods</dl></h3></td> -<td align=right><a href="../../ref/am_conf/byteorder.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/am_conf/malloc.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Duplicate data items</h1> -<p>The Btree and Hash access methods support the creation of multiple data -items for a single key item. By default, multiple data items are not -permitted, and each database store operation will overwrite any previous -data item for that key. To configure Berkeley DB for duplicate data items, -call the <a href="../../api_c/db_set_flags.html">DB->set_flags</a> method with the <a href="../../api_c/db_set_flags.html#DB_DUP">DB_DUP</a> flag. Only one -copy of the key will be stored for each set of duplicate data items. -If the Btree access method comparison routine returns that two keys -compare equally, it is undefined which of the two keys will be stored -and returned from future database operations. -<p>By default, Berkeley DB stores duplicates in the order in which they were added, -that is, each new duplicate data item will be stored after any already -existing data items. This default behavior can be overridden by using -the <a href="../../api_c/dbc_put.html">DBcursor->c_put</a> method and one of the <a href="../../api_c/dbc_put.html#DB_AFTER">DB_AFTER</a>, <a href="../../api_c/dbc_put.html#DB_BEFORE">DB_BEFORE</a> -<a href="../../api_c/dbc_put.html#DB_KEYFIRST">DB_KEYFIRST</a> or <a href="../../api_c/dbc_put.html#DB_KEYLAST">DB_KEYLAST</a> flags. Alternatively, Berkeley DB -may be configured to sort duplicate data items. -<p>When stepping through the database sequentially, duplicate data items will -be returned individually, as a key/data pair, where the key item only -changes after the last duplicate data item has been returned. For this -reason, duplicate data items cannot be accessed using the -<a href="../../api_c/db_get.html">DB->get</a> method, as it always returns the first of the duplicate data -items. Duplicate data items should be retrieved using the Berkeley DB cursor -interface, <a href="../../api_c/dbc_get.html">DBcursor->c_get</a>. -<p>There is an interface flag that permits applications to request the -following data item only if it <b>is</b> a duplicate data item of the -current entry, see <a href="../../api_c/dbc_get.html#DB_NEXT_DUP">DB_NEXT_DUP</a> for more information. There is an -interface flag that permits applications to request the following data -item only if it <b>is not</b> a duplicate data item of the current -entry, see <a href="../../api_c/dbc_get.html#DB_NEXT_NODUP">DB_NEXT_NODUP</a> and <a href="../../api_c/dbc_get.html#DB_PREV_NODUP">DB_PREV_NODUP</a> for more -information. -<p>It is also possible to maintain duplicate records in sorted order. Sorting -duplicates will significantly increase performance when searching them -and performing equality joins, common operations when using secondary -indices. To configure Berkeley DB to sort duplicate data items, the application -must call the <a href="../../api_c/db_set_flags.html">DB->set_flags</a> method with the <a href="../../api_c/db_set_flags.html#DB_DUPSORT">DB_DUPSORT</a> flag (in -addition to the <a href="../../api_c/db_set_flags.html#DB_DUP">DB_DUP</a> flag). In addition, a custom sorting -function may be specified using the <a href="../../api_c/db_set_dup_compare.html">DB->set_dup_compare</a> method. If the -<a href="../../api_c/db_set_flags.html#DB_DUPSORT">DB_DUPSORT</a> flag is given, but no comparison routine is specified, -then Berkeley DB defaults to the same lexicographical sorting used for Btree -keys, with shorter items collating before longer items. -<p>If the duplicate data items are unsorted, applications may store identical -duplicate data items, or, for those that just like the way it sounds, -<i>duplicate duplicates</i>. -<p><b>In this release it is an error to attempt to store identical -duplicate data items when duplicates are being stored in a sorted order.</b> -This restriction is expected to be lifted in a future release. There is -an interface flag that permits applications to disallow storing duplicate -data items when the database has been configured for sorted duplicates, -see <a href="../../api_c/db_put.html#DB_NODUPDATA">DB_NODUPDATA</a> for more information. Applications not wanting -to permit duplicate duplicates in databases configured for sorted -duplicates should begin using the <a href="../../api_c/db_put.html#DB_NODUPDATA">DB_NODUPDATA</a> flag immediately. -<p>For further information on how searching and insertion behaves in the -presence of duplicates (sorted or not), see the <a href="../../api_c/db_get.html">DB->get</a>, -<a href="../../api_c/db_put.html">DB->put</a>, <a href="../../api_c/dbc_get.html">DBcursor->c_get</a> and <a href="../../api_c/dbc_put.html">DBcursor->c_put</a> documentation. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/am_conf/byteorder.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/am_conf/malloc.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/libdb/docs/ref/am_conf/extentsize.html b/libdb/docs/ref/am_conf/extentsize.html deleted file mode 100644 index 78bdbf564..000000000 --- a/libdb/docs/ref/am_conf/extentsize.html +++ /dev/null @@ -1,44 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Selecting a Queue extent size</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Access Methods</dl></h3></td> -<td align=right><a href="../../ref/am_conf/recno.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/am_conf/re_source.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Selecting a Queue extent size</h1> -<p>In Queue databases, records are allocated sequentially and directly -mapped to an offset within the file storage for the database. As -records are deleted from the Queue, pages will become empty and will -not be reused in normal queue operations. To facilitate the reclamation -of disk space a Queue may be partitioned into extents. Each extent is -kept in a separate physical file. -<p>Extent files are automatically created as needed and marked for deletion -when the head of the queue moves off the extent. The extent will not -be deleted until all processes close the extent. In addition, Berkeley DB -caches a small number of extents that have been recently used; this may -delay when an extent will be deleted. The number of extents left open -depends on queue activity. -<p>The extent size specifies the number of pages that make up each extent. -By default, if no extent size is specified, the Queue resides in a -single file and disk space is not reclaimed. In choosing an extent size -there is a tradeoff between the amount of disk space used and the -overhead of creating and deleting files. If the extent size is too -small, the system will pay a performance penalty, creating and deleting -files frequently. In addition, if the active part of the queue spans -many files, all those files will need to be open at the same time, -consuming system and process file resources. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/am_conf/recno.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/am_conf/re_source.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/libdb/docs/ref/am_conf/h_ffactor.html b/libdb/docs/ref/am_conf/h_ffactor.html deleted file mode 100644 index 4acbd8cf5..000000000 --- a/libdb/docs/ref/am_conf/h_ffactor.html +++ /dev/null @@ -1,32 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Page fill factor</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Access Methods</dl></h3></td> -<td align=right><a href="../../ref/am_conf/bt_recnum.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/am_conf/h_hash.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Page fill factor</h1> -<p>The density, or page fill factor, is an approximation of the number of -keys allowed to accumulate in any one bucket, determining when the hash -table grows or shrinks. If you know the average sizes of the keys and -data in your data set, setting the fill factor can enhance performance. -A reasonable rule to use to compute fill factor is: -<p><blockquote><pre>(pagesize - 32) / (average_key_size + average_data_size + 8)</pre></blockquote> -<p>The desired density within the hash table can be specified by calling -the <a href="../../api_c/db_set_h_ffactor.html">DB->set_h_ffactor</a> method. If no density is specified, one will -be selected dynamically as pages are filled. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/am_conf/bt_recnum.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/am_conf/h_hash.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/libdb/docs/ref/am_conf/h_hash.html b/libdb/docs/ref/am_conf/h_hash.html deleted file mode 100644 index d78392377..000000000 --- a/libdb/docs/ref/am_conf/h_hash.html +++ /dev/null @@ -1,40 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Specifying a database hash</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Access Methods</dl></h3></td> -<td align=right><a href="../../ref/am_conf/h_ffactor.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/am_conf/h_nelem.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Specifying a database hash</h1> -<p>The database hash determines in which bucket a particular key will reside. -The goal of hashing keys is to distribute keys equally across the database -pages, therefore it is important that the hash function work well with -the specified keys so that the resulting bucket usage is relatively -uniform. A hash function that does not work well can effectively turn -into a sequential list. -<p>No hash performs equally well on all possible data sets. It is possible -that applications may find that the default hash function performs poorly -with a particular set of keys. The distribution resulting from the hash -function can be checked using <a href="../../utility/db_stat.html">db_stat</a> utility. By comparing the -number of hash buckets and the number of keys, one can decide if the entries -are hashing in a well-distributed manner. -<p>The hash function for the hash table can be specified by calling the -<a href="../../api_c/db_set_h_hash.html">DB->set_h_hash</a> method. If no hash function is specified, a default -function will be used. Any application-specified hash function must -take a reference to a <a href="../../api_c/db_class.html">DB</a> object, a pointer to a byte string and -its length, as arguments and return an unsigned, 32-bit hash value. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/am_conf/h_ffactor.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/am_conf/h_nelem.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/libdb/docs/ref/am_conf/h_nelem.html b/libdb/docs/ref/am_conf/h_nelem.html deleted file mode 100644 index a95bb447e..000000000 --- a/libdb/docs/ref/am_conf/h_nelem.html +++ /dev/null @@ -1,33 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Hash table size</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Access Methods</dl></h3></td> -<td align=right><a href="../../ref/am_conf/h_hash.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/am_conf/recno.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Hash table size</h1> -<p>When setting up the hash database, knowing the expected number of elements -that will be stored in the hash table is useful. This value can be used -by the Hash access method implementation to more accurately construct the -necessary number of buckets that the database will eventually require. -<p>The anticipated number of elements in the hash table can be specified by -calling the <a href="../../api_c/db_set_h_nelem.html">DB->set_h_nelem</a> method. If not specified, or set too low, -hash tables will expand gracefully as keys are entered, although a slight -performance degradation may be noticed. In order for the estimated number -of elements to be a useful value to Berkeley DB, the <a href="../../api_c/db_set_h_ffactor.html">DB->set_h_ffactor</a> method -must also be called to set the page fill factor. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/am_conf/h_hash.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/am_conf/recno.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/libdb/docs/ref/am_conf/intro.html b/libdb/docs/ref/am_conf/intro.html deleted file mode 100644 index 4636b77e4..000000000 --- a/libdb/docs/ref/am_conf/intro.html +++ /dev/null @@ -1,46 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: What are the available access methods?</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Access Methods</dl></h3></td> -<td align=right><a href="../../ref/simple_tut/close.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/am_conf/select.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>What are the available access methods?</h1> -<p>Berkeley DB currently offers four access methods: Btree, Hash, Queue and Recno. -<h3>Btree</h3> -<p>The Btree access method is an implementation of a sorted, balanced tree -structure. Searches, insertions, and deletions in the tree all take O(log -base_b N) time, where base_b is the average number of keys per page, and -N is the total number of keys stored. Often, inserting ordered data into -Btree implementations results in pages that are only half-full. Berkeley DB -makes ordered (or inverse ordered) insertion the best case, resulting in -nearly full-page space utilization. -<h3>Hash</h3> -<p>The Hash access method data structure is an implementation of Extended -Linear Hashing, as described in "Linear Hashing: A New Tool for File and -Table Addressing", Witold Litwin, <i>Proceedings of the 6th -International Conference on Very Large Databases (VLDB)</i>, 1980. -<h3>Queue</h3> -<p>The Queue access method stores fixed-length records with logical record -numbers as keys. It is designed for fast inserts at the tail and has a -special cursor consume operation that deletes and returns a record from -the head of the queue. The Queue access method uses record level locking. -<h3>Recno</h3> -<p>The Recno access method stores both fixed and variable-length records with -logical record numbers as keys, optionally backed by a flat text (byte -stream) file. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/simple_tut/close.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/am_conf/select.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/libdb/docs/ref/am_conf/logrec.html b/libdb/docs/ref/am_conf/logrec.html deleted file mode 100644 index a19e96145..000000000 --- a/libdb/docs/ref/am_conf/logrec.html +++ /dev/null @@ -1,123 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Logical record numbers</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Access Methods</dl></h3></td> -<td align=right><a href="../../ref/am_conf/select.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/am_conf/pagesize.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Logical record numbers</h1> -<p>The Berkeley DB Btree, Queue and Recno access methods can operate on logical -record numbers. Record numbers are 1-based, not 0-based, that is, the -first record in a database is record number 1. -<p>In all cases for the Queue and Recno access methods, and when calling -the Btree access method using the <a href="../../api_c/db_get.html">DB->get</a> and <a href="../../api_c/dbc_get.html">DBcursor->c_get</a> methods -with the <a href="../../api_c/db_get.html#DB_SET_RECNO">DB_SET_RECNO</a> flag specified, the <b>data</b> field of -the key <a href="../../api_c/dbt_class.html">DBT</a> must be a pointer to a memory location of type -<b>db_recno_t</b>, as typedef'd in the standard Berkeley DB include file. -The <b>size</b> field of the key <a href="../../api_c/dbt_class.html">DBT</a> should be the size of that -type (for example, "sizeof(db_recno_t)" in the C programming language). -The <b>db_recno_t</b> type is a 32-bit unsigned type, which limits the -number of logical records in a Queue or Recno database, and the maximum -logical record which may be directly retrieved from a Btree database, -to 4,294,967,295. -<p>Record numbers in Queue databases wrap around. When the tail of the -queue reaches the maximum record number, the next record appended will -be given record number 1. If the head of the queue ever catches up to -the tail of the queue, the Berkeley DB interface will return the system error -EFBIG. -<p>Record numbers in Recno databases can be configured to run in either -mutable or fixed mode: mutable, where logical record numbers change as -records are deleted or inserted, and fixed, where record numbers never -change regardless of the database operation. Record numbers in Queue -databases are always fixed, and never change regardless of the database -operation. Record numbers in Btree databases are always mutable, and -as records are deleted or inserted, the logical record number for other -records in the database can change. See -<a href="../../ref/am_conf/renumber.html">Logically renumbering records</a> -for more information. -<p>Configuring Btree databases to support record numbers can severely limit -the throughput of applications with multiple concurrent threads writing -the database, because locations used to store record counts often become -hot spots that many different threads all need to update. In the case -of a Btree supporting duplicate data items, the logical record number -refers to a key and all of its data items, as duplicate data items are -not individually numbered. -<p>The following is an example function that reads records from standard -input and stores them into a Recno database. The function then uses a -cursor to step through the database and display the stored records. -<p><blockquote><pre>int -recno_build(dbp) - DB *dbp; -{ - DBC *dbcp; - DBT key, data; - db_recno_t recno; - u_int32_t len; - int ret; - char buf[1024]; -<p> - /* Insert records into the database. */ - memset(&key, 0, sizeof(DBT)); - memset(&data, 0, sizeof(DBT)); - for (recno = 1;; ++recno) { - printf("record #%lu> ", (u_long)recno); - fflush(stdout); - if (fgets(buf, sizeof(buf), stdin) == NULL) - break; - if ((len = strlen(buf)) <= 1) - continue; -<p> - key.data = &recno; - key.size = sizeof(recno); - data.data = buf; - data.size = len - 1; -<p> - switch (ret = dbp->put(dbp, NULL, &key, &data, 0)) { - case 0: - break; - default: - dbp->err(dbp, ret, "DB->put"); - break; - } - } - printf("\n"); -<p> - /* Acquire a cursor for the database. */ - if ((ret = dbp->cursor(dbp, NULL, &dbcp, 0)) != 0) { - dbp->err(dbp, ret, "DB->cursor"); - return (1); - } -<p> - /* Re-initialize the key/data pair. */ - memset(&key, 0, sizeof(key)); - memset(&data, 0, sizeof(data)); -<p> - /* Walk through the database and print out the key/data pairs. */ - while ((ret = dbcp->c_get(dbcp, &key, &data, DB_NEXT)) == 0) - printf("%lu : %.*s\n", - *(u_long *)key.data, (int)data.size, (char *)data.data); - if (ret != DB_NOTFOUND) - dbp->err(dbp, ret, "DBcursor->get"); -<p> - /* Close the cursor. */ - if ((ret = dbcp->c_close(dbcp)) != 0) { - dbp->err(dbp, ret, "DBcursor->close"); - return (1); - } - return (0); -}</pre></blockquote> -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/am_conf/select.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/am_conf/pagesize.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/libdb/docs/ref/am_conf/malloc.html b/libdb/docs/ref/am_conf/malloc.html deleted file mode 100644 index c6b817a49..000000000 --- a/libdb/docs/ref/am_conf/malloc.html +++ /dev/null @@ -1,33 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Non-local memory allocation</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Access Methods</dl></h3></td> -<td align=right><a href="../../ref/am_conf/dup.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/am_conf/bt_compare.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Non-local memory allocation</h1> -<p>Berkeley DB allocates memory for returning key/data pairs and statistical -information which becomes the responsibility of the application. -There are also interfaces where an application will allocate memory -which becomes the responsibility of Berkeley DB. -<p>On systems in which there may be multiple library versions of the -standard allocation routines (notably Windows NT), transferring memory -between the library and the application will fail because the Berkeley DB -library allocates memory from a different heap than the application -uses to free it, or vice versa. To avoid this problem, the -<a href="../../api_c/env_set_alloc.html">DB_ENV->set_alloc</a> and <a href="../../api_c/db_set_alloc.html">DB->set_alloc</a> methods can be used to -give Berkeley DB references to the application's allocation routines. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/am_conf/dup.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/am_conf/bt_compare.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/libdb/docs/ref/am_conf/pagesize.html b/libdb/docs/ref/am_conf/pagesize.html deleted file mode 100644 index 5990860c3..000000000 --- a/libdb/docs/ref/am_conf/pagesize.html +++ /dev/null @@ -1,78 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Selecting a page size</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Access Methods</dl></h3></td> -<td align=right><a href="../../ref/am_conf/logrec.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/am_conf/cachesize.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Selecting a page size</h1> -<p>The size of the pages used in the underlying database can be specified by -calling the <a href="../../api_c/db_set_pagesize.html">DB->set_pagesize</a> method. The minimum page size is 512 bytes -and the maximum page size is 64K bytes, and must be a power of two. If -no page size is specified by the application, a page size is selected -based on the underlying filesystem I/O block size. (A page size selected -in this way has a lower limit of 512 bytes and an upper limit of 16K -bytes.) -<p>There are several issues to consider when selecting a pagesize: overflow -record sizes, locking, I/O efficiency, and recoverability. -<p>First, the page size implicitly sets the size of an overflow record. -Overflow records are key or data items that are too large to fit on a -normal database page because of their size, and are therefore stored in -overflow pages. Overflow pages are pages that exist outside of the normal -database structure. For this reason, there is often a significant -performance penalty associated with retrieving or modifying overflow -records. Selecting a page size that is too small, and which forces the -creation of large numbers of overflow pages, can seriously impact the -performance of an application. -<p>Second, in the Btree, Hash and Recno access methods, the finest-grained -lock that Berkeley DB acquires is for a page. (The Queue access method -generally acquires record-level locks rather than page-level locks.) -Selecting a page size that is too large, and which causes threads or -processes to wait because other threads of control are accessing or -modifying records on the same page, can impact the performance of your -application. -<p>Third, the page size specifies the granularity of I/O from the database -to the operating system. Berkeley DB will give a page-sized unit of bytes to -the operating system to be scheduled for reading/writing from/to the -disk. For many operating systems, there is an internal <b>block -size</b> which is used as the granularity of I/O from the operating system -to the disk. Generally, it will be more efficient for Berkeley DB to write -filesystem-sized blocks to the operating system and for the operating -system to write those same blocks to the disk. -<p>Selecting a database page size smaller than the filesystem block size -may cause the operating system to coalesce or otherwise manipulate Berkeley DB -pages and can impact the performance of your application. When the page -size is smaller than the filesystem block size and a page written by -Berkeley DB is not found in the operating system's cache, the operating system -may be forced to read a block from the disk, copy the page into the -block it read, and then write out the block to disk, rather than simply -writing the page to disk. Additionally, as the operating system is -reading more data into its buffer cache than is strictly necessary to -satisfy each Berkeley DB request for a page, the operating system buffer cache -may be wasting memory. -<p>Alternatively, selecting a page size larger than the filesystem block -size may cause the operating system to read more data than necessary. -On some systems, reading filesystem blocks sequentially may cause the -operating system to begin performing read-ahead. If requesting a single -database page implies reading enough filesystem blocks to satisfy the -operating system's criteria for read-ahead, the operating system may do -more I/O than is required. -<p>Fourth, when using the Berkeley DB Transactional Data Store product, the page size may affect the errors -from which your database can recover See -<a href="../../ref/transapp/reclimit.html">Berkeley DB Recoverability</a> for more -information. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/am_conf/logrec.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/am_conf/cachesize.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/libdb/docs/ref/am_conf/re_source.html b/libdb/docs/ref/am_conf/re_source.html deleted file mode 100644 index d28f9fa1a..000000000 --- a/libdb/docs/ref/am_conf/re_source.html +++ /dev/null @@ -1,63 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Flat-text backing files</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Access Methods</dl></h3></td> -<td align=right><a href="../../ref/am_conf/extentsize.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/am_conf/renumber.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Flat-text backing files</h1> -<p>It is possible to back any Recno database (either fixed or variable -length) with a flat-text source file. This provides fast read (and -potentially write) access to databases that are normally created and -stored as flat-text files. The backing source file may be specified by -calling the <a href="../../api_c/db_set_re_source.html">DB->set_re_source</a> method. -<p>The backing source file will be read to initialize the database. In the -case of variable length records, the records are assumed to be separated -as described for the <a href="../../api_c/db_set_re_delim.html">DB->set_re_delim</a> method interface. For example, -standard UNIX byte stream files can be interpreted as a sequence of -variable length records separated by ASCII newline characters. This is -the default. -<p>When cached data would normally be written back to the underlying -database file (for example, when the <a href="../../api_c/db_close.html">DB->close</a> or -<a href="../../api_c/db_sync.html">DB->sync</a> methods are called), the in-memory copy of the database will -be written back to the backing source file. -<p>The backing source file must already exist (but may be zero-length) when -<a href="../../api_c/db_open.html">DB->open</a> is called. By default, the backing source file is read -lazily, that is, records are not read from the backing source file until -they are requested by the application. If multiple processes (not -threads) are accessing a Recno database concurrently and either -inserting or deleting records, the backing source file must be read in -its entirety before more than a single process accesses the database, -and only that process should specify the backing source file as part of -the <a href="../../api_c/db_open.html">DB->open</a> call. This can be accomplished by calling the -<a href="../../api_c/db_set_flags.html">DB->set_flags</a> method with the <a href="../../api_c/db_set_flags.html#DB_SNAPSHOT">DB_SNAPSHOT</a> flag. -<p>Reading and writing the backing source file cannot be transactionally -protected because it involves filesystem operations that are not part of -the Berkeley DB transaction methodology. For this reason, if a temporary -database is used to hold the records (a NULL was specified as the file -argument to <a href="../../api_c/db_open.html">DB->open</a>), <b>it is possible to lose the -contents of the backing source file if the system crashes at the right -instant</b>. If a permanent file is used to hold the database (a filename -was specified as the file argument to <a href="../../api_c/db_open.html">DB->open</a>), normal database -recovery on that file can be used to prevent information loss. It is -still possible that the contents of the backing source file itself will -be corrupted or lost if the system crashes. -<p>For all of the above reasons, the backing source file is generally used -to specify databases that are read-only for Berkeley DB applications, and that -are either generated on the fly by software tools, or modified using a -different mechanism such as a text editor. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/am_conf/extentsize.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/am_conf/renumber.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/libdb/docs/ref/am_conf/recno.html b/libdb/docs/ref/am_conf/recno.html deleted file mode 100644 index b29f9e758..000000000 --- a/libdb/docs/ref/am_conf/recno.html +++ /dev/null @@ -1,70 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Managing record-based 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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Access Methods</dl></h3></td> -<td align=right><a href="../../ref/am_conf/h_nelem.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/am_conf/extentsize.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Managing record-based databases</h1> -<p>When using fixed- or variable-length record-based databases, particularly -with flat-text backing files, there are several items that the user can -control. The Recno access method can be used to store either variable- -or fixed-length data items. By default, the Recno access method stores -variable-length data items. The Queue access method can only store -fixed-length data items. -<h3>Record Delimiters</h3> -<p>When using the Recno access method to store variable-length records, -records read from any backing source file are separated by a specific -byte value which marks the end of one record and the beginning of the -next. This delimiting value is ignored except when reading records from -a backing source file, that is, records may be stored into the database -that include the delimiter byte. However, if such records are written -out to the backing source file and the backing source file is -subsequently read into a database, the records will be split where -delimiting bytes were found. -<p>For example, UNIX text files can usually be interpreted as a sequence of -variable-length records separated by ASCII newline characters. This byte -value (ASCII 0x0a) is the default delimiter. Applications may specify a -different delimiting byte using the <a href="../../api_c/db_set_re_delim.html">DB->set_re_delim</a> interface. -If no backing source file is being used, there is no reason to set the -delimiting byte value. -<h3>Record Length</h3> -<p>When using the Recno or Queue access methods to store fixed-length -records, the record length must be specified. Since the Queue access -method always uses fixed-length records, the user must always set the -record length prior to creating the database. Setting the record length -is what causes the Recno access method to store fixed-length, not -variable-length, records. -<p>The length of the records is specified by calling the -<a href="../../api_c/db_set_re_len.html">DB->set_re_len</a> method. The default length of the records is 0 bytes. -Any record read from a backing source file or otherwise stored in the -database that is shorter than the declared length will automatically be -padded as described for the <a href="../../api_c/db_set_re_pad.html">DB->set_re_pad</a> method. Any record stored -that is longer than the declared length results in an error. For -further information on backing source files, see -<a href="../../ref/am_conf/re_source.html">Flat-text backing files</a>. -<h3>Record Padding Byte Value</h3> -<p>When storing fixed-length records in a Queue or Recno database, a pad -character may be specified by calling the <a href="../../api_c/db_set_re_pad.html">DB->set_re_pad</a> method. Any -record read from the backing source file or otherwise stored in the -database that is shorter than the expected length will automatically be -padded with this byte value. If fixed-length records are specified but -no pad value is specified, a space character (0x20 in the ASCII -character set) will be used. For further information on backing source -files, see <a href="../../ref/am_conf/re_source.html">Flat-text backing -files</a>. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/am_conf/h_nelem.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/am_conf/extentsize.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/libdb/docs/ref/am_conf/renumber.html b/libdb/docs/ref/am_conf/renumber.html deleted file mode 100644 index 6a039c0bf..000000000 --- a/libdb/docs/ref/am_conf/renumber.html +++ /dev/null @@ -1,81 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Logically renumbering 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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Access Methods</dl></h3></td> -<td align=right><a href="../../ref/am_conf/re_source.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/am/ops.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Logically renumbering records</h1> -<p>Records stored in the Queue and Recno access methods are accessed by -logical record number. In all cases in Btree databases, and optionally -in Recno databases (see the <a href="../../api_c/db_set_flags.html">DB->set_flags</a> method and the -<a href="../../api_c/db_set_flags.html#DB_RENUMBER">DB_RENUMBER</a> flag for more information), record numbers are -mutable. This means that the record numbers may change as records are -added to and deleted from the database. The deletion of record number -4 causes any records numbered 5 and higher to be renumbered downward by -1; the addition of a new record after record number 4 causes any -records numbered 5 and higher to be renumbered upward by 1. In all -cases in Queue databases, and by default in Recno databases, record -numbers are not mutable, and the addition or deletion of records to the -database will not cause already-existing record numbers to change. For -this reason, new records cannot be inserted between already-existing -records in databases with immutable record numbers. -<p>Cursors pointing into a Btree database or a Recno database with mutable -record numbers maintain a reference to a specific record, rather than -a record number, that is, the record they reference does not change as -other records are added or deleted. For example, if a database contains -three records with the record numbers 1, 2, and 3, and the data items -"A", "B", and "C", respectively, the deletion of record number 2 ("B") -will cause the record "C" to be renumbered downward to record number 2. -A cursor positioned at record number 3 ("C") will be adjusted and -continue to point to "C" after the deletion. Similarly, a cursor -previously referring to the now deleted record number 2 will be -positioned between the new record numbers 1 and 2, and an insertion -using that cursor will appear between those records. In this manner -records can be added and deleted to a database without disrupting the -sequential traversal of the database by a cursor. -<p>Only cursors created using a single <a href="../../api_c/db_class.html">DB</a> handle can adjust each -other's position in this way, however. If multiple <a href="../../api_c/db_class.html">DB</a> handles -have a renumbering Recno database open simultaneously (as when multiple -processes share a single database environment), a record referred to by -one cursor could change underfoot if a cursor created using another -<a href="../../api_c/db_class.html">DB</a> handle inserts or deletes records into the database. For -this reason, applications using Recno databases with mutable record -numbers will usually make all accesses to the database using a single -<a href="../../api_c/db_class.html">DB</a> handle and cursors created from that handle, or will -otherwise single-thread access to the database, for example, by using -the Berkeley DB Concurrent Data Store product. -<p>In any Queue or Recno databases, creating new records will cause the -creation of multiple records if the record number being created is more -than one greater than the largest record currently in the database. For -example, creating record number 28, when record 25 was previously the -last record in the database, will implicitly create records 26 and 27 -as well as 28. All first, last, next and previous cursor operations -will automatically skip over these implicitly created records. So, if -record number 5 is the only record the application has created, -implicitly creating records 1 through 4, the <a href="../../api_c/dbc_get.html">DBcursor->c_get</a> interface -with the <a href="../../api_c/dbc_get.html#DB_FIRST">DB_FIRST</a> flag will return record number 5, not record -number 1. Attempts to explicitly retrieve implicitly created records -by their record number will result in a special error return, -<a href="../../ref/program/errorret.html#DB_KEYEMPTY">DB_KEYEMPTY</a>. -<p>In any Berkeley DB database, attempting to retrieve a deleted record, using -a cursor positioned on the record, results in a special error return, -<a href="../../ref/program/errorret.html#DB_KEYEMPTY">DB_KEYEMPTY</a>. In addition, when using Queue databases or Recno -databases with immutable record numbers, attempting to retrieve a deleted -record by its record number will also result in the <a href="../../ref/program/errorret.html#DB_KEYEMPTY">DB_KEYEMPTY</a> -return. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/am_conf/re_source.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/am/ops.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/libdb/docs/ref/am_conf/select.html b/libdb/docs/ref/am_conf/select.html deleted file mode 100644 index 789eb5c7d..000000000 --- a/libdb/docs/ref/am_conf/select.html +++ /dev/null @@ -1,118 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Selecting an access method</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Access Methods</dl></h3></td> -<td align=right><a href="../../ref/am_conf/intro.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/am_conf/logrec.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Selecting an access method</h1> -<p>The Berkeley DB access method implementation unavoidably interacts with each -application's data set, locking requirements and data access patterns. -For this reason, one access method may result in dramatically better -performance for an application than another one. Applications whose data -could be stored using more than one access method may want to benchmark -their performance using the different candidates. -<p>One of the strengths of Berkeley DB is that it provides multiple access methods -with nearly identical interfaces to the different access methods. This -means that it is simple to modify an application to use a different access -method. Applications can easily benchmark the different Berkeley DB access -methods against each other for their particular data set and access pattern. -<p>Most applications choose between using the Btree or Hash access methods -or between using the Queue and Recno access methods, because each of the -two pairs offer similar functionality. -<h3>Hash or Btree?</h3> -<p>The Hash and Btree access methods should be used when logical record -numbers are not the primary key used for data access. (If logical record -numbers are a secondary key used for data access, the Btree access method -is a possible choice, as it supports simultaneous access by a key and a -record number.) -<p>Keys in Btrees are stored in sorted order and the relationship between -them is defined by that sort order. For this reason, the Btree access -method should be used when there is any locality of reference among keys. -Locality of reference means that accessing one particular key in the -Btree implies that the application is more likely to access keys near to -the key being accessed, where "near" is defined by the sort order. For -example, if keys are timestamps, and it is likely that a request for an -8AM timestamp will be followed by a request for a 9AM timestamp, the -Btree access method is generally the right choice. Or, for example, if -the keys are names, and the application will want to review all entries -with the same last name, the Btree access method is again a good choice. -<p>There is little difference in performance between the Hash and Btree -access methods on small data sets, where all, or most of, the data set -fits into the cache. However, when a data set is large enough that -significant numbers of data pages no longer fit into the cache, then -the Btree locality of reference described previously becomes important -for performance reasons. For example, there is no locality of reference -for the Hash access method, and so key "AAAAA" is as likely to be stored -on the same database page with key "ZZZZZ" as with key "AAAAB". In the -Btree access method, because items are sorted, key "AAAAA" is far more -likely to be near key "AAAAB" than key "ZZZZZ". So, if the application -exhibits locality of reference in its data requests, then the Btree page -read into the cache to satisfy a request for key "AAAAA" is much more -likely to be useful to satisfy subsequent requests from the application -than the Hash page read into the cache to satisfy the same request. -This means that for applications with locality of reference, the cache -is generally much more effective for the Btree access method than the -Hash access method, and the Btree access method will make many fewer -I/O calls. -<p>However, when a data set becomes even larger, the Hash access method can -outperform the Btree access method. The reason for this is that Btrees -contain more metadata pages than Hash databases. The data set can grow -so large that metadata pages begin to dominate the cache for the Btree -access method. If this happens, the Btree can be forced to do an I/O -for each data request because the probability that any particular data -page is already in the cache becomes quite small. Because the Hash access -method has fewer metadata pages, its cache stays "hotter" longer in the -presence of large data sets. In addition, once the data set is so large -that both the Btree and Hash access methods are almost certainly doing -an I/O for each random data request, the fact that Hash does not have to -walk several internal pages as part of a key search becomes a performance -advantage for the Hash access method as well. -<p>Application data access patterns strongly affect all of these behaviors, -for example, accessing the data by walking a cursor through the database -will greatly mitigate the large data set behavior describe above because -each I/O into the cache will satisfy a fairly large number of subsequent -data requests. -<p>In the absence of information on application data and data access -patterns, for small data sets either the Btree or Hash access methods -will suffice. For data sets larger than the cache, we normally recommend -using the Btree access method. If you have truly large data, then the -Hash access method may be a better choice. The <a href="../../utility/db_stat.html">db_stat</a> utility -is a useful tool for monitoring how well your cache is performing. -<h3>Queue or Recno?</h3> -<p>The Queue or Recno access methods should be used when logical record -numbers are the primary key used for data access. The advantage of the -Queue access method is that it performs record level locking and for this -reason supports significantly higher levels of concurrency than the Recno -access method. The advantage of the Recno access method is that it -supports a number of additional features beyond those supported by the -Queue access method, such as variable-length records and support for -backing flat-text files. -<p>Logical record numbers can be mutable or fixed: mutable, where logical -record numbers can change as records are deleted or inserted, and fixed, -where record numbers never change regardless of the database operation. -It is possible to store and retrieve records based on logical record -numbers in the Btree access method. However, those record numbers are -always mutable, and as records are deleted or inserted, the logical record -number for other records in the database will change. The Queue access -method always runs in fixed mode, and logical record numbers never change -regardless of the database operation. The Recno access method can be -configured to run in either mutable or fixed mode. -<p>In addition, the Recno access method provides support for databases whose -permanent storage is a flat text file and the database is used as a fast, -temporary storage area while the data is being read or modified. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/am_conf/intro.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/am_conf/logrec.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/libdb/docs/ref/am_misc/align.html b/libdb/docs/ref/am_misc/align.html deleted file mode 100644 index 8c9e503ba..000000000 --- a/libdb/docs/ref/am_misc/align.html +++ /dev/null @@ -1,29 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Data alignment</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Access Methods</dl></h3></td> -<td align=right><a href="../../ref/am/curclose.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/am_misc/get_bulk.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Data alignment</h1> -<p>The Berkeley DB access methods provide no guarantees about byte alignment for -returned key/data pairs, or callback functions which take <a href="../../api_c/dbt_class.html">DBT</a> -references as arguments, and applications are responsible for arranging -any necessary alignment. The <a href="../../api_c/dbt_class.html#DB_DBT_MALLOC">DB_DBT_MALLOC</a>, -<a href="../../api_c/dbt_class.html#DB_DBT_REALLOC">DB_DBT_REALLOC</a> and <a href="../../api_c/dbt_class.html#DB_DBT_USERMEM">DB_DBT_USERMEM</a> flags may be used to -store returned items in memory of arbitrary alignment. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/am/curclose.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/am_misc/get_bulk.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/libdb/docs/ref/am_misc/dbsizes.html b/libdb/docs/ref/am_misc/dbsizes.html deleted file mode 100644 index 3705eb557..000000000 --- a/libdb/docs/ref/am_misc/dbsizes.html +++ /dev/null @@ -1,46 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Database limits</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Access Methods</dl></h3></td> -<td align=right><a href="../../ref/am_misc/stability.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/am_misc/diskspace.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Database limits</h1> -<p>The largest database file that Berkeley DB can handle depends on the page size -selected by the application. Berkeley DB stores database file page numbers as -unsigned 32-bit numbers and database file page sizes as unsigned 16-bit -numbers. Using the maximum database page size of 65536, this results in -a maximum database file size of 2<sup>48</sup> (256 terabytes). The -minimum database page size is 512 bytes, which results in a minimum -maximum database size of 2<sup>41</sup> (2 terabytes). -<p>The largest database file Berkeley DB can support is potentially further limited -if the host system does not have filesystem support for files larger than -2<sup>32</sup>, including the ability to seek to absolute offsets within -those files. -<p>The largest key or data item that Berkeley DB can support is largely limited -by available memory. Specifically, while key and data byte strings may -be of essentially unlimited length, any one of them must fit into -available memory so that it can be returned to the application. As some -of the Berkeley DB interfaces return both key and data items to the application, -those interfaces will require that any key/data pair fit simultaneously -into memory. Further, as the access methods may need to compare key and -data items with other key and data items, it may be a requirement that -any two key or two data items fit into available memory. Finally, when -writing applications supporting transactions, it may be necessary to have -an additional copy of any data item in memory for logging purposes. -<p>The maximum Btree depth is 255. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/am_misc/stability.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/am_misc/diskspace.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/libdb/docs/ref/am_misc/diskspace.html b/libdb/docs/ref/am_misc/diskspace.html deleted file mode 100644 index 0c7866fbe..000000000 --- a/libdb/docs/ref/am_misc/diskspace.html +++ /dev/null @@ -1,149 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Disk space requirements</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Access Methods</dl></h3></td> -<td align=right><a href="../../ref/am_misc/dbsizes.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/am_misc/tune.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Disk space requirements</h1> -<p>It is possible to estimate the total database size based on the size of -the data. The following calculations are an estimate of how many bytes -you will need to hold a set of data and then how many pages it will take -to actually store it on disk. -<p>Space freed by deleting key/data pairs from a Btree or Hash database is -never returned to the filesystem, although it is reused where possible. -This means that the Btree and Hash databases are grow-only. If enough -keys are deleted from a database that shrinking the underlying file is -desirable, you should create a new database and copy the records from -the old one into it. -<p>These are rough estimates at best. For example, they do not take into -account overflow records, filesystem metadata information, large sets -of duplicate data items (where the key is only stored once), or -real-life situations where the sizes of key and data items are wildly -variable, and the page-fill factor changes over time. -<h3>Btree</h3> -<p>The formulas for the Btree access method are as follows: -<p><blockquote><pre>useful-bytes-per-page = (page-size - page-overhead) * page-fill-factor -<p> -bytes-of-data = n-records * - (bytes-per-entry + page-overhead-for-two-entries) -<p> -n-pages-of-data = bytes-of-data / useful-bytes-per-page -<p> -total-bytes-on-disk = n-pages-of-data * page-size -</pre></blockquote> -<p>The <b>useful-bytes-per-page</b> is a measure of the bytes on each page -that will actually hold the application data. It is computed as the total -number of bytes on the page that are available to hold application data, -corrected by the percentage of the page that is likely to contain data. -The reason for this correction is that the percentage of a page that -contains application data can vary from close to 50% after a page split -to almost 100% if the entries in the database were inserted in sorted -order. Obviously, the <b>page-fill-factor</b> can drastically alter -the amount of disk space required to hold any particular data set. The -page-fill factor of any existing database can be displayed using the -<a href="../../utility/db_stat.html">db_stat</a> utility. -<p>The page-overhead for Btree databases is 26 bytes. As an example, using -an 8K page size, with an 85% page-fill factor, there are 6941 bytes of -useful space on each page: -<p><blockquote><pre>6941 = (8192 - 26) * .85</pre></blockquote> -<p>The total <b>bytes-of-data</b> is an easy calculation: It is the -number of key or data items plus the overhead required to store each -item on a page. The overhead to store a key or data item on a Btree -page is 5 bytes. So, it would take 1560000000 bytes, or roughly 1.34GB -of total data to store 60,000,000 key/data pairs, assuming each key or -data item was 8 bytes long: -<p><blockquote><pre>1560000000 = 60000000 * ((8 + 5) * 2)</pre></blockquote> -<p>The total pages of data, <b>n-pages-of-data</b>, is the -<b>bytes-of-data</b> divided by the <b>useful-bytes-per-page</b>. In -the example, there are 224751 pages of data. -<p><blockquote><pre>224751 = 1560000000 / 6941</pre></blockquote> -<p>The total bytes of disk space for the database is <b>n-pages-of-data</b> -multiplied by the <b>page-size</b>. In the example, the result is -1841160192 bytes, or roughly 1.71GB. -<p><blockquote><pre>1841160192 = 224751 * 8192</pre></blockquote> -<h3>Hash</h3> -<p>The formulas for the Hash access method are as follows: -<p><blockquote><pre>useful-bytes-per-page = (page-size - page-overhead) -<p> -bytes-of-data = n-records * - (bytes-per-entry + page-overhead-for-two-entries) -<p> -n-pages-of-data = bytes-of-data / useful-bytes-per-page -<p> -total-bytes-on-disk = n-pages-of-data * page-size -</pre></blockquote> -<p>The <b>useful-bytes-per-page</b> is a measure of the bytes on each page -that will actually hold the application data. It is computed as the total -number of bytes on the page that are available to hold application data. -If the application has explicitly set a page-fill factor, pages will -not necessarily be kept full. For databases with a preset fill factor, -see the calculation below. The page-overhead for Hash databases is 26 -bytes and the page-overhead-for-two-entries is 6 bytes. -<p>As an example, using an 8K page size, there are 8166 bytes of useful space -on each page: -<p><blockquote><pre>8166 = (8192 - 26)</pre></blockquote> -<p>The total <b>bytes-of-data</b> is an easy calculation: it is the number -of key/data pairs plus the overhead required to store each pair on a page. -In this case that's 6 bytes per pair. So, assuming 60,000,000 key/data -pairs, each of which is 8 bytes long, there are 1320000000 bytes, or -roughly 1.23GB of total data: -<p><blockquote><pre>1320000000 = 60000000 * (16 + 6)</pre></blockquote> -<p>The total pages of data, <b>n-pages-of-data</b>, is the -<b>bytes-of-data</b> divided by the <b>useful-bytes-per-page</b>. In -this example, there are 161646 pages of data. -<p><blockquote><pre>161646 = 1320000000 / 8166</pre></blockquote> -<p>The total bytes of disk space for the database is <b>n-pages-of-data</b> -multiplied by the <b>page-size</b>. In the example, the result is -1324204032 bytes, or roughly 1.23GB. -<p><blockquote><pre>1324204032 = 161646 * 8192</pre></blockquote> -<p>Now, let's assume that the application specified a fill factor explicitly. -The fill factor indicates the target number of items to place on a single -page (a fill factor might reduce the utilization of each page, but it can -be useful in avoiding splits and preventing buckets from becoming too -large). Using our estimates above, each item is 22 bytes (16 + 6), and -there are 8166 useful bytes on a page (8192 - 26). That means that, on -average, you can fit 371 pairs per page. -<p><blockquote><pre>371 = 8166 / 22</pre></blockquote> -<p>However, let's assume that the application designer knows that although -most items are 8 bytes, they can sometimes be as large as 10, and it's -very important to avoid overflowing buckets and splitting. Then, the -application might specify a fill factor of 314. -<p><blockquote><pre>314 = 8166 / 26</pre></blockquote> -<p>With a fill factor of 314, then the formula for computing database size -is -<p><blockquote><pre>n-pages-of-data = npairs / pairs-per-page</pre></blockquote> -<p>or 191082. -<p><blockquote><pre>191082 = 60000000 / 314</pre></blockquote> -<p>At 191082 pages, the total database size would be 1565343744, or 1.46GB. -<p><blockquote><pre>1565343744 = 191082 * 8192</pre></blockquote> -<p>There are a few additional caveats with respect to Hash databases. This -discussion assumes that the hash function does a good job of evenly -distributing keys among hash buckets. If the function does not do this, -you may find your table growing significantly larger than you expected. -Secondly, in order to provide support for Hash databases coexisting with -other databases in a single file, pages within a Hash database are -allocated in power-of-two chunks. That means that a Hash database with 65 -buckets will take up as much space as a Hash database with 128 buckets; -each time the Hash database grows beyond its current power-of-two number -of buckets, it allocates space for the next power-of-two buckets. This -space may be sparsely allocated in the file system, but the files will -appear to be their full size. Finally, because of this need for -contiguous allocation, overflow pages and duplicate pages can be allocated -only at specific points in the file, and this too can lead to sparse hash -tables. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/am_misc/dbsizes.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/am_misc/tune.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/libdb/docs/ref/am_misc/error.html b/libdb/docs/ref/am_misc/error.html deleted file mode 100644 index b16b046e9..000000000 --- a/libdb/docs/ref/am_misc/error.html +++ /dev/null @@ -1,63 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Access Methods</dl></h3></td> -<td align=right><a href="../../ref/am_misc/perm.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/am_misc/stability.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> method appends the standard error string to the constructed -message; the <a href="../../api_c/db_err.html">DB->errx</a> method 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 -(for example, 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" -<p> -int ret; -<p> -(void)dbp->set_errpfx(dbp, program_name); -<p> -if ((ret = dbp->open(dbp, - NULL, DATABASE, NULL, 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 were 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 width="100%"><tr><td><br></td><td align=right><a href="../../ref/am_misc/perm.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/am_misc/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/libdb/docs/ref/am_misc/faq.html b/libdb/docs/ref/am_misc/faq.html deleted file mode 100644 index d0261c920..000000000 --- a/libdb/docs/ref/am_misc/faq.html +++ /dev/null @@ -1,130 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Access method FAQ</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Access Methods</dl></h3></td> -<td align=right><a href="../../ref/am_misc/tune.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.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>Access method FAQ</h1> -<p><ol> -<p><li><b>Is a Berkeley DB database the same as a "table"?</b> -<p>Yes; "tables" are databases, "rows" are key/data pairs, and "columns" -are application-encapsulated fields within a data item (to which Berkeley DB -does not directly provide access). -<p><li><b>I'm getting an error return in my application, but I can't -figure out what the library is complaining about.</b> -<p>See <a href="../../api_c/env_set_errcall.html">DB_ENV->set_errcall</a>, <a href="../../api_c/env_set_errfile.html">DB_ENV->set_errfile</a> and -<a href="../../api_c/db_set_errfile.html">DB->set_errfile</a> for ways to get additional information about -error returns from Berkeley DB. -<p><li><b>Are Berkeley DB databases portable between architectures?</b> -<p>Yes. See <a href="../../ref/am_conf/byteorder.html">Selecting a byte -order</a> for more information. -<p><li><b>I'm seeing database corruption when creating multiple databases -in a single physical file.</b> -<p>This problem is usually the result of <a href="../../api_c/db_class.html">DB</a> handles not sharing an -underlying database environment. See <a href="../../ref/am/opensub.html">Opening multiple databases in a single file</a> for more information. -<a name="3"><!--meow--></a><a name="4"><!--meow--></a> -<p><li><b>Is there any way to compact databases, or return unused -database pages to the filesystem?</b> -<p>When Berkeley DB database pages are emptied, they are made available for other -uses, that is, new pages will not be allocated from the underlying -filesystem as long as there are unused pages available. However, the -pages cannot be returned to the filesystem without dumping the database, -removing the physical file, and reloading the database. The one -exception to this rule is Queue access method extent files. Queue -extent files are removed when they are emptied, and their pages returned -to the underlying filesystem. -<p><li><b>I'm using integers as keys for a Btree database, and even -though the key/data pairs are entered in sorted order, the page-fill -factor is low.</b> -<p>This is usually the result of using integer keys on little-endian -architectures such as the x86. Berkeley DB sorts keys as byte strings, and -little-endian integers don't sort well when viewed as byte strings. -For example, take the numbers 254 through 257. Their byte patterns on -a little-endian system are: -<p><blockquote><pre>254 fe 0 0 0 -255 ff 0 0 0 -256 0 1 0 0 -257 1 1 0 0</pre></blockquote> -<p>If you treat them as strings, then they sort badly: -<p><blockquote><pre>256 -257 -254 -255</pre></blockquote> -<p>On a big-endian system, their byte patterns are: -<p><blockquote><pre>254 0 0 0 fe -255 0 0 0 ff -256 0 0 1 1 -257 0 0 1 1</pre></blockquote> -<p>and so, if you treat them as strings they sort nicely. Which means, if -you use steadily increasing integers as keys on a big-endian system -Berkeley DB behaves well and you get compact trees, but on a little-endian -system Berkeley DB produces much less compact trees. To avoid this problem, -you may want to convert the keys to flat text or big-endian -representations, or provide your own Btree comparison function. -<a name="5"><!--meow--></a> -<p><li><b>Is there any way to avoid double buffering in the Berkeley DB system?</b> -<p>While you cannot avoid double buffering entirely, there are a few things -you can do to address this issue: -<p>First, the Berkeley DB cache size can be explicitly set. Rather than allocate -additional space in the Berkeley DB cache to cover unexpectedly heavy load or -large table sizes, double buffering may suggest you size the cache to -function well under normal conditions, and then depend on the file -buffer cache to cover abnormal conditions. Obviously, this is a -trade-off, as Berkeley DB may not then perform as well as usual under abnormal -conditions. -<p>Second, depending on the underlying operating system you're using, you -may be able to alter the amount of physical memory devoted to the file -buffer cache. Running as the system super-user makes a difference for -some UNIX or UNIX-like operating systems as well. -<p>Third, changing the size of the Berkeley DB environment regions can change -the amount of space the operating system makes available for the file -buffer cache, and it's often worth considering exactly how the operating -system is dividing up its available memory. Further, moving the Berkeley DB -database environment regions from filesystem backed memory into system -memory (or heap memory), can often make additional system memory -available for the file buffer cache, especially on systems without a -unified buffer cache and VM system. -<p>Finally, for operating systems that allow buffering to be turned off, -specifying the <a href="../../api_c/env_set_flags.html#DB_DIRECT_DB">DB_DIRECT_DB</a> and <a href="../../api_c/env_set_flags.html#DB_DIRECT_LOG">DB_DIRECT_LOG</a> flags -will attempt to do so. -<p><li><b>I'm seeing database corruption when I run out of disk space.</b> -<p>Berkeley DB can continue to run when when out-of-disk-space errors occur, but -it requires the application to be transaction protected. Applications -which do not enclose update operations in transactions cannot recover -from out-of-disk-space errors, and the result of running out of disk -space may be database corruption. -<p><li><b>How can I associate application information with a <a href="../../api_c/db_class.html">DB</a> -or <a href="../../api_c/env_class.html">DB_ENV</a> handle?</b> -<p>In the C API, the <a href="../../api_c/db_class.html">DB</a> and <a href="../../api_c/env_class.html">DB_ENV</a> structures each contain -an "app_private" field intended to be used to reference -application-specific information. See the <a href="../../api_c/db_create.html">db_create</a> and -<a href="../../api_c/env_create.html">db_env_create</a> documentation for more information. -<p>In the C++ or Java APIs, the easiest way to associate -application-specific data with a handle is to subclass the <a href="../../api_cxx/db_class.html">Db</a> -or <a href="../../api_cxx/env_class.html">DbEnv</a>, for example subclassing <a href="../../api_cxx/db_class.html">Db</a> to get MyDb. -Objects of type MyDb will still have the Berkeley DB API methods available on -them, and you can put any extra data or methods you want into the MyDb -class. If you are using "callback" APIs that take <a href="../../api_cxx/db_class.html">Db</a> or -<a href="../../api_cxx/env_class.html">DbEnv</a> arguments (for example, <a href="../../api_cxx/db_set_bt_compare.html">Db::set_bt_compare</a>) -these will always be called with the <a href="../../api_cxx/db_class.html">Db</a> or <a href="../../api_cxx/env_class.html">DbEnv</a> -objects you create. So if you always use MyDb objects, you will be able -to take the first argument to the callback function and cast it to a -MyDb (in C++, cast it to (MyDb*)). That will allow you to access your -data members or methods. -</ol> -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/am_misc/tune.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.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/libdb/docs/ref/am_misc/get_bulk.html b/libdb/docs/ref/am_misc/get_bulk.html deleted file mode 100644 index 99d77c8e4..000000000 --- a/libdb/docs/ref/am_misc/get_bulk.html +++ /dev/null @@ -1,136 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Retrieving records in bulk</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Access Methods</dl></h3></td> -<td align=right><a href="../../ref/am_misc/align.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/am_misc/partial.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Retrieving records in bulk</h1> -<p>When retrieving large numbers of records from the database, the number -of method calls can often dominate performance. Berkeley DB offers bulk get -interfaces which can significantly increase performance for some -applications. To retrieve records in bulk, an application buffer must -be specified to the <a href="../../api_c/db_get.html">DB->get</a> or <a href="../../api_c/dbc_get.html">DBcursor->c_get</a> methods. This is done -in the C API by setting the <b>data</b> and <b>ulen</b> fields of the -<b>data</b> <a href="../../api_c/dbt_class.html">DBT</a> to reference an application buffer, and the -<b>flags</b> field of that structure to <a href="../../api_c/dbt_class.html#DB_DBT_USERMEM">DB_DBT_USERMEM</a>. In -the Berkeley DB C++ and Java APIs, the actions are similar, although there -are API-specific methods to set the <a href="../../api_c/dbt_class.html">DBT</a> values. Then, the -<a href="../../api_c/dbc_get.html#DB_MULTIPLE">DB_MULTIPLE</a> or <a href="../../api_c/dbc_get.html#DB_MULTIPLE_KEY">DB_MULTIPLE_KEY</a> flags are specified to -the <a href="../../api_c/db_get.html">DB->get</a> or <a href="../../api_c/dbc_get.html">DBcursor->c_get</a> methods, which cause multiple records -to be returned in the specified buffer. -<p>The difference between <a href="../../api_c/dbc_get.html#DB_MULTIPLE">DB_MULTIPLE</a> and <a href="../../api_c/dbc_get.html#DB_MULTIPLE_KEY">DB_MULTIPLE_KEY</a> -is as follows: <a href="../../api_c/dbc_get.html#DB_MULTIPLE">DB_MULTIPLE</a> returns multiple data items for a -single key. For example, the <a href="../../api_c/dbc_get.html#DB_MULTIPLE">DB_MULTIPLE</a> flag would be used to -retrieve all of the duplicate data items for a single key in a single -call. The <a href="../../api_c/dbc_get.html#DB_MULTIPLE_KEY">DB_MULTIPLE_KEY</a> flag is used to retrieve multiple -key/data pairs, where each returned key may or may not have duplicate -data items. -<p>Once the <a href="../../api_c/db_get.html">DB->get</a> or <a href="../../api_c/dbc_get.html">DBcursor->c_get</a> method has returned, the -application will walk through the buffer handling the returned records. -This is implemented for the C and C++ APIs using four macros: -<a href="../../api_c/dbt_bulk.html#DB_MULTIPLE_INIT">DB_MULTIPLE_INIT</a>, <a href="../../api_c/dbt_bulk.html#DB_MULTIPLE_NEXT">DB_MULTIPLE_NEXT</a>, -<a href="../../api_c/dbt_bulk.html#DB_MULTIPLE_KEY_NEXT">DB_MULTIPLE_KEY_NEXT</a>, and <a href="../../api_c/dbt_bulk.html#DB_MULTIPLE_RECNO_NEXT">DB_MULTIPLE_RECNO_NEXT</a>. For -the Java API, this is implemented as three iterator classes: -<a href="../../api_java/dbt_bulk_class.html">DbMultipleDataIterator</a>, -<a href="../../api_java/dbt_bulk_class.html">DbMultipleKeyDataIterator</a>, and -<a href="../../api_java/dbt_bulk_class.html">DbMultipleRecnoDataIterator</a>. -<p>The <a href="../../api_c/dbt_bulk.html#DB_MULTIPLE_INIT">DB_MULTIPLE_INIT</a> macro is always called first. It -initializes a local application variable and the <b>data</b> -<a href="../../api_c/dbt_class.html">DBT</a> for stepping through the set of returned records. Then, -the application calls one of the remaining three macros: -<a href="../../api_c/dbt_bulk.html#DB_MULTIPLE_NEXT">DB_MULTIPLE_NEXT</a>, <a href="../../api_c/dbt_bulk.html#DB_MULTIPLE_KEY_NEXT">DB_MULTIPLE_KEY_NEXT</a>, and -<a href="../../api_c/dbt_bulk.html#DB_MULTIPLE_RECNO_NEXT">DB_MULTIPLE_RECNO_NEXT</a>. -<p>If the <a href="../../api_c/dbc_get.html#DB_MULTIPLE">DB_MULTIPLE</a> flag was specified to the <a href="../../api_c/db_get.html">DB->get</a> or -<a href="../../api_c/dbc_get.html">DBcursor->c_get</a> method, the application will always call the -<a href="../../api_c/dbt_bulk.html#DB_MULTIPLE_NEXT">DB_MULTIPLE_NEXT</a> macro. If the <a href="../../api_c/dbc_get.html#DB_MULTIPLE_KEY">DB_MULTIPLE_KEY</a> flag -was specified to the <a href="../../api_c/db_get.html">DB->get</a> or <a href="../../api_c/dbc_get.html">DBcursor->c_get</a> method, and, the -underlying database is a Btree or Hash database, the application will -always call the <a href="../../api_c/dbt_bulk.html#DB_MULTIPLE_KEY_NEXT">DB_MULTIPLE_KEY_NEXT</a> macro. If the -<a href="../../api_c/dbc_get.html#DB_MULTIPLE_KEY">DB_MULTIPLE_KEY</a> flag was specified to the <a href="../../api_c/db_get.html">DB->get</a> or -<a href="../../api_c/dbc_get.html">DBcursor->c_get</a> method, and, the underlying database is a Queue or Recno -database, the application will always call the -<a href="../../api_c/dbt_bulk.html#DB_MULTIPLE_RECNO_NEXT">DB_MULTIPLE_RECNO_NEXT</a> macro. The <a href="../../api_c/dbt_bulk.html#DB_MULTIPLE_NEXT">DB_MULTIPLE_NEXT</a>, -<a href="../../api_c/dbt_bulk.html#DB_MULTIPLE_KEY_NEXT">DB_MULTIPLE_KEY_NEXT</a>, and <a href="../../api_c/dbt_bulk.html#DB_MULTIPLE_RECNO_NEXT">DB_MULTIPLE_RECNO_NEXT</a> macros -are called repeatedly, until the end of the returned records is reached. -The end of the returned records is detected by the application's local -pointer variable being set to NULL. -<p>The following is an example of a routine that displays the contents of -a Btree database using the bulk return interfaces. -<p><blockquote><pre>int -rec_display(dbp) - DB *dbp; -{ - DBC *dbcp; - DBT key, data; - size_t retklen, retdlen; - char *retkey, *retdata; - int ret, t_ret; - void *p; -<p> - memset(&key, 0, sizeof(key)); - memset(&data, 0, sizeof(data)); -<p> - /* Review the database in 5MB chunks. */ -#define BUFFER_LENGTH (5 * 1024 * 1024) - if ((data.data = malloc(BUFFER_LENGTH)) == NULL) - return (errno); - data.ulen = BUFFER_LENGTH; - data.flags = DB_DBT_USERMEM; -<p> - /* Acquire a cursor for the database. */ - if ((ret = dbp->cursor(dbp, NULL, &dbcp, 0)) != 0) { - dbp->err(dbp, ret, "DB->cursor"); - free(data.data); - return (ret); - } -<p> - for (;;) { - /* - * Acquire the next set of key/data pairs. This code does - * not handle single key/data pairs that won't fit in a - * BUFFER_LENGTH size buffer, instead returning ENOMEM to - * our caller. - */ - if ((ret = dbcp->c_get(dbcp, - &key, &data, DB_MULTIPLE_KEY | DB_NEXT)) != 0) { - if (ret != DB_NOTFOUND) - dbp->err(dbp, ret, "DBcursor->c_get"); - break; - } -<p> - for (DB_MULTIPLE_INIT(p, &data);;) { - DB_MULTIPLE_KEY_NEXT(p, - &data, retkey, retklen, retdata, retdlen); - if (p == NULL) - break; - printf("key: %.*s, data: %.*s\n", - (int)retklen, retkey, (int)retdlen, retdata); - } - } -<p> - if ((t_ret = dbcp->c_close(dbcp)) != 0) { - dbp->err(dbp, ret, "DBcursor->close"); - if (ret == 0) - ret = t_ret; - } -<p> - free(data.data); -<p> - return (ret); -}</pre></blockquote> -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/am_misc/align.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/am_misc/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/libdb/docs/ref/am_misc/partial.html b/libdb/docs/ref/am_misc/partial.html deleted file mode 100644 index 9d1b3a4f3..000000000 --- a/libdb/docs/ref/am_misc/partial.html +++ /dev/null @@ -1,134 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Access Methods</dl></h3></td> -<td align=right><a href="../../ref/am_misc/get_bulk.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/am_misc/struct.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_class.html#DB_DBT_PARTIAL">DB_DBT_PARTIAL</a> flag in the <a href="../../api_c/dbt_class.html">DBT</a> structure passed to the -Berkeley DB interface. -<p>The <a href="../../api_c/dbt_class.html#DB_DBT_PARTIAL">DB_DBT_PARTIAL</a> flag is based on the values of two fields -of the <a href="../../api_c/dbt_class.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 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_class.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; -that is, 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; -that is, 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; -that is, 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; -that is, 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; -that is, 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; -that is, 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 width="100%"><tr><td><br></td><td align=right><a href="../../ref/am_misc/get_bulk.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/am_misc/struct.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/libdb/docs/ref/am_misc/perm.html b/libdb/docs/ref/am_misc/perm.html deleted file mode 100644 index fddb37654..000000000 --- a/libdb/docs/ref/am_misc/perm.html +++ /dev/null @@ -1,37 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Retrieved key/data permanence for C/C++</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Access Methods</dl></h3></td> -<td align=right><a href="../../ref/am_misc/struct.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/am_misc/error.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Retrieved key/data permanence for C/C++</h1> -<p>When using the non-cursor Berkeley DB calls to retrieve key/data items under -the C/C++ APIs (for example, <a href="../../api_c/db_get.html">DB->get</a>), the memory to which the -pointer stored into the <a href="../../api_c/dbt_class.html">DBT</a> refers is only valid until the next -call to Berkeley DB using the <a href="../../api_c/db_class.html">DB</a> handle. (This includes <b>any</b> -use of the returned <a href="../../api_c/db_class.html">DB</a> handle, including by another thread of -control within the process. For this reason, when multiple threads are -using the returned <a href="../../api_c/db_class.html">DB</a> handle concurrently, one of the -<a href="../../api_c/dbt_class.html#DB_DBT_MALLOC">DB_DBT_MALLOC</a>, <a href="../../api_c/dbt_class.html#DB_DBT_REALLOC">DB_DBT_REALLOC</a> or <a href="../../api_c/dbt_class.html#DB_DBT_USERMEM">DB_DBT_USERMEM</a> -flags must be specified with any non-cursor <a href="../../api_c/dbt_class.html">DBT</a> used for key or -data retrieval.) -<p>When using the cursor Berkeley DB calls to retrieve key/data items under the -C/C++ APIs (for example, <a href="../../api_c/dbc_get.html">DBcursor->c_get</a>), the memory to which the -pointer stored into the <a href="../../api_c/dbt_class.html">DBT</a> refers is only valid until the next -call to Berkeley DB using the <a href="../../api_c/dbc_class.html">DBC</a> handle returned by <a href="../../api_c/db_cursor.html">DB->cursor</a>. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/am_misc/struct.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/am_misc/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> diff --git a/libdb/docs/ref/am_misc/stability.html b/libdb/docs/ref/am_misc/stability.html deleted file mode 100644 index 8d9587d7f..000000000 --- a/libdb/docs/ref/am_misc/stability.html +++ /dev/null @@ -1,55 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Access Methods</dl></h3></td> -<td align=right><a href="../../ref/am_misc/error.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/am_misc/dbsizes.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 threads of control. However, the Btree, Queue -and Recno access methods guarantee that cursor operations, interspersed -with any other operation 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 transactional locking is performed. -<p>If locking was specified when the Berkeley DB environment 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. -<a name="4"><!--meow--></a><a name="5"><!--meow--></a> -<p>In the presence of transactions, the Btree, Hash and Recno access -methods provide degree 3 isolation (serializable transactions). The -Queue access method provides degree 3 isolation with the exception that -it 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. For -readers not enclosed in transactions, all access method calls provide -degree 2 isolation, that is, reads are not repeatable. Finally, Berkeley DB -provides degree 1 isolation when the <a href="../../api_c/db_open.html#DB_DIRTY_READ">DB_DIRTY_READ</a> flag is -specified; that is, reads may see data modified in transactions which -have not yet committed. -<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 width="100%"><tr><td><br></td><td align=right><a href="../../ref/am_misc/error.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/am_misc/dbsizes.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/libdb/docs/ref/am_misc/struct.html b/libdb/docs/ref/am_misc/struct.html deleted file mode 100644 index 6ea058236..000000000 --- a/libdb/docs/ref/am_misc/struct.html +++ /dev/null @@ -1,88 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Storing C/C++ structures/objects</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Access Methods</dl></h3></td> -<td align=right><a href="../../ref/am_misc/partial.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/am_misc/perm.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Storing C/C++ structures/objects</h1> -<p>Berkeley DB can store any kind of data, that is, it is entirely 8-bit clean. -How you use this depends, to some extent, on the application language -you are using. In the C/C++ languages, there are a couple of different -ways to store structures and objects. -<p>First, you can do some form of run-length encoding and copy your -structure into another piece of memory before storing it: -<p><blockquote><pre>struct { - char *data1; - u_int32_t data2; - ... -} info; -size_t len; -u_int8_t *p, data_buffer[1024]; -<p> -p = &data_buffer[0]; -len = strlen(info.data1); -memcpy(p, &len, sizeof(len)); -p += sizeof(len); -memcpy(p, info.data1, len); -p += len; -memcpy(p, &info.data2, sizeof(info.data2)); -p += sizeof(info.data2); -...</pre></blockquote> -<p>and so on, until all the fields of the structure have been loaded into -the byte array. If you want more examples, see the Berkeley DB logging -routines (for example, btree/btree_auto.c:__bam_split_log()). This -technique is generally known as "marshalling". If you use this -technique, you must then un-marshall the data when you read it back: -<p><blockquote><pre>struct { - char *data1; - u_int32_t data2; - ... -} info; -size_t len; -u_int8_t *p; -<p> -p = &data_buffer[0]; -memcpy(&len, p, sizeof(len)); -p += sizeof(len); -info.data1 = malloc(len); -memcpy(info.data1, p, len); -p += len; -memcpy(&info.data2, p, sizeof(info.data2)); -p += sizeof(info.data2); -...</pre></blockquote> -<p>and so on. -<p>The second way to solve this problem only works if you have just one -variable length field in the structure. In that case, you can declare -the structure as follows: -<p><blockquote><pre>struct { - int a, b, c; - u_int8_t buf[1]; -} info;</pre></blockquote> -<p>Then, let's say you have a string you want to store in this structure. -When you allocate the structure, you allocate it as: -<p><blockquote><pre>malloc(sizeof(struct info) + strlen(string));</pre></blockquote> -<p>Since the allocated memory is contiguous, you can the initialize the -structure as: -<p><blockquote><pre>info.a = 1; -info.b = 2; -info.c = 3; -memcpy(&info.buf[0], string, strlen(string));</pre></blockquote> -<p>and give it to Berkeley DB to store, with a length of: -<p><blockquote><pre>sizeof(struct info) + strlen(string);</pre></blockquote> -<p>In this case, the structure can be copied out of the database and used -without any additional work. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/am_misc/partial.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/am_misc/perm.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/libdb/docs/ref/am_misc/tune.html b/libdb/docs/ref/am_misc/tune.html deleted file mode 100644 index 8abe33ed8..000000000 --- a/libdb/docs/ref/am_misc/tune.html +++ /dev/null @@ -1,85 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Access method tuning</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Access Methods</dl></h3></td> -<td align=right><a href="../../ref/am_misc/diskspace.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/am_misc/faq.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Access method tuning</h1> -<p>There are a few different issues to consider when tuning the performance -of Berkeley DB access method applications. -<p><dl compact> -<p><dt>access method<dd>An application's choice of a database access method can significantly -affect performance. Applications using fixed-length records and integer -keys are likely to get better performance from the Queue access method. -Applications using variable-length records are likely to get better -performance from the Btree access method, as it tends to be faster for -most applications than either the Hash or Recno access methods. Because -the access method APIs are largely identical between the Berkeley DB access -methods, it is easy for applications to benchmark the different access -methods against each other. See <a href="../../ref/am_conf/select.html">Selecting an access method</a> for more information. -<p><dt>cache size<dd>The Berkeley DB database cache defaults to a fairly small size, and most -applications concerned with performance will want to set it explicitly. -Using a too-small cache will result in horrible performance. The first -step in tuning the cache size is to use the db_stat utility (or the -statistics returned by the <a href="../../api_c/db_stat.html">DB->stat</a> function) to measure the -effectiveness of the cache. The goal is to maximize the cache's hit -rate. Typically, increasing the size of the cache until the hit rate -reaches 100% or levels off will yield the best performance. However, -if your working set is sufficiently large, you will be limited by the -system's available physical memory. Depending on the virtual memory -and file system buffering policies of your system, and the requirements -of other applications, the maximum cache size will be some amount -smaller than the size of physical memory. If you find that -<a href="../../utility/db_stat.html">db_stat</a> shows that increasing the cache size improves your hit -rate, but performance is not improving (or is getting worse), then it's -likely you've hit other system limitations. At this point, you should -review the system's swapping/paging activity and limit the size of the -cache to the maximum size possible without triggering paging activity. -Finally, always remember to make your measurements under conditions as -close as possible to the conditions your deployed application will run -under, and to test your final choices under worst-case conditions. -<p><dt>shared memory<dd>By default, Berkeley DB creates its database environment shared regions in -filesystem backed memory. Some systems do not distinguish between -regular filesystem pages and memory-mapped pages backed by the -filesystem, when selecting dirty pages to be flushed back to disk. For -this reason, dirtying pages in the Berkeley DB cache may cause intense -filesystem activity, typically when the filesystem sync thread or -process is run. In some cases, this can dramatically affect application -throughput. The workaround to this problem is to create the shared -regions in system shared memory (<a href="../../api_c/env_open.html#DB_SYSTEM_MEM">DB_SYSTEM_MEM</a>) or in -application private memory (<a href="../../api_c/env_open.html#DB_PRIVATE">DB_PRIVATE</a>). -<p><dt>large key/data items<dd>Storing large key/data items in a database can alter the performance -characteristics of Btree, Hash and Recno databases. The first parameter -to consider is the database page size. When a key/data item is too -large to be placed on a database page, it is stored on "overflow" pages -that are maintained outside of the normal database structure (typically, -items that are larger than one-quarter of the page size are deemed to -be too large). Accessing these overflow pages requires at least one -additional page reference over a normal access, so it is usually better -to increase the page size than to create a database with a large number -of overflow pages. Use the <a href="../../utility/db_stat.html">db_stat</a> utility (or the statistics -returned by the <a href="../../api_c/db_stat.html">DB->stat</a> method) to review the number of overflow -pages in the database. -<p>The second issue is using large key/data items instead of duplicate data -items. While this can offer performance gains to some applications -(because it is possible to retrieve several data items in a single get -call), once the key/data items are large enough to be pushed off-page, -they will slow the application down. Using duplicate data items is -usually the better choice in the long run. -</dl> -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/am_misc/diskspace.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/am_misc/faq.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/libdb/docs/ref/apprec/auto.html b/libdb/docs/ref/apprec/auto.html deleted file mode 100644 index 567cb13f7..000000000 --- a/libdb/docs/ref/apprec/auto.html +++ /dev/null @@ -1,159 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Automatically generated functions</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Application Specific Logging and Recovery</dl></h3></td> -<td align=right><a href="../../ref/apprec/def.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/apprec/config.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Automatically generated functions</h1> -<p>The XXX.src file is processed using the gen_rec.awk script included in -the dist directory of the Berkeley DB distribution. This is an awk script -that is executed from with the following command line: -<p><blockquote><pre>awk -f gen_rec.awk \ - -v source_file=<i>C_FILE</i> \ - -v header_file=<i>H_FILE</i> \ - -v template_file=<i>TMP_FILE</i> < XXX.src</pre></blockquote> -<p>where <i>C_FILE</i> is the name of the file into which to place the -automatically generated C code, <i>H_FILE</i> is the name of the -file into which to place the automatically generated data structures -and declarations, and <i>TMP_FILE</i> is the name of the file into -which to place a template for the recovery routines. -<p>Because the gen_rec.awk script uses sources files located relative to -the Berkeley DB dist directory, it must be run from the dist directory. For -example, in building the Berkeley DB logging and recovery routines for -ex_apprec, the following script is used to rebuild the automatically -generated files: -<p><blockquote><pre>E=../examples_c/ex_apprec -<p> -cd ../../dist -awk -f gen_rec.awk \ - -v source_file=$E/ex_apprec_auto.c \ - -v header_file=$E/ex_apprec_auto.h \ - -v template_file=$E/ex_apprec_template < $E/ex_apprec.src</pre></blockquote> -<p>For each log record description found in the XXX.src file, the following -structure declarations and #defines will be created in the file -<i>header_file</i>: -<p><blockquote><pre>#define DB_PREFIX_RECORD_TYPE /* Integer ID number */ -<p> -typedef struct _PREFIX_RECORD_TYPE_args { - /* - * These three fields are generated for every record. - */ - u_int32_t type; /* Record type used for dispatch. */ -<p> - /* - * Transaction handle that identifies the transaction on whose - * behalf the record is being logged. - */ - DB_TXN *txnid; -<p> - /* - * The log sequence number returned by the previous call to log_put - * for this transaction. - */ - DB_LSN *prev_lsn; -<p> - /* - * The rest of the structure contains one field for each of - * the entries in the record statement. - */ -};</pre></blockquote> -<p>Thus, the auto-generated ex_apprec_mkdir_args structure looks as follows: -<p><blockquote><pre>typedef struct _ex_apprec_mkdir_args { - u_int32_t type; - DB_TXN *txnid; - DB_LSN prev_lsn; - DBT dirname; -} ex_apprec_mkdir_args;</pre></blockquote> -<p>The template_file will contain a template for a recovery function. The -recovery function is called on each record read from the log during -system recovery, transaction abort, or the application of log records -on a replication client, and is expected to redo or undo the operations -described by that record. The details of the recovery function will be -specific to the record being logged and need to be written manually, -but the template provides a good starting point. (Note that the -template assumes that the record is manipulating the internals of a -Berkeley DB database and sets up database handles, page structures, and such -for convenience. Many application-specific log records will not need -these, and may simply delete much of the template. See -ex_apprec_template and ex_apprec_rec.c for an example.) -<p>The template file should be copied to a source file in the application -(but not the automatically generated source_file, as that will get -overwritten each time gen_rec.awk is run) and fully developed there. -The recovery function takes the following parameters: -<p><blockquote><p><dl compact> -<p><dt>dbenv<dd>The environment in which recovery is running. -<p><dt>rec<dd>The record being recovered. -<p><dt>lsn<dd>The log sequence number of the record being recovered. The -prev_lsn field, automatically included in every auto-generated log -record, should be returned through this argument. The prev_lsn field -is used to chain log records together to allow transaction aborts; -because the recovery function is the only place that a log record gets -parsed, the responsibility for returning this value lies with the -recovery function writer. -<p><dt>op<dd>A parameter of type db_recops, which indicates what operation is being -run (<a href="../../api_c/env_set_app_dispatch.html#DB_TXN_ABORT">DB_TXN_ABORT</a>, <a href="../../api_c/env_set_app_dispatch.html#DB_TXN_APPLY">DB_TXN_APPLY</a>, <a href="../../api_c/env_set_app_dispatch.html#DB_TXN_BACKWARD_ROLL">DB_TXN_BACKWARD_ROLL</a>, -<a href="../../api_c/env_set_app_dispatch.html#DB_TXN_FORWARD_ROLL">DB_TXN_FORWARD_ROLL</a> or <a href="../../api_c/env_set_app_dispatch.html#DB_TXN_PRINT">DB_TXN_PRINT</a>). -<p><dt>info<dd>A structure passed by the dispatch function. It is used to contain a -list of committed transactions and information about files that may have -been deleted. Application-specific log records can usually simply -ignore this field. -</dl></blockquote> -<p>In addition to the header_file and template_file, a source_file is -created, containing a log, read, recovery, and print function for each -record type. -<p>The log function marshalls the parameters into a buffer, and calls -<a href="../../api_c/log_put.html">DB_ENV->log_put</a> on that buffer returning 0 on success and non-zero on -failure. The log function takes the following parameters: -<p><blockquote><p><dl compact> -<p><dt>dbenv<dd>The environment in which recovery is running. -<p><dt>txnid<dd>The transaction identifier for the transaction handle returned by -<a href="../../api_c/txn_begin.html">DB_ENV->txn_begin</a>. -<p><dt>lsnp<dd>A pointer to storage for a log sequence number into which the log -sequence number of the new log record will be returned. -<p><dt>syncflag<dd>A flag indicating whether the record must be written synchronously. -Valid values are 0 and <a href="../../api_c/log_put.html#DB_FLUSH">DB_FLUSH</a>. -<p><dt>args<dd>The remaining parameters to the log message are the fields described -in the XXX.src file, in order. -</dl></blockquote> -<p>The read function takes a buffer and unmarshalls its contents into a -structure of the appropriate type. It returns 0 on success and non-zero -on error. After the fields of the structure have been used, the pointer -returned from the read function should be freed. The read function -takes the following parameters: -<p><blockquote><p><dl compact> -<p><dt>dbenv<dd>The environment in which recovery is running. -<p><dt>recbuf<dd>A buffer. -<p><dt>argp<dd>A pointer to a structure of the appropriate type. -</dl></blockquote> -<p>The print function displays the contents of the record. The print -function takes the same parameters as the recovery function described -previously. Although some of the parameters are unused by the print -function, taking the same parameters allows a single dispatch loop to -dispatch to a variety of functions. The print function takes the -following parameters: -<p><blockquote><p><dl compact> -<p><dt>dbenv<dd>The environment in which recovery is running. -<p><dt>rec<dd>The record being recovered. -<p><dt>lsn<dd>The log sequence number of the record being recovered. -<p><dt>op<dd>Unused. -<p><dt>info<dd>Unused. -</dl></blockquote> -<p>Finally, the source file will contain a function (named XXX_init_print, -where XXX is replaced by the prefix) which should be added to the -initialization part of the standalone <a href="../../utility/db_printlog.html">db_printlog</a> utility code -so that utility can be used to display application-specific log records. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/apprec/def.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/apprec/config.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/libdb/docs/ref/apprec/config.html b/libdb/docs/ref/apprec/config.html deleted file mode 100644 index 29c9f9d07..000000000 --- a/libdb/docs/ref/apprec/config.html +++ /dev/null @@ -1,128 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Application configuration</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Application Specific Logging and Recovery</dl></h3></td> -<td align=right><a href="../../ref/apprec/auto.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/program/appsignals.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Application configuration</h1> -<p>The application should include a dispatch function that dispatches to -appropriate printing and/or recovery functions based on the log record -type and the operation code. The dispatch function should take the same -arguments as the recovery function, and should call the appropriate -recovery and/or printing functions based on the log record type and the -operation code. For example, the ex_apprec dispatch function is as -follows: -<p><blockquote><pre>int -apprec_dispatch(dbenv, dbt, lsn, op) - DB_ENV *dbenv; - DBT *dbt; - DB_LSN *lsn; - db_recops op; -{ - u_int32_t rectype; - /* Pull the record type out of the log record. */ - memcpy(&rectype, dbt->data, sizeof(rectype)); - switch (rectype) { - case DB_ex_apprec_mkdir: - return (ex_apprec_mkdir_recover(dbenv, dbt, lsn, op, NULL)); - default: - /* - * We've hit an unexpected, allegedly user-defined record - * type. - */ - dbenv->errx(dbenv, "Unexpected log record type encountered"); - return (EINVAL); - } -} -</pre></blockquote> -<p>Applications use this dispatch function and the automatically generated -functions as follows: -<p><ol> -<p><li>When the application starts, call the <a href="../../api_c/env_set_app_dispatch.html">DB_ENV->set_app_dispatch</a> -with your dispatch function. -<p><li>Issue a <a href="../../api_c/txn_begin.html">DB_ENV->txn_begin</a> call before any operations you want to be -transaction-protected. -<p><li>Before accessing any data, issue the appropriate lock call to lock the -data (either for reading or writing). -<p><li>Before modifying any data that is transaction-protected, issue a call -to the appropriate log function. -<p><li>Call <a href="../../api_c/txn_commit.html">DB_TXN->commit</a> to save all the changes, or call <a href="../../api_c/txn_abort.html">DB_TXN->abort</a> -to cancel all of the modifications. -</ol> -<p>The recovery functions are called in the three following cases: -<p><ol> -<p><li>During recovery after application or system failure, with op set to -<a href="../../api_c/env_set_app_dispatch.html#DB_TXN_FORWARD_ROLL">DB_TXN_FORWARD_ROLL</a> or <a href="../../api_c/env_set_app_dispatch.html#DB_TXN_BACKWARD_ROLL">DB_TXN_BACKWARD_ROLL</a>. -<p><li>During transaction abort, with op set to <a href="../../api_c/env_set_app_dispatch.html#DB_TXN_ABORT">DB_TXN_ABORT</a>. -<p><li>On a replicated client to apply updates from the master, with op set to -<a href="../../api_c/env_set_app_dispatch.html#DB_TXN_APPLY">DB_TXN_APPLY</a>. -</ol> -<p>For each log record type you declare, you must write the appropriate -function to undo and redo the modifications. The shell of these -functions will be generated for you automatically, but you must fill in -the details. -<p>Your code must be able to detect whether the described modifications -have been applied to the data. The function will be called with the -"op" parameter set to <a href="../../api_c/env_set_app_dispatch.html#DB_TXN_ABORT">DB_TXN_ABORT</a> when a transaction that wrote -the log record aborts, with <a href="../../api_c/env_set_app_dispatch.html#DB_TXN_FORWARD_ROLL">DB_TXN_FORWARD_ROLL</a> and -<a href="../../api_c/env_set_app_dispatch.html#DB_TXN_BACKWARD_ROLL">DB_TXN_BACKWARD_ROLL</a> during recovery, and with <a href="../../api_c/env_set_app_dispatch.html#DB_TXN_APPLY">DB_TXN_APPLY</a> -on a replicated client. -<p>The actions for <a href="../../api_c/env_set_app_dispatch.html#DB_TXN_ABORT">DB_TXN_ABORT</a> and <a href="../../api_c/env_set_app_dispatch.html#DB_TXN_BACKWARD_ROLL">DB_TXN_BACKWARD_ROLL</a> -should generally be the same, and the actions for -<a href="../../api_c/env_set_app_dispatch.html#DB_TXN_FORWARD_ROLL">DB_TXN_FORWARD_ROLL</a> and <a href="../../api_c/env_set_app_dispatch.html#DB_TXN_APPLY">DB_TXN_APPLY</a> should generally -be the same. However, if the application is using Berkeley DB replication -and another thread of control may be performing read operations while -log records are applied on a replication client, the recovery function -should perform appropriate locking during <a href="../../api_c/env_set_app_dispatch.html#DB_TXN_APPLY">DB_TXN_APPLY</a> -operations. In this case, the recovery function may encounter deadlocks -when issuing locking calls. The application should run with the -deadlock detector, and the recovery function should simply return -<a href="../../ref/program/errorret.html#DB_LOCK_DEADLOCK">DB_LOCK_DEADLOCK</a> if a deadlock is detected and a locking -operation fails with that error. -<p>The <a href="../../api_c/env_set_app_dispatch.html#DB_TXN_PRINT">DB_TXN_PRINT</a> operation should print the log record, -typically using the auto-generated print function; it is not used in -the Berkeley DB library, but may be useful for debugging, as in the -<a href="../../utility/db_printlog.html">db_printlog</a> utility. Applications may safely ignore this -operation code, they may handle printing from the recovery function, or -they may dispatch directly to the auto-generated print function. -<p>One common way to determine whether operations need to be undone or -redone is the use of log sequence numbers (LSNs). For example, each -access method database page contains the LSN of the most recent log -record that describes a modification to the page. When the access -method changes a page, it writes a log record describing the change and -including the LSN that was on the page before the change. This LSN is -referred to as the previous LSN. The recovery functions read the page -described by a log record, and compare the LSN on the page to the LSN -they were passed. -<p>If the page LSN is less than the passed LSN and the operation is an -undo, no action is necessary (because the modifications have not been -written to the page). If the page LSN is the same as the previous LSN -and the operation is a redo, the actions described are reapplied to the -page. If the page LSN is equal to the passed LSN and the operation is -an undo, the actions are removed from the page; if the page LSN is -greater than the passed LSN and the operation is a redo, no further -action is necessary. If the action is a redo and the LSN on the page -is less than the previous LSN in the log record, it is an error because -it could happen only if some previous log record was not processed. -<p>Examples of other recovery functions can be found in the Berkeley DB library -recovery functions (found in files named XXX_rec.c) and in the -application-specific recovery example (specifically, ex_apprec_rec.c). -<p>Finally, applications need to ensure that any data modifications they -have made, that were part of a committed transaction, must be written -to stable storage before calling the <a href="../../api_c/txn_checkpoint.html">DB_ENV->txn_checkpoint</a> method. This is -to allow the periodic removal of database environment log files. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/apprec/auto.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/program/appsignals.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/libdb/docs/ref/apprec/def.html b/libdb/docs/ref/apprec/def.html deleted file mode 100644 index 8ff5da64a..000000000 --- a/libdb/docs/ref/apprec/def.html +++ /dev/null @@ -1,96 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Defining application-specific log 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> -<table width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Application Specific Logging and Recovery</dl></h3></td> -<td align=right><a href="../../ref/apprec/intro.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/apprec/auto.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Defining application-specific log records</h1> -<p>By convention, log records are described in files named <b>XXX.src</b>, -where "XXX" is typically a descriptive name for a subsystem or other -logical group of logging functions. These files contain interface -definition language descriptions for each type of log record that is -used by the subsystem. -<p>All blank lines and lines beginning with a hash ("#") character in -the XXX.src files are ignored. -<p>The first non-comment line in the file should begin with the keyword -PREFIX, followed by a string that will be prepended to every generated -function name. Frequently, the PREFIX is either identical or similar -to the name of the <b>XXX.src</b> file. For example, the Berkeley DB -application-specific recovery example uses the file -<b>ex_apprec.src</b>, which begins with the following PREFIX line: -<p><blockquote><pre>PREFIX ex_apprec</pre></blockquote> -<p>Following the PREFIX line are the include files required by the -automatically generated functions. The include files should be listed -in order, prefixed by the keyword INCLUDE. For example, the Berkeley DB -application-specific recovery example lists the following include -files: -<p><blockquote><pre>INCLUDE #include <ctype.h> -INCLUDE #include <errno.h> -INCLUDE #include <stdlib.h> -INCLUDE #include <string.h> -INCLUDE -INCLUDE #include <db.h> -INCLUDE -INCLUDE #include "ex_apprec.h"</pre></blockquote> -<p>The rest of the XXX.src file consists of log record descriptions. Each -log record description begins with the line: -<p><blockquote><pre>BEGIN <i>RECORD_NAME</i> <i>RECORD_NUMBER</i></pre></blockquote> -<p>and ends with the line: -<p><blockquote><pre>END</pre></blockquote> -<p>The <i>RECORD_NAME</i> variable should be replaced with a record -name for this log record. The <i>RECORD_NUMBER</i> variable should -be replaced with a record number. -<p>The combination of PREFIX name and <i>RECORD_NAME</i>, and the -<i>RECORD_NUMBER</i> must be unique for the application, that is, -values for application-specific and Berkeley DB log records may not overlap. -Further, because record numbers are stored in log files, which are -usually portable across application and Berkeley DB releases, any change to -the record numbers or log record format or should be handled as -described in the <a href="../../ref/upgrade/process.html">Upgrading Berkeley DB -installations</a> section on log format changes. The record number space -below 10,000 is reserved for Berkeley DB itself; applications should choose -record number values equal to or greater than 10,000. -<p>Between the BEGIN and END keywords there should be one line for each -data item logged as part of this log record. The format of these lines -is as follows: -<p><blockquote><pre>ARG | DBT | POINTER <i>variable_name</i> <i>variable_type</i> <i>printf_format</i></pre></blockquote> -<p>The keyword ARG indicates that the argument is a simple parameter of -the type specified. For example, a file ID might be logged as: -<p><blockquote><pre>ARG fileID int d</pre></blockquote> -<p>The keyword DBT indicates that the argument is a Berkeley DB DBT structure, -containing a length and pointer to a byte string. The keyword POINTER -indicates that the argument is a pointer to the data type specified (of -course the data type, not the pointer, is what is logged). -<p>The <i>variable_name</i> is the field name within the structure that -will be used to refer to this item. The <i>variable_type</i> is -the C-language type of the variable, and the printf format is the -C-language format string, without the leading percent ("%") character, -that should be used to display the contents of the field (for example, -"s" for string, "d" for signed integral type, "u" for unsigned integral -type, "ld" for signed long integral type, "lu" for long unsigned -integral type, and so on). -<p>For example, ex_apprec.src defines a single log record type, used to -log a directory name that has been stored in a DBT: -<p><blockquote><pre>BEGIN mkdir 10000 -DBT dirname DBT s -END</pre></blockquote> -<p>As the name suggests, this example of an application-defined log record -will be used to log the creation of a directory. There are many more -examples of XXX.src files in the Berkeley DB distribution. For example, the -file btree/btree.src contains the definitions for the log records -supported by the Berkeley DB Btree access method. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/apprec/intro.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/apprec/auto.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/libdb/docs/ref/apprec/intro.html b/libdb/docs/ref/apprec/intro.html deleted file mode 100644 index 7561ef667..000000000 --- a/libdb/docs/ref/apprec/intro.html +++ /dev/null @@ -1,77 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Introduction</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Application Specific Logging and Recovery</dl></h3></td> -<td align=right><a href="../../ref/xa/faq.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/apprec/def.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Introduction</h1> -<p>It is possible to use the Locking, Logging and Transaction subsystems -of Berkeley DB to provide transaction semantics on objects other than those -described by the Berkeley DB access methods. In these cases, the application -will need application-specific logging and recovery functions. -<p>For example, consider an application that provides transaction semantics -on data stored in plain text files accessed using the POSIX read and -write system calls. The read and write operations for which transaction -protection is desired will be bracketed by calls to the standard Berkeley DB -transactional interfaces, <a href="../../api_c/txn_begin.html">DB_ENV->txn_begin</a> and <a href="../../api_c/txn_commit.html">DB_TXN->commit</a>, and -the transaction's locker ID will be used to acquire relevant read and -write locks. -<p>Before data is accessed, the application must make a call to the lock -manager, <a href="../../api_c/lock_get.html">DB_ENV->lock_get</a>, for a lock of the appropriate type (for -example, read) on the object being locked. The object might be a page -in the file, a byte, a range of bytes, or some key. It is up to the -application to ensure that appropriate locks are acquired. Before a -write is performed, the application should acquire a write lock on the -object by making an appropriate call to the lock manager, -<a href="../../api_c/lock_get.html">DB_ENV->lock_get</a>. Then, the application should make a call to the log -manager, <a href="../../api_c/log_put.html">DB_ENV->log_put</a>, to record enough information to redo the -operation in case of failure after commit and to undo the operation in -case of abort. -<p>When designing applications that will use the log subsystem, it is -important to remember that the application is responsible for providing -any necessary structure to the log record. For example, the application -must understand what part of the log record is an operation code, what -part identifies the file being modified, what part is redo information, -and what part is undo information. -<p>After the log message is written, the application may issue the write -system call. After all requests are issued, the application may call -<a href="../../api_c/txn_commit.html">DB_TXN->commit</a>. When <a href="../../api_c/txn_commit.html">DB_TXN->commit</a> returns, the caller is -guaranteed that all necessary log writes have been written to disk. -<p>At any time before issuing a <a href="../../api_c/txn_commit.html">DB_TXN->commit</a>, -the application may call <a href="../../api_c/txn_abort.html">DB_TXN->abort</a>, which will -result in restoration of the database to a consistent pretransaction -state. (The application may specify its own recovery function for this -purpose using the <a href="../../api_c/env_set_app_dispatch.html">DB_ENV->set_app_dispatch</a> method. The recovery -function must be able to either reapply or undo the update depending on -the context, for each different type of log record.) -<p>If the application crashes, the recovery process uses the log to restore -the database to a consistent state. -<p>Berkeley DB includes tools to assist in the development of application-specific -logging and recovery. Specifically, given a description of information -to be logged in a family of log records, these tools will automatically -create log-writing functions (functions that marshall their arguments -into a single log record), log-reading functions (functions that read -a log record and unmarshall it into a structure containing fields that -map into the arguments written to the log), log-printing functions -(functions that print the contents of a log record for debugging), and -templates for recovery functions (functions that review log records -during transaction abort or recovery). The tools and generated code -are C-language and POSIX-system based, but the generated code should be -usable on any system, not just POSIX systems. -<p>A sample application that does application-specific recovery is included -in the Berkeley DB distribution, in the directory <b>examples_c/ex_apprec</b>. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/xa/faq.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/apprec/def.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/libdb/docs/ref/arch/apis.html b/libdb/docs/ref/arch/apis.html deleted file mode 100644 index 771ceeb3b..000000000 --- a/libdb/docs/ref/arch/apis.html +++ /dev/null @@ -1,77 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Programmatic APIs</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Architecture</dl></h3></td> -<td align=right><a href="../../ref/arch/progmodel.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/arch/script.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Programmatic APIs</h1> -<p>The Berkeley DB subsystems can be accessed through interfaces from multiple -languages. The standard library interface is ANSI C. Applications can -also use Berkeley DB via C++ or Java, as well as from scripting languages. -Environments can be shared among applications written by using any of -theses APIs. For example, you might have a local server written in C -or C++, a script for an administrator written in Perl or Tcl, and a -Web-based user interface written in Java -- all sharing a single -database environment. -<h3>C</h3> -<p>The Berkeley DB library is written entirely in ANSI C. C applications use a -single include file: -<p><blockquote><pre>#include <db.h></pre></blockquote> -<h3>C++</h3> -<p>The C++ classes provide a thin wrapper around the C API, with the major -advantages being improved encapsulation and an optional exception -mechanism for errors. C++ applications use a single include file: -<p><blockquote><pre>#include <db_cxx.h></pre></blockquote> -<p>The classes and methods are named in a fashion that directly corresponds -to structures and functions in the C interface. Likewise, arguments to -methods appear in the same order as the C interface, except to remove the -explicit <b>this</b> pointer. The #defines used for flags are identical -between the C and C++ interfaces. -<p>As a rule, each C++ object has exactly one structure from the underlying -C API associated with it. The C structure is allocated with each -constructor call and deallocated with each destructor call. Thus, the -rules the user needs to follow in allocating and deallocating structures -are the same between the C and C++ interfaces. -<p>To ensure portability to many platforms, both new and old, Berkeley DB makes -as few assumptions as possible about the C++ compiler and library. For -example, it does not expect STL, templates, or namespaces to be -available. The newest C++ feature used is exceptions, which are used -liberally to transmit error information. Even the use of exceptions -can be disabled at runtime. -<h3>Java</h3> -<p>The Java classes provide a layer around the C API that is almost identical -to the C++ layer. The classes and methods are, for the most part -identical to the C++ layer. Berkeley DB constants and #defines are represented as -"static final int" values. Error conditions are communicated as Java -exceptions. -<p>As in C++, each Java object has exactly one structure from the underlying -C API associated with it. The Java structure is allocated with each -constructor or open call, but is deallocated only by the Java garbage -collector. Because the timing of garbage collection is not predictable, -applications should take care to do a close when finished with any object -that has a close method. -<h3>Dbm/Ndbm, Hsearch</h3> -<p>Berkeley DB supports the standard UNIX interfaces <a href="../../api_c/dbm.html">dbm</a>, <a href="../../api_c/dbm.html">ndbm</a>, -and <a href="../../api_c/hsearch.html">hsearch</a>. After including a new header file and recompiling, -programs will run orders of magnitude faster, and underlying databases -can grow as large as necessary. Also, historic <a href="../../api_c/dbm.html">dbm</a> and -<a href="../../api_c/dbm.html">ndbm</a> applications can fail once some number of entries are -inserted into the database, in which the number depends on the -effectiveness of the internal hashing function on the particular data -set. This is not a problem with Berkeley DB. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/arch/progmodel.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/arch/script.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/libdb/docs/ref/arch/bigpic.gif b/libdb/docs/ref/arch/bigpic.gif Binary files differdeleted file mode 100644 index 48c52aed5..000000000 --- a/libdb/docs/ref/arch/bigpic.gif +++ /dev/null diff --git a/libdb/docs/ref/arch/bigpic.html b/libdb/docs/ref/arch/bigpic.html deleted file mode 100644 index 636d1d155..000000000 --- a/libdb/docs/ref/arch/bigpic.html +++ /dev/null @@ -1,125 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: The big picture</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Architecture</dl></h3></td> -<td align=right><a href="../../ref/am_misc/faq.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/arch/progmodel.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>The big picture</h1> -<p>The previous chapters in this Reference Guide have described -applications that use the Berkeley DB access methods for fast data storage -and retrieval. The applications described in the following chapters -are similar in nature to the access method applications, but they are -also threaded and/or recoverable in the face of application or system -failure. -<p>Application code that uses only the Berkeley DB access methods might appear -as follows: -<p><blockquote><pre>switch (ret = dbp->put(dbp, NULL, &key, &data, 0)) { -case 0: - printf("db: %s: key stored.\n", (char *)key.data); - break; -default: - dbp->err(dbp, ret, "dbp->put"); - exit (1); -}</pre></blockquote> -<p>The underlying Berkeley DB architecture that supports this is -<p align=center><img src="smallpic.gif" alt="small"> -<p>As you can see from this diagram, the application makes calls into the -access methods, and the access methods use the underlying shared memory -buffer cache to hold recently used file pages in main memory. -<p>When applications require recoverability, their calls to the Access -Methods must be wrapped in calls to the transaction subsystem. The -application must inform Berkeley DB where to begin and end transactions, and -must be prepared for the possibility that an operation may fail at any -particular time, causing the transaction to abort. -<p>An example of transaction-protected code might appear as follows: -<p><blockquote><pre>for (fail = 0;;) { - /* Begin the transaction. */ - if ((ret = dbenv->txn_begin(dbenv, NULL, &tid, 0)) != 0) { - dbenv->err(dbenv, ret, "dbenv->txn_begin"); - exit (1); - } -<p> - /* Store the key. */ - switch (ret = dbp->put(dbp, tid, &key, &data, 0)) { - case 0: - /* Success: commit the change. */ - printf("db: %s: key stored.\n", (char *)key.data); - if ((ret = tid->commit(tid, 0)) != 0) { - dbenv->err(dbenv, ret, "DB_TXN->commit"); - exit (1); - } - return (0); - case DB_LOCK_DEADLOCK: - default: - /* Failure: retry the operation. */ - if ((t_ret = tid->abort(tid)) != 0) { - dbenv->err(dbenv, t_ret, "DB_TXN->abort"); - exit (1); - } - if (++fail == MAXIMUM_RETRY) - return (ret); - continue; - } -}</pre></blockquote> -<p>In this example, the same operation is being done as before; however, -it is wrapped in transaction calls. The transaction is started with -<a href="../../api_c/txn_begin.html">DB_ENV->txn_begin</a> and finished with <a href="../../api_c/txn_commit.html">DB_TXN->commit</a>. If the -operation fails due to a deadlock, the transaction is aborted using -<a href="../../api_c/txn_abort.html">DB_TXN->abort</a>, after which the operation may be retried. -<p>There are actually five major subsystems in Berkeley DB, as follows: -<p><dl compact> -<p><dt>Access Methods<dd>The access methods subsystem provides general-purpose support for -creating and accessing database files formatted as Btrees, Hashed files, -and Fixed- and Variable-length records. These modules are useful in -the absence of transactions for applications that need fast formatted -file support. See <a href="../../api_c/db_open.html">DB->open</a> and <a href="../../api_c/db_cursor.html">DB->cursor</a> for more -information. These functions were already discussed in detail in the -previous chapters. -<p><dt>Memory Pool<dd>The Memory Pool subsystem is the general-purpose shared memory buffer pool -used by Berkeley DB. This is the shared memory cache that allows multiple -processes and threads within processes to share access to databases. This -module is useful outside of the Berkeley DB package for processes that require -portable, page-oriented, cached, shared file access. -<p><dt>Transaction<dd>The Transaction subsystem allows a group of database changes to be -treated as an atomic unit so that either all of the changes are done, -or none of the changes are done. The transaction subsystem implements -the Berkeley DB transaction model. This module is useful outside of the Berkeley DB -package for processes that want to transaction-protect their own data -modifications. -<p><dt>Locking<dd>The Locking subsystem is the general-purpose lock manager used by Berkeley DB. -This module is useful outside of the Berkeley DB package for processes that -require a portable, fast, configurable lock manager. -<p><dt>Logging<dd>The Logging subsystem is the write-ahead logging used to support the -Berkeley DB transaction model. It is largely specific to the Berkeley DB package, -and unlikely to be useful elsewhere except as a supporting module for -the Berkeley DB transaction subsystem. -</dl> -<p>Here is a more complete picture of the Berkeley DB library: -<p align=center><img src="bigpic.gif" alt="large"> -<p>In this model, the application makes calls to the access methods and to -the Transaction subsystem. The access methods and Transaction subsystems -in turn make calls into the Memory Pool, Locking and Logging subsystems -on behalf of the application. -<p>The underlying subsystems can be used independently by applications. -For example, the Memory Pool subsystem can be used apart from the rest -of Berkeley DB by applications simply wanting a shared memory buffer pool, or -the Locking subsystem may be called directly by applications that are -doing their own locking outside of Berkeley DB. However, this usage is not -common, and most applications will either use only the access methods -subsystem, or the access methods subsystem wrapped in calls to the Berkeley DB -transaction interfaces. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/am_misc/faq.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/arch/progmodel.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/libdb/docs/ref/arch/progmodel.html b/libdb/docs/ref/arch/progmodel.html deleted file mode 100644 index f8d30d052..000000000 --- a/libdb/docs/ref/arch/progmodel.html +++ /dev/null @@ -1,44 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Programming model</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Architecture</dl></h3></td> -<td align=right><a href="../../ref/arch/bigpic.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/arch/apis.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Programming model</h1> -<p>Berkeley DB is a database library, in which the library is linked into the -address space of the application using it. The code using Berkeley DB may be -a standalone application or it may be a server providing functionality -to many clients via inter-process or remote-process communication -(IPC/RPC). -<p>In the standalone application model, one or more applications link the -Berkeley DB library directly into their address spaces. There may be many -threads of control in this model because Berkeley DB supports locking for both -multiple processes and for multiple threads within a process. This -model provides significantly faster access to the database -functionality, but implies trust among all threads of control sharing -the database environment because they will have the ability to read, -write and potentially corrupt each other's data. -<p>In the client-server model, developers write a database server -application that accepts requests via some form of IPC/RPC, and issues -calls to the Berkeley DB interfaces based on those requests. In this model, -the database server is the only application linking the Berkeley DB library -into its address space. The client-server model trades performance for -protection because it does not require that the applications share a -protection domain with the server, but IPC/RPC is slower than a function -call. Of course, this model also greatly simplifies the creation of -network client-server applications. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/arch/bigpic.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/arch/apis.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/libdb/docs/ref/arch/script.html b/libdb/docs/ref/arch/script.html deleted file mode 100644 index 089a89e39..000000000 --- a/libdb/docs/ref/arch/script.html +++ /dev/null @@ -1,32 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Scripting languages</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Architecture</dl></h3></td> -<td align=right><a href="../../ref/arch/apis.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/arch/utilities.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Scripting languages</h1> -<h3>Perl</h3> -<p>Two Perl APIs are distributed with the Berkeley DB release. The Perl -interface to Berkeley DB version 1.85 is called DB_File. The Perl interface -to Berkeley DB version 2 and later is called BerkeleyDB. See -<a href="../../ref/perl/intro.html">Using Berkeley DB with Perl</a> for more -information. -<h3>Tcl</h3> -<p>A Tcl API is distributed with the Berkeley DB release. See -<a href="../../ref/tcl/intro.html">Using Berkeley DB with Tcl</a> for more -information. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/arch/apis.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/arch/utilities.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/libdb/docs/ref/arch/smallpic.gif b/libdb/docs/ref/arch/smallpic.gif Binary files differdeleted file mode 100644 index 5eb7ae8da..000000000 --- a/libdb/docs/ref/arch/smallpic.gif +++ /dev/null diff --git a/libdb/docs/ref/arch/utilities.html b/libdb/docs/ref/arch/utilities.html deleted file mode 100644 index af8798c6c..000000000 --- a/libdb/docs/ref/arch/utilities.html +++ /dev/null @@ -1,64 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Supporting utilities</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Architecture</dl></h3></td> -<td align=right><a href="../../ref/arch/script.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/env/intro.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Supporting utilities</h1> -<p>The following are the standalone utilities that provide supporting -functionality for the Berkeley DB environment: -<p><dl compact> -<p><dt><a href="../../utility/berkeley_db_svc.html">berkeley_db_svc</a><dd>The <a href="../../utility/berkeley_db_svc.html">berkeley_db_svc</a> utility is the Berkeley DB RPC server that -provides standard server functionality for client applications. -<p><dt><a href="../../utility/db_archive.html">db_archive</a><dd>The <a href="../../utility/db_archive.html">db_archive</a> utility supports database backup and archival, -and log file administration. It facilitates log reclamation and the -creation of database snapshots. Generally, some form of log archival -must be done if a database environment has been configured for logging -or transactions. -<p><dt><a href="../../utility/db_checkpoint.html">db_checkpoint</a><dd>The <a href="../../utility/db_checkpoint.html">db_checkpoint</a> utility runs as a daemon process, monitoring -the database log and periodically issuing checkpoints. It facilitates -log reclamation and the creation of database snapshots. Generally, some -form of database checkpointing must be done if a database environment has -been configured for transactions. -<p><dt><a href="../../utility/db_deadlock.html">db_deadlock</a><dd>The <a href="../../utility/db_deadlock.html">db_deadlock</a> utility runs as a daemon process, periodically -traversing the database lock structures and aborting transactions when it -detects a deadlock. Generally, some form of deadlock detection must be -done if a database environment has been configured for locking. -<p><dt><a href="../../utility/db_dump.html">db_dump</a><dd>The <a href="../../utility/db_dump.html">db_dump</a> utility writes a copy of the database to a flat-text -file in a portable format. -<p><dt><a href="../../utility/db_load.html">db_load</a><dd>The <a href="../../utility/db_load.html">db_load</a> utility reads the flat-text file produced by -<a href="../../utility/db_dump.html">db_dump</a> and loads it into a database file. -<p><dt><a href="../../utility/db_printlog.html">db_printlog</a><dd>The <a href="../../utility/db_printlog.html">db_printlog</a> utility displays the contents of Berkeley DB log files -in a human-readable and parsable format. -<p><dt><a href="../../utility/db_recover.html">db_recover</a><dd>The <a href="../../utility/db_recover.html">db_recover</a> utility runs after an unexpected Berkeley DB or system -failure to restore the database to a consistent state. Generally, some -form of database recovery must be done if databases are being modified. -<p><dt><a href="../../utility/db_stat.html">db_stat</a> <dd>The <a href="../../utility/db_stat.html">db_stat</a> utility displays statistics for databases and database -environments. -<p><dt><a href="../../utility/db_upgrade.html">db_upgrade</a><dd>The <a href="../../utility/db_upgrade.html">db_upgrade</a> utility provides a command-line interface for -upgrading underlying database formats. -<p><dt><a href="../../utility/db_verify.html">db_verify</a><dd>The <a href="../../utility/db_verify.html">db_verify</a> utility provides a command-line interface for -verifying the database format. -</dl> -<p>All of the functionality implemented for these utilities is also available -as part of the standard Berkeley DB API. This means that threaded applications -can easily create a thread that calls the same Berkeley DB functions as do the -utilities. This often simplifies an application environment by removing -the necessity for multiple processes to negotiate database and database -environment creation and shut down. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/arch/script.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/env/intro.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/libdb/docs/ref/build_unix/aix.html b/libdb/docs/ref/build_unix/aix.html deleted file mode 100644 index 6159159b8..000000000 --- a/libdb/docs/ref/build_unix/aix.html +++ /dev/null @@ -1,72 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: AIX</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Building Berkeley DB for UNIX systems</dl></h3></td> -<td align=right><a href="../../ref/build_unix/notes.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/build_unix/embedix.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>AIX</h1> -<p><ol> -<p><li><b>I can't compile and run multithreaded applications.</b> -<p>Special compile-time flags are required when compiling threaded -applications on AIX. If you are compiling a threaded application, you -must compile with the _THREAD_SAFE flag and load with specific -libraries; for example, "-lc_r". Specifying the compiler name with a -trailing "_r" usually performs the right actions for the system. -<p><blockquote><pre>xlc_r ... -cc -D_THREAD_SAFE -lc_r ...</pre></blockquote> -<p>The Berkeley DB library will automatically build with the correct options. -<hr size=1 noshade> -<p><li><b>I can't run using the <a href="../../api_c/env_open.html#DB_SYSTEM_MEM">DB_SYSTEM_MEM</a> option to -<a href="../../api_c/env_open.html">DB_ENV->open</a>.</b> -<p>AIX 4.1 allows applications to map only 10 system shared memory -segments. In AIX 4.3, this has been raised to 256K segments, but only -if you set the environment variable "export EXTSHM=ON". -<hr size=1 noshade> -<p><li><b>On AIX 4.3.2 (or before) I see undefined symbols when linking C++ -applications. Also, Java complains about missing symbols on this -platform even though I've configured and built for Java.</b> -<p>Versions of AIX 4.3.2 and before do not have the tools necessary to -produce shared libraries for languages such as C++ and Java that use -"name mangling" to map their names to C names. The Berkeley DB C++ API can -be only used on this platform as a static library. The Berkeley DB Java API -cannot be used on this platform. -<hr size=1 noshade> -<p><li><b>On AIX 4.3.3 I see undefined symbols for DbEnv::set_error_stream, -Db::set_error_stream or DbEnv::verify when linking C++ applications. -(These undefined symbols also appear when building the Berkeley DB C++ example -applications).</b> -<p>By default, Berkeley DB is built with _LARGE_FILES set to 1 to support the -creation of "large" database files. However, this also affects how -standard classes, like iostream, are named internally. When building -your application, use a "-D_LARGE_FILES=1" compilation option, or insert -"#define _LARGE_FILES 1" before any #include statements. -<hr size=1 noshade> -<p><li><b>I can't create database files larger than 1GB on AIX.</b> -<p>If you're running on AIX 4.1 or earlier, try changing the source code -for <b>os/os_open.c</b> to always specify the <b>O_LARGEFILE</b> -flag to the <b>open</b>(2) system call, and recompile Berkeley DB from -scratch. -<p>Also, the documentation for the IBM Visual Age compiler states that it -does not not support the 64-bit filesystem APIs necessary for creating -large files; the ibmcxx product must be used instead. We have not heard -whether the GNU gcc compiler supports the 64-bit APIs or not. -<p>Finally, to create large files under AIX, the filesystem has to be -configured to support large files and the system wide user hard-limit -for file sizes has to be greater than 1GB. -</ol> -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/build_unix/notes.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/build_unix/embedix.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/libdb/docs/ref/build_unix/conf.html b/libdb/docs/ref/build_unix/conf.html deleted file mode 100644 index a9c293aba..000000000 --- a/libdb/docs/ref/build_unix/conf.html +++ /dev/null @@ -1,183 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Configuring Berkeley DB</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Building Berkeley DB for UNIX systems</dl></h3></td> -<td align=right><a href="../../ref/build_unix/intro.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/build_unix/flags.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Configuring Berkeley DB</h1> -<p>There are several arguments you can specify when configuring Berkeley DB. -Although only the Berkeley DB-specific ones are described here, most of the -standard GNU autoconf arguments are available and supported. To see a -complete list of possible arguments, specify the --help flag to the -configure program. -<p>The Berkeley DB specific arguments are as follows: -<p><dl compact> -<a name="4"><!--meow--></a> -<p><dt><a name="--enable-compat185">--enable-compat185</a><dd>To compile or load Berkeley DB 1.85 applications against this release of the -Berkeley DB library, enter --enable-compat185 as an argument to configure. -This will include Berkeley DB 1.85 API compatibility code in the library. -<a name="5"><!--meow--></a> -<p><dt><a name="--enable-cxx">--enable-cxx</a><dd>To build the Berkeley DB C++ API, enter --enable-cxx as an argument to -configure. -<p><dt><a name="--enable-debug">--enable-debug</a><dd>To build Berkeley DB with <b>-g</b> as a compiler flag and with -<b>DEBUG</b> #defined during compilation, enter --enable-debug as an -argument to configure. This will create a Berkeley DB library and utilities -with debugging symbols, as well as load various routines that can be -called from a debugger to display pages, cursor queues, and so forth. -If installed, the utilities will not be stripped. This argument should -not be specified when configuring to build production binaries. -<p><dt><a name="--enable-debug_rop">--enable-debug_rop</a><dd>To build Berkeley DB to output log records for read operations, enter ---enable-debug_rop as an argument to configure. This argument should not -be specified when configuring to build production binaries. -<p><dt><a name="--enable-debug_wop">--enable-debug_wop</a><dd>To build Berkeley DB to output log records for write operations, enter ---enable-debug_wop as an argument to configure. This argument should not -be specified when configuring to build production binaries. -<p><dt><a name="--enable-diagnostic">--enable-diagnostic</a><dd>To build Berkeley DB with run-time debugging checks, enter --enable-diagnostic -as an argument to configure. This will cause a number of special checks -to be performed when Berkeley DB is running. Applications built using this -argument should not share database environments with applications built -without this argument. This argument should not be specified when -configuring to build production binaries. -<a name="6"><!--meow--></a> -<p><dt><a name="--enable-dump185">--enable-dump185</a><dd>To convert Berkeley DB 1.85 (or earlier) databases to this release of Berkeley DB, -enter --enable-dump185 as an argument to configure. This will build the -<a href="../../utility/db_dump.html">db_dump185</a> utility, which can dump Berkeley DB 1.85 and 1.86 databases -in a format readable by the Berkeley DB <a href="../../utility/db_load.html">db_load</a> utility. -<p>The system libraries with which you are loading the <a href="../../utility/db_dump.html">db_dump185</a> -utility must already contain the Berkeley DB 1.85 library routines for this -to work because the Berkeley DB distribution does not include them. If you -are using a non-standard library for the Berkeley DB 1.85 library routines, -you will have to change the Makefile that the configuration step creates -to load the <a href="../../utility/db_dump.html">db_dump185</a> utility with that library. -<a name="7"><!--meow--></a> -<p><dt><a name="--enable-java">--enable-java</a><dd>To build the Berkeley DB Java API, enter --enable-java as an argument to -configure. To build Java, you must also build with shared libraries. -Before configuring, you must set your PATH environment variable to -include javac. Note that it is not sufficient to include a symbolic -link to javac in your PATH because the configuration process uses the -location of javac to determine the location of the Java include files -(for example, jni.h). On some systems, additional include directories -may be needed to process jni.h; see <a href="flags.html">Changing compile or -load options</a> for more information. -<a name="8"><!--meow--></a> -<p><dt><a name="--disable-largefile">--disable-largefile</a><dd>Some systems, notably versions of HP/UX and Solaris, require special -compile-time options in order to create files larger than 2^32 bytes. -These options are automatically enabled when Berkeley DB is compiled. For -this reason, binaries built on current versions of these systems may -not run on earlier versions of the system because the library and system -calls necessary for large files are not available. To disable building -with these compile-time options, enter --disable-largefile as an argument -to configure. -<p><dt><a name="--enable-posixmutexes">--enable-posixmutexes</a><dd>To force Berkeley DB to use the POSIX pthread mutex interfaces for underlying -mutex support, enter --enable-posixmutexes as an argument to configure. -This is rarely necessary: POSIX mutexes will be selected automatically -on systems where they are the preferred implementation. -<p>The --enable-posixmutexes configuration argument is normally used in -two ways: First, when there are multiple mutex implementations available -and the POSIX mutex implementation is not the preferred one (for -example, on Solaris where the LWP mutexes are used by default). Second, -by default the Berkeley DB library will only select the POSIX mutex -implementation if it supports mutexes shared between multiple processes, -as described for the pthread_condattr_setpshared and -pthread_mutexattr_setpshared interfaces. The --enable-posixmutexes -configuration argument can be used to force the selection of POSIX -mutexes in this case, which can improve application performance -significantly when the alternative mutex implementation is a -non-blocking one (for example test-and-set assembly instructions). -However, configuring to use POSIX mutexes when the implementation does -not have inter-process support will only allow the creation of private -database environments, that is, environments where the -<a href="../../api_c/env_open.html#DB_PRIVATE">DB_PRIVATE</a> flag is specified to the <a href="../../api_c/env_open.html">DB_ENV->open</a> method. -<p>Specifying the --enable-posixmutexes configuration argument may require -that Berkeley DB be linked with the -lpthread library. -<a name="9"><!--meow--></a> -<p><dt><a name="--enable-rpc">--enable-rpc</a><dd>To build the Berkeley DB RPC client code and server utility, enter --enable-rpc -as an argument to configure. The --enable-rpc argument requires that RPC -libraries already be installed on your system. -<a name="10"><!--meow--></a><a name="11"><!--meow--></a> -<p><dt><a name="--disable-shared">--disable-shared</a>, <a name="--disable-static">--disable-static</a><dd>On systems supporting shared libraries, Berkeley DB builds both static and -shared libraries by default. (Shared libraries are built using -<a href="http://www.gnu.org/software/libtool/libtool.html">the GNU -Project's Libtool</a> distribution, which supports shared library builds -on many (although not all) systems.) To not build shared libraries, -configure using the --disable-shared argument. To not build static -libraries, configure using the --disable-static argument. -<a name="12"><!--meow--></a> -<p><dt><a name="--enable-tcl">--enable-tcl</a><dd>To build the Berkeley DB Tcl API, enter --enable-tcl as an argument to -configure. This configuration argument expects to find Tcl's tclConfig.sh -file in the <b>/usr/local/lib</b> directory. See the --with-tcl -argument for instructions on specifying a non-standard location for the -Tcl installation. See <a href="../../ref/tcl/intro.html">Loading Berkeley DB -with Tcl</a> for information on sites from which you can download Tcl and -which Tcl versions are compatible with Berkeley DB. To build Tcl, you must -also build with shared libraries. -<a name="13"><!--meow--></a> -<p><dt><a name="--enable-test">--enable-test</a><dd>To build the Berkeley DB test suite, enter --enable-test as an argument to -configure. To run the Berkeley DB test suite, you must also build the Tcl -API. This argument should not be specified when configuring to build -production binaries. -<p><dt><a name="--enable-uimutexes">--enable-uimutexes</a><dd>To force Berkeley DB to use the UNIX International (UI) mutex interfaces for -underlying mutex support, enter --enable-uimutexes as an argument to -configure. This is rarely necessary: UI mutexes will be selected -automatically on systems where they are the preferred implementation. -<p>The --enable-uimutexes configuration argument is normally used when -there are multiple mutex implementations available and the UI mutex -implementation is not the preferred one (for example, on Solaris where -the LWP mutexes are used by default). -<p>Specifying the --enable-uimutexes configuration argument may require -that Berkeley DB be linked with the -lthread library. -<p><dt><a name="--enable-umrw">--enable-umrw</a><dd>Rational Software's Purify product and other run-time tools complain -about uninitialized reads/writes of structure fields whose only purpose -is padding, as well as when heap memory that was never initialized is -written to disk. Specify the --enable-umrw argument during -configuration to mask these errors. This argument should not be -specified when configuring to build production binaries. -<p><dt><a name="--with-embedix=DIR">--with-embedix=DIR</a><dd>To build Berkeley DB for Embedix, configure with --with-embedix=DIR, where -DIR is the directory in which Embedix is installed. If "=DIR" is not -specified, a default installation directory of <b>/opt/Embedix</b> is -used. This configuration argument creates an Embedix Component Descriptor -file (ECD) for Berkeley DB. To configure for Embedix, you must also specify -the --with-rpm argument. -<p><dt><a name="--with-mutex=MUTEX">--with-mutex=MUTEX</a><dd>To force Berkeley DB to use a specific mutex implementation, configure with ---with-mutex=MUTEX, where MUTEX is the mutex implementation you want. -For example, --with-mutex=x86/gcc-assembly will configure Berkeley DB to use -the x86 GNU gcc compiler based test-and-set assembly mutexes. This is -rarely necessary and should be done only when the default configuration -selects the wrong mutex implementation. A list of available mutex -implementations can be found in the distribution file -<b>dist/aclocal/mutex.ac</b>. -<p><dt><a name="--with-rpm=DIR">--with-rpm=DIR</a><dd>To build Berkeley DB as an RPM software package, configure with --with-rpm=DIR, -where DIR is the directory in which the gzipped tar archive file of the -distribution may be found. This configuration argument will create an -RPM specification file from which the RPM software package can be built, -using the "make" command. -<p><dt><a name="--with-tcl=DIR">--with-tcl=DIR</a><dd>To build the Berkeley DB Tcl API, enter --with-tcl=DIR, replacing DIR with -the directory in which the Tcl tclConfig.sh file may be found. See -<a href="../../ref/tcl/intro.html">Loading Berkeley DB with Tcl</a> for information -on sites from which you can download Tcl and which Tcl versions are -compatible with Berkeley DB. To build Tcl, you must also build with shared -libraries. -<p><dt><a name="--with-uniquename=NAME">--with-uniquename=NAME</a><dd>To build Berkeley DB with unique symbol names (in order to avoid conflicts -with other application modules or libraries), enter --with-uniquename=NAME, -replacing NAME with a string that to be appended to every Berkeley DB symbol. -If "=NAME" is not specified, a default value of "_MAJORMINOR" is used, -where MAJORMINOR is the major and minor release numbers of the Berkeley DB -release. See <a href="../../ref/install/multiple.html">Building with -multiple versions of Berkeley DB</a> for more information. -</dl> -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/build_unix/intro.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/build_unix/flags.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/libdb/docs/ref/build_unix/embedix.html b/libdb/docs/ref/build_unix/embedix.html deleted file mode 100644 index 6449cc3c6..000000000 --- a/libdb/docs/ref/build_unix/embedix.html +++ /dev/null @@ -1,37 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Embedix</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Building Berkeley DB for UNIX systems</dl></h3></td> -<td align=right><a href="../../ref/build_unix/aix.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/build_unix/freebsd.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Embedix</h1> -<p><ol> -<p><li><b>How do I make Embedix aware of Berkeley DB?</b> -<p>In order to make Embedix aware of a software component, two items are -needed, an Embedix Component Descriptor file and a source RPM file -for that component. After Berkeley DB has been configured for RPM and -Embedix using the configuration options described in <a href="conf.html">Configuring -Berkeley DB</a>, the RPM should be built using: -<p><blockquote><pre>make</pre></blockquote> -After the RPM is built, as root, the files need to be installed -in the Embedix installation area, using: -<p><blockquote><pre>make install</pre></blockquote> -After installation, start up the -Embedix target wizard and Berkeley DB will appear in the component list. -</ol> -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/build_unix/aix.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/build_unix/freebsd.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/libdb/docs/ref/build_unix/flags.html b/libdb/docs/ref/build_unix/flags.html deleted file mode 100644 index 538875370..000000000 --- a/libdb/docs/ref/build_unix/flags.html +++ /dev/null @@ -1,62 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Changing compile or load options</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Building Berkeley DB for UNIX systems</dl></h3></td> -<td align=right><a href="../../ref/build_unix/conf.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/build_unix/install.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Changing compile or load options</h1> -<p>You can specify compiler and/or compile and load time flags by using -environment variables during Berkeley DB configuration. For example, if you -want to use a specific compiler, specify the CC environment variable -before running configure: -<p><blockquote><pre>prompt: env CC=gcc ../dist/configure</pre></blockquote> -<p>Using anything other than the native compiler will almost certainly mean -that you'll want to check the flags specified to the compiler and -loader, too. -<p>To specify debugging and optimization options for the C compiler, -use the CFLAGS environment variable: -<p><blockquote><pre>prompt: env CFLAGS=-O2 ../dist/configure</pre></blockquote> -<p>To specify header file search directories and other miscellaneous options -for the C preprocessor and compiler, use the CPPFLAGS environment variable: -<p><blockquote><pre>prompt: env CPPFLAGS=-I/usr/contrib/include ../dist/configure</pre></blockquote> -<p>To specify debugging and optimization options for the C++ compiler, -use the CXXFLAGS environment variable: -<p><blockquote><pre>prompt: env CXXFLAGS=-Woverloaded-virtual ../dist/configure</pre></blockquote> -<p>To specify miscellaneous options or additional library directories for -the linker, use the LDFLAGS environment variable: -<p><blockquote><pre>prompt: env LDFLAGS="-N32 -L/usr/local/lib" ../dist/configure</pre></blockquote> -<p>If you want to specify additional libraries, set the LIBS environment -variable before running configure. For example, the following would -specify two additional libraries to load, "posix" and "socket": -<p><blockquote><pre>prompt: env LIBS="-lposix -lsocket" ../dist/configure</pre></blockquote> -<p>Make sure that you prepend -L to any library directory names and that you -prepend -I to any include file directory names! Also, if the arguments -you specify contain blank or tab characters, be sure to quote them as -shown previously; that is with single or double quotes around the values -you are specifying for LIBS. -<p>The env command, which is available on most systems, simply sets one or -more environment variables before running a command. If the env command -is not available to you, you can set the environment variables in your -shell before running configure. For example, in sh or ksh, you could -do the following: -<p><blockquote><pre>prompt: LIBS="-lposix -lsocket" ../dist/configure</pre></blockquote> -<p>In csh or tcsh, you could do the following: -<p><blockquote><pre>prompt: setenv LIBS "-lposix -lsocket" -prompt: ../dist/configure</pre></blockquote> -<p>See your command shell's manual page for further information. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/build_unix/conf.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/build_unix/install.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/libdb/docs/ref/build_unix/freebsd.html b/libdb/docs/ref/build_unix/freebsd.html deleted file mode 100644 index eddae0414..000000000 --- a/libdb/docs/ref/build_unix/freebsd.html +++ /dev/null @@ -1,59 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: FreeBSD</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Building Berkeley DB for UNIX systems</dl></h3></td> -<td align=right><a href="../../ref/build_unix/embedix.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/build_unix/hpux.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>FreeBSD</h1> -<p><ol> -<p><li><b>I can't compile and run multithreaded applications.</b> -<p>Special compile-time flags are required when compiling threaded -applications on FreeBSD. If you are compiling a threaded application, -you must compile with the _THREAD_SAFE and -pthread flags: -<p><blockquote><pre>cc -D_THREAD_SAFE -pthread ...</pre></blockquote> -<p>The Berkeley DB library will automatically build with the correct options. -<hr size=1 noshade> -<p><li><b>I get occasional failures when running RPC-based programs under -FreeBSD clients.</b> -<p>There is a known bug in the XDR implementation in the FreeBSD C library -from version 2.2 up to version 4.0-RELEASE, that causes certain-sized -messages to fail and return a zero-filled reply to the client. A bug -report (#16028) has been filed with FreeBSD. The following patch is the -FreeBSD fix: -<p><blockquote><pre>*** /usr/src/lib/libc/xdr/xdr_rec.c.orig Mon Jan 10 10:20:42 2000 ---- /usr/src/lib/libc/xdr/xdr_rec.c Wed Jan 19 10:53:45 2000 -*************** -*** 558,564 **** - * but we don't have any way to be certain that they aren't - * what the client actually intended to send us. - */ -! if ((header & (~LAST_FRAG)) == 0) - return(FALSE); - rstrm->fbtbc = header & (~LAST_FRAG); - return (TRUE); ---- 558,564 ---- - * but we don't have any way to be certain that they aren't - * what the client actually intended to send us. - */ -! if (header == 0) - return(FALSE); - rstrm->fbtbc = header & (~LAST_FRAG); - return (TRUE); -</pre></blockquote> -</ol> -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/build_unix/embedix.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/build_unix/hpux.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/libdb/docs/ref/build_unix/hpux.html b/libdb/docs/ref/build_unix/hpux.html deleted file mode 100644 index 7332b91a2..000000000 --- a/libdb/docs/ref/build_unix/hpux.html +++ /dev/null @@ -1,91 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: HP-UX</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Building Berkeley DB for UNIX systems</dl></h3></td> -<td align=right><a href="../../ref/build_unix/freebsd.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/build_unix/irix.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>HP-UX</h1> -<p><ol> -<p><li><b>I can't specify the <a href="../../api_c/env_open.html#DB_SYSTEM_MEM">DB_SYSTEM_MEM</a> flag to <a href="../../api_c/env_open.html">DB_ENV->open</a>.</b> -<p>The <b>shmget</b>(2) interfaces are not always used on HP-UX, even -though they exist, because anonymous memory allocated using <b>shmget</b>(2) -cannot be used to store the standard HP-UX msemaphore semaphores. For -this reason, it may not be possible to specify the <a href="../../api_c/env_open.html#DB_SYSTEM_MEM">DB_SYSTEM_MEM</a> -flag on some versions of HP-UX. (We have seen this problem only on HP-UX -10.XX, so the simplest workaround may be to upgrade your HP-UX release.) -<hr size=1 noshade> -<p><li><b>I can't specify both the <a href="../../api_c/env_open.html#DB_PRIVATE">DB_PRIVATE</a> and <a href="../../api_c/env_open.html#DB_THREAD">DB_THREAD</a> -flags to <a href="../../api_c/env_open.html">DB_ENV->open</a>.</b> -<p>It is not possible to store the standard HP-UX msemaphore semaphores in -memory returned by <b>malloc</b>(3) in some versions of HP-UX. For -this reason, it may not be possible to specify both the -<a href="../../api_c/env_open.html#DB_PRIVATE">DB_PRIVATE</a> and <a href="../../api_c/env_open.html#DB_THREAD">DB_THREAD</a> flags on some versions of -HP-UX. (We have seen this problem only on HP-UX 10.XX, so the simplest -workaround may be to upgrade your HP-UX release.) -<hr size=1 noshade> -<p><li><b>During configuration, I see a message that large file support -has been turned off.</b> -<p>Some HP-UX system include files redefine "open" when big-file support (the -HAVE_FILE_OFFSET_BITS and _FILE_OFFSET_BITS #defines) is enabled. This -causes problems when compiling for C++, where "open" is a legal -identifier, used in the Berkeley DB C++ API. For this reason, we automatically -turn off big-file support when Berkeley DB is configured with a C++ API. This -should not be a problem for applications unless there is a need to create -databases larger than 2GB. -<hr size=1 noshade> -<p><li><b>I can't compile and run multithreaded applications.</b> -<p>Special compile-time flags are required when compiling threaded -applications on HP-UX. If you are compiling a threaded application, you -must compile with the _REENTRANT flag: -<p><blockquote><pre>cc -D_REENTRANT ...</pre></blockquote> -<p>The Berkeley DB library will automatically build with the correct options. -<hr size=1 noshade> -<p><li><b>An ENOMEM error is returned from <a href="../../api_c/env_open.html">DB_ENV->open</a> or -<a href="../../api_c/env_remove.html">DB_ENV->remove</a>.</b> -<p>Due to the constraints of the PA-RISC memory architecture, HP-UX does not -allow a process to map a file into its address space multiple times. -For this reason, each Berkeley DB environment may be opened only once by a -process on HP-UX; that is, calls to <a href="../../api_c/env_open.html">DB_ENV->open</a> will fail if the -specified Berkeley DB environment has been opened and not subsequently closed. -<hr size=1 noshade> -<p><li><b>When compiling with gcc, I see the following error: -<p><blockquote><pre>#error "Large Files (ILP32) not supported in strict ANSI mode."</pre></blockquote></b> -<p>We believe this is an error in the HP-UX include files, but we don't -really understand it. The only workaround we have found is to add --D__STDC_EXT__ to the C preprocessor defines as part of compilation. -<hr size=1 noshade> -<p><li><b>When using the Tcl or Perl APIs (including running the test -suite), I see the error "Can't shl_load() a library containing Thread -Local Storage".</b> -<p>This problem happens when HP-UX has been configured to use pthread mutex -locking, and an attempt is made to call Berkeley DB using the Tcl or Perl APIs. -We have never found any way to fix this problem as part of the Berkeley DB -build process. To work around the problem, rebuild tclsh or Perl, and -modify its build process to explicitly link it against the HP-UX pthread -library (currently /usr/lib/libpthread.a). -<hr size=1 noshade> -<p><li><b>When running an executable that has been dynamically linked -against the Berkeley DB library, I see the error "Can't find path for shared -library" even though I correctly set the SHLIB_PATH environment variable.</b> -<p>By default, some versions of HP-UX ignore the dynamic library search -path specified by the SHLIB_PATH environment variable. To work around -this, specify the "+s" flag to ld when linking, or run the following -command on the executable that is not working: -<p><blockquote><pre>chatr +s enable -l /full/path/to/libdb-3.2.sl ...</pre></blockquote> -</ol> -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/build_unix/freebsd.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/build_unix/irix.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/libdb/docs/ref/build_unix/install.html b/libdb/docs/ref/build_unix/install.html deleted file mode 100644 index ec992abf7..000000000 --- a/libdb/docs/ref/build_unix/install.html +++ /dev/null @@ -1,65 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Installing Berkeley DB</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Building Berkeley DB for UNIX systems</dl></h3></td> -<td align=right><a href="../../ref/build_unix/flags.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/build_unix/shlib.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Installing Berkeley DB</h1> -<p>Berkeley DB installs the following files into the following locations, with the -following default values: -<p><table border=1 align=center> -<tr><th>Configuration Variables</th><th>Default value</th></tr> -<tr><td>--prefix</td><td>/usr/local/BerkeleyDB.<b>Major</b>.<b>Minor</b></td></tr> -<tr><td>--exec_prefix</td><td>$(prefix)</td></tr> -<tr><td>--bindir</td><td>$(exec_prefix)/bin</td></tr> -<tr><td>--includedir</td><td>$(prefix)/include</td></tr> -<tr><td>--libdir</td><td>$(exec_prefix)/lib</td></tr> -<tr><td>docdir</td><td>$(prefix)/docs</td></tr> -<tr><th>Files</th><th>Default location</th></tr> -<tr><td>include files</td><td>$(includedir)</td></tr> -<tr><td>libraries</td><td>$(libdir)</td></tr> -<tr><td>utilities</td><td>$(bindir)</td></tr> -<tr><td>documentation</td><td>$(docdir)</td></tr> -</table> -<p>With one exception, this follows the GNU Autoconf and GNU Coding -Standards installation guidelines; please see that documentation for -more information and rationale. -<p>The single exception is the Berkeley DB documentation. The Berkeley DB -documentation is provided in HTML format, not in UNIX-style man or GNU -info format. For this reason, Berkeley DB configuration does not support -<b>--infodir</b> or <b>--mandir</b>. To change the default -installation location for the Berkeley DB documentation, modify the Makefile -variable, <b>docdir</b>. -<p>When installing Berkeley DB on filesystems shared by machines of different -architectures, please note that although Berkeley DB include files are -installed based on the value of $(prefix), rather than $(exec_prefix), -the Berkeley DB include files are not always architecture independent. -<p>To move the entire installation tree to somewhere besides -<b>/usr/local</b>, change the value of <b>prefix</b>. -<p>To move the binaries and libraries to a different location, change the -value of <b>exec_prefix</b>. The values of <b>includedir</b> and -<b>libdir</b> may be similarly changed. -<p>Any of these values except for <b>docdir</b> may be set as part of -the configuration: -<p><blockquote><pre>prompt: ../dist/configure --bindir=/usr/local/bin</pre></blockquote> -<p>Any of these values, including <b>docdir</b>, may be changed when doing -the install itself: -<p><blockquote><pre>prompt: make prefix=/usr/contrib/bdb install</pre></blockquote> -<p>The Berkeley DB installation process will attempt to create any directories that -do not already exist on the system. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/build_unix/flags.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/build_unix/shlib.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/libdb/docs/ref/build_unix/intro.html b/libdb/docs/ref/build_unix/intro.html deleted file mode 100644 index 016599efe..000000000 --- a/libdb/docs/ref/build_unix/intro.html +++ /dev/null @@ -1,64 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Building for UNIX</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><a name="5"><!--meow--></a> -<table width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Building Berkeley DB for UNIX systems</dl></h3></td> -<td align=right><a href="../../ref/debug/common.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/build_unix/conf.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Building for UNIX</h1> -<p>The Berkeley DB distribution builds up to four separate libraries: the base -C API Berkeley DB library and the optional C++, Java, and Tcl API libraries. -For portability reasons, each library is standalone and contains the -full Berkeley DB support necessary to build applications; that is, the C++ -API Berkeley DB library does not require any other Berkeley DB libraries to build -and run C++ applications. -<p>Building for Linux, Mac OS X and the QNX Neutrino release is the same -as building for a conventional UNIX platform. Building for the Embedix -release is somewhat different -- see the <a href="embedix.html">Embedix</a> FAQ -page for more information. -<p>The Berkeley DB distribution uses the Free Software Foundation's -<a href="http://www.gnu.org/software/autoconf/autoconf.html">autoconf</a> -and <a href="http://www.gnu.org/software/libtool/libtool.html">libtool</a> tools to build on UNIX platforms. In general, the standard -configuration and installation options for these tools apply to the -Berkeley DB distribution. -<p>To do a standard UNIX build of Berkeley DB, change to the <b>build_unix</b> -directory and then enter the following two commands: -<p><blockquote><pre>../dist/configure -make</pre></blockquote> -<p>This will build the Berkeley DB library. -<p>To install the Berkeley DB library, enter the following command: -<p><blockquote><pre>make install</pre></blockquote> -<p>To rebuild Berkeley DB, enter: -<p><blockquote><pre>make clean -make</pre></blockquote> -<p>If you change your mind about how Berkeley DB is to be configured, you must -start from scratch by entering the following command: -<p><blockquote><pre>make realclean -../dist/configure -make</pre></blockquote> -<p>To build multiple UNIX versions of Berkeley DB in the same source tree, create -a new directory at the same level as the build_unix directory, and then -configure and build in that directory as described previously. -<p>If you have trouble with any of these commands, please send email to -the support addresses found in the Sleepycat Software contact -information. In that email, please include the following information: -<p><ul type=disc> -<li>A screen snapshot of the commands you entered to do configuration and -compilation, and any output they produced. -<li>A copy of the <b>config.log</b> file created during configuration. -</ul> -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/debug/common.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/build_unix/conf.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/libdb/docs/ref/build_unix/irix.html b/libdb/docs/ref/build_unix/irix.html deleted file mode 100644 index 52393b90a..000000000 --- a/libdb/docs/ref/build_unix/irix.html +++ /dev/null @@ -1,31 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: IRIX</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Building Berkeley DB for UNIX systems</dl></h3></td> -<td align=right><a href="../../ref/build_unix/hpux.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/build_unix/linux.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>IRIX</h1> -<p><ol> -<p><li><b>I can't compile and run multithreaded applications.</b> -<p>Special compile-time flags are required when compiling threaded -applications on IRIX. If you are compiling a threaded application, you -must compile with the _SGI_MP_SOURCE flag: -<p><blockquote><pre>cc -D_SGI_MP_SOURCE ...</pre></blockquote> -<p>The Berkeley DB library will automatically build with the correct options. -</ol> -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/build_unix/hpux.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/build_unix/linux.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/libdb/docs/ref/build_unix/linux.html b/libdb/docs/ref/build_unix/linux.html deleted file mode 100644 index 8d57487a4..000000000 --- a/libdb/docs/ref/build_unix/linux.html +++ /dev/null @@ -1,31 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Linux</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Building Berkeley DB for UNIX systems</dl></h3></td> -<td align=right><a href="../../ref/build_unix/irix.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/build_unix/macosx.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Linux</h1> -<p><ol> -<p><li><b>I can't compile and run multithreaded applications.</b> -<p>Special compile-time flags are required when compiling threaded -applications on Linux. If you are compiling a threaded application, you -must compile with the _REENTRANT flag: -<p><blockquote><pre>cc -D_REENTRANT ...</pre></blockquote> -<p>The Berkeley DB library will automatically build with the correct options. -</ol> -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/build_unix/irix.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/build_unix/macosx.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/libdb/docs/ref/build_unix/macosx.html b/libdb/docs/ref/build_unix/macosx.html deleted file mode 100644 index 1cb9c29d9..000000000 --- a/libdb/docs/ref/build_unix/macosx.html +++ /dev/null @@ -1,42 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Mac OS X</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Building Berkeley DB for UNIX systems</dl></h3></td> -<td align=right><a href="../../ref/build_unix/linux.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/build_unix/osf1.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Mac OS X</h1> -<p><ol> -<p><li><b>I cannot use the Java API on Mac OS X.</b> -<p>The Berkeley DB configuration and build procedure is unable to dynamically -load some libraries on Mac OS X. This restriction is expected to be -removed in future Berkeley DB releases. -<p>There is a workaround for Java. Mac OS X normally requires Java -loadable libraries to end with a .jnilib extension. Libtool, used by -our build procedure, does not support this extension. To work around -this, you must add a -D option to your Java command line to specify the -complete pathname of the installed library: -<p><blockquote><pre>% java -Dsleepycat.db.libfile=/full/path/to/libdb_java-VERSION.so</pre></blockquote> -<p><li><b>I cannot run the test suite on Mac OS X.</b> -<p>The Mac OS X 10.1 and 10.2 Developer Tools installer will optionally -install one additional package called simply, "BSD SDK". That package -contains the additional parts of the TCL distribution required to -configure, compile and run the Berkeley DB test suite. The Berkeley DB configuration -step will need the flag "--with-tcl=/System/Library/Tcl/8.3" added to -the arguments in order to locate the now installed TCL distribution. -</ol> -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/build_unix/linux.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/build_unix/osf1.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/libdb/docs/ref/build_unix/notes.html b/libdb/docs/ref/build_unix/notes.html deleted file mode 100644 index 41093c99c..000000000 --- a/libdb/docs/ref/build_unix/notes.html +++ /dev/null @@ -1,153 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Architecture independent FAQ</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Building Berkeley DB for UNIX systems</dl></h3></td> -<td align=right><a href="../../ref/build_unix/test.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/build_unix/aix.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Architecture independent FAQ</h1> -<p><ol> -<p><li><b>When compiling with gcc, I get unreferenced symbols; for example -the following: -<p><blockquote><pre>symbol __muldi3: referenced symbol not found -symbol __cmpdi2: referenced symbol not found</pre></blockquote></b> -<p>Berkeley DB often uses 64-bit integral types on systems supporting large -files, and gcc performs operations on those types by calling library -functions. These unreferenced symbol errors are usually caused by -linking an application by calling "ld" rather than by calling "gcc": -gcc will link in libgcc.a and will resolve the symbols. If that does -not help, another possible workaround is to reconfigure Berkeley DB using the -<a href="../../ref/build_unix/conf.html#--disable-largefile">--disable-largefile</a> configuration option and then rebuild. -<hr size=1 noshade> -<p><li><b>My C++ program traps during a failure in a DB call on my -gcc-based system.</b> -<p>We believe there are some severe bugs in the implementation of -exceptions for some gcc compilers. Exceptions require some interaction -between compiler, assembler, and runtime libraries. We're not sure -exactly what is at fault, but one failing combination is gcc 2.7.2.3 -running on SuSE Linux 6.0. The problem on this system can be seen with -a rather simple test case of an exception thrown from a shared library -and caught in the main program. -<p>A variation of this problem seems to occur on AIX, although we believe it -does not necessarily involve shared libraries on that platform. -<p>If you see a trap that occurs when an exception might be thrown by the -Berkeley DB runtime, we suggest that you use static libraries instead of -shared libraries. See the documentation for configuration. If this -doesn't work and you have a choice of compilers, try using a more recent -gcc- or a non-gcc based compiler to build Berkeley DB. -<p>Finally, you can disable the use of exceptions in the C++ runtime for -Berkeley DB by using the <a href="../../api_cxx/env_class.html#DB_CXX_NO_EXCEPTIONS">DB_CXX_NO_EXCEPTIONS</a> flag with the -<a href="../../api_cxx/env_class.html">DbEnv</a> or <a href="../../api_cxx/db_class.html">Db</a> constructors. When this flag is on, -all C++ methods fail by returning an error code rather than throwing an -exception. -<hr size=1 noshade> -<p><li><b>I get unexpected results and database corruption when running -threaded programs.</b> -<p><b>I get error messages that mutex (for example, pthread_mutex_XXX or -mutex_XXX) functions are undefined when linking applications with Berkeley DB.</b> -<p>On some architectures, the Berkeley DB library uses the ISO POSIX standard -pthreads and UNIX International (UI) threads interfaces for underlying -mutex support; for example, Solaris and HP-UX. You can specify -compilers or compiler flags, or link with the appropriate thread library -when loading your application to resolve the undefined references: -<p><blockquote><pre>cc ... -lpthread ... -cc ... -lthread ... -xlc_r ... -cc ... -mt ...</pre></blockquote> -<p>See the appropriate architecture-specific Reference Guide pages for more -information. -<p>On systems where more than one type of mutex is available, it may be -necessary for applications to use the same threads package from which -Berkeley DB draws its mutexes. For example, if Berkeley DB was built to use the -POSIX pthreads mutex calls for mutex support, the application may need -to be written to use the POSIX pthreads interfaces for its threading -model. This is only conjecture at this time, and although we know of -no systems that actually have this requirement, it's not unlikely that -some exist. -<p>In a few cases, Berkeley DB can be configured to use specific underlying mutex -interfaces. You can use the <a href="../../ref/build_unix/conf.html#--enable-posixmutexes">--enable-posixmutexes</a> and -<a href="../../ref/build_unix/conf.html#--enable-uimutexes">--enable-uimutexes</a> configuration options to specify the POSIX and Unix -International (UI) threads packages. This should not, however, be -necessary in most cases. -<p>In some cases, it is vitally important to make sure that you load the -correct library. For example, on Solaris systems, there are POSIX -pthread interfaces in the C library, so applications can link Berkeley DB -using only C library and not see any undefined symbols. However, the -C library POSIX pthread mutex support is insufficient for Berkeley DB, and -Berkeley DB cannot detect that fact. Similar errors can arise when -applications (for example, tclsh) use dlopen to dynamically load Berkeley DB -as a library. -<p>If you are seeing problems in this area after you confirm that you're -linking with the correct libraries, there are two other things you can -try. First, if your platform supports interlibrary dependencies, we -recommend that you change the Berkeley DB Makefile to specify the appropriate -threads library when creating the Berkeley DB shared library, as an -interlibrary dependency. Second, if your application is using dlopen -to dynamically load Berkeley DB, specify the appropriate thread library on -the link line when you load the application itself. -<hr size=1 noshade> -<p><li><b>I get core dumps when running programs that fork children.</b> -<p>Berkeley DB handles should not be shared across process forks, each forked -child should acquire its own Berkeley DB handles. -<hr size=1 noshade> -<p><li><b>I get reports of uninitialized memory reads and writes when -running software analysis tools (for example, Rational Software Corp.'s -Purify tool).</b> -<p>For performance reasons, Berkeley DB does not write the unused portions of -database pages or fill in unused structure fields. To turn off these -errors when running software analysis tools, build with the ---enable-umrw configuration option. -<hr size=1 noshade> -<p><li><b>Berkeley DB programs or the test suite fail unexpectedly.</b> -<p>The Berkeley DB architecture does not support placing the shared memory -regions on remote filesystems -- for example, the Network File System -(NFS) or the Andrew File System (AFS). For this reason, the shared -memory regions (normally located in the database home directory) must -reside on a local filesystem. See <a href="../../ref/env/region.html">Shared Memory Regions</a> for more information. -<p>With respect to running the test suite, always check to make sure that -TESTDIR is not on a remote mounted filesystem. -<hr size=1 noshade> -<p><li><b>The <a href="../../utility/db_dump.html">db_dump185</a> utility fails to build.</b> -<p>The <a href="../../utility/db_dump.html">db_dump185</a> utility is the utility that supports the -conversion of Berkeley DB 1.85 and earlier databases to current database -formats. If the build errors look something like the following, it -means the db.h include file being loaded is not a Berkeley DB 1.85 version -include file: -<p><blockquote><pre>db_dump185.c: In function `main': -db_dump185.c:210: warning: assignment makes pointer from integer without a cast -db_dump185.c:212: warning: assignment makes pointer from integer without a cast -db_dump185.c:227: structure has no member named `seq' -db_dump185.c:227: `R_NEXT' undeclared (first use in this function)</pre></blockquote> -<p>If the build errors look something like the following, it means that -the Berkeley DB 1.85 code was not found in the standard libraries: -<p><blockquote><pre>cc -o db_dump185 db_dump185.o -ld: -Unresolved: -dbopen</pre></blockquote> -<p>To build <a href="../../utility/db_dump.html">db_dump185</a>, the Berkeley DB version 1.85 code must already -been built and available on the system. If the Berkeley DB 1.85 header file -is not found in a standard place, or if the library is not part of the -standard libraries used for loading, you will need to edit your -Makefile, and change the following lines: -<p><blockquote><pre>DB185INC= -DB185LIB=</pre></blockquote> -<p>So that the system Berkeley DB 1.85 header file and library are found; for -example: -<p><blockquote><pre>DB185INC=/usr/local/include -DB185LIB=-ldb185</pre></blockquote> -</ol> -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/build_unix/test.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/build_unix/aix.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/libdb/docs/ref/build_unix/osf1.html b/libdb/docs/ref/build_unix/osf1.html deleted file mode 100644 index 83820f3bb..000000000 --- a/libdb/docs/ref/build_unix/osf1.html +++ /dev/null @@ -1,31 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: OSF/1</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Building Berkeley DB for UNIX systems</dl></h3></td> -<td align=right><a href="../../ref/build_unix/macosx.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/build_unix/qnx.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>OSF/1</h1> -<p><ol> -<p><li><b>I can't compile and run multithreaded applications.</b> -<p>Special compile-time flags are required when compiling threaded -applications on OSF/1. If you are compiling a threaded application, you -must compile with the _REENTRANT flag: -<p><blockquote><pre>cc -D_REENTRANT ...</pre></blockquote> -<p>The Berkeley DB library will automatically build with the correct options. -</ol> -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/build_unix/macosx.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/build_unix/qnx.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/libdb/docs/ref/build_unix/qnx.html b/libdb/docs/ref/build_unix/qnx.html deleted file mode 100644 index 32ad74f41..000000000 --- a/libdb/docs/ref/build_unix/qnx.html +++ /dev/null @@ -1,77 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: QNX</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Building Berkeley DB for UNIX systems</dl></h3></td> -<td align=right><a href="../../ref/build_unix/osf1.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/build_unix/sco.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>QNX</h1> -<p><ol> -<p><li><b>To what versions of QNX has DB been ported?</b> -<p>Berkeley DB has been ported to the QNX Neutrino technology which is commonly -referred to as QNX RTP (Real-Time Platform). Berkeley DB has not been -ported to earlier versions of QNX, such as QNX 4.25. -<p><li><b>Are there any QNX filesystem issues?</b> -<p>Berkeley DB generates temporary files for use in transactionally -protected file system operations. Due to the filename length limit of -48 characters in the QNX filesystem, applications that are using -transactions should specify a database name that is at most 43 characters. -<p><li><b>What is the impact of QNX's use of <b>shm_open</b>(2) for -shared memory regions?</b> -<p>QNX requires the use of the POSIX <b>shm_open</b>(2) and -<b>shm_unlink</b>(2) calls for shared memory regions that will later -be mapped into memory using <b>mmap</b>(2). QNX's implementation -of the shared memory functions requires that the name given must begin -with a slash, and that no other slash may appear in the name. -<p>In order to comply with those requirements and allow relative pathnames -to find the same environment, Berkeley DB uses only the last component of the -home directory path and the name of the shared memory file, separated -by a colon, as the name specified to the shared memory functions. For -example, if an application specifies a home directory of -<b>/home/db/DB_DIR</b>, Berkeley DB will use <b>/DB_DIR:__db.001</b> as -the name for the shared memory area argument to <b>shm_open</b>(2). -<p>The impact of this decision is that the last component of all -environment home directory pathnames on QNX must be unique with respect -to each other. Additionally, Berkeley DB requires that environments use home -directories for QNX in order to generate a reasonable entry in the -shared memory area. -<p><li><b>What are the implications of QNX's requirement to use -<b>shm_open</b>(2) in order to use <b>mmap</b>(2)?</b> -<p>QNX requires that files mapped with <b>mmap</b>(2) be opened using -<b>shm_open</b>(2). There are other places in addition to the -environment shared memory regions, where Berkeley DB tries to memory map files -if it can. -<p>The memory pool subsystem normally attempts to use <b>mmap</b>(2) -even when using private memory, as indicated by the <a href="../../api_c/env_open.html#DB_PRIVATE">DB_PRIVATE</a> -flag to <a href="../../api_c/env_open.html">DB_ENV->open</a>. In the case of QNX, if an application is -using private memory, Berkeley DB will not attempt to map the memory and will -instead use the local cache. -<p><li><b>What are the implications of QNX's mutex implementation using -microkernel resources?</b> -<p>On QNX, the primitives implementing mutexes consume system resources. -Therefore, if an application unexpectedly fails, those resources could -leak. Berkeley DB solves this problem by always allocating mutexes in the -persistent shared memory regions. Then, if an application fails, -running recovery or explicitly removing the database environment by -calling the <a href="../../api_c/env_remove.html">DB_ENV->remove</a> method will allow Berkeley DB to release those -previously held mutex resources. If an application specifies the -<a href="../../api_c/env_open.html#DB_PRIVATE">DB_PRIVATE</a> flag (choosing not to use persistent shared memory), -and then fails, mutexes allocated in that private memory may leak their -underlying system resources. Therefore, the <a href="../../api_c/env_open.html#DB_PRIVATE">DB_PRIVATE</a> flag -should be used with caution on QNX. -</ol> -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/build_unix/osf1.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/build_unix/sco.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/libdb/docs/ref/build_unix/sco.html b/libdb/docs/ref/build_unix/sco.html deleted file mode 100644 index 4da050330..000000000 --- a/libdb/docs/ref/build_unix/sco.html +++ /dev/null @@ -1,30 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: SCO</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Building Berkeley DB for UNIX systems</dl></h3></td> -<td align=right><a href="../../ref/build_unix/qnx.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/build_unix/solaris.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>SCO</h1> -<p><ol> -<p><li><b>If I build with gcc, programs such as db_dump and db_stat core dump -immediately when invoked.</b> -<p>We suspect gcc or the runtime loader may have a bug, but we haven't -tracked it down. If you want to use gcc, we suggest building static -libraries. -</ol> -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/build_unix/qnx.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/build_unix/solaris.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/libdb/docs/ref/build_unix/shlib.html b/libdb/docs/ref/build_unix/shlib.html deleted file mode 100644 index ae3f271d1..000000000 --- a/libdb/docs/ref/build_unix/shlib.html +++ /dev/null @@ -1,99 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Dynamic shared libraries</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Building Berkeley DB for UNIX systems</dl></h3></td> -<td align=right><a href="../../ref/build_unix/install.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/build_unix/test.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Dynamic shared libraries</h1> -<p><b>Warning</b>: the following information is intended to be generic and -is likely to be correct for most UNIX systems. Unfortunately, dynamic -shared libraries are not standard between UNIX systems, so there may be -information here that is not correct for your system. If you have -problems, consult your compiler and linker manual pages, or your system -administrator. -<p>The Berkeley DB dynamic shared libraries are created with the name -libdb-<b>major</b>.<b>minor</b>.so, where <b>major</b> is the major -version number and <b>minor</b> is the minor version number. Other -shared libraries are created if Java and Tcl support are enabled -- -specifically, libdb_java-<b>major</b>.<b>minor</b>.so and -libdb_tcl-<b>major</b>.<b>minor</b>.so. -<p>On most UNIX systems, when any shared library is created, the linker -stamps it with a "SONAME". In the case of Berkeley DB, the SONAME is -libdb-<b>major</b>.<b>minor</b>.so. It is important to realize that -applications linked against a shared library remember the SONAMEs of the -libraries they use and not the underlying names in the filesystem. -<p>When the Berkeley DB shared library is installed, links are created in the -install lib directory so that libdb-<b>major</b>.<b>minor</b>.so, -libdb-<b>major</b>.so, and libdb.so all refer to the same library. This -library will have an SONAME of libdb-<b>major</b>.<b>minor</b>.so. -<p>Any previous versions of the Berkeley DB libraries that are present in the -install directory (such as libdb-2.7.so or libdb-2.so) are left unchanged. -(Removing or moving old shared libraries is one drastic way to identify -applications that have been linked against those vintage releases.) -<p>Once you have installed the Berkeley DB libraries, unless they are installed -in a directory where the linker normally looks for shared libraries, -you will need to specify the installation directory as part of compiling -and linking against Berkeley DB. Consult your system manuals or system -administrator for ways to specify a shared library directory when -compiling and linking applications with the Berkeley DB libraries. Many -systems support environment variables (for example, LD_LIBRARY_PATH or -LD_RUN_PATH), or system configuration files (for example, /etc/ld.so.conf) -for this purpose. -<p><b>Warning</b>: some UNIX installations may have an already existing -<b>/usr/lib/libdb.so</b>, and this library may be an incompatible -version of Berkeley DB. -<p>We recommend that applications link against libdb.so (for example, using --ldb). Even though the linker uses the file named libdb.so, the -executable file for the application remembers the library's SONAME -(libdb-<b>major</b>.<b>minor</b>.so). This has the effect of -marking the applications with the versions they need at link time. -Because applications locate their needed SONAMEs when they are executed, -all previously linked applications will continue to run using the -library they were linked with, even when a new version of Berkeley DB is -installed and the file <b>libdb.so</b> is replaced with a new -version. -<p>Applications that know they are using features specific to a particular -Berkeley DB release can be linked to that release. For example, an application -wanting to link to Berkeley DB major release "3" can link using -ldb-3, and -applications that know about a particular minor release number can specify -both major and minor release numbers; for example, -ldb-3.5. -<p>If you want to link with Berkeley DB before performing library installation, -the "make" command will have created a shared library object in the -<b>.libs</b> subdirectory of the build directory, such as -<b>build_unix/.libs/libdb-major.minor.so</b>. If you want to link a -file against this library, with, for example, a major number of "3" and -a minor number of "5", you should be able to do something like the -following: -<p><blockquote><pre>cc -L BUILD_DIRECTORY/.libs -o testprog testprog.o -ldb-3.5 -env LD_LIBRARY_PATH="BUILD_DIRECTORY/.libs:$LD_LIBRARY_PATH" ./testprog</pre></blockquote> -<p>where <b>BUILD_DIRECTORY</b> is the full directory path to the directory -where you built Berkeley DB. -<p>The libtool program (which is configured in the build directory) can be -used to set the shared library path and run a program. For example, -the following runs the gdb debugger on the db_dump utility after setting -the appropriate paths: -<p><blockquote><pre>libtool gdb db_dump</pre></blockquote> -<p>Libtool may not know what to do with arbitrary commands (it is hardwired -to recognize "gdb" and some other commands). If it complains the mode -argument will usually resolve the problem: -<p><blockquote><pre>libtool --mode=execute my_debugger db_dump</pre></blockquote> -<p>On most systems, using libtool in this way is exactly equivalent to -setting the LD_LIBRARY_PATH environment variable and then executing the -program. On other systems, using libtool has the virtue of knowing about -any other details on systems that don't behave in this typical way. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/build_unix/install.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/build_unix/test.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/libdb/docs/ref/build_unix/solaris.html b/libdb/docs/ref/build_unix/solaris.html deleted file mode 100644 index 1a3dbdece..000000000 --- a/libdb/docs/ref/build_unix/solaris.html +++ /dev/null @@ -1,97 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Solaris</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Building Berkeley DB for UNIX systems</dl></h3></td> -<td align=right><a href="../../ref/build_unix/sco.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/build_unix/sunos.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Solaris</h1> -<p><ol> -<p><li><b>I can't compile and run multithreaded applications.</b> -<p>Special compile-time flags and additional libraries are required when -compiling threaded applications on Solaris. If you are compiling a -threaded application, you must compile with the D_REENTRANT flag and link -with the libpthread.a or libthread.a libraries: -<p><blockquote><pre>cc -mt ... -cc -D_REENTRANT ... -lthread -cc -D_REENTRANT ... -lpthread</pre></blockquote> -<p>The Berkeley DB library will automatically build with the correct options. -<hr size=1 noshade> -<p><li><b>I've installed gcc on my Solaris system, but configuration -fails because the compiler doesn't work.</b> -<p>On some versions of Solaris, there is a cc executable in the user's path, -but all it does is display an error message and fail: -<p><blockquote><pre>% which cc -/usr/ucb/cc -% cc -/usr/ucb/cc: language optional software package not installed</pre></blockquote> -<p>Because Berkeley DB always uses the native compiler in preference to gcc, this -is a fatal error. If the error message you are seeing is the following, -then this may be the problem: -<p><blockquote><pre>checking whether the C compiler (cc -O) works... no -configure: error: installation or configuration problem: C compiler cannot create executables.</pre></blockquote> -<p>The simplest workaround is to set your CC environment variable to the -system compiler and reconfigure; for example: -<p><blockquote><pre>env CC=gcc ../dist/configure</pre></blockquote> -<p>If you are using the --configure-cxx option, you may also want to specify -a C++ compiler, for example the following: -<p><blockquote><pre>env CC=gcc CCC=g++ ../dist/configure</pre></blockquote> -<hr size=1 noshade> -<p><li><b>I see the error -"libc internal error: _rmutex_unlock: rmutex not held", followed by a core -dump when running threaded or JAVA programs.</b> -<p>This is a known bug in Solaris 2.5 and it is fixed by Sun patch 103187-25. -<hr size=1 noshade> -<p><li><b>I see error reports of nonexistent files, corrupted metadata -pages and core dumps.</b> -<p>Solaris 7 contains a bug in the threading libraries (-lpthread, --lthread), which causes the wrong version of the pwrite routine to be -linked into the application if the thread library is linked in after -the C library. The result will be that the pwrite function is called -rather than the pwrite64. To work around the problem, use an explicit -link order when creating your application. -<p>Sun Microsystems is tracking this problem with Bug Id's 4291109 and 4267207, -and patch 106980-09 to Solaris 7 fixes the problem: -<p><blockquote><pre>Bug Id: 4291109 -Duplicate of: 4267207 -Category: library -Subcategory: libthread -State: closed -Synopsis: pwrite64 mapped to pwrite -Description: -When libthread is linked after libc, there is a table of functions in -libthread that gets "wired into" libc via _libc_threads_interface(). -The table in libthread is wrong in both Solaris 7 and on28_35 for the -TI_PWRITE64 row (see near the end).</pre></blockquote> -<hr size=1 noshade> -<p><li><b>I see corrupted databases when doing hot backups or creating -a hot failover archive.</b> -<p>The Solaris cp utility is implemented using the mmap system call, and -so writes are not blocked when it reads database pages. See -<a href="../../ref/transapp/reclimit.html">Berkeley DB recoverability</a> for more -information. -<hr size=1 noshade> -<p><li><b>I see errors about "open64" when building C++ applications.</b> -<p>In some releases of Solaris, include files redefine "open" when big-file -support (the HAVE_FILE_OFFSET_BITS and _FILE_OFFSET_BITS #defines) is -enabled. This causes problems when compiling for C++, where "open" is -a legal identifier used in the Berkeley DB C++ API. To work around this -problem, avoid including those include files in C++ files which also -include Berkeley DB include files and call into the Berkeley DB API, or specify the -<a href="../../ref/build_unix/conf.html#--disable-largefile">--disable-largefile</a> configuration option and then rebuild. -</ol> -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/build_unix/sco.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/build_unix/sunos.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/libdb/docs/ref/build_unix/sunos.html b/libdb/docs/ref/build_unix/sunos.html deleted file mode 100644 index bf045fc15..000000000 --- a/libdb/docs/ref/build_unix/sunos.html +++ /dev/null @@ -1,31 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: SunOS</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Building Berkeley DB for UNIX systems</dl></h3></td> -<td align=right><a href="../../ref/build_unix/solaris.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/build_unix/ultrix.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>SunOS</h1> -<p><ol> -<p><li><b>I can't specify the <a href="../../api_c/env_open.html#DB_SYSTEM_MEM">DB_SYSTEM_MEM</a> flag to <a href="../../api_c/env_open.html">DB_ENV->open</a>.</b> -<p>The <b>shmget</b>(2) interfaces are not used on SunOS releases prior -to 5.0, even though they apparently exist, because the distributed -include files did not allow them to be compiled. For this reason, it -will not be possible to specify the <a href="../../api_c/env_open.html#DB_SYSTEM_MEM">DB_SYSTEM_MEM</a> flag those -versions of SunOS. -</ol> -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/build_unix/solaris.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/build_unix/ultrix.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/libdb/docs/ref/build_unix/test.html b/libdb/docs/ref/build_unix/test.html deleted file mode 100644 index 99054f435..000000000 --- a/libdb/docs/ref/build_unix/test.html +++ /dev/null @@ -1,53 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Running the test suite under UNIX</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Building Berkeley DB for UNIX systems</dl></h3></td> -<td align=right><a href="../../ref/build_unix/shlib.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/build_unix/notes.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Running the test suite under UNIX</h1> -<p>The Berkeley DB test suite is built if you specify --enable-test as an -argument when configuring Berkeley DB. The test suite also requires that you -configure and build the Tcl API. -<p>Before running the tests for the first time, you may need to edit the -<b>include.tcl</b> file in your build directory. The Berkeley DB -configuration assumes that you intend to use the version of the tclsh -utility included in the Tcl installation with which Berkeley DB was configured -to run the test suite, and further assumes that the test suite will be -run with the libraries prebuilt in the Berkeley DB build directory. If -either of these assumptions are incorrect, you will need to edit the -<b>include.tcl</b> file and change the following line to correctly -specify the full path to the version of tclsh with which you are going -to run the test suite: -<p><blockquote><pre>set tclsh_path ...</pre></blockquote> -<p>You may also need to change the following line to correctly specify the -path from the directory where you are running the test suite to the -location of the Berkeley DB Tcl API library you built: -<p><blockquote><pre>set test_path ...</pre></blockquote> -<p>It may not be necessary that this be a full path if you have configured -your system's shared library mechanisms to search the directory where -you built or installed the Tcl library. -<p>All Berkeley DB tests are run from within <b>tclsh</b>. After starting tclsh, -you must source the file <b>test.tcl</b> in the test directory. For -example, if you built in the <b>build_unix</b> directory of the -distribution, this would be done using the following command: -<p><blockquote><pre>% source ../test/test.tcl</pre></blockquote> -<p>If no errors occur, you should get a "%" prompt. -<p>You are now ready to run tests in the test suite; see -<a href="../../ref/test/run.html">Running the test suite</a> for more -information. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/build_unix/shlib.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/build_unix/notes.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/libdb/docs/ref/build_unix/ultrix.html b/libdb/docs/ref/build_unix/ultrix.html deleted file mode 100644 index 2a520e4cb..000000000 --- a/libdb/docs/ref/build_unix/ultrix.html +++ /dev/null @@ -1,28 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Ultrix</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Building Berkeley DB for UNIX systems</dl></h3></td> -<td align=right><a href="../../ref/build_unix/sunos.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/build_win/intro.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Ultrix</h1> -<p><ol> -<p><li><b>Configuration complains that mmap(2) interfaces aren't being used.</b> -<p>The <b>mmap</b>(2) interfaces are not used on Ultrix, even though -they exist, because they are known to not work correctly. -</ol> -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/build_unix/sunos.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/build_win/intro.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/libdb/docs/ref/build_vxworks/faq.html b/libdb/docs/ref/build_vxworks/faq.html deleted file mode 100644 index b91c02223..000000000 --- a/libdb/docs/ref/build_vxworks/faq.html +++ /dev/null @@ -1,130 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: VxWorks FAQ</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Building Berkeley DB for VxWorks systems</dl></h3></td> -<td align=right><a href="../../ref/build_vxworks/notes.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade/version.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>VxWorks FAQ</h1> -<p><ol> -<p><li><b>I get the error "Workspace open failed: This project workspace is an -older format.", when trying to open the supplied workspace on Tornado 2.0 -under Windows.</b> -<p>This error will occur if the files were extracted in a manner that adds -a CR/LF to lines in the file. Make sure that you download the Berkeley DB -".zip" version of the Berkeley DB distribution, and, when extracting the Berkeley DB -sources, that you use an unzipper program that will not do any -conversion. -<p><li><b>I sometimes see spurious output errors about temporary directories.</b> -<p>These messages are coming from the <b>stat</b>(2) function call -in VxWorks. Unlike other systems, there may not be a well known -temporary directory on the target. Therefore, we highly recommend that -all applications use <a href="../../api_c/env_set_tmp_dir.html">DB_ENV->set_tmp_dir</a> to -specify a temporary directory for the application. -<p><li><b>How can I build Berkeley DB without using Tornado?</b> -<p>The simplest way to build Berkeley DB without using Tornado is to configure -Berkeley DB on a UNIX system, and then use the Makefile and include files -generated by that configuration as the starting point for your build. -The Makefile and include files are created during configuration, in the -current directory, based on your configuration decisions (for example, -debugging vs. non-debugging builds), so you'll need to configure the -system for the way you want Berkeley DB to be built. -<p>Additionally, you'll need to account for the slight difference between -the set of source files used in a UNIX build and the set used in a -VxWorks build. You can use the following command to create a list of -the Berkeley DB VxWorks files. The commands assume you are in the build_vxworks -directory of the Berkeley DB distribution: -<p><blockquote><pre>% cat > /tmp/files.sed -s/<BEGIN> FILE_// -s/_objects// -^D -% grep FILE_ BerkeleyDB.wpj | grep _objects | sed -f /tmp/files.sed > /tmp/db.files</pre></blockquote> -<p>You will then have a template Makefile and include files, and a list of -VxWorks-specific source files. You will need to convert this Makefile -and list of files into a form that is acceptable to your specific build -environment. -<p><li><b>Does Berkeley DB use floating point registers?</b> -<p>Yes, there are a few places in Berkeley DB where floating point computations -are performed. As a result, all applications that call -<i>taskSpawn</i> should specify the <b>VX_FP_TASK</b> option. -<p><li><b>Can I run the test suite under VxWorks?</b> -<p>The test suite requires the Berkeley DB Tcl library. In turn, this library -requires Tcl 8.1 or greater. In order to run the test suite, you would -need to port Tcl 8.1 or greater to VxWorks. The Tcl shell included in -<i>windsh</i> is not adequate for two reasons. First, it is based on -Tcl 8.0. Second, it does not include the necessary Tcl components for -adding a Tcl extension. -<p><li><b>Are all Berkeley DB features available for VxWorks?</b> -<p>All Berkeley DB features are available for VxWorks with the exception of the -<a href="../../api_c/db_open.html#DB_TRUNCATE">DB_TRUNCATE</a> flag for <a href="../../api_c/db_open.html">DB->open</a>. The underlying mechanism -needed for that flag is not available consistently across different file -systems for VxWorks. -<p><li><b>Are there any constraints using particular filesystem drivers?</b> -<p>There are constraints using the dosFs filesystems with Berkeley DB. Namely, -you must configure your dosFs filesystem to support long filenames if -you are using Berkeley DB logging in your application. The VxWorks' dosFs -1.0 filesystem, by default, uses the old MS-DOS 8.3 file-naming -constraints, restricting to 8 character filenames with a 3 character -extension. If you have configured with VxWorks' dosFs 2.0 you should -be compatible with Windows FAT32 filesystems which supports long -filenames. -<p><li><b>Are there any dependencies on particular filesystem drivers?</b> -<p>There is one dependency on specifics of filesystem drivers in the port -of Berkeley DB to VxWorks. Berkeley DB synchronizes data using the FIOSYNC function -to ioctl() (another option would have been to use the FIOFLUSH function -instead). The FIOSYNC function was chosen because the NFS client driver, -nfsDrv, only supports it and doesn't support FIOFLUSH. All local file -systems, as of VxWorks 5.4, support FIOSYNC -- with the exception of -rt11fsLib, which only supports FIOFLUSH. To use rt11fsLib, you will need -to modify the os/os_fsync.c file to use the FIOFLUSH function; note that -rt11fsLib cannot work with NFS clients. -<p><li><b>Are there any known filesystem problems?</b> -<p>During the course of our internal testing, we came across two problems -with the dosFs 2.0 filesystem that warranted patches from Wind River Systems. -You should ask Wind River Systems for the patches to these -problems if you encounter them. -<p>The first problem is that files will seem to disappear. You should -look at <b>SPR 31480</b> in the Wind River Systems' Support pages for -a more detailed description of this problem. -<p>The second problem is a semaphore deadlock within the dosFs filesystem -code. Looking at a stack trace via CrossWind, you will see two or more of -your application's tasks waiting in semaphore code within dosFs. The patch -for this problem is under <b>SPR 33221</b> at Wind River Systems. -There are several SPR numbers at Wind River Systems that refer to this -particular problem. -<p><li><b>Are there any filesystems I cannot use?</b> -<p>The Target Server File System (TSFS) uses the netDrv driver. This driver -does not support any ioctl that allows flushing to the disk, and therefore -cannot be used with Berkeley DB. -<p><li><b>What VxWorks primitives are used for mutual exclusion in Berkeley DB?</b> -<p>Mutexes inside of Berkeley DB use the basic binary semaphores in VxWorks. The -mutexes are created using the FIFO queue type. -<p><li><b>What are the implications of VxWorks' mutex implementation -using microkernel resources?</b> -<p>On VxWorks, the semaphore primitives implementing mutexes consume system -resources. Therefore, if an application unexpectedly fails, those -resources could leak. Berkeley DB solves this problem by always allocating -mutexes in the persistent shared memory regions. Then, if an -application fails, running recovery or explicitly removing the database -environment by calling the <a href="../../api_c/env_remove.html">DB_ENV->remove</a> method will allow Berkeley DB to -release those previously held mutex resources. If an application -specifies the <a href="../../api_c/env_open.html#DB_PRIVATE">DB_PRIVATE</a> flag (choosing not to use persistent -shared memory), and then fails, mutexes allocated in that private memory -may leak their underlying system resources. Therefore, the -<a href="../../api_c/env_open.html#DB_PRIVATE">DB_PRIVATE</a> flag should be used with caution on VxWorks. -</ol> -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/build_vxworks/notes.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade/version.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/libdb/docs/ref/build_vxworks/intro.html b/libdb/docs/ref/build_vxworks/intro.html deleted file mode 100644 index d1b8b953b..000000000 --- a/libdb/docs/ref/build_vxworks/intro.html +++ /dev/null @@ -1,103 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Building for VxWorks</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Building Berkeley DB for VxWorks systems</dl></h3></td> -<td align=right><a href="../../ref/build_win/faq.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/build_vxworks/introae.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Building for VxWorks</h1> -<p>The build_vxworks directory in the Berkeley DB distribution contains a workspace -and project files for Tornado 2.0. The Berkeley DB distribution also contains -component files for Tornado 3.1/VxWorks AE. See -<a href="../../ref/build_vxworks/introae.html">Building for VxWorks AE</a> for -information about VxWorks AE. -<p><table border=1 align=center> -<tr><th>File</th><th>Description</th></tr> -<tr> <td align=left>Berkeley DB.wsp</td> <td align=left>Berkeley DB Workspace file</td> </tr> -<tr> <td align=left>Berkeley DB.wpj</td> <td align=left>Berkeley DB Project file</td> </tr> -<tr> <td align=left>dbdemo/dbdemo.wpj</td> <td align=left><a href="../../ref/build_vxworks/notes.html">Demo program</a> project file</td> </tr> -<tr> <td align=left>db_*/*.wpj</td> <td align=left><a href="../../ref/build_vxworks/notes.html">Support utilities</a> project files</td> </tr> -</table> -<h3>Building With Tornado 2.0</h3> -<p>Open the workspace <b>Berkeley DB.wsp</b>. The list of projects -in this workspace will be shown. These projects were created for -the x86 BSP for VxWorks. -<p>The remainder of this document assumes that you already have a -VxWorks target and a target server, both up and running. It also -assumes that your VxWorks image is configured properly for your -needs. It also assumes that you -have an acceptable file system already available. See -<a href="../../ref/build_vxworks/faq.html">VxWorks FAQ</a> for more -information about file system requirements. -<p>First, you need to set the include directories. To do this, go to the -<i>Builds</i> tab for the workspace. Open up <i>Berkeley DB -Builds</i>. You will see several different builds, containing different -configurations. All of the projects in the Berkeley DB workspace are created -to be downloadable applications. -<p><table border=1 align=center> -<tr><th>Build</th><th>Description</th></tr> -<tr> <td align=left>PENTIUM_debug</td> <td align=left>x86 BSP with debugging</td> </tr> -<tr> <td align=left>PENTIUM_nodebug</td> <td align=left>x86 BSP no debugging</td> </tr> -</table> -<p>You have to add a new build specification if you use a -different BSP, want to add a build for the simulator or -want to customize further. For instance, if you have the Power PC (PPC) -BSP, you need to add a new build for the PPC tool chain. To do so, -select the "Builds" tab, select the Berkeley DB project name, and right-click. -Choose the <i>New Build...</i> selection and create the new build -target. For your new build target, you need to decide whether -it should be built for -debugging. See the properties of the Pentium builds for ways to -configure for each case. After you add this build you, you still need -to configure correctly the include directories, as described in the -sections that follow. -<p>If you are running with a different -BSP, you should remove the build specifications that do not apply to -your hardware. We recommend that you do this after you configure any -new build specifications first. The Tornado tools will get confused if -you have a PENTIUMgnu build specification for a PPC BSP, -for instance. -<p>Select the build you are interested in, and right-click. Choose the -<i>Properties...</i> selection. At this point, a tabbed dialog -should appear. In this new window, choose the <i>C/C++ compiler</i> -tab. In the edit box, you need to modify the full pathname of the -<i>build_vxworks</i> subdirectory of Berkeley DB, followed by the full -pathname of the <i>include</i> and <i>include_auto</i> -subdirectories of Berkeley DB. Then, click OK. -<p>Note that some versions of Tornado (such as the version for Windows) -do not correctly handle relative pathnames in the include paths. -If you get an error about an inability to find header files -you should edit the <i>include</i> and <i>include_auto</i> -pathnames to remove the <i>build_vxworks/..</i> relative -portion. Then you should rebuild your dependencies. -<p>To build and download the Berkeley DB downloadable application for the first time -requires several steps: -<p><ol> -<p><li>Select the build you are interested in, and right-click. Choose the -<i>Set... as Active Build</i> selection. -<p><li>Select the build you are interested in, and right-click. Choose the -<i>Dependencies...</i> selection. Run dependencies over all files -in the Berkeley DB project. -<p><li>Select the build you are interested in, and right-click. Choose the -<i>Rebuild All (Berkeley DB.out)</i> selection. -<p><li>Select the Berkeley DB project name, and right-click. Choose the -<i>Download "Berkeley DB.out"</i> selection. -</ol> -<p>You need to repeat this procedure for all builds you are interested in -building, as well as for all of the utility project builds you want to -run. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/build_win/faq.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/build_vxworks/introae.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/libdb/docs/ref/build_vxworks/introae.html b/libdb/docs/ref/build_vxworks/introae.html deleted file mode 100644 index 2905651b5..000000000 --- a/libdb/docs/ref/build_vxworks/introae.html +++ /dev/null @@ -1,135 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Building for VxWorks AE</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Building Berkeley DB for VxWorks systems</dl></h3></td> -<td align=right><a href="../../ref/build_vxworks/intro.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/build_vxworks/notes.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Building for VxWorks AE</h1> -<p>The build_vxworks directory in the Berkeley DB distribution contains component -files for Tornado 3.1. The Berkeley DB distribution also contains workspace -and project files for Tornado 2.0. See -<a href="../../ref/build_vxworks/intro.html">Building for VxWorks</a> for -information about Tornado 2.0/VxWorks 5.4. -The VxWorks AE component files are all within subdirectories, and -all component files are named <i>component.wpj</i>. -<p><table border=1 align=center> -<tr><th>File</th><th>Description</th></tr> -<tr> <td align=left>Berkeley DB/</td> <td align=left>Berkeley DB component directory</td> </tr> -<tr> <td align=left>dbdemo/dbdemo</td> <td align=left><a href="../../ref/build_vxworks/notes.html">Demo program</a> component directory</td> </tr> -<tr> <td align=left>db_*/db_*</td> <td align=left><a href="../../ref/build_vxworks/notes.html">Support utilities</a> component directories</td> </tr> -</table> -<h3>Building With Tornado 3.1</h3> -<p>This document assumes you already have a workspace set up and you -want to add Berkeley DB as a component in that workspace. You may include -this component in any domain deemed appropriate for your application. -<p>To add the Berkeley DB component into your workspace, right-click on the -"Components" and choose <i>Add existing...</i>. Enter -the pathname to your Berkeley DB distribution in the form -<i><pathname to your Berkeley DB distribution></i> -<b>/build_vxworks/Berkeley DB/</b>. -You will see <b>component.wpj</b> listed under the "Files". -Choose that filename and click "Ok". You will now have -a Berkeley DB component in your workspace. -<p>There are essentially three options regarding protection -domains and the Berkeley DB component. The first option is to add -the Berkeley DB component directly into your application domain. You may -choose to do this by downloading Berkeley DB into that domain on your -target, or by adding the component to the domain itself and it will -be built when the application domain is built. The disadvantage -of this option is that no other application domain will have access to -the Berkeley DB interfaces. -<p>The second option is to add the Berkeley DB component directly into your -<i>vxKernel</i> domain. The advantage is that any application -using the Berkeley DB interface would have access to them and no changes -would be necessary to the linkage path. The disadvantage is that -all Berkeley DB code would run with system privileges. -<p>The third option is to add a Berkeley DB shared library domain to your -system. Then add or download the Berkeley DB component to that shared -library domain. The advantage is that all application domains -using the Berkeley DB interfaces can access a single copy of the library -running in user mode. The disadvantages are that one must -remember to add the Berkeley DB shared library domain to the linkage -path of every application domain using Berkeley DB and that shared library -domains may not link against one another, a consideration if the -application using Berkeley DB is itself a shared library. -<p>We believe the options outlined above are the most common methods -that the Berkeley DB component will be used. We believe that the third -option, creating a shared library domain, is the most useful option. -Ultimately, the responsibility of choosing the correct mechanism -for including the Berkeley DB component into the appropriate domain falls -to the application developer. -<p>The remainder of this document assumes that you already have a -VxWorks AE target and a target server, both up and running. It also -assumes that your VxWorks AE image is configured properly for your -needs. It also assumes that you -have an acceptable file system already available. See -<a href="../../ref/build_vxworks/faq.html">VxWorks FAQ</a> for more -information about file system requirements. -<p>To build Berkeley DB, first, you need to set the build selection. To do -this, right-click on the Berkeley DB component name and choose the -<i>Build settings...</i> selection. If you look at the -<i>Active Build Specification</i> drop down list, you will see -several different builds, containing different configurations. -<p><table border=1 align=center> -<tr><th>Build</th><th>Description</th></tr> -<tr> <td align=left>PENTIUM2gnu.debug</td> <td align=left>PII BSP with debugging</td> </tr> -<tr> <td align=left>PENTIUM2gnu.release</td> <td align=left>PII BSP no debugging</td> </tr> -</table> -<p>You have to add a new build specification if you use a -different BSP, want to add a build for the simulator or -want to customize further. For instance, if you have the Power PC (PPC) -BSP, you need to add a new build for the PPC tool chain. To do so, -select the "Add..." button in the <i>Build Settings</i> window. -A new window will appear giving you a list of all the BSPs -you have available from which to choose. -For your new build target, you need to decide whether it should be built for -debugging. See the <i>C/C++ compiler</i> tab of the Pentium -builds for ways to -configure for each case. After you add this build, you still need -to configure the include directories correctly, as described in the -sections that follow. -<p>If you are running with a different -BSP, you should remove the build specifications that do not apply to -your hardware. We recommend that you do this after you configure any -new build specifications first. -<p>If you are adding a new build you must set the include directories -correctly. After you have added the new build in the "Build Settings" -window, click on the <i>C/C++ compiler</i> tab. -In the edit box, you need to add the pathname of the -<i>build_vxworks</i> subdirectory of Berkeley DB, followed by the -pathname of the <i>include</i> and <i>include_auto</i> -subdirectories of Berkeley DB. You should add these directories -relative to the project directory, using the <b>PRJ_DIR</b> -macro, which is the Berkeley DB subdirectory of <i>build_vxworks</i>. -Then, click OK. The typical addition of include -directories will look like: -<p><blockquote><pre>-I$(PRJ_DIR)/.. -I$(PRJ_DIR)/../../include -I$(PRJ_DIR)/../../include_auto</pre></blockquote> -<p>To build and download the Berkeley DB downloadable application for the first time -requires several steps: -<p><ol> -<p><li>Select the build you are interested in using the <i>Build Settings</i> -window. Click OK when done. -<p><li>Select the Berkeley DB component and right-click. Choose the -<i>Clean Build</i> selection. -<p><li>Select the Berkeley DB component and right-click. Choose the -<i>Download...</i> selection. -</ol> -<p>You need to repeat this procedure for all builds you are interested in -building, as well as for all of the utility project builds you want to -run. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/build_vxworks/intro.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/build_vxworks/notes.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/libdb/docs/ref/build_vxworks/notes.html b/libdb/docs/ref/build_vxworks/notes.html deleted file mode 100644 index abd321b25..000000000 --- a/libdb/docs/ref/build_vxworks/notes.html +++ /dev/null @@ -1,70 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: VxWorks notes</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Building Berkeley DB for VxWorks systems</dl></h3></td> -<td align=right><a href="../../ref/build_vxworks/introae.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/build_vxworks/faq.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>VxWorks notes</h1> -<p>Berkeley DB currently disallows the DB_TRUNC flag to <a href="../../api_c/db_open.html">DB->open</a>. The -operations that this flag represents are not fully supported under -VxWorks. -<p>The <a href="../../api_c/db_sync.html">DB->sync</a> function is implemented using an ioctl call into -the file system driver with the FIOSYNC command. Most, but not all file -system drivers support this call. Berkeley DB requires the use of a file -system supporting FIOSYNC. -<h3>Building and Running the Demo Program</h3> -<p>The demo program should be built in a manner very similar to -building Berkeley DB. If you want different or additional BSP -build specifications you should add them by following the -directions indicated in <a href="../../ref/build_vxworks/intro.html">Building -with Tornado 2.0</a> or <a href="../../ref/build_vxworks/introae.html">Building -with Tornado 3.1</a>. -<p>The demo program can be downloaded and run by calling the entry function -<b>dbdemo</b> with the pathname of a database to use. The demo -program will ask for some input keys. It creates a database and adds -those keys into the database, using the reverse of the key as the data -value. When complete you can either enter EOF (control-D) or -<b>quit</b> and the demo program will display all of the key/data -items in the database. -<h3>Building and Running the Utility Programs</h3> -<p>The Berkeley DB <a href="../../utility/index.html">utility programs</a> -can be downloaded and run by calling the -function equivalent to the utility's name. The utility functions take -a string containing all the supported arguments. The program will then -decompose that string into a traditional argc/argv used internally. -For example, to execute <a href="../../utility/db_stat.html">db_stat</a> on a database within an -environment you would execute the following from the windsh prompt. -Obviously you would change the pathname and database name to reflect -your system. -<p><blockquote><pre>-> db_stat "-h /tmp/myenvhome -d mydatabase.db"</pre></blockquote> -<h3>Notes for VxWorks 5.4</h3> -<p>The memory on VxWorks is always resident and fully shared among all -tasks running on the target. For this reason, the <a href="../../api_c/env_open.html#DB_SYSTEM_MEM">DB_SYSTEM_MEM</a> -flag is implied for any application that does not specify the -<a href="../../api_c/env_open.html#DB_PRIVATE">DB_PRIVATE</a> flag. Additionally, applications must use a segment -ID to ensure that different applications do not overwrite each other's -database environments. See the <a href="../../api_c/env_set_shm_key.html">DB_ENV->set_shm_key</a> method for more -information. Also, the <a href="../../api_c/env_open.html#DB_LOCKDOWN">DB_LOCKDOWN</a> flag has no effect. -<h3>Notes for VxWorks AE 1.1</h3> -<p>All tasks wishing to access a particular environment must run in -the same application domain. The memory regions used by the -environment are only accessible to the application domain. -If more than one application domain attempts to access an -environment simultaneously, the results are undefined but will -likely lead to corruption. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/build_vxworks/introae.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/build_vxworks/faq.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/libdb/docs/ref/build_win/faq.html b/libdb/docs/ref/build_win/faq.html deleted file mode 100644 index 5f0d32e23..000000000 --- a/libdb/docs/ref/build_win/faq.html +++ /dev/null @@ -1,60 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Windows FAQ</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Building Berkeley DB for Windows systems</dl></h3></td> -<td align=right><a href="../../ref/build_win/notes.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/build_vxworks/intro.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Windows FAQ</h1> -<p><ol> -<p><li><b>My Win* C/C++ application crashes in the Berkeley DB library when Berkeley DB calls -fprintf (or some other standard C library function).</b> -<p>You should be using the "Debug Multithreaded DLL" compiler option in -your application when you link with the -build_win32/Debug/libdb41d.lib library (this .lib file -is actually a stub for libdb41d.DLL). To check this -setting in Visual C++, choose the <i>Project/Settings</i> menu -item and select <i>Code Generation</i> under the tab marked -<i>C/C++</i>; and see the box marked <i>Use runtime -library</i>. This should be set to <i>Debug Multithreaded DLL</i>. -If your application is linked against the static library, -build_win32/Debug/libdb41sd.lib; then, you will want -to set <i>Use runtime library</i> to <i>Debug Multithreaded</i>. -<p>Setting this option incorrectly can cause multiple versions of the -standard libraries to be linked into your application (one on behalf -of your application, and one on behalf of the Berkeley DB library). That -violates assumptions made by these libraries, and traps can result. -<p><li><b>Why are the build options for DB_DLL marked as "Use MFC in a Shared DLL"? -Does Berkeley DB use MFC?</b> -<p>Berkeley DB does not use MFC at all. It does however, call malloc and free -and other facilities provided by the Microsoft C runtime library. We -found in our work that many applications and libraries are built -assuming MFC, and specifying this for Berkeley DB solves various -interoperation issues, and guarantees that the right runtime libraries -are selected. Note that because we do not use MFC facilities, the MFC -library DLL is not marked as a dependency for libdb.dll, but the -appropriate Microsoft C runtime is. -<p><li><b>The test suite hangs under Windows.</b> -<p>There are bugs in some versions of Tcl that may cause the test suite to -hang on Windows (specifically, we've seen hangs on Windows/NT 4.0). Tcl -version 8.4 (currently available as an alpha release) has fixed the -problem, or there are patches available for Tcl 8.3.2 (see bug #119188 -in the Tcl SourceForge database). Note that if you want to run the test -suite against a Debug version of Berkeley DB, you need to build a Debug -version of Tcl. This involves building Tcl from its source. -</ol> -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/build_win/notes.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/build_vxworks/intro.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/libdb/docs/ref/build_win/intro.html b/libdb/docs/ref/build_win/intro.html deleted file mode 100644 index 2b611534c..000000000 --- a/libdb/docs/ref/build_win/intro.html +++ /dev/null @@ -1,159 +0,0 @@ -<!--"@(#)intro.so 10.26 (Sleepycat) 11/18/99"--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Building for Win32</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Building Berkeley DB for Windows systems</dl></h3></td> -<td align=right><a href="../../ref/build_unix/ultrix.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/build_win/test.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Building for Win32</h1> -<p>The build_win32 directory in the Berkeley DB distribution contains project files -for Microsoft Visual C++: -<p><table border=1 align=center> -<tr><th>Project File</th><th>Description</th></tr> -<tr> <td align=center>Berkeley_DB.dsw</td> <td align=center>Visual C++ 6.0 workspace</td> </tr> -<tr> <td align=center>*.dsp</td> <td align=center>Visual C++ 6.0 projects</td> </tr> -</table> -<p>These project files can be used to build Berkeley DB for any Win32 platform: -Windows/XP, Windows/2000, Windows/NT, Windows/98 and Windows/95. -<h3>Building Berkeley DB with Visual C++</h3> -<p>Open the file <b>Berkeley_DB.dsw</b>. This workspace includes a number -of subprojects needed to build Berkeley DB. To do this in Visual C++ .NET, -choose <i>Open Solution</i> from the <i>File</i> menu. Then -choose <i>Compatible Workspace Files</i> under <i>Files of -type</i>. After you select <b>Berkeley_DB.dsw</b>, you will be prompted to -upgrade the project files. Choose <i>Yes to All</i>. -<p>First, you'll need to set the include directories. To do this, select -<i>Options...</i> from the <i>Tools</i> pull-down menu. In Visual -C++ 6.0, a tabbed dialog should appear. Choose the <i>Directories</i> -tab in the dialog, and for the <i>Platform</i>, select -<i>Win32</i>. In Visual C++ .NET, a different window appears. Choose -<i>Projects</i>, then <i>VC++ Directories</i>. -<p>In either case, choose <i>Include files</i> under <i>Show -directories for</i>. You should then add two directories to the list of -directories: the full pathname of the <i>build_win32</i> subdirectory -of Berkeley DB, followed by the full pathname of the <i>dbinc</i> -subdirectory of Berkeley DB. Then click OK. -<p>In Visual C++ 6.0, select <i>Active Project Configuration</i> under -the <i>Build</i> pull-down menu. For a debug version of the -libraries, tools, and examples, select <i>build_all -- Win32 -Debug</i>. Results from this build are put into <b>build_win32/Debug</b>. -For a release version, select <i>build_all -- Win32 Release</i>; -results are put into <b>build_win32/Release</b>. For a debug version -that has all tools and examples built with static libraries, select -<i>build_all -- Win32 Debug Static</i>; results are put into -<b>build_win32/Debug_static</b>. For a release version of the same, -select <i>build_all -- Win32 Release Static</i>; results are put into -<b>build_win32/Release_static</b>. Finally, to build, select -<i>Build build_all.exe</i> under the <i>Build</i> pull-down -menu. -<p>In Visual C++ .NET, choose the configuration from the drop down list on -the tool bar (<i>Debug</i>, <i>Release</i>, <i>Debug -Static</i> or <i>Release Static</i>). Then, to build, right-click on -<i>build_all</i> and choose <i>Build</i>. -<p>When building your application, you should normally use compile options -"debug multithreaded dll" and link against -<b>build_win32/Debug/libdb41d.lib</b>. If you want to -link against a static (non-DLL) version of the library, use the "debug -multithreaded" compile options and link against -<b>build_win32/Debug_static/libdb41sd.lib</b>. You -can also build using a release version of the libraries and tools, which -will be placed in -<b>build_win32/Release/libdb41.lib</b>. The static -version will be in -<b>build_win32/Release_static/libdb41s.lib</b>. -<p>Each release of Berkeley DB is built and tested with this procedure using -Microsoft Visual C++ 6.0, Standard Version and Microsoft Visual C++ .NET, -Standard Version. -<h3>Building the C++ API</h3> -<p>C++ support is built automatically on Win32. -<h3>Building the Java API</h3> -<p>Java support is not built automatically. The following instructions -assume that you have installed the Sun Java Development Kit in -<b>d:/java</b>. Of course, if you installed elsewhere or have different -Java software, you will need to adjust the pathnames accordingly. First, -use the previous instructions to open the Tools/Options window for adding -include directories. In addition to the directories specified previously, -add <b>d:/java/include</b> and <b>d:/java/include/win32</b>. These -are the directories needed when including <b>jni.h</b>. Now, before -clicking OK, choose <i>Executable files</i> under <i>Show -directories for</i>. Add <b>d:/java/bin</b>. That directory is needed to -find javac. Now select OK. -<p>In Visual C++ 6.0, select <i>Active Project Configuration</i> under -the <i>Build</i> pull-down menu. Choose <i>db_java -- Win32 -Release</i>. To build, select <i>Build -libdb_java41.dll</i> under the <i>Build</i> pull-down -menu. This builds the Java support library for Berkeley DB and compiles all the -java files, placing the resulting <b>db.jar</b> and -<b>dbexamples.jar</b> files in the <b>build_win32/Release</b> -subdirectory of Berkeley DB. -<p>In Visual C++ .NET, set the build type to <i>Release</i> in the drop -down list on the toolbar, then right-click on <i>db_java</i> and -choose <i>Build</i>. -<p>To run Java code, set your environment variable <b>CLASSPATH</b> to -include the full pathname of these jar files, and your environment -variable <b>PATH</b> to include the <b>build_win32/Release</b> -subdirectory. On Windows, remember that files or directories in the -<b>CLASSPATH</b> and <b>PATH</b> variables must be separated by -semicolons (unlike UNIX). Then, try running the following command as a -test: -<p><blockquote><pre>java com.sleepycat.examples.AccessExample</pre></blockquote> -<p>If you want to run Java code using a Debug build, it is slightly more -complicated. Make sure you build the Debug version of <i>db_java</i> -instead of the Release version. Also make sure that your <b>PATH</b> -contains <b>build_win32/Debug</b>. Then run the following (as one -command): -<p><blockquote><pre>java -dsleepycat.db.libname=libdb_java41d com.sleepycat.examples.AccessExample</pre></blockquote> -<h3>Building the Tcl API</h3> -<p>Tcl support is not built automatically. See -<a href="../../ref/tcl/intro.html">Loading Berkeley DB with Tcl</a> for information on -sites from which you can download Tcl and which Tcl versions are -compatible with Berkeley DB. -<p>The Tcl library must be built as the same build type as the Berkeley DB library -(both Release or both Debug). We found that the binary release of Tcl can -be used with the Release configuration of Berkeley DB, but you will need to need -to build Tcl from sources for the Debug configuration. Before building -Tcl, you will need to modify its makefile to make sure that you are -building a debug version, including thread support. This is because the -set of DLLs linked into the Tcl executable must match the corresponding -set of DLLs used by Berkeley DB. -<p>These notes assume that Tcl is installed as <b>d:/tcl</b>, but you can -change that if you want. If you run using a version of Tcl different from -the one currently being used by Sleepycat Software, you will need to -change the name of the Tcl library used in the build (for example, -<b>tcl83d.lib</b>) to the appropriate name. See -Projects->Settings->Link in the db_tcl subproject. -<p>Use the previous instructions for Visual C++ to open the -<i>Tools/Options</i> window for adding include directories. In -addition to the directories specified previously, add -<b>d:/tcl/include</b>. This is the directory that contains -<b>tcl.h</b>. Then, in that same window, choose <i>Library -Files</i> under <i>Show directories for</i>. Add <b>d:/tcl/lib</b> (or -whatever directory contains <b>tcl83d.lib</b> in your distribution) to -the list. Now, select OK. -<p>In Visual C++ 6.0, select <i>Active Project Configuration</i> under -the <i>Build</i> pull-down menu. Choose <i>db_tcl -- Win32 -Release</i>. To build, select <i>Build -libdb_tcl41.dll</i> under the <i>Build</i> pull-down -menu. This builds the Tcl support library for Berkeley DB, placing the result -into <b>build_win32/Release/libdb_tcl41.dll</b>. -Selecting an Active Configuration of <i>db_tcl -- Win32 Debug</i> will -build a debug version, placing the result into -<b>build_win32/Debug/libdb_tcl41d.dll</b>. -<p>In Visual C++ .NET, choose the build type (<i>Debug</i> or -<i>Release</i>) from the drop down list on the toolbar, then -right-click on <i>db_tcl</i> and choose <i>Build</i>. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/build_unix/ultrix.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/build_win/test.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/libdb/docs/ref/build_win/notes.html b/libdb/docs/ref/build_win/notes.html deleted file mode 100644 index b98656cf2..000000000 --- a/libdb/docs/ref/build_win/notes.html +++ /dev/null @@ -1,60 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Windows notes</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Building Berkeley DB for Windows systems</dl></h3></td> -<td align=right><a href="../../ref/build_win/test.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/build_win/faq.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Windows notes</h1> -<p><ol> -<p><li>Various Berkeley DB interfaces take a <b>mode</b> argument, which is intended -to specify the underlying file permissions for created files. Berkeley DB -currently ignores this argument on Windows systems. -<p>It would be possible to construct a set of security attributes to pass to -<b>CreateFile</b> that accurately represents the mode. In the worst -case, this would involve looking up user and all group names, and creating -an entry for each. Alternatively, we could call the <b>_chmod</b> -(partial emulation) function after file creation, although this leaves us -with an obvious race. -<p>Practically speaking, however, these efforts would be largely meaningless -on FAT, the most common file system, which only has a "readable" and -"writable" flag, applying to all users. -<p><li>On Windows/9X, files opened by multiple processes do not share data -correctly. For this reason, the <a href="../../api_c/env_open.html#DB_SYSTEM_MEM">DB_SYSTEM_MEM</a> flag is implied -for any application that does not specify the <a href="../../api_c/env_open.html#DB_PRIVATE">DB_PRIVATE</a> flag, -causing the system paging file to be used for sharing data. -<p>On all Windows platforms, system paging file memory is freed on last -close. For this reason, multiple processes sharing a database -environment created using the <a href="../../api_c/env_open.html#DB_SYSTEM_MEM">DB_SYSTEM_MEM</a> flag must arrange -for at least one process to always have the environment open, or -alternatively that any process joining the environment be prepared to -re-create it. If a shared environment is closed by all processes, a -subsequent open without specifying the <a href="../../api_c/env_open.html#DB_CREATE">DB_CREATE</a> flag will -return an error. Further, if a shared environment that supports -transactions is closed by all processes, recovery must be run by the -next process to open the environment or data corruption may occur. -<p>When using the <a href="../../api_c/env_open.html#DB_SYSTEM_MEM">DB_SYSTEM_MEM</a> flag, Berkeley DB shared regions are -created without ACLs, which means that the regions are only accessible -to a single user. If wider sharing is appropriate (for example, both -user applications and Windows/NT service applications need to access -the Berkeley DB regions), the Berkeley DB code will need to be modified to create -the shared regions with the correct ACLs. Alternatively, by not -specifying the <a href="../../api_c/env_open.html#DB_SYSTEM_MEM">DB_SYSTEM_MEM</a> flag, filesystem-backed regions -will be created instead, and the permissions on those files may be -directly specified through the <a href="../../api_c/env_open.html">DB_ENV->open</a> interface. -</ol> -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/build_win/test.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/build_win/faq.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/libdb/docs/ref/build_win/test.html b/libdb/docs/ref/build_win/test.html deleted file mode 100644 index c1581ee7a..000000000 --- a/libdb/docs/ref/build_win/test.html +++ /dev/null @@ -1,75 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Running the test suite under Windows</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Building Berkeley DB for Windows systems</dl></h3></td> -<td align=right><a href="../../ref/build_win/intro.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/build_win/notes.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Running the test suite under Windows</h1> -<p>To build the test suite on Win32 platforms, you will need to configure -Tcl support. You will also need sufficient main memory (at least 64MB), -and disk (around 250MB of disk will be sufficient). -<h3>Building the software needed by the tests</h3> -<p>To build for testing, perform the following steps. -<p><ol> -<p><li>Open the <b>build_win32/Berkeley_DB.dsw</b> workspace. -<p><li>Build the Tcl API (see <a href="../../ref/build_win/intro.html">Building the Tcl API</a> for details). -<p><li>In Visual C++ 6.0, set the active configuration to db_test -- -Debug. To set an active configuration, under the <i>Build</i> menu, -select <i>Set Active Configuration</i>. Then choose <i>db_test --- Debug</i>. In Visual C++ .NET, just make sure <i>Debug</i> is -selected in the drop down list on the tool bar. -<p><li>Build. In Visual C++ 6.0, the IDE menu item for this is called -"build dbkill.exe", even though dbkill is just one of the things that is -built. In Visual C++ .NET, right-click on the <i>db_test</i> project -and select <i>Build</i>. This step makes sure that the base Berkeley DB -.dll, tcl support, and various tools that are needed by the test suite are -all built. -</ol> -<p>Note that if you want to run the test suite against a Debug version of -Berkeley DB, you need to build a Debug version of Tcl. This involves building -Tcl from its source. -<h3>Running the test suite under Windows</h3> -<p>Before running the tests for the first time, you must edit the file -<b>include.tcl</b> in your build directory and change the line -that reads: -<p><blockquote><pre>set tclsh_path SET_YOUR_TCLSH_PATH</pre></blockquote> -<p>You will want to use the location of the <b>tclsh</b> program (be -sure to include the name of the executable). For example, if Tcl is -installed in <b>d:/tcl</b>, this line should be the following: -<p><blockquote><pre>set tclsh_path d:/tcl/bin/tclsh83d.exe</pre></blockquote> -<p>If your path includes spaces be sure to enclose it in quotes: -<p><blockquote><pre>set tclsh_path "c:/Program Files/tcl/bin/tclsh83d.exe"</pre></blockquote> -<p>If you run the test suite from the command prompt make sure that the -path to Berkeley DB's tcl library is in your current path. On Windows NT/2000/XP, -edit your PATH using the My Computer -> Properties -> Advanced --> Environment Variables dialog. On earlier versions of Windows, you -may find it convenient to add a line to c:\AUTOEXEC.BAT: -<p><blockquote><pre>SET PATH=%PATH%;c:\db\build_win32\Debug</pre></blockquote> -<p>Then, in a shell of your choice enter the following commands: -<p><ol> -<p><li>cd build_win32 -<p><li>run <b>d:/tcl/bin/tclsh83d.exe</b>, or the equivalent name of -the Tcl shell for your distribution. -<p>You should get a "%" prompt. -<p><li>% source ../test/test.tcl. -<p>If no errors occur, you should get a "%" prompt. -</ol> -<p>You are now ready to run tests in the test suite; see -<a href="../../ref/test/run.html">Running the test suite</a> for more -information. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/build_win/intro.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/build_win/notes.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/libdb/docs/ref/cam/intro.html b/libdb/docs/ref/cam/intro.html deleted file mode 100644 index b596bb99a..000000000 --- a/libdb/docs/ref/cam/intro.html +++ /dev/null @@ -1,108 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Berkeley DB Concurrent Data Store applications</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Berkeley DB Concurrent Data Store Applications</dl></h3></td> -<td align=right><a href="../../ref/env/faq.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/transapp/intro.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Berkeley DB Concurrent Data Store applications</h1> -<p>It is often desirable to have concurrent read-write access to a database -when there is no need for full recoverability or transaction semantics. -For this class of applications, Berkeley DB provides an interface supporting -deadlock-free, multiple-reader/single writer access to the database. -This means that at any instant in time, there may be either multiple -readers accessing data or a single writer modifying data. The -application is entirely unaware of which is happening, and Berkeley DB -implements the necessary locking and blocking to ensure this behavior. -<p>To create Berkeley DB Concurrent Data Store applications, you must first initialize an environment -by calling <a href="../../api_c/env_open.html">DB_ENV->open</a>. You must specify the <a href="../../api_c/env_open.html#DB_INIT_CDB">DB_INIT_CDB</a> -and <a href="../../api_c/env_open.html#DB_INIT_MPOOL">DB_INIT_MPOOL</a> flags to that interface. It is an error to -specify any of the other <a href="../../api_c/env_open.html">DB_ENV->open</a> subsystem or recovery -configuration flags, for example, <a href="../../api_c/env_open.html#DB_INIT_LOCK">DB_INIT_LOCK</a>, -<a href="../../api_c/env_open.html#DB_INIT_TXN">DB_INIT_TXN</a>, or <a href="../../api_c/env_open.html#DB_RECOVER">DB_RECOVER</a>. All databases must, of -course, be created in this environment by using the <a href="../../api_c/db_create.html">db_create</a> -interface or <a href="../../api_cxx/db_class.html">Db</a> constructor, and specifying the environment -as an argument. -<p>Berkeley DB performs appropriate locking in its interface so that safe -enforcement of the deadlock-free, multiple-reader/single-writer semantic -is transparent to the application. However, a basic understanding of -Berkeley DB Concurrent Data Store locking behavior is helpful when writing Berkeley DB Concurrent Data Store applications. -<p>Berkeley DB Concurrent Data Store -avoids deadlocks without the need for a deadlock detector by performing -all locking on an entire database at once (or on an entire environment -in the case of the <a href="../../api_c/env_set_flags.html#DB_CDB_ALLDB">DB_CDB_ALLDB</a> flag), and by ensuring that at -any given time only one thread of control is allowed to simultaneously -hold a read (shared) lock and attempt to acquire a write (exclusive) -lock. -<p>All open Berkeley DB cursors hold a read lock, which serves as a guarantee -that the database will not change beneath them; likewise, all -non-cursor <a href="../../api_c/db_get.html">DB->get</a> operations temporarily acquire and release -a read lock that is held during the actual traversal of the database. -Because read locks will not conflict with each other, any number of -cursors in any number of threads of control may be open simultaneously, -and any number of <a href="../../api_c/db_get.html">DB->get</a> operations may be concurrently in -progress. -<p>To enforce the rule that only one thread of control at a time can -attempt to upgrade a read lock to a write lock, however, Berkeley DB must -forbid multiple cursors from attempting to write concurrently. This is -done using the <a href="../../api_c/db_cursor.html#DB_WRITECURSOR">DB_WRITECURSOR</a> flag to the <a href="../../api_c/db_cursor.html">DB->cursor</a> -interface. This is the only difference between access method calls in -Berkeley DB Concurrent Data Store and in the other Berkeley DB products. The <a href="../../api_c/db_cursor.html#DB_WRITECURSOR">DB_WRITECURSOR</a> flag -causes the newly created cursor to be a "write" cursor; that is, a -cursor capable of performing writes as well as reads. Only cursors thus -created are permitted to perform write operations (either deletes or -puts), and only one such cursor can exist at any given time. -<p>Any attempt to create a second write cursor or to perform a non-cursor -write operation while a write cursor is open will block until that write -cursor is closed. Read cursors may open and perform reads without blocking -while a write cursor is extant. However, any attempts to actually perform -a write, either using the write cursor or directly using the -<a href="../../api_c/db_put.html">DB->put</a> or <a href="../../api_c/db_del.html">DB->del</a> methods, will block until all read cursors -are closed. This is how the multiple-reader/single-writer semantic is -enforced, and prevents reads from seeing an inconsistent database state -that may be an intermediate stage of a write operation. -<p>With these behaviors, Berkeley DB can guarantee deadlock-free concurrent -database access, so that multiple threads of control are free to perform -reads and writes without needing to handle synchronization themselves -or having to run a deadlock detector. Because Berkeley DB has no knowledge -of which cursors belong to which threads, however, some care must be -taken to ensure that applications do not inadvertently block themselves, -causing the application to hang and be unable to proceed. Some common -mistakes include the following: -<p><ol> -<p><li>Keeping a cursor open while issuing a <a href="../../api_c/db_put.html">DB->put</a> or <a href="../../api_c/db_del.html">DB->del</a> -access method call. -<p><li>Attempting to open a write cursor while a write cursor is already being -held open by the same thread of control. Note that it is correct -operation for one thread of control to attempt to open a write cursor -or to perform a non-cursor write (<a href="../../api_c/db_put.html">DB->put</a> or <a href="../../api_c/db_del.html">DB->del</a>) -while a write cursor is already active in another thread. It is only -a problem if these things are done within a single thread of control -- -in which case that thread will block and never be able to release the -lock that is blocking it. -<p><li>Keeping a write cursor open for an extended period of time. -<p><li>Not testing Berkeley DB error return codes (if any cursor operation returns -an unexpected error, that cursor must still be closed). -<p><li>By default, Berkeley DB Concurrent Data Store does locking on a per-database basis. For this reason, -accessing multiple databases in different orders in different threads -or processes, or leaving cursors open on one database while accessing -another database, can cause an application to hang. If this behavior -is a requirement for the application, Berkeley DB should be configured to do -locking on an environment-wide basis. See the <a href="../../api_c/env_set_flags.html#DB_CDB_ALLDB">DB_CDB_ALLDB</a> flag -of the <a href="../../api_c/env_set_flags.html">DB_ENV->set_flags</a> function for more information. -</ol> -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/env/faq.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/transapp/intro.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/libdb/docs/ref/debug/common.html b/libdb/docs/ref/debug/common.html deleted file mode 100644 index 21ca1465d..000000000 --- a/libdb/docs/ref/debug/common.html +++ /dev/null @@ -1,111 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Common errors</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Debugging Applications</dl></h3></td> -<td align=right><a href="../../ref/debug/printlog.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/build_unix/intro.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Common errors</h1> -<p>This page outlines some of the most common problems that people encounter -and some suggested courses of action. -<p><dl compact> -<p><dt><b>Symptom:</b><dd>Core dumps or garbage returns from random Berkeley DB operations. -<p><dt>Possible Cause:<dd>Failure to zero out DBT structure before issuing request. -<p><dt>Fix:<dd>Before using a <a href="../../api_c/dbt_class.html">DBT</a>, you must initialize all its elements -to 0 and then set the ones you are using explicitly. -<p><dt><b>Symptom:</b><dd>Random crashes and/or database corruption. -<p><dt>Possible Cause:<dd>Running multiple threads, but did not specify <a href="../../api_c/env_open.html#DB_THREAD">DB_THREAD</a> -to <a href="../../api_c/db_open.html">DB->open</a> or <a href="../../api_c/env_open.html">DB_ENV->open</a>. -<p><dt>Fix:<dd>Any time you are sharing a handle across multiple threads, you must -specify <a href="../../api_c/env_open.html#DB_THREAD">DB_THREAD</a> when you open that handle. -<p><dt><b>Symptom:</b><dd><a href="../../api_c/env_open.html">DB_ENV->open</a> returns EINVAL. -<p><dt>Possible Cause:<dd>The environment home directory is a remote mounted filesystem. -<p><dt>Fix:<dd>Use a locally mounted filesystem instead. -<p><dt><b>Symptom:</b><dd><a href="../../api_c/db_get.html">DB->get</a> calls are returning EINVAL. -<p><dt>Possible Cause:<dd>The application is running with threads, but did not specify the -<a href="../../api_c/dbt_class.html#DB_DBT_MALLOC">DB_DBT_MALLOC</a>, <a href="../../api_c/dbt_class.html#DB_DBT_REALLOC">DB_DBT_REALLOC</a> or <a href="../../api_c/dbt_class.html#DB_DBT_USERMEM">DB_DBT_USERMEM</a> -flags in the <a href="../../api_c/dbt_class.html">DBT</a> structures used in the call. -<p><dt>Fix:<dd>When running with threaded handles (that is, specifying <a href="../../api_c/env_open.html#DB_THREAD">DB_THREAD</a> -to <a href="../../api_c/env_open.html">DB_ENV->open</a> or <a href="../../api_c/db_open.html">DB->open</a>), you must specify one of those -flags for all <a href="../../api_c/dbt_class.html">DBT</a> structures in which Berkeley DB is returning data. -<p><dt><b>Symptom:</b><dd>Running multiple threads or processes, and the database appears to be -getting corrupted. -<p><dt>Possible Cause:<dd>Locking is not enabled. -<p><dt>Fix:<dd>Make sure that you are acquiring locks in your access methods. You -must specify <a href="../../api_c/env_open.html#DB_INIT_LOCK">DB_INIT_LOCK</a> to your <a href="../../api_c/env_open.html">DB_ENV->open</a> call and then -pass that environment to <a href="../../api_c/db_open.html">DB->open</a>. -<p><dt><b>Symptom:</b><dd>Locks are accumulating, or threads and/or processes are deadlocking, -even though there is no concurrent access to the database. -<p><dt>Possible Cause:<dd>Failure to close a cursor. -<p><dt>Fix:<dd>Cursors retain locks between calls. Everywhere the application uses -a cursor, the cursor should be explicitly closed as soon as possible after -it is used. -<p><dt><b>Symptom:</b><dd>The system locks up. -<p><dt>Possible Cause:<dd>Application not checking for <a href="../../ref/program/errorret.html#DB_LOCK_DEADLOCK">DB_LOCK_DEADLOCK</a>. -<p><dt>Fix:<dd>Unless you are using the Concurrent Data Store product, whenever you -have multiple threads and/or processes and at least one of them is -writing, you have the potential for deadlock. As a result, you must -test for the <a href="../../ref/program/errorret.html#DB_LOCK_DEADLOCK">DB_LOCK_DEADLOCK</a> return on every Berkeley DB call. In -general, updates should take place in a transaction, or you might leave -the database in an inconsistent state. Reads may take place outside -the context of a transaction under common conditions. -<p>Whenever you get a <a href="../../ref/program/errorret.html#DB_LOCK_DEADLOCK">DB_LOCK_DEADLOCK</a> return, you should do the -following: -<p><ol> -<p><li>If you are running in a transaction, abort the transaction after first -closing any cursors opened in the transaction. -<p><li>If you are not running in a transaction, simply close the cursor that got -the <a href="../../ref/program/errorret.html#DB_LOCK_DEADLOCK">DB_LOCK_DEADLOCK</a> (if it was a cursor operation), and retry. -</ol> -<p>See <a href="../../ref/transapp/put.html">Recoverability and deadlock -avoidance</a> for further information. -<p><dt><b>Symptom:</b><dd>An inordinately high number of deadlocks. -<p><dt>Possible Cause:<dd>Read-Modify-Write pattern without using the RMW flag. -<p><dt>Fix:<dd>If you frequently read a piece of data, modify it and then write -it, you may be inadvertently causing a large number of deadlocks. Try -specifying the <a href="../../api_c/dbc_get.html#DB_RMW">DB_RMW</a> flag on your get calls. -<p>Or, if the application is doing a large number of updates in a small -database, turning off Btree splits may help (see <a href="../../api_c/db_set_flags.html#DB_REVSPLITOFF">DB_REVSPLITOFF</a> -for more information.) -<p><dt><b>Symptom:</b><dd>I run recovery and it exits cleanly, but my database changes are missing. -<p><dt>Possible Cause:<dd>Failure to enable logging and transactions in the database environment; -failure to specify <a href="../../api_c/env_class.html">DB_ENV</a> handle when creating <a href="../../api_c/db_class.html">DB</a> handle; -transaction handle not passed to Berkeley DB interface; failure to commit the -transaction. -<p><dt>Fix:<dd>Make sure that the environment and database handles are properly -created, that the application passes the transaction handle returned by -<a href="../../api_c/txn_begin.html">DB_ENV->txn_begin</a> to the appropriate Berkeley DB interfaces, and that each -transaction is eventually committed. -<p><dt><b>Symptom:</b><dd>Recovery fails. -<p><dt>Possible Cause:<dd>A database was updated in a transactional environment, both with and -without transactional handles. -<p><dt>Fix:<dd>If any database write operation is done using a transaction handle, -every write operation must be done in the context of a transaction. -<p><dt><b>Symptom:</b><dd>A database environment locks up, sometimes gradually. -<p><dt>Possible Cause:<dd>A thread of control exited unexpectedly, holding Berkeley DB resources. -<p><dt>Fix:<dd>Whenever a thread of control exits holding Berkeley DB resources, all threads -of control must exit the database environment, and recovery must be run. -<p><dt><b>Symptom:</b><dd>A database environment locks up, sometimes gradually. -<p><dt>Possible Cause:<dd>Cursors are not being closed before transaction abort. -<p><dt>Fix:<dd>Before an application aborts a transaction, any cursors opened within -the context of that transaction must be closed. -<p><dt><b>Symptom:</b><dd>Transaction abort or recovery fail, or database corruption occurs. -<p><dt>Possible Cause:<dd>Log files were removed before it was safe. -<p><dt>Fix:<dd>Do not remove any log files from a database environment until Berkeley DB -declares it safe. -</dl> -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/debug/printlog.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/build_unix/intro.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/libdb/docs/ref/debug/compile.html b/libdb/docs/ref/debug/compile.html deleted file mode 100644 index afc14f9bd..000000000 --- a/libdb/docs/ref/debug/compile.html +++ /dev/null @@ -1,45 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Compile-time configuration</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Debugging Applications</dl></h3></td> -<td align=right><a href="../../ref/debug/intro.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/debug/runtime.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Compile-time configuration</h1> -<p>There are three compile-time configuration options that assist in -debugging Berkeley DB and Berkeley DB applications: -<p><dl compact> -<p><dt><a href="../../ref/build_unix/conf.html#--enable-debug">--enable-debug</a><dd>If you want to build Berkeley DB with <b>-g</b> as the C and C++ compiler -flag, enter --enable-debug as an argument to configure. This will create -Berkeley DB with debugging symbols, as well as load various Berkeley DB routines -that can be called directly from a debugger to display database page -content, cursor queues, and so forth. (Note that the <b>-O</b> -optimization flag will still be specified. To compile with only the -<b>-g</b>, explicitly set the <b>CFLAGS</b> environment variable -before configuring.) -<p><dt><a href="../../ref/build_unix/conf.html#--enable-diagnostic">--enable-diagnostic</a><dd>If you want to build Berkeley DB with debugging run-time sanity checks and with -DIAGNOSTIC #defined during compilation, enter --enable-diagnostic as an -argument to configure. This will cause a number of special checks to be -performed when Berkeley DB is running. This flag should not be defined when -configuring to build production binaries because it degrades performance. -<p><dt><a href="../../ref/build_unix/conf.html#--enable-umrw">--enable-umrw</a><dd>When compiling Berkeley DB for use in run-time memory consistency checkers -(in particular, programs that look for reads and writes of uninitialized -memory), use --enable-umrw as an argument to configure. This -guarantees, among other things, that Berkeley DB will completely initialize -allocated pages rather than initializing only the minimum necessary -amount. -</dl> -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/debug/intro.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/debug/runtime.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/libdb/docs/ref/debug/intro.html b/libdb/docs/ref/debug/intro.html deleted file mode 100644 index a2f2c2f3c..000000000 --- a/libdb/docs/ref/debug/intro.html +++ /dev/null @@ -1,59 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Introduction</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Debugging Applications</dl></h3></td> -<td align=right><a href="../../ref/install/rpm.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/debug/compile.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Introduction</h1> -<p>Because Berkeley DB is an embedded library, debugging applications that use -Berkeley DB is both harder and easier than debugging a separate server. -Debugging can be harder because when a problem arises, it is not always -readily apparent whether the problem is in the application, is in the -database library, or is a result of an unexpected interaction between -the two. Debugging can be easier because it is easier to track down a -problem when you can review a stack trace rather than deciphering -interprocess communication messages. This chapter is intended to assist -you with debugging applications and reporting bugs to us so that we can -provide you with the correct answer or fix as quickly as possible. -<p>When you encounter a problem, there are a few general actions you can -take: -<p><dl compact> -<p><dt>Review the Berkeley DB error output<dd>If an error output mechanism has been configured in the Berkeley DB -environment, additional run-time error messages are made available to -the applications. If you are not using an environment, it is well worth -modifying your application to create one so that you can get more -detailed error messages. See <a href="runtime.html">Run-time error -information</a> for more information on configuring Berkeley DB to output these -error messages. -<p><dt>Review <a href="../../api_c/env_set_verbose.html">DB_ENV->set_verbose</a><dd>Check the list of flags for the <a href="../../api_c/env_set_verbose.html">DB_ENV->set_verbose</a> function, and -see if any of them will produce additional information that might help -understand the problem. -<p><dt>Add run-time diagnostics<dd>You can configure and build Berkeley DB to perform run-time diagnostics. (By -default, these checks are not done because they can seriously impact -performance.) See <a href="compile.html">Compile-time configuration</a> for more -information. -<p><dt>Apply all available patches<dd>Before reporting a problem to Sleepycat Software, please upgrade to the -latest Sleepycat Software release of Berkeley DB, if possible, or at least -make sure you have applied any updates available for your release from -the <a href="http://www.sleepycat.com/update/index.html">Sleepycat -Software web site</a>. -<p><dt>Run the test suite<dd>If you see repeated failures or failures of simple test cases, run the -Berkeley DB test suite to determine whether the distribution of Berkeley DB you are -using was built and configured correctly. -</dl> -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/install/rpm.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/debug/compile.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/libdb/docs/ref/debug/printlog.html b/libdb/docs/ref/debug/printlog.html deleted file mode 100644 index b09f30be2..000000000 --- a/libdb/docs/ref/debug/printlog.html +++ /dev/null @@ -1,153 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Reviewing Berkeley DB log files</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Debugging Applications</dl></h3></td> -<td align=right><a href="../../ref/debug/runtime.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/debug/common.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Reviewing Berkeley DB log files</h1> -<p>If you are running with transactions and logging, the <a href="../../utility/db_printlog.html">db_printlog</a> -utility can be a useful debugging aid. The <a href="../../utility/db_printlog.html">db_printlog</a> utility -will display the contents of your log files in a human readable (and -machine-processable) format. -<p>The <a href="../../utility/db_printlog.html">db_printlog</a> utility will attempt to display any and all -log files present in a designated db_home directory. For each log record, -<a href="../../utility/db_printlog.html">db_printlog</a> will display a line of the form: -<p><blockquote><pre>[22][28]db_big: rec: 43 txnid 80000963 prevlsn [21][10483281]</pre></blockquote> -<p>The opening numbers in square brackets are the <i>log sequence -number</i> (<i>LSN</i>) of the log record being displayed. The first -number indicates the log file in which the record appears, and the -second number indicates the offset in that file of the record. -<p>The first character string identifies the particular log operation being -reported. The log records corresponding to particular operations are -described following. The rest of the line consists of name/value pairs. -<p>The rec field indicates the record type (this is used to dispatch records -in the log to appropriate recovery functions). -<p>The txnid field identifies the transaction for which this record was -written. A txnid of 0 means that the record was written outside the -context of any transaction. You will see these most frequently for -checkpoints. -<p>Finally, the prevlsn contains the LSN of the last record for this -transaction. By following prevlsn fields, you can accumulate all the -updates for a particular transaction. During normal abort processing, -this field is used to quickly access all the records for a particular -transaction. -<p>After the initial line identifying the record type, each field of the log -record is displayed, one item per line. There are several fields that -appear in many different records and a few fields that appear only in -some records. -<p>The following table presents each currently written log record type with -a brief description of the operation it describes. -<!--START LOG RECORD TYPES--> -<p><table border=1> -<tr><th>Log Record Type</th><th>Description</th></tr> -<tr><td>bam_adj</td><td>Used when we insert/remove an index into/from the page header of a Btree page.</td></tr> -<tr><td>bam_cadjust</td><td>Keeps track of record counts in a Btree or Recno database.</td></tr> -<tr><td>bam_cdel</td><td>Used to mark a record on a page as deleted.</td></tr> -<tr><td>bam_curadj</td><td>Used to adjust a cursor location when a nearby record changes in a Btree database.</td></tr> -<tr><td>bam_rcuradj</td><td>Used to adjust a cursor location when a nearby record changes in a Recno database.</td></tr> -<tr><td>bam_repl</td><td>Describes a replace operation on a record.</td></tr> -<tr><td>bam_root</td><td>Describes an assignment of a root page.</td></tr> -<tr><td>bam_rsplit</td><td>Describes a reverse page split.</td></tr> -<tr><td>bam_split</td><td>Describes a page split.</td></tr> -<tr><td>crdel_metasub</td><td>Describes the creation of a metadata page for a subdatabase.</td></tr> -<tr><td>db_addrem</td><td>Add or remove an item from a page of duplicates.</td></tr> -<tr><td>db_big</td><td>Add an item to an overflow page (<i>overflow pages</i> contain items too large to place on the main page)</td></tr> -<tr><td>db_cksum</td><td>Unable to checksum a page.</td></tr> -<tr><td>db_debug</td><td>Log debugging message.</td></tr> -<tr><td>db_noop</td><td>This marks an operation that did nothing but update the LSN on a page.</td></tr> -<tr><td>db_ovref</td><td>Increment or decrement the reference count for a big item.</td></tr> -<tr><td>db_pg_alloc</td><td>Indicates that we allocated a page to a Btree.</td></tr> -<tr><td>db_pg_free</td><td>Indicates that we freed a page in the Btree (freed pages are added to a freelist and reused).</td></tr> -<tr><td>db_relink</td><td>Fix prev/next chains on duplicate pages because a page was added or removed.</td></tr> -<tr><td>dbreg_register</td><td>Records an open of a file (mapping the filename to a log-id that is used in subsequent log operations).</td></tr> -<tr><td>ham_chgpg</td><td>Used to adjust a cursor location when a Hash page is removed, and its elements are moved to a different Hash page.</td></tr> -<tr><td>ham_copypage</td><td>Used when we empty a bucket page, but there are overflow pages for the bucket; one needs to be copied back into the actual bucket.</td></tr> -<tr><td>ham_curadj</td><td>Used to adjust a cursor location when a nearby record changes in a Hash database.</td></tr> -<tr><td>ham_groupalloc</td><td>Allocate some number of contiguous pages to the Hash database.</td></tr> -<tr><td>ham_insdel</td><td>Insert/delete an item on a Hash page.</td></tr> -<tr><td>ham_metagroup</td><td>Update the metadata page to reflect the allocation of a sequence of contiguous pages.</td></tr> -<tr><td>ham_newpage</td><td>Adds or removes overflow pages from a Hash bucket.</td></tr> -<tr><td>ham_replace</td><td>Handle updates to records that are on the main page.</td></tr> -<tr><td>ham_splitdata</td><td>Record the page data for a split.</td></tr> -<tr><td>qam_add</td><td>Describes the actual addition of a new record to a Queue.</td></tr> -<tr><td>qam_del</td><td>Delete a record in a Queue.</td></tr> -<tr><td>qam_delext</td><td>Delete a record in a Queue with extents.</td></tr> -<tr><td>qam_incfirst</td><td>Increments the record number that refers to the first record in the database.</td></tr> -<tr><td>qam_mvptr</td><td>Indicates that we changed the reference to either or both of the first and current records in the file.</td></tr> -<tr><td>txn_child</td><td>Commit a child transaction.</td></tr> -<tr><td>txn_ckp</td><td>Transaction checkpoint.</td></tr> -<tr><td>txn_recycle</td><td>Transaction IDs wrapped.</td></tr> -<tr><td>txn_regop</td><td>Logs a regular (non-child) transaction commit.</td></tr> -<tr><td>txn_xa_regop</td><td>Logs a prepare message.</td></tr> -</table> -<!--END LOG RECORD TYPES--> -<h3>Augmenting the Log for Debugging</h3> -<p>When debugging applications, it is sometimes useful to log not only the -actual operations that modify pages, but also the underlying Berkeley DB -functions being executed. This form of logging can add significant bulk -to your log, but can permit debugging application errors that are almost -impossible to find any other way. To turn on these log messages, specify -the --enable-debug_rop and --enable-debug_wop configuration options when -configuring Berkeley DB. See <a href="../../ref/build_unix/conf.html">Configuring -Berkeley DB</a> for more information. -<h3>Extracting Committed Transactions and Transaction Status</h3> -<p>Sometimes, it is helpful to use the human-readable log output to -determine which transactions committed and aborted. The awk script, -commit.awk, (found in the db_printlog directory of the Berkeley DB -distribution) allows you to do just that. The following command, -where log_output is the output of db_printlog, will display a list of -the transaction IDs of all committed transactions found in the log: -<p><blockquote><pre>awk -f commit.awk log_output</pre></blockquote> -<p>If you need a complete list of both committed and aborted transactions, -then the script status.awk will produce it. The syntax is as follows: -<p><blockquote><pre>awk -f status.awk log_output</pre></blockquote> -<h3>Extracting Transaction Histories</h3> -<p>Another useful debugging aid is to print out the complete history of a -transaction. The awk script txn.awk allows you to do that. The -following command line, where log_output is the output of -<a href="../../utility/db_printlog.html">db_printlog</a> and txnlist is a comma-separated list of transaction -IDs, will display all log records associated with the designated -transaction ids: -<p><blockquote><pre>awk -f txn.awk TXN=txnlist log_output</pre></blockquote> -<h3>Extracting File Histories</h3> -<p>The awk script fileid.awk allows you to extract all log records that -refer to a designated file. The syntax for the fileid.awk script is -the following, where log_output is the output of db_printlog and fids -is a comma-separated list of fileids: -<p><blockquote><pre>awk -f fileid.awk PGNO=fids log_output</pre></blockquote> -<h3>Extracting Page Histories</h3> -<p>The awk script pgno.awk allows you to extract all log records that refer -to designated page numbers. However, because this script will extract -records with the designated page numbers for all files, it is most -useful in conjunction with the fileid script. The syntax for the -pgno.awk script is the following, where log_output is the output of -db_printlog and pgnolist is a comma-separated list of page numbers: -<p><blockquote><pre>awk -f pgno.awk PGNO=pgnolist log_output</pre></blockquote> -<h3>Other log processing tools</h3> -<p>The awk script count.awk prints out the number of log records -encountered that belonged to some transaction (that is, the number of -log records excluding those for checkpoints and -non-transaction-protected operations). -<p>The script range.awk will extract a subset of a log. This is useful -when the output of <a href="../../utility/db_printlog.html">db_printlog</a> is too large to be reasonably -manipulated with an editor or other tool. The syntax for range.awk is -the following, where <b>sf</b> and <b>so</b> represent the LSN -of the beginning of the sublog you want to extract, and <b>ef</b> and -<b>eo</b> represent the LSN of the end of the sublog you want to -extract: -<p><blockquote><pre>awk -f range.awk START_FILE=sf START_OFFSET=so END_FILE=ef END_OFFSET=eo log_output</pre></blockquote> -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/debug/runtime.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/debug/common.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/libdb/docs/ref/debug/runtime.html b/libdb/docs/ref/debug/runtime.html deleted file mode 100644 index 5e703f46c..000000000 --- a/libdb/docs/ref/debug/runtime.html +++ /dev/null @@ -1,48 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Run-time error information</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Debugging Applications</dl></h3></td> -<td align=right><a href="../../ref/debug/compile.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/debug/printlog.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Run-time error information</h1> -<p>Normally, when an error occurs in the Berkeley DB library, an integer value -(either a Berkeley DB specific value or a system <b>errno</b> value) is -returned by the Berkeley DB interface. In some cases, however, this value -may be insufficient to completely describe the cause of the error, -especially during initial application debugging. -<p>There are four interfaces intended to provide applications with -additional run-time error information: -<a href="../../api_c/env_set_errcall.html">DB_ENV->set_errcall</a>, <a href="../../api_c/env_set_errfile.html">DB_ENV->set_errfile</a>, -<a href="../../api_c/env_set_errpfx.html">DB_ENV->set_errpfx</a>, and <a href="../../api_c/env_set_verbose.html">DB_ENV->set_verbose</a>. -<p>If the environment is configured with these interfaces, many Berkeley DB errors -will result in additional information being written to a file or passed -as an argument to an application function. -<p>The Berkeley DB error-reporting facilities do not slow performance or -significantly increase application size, and may be run during normal -operation as well as during debugging. Where possible, we recommend -that these options always be configured and the output saved in the -filesystem. We have found that this often saves time when debugging -installation or other system-integration problems. -<p>In addition, there are three interfaces to assist applications in -displaying their own error messages: <a href="../../api_c/env_strerror.html">db_strerror</a>, -<a href="../../api_c/env_err.html">DB_ENV->err</a>, and <a href="../../api_c/env_err.html">DB_ENV->errx</a>. The first is a superset of -the ANSI C strerror interface, and returns a descriptive string for any -error return from the Berkeley DB library. The <a href="../../api_c/env_err.html">DB_ENV->err</a> and -<a href="../../api_c/env_err.html">DB_ENV->errx</a> methods use the error message configuration options -described previously to format and display error messages to appropriate -output devices. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/debug/compile.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/debug/printlog.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/libdb/docs/ref/distrib/layout.html b/libdb/docs/ref/distrib/layout.html deleted file mode 100644 index f2872f00a..000000000 --- a/libdb/docs/ref/distrib/layout.html +++ /dev/null @@ -1,80 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Source code layout</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Distribution</dl></h3></td> -<td align=right><a href="../../ref/distrib/port.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/refs/refs.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Source code layout</h1> -<p><table border=1 align=center> -<tr><th>Directory</th><th>Description</th></tr> -<tr><td>LICENSE</td><td>Berkeley DB Copyright</td></tr> -<tr><td>btree</td><td>Btree access method source code</td></tr> -<tr><td>build_unix</td><td>UNIX build directory</td></tr> -<tr><td>build_vxworks</td><td>VxWorks build directory.</td></tr> -<tr><td>build_win32</td><td>Windows build directory.</td></tr> -<tr><td>clib</td><td>C library replacement functions</td></tr> -<tr><td>common</td><td>Common Berkeley DB functions</td></tr> -<tr><td>crypto</td><td>Cryptographic support</td></tr> -<tr><td>cxx</td><td>C++ API</td></tr> -<tr><td>db</td><td>Berkeley DB database interfaces</td></tr> -<tr><td>db185</td><td>Berkeley DB version 1.85 compatibility API</td></tr> -<tr><td>db_archive</td><td>The db_archive utility</td></tr> -<tr><td>db_checkpoint</td><td>The db_checkpoint utility</td></tr> -<tr><td>db_deadlock</td><td>The db_deadlock utility</td></tr> -<tr><td>db_dump</td><td>The db_dump utility</td></tr> -<tr><td>db_dump185</td><td>The db_dump185 utility</td></tr> -<tr><td>db_load</td><td>The db_load utility</td></tr> -<tr><td>db_printlog</td><td>The db_printlog debugging utility</td></tr> -<tr><td>db_recover</td><td>The db_recover utility</td></tr> -<tr><td>db_stat</td><td>The db_stat utility</td></tr> -<tr><td>db_upgrade</td><td>The db_upgrade utility</td></tr> -<tr><td>db_verify</td><td>The db_verify utility</td></tr> -<tr><td>dbinc</td><td>C language include files</td></tr> -<tr><td>dbinc_auto</td><td>Automatically generated C language include files</td></tr> -<tr><td>dbm</td><td>The dbm/ndbm compatibility APIs</td></tr> -<tr><td>dbreg</td><td>Berkeley DB database handle logging support</td></tr> -<tr><td>dist</td><td>Berkeley DB administration/distribution tools</td></tr> -<tr><td>docs</td><td>Documentation</td></tr> -<tr><td>env</td><td>Berkeley DB environment interfaces</td></tr> -<tr><td>examples_c</td><td>C API example programs</td></tr> -<tr><td>examples_cxx</td><td>C++ API example programs</td></tr> -<tr><td>examples_java</td><td>Java API example programs</td></tr> -<tr><td>fileops</td><td>File object operation support</td></tr> -<tr><td>hash</td><td>Hash access method</td></tr> -<tr><td>hmac</td><td>Checksum support</td></tr> -<tr><td>hsearch</td><td>The hsearch compatibility API</td></tr> -<tr><td>java</td><td>Java API</td></tr> -<tr><td>libdb_java</td><td>The libdb_java shared library</td></tr> -<tr><td>lock</td><td>Lock manager</td></tr> -<tr><td>log</td><td>Log manager</td></tr> -<tr><td>mp</td><td>Shared memory buffer pool</td></tr> -<tr><td>mutex</td><td>Mutexes</td></tr> -<tr><td>os</td><td>POSIX 1003.1 operating-system specific functionality</td></tr> -<tr><td>os_vxworks</td><td>VxWorks operating-system specific functionality</td></tr> -<tr><td>os_win32</td><td>Windows operating-system specific functionality</td></tr> -<tr><td>perl</td><td>DB_File and BerkeleyDB Perl modules</td></tr> -<tr><td>qam</td><td>Queue access method source code</td></tr> -<tr><td>rep</td><td>Replication source code</td></tr> -<tr><td>rpc_client</td><td>RPC client interface</td></tr> -<tr><td>rpc_server</td><td>RPC server utility</td></tr> -<tr><td>tcl</td><td>Tcl API</td></tr> -<tr><td>test</td><td>Test suite</td></tr> -<tr><td>txn</td><td>Transaction manager</td></tr> -<tr><td>xa</td><td>X/Open Distributed Transaction Processing XA interface</td></tr> -</table> -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/distrib/port.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/refs/refs.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/libdb/docs/ref/distrib/port.html b/libdb/docs/ref/distrib/port.html deleted file mode 100644 index b993041ce..000000000 --- a/libdb/docs/ref/distrib/port.html +++ /dev/null @@ -1,110 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Porting Berkeley DB to new architectures</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Distribution</dl></h3></td> -<td align=right><a href="../../ref/test/faq.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/distrib/layout.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Porting Berkeley DB to new architectures</h1> -<p>Berkeley DB is generally easy to port to new architectures. Berkeley DB was -designed to be as portable as possible, and has been ported to a wide -variety of systems, from Wind River's Tornado system, to VMS, to -Windows/NT and Windows/95, and most existing UNIX platforms. It runs -on 16, 32 and 64-bit machines, little or big-endian. The difficulty of -a port depends on how much of the ANSI C and POSIX 1003.1 standards the -new architecture offers. -<p>An abstraction layer separates the main Berkeley DB code from the operating -system and architecture specific components. This layer is comprised -of approximately 2500 lines of C language code, found in the <b>os</b> -subdirectory of the Berkeley DB distribution. The following list of files -include functionality that may need to be modified or implemented in -order to support a new architecture. Within each file, there is usually -one, but sometimes several functions (for example, the -<b>os_alloc.c</b> file contains the malloc, calloc, realloc, free, -and strdup functions). -<p><table border=1 align=center> -<tr><th>Source file</th><th>Description</th></tr> -<tr><td>os_abs.c</td><td>Return if a filename is an absolute pathname</td></tr> -<tr><td>os_alloc.c</td><td>ANSI C malloc, calloc, realloc, strdup, free front-ends</td></tr> -<tr><td>os_clock.c</td><td>Return the current time-of-day</td></tr> -<tr><td>os_config.c</td><td>Return run-time configuration information</td></tr> -<tr><td>os_dir.c</td><td>Read the filenames from a directory</td></tr> -<tr><td>os_errno.c</td><td>Set/get the ANSI C errno value</td></tr> -<tr><td>os_fid.c</td><td>Create a unique ID for a file</td></tr> -<tr><td>os_fsync.c</td><td>POSIX 1003.1 fsync front-end</td></tr> -<tr><td>os_handle.c</td><td>Open file handles</td></tr> -<tr><td>os_id.c</td><td>Return thread ID</td></tr> -<tr><td>os_map.c</td><td>Map a shared memory area</td></tr> -<tr><td>os_method.c</td><td>Run-time replacement of system calls</td></tr> -<tr><td>os_oflags.c</td><td>Convert POSIX 1003.1 open flags, modes to Berkeley DB flags</td></tr> -<tr><td>os_open.c</td><td>Open file handles</td></tr> -<tr><td>os_region.c</td><td>Map a shared memory area</td></tr> -<tr><td>os_rename.c</td><td>POSIX 1003.1 rename call</td></tr> -<tr><td>os_root.c</td><td>Return if application has special permissions</td></tr> -<tr><td>os_rpath.c</td><td>Return last pathname separator</td></tr> -<tr><td>os_rw.c</td><td>POSIX 1003.1 read/write calls</td></tr> -<tr><td>os_seek.c</td><td>POSIX 1003.1 seek call</td></tr> -<tr><td>os_sleep.c</td><td>Cause a thread of control to release the CPU</td></tr> -<tr><td>os_spin.c</td><td>Return the times to spin while waiting for a mutex</td></tr> -<tr><td>os_stat.c</td><td>POSIX 1003.1 stat call</td></tr> -<tr><td>os_tmpdir.c</td><td>Set the path for temporary files</td></tr> -<tr><td>os_unlink.c</td><td>POSIX 1003.1 unlink call</td></tr> -</table> -<p>All but a few of these files contain relatively trivial pieces of code. -Typically, there is only a single version of the code for all platforms -Berkeley DB supports, and that code lives in the <b>os</b> directory of the -distribution. Where different code is required, the code is either -conditionally compiled or an entirely different version is written. For -example, VxWorks versions of some of these files can be found in the -distribution directory os_vxworks, and Win32 versions can be found in -os_win32. -<p>Historically, there are only two difficult questions to answer for each -new port. The first question is how to handle shared memory. In order -to write multiprocess database applications (not multithreaded, but -threads of control running in different address spaces), Berkeley DB must be -able to name pieces of shared memory and access them from multiple -processes. On UNIX/POSIX systems, we use <b>mmap</b> and -<b>shmget</b> for that purpose, but any interface that provides access -to named shared memory is sufficient. If you have a simple, flat -address space, you should be able to use the code in -<b>os_vxworks/os_map.c</b> as a starting point for the port. If you -are not intending to write multiprocess database applications, then -this won't be necessary, as Berkeley DB can simply allocate memory from the -heap if all threads of control will live in a single address space. -<p>The second question is mutex support. Berkeley DB requires some form of -<b>self-blocking</b> mutual exclusion mutex. Blocking mutexes are -preferred as they tend to be less CPU-expensive and less likely to cause -thrashing. If blocking mutexes are not available, however, test-and-set -will work as well. The code for mutexes is in two places in the system: -the include file <b>dbinc/mutex.h</b>, and the distribution directory -<b>mutex</b>. -<p>Berkeley DB uses the GNU autoconf tools for configuration on almost all of -the platforms it supports. Specifically, the include file -<b>db_config.h</b> configures the Berkeley DB build. The simplest way to -begin a port is to configure and build Berkeley DB on a UNIX or UNIX-like -system, and then take the <b>Makefile</b> and <b>db_config.h</b> -file created by that configuration, and modify it by hand to reflect -the needs of the new architecture. Unless you're already familiar with -the GNU autoconf toolset, we don't recommend you take the time to -integrate your changes back into the Berkeley DB autoconfiguration framework. -Instead, send Sleepycat Software context diffs of your changes and any -new source files you created, and we'll integrate the changes into our -source tree. -<p>Finally, we're happy to work with you on the port, or potentially, do -the port ourselves, if that is of interest to you. Regardless, if you -have any porting questions, just let us know, and we will be happy to -answer them. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/test/faq.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/distrib/layout.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/libdb/docs/ref/dumpload/format.html b/libdb/docs/ref/dumpload/format.html deleted file mode 100644 index e99727275..000000000 --- a/libdb/docs/ref/dumpload/format.html +++ /dev/null @@ -1,70 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Dump output formats</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Dumping and Reloading</dl></h3></td> -<td align=right><a href="../../ref/dumpload/utility.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/dumpload/text.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Dump output formats</h1> -<p>There are two output formats used by <a href="../../utility/db_dump.html">db_dump</a> and <a href="../../utility/db_dump.html">db_dump185</a>. -<p>In both output formats, the first few lines of the output contain header -information describing the underlying access method, filesystem page size, -and other bookkeeping information. -<p>The header information starts with a single line, VERSION=N, where N is -the version number of the dump output format. -<p>The header information is then output in name=value pairs, where name may -be any of the keywords listed in the <a href="../../utility/db_load.html">db_load</a> manual page, and -value will be its value. Although this header information can be manually -edited before the database is reloaded, there is rarely any reason to do -so because all of this information can also be specified or overridden by -command-line arguments to <a href="../../utility/db_load.html">db_load</a>. -<p>The header information ends with single line HEADER=END. -<p>Following the header information are the key/data pairs from the -database. If the database being dumped is a Btree or Hash database, or -if the <b>-k</b> option was specified, the output will be paired lines -of text where the first line of the pair is the key item, and the second -line of the pair is its corresponding data item. If the database being -dumped is a Queue or Recno database, and the <b>-k</b> option was not -specified, the output will be lines of text where each line is the next -data item for the database. Each of these lines is preceded by a single -space. -<p>If the <b>-p</b> option to <a href="../../utility/db_dump.html">db_dump</a> or <a href="../../utility/db_dump.html">db_dump185</a> was -specified, the key/data lines will consist of single characters -representing any characters from the database that are <i>printing -characters</i> and backslash (<b>\</b>) escaped characters -for any that were not. Backslash characters appearing in the output mean -one of two things: if the backslash character precedes another backslash -character, it means that a literal backslash character occurred in the -key or data item. If the backslash character precedes any other -character, the next two characters must be interpreted as hexadecimal -specification of a single character; for example, <b>\0a</b> -is a newline character in the ASCII character set. -<p>Although some care should be exercised, it is perfectly reasonable to use -standard text editors and tools to edit databases dumped using the -<b>-p</b> option before reloading them using the <a href="../../utility/db_load.html">db_load</a> -utility. -<p>Note that the definition of a printing character may vary from system to -system, so database representations created using the <b>-p</b> -option may be less portable than those created without it. -<p>If the <b>-p</b> option to <a href="../../utility/db_dump.html">db_dump</a> or <a href="../../utility/db_dump.html">db_dump185</a> is -not specified, each output line will consist of paired hexadecimal values; -for example, the line <b>726f6f74</b> is the string <b>root</b> in -the ASCII character set. -<p>In all output formats, the key and data items are ended by a single line -DATA=END. -<p>Where multiple databases have been dumped from a file, the overall output -will repeat; that is, a new set of headers and a new set of data items. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/dumpload/utility.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/dumpload/text.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/libdb/docs/ref/dumpload/text.html b/libdb/docs/ref/dumpload/text.html deleted file mode 100644 index 53153c25b..000000000 --- a/libdb/docs/ref/dumpload/text.html +++ /dev/null @@ -1,33 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Loading text into 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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Dumping and Reloading</dl></h3></td> -<td align=right><a href="../../ref/dumpload/format.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/install/file.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Loading text into databases</h1> -<p>The <a href="../../utility/db_load.html">db_load</a> utility can be used to load text into databases. -The <b>-T</b> option permits nondatabase applications to create -flat-text files that are then loaded into databases for fast, -highly-concurrent access. For example, the following command loads the -standard UNIX <b>/etc/passwd</b> file into a database, with the login -name as the key item and the entire password entry as the data item: -<p><blockquote><pre>awk -F: '{print $1; print $0}' < /etc/passwd |\ - sed 's/\\/\\\\/g' | db_load -T -t hash passwd.db</pre></blockquote> -<p>Note that backslash characters naturally occurring in the text are escaped -to avoid interpretation as escape characters by <a href="../../utility/db_load.html">db_load</a>. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/dumpload/format.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/install/file.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/libdb/docs/ref/dumpload/utility.html b/libdb/docs/ref/dumpload/utility.html deleted file mode 100644 index 9e7698f61..000000000 --- a/libdb/docs/ref/dumpload/utility.html +++ /dev/null @@ -1,46 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: The db_dump and db_load utilities</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Dumping and Reloading</dl></h3></td> -<td align=right><a href="../../ref/sendmail/intro.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/dumpload/format.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>The db_dump and db_load utilities</h1> -<p>There are three utilities used for dumping and loading Berkeley DB -databases: <a href="../../utility/db_dump.html">db_dump</a>, <a href="../../utility/db_dump.html">db_dump185</a>, and <a href="../../utility/db_load.html">db_load</a>. -<p>The <a href="../../utility/db_dump.html">db_dump</a> and <a href="../../utility/db_dump.html">db_dump185</a> utilities dump Berkeley DB -databases into a flat-text representation of the data that can be read -by <a href="../../utility/db_load.html">db_load</a>. The only difference between them is that -<a href="../../utility/db_dump.html">db_dump</a> reads Berkeley DB version 2 and greater database formats, -whereas <a href="../../utility/db_dump.html">db_dump185</a> reads Berkeley DB version 1.85 and 1.86 database -formats. -<p>The <a href="../../utility/db_load.html">db_load</a> utility reads either the output format used -by the dump utilities or (optionally) a flat-text representation -created using other tools, and stores it into a Berkeley DB database. -<p>Dumping and reloading Hash databases that use user-defined hash functions -will result in new databases that use the default hash function. Although -using the default hash function may not be optimal for the new database, -it will continue to work correctly. -<p>Dumping and reloading Btree databases that use user-defined prefix or -comparison functions will result in new databases that use the default -prefix and comparison functions. In this case, it is quite likely that -applications will be unable to retrieve records, and it is possible that -the load process itself will fail. -<p>The only available workaround for either Hash or Btree databases is to -modify the sources for the <a href="../../utility/db_load.html">db_load</a> utility to load the database -using the correct hash, prefix, and comparison functions. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/sendmail/intro.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/dumpload/format.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/libdb/docs/ref/env/create.html b/libdb/docs/ref/env/create.html deleted file mode 100644 index 0f401f0b9..000000000 --- a/libdb/docs/ref/env/create.html +++ /dev/null @@ -1,130 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Creating a database environment</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Environment</dl></h3></td> -<td align=right><a href="../../ref/env/intro.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/env/open.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Creating a database environment</h1> -<p>The Berkeley DB environment is created and described by the <a href="../../api_c/env_create.html">db_env_create</a> -and <a href="../../api_c/env_open.html">DB_ENV->open</a> interfaces. In situations where customization is -desired, such as storing log files on a separate disk drive or selection -of a particular cache size, applications must describe the customization -by either creating an environment configuration file in the environment -home directory or by arguments passed to other <a href="../../api_c/env_class.html">DB_ENV</a> handle methods. -<p>Once an environment has been created, database files specified using -relative pathnames will be named relative to the home directory. Using -pathnames relative to the home directory allows the entire environment -to be easily moved, simplifying restoration and recovery of a database -in a different directory or on a different system. -<p>Applications first obtain an environment handle using the -<a href="../../api_c/env_create.html">db_env_create</a> method, then call the <a href="../../api_c/env_open.html">DB_ENV->open</a> method which creates -or joins the database environment. There are a number of options you -can set to customize <a href="../../api_c/env_open.html">DB_ENV->open</a> for your environment. These -options fall into four broad categories: -<p><dl compact> -<p><dt>Subsystem Initialization:<dd>These flags indicate which Berkeley DB subsystems will be initialized for the -environment, and what operations will happen automatically when -databases are accessed within the environment. The flags include -<a href="../../api_c/env_open.html#DB_JOINENV">DB_JOINENV</a>, <a href="../../api_c/env_open.html#DB_INIT_CDB">DB_INIT_CDB</a>, <a href="../../api_c/env_open.html#DB_INIT_LOCK">DB_INIT_LOCK</a>, -<a href="../../api_c/env_open.html#DB_INIT_LOG">DB_INIT_LOG</a>, <a href="../../api_c/env_open.html#DB_INIT_MPOOL">DB_INIT_MPOOL</a>, and <a href="../../api_c/env_open.html#DB_INIT_TXN">DB_INIT_TXN</a>. -The <a href="../../api_c/env_open.html#DB_INIT_CDB">DB_INIT_CDB</a> flag does initialization for Berkeley DB Concurrent Data Store -applications. (See <a href="../../ref/cam/intro.html">Building Berkeley DB Concurrent Data Store -applications</a> for more information.) The rest of the flags initialize -a single subsystem; that is, when <a href="../../api_c/env_open.html#DB_INIT_LOCK">DB_INIT_LOCK</a> is specified, -applications reading and writing databases opened in this environment -will be using locking to ensure that they do not overwrite each other's -changes. -<p><dt>Recovery options:<dd>These flags, which include <a href="../../api_c/env_open.html#DB_RECOVER">DB_RECOVER</a> and -<a href="../../api_c/env_open.html#DB_RECOVER_FATAL">DB_RECOVER_FATAL</a>, indicate what recovery is to be performed on -the environment before it is opened for normal use. -<p><dt>Naming options:<dd>These flags, which include <a href="../../api_c/env_open.html#DB_USE_ENVIRON">DB_USE_ENVIRON</a> and -<a href="../../api_c/env_open.html#DB_USE_ENVIRON_ROOT">DB_USE_ENVIRON_ROOT</a>, modify how file naming happens in the -environment. -<p><dt>Miscellaneous:<dd>Finally, there are a number of miscellaneous flags, for example, -<a href="../../api_c/env_open.html#DB_CREATE">DB_CREATE</a> which causes underlying files to be created as -necessary. See the <a href="../../api_c/env_open.html">DB_ENV->open</a> manual pages for further -information. -</dl> -<p>Most applications either specify only the <a href="../../api_c/env_open.html#DB_INIT_MPOOL">DB_INIT_MPOOL</a> flag or -they specify all four subsystem initialization flags -(<a href="../../api_c/env_open.html#DB_INIT_MPOOL">DB_INIT_MPOOL</a>, <a href="../../api_c/env_open.html#DB_INIT_LOCK">DB_INIT_LOCK</a>, <a href="../../api_c/env_open.html#DB_INIT_LOG">DB_INIT_LOG</a>, and -<a href="../../api_c/env_open.html#DB_INIT_TXN">DB_INIT_TXN</a>). The former configuration is for applications that -simply want to use the basic Access Method interfaces with a shared -underlying buffer pool, but don't care about recoverability after -application or system failure. The latter is for applications that need -recoverability. There are situations in which other combinations of -the initialization flags make sense, but they are rare. -<p>The <a href="../../api_c/env_open.html#DB_RECOVER">DB_RECOVER</a> flag is specified by applications that want to -perform any necessary database recovery when they start running. That -is, if there was a system or application failure the last time they ran, -they want the databases to be made consistent before they start running -again. It is not an error to specify this flag when no recovery needs -to be done. -<p>The <a href="../../api_c/env_open.html#DB_RECOVER_FATAL">DB_RECOVER_FATAL</a> flag is more special-purpose. It performs -catastrophic database recovery, and normally requires that some initial -arrangements be made; that is, archived log files be brought back into -the filesystem. Applications should not normally specify this flag. -Instead, under these rare conditions, the <a href="../../utility/db_recover.html">db_recover</a> utility -should be used. -<p>The following is a simple example of a function that opens a database -environment for a transactional program. -<p><blockquote><pre>DB_ENV * -db_setup(home, data_dir, errfp, progname) - char *home, *data_dir, *progname; - FILE *errfp; -{ - DB_ENV *dbenv; - int ret; -<p> - /* - * Create an environment and initialize it for additional error - * reporting. - */ - if ((ret = db_env_create(&dbenv, 0)) != 0) { - fprintf(errfp, "%s: %s\n", progname, db_strerror(ret)); - return (NULL); - } - dbenv->set_errfile(dbenv, errfp); - dbenv->set_errpfx(dbenv, progname); -<p> - /* - * Specify the shared memory buffer pool cachesize: 5MB. - * Databases are in a subdirectory of the environment home. - */ - if ((ret = dbenv->set_cachesize(dbenv, 0, 5 * 1024 * 1024, 0)) != 0) { - dbenv->err(dbenv, ret, "set_cachesize"); - goto err; - } - if ((ret = dbenv->set_data_dir(dbenv, data_dir)) != 0) { - dbenv->err(dbenv, ret, "set_data_dir: %s", data_dir); - goto err; - } -<p> - /* Open the environment with full transactional support. */ - if ((ret = dbenv->open(dbenv, home, DB_CREATE | - DB_INIT_LOG | DB_INIT_LOCK | DB_INIT_MPOOL | DB_INIT_TXN, 0)) != 0) { - dbenv->err(dbenv, ret, "environment open: %s", home); - goto err; - } -<p> - return (dbenv); -<p> -err: (void)dbenv->close(dbenv, 0); - return (NULL); -}</pre></blockquote> -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/env/intro.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/env/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/libdb/docs/ref/env/db_config.html b/libdb/docs/ref/env/db_config.html deleted file mode 100644 index 0b264500b..000000000 --- a/libdb/docs/ref/env/db_config.html +++ /dev/null @@ -1,51 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: DB_CONFIG configuration 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> -<a name="2"><!--meow--></a><a name="3"><!--meow--></a> -<table width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Environment</dl></h3></td> -<td align=right><a href="../../ref/env/error.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/env/naming.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>DB_CONFIG configuration file</h1> -<p>Most of the configuration information that can be specified to -<a href="../../api_c/env_class.html">DB_ENV</a> methods can also be specified using a configuration file. -If an environment home directory has been specified (either by the -application specifying a non-NULL <b>db_home</b> argument to -<a href="../../api_c/env_open.html">DB_ENV->open</a>, or by the application setting the -<a href="../../api_c/env_open.html#DB_USE_ENVIRON">DB_USE_ENVIRON</a> or <a href="../../api_c/env_open.html#DB_USE_ENVIRON_ROOT">DB_USE_ENVIRON_ROOT</a> flags and the -<a href="../../ref/env/naming.html#DB_HOME">DB_HOME</a> environment variable being set), any file named -DB_CONFIG in the database home directory will be read for lines -of the format <b>NAME VALUE</b>. -<p>One or more whitespace characters are used to delimit the two parts of -the line, and trailing whitespace characters are discarded. All empty -lines or lines whose first character is a whitespace or hash -(<b>#</b>) character will be ignored. Each line must specify both -the NAME and the VALUE of the pair. The specific NAME VALUE pairs are -documented in the manual for the corresponding methods (for example, -the <a href="../../api_c/env_set_data_dir.html">DB_ENV->set_data_dir</a> documentation includes NAME VALUE pair -information Berkeley DB administrators can use to configure locations for -database files). -<p>The DB_CONFIG configuration file is intended to allow database -environment administrators to customize environments independent of -applications using the environment. For example, a database -administrator can move the database log and data files to a different -location without application recompilation. In addition, because the -DB_CONFIG file is read when the database environment is opened, -it can be used to overrule application configuration done before that -time. For example a database administrator could override the -compiled-in application cache size to a size more appropriate for a -specific machine. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/env/error.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/env/naming.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/libdb/docs/ref/env/encrypt.html b/libdb/docs/ref/env/encrypt.html deleted file mode 100644 index 2c4c6c325..000000000 --- a/libdb/docs/ref/env/encrypt.html +++ /dev/null @@ -1,99 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Encryption</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Environment</dl></h3></td> -<td align=right><a href="../../ref/env/security.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/env/remote.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Encryption</h1> -<p>Berkeley DB releases optionally include strong cryptography support; this release -<b>DOES NOT</b> contain cryptography support. -<p><b>Note that export/import and/or use of cryptography -software, or even communicating technical details about cryptography -software, is illegal in some parts of the world. You are strongly -advised to pay close attention to any export/import and/or use laws -which apply to you when you import release of Berkeley DB including -cryptography to your country or re-distribute source code from it in -any way.</b> -<p>Berkeley DB supports encryption using the Rijndael/AES (also known as the -Advanced Encryption Standard and Federal Information Processing Standard -(FIPS) 197) algorithm for encryption or decryption. The algorithm is -configured to use a 128-bit key. Berkeley DB uses a 16-byte initialization -vector generated using the Mersenne Twister. All encrypted information -is additionally checksummed using the SHA1 Secure Hash Algorithm, using -a 160-bit message digest. -<p>The encryption support provided with Berkeley DB is intended to protect -applications from an attacker obtaining physical access to the media on -which a Berkeley DB database is stored, or an attacker compromising a system -on which Berkeley DB is running but who is unable to read system or process -memory on that system. -<b>The encryption support provided with Berkeley DB will not protect applications -from attackers able to read system memory on the system where Berkeley DB is -running.</b> -<p>Encryption is not the default for created databases, even in database -environments configured for encryption. In addition to configuring for -encryption by calling the <a href="../../api_c/env_set_encrypt.html">DB_ENV->set_encrypt</a> or -<a href="../../api_c/db_set_encrypt.html">DB->set_encrypt</a> methods, applications must specify the -<a href="../../api_c/db_set_flags.html#DB_ENCRYPT">DB_ENCRYPT</a> flag before creating the database in order for the -database to be encrypted. Further, databases cannot be converted to an -encrypted format after they have been created without dumping and -re-creating them. -<p>Each encrypted database environment (including all its encrypted -databases) is encrypted using a single password and a single algorithm. -Applications wanting to provide a finer granularity of database access -must either use multiple database environments or implement additional -access controls outside of Berkeley DB. -<p>The only encrypted parts of a database environment are its databases -and its log files. Specifically, the <a href="../../ref/env/region.html">Shared memory regions</a> supporting the database environment are not -encrypted. For this reason, it may be possible for an attacker to read -some or all of an encrypted database by reading the on-disk files that -back these shared memory regions. To prevent such attacks, applications -may want to use in-memory filesystem support (on systems that support -it), or the <a href="../../api_c/env_open.html#DB_PRIVATE">DB_PRIVATE</a> or <a href="../../api_c/env_open.html#DB_SYSTEM_MEM">DB_SYSTEM_MEM</a> flags to the -<a href="../../api_c/env_open.html">DB_ENV->open</a> method, to place the shared memory regions in memory that -is never written to a disk. As some systems page system memory to a -backing disk, it is important to consider the specific operating system -running on the machine as well. Finally, when backing database -environment shared regions with the filesystem, Berkeley DB can be configured -to overwrite the shared regions before removing them by specifying the -<a href="../../api_c/env_set_flags.html#DB_OVERWRITE">DB_OVERWRITE</a> flag. This option is only effective in the -presence of fixed-block filesystems, journaling or logging filesystems -will require operating system support and probably modification of the -Berkeley DB sources. -<p>While all user data is encrypted, parts of the databases and log files -in an encrypted environment are maintained in an unencrypted state. -Specifically, log record headers are not encrypted, only the actual log -records. Additionally, database internal page header fields are not -encrypted. These page header fields includes information such as the -page's <a href="../../api_c/lsn_class.html">DB_LSN</a>, number, and position in the database's sort -order. -<p>Log records distributed by replication master to replicated clients are -transmitted to the clients in unencrypted form. If encryption is -desired in a replicated application, the use of a secure transport -is strongly suggested. -<p>Sleepycat Software gratefully acknowledges: -<p><ul type=disc> -<li>Vincent Rijmen, Antoon Bosselaers and Paulo Barreto for writing the -Rijndael/AES code used in Berkeley DB. -<li>Steve Reid and James H. Brown for writing the SHA1 checksum code used -in Berkeley DB. -<li>Makoto Matsumoto and Takuji Nishimura for writing the Mersenne Twister -code used in Berkeley DB. -<li>Adam Stubblefield for integrating the Rijndael/AES, SHA1 checksum and -Mersenne Twister code into Berkeley DB. -</ul> -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/env/security.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/env/remote.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/libdb/docs/ref/env/error.html b/libdb/docs/ref/env/error.html deleted file mode 100644 index 23b9d9814..000000000 --- a/libdb/docs/ref/env/error.html +++ /dev/null @@ -1,59 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<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> -<table width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Environment</dl></h3></td> -<td align=right><a href="../../ref/env/open.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/env/db_config.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. -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. This is similar to -the ANSI C strerror interface, but can handle both system error returns -and Berkeley DB-specific return values. -<p>For example: -<p><blockquote><pre>int ret; -if ((ret = dbenv->set_cachesize(dbenv, 0, 32 * 1024, 1)) != 0) { - fprintf(stderr, "set_cachesize failed: %s\n", db_strerror(ret)); - return (1); -}</pre></blockquote> -<p>There are also two additional error interfaces: <a href="../../api_c/env_err.html">DB_ENV->err</a> and -<a href="../../api_c/env_err.html">DB_ENV->errx</a>. These functions work like the 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/env_err.html">DB_ENV->err</a> function appends the standard error string to the -constructed message; the <a href="../../api_c/env_err.html">DB_ENV->errx</a> function does not. -<p>Error messages can be configured always to include a prefix (for -example, the program name) using the <a href="../../api_c/env_set_errpfx.html">DB_ENV->set_errpfx</a> -interface. -<p>These functions provide simpler ways of displaying Berkeley DB error messages: -<p><blockquote><pre>int ret; -dbenv->set_errpfx(dbenv, program_name); -if ((ret = dbenv->open(dbenv, home, NULL, - DB_CREATE | DB_INIT_LOG | DB_INIT_TXN | DB_USE_ENVIRON)) - != 0) { - dbenv->err(dbenv, ret, "open: %s", home); - dbenv->errx(dbenv, - "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 it tried to open -an environment home directory in "/tmp/home" and the open call returned -a permission error, the error messages shown would look like this: -<p><blockquote><pre>my_app: open: /tmp/home: Permission denied. -my_app: contact your system administrator: session ID was 2</pre></blockquote> -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/env/open.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/env/db_config.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/libdb/docs/ref/env/faq.html b/libdb/docs/ref/env/faq.html deleted file mode 100644 index a17072b15..000000000 --- a/libdb/docs/ref/env/faq.html +++ /dev/null @@ -1,60 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Environment FAQ</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Environment</dl></h3></td> -<td align=right><a href="../../ref/env/remote.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/cam/intro.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Environment FAQ</h1> -<p><ol> -<p><li><b>I'm using multiple processes to access an Berkeley DB database -environment; is there any way to ensure that two processes don't run -recovery at the same time, or that all processes have exited the -database environment so that recovery can be run?</b> -<p>It's the responsibility of the processes (and/or threads of control) -using a Berkeley DB environment to ensure recovery is never performed if there -are other processes running recovery or using an existing database -environment. It would be great if Berkeley DB could solve this, but it -requires a way to single-thread execution on a system, and there's -rarely anything Berkeley DB can use for that purpose -- let alone a portable -method. -<p>Most application suites solve this problem by writing a tiny watch -program that recovers the database environment and then runs the -processes that actually use the database environment to perform work. -The watcher program then monitors the working processes, and if any of -them exit badly for any reason, the watcher kills any remaining -processes and restarts the cycle. -<p><li><b>How can I associate application information with a <a href="../../api_c/db_class.html">DB</a> -or <a href="../../api_c/env_class.html">DB_ENV</a> handle?</b> -<p>In the C API, the <a href="../../api_c/db_class.html">DB</a> and <a href="../../api_c/env_class.html">DB_ENV</a> structures each contain -an "app_private" field intended to be used to reference -application-specific information. See the <a href="../../api_c/db_create.html">db_create</a> and -<a href="../../api_c/env_create.html">db_env_create</a> documentation for more information. -<p>In the C++ or Java APIs, the easiest way to associate -application-specific data with a handle is to subclass the <a href="../../api_cxx/db_class.html">Db</a> -or <a href="../../api_cxx/env_class.html">DbEnv</a>, for example subclassing <a href="../../api_cxx/db_class.html">Db</a> to get MyDb. -Objects of type MyDb will still have the Berkeley DB API methods available on -them, and you can put any extra data or methods you want into the MyDb -class. If you are using "callback" APIs that take <a href="../../api_cxx/db_class.html">Db</a> or -<a href="../../api_cxx/env_class.html">DbEnv</a> arguments (for example, <a href="../../api_cxx/db_set_bt_compare.html">Db::set_bt_compare</a>) -these will always be called with the <a href="../../api_cxx/db_class.html">Db</a> or <a href="../../api_cxx/env_class.html">DbEnv</a> -objects you create. So if you always use MyDb objects, you will be able -to take the first argument to the callback function and cast it to a -MyDb (in C++, cast it to (MyDb*)). That will allow you to access your -data members or methods. -</ol> -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/env/remote.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/cam/intro.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/libdb/docs/ref/env/intro.html b/libdb/docs/ref/env/intro.html deleted file mode 100644 index a6e960abd..000000000 --- a/libdb/docs/ref/env/intro.html +++ /dev/null @@ -1,118 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Introduction</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Environment</dl></h3></td> -<td align=right><a href="../../ref/arch/utilities.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/env/create.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Introduction</h1> -<p>A Berkeley DB environment is an encapsulation of one or more databases, log -files and region files. Region files are the shared memory areas that -contain information about the database environment such as memory pool -cache pages. Only databases are byte-order independent and only -database files can be moved between machines of different byte orders. -Log files can be moved between machines of the same byte order. Region -files are usually unique to a specific machine and potentially to a -specific operating system release. -<p>The simplest way to administer a Berkeley DB application environment is to -create a single <b>home</b> directory that stores the files for the -applications that will share the environment. The environment home -directory must be created before any Berkeley DB applications are run. Berkeley DB -itself never creates the environment home directory. The environment can -then be identified by the name of that directory. -<p>An environment may be shared by any number of processes, as well as by -any number of threads within those processes. It is possible for an -environment to include resources from other directories on the system, -and applications often choose to distribute resources to other -directories or disks for performance or other reasons. However, by -default, the databases, shared regions (the locking, logging, memory -pool, and transaction shared memory areas) and log files will be stored -in a single directory hierarchy. -<p>It is important to realize that all applications sharing a database -environment implicitly trust each other. They have access to each -other's data as it resides in the shared regions, and they will share -resources such as buffer space and locks. At the same time, any -applications using the same databases <b>must</b> share an environment -if consistency is to be maintained between them. -<!--$Id$--> -<p><table border=1 align=center> -<tr><th>Database Environments and Related Methods</th><th>Description</th></tr> -<tr><td><a href="../../api_c/env_close.html">DB_ENV->close</a></td><td>Close an environment</td></tr> -<tr><td><a href="../../api_c/env_dbremove.html">DB_ENV->dbremove</a></td><td>Remove a database</td></tr> -<tr><td><a href="../../api_c/env_dbrename.html">DB_ENV->dbrename</a></td><td>Rename a database</td></tr> -<tr><td><a href="../../api_c/env_err.html">DB_ENV->err</a></td><td>Error message with error string</td></tr> -<tr><td><a href="../../api_c/env_err.html">DB_ENV->errx</a></td><td>Error message</td></tr> -<tr><td><a href="../../api_c/lock_detect.html">DB_ENV->lock_detect</a></td><td>Perform deadlock detection</td></tr> -<tr><td><a href="../../api_c/lock_get.html">DB_ENV->lock_get</a></td><td>Acquire a lock</td></tr> -<tr><td><a href="../../api_c/lock_id.html">DB_ENV->lock_id</a></td><td>Acquire a locker ID</td></tr> -<tr><td><a href="../../api_c/lock_id_free.html">DB_ENV->lock_id_free</a></td><td>Release a locker ID</td></tr> -<tr><td><a href="../../api_c/lock_put.html">DB_ENV->lock_put</a></td><td>Release a lock</td></tr> -<tr><td><a href="../../api_c/lock_stat.html">DB_ENV->lock_stat</a></td><td>Return lock subsystem statistics</td></tr> -<tr><td><a href="../../api_c/lock_vec.html">DB_ENV->lock_vec</a></td><td>Acquire/release locks</td></tr> -<tr><td><a href="../../api_c/log_archive.html">DB_ENV->log_archive</a></td><td>List log and database files</td></tr> -<tr><td><a href="../../api_c/log_file.html">DB_ENV->log_file</a></td><td>Map Log Sequence Numbers to log files</td></tr> -<tr><td><a href="../../api_c/log_flush.html">DB_ENV->log_flush</a></td><td>Flush log records</td></tr> -<tr><td><a href="../../api_c/log_put.html">DB_ENV->log_put</a></td><td>Write a log record</td></tr> -<tr><td><a href="../../api_c/log_stat.html">DB_ENV->log_stat</a></td><td>Return log subsystem statistics</td></tr> -<tr><td><a href="../../api_c/memp_register.html">DB_ENV->memp_register</a></td><td>Register input/output functions for a file in a memory pool</td></tr> -<tr><td><a href="../../api_c/memp_stat.html">DB_ENV->memp_stat</a></td><td>Return memory pool statistics</td></tr> -<tr><td><a href="../../api_c/memp_sync.html">DB_ENV->memp_sync</a></td><td>Flush pages from a memory pool</td></tr> -<tr><td><a href="../../api_c/memp_trickle.html">DB_ENV->memp_trickle</a></td><td>Trickle flush pages from a memory pool</td></tr> -<tr><td><a href="../../api_c/env_open.html">DB_ENV->open</a></td><td>Open an environment</td></tr> -<tr><td><a href="../../api_c/env_remove.html">DB_ENV->remove</a></td><td>Remove an environment</td></tr> -<tr><td><a href="../../api_c/rep_elect.html">DB_ENV->rep_elect</a></td><td>Hold a replication election</td></tr> -<tr><td><a href="../../api_c/rep_message.html">DB_ENV->rep_process_message</a></td><td>Process a replication message</td></tr> -<tr><td><a href="../../api_c/rep_start.html">DB_ENV->rep_start</a></td><td>Configure an environment for replication</td></tr> -<tr><td><a href="../../api_c/rep_stat.html">DB_ENV->rep_stat</a></td><td>Replication statistics</td></tr> -<tr><td><a href="../../api_c/env_set_alloc.html">DB_ENV->set_alloc</a></td><td>Set local space allocation functions</td></tr> -<tr><td><a href="../../api_c/env_set_app_dispatch.html">DB_ENV->set_app_dispatch</a></td><td>Configure application recovery interface</td></tr> -<tr><td><a href="../../api_c/env_set_cachesize.html">DB_ENV->set_cachesize</a></td><td>Set the environment cache size</td></tr> -<tr><td><a href="../../api_c/env_set_data_dir.html">DB_ENV->set_data_dir</a></td><td>Set the environment data directory</td></tr> -<tr><td><a href="../../api_c/env_set_encrypt.html">DB_ENV->set_encrypt</a></td><td>Set the environment cryptographic key</td></tr> -<tr><td><a href="../../api_c/env_set_errcall.html">DB_ENV->set_errcall</a></td><td>Set error message callback</td></tr> -<tr><td><a href="../../api_c/env_set_errfile.html">DB_ENV->set_errfile</a></td><td>Set error message FILE</td></tr> -<tr><td><a href="../../api_cxx/env_set_error_stream.html">DbEnv::set_error_stream</a></td><td>Set error message output stream</td></tr> -<tr><td><a href="../../api_c/env_set_errpfx.html">DB_ENV->set_errpfx</a></td><td>Set error message prefix</td></tr> -<tr><td><a href="../../api_c/env_set_feedback.html">DB_ENV->set_feedback</a></td><td>Set feedback callback</td></tr> -<tr><td><a href="../../api_c/env_set_flags.html">DB_ENV->set_flags</a></td><td>Environment configuration</td></tr> -<tr><td><a href="../../api_c/env_set_lg_bsize.html">DB_ENV->set_lg_bsize</a></td><td>Set log buffer size</td></tr> -<tr><td><a href="../../api_c/env_set_lg_dir.html">DB_ENV->set_lg_dir</a></td><td>Set the environment logging directory</td></tr> -<tr><td><a href="../../api_c/env_set_lg_max.html">DB_ENV->set_lg_max</a></td><td>Set log file size</td></tr> -<tr><td><a href="../../api_c/env_set_lg_regionmax.html">DB_ENV->set_lg_regionmax</a></td><td>Set logging region size</td></tr> -<tr><td><a href="../../api_c/env_set_lk_conflicts.html">DB_ENV->set_lk_conflicts</a></td><td>Set lock conflicts matrix</td></tr> -<tr><td><a href="../../api_c/env_set_lk_detect.html">DB_ENV->set_lk_detect</a></td><td>Set automatic deadlock detection</td></tr> -<tr><td><a href="../../api_c/env_set_lk_max_lockers.html">DB_ENV->set_lk_max_lockers</a></td><td>Set maximum number of lockers</td></tr> -<tr><td><a href="../../api_c/env_set_lk_max_locks.html">DB_ENV->set_lk_max_locks</a></td><td>Set maximum number of locks</td></tr> -<tr><td><a href="../../api_c/env_set_lk_max_objects.html">DB_ENV->set_lk_max_objects</a></td><td>Set maximum number of lock objects</td></tr> -<tr><td><a href="../../api_c/env_set_mp_mmapsize.html">DB_ENV->set_mp_mmapsize</a></td><td>Set maximum mapped-in database file size</td></tr> -<tr><td><a href="../../api_c/env_set_paniccall.html">DB_ENV->set_paniccall</a></td><td>Set panic callback</td></tr> -<tr><td><a href="../../api_c/rep_limit.html">DB_ENV->set_rep_limit</a></td><td>Limit data sent in response to a single message</td></tr> -<tr><td><a href="../../api_c/rep_transport.html">DB_ENV->set_rep_transport</a></td><td>Configure replication transport</td></tr> -<tr><td><a href="../../api_c/env_set_rpc_server.html">DB_ENV->set_rpc_server</a></td><td>Establish an RPC server connection</td></tr> -<tr><td><a href="../../api_c/env_set_shm_key.html">DB_ENV->set_shm_key</a></td><td>Set system memory shared segment ID</td></tr> -<tr><td><a href="../../api_c/env_set_tas_spins.html">DB_ENV->set_tas_spins</a></td><td>Set the number of test-and-set spins</td></tr> -<tr><td><a href="../../api_c/env_set_timeout.html">DB_ENV->set_timeout</a></td><td>Set lock and transaction timeout</td></tr> -<tr><td><a href="../../api_c/env_set_tmp_dir.html">DB_ENV->set_tmp_dir</a></td><td>Set the environment temporary file directory</td></tr> -<tr><td><a href="../../api_c/env_set_tx_max.html">DB_ENV->set_tx_max</a></td><td>Set maximum number of transactions</td></tr> -<tr><td><a href="../../api_c/env_set_tx_timestamp.html">DB_ENV->set_tx_timestamp</a></td><td>Set recovery timestamp</td></tr> -<tr><td><a href="../../api_c/env_set_verbose.html">DB_ENV->set_verbose</a></td><td>Set verbose messages</td></tr> -<tr><td><a href="../../api_c/txn_begin.html">DB_ENV->txn_begin</a></td><td>Begin a transaction</td></tr> -<tr><td><a href="../../api_c/txn_checkpoint.html">DB_ENV->txn_checkpoint</a></td><td>Checkpoint the transaction subsystem</td></tr> -<tr><td><a href="../../api_c/txn_recover.html">DB_ENV->txn_recover</a></td><td>Distributed transaction recovery</td></tr> -<tr><td><a href="../../api_c/txn_stat.html">DB_ENV->txn_stat</a></td><td>Return transaction subsystem statistics</td></tr> -</table> -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/arch/utilities.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/env/create.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/libdb/docs/ref/env/naming.html b/libdb/docs/ref/env/naming.html deleted file mode 100644 index 0086600ff..000000000 --- a/libdb/docs/ref/env/naming.html +++ /dev/null @@ -1,128 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: File naming</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Environment</dl></h3></td> -<td align=right><a href="../../ref/env/db_config.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/env/region.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>File naming</h1> -<p>One of the most important tasks of the database environment is to -structure file naming within Berkeley DB. Cooperating applications (or -multiple invocations of the same application) must agree on the location -of the database environment, log files and other files used by the Berkeley DB -subsystems, and, of course, the database files. Although it is possible -to specify full pathnames to all Berkeley DB functions, this is -cumbersome and requires that applications be recompiled when database -files are moved. -<p>Applications are normally expected to specify a single directory home -for the database environment. This can be done easily in the call to -<a href="../../api_c/env_open.html">DB_ENV->open</a> by specifying a value for the <b>db_home</b> -argument. There are more complex configurations in which it may be -desirable to override <b>db_home</b> or provide supplementary path -information. -<h3>Specifying file naming to Berkeley DB</h3> -<p>The following list describes the possible ways in which file naming -information may be specified to the Berkeley DB library. The specific -circumstances and order in which these ways are applied are described -in a subsequent paragraph. -<p><dl compact> -<p><dt><a name="db_home">db_home</a><dd>If the <b>db_home</b> argument to <a href="../../api_c/env_open.html">DB_ENV->open</a> is non-NULL, -its value may be used as the database home, and files named relative to -its path. -<p><dt><a name="DB_HOME">DB_HOME</a><dd>If the DB_HOME environment variable is set when <a href="../../api_c/env_open.html">DB_ENV->open</a> is -called, its value may be used as the database home, and files named -relative to its path. -<p>The DB_HOME environment variable is intended to permit users and system -administrators to override application and installation defaults. For -example:: -<p><blockquote><pre>env DB_HOME=/database/my_home application</pre></blockquote> -<p>Application writers are encouraged to support the <b>-h</b> option -found in the supporting Berkeley DB utilities to let users specify a database -home. -<p><dt><a href="../../api_c/env_class.html">DB_ENV</a> methods<dd>There are three <a href="../../api_c/env_class.html">DB_ENV</a> methods that affect file naming. The -<a href="../../api_c/env_set_data_dir.html">DB_ENV->set_data_dir</a> method specifies a directory to search for database -files. The <a href="../../api_c/env_set_lg_dir.html">DB_ENV->set_lg_dir</a> method specifies a directory in which to -create logging files. The <a href="../../api_c/env_set_tmp_dir.html">DB_ENV->set_tmp_dir</a> method specifies a -directory in which to create backing temporary files. These methods -are intended to permit applications to customize a file location for a -database. For example, an application writer can place data files and -log files in different directories or instantiate a new log directory -each time the application runs. -<p><dt><a href="../../ref/env/db_config.html#DB_CONFIG">DB_CONFIG</a><dd>The same information specified to the <a href="../../api_c/env_class.html">DB_ENV</a> methods may also be -specified using the <a href="../../ref/env/db_config.html#DB_CONFIG">DB_CONFIG</a> configuration file. -</dl> -<h3>Filename resolution in Berkeley DB</h3> -<p>The following list describes the specific circumstances and order in -which the different ways of specifying file naming information are -applied. Berkeley DB filename processing proceeds sequentially through the -following steps: -<p><dl compact> -<p><dt>absolute pathnames<dd>If the filename specified to a Berkeley DB function is an <i>absolute -pathname</i>, that filename is used without modification by Berkeley DB. -<p>On UNIX systems, an absolute pathname is defined as any pathname that -begins with a leading slash (<b>/</b>). -<p>On Windows systems, an absolute pathname is any pathname that begins with -a leading slash or leading backslash (<b>\</b>); or any -pathname beginning with a single alphabetic character, a colon and a -leading slash or backslash (for example, <b>C:/tmp</b>). -<p><dt><a href="../../api_c/env_class.html">DB_ENV</a> methods, DB_CONFIG<dd>If a relevant configuration string (for example, set_data_dir), is -specified either by calling a <a href="../../api_c/env_class.html">DB_ENV</a> method or as a line in the -DB_CONFIG configuration file, the value is prepended to the filename. -If the resulting filename is an absolute pathname, the filename is used -without further modification by Berkeley DB. -<p><dt>db_home<dd>If the application specified a non-NULL <b>db_home</b> argument to -<a href="../../api_c/env_open.html">DB_ENV->open</a>, its value is prepended to the filename. If the -resulting filename is an absolute pathname, the filename is used without -further modification by Berkeley DB. -<p><dt>DB_HOME<dd>If the <b>db_home</b> argument is NULL, the DB_HOME environment variable -was set, and the application has set the appropriate DB_USE_ENVIRON or -DB_USE_ENVIRON_ROOT environment variable, its value is prepended to the -filename. If the resulting filename is an absolute pathname, the file -name is used without further modification by Berkeley DB. -<p><dt>default<dd>Finally, all filenames are interpreted relative to the current working -directory of the process. -</dl> -<p>The common model for a Berkeley DB environment is one in which only the DB_HOME -environment variable, or the <b>db_home</b> argument is specified. In -this case, all data filenames are relative to that directory, and all -files created by the Berkeley DB subsystems will be created in that directory. -<p>The more complex model for a transaction environment might be one in -which a database home is specified, using either the DB_HOME environment -variable or the <b>db_home</b> argument to <a href="../../api_c/env_open.html">DB_ENV->open</a>; and then -the data directory and logging directory are set to the relative -pathnames of directories underneath the environment home. -<h3>Examples</h3> -<p>Store all files in the directory <b>/a/database</b>: -<p><blockquote><pre>dbenv->open(dbenv, "/a/database", flags, mode);</pre></blockquote> -<p>Create temporary backing files in <b>/b/temporary</b>, and all other files -in <b>/a/database</b>: -<p><blockquote><pre>dbenv->set_tmp_dir(dbenv, "/b/temporary"); -dbenv->open(dbenv, "/a/database", flags, mode);</pre></blockquote> -<p>Store data files in <b>/a/database/datadir</b>, log files in -<b>/a/database/logdir</b>, and all other files in the directory -<b>/a/database</b>: -<p><blockquote><pre>dbenv->set_lg_dir(dbenv, "logdir"); -dbenv->set_data_dir(dbenv, "datadir"); -dbenv->open(dbenv, "/a/database", flags, mode);</pre></blockquote> -<p>Store data files in <b>/a/database/data1</b> and <b>/b/data2</b>, and -all other files in the directory <b>/a/database</b>. Any data files -that are created will be created in <b>/b/data2</b>, because it is -the first data file directory specified: -<p><blockquote><pre>dbenv->set_data_dir(dbenv, "/b/data2"); -dbenv->set_data_dir(dbenv, "data1"); -dbenv->open(dbenv, "/a/database", flags, mode);</pre></blockquote> -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/env/db_config.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/env/region.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/libdb/docs/ref/env/open.html b/libdb/docs/ref/env/open.html deleted file mode 100644 index 4e3fd43f4..000000000 --- a/libdb/docs/ref/env/open.html +++ /dev/null @@ -1,66 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Opening databases within the environment</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Environment</dl></h3></td> -<td align=right><a href="../../ref/env/create.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/env/error.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Opening databases within the environment</h1> -<p>Once the environment has been created, database handles may be created -and then opened within the environment. This is done by calling the -<a href="../../api_c/db_create.html">db_create</a> interface and specifying the appropriate environment -as an argument. -<p>File naming, database operations, and error handling will all be done as -specified for the environment. For example, if the <a href="../../api_c/env_open.html#DB_INIT_LOCK">DB_INIT_LOCK</a> -or <a href="../../api_c/env_open.html#DB_INIT_CDB">DB_INIT_CDB</a> flags were specified when the environment was -created or joined, database operations will automatically perform all -necessary locking operations for the application. -<p>The following is a simple example of opening two databases within a -database environment: -<p><blockquote><pre> DB_ENV *dbenv; - DB *dbp1, *dbp2; - int ret; -</pre></blockquote> -<p><blockquote><pre> /* Open an environment with just a memory pool. */ - if ((ret = - dbenv->open(dbenv, home, DB_CREATE | DB_INIT_MPOOL, 0)) != 0) { - dbenv->err(dbenv, ret, "environment open: %s", home); - return (ret); - } -<p> - /* Open database #1. */ - if ((ret = db_create(&dbp1, dbenv, 0)) != 0) { - dbenv->err(dbenv, ret, "database create"); - return (ret); - } - if ((ret = dbp1->open(dbp1, - NULL, DATABASE1, NULL, DB_BTREE, DB_CREATE, 0664)) != 0) { - dbenv->err(dbenv, ret, "DB->open: %s", DATABASE1); - return (ret); - } -<p> - /* Open database #2. */ - if ((ret = db_create(&dbp2, dbenv, 0)) != 0) { - dbenv->err(dbenv, ret, "database create"); - return (ret); - } - if ((ret = dbp2->open(dbp2, - NULL, DATABASE2, NULL, DB_HASH, DB_CREATE, 0664)) != 0) { - dbenv->err(dbenv, ret, "DB->open: %s", DATABASE2); - return (ret); - } -</pre></blockquote> -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/env/create.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/env/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> diff --git a/libdb/docs/ref/env/region.html b/libdb/docs/ref/env/region.html deleted file mode 100644 index 9cda3fc71..000000000 --- a/libdb/docs/ref/env/region.html +++ /dev/null @@ -1,73 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Shared memory regions</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Environment</dl></h3></td> -<td align=right><a href="../../ref/env/naming.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/env/security.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Shared memory regions</h1> -<p>Each of the Berkeley DB subsystems within an environment is described by one or -more regions. The regions contain all of the per-process and per-thread -shared information, including mutexes, that comprise a Berkeley DB environment. -These regions are created in one of three areas, depending on the flags -specified to the <a href="../../api_c/env_open.html">DB_ENV->open</a> function: -<p><ol> -<p><li>If the <a href="../../api_c/env_open.html#DB_PRIVATE">DB_PRIVATE</a> flag is specified to <a href="../../api_c/env_open.html">DB_ENV->open</a>, -regions are created in per-process heap memory; that is, memory returned -by <b>malloc</b>(3). In this case, the Berkeley DB environment may only -be accessed by a single process, although that process may be -multithreaded. -<p><li>If the <a href="../../api_c/env_open.html#DB_SYSTEM_MEM">DB_SYSTEM_MEM</a> flag is specified to <a href="../../api_c/env_open.html">DB_ENV->open</a>, -regions are created in system memory. When regions are created in system -memory, the Berkeley DB environment may be accessed by both multiple processes -and multiple threads within processes. -<p>The system memory used by Berkeley DB is potentially useful past the lifetime -of any particular process. Therefore, additional cleanup may be -necessary after an application fails because there may be no way for -Berkeley DB to ensure that system resources backing the shared memory regions -are returned to the system. -<p>The system memory that is used is architecture-dependent. For example, -on systems supporting X/Open-style shared memory interfaces, such as -UNIX systems, the <b>shmget</b>(2) and related System V IPC -interfaces are used. Additionally, VxWorks systems use system memory. -In these cases, an initial segment ID must be specified by the -application to ensure that applications do not overwrite each other's -database environments, so that the number of segments created does not -grow without bounds. See the <a href="../../api_c/env_set_shm_key.html">DB_ENV->set_shm_key</a> method for more -information. -<p>On Windows platforms, the use of the <a href="../../api_c/env_open.html#DB_SYSTEM_MEM">DB_SYSTEM_MEM</a> flag is -problematic because the operating system uses reference counting to -clean up shared objects in the paging file automatically. See -<a href="../../ref/build_win/notes.html">Windows Notes</a> for more -information. -<p><li>If no memory-related flags are specified to <a href="../../api_c/env_open.html">DB_ENV->open</a>, memory -backed by the filesystem is used to store the regions. On UNIX systems, -the Berkeley DB library will use the POSIX mmap interface. If mmap is not -available, the UNIX shmget interfaces will be used, assuming they are -available. -</ol> -<a name="2"><!--meow--></a> -<p>Any files created in the filesystem to back the regions are created in -the environment home directory specified to the <a href="../../api_c/env_open.html">DB_ENV->open</a> call. -These files are named __db.### (for example, __db.001, __db.002 and -so on). When region files are backed by the filesystem, one file per -region is created. When region files are backed by system memory, a -single file will still be created because there must be a well-known -name in the filesystem so that multiple processes can locate the system -shared memory that is being used by the environment. -<p>Statistics about the shared memory regions in the environment can be -displayed using the <b>-e</b> option to the <a href="../../utility/db_stat.html">db_stat</a> utility. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/env/naming.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/env/security.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/libdb/docs/ref/env/remote.html b/libdb/docs/ref/env/remote.html deleted file mode 100644 index 0390fdc8c..000000000 --- a/libdb/docs/ref/env/remote.html +++ /dev/null @@ -1,50 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Remote filesystems</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Environment</dl></h3></td> -<td align=right><a href="../../ref/env/encrypt.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/env/faq.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Remote filesystems</h1> -<p>When regions are backed by the filesystem, it is a common error to attempt -to create Berkeley DB environments backed by remote filesystems such as the -Network File System (NFS) or the Andrew File System (AFS). Remote -filesystems rarely support mapping files into process memory, and even -more rarely support correct semantics for mutexes after the attempt -succeeds. For this reason, we strongly recommend that the database -environment directory reside in a local filesystem. -<p>For remote filesystems that do allow system files to be mapped into -process memory, home directories accessed via remote filesystems cannot -be used simultaneously from multiple clients. None of the commercial -remote filesystems available today implement coherent, distributed -shared memory for remote-mounted files. As a result, different machines -will see different versions of these shared regions, and the system -behavior is undefined. -<p>Databases, log files, and temporary files may be placed on remote -filesystems, <b>as long as the remote filesystem fully supports -standard POSIX filesystem semantics</b> (although the application may -incur a performance penalty for doing so). Obviously, NFS-mounted -databases cannot be accessed from more than one Berkeley DB environment at a -time (and therefore from more than one system), because no Berkeley DB -database may be accessed from more than one Berkeley DB environment at a -time. -<p><dl compact> -<p><dt>Linux note:<dd>Some Linux releases are known to not support complete semantics for the -POSIX fsync call on NFS-mounted filesystems. No Berkeley DB files should be -placed on NFS-mounted filesystems on these systems. -</dl> -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/env/encrypt.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/env/faq.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/libdb/docs/ref/env/security.html b/libdb/docs/ref/env/security.html deleted file mode 100644 index 26632e2cf..000000000 --- a/libdb/docs/ref/env/security.html +++ /dev/null @@ -1,56 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Security</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Environment</dl></h3></td> -<td align=right><a href="../../ref/env/region.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/env/encrypt.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Security</h1> -<p>The following are security issues that should be considered when writing -Berkeley DB applications: -<p><dl compact> -<p><dt>Database environment permissions<dd>The directory used as the Berkeley DB database environment should have its -permissions set to ensure that files in the environment are not accessible -to users without appropriate permissions. Applications that add to the -user's permissions (for example, UNIX setuid or setgid applications), -must be carefully checked to not permit illegal use of those permissions -such as general file access in the environment directory. -<p><dt>Environment variables<dd>Setting the <a href="../../api_c/env_open.html#DB_USE_ENVIRON">DB_USE_ENVIRON</a> and <a href="../../api_c/env_open.html#DB_USE_ENVIRON_ROOT">DB_USE_ENVIRON_ROOT</a> flags -and allowing the use of environment variables during file naming can be -dangerous. Setting those flags in Berkeley DB applications with additional -permissions (for example, UNIX setuid or setgid applications) could -potentially allow users to read and write databases to which they would -not normally have access. -<p><dt>File permissions<dd>By default, Berkeley DB always creates files readable and writable by the owner -and the group (that is, S_IRUSR, S_IWUSR, S_IRGRP and S_IWGRP; or octal mode -0660 on historic UNIX systems). The group ownership of created files is -based on the system and directory defaults, and is not further specified -by Berkeley DB. -<p><dt>Temporary backing files<dd>If an unnamed database is created and the cache is too small to hold -the database in memory, Berkeley DB will create a temporary physical file to -enable it to page the database to disk as needed. In this case, -environment variables such as <b>TMPDIR</b> may be used to specify -the location of that temporary file. Although temporary backing files -are created readable and writable by the owner only (S_IRUSR and -S_IWUSR, or octal mode 0600 on historic UNIX systems), some filesystems -may not sufficiently protect temporary files created in random -directories from improper access. To be absolutely safe, applications -storing sensitive data in unnamed databases should use the -<a href="../../api_c/env_set_tmp_dir.html">DB_ENV->set_tmp_dir</a> method to specify a temporary directory with -known permissions. -</dl> -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/env/region.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/env/encrypt.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/libdb/docs/ref/install/file.html b/libdb/docs/ref/install/file.html deleted file mode 100644 index 8149de39a..000000000 --- a/libdb/docs/ref/install/file.html +++ /dev/null @@ -1,38 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: File utility /etc/magic information</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>System Installation Notes</dl></h3></td> -<td align=right><a href="../../ref/dumpload/text.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/install/multiple.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>File utility /etc/magic information</h1> -<p>The <b>file</b>(1) utility is a UNIX utility that examines and -classifies files, based on information found in its database of file -types, the /etc/magic file. The following information may be added -to your system's /etc/magic file to enable <b>file</b>(1) to -correctly identify Berkeley DB database files. -<p>The <b>file</b>(1) utility <b>magic</b>(5) information for the -standard System V UNIX implementation of the <b>file</b>(1) utility -is included in the Berkeley DB distribution for both -<a href="magic.s5.be.txt">big-endian</a> (for example, Sparc) and -<a href="magic.s5.le.txt">little-endian</a> (for example, x86) architectures. -<p>The <b>file</b>(1) utility <b>magic</b>(5) information for -Release 3.X of Ian Darwin's implementation of the file utility (as -distributed by FreeBSD and most Linux distributions) is included in the -Berkeley DB distribution. This <a href="magic.txt">magic.txt</a> information -is correct for both big-endian and little-endian architectures. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/dumpload/text.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/install/multiple.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/libdb/docs/ref/install/magic.s5.be.txt b/libdb/docs/ref/install/magic.s5.be.txt deleted file mode 100644 index 2802ca9f7..000000000 --- a/libdb/docs/ref/install/magic.s5.be.txt +++ /dev/null @@ -1,87 +0,0 @@ -# Berkeley DB -# $Id$ -# -# System V /etc/magic files: big-endian version. -# -# Hash 1.85/1.86 databases store metadata in network byte order. -# Btree 1.85/1.86 databases store the metadata in host byte order. -# Hash and Btree 2.X and later databases store the metadata in host byte order. - -0 long 0x00053162 Berkeley DB 1.85/1.86 (Btree, ->4 long 0x00000002 version 2, ->4 long 0x00000003 version 3, ->0 long 0x00053162 native byte-order) - -0 long 0x62310500 Berkeley DB 1.85/1.86 (Btree, ->4 long 0x02000000 version 2, ->4 long 0x03000000 version 3, ->0 long 0x62310500 little-endian) - -12 long 0x00053162 Berkeley DB (Btree, ->16 long 0x00000004 version 4, ->16 long 0x00000005 version 5, ->16 long 0x00000006 version 6, ->16 long 0x00000007 version 7, ->16 long 0x00000008 version 8, ->16 long 0x00000009 version 9, ->12 long 0x00053162 native byte-order) - -12 long 0x62310500 Berkeley DB (Btree, ->16 long 0x04000000 version 4, ->16 long 0x05000000 version 5, ->16 long 0x06000000 version 6, ->16 long 0x07000000 version 7, ->16 long 0x08000000 version 8, ->16 long 0x09000000 version 9, ->12 long 0x62310500 little-endian) - -0 long 0x00061561 Berkeley DB ->4 long >2 1.86 ->4 long <3 1.85 ->0 long 0x00061561 (Hash, ->4 long 2 version 2, ->4 long 3 version 3, ->8 long 0x000004D2 little-endian) ->8 long 0x000010E1 native byte-order) - -12 long 0x00061561 Berkeley DB (Hash, ->16 long 0x00000004 version 4, ->16 long 0x00000005 version 5, ->16 long 0x00000006 version 6, ->16 long 0x00000007 version 7, ->16 long 0x00000008 version 8, ->16 long 0x00000009 version 9, ->12 long 0x00061561 native byte-order) - -12 long 0x61150600 Berkeley DB (Hash, ->16 long 0x04000000 version 4, ->16 long 0x05000000 version 5, ->16 long 0x06000000 version 6, ->16 long 0x07000000 version 7, ->16 long 0x08000000 version 8, ->16 long 0x09000000 version 9, ->12 long 0x61150600 little-endian) - -12 long 0x00042253 Berkeley DB (Queue, ->16 long 0x00000001 version 1, ->16 long 0x00000002 version 2, ->16 long 0x00000003 version 3, ->16 long 0x00000004 version 4, ->16 long 0x00000005 version 5, ->16 long 0x00000006 version 6, ->16 long 0x00000007 version 7, ->16 long 0x00000008 version 8, ->16 long 0x00000009 version 9, ->12 long 0x00042253 native byte-order) - -12 long 0x53220400 Berkeley DB (Queue, ->16 long 0x01000000 version 1, ->16 long 0x02000000 version 2, ->16 long 0x03000000 version 3, ->16 long 0x04000000 version 4, ->16 long 0x05000000 version 5, ->16 long 0x06000000 version 6, ->16 long 0x07000000 version 7, ->16 long 0x08000000 version 8, ->16 long 0x09000000 version 9, ->12 long 0x53220400 little-endian) diff --git a/libdb/docs/ref/install/magic.s5.le.txt b/libdb/docs/ref/install/magic.s5.le.txt deleted file mode 100644 index 02161423a..000000000 --- a/libdb/docs/ref/install/magic.s5.le.txt +++ /dev/null @@ -1,87 +0,0 @@ -# Berkeley DB -# $Id$ -# -# System V /etc/magic files: little-endian version. -# -# Hash 1.85/1.86 databases store metadata in network byte order. -# Btree 1.85/1.86 databases store the metadata in host byte order. -# Hash and Btree 2.X and later databases store the metadata in host byte order. - -0 long 0x00053162 Berkeley DB 1.85/1.86 (Btree, ->4 long 0x00000002 version 2, ->4 long 0x00000003 version 3, ->0 long 0x00053162 native byte-order) - -0 long 0x62310500 Berkeley DB 1.85/1.86 (Btree, ->4 long 0x02000000 version 2, ->4 long 0x03000000 version 3, ->0 long 0x62310500 big-endian) - -12 long 0x00053162 Berkeley DB (Btree, ->16 long 0x00000004 version 4, ->16 long 0x00000005 version 5, ->16 long 0x00000006 version 6, ->16 long 0x00000007 version 7, ->16 long 0x00000008 version 8, ->16 long 0x00000009 version 9, ->12 long 0x00053162 native byte-order) - -12 long 0x62310500 Berkeley DB (Btree, ->16 long 0x04000000 version 4, ->16 long 0x05000000 version 5, ->16 long 0x06000000 version 6, ->16 long 0x07000000 version 7, ->16 long 0x08000000 version 8, ->16 long 0x09000000 version 9, ->12 long 0x62310500 big-endian) - -0 long 0x61150600 Berkeley DB ->4 long >0x02000000 1.86 ->4 long <0x03000000 1.85 ->0 long 0x00061561 (Hash, ->4 long 0x02000000 version 2, ->4 long 0x03000000 version 3, ->8 long 0xD2040000 native byte-order) ->8 long 0xE1100000 big-endian) - -12 long 0x00061561 Berkeley DB (Hash, ->16 long 0x00000004 version 4, ->16 long 0x00000005 version 5, ->16 long 0x00000006 version 6, ->16 long 0x00000007 version 7, ->16 long 0x00000008 version 8, ->16 long 0x00000009 version 9, ->12 long 0x00061561 native byte-order) - -12 long 0x61150600 Berkeley DB (Hash, ->16 long 0x04000000 version 4, ->16 long 0x05000000 version 5, ->16 long 0x06000000 version 6, ->16 long 0x07000000 version 7, ->16 long 0x08000000 version 8, ->16 long 0x09000000 version 9, ->12 long 0x61150600 big-endian) - -12 long 0x00042253 Berkeley DB (Queue, ->16 long 0x00000001 version 1, ->16 long 0x00000002 version 2, ->16 long 0x00000003 version 3, ->16 long 0x00000004 version 4, ->16 long 0x00000005 version 5, ->16 long 0x00000006 version 6, ->16 long 0x00000007 version 7, ->16 long 0x00000008 version 8, ->16 long 0x00000009 version 9, ->12 long 0x00042253 native byte-order) - -12 long 0x53220400 Berkeley DB (Queue, ->16 long 0x01000000 version 1, ->16 long 0x02000000 version 2, ->16 long 0x03000000 version 3, ->16 long 0x04000000 version 4, ->16 long 0x05000000 version 5, ->16 long 0x06000000 version 6, ->16 long 0x07000000 version 7, ->16 long 0x08000000 version 8, ->16 long 0x09000000 version 9, ->12 long 0x53220400 big-endian) diff --git a/libdb/docs/ref/install/magic.txt b/libdb/docs/ref/install/magic.txt deleted file mode 100644 index 07c1a7e98..000000000 --- a/libdb/docs/ref/install/magic.txt +++ /dev/null @@ -1,56 +0,0 @@ -# Berkeley DB -# $Id$ -# -# Ian Darwin's file /etc/magic files: big/little-endian version. -# -# Hash 1.85/1.86 databases store metadata in network byte order. -# Btree 1.85/1.86 databases store the metadata in host byte order. -# Hash and Btree 2.X and later databases store the metadata in host byte order. - -0 long 0x00061561 Berkeley DB ->8 belong 4321 ->>4 belong >2 1.86 ->>4 belong <3 1.85 ->>4 belong >0 (Hash, version %d, native byte-order) ->8 belong 1234 ->>4 belong >2 1.86 ->>4 belong <3 1.85 ->>4 belong >0 (Hash, version %d, little-endian) - -0 belong 0x00061561 Berkeley DB ->8 belong 4321 ->>4 belong >2 1.86 ->>4 belong <3 1.85 ->>4 belong >0 (Hash, version %d, big-endian) ->8 belong 1234 ->>4 belong >2 1.86 ->>4 belong <3 1.85 ->>4 belong >0 (Hash, version %d, native byte-order) - -0 long 0x00053162 Berkeley DB 1.85/1.86 ->4 long >0 (Btree, version %d, native byte-order) -0 belong 0x00053162 Berkeley DB 1.85/1.86 ->4 belong >0 (Btree, version %d, big-endian) -0 lelong 0x00053162 Berkeley DB 1.85/1.86 ->4 lelong >0 (Btree, version %d, little-endian) - -12 long 0x00061561 Berkeley DB ->16 long >0 (Hash, version %d, native byte-order) -12 belong 0x00061561 Berkeley DB ->16 belong >0 (Hash, version %d, big-endian) -12 lelong 0x00061561 Berkeley DB ->16 lelong >0 (Hash, version %d, little-endian) - -12 long 0x00053162 Berkeley DB ->16 long >0 (Btree, version %d, native byte-order) -12 belong 0x00053162 Berkeley DB ->16 belong >0 (Btree, version %d, big-endian) -12 lelong 0x00053162 Berkeley DB ->16 lelong >0 (Btree, version %d, little-endian) - -12 long 0x00042253 Berkeley DB ->16 long >0 (Queue, version %d, native byte-order) -12 belong 0x00042253 Berkeley DB ->16 belong >0 (Queue, version %d, big-endian) -12 lelong 0x00042253 Berkeley DB ->16 lelong >0 (Queue, version %d, little-endian) diff --git a/libdb/docs/ref/install/multiple.html b/libdb/docs/ref/install/multiple.html deleted file mode 100644 index 5b74c3141..000000000 --- a/libdb/docs/ref/install/multiple.html +++ /dev/null @@ -1,55 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Building with multiple versions of Berkeley DB</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>System Installation Notes</dl></h3></td> -<td align=right><a href="../../ref/install/file.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/install/rpm.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Building with multiple versions of Berkeley DB</h1> -<p>In some cases it may be necessary to build applications which include -multiple versions of Berkeley DB. Examples include applications which include -software from other vendors, or applications running on a system where -the system C library itself uses Berkeley DB. In such cases, the two versions -of Berkeley DB may be incompatible, that is, they may have different external -and internal interfaces, and may even have different underlying database -formats. -<p>To create a Berkeley DB library whose symbols won't collide with other Berkeley DB -libraries (or other application or library modules, for that matter), -configure Berkeley DB using the <a href="../../ref/build_unix/conf.html#--with-uniquename=NAME">--with-uniquename=NAME</a> configuration option, -and then build Berkeley DB as usual. (Note that -<a href="../../ref/build_unix/conf.html#--with-uniquename=NAME">--with-uniquename</a> only affects the Berkeley DB C language library build; -loading multiple versions of the C++ or Java APIs will require -additional work.) The modified symbol names are hidden from the -application in the Berkeley DB header files, that is, there is no need for -the application to be aware that it is using a special library build as -long as it includes the appropriate Berkeley DB header file. -<p>If "NAME" is not specified when configuring with -<a href="../../ref/build_unix/conf.html#--with-uniquename=NAME">--with-uniquename</a>, a default value built from the major and minor -numbers of the Berkeley DB release will be used. It is rarely necessary to -specify NAME; using the major and minor release numbers will ensure that -only one copy of the library will be loaded into the application unless -two distinct versions really are necessary. -<p>When distributing any library software that uses Berkeley DB, or any software -which will be recompiled by users for their systems, we recommend two -things: First, include the Berkeley DB release as part of your release. This -will insulate your software from potential Berkeley DB API changes as well as -simplifying your coding because you will only have to code to a single -version of the Berkeley DB API instead of adapting at compile time to whatever -version of Berkeley DB happens to be installed on the target system. Second, -use <a href="../../ref/build_unix/conf.html#--with-uniquename=NAME">--with-uniquename</a> when configuring Berkeley DB, because that will insure that -you do not unexpectedly collide with other application code or a library -already installed on the target system. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/install/file.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/install/rpm.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/libdb/docs/ref/install/rpm.html b/libdb/docs/ref/install/rpm.html deleted file mode 100644 index d359e29ba..000000000 --- a/libdb/docs/ref/install/rpm.html +++ /dev/null @@ -1,29 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Building RPM distribution packages</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>System Installation Notes</dl></h3></td> -<td align=right><a href="../../ref/install/multiple.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/debug/intro.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Building RPM distribution packages</h1> -<p>If you would like to distribute your configuration and build of Berkeley DB -as an RPM software package, first configure Berkeley DB using the -<a href="../../ref/build_unix/conf.html#--with-rpm">--with-rpm</a> -configuration option, and then build Berkeley DB as follows: -<p><blockquote><pre>../dist/configure --with-rpm=DIR -make</pre></blockquote> -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/install/multiple.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/debug/intro.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/libdb/docs/ref/intro/data.html b/libdb/docs/ref/intro/data.html deleted file mode 100644 index 13dc52d80..000000000 --- a/libdb/docs/ref/intro/data.html +++ /dev/null @@ -1,55 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: An introduction to data management</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Introduction</dl></h3></td> -<td align=right><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/intro/terrain.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>An introduction to data management</h1> -<p>Cheap, powerful computing and networking have created countless new -applications that could not have existed a decade ago. The advent of -the World-Wide Web, and its influence in driving the Internet into homes -and businesses, is one obvious example. Equally important, though, is -the from large, general-purpose desktop and server computers -toward smaller, special-purpose devices with built-in processing and -communications services. -<p>As computer hardware has spread into virtually every corner of our -lives, of course, software has followed. Software developers today are -building applications not just for conventional desktop and server -environments, but also for handheld computers, home appliances, -networking hardware, cars and trucks, factory floor automation systems, -and more. -<p>While these operating environments are diverse, the problems that -software engineers must solve in them are often strikingly similar. Most -systems must deal with the outside world, whether that means -communicating with users or controlling machinery. As a result, most -need some sort of I/O system. Even a simple, single-function system -generally needs to handle multiple tasks, and so needs some kind of -operating system to schedule and manage control threads. Also, many -computer systems must store and retrieve data to track history, record -configuration settings, or manage access. -<p>Data management can be very simple. In some cases, just recording -configuration in a flat text file is enough. More often, though, -programs need to store and search a large amount of data, or -structurally complex data. Database management systems are tools that -programmers can use to do this work quickly and efficiently using -off-the-shelf software. -<p>Of course, database management systems have been around for a long time. -Data storage is a problem dating back to the earliest days of computing. -Software developers can choose from hundreds of good, -commercially-available database systems. The problem is selecting the -one that best solves the problems that their applications face. -<table width="100%"><tr><td><br></td><td align=right><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/intro/terrain.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/libdb/docs/ref/intro/dbis.html b/libdb/docs/ref/intro/dbis.html deleted file mode 100644 index 07cea7fdf..000000000 --- a/libdb/docs/ref/intro/dbis.html +++ /dev/null @@ -1,160 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: What is Berkeley DB?</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Introduction</dl></h3></td> -<td align=right><a href="../../ref/intro/terrain.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/intro/dbisnot.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>What is Berkeley DB?</h1> -<p>So far, we've discussed database systems in general terms. It's time -now to consider Berkeley DB in particular and see how it fits into the -framework we have introduced. The key question is, what kinds of -applications should use Berkeley DB? -<p>Berkeley DB is an open source embedded database library that provides -scalable, high-performance, transaction-protected data management -services to applications. Berkeley DB provides a simple function-call API -for data access and management. -<p>By "open source," we mean that Berkeley DB is distributed under a license that -conforms to the <a href="http://www.opensource.org/osd.html">Open -Source Definition</a>. This license guarantees that Berkeley DB is freely -available for use and redistribution in other open source products. -<a href="http://www.sleepycat.com">Sleepycat Software</a> sells -commercial licenses for redistribution in proprietary applications, but -in all cases the complete source code for Berkeley DB is freely available for -download and use. -<p>Berkeley DB is embedded because it links directly into the application. It -runs in the same address space as the application. As a result, no -inter-process communication, either over the network or between -processes on the same machine, is required for database operations. -Berkeley DB provides a simple function-call API for a number of programming -languages, including C, C++, Java, Perl, Tcl, Python, and PHP. All -database operations happen inside the library. Multiple processes, or -multiple threads in a single process, can all use the database at the -same time as each uses the Berkeley DB library. Low-level services like -locking, transaction logging, shared buffer management, memory -management, and so on are all handled transparently by the library. -<p>The library is extremely portable. It runs under almost all UNIX and -Linux variants, Windows, and a number of embedded real-time operating -systems. It runs on both 32-bit and 64-bit systems. -It has been deployed on high-end -Internet servers, desktop machines, and on palmtop computers, set-top -boxes, in network switches, and elsewhere. Once Berkeley DB is linked into -the application, the end user generally does not know that there's a -database present at all. -<p>Berkeley DB is scalable in a number of respects. The database library itself -is quite compact (under 300 kilobytes of text space on common -architectures), but it can manage databases up to 256 terabytes in size. -It also supports high concurrency, with thousands of users operating on -the same database at the same time. Berkeley DB is small enough to run in -tightly constrained embedded systems, but can take advantage of -gigabytes of memory and terabytes of disk on high-end server machines. -<p>Berkeley DB generally outperforms relational and object-oriented database -systems in embedded applications for a couple of reasons. First, because -the library runs in the same address space, no inter-process -communication is required for database operations. The cost of -communicating between processes on a single machine, or among machines -on a network, is much higher than the cost of making a function call. -Second, because Berkeley DB uses a simple function-call interface for all -operations, there is no query language to parse, and no execution plan -to produce. -<h3>Data Access Services</h3> -<p>Berkeley DB applications can choose the storage structure that best suits the -application. Berkeley DB supports hash tables, Btrees, simple -record-number-based storage, and persistent queues. Programmers can -create tables using any of these storage structures, and can mix -operations on different kinds of tables in a single application. -<p>Hash tables are generally good for very large databases that need -predictable search and update times for random-access records. Hash -tables allow users to ask, "Does this key exist?" or to fetch a record -with a known key. Hash tables do not allow users to ask for records -with keys that are close to a known key. -<p>Btrees are better for range-based searches, as when the application -needs to find all records with keys between some starting and ending -value. Btrees also do a better job of exploiting <i>locality -of reference</i>. If the application is likely to touch keys near each -other at the same time, the Btrees work well. The tree structure keeps -keys that are close together near one another in storage, so fetching -nearby values usually doesn't require a disk access. -<p>Record-number-based storage is natural for applications that need to -store and fetch records, but that do not have a simple way to generate -keys of their own. In a record number table, the record number is the -key for the record. Berkeley DB will generate these record numbers -automatically. -<p>Queues are well-suited for applications that create records, and then -must deal with those records in creation order. A good example is -on-line purchasing systems. Orders can enter the system at any time, -but should generally be filled in the order in which they were placed. -<h3>Data management services</h3> -<p>Berkeley DB offers important data management services, including concurrency, -transactions, and recovery. All of these services work on all of the -storage structures. -<p>Many users can work on the same database concurrently. Berkeley DB handles -locking transparently, ensuring that two users working on the same -record do not interfere with one another. -<p>The library provides strict ACID transaction semantics, by default. -However, applications are allowed to relax the isolation guarantees -the database system makes. -<p>Multiple operations can be grouped into a single transaction, and can -be committed or rolled back atomically. Berkeley DB uses a technique called -<i>two-phase locking</i> to be sure that concurrent transactions -are isolated from one another, and a technique called -<i>write-ahead logging</i> to guarantee that committed changes -survive application, system, or hardware failures. -<p>When an application starts up, it can ask Berkeley DB to run recovery. -Recovery restores the database to a clean state, with all committed -changes present, even after a crash. The database is guaranteed to be -consistent and all committed changes are guaranteed to be present when -recovery completes. -<p>An application can specify, when it starts up, which data management -services it will use. Some applications need fast, single-user, -non-transactional Btree data storage. In that case, the application can -disable the locking and transaction systems, and will not incur the -overhead of locking or logging. If an application needs to support -multiple concurrent users, but doesn't need transactions, it can turn -on locking without transactions. Applications that need concurrent, -transaction-protected database access can enable all of the -subsystems. -<p>In all these cases, the application uses the same function-call API to -fetch and update records. -<h3>Design</h3> -<p>Berkeley DB was designed to provide industrial-strength database services to -application developers, without requiring them to become database -experts. It is a classic C-library style <i>toolkit</i>, providing -a broad base of functionality to application writers. Berkeley DB was designed -by programmers, for programmers: its modular design surfaces simple, -orthogonal interfaces to core services, and it provides mechanism (for -example, good thread support) without imposing policy (for example, the -use of threads is not required). Just as importantly, Berkeley DB allows -developers to balance performance against the need for crash recovery -and concurrent use. An application can use the storage structure that -provides the fastest access to its data and can request only the degree -of logging and locking that it needs. -<p>Because of the tool-based approach and separate interfaces for each -Berkeley DB subsystem, you can support a complete transaction environment for -other system operations. Berkeley DB even allows you to wrap transactions -around the standard UNIX file read and write operations! Further, Berkeley DB -was designed to interact correctly with the native system's toolset, a -feature no other database package offers. For example, Berkeley DB supports -hot backups (database backups while the database is in use), using -standard UNIX system utilities, for example, dump, tar, cpio, pax or -even cp. -<p>Finally, because scripting language interfaces are available for Berkeley DB -(notably Tcl and Perl), application writers can build incredibly powerful -database engines with little effort. You can build transaction-protected -database applications using your favorite scripting languages, an -increasingly important feature in a world using CGI scripts to deliver -HTML. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/intro/terrain.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/intro/dbisnot.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/libdb/docs/ref/intro/dbisnot.html b/libdb/docs/ref/intro/dbisnot.html deleted file mode 100644 index e519ece42..000000000 --- a/libdb/docs/ref/intro/dbisnot.html +++ /dev/null @@ -1,141 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: What Berkeley DB is not</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Introduction</dl></h3></td> -<td align=right><a href="../../ref/intro/dbis.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/intro/need.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>What Berkeley DB is not</h1> -<p>In contrast to most other database systems, Berkeley DB provides relatively -simple data access services. -<p>Records in Berkeley DB are (<i>key</i>, <i>value</i>) pairs. Berkeley DB -supports only a few logical operations on records. They are: -<p><ul type=disc> -<li>Insert a record in a table. -<li>Delete a record from a table. -<li>Find a record in a table by looking up its key. -<li>Update a record that has already been found. -</ul> -<p>Notice that Berkeley DB never operates on the value part of a record. -Values are simply payload, to be -stored with keys and reliably delivered back to the application on -demand. -<p>Both keys and values can be arbitrary byte strings, either fixed-length -or variable-length. As a result, programmers can put native programming -language data structures into the database without converting them to -a foreign record format first. Storage and retrieval are very simple, -but the application needs to know what the structure of a key and a -value is in advance. It cannot ask Berkeley DB, because Berkeley DB doesn't know. -<p>This is an important feature of Berkeley DB, and one worth considering more -carefully. On the one hand, Berkeley DB cannot provide the programmer with -any information on the contents or structure of the values that it -stores. The application must understand the keys and values that it -uses. On the other hand, there is literally no limit to the data types -that can be store in a Berkeley DB database. The application never needs to -convert its own program data into the data types that Berkeley DB supports. -Berkeley DB is able to operate on any data type the application uses, no -matter how complex. -<p>Because both keys and values can be up to four gigabytes in length, a -single record can store images, audio streams, or other large data -values. Large values are not treated specially in Berkeley DB. They are -simply broken into page-sized chunks, and reassembled on demand when -the application needs them. Unlike some other database systems, Berkeley DB -offers no special support for binary large objects (BLOBs). -<h3>Not a relational database</h3> -<p>Berkeley DB is not a relational database. -<p>First, Berkeley DB does not support SQL queries. All access to data is through -the Berkeley DB API. Developers must learn a new set of interfaces in order -to work with Berkeley DB. Although the interfaces are fairly simple, they are -non-standard. -<p>SQL support is a double-edged sword. One big advantage of relational -databases is that they allow users to write simple declarative queries -in a high-level language. The database system knows everything about -the data and can carry out the command. This means that it's simple to -search for data in new ways, and to ask new questions of the database. -No programming is required. -<p>On the other hand, if a programmer can predict in advance how an -application will access data, then writing a low-level program to get -and store records can be faster. It eliminates the overhead of query -parsing, optimization, and execution. The programmer must understand -the data representation, and must write the code to do the work, but -once that's done, the application can be very fast. -<p>Second, Berkeley DB has no notion of <i>schema</i> and data types in -the way that relational systems do. Schema is the structure of records -in tables, and the relationships among the tables in the database. For -example, in a relational system the programmer can create a record from -a fixed menu of data types. Because the record types are declared to -the system, the relational engine can reach inside records and examine -individual values in them. In addition, programmers can use SQL to -declare relationships among tables, and to create indices on tables. -Relational engines usually maintain these relationships and indices -automatically. -<p>In Berkeley DB, the key and value in a record are opaque to Berkeley DB. They may -have a rich internal structure, but the library is unaware of it. As a -result, Berkeley DB cannot decompose the value part of a record into its -constituent parts, and cannot use those parts to find values of -interest. Only the application, which knows the data structure, can do -that. Berkeley DB does support indices on tables and automatically maintain -those indices as their associated tables are modified. -<p>Berkeley DB is not a relational system. Relational database systems are -semantically rich and offer high-level database access. Compared to such -systems, Berkeley DB is a high-performance, transactional library for record -storage. It's possible to build a relational system on top of Berkeley DB. In -fact, the popular MySQL relational system uses Berkeley DB for -transaction-protected table management, and takes care of all the SQL -parsing and execution. It uses Berkeley DB for the storage level, and provides -the semantics and access tools. -<h3>Not an object-oriented database</h3> -<p>Object-oriented databases are designed for very tight integration with -object-oriented programming languages. Berkeley DB is written entirely in the -C programming language. It includes language bindings for C++, Java, -and other languages, but the library has no information about the -objects created in any object-oriented application. Berkeley DB never makes -method calls on any application object. It has no idea what methods are -defined on user objects, and cannot see the public or private members -of any instance. The key and value part of all records are opaque to -Berkeley DB. -<p>Berkeley DB cannot automatically page in objects as they are accessed, as some -object-oriented databases do. The object-oriented application programmer -must decide what records are required, and must fetch them by making -method calls on Berkeley DB objects. -<h3>Not a network database</h3> -<p>Berkeley DB does not support network-style navigation among records, as -network databases do. Records in a Berkeley DB table may move around over -time, as new records are added to the table and old ones are deleted. -Berkeley DB is able to do fast searches for records based on keys, but there -is no way to create a persistent physical pointer to a record. -Applications can only refer to records by key, not by address. -<h3>Not a database server</h3> -<p>Berkeley DB is not a standalone database server. It is a library, and runs in -the address space of the application that uses it. If more than one -application links in Berkeley DB, then all can use the same database at the -same time; the library handles coordination among the applications, and -guarantees that they do not interfere with one another. -<p>Recent releases of Berkeley DB allow programmers to compile the library as a -standalone process, and to use RPC stubs to connect to it and to carry -out operations. However, there are some important limitations to this -feature. The RPC stubs provide exactly the same API that the library -itself does. There is no higher-level access provided by the standalone -process. Tuning the standalone process is difficult, since Berkeley DB does -no threading in the library (applications can be threaded, but the -library never creates a thread on its own). -<p>It is possible to build a server application that uses Berkeley DB for data -management. For example, many commercial and open source Lightweight -Directory Access Protocol (LDAP) servers use Berkeley DB for record storage. -LDAP clients connect to these servers over the network. Individual -servers make calls through the Berkeley DB API to find records and return them -to clients. On its own, however, Berkeley DB is not a server. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/intro/dbis.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/intro/need.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/libdb/docs/ref/intro/distrib.html b/libdb/docs/ref/intro/distrib.html deleted file mode 100644 index 26d87da5c..000000000 --- a/libdb/docs/ref/intro/distrib.html +++ /dev/null @@ -1,29 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: What does the Berkeley DB distribution include?</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Introduction</dl></h3></td> -<td align=right><a href="../../ref/intro/what.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/intro/where.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>What does the Berkeley DB distribution include?</h1> -<p>The Berkeley DB distribution includes complete source code for the Berkeley DB -library, including all three Berkeley DB products and their supporting -utilities, as well as complete documentation in HTML format. -<p>The distribution does not include prebuilt binaries or libraries, or -hard-copy documentation. Prebuilt libraries and binaries for some -architecture/compiler combinations are available as part of Sleepycat -Software's Berkeley DB support services. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/intro/what.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/intro/where.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/libdb/docs/ref/intro/need.html b/libdb/docs/ref/intro/need.html deleted file mode 100644 index c29af8b51..000000000 --- a/libdb/docs/ref/intro/need.html +++ /dev/null @@ -1,61 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Do you need Berkeley DB?</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Introduction</dl></h3></td> -<td align=right><a href="../../ref/intro/dbisnot.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/intro/what.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Do you need Berkeley DB?</h1> -<p>Berkeley DB is an ideal database system for applications that need fast, -scalable, and reliable embedded database management. For applications -that need different services, however, it can be a poor choice. -<p>First, do you need the ability to access your data in ways you cannot -predict in advance? If your users want to be able to enter SQL -queries to perform -complicated searches that you cannot program into your application to -begin with, then you should consider a relational engine instead. Berkeley DB -requires a programmer to write code in order to run a new kind of query. -<p>On the other hand, if you can predict your data access patterns up front --- and in particular if you need fairly simple key/value lookups -- then -Berkeley DB is a good choice. The queries can be coded up once, and will then -run very quickly because there is no SQL to parse and execute. -<p>Second, are there political arguments for or against a standalone -relational server? If you're building an application for your own use -and have a relational system installed with administrative support -already, it may be simpler to use that than to build and learn Berkeley DB. -On the other hand, if you'll be shipping many copies of your application -to customers, and don't want your customers to have to buy, install, -and manage a separate database system, then Berkeley DB may be a better -choice. -<p>Third, are there any technical advantages to an embedded database? If -you're building an application that will run unattended for long periods -of time, or for end users who are not sophisticated administrators, then -a separate server process may be too big a burden. It will require -separate installation and management, and if it creates new ways for -the application to fail, or new complexities to master in the field, -then Berkeley DB may be a better choice. -<p>The fundamental question is, how closely do your requirements match the -Berkeley DB design? Berkeley DB was conceived and built to provide fast, reliable, -transaction-protected record storage. The library itself was never -intended to provide interactive query support, graphical reporting -tools, or similar services that some other database systems provide. We -have tried always to err on the side of minimalism and simplicity. By -keeping the library small and simple, we create fewer opportunities for -bugs to creep in, and we guarantee that the database system stays fast, -because there is very little code to execute. If your application needs -that set of features, then Berkeley DB is almost certainly the best choice -for you. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/intro/dbisnot.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/intro/what.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/libdb/docs/ref/intro/products.html b/libdb/docs/ref/intro/products.html deleted file mode 100644 index 3de81653c..000000000 --- a/libdb/docs/ref/intro/products.html +++ /dev/null @@ -1,70 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Sleepycat Software's Berkeley DB products</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Introduction</dl></h3></td> -<td align=right><a href="../../ref/intro/where.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/simple_tut/intro.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Sleepycat Software's Berkeley DB products</h1> -<p>Sleepycat Software licenses four different products that use the Berkeley DB -technology. Each product offers a distinct level of database support. -It is not possible to mix-and-match products, that is, each application -or group of applications must use the same Berkeley DB product. -<p>All four products are included in the single Open Source distribution -of Berkeley DB from Sleepycat Software, and building that distribution -automatically builds all four products. Each product adds new -interfaces and services to the product that precedes it in the list. -As a result, developers can download Berkeley DB and build an application that -does only single-user, read-only database access, and easily add support -later for more users and more complex database access patterns. -<p>Users who distribute Berkeley DB must ensure that they are licensed for the -Berkeley DB interfaces they use. Information on licensing is available -directly from Sleepycat Software. -<h3>Berkeley DB Data Store</h3> -<p>The Berkeley DB Data Store product is an embeddable, high-performance data store. It -supports multiple concurrent threads of control to read information -managed by Berkeley DB. When updates are required, only a single process may -be using the database. That process may be multithreaded, but only one -thread of control should be allowed to update the database at any time. -The Berkeley DB Data Store does no locking, and so provides no guarantees of correct -behavior if more than one thread of control is updating the database at -a time. The Berkeley DB Data Store is intended for use in single-user or read-only -applications that can guarantee that no more than one thread of control -will ever update the database at any time. -<h3>Berkeley DB Concurrent Data Store</h3> -<p>The Berkeley DB Concurrent Data Store product adds multiple-reader, single writer capabilities to -the Berkeley DB Data Store product, supporting applications that need concurrent updates -and do not want to implement their own locking protocols. Berkeley DB Concurrent Data Store is -intended for applications that require occasional write access to a -database that is largely used for reading. -<h3>Berkeley DB Transactional Data Store</h3> -<p>The Berkeley DB Transactional Data Store product adds full transactional support and recoverability -to the Berkeley DB Data Store product. Berkeley DB Transactional Data Store is intended for applications that require -industrial-strength database services, including excellent performance -under high-concurrency workloads with a mixture of readers and writers, -the ability to commit or roll back multiple changes to the database at -a single instant, and the guarantee that even in the event of a -catastrophic system or hardware failure, any committed database changes -will be preserved. -<h3>Berkeley DB High Availability</h3> -<p>The Berkeley DB High Availability product support for data replication. A single master system -handles all updates, and distributes them to as many replicas as the -application requires. All replicas can handle read requests during -normal processing. If the master system fails for any reason, one of -the replicas takes over as the new master system, and distributes -updates to the remaining replicas. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/intro/where.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/simple_tut/intro.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/libdb/docs/ref/intro/terrain.html b/libdb/docs/ref/intro/terrain.html deleted file mode 100644 index 46f74da95..000000000 --- a/libdb/docs/ref/intro/terrain.html +++ /dev/null @@ -1,249 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Mapping the terrain: theory and practice</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Introduction</dl></h3></td> -<td align=right><a href="../../ref/intro/data.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/intro/dbis.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Mapping the terrain: theory and practice</h1> -<p>The first step in selecting a database system is figuring out what the -choices are. Decades of research and real-world deployment have produced -countless systems. We need to organize them somehow to reduce the number -of options. -<p>One obvious way to group systems is to use the common labels that -vendors apply to them. The buzzwords here include "network," -"relational," "object-oriented," and "embedded," with some -cross-fertilization like "object-relational" and "embedded network". -Understanding the buzzwords is important. Each has some grounding in -theory, but has also evolved into a practical label for categorizing -systems that work in a certain way. -<p>All database systems, regardless of the buzzwords that apply to them, -provide a few common services. All of them store data, for example. -We'll begin by exploring the common services that all systems provide, -and then examine the differences among the different kinds of systems. -<h3>Data access and data management</h3> -<p>Fundamentally, database systems provide two services. -<p>The first service is <i>data access</i>. Data access means adding -new data to the database (inserting), finding data of interest -(searching), changing data already stored (updating), and removing data -from the database (deleting). All databases provide these services. How -they work varies from category to category, and depends on the record -structure that the database supports. -<p>Each record in a database is a collection of values. For example, the -record for a Web site customer might include a name, email address, -shipping address, and payment information. Records are usually stored -in tables. Each table holds records of the same kind. For example, the -<b>customer</b> table at an e-commerce Web site might store the -customer records for every person who shopped at the site. Often, -database records have a different structure from the structures or -instances supported by the programming language in which an application -is written. As a result, working with records can mean: -<p><ul type=disc> -<li>using database operations like searches and updates on records; and -<li>converting between programming language structures and database record -types in the application. -</ul> -<p>The second service is <i>data management</i>. Data management is -more complicated than data access. Providing good data management -services is the hard part of building a database system. When you -choose a database system to use in an application you build, making sure -it supports the data management services you need is critical. -<p>Data management services include allowing multiple users to work on the -database simultaneously (concurrency), allowing multiple records to be -changed instantaneously (transactions), and surviving application and -system crashes (recovery). Different database systems offer different -data management services. Data management services are entirely -independent of the data access services listed above. For example, -nothing about relational database theory requires that the system -support transactions, but most commercial relational systems do. -<p>Concurrency means that multiple users can operate on the database at -the same time. Support for concurrency ranges from none (single-user -access only) to complete (many readers and writers working -simultaneously). -<p>Transactions permit users to make multiple changes appear at once. For -example, a transfer of funds between bank accounts needs to be a -transaction because the balance in one account is reduced and the -balance in the other increases. If the reduction happened before the -increase, than a poorly-timed system crash could leave the customer -poorer; if the bank used the opposite order, then the same system crash -could make the customer richer. Obviously, both the customer and the -bank are best served if both operations happen at the same instant. -<p>Transactions have well-defined properties in database systems. They are -<i>atomic</i>, so that the changes happen all at once or not at all. -They are <i>consistent</i>, so that the database is in a legal state -when the transaction begins and when it ends. They are typically -<i>isolated</i>, which means that any other users in the database -cannot interfere with them while they are in progress. And they are -<i>durable</i>, so that if the system or application crashes after -a transaction finishes, the changes are not lost. Together, the -properties of <i>atomicity</i>, <i>consistency</i>, -<i>isolation</i>, and <i>durability</i> are known as the ACID -properties. -<p>As is the case for concurrency, support for transactions varies among -databases. Some offer atomicity without making guarantees about -durability. Some ignore isolatability, especially in single-user -systems; there's no need to isolate other users from the effects of -changes when there are no other users. -<p>Another important data management service is recovery. Strictly -speaking, recovery is a procedure that the system carries out when it -starts up. The purpose of recovery is to guarantee that the database is -complete and usable. This is most important after a system or -application crash, when the database may have been damaged. The recovery -process guarantees that the internal structure of the database is good. -Recovery usually means that any completed transactions are checked, and -any lost changes are reapplied to the database. At the end of the -recovery process, applications can use the database as if there had been -no interruption in service. -<p>Finally, there are a number of data management services that permit -copying of data. For example, most database systems are able to import -data from other sources, and to export it for use elsewhere. Also, most -systems provide some way to back up databases and to restore in the -event of a system failure that damages the database. Many commercial -systems allow <i>hot backups</i>, so that users can back up -databases while they are in use. Many applications must run without -interruption, and cannot be shut down for backups. -<p>A particular database system may provide other data management services. -Some provide browsers that show database structure and contents. Some -include tools that enforce data integrity rules, such as the rule that -no employee can have a negative salary. These data management services -are not common to all systems, however. Concurrency, recovery, and -transactions are the data management services that most database vendors -support. -<p>Deciding what kind of database to use means understanding the data -access and data management services that your application needs. Berkeley DB -is an embedded database that supports fairly simple data access with a -rich set of data management services. To highlight its strengths and -weaknesses, we can compare it to other database system categories. -<h3>Relational databases</h3> -<p>Relational databases are probably the best-known database variant, -because of the success of companies like Oracle. Relational databases -are based on the mathematical field of set theory. The term "relation" -is really just a synonym for "set" -- a relation is just a set of -records or, in our terminology, a table. One of the main innovations in -early relational systems was to insulate the programmer from the -physical organization of the database. Rather than walking through -arrays of records or traversing pointers, programmers make statements -about tables in a high-level language, and the system executes those -statements. -<p>Relational databases operate on <i>tuples</i>, or records, composed -of values of several different data types, including integers, character -strings, and others. Operations include searching for records whose -values satisfy some criteria, updating records, and so on. -<p>Virtually all relational databases use the Structured Query Language, -or SQL. This language permits people and computer programs to work with -the database by writing simple statements. The database engine reads -those statements and determines how to satisfy them on the tables in -the database. -<p>SQL is the main practical advantage of relational database systems. -Rather than writing a computer program to find records of interest, the -relational system user can just type a query in a simple syntax, and -let the engine do the work. This gives users enormous flexibility; they -do not need to decide in advance what kind of searches they want to do, -and they do not need expensive programmers to find the data they need. -Learning SQL requires some effort, but it's much simpler than a -full-blown high-level programming language for most purposes. And there -are a lot of programmers who have already learned SQL. -<h3>Object-oriented databases</h3> -<p>Object-oriented databases are less common than relational systems, but -are still fairly widespread. Most object-oriented databases were -originally conceived as persistent storage systems closely wedded to -particular high-level programming languages like C++. With the spread -of Java, most now support more than one programming language, but -object-oriented database systems fundamentally provide the same class -and method abstractions as do object-oriented programming languages. -<p>Many object-oriented systems allow applications to operate on objects -uniformly, whether they are in memory or on disk. These systems create -the illusion that all objects are in memory all the time. The advantage -to object-oriented programmers who simply want object storage and -retrieval is clear. They need never be aware of whether an object is in -memory or not. The application simply uses objects, and the database -system moves them between disk and memory transparently. All of the -operations on an object, and all its behavior, are determined by the -programming language. -<p>Object-oriented databases aren't nearly as widely deployed as relational -systems. In order to attract developers who understand relational -systems, many of the object-oriented systems have added support for -query languages very much like SQL. In practice, though, object-oriented -databases are mostly used for persistent storage of objects in C++ and -Java programs. -<h3>Network databases</h3> -<p>The "network model" is a fairly old technique for managing and -navigating application data. Network databases are designed to make -pointer traversal very fast. Every record stored in a network database -is allowed to contain pointers to other records. These pointers are -generally physical addresses, so fetching the record to which it refers -just means reading it from disk by its disk address. -<p>Network database systems generally permit records to contain integers, -floating point numbers, and character strings, as well as references to -other records. An application can search for records of interest. After -retrieving a record, the application can fetch any record to which it -refers, quickly. -<p>Pointer traversal is fast because most network systems use physical disk -addresses as pointers. When the application wants to fetch a record, -the database system uses the address to fetch exactly the right string -of bytes from the disk. This requires only a single disk access in all -cases. Other systems, by contrast, often must do more than one disk read -to find a particular record. -<p>The key advantage of the network model is also its main drawback. The -fact that pointer traversal is so fast means that applications that do -it will run well. On the other hand, storing pointers all over the -database makes it very hard to reorganize the database. In effect, once -you store a pointer to a record, it is difficult to move that record -elsewhere. Some network databases handle this by leaving forwarding -pointers behind, but this defeats the speed advantage of doing a single -disk access in the first place. Other network databases find, and fix, -all the pointers to a record when it moves, but this makes -reorganization very expensive. Reorganization is often necessary in -databases, since adding and deleting records over time will consume -space that cannot be reclaimed without reorganizing. Without periodic -reorganization to compact network databases, they can end up with a -considerable amount of wasted space. -<h3>Clients and servers</h3> -<p>Database vendors have two choices for system architecture. They can -build a server to which remote clients connect, and do all the database -management inside the server. Alternatively, they can provide a module -that links directly into the application, and does all database -management locally. In either case, the application developer needs -some way of communicating with the database (generally, an Application -Programming Interface (API) that does work in the process or that -communicates with a server to get work done). -<p>Almost all commercial database products are implemented as servers, and -applications connect to them as clients. Servers have several features -that make them attractive. -<p>First, because all of the data is managed by a separate process, and -possibly on a separate machine, it's easy to isolate the database server -from bugs and crashes in the application. -<p>Second, because some database products (particularly relational engines) -are quite large, splitting them off as separate server processes keeps -applications small, which uses less disk space and memory. Relational -engines include code to parse SQL statements, to analyze them and -produce plans for execution, to optimize the plans, and to execute -them. -<p>Finally, by storing all the data in one place and managing it with a -single server, it's easier for organizations to back up, protect, and -set policies on their databases. The enterprise databases for large -companies often have several full-time administrators caring for them, -making certain that applications run quickly, granting and denying -access to users, and making backups. -<p>However, centralized administration can be a disadvantage in some cases. -In particular, if a programmer wants to build an application that uses -a database for storage of important information, then shipping and -supporting the application is much harder. The end user needs to install -and administer a separate database server, and the programmer must -support not just one product, but two. Adding a server process to the -application creates new opportunity for installation mistakes and -run-time problems. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/intro/data.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/intro/dbis.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/libdb/docs/ref/intro/what.html b/libdb/docs/ref/intro/what.html deleted file mode 100644 index e41cae155..000000000 --- a/libdb/docs/ref/intro/what.html +++ /dev/null @@ -1,54 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: What other services does Berkeley DB provide?</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Introduction</dl></h3></td> -<td align=right><a href="../../ref/intro/need.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/intro/distrib.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>What other services does Berkeley DB provide?</h1> -<p>Berkeley DB also provides core database services to developers. These -services include: -<p><dl compact> -<p><dt>Page cache management:<dd>The page cache provides fast access to a cache of database pages, -handling the I/O associated with the cache to ensure that dirty pages -are written back to the file system and that new pages are allocated on -demand. Applications may use the Berkeley DB shared memory buffer manager to -serve their own files and pages. -<p><dt>Transactions and logging:<dd>The transaction and logging systems provide recoverability and atomicity -for multiple database operations. The transaction system uses two-phase -locking and write-ahead logging protocols to ensure that database -operations may be undone or redone in the case of application or system -failure. Applications may use Berkeley DB transaction and logging subsystems -to protect their own data structures and operations from application or -system failure. -<p><dt>Locking:<dd>The locking system provides multiple reader or single writer access to -objects. The Berkeley DB access methods use the locking system to acquire -the right to read or write database pages. Applications may use the -Berkeley DB locking subsystem to support their own locking needs. -</dl> -<p>By combining the page cache, transaction, locking, and logging systems, -Berkeley DB provides the same services found in much larger, more complex and -more expensive database systems. Berkeley DB supports multiple simultaneous -readers and writers and guarantees that all changes are recoverable, even -in the case of a catastrophic hardware failure during a database update. -<p>Developers may select some or all of the core database services for any -access method or database. Therefore, it is possible to choose the -appropriate storage structure and the right degrees of concurrency and -recoverability for any application. In addition, some of the subsystems -(for example, the Locking subsystem) can be called separately from the -Berkeley DB access method. As a result, developers can integrate non-database -objects into their transactional applications using Berkeley DB. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/intro/need.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/intro/distrib.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/libdb/docs/ref/intro/where.html b/libdb/docs/ref/intro/where.html deleted file mode 100644 index 313a5244e..000000000 --- a/libdb/docs/ref/intro/where.html +++ /dev/null @@ -1,45 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Where does Berkeley DB run?</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Introduction</dl></h3></td> -<td align=right><a href="../../ref/intro/distrib.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/intro/products.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Where does Berkeley DB run?</h1> -<p>Berkeley DB requires only underlying IEEE/ANSI Std 1003.1 (POSIX) system calls and can be -ported easily to new architectures by adding stub routines to connect -the native system interfaces to the Berkeley DB POSIX-style system calls. -See <a href="../../ref/distrib/port.html">Porting Berkeley DB to new -architectures</a> for more information. -<p>Berkeley DB will autoconfigure and run on almost any modern UNIX, POSIX or -Linux systems, and on most historical UNIX platforms. Berkeley DB will -autoconfigure and run on almost any GNU gcc toolchain-based embedded -platform, including Cygwin, Embedix, OpenLinux and others. See -<a href="../../ref/build_unix/intro.html">Building for UNIX systems</a> for -more information. -<p>The Berkeley DB distribution includes support for QNX Neutrino. See -<a href="../../ref/build_unix/intro.html">Building for UNIX systems</a> for -more information. -<p>The Berkeley DB distribution includes support for VxWorks, via a workspace -and project files for Tornado 2.0. See -<a href="../../ref/build_vxworks/intro.html">Building for VxWorks</a> for more -information. -<p>The Berkeley DB distribution includes support for Windows/95, Windows/98, -Windows/NT, Windows/2000 and Windows/XP, via the Microsoft Visual C++ -6.0 and .NET development environments. See -<a href="../../ref/build_win/intro.html">Building for Windows systems</a> -for more information. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/intro/distrib.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/intro/products.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/libdb/docs/ref/java/compat.html b/libdb/docs/ref/java/compat.html deleted file mode 100644 index b92045a77..000000000 --- a/libdb/docs/ref/java/compat.html +++ /dev/null @@ -1,35 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Compatibility</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Java API</dl></h3></td> -<td align=right><a href="../../ref/java/conf.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/java/program.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Compatibility</h1> -<p>The Berkeley DB Java API has been tested with the -<a href="http://www.javasoft.com">Sun Microsystems JDK 1.1.3</a> on SunOS -5.5; and Sun's JDK 1.1.7, JDK 1.2.2, JDK 1.3.0 and JDK 1.4.0 on Linux and -Windows/NT. It should work with any JDK 1.1-, 1.2-, 1.3- or 1.4-compatible -environment (the latter three are known as Java 2). IBM's VM 1.3.0 has -also been tested on Linux. -<p>The primary requirement of the Berkeley DB Java API is that the target Java -environment must support JNI (Java Native Interface) rather than another -method for allowing native C/C++ code to interface to Java. The JNI was -new in JDK 1.1, but is the most likely interface to be implemented -across multiple platforms. However, using the JNI means that Berkeley DB will -not be compatible with Microsoft Visual J++. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/java/conf.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/java/program.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/libdb/docs/ref/java/conf.html b/libdb/docs/ref/java/conf.html deleted file mode 100644 index 2eb60a711..000000000 --- a/libdb/docs/ref/java/conf.html +++ /dev/null @@ -1,94 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Java configuration</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Java API</dl></h3></td> -<td align=right><a href="../../ref/rpc/faq.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/java/compat.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Java configuration</h1> -<p>Building the Berkeley DB java classes, the examples and the native support -library is integrated into the normal build process. See -<a href="../../ref/build_unix/conf.html#--enable-java">Configuring -Berkeley DB</a> and <a href="../../ref/build_win/intro.html">Building for Win32</a> -for more information. -<p>We expect that you already installed the Java JDK or equivalent on your -system. For the sake of discussion, we assume that it is in a directory -called db-VERSION; for example, you downloaded a Berkeley DB archive, and you -did not change the top-level directory name. The files related to Java -are in two subdirectories of db-VERSION: java (the java source files) -and libdb_java (the C++ files that provide the "glue" between java and -Berkeley DB). The directory tree looks like this: -<p><blockquote><pre> db-VERSION - / \ - java libdb_java - | | - src ... - | - com - | - sleepycat - / \ - db examples - | | - ... ... -</pre></blockquote> -<p>This naming conforms to the de facto standard for naming java packages. -When the java code is built, it is placed into two jar files: -<b>db.jar</b>, containing the db package, -and <b>dbexamples.jar</b>, containing the examples. -<p>For your application to use Berkeley DB successfully, you must set your -<b>CLASSPATH</b> environment variable to include the full pathname of -the db jar files as well as the classes in your java distribution. -On UNIX, <b>CLASSPATH</b> is a colon-separated -list of directories and jar files; -on Windows, it is separated by semicolons. -On UNIX, the jar files are put in your build directory, and when -you do the make install step, they are copied to the lib directory -of your installation tree. On Windows, the jar files are placed -in the Release or Debug subdirectory with your other objects. -<p>The Berkeley DB Java classes are mostly implemented in native -methods. Before you can use them, you need to make sure that the -DLL or shared library containing the native methods can be found -by your Java runtime. On Windows, you should set your PATH variable -to include: -<p><blockquote><pre><b>db-VERSION\build_win32\Release</b></pre></blockquote> -<p>On UNIX, you should set the -<b>LD_LIBRARY_PATH</b> environment variable or local equivalent -to include the Berkeley DB library installation directory. Of course, the -standard install directory may have been changed for your site; see your -system administrator for details. -<p>On other platforms, the path can be set on the command line as follows -(assuming the shared library is in <b>/usr/local/BerkeleyDB/lib</b>:) -<p><blockquote><pre>% java -Djava.library.path=/usr/local/BerkeleyDB/lib ...</pre></blockquote> -<p>Regardless, if you get the following exception when you run, you -probably do not have the library search path configured correctly: -<p><blockquote><pre>java.lang.UnsatisfiedLinkError</pre></blockquote> -<p>Different Java interpreters provide different error messages if the -<b>CLASSPATH</b> value is incorrect, a typical error is the following: -<p><blockquote><pre>java.lang.NoClassDefFoundError</pre></blockquote> -<p>To ensure that everything is running correctly, you may want to try a -simple test from the example programs in -<p><blockquote><pre><b>db-VERSION/java/src/com/sleepycat/examples</b></pre></blockquote> -<p>For example, the following sample program will prompt for text input -lines, which are then stored in a Btree database named <b>access.db</b> in -your current directory: -<p><blockquote><pre>% java com.sleepycat.examples.AccessExample</pre></blockquote> -<p>Try giving it a few lines of input text and then end-of-file. Before -it exits, you should see a list of the lines you entered display with -data items. This is a simple check to make sure the fundamental -configuration is working correctly. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/rpc/faq.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/java/compat.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/libdb/docs/ref/java/faq.html b/libdb/docs/ref/java/faq.html deleted file mode 100644 index bb7af6a6d..000000000 --- a/libdb/docs/ref/java/faq.html +++ /dev/null @@ -1,40 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Java FAQ</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Java API</dl></h3></td> -<td align=right><a href="../../ref/java/program.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/perl/intro.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Java FAQ</h1> -<p><ol> -<p><li><b>During one of the first calls to the Berkeley DB Java API, a -DbException is thrown with a "Bad file number" or "Bad file descriptor" -message.</b> -<p>There are known large-file support bugs under JNI in various releases -of the JDK. Please upgrade to the latest release of the JDK, and, if -that does not solve the problem, disable big file support using the ---disable-largefile configuration option. -<p><li><b>How can I use native methods from a debug build of the -Java library?</b> -<p>The Berkeley DB Java code checks a system property for the library name -before defaulting to the released library. On Windows, run as -follows (note the 'd' at the end): -<p><blockquote><pre>% java -Dsleepycat.db.libname=libdb_java-VERSIONd</pre></blockquote> -<p>On UNIX, try: -<p><blockquote><pre>% java -Dsleepycat.db.libname=db_java_g-VERSION</pre></blockquote> -</ol> -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/java/program.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/perl/intro.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/libdb/docs/ref/java/program.html b/libdb/docs/ref/java/program.html deleted file mode 100644 index 7b7aef13b..000000000 --- a/libdb/docs/ref/java/program.html +++ /dev/null @@ -1,78 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Java programming notes</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Java API</dl></h3></td> -<td align=right><a href="../../ref/java/compat.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/java/faq.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Java programming notes</h1> -<p>The Java API closely parallels the Berkeley DB C++ and C interfaces. If you -are currently using either of those APIs, there will be very little to -surprise you in the Java API. We have even taken care to make the names -of classes, constants, methods and arguments identical, where possible, -across all three APIs. -<p><ol> -<p><li>The Java runtime does not automatically close Berkeley DB objects on -finalization. There are several reasons for this. One is that -finalization is generally run only when garbage collection occurs, and -there is no guarantee that this occurs at all, even on exit. Allowing -specific Berkeley DB actions to occur in ways that cannot be replicated seems -wrong. Second, finalization of objects may happen in an arbitrary -order, so we would have to do extra bookkeeping to make sure that -everything was closed in the proper order. The best word of advice is -to always do a close() for any matching open() call. Specifically, the -Berkeley DB package requires that you explicitly call close on each individual -<a href="../../api_java/db_class.html">Db</a> and <a href="../../api_java/dbc_class.html">Dbc</a> object that you opened. Your database -activity may not be synchronized to disk unless you do so. -<p><li>Some methods in the Java API have no return type, and throw a -<a href="../../api_java/except_class.html">DbException</a> when an severe error arises. There are some notable -methods that do have a return value, and can also throw an exception. -<a href="../../api_java/db_get.html">Db.get</a> and <a href="../../api_java/dbc_get.html">Dbc.get</a> both return 0 when a get succeeds, -return <a href="../../ref/program/errorret.html#DB_NOTFOUND">Db.DB_NOTFOUND</a> when the key is not found, and throw an error -when there is a severe error. This approach allows the programmer to -check for typical data-driven errors by watching return values without -special casing exceptions. -<p>An object of type <a href="../../api_java/deadlock_class.html">DbDeadlockException</a> is thrown when a deadlock -would occur. -<p>An object of type <a href="../../api_java/memp_class.html">DbMemoryException</a> is thrown when the system -cannot provide enough memory to complete the operation (the ENOMEM -system error on UNIX). -<p>An object of type <a href="../../api_java/runrec_class.html">DbRunRecoveryException</a>, a subclass of -<a href="../../api_java/except_class.html">DbException</a>, is thrown when there is an error that requires a -recovery of the database using <a href="../../utility/db_recover.html">db_recover</a>. -<p><li>There is no class corresponding to the C++ DbMpoolFile class in the Berkeley DB -Java API. There is a subset of the memp_XXX methods in the <a href="../../api_java/env_class.html">DbEnv</a> -class. This has been provided to allow you to perform certain -administrative actions on underlying memory pools opened as a consequence -of <a href="../../api_java/env_open.html">DbEnv.open</a>. Direct access to other memory pool functionality -is not appropriate for the Java environment. -<p><li>Berkeley DB always turns on the <a href="../../api_java/env_open.html#DB_THREAD">Db.DB_THREAD</a> flag because -threads are expected in Java. -<p><li>If there are embedded null strings in the <b>curslist</b> argument for -<a href="../../api_java/db_join.html">Db.join</a>, they will be treated as the end of the list of -cursors, even if you may have allocated a longer array. Fill in all -the strings in your array unless you intend to cut it short. -<p><li>The callback installed for <a href="../../api_java/env_set_errcall.html">DbEnv.set_errcall</a> will run in the same -thread as the caller to <a href="../../api_java/env_set_errcall.html">DbEnv.set_errcall</a>. Make sure that thread -remains running until your application exits or until <a href="../../api_java/env_close.html">DbEnv.close</a> -is called. -<p><li>If you are using custom class loaders in your application, make sure -that the Berkeley DB classes are loaded by the system class loader, not a -custom class loader. This is due to a JVM bug that can cause an access -violation during finalization (see the bug 4238486 in Sun Microsystem's -Java Bug Database). -</ol> -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/java/compat.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/java/faq.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/libdb/docs/ref/lock/am_conv.html b/libdb/docs/ref/lock/am_conv.html deleted file mode 100644 index ad040566c..000000000 --- a/libdb/docs/ref/lock/am_conv.html +++ /dev/null @@ -1,124 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Berkeley DB Transactional Data Store locking conventions</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Locking Subsystem</dl></h3></td> -<td align=right><a href="../../ref/lock/cam_conv.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/lock/nondb.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Berkeley DB Transactional Data Store locking conventions</h1> -<p>All Berkeley DB access methods follow the same conventions for locking -database objects. Applications that do their own locking and also do -locking via the access methods must be careful to adhere to these -conventions. -<p>Whenever a Berkeley DB database is opened, the <a href="../../api_c/db_class.html">DB</a> handle is assigned -a unique locker ID. Unless transactions are specified, that ID is used -as the locker for all calls that the Berkeley DB methods make to the lock -subsystem. In order to lock a file, pages in the file, or records in -the file, we must create a unique ID that can be used as the object to -be locked in calls to the lock manager. Under normal operation, that -object is a 28-byte value created by the concatenation of a unique file -identifier, a page or record number, and an object type (page or record). -<p>In a transaction-protected environment, database create and delete -operations are recoverable and single-threaded. This single-threading -is achieved using a single lock for the entire environment that must be -acquired before beginning a create or delete operation. In this case, -the object on which Berkeley DB will lock is a 4-byte unsigned integer with -a value of 0. -<p>If applications are using the lock subsystem directly while they are -also using locking via the access methods, they must take care not to -inadvertently lock objects that happen to be equal to the unique file -IDs used to lock files. This is most easily accomplished by using a -lock object with a length different from the values used by Berkeley DB. -<p>All the access methods other than Queue use standard read/write locks -in a simple multiple-reader/single writer page-locking scheme. An -operation that returns data (for example, <a href="../../api_c/db_get.html">DB->get</a> or -<a href="../../api_c/dbc_get.html">DBcursor->c_get</a>) obtains a read lock on all the pages accessed while -locating the requested record. When an update operation is requested -(for example, <a href="../../api_c/db_put.html">DB->put</a> or <a href="../../api_c/dbc_del.html">DBcursor->c_del</a>), the page containing -the updated (or new) data is write-locked. As read-modify-write cycles -are quite common and are deadlock-prone under normal circumstances, the -Berkeley DB interfaces allow the application to specify the <a href="../../api_c/dbc_get.html#DB_RMW">DB_RMW</a> -flag, which causes operations to immediately obtain a write lock, even -though they are only reading the data. Although this may reduce -concurrency somewhat, it reduces the probability of deadlock. In the -presence of transactions, page locks are held until transaction commit. -<p>The Queue access method does not hold long-term page locks. Instead, -page locks are held only long enough to locate records or to change -metadata on a page, and record locks are held for the appropriate -duration. In the presence of transactions, record locks are held until -transaction commit. For Berkeley DB operations, record locks are held until -operation completion; for <a href="../../api_c/dbc_class.html">DBC</a> operations, record locks are held -until subsequent records are returned or the cursor is closed. -<p>Under non-transaction operations, the access methods do not normally -hold locks across calls to the Berkeley DB interfaces. The one exception to -this rule is when cursors are used. Because cursors maintain a position -in a file, they must hold locks across calls; in fact, they will hold -locks until the cursor is closed. -<p>In this mode, the assignment of locker IDs to <a href="../../api_c/db_class.html">DB</a> and cursor -handles is complicated. If the <a href="../../api_c/env_open.html#DB_THREAD">DB_THREAD</a> option was specified -when the <a href="../../api_c/db_class.html">DB</a> handle was opened, each use of a <a href="../../api_c/db_class.html">DB</a> has its -own unique locker ID, and each cursor is assigned its own unique locker -ID when it is created, so <a href="../../api_c/db_class.html">DB</a> handle and cursor operations can -all conflict with one another. (This is because when Berkeley DB handles -may be shared by multiple threads of control the Berkeley DB library cannot -identify which operations are performed by which threads of control, -and it must ensure that two different threads of control are not -simultaneously modifying the same data structure. By assigning each -<a href="../../api_c/db_class.html">DB</a> handle and cursor its own locker, two threads of control -sharing a handle cannot inadvertently interfere with each other.) -<p>This has important implications. If a single thread of control opens -two cursors, uses a combination of cursor and non-cursor operations, or -begins two separate transactions, the operations are performed on behalf -of different lockers. Conflicts that arise between these different -lockers may not cause actual deadlocks, but can, in fact, permanently -block the thread of control. For example, assume that an application -creates a cursor and uses it to read record A. Now, assume a second -cursor is opened, and the application attempts to write record A using -the second cursor. Unfortunately, the first cursor has a read lock, so -the second cursor cannot obtain its write lock. However, that read lock -is held by the same thread of control, so the read lock can never be -released if we block waiting for the write lock. This might appear to -be a deadlock from the application's perspective, but Berkeley DB cannot -identify it as such because it has no knowledge of which lockers belong -to which threads of control. For this reason, application designers -are encouraged to close cursors as soon as they are done with them. -<p>If the <a href="../../api_c/env_open.html#DB_THREAD">DB_THREAD</a> option was not specified when the <a href="../../api_c/db_class.html">DB</a> -handle was opened, all uses of the <a href="../../api_c/db_class.html">DB</a> handle and all cursors -created using that handle will use the same locker ID for all -operations. In this case, if a single thread of control opens two -cursors or uses a combination of cursor and non-cursor operations, these -operations are performed on behalf of the same locker, and so cannot -deadlock or block the thread of control. -<p>Complicated operations that require multiple cursors (or combinations -of cursor and non-cursor operations) can be performed in two ways. -First, they may be performed within a transaction, in which case all -operations lock on behalf of the designated transaction. Second, they -may be performed using a local <a href="../../api_c/db_class.html">DB</a> handle, although, as -<a href="../../api_c/db_open.html">DB->open</a> operations are relatively slow, this may not be a good -idea. Finally, the <a href="../../api_c/dbc_dup.html">DBcursor->c_dup</a> function duplicates a cursor, using -the same locker ID as the originating cursor. There is no way to -achieve this duplication functionality through the <a href="../../api_c/db_class.html">DB</a> handle -calls, but any <a href="../../api_c/db_class.html">DB</a> call can be implemented by one or more calls -through a cursor. -<p>When the access methods use transactions, many of these problems disappear. -The transaction ID is used as the locker ID for all operations performed -on behalf of the transaction. This means that the application may open -multiple cursors on behalf of the same transaction and these cursors will -all share a common locker ID. This is safe because transactions cannot -span threads of control, so the library knows that two cursors in the same -transaction cannot modify the database concurrently. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/lock/cam_conv.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/lock/nondb.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/libdb/docs/ref/lock/cam_conv.html b/libdb/docs/ref/lock/cam_conv.html deleted file mode 100644 index e3eebae88..000000000 --- a/libdb/docs/ref/lock/cam_conv.html +++ /dev/null @@ -1,54 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Berkeley DB Concurrent Data Store locking conventions</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Locking Subsystem</dl></h3></td> -<td align=right><a href="../../ref/lock/twopl.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/lock/am_conv.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Berkeley DB Concurrent Data Store locking conventions</h1> -<p>The Berkeley DB Concurrent Data Store product has a simple set of conventions for locking. It -provides multiple-reader/single-writer semantics, but not per-page -locking or transaction recoverability. As such, it does its locking -entirely at the interface to the access methods. -<p>The object it locks is the file, identified by its unique file number. -The locking matrix is not one of the two standard lock modes, instead, -we use a four-lock set, consisting of the following: -<p><dl compact> -<p><dt>DB_LOCK_NG<dd>not granted (always 0) -<dt>DB_LOCK_READ<dd>read (shared) -<dt>DB_LOCK_WRITE<dd>write (exclusive) -<dt>DB_LOCK_IWRITE<dd>intention-to-write (shared with NG and READ, but conflicts with WRITE and IWRITE) -</dl> -<p>The IWRITE lock is used for cursors that will be used for updating -(IWRITE locks are implicitly obtained for write operations through the -Berkeley DB handles, for example, <a href="../../api_c/db_put.html">DB->put</a> or <a href="../../api_c/db_del.html">DB->del</a>). While -the cursor is reading, the IWRITE lock is held; but as soon as the -cursor is about to modify the database, the IWRITE is upgraded to a -WRITE lock. This upgrade blocks until all readers have exited the -database. Because only one IWRITE lock is allowed at any one time, no -two cursors can ever try to upgrade to a WRITE lock at the same time, -and therefore deadlocks are prevented, which is essential because Berkeley DB Concurrent Data Store -does not include deadlock detection and recovery. -<p>Applications that need to lock compatibly with Berkeley DB Concurrent Data Store must obey the -following rules: -<p><ol> -<p><li>Use only lock modes DB_LOCK_NG, DB_LOCK_READ, DB_LOCK_WRITE, -DB_LOCK_IWRITE. -<p><li>Never attempt to acquire a WRITE lock on an object that is -already locked with a READ lock. -</ol> -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/lock/twopl.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/lock/am_conv.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/libdb/docs/ref/lock/config.html b/libdb/docs/ref/lock/config.html deleted file mode 100644 index b8a400bc7..000000000 --- a/libdb/docs/ref/lock/config.html +++ /dev/null @@ -1,44 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Configuring locking</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Locking Subsystem</dl></h3></td> -<td align=right><a href="../../ref/lock/intro.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/lock/max.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Configuring locking</h1> -<p>The <a href="../../api_c/env_set_lk_detect.html">DB_ENV->set_lk_detect</a> method specifies that the deadlock detector -should be run whenever a lock is about to block. This option provides -for rapid detection of deadlocks at the expense of potentially frequent -invocations of the deadlock detector. On a fast processor with a highly -contentious application where response time is critical, this is a good -choice. An option argument to the <a href="../../api_c/env_set_lk_detect.html">DB_ENV->set_lk_detect</a> method -indicates which lock requests should be rejected. -<p>In general, when applications are not specifying lock and transaction -timeout values, the <a href="../../api_c/env_set_lk_detect.html#DB_LOCK_DEFAULT">DB_LOCK_DEFAULT</a> option is probably the -correct first choice, and other options should only be selected based -on evidence that they improve transaction throughput. If an application -has long-running transactions, <a href="../../api_c/env_set_lk_detect.html#DB_LOCK_YOUNGEST">DB_LOCK_YOUNGEST</a> will guarantee -that transactions eventually complete, but it may do so at the expense -of a large number of lock request rejections (and therefore, transaction -aborts). -<p>The alternative to using the <a href="../../api_c/env_set_lk_detect.html">DB_ENV->set_lk_detect</a> interface is -to explicitly perform deadlock detection using the Berkeley DB -<a href="../../api_c/lock_detect.html">DB_ENV->lock_detect</a> interface. -<p>The <a href="../../api_c/env_set_lk_conflicts.html">DB_ENV->set_lk_conflicts</a> method allows you to specify your own -locking conflicts matrix. This is an advanced configuration option, -and is almost never necessary. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/lock/intro.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/lock/max.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/libdb/docs/ref/lock/dead.html b/libdb/docs/ref/lock/dead.html deleted file mode 100644 index 48681b225..000000000 --- a/libdb/docs/ref/lock/dead.html +++ /dev/null @@ -1,84 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Deadlock detection</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Locking Subsystem</dl></h3></td> -<td align=right><a href="../../ref/lock/stdmode.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/lock/timeout.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Deadlock detection</h1> -<p>Practically any application that uses locking may deadlock. The -exceptions to this rule are when all the threads of control accessing -the database are read-only or when the Berkeley DB Concurrent Data Store product is used; the -Berkeley DB Concurrent Data Store product guarantees deadlock-free operation at the expense of -reduced concurrency. While there are data access patterns that are -deadlock free (for example, an application doing nothing but overwriting -fixed-length records in an already existing database), they are -extremely rare. -<p>When a deadlock exists in the system, all the threads of control -involved in the deadlock are, by definition, waiting on a lock. The -deadlock detector examines the state of the lock manager and identifies -a deadlock, and selects one of the lock requests to reject. (See -<a href="../../ref/lock/config.html">Configuring locking</a> for a -discussion of how a participant is selected). The <a href="../../api_c/lock_get.html">DB_ENV->lock_get</a> or -<a href="../../api_c/lock_vec.html">DB_ENV->lock_vec</a> call for which the selected participant is waiting then -returns a <a href="../../ref/program/errorret.html#DB_LOCK_DEADLOCK">DB_LOCK_DEADLOCK</a> error. When using the Berkeley DB access -methods, this error return is propagated back through the Berkeley DB -interface database handle interface to the calling application. -<p>The deadlock detector identifies deadlocks by looking for a cycle in -what is commonly referred to as its "waits-for" graph. More precisely, -the deadlock detector reads through the lock table, and reviews each -lock object currently locked. Each object has lockers that currently -hold locks on the object and possibly a list of lockers waiting for a -lock on the object. Each object's list of waiting lockers defines a -partial ordering. That is, for a particular object, every waiting -locker comes after every holding locker because that holding locker must -release its lock before the waiting locker can make forward progress. -Conceptually, after each object has been examined, the partial orderings -are topologically sorted. If this topological sort reveals any cycles, -the lockers forming the cycle are involved in a deadlock. One of the -lockers is selected for rejection. -<p>It is possible that rejecting a single lock request involved in a -deadlock is not enough to allow other lockers to make forward progress. -Unfortunately, at the time a lock request is selected for rejection, -there is not enough information available to determine whether rejecting -that single lock request will allow forward progress or not. Because -most applications have few deadlocks, Berkeley DB takes the conservative -approach, rejecting as few requests as may be necessary to resolve the -existing deadlocks. In particular, for each unique cycle found in the -waits-for graph described in the previous paragraph, only one lock -request is selected for rejection. However, if there are multiple -cycles, one lock request from each cycle is selected for rejection. -Only after the enclosing transactions have received the lock request -rejection return and aborted their transactions can it be determined -whether it is necessary to reject additional lock requests in order to -allow forward progress. -<p>The <a href="../../utility/db_deadlock.html">db_deadlock</a> utility performs deadlock detection by calling -the underlying Berkeley DB <a href="../../api_c/lock_detect.html">DB_ENV->lock_detect</a> method at regular intervals -(<a href="../../api_c/lock_detect.html">DB_ENV->lock_detect</a> runs a single iteration of the Berkeley DB deadlock -detector). Alternatively, applications can create their own deadlock -utility or thread by calling the <a href="../../api_c/lock_detect.html">DB_ENV->lock_detect</a> method directly, or by -using the <a href="../../api_c/env_set_lk_detect.html">DB_ENV->set_lk_detect</a> method to configure Berkeley DB to -automatically run the deadlock detector whenever there is a conflict -over a lock. The tradeoffs between using the <a href="../../api_c/lock_detect.html">DB_ENV->lock_detect</a> and -<a href="../../api_c/env_set_lk_detect.html">DB_ENV->set_lk_detect</a> methods is that automatic deadlock detection will -resolve deadlocks more quickly (because as the deadlock detector runs -as soon as the lock request blocks), however, automatic deadlock -detection often runs the deadlock detector when there is no need for -it, and for applications with large numbers of locks and/or where many -operations block temporarily on locks but are soon able to proceed, -automatic detection can decrease performance. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/lock/stdmode.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/lock/timeout.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/libdb/docs/ref/lock/deaddbg.html b/libdb/docs/ref/lock/deaddbg.html deleted file mode 100644 index a07409ad9..000000000 --- a/libdb/docs/ref/lock/deaddbg.html +++ /dev/null @@ -1,141 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Deadlock debugging</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Locking Subsystem</dl></h3></td> -<td align=right><a href="../../ref/lock/timeout.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/lock/page.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Deadlock debugging</h1> -<p>An occasional debugging problem in Berkeley DB applications is unresolvable -deadlock. The output of the <b>-Co</b> flags of the <a href="../../utility/db_stat.html">db_stat</a> -utility can be used to detect and debug these problems. The following -is a typical example of the output of this utility: -<p><blockquote><pre>Locks grouped by object -Locker Mode Count Status ----------- Object ---------- - 1 READ 1 HELD a.db handle 0 -80000004 WRITE 1 HELD a.db page 3</pre></blockquote> -<p>In this example, we have opened a database and stored a single key/data -pair in it. Because we have a database handle open, we have a read lock -on that database handle. The database handle lock is the read lock -labelled <i>handle</i>. (We can normally ignore handle locks for -the purposes of database debugging, as they will only conflict with -other handle operations, for example, an attempt to remove the database -will block because we are holding the handle locked, but reading and -writing the database will not conflict with the handle lock.) -<p>It is important to note that locker IDs are 32-bit unsigned integers, -and are divided into two name spaces. Locker IDs with the high bit set -(that is, values 80000000 or higher), are locker IDs associated with -transactions. Locker IDs without the high bit set are locker IDs that -are not associated with a transaction. Locker IDs associated with -transactions map one-to-one with the transaction, that is, a transaction -never has more than a single locker ID, and all of the locks acquired -by the transaction will be acquired on behalf of the same locker ID. -<p>We also hold a write lock on the database page where we stored the new -key/data pair. The page lock is labeled <i>page</i> and is on page -number 3. If we were to put an additional key/data pair in the -database, we would see the following output: -<p><blockquote><pre>Locks grouped by object -Locker Mode Count Status ----------- Object ---------- -80000004 WRITE 2 HELD a.db page 3 - 1 READ 1 HELD a.db handle 0</pre></blockquote> -<p>That is, we have acquired a second reference count to page number 3, but -have not acquired any new locks. If we add an entry to a different page -in the database, we would acquire additional locks: -<p><blockquote><pre>Locks grouped by object -Locker Mode Count Status ----------- Object ---------- - 1 READ 1 HELD a.db handle 0 -80000004 WRITE 2 HELD a.db page 3 -80000004 WRITE 1 HELD a.db page 2</pre></blockquote> -<p>Here's a simple example of one lock blocking another one: -<p><blockquote><pre>Locks grouped by object -Locker Mode Count Status ----------- Object ---------- -80000004 WRITE 1 HELD a.db page 2 -80000005 WRITE 1 WAIT a.db page 2 - 1 READ 1 HELD a.db handle 0 -80000004 READ 1 HELD a.db page 1</pre></blockquote> -<p>In this example, there are two different transactional lockers (80000004 and -80000005). Locker 80000004 is holding a write lock on page 2, and -locker 80000005 is waiting for a write lock on page 2. This is not a -deadlock, because locker 80000004 is not blocked on anything. -Presumably, the thread of control using locker 80000004 will proceed, -eventually release its write lock on page 2, at which point the thread -of control using locker 80000005 can also proceed, acquiring a write -lock on page 2. -<p>If lockers 80000004 and 80000005 are not in different threads of -control, the result would be <i>self deadlock</i>. Self deadlock -is not a true deadlock, and won't be detected by the Berkeley DB deadlock -detector. It's not a true deadlock because, if work could continue to -be done on behalf of locker 80000004, then the lock would eventually be -released, and locker 80000005 could acquire the lock and itself proceed. -So, the key element is that the thread of control holding the lock -cannot proceed because it the same thread as is blocked waiting on the -lock. -<p>Here's an example of three transactions reaching true deadlock. First, -three different threads of control opened the database, acquiring three -database handle read locks. -<p><blockquote><pre>Locks grouped by object -Locker Mode Count Status ----------- Object ---------- - 1 READ 1 HELD a.db handle 0 - 3 READ 1 HELD a.db handle 0 - 5 READ 1 HELD a.db handle 0</pre></blockquote> -<p>The three threads then each began a transaction, and put a key/data pair -on a different page: -<p><blockquote><pre>Locks grouped by object -Locker Mode Count Status ----------- Object ---------- -80000008 WRITE 1 HELD a.db page 4 - 1 READ 1 HELD a.db handle 0 - 3 READ 1 HELD a.db handle 0 - 5 READ 1 HELD a.db handle 0 -80000006 READ 1 HELD a.db page 1 -80000007 READ 1 HELD a.db page 1 -80000008 READ 1 HELD a.db page 1 -80000006 WRITE 1 HELD a.db page 2 -80000007 WRITE 1 HELD a.db page 3</pre></blockquote> -<p>The thread using locker 80000006 put a new key/data pair on page 2, the -thread using locker 80000007, on page 3, and the thread using locker -80000008 on page 4. Because the database is a 2-level Btree, the tree -was searched, and so each transaction acquired a read lock on the Btree -root page (page 1) as part of this operation. -<p>The three threads then each attempted to put a second key/data pair on -a page currently locked by another thread. The thread using locker -80000006 tried to put a key/data pair on page 3, the thread using locker -80000007 on page 4, and the thread using locker 80000008 on page 2: -<p><blockquote><pre>Locks grouped by object -Locker Mode Count Status ----------- Object ---------- -80000008 WRITE 1 HELD a.db page 4 -80000007 WRITE 1 WAIT a.db page 4 - 1 READ 1 HELD a.db handle 0 - 3 READ 1 HELD a.db handle 0 - 5 READ 1 HELD a.db handle 0 -80000006 READ 2 HELD a.db page 1 -80000007 READ 2 HELD a.db page 1 -80000008 READ 2 HELD a.db page 1 -80000006 WRITE 1 HELD a.db page 2 -80000008 WRITE 1 WAIT a.db page 2 -80000007 WRITE 1 HELD a.db page 3 -80000006 WRITE 1 WAIT a.db page 3</pre></blockquote> -<p>Now, each of the threads of control are blocked, waiting on a different -thread of control. -The thread using locker 80000007 is blocked by -the thread using locker 80000008, due to the lock on page 4. -The thread using locker 80000008 is blocked by -the thread using locker 80000006, due to the lock on page 2. -And the thread using locker 80000006 is blocked by -the thread using locker 80000007, due to the lock on page 3. -Since none of the threads of control can make -progress, one of them will have to be killed in order to resolve the -deadlock. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/lock/timeout.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/lock/page.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/libdb/docs/ref/lock/intro.html b/libdb/docs/ref/lock/intro.html deleted file mode 100644 index df90ae973..000000000 --- a/libdb/docs/ref/lock/intro.html +++ /dev/null @@ -1,107 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Berkeley DB and locking</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Locking Subsystem</dl></h3></td> -<td align=right><a href="../../ref/program/faq.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/lock/config.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Berkeley DB and locking</h1> -<p>The locking subsystem provides interprocess and intraprocess concurrency -control mechanisms. Although the lock system is used extensively by -the Berkeley DB access methods and transaction system, it may also be used as -a standalone subsystem to provide concurrency control to any set of -designated resources. -<p>The Lock subsystem is created, initialized, and opened by calls to -<a href="../../api_c/env_open.html">DB_ENV->open</a> with the <a href="../../api_c/env_open.html#DB_INIT_LOCK">DB_INIT_LOCK</a> or <a href="../../api_c/env_open.html#DB_INIT_CDB">DB_INIT_CDB</a> -flags specified. -<p>The <a href="../../api_c/lock_vec.html">DB_ENV->lock_vec</a> interface is used to acquire and release locks. -The <a href="../../api_c/lock_vec.html">DB_ENV->lock_vec</a> function performs any number of lock operations -atomically. It also provides the capability to release all locks held -by a particular locker and release all the locks on a particular object. -(Performing multiple lock operations atomically is useful in performing -Btree traversals -- you want to acquire a lock on a child page and once -acquired, immediately release the lock on its parent. This is -traditionally referred to as <i>lock-coupling</i>). Two additional -interfaces, <a href="../../api_c/lock_get.html">DB_ENV->lock_get</a> and <a href="../../api_c/lock_put.html">DB_ENV->lock_put</a>, are provided. These -interfaces are simpler front-ends to the <a href="../../api_c/lock_vec.html">DB_ENV->lock_vec</a> functionality, -where <a href="../../api_c/lock_get.html">DB_ENV->lock_get</a> acquires a lock, and <a href="../../api_c/lock_put.html">DB_ENV->lock_put</a> releases -a lock that was acquired using <a href="../../api_c/lock_get.html">DB_ENV->lock_get</a> or <a href="../../api_c/lock_vec.html">DB_ENV->lock_vec</a>. -All locks explicitly requested by an application should be released via -calls to <a href="../../api_c/lock_put.html">DB_ENV->lock_put</a> or <a href="../../api_c/lock_vec.html">DB_ENV->lock_vec</a>. Using <a href="../../api_c/lock_vec.html">DB_ENV->lock_vec</a> -instead of separate calls to <a href="../../api_c/lock_put.html">DB_ENV->lock_put</a> and <a href="../../api_c/lock_get.html">DB_ENV->lock_get</a> also -reduces the synchronization overhead between multiple threads or -processes. The three interfaces are fully compatible, and may be used -interchangeably. -<p>Applications must specify lockers and lock objects appropriately. When -used with the Berkeley DB access methods, lockers and objects are handled -completely internally, but an application using the lock manager -directly must either use the same conventions as the access methods or -define its own convention to which it adheres. If an application is -using the access methods with locking at the same time that it is -calling the lock manager directly, the application must follow a -convention that is compatible with the access methods' use of the -locking subsystem. See <a href="../../ref/lock/am_conv.html">Access -method locking conventions</a> for more information. -<p>The <a href="../../api_c/lock_id.html">DB_ENV->lock_id</a> function returns a unique ID that may safely be used -as the locker parameter to the <a href="../../api_c/lock_vec.html">DB_ENV->lock_vec</a> interface. The access -methods use <a href="../../api_c/lock_id.html">DB_ENV->lock_id</a> to generate unique lockers for the cursors -associated with a database. -<p>The <a href="../../api_c/lock_detect.html">DB_ENV->lock_detect</a> function provides the programmatic interface to -the Berkeley DB deadlock detector. Whenever two threads of control issue lock -requests concurrently, the possibility for deadlock arises. A deadlock -occurs when two or more threads of control are blocked, waiting for -actions that another one of the blocked threads must take. For example, -assume that threads A and B have each obtained read locks on object X. -Now suppose that both threads want to obtain write locks on object X. -Neither thread can be granted its write lock (because of the other -thread's read lock). Both threads block and will never unblock because -the event for which they are waiting can never happen. -<p>The deadlock detector examines all the locks held in the environment, -and identifies situations where no thread can make forward progress. -It then selects one of the participants in the deadlock (according to -the argument that was specified to <a href="../../api_c/env_set_lk_detect.html">DB_ENV->set_lk_detect</a>), and -forces it to return the value <a href="../../ref/program/errorret.html#DB_LOCK_DEADLOCK">DB_LOCK_DEADLOCK</a>, which indicates -that a deadlock occurred. The thread receiving such an error must -release all of its locks and undo any incomplete modifications to the -locked resource. Locks are typically released, and modifications -undone, by closing any cursors involved in the operation and aborting -any transaction enclosing the operation. The operation may optionally -be retried. -<p>The <a href="../../api_c/lock_stat.html">DB_ENV->lock_stat</a> function returns information about the status of -the lock subsystem. It is the programmatic interface used by the -<a href="../../utility/db_stat.html">db_stat</a> utility. -<p>The locking subsystem is closed by the call to <a href="../../api_c/env_close.html">DB_ENV->close</a>. -<p>Finally, the entire locking subsystem may be discarded using the -<a href="../../api_c/env_remove.html">DB_ENV->remove</a> interface. -<!--$Id$--> -<p><table border=1 align=center> -<tr><th>Locking Subsystem and Related Methods</th><th>Description</th></tr> -<tr><td><a href="../../api_c/env_set_lk_conflicts.html">DB_ENV->set_lk_conflicts</a></td><td>Set lock conflicts matrix</td></tr> -<tr><td><a href="../../api_c/env_set_lk_detect.html">DB_ENV->set_lk_detect</a></td><td>Set automatic deadlock detection</td></tr> -<tr><td><a href="../../api_c/env_set_lk_max_lockers.html">DB_ENV->set_lk_max_lockers</a></td><td>Set maximum number of lockers</td></tr> -<tr><td><a href="../../api_c/env_set_lk_max_locks.html">DB_ENV->set_lk_max_locks</a></td><td>Set maximum number of locks</td></tr> -<tr><td><a href="../../api_c/env_set_lk_max_objects.html">DB_ENV->set_lk_max_objects</a></td><td>Set maximum number of lock objects</td></tr> -<tr><td><a href="../../api_c/env_set_timeout.html">DB_ENV->set_timeout</a></td><td>Set lock and transaction timeout</td></tr> -<tr><td><a href="../../api_c/lock_detect.html">DB_ENV->lock_detect</a></td><td>Perform deadlock detection</td></tr> -<tr><td><a href="../../api_c/lock_get.html">DB_ENV->lock_get</a></td><td>Acquire a lock</td></tr> -<tr><td><a href="../../api_c/lock_id.html">DB_ENV->lock_id</a></td><td>Acquire a locker ID</td></tr> -<tr><td><a href="../../api_c/lock_id_free.html">DB_ENV->lock_id_free</a></td><td>Release a locker ID</td></tr> -<tr><td><a href="../../api_c/lock_put.html">DB_ENV->lock_put</a></td><td>Release a lock</td></tr> -<tr><td><a href="../../api_c/lock_stat.html">DB_ENV->lock_stat</a></td><td>Return lock subsystem statistics</td></tr> -<tr><td><a href="../../api_c/lock_vec.html">DB_ENV->lock_vec</a></td><td>Acquire/release locks</td></tr> -</table> -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/program/faq.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/lock/config.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/libdb/docs/ref/lock/max.html b/libdb/docs/ref/lock/max.html deleted file mode 100644 index 2fa82bf4e..000000000 --- a/libdb/docs/ref/lock/max.html +++ /dev/null @@ -1,88 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Configuring locking: sizing the system</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Locking Subsystem</dl></h3></td> -<td align=right><a href="../../ref/lock/config.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/lock/stdmode.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Configuring locking: sizing the system</h1> -<p>The lock system is sized using the following three functions: -<p><blockquote><pre><a href="../../api_c/env_set_lk_max_locks.html">DB_ENV->set_lk_max_locks</a> -<a href="../../api_c/env_set_lk_max_lockers.html">DB_ENV->set_lk_max_lockers</a> -<a href="../../api_c/env_set_lk_max_objects.html">DB_ENV->set_lk_max_objects</a></pre></blockquote> -<p>The <a href="../../api_c/env_set_lk_max_locks.html">DB_ENV->set_lk_max_locks</a>, <a href="../../api_c/env_set_lk_max_lockers.html">DB_ENV->set_lk_max_lockers</a>, -and <a href="../../api_c/env_set_lk_max_objects.html">DB_ENV->set_lk_max_objects</a> methods specify the maximum number of -locks, lockers, and locked objects supported by the lock subsystem, -respectively. The maximum number of locks is the number of locks that -can be simultaneously requested in the system. The maximum number of -lockers is the number of lockers that can simultaneously request locks -in the system. The maximum number of lock objects is the number of -objects that can simultaneously be locked in the system. Selecting -appropriate values requires an understanding of your application and -its databases. If the values are too small, requests for locks in an -application will fail. If the values are too large, the locking -subsystem will consume more resources than is necessary. It is better -to err in the direction of allocating too many locks, lockers, and -objects because increasing the number of locks does not require large -amounts of additional resources. -<p>The recommended algorithm for selecting the maximum number of locks, -lockers, and lock objects is to run the application under stressful -conditions and then review the lock system's statistics to determine -the maximum number of locks, lockers, and lock objects that were used. -Then, double these values for safety. However, in some large -applications, finer granularity of control is necessary in order to -minimize the size of the Lock subsystem. -<p>The maximum number of lockers can be estimated as follows: -<p><ul type=disc> -<li>If the database environment is configured to use transactions, the -maximum number of lockers needed is the number of simultaneously active -transactions and child transactions (where a child transaction is active -until its parent commits or aborts, not until it commits or aborts). -<li>If the database environment is not configured to use transactions, the -maximum number of lockers needed is the number of simultaneous -non-cursor operations plus an additional locker for every simultaneously -open cursor. -</ul> -<p>The maximum number of lock objects needed can be estimated as follows: -<p><ul type=disc> -<li>For Btree and Recno access methods, you will need one lock object per -level of the database tree, at a minimum. (Unless keys are quite large -with respect to the page size, neither Recno nor Btree database trees -should ever be deeper than five levels.) Then, you will need one lock -object for each leaf page of the database tree that will be -simultaneously accessed. -<li>For the Queue access method, you will need one lock object per record -that is simultaneously accessed. To this, add one lock object per page -that will be simultaneously accessed. (Because the Queue access method -uses fixed-length records and the database page size is known, it is -possible to calculate the number of pages -- and, therefore, the lock -objects -- required.) Deleted records skipped by a <a href="../../api_c/dbc_get.html#DB_NEXT">DB_NEXT</a> or -<a href="../../api_c/dbc_get.html#DB_PREV">DB_PREV</a> operation do not require a separate lock object. -Further, if your application is using transactions, no database -operation will ever use more than three lock objects at any time. -<li>For the Hash access method, you only need a single lock object. -</ul> -<p>For all access methods, you should then add an additional lock object -per database for the database's metadata page. -<p>The maximum number of locks required by an application cannot be easily -estimated. It is possible to calculate a maximum number of locks by -multiplying the maximum number of lockers, times the maximum number of -lock objects, times two (two for the two possible lock modes for each -object, read and write). However, this is a pessimal value, and real -applications are unlikely to actually need that many locks. Reviewing -the Lock subsystem statistics is the best way to determine this value. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/lock/config.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/lock/stdmode.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/libdb/docs/ref/lock/nondb.html b/libdb/docs/ref/lock/nondb.html deleted file mode 100644 index c10304a2b..000000000 --- a/libdb/docs/ref/lock/nondb.html +++ /dev/null @@ -1,51 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Locking and non-Berkeley DB applications</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Locking Subsystem</dl></h3></td> -<td align=right><a href="../../ref/lock/am_conv.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/log/intro.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Locking and non-Berkeley DB applications</h1> -<p>The Lock subsystem is useful outside the context of Berkeley DB. It can be -used to manage concurrent access to any collection of either ephemeral -or persistent objects. That is, the lock region can persist across -invocations of an application, so it can be used to provide long-term -locking (for example, conference room scheduling). -<p>In order to use the locking subsystem in such a general way, the -applications must adhere to a convention for identifying objects and -lockers. Consider a conference room scheduling problem, in which there -are three conference rooms scheduled in half-hour intervals. The -scheduling application must then select a way to identify each -conference room/time slot combination. In this case, we could describe -the objects being locked as bytestrings consisting of the conference -room name, the date when it is needed, and the beginning of the -appropriate half-hour slot. -<p>Lockers are 32-bit numbers, so we might choose to use the User ID of -the individual running the scheduling program. To schedule half-hour -slots, all the application needs to do is issue a <a href="../../api_c/lock_get.html">DB_ENV->lock_get</a> call -for the appropriate locker/object pair. To schedule a longer slot, the -application needs to issue a <a href="../../api_c/lock_vec.html">DB_ENV->lock_vec</a> call, with one -<a href="../../api_c/lock_get.html">DB_ENV->lock_get</a> operation per half-hour -- up to the total length. If -the <a href="../../api_c/lock_vec.html">DB_ENV->lock_vec</a> call fails, the application would have to release -the parts of the time slot that were obtained. -<p>To cancel a reservation, the application would make the appropriate -<a href="../../api_c/lock_put.html">DB_ENV->lock_put</a> calls. To reschedule a reservation, the -<a href="../../api_c/lock_get.html">DB_ENV->lock_get</a> and <a href="../../api_c/lock_put.html">DB_ENV->lock_put</a> calls could all be made inside of -a single <a href="../../api_c/lock_vec.html">DB_ENV->lock_vec</a> call. The output of <a href="../../api_c/lock_stat.html">DB_ENV->lock_stat</a> could -be post-processed into a human-readable schedule of conference room -use. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/lock/am_conv.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/log/intro.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/libdb/docs/ref/lock/notxn.html b/libdb/docs/ref/lock/notxn.html deleted file mode 100644 index 3428e555f..000000000 --- a/libdb/docs/ref/lock/notxn.html +++ /dev/null @@ -1,47 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Locking without transactions</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Locking Subsystem</dl></h3></td> -<td align=right><a href="../../ref/lock/page.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/lock/twopl.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Locking without transactions</h1> -<p>If an application runs with locking specified, but not transactions (for -example, <a href="../../api_c/env_open.html">DB_ENV->open</a> is called with <a href="../../api_c/env_open.html#DB_INIT_LOCK">DB_INIT_LOCK</a> or -<a href="../../api_c/env_open.html#DB_INIT_CDB">DB_INIT_CDB</a> specified, but not <a href="../../api_c/env_open.html#DB_INIT_TXN">DB_INIT_TXN</a>), locks are -normally acquired during each Berkeley DB operation and released before the -operation returns to the caller. The only exception is in the case of -cursor operations. Cursors identify a particular position in a file. -For this reason, cursors must retain read locks across cursor calls to -make sure that the position is uniquely identifiable during a subsequent -cursor call, and so that an operation using <a href="../../api_c/dbc_get.html#DB_CURRENT">DB_CURRENT</a> will -always refer to the same record as a previous cursor call. These cursor -locks cannot be released until the cursor is either repositioned and a -new cursor lock established (for example, using the <a href="../../api_c/dbc_get.html#DB_NEXT">DB_NEXT</a> -or <a href="../../api_c/dbc_get.html#DB_SET">DB_SET</a> flags), or the cursor is closed. As a result, -application writers are encouraged to close cursors as soon as -possible. -<p>It is important to realize that concurrent applications that use locking -must ensure that two concurrent threads do not block each other. -However, because Btree and Hash access method page splits can occur at -any time, there is virtually no way to guarantee that an application -that writes the database cannot deadlock. Applications running without -the protection of transactions may deadlock, and can leave the database -in an inconsistent state when they do so. Applications that need -concurrent access, but not transactions, are more safely implemented -using the Berkeley DB Concurrent Data Store Product. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/lock/page.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/lock/twopl.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/libdb/docs/ref/lock/page.html b/libdb/docs/ref/lock/page.html deleted file mode 100644 index 2cccde6b3..000000000 --- a/libdb/docs/ref/lock/page.html +++ /dev/null @@ -1,72 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Locking granularity</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Locking Subsystem</dl></h3></td> -<td align=right><a href="../../ref/lock/deaddbg.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/lock/notxn.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Locking granularity</h1> -<p>With the exception of the Queue access method, the Berkeley DB access methods -do page-level locking. The size of pages in a database may be set when -the database is created by calling the <a href="../../api_c/db_set_pagesize.html">DB->set_pagesize</a> method. If -not specified by the application, Berkeley DB selects a page size that will -provide the best I/O performance by setting the page size equal to the -block size of the underlying file system. Selecting a smaller page size -can result in increased concurrency for some applications. -<p>In the Btree access method, Berkeley DB uses a technique called lock coupling -to improve concurrency. The traversal of a Btree requires reading a -page, searching that page to determine which page to search next, and -then repeating this process on the next page. Once a page has been -searched, it will never be accessed again for this operation, unless a -page split is required. To improve concurrency in the tree, once the -next page to read/search has been determined, that page is locked and -then the original page lock is released atomically (that is, without -relinquishing control of the lock manager). When page splits become -necessary, write locks are reacquired. -<p>Because the Recno access method is built upon Btree, it also uses lock -coupling for read operations. However, because the Recno access method -must maintain a count of records on its internal pages, it cannot -lock-couple during write operations. Instead, it retains write locks -on all internal pages during every update operation. For this reason, -it is not possible to have high concurrency in the Recno access method -in the presence of write operations. -<p>The Queue access method uses only short-term page locks. That is, a page -lock is released prior to requesting another page lock. Record locks are -used for transaction isolation. The provides a high degree of concurrency -for write operations. A metadata page is used to keep track of the head -and tail of the queue. This page is never locked during other locking or -I/O operations. -<p>The Hash access method does not have such traversal issues, but it must -always refer to its metadata while computing a hash function because it -implements dynamic hashing. This metadata is stored on a special page -in the hash database. This page must therefore be read-locked on every -operation. Fortunately, it needs to be write-locked only when new pages -are allocated to the file, which happens in three cases: -<p><ul type=disc> -<li>a hash bucket becomes full and needs to split -<li>a key or data item is too large to fit on a normal page -<li>the number of duplicate items for a fixed key becomes so large that they -are moved to an auxiliary page -</ul> -<p>In this case, the access method must obtain a write lock on the metadata -page, thus requiring that all readers be blocked from entering the tree -until the update completes. -<p>Finally, when traversing duplicate data items for a key, the lock on -the key value also acts as a lock on all duplicates of that key. -Therefore, two conflicting threads of control cannot access the same -duplicate set simultaneously. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/lock/deaddbg.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/lock/notxn.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/libdb/docs/ref/lock/stdmode.html b/libdb/docs/ref/lock/stdmode.html deleted file mode 100644 index 812dff3fa..000000000 --- a/libdb/docs/ref/lock/stdmode.html +++ /dev/null @@ -1,59 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Standard lock modes</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Locking Subsystem</dl></h3></td> -<td align=right><a href="../../ref/lock/max.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/lock/dead.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Standard lock modes</h1> -<p>The Berkeley DB locking protocol is described by a conflict matrix. A -conflict matrix is an NxN array in which N is the number of different -lock modes supported, and the (i, j)th entry of the array indicates -whether a lock of mode i conflicts with a lock of mode j. In addition, -Berkeley DB defines the type <b>db_lockmode_t</b>, which is the type of a -lock mode within a conflict matrix. -<p>The following is an example of a conflict matrix. The actual conflict -matrix used by Berkeley DB to support the underlying access methods is more -complicated, but this matrix shows the lock mode relationships available -to applications using the Berkeley DB Locking subsystem interfaces directly. -<p><dl compact> -<p><dt>DB_LOCK_NG<dd>not granted (always 0) -<dt>DB_LOCK_READ<dd>read (shared) -<dt>DB_LOCK_WRITE<dd>write (exclusive) -<dt>DB_LOCK_IWRITE<dd>intention to write (shared) -<dt>DB_LOCK_IREAD<dd>intention to read (shared) -<dt>DB_LOCK_IWR<dd>intention to read and write (shared) -</dl> -<p>In a conflict matrix, the rows indicate the lock that is held, and the -columns indicate the lock that is requested. A 1 represents a conflict -(that is, do not grant the lock if the indicated lock is held), and a -0 indicates that it is OK to grant the lock. -<p><blockquote><pre> Notheld Read Write IWrite IRead IRW -Notheld 0 0 0 0 0 0 -Read* 0 0 1 1 0 1 -Write** 0 1 1 1 1 1 -Intent Write 0 1 1 0 0 0 -Intent Read 0 0 1 0 0 0 -Intent RW 0 1 1 0 0 0</pre></blockquote> -<p><dl compact> -<p><dt>*<dd>In this case, suppose that there is a read lock held on an object. A new -request for a read lock would be granted, but a request for a write lock -would not. -<p><dt>**<dd>In this case, suppose that there is a write lock held on an object. A -new request for either a read or write lock would be denied. -</dl> -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/lock/max.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/lock/dead.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/libdb/docs/ref/lock/timeout.html b/libdb/docs/ref/lock/timeout.html deleted file mode 100644 index c4232e492..000000000 --- a/libdb/docs/ref/lock/timeout.html +++ /dev/null @@ -1,59 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Deadlock detection using timers</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Locking Subsystem</dl></h3></td> -<td align=right><a href="../../ref/lock/dead.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/lock/deaddbg.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Deadlock detection using timers</h1> -<p>Lock and transaction timeouts may be used in place of, or in addition -to, regular deadlock detection. If lock timeouts are set, lock requests -will return <a href="../../ref/program/errorret.html#DB_LOCK_DEADLOCK">DB_LOCK_DEADLOCK</a> from a lock call when it is -detected that the locks timeouts has expired, that is, the lock request -has blocked, waiting, longer than the specified timeout. If transaction -timeouts are set, lock requests will return <a href="../../ref/program/errorret.html#DB_LOCK_DEADLOCK">DB_LOCK_DEADLOCK</a> -from a lock call when it has been detected that the transaction has been -active longer than the specified timeout. -<p>As lock and transaction timeouts are only checked when lock requests -first block or when deadlock detection is performed, the accuracy of -the timeout depends on how often deadlock detection is performed. More -specifically, transactions will continue to run after their timeout has -expired if they do not block on a lock request after that time. -<p>If the database environment deadlock detector has been configured with -the <a href="../../api_c/env_set_lk_detect.html#DB_LOCK_EXPIRE">DB_LOCK_EXPIRE</a> option, timeouts are the only mechanism by -which deadlocks will be broken. If the deadlock detector has been -configured with a different option, then regular deadlock detection will -be performed, and in addition, if timeouts have also been specified, -lock requests and transactions will time out as well. -<p>Lock and transaction timeouts may be specified on a database environment -wide basis using the <a href="../../api_c/env_set_timeout.html">DB_ENV->set_timeout</a> method. Lock timeouts may be -specified on a per-lock request basis using the <a href="../../api_c/lock_vec.html">DB_ENV->lock_vec</a> method. -Transaction timeouts may be specified on a per-transaction basis using -the <a href="../../api_c/txn_set_timeout.html">DB_TXN->set_timeout</a> method. Per-lock and per-transaction timeouts -supersede environment wide timeouts. -<p>For example, consider that the environment wide transaction timeout has -been set to 20ms, the environment wide lock timeout has been set to -10ms, a transaction has been created in this environment and its timeout -value set to 8ms, and a specific lock request has been made on behalf -of this transaction where the lock timeout was set to 4ms. By default, -transactions in this environment will be timed out if they block waiting -for a lock after 20ms. The specific transaction described will be timed -out if it blocks waiting for a lock after 8ms. By default, any lock -request in this system will be timed out if it blocks longer than 10ms, -and the specific lock described will be timed out if it blocks longer -than 4ms. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/lock/dead.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/lock/deaddbg.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/libdb/docs/ref/lock/twopl.html b/libdb/docs/ref/lock/twopl.html deleted file mode 100644 index 3cd027de0..000000000 --- a/libdb/docs/ref/lock/twopl.html +++ /dev/null @@ -1,51 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Locking with transactions: two-phase locking</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Locking Subsystem</dl></h3></td> -<td align=right><a href="../../ref/lock/notxn.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/lock/cam_conv.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Locking with transactions: two-phase locking</h1> -<p>Berkeley DB uses a locking protocol called <i>two-phase locking (2PL)</i>. This -is the traditional protocol used in conjunction with lock-based transaction -systems. -<p>In a two-phase locking system, transactions are divided into two -distinct phases. During the first phase, the transaction only acquires -locks; during the second phase, the transaction only releases locks. -More formally, once a transaction releases a lock, it may not acquire -any additional locks. Practically, this translates into a system in -which locks are acquired as they are needed throughout a transaction -and retained until the transaction ends, either by committing or -aborting. In Berkeley DB, locks are released during <a href="../../api_c/txn_abort.html">DB_TXN->abort</a> or -<a href="../../api_c/txn_commit.html">DB_TXN->commit</a>. The only exception to this protocol occurs when we -use lock-coupling to traverse a data structure. If the locks are held -only for traversal purposes, it is safe to release locks before -transactions commit or abort. -<p>For applications, the implications of 2PL are that long-running -transactions will hold locks for a long time. When designing -applications, lock contention should be considered. In order to reduce -the probability of deadlock and achieve the best level of concurrency -possible, the following guidelines are helpful. -<p><ol> -<p><li>When accessing multiple databases, design all transactions so that they -access the files in the same order. -<p><li>If possible, access your most hotly contested resources last (so that -their locks are held for the shortest time possible). -<p><li>If possible, use nested transactions to protect the parts of your -transaction most likely to deadlock. -</ol> -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/lock/notxn.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/lock/cam_conv.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/libdb/docs/ref/log/config.html b/libdb/docs/ref/log/config.html deleted file mode 100644 index b7a35a15b..000000000 --- a/libdb/docs/ref/log/config.html +++ /dev/null @@ -1,47 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Configuring logging</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Logging Subsystem</dl></h3></td> -<td align=right><a href="../../ref/log/intro.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/log/limits.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Configuring logging</h1> -<p>The aspects of logging that may be configured are the size of the -logging subsystem's region, the size of the log files on disk and the -size of the log buffer in memory. The <a href="../../api_c/env_set_lg_regionmax.html">DB_ENV->set_lg_regionmax</a> -interface specifies the size of the logging subsystem's region, in -bytes. The logging subsystem's default size is 60KB. This value may -need to be increased if a large number of files are registered with the -Berkeley DB log manager, for example, by opening a large number of Berkeley DB -database files in a transactional application. -<p>The <a href="../../api_c/env_set_lg_max.html">DB_ENV->set_lg_max</a> interface specifies the individual log file -size for all the applications sharing the Berkeley DB environment. Setting -the log file size is largely a matter of convenience and a reflection -of the application's preferences in backup media and frequency. -However, setting the log file size too low can potentially cause -problems because it would be possible to run out of log sequence -numbers, which requires a full archival and application restart to -reset. See <a href="../../ref/log/limits.html">Log file limits</a> for more -information. -<p>The <a href="../../api_c/env_set_lg_bsize.html">DB_ENV->set_lg_bsize</a> interface specifies the size of the -in-memory log buffer, in bytes. Log information is stored in memory -until the buffer fills up or transaction commit forces the buffer to be -written to disk. Larger buffer sizes can significantly increase -throughput in the presence of long-running transactions, highly -concurrent applications, or transactions producing large amounts of -data. By default, the buffer is 32KB. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/log/intro.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/log/limits.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/libdb/docs/ref/log/intro.html b/libdb/docs/ref/log/intro.html deleted file mode 100644 index 9e4bb6c9e..000000000 --- a/libdb/docs/ref/log/intro.html +++ /dev/null @@ -1,70 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Berkeley DB and logging</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Logging Subsystem</dl></h3></td> -<td align=right><a href="../../ref/lock/nondb.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/log/config.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Berkeley DB and logging</h1> -<p>The Logging subsystem is the logging facility used by Berkeley DB. It is -largely Berkeley DB-specific, although it is potentially useful outside of -the Berkeley DB package for applications wanting write-ahead logging support. -Applications wanting to use the log for purposes other than logging file -modifications based on a set of open file descriptors will almost -certainly need to make source code modifications to the Berkeley DB code -base. -<p>A log can be shared by any number of threads of control. The -<a href="../../api_c/env_open.html">DB_ENV->open</a> interface is used to open a log. When the log is no -longer in use, it should be closed using the <a href="../../api_c/env_close.html">DB_ENV->close</a> -interface. -<p>Individual log entries are identified by log sequence numbers. Log -sequence numbers are stored in an opaque object, a <a href="../../api_c/lsn_class.html">DB_LSN</a>. -<p>The <a href="../../api_c/log_cursor.html">DB_ENV->log_cursor</a> method is used to allocate a log cursor. Log cursors -have two methods: <a href="../../api_c/logc_get.html">DB_LOGC->get</a> method to retrieve log records from the -log, and <a href="../../api_c/logc_close.html">DB_LOGC->close</a> method to destroy the cursor. -<p>There are additional interfaces for integrating the log subsystem with a -transaction processing system: -<p><dl compact> -<p><dt><a href="../../api_c/log_flush.html">DB_ENV->log_flush</a><dd>Flushes the log up to a particular log sequence number. -<p><dt><a href="../../api_c/log_compare.html">log_compare</a><dd>Allows applications to compare any two log sequence numbers. -<p><dt><a href="../../api_c/log_file.html">DB_ENV->log_file</a> <dd>Maps a log sequence number to the specific log file that contains it. -<p><dt><a href="../../api_c/log_archive.html">DB_ENV->log_archive</a><dd>Returns various sets of log filenames. These interfaces are used for -database administration; for example, to determine if log files may -safely be removed from the system. -<p><dt><a href="../../api_c/log_stat.html">DB_ENV->log_stat</a> <dd>The display <a href="../../utility/db_stat.html">db_stat</a> utility uses the <a href="../../api_c/log_stat.html">DB_ENV->log_stat</a> interface -to display statistics about the log. -<p><dt><a href="../../api_c/env_remove.html">DB_ENV->remove</a><dd>The log meta-information (but not the log files themselves) may be -removed using the <a href="../../api_c/env_remove.html">DB_ENV->remove</a> interface. -</dl> -<!--$Id$--> -<p><table border=1 align=center> -<tr><th>Logging Subsystem and Related Methods</th><th>Description</th></tr> -<tr><td><a href="../../api_c/log_archive.html">DB_ENV->log_archive</a></td><td>List log and database files</td></tr> -<tr><td><a href="../../api_c/log_cursor.html">DB_ENV->log_cursor</a></td><td>Create a log cursor handle</td></tr> -<tr><td><a href="../../api_c/log_file.html">DB_ENV->log_file</a></td><td>Map Log Sequence Numbers to log files</td></tr> -<tr><td><a href="../../api_c/log_flush.html">DB_ENV->log_flush</a></td><td>Flush log records</td></tr> -<tr><td><a href="../../api_c/log_put.html">DB_ENV->log_put</a></td><td>Write a log record</td></tr> -<tr><td><a href="../../api_c/env_set_lg_bsize.html">DB_ENV->set_lg_bsize</a></td><td>Set log buffer size</td></tr> -<tr><td><a href="../../api_c/env_set_lg_dir.html">DB_ENV->set_lg_dir</a></td><td>Set the environment logging directory</td></tr> -<tr><td><a href="../../api_c/env_set_lg_max.html">DB_ENV->set_lg_max</a></td><td>Set log file size</td></tr> -<tr><td><a href="../../api_c/env_set_lg_regionmax.html">DB_ENV->set_lg_regionmax</a></td><td>Set logging region size</td></tr> -<tr><td><a href="../../api_c/log_compare.html">log_compare</a></td><td>Compare two Log Sequence Numbers</td></tr> -<tr><td><a href="../../api_c/log_stat.html">DB_ENV->log_stat</a></td><td>Return log subsystem statistics</td></tr> -<tr><td><a href="../../api_c/logc_close.html">DB_LOGC->close</a></td><td>Close a log cursor</td></tr> -<tr><td><a href="../../api_c/logc_get.html">DB_LOGC->get</a></td><td>Retrieve a log record</td></tr> -</table> -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/lock/nondb.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/log/config.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/libdb/docs/ref/log/limits.html b/libdb/docs/ref/log/limits.html deleted file mode 100644 index efab9ebb9..000000000 --- a/libdb/docs/ref/log/limits.html +++ /dev/null @@ -1,49 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Log file limits</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Logging Subsystem</dl></h3></td> -<td align=right><a href="../../ref/log/config.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/mp/intro.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Log file limits</h1> -<p>Log filenames and sizes impose a limit on how long databases may be -used in a Berkeley DB database environment. It is quite unlikely that an -application will reach this limit; however, if the limit is reached, -the Berkeley DB environment's databases must be dumped and reloaded. -<p>The log filename consists of <b>log.</b> followed by 10 digits, with -a maximum of 2,000,000,000 log files. Consider an application performing -6000 transactions per second for 24 hours a day, logged into 10MB log -files, in which each transaction is logging approximately 500 bytes of data. -The following calculation: -<p><blockquote><pre>(10 * 2^20 * 2000000000) / (6000 * 500 * 365 * 60 * 60 * 24) = ~221</pre></blockquote> -<p>indicates that the system will run out of log filenames in roughly 221 -years. -<p>There is no way to reset the log filename space in Berkeley DB. If your -application is reaching the end of its log filename space, you must do -the following: -<p><ol> -<p><li>Archive your databases as if to prepare for catastrophic failure (see -<a href="../../utility/db_archive.html">db_archive</a> for more information). -<p><li>Dump and reload all your databases (see <a href="../../utility/db_dump.html">db_dump</a> and -<a href="../../utility/db_load.html">db_load</a> for more information). -<p><li>Remove all of the log files from the database environment. Note: This -is the only situation in which all the log files are removed from an -environment; in all other cases, at least a single log file is -retained. -<p><li>Restart your application. -</ol> -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/log/config.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/mp/intro.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/libdb/docs/ref/mp/config.html b/libdb/docs/ref/mp/config.html deleted file mode 100644 index 696f2c5db..000000000 --- a/libdb/docs/ref/mp/config.html +++ /dev/null @@ -1,52 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Configuring the memory pool</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Memory Pool Subsystem</dl></h3></td> -<td align=right><a href="../../ref/mp/intro.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/txn/intro.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Configuring the memory pool</h1> -<p>There are two issues to consider when configuring the memory pool. -<p>The first issue, the most important tuning parameter for Berkeley DB -applications, is the size of the memory pool. There are two ways to -specify the pool size. First, calling the <a href="../../api_c/env_set_cachesize.html">DB_ENV->set_cachesize</a> method -specifies the pool size for all of the applications sharing the Berkeley DB -environment. Second, the <a href="../../api_c/db_set_cachesize.html">DB->set_cachesize</a> method only specifies a -pool size for the specific database. Note: It is meaningless to call -<a href="../../api_c/db_set_cachesize.html">DB->set_cachesize</a> for a database opened inside of a Berkeley DB -environment because the environment pool size will override any pool -size specified for a single database. For information on tuning the -Berkeley DB cache size, see <a href="../../ref/am_conf/cachesize.html">Selecting -a cache size</a>. -<p>The second memory pool configuration issue is the maximum size an -underlying file can be and still be mapped into the process address -space (instead of reading the file's pages into the cache). Mapping -files into the process address space can result in better performance -because available virtual memory is often much larger than the local -cache, and page faults are faster than page copying on many systems. -However, in the presence of limited virtual memory, it can cause -resource starvation; and in the presence of large databases, it can -result in immense process sizes. In addition, because of the -requirements of the Berkeley DB transactional implementation, only read-only -files can be mapped into process memory. -<p>To specify that no files are to be mapped into the process address space, -specify the <a href="../../api_c/env_set_flags.html#DB_NOMMAP">DB_NOMMAP</a> flag to the <a href="../../api_c/env_set_flags.html">DB_ENV->set_flags</a> interface. -To specify that any individual file should not be mapped into the process -address space, specify the <a href="../../api_c/env_set_flags.html#DB_NOMMAP">DB_NOMMAP</a> flag to the -<a href="../../api_c/memp_fopen.html">DB_MPOOLFILE->open</a> interface. To limit the size of files mapped into the -process address space, use the <a href="../../api_c/env_set_mp_mmapsize.html">DB_ENV->set_mp_mmapsize</a> method. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/mp/intro.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/txn/intro.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/libdb/docs/ref/mp/intro.html b/libdb/docs/ref/mp/intro.html deleted file mode 100644 index 298bc4d30..000000000 --- a/libdb/docs/ref/mp/intro.html +++ /dev/null @@ -1,97 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Berkeley DB and the memory pool</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Memory Pool Subsystem</dl></h3></td> -<td align=right><a href="../../ref/log/limits.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/mp/config.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Berkeley DB and the memory pool</h1> -<p>The Memory Pool subsystem is the general-purpose shared memory buffer -pool used by Berkeley DB. This module is useful outside of the Berkeley DB package -for processes that require page-oriented, shared and cached file access. -<p>A <i>memory pool</i> is a memory cache shared among any number of -threads of control. The <a href="../../api_c/env_open.html#DB_INIT_MPOOL">DB_INIT_MPOOL</a> flag to the -<a href="../../api_c/env_open.html">DB_ENV->open</a> method opens and optionally creates a memory pool. When -that pool is no longer in use, it should be closed using the -<a href="../../api_c/env_close.html">DB_ENV->close</a> method. -<p>The <a href="../../api_c/memp_fcreate.html">DB_ENV->memp_fcreate</a> method returns a <a href="../../api_c/mempfile_class.html">DB_MPOOLFILE</a> handle on an -underlying file within the memory pool. The file may be opened using -the <a href="../../api_c/memp_fopen.html">DB_MPOOLFILE->open</a> method. The <a href="../../api_c/memp_fget.html">DB_MPOOLFILE->get</a> method is used to retrieve -pages from files in the pool. All retrieved pages must be subsequently -returned using the <a href="../../api_c/memp_fput.html">DB_MPOOLFILE->put</a> method. At the time pages are returned, -they may be marked <b>dirty</b>, which causes them to be written to -the underlying file before being discarded from the pool. If there is -insufficient room to bring a new page in the pool, a page is selected -to be discarded from the pool using a least-recently-used algorithm. -Pages in files may also be explicitly marked clean or dirty using the -<a href="../../api_c/memp_fset.html">DB_MPOOLFILE->set</a> method. All dirty pages in the pool from the file may be -flushed using the <a href="../../api_c/memp_fsync.html">DB_MPOOLFILE->sync</a> method. When the file handle is no -longer in use, it should be closed using the <a href="../../api_c/memp_fclose.html">DB_MPOOLFILE->close</a> method. -<p>There are additional configuration interfaces that apply when opening -a new file in the memory pool: -<p><ul type=disc> -<li>The <a href="../../api_c/memp_set_clear_len.html">DB_MPOOLFILE->set_clear_len</a> method specifies the number of bytes to clear -when creating a new page in the memory pool. -<li>The <a href="../../api_c/memp_set_fileid.html">DB_MPOOLFILE->set_fileid</a> method specifies a unique ID associated with the file. -<li>The <a href="../../api_c/memp_set_ftype.html">DB_MPOOLFILE->set_ftype</a> method specifies the type of file for the purposes of -page input and output processing. -<li>The <a href="../../api_c/memp_set_lsn_offset.html">DB_MPOOLFILE->set_lsn_offset</a> method specifies the byte offset of each page's -log sequence number (<a href="../../api_c/lsn_class.html">DB_LSN</a>) for the purposes of transaction -checkpoints. -<li>The <a href="../../api_c/memp_set_pgcookie.html">DB_MPOOLFILE->set_pgcookie</a> method specifies an application provided argument -for the purposes of page input and output processing. -</ul> -<p>There are additional interfaces for the memory pool as a whole: -<p><ul type=disc> -<li>It is possible to gradually flush buffers from the pool in order to -maintain a consistent percentage of clean buffers in the pool using -the <a href="../../api_c/memp_trickle.html">DB_ENV->memp_trickle</a> method. -<li>Because special-purpose processing may be necessary when pages are read -or written (for example, compression or endian conversion), the -<a href="../../api_c/memp_register.html">DB_ENV->memp_register</a> function allows applications to specify automatic -input and output processing in these cases. -<li>The <a href="../../utility/db_stat.html">db_stat</a> utility uses the <a href="../../api_c/memp_stat.html">DB_ENV->memp_stat</a> method to display -statistics about the efficiency of the pool. -<li>All dirty pages in the pool may be flushed using the <a href="../../api_c/memp_sync.html">DB_ENV->memp_sync</a> method. -In addition, <a href="../../api_c/memp_sync.html">DB_ENV->memp_sync</a> takes an argument that is specific to -database systems, and which allows the memory pool to be flushed up to -a specified log sequence number (<a href="../../api_c/lsn_class.html">DB_LSN</a>). -<li>The entire pool may be discarded using the <a href="../../api_c/env_remove.html">DB_ENV->remove</a> method. -</ul> -<!--$Id$--> -<p><table border=1 align=center> -<tr><th>Memory Pools and Related Methods</th><th>Description</th></tr> -<tr><td><a href="../../api_c/env_set_cachesize.html">DB_ENV->set_cachesize</a></td><td>Set the environment cache size</td></tr> -<tr><td><a href="../../api_c/env_set_mp_mmapsize.html">DB_ENV->set_mp_mmapsize</a></td><td>Set maximum mapped-in database file size</td></tr> -<tr><td><a href="../../api_c/memp_register.html">DB_ENV->memp_register</a></td><td>Register input/output functions for a file in a memory pool</td></tr> -<tr><td><a href="../../api_c/memp_stat.html">DB_ENV->memp_stat</a></td><td>Return memory pool statistics</td></tr> -<tr><td><a href="../../api_c/memp_sync.html">DB_ENV->memp_sync</a></td><td>Flush pages from a memory pool</td></tr> -<tr><td><a href="../../api_c/memp_trickle.html">DB_ENV->memp_trickle</a></td><td>Trickle flush pages from a memory pool</td></tr> -<tr><td><a href="../../api_c/memp_fcreate.html">DB_ENV->memp_fcreate</a></td><td>Open a file in a memory pool</td></tr> -<tr><td><a href="../../api_c/memp_fclose.html">DB_MPOOLFILE->close</a></td><td>Close a file in a memory pool</td></tr> -<tr><td><a href="../../api_c/memp_fget.html">DB_MPOOLFILE->get</a></td><td>Get page from a file in a memory pool</td></tr> -<tr><td><a href="../../api_c/memp_fopen.html">DB_MPOOLFILE->open</a></td><td>Open a file in a memory pool</td></tr> -<tr><td><a href="../../api_c/memp_fput.html">DB_MPOOLFILE->put</a></td><td>Return a page to a memory pool</td></tr> -<tr><td><a href="../../api_c/memp_fset.html">DB_MPOOLFILE->set</a></td><td>Set memory pool page status</td></tr> -<tr><td><a href="../../api_c/memp_fsync.html">DB_MPOOLFILE->sync</a></td><td>Flush pages from a file in a memory pool</td></tr> -<tr><td><a href="../../api_c/memp_set_clear_len.html">DB_MPOOLFILE->set_clear_len</a></td><td>Set file page bytes to be cleared</td></tr> -<tr><td><a href="../../api_c/memp_set_fileid.html">DB_MPOOLFILE->set_fileid</a></td><td>Set file unique identifier</td></tr> -<tr><td><a href="../../api_c/memp_set_ftype.html">DB_MPOOLFILE->set_ftype</a></td><td>Set file type</td></tr> -<tr><td><a href="../../api_c/memp_set_lsn_offset.html">DB_MPOOLFILE->set_lsn_offset</a></td><td>Set file log-sequence-number offset</td></tr> -<tr><td><a href="../../api_c/memp_set_pgcookie.html">DB_MPOOLFILE->set_pgcookie</a></td><td>Set file cookie for pgin/pgout</td></tr> -</table> -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/log/limits.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/mp/config.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/libdb/docs/ref/perl/intro.html b/libdb/docs/ref/perl/intro.html deleted file mode 100644 index 72570190f..000000000 --- a/libdb/docs/ref/perl/intro.html +++ /dev/null @@ -1,43 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Using Berkeley DB with Perl</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Perl</dl></h3></td> -<td align=right><a href="../../ref/java/faq.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/tcl/intro.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Using Berkeley DB with Perl</h1> -<p>The original Perl module for Berkeley DB was DB_File, which was written to -interface to Berkeley DB version 1.85. The newer Perl module for Berkeley DB is -BerkeleyDB, which was written to interface to version 2.0 and subsequent -releases. Because Berkeley DB version 2.X has a compatibility API for version -1.85, you can (and should!) build DB_File using version 2.X of Berkeley DB, -although DB_File will still only support the 1.85 functionality. -<p>DB_File is distributed with the standard Perl source distribution (look -in the directory "ext/DB_File"). You can find both DB_File and BerkeleyDB -on CPAN, the Comprehensive Perl Archive Network of mirrored FTP sites. -The master CPAN site is -<a href="ftp://ftp.funet.fi/">ftp://ftp.funet.fi/</a>. -<p>Versions of both BerkeleyDB and DB_File that are known to work correctly -with each release of Berkeley DB are included in the distributed Berkeley DB source -tree, in the subdirectories <b>perl.BerkeleyDB</b> and -<b>perl.DB_File</b>. Each of those directories contains a -<b>README</b> file with instructions on installing and using those -modules. -<p>The Perl interface is not maintained by Sleepycat Software. Questions -about the DB_File and BerkeleyDB modules are best asked on the Usenet -newsgroup comp.lang.perl.modules. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/java/faq.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/tcl/intro.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/libdb/docs/ref/pindex.src b/libdb/docs/ref/pindex.src deleted file mode 100644 index bf0ef2219..000000000 --- a/libdb/docs/ref/pindex.src +++ /dev/null @@ -1,276 +0,0 @@ -__APIREL__/ref/am/close.html__OCT__2 @closing a database -__APIREL__/ref/am/count.html__OCT__2 @counting data items for a key -__APIREL__/ref/am/curclose.html__OCT__2 @closing a cursor -__APIREL__/ref/am/curclose.html__OCT__3 closing a @cursor -__APIREL__/ref/am/curdel.html__OCT__2 @deleting records with a cursor -__APIREL__/ref/am/curdel.html__OCT__3 deleting records with a @cursor -__APIREL__/ref/am/curdup.html__OCT__2 @duplicating a cursor -__APIREL__/ref/am/curdup.html__OCT__3 duplicating a @cursor -__APIREL__/ref/am/curget.html__OCT__2 @retrieving records with a cursor -__APIREL__/ref/am/curget.html__OCT__3 retrieving records with a @cursor -__APIREL__/ref/am/curput.html__OCT__2 @storing records with a cursor -__APIREL__/ref/am/curput.html__OCT__3 storing records with a @cursor -__APIREL__/ref/am/cursor.html__OCT__2 database @cursors -__APIREL__/ref/am/delete.html__OCT__2 @deleting records -__APIREL__/ref/am/get.html__OCT__2 @retrieving records -__APIREL__/ref/am/join.html__OCT__2 @equality join -__APIREL__/ref/am/join.html__OCT__3 equality @join -__APIREL__/ref/am/join.html__OCT__4 @natural join -__APIREL__/ref/am/open.html__OCT__2 @opening a database -__APIREL__/ref/am/put.html__OCT__2 @storing records -__APIREL__/ref/am/second.html__OCT__2 @secondary indices -__APIREL__/ref/am/second.html__OCT__3 secondary @indices -__APIREL__/ref/am/stat.html__OCT__2 database @statistics -__APIREL__/ref/am/sync.html__OCT__2 flushing the database @cache -__APIREL__/ref/am/truncate.html__OCT__2 @truncating a database -__APIREL__/ref/am/truncate.html__OCT__3 @emptying a database -__APIREL__/ref/am/upgrade.html__OCT__2 @upgrading databases -__APIREL__/ref/am/verify.html__OCT__2 database @verification -__APIREL__/ref/am/verify.html__OCT__3 database @salvage -__APIREL__/ref/am/verify.html__OCT__4 salvaging @corrupted databases -__APIREL__/ref/am_conf/bt_compare.html__OCT__2 specifying a Btree @comparison function -__APIREL__/ref/am_conf/bt_recnum.html__OCT__2 retrieving Btree records by logical record @number -__APIREL__/ref/am_conf/bt_recnum.html__OCT__3 retrieving Btree records by @logical record @number -__APIREL__/ref/am_conf/byteorder.html__OCT__2 selecting a @byte order -__APIREL__/ref/am_conf/cachesize.html__OCT__2 selecting a @cache size -__APIREL__/ref/am_conf/dup.html__OCT__2 @duplicate data items -__APIREL__/ref/am_conf/extentsize.html__OCT__2 selecting a Queue @extent size -__APIREL__/ref/am_conf/h_ffactor.html__OCT__2 page @fill factor -__APIREL__/ref/am_conf/h_hash.html__OCT__2 specifying a database @hash -__APIREL__/ref/am_conf/h_nelem.html__OCT__2 @hash table size -__APIREL__/ref/am_conf/intro.html__OCT__2 introduction to the @access methods -__APIREL__/ref/am_conf/logrec.html__OCT__2 logical @record numbers -__APIREL__/ref/am_conf/pagesize.html__OCT__2 selecting a @page size -__APIREL__/ref/am_conf/re_source.html__OCT__2 @text backing files -__APIREL__/ref/am_conf/recno.html__OCT__2 managing @record-based databases -__APIREL__/ref/am_conf/renumber.html__OCT__2 logically renumbering @records -__APIREL__/ref/am_conf/select.html__OCT__2 selecting an @access method -__APIREL__/ref/am_misc/align.html__OCT__2 data @alignment -__APIREL__/ref/am_misc/dbsizes.html__OCT__2 database @limits -__APIREL__/ref/am_misc/diskspace.html__OCT__2 @disk space requirements -__APIREL__/ref/am_misc/error.html__OCT__2 @error handling -__APIREL__/ref/am_misc/faq.html__OCT__2 @access method FAQ -__APIREL__/ref/am_misc/faq.html__OCT__3 database @compaction -__APIREL__/ref/am_misc/faq.html__OCT__4 returning pages to the @filesystem -__APIREL__/ref/am_misc/faq.html__OCT__5 @double buffering -__APIREL__/ref/am_misc/get_bulk.html__OCT__2 @retrieving records in bulk -__APIREL__/ref/am_misc/partial.html__OCT__2 @partial record storage and retrieval -__APIREL__/ref/am_misc/perm.html__OCT__2 retrieved key/data @permanence -__APIREL__/ref/am_misc/perm.html__OCT__3 retrieved @key/data permanence -__APIREL__/ref/am_misc/stability.html__OCT__2 @cursor stability -__APIREL__/ref/am_misc/stability.html__OCT__3 cursor @stability -__APIREL__/ref/am_misc/stability.html__OCT__4 @degrees of isolation -__APIREL__/ref/am_misc/stability.html__OCT__5 degrees of @isolation -__APIREL__/ref/am_misc/tune.html__OCT__2 @access method tuning -__APIREL__/ref/am_misc/tune.html__OCT__3 access method @tuning -__APIREL__/ref/arch/apis.html__OCT__2 programmatic @APIs -__APIREL__/ref/arch/utilities.html__OCT__2 @utilities -__APIREL__/ref/build_unix/aix.html__OCT__2 @AIX -__APIREL__/ref/build_unix/conf.html__OCT__2 @configuring Berkeley DB for UNIX systems -__APIREL__/ref/build_unix/conf.html__OCT__3 configuring Berkeley DB for @UNIX systems -__APIREL__/ref/build_unix/conf.html__OCT__4 configuring Berkeley DB @1.85 API compatibility -__APIREL__/ref/build_unix/conf.html__OCT__--enable-compat185 Configuring Berkeley DB@--enable-compat185 -__APIREL__/ref/build_unix/conf.html__OCT__5 configuring the @C++ API -__APIREL__/ref/build_unix/conf.html__OCT__--enable-cxx Configuring Berkeley DB@--enable-cxx -__APIREL__/ref/build_unix/conf.html__OCT__--enable-debug Configuring Berkeley DB@--enable-debug -__APIREL__/ref/build_unix/conf.html__OCT__--enable-debug_rop Configuring Berkeley DB@--enable-debug_rop -__APIREL__/ref/build_unix/conf.html__OCT__--enable-debug_wop Configuring Berkeley DB@--enable-debug_wop -__APIREL__/ref/build_unix/conf.html__OCT__--enable-diagnostic Configuring Berkeley DB@--enable-diagnostic -__APIREL__/ref/build_unix/conf.html__OCT__6 building a utility to dump Berkeley DB @1.85 databases -__APIREL__/ref/build_unix/conf.html__OCT__--enable-dump185 Configuring Berkeley DB@--enable-dump185 -__APIREL__/ref/build_unix/conf.html__OCT__7 configuring the @Java API -__APIREL__/ref/build_unix/conf.html__OCT__--enable-java Configuring Berkeley DB@--enable-java -__APIREL__/ref/build_unix/conf.html__OCT__8 configuring without large @file support -__APIREL__/ref/build_unix/conf.html__OCT__--disable-largefile Configuring Berkeley DB@--disable-largefile -__APIREL__/ref/build_unix/conf.html__OCT__--enable-posixmutexes Configuring Berkeley DB@--enable-posixmutexes -__APIREL__/ref/build_unix/conf.html__OCT__9 configuring a @RPC client/server -__APIREL__/ref/build_unix/conf.html__OCT__--enable-rpc Configuring Berkeley DB@--enable-rpc -__APIREL__/ref/build_unix/conf.html__OCT__10 disabling @shared libraries -__APIREL__/ref/build_unix/conf.html__OCT__11 disabling @static libraries -__APIREL__/ref/build_unix/conf.html__OCT__--disable-shared Configuring Berkeley DB@--disable-shared -__APIREL__/ref/build_unix/conf.html__OCT__--disable-static Configuring Berkeley DB@--disable-static -__APIREL__/ref/build_unix/conf.html__OCT__12 configuring the @Tcl API -__APIREL__/ref/build_unix/conf.html__OCT__--enable-tcl Configuring Berkeley DB@--enable-tcl -__APIREL__/ref/build_unix/conf.html__OCT__13 configuring the @test suite -__APIREL__/ref/build_unix/conf.html__OCT__--enable-test Configuring Berkeley DB@--enable-test -__APIREL__/ref/build_unix/conf.html__OCT__--enable-uimutexes Configuring Berkeley DB@--enable-uimutexes -__APIREL__/ref/build_unix/conf.html__OCT__--enable-umrw Configuring Berkeley DB@--enable-umrw -__APIREL__/ref/build_unix/conf.html__OCT__--with-embedix=DIR Configuring Berkeley DB@--with-embedix=DIR -__APIREL__/ref/build_unix/conf.html__OCT__--with-mutex=MUTEX Configuring Berkeley DB@--with-mutex=MUTEX -__APIREL__/ref/build_unix/conf.html__OCT__--with-rpm=DIR Configuring Berkeley DB@--with-rpm=DIR -__APIREL__/ref/build_unix/conf.html__OCT__--with-tcl=DIR Configuring Berkeley DB@--with-tcl=DIR -__APIREL__/ref/build_unix/conf.html__OCT__--with-uniquename=NAME Configuring Berkeley DB@--with-uniquename=NAME -__APIREL__/ref/build_unix/embedix.html__OCT__2 @Embedix -__APIREL__/ref/build_unix/flags.html__OCT__2 changing @compile or load options -__APIREL__/ref/build_unix/flags.html__OCT__3 changing compile or @load options -__APIREL__/ref/build_unix/freebsd.html__OCT__2 @FreeBSD -__APIREL__/ref/build_unix/hpux.html__OCT__2 @HP-UX -__APIREL__/ref/build_unix/install.html__OCT__2 @installing Berkeley DB for UNIX systems -__APIREL__/ref/build_unix/intro.html__OCT__2 @building for UNIX -__APIREL__/ref/build_unix/intro.html__OCT__3 @building for QNX -__APIREL__/ref/build_unix/intro.html__OCT__4 building for @UNIX -__APIREL__/ref/build_unix/intro.html__OCT__5 building for @QNX -__APIREL__/ref/build_unix/irix.html__OCT__2 @IRIX -__APIREL__/ref/build_unix/linux.html__OCT__2 @Linux -__APIREL__/ref/build_unix/macosx.html__OCT__2 @Mac OS X -__APIREL__/ref/build_unix/notes.html__OCT__2 @building for UNIX FAQ -__APIREL__/ref/build_unix/notes.html__OCT__3 building for @UNIX FAQ -__APIREL__/ref/build_unix/osf1.html__OCT__2 @OSF/1 -__APIREL__/ref/build_unix/qnx.html__OCT__2 @QNX -__APIREL__/ref/build_unix/sco.html__OCT__2 @SCO -__APIREL__/ref/build_unix/shlib.html__OCT__2 @shared libraries -__APIREL__/ref/build_unix/solaris.html__OCT__2 @Solaris -__APIREL__/ref/build_unix/sunos.html__OCT__2 @SunOS -__APIREL__/ref/build_unix/test.html__OCT__2 running the @test suite under UNIX -__APIREL__/ref/build_unix/ultrix.html__OCT__2 @Ultrix -__APIREL__/ref/build_vxworks/faq.html__OCT__2 @building for VxWorks FAQ -__APIREL__/ref/build_vxworks/faq.html__OCT__3 building for @VxWorks FAQ -__APIREL__/ref/build_vxworks/intro.html__OCT__2 @building for VxWorks -__APIREL__/ref/build_vxworks/introae.html__OCT__2 @building for VxWorks AE -__APIREL__/ref/build_vxworks/notes.html__OCT__2 @VxWorks notes -__APIREL__/ref/build_win/faq.html__OCT__2 @building for Windows FAQ -__APIREL__/ref/build_win/faq.html__OCT__3 building for @Windows FAQ -__APIREL__/ref/build_win/intro.html__OCT__2 @building for Win32 -__APIREL__/ref/build_win/notes.html__OCT__2 @Windows notes -__APIREL__/ref/build_win/test.html__OCT__2 running the @test suite under Windows -__APIREL__/ref/build_win/test.html__OCT__3 running the test suite under @Windows -__APIREL__/ref/cam/intro.html__OCT__2 @Concurrent Data Store -__APIREL__/ref/debug/intro.html__OCT__2 introduction to @debugging -__APIREL__/ref/debug/common.html__OCT__2 @debugging applications -__APIREL__/ref/distrib/layout.html__OCT__2 @source code layout -__APIREL__/ref/dumpload/text.html__OCT__2 loading @text into databases -__APIREL__/ref/dumpload/utility.html__OCT__2 dumping/loading @text to/from databases -__APIREL__/ref/env/create.html__OCT__2 database @environment -__APIREL__/ref/env/db_config.html__OCT__2 @DB_CONFIG -__APIREL__/ref/env/db_config.html__OCT__3 database environment @configuration -__APIREL__/ref/env/encrypt.html__OCT__2 @encryption -__APIREL__/ref/env/faq.html__OCT__2 database @environment FAQ -__APIREL__/ref/env/intro.html__OCT__2 introduction to database @environments -__APIREL__/ref/env/naming.html__OCT__2 file @naming -__APIREL__/ref/env/naming.html__OCT__db_home File naming@db_home -__APIREL__/ref/env/naming.html__OCT__DB_HOME File naming@DB_HOME -__APIREL__/ref/env/region.html__OCT__2 @__db.001 -__APIREL__/ref/env/remote.html__OCT__2 remote @filesystems -__APIREL__/ref/env/security.html__OCT__2 @security -__APIREL__/ref/intro/products.html__OCT__2 Sleepycat Software's Berkeley DB @products -__APIREL__/ref/install/file.html__OCT__2 @/etc/magic -__APIREL__/ref/install/file.html__OCT__3 @file utility -__APIREL__/ref/install/rpm.html__OCT__2 @RPM -__APIREL__/ref/java/compat.html__OCT__2 @Java compatibility -__APIREL__/ref/java/conf.html__OCT__2 @Java configuration -__APIREL__/ref/java/faq.html__OCT__2 Java @FAQ -__APIREL__/ref/java/faq.html__OCT__3 @Java FAQ -__APIREL__/ref/lock/am_conv.html__OCT__2 Berkeley DB Transactional Data Store @locking conventions -__APIREL__/ref/lock/cam_conv.html__OCT__2 Berkeley DB Concurrent Data Store @locking conventions -__APIREL__/ref/lock/config.html__OCT__2 @locking configuration -__APIREL__/ref/lock/dead.html__OCT__2 @deadlocks -__APIREL__/ref/lock/intro.html__OCT__2 introduction to the @locking subsystem -__APIREL__/ref/lock/max.html__OCT__2 sizing the @locking subsystem -__APIREL__/ref/lock/nondb.html__OCT__2 @locking and non-Berkeley DB applications -__APIREL__/ref/lock/notxn.html__OCT__2 @locking without transactions -__APIREL__/ref/lock/page.html__OCT__2 page-level @locking -__APIREL__/ref/lock/page.html__OCT__3 @locking granularity -__APIREL__/ref/lock/stdmode.html__OCT__2 standard @lock modes -__APIREL__/ref/lock/timeout.html__OCT__2 lock @timeouts -__APIREL__/ref/lock/timeout.html__OCT__3 transaction @timeouts -__APIREL__/ref/lock/twopl.html__OCT__2 two-phase @locking -__APIREL__/ref/log/config.html__OCT__2 @logging configuration -__APIREL__/ref/log/intro.html__OCT__2 introduction to the @logging subsystem -__APIREL__/ref/log/limits.html__OCT__2 @log file limits -__APIREL__/ref/mp/intro.html__OCT__2 introduction to the @memory pool subsystem -__APIREL__/ref/mp/intro.html__OCT__3 introduction to the memory @cache subsystem -__APIREL__/ref/mp/intro.html__OCT__4 introduction to the @buffer pool subsystem -__APIREL__/ref/mp/config.html__OCT__2 @memory pool configuration -__APIREL__/ref/perl/intro.html__OCT__2 @Perl -__APIREL__/ref/program/appsignals.html__OCT__2 @signal handling -__APIREL__/ref/program/compatible.html__OCT__2 @interface compatibility -__APIREL__/ref/program/environ.html__OCT__2 @environment variables -__APIREL__/ref/program/errorret.html__OCT__2 @error returns -__APIREL__/ref/program/errorret.html__OCT__3 @error name space -__APIREL__/ref/program/errorret.html__OCT__DB_NOTFOUND Error returns to applications@DB_NOTFOUND -__APIREL__/ref/program/errorret.html__OCT__DB_KEYEMPTY Error returns to applications@DB_KEYEMPTY -__APIREL__/ref/program/errorret.html__OCT__DB_KEYEXIST Error returns to applications@DB_KEYEXIST -__APIREL__/ref/program/errorret.html__OCT__4 @DB_LOCK_DEADLOCK -__APIREL__/ref/program/errorret.html__OCT__DB_LOCK_DEADLOCK Error returns to applications@DB_LOCK_DEADLOCK -__APIREL__/ref/program/errorret.html__OCT__DB_LOCK_NOTGRANTED Error returns to applications@DB_LOCK_NOTGRANTED -__APIREL__/ref/program/errorret.html__OCT__DB_RUNRECOVERY Error returns to applications@DB_RUNRECOVERY -__APIREL__/ref/program/faq.html__OCT__2 task/thread @priority -__APIREL__/ref/program/mt.html__OCT__2 building @threaded applications -__APIREL__/ref/program/namespace.html__OCT__2 Berkeley DB library @name spaces -__APIREL__/ref/program/scope.html__OCT__2 Berkeley DB handle @scope -__APIREL__/ref/program/scope.html__OCT__3 Berkeley DB @free-threaded handles -__APIREL__/ref/rep/intro.html__OCT__2 introduction to @replication -__APIREL__/ref/rpc/client.html__OCT__2 @RPC client -__APIREL__/ref/rpc/faq.html__OCT__2 @RPC FAQ -__APIREL__/ref/rpc/intro.html__OCT__2 introduction to @rpc client/server -__APIREL__/ref/rpc/server.html__OCT__2 @RPC server -__APIREL__/ref/sendmail/intro.html__OCT__2 @Sendmail -__APIREL__/ref/simple_tut/intro.html__OCT__2 simple @tutorial -__APIREL__/ref/tcl/intro.html__OCT__2 loading Berkeley DB with @Tcl -__APIREL__/ref/tcl/faq.html__OCT__2 Tcl @FAQ -__APIREL__/ref/tcl/faq.html__OCT__3 @Tcl FAQ -__APIREL__/ref/tcl/program.html__OCT__2 @Tcl API programming notes -__APIREL__/ref/tcl/using.html__OCT__2 using Berkeley DB with @Tcl -__APIREL__/ref/test/run.html__OCT__2 running the @test suite -__APIREL__/ref/transapp/admin.html__OCT__2 administering @transaction protected applications -__APIREL__/ref/transapp/archival.html__OCT__2 archival in @transaction protected applications -__APIREL__/ref/transapp/archival.html__OCT__3 @catastrophic recovery -__APIREL__/ref/transapp/archival.html__OCT__4 hot @backup -__APIREL__/ref/transapp/checkpoint.html__OCT__2 checkpoints in @transaction protected applications -__APIREL__/ref/transapp/deadlock.html__OCT__2 deadlock detection in @transaction protected applications -__APIREL__/ref/transapp/faq.html__OCT__2 @transaction FAQ -__APIREL__/ref/transapp/filesys.html__OCT__2 recovery and @filesystem operations -__APIREL__/ref/transapp/hotfail.html__OCT__2 hot @failover -__APIREL__/ref/transapp/intro.html__OCT__2 @Transactional Data Store -__APIREL__/ref/transapp/logfile.html__OCT__2 @log file removal -__APIREL__/ref/transapp/nested.html__OCT__2 nested @transactions -__APIREL__/ref/transapp/read.html__OCT__2 @repeatable read -__APIREL__/ref/transapp/read.html__OCT__3 dirty @reads -__APIREL__/ref/transapp/read.html__OCT__4 @dirty reads -__APIREL__/ref/transapp/reclimit.html__OCT__2 Berkeley DB @recoverability -__APIREL__/ref/transapp/recovery.html__OCT__2 recovery in @transaction protected applications -__APIREL__/ref/transapp/throughput.html__OCT__2 @transaction throughput -__APIREL__/ref/transapp/tune.html__OCT__2 @transaction tuning -__APIREL__/ref/transapp/tune.html__OCT__3 transaction @tuning -__APIREL__/ref/txn/config.html__OCT__2 @transaction configuration -__APIREL__/ref/txn/intro.html__OCT__2 introduction to the @transaction subsystem -__APIREL__/ref/txn/limits.html__OCT__2 @transaction limits -__APIREL__/ref/upgrade.2.0/intro.html__OCT__2 Upgrading to release @2.0 -__APIREL__/ref/upgrade.3.0/intro.html__OCT__2 Upgrading to release @3.0 -__APIREL__/ref/upgrade.3.1/intro.html__OCT__2 Upgrading to release @3.1 -__APIREL__/ref/upgrade.3.2/intro.html__OCT__2 Upgrading to release @3.2 -__APIREL__/ref/upgrade.3.3/intro.html__OCT__2 Upgrading to release @3.3 -__APIREL__/ref/upgrade.4.0/intro.html__OCT__2 Upgrading to release @4.0 -__APIREL__/ref/upgrade.4.1/intro.html__OCT__2 Upgrading to release @4.1 -__APIREL__/ref/xa/build.html__OCT__2 @Transaction Manager -__APIREL__/ref/xa/intro.html__OCT__2 @Distributed Transactions -__APIREL__/ref/xa/intro.html__OCT__3 @Resource Manager -__APIREL__/ref/xa/faq.html__OCT__2 XA @FAQ -__APIREL__/ref/xa/faq.html__OCT__3 @XA FAQ -__APIREL__/ref/xa/xa_config.html__OCT__2 configuring Berkeley DB with the @Tuxedo System -__APIREL__/ref/xa/xa_intro.html__OCT__2 @XA Resource Manager -__APIREL__/ref/xa/xa_intro.html__OCT__3 XA @Resource Manager -__APIREL__/utility/berkeley_db_svc.html__OCT__2 @berkeley_db_svc -__APIREL__/utility/berkeley_db_svc.html__OCT__3 utility to support @RPC client/server -__APIREL__/utility/db_archive.html__OCT__2 @db_archive -__APIREL__/utility/db_archive.html__OCT__3 utility to @archive log files -__APIREL__/utility/db_checkpoint.html__OCT__2 @db_checkpoint -__APIREL__/utility/db_checkpoint.html__OCT__3 utility to take @checkpoints -__APIREL__/utility/db_deadlock.html__OCT__2 @db_deadlock -__APIREL__/utility/db_deadlock.html__OCT__3 utility to detect @deadlocks -__APIREL__/utility/db_dump.html__OCT__2 @db_dump -__APIREL__/utility/db_dump.html__OCT__3 utility to @dump databases as text files -__APIREL__/utility/db_load.html__OCT__2 @db_load -__APIREL__/utility/db_load.html__OCT__3 utility to @load text files into databases -__APIREL__/utility/db_printlog.html__OCT__2 @db_printlog -__APIREL__/utility/db_printlog.html__OCT__3 utility to display @log files as text -__APIREL__/utility/db_recover.html__OCT__2 @db_recover -__APIREL__/utility/db_recover.html__OCT__3 utility to @recover database environments -__APIREL__/utility/db_stat.html__OCT__2 @db_stat -__APIREL__/utility/db_stat.html__OCT__3 utility to display database and environment @statistics -__APIREL__/utility/db_upgrade.html__OCT__2 @db_upgrade -__APIREL__/utility/db_upgrade.html__OCT__3 utility to upgrade @database files -__APIREL__/utility/db_upgrade.html__OCT__4 utility to @upgrade database files -__APIREL__/utility/db_verify.html__OCT__2 @db_verify -__APIREL__/utility/db_verify.html__OCT__3 utility to verify @database files -__APIREL__/utility/db_verify.html__OCT__4 utility to @verify database files diff --git a/libdb/docs/ref/program/appsignals.html b/libdb/docs/ref/program/appsignals.html deleted file mode 100644 index de4bf6d06..000000000 --- a/libdb/docs/ref/program/appsignals.html +++ /dev/null @@ -1,39 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Signal handling</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Programmer Notes</dl></h3></td> -<td align=right><a href="../../ref/apprec/config.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/program/errorret.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Signal handling</h1> -<p>When applications using Berkeley DB receive signals, it is important that they -exit gracefully, discarding any Berkeley DB locks that they may hold. This is -normally done by setting a flag when a signal arrives and then checking -for that flag periodically within the application. Because Berkeley DB is not -re-entrant, the signal handler should not attempt to release locks and/or -close the database handles itself. Re-entering Berkeley DB is not guaranteed to -work correctly, and the results are undefined. -<p>If an application exits holding a lock, the situation is no different -than if the application crashed, and all applications participating in -the database environment must be shut down, and then recovery must be -performed. If this is not done, databases may be left in an -inconsistent state, or locks the application held may cause unresolvable -deadlocks inside the environment, causing applications to hang. -<p>Berkeley DB restarts all system calls interrupted by signals, that is, any -underlying system calls that return failure with errno set to EINTR will -be restarted rather than failing. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/apprec/config.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/program/errorret.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/libdb/docs/ref/program/cache.html b/libdb/docs/ref/program/cache.html deleted file mode 100644 index d70b3438d..000000000 --- a/libdb/docs/ref/program/cache.html +++ /dev/null @@ -1,35 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Disk drive caches</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Programmer Notes</dl></h3></td> -<td align=right><a href="../../ref/program/namespace.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/program/copy.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Disk drive caches</h1> -<p>Many disk drives contain onboard caches. Some of these drives include -battery-backup or other functionality that guarantees that all cached -data will be completely written if the power fails. These drives can -offer substantial performance improvements over drives without caching -support. However, some caching drives rely on capacitors or other -mechanisms that guarantee only that the write of the current sector -will complete. These drives can endanger your database and potentially -cause corruption of your data. -<p>To avoid losing your data, make sure the caching on your disk drives is -properly configured so the drive will never report that data has been written -unless the data is guaranteed to be written in the face of a power failure. -Many times, this means that write-caching on the disk drive must -be disabled. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/program/namespace.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/program/copy.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/libdb/docs/ref/program/compatible.html b/libdb/docs/ref/program/compatible.html deleted file mode 100644 index 2b76a27b9..000000000 --- a/libdb/docs/ref/program/compatible.html +++ /dev/null @@ -1,33 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Compatibility with historic UNIX interfaces</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Programmer Notes</dl></h3></td> -<td align=right><a href="../../ref/program/copy.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/program/runtime.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Compatibility with historic UNIX interfaces</h1> -<p>The Berkeley DB version 2 library provides backward-compatible interfaces for -the historic UNIX <a href="../../api_c/dbm.html">dbm</a>, <a href="../../api_c/dbm.html">ndbm</a>, and <a href="../../api_c/hsearch.html">hsearch</a> -interfaces. It also provides a backward-compatible interface for the -historic Berkeley DB 1.85 release. -<p>Berkeley DB version 2 does not provide database compatibility for any of the -previous interfaces, and existing databases must be converted manually. -To convert existing databases from the Berkeley DB 1.85 format to the Berkeley DB -version 2 format, review the <a href="../../utility/db_dump.html">db_dump185</a> and <a href="../../utility/db_load.html">db_load</a> -information. No utilities are provided to convert UNIX <a href="../../api_c/dbm.html">dbm</a>, -<a href="../../api_c/dbm.html">ndbm</a>, or <a href="../../api_c/hsearch.html">hsearch</a> databases. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/program/copy.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/program/runtime.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/libdb/docs/ref/program/copy.html b/libdb/docs/ref/program/copy.html deleted file mode 100644 index 9d8361af6..000000000 --- a/libdb/docs/ref/program/copy.html +++ /dev/null @@ -1,64 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Copying 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> -<table width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Programmer Notes</dl></h3></td> -<td align=right><a href="../../ref/program/cache.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/program/compatible.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Copying databases</h1> -<p>Because file identification cookies (for example, filenames, device and -inode numbers, volume and file IDs, and so on) are not necessarily -unique or maintained across system reboots, each Berkeley DB database file -contains a 20-byte file identification bytestring that is stored in the -first page of the database, starting with the 53rd byte on the page. -When multiple processes or threads open the same database file in Berkeley DB, -it is this bytestring that is used to ensure that the same underlying -pages are updated in the shared memory buffer pool, no matter which -Berkeley DB handle is used for the operation. -<p>It is usually a bad idea to physically copy a database to a new name. In -the few cases in which copying is the best solution for your application, -you must guarantee that there are never two different databases with -the same file identification bytestring in the memory pool at the same -time. Copying databases is further complicated by the fact that the -shared memory buffer pool does not discard all cached copies of pages -for a database when the database is logically closed; that is, when -<a href="../../api_c/db_close.html">DB->close</a> is called. Nor is there a Berkeley DB interface to -explicitly discard pages from the shared memory buffer pool for any -particular database. -<p>Before copying a database, you must ensure that all modified pages have -been written from the memory pool cache to the backing database file. -This is done using the <a href="../../api_c/db_sync.html">DB->sync</a> or <a href="../../api_c/db_close.html">DB->close</a> interfaces. -<p>Before using a copy of a database from Berkeley DB, you must ensure that all -pages from any database with the same bytestring have been removed from -the memory pool cache. If the environment in which you intend to open -the copy of the database potentially has pages from files with identical -bytestrings to the copied database (which is likely to be the case), there -are a few possible solutions: -<p><ol> -<p><li>Remove the environment, either explicitly or by calling <a href="../../api_c/env_remove.html">DB_ENV->remove</a>. -Note that this will not allow you to access both the original and copy -of the database at the same time. -<p><li>Create a new file that will have a new bytestring. The simplest way to -create a new file that will have a new bytestring is to call the -<a href="../../utility/db_dump.html">db_dump</a> utility to dump out the contents of the database and -then use the <a href="../../utility/db_load.html">db_load</a> utility to load the dumped output into a -new file. This allows you to access both the original and copy of -the database at the same time. -<p><li>If your database is too large to be copied, overwrite the bytestring in -the copied database with a new bytestring. This allows you to access -both the original and copy of the database at the same time. -</ol> -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/program/cache.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/program/compatible.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/libdb/docs/ref/program/environ.html b/libdb/docs/ref/program/environ.html deleted file mode 100644 index ca44051bb..000000000 --- a/libdb/docs/ref/program/environ.html +++ /dev/null @@ -1,34 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Environment variables</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Programmer Notes</dl></h3></td> -<td align=right><a href="../../ref/program/errorret.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/program/mt.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Environment variables</h1> -<p>The Berkeley DB library uses the following environment variables: -<p><dl compact> -<p><dt>DB_HOME<dd>If the environment variable DB_HOME is set, it is used as part of -<a href="../../ref/env/naming.html">File Naming</a>. -Note: For the DB_HOME variable to take effect, either the -<a href="../../api_c/env_open.html#DB_USE_ENVIRON">DB_USE_ENVIRON</a> or <a href="../../api_c/env_open.html#DB_USE_ENVIRON_ROOT">DB_USE_ENVIRON_ROOT</a> flags must be -specified to <a href="../../api_c/env_open.html">DB_ENV->open</a>. -<p><dt>TMPDIR, TEMP, TMP, TempFolder<dd>The TMPDIR, TEMP, TMP, and TempFolder environment variables are all -checked as locations in which to create temporary files. See -<a href="../../api_c/env_set_tmp_dir.html">DB_ENV->set_tmp_dir</a> for more information. -</dl> -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/program/errorret.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/program/mt.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/libdb/docs/ref/program/errorret.html b/libdb/docs/ref/program/errorret.html deleted file mode 100644 index 1baf2abf0..000000000 --- a/libdb/docs/ref/program/errorret.html +++ /dev/null @@ -1,114 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Error returns to applications</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Programmer Notes</dl></h3></td> -<td align=right><a href="../../ref/program/appsignals.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/program/environ.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Error returns to applications</h1> -<p>Except for the historic <a href="../../api_c/dbm.html">dbm</a>, <a href="../../api_c/dbm.html">ndbm</a>, and <a href="../../api_c/hsearch.html">hsearch</a> -interfaces, Berkeley DB does not use the global variable <b>errno</b> to -return error values. The return values for all Berkeley DB functions are -grouped into the following three categories: -<p><dl compact> -<p><dt>0<dd>A return value of 0 indicates that the operation was successful. -<p><dt>> 0<dd>A return value that is greater than 0 indicates that there was a system -error. The <b>errno</b> value returned by the system is returned by -the function; for example, when a Berkeley DB function is unable to allocate -memory, the return value from the function will be ENOMEM. -<p><dt>< 0<dd>A return value that is less than 0 indicates a condition that was not -a system failure, but was not an unqualified success, either. For -example, a routine to retrieve a key/data pair from the database may -return DB_NOTFOUND when the key/data pair does not appear in -the database; as opposed to the value of 0, which would be returned if -the key/data pair were found in the database. -<p><a name="3"><!--meow--></a> -All values returned by Berkeley DB functions are less than 0 in order to avoid -conflict with possible values of <b>errno</b>. Specifically, Berkeley DB -reserves all values from -30,800 to -30,999 to itself as possible error -values. There are a few Berkeley DB interfaces where it is possible for an -application function to be called by a Berkeley DB function and subsequently -fail with an application-specific return. Such failure returns will be -passed back to the function that originally called a Berkeley DB interface. -To avoid ambiguity about the cause of the error, error values separate -from the Berkeley DB error name space should be used. -</dl> -<p>Although possible error returns are specified by each individual function's -manual page, there are a few error returns that deserve general mention: -<h3><a name="DB_NOTFOUND">DB_NOTFOUND</a> and <a name="DB_KEYEMPTY">DB_KEYEMPTY</a></h3> -<p>There are two special return values that are similar in meaning and that -are returned in similar situations, and therefore might be confused: -DB_NOTFOUND and DB_KEYEMPTY. -<p>The DB_NOTFOUND error return indicates that the requested key/data -pair did not exist in the database or that start-of- or end-of-file has -been reached by a cursor. -<p>The DB_KEYEMPTY error return indicates that the requested -key/data pair logically exists but was never explicitly created by the -application (the Recno and Queue access methods will automatically -create key/data pairs under some circumstances; see <a href="../../api_c/db_open.html">DB->open</a> -for more information), or that the requested key/data pair was deleted -and never re-created. In addition, the Queue access method will return -DB_KEYEMPTY for records that were created as part of a -transaction that was later aborted and never re-created. -<h3><a name="DB_KEYEXIST">DB_KEYEXIST</a></h3> -<p>The DB_KEYEXIST error return indicates the <a href="../../api_c/db_put.html#DB_NOOVERWRITE">DB_NOOVERWRITE</a> -option was specified to the <a href="../../api_c/db_put.html">DB->put</a> method and the key already exists -in the database. -<a name="4"><!--meow--></a> -<h3><a name="DB_LOCK_DEADLOCK">DB_LOCK_DEADLOCK</a></h3> -<p>When multiple threads of control are modifying the database, there is -normally the potential for deadlock. In Berkeley DB, deadlock is signified by -an error return from the Berkeley DB function of the value -DB_LOCK_DEADLOCK. Whenever a Berkeley DB function returns -DB_LOCK_DEADLOCK, the enclosing transaction should be aborted. -<p>Any Berkeley DB function that attempts to acquire locks can potentially return -DB_LOCK_DEADLOCK. Practically speaking, the safest way to deal -with applications that can deadlock is to handle a -DB_LOCK_DEADLOCK return from any Berkeley DB access method call. -<h3><a name="DB_LOCK_NOTGRANTED">DB_LOCK_NOTGRANTED</a></h3> -<p>When multiple threads of control are modifying the database, there is -normally the potential for deadlock. In order to avoid deadlock, -applications may specify -- on a per-transaction basis -- that if a lock -is unavailable, the Berkeley DB operation should return immediately instead -of waiting on the lock. The error return in this case will be -DB_LOCK_NOTGRANTED. Whenever a Berkeley DB function returns -DB_LOCK_NOTGRANTED, the enclosing transaction should be -aborted. -<h3><a name="DB_RUNRECOVERY">DB_RUNRECOVERY</a></h3> -<p>There exists a class of errors that Berkeley DB considers fatal to an entire -Berkeley DB environment. An example of this type of error is a corrupted -database page. The only way to recover from these failures is to have -all threads of control exit the Berkeley DB environment, run recovery of the -environment, and re-enter Berkeley DB. (It is not strictly necessary that the -processes exit, although that is the only way to recover system -resources, such as file descriptors and memory, allocated by Berkeley DB.) -<p>When this type of error is encountered, the error value -DB_RUNRECOVERY is returned. This error can be returned by any -Berkeley DB interface. Once DB_RUNRECOVERY is returned by any -interface, it will be returned from all subsequent Berkeley DB calls made by -any threads of control participating in the environment. -<p>Optionally, applications may also specify a fatal-error callback function -using the <a href="../../api_c/env_set_paniccall.html">DB_ENV->set_paniccall</a> method. This callback function will be -called with two arguments: a reference to the <a href="../../api_c/env_class.html">DB_ENV</a> structure -associated with the environment and the <b>errno</b> value -associated with the underlying error that caused the problem. -<p>Applications can handle such fatal errors in one of two ways: by checking -for DB_RUNRECOVERY as part of their normal Berkeley DB error return -checking, similarly to DB_LOCK_DEADLOCK or any other error, or -by simply exiting the application when the callback function is called -in applications that have no cleanup processing of their own. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/program/appsignals.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/program/environ.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/libdb/docs/ref/program/faq.html b/libdb/docs/ref/program/faq.html deleted file mode 100644 index b99b598b8..000000000 --- a/libdb/docs/ref/program/faq.html +++ /dev/null @@ -1,31 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Programmer notes FAQ</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Programmer Notes</dl></h3></td> -<td align=right><a href="../../ref/program/runtime.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/lock/intro.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Programmer notes FAQ</h1> -<p><ol> -<a name="2"><!--meow--></a> -<p><li><b>What priorities should threads/tasks executing Berkeley DB functions -be given?</b> -<p>Tasks executing Berkeley DB functions should have the same, or roughly -equivalent, system priorities. For example, it can be dangerous to give -tasks of control performing checkpoints a lower priority than tasks of -control doing database lookups, and starvation can sometimes result. -</ol> -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/program/runtime.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/lock/intro.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/libdb/docs/ref/program/mt.html b/libdb/docs/ref/program/mt.html deleted file mode 100644 index 484b6c6ef..000000000 --- a/libdb/docs/ref/program/mt.html +++ /dev/null @@ -1,74 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Multithreaded applications</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Programmer Notes</dl></h3></td> -<td align=right><a href="../../ref/program/environ.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/program/scope.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Multithreaded applications</h1> -<p>Berkeley DB fully supports multithreaded applications. The Berkeley DB library is -not itself multithreaded, as it was deliberately architected to not use -threads internally because of the portability problems it would -introduce. Database environment and database object handles returned -from Berkeley DB library functions are free-threaded. No other object handles -returned from the Berkeley DB library are free-threaded. The following rules -should be observed when using threads to access the Berkeley DB library: -<p><ol> -<p><li>The <a href="../../api_c/env_open.html#DB_THREAD">DB_THREAD</a> flag must be specified to the <a href="../../api_c/env_open.html">DB_ENV->open</a> -and <a href="../../api_c/db_open.html">DB->open</a> methods if the Berkeley DB handles returned by those interfaces -will be used in the context of more than one thread. Setting the -<a href="../../api_c/env_open.html#DB_THREAD">DB_THREAD</a> flag inconsistently may result in database corruption. -<p>Threading is assumed in the Java API, so no special flags are required; -and Berkeley DB functions will always behave as if the <a href="../../api_c/env_open.html#DB_THREAD">DB_THREAD</a> flag -was specified. -<p>Only a single thread may call the <a href="../../api_c/env_close.html">DB_ENV->close</a> or <a href="../../api_c/db_close.html">DB->close</a> methods -for a returned environment or database handle. -<p>No other Berkeley DB handles are free-threaded; for example, cursors and -transactions may not span threads because their returned handles are -not free-threaded. -<p><li>When using the non-cursor Berkeley DB calls to retrieve key/data items (for -example, <a href="../../api_c/db_get.html">DB->get</a>), the memory to which the pointer stored into -the Dbt refers is valid only until the next call using the <a href="../../api_c/db_class.html">DB</a> -handle returned by <a href="../../api_c/db_open.html">DB->open</a>. This includes <b>any</b> use of -the returned <a href="../../api_c/db_class.html">DB</a> handle, including by another thread within the -process. -<p>For this reason, if the <a href="../../api_c/env_open.html#DB_THREAD">DB_THREAD</a> handle was specified to the -<a href="../../api_c/db_open.html">DB->open</a> method, either <a href="../../api_c/dbt_class.html#DB_DBT_MALLOC">DB_DBT_MALLOC</a>, <a href="../../api_c/dbt_class.html#DB_DBT_REALLOC">DB_DBT_REALLOC</a>, -or <a href="../../api_c/dbt_class.html#DB_DBT_USERMEM">DB_DBT_USERMEM</a> must be specified in the <a href="../../api_c/dbt_class.html">DBT</a> when -performing any non-cursor key or data retrieval. -<p><li>Transactions may not span threads. Each transaction must begin and end -in the same thread, and each transaction may be used only by a single -thread. -<p>Cursors may not span transactions or threads. Each cursor must be -allocated and deallocated within the same transaction and within -the same thread. -<p><li>User-level synchronization mutexes must have been implemented for the -compiler/architecture combination. Attempting to specify the DB_THREAD -flag will fail if fast mutexes are not available. -<p>If blocking mutexes are available (for example POSIX pthreads), they -will be used. Otherwise, the Berkeley DB library will make a system call to -pause for some amount of time when it is necessary to wait on a lock. -This may not be optimal, especially in a thread-only environment, in -which it will be more efficient to explicitly yield the processor to -another thread. -<p>It is possible to specify a yield function on an per-application basis. -See <a href="../../api_c/set_func_yield.html">db_env_set_func_yield</a> for more information. -<p>It is possible to specify the number of attempts that will be made to -acquire the mutex before waiting. See <a href="../../api_c/env_set_tas_spins.html">DB_ENV->set_tas_spins</a> for -more information. -</ol> -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/program/environ.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/program/scope.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/libdb/docs/ref/program/namespace.html b/libdb/docs/ref/program/namespace.html deleted file mode 100644 index d67abcb55..000000000 --- a/libdb/docs/ref/program/namespace.html +++ /dev/null @@ -1,48 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Name spaces</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Programmer Notes</dl></h3></td> -<td align=right><a href="../../ref/program/scope.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/program/cache.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Name spaces</h1> -<h3>C Language Name Space</h3> -<p>The Berkeley DB library is careful to avoid C language programmer name spaces, -but there are a few potential areas for concern, mostly in the Berkeley DB -include file db.h. The db.h include file defines a number of types and -strings. Where possible, all of these types and strings are prefixed with -"DB_" or "db_". There are a few notable exceptions. -<p>The Berkeley DB library uses a macro named "__P" to configure for systems that -do not provide ANSI C function prototypes. This could potentially collide -with other systems using a "__P" macro for similar or different purposes. -<p>The Berkeley DB library needs information about specifically sized types for -each architecture. If they are not provided by the system, they are -typedef'd in the db.h include file. The types that may be typedef'd -by db.h include the following: u_int8_t, int16_t, u_int16_t, int32_t, -u_int32_t, u_char, u_short, u_int, and u_long. -<p>The Berkeley DB library declares a number of external routines. All these -routines are prefixed with the strings "db_", "lock_", "log_", "memp_" -or "txn_". All internal routines are prefixed with the strings "__db_", -"__lock_", "__log_", "__memp_", or "__txn_". -<h3>Filesystem Name Space</h3> -<p>Berkeley DB environments create or use some number of files in environment -home directories. These files are named <a href="../../ref/env/db_config.html#DB_CONFIG">DB_CONFIG</a>, "log.NNNNN" -(for example, log.0000000003, where the number of digits following the -dot is unspecified), or with the string prefix "__db" (for example, -__db.001). Database files that match these names should not be created -in the environment directory. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/program/scope.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/program/cache.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/libdb/docs/ref/program/runtime.html b/libdb/docs/ref/program/runtime.html deleted file mode 100644 index 84d5f7f7c..000000000 --- a/libdb/docs/ref/program/runtime.html +++ /dev/null @@ -1,55 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Run-time configuration</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Programmer Notes</dl></h3></td> -<td align=right><a href="../../ref/program/compatible.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/program/faq.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Run-time configuration</h1> -<p>It is possible to configure Berkeley DB at run-time so applications can -redirect all Berkeley DB calls to underlying library or system call -functionality. For example, an application might want Berkeley DB to call -debugging memory allocation routines rather than the standard C library -interfaces. The following interfaces support this functionality: -<p><blockquote><pre><a href="../../api_c/set_func_close.html">db_env_set_func_close</a> -<a href="../../api_c/set_func_dirfree.html">db_env_set_func_dirfree</a> -<a href="../../api_c/set_func_dirlist.html">db_env_set_func_dirlist</a> -<a href="../../api_c/set_func_exists.html">db_env_set_func_exists</a> -<a href="../../api_c/set_func_free.html">db_env_set_func_free</a> -<a href="../../api_c/set_func_fsync.html">db_env_set_func_fsync</a> -<a href="../../api_c/set_func_ioinfo.html">db_env_set_func_ioinfo</a> -<a href="../../api_c/set_func_malloc.html">db_env_set_func_malloc</a> -<a href="../../api_c/set_func_map.html">db_env_set_func_map</a> -<a href="../../api_c/set_func_open.html">db_env_set_func_open</a> -<a href="../../api_c/set_func_read.html">db_env_set_func_read</a> -<a href="../../api_c/set_func_realloc.html">db_env_set_func_realloc</a> -<a href="../../api_c/set_func_seek.html">db_env_set_func_seek</a> -<a href="../../api_c/set_func_sleep.html">db_env_set_func_sleep</a> -<a href="../../api_c/set_func_unlink.html">db_env_set_func_unlink</a> -<a href="../../api_c/set_func_unmap.html">db_env_set_func_unmap</a> -<a href="../../api_c/set_func_write.html">db_env_set_func_write</a> -<a href="../../api_c/set_func_yield.html">db_env_set_func_yield</a></pre></blockquote> -<p>These interfaces are available only from the Berkeley DB C language API, and -are not available from all of the operating systems Berkeley DB supports. -<p>A not-uncommon problem for applications is the new API in Solaris 2.6 -for manipulating large files. Because this API was not part of Solaris -2.5, it is difficult to create a single binary that takes advantage of -the large file functionality in Solaris 2.6, but still runs on Solaris -2.5. <a href="solaris.txt">Example code</a> that supports this is -included in the Berkeley DB distribution, however, the example code was -written using previous versions of the Berkeley DB APIs, and is only useful -as an example. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/program/compatible.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/program/faq.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/libdb/docs/ref/program/scope.html b/libdb/docs/ref/program/scope.html deleted file mode 100644 index 3e82d1b9d..000000000 --- a/libdb/docs/ref/program/scope.html +++ /dev/null @@ -1,74 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Berkeley DB handles</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Programmer Notes</dl></h3></td> -<td align=right><a href="../../ref/program/mt.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/program/namespace.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Berkeley DB handles</h1> -<p>The Berkeley DB library has a number of object handles. The following table -lists those handles, their scope, and whether they are free-threaded -(that is, whether multiple threads within a process can share them). -<p><dl compact> -<p><dt><a href="../../api_c/env_class.html">DB_ENV</a><dd>The <a href="../../api_c/env_class.html">DB_ENV</a> handle, created by the <a href="../../api_c/env_create.html">db_env_create</a> method, refers -to a Berkeley DB database environment -- a collection of Berkeley DB subsystems, -log files and databases. <a href="../../api_c/env_class.html">DB_ENV</a> handles are free-threaded if -the <a href="../../api_c/env_open.html#DB_THREAD">DB_THREAD</a> flag is specified to the <a href="../../api_c/env_open.html">DB_ENV->open</a> method when -the environment is opened. The handle should not be closed while any -other handle remains open that is using it as a reference (for example, -<a href="../../api_c/db_class.html">DB</a> or <a href="../../api_c/txn_class.html">DB_TXN</a>). Once either the <a href="../../api_c/env_close.html">DB_ENV->close</a> or -<a href="../../api_c/env_remove.html">DB_ENV->remove</a> methods are called, the handle may not be accessed again, -regardless of the function's return. -<p><dt><a href="../../api_c/txn_class.html">DB_TXN</a><dd>The <a href="../../api_c/txn_class.html">DB_TXN</a> handle, created by the <a href="../../api_c/txn_begin.html">DB_ENV->txn_begin</a> method, refers to -a single transaction. The handle is not free-threaded; and transactions -may not span threads, nor may transactions be used by more than a single -thread. Once the <a href="../../api_c/txn_abort.html">DB_TXN->abort</a> or <a href="../../api_c/txn_commit.html">DB_TXN->commit</a> methods are called, -the handle may not be accessed again, regardless of the function's -return. In addition, parent transactions may not issue any Berkeley DB -operations while they have active child transactions (child transactions -that have not yet been committed or aborted) except for -<a href="../../api_c/txn_begin.html">DB_ENV->txn_begin</a>, <a href="../../api_c/txn_abort.html">DB_TXN->abort</a> and <a href="../../api_c/txn_commit.html">DB_TXN->commit</a>. -<p><dt><a href="../../api_c/logc_class.html">DB_LOGC</a><dd>The <a href="../../api_c/logc_class.html">DB_LOGC</a> handle refers to a cursor into the log files. The -handle is not free-threaded. Once the <a href="../../api_c/logc_close.html">DB_LOGC->close</a> method is called, -the handle may not be accessed again, regardless of the function's -return. -<p><dt><a href="../../api_c/mempfile_class.html">DB_MPOOLFILE</a><dd>The <a href="../../api_c/mempfile_class.html">DB_MPOOLFILE</a> handle refers to an open file in the shared -memory buffer pool of the database environment. The handle is not -free-threaded. Once the <a href="../../api_c/memp_fclose.html">DB_MPOOLFILE->close</a> method is called, the handle may -not be accessed again, regardless of the function's return. -<p><dt><a href="../../api_c/db_class.html">DB</a><dd>The <a href="../../api_c/db_class.html">DB</a> handle, created by the <a href="../../api_c/db_create.html">db_create</a> method, refers to a -single Berkeley DB database, which may or may not be part of a database -environment. <a href="../../api_c/db_class.html">DB</a> handles are free-threaded if the -<a href="../../api_c/env_open.html#DB_THREAD">DB_THREAD</a> flag is specified to the <a href="../../api_c/db_open.html">DB->open</a> method when the -database is opened or if the database environment in which the database -is opened is free-threaded. The handle should not be closed while any -other handle that refers to the database is in use; for example, -database handles must not be closed while cursor handles into the -database remain open, or transactions that include operations on the -database have not yet been committed or aborted. Once the -<a href="../../api_c/db_close.html">DB->close</a>, <a href="../../api_c/db_remove.html">DB->remove</a>, or <a href="../../api_c/db_rename.html">DB->rename</a> methods are -called, the handle may not be accessed again, regardless of the -function's return. -<p><dt><a href="../../api_c/dbc_class.html">DBC</a><dd>The <a href="../../api_c/dbc_class.html">DBC</a> handle refers to a cursor into a Berkeley DB database. The -handle is not free-threaded, and cursors may not span threads; nor may -cursors be used by more than a single thread. If the cursor is to be -used to perform operations on behalf of a transaction, the cursor must -be opened and closed within the context of that single transaction. -Once <a href="../../api_c/dbc_close.html">DBcursor->c_close</a> has been called, the handle may not be accessed -again, regardless of the function's return. -</dl> -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/program/mt.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/program/namespace.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/libdb/docs/ref/program/solaris.txt b/libdb/docs/ref/program/solaris.txt deleted file mode 100644 index d2ec31682..000000000 --- a/libdb/docs/ref/program/solaris.txt +++ /dev/null @@ -1,213 +0,0 @@ -#ifdef OS_solaris - * This is all for Solaris 2.6. - * - * Sun defined a new API in Solaris2.6 to be used when manipulating large - * (>2Gbyte) files. This API isn't present in 2.5.x, so we can't simply - * call it -- that would mean two binaries, one for 2.5.x and the other for - * 2.6. Not pretty. So, what we do here is determine the OS on which we're - * running at runtime, and adjust the underlying Berkeley DB calls to use - * the new API if it's there. - */ - -/* This must match the definition of stat64 in Solaris2.6 */ -struct our_stat64 { - dev_t st_dev; - long st_pad1[3]; /* reserve for dev expansion */ - u_longlong_t st_ino; - mode_t st_mode; - nlink_t st_nlink; - uid_t st_uid; - gid_t st_gid; - dev_t st_rdev; - long st_pad2[2]; - longlong_t st_size; - timestruc_t mst_atime; - timestruc_t mst_mtime; - timestruc_t mst_ctime; - long st_blksize; - longlong_t st_blocks; /* large file support */ - char st_fstype[_ST_FSTYPSZ]; - long st_pad4[8]; /* expansion area */ -}; - -#define MEGABYTE (1024 * 1024) - -typedef int (*open_fn)(const char *path, int flags, ...); -typedef longlong_t (*lseek64_fn)(int fildes, longlong_t offset, int whence); -typedef longlong_t (*fstat64_fn)(int fildes, struct our_stat64 *s); -typedef void* (*mmap64_fn)(void* addr, size_t len, int prot, int flags, -int filedes, longlong_t off); - -static fstat64_fn os_fstat64_fn = NULL; -static lseek64_fn os_lseek64_fn = NULL; -static mmap64_fn os_mmap64_fn = NULL; -static open_fn os_open64_fn = NULL; - -static int dblayer_load_largefile_fns() -{ - void *lib_handle = NULL; - void *function_found = NULL; - int ret = 0; - - lib_handle = dlopen(NULL, RTLD_NOW); - if (NULL == lib_handle) - return (-1); - - function_found = dlsym(lib_handle,"open64"); - if (NULL == function_found) - return (-1); - os_open64_fn = (open_fn)function_found; - - function_found = dlsym(lib_handle,"lseek64"); - if (NULL == function_found) - return (-1); - os_lseek64_fn = (lseek64_fn)function_found; - - function_found = dlsym(lib_handle,"fstat64"); - if (NULL == function_found) - return (-1); - os_fstat64_fn = (fstat64_fn)function_found; - - function_found = dlsym(lib_handle,"mmap64"); - if (NULL == function_found) - return (-1); - os_mmap64_fn = (mmap64_fn)function_found; - - return 0; -} - -/* Helper function for large seeks */ -static int dblayer_seek_fn_solaris(int fd, - size_t pgsize, db_pgno_t pageno, u_long relative, int whence) -{ - longlong_t offset = 0; - longlong_t ret = 0; - - if (NULL == os_lseek64_fn) { - return -1; - } - - offset = (longlong_t)pgsize * pageno + relative; - - ret = (*os_lseek64_fn)(fd,offset,whence); - - return (ret == -1) ? errno : 0; -} - -/* Helper function for large file mmap */ -static int dblayer_map_solaris(fd, len, is_private, is_rdonly, addr) - int fd, is_private, is_rdonly; - size_t len; - void **addr; -{ - void *p; - int flags, prot; - - flags = is_private ? MAP_PRIVATE : MAP_SHARED; - prot = PROT_READ | (is_rdonly ? 0 : PROT_WRITE); - - if ((p = (*os_mmap64_fn)(NULL, - len, prot, flags, fd, (longlong_t)0)) == (void *)MAP_FAILED) - return (errno); - - *addr = p; - return (0); -} - -/* Helper function for large fstat */ -static int dblayer_ioinfo_solaris(const char *path, - int fd, u_int32_t *mbytesp, u_int32_t *bytesp, u_int32_t *iosizep) -{ - struct our_stat64 sb; - - if (NULL == os_fstat64_fn) { - return -1; - } - - if ((*os_fstat64_fn)(fd, &sb) == -1) - return (errno); - - /* Return the size of the file. */ - if (mbytesp != NULL) - *mbytesp = (u_int32_t) (sb.st_size / (longlong_t)MEGABYTE); - if (bytesp != NULL) - *bytesp = (u_int32_t) (sb.st_size % (longlong_t)MEGABYTE); - - /* - * Return the underlying filesystem blocksize, if available. Default - * to 8K on the grounds that most OS's use less than 8K as their VM - * page size. - */ - if (iosizep != NULL) - *iosizep = sb.st_blksize; - return (0); -} -#endif - -#ifdef irix - * A similar mess to Solaris: a new API added in IRIX6.2 to support large - * files. We always build on 6.2 or later, so no need to do the same song - * and dance as on Solaris -- we always have the header files for the - * 64-bit API. - */ - -/* Helper function for large seeks */ -static int dblayer_seek_fn_irix(int fd, - size_t pgsize, db_pgno_t pageno, u_long relative, int whence) -{ - off64_t offset = 0; - off64_t ret = 0; - - offset = (off64_t)pgsize * pageno + relative; - - ret = lseek64(fd,offset,whence); - - return (ret == -1) ? errno : 0; -} - -/* Helper function for large fstat */ -static int dblayer_ioinfo_irix(const char *path, - int fd, u_int32_t *mbytesp, u_int32_t *bytesp, u_int32_t *iosizep) -{ - struct stat64 sb; - - if (fstat64(fd, &sb) == -1) { - return (errno); - } - - /* Return the size of the file. */ - if (mbytesp != NULL) - *mbytesp = (u_int32_t) (sb.st_size / (off64_t)MEGABYTE); - if (bytesp != NULL) - *bytesp = (u_int32_t) (sb.st_size % (off64_t)MEGABYTE); - - if (iosizep != NULL) - *iosizep = sb.st_blksize; - return (0); -} -#endif /* irix */ - -static int dblayer_override_libdb_functions(dblayer_private *priv) -{ -#if defined(OS_solaris) - int ret = 0; - - ret = dblayer_load_largefile_fns(); - if (0 != ret) { - Debug("Not Solaris2.6: no large file support enabled\n"); - } else { - /* Means we did get the XXX64 functions, so let's use them */ - db_jump_set((void*)os_open64_fn, DB_FUNC_OPEN); - db_jump_set((void*)dblayer_seek_fn_solaris, DB_FUNC_SEEK); - db_jump_set((void*)dblayer_ioinfo_solaris, DB_FUNC_IOINFO); - db_jump_set((void*)dblayer_map_solaris, DB_FUNC_MAP); - Debug("Solaris2.6: selected 64-bit file handling.\n"); - } -#else -#if defined (irix) - db_jump_set((void*)dblayer_seek_fn_irix, DB_FUNC_SEEK); - db_jump_set((void*)dblayer_ioinfo_irix, DB_FUNC_IOINFO); -#endif /* irix */ -#endif /* OS_solaris */ - return 0; -} diff --git a/libdb/docs/ref/refs/bdb_usenix.html b/libdb/docs/ref/refs/bdb_usenix.html deleted file mode 100644 index 6ff321119..000000000 --- a/libdb/docs/ref/refs/bdb_usenix.html +++ /dev/null @@ -1,1120 +0,0 @@ -<!--"@(#)usenix.html 1.2 4/26/99"--> -<html> -<head> -<title>Berkeley DB</title> -</head> -<body bgcolor="white"> -<center> -<h1> -Berkeley DB -</h1> -<p> -<i> -Michael A. Olson -<br> -Keith Bostic -<br> -Margo Seltzer -<br> -<br> -Sleepycat Software, Inc. -<br> -<br> -</i> -<b> -Abstract -</b> -</center> -<font size="-1"> -<blockquote> -<p> -Berkeley DB is an Open Source embedded database system with a number -of key advantages over comparable systems. It is simple to use, supports -concurrent access by multiple users, and provides industrial-strength -transaction support, including surviving system and disk crashes. This -paper describes the design and technical features of Berkeley DB, the -distribution, and its license. -</blockquote> -</font> -<h1> -Introduction -</h1> -<p> -The Berkeley Database (Berkeley DB) is an embedded database system -that can be used in applications requiring high-performance -concurrent storage and retrieval of key/value pairs. The software -is distributed as a library that can be linked directly into an -application. -It provides a variety of programmatic interfaces, -including callable APIs for C, C++, Perl, Tcl and Java. -Users may download Berkeley DB from Sleepycat Software's Web site, -at -<a href="http://www.sleepycat.com">www.sleepycat.com</a>. -<p> -Sleepycat distributes Berkeley DB as an Open Source product. The company -collects license fees for certain uses of the software and sells support -and services. -<h2> -History -</h2> -<p> -Berkeley DB began as a new implementation of a hash access method -to replace both -<tt>hsearch</tt> -and the various -<tt>dbm</tt> -implementations -(<tt>dbm</tt> from AT&T, -<tt>ndbm</tt> -from Berkeley, and -<tt>gdbm</tt> -from the GNU project). -In 1990 Seltzer and Yigit produced a package called Hash to do this -<a href="#Selt91">[Selt91]</a>. -<p> -The first general release of Berkeley DB, in 1991, -included some interface changes and a new B+tree access method. -At roughly the same time, Seltzer and Olson -developed a prototype transaction -system based on Berkeley DB, called LIBTP <a href="#Selt92">[Selt92]</a>, -but never released the code. -<p> -The 4.4BSD UNIX release included Berkeley DB 1.85 in 1992. -Seltzer and Bostic maintained the code in the early 1990s -in Berkeley and in Massachusetts. -Many users adopted the code during this period. -<p> -By mid-1996, -users wanted commercial support for the software. -In response, Bostic and Seltzer formed Sleepycat Software. -The company enhances, distributes, and -supports Berkeley DB and supporting software and documentation. -Sleepycat released version 2.1 of Berkeley DB in mid-1997 -with important new features, including -support for concurrent access to databases. -The company makes about three commercial releases a year, -and most recently shipped version 2.8. -<h2> -Overview of Berkeley DB -</h2> -<p> -The C interfaces in Berkeley DB permit -<tt>dbm</tt>-style -record management -for databases, -with significant extensions to handle duplicate data items elegantly, -to deal with concurrent access, and to provide transactional -support so that multiple changes can be simultaneously committed -(so that they are made permanent) or rolled back (so that the -database is restored to its state at the beginning of the transaction). -<p> -C++ and Java interfaces provide a small set of classes for -operating on a database. The main class in both cases is called -<tt>Db</tt>, -and provides methods that encapsulate the -<tt>dbm</tt>-style -interfaces that the C interfaces provide. -<p> -Tcl and Perl interfaces allow developers working in those languages -to use Berkeley DB in their applications. -Bindings for both languages are included in the distribution. -<p> -Developers may compile their applications and link in Berkeley DB -statically or dynamically. -<h2> -How Berkeley DB is used -</h2> -<p> -The Berkeley DB library supports concurrent access to databases. -It can be linked -into standalone applications, into a collection of cooperating applications, -or into servers that handle requests and do database operations on -behalf of clients. -<p> -Compared to using a standalone database management system, Berkeley -DB is easy to understand and simple to use. The -software stores and retrieves records, which consist of key/value pairs. -Keys are used to locate items and can be any data type or structure -supported by the programming language. -<p> -The programmer can provide the functions that Berkeley DB uses to -operate on keys. -For example, -B+trees can use a custom comparison function, -and the Hash access method can use a custom hash function. -Berkeley DB uses default functions if none are supplied. -Otherwise, Berkeley DB does not examine or interpret either keys -or values in any way. -Values may be arbitrarily long. -<p> -It is also important to understand what Berkeley DB is not. -It is not a database server that handles network requests. It is not an -SQL engine that executes queries. It is not a relational or object-oriented -database management system. -<p> -It is possible to build any of those on top of Berkeley DB, -but the package, as distributed, -is an embedded database engine. It has been designed -to be portable, small, fast, and reliable. -<h2> -Applications that use Berkeley DB -</h2> -<p> -Berkeley DB is embedded in a variety of proprietary and Open Source -software packages. -This section highlights a few of the products that use it. -<p> -Directory servers, which do data storage and retrieval using the -Local Directory Access Protocol (LDAP), provide naming and directory -lookup service on local-area networks. -This service is, -essentially, -database query and update, -but uses a simple protocol rather than SQL or ODBC. -Berkeley DB is the embedded data manager in the majority of deployed -directory servers today, -including LDAP servers from Netscape, -MessageDirect (formerly Isode), -and others. -<p> -Berkeley DB is also embedded in a large number of mail servers. -Intermail, -from Software.com, -uses Berkeley DB as a message store -and as the backing store for its directory server. -The sendmail server -(including both the commercial Sendmail Pro offering from Sendmail, -Inc. and the version distributed by sendmail.org) -uses Berkeley DB to store aliases and other information. -Similarly, -Postfix (formerly VMailer) uses Berkeley DB -to store administrative information. -<p> -In addition, -Berkeley DB is embedded in a wide variety of other software products. -Example applications include managing access control lists, -storing user keys in a public-key infrastructure, -recording machine-to-network-address mappings in address servers, -and storing configuration and device information in video -post-production software. -<p> -Finally, -Berkeley DB is a part of many other Open Source software packages -available on the Internet. -For example, -the software is embedded in the Apache Web server and the Gnome desktop. -<h1> -Access Methods -</h1> -<p> -In database terminology, an access method is the disk-based structure -used to store data and the operations available on that structure. -For example, many database systems support a B+tree access method. -B+trees allow equality-based lookups (find keys equal to some constant), -range-based lookups (find keys between two constants) and record -insertion and deletion. -<p> -Berkeley DB supports three access methods: B+tree, -Extended Linear Hashing (Hash), -and Fixed- or Variable-length Records (Recno). -All three operate on records composed of a key and a data value. -In the B+tree and Hash access methods, keys can have arbitrary structure. -In the Recno access method, each record is assigned a record number, which -serves as the key. -In all the access methods, the -value can have arbitrary structure. -The programmer can supply comparison or hashing functions for keys, -and Berkeley DB stores and retrieves values without -interpreting them. -<p> -All of the access methods use the host filesystem as a backing store. -<h2> -Hash -</h2> -<p> -Berkeley DB includes a Hash access method that implements extended -linear hashing <a href="#Litw80">[Litw80]</a>. -Extended linear hashing adjusts the hash function as the hash -table grows, attempting to keep all buckets underfull in the steady -state. -<p> -The Hash access method supports insertion and deletion of records and -lookup by exact match only. Applications may iterate over all records -stored in a table, but the order in which they are returned is undefined. -<h2> -B+tree -</h2> -<p> -Berkeley DB includes a B+tree <a href="#Come79">[Come79]</a> access method. -B+trees store records of key/value pairs in leaf pages, -and pairs of (key, child page address) at internal nodes. -Keys in the tree are stored in sorted order, -where the order is determined by the comparison function supplied when the -database was created. -Pages at the leaf level of the tree include pointers -to their neighbors to simplify traversal. B+trees support lookup by -exact match (equality) or range (greater than or equal to a key). -Like Hash tables, B+trees support record insertion, -deletion, and iteration over all records in the tree. -<p> -As records are inserted and pages in the B+tree fill up, they are split, -with about half the keys going into a new peer page at the same level in -the tree. -Most B+tree implementations leave both nodes half-full after a split. -This leads to poor performance in a common case, where the caller inserts -keys in order. -To handle this case, Berkeley DB keeps track of the insertion order, -and splits pages unevenly to keep pages fuller. -This reduces tree size, yielding better search performance and smaller -databases. -<p> -On deletion, empty pages are coalesced by reverse splits -into single pages. -The access method does no other page balancing on insertion -or deletion. -Keys are not moved among pages at every update -to keep the tree well-balanced. While this could improve search times -in some cases, the additional code complexity leads to slower updates and -is prone to deadlocks. -<p> -For simplicity, Berkeley DB B+trees do no prefix compression of keys -at internal or leaf nodes. -<h2> -Recno -</h2> -<p> -Berkeley DB includes a fixed- or variable-length record access method, -called -<i>Recno</i>. -The Recno access method assigns logical record numbers to each -record, -and can search for and update records by record number. -Recno is able, -for example, -to load a text file into a database, -treating each line as a record. -This permits fast searches by line number for applications like -text editors <a href="#Ston82">[Ston82]</a>. -<p> -Recno is actually built -on top of the B+tree access method and provides a simple interface -for storing sequentially-ordered data values. -The Recno access method generates keys internally. -The programmer's view of the values is that -they are numbered sequentially from one. -Developers can choose to have records automatically renumbered -when lower-numbered records are added or deleted. -In this case, new keys can be inserted between existing keys. -<h1> -Features -</h1> -<p> -This section describes important features of Berkeley DB. -In general, -developers can choose which features are useful to them, -and use only those that are required by their application. -<p> -For example, -when an application opens a database, it can declare the degree of -concurrency and recovery that it requires. Simple stand-alone applications, -and in particular ports of applications that used -<tt>dbm</tt> -or one of its -variants, generally do not require concurrent access or crash recovery. -Other applications, such as enterprise-class database management systems -that store sales transactions or other critical data, need full -transactional service. Single-user operation is faster than multi-user -operation, since no overhead is incurred by locking. Running with -the recovery system disabled is faster than running with it enabled, -since log records need not be written when changes are made to the -database. -<p> -In addition, some core subsystems, including the locking system and -the logging facility, -can be used outside the context of the access methods as well. -Although few users have chosen to do so, it is possible to -use only the lock manager in Berkeley DB to control concurrency -in an application, without using any of the standard database services. -Alternatively, the caller can integrate locking of non-database resources -with Berkeley DB's transactional two-phase locking system, to impose -transaction semantics on objects outside the database. -<h2> -Programmatic interfaces -</h2> -<p> -Berkeley DB defines a simple API for database management. -The package does not include industry-standard -programmatic interfaces such as Open Database Connectivity (ODBC), -Object Linking and Embedding for Databases (OleDB), or Structured -Query Language (SQL). These interfaces, while useful, were -designed to promote interoperability of database systems, and not -simplicity or performance. -<p> -In response to customer demand, -Berkeley DB 2.5 introduced support for the XA standard <a href="#Open94">[Open94]</a>. -XA permits Berkeley DB to participate in distributed transactions -under a transaction processing monitor like Tuxedo from BEA Systems. -Like XA, other standard interfaces can be built on top of the -core system. -The standards do not belong inside Berkeley DB, -since not all applications need them. -<h2> -Working with records -</h2> -<p> -A database user may need to search for particular keys in a database, -or may simply want to browse available records. -Berkeley DB supports both keyed access, -to find one or more records with a given key, -or sequential access, -to retrieve all the records in the database one at a time. -The order of the records returned during sequential scans -depends on the access method. -B+tree and Recno databases return records in sort order, -and Hash databases return them in apparently random order. -<p> -Similarly, -Berkeley DB defines simple interfaces for inserting, -updating, -and deleting records in a database. -<h2> -Long keys and values -</h2> -<p> -Berkeley DB manages keys and values as large as -2<sup>32</sup> bytes. -Since the time required to copy a record is proportional to its size, -Berkeley DB includes interfaces that operate on partial records. -If an application requires only part of a large record, -it requests partial record retrieval, -and receives just the bytes that it needs. -The smaller copy saves both time and memory. -<p> -Berkeley DB allows the programmer to define the data types of -keys and values. -Developers use any type expressible in the programming language. -<h2> -Large databases -</h2> -<p> -A single database managed by Berkeley DB can be up to 2<sup>48</sup> -bytes, -or 256 petabytes, -in size. -Berkeley DB uses the host filesystem as the backing store -for the database, -so large databases require big file support from the operating system. -Sleepycat Software has customers using Berkeley DB -to manage single databases in excess of 100 gigabytes. -<h2> -Main memory databases -</h2> -<p> -Applications that do not require persistent storage can create -databases that exist only in main memory. -These databases bypass the overhead imposed by the I/O system -altogether. -<p> -Some applications do need to use disk as a backing store, -but run on machines with very large memory. -Berkeley DB is able to manage very large shared memory regions -for cached data pages, -log records, -and lock management. -For example, -the cache region used for data pages may be gigabytes in size, -reducing the likelihood that any read operation will need to -visit the disk in the steady state. -The programmer declares the size of the cache region at -startup. -<p> -Finally, many operating systems provide memory-mapped file services -that are much faster than their general-purpose file system -interfaces. -Berkeley DB can memory-map its database files for read-only database use. -The application operates on records stored directly on the pages, -with no cache management overhead. -Because the application gets pointers directly into the -Berkeley DB pages, -writes cannot be permitted. -Otherwise, -changes could bypass the locking and logging systems, -and software errors could corrupt the database. -Read-only applications can use Berkeley DB's memory-mapped -file service to improve performance on most architectures. -<h2> -Configurable page size -</h2> -<p> -Programmers declare the size of the pages used by their access -methods when they create a database. -Although Berkeley DB provides reasonable defaults, -developers may override them to control system performance. -Small pages reduce the number of records that fit on a single page. -Fewer records on a page means that fewer records are locked when -the page is locked, -improving concurrency. -The per-page overhead is proportionally higher with smaller pages, -of course, -but developers can trade off space for time as an application requires. -<h2> -Small footprint -</h2> -<p> -Berkeley DB is a compact system. -The full package, including all access methods, recoverability, -and transaction support -is roughly 175K of text space on common architectures. -<h2> -Cursors -</h2> -<p> -In database terminology, a cursor is a pointer into an access method -that can be called iteratively to return records in sequence. Berkeley -DB includes cursor interfaces for all access methods. This permits, -for example, users to traverse a B+tree and view records in order. -Pointers to records in cursors are persistent, so that once fetched, -a record may be updated in place. Finally, cursors support access to -chains of duplicate data items in the various access methods. -<h2> -Joins -</h2> -<p> -In database terminology, -a join is an operation that spans multiple separate -tables (or in the case of Berkeley DB, multiple separate DB files). -For example, a company may store information about its customers -in one table and information about sales in another. An application -will likely want to look up sales information by customer name; this -requires matching records in the two tables that share a common -customer ID field. -This combining of records from multiple tables is called a join. -<p> -Berkeley DB includes interfaces for joining two or more tables. -<h2> -Transactions -</h2> -<p> -Transactions have four properties <a href="#Gray93">[Gray93]</a>: -<ul> -<li> -They are atomic. That is, all of the changes made in a single -transaction must be applied at the same instant or not at all. -This permits, for example, the transfer of money between two -accounts to be accomplished, by making the reduction of the -balance in one account and the increase in the other into a -single, atomic action. -</li> -<li> -They must be consistent. That is, changes to the database -by any transaction cannot leave the database in an illegal -or corrupt state. -</li> -<li> -They must be isolatable. Regardless of the number of users -working in the database at the same time, every user must have -the illusion that no other activity is going on. -</li> -<li> -They must be durable. Even if the disk that stores the database -is lost, it must be possible to recover the database to its last -transaction-consistent state. -</li> -</ul> -<p> -This combination of properties -- atomicity, consistency, isolation, and -durability -- is referred to as ACIDity in the literature. Berkeley DB, -like most database systems, provides ACIDity using a collection of core -services. -<p> -Programmers can choose to use Berkeley DB's transaction services -for applications that need them. -<h3> -Write-ahead logging -</h3> -<p> -Programmers can enable the logging system when they start up Berkeley DB. -During a transaction, -the application makes a series of changes to the database. -Each change is captured in a log entry, -which holds the state of the database record -both before and after the change. -The log record is guaranteed -to be flushed to stable storage before any of the changed data pages -are written. -This behavior -- writing the log before the data pages -- is called -<i>write-ahead logging</i>. -<p> -At any time during the transaction, -the application can -<i>commit</i>, -making the changes permanent, -or -<i>roll back</i>, -cancelling all changes and restoring the database to its -pre-transaction state. -If the application -rolls back the transaction, then the log holds the state of all -changed pages prior to the transaction, and Berkeley DB simply -restores that state. -If the application commits the transaction, -Berkeley DB writes the log records to disk. -In-memory copies of the data pages already reflect the changes, -and will be flushed as necessary during normal processing. -Since log writes are sequential, but data page -writes are random, this improves performance. -<h3> -Crashes and recovery -</h3> -<p> -Berkeley DB's write-ahead log is used by the transaction -system to commit or roll back transactions. -It also gives the recovery system the information that -it needs to protect against data loss or corruption -from crashes. -Berkeley DB is able to survive application crashes, -system crashes, -and even catastrophic failures like the loss of a hard -disk, -without losing any data. -<p> -Surviving crashes requires data stored in several different places. -During normal processing, -Berkeley DB has copies of active log records and recently-used -data pages in memory. -Log records are flushed to the log disk when transactions commit. -Data pages trickle out to the data disk as pages move through -the buffer cache. -Periodically, -the system administrator backs up the data disk, -creating a safe copy of the database at a particular instant. -When the database is backed up, -the log can be truncated. -For maximum robustness, -the log disk and data disk should be separate devices. -<p> -Different system failures can destroy memory, -the log disk, -or the data disk. -Berkeley DB is able to survive the loss of any one -of these repositories -without losing any committed transactions. -<p> -If the computer's memory is lost, -through an application or operating system crash, -then the log holds all committed transactions. -On restart, -the recovery system rolls the log forward against -the database, -reapplying any changes to on-disk pages that were in memory at the -time of the crash. -Since the log contains pre- and post-change state for -transactions, -the recovery system also uses the log to restore any pages to -their original state if they were modified by transactions -that never committed. -<p> -If the data disk is lost, -the system administrator can restore the most recent copy from backup. -The recovery system will roll the entire log forward against -the original database, -reapplying all committed changes. -When it finishes, -the database will contain every change made by every -transaction that ever committed. -<p> -If the log disk is lost, -then the recovery system can use the in-memory copies of -log entries to roll back any uncommitted transactions, -flush all in-memory database pages to the data disk, -and shut down gracefully. -At that point, -the system administrator can back up the database disk, -install a new log disk, -and restart the system. -<h3> -Checkpoints -</h3> -<p> -Berkeley DB includes a checkpointing service that interacts -with the recovery system. -During normal processing, -both the log and the database are changing continually. -At any given instant, -the on-disk versions of the two are not guaranteed to be consistent. -The log probably contains changes that are not yet in the database. -<p> -When an application makes a -<i>checkpoint</i>, -all committed changes in the log up to that point -are guaranteed to be present on the data disk, -too. -Checkpointing is moderately expensive during normal processing, -but limits the time spent recovering from crashes. -<p> -After an application or operating system crash, -the recovery system only needs to go back two checkpoints -to start rolling the log forward. -(One checkpoint is not far enough. -The recovery system cannot be sure that the most recent -checkpoint completed -- -it may have been interrupted by the crash that forced the -recovery system to run in the first place.) -Without checkpoints, -there is no way to be sure how long restarting after a crash will take. -With checkpoints, -the restart interval can be fixed by the programmer. -Recovery processing can be guaranteed to complete in a second or two. -<p> -Software crashes are much more common than disk failures. -Many developers want to guarantee that software bugs do not destroy data, -but are willing to restore from tape, -and to tolerate a day or two of lost work, -in the unlikley event of a disk crash. -With Berkeley DB, -programmers may truncate the log at checkpoints. -As long as the two most recent checkpoints are present, -the recovery system can guarantee that no committed transactions -are lost after a software crash. -In this case, -the recovery system does not require that the log and the -data be on separate devices, -although separating them can still improve performance -by spreading out writes. -<h3> -Two-phase locking -</h3> -<p> -Berkeley DB provides a service known as two-phase locking. -In order to reduce the likelihood of deadlocks and to guarantee ACID -properties, database systems manage locks in two phases. First, during -the operation of a transaction, they acquire locks, but never release -them. Second, at the end of the transaction, they release locks, but -never acquire them. In practice, most database systems, including Berkeley -DB, acquire locks on demand over the course of the transaction, then -flush the log, then release all locks. -<p> -Berkeley DB can lock entire database files, which correspond to tables, -or individual pages in them. -It does no record-level locking. -By shrinking the page size, -however, -developers can guarantee that every page holds only a small -number of records. -This reduces contention. -<p> -If locking is enabled, -then read and write operations on a database acquire two-phase locks, -which are held until the transaction completes. -Which objects are locked and the order of lock acquisition -depend on the workload for each transaction. -It is possible for two or more transactions to deadlock, -so that each is waiting for a lock that is held by another. -<p> -Berkeley DB detects deadlocks and automatically rolls back -one of the transactions. -This releases the locks that it held -and allows the other transactions to continue. -The caller is notified that its transaction did not complete, -and may restart it. -Developers can specify the deadlock detection interval -and the policy to use in choosing a transaction to roll back. -<p> -The two-phase locking interfaces are separately callable by applications -that link Berkeley DB, though few users have needed to use that facility -directly. -Using these interfaces, -Berkeley DB provides a fast, -platform-portable locking system for general-purpose use. -It also lets users include non-database objects in a database transaction, -by controlling access to them exactly as if they were inside the database. -<p> -The Berkeley DB two-phase locking facility is built on the fastest correct -locking primitives that are supported by the underlying architecture. -In the current implementation, this means that the locking system is -different on the various UNIX platforms, and is still more different -on Windows NT. In our experience, the most difficult aspect of performance -tuning is finding the fastest locking primitives that work correctly -on a particular architecture and then integrating the new -interface with the several that we already support. -<p> -The world would be a better place if the operating systems community -would uniformly implement POSIX locking primitives and would guarantee -that acquiring an uncontested lock was a fast operation. -Locks must work both among threads in a single process -and among processes. -<h2> -Concurrency -</h2> -<p> -Good performance under concurrent operation is a critical design point -for Berkeley DB. Although Berkeley DB is itself not multi-threaded, -it is thread-safe, and runs well in threaded applications. -Philosophically, -we view the use of threads and the choice of a threads package -as a policy decision, -and prefer to offer mechanism (the ability to run threaded or not), -allowing applications to choose their own policies. -<p> -The locking, logging, and buffer pool subsystems all use shared memory -or other OS-specific sharing facilities to communicate. Locks, buffer -pool fetches, and log writes behave in the same way across threads in -a single process as they do across different processes on a single -machine. -<p> -As a result, concurrent database applications may start up a new process -for every single user, may create a single server which spawns a new -thread for every client request, or may choose any policy in between. -<p> -Berkeley DB has been carefully designed to minimize contention -and maximize concurrency. -The cache manager allows all threads or processes to benefit from -I/O done by one. -Shared resources must sometimes be locked for exclusive access -by one thread of control. -We have kept critical sections small, -and are careful not to hold critical resource locks across -system calls that could deschedule the locking thread or process. -Sleepycat Software has customers with hundreds of concurrent -users working on a single database in production. -<h1> -Engineering Philosophy -</h1> -<p> -Fundamentally, Berkeley DB is a collection of access methods with -important facilities, like logging, locking, and transactional access -underlying them. In both the research and the commercial world, -the techniques for building systems like Berkeley DB have been well-known -for a long time. -<p> -The key advantage of Berkeley DB is the careful attention that has been -paid to engineering details throughout its life. We have carefully -designed the system so that the core facilities, like locking and I/O, -surface the right interfaces and are otherwise opaque to the caller. -As programmers, we understand the value of simplicity and have worked -hard to simplify the interfaces we surface to users of the -database system. -<p> -Berkeley DB avoids limits in the code. It places no practical limit -on the size of keys, values, or databases; they may grow to occupy -the available storage space. -<p> -The locking and logging subsystems have been carefully crafted to -reduce contention and improve throughput by shrinking or eliminating -critical sections, and reducing the sizes of locked regions and log -entries. -<p> -There is nothing in the design or implementation of Berkeley DB that -pushes the state of the art in database systems. Rather, we have been -very careful to get the engineering right. The result is a system that -is superior, as an embedded database system, to any other solution -available. -<p> -Most database systems trade off simplicity for correctness. Either the -system is easy to use, or it supports concurrent use and survives system -failures. Berkeley DB, because of its careful design and implementation, -offers both simplicity and correctness. -<p> -The system has a small footprint, -makes simple operations simple to carry out (inserting a new record takes -just a few lines of code), and behaves correctly in the face of heavy -concurrent use, system crashes, and even catastrophic failures like loss -of a hard disk. -<h1> -The Berkeley DB 2.x Distribution -</h1> -<p> -Berkeley DB is distributed in source code form from -<a href="http://www.sleepycat.com">www.sleepycat.com</a>. -Users are free to download and build the software, and to use it in -their applications. -<h2> -What is in the distribution -</h2> -<p> -The distribution is a compressed archive file. -It includes the source code for the Berkeley DB library, -as well as documentation, test suites, and supporting utilities. -<p> -The source code includes build support for all supported platforms. -On UNIX systems Berkeley DB uses the GNU autoconfiguration tool, -<tt>autoconf</tt>, -to identify the system and to build the library -and supporting utilities. -Berkeley DB includes specific build environments for other platforms, -such as VMS and Windows. -<h3> -Documentation -</h3> -<p> -The distributed system includes documentation in HTML format. -The documentation is in two parts: -a UNIX-style reference manual for use by programmers, -and a reference guide which is tutorial in nature. -<h3> -Test suite -</h3> -<p> -The software also includes a complete test suite, written in Tcl. -We believe that the test suite is a key advantage of Berkeley DB -over comparable systems. -<p> -First, the test suite allows users who download and build the software -to be sure that it is operating correctly. -<p> -Second, the test suite allows us, like other commercial developers -of database software, to exercise the system thoroughly at every -release. When we learn of new bugs, we add them to the test suite. -We run the test suite continually during development cycles, and -always prior to release. The result is a much more reliable system -by the time it reaches beta release. -<h2> -Binary distribution -</h2> -<p> -Sleepycat makes compiled libraries and general binary distributions available -to customers for a fee. -<h2> -Supported platforms -</h2> -<p> -Berkeley DB runs on any operating system with a -POSIX 1003.1 interface <a href="#IEEE96">[IEEE96]</a>, -which includes virtually every UNIX system. -In addition, -the software runs on VMS, -Windows/95, -Windows/98, -and Windows/NT. -Sleepycat Software no longer supports deployment on sixteen-bit -Windows systems. -<h1> -Berkeley DB 2.x Licensing -</h1> -<p> -Berkeley DB 2.x is distributed as an Open Source product. The software -is freely available from us at our Web site, and in other media. Users -are free to download the software and build applications with it. -<p> -The 1.x versions of Berkeley DB were covered by the UC Berkeley copyright -that covers software freely redistributable in source form. When -Sleepycat Software was formed, we needed to draft a license consistent -with the copyright governing the existing, older software. Because -of important differences between the UC Berkeley copyright and the GPL, -it was impossible for us to use the GPL. -A second copyright, with -terms contradictory to the first, simply would not have worked. -<p> -Sleepycat wanted to continue Open Source development of Berkeley DB -for several reasons. -We agree with Raymond <a href="#Raym98">[Raym98]</a> and others that Open -Source software is typically of higher quality than proprietary, -binary-only products. -Our customers benefit from a community of developers who -know and use Berkeley DB, -and can help with application design, -debugging, -and performance tuning. -Widespread distribution and use of the source code tends to -isolate bugs early, -and to get fixes back into the distributed system quickly. -As a result, -Berkeley DB is more reliable. -Just as importantly, -individual users are able to contribute new features -and performance enhancements, -to the benefit of everyone who uses Berkeley DB. -From a business perspective, -Open Source and free distribution of the -software creates share for us, and gives us a market into which -we can sell products and services. -Finally, making the source code -freely available reduces our support load, since customers can -find and fix bugs without recourse to us, in many cases. -<p> -To preserve the Open Source heritage of the older Berkeley DB code, -we drafted a new license governing the distribution of Berkeley DB -2.x. We adopted terms from the GPL that make it impossible to -turn our Open Source code into proprietary code owned by someone else. -<p> -Briefly, the terms governing the use and distribution of Berkeley DB -are: -<ul> -<li> -your application must be internal to your site, or -</li> -<li> -your application must be freely redistributable in source form, or -</li> -<li> -you must get a license from us. -</li> -</ul> -<p> -For customers who prefer not to distribute Open Source products, -we sell licenses to use and extend Berkeley DB at a reasonable cost. -<p> -We work hard to accommodate the needs of the Open Source community. -For example, -we have crafted special licensing arrangements with Gnome -to encourage its use and distribution of Berkeley DB. -<p> -Berkeley DB conforms to the Open Source definition <a href="#Open99">[Open99]</a>. -The license has -been carefully crafted to keep the product available as an Open Source -offering, -while providing enough of a return on our investment to fund continued -development and support of the product. The current license has -created a business capable of funding three years of development on -the software that simply would not have happened otherwise. -<h1> -Summary -</h1> -<p> -Berkeley DB offers a unique collection of features, targeted squarely -at software developers who need simple, reliable database management -services in their applications. Good design and implementation and -careful engineering throughout make the software better than many -other systems. -<p> -Berkeley DB is an Open Source product, available at -<a href="http://www.sleepycat.com">www.sleepycat.com</a>. -for download. The distributed system includes everything needed to -build and deploy the software or to port it to new systems. -<p> -Sleepycat Software distributes Berkeley DB under a license agreement -that draws on both the UC Berkeley copyright and the GPL. The license -guarantees that Berkeley DB will remain an Open Source product and -provides Sleepycat with opportunities to make money to fund continued -development on the software. -<h1> -References -</h1> -<table border=0 cellpadding=4 cellspacing=2> -<tr> -<td valign="top"><a name="Come79">[Come79]</a></td> -<td> -<p> -Comer, D., -"The Ubiquitous B-tree," -<i>ACM Computing Surveys</i> -Volume 11, number 2, -June 1979. -</td> -</tr> -<tr> -<td valign="top"> -<a name="Gray93">[Gray93]</a> -</td> -<td> -<p> -Gray, J., and Reuter, A., -<i>Transaction Processing: Concepts and Techniques</i>, -Morgan-Kaufman Publishers, -1993. -</td> -</tr> -<tr> -<td valign="top"> -<a name="IEEE96">[IEEE96]</a> -</td> -<td> -<p> -Institute for Electrical and Electronics Engineers, -<i>IEEE/ANSI Std 1003.1</i>, -1996 Edition. -</td> -</tr> -<tr> -<td valign="top"> -<a name="Litw80">[Litw80]</a> -</td> -<td> -<p> -Litwin, W., -"Linear Hashing: A New Tool for File and Table Addressing," -<i>Proceedings of the 6th International Conference on Very Large Databases (VLDB)</i>, -Montreal, Quebec, Canada, -October 1980. -</td> -</tr> -<tr> -<td valign="top"> -<a name="Open94">[Open94]</a> -</td> -<td> -<p> -The Open Group, -<i>Distributed TP: The XA+ Specification, Version 2</i>, -The Open Group, 1994. -</td> -</tr> -<tr> -<td valign="top"> -<a name="Open99">[Open99]</a> -</td> -<td> -<p> -Opensource.org, -"Open Source Definition," -<a href="http://www.opensource.org/osd.html"><i>www.opensource.org/osd.html</i></a>, -version 1.4, -1999. -</td> -</tr> -<tr> -<td valign="top"> -<a name="Raym98">[Raym98]</a> -</td> -<td> -<p> -Raymond, E.S., -"The Cathedral and the Bazaar," -<a href="http://www.tuxedo.org/~esr/writings/cathedral-bazaar/"> -www.tuxedo.org/~esr/writings/cathedral-bazaar/cathedral-bazaar.html</a>, -January 1998. -</td> -</tr> -<tr> -<td valign="top"> -<a name="Selt91">[Selt91]</a> -</td> -<td> -<p> -Seltzer, M., and Yigit, O., -"A New Hashing Package for UNIX," -<i>Proceedings 1991 Winter USENIX Conference</i>, -Dallas, TX, -January 1991. -</td> -</tr> -<tr> -<td valign="top"> -<a name="Selt92">[Selt92]</a> -</td> -<td> -<p> -Seltzer, M., and Olson, M., -"LIBTP: Portable Modular Transactions for UNIX," -<i>Proceedings 1992 Winter Usenix Conference</i> -San Francisco, CA, -January 1992.] -</td> -</tr> -<tr> -<td valign="top"> -<a name="Ston82">[Ston82]</a> -</td> -<td> -<p> -Stonebraker, M., Stettner, H., Kalash, J., Guttman, A., and Lynn, N., -"Document Processing in a Relational Database System," -Memorandum No. UCB/ERL M82/32, -University of California at Berkeley, -Berkeley, CA, -May 1982. -</td> -</tr> -</table> -</body> -</html> diff --git a/libdb/docs/ref/refs/bdb_usenix.ps b/libdb/docs/ref/refs/bdb_usenix.ps deleted file mode 100644 index 82e678971..000000000 --- a/libdb/docs/ref/refs/bdb_usenix.ps +++ /dev/null @@ -1,1441 +0,0 @@ -%!PS-Adobe-3.0 -%%Creator: groff version 1.11 -%%CreationDate: Mon Apr 26 13:38:12 1999 -%%DocumentNeededResources: font Times-Bold -%%+ font Times-Roman -%%+ font Times-Italic -%%+ font Courier -%%DocumentSuppliedResources: procset grops 1.11 0 -%%Pages: 9 -%%PageOrder: Ascend -%%Orientation: Portrait -%%EndComments -%%BeginProlog -%%BeginResource: procset grops 1.11 0 -/setpacking where{ -pop -currentpacking -true setpacking -}if -/grops 120 dict dup begin -/SC 32 def -/A/show load def -/B{0 SC 3 -1 roll widthshow}bind def -/C{0 exch ashow}bind def -/D{0 exch 0 SC 5 2 roll awidthshow}bind def -/E{0 rmoveto show}bind def -/F{0 rmoveto 0 SC 3 -1 roll widthshow}bind def -/G{0 rmoveto 0 exch ashow}bind def -/H{0 rmoveto 0 exch 0 SC 5 2 roll awidthshow}bind def -/I{0 exch rmoveto show}bind def -/J{0 exch rmoveto 0 SC 3 -1 roll widthshow}bind def -/K{0 exch rmoveto 0 exch ashow}bind def -/L{0 exch rmoveto 0 exch 0 SC 5 2 roll awidthshow}bind def -/M{rmoveto show}bind def -/N{rmoveto 0 SC 3 -1 roll widthshow}bind def -/O{rmoveto 0 exch ashow}bind def -/P{rmoveto 0 exch 0 SC 5 2 roll awidthshow}bind def -/Q{moveto show}bind def -/R{moveto 0 SC 3 -1 roll widthshow}bind def -/S{moveto 0 exch ashow}bind def -/T{moveto 0 exch 0 SC 5 2 roll awidthshow}bind def -/SF{ -findfont exch -[exch dup 0 exch 0 exch neg 0 0]makefont -dup setfont -[exch/setfont cvx]cvx bind def -}bind def -/MF{ -findfont -[5 2 roll -0 3 1 roll -neg 0 0]makefont -dup setfont -[exch/setfont cvx]cvx bind def -}bind def -/level0 0 def -/RES 0 def -/PL 0 def -/LS 0 def -/MANUAL{ -statusdict begin/manualfeed true store end -}bind def -/PLG{ -gsave newpath clippath pathbbox grestore -exch pop add exch pop -}bind def -/BP{ -/level0 save def -1 setlinecap -1 setlinejoin -72 RES div dup scale -LS{ -90 rotate -}{ -0 PL translate -}ifelse -1 -1 scale -}bind def -/EP{ -level0 restore -showpage -}bind def -/DA{ -newpath arcn stroke -}bind def -/SN{ -transform -.25 sub exch .25 sub exch -round .25 add exch round .25 add exch -itransform -}bind def -/DL{ -SN -moveto -SN -lineto stroke -}bind def -/DC{ -newpath 0 360 arc closepath -}bind def -/TM matrix def -/DE{ -TM currentmatrix pop -translate scale newpath 0 0 .5 0 360 arc closepath -TM setmatrix -}bind def -/RC/rcurveto load def -/RL/rlineto load def -/ST/stroke load def -/MT/moveto load def -/CL/closepath load def -/FL{ -currentgray exch setgray fill setgray -}bind def -/BL/fill load def -/LW/setlinewidth load def -/RE{ -findfont -dup maxlength 1 index/FontName known not{1 add}if dict begin -{ -1 index/FID ne{def}{pop pop}ifelse -}forall -/Encoding exch def -dup/FontName exch def -currentdict end definefont pop -}bind def -/DEFS 0 def -/EBEGIN{ -moveto -DEFS begin -}bind def -/EEND/end load def -/CNT 0 def -/level1 0 def -/PBEGIN{ -/level1 save def -translate -div 3 1 roll div exch scale -neg exch neg exch translate -0 setgray -0 setlinecap -1 setlinewidth -0 setlinejoin -10 setmiterlimit -[]0 setdash -/setstrokeadjust where{ -pop -false setstrokeadjust -}if -/setoverprint where{ -pop -false setoverprint -}if -newpath -/CNT countdictstack def -userdict begin -/showpage{}def -}bind def -/PEND{ -clear -countdictstack CNT sub{end}repeat -level1 restore -}bind def -end def -/setpacking where{ -pop -setpacking -}if -%%EndResource -%%IncludeResource: font Times-Bold -%%IncludeResource: font Times-Roman -%%IncludeResource: font Times-Italic -%%IncludeResource: font Courier -grops begin/DEFS 1 dict def DEFS begin/u{.001 mul}bind def end/RES 72 -def/PL 792 def/LS false def/ENC0[/asciicircum/asciitilde/Scaron/Zcaron -/scaron/zcaron/Ydieresis/trademark/quotesingle/.notdef/.notdef/.notdef -/.notdef/.notdef/.notdef/.notdef/.notdef/.notdef/.notdef/.notdef/.notdef -/.notdef/.notdef/.notdef/.notdef/.notdef/.notdef/.notdef/.notdef/.notdef -/.notdef/.notdef/space/exclam/quotedbl/numbersign/dollar/percent -/ampersand/quoteright/parenleft/parenright/asterisk/plus/comma/hyphen -/period/slash/zero/one/two/three/four/five/six/seven/eight/nine/colon -/semicolon/less/equal/greater/question/at/A/B/C/D/E/F/G/H/I/J/K/L/M/N/O -/P/Q/R/S/T/U/V/W/X/Y/Z/bracketleft/backslash/bracketright/circumflex -/underscore/quoteleft/a/b/c/d/e/f/g/h/i/j/k/l/m/n/o/p/q/r/s/t/u/v/w/x/y -/z/braceleft/bar/braceright/tilde/.notdef/quotesinglbase/guillemotleft -/guillemotright/bullet/florin/fraction/perthousand/dagger/daggerdbl -/endash/emdash/ff/fi/fl/ffi/ffl/dotlessi/dotlessj/grave/hungarumlaut -/dotaccent/breve/caron/ring/ogonek/quotedblleft/quotedblright/oe/lslash -/quotedblbase/OE/Lslash/.notdef/exclamdown/cent/sterling/currency/yen -/brokenbar/section/dieresis/copyright/ordfeminine/guilsinglleft -/logicalnot/minus/registered/macron/degree/plusminus/twosuperior -/threesuperior/acute/mu/paragraph/periodcentered/cedilla/onesuperior -/ordmasculine/guilsinglright/onequarter/onehalf/threequarters -/questiondown/Agrave/Aacute/Acircumflex/Atilde/Adieresis/Aring/AE -/Ccedilla/Egrave/Eacute/Ecircumflex/Edieresis/Igrave/Iacute/Icircumflex -/Idieresis/Eth/Ntilde/Ograve/Oacute/Ocircumflex/Otilde/Odieresis -/multiply/Oslash/Ugrave/Uacute/Ucircumflex/Udieresis/Yacute/Thorn -/germandbls/agrave/aacute/acircumflex/atilde/adieresis/aring/ae/ccedilla -/egrave/eacute/ecircumflex/edieresis/igrave/iacute/icircumflex/idieresis -/eth/ntilde/ograve/oacute/ocircumflex/otilde/odieresis/divide/oslash -/ugrave/uacute/ucircumflex/udieresis/yacute/thorn/ydieresis]def -/Courier@0 ENC0/Courier RE/Times-Italic@0 ENC0/Times-Italic RE -/Times-Roman@0 ENC0/Times-Roman RE/Times-Bold@0 ENC0/Times-Bold RE -%%EndProlog -%%Page: 1 1 -%%BeginPageSetup -BP -%%EndPageSetup -/F0 14/Times-Bold@0 SF(Berk)275.358 100.8 Q(eley DB)-.14 E/F1 12 -/Times-Roman@0 SF(Michael A. Olson)270.372 129.6 Q -.3(Ke)283.182 144 S -(ith Bostic).3 E(Mar)279.15 158.4 Q(go Seltzer)-.216 E/F2 12 -/Times-Italic@0 SF(Sleepycat Softwar)255.492 174.24 Q .24 -.12(e, I) --.444 H(nc.).12 E/F3 12/Times-Bold@0 SF(Abstract)290.874 210.24 Q/F4 10 -/Times-Roman@0 SF(Berk)79.2 226.44 Q(ele)-.1 E 2.925(yD)-.15 G 2.925(Bi) --2.925 G 2.924(sa)-2.925 G 2.924(nO)-2.924 G .424 -(pen Source embedded database system with a number of k)-2.924 F .724 --.15(ey a)-.1 H(dv).15 E .424(antages o)-.25 F -.15(ve)-.15 G 2.924(rc) -.15 G .424(omparable sys-)-2.924 F 3.102(tems. It)79.2 238.44 R .602(is simple to use, supports concurrent access by multiple users, and pro) -3.102 F .602(vides industrial-strength transaction)-.15 F 1.555 -(support, including survi)79.2 250.44 R 1.555 -(ving system and disk crashes.)-.25 F 1.554 -(This paper describes the design and technical features of)6.555 F(Berk) -79.2 262.44 Q(ele)-.1 E 2.5(yD)-.15 G(B, the distrib)-2.5 E -(ution, and its license.)-.2 E F3 3(1. Intr)79.2 286.44 R(oduction)-.216 -E F4 .691(The Berk)79.2 302.64 R(ele)-.1 E 3.191(yD)-.15 G .691 -(atabase \(Berk)-3.191 F(ele)-.1 E 3.191(yD)-.15 G .692 -(B\) is an embedded)-3.191 F .253 -(database system that can be used in applications requir)79.2 314.64 R -(-)-.2 E 1.636(ing high-performance concurrent storage and retrie)79.2 -326.64 R -.25(va)-.25 G(l).25 E 2.619(of k)79.2 338.64 R -.15(ey)-.1 G -(/v).15 E 2.619(alue pairs.)-.25 F 2.619(The softw)7.619 F 2.619 -(are is distrib)-.1 F 2.618(uted as a)-.2 F .057 -(library that can be link)79.2 350.64 R .058 -(ed directly into an application.)-.1 F(It)5.058 E(pro)79.2 362.64 Q -1.454(vides a v)-.15 F 1.453(ariety of programmatic interf)-.25 F 1.453 -(aces, includ-)-.1 F .237 -(ing callable APIs for C, C++, Perl, Tcl and Ja)79.2 374.64 R -.25(va) --.2 G 5.237(.U).25 G(sers)-5.237 E .327(may do)79.2 386.64 R .327 -(wnload Berk)-.25 F(ele)-.1 E 2.827(yD)-.15 G 2.827(Bf)-2.827 G .326 -(rom Sleep)-2.827 F .326(ycat Softw)-.1 F(are')-.1 E(s)-.55 E -.8(We) -79.2 398.64 S 2.5(bs).8 G(ite, at)-2.5 E/F5 10/Times-Italic@0 SF(www)2.5 -E(.sleepycat.com)-.74 E F4(.)A(Sleep)79.2 414.84 Q 1.33(ycat distrib)-.1 -F 1.33(utes Berk)-.2 F(ele)-.1 E 3.83(yD)-.15 G 3.83(Ba)-3.83 G 3.83(sa) --3.83 G 3.83(nO)-3.83 G 1.33(pen Source)-3.83 F 3.3(product. The)79.2 -426.84 R(compan)3.3 E 3.3(yc)-.15 G .8(ollects license fees for certain) --3.3 F(uses of the softw)79.2 438.84 Q -(are and sells support and services.)-.1 E F3 3(1.1. History)79.2 468.84 -R F4(Berk)79.2 485.04 Q(ele)-.1 E 3.057(yD)-.15 G 3.057(Bb)-3.057 G --2.25 -.15(eg a)-3.057 H 3.058(na).15 G 3.058(san)-3.058 G 1.058 -.25 -(ew i)-3.058 H .558(mplementation of a hash).25 F .843 -(access method to replace both)79.2 497.04 R/F6 10/Courier@0 SF(hsearch) -3.342 E F4 .842(and the v)3.342 F(ari-)-.25 E(ous)79.2 509.04 Q F6(dbm) -5.466 E F4 2.967(implementations \()5.466 F F6(dbm)A F4 2.967(from A) -5.467 F(T&T)-1.11 E(,)-.74 E F6(ndbm)5.467 E F4 1.334(from Berk)79.2 -521.04 R(ele)-.1 E 2.634 -.65(y, a)-.15 H(nd).65 E F6(gdbm)3.834 E F4 -1.334(from the GNU project\).)3.834 F(In)6.333 E .367 -(1990 Seltzer and Y)79.2 533.04 R .368 -(igit produced a package called Hash)-.55 F(to do this [Selt91].)79.2 -545.04 Q 3.106(The \214rst general release of Berk)79.2 561.24 R(ele)-.1 -E 5.606(yD)-.15 G 3.106(B, in 1991,)-5.606 F 3.038(included some interf) -79.2 573.24 R 3.039(ace changes and a ne)-.1 F 5.539(wB)-.25 G(+tree) --5.539 E .887(access method.)79.2 585.24 R .886 -(At roughly the same time, Seltzer and)5.887 F 1.201(Olson de)79.2 -597.24 R -.15(ve)-.25 G 1.202 -(loped a prototype transaction system based).15 F 3.356(on Berk)79.2 -609.24 R(ele)-.1 E 5.856(yD)-.15 G 3.356(B, called LIBTP [Selt92], b) --5.856 F 3.355(ut ne)-.2 F -.15(ve)-.25 G(r).15 E(released the code.) -79.2 621.24 Q .653(The 4.4BSD UNIX release included Berk)79.2 637.44 R -(ele)-.1 E 3.153(yD)-.15 G 3.153(B1)-3.153 G(.85)-3.153 E .602(in 1992.) -79.2 649.44 R .601(Seltzer and Bostic maintained the code in the)5.601 F -1.545(early 1990s in Berk)79.2 661.44 R(ele)-.1 E 4.046(ya)-.15 G 1.546 -(nd in Massachusetts.)-4.046 F(Man)6.546 E(y)-.15 E -(users adopted the code during this period.)79.2 673.44 Q .432 -(By mid-1996, users w)79.2 689.64 R .431 -(anted commercial support for the)-.1 F(softw)79.2 701.64 Q 7.033 -(are. In)-.1 F 4.533(response, Bostic and Seltzer formed)7.033 F(Sleep) -79.2 713.64 Q 10.128(ycat Softw)-.1 F 12.628(are. The)-.1 F(compan) -12.627 E 15.127(ye)-.15 G(nhances,)-15.127 E(distrib)323.2 286.44 Q -1.623(utes, and supports Berk)-.2 F(ele)-.1 E 4.123(yD)-.15 G 4.124(Ba) --4.123 G 1.624(nd supporting)-4.124 F(softw)323.2 298.44 Q 2.2 -(are and documentation.)-.1 F(Sleep)7.2 E 2.2(ycat released v)-.1 F(er) --.15 E(-)-.2 E 1.677(sion 2.1 of Berk)323.2 310.44 R(ele)-.1 E 4.177(yD) --.15 G 4.178(Bi)-4.177 G 4.178(nm)-4.178 G 1.678(id-1997 with important) --4.178 F(ne)323.2 322.44 Q 2.56(wf)-.25 G .06 -(eatures, including support for concurrent access to)-2.56 F 4.176 -(databases. The)323.2 334.44 R(compan)4.176 E 4.177(ym)-.15 G(ak)-4.177 -E 1.677(es about three commer)-.1 F(-)-.2 E .958(cial releases a year) -323.2 346.44 R 3.458(,a)-.4 G .957(nd most recently shipped v)-3.458 F -(ersion)-.15 E(2.8.)323.2 358.44 Q F3 3(1.2. Ov)323.2 388.44 R(er)-.12 E -(view of Berk)-.12 E(eley DB)-.12 E F4 3.094(The C interf)323.2 404.64 R -3.094(aces in Berk)-.1 F(ele)-.1 E 5.594(yD)-.15 G 5.595(Bp)-5.594 G -(ermit)-5.595 E F6(dbm)5.595 E F4(-style)A 4.586 -(record management for databases, with signi\214cant)323.2 416.64 R -.15 -(ex)323.2 428.64 S 1.273(tensions to handle duplicate data items ele).15 -F -.05(ga)-.15 G(ntly).05 E 3.773(,t)-.65 G(o)-3.773 E 2.427 -(deal with concurrent access, and to pro)323.2 440.64 R 2.427 -(vide transac-)-.15 F .71 -(tional support so that multiple changes can be simulta-)323.2 452.64 R -1.273(neously committed \(so that the)323.2 464.64 R 3.773(ya)-.15 G -1.273(re made permanent\))-3.773 F 1.848 -(or rolled back \(so that the database is restored to its)323.2 476.64 R -(state at the be)323.2 488.64 Q(ginning of the transaction\).)-.15 E -1.034(C++ and Ja)323.2 504.84 R 1.534 -.25(va i)-.2 H(nterf).25 E 1.033 -(aces pro)-.1 F 1.033(vide a small set of classes)-.15 F 1.961 -(for operating on a database.)323.2 516.84 R 1.961 -(The main class in both)6.961 F .587(cases is called)323.2 528.84 R F6 -(Db)3.086 E F4 3.086(,a)C .586(nd pro)-3.086 F .586 -(vides methods that encapsu-)-.15 F 1.128(late the)323.2 540.84 R F6 -(dbm)3.628 E F4 1.129(-style interf)B 1.129(aces that the C interf)-.1 F -1.129(aces pro-)-.1 F(vide.)323.2 552.84 Q 2.565(Tcl and Perl interf) -323.2 569.04 R 2.564(aces allo)-.1 F 5.064(wd)-.25 G -2.15 -.25(ev e) --5.064 H 2.564(lopers w).25 F 2.564(orking in)-.1 F 1.716 -(those languages to use Berk)323.2 581.04 R(ele)-.1 E 4.216(yD)-.15 G -4.216(Bi)-4.216 G 4.217(nt)-4.216 G 1.717(heir applica-)-4.217 F 3.419 -(tions. Bindings)323.2 593.04 R .919 -(for both languages are included in the)3.419 F(distrib)323.2 605.04 Q -(ution.)-.2 E(De)323.2 621.24 Q -.15(ve)-.25 G 1.069 -(lopers may compile their applications and link in).15 F(Berk)323.2 -633.24 Q(ele)-.1 E 2.5(yD)-.15 G 2.5(Bs)-2.5 G(tatically or dynamically) --2.5 E(.)-.65 E F3 3(1.3. Ho)323.2 663.24 R 3(wB)-.12 G(erk)-3 E -(eley DB is used)-.12 E F4 .655(The Berk)323.2 679.44 R(ele)-.1 E 3.155 -(yD)-.15 G 3.154(Bl)-3.155 G .654(ibrary supports concurrent access to) --3.154 F 5.115(databases. It)323.2 691.44 R 2.616(can be link)5.115 F -2.616(ed into standalone applica-)-.1 F 1.487 -(tions, into a collection of cooperating applications, or)323.2 703.44 R -4.21(into serv)323.2 715.44 R 4.21 -(ers that handle requests and do database)-.15 F EP -%%Page: 2 2 -%%BeginPageSetup -BP -%%EndPageSetup -/F0 10/Times-Roman@0 SF(operations on behalf of clients.)79.2 84 Q .858 -(Compared to using a standalone database management)79.2 100.2 R .846 -(system, Berk)79.2 112.2 R(ele)-.1 E 3.346(yD)-.15 G 3.346(Bi)-3.346 G -3.346(se)-3.346 G .846(asy to understand and simple)-3.346 F 3.826 -(to use.)79.2 124.2 R 3.826(The softw)8.826 F 3.826 -(are stores and retrie)-.1 F -.15(ve)-.25 G 6.325(sr).15 G(ecords,) --6.325 E 2.77(which consist of k)79.2 136.2 R -.15(ey)-.1 G(/v).15 E -2.77(alue pairs.)-.25 F -2.15 -.25(Ke y)7.77 H 5.27(sa).25 G 2.77 -(re used to)-5.27 F .698(locate items and can be an)79.2 148.2 R 3.198 -(yd)-.15 G .698(ata type or structure sup-)-3.198 F -(ported by the programming language.)79.2 160.2 Q .813 -(The programmer can pro)79.2 176.4 R .813(vide the functions that Berk) --.15 F(e-)-.1 E(le)79.2 188.4 Q 3.264(yD)-.15 G 3.264(Bu)-3.264 G .763 -(ses to operate on k)-3.264 F -.15(ey)-.1 G 3.263(s. F).15 F .763(or e) --.15 F .763(xample, B+trees)-.15 F 1.72 -(can use a custom comparison function, and the Hash)79.2 200.4 R .519 -(access method can use a custom hash function.)79.2 212.4 R(Berk)5.518 E -(e-)-.1 E(le)79.2 224.4 Q 5.222(yD)-.15 G 5.222(Bu)-5.222 G 2.722 -(ses def)-5.222 F 2.723(ault functions if none are supplied.)-.1 F .873 -(Otherwise, Berk)79.2 236.4 R(ele)-.1 E 3.373(yD)-.15 G 3.373(Bd)-3.373 -G .873(oes not e)-3.373 F .873(xamine or interpret)-.15 F .934(either k) -79.2 248.4 R -.15(ey)-.1 G 3.434(so).15 G 3.434(rv)-3.434 G .934 -(alues in an)-3.684 F 3.434(yw)-.15 G(ay)-3.534 E 5.934(.V)-.65 G .934 -(alues may be arbi-)-7.044 F(trarily long.)79.2 260.4 Q .69 -(It is also important to understand what Berk)79.2 276.6 R(ele)-.1 E -3.19(yD)-.15 G 3.19(Bi)-3.19 G(s)-3.19 E 4.365(not. It)79.2 288.6 R -1.865(is not a database serv)4.365 F 1.866(er that handles netw)-.15 F -(ork)-.1 E 2.797(requests. It)79.2 300.6 R .297 -(is not an SQL engine that e)2.797 F -.15(xe)-.15 G .296(cutes queries.) -.15 F 1.547(It is not a relational or object-oriented database man-)79.2 -312.6 R(agement system.)79.2 324.6 Q 1.101(It is possible to b)79.2 -340.8 R 1.101(uild an)-.2 F 3.601(yo)-.15 G 3.601(ft)-3.601 G 1.101 -(hose on top of Berk)-3.601 F(ele)-.1 E(y)-.15 E 2.116(DB, b)79.2 352.8 -R 2.116(ut the package, as distrib)-.2 F 2.117(uted, is an embedded)-.2 -F 1.444(database engine.)79.2 364.8 R 1.444 -(It has been designed to be portable,)6.444 F(small, f)79.2 376.8 Q -(ast, and reliable.)-.1 E/F1 12/Times-Bold@0 SF 3(1.4. A)79.2 406.8 R -(pplications that use Berk)-.3 E(eley DB)-.12 E F0(Berk)79.2 423 Q(ele) --.1 E 4.248(yD)-.15 G 4.248(Bi)-4.248 G 4.249(se)-4.248 G 1.749 -(mbedded in a v)-4.249 F 1.749(ariety of proprietary)-.25 F 3.84 -(and Open Source softw)79.2 435 R 3.84(are packages.)-.1 F 3.84 -(This section)8.84 F(highlights a fe)79.2 447 Q 2.5(wo)-.25 G 2.5(ft) --2.5 G(he products that use it.)-2.5 E 1.467(Directory serv)79.2 463.2 R -1.467(ers, which do data storage and retrie)-.15 F -.25(va)-.25 G(l).25 -E 2.823(using the Local Directory Access Protocol \(LD)79.2 475.2 R -(AP\),)-.4 E(pro)79.2 487.2 Q .956 -(vide naming and directory lookup service on local-)-.15 F 2.837 -(area netw)79.2 499.2 R 5.337(orks. This)-.1 F 2.837 -(service is, essentially)5.337 F 5.336(,d)-.65 G(atabase)-5.336 E .039 -(query and update, b)79.2 511.2 R .039 -(ut uses a simple protocol rather than)-.2 F 2.202(SQL or ODBC.)79.2 -523.2 R(Berk)7.201 E(ele)-.1 E 4.701(yD)-.15 G 4.701(Bi)-4.701 G 4.701 -(st)-4.701 G 2.201(he embedded data)-4.701 F 1.288 -(manager in the majority of deplo)79.2 535.2 R 1.289(yed directory serv) --.1 F(ers)-.15 E(today)79.2 547.2 Q 4.855(,i)-.65 G 2.355(ncluding LD) --4.855 F 2.355(AP serv)-.4 F 2.355(ers from Netscape, Mes-)-.15 F -(sageDirect \(formerly Isode\), and others.)79.2 559.2 Q(Berk)79.2 575.4 -Q(ele)-.1 E 4.385(yD)-.15 G 4.385(Bi)-4.385 G 4.385(sa)-4.385 G 1.886 -(lso embedded in a lar)-4.385 F 1.886(ge number of)-.18 F 5.302 -(mail serv)79.2 587.4 R 7.802(ers. Intermail,)-.15 F 5.302(from Softw) -7.802 F 5.302(are.com, uses)-.1 F(Berk)79.2 599.4 Q(ele)-.1 E 4.613(yD) --.15 G 4.613(Ba)-4.613 G 4.613(sam)-4.613 G 2.114 -(essage store and as the backing)-4.613 F 3.597 -(store for its directory serv)79.2 611.4 R(er)-.15 E 8.597(.T)-.55 G -3.597(he sendmail serv)-8.597 F(er)-.15 E 1.175 -(\(including both the commercial Sendmail Pro of)79.2 623.4 R(fering) --.25 E 3.283(from Sendmail, Inc. and the v)79.2 635.4 R 3.283 -(ersion distrib)-.15 F 3.282(uted by)-.2 F(sendmail.or)79.2 647.4 Q -2.304(g\) uses Berk)-.18 F(ele)-.1 E 4.804(yD)-.15 G 4.804(Bt)-4.804 G -4.804(os)-4.804 G 2.305(tore aliases and)-4.804 F 9.01 -(other information.)79.2 659.4 R(Similarly)14.01 E 11.51(,P)-.65 G 9.01 -(ost\214x \(formerly)-11.51 F 3.465(VMailer\) uses Berk)79.2 671.4 R -(ele)-.1 E 5.965(yD)-.15 G 5.965(Bt)-5.965 G 5.965(os)-5.965 G 3.465 -(tore administrati)-5.965 F -.15(ve)-.25 G(information.)79.2 683.4 Q -.134(In addition, Berk)79.2 699.6 R(ele)-.1 E 2.634(yD)-.15 G 2.633(Bi) --2.634 G 2.633(se)-2.633 G .133(mbedded in a wide v)-2.633 F(ariety)-.25 -E 4.994(of other softw)79.2 711.6 R 4.994(are products.)-.1 F 4.994 -(Example applications)9.994 F .373 -(include managing access control lists, storing user k)323.2 84 R -.15 -(ey)-.1 G(s).15 E 2.75(in a public-k)323.2 96 R 3.05 -.15(ey i)-.1 H -2.75(nfrastructure, recording machine-to-).15 F(netw)323.2 108 Q .519 -(ork-address mappings in address serv)-.1 F .518(ers, and stor)-.15 F(-) --.2 E .411(ing con\214guration and de)323.2 120 R .412 -(vice information in video post-)-.25 F(production softw)323.2 132 Q -(are.)-.1 E(Finally)323.2 148.2 Q 4.978(,B)-.65 G(erk)-4.978 E(ele)-.1 E -4.978(yD)-.15 G 4.978(Bi)-4.978 G 4.978(sap)-4.978 G 2.478(art of man) --4.978 F 4.977(yo)-.15 G 2.477(ther Open)-4.977 F .005(Source softw) -323.2 160.2 R .005(are packages a)-.1 F -.25(va)-.2 G .006 -(ilable on the Internet.).25 F -.15(Fo)5.006 G(r).15 E -.15(ex)323.2 -172.2 S .604(ample, the softw).15 F .604 -(are is embedded in the Apache W)-.1 F(eb)-.8 E(serv)323.2 184.2 Q -(er and the Gnome desktop.)-.15 E F1 3(2. Access)323.2 214.2 R(Methods)3 -E F0 .828(In database terminology)323.2 230.4 R 3.329(,a)-.65 G 3.329 -(na)-3.329 G .829(ccess method is the disk-)-3.329 F 1.964 -(based structure used to store data and the operations)323.2 242.4 R -.2 -(av)323.2 254.4 S 6.053(ailable on that structure.)-.05 F -.15(Fo)11.053 -G 8.554(re).15 G 6.054(xample, man)-8.704 F(y)-.15 E 3.853 -(database systems support a B+tree access method.)323.2 266.4 R 1.203 -(B+trees allo)323.2 278.4 R 3.703(we)-.25 G 1.203 -(quality-based lookups \(\214nd k)-3.703 F -.15(ey)-.1 G 3.704(se).15 G -(qual)-3.704 E 4(to some constant\), range-based lookups \(\214nd k) -323.2 290.4 R -.15(ey)-.1 G(s).15 E 1.188(between tw)323.2 302.4 R 3.688 -(oc)-.1 G 1.189(onstants\) and record insertion and dele-)-3.688 F -(tion.)323.2 314.4 Q(Berk)323.2 330.6 Q(ele)-.1 E 4.729(yD)-.15 G 4.729 -(Bs)-4.729 G 2.228(upports three access methods: B+tree,)-4.729 F 1.553 -(Extended Linear Hashing \(Hash\), and Fix)323.2 342.6 R 1.553(ed- or V) --.15 F(ari-)-1.11 E 3.639(able-length Records \(Recno\).)323.2 354.6 R -3.638(All three operate on)8.638 F 1.956(records composed of a k)323.2 -366.6 R 2.256 -.15(ey a)-.1 H 1.956(nd a data v).15 F 4.456(alue. In) --.25 F(the)4.456 E 1.301(B+tree and Hash access methods, k)323.2 378.6 R --.15(ey)-.1 G 3.801(sc).15 G 1.301(an ha)-3.801 F 1.601 -.15(ve a)-.2 H -(rbi-).15 E 3.595(trary structure.)323.2 390.6 R 3.596 -(In the Recno access method, each)8.595 F .266 -(record is assigned a record number)323.2 402.6 R 2.765(,w)-.4 G .265 -(hich serv)-2.765 F .265(es as the)-.15 F -.1(ke)323.2 414.6 S 4.106 --.65(y. I)-.05 H 2.806(na).65 G .306(ll the access methods, the v)-2.806 -F .306(alue can ha)-.25 F .606 -.15(ve a)-.2 H(rbi-).15 E 1.417 -(trary structure.)323.2 426.6 R 1.417 -(The programmer can supply compari-)6.417 F 2.129 -(son or hashing functions for k)323.2 438.6 R -.15(ey)-.1 G 2.129 -(s, and Berk).15 F(ele)-.1 E 4.629(yD)-.15 G(B)-4.629 E -(stores and retrie)323.2 450.6 Q -.15(ve)-.25 G 2.5(sv).15 G -(alues without interpreting them.)-2.75 E 1.069 -(All of the access methods use the host \214lesystem as a)323.2 466.8 R -(backing store.)323.2 478.8 Q F1 3(2.1. Hash)323.2 508.8 R F0(Berk)323.2 -525 Q(ele)-.1 E 6.485(yD)-.15 G 6.485(Bi)-6.485 G 3.986 -(ncludes a Hash access method that)-6.485 F 9.863(implements e)323.2 537 -R 9.862(xtended linear hashing [Litw80].)-.15 F .017 -(Extended linear hashing adjusts the hash function as the)323.2 549 R -.507(hash table gro)323.2 561 R .506(ws, attempting to k)-.25 F .506 -(eep all b)-.1 F(uck)-.2 E .506(ets under)-.1 F(-)-.2 E -(full in the steady state.)323.2 573 Q 1.649 -(The Hash access method supports insertion and dele-)323.2 589.2 R .259 -(tion of records and lookup by e)323.2 601.2 R .259(xact match only)-.15 -F 5.258(.A)-.65 G(ppli-)-5.258 E .038(cations may iterate o)323.2 613.2 -R -.15(ve)-.15 G 2.538(ra).15 G .038(ll records stored in a table, b) --2.538 F(ut)-.2 E(the order in which the)323.2 625.2 Q 2.5(ya)-.15 G -(re returned is unde\214ned.)-2.5 E F1 3(2.2. B+tr)323.2 655.2 R(ee) --.216 E F0(Berk)323.2 671.4 Q(ele)-.1 E 7.184(yD)-.15 G 7.184(Bi)-7.184 -G 4.683(ncludes a B+tree [Come79] access)-7.184 F 2.502(method. B+trees) -323.2 683.4 R .002(store records of k)2.502 F -.15(ey)-.1 G(/v).15 E -.003(alue pairs in leaf)-.25 F .52(pages, and pairs of \(k)323.2 695.4 R --.15(ey)-.1 G 3.02(,c)-.5 G .52(hild page address\) at internal)-3.02 F -5.384(nodes. K)323.2 707.4 R -.15(ey)-.25 G 5.384(si).15 G 5.384(nt) --5.384 G 2.885(he tree are stored in sorted order)-5.384 F(,)-.4 E EP -%%Page: 3 3 -%%BeginPageSetup -BP -%%EndPageSetup -/F0 10/Times-Roman@0 SF .576 -(where the order is determined by the comparison func-)79.2 84 R .815 -(tion supplied when the database w)79.2 96 R .815(as created.)-.1 F -.15 -(Pa)5.815 G .815(ges at).15 F .389(the leaf le)79.2 108 R -.15(ve)-.25 G -2.889(lo).15 G 2.889(ft)-2.889 G .389 -(he tree include pointers to their neigh-)-2.889 F 1.444 -(bors to simplify tra)79.2 120 R -.15(ve)-.2 G 3.944(rsal. B+trees).15 F -1.445(support lookup by)3.944 F -.15(ex)79.2 132 S .068 -(act match \(equality\) or range \(greater than or equal to).15 F 2.891 -(ak)79.2 144 S -.15(ey)-2.991 G 2.891(\). Lik).15 F 2.891(eH)-.1 G .391 -(ash tables, B+trees support record inser)-2.891 F(-)-.2 E -(tion, deletion, and iteration o)79.2 156 Q -.15(ve)-.15 G 2.5(ra).15 G -(ll records in the tree.)-2.5 E .646 -(As records are inserted and pages in the B+tree \214ll up,)79.2 172.2 R -(the)79.2 184.2 Q 2.722(ya)-.15 G .223(re split, with about half the k) --2.722 F -.15(ey)-.1 G 2.723(sg).15 G .223(oing into a ne)-2.723 F(w) --.25 E 1.603(peer page at the same le)79.2 196.2 R -.15(ve)-.25 G 4.103 -(li).15 G 4.103(nt)-4.103 G 1.603(he tree.)-4.103 F 1.603(Most B+tree) -6.603 F .387(implementations lea)79.2 208.2 R .687 -.15(ve b)-.2 H .387 -(oth nodes half-full after a split.).15 F 2.763 -(This leads to poor performance in a common case,)79.2 220.2 R 1.522 -(where the caller inserts k)79.2 232.2 R -.15(ey)-.1 G 4.022(si).15 G -4.022(no)-4.022 G(rder)-4.022 E 6.522(.T)-.55 G 4.023(oh)-7.322 G 1.523 -(andle this)-4.023 F 1.643(case, Berk)79.2 244.2 R(ele)-.1 E 4.143(yD) --.15 G 4.143(Bk)-4.143 G 1.642(eeps track of the insertion order)-4.243 -F(,)-.4 E 2.023(and splits pages une)79.2 256.2 R -.15(ve)-.25 G 2.024 -(nly to k).15 F 2.024(eep pages fuller)-.1 F 7.024(.T)-.55 G(his)-7.024 -E 2.3(reduces tree size, yielding better search performance)79.2 268.2 R -(and smaller databases.)79.2 280.2 Q 3.177 -(On deletion, empty pages are coalesced by re)79.2 296.4 R -.15(ve)-.25 -G(rse).15 E 2.03(splits into single pages.)79.2 308.4 R 2.03 -(The access method does no)7.03 F .347 -(other page balancing on insertion or deletion.)79.2 320.4 R -2.15 -.25 -(Ke y)5.348 H 2.848(sa).25 G(re)-2.848 E 1.927(not mo)79.2 332.4 R -.15 -(ve)-.15 G 4.427(da).15 G 1.927(mong pages at e)-4.427 F -.15(ve)-.25 G -1.926(ry update to k).15 F 1.926(eep the)-.1 F 2.206 -(tree well-balanced.)79.2 344.4 R 2.207(While this could impro)7.206 F -2.507 -.15(ve s)-.15 H(earch).15 E 2.341 -(times in some cases, the additional code comple)79.2 356.4 R(xity)-.15 -E(leads to slo)79.2 368.4 Q(wer updates and is prone to deadlocks.)-.25 -E -.15(Fo)79.2 384.6 S 2.948(rs).15 G(implicity)-2.948 E 2.948(,B)-.65 G -(erk)-2.948 E(ele)-.1 E 2.949(yD)-.15 G 2.949(BB)-2.949 G .449 -(+trees do no pre\214x com-)-2.949 F(pression of k)79.2 396.6 Q -.15(ey) --.1 G 2.5(sa).15 G 2.5(ti)-2.5 G(nternal or leaf nodes.)-2.5 E/F1 12 -/Times-Bold@0 SF 3(2.3. Recno)79.2 426.6 R F0(Berk)79.2 442.8 Q(ele)-.1 -E 2.736(yD)-.15 G 2.736(Bi)-2.736 G .236(ncludes a \214x)-2.736 F .236 -(ed- or v)-.15 F .235(ariable-length record)-.25 F 5.075 -(access method, called)79.2 454.8 R/F2 10/Times-Italic@0 SF(Recno)7.575 -E F0 10.075(.T)C 5.075(he Recno access)-10.075 F .896 -(method assigns logical record numbers to each record,)79.2 466.8 R .978 -(and can search for and update records by record num-)79.2 478.8 R(ber) -79.2 490.8 Q 5.037(.R)-.55 G .037(ecno is able, for e)-5.037 F .037 -(xample, to load a te)-.15 F .036(xt \214le into a)-.15 F 1.514 -(database, treating each line as a record.)79.2 502.8 R 1.514 -(This permits)6.514 F -.1(fa)79.2 514.8 S 1.313 -(st searches by line number for applications lik).1 F 3.812(et)-.1 G --.15(ex)-3.812 G(t).15 E(editors [Ston82].)79.2 526.8 Q 2.59 -(Recno is actually b)79.2 543 R 2.59(uilt on top of the B+tree access) --.2 F 3.192(method and pro)79.2 555 R 3.191(vides a simple interf)-.15 F -3.191(ace for storing)-.1 F 3.14(sequentially-ordered data v)79.2 567 R -5.64(alues. The)-.25 F 3.14(Recno access)5.64 F 2.266 -(method generates k)79.2 579 R -.15(ey)-.1 G 4.766(si).15 G(nternally) --4.766 E 7.266(.T)-.65 G 2.266(he programmer')-7.266 F(s)-.55 E(vie)79.2 -591 Q 4.102(wo)-.25 G 4.102(ft)-4.102 G 1.602(he v)-4.102 F 1.602 -(alues is that the)-.25 F 4.102(ya)-.15 G 1.603(re numbered sequen-) --4.102 F .254(tially from one.)79.2 603 R(De)5.254 E -.15(ve)-.25 G .254 -(lopers can choose to ha).15 F .553 -.15(ve r)-.2 H(ecords).15 E 9 -(automatically renumbered when lo)79.2 615 R(wer)-.25 E(-numbered)-.2 E -.041(records are added or deleted.)79.2 627 R .041(In this case, ne) -5.041 F 2.541(wk)-.25 G -.15(ey)-2.641 G 2.541(sc).15 G(an)-2.541 E -(be inserted between e)79.2 639 Q(xisting k)-.15 E -.15(ey)-.1 G(s.).15 -E F1 3(3. F)79.2 669 R(eatur)-.3 E(es)-.216 E F0 1.827 -(This section describes important features of Berk)79.2 685.2 R(ele)-.1 -E(y)-.15 E 3.456(DB. In)79.2 697.2 R .956(general, de)3.456 F -.15(ve) --.25 G .956(lopers can choose which features).15 F .488 -(are useful to them, and use only those that are required)79.2 709.2 R -(by their application.)323.2 84 Q -.15(Fo)323.2 100.2 S 3.529(re).15 G -1.029(xample, when an application opens a database, it)-3.679 F .101 -(can declare the de)323.2 112.2 R .101(gree of concurrenc)-.15 F 2.601 -(ya)-.15 G .102(nd reco)-2.601 F -.15(ve)-.15 G .102(ry that).15 F .049 -(it requires.)323.2 124.2 R .048 -(Simple stand-alone applications, and in par)5.049 F(-)-.2 E .491 -(ticular ports of applications that used)323.2 136.2 R/F3 10/Courier@0 -SF(dbm)2.991 E F0 .491(or one of its)2.991 F -.25(va)323.2 148.2 S 1.093 -(riants, generally do not require concurrent access or).25 F .975 -(crash reco)323.2 160.2 R -.15(ve)-.15 G(ry).15 E 5.975(.O)-.65 G .975 -(ther applications, such as enterprise-)-5.975 F 3.08 -(class database management systems that store sales)323.2 172.2 R 2.643 -(transactions or other critical data, need full transac-)323.2 184.2 R -3.93(tional service.)323.2 196.2 R 3.93(Single-user operation is f)8.93 -F 3.93(aster than)-.1 F 1.175(multi-user operation, since no o)323.2 -208.2 R -.15(ve)-.15 G 1.176(rhead is incurred by).15 F 3.156 -(locking. Running)323.2 220.2 R .656(with the reco)3.156 F -.15(ve)-.15 -G .655(ry system disabled is).15 F -.1(fa)323.2 232.2 S 1.732 -(ster than running with it enabled, since log records).1 F 2.703 -(need not be written when changes are made to the)323.2 244.2 R -(database.)323.2 256.2 Q .851 -(In addition, some core subsystems, including the lock-)323.2 272.4 R -.345(ing system and the logging f)323.2 284.4 R(acility)-.1 E 2.844(,c) --.65 G .344(an be used outside)-2.844 F 1.772(the conte)323.2 296.4 R -1.772(xt of the access methods as well.)-.15 F(Although)6.773 E(fe)323.2 -308.4 Q 4.284(wu)-.25 G 1.784(sers ha)-4.284 F 2.084 -.15(ve c)-.2 H -1.784(hosen to do so, it is possible to use).15 F .939 -(only the lock manager in Berk)323.2 320.4 R(ele)-.1 E 3.439(yD)-.15 G -3.439(Bt)-3.439 G 3.439(oc)-3.439 G .939(ontrol con-)-3.439 F(currenc) -323.2 332.4 Q 4.743(yi)-.15 G 4.743(na)-4.743 G 4.743(na)-4.743 G 2.242 -(pplication, without using an)-4.743 F 4.742(yo)-.15 G 4.742(ft)-4.742 G -(he)-4.742 E .158(standard database services.)323.2 344.4 R(Alternati) -5.158 E -.15(ve)-.25 G(ly).15 E 2.658(,t)-.65 G .159(he caller can) --2.658 F(inte)323.2 356.4 Q .07 -(grate locking of non-database resources with Berk)-.15 F(e-)-.1 E(le) -323.2 368.4 Q 5.201(yD)-.15 G(B')-5.201 E 5.201(st)-.55 G 2.702 -(ransactional tw)-5.201 F 2.702(o-phase locking system, to)-.1 F 2.892 -(impose transaction semantics on objects outside the)323.2 380.4 R -(database.)323.2 392.4 Q F1 3(3.1. Pr)323.2 422.4 R -(ogrammatic interfaces)-.216 E F0(Berk)323.2 438.6 Q(ele)-.1 E 4.008(yD) --.15 G 4.008(Bd)-4.008 G 1.509(e\214nes a simple API for database man-) --4.008 F 3.452(agement. The)323.2 450.6 R .952 -(package does not include industry-stan-)3.452 F 1.898 -(dard programmatic interf)323.2 462.6 R 1.898 -(aces such as Open Database)-.1 F(Connecti)323.2 474.6 Q .852 -(vity \(ODBC\), Object Linking and Embedding)-.25 F .817 -(for Databases \(OleDB\), or Structured Query Language)323.2 486.6 R -4.027(\(SQL\). These)323.2 498.6 R(interf)4.027 E 1.527 -(aces, while useful, were designed)-.1 F 2.477 -(to promote interoperability of database systems, and)323.2 510.6 R -(not simplicity or performance.)323.2 522.6 Q 3.192 -(In response to customer demand, Berk)323.2 538.8 R(ele)-.1 E 5.691(yD) --.15 G 5.691(B2)-5.691 G(.5)-5.691 E .538 -(introduced support for the XA standard [Open94].)323.2 550.8 R(XA)5.539 -E .52(permits Berk)323.2 562.8 R(ele)-.1 E 3.02(yD)-.15 G 3.02(Bt)-3.02 -G 3.02(op)-3.02 G .52(articipate in distrib)-3.02 F .52(uted trans-)-.2 -F 3.373(actions under a transaction processing monitor lik)323.2 574.8 R -(e)-.1 E -.45(Tu)323.2 586.8 S -.15(xe).45 G 1.31(do from BEA Systems.) -.15 F(Lik)6.31 E 3.81(eX)-.1 G 1.31(A, other standard)-3.81 F(interf) -323.2 598.8 Q .99(aces can be b)-.1 F .99 -(uilt on top of the core system.)-.2 F(The)5.99 E .846 -(standards do not belong inside Berk)323.2 610.8 R(ele)-.1 E 3.346(yD) --.15 G .846(B, since not)-3.346 F(all applications need them.)323.2 -622.8 Q F1 3(3.2. W)323.2 652.8 R(orking with r)-.9 E(ecords)-.216 E F0 -3.134(Ad)323.2 669 S .634 -(atabase user may need to search for particular k)-3.134 F -.15(ey)-.1 G -(s).15 E .908(in a database, or may simply w)323.2 681 R .908 -(ant to bro)-.1 F .907(wse a)-.25 F -.25(va)-.2 G(ilable).25 E 4.101 -(records. Berk)323.2 693 R(ele)-.1 E 4.101(yD)-.15 G 4.101(Bs)-4.101 G -1.601(upports both k)-4.101 F -.15(ey)-.1 G 1.602(ed access, to).15 F -.173(\214nd one or more records with a gi)323.2 705 R -.15(ve)-.25 G -2.673(nk).15 G -.15(ey)-2.773 G 2.673(,o)-.5 G 2.673(rs)-2.673 G -(equential)-2.673 E .53(access, to retrie)323.2 717 R .83 -.15(ve a)-.25 -H .53(ll the records in the database one at).15 F EP -%%Page: 4 4 -%%BeginPageSetup -BP -%%EndPageSetup -/F0 10/Times-Roman@0 SF 6.34(at)79.2 84 S 6.34(ime. The)-6.34 F 3.84 -(order of the records returned during)6.34 F .208 -(sequential scans depends on the access method.)79.2 96 R(B+tree)5.209 E -1.495(and Recno databases return records in sort order)79.2 108 R 3.995 -(,a)-.4 G(nd)-3.995 E .023 -(Hash databases return them in apparently random order)79.2 120 R(.)-.55 -E(Similarly)79.2 136.2 Q 4.959(,B)-.65 G(erk)-4.959 E(ele)-.1 E 4.959 -(yD)-.15 G 4.958(Bd)-4.959 G 2.458(e\214nes simple interf)-4.958 F 2.458 -(aces for)-.1 F -(inserting, updating, and deleting records in a database.)79.2 148.2 Q -/F1 12/Times-Bold@0 SF 3(3.3. Long)79.2 178.2 R -.12(ke)3 G(ys and v).12 -E(alues)-.12 E F0(Berk)79.2 194.4 Q(ele)-.1 E 3.553(yD)-.15 G 3.553(Bm) --3.553 G 1.053(anages k)-3.553 F -.15(ey)-.1 G 3.553(sa).15 G 1.053 -(nd v)-3.553 F 1.053(alues as lar)-.25 F 1.054(ge as 2)-.18 F/F2 8 -/Times-Roman@0 SF(32)-5 I F0 3.192(bytes. Since)79.2 206.4 R .692 -(the time required to cop)3.192 F 3.192(yar)-.1 G .692(ecord is pro-) --3.192 F 1.895(portional to its size, Berk)79.2 218.4 R(ele)-.1 E 4.396 -(yD)-.15 G 4.396(Bi)-4.396 G 1.896(ncludes interf)-4.396 F(aces)-.1 E -4.507(that operate on partial records.)79.2 230.4 R 4.507 -(If an application)9.507 F 1.273(requires only part of a lar)79.2 242.4 -R 1.274(ge record, it requests partial)-.18 F .026(record retrie)79.2 -254.4 R -.25(va)-.25 G .026(l, and recei).25 F -.15(ve)-.25 G 2.526(sj) -.15 G .025(ust the bytes that it needs.)-2.526 F(The smaller cop)79.2 -266.4 Q 2.5(ys)-.1 G -2.25 -.2(av e)-2.5 H 2.5(sb).2 G -(oth time and memory)-2.5 E(.)-.65 E(Berk)79.2 282.6 Q(ele)-.1 E 3.206 -(yD)-.15 G 3.206(Ba)-3.206 G(llo)-3.206 E .706 -(ws the programmer to de\214ne the data)-.25 F 2.72(types of k)79.2 -294.6 R -.15(ey)-.1 G 5.22(sa).15 G 2.72(nd v)-5.22 F 5.22(alues. De) --.25 F -.15(ve)-.25 G 2.72(lopers use an).15 F 5.22(yt)-.15 G(ype)-5.22 -E -.15(ex)79.2 306.6 S(pressible in the programming language.).15 E F1 3 -(3.4. Lar)79.2 336.6 R(ge databases)-.12 E F0 3.255(As)79.2 352.8 S .755 -(ingle database managed by Berk)-3.255 F(ele)-.1 E 3.256(yD)-.15 G 3.256 -(Bc)-3.256 G .756(an be up)-3.256 F 1.716(to 2)79.2 364.8 R F2(48)-5 I -F0 1.716(bytes, or 256 petabytes, in size.)4.216 5 N(Berk)6.715 E(ele) --.1 E 4.215(yD)-.15 G(B)-4.215 E 2.144 -(uses the host \214lesystem as the backing store for the)79.2 376.8 R -2.668(database, so lar)79.2 388.8 R 2.667 -(ge databases require big \214le support)-.18 F 3.113 -(from the operating system.)79.2 400.8 R(Sleep)8.113 E 3.114(ycat Softw) --.1 F 3.114(are has)-.1 F 5.712(customers using Berk)79.2 412.8 R(ele) --.1 E 8.212(yD)-.15 G 8.212(Bt)-8.212 G 8.211(om)-8.212 G 5.711 -(anage single)-8.211 F(databases in e)79.2 424.8 Q(xcess of 100 gig)-.15 -E(abytes.)-.05 E F1 3(3.5. Main)79.2 454.8 R(memory databases)3 E F0 -1.171(Applications that do not require persistent storage can)79.2 471 R -.119(create databases that e)79.2 483 R .119(xist only in main memory) --.15 F 5.118(.T)-.65 G(hese)-5.118 E .542(databases bypass the o)79.2 -495 R -.15(ve)-.15 G .543(rhead imposed by the I/O sys-).15 F -(tem altogether)79.2 507 Q(.)-.55 E 2.144 -(Some applications do need to use disk as a backing)79.2 523.2 R 2.248 -(store, b)79.2 535.2 R 2.249(ut run on machines with v)-.2 F 2.249 -(ery lar)-.15 F 2.249(ge memory)-.18 F(.)-.65 E(Berk)79.2 547.2 Q(ele) --.1 E 2.799(yD)-.15 G 2.799(Bi)-2.799 G 2.799(sa)-2.799 G .299 -(ble to manage v)-2.799 F .299(ery lar)-.15 F .299(ge shared mem-)-.18 F -.128(ory re)79.2 559.2 R .129 -(gions for cached data pages, log records, and lock)-.15 F 3.938 -(management. F)79.2 571.2 R 1.437(or e)-.15 F 1.437 -(xample, the cache re)-.15 F 1.437(gion used for)-.15 F .033 -(data pages may be gig)79.2 583.2 R .034 -(abytes in size, reducing the lik)-.05 F(eli-)-.1 E .639(hood that an) -79.2 595.2 R 3.139(yr)-.15 G .639 -(ead operation will need to visit the disk)-3.139 F 1.201 -(in the steady state.)79.2 607.2 R 1.201 -(The programmer declares the size)6.201 F(of the cache re)79.2 619.2 Q -(gion at startup.)-.15 E(Finally)79.2 635.4 Q 7.048(,m)-.65 G(an)-7.048 -E 7.048(yo)-.15 G 4.548(perating systems pro)-7.048 F 4.548 -(vide memory-)-.15 F 2.532(mapped \214le services that are much f)79.2 -647.4 R 2.533(aster than their)-.1 F 2.602 -(general-purpose \214le system interf)79.2 659.4 R 5.102(aces. Berk)-.1 -F(ele)-.1 E 5.102(yD)-.15 G(B)-5.102 E 5.118 -(can memory-map its database \214les for read-only)79.2 671.4 R 3.917 -(database use.)79.2 683.4 R 3.917(The application operates on records) -8.917 F 2.069(stored directly on the pages, with no cache manage-)79.2 -695.4 R 1.557(ment o)79.2 707.4 R -.15(ve)-.15 G 4.057(rhead. Because) -.15 F 1.556(the application gets pointers)4.057 F 1.265 -(directly into the Berk)323.2 84 R(ele)-.1 E 3.765(yD)-.15 G 3.765(Bp) --3.765 G 1.265(ages, writes cannot be)-3.765 F 3.775 -(permitted. Otherwise,)323.2 96 R 1.275(changes could bypass the lock-) -3.775 F .23(ing and logging systems, and softw)323.2 108 R .23 -(are errors could cor)-.1 F(-)-.2 E 4.007(rupt the database.)323.2 120 R -4.006(Read-only applications can use)9.007 F(Berk)323.2 132 Q(ele)-.1 E -2.893(yD)-.15 G(B')-2.893 E 2.893(sm)-.55 G .393 -(emory-mapped \214le service to impro)-2.893 F -.15(ve)-.15 G -(performance on most architectures.)323.2 144 Q F1 3 -(3.6. Con\214gurable)323.2 174 R(page size)3 E F0 .111 -(Programmers declare the size of the pages used by their)323.2 190.2 R -.403(access methods when the)323.2 202.2 R 2.903(yc)-.15 G .403 -(reate a database.)-2.903 F(Although)5.403 E(Berk)323.2 214.2 Q(ele)-.1 -E 4.046(yD)-.15 G 4.046(Bp)-4.046 G(ro)-4.046 E 1.546 -(vides reasonable def)-.15 F 1.546(aults, de)-.1 F -.15(ve)-.25 G -(lopers).15 E 3.64(may o)323.2 226.2 R -.15(ve)-.15 G 3.64 -(rride them to control system performance.).15 F .793 -(Small pages reduce the number of records that \214t on a)323.2 238.2 R -.353(single page.)323.2 250.2 R(Fe)5.353 E .353 -(wer records on a page means that fe)-.25 F(wer)-.25 E .724 -(records are lock)323.2 262.2 R .724(ed when the page is lock)-.1 F .723 -(ed, impro)-.1 F(ving)-.15 E(concurrenc)323.2 274.2 Q 5.262 -.65(y. T) --.15 H 1.462(he per).65 F 1.462(-page o)-.2 F -.15(ve)-.15 G 1.462 -(rhead is proportionally).15 F 2.29 -(higher with smaller pages, of course, b)323.2 286.2 R 2.29(ut de)-.2 F --.15(ve)-.25 G(lopers).15 E(can trade of)323.2 298.2 Q 2.5(fs)-.25 G -(pace for time as an application requires.)-2.5 E F1 3(3.7. Small)323.2 -328.2 R -.3(fo)3 G(otprint).3 E F0(Berk)323.2 344.4 Q(ele)-.1 E 3.973 -(yD)-.15 G 3.973(Bi)-3.973 G 3.974(sac)-3.973 G 1.474(ompact system.) --3.974 F 1.474(The full package,)6.474 F .832 -(including all access methods, reco)323.2 356.4 R -.15(ve)-.15 G -(rability).15 E 3.331(,a)-.65 G .831(nd trans-)-3.331 F 1.235 -(action support is roughly 175K of te)323.2 368.4 R 1.236 -(xt space on com-)-.15 F(mon architectures.)323.2 380.4 Q F1 3 -(3.8. Cursors)323.2 410.4 R F0 1.57(In database terminology)323.2 426.6 -R 4.07(,ac)-.65 G 1.57(ursor is a pointer into an)-4.07 F 1.806 -(access method that can be called iterati)323.2 438.6 R -.15(ve)-.25 G -1.807(ly to return).15 F 3.68(records in sequence.)323.2 450.6 R(Berk) -8.68 E(ele)-.1 E 6.18(yD)-.15 G 6.18(Bi)-6.18 G 3.68(ncludes cursor) --6.18 F(interf)323.2 462.6 Q 2.814(aces for all access methods.)-.1 F -2.815(This permits, for)7.814 F -.15(ex)323.2 474.6 S .34 -(ample, users to tra).15 F -.15(ve)-.2 G .34(rse a B+tree and vie).15 F -2.84(wr)-.25 G .34(ecords in)-2.84 F(order)323.2 486.6 Q 6.233(.P)-.55 G -1.234(ointers to records in cursors are persistent, so)-6.233 F 1.779 -(that once fetched, a record may be updated in place.)323.2 498.6 R -(Finally)323.2 510.6 Q 4.438(,c)-.65 G 1.939 -(ursors support access to chains of duplicate)-4.438 F -(data items in the v)323.2 522.6 Q(arious access methods.)-.25 E F1 3 -(3.9. J)323.2 552.6 R(oins)-.18 E F0 2.703(In database terminology)323.2 -568.8 R 5.203(,aj)-.65 G 2.702(oin is an operation that)-5.203 F .616 -(spans multiple separate tables \(or in the case of Berk)323.2 580.8 R -(e-)-.1 E(le)323.2 592.8 Q 4.518(yD)-.15 G 2.018 -(B, multiple separate DB \214les\).)-4.518 F -.15(Fo)7.017 G 4.517(re) -.15 G 2.017(xample, a)-4.667 F(compan)323.2 604.8 Q 3.372(ym)-.15 G .873 -(ay store information about its customers in)-3.372 F 1.545 -(one table and information about sales in another)323.2 616.8 R 6.545 -(.A)-.55 G(n)-6.545 E 1.498(application will lik)323.2 628.8 R 1.499 -(ely w)-.1 F 1.499(ant to look up sales informa-)-.1 F .933 -(tion by customer name; this requires matching records)323.2 640.8 R -2.28(in the tw)323.2 652.8 R 4.78(ot)-.1 G 2.28 -(ables that share a common customer ID)-4.78 F 2.515(\214eld. This)323.2 -664.8 R .015(combining of records from multiple tables is)2.515 F -(called a join.)323.2 676.8 Q(Berk)323.2 693 Q(ele)-.1 E 5.561(yD)-.15 G -5.561(Bi)-5.561 G 3.061(ncludes interf)-5.561 F 3.062 -(aces for joining tw)-.1 F 5.562(oo)-.1 G(r)-5.562 E(more tables.)323.2 -705 Q EP -%%Page: 5 5 -%%BeginPageSetup -BP -%%EndPageSetup -/F0 12/Times-Bold@0 SF 3(3.10. T)79.2 84 R(ransactions)-.888 E/F1 10 -/Times-Roman@0 SF -.35(Tr)79.2 100.2 S(ansactions ha).35 E .3 -.15(ve f) --.2 H(our properties [Gray93]:).15 E/F2 8/Times-Roman@0 SF<83>84.2 116.4 -Q F1(The)17.2 E 5.489(ya)-.15 G 2.989(re atomic.)-5.489 F 2.989 -(That is, all of the changes)7.989 F 1.475 -(made in a single transaction must be applied at)104.2 128.4 R 1.31 -(the same instant or not at all.)104.2 140.4 R 1.31(This permits, for) -6.31 F -.15(ex)104.2 152.4 S 3.565(ample, the transfer of mone).15 F -6.065(yb)-.15 G 3.565(etween tw)-6.065 F(o)-.1 E 3.68 -(accounts to be accomplished, by making the)104.2 164.4 R 1.27 -(reduction of the balance in one account and the)104.2 176.4 R -(increase in the other into a single, atomic action.)104.2 188.4 Q F2 -<83>84.2 204.6 Q F1(The)17.2 E 3.125(ym)-.15 G .625(ust be consistent.) --3.125 F .625(That is, changes to the)5.625 F 3.628(database by an)104.2 -216.6 R 6.128(yt)-.15 G 3.628(ransaction cannot lea)-6.128 F 3.929 -.15 -(ve t)-.2 H(he).15 E(database in an ille)104.2 228.6 Q -.05(ga)-.15 G -2.5(lo).05 G 2.5(rc)-2.5 G(orrupt state.)-2.5 E F2<83>84.2 244.8 Q F1 -(The)17.2 E 3.006(ym)-.15 G .506(ust be isolatable.)-3.006 F(Re)5.506 E --.05(ga)-.15 G .505(rdless of the num-).05 F .8(ber of users w)104.2 -256.8 R .8(orking in the database at the same)-.1 F 1.88(time, e)104.2 -268.8 R -.15(ve)-.25 G 1.88(ry user must ha).15 F 2.18 -.15(ve t)-.2 H -1.88(he illusion that no).15 F(other acti)104.2 280.8 Q -(vity is going on.)-.25 E F2<83>84.2 297 Q F1(The)17.2 E 5.54(ym)-.15 G -3.04(ust be durable.)-5.54 F(Ev)8.04 E 3.04(en if the disk that)-.15 F -.877(stores the database is lost, it must be possible to)104.2 309 R -(reco)104.2 321 Q -.15(ve)-.15 G 2.668(rt).15 G .168 -(he database to its last transaction-consis-)-2.668 F(tent state.)104.2 -333 Q 2.49(This combination of properties \212 atomicity)79.2 349.2 R -4.99(,c)-.65 G(onsis-)-4.99 E(tenc)79.2 361.2 Q 4.542 -.65(y, i)-.15 H -3.243(solation, and durability \212 is referred to as).65 F -.4(AC)79.2 -373.2 S 3.459(IDity in the literature.).4 F(Berk)8.459 E(ele)-.1 E 5.958 -(yD)-.15 G 3.458(B, lik)-5.958 F 5.958(em)-.1 G(ost)-5.958 E .993 -(database systems, pro)79.2 385.2 R .993(vides A)-.15 F .994 -(CIDity using a collection)-.4 F(of core services.)79.2 397.2 Q .257 -(Programmers can choose to use Berk)79.2 413.4 R(ele)-.1 E 2.757(yD)-.15 -G(B')-2.757 E 2.757(st)-.55 G(ransac-)-2.757 E -(tion services for applications that need them.)79.2 425.4 Q F0 3 -(3.10.1. Write-ahead)79.2 455.4 R(logging)3 E F1 .479 -(Programmers can enable the logging system when the)79.2 471.6 R(y)-.15 -E .918(start up Berk)79.2 483.6 R(ele)-.1 E 3.418(yD)-.15 G 3.418 -(B. During)-3.418 F 3.417(at)3.417 G .917(ransaction, the appli-)-3.417 -F .493(cation mak)79.2 495.6 R .493 -(es a series of changes to the database.)-.1 F(Each)5.494 E .552 -(change is captured in a log entry)79.2 507.6 R 3.052(,w)-.65 G .552 -(hich holds the state)-3.052 F .207 -(of the database record both before and after the change.)79.2 519.6 R -2.208(The log record is guaranteed to be \215ushed to stable)79.2 531.6 -R .871(storage before an)79.2 543.6 R 3.371(yo)-.15 G 3.371(ft)-3.371 G -.871(he changed data pages are writ-)-3.371 F 3.989(ten. This)79.2 555.6 -R(beha)3.989 E 1.489(vior \212 writing the log before the data)-.2 F -(pages \212 is called)79.2 567.6 Q/F3 10/Times-Italic@0 SF -(write-ahead lo)2.5 E -.1(gg)-.1 G(ing).1 E F1(.)A .835(At an)79.2 583.8 -R 3.335(yt)-.15 G .835(ime during the transaction, the application can) --3.335 F F3(commit)79.2 595.8 Q F1 4.202(,m)C 1.702 -(aking the changes permanent, or)-4.202 F F3 -.45(ro)4.201 G 1.701 -(ll bac).45 F(k)-.2 E F1(,)A .852 -(cancelling all changes and restoring the database to its)79.2 607.8 R -1.57(pre-transaction state.)79.2 619.8 R 1.57 -(If the application rolls back the)6.57 F 1.003 -(transaction, then the log holds the state of all changed)79.2 631.8 R -.5(pages prior to the transaction, and Berk)79.2 643.8 R(ele)-.1 E 3(yD) --.15 G 3(Bs)-3 G(imply)-3 E .226(restores that state.)79.2 655.8 R .226 -(If the application commits the trans-)5.226 F .538(action, Berk)79.2 -667.8 R(ele)-.1 E 3.038(yD)-.15 G 3.038(Bw)-3.038 G .538 -(rites the log records to disk.)-3.038 F(In-)5.537 E 2.312 -(memory copies of the data pages already re\215ect the)79.2 679.8 R -1.399(changes, and will be \215ushed as necessary during nor)79.2 691.8 -R(-)-.2 E 2.35(mal processing.)79.2 703.8 R 2.35 -(Since log writes are sequential, b)7.35 F(ut)-.2 E 8.732 -(data page writes are random, this impro)79.2 715.8 R -.15(ve)-.15 G(s) -.15 E(performance.)323.2 84 Q F0 3(3.10.2. Crashes)323.2 114 R(and r)3 E -(eco)-.216 E -.12(ve)-.12 G(ry).12 E F1(Berk)323.2 130.2 Q(ele)-.1 E -3.592(yD)-.15 G(B')-3.592 E 3.592(sw)-.55 G 1.093 -(rite-ahead log is used by the transac-)-3.592 F .415 -(tion system to commit or roll back transactions.)323.2 142.2 R .414 -(It also)5.414 F(gi)323.2 154.2 Q -.15(ve)-.25 G 3.23(st).15 G .73 -(he reco)-3.23 F -.15(ve)-.15 G .73 -(ry system the information that it needs).15 F .824(to protect ag)323.2 -166.2 R .824(ainst data loss or corruption from crashes.)-.05 F(Berk) -323.2 178.2 Q(ele)-.1 E 2.703(yD)-.15 G 2.703(Bi)-2.703 G 2.704(sa) --2.703 G .204(ble to survi)-2.704 F .504 -.15(ve a)-.25 H .204 -(pplication crashes, sys-).15 F .408(tem crashes, and e)323.2 190.2 R --.15(ve)-.25 G 2.908(nc).15 G .407(atastrophic f)-2.908 F .407 -(ailures lik)-.1 F 2.907(et)-.1 G .407(he loss)-2.907 F -(of a hard disk, without losing an)323.2 202.2 Q 2.5(yd)-.15 G(ata.)-2.5 -E(Survi)323.2 218.4 Q .538(ving crashes requires data stored in se)-.25 -F -.15(ve)-.25 G .539(ral dif).15 F(fer)-.25 E(-)-.2 E 2.52(ent places.) -323.2 230.4 R 2.52(During normal processing, Berk)7.52 F(ele)-.1 E 5.02 -(yD)-.15 G(B)-5.02 E .766(has copies of acti)323.2 242.4 R 1.066 -.15 -(ve l)-.25 H .766(og records and recently-used data).15 F 1.539 -(pages in memory)323.2 254.4 R 6.539(.L)-.65 G 1.539 -(og records are \215ushed to the log)-6.539 F .694 -(disk when transactions commit.)323.2 266.4 R .695 -(Data pages trickle out)5.694 F .008(to the data disk as pages mo)323.2 -278.4 R .308 -.15(ve t)-.15 H .008(hrough the b).15 F(uf)-.2 E .008 -(fer cache.)-.25 F(Periodically)323.2 290.4 Q 2.691(,t)-.65 G .191 -(he system administrator backs up the data)-2.691 F .278 -(disk, creating a safe cop)323.2 302.4 R 2.778(yo)-.1 G 2.778(ft)-2.778 -G .278(he database at a particular)-2.778 F 2.609(instant. When)323.2 -314.4 R .109(the database is back)2.609 F .109(ed up, the log can be)-.1 -F 3.838(truncated. F)323.2 326.4 R 1.337(or maximum rob)-.15 F 1.337 -(ustness, the log disk and)-.2 F(data disk should be separate de)323.2 -338.4 Q(vices.)-.25 E(Dif)323.2 354.6 Q 1.29(ferent system f)-.25 F 1.29 -(ailures can destro)-.1 F 3.79(ym)-.1 G(emory)-3.79 E 3.79(,t)-.65 G -1.29(he log)-3.79 F 1.106(disk, or the data disk.)323.2 366.6 R(Berk) -6.106 E(ele)-.1 E 3.606(yD)-.15 G 3.606(Bi)-3.606 G 3.606(sa)-3.606 G -1.106(ble to survi)-3.606 F -.15(ve)-.25 G .679(the loss of an)323.2 -378.6 R 3.179(yo)-.15 G .679(ne of these repositories without losing) --3.179 F(an)323.2 390.6 Q 2.5(yc)-.15 G(ommitted transactions.)-2.5 E -1.372(If the computer')323.2 406.8 R 3.871(sm)-.55 G 1.371 -(emory is lost, through an applica-)-3.871 F 1.619 -(tion or operating system crash, then the log holds all)323.2 418.8 R -1.789(committed transactions.)323.2 430.8 R 1.788(On restart, the reco) -6.789 F -.15(ve)-.15 G 1.788(ry sys-).15 F .49(tem rolls the log forw) -323.2 442.8 R .49(ard ag)-.1 F .49(ainst the database, reapply-)-.05 F -.682(ing an)323.2 454.8 R 3.181(yc)-.15 G .681 -(hanges to on-disk pages that were in memory)-3.181 F .14 -(at the time of the crash.)323.2 466.8 R .14 -(Since the log contains pre- and)5.14 F .957 -(post-change state for transactions, the reco)323.2 478.8 R -.15(ve)-.15 -G .956(ry system).15 F 1.14(also uses the log to restore an)323.2 490.8 -R 3.64(yp)-.15 G 1.14(ages to their original)-3.64 F 1.615(state if the) -323.2 502.8 R 4.115(yw)-.15 G 1.615 -(ere modi\214ed by transactions that ne)-4.115 F -.15(ve)-.25 G(r).15 E -(committed.)323.2 514.8 Q 2.051 -(If the data disk is lost, the system administrator can)323.2 531 R .887 -(restore the most recent cop)323.2 543 R 3.386(yf)-.1 G .886 -(rom backup.)-3.386 F .886(The reco)5.886 F(v-)-.15 E 1.298 -(ery system will roll the entire log forw)323.2 555 R 1.298(ard ag)-.1 F -1.298(ainst the)-.05 F 2.64 -(original database, reapplying all committed changes.)323.2 567 R 4.363 -(When it \214nishes, the database will contain e)323.2 579 R -.15(ve) --.25 G(ry).15 E .535(change made by e)323.2 591 R -.15(ve)-.25 G .534 -(ry transaction that e).15 F -.15(ve)-.25 G 3.034(rc).15 G(ommitted.) --3.034 E .494(If the log disk is lost, then the reco)323.2 607.2 R -.15 -(ve)-.15 G .495(ry system can use).15 F 1.853 -(the in-memory copies of log entries to roll back an)323.2 619.2 R(y) --.15 E .026(uncommitted transactions, \215ush all in-memory database) -323.2 631.2 R 1.659(pages to the data disk, and shut do)323.2 643.2 R -1.659(wn gracefully)-.25 F 6.658(.A)-.65 G(t)-6.658 E 2.204 -(that point, the system administrator can back up the)323.2 655.2 R .039 -(database disk, install a ne)323.2 667.2 R 2.539(wl)-.25 G .039 -(og disk, and restart the sys-)-2.539 F(tem.)323.2 679.2 Q EP -%%Page: 6 6 -%%BeginPageSetup -BP -%%EndPageSetup -/F0 12/Times-Bold@0 SF 3(3.10.3. Checkpoints)79.2 84 R/F1 10 -/Times-Roman@0 SF(Berk)79.2 100.2 Q(ele)-.1 E 6.085(yD)-.15 G 6.085(Bi) --6.085 G 3.585(ncludes a checkpointing service that)-6.085 F .263 -(interacts with the reco)79.2 112.2 R -.15(ve)-.15 G .263(ry system.).15 -F .263(During normal pro-)5.263 F 2.415 -(cessing, both the log and the database are changing)79.2 124.2 R -(continually)79.2 136.2 Q 5.925(.A)-.65 G 3.425(ta)-5.925 G 1.224 -.15 -(ny g)-3.425 H -2.15 -.25(iv e).15 H 3.424(ni).25 G .924 -(nstant, the on-disk v)-3.424 F(ersions)-.15 E .414(of the tw)79.2 148.2 -R 2.914(oa)-.1 G .414(re not guaranteed to be consistent.)-2.914 F .414 -(The log)5.414 F 3.838 -(probably contains changes that are not yet in the)79.2 160.2 R -(database.)79.2 172.2 Q .085(When an application mak)79.2 188.4 R .086 -(es a)-.1 F/F2 10/Times-Italic@0 SF -.15(ch)2.586 G(ec).15 E(kpoint)-.2 -E F1 2.586(,a)C .086(ll committed)-2.586 F .443 -(changes in the log up to that point are guaranteed to be)79.2 200.4 R -.631(present on the data disk, too.)79.2 212.4 R .632 -(Checkpointing is moder)5.631 F(-)-.2 E .046(ately e)79.2 224.4 R -(xpensi)-.15 E .346 -.15(ve d)-.25 H .046(uring normal processing, b).15 -F .045(ut limits the)-.2 F(time spent reco)79.2 236.4 Q -.15(ve)-.15 G -(ring from crashes.).15 E 3.117 -(After an application or operating system crash, the)79.2 252.6 R(reco) -79.2 264.6 Q -.15(ve)-.15 G 7.419(ry system only needs to go back tw).15 -F(o)-.1 E(checkpoints)79.2 278.6 Q/F3 7/Times-Roman@0 SF(1)-4 I F1 1.376 -(to start rolling the log forw)3.876 4 N 3.875(ard. W)-.1 F(ithout)-.4 E -3.264(checkpoints, there is no w)79.2 290.6 R 3.265(ay to be sure ho)-.1 -F 5.765(wl)-.25 G(ong)-5.765 E .395(restarting after a crash will tak) -79.2 302.6 R 2.895(e. W)-.1 F .395(ith checkpoints, the)-.4 F .088 -(restart interv)79.2 314.6 R .089(al can be \214x)-.25 F .089 -(ed by the programmer)-.15 F 5.089(.R)-.55 G(eco)-5.089 E(v-)-.15 E .668 -(ery processing can be guaranteed to complete in a sec-)79.2 326.6 R -(ond or tw)79.2 338.6 Q(o.)-.1 E(Softw)79.2 354.8 Q 2.457 -(are crashes are much more common than disk)-.1 F -.1(fa)79.2 366.8 S -3.385(ilures. Man).1 F 3.385(yd)-.15 G -2.15 -.25(ev e)-3.385 H .884 -(lopers w).25 F .884(ant to guarantee that soft-)-.1 F -.1(wa)79.2 378.8 -S .158(re b).1 F .158(ugs do not destro)-.2 F 2.658(yd)-.1 G .158 -(ata, b)-2.658 F .158(ut are willing to restore)-.2 F .631 -(from tape, and to tolerate a day or tw)79.2 390.8 R 3.131(oo)-.1 G -3.131(fl)-3.131 G .63(ost w)-3.131 F .63(ork, in)-.1 F .89(the unlikle) -79.2 402.8 R 3.39(ye)-.15 G -.15(ve)-3.64 G .89(nt of a disk crash.).15 -F -.4(Wi)5.89 G .89(th Berk).4 F(ele)-.1 E 3.39(yD)-.15 G(B,)-3.39 E -1.093(programmers may truncate the log at checkpoints.)79.2 414.8 R(As) -6.092 E .09(long as the tw)79.2 426.8 R 2.59(om)-.1 G .09 -(ost recent checkpoints are present, the)-2.59 F(reco)79.2 438.8 Q -.15 -(ve)-.15 G .106(ry system can guarantee that no committed trans-).15 F -.611(actions are lost after a softw)79.2 450.8 R .611(are crash.)-.1 F -.611(In this case, the)5.611 F(reco)79.2 462.8 Q -.15(ve)-.15 G 1.439 -(ry system does not require that the log and the).15 F 1.328 -(data be on separate de)79.2 474.8 R 1.329 -(vices, although separating them)-.25 F(can still impro)79.2 486.8 Q .3 --.15(ve p)-.15 H(erformance by spreading out writes.).15 E F0 3 -(3.10.4. T)79.2 516.8 R -.12(wo)-.888 G(-phase locking).12 E F1(Berk) -79.2 533 Q(ele)-.1 E 4.416(yD)-.15 G 4.416(Bp)-4.416 G(ro)-4.416 E 1.916 -(vides a service kno)-.15 F 1.915(wn as tw)-.25 F(o-phase)-.1 E 3.017 -(locking. In)79.2 545 R .517(order to reduce the lik)3.017 F .518 -(elihood of deadlocks)-.1 F 2.547(and to guarantee A)79.2 557 R 2.546 -(CID properties, database systems)-.4 F .063(manage locks in tw)79.2 569 -R 2.564(op)-.1 G 2.564(hases. First,)-2.564 F .064(during the operation) -2.564 F 1.574(of a transaction, the)79.2 581 R 4.074(ya)-.15 G 1.574 -(cquire locks, b)-4.074 F 1.573(ut ne)-.2 F -.15(ve)-.25 G 4.073(rr).15 -G(elease)-4.073 E 6.147(them. Second,)79.2 593 R 3.648 -(at the end of the transaction, the)6.147 F(y)-.15 E .235 -(release locks, b)79.2 605 R .235(ut ne)-.2 F -.15(ve)-.25 G 2.735(ra) -.15 G .235(cquire them.)-2.735 F .235(In practice, most)5.235 F 4.69 -(database systems, including Berk)79.2 617 R(ele)-.1 E 7.19(yD)-.15 G -4.69(B, acquire)-7.19 F 2.314(locks on demand o)79.2 629 R -.15(ve)-.15 -G 4.814(rt).15 G 2.314(he course of the transaction,)-4.814 F -(then \215ush the log, then release all locks.)79.2 641 Q .32 LW 83.2 -650.6 79.2 650.6 DL 87.2 650.6 83.2 650.6 DL 91.2 650.6 87.2 650.6 DL -95.2 650.6 91.2 650.6 DL 99.2 650.6 95.2 650.6 DL 103.2 650.6 99.2 650.6 -DL 107.2 650.6 103.2 650.6 DL 111.2 650.6 107.2 650.6 DL 115.2 650.6 -111.2 650.6 DL 119.2 650.6 115.2 650.6 DL 123.2 650.6 119.2 650.6 DL -127.2 650.6 123.2 650.6 DL 131.2 650.6 127.2 650.6 DL 135.2 650.6 131.2 -650.6 DL 139.2 650.6 135.2 650.6 DL 143.2 650.6 139.2 650.6 DL 147.2 -650.6 143.2 650.6 DL 151.2 650.6 147.2 650.6 DL 155.2 650.6 151.2 650.6 -DL 159.2 650.6 155.2 650.6 DL 163.2 650.6 159.2 650.6 DL 167.2 650.6 -163.2 650.6 DL 171.2 650.6 167.2 650.6 DL 175.2 650.6 171.2 650.6 DL -179.2 650.6 175.2 650.6 DL 183.2 650.6 179.2 650.6 DL 187.2 650.6 183.2 -650.6 DL 191.2 650.6 187.2 650.6 DL 195.2 650.6 191.2 650.6 DL 199.2 -650.6 195.2 650.6 DL 203.2 650.6 199.2 650.6 DL 207.2 650.6 203.2 650.6 -DL 211.2 650.6 207.2 650.6 DL 215.2 650.6 211.2 650.6 DL 219.2 650.6 -215.2 650.6 DL 223.2 650.6 219.2 650.6 DL/F4 5/Times-Roman@0 SF(1)100.8 -661 Q/F5 8/Times-Roman@0 SF .338(One checkpoint is not f)2.338 3.2 N -.338(ar enough.)-.08 F .338(The reco)4.338 F -.12(ve)-.12 G .338 -(ry system can-).12 F .211 -(not be sure that the most recent checkpoint completed \212 it may ha) -79.2 673.8 R -.12(ve)-.16 G .734 -(been interrupted by the crash that forced the reco)79.2 683.4 R -.12 -(ve)-.12 G .734(ry system to run).12 F(in the \214rst place.)79.2 693 Q -F1(Berk)323.2 84 Q(ele)-.1 E 3.306(yD)-.15 G 3.306(Bc)-3.306 G .806 -(an lock entire database \214les, which cor)-3.306 F(-)-.2 E .845 -(respond to tables, or indi)323.2 96 R .844(vidual pages in them.)-.25 F -.844(It does)5.844 F 2.141(no record-le)323.2 108 R -.15(ve)-.25 G 4.641 -(ll).15 G 4.641(ocking. By)-4.641 F 2.142(shrinking the page size,)4.641 -F(ho)323.2 120 Q(we)-.25 E -.15(ve)-.25 G 4.427 -.4(r, d).15 H -2.15 --.25(ev e).4 H 3.627(lopers can guarantee that e).25 F -.15(ve)-.25 G -3.626(ry page).15 F 2.101(holds only a small number of records.)323.2 -132 R 2.102(This reduces)7.102 F(contention.)323.2 144 Q .388 -(If locking is enabled, then read and write operations on)323.2 160.2 R -5.317(ad)323.2 172.2 S 2.817(atabase acquire tw)-5.317 F 2.817 -(o-phase locks, which are held)-.1 F 3.635 -(until the transaction completes.)323.2 184.2 R 3.635(Which objects are) -8.635 F(lock)323.2 196.2 Q .738 -(ed and the order of lock acquisition depend on the)-.1 F -.1(wo)323.2 -208.2 S .503(rkload for each transaction.).1 F .502 -(It is possible for tw)5.502 F 3.002(oo)-.1 G(r)-3.002 E 1.315 -(more transactions to deadlock, so that each is w)323.2 220.2 R(aiting) --.1 E(for a lock that is held by another)323.2 232.2 Q(.)-.55 E(Berk) -323.2 248.4 Q(ele)-.1 E 3.307(yD)-.15 G 3.307(Bd)-3.307 G .807 -(etects deadlocks and automatically rolls)-3.307 F 1.825 -(back one of the transactions.)323.2 260.4 R 1.825 -(This releases the locks)6.825 F 1.926(that it held and allo)323.2 272.4 -R 1.925(ws the other transactions to con-)-.25 F 3.346(tinue. The)323.2 -284.4 R .847(caller is noti\214ed that its transaction did not)3.346 F -1.747(complete, and may restart it.)323.2 296.4 R(De)6.747 E -.15(ve) --.25 G 1.747(lopers can specify).15 F .646 -(the deadlock detection interv)323.2 308.4 R .647(al and the polic)-.25 -F 3.147(yt)-.15 G 3.147(ou)-3.147 G .647(se in)-3.147 F -(choosing a transaction to roll back.)323.2 320.4 Q 6.686(The tw)323.2 -336.6 R 6.686(o-phase locking interf)-.1 F 6.686(aces are separately)-.1 -F .927(callable by applications that link Berk)323.2 348.6 R(ele)-.1 E -3.427(yD)-.15 G .928(B, though)-3.427 F(fe)323.2 360.6 Q 5.64(wu)-.25 G -3.14(sers ha)-5.64 F 3.44 -.15(ve n)-.2 H 3.14(eeded to use that f).15 F -3.14(acility directly)-.1 F(.)-.65 E 2.211(Using these interf)323.2 -372.6 R 2.211(aces, Berk)-.1 F(ele)-.1 E 4.711(yD)-.15 G 4.712(Bp)-4.711 -G(ro)-4.712 E 2.212(vides a f)-.15 F(ast,)-.1 E 2.4 -(platform-portable locking system for general-purpose)323.2 384.6 R -2.917(use. It)323.2 396.6 R .418 -(also lets users include non-database objects in a)2.917 F 3.497 -(database transaction, by controlling access to them)323.2 408.6 R -.15 -(ex)323.2 420.6 S(actly as if the).15 E 2.5(yw)-.15 G -(ere inside the database.)-2.5 E .583(The Berk)323.2 436.8 R(ele)-.1 E -3.083(yD)-.15 G 3.084(Bt)-3.083 G -.1(wo)-3.084 G .584(-phase locking f) -.1 F .584(acility is b)-.1 F .584(uilt on)-.2 F .609(the f)323.2 448.8 R -.609(astest correct locking primiti)-.1 F -.15(ve)-.25 G 3.108(st).15 G -.608(hat are supported)-3.108 F 1.967(by the underlying architecture.) -323.2 460.8 R 1.967(In the current imple-)6.967 F .593 -(mentation, this means that the locking system is dif)323.2 472.8 R(fer) --.25 E(-)-.2 E 1.709(ent on the v)323.2 484.8 R 1.709 -(arious UNIX platforms, and is still more)-.25 F(dif)323.2 496.8 Q .695 -(ferent on W)-.25 F(indo)-.4 E .695(ws NT)-.25 F 5.695(.I)-.74 G 3.195 -(no)-5.695 G .695(ur e)-3.195 F .695(xperience, the most)-.15 F(dif) -323.2 508.8 Q 2.634 -(\214cult aspect of performance tuning is \214nding the)-.25 F -.1(fa) -323.2 520.8 S .883(stest locking primiti).1 F -.15(ve)-.25 G 3.383(st) -.15 G .883(hat w)-3.383 F .882(ork correctly on a par)-.1 F(-)-.2 E 1.26 -(ticular architecture and then inte)323.2 532.8 R 1.26(grating the ne) --.15 F 3.76(wi)-.25 G(nter)-3.76 E(-)-.2 E -.1(fa)323.2 544.8 S -(ce with the se).1 E -.15(ve)-.25 G(ral that we already support.).15 E -.536(The w)323.2 561 R .536(orld w)-.1 F .536 -(ould be a better place if the operating sys-)-.1 F 2.096 -(tems community w)323.2 573 R 2.096(ould uniformly implement POSIX)-.1 F -1.31(locking primiti)323.2 585 R -.15(ve)-.25 G 3.81(sa).15 G 1.31(nd w) --3.81 F 1.31(ould guarantee that acquiring)-.1 F 1.085 -(an uncontested lock w)323.2 597 R 1.085(as a f)-.1 F 1.085 -(ast operation.)-.1 F 1.085(Locks must)6.085 F -.1(wo)323.2 609 S 3.641 -(rk both among threads in a single process and).1 F(among processes.) -323.2 621 Q F0 3(3.11. Concurr)323.2 651 R(ency)-.216 E F1 .383 -(Good performance under concurrent operation is a crit-)323.2 667.2 R -.766(ical design point for Berk)323.2 679.2 R(ele)-.1 E 3.266(yD)-.15 G -3.265(B. Although)-3.266 F(Berk)3.265 E(ele)-.1 E(y)-.15 E 1.961 -(DB is itself not multi-threaded, it is thread-safe, and)323.2 691.2 R -.547(runs well in threaded applications.)323.2 703.2 R(Philosophically) -5.546 E 3.046(,w)-.65 G(e)-3.046 E(vie)323.2 715.2 Q 4.764(wt)-.25 G -2.264(he use of threads and the choice of a threads)-4.764 F EP -%%Page: 7 7 -%%BeginPageSetup -BP -%%EndPageSetup -/F0 10/Times-Roman@0 SF .066(package as a polic)79.2 84 R 2.566(yd)-.15 -G .065(ecision, and prefer to of)-2.566 F .065(fer mecha-)-.25 F .042 -(nism \(the ability to run threaded or not\), allo)79.2 96 R .043 -(wing appli-)-.25 F(cations to choose their o)79.2 108 Q(wn policies.) --.25 E 1.947(The locking, logging, and b)79.2 124.2 R(uf)-.2 E 1.947 -(fer pool subsystems all)-.25 F .711 -(use shared memory or other OS-speci\214c sharing f)79.2 136.2 R(acili-) --.1 E 1.713(ties to communicate.)79.2 148.2 R 1.713(Locks, b)6.713 F(uf) --.2 E 1.713(fer pool fetches, and)-.25 F 1.061(log writes beha)79.2 -160.2 R 1.361 -.15(ve i)-.2 H 3.561(nt).15 G 1.061(he same w)-3.561 F -1.061(ay across threads in a)-.1 F .033(single process as the)79.2 172.2 -R 2.532(yd)-.15 G 2.532(oa)-2.532 G .032(cross dif)-2.532 F .032 -(ferent processes on a)-.25 F(single machine.)79.2 184.2 Q .896 -(As a result, concurrent database applications may start)79.2 200.4 R -1.651(up a ne)79.2 212.4 R 4.151(wp)-.25 G 1.651(rocess for e)-4.151 F --.15(ve)-.25 G 1.651(ry single user).15 F 4.151(,m)-.4 G 1.651 -(ay create a)-4.151 F 2.848(single serv)79.2 224.4 R 2.848(er which spa) --.15 F 2.849(wns a ne)-.15 F 5.349(wt)-.25 G 2.849(hread for e)-5.349 F --.15(ve)-.25 G(ry).15 E(client request, or may choose an)79.2 236.4 Q -2.5(yp)-.15 G(olic)-2.5 E 2.5(yi)-.15 G 2.5(nb)-2.5 G(etween.)-2.5 E -(Berk)79.2 252.6 Q(ele)-.1 E 3.629(yD)-.15 G 3.629(Bh)-3.629 G 1.128 -(as been carefully designed to minimize)-3.629 F .07 -(contention and maximize concurrenc)79.2 264.6 R 3.87 -.65(y. T)-.15 H -.07(he cache man-).65 F .57(ager allo)79.2 276.6 R .57 -(ws all threads or processes to bene\214t from I/O)-.25 F 2.917 -(done by one.)79.2 288.6 R 2.917(Shared resources must sometimes be) -7.917 F(lock)79.2 300.6 Q 1.804(ed for e)-.1 F(xclusi)-.15 E 2.104 -.15 -(ve a)-.25 H 1.804(ccess by one thread of control.).15 F 1.757 -.8(We h) -79.2 312.6 T -2.25 -.2(av e).8 H -.1(ke)2.857 G .158 -(pt critical sections small, and are careful not).1 F 1.199 -(to hold critical resource locks across system calls that)79.2 324.6 R -.538(could deschedule the locking thread or process.)79.2 336.6 R -(Sleep-)5.539 E .979(ycat Softw)79.2 348.6 R .979 -(are has customers with hundreds of concur)-.1 F(-)-.2 E(rent users w) -79.2 360.6 Q(orking on a single database in production.)-.1 E/F1 12 -/Times-Bold@0 SF 3(4. Engineering)79.2 390.6 R(Philosoph)3 E(y)-.18 E F0 -(Fundamentally)79.2 406.8 Q 3.998(,B)-.65 G(erk)-3.998 E(ele)-.1 E 3.998 -(yD)-.15 G 3.998(Bi)-3.998 G 3.999(sac)-3.998 G 1.499 -(ollection of access)-3.999 F .19(methods with important f)79.2 418.8 R -.19(acilities, lik)-.1 F 2.69(el)-.1 G .19(ogging, locking,)-2.69 F -1.251(and transactional access underlying them.)79.2 430.8 R 1.252 -(In both the)6.252 F .992(research and the commercial w)79.2 442.8 R -.991(orld, the techniques for)-.1 F -.2(bu)79.2 454.8 S 2.727 -(ilding systems lik).2 F 5.227(eB)-.1 G(erk)-5.227 E(ele)-.1 E 5.227(yD) --.15 G 5.227(Bh)-5.227 G -2.25 -.2(av e)-5.227 H 2.728(been well-)5.427 -F(kno)79.2 466.8 Q(wn for a long time.)-.25 E .443(The k)79.2 483 R .743 --.15(ey a)-.1 H(dv).15 E .442(antage of Berk)-.25 F(ele)-.1 E 2.942(yD) --.15 G 2.942(Bi)-2.942 G 2.942(st)-2.942 G .442(he careful atten-)-2.942 -F 1.059(tion that has been paid to engineering details through-)79.2 495 -R 1.039(out its life.)79.2 507 R 2.639 -.8(We h)6.039 H -2.25 -.2(av e) -.8 H 1.039(carefully designed the system so)3.739 F .452 -(that the core f)79.2 519 R .452(acilities, lik)-.1 F 2.952(el)-.1 G -.452(ocking and I/O, surf)-2.952 F .453(ace the)-.1 F .972(right interf) -79.2 531 R .971(aces and are otherwise opaque to the caller)-.1 F(.)-.55 -E .294(As programmers, we understand the v)79.2 543 R .295 -(alue of simplicity)-.25 F .206(and ha)79.2 555 R .506 -.15(ve w)-.2 H -(ork).05 E .206(ed hard to simplify the interf)-.1 F .205(aces we sur) --.1 F(-)-.2 E -.1(fa)79.2 567 S(ce to users of the database system.).1 E -(Berk)79.2 583.2 Q(ele)-.1 E 4.531(yD)-.15 G 4.531(Ba)-4.531 G -.2(vo) --4.731 G 2.031(ids limits in the code.).2 F 2.031(It places no)7.031 F -.474(practical limit on the size of k)79.2 595.2 R -.15(ey)-.1 G .473 -(s, v).15 F .473(alues, or databases;)-.25 F(the)79.2 607.2 Q 2.5(ym) --.15 G(ay gro)-2.5 E 2.5(wt)-.25 G 2.5(oo)-2.5 G(ccup)-2.5 E 2.5(yt)-.1 -G(he a)-2.5 E -.25(va)-.2 G(ilable storage space.).25 E 1.857 -(The locking and logging subsystems ha)79.2 623.4 R 2.157 -.15(ve b)-.2 -H 1.858(een care-).15 F .184 -(fully crafted to reduce contention and impro)79.2 635.4 R .484 -.15 -(ve t)-.15 H(hrough-).15 E 2.16 -(put by shrinking or eliminating critical sections, and)79.2 647.4 R -(reducing the sizes of lock)79.2 659.4 Q(ed re)-.1 E -(gions and log entries.)-.15 E 2.238 -(There is nothing in the design or implementation of)79.2 675.6 R(Berk) -79.2 687.6 Q(ele)-.1 E 2.818(yD)-.15 G 2.818(Bt)-2.818 G .318 -(hat pushes the state of the art in database)-2.818 F 3.545 -(systems. Rather)79.2 699.6 R 3.545(,w)-.4 G 3.545(eh)-3.545 G -2.25 -.2 -(av e)-3.545 H 1.044(been v)3.745 F 1.044(ery careful to get the)-.15 F -4.321(engineering right.)79.2 711.6 R 4.321 -(The result is a system that is)9.321 F(superior)323.2 84 Q 2.867(,a)-.4 -G 2.867(sa)-2.867 G 2.866(ne)-2.867 G .366 -(mbedded database system, to an)-2.866 F 2.866(yo)-.15 G(ther)-2.866 E -(solution a)323.2 96 Q -.25(va)-.2 G(ilable.).25 E .811 -(Most database systems trade of)323.2 112.2 R 3.312(fs)-.25 G .812 -(implicity for correct-)-3.312 F 4.151(ness. Either)323.2 124.2 R 1.651 -(the system is easy to use, or it supports)4.151 F 1.17 -(concurrent use and survi)323.2 136.2 R -.15(ve)-.25 G 3.67(ss).15 G -1.17(ystem f)-3.67 F 3.67(ailures. Berk)-.1 F(ele)-.1 E(y)-.15 E 1.013 -(DB, because of its careful design and implementation,)323.2 148.2 R(of) -323.2 160.2 Q(fers both simplicity and correctness.)-.25 E .759 -(The system has a small footprint, mak)323.2 176.4 R .759 -(es simple opera-)-.1 F 1.012 -(tions simple to carry out \(inserting a ne)323.2 188.4 R 3.512(wr)-.25 -G 1.012(ecord tak)-3.512 F(es)-.1 E 1.16(just a fe)323.2 200.4 R 3.66 -(wl)-.25 G 1.16(ines of code\), and beha)-3.66 F -.15(ve)-.2 G 3.66(sc) -.15 G 1.16(orrectly in the)-3.66 F -.1(fa)323.2 212.4 S .528(ce of hea) -.1 F .527(vy concurrent use, system crashes, and e)-.2 F -.15(ve)-.25 G -(n).15 E(catastrophic f)323.2 224.4 Q(ailures lik)-.1 E 2.5(el)-.1 G -(oss of a hard disk.)-2.5 E F1 3(5. The)323.2 254.4 R(Berk)3 E -(eley DB 2.x Distrib)-.12 E(ution)-.24 E F0(Berk)323.2 270.6 Q(ele)-.1 E -4.171(yD)-.15 G 4.171(Bi)-4.171 G 4.171(sd)-4.171 G(istrib)-4.171 E -1.671(uted in source code form from)-.2 F/F2 10/Times-Italic@0 SF(www) -323.2 282.6 Q(.sleepycat.com)-.74 E F0 7.322(.U)C 2.322 -(sers are free to do)-7.322 F 2.321(wnload and)-.25 F -.2(bu)323.2 294.6 -S(ild the softw).2 E(are, and to use it in their applications.)-.1 E F1 -3(5.1. What)323.2 324.6 R(is in the distrib)3 E(ution)-.24 E F0 4.827 -(The distrib)323.2 340.8 R 4.827(ution is a compressed archi)-.2 F 5.127 --.15(ve \214)-.25 H 7.328(le. It).15 F .057 -(includes the source code for the Berk)323.2 352.8 R(ele)-.1 E 2.556(yD) --.15 G 2.556(Bl)-2.556 G(ibrary)-2.556 E 2.556(,a)-.65 G(s)-2.556 E .453 -(well as documentation, test suites, and supporting utili-)323.2 364.8 R -(ties.)323.2 376.8 Q 2.613(The source code includes b)323.2 393 R 2.612 -(uild support for all sup-)-.2 F .254(ported platforms.)323.2 405 R .254 -(On UNIX systems Berk)5.254 F(ele)-.1 E 2.755(yD)-.15 G 2.755(Bu)-2.755 -G(ses)-2.755 E 1.28(the GNU autocon\214guration tool,)323.2 417 R/F3 10 -/Courier@0 SF(autoconf)3.78 E F0 3.78(,t)C 3.78(oi)-3.78 G(den-)-3.78 E -.992(tify the system and to b)323.2 429 R .992 -(uild the library and supporting)-.2 F 3.589(utilities. Berk)323.2 441 R -(ele)-.1 E 3.589(yD)-.15 G 3.588(Bi)-3.589 G 1.088(ncludes speci\214c b) --3.588 F 1.088(uild en)-.2 F(viron-)-.4 E .515 -(ments for other platforms, such as VMS and W)323.2 453 R(indo)-.4 E -(ws.)-.25 E F1 3(5.1.1. Documentation)323.2 483 R F0 5.008(The distrib) -323.2 499.2 R 5.008(uted system includes documentation in)-.2 F 1.626 -(HTML format.)323.2 511.2 R 1.626(The documentation is in tw)6.626 F -4.127(op)-.1 G 1.627(arts: a)-4.127 F .725 -(UNIX-style reference manual for use by programmers,)323.2 523.2 R -(and a reference guide which is tutorial in nature.)323.2 535.2 Q F1 3 -(5.1.2. T)323.2 565.2 R(est suite)-1.104 E F0 1.107(The softw)323.2 -581.4 R 1.108(are also includes a complete test suite, writ-)-.1 F .155 -(ten in Tcl.)323.2 593.4 R 1.754 -.8(We b)5.154 H(elie).8 E .454 -.15 -(ve t)-.25 H .154(hat the test suite is a k).15 F .454 -.15(ey a)-.1 H -(dv).15 E(an-)-.25 E(tage of Berk)323.2 605.4 Q(ele)-.1 E 2.5(yD)-.15 G -2.5(Bo)-2.5 G -.15(ve)-2.65 G 2.5(rc).15 G(omparable systems.)-2.5 E -2.612(First, the test suite allo)323.2 621.6 R 2.613(ws users who do) --.25 F 2.613(wnload and)-.25 F -.2(bu)323.2 633.6 S 1.731(ild the softw) -.2 F 1.731(are to be sure that it is operating cor)-.1 F(-)-.2 E(rectly) -323.2 645.6 Q(.)-.65 E .893(Second, the test suite allo)323.2 661.8 R -.894(ws us, lik)-.25 F 3.394(eo)-.1 G .894(ther commercial)-3.394 F(de) -323.2 673.8 Q -.15(ve)-.25 G .536(lopers of database softw).15 F .536 -(are, to e)-.1 F -.15(xe)-.15 G .535(rcise the system).15 F 2.256 -(thoroughly at e)323.2 685.8 R -.15(ve)-.25 G 2.256(ry release.).15 F -2.256(When we learn of ne)7.256 F(w)-.25 E -.2(bu)323.2 697.8 S 1.719 -(gs, we add them to the test suite.).2 F 3.319 -.8(We r)6.719 H 1.719 -(un the test).8 F 5.692(suite continually during de)323.2 709.8 R -.15 -(ve)-.25 G 5.692(lopment c).15 F 5.692(ycles, and)-.15 F EP -%%Page: 8 8 -%%BeginPageSetup -BP -%%EndPageSetup -/F0 10/Times-Roman@0 SF(al)79.2 84 Q -.1(wa)-.1 G .314 -(ys prior to release.).1 F .314(The result is a much more reli-)5.314 F -(able system by the time it reaches beta release.)79.2 96 Q/F1 12 -/Times-Bold@0 SF 3(5.2. Binary)79.2 126 R(distrib)3 E(ution)-.24 E F0 -(Sleep)79.2 142.2 Q .893(ycat mak)-.1 F .893 -(es compiled libraries and general binary)-.1 F(distrib)79.2 154.2 Q -(utions a)-.2 E -.25(va)-.2 G(ilable to customers for a fee.).25 E F1 3 -(5.3. Supported)79.2 184.2 R(platf)3 E(orms)-.3 E F0(Berk)79.2 200.4 Q -(ele)-.1 E 5.623(yD)-.15 G 5.623(Br)-5.623 G 3.123(uns on an)-5.623 F -5.622(yo)-.15 G 3.122(perating system with a)-5.622 F .816 -(POSIX 1003.1 interf)79.2 212.4 R .817(ace [IEEE96], which includes vir) --.1 F(-)-.2 E 1.998(tually e)79.2 224.4 R -.15(ve)-.25 G 1.997 -(ry UNIX system.).15 F 1.997(In addition, the softw)6.997 F(are)-.1 E -2.85(runs on VMS, W)79.2 236.4 R(indo)-.4 E 2.85(ws/95, W)-.25 F(indo) --.4 E 2.85(ws/98, and W)-.25 F(in-)-.4 E(do)79.2 248.4 Q(ws/NT)-.25 E -10.21(.S)-.74 G(leep)-10.21 E 5.21(ycat Softw)-.1 F 5.21 -(are no longer supports)-.1 F(deplo)79.2 260.4 Q(yment on sixteen-bit W) --.1 E(indo)-.4 E(ws systems.)-.25 E F1 3(6. Berk)79.2 290.4 R -(eley DB 2.x Licensing)-.12 E F0(Berk)79.2 306.6 Q(ele)-.1 E 2.627(yD) --.15 G 2.627(B2)-2.627 G .128(.x is distrib)-2.627 F .128 -(uted as an Open Source prod-)-.2 F 4.709(uct. The)79.2 318.6 R(softw) -4.709 E 2.209(are is freely a)-.1 F -.25(va)-.2 G 2.209 -(ilable from us at our).25 F -.8(We)79.2 330.6 S 3.372(bs).8 G .872 -(ite, and in other media.)-3.372 F .872(Users are free to do)5.872 F -(wn-)-.25 E(load the softw)79.2 342.6 Q(are and b)-.1 E -(uild applications with it.)-.2 E 1.023(The 1.x v)79.2 358.8 R 1.022 -(ersions of Berk)-.15 F(ele)-.1 E 3.522(yD)-.15 G 3.522(Bw)-3.522 G -1.022(ere co)-3.522 F -.15(ve)-.15 G 1.022(red by the).15 F 3.763 -(UC Berk)79.2 370.8 R(ele)-.1 E 6.263(yc)-.15 G(op)-6.263 E 3.763 -(yright that co)-.1 F -.15(ve)-.15 G 3.764(rs softw).15 F 3.764 -(are freely)-.1 F(redistrib)79.2 382.8 Q 1.742(utable in source form.) --.2 F 1.741(When Sleep)6.742 F 1.741(ycat Soft-)-.1 F -.1(wa)79.2 394.8 -S .906(re w).1 F .907(as formed, we needed to draft a license consis-) --.1 F 2.319(tent with the cop)79.2 406.8 R 2.319(yright go)-.1 F -.15 -(ve)-.15 G 2.318(rning the e).15 F 2.318(xisting, older)-.15 F(softw) -79.2 418.8 Q 5.328(are. Because)-.1 F 2.828(of important dif)5.328 F -2.828(ferences between)-.25 F .497(the UC Berk)79.2 430.8 R(ele)-.1 E -2.997(yc)-.15 G(op)-2.997 E .497(yright and the GPL, it w)-.1 F .496 -(as impos-)-.1 F .884(sible for us to use the GPL.)79.2 442.8 R 3.384 -(As)5.884 G .884(econd cop)-3.384 F .884(yright, with)-.1 F .87 -(terms contradictory to the \214rst, simply w)79.2 454.8 R .87 -(ould not ha)-.1 F -.15(ve)-.2 G -.1(wo)79.2 466.8 S(rk).1 E(ed.)-.1 E -(Sleep)79.2 483 Q 2.533(ycat w)-.1 F 2.533 -(anted to continue Open Source de)-.1 F -.15(ve)-.25 G(lop-).15 E 2.079 -(ment of Berk)79.2 495 R(ele)-.1 E 4.579(yD)-.15 G 4.579(Bf)-4.579 G -2.079(or se)-4.579 F -.15(ve)-.25 G 2.079(ral reasons.).15 F 3.678 -.8 -(We a)7.078 H(gree).8 E .853 -(with Raymond [Raym98] and others that Open Source)79.2 507 R(softw)79.2 -519 Q .763(are is typically of higher quality than proprietary)-.1 F(,) --.65 E 2.616(binary-only products.)79.2 531 R 2.617 -(Our customers bene\214t from a)7.616 F .983(community of de)79.2 543 R --.15(ve)-.25 G .983(lopers who kno).15 F 3.483(wa)-.25 G .983 -(nd use Berk)-3.483 F(ele)-.1 E(y)-.15 E 1.317 -(DB, and can help with application design, deb)79.2 555 R(ugging,)-.2 E -1.65(and performance tuning.)79.2 567 R -.4(Wi)6.65 G 1.65 -(despread distrib).4 F 1.65(ution and)-.2 F 1.017 -(use of the source code tends to isolate b)79.2 579 R 1.017(ugs early) --.2 F 3.517(,a)-.65 G(nd)-3.517 E .032(to get \214x)79.2 591 R .031 -(es back into the distrib)-.15 F .031(uted system quickly)-.2 F 5.031 -(.A)-.65 G(s)-5.031 E 3.553(ar)79.2 603 S 1.053(esult, Berk)-3.553 F -(ele)-.1 E 3.553(yD)-.15 G 3.553(Bi)-3.553 G 3.553(sm)-3.553 G 1.053 -(ore reliable.)-3.553 F 1.054(Just as impor)6.054 F(-)-.2 E(tantly)79.2 -615 Q 3.695(,i)-.65 G(ndi)-3.695 E 1.195 -(vidual users are able to contrib)-.25 F 1.195(ute ne)-.2 F 3.695(wf) --.25 G(ea-)-3.695 E 1.056 -(tures and performance enhancements, to the bene\214t of)79.2 627 R --2.15 -.25(ev e)79.2 639 T .359(ryone who uses Berk).25 F(ele)-.1 E -2.859(yD)-.15 G 2.859(B. From)-2.859 F 2.858(ab)2.859 G .358 -(usiness per)-3.058 F(-)-.2 E(specti)79.2 651 Q -.15(ve)-.25 G 3.115(,O) -.15 G .615(pen Source and free distrib)-3.115 F .615(ution of the soft-) --.2 F -.1(wa)79.2 663 S 1.605(re creates share for us, and gi).1 F -.15 -(ve)-.25 G 4.105(su).15 G 4.105(sam)-4.105 G(ark)-4.105 E 1.605(et into) --.1 F .412(which we can sell products and services.)79.2 675 R(Finally) -5.413 E 2.913(,m)-.65 G(ak-)-2.913 E .148(ing the source code freely a) -79.2 687 R -.25(va)-.2 G .147(ilable reduces our support).25 F 2.436 -(load, since customers can \214nd and \214x b)79.2 699 R 2.437 -(ugs without)-.2 F(recourse to us, in man)79.2 711 Q 2.5(yc)-.15 G -(ases.)-2.5 E 4.727 -.8(To p)323.2 84 T(reserv).8 E 5.627(et)-.15 G -3.126(he Open Source heritage of the older)-5.627 F(Berk)323.2 96 Q(ele) --.1 E 3.003(yD)-.15 G 3.003(Bc)-3.003 G .504(ode, we drafted a ne)-3.003 -F 3.004(wl)-.25 G .504(icense go)-3.004 F -.15(ve)-.15 G(rning).15 E -.417(the distrib)323.2 108 R .417(ution of Berk)-.2 F(ele)-.1 E 2.916 -(yD)-.15 G 2.916(B2)-2.916 G 2.916(.x. W)-2.916 F 2.916(ea)-.8 G .416 -(dopted terms)-2.916 F .411(from the GPL that mak)323.2 120 R 2.911(ei) --.1 G 2.911(ti)-2.911 G .411(mpossible to turn our Open)-2.911 F 1.289 -(Source code into proprietary code o)323.2 132 R 1.288(wned by someone) --.25 F(else.)323.2 144 Q(Brie\215y)323.2 160.2 Q 3.18(,t)-.65 G .68 -(he terms go)-3.18 F -.15(ve)-.15 G .68(rning the use and distrib).15 F -.68(ution of)-.2 F(Berk)323.2 172.2 Q(ele)-.1 E 2.5(yD)-.15 G 2.5(Ba) --2.5 G(re:)-2.5 E/F2 8/Times-Roman@0 SF<83>328.2 188.4 Q F0 -(your application must be internal to your site, or)17.2 E F2<83>328.2 -204.6 Q F0 .612(your application must be freely redistrib)17.2 F .611 -(utable in)-.2 F(source form, or)348.2 216.6 Q F2<83>328.2 232.8 Q F0 -(you must get a license from us.)17.2 E -.15(Fo)323.2 249 S 2.631(rc).15 -G .131(ustomers who prefer not to distrib)-2.631 F .132(ute Open Source) --.2 F 1.493(products, we sell licenses to use and e)323.2 261 R 1.492 -(xtend Berk)-.15 F(ele)-.1 E(y)-.15 E(DB at a reasonable cost.)323.2 273 -Q 2.675 -.8(We w)323.2 289.2 T 1.076 -(ork hard to accommodate the needs of the Open).7 F .606 -(Source community)323.2 301.2 R 5.606(.F)-.65 G .606(or e)-5.756 F .606 -(xample, we ha)-.15 F .905 -.15(ve c)-.2 H .605(rafted spe-).15 F 1.415 -(cial licensing arrangements with Gnome to encourage)323.2 313.2 R -(its use and distrib)323.2 325.2 Q(ution of Berk)-.2 E(ele)-.1 E 2.5(yD) --.15 G(B.)-2.5 E(Berk)323.2 341.4 Q(ele)-.1 E 4.103(yD)-.15 G 4.103(Bc) --4.103 G 1.603(onforms to the Open Source de\214nition)-4.103 F 4.867 -([Open99]. The)323.2 353.4 R 2.367 -(license has been carefully crafted to)4.867 F -.1(ke)323.2 365.4 S .643 -(ep the product a).1 F -.25(va)-.2 G .642(ilable as an Open Source of) -.25 F(fering,)-.25 E(while pro)323.2 377.4 Q -(viding enough of a return on our in)-.15 E -.15(ve)-.4 G(stment to).15 -E 1.546(fund continued de)323.2 389.4 R -.15(ve)-.25 G 1.546 -(lopment and support of the prod-).15 F 3.033(uct. The)323.2 401.4 R -.534(current license has created a b)3.033 F .534(usiness capable)-.2 F -.916(of funding three years of de)323.2 413.4 R -.15(ve)-.25 G .916 -(lopment on the softw).15 F(are)-.1 E(that simply w)323.2 425.4 Q -(ould not ha)-.1 E .3 -.15(ve h)-.2 H(appened otherwise.).15 E F1 3 -(7. Summary)323.2 455.4 R F0(Berk)323.2 471.6 Q(ele)-.1 E 2.991(yD)-.15 -G 2.991(Bo)-2.991 G -.25(ff)-2.991 G .491 -(ers a unique collection of features, tar).25 F(-)-.2 E .175 -(geted squarely at softw)323.2 483.6 R .174(are de)-.1 F -.15(ve)-.25 G -.174(lopers who need simple,).15 F .492 -(reliable database management services in their applica-)323.2 495.6 R -5.3(tions. Good)323.2 507.6 R 2.8(design and implementation and careful) -5.3 F 1.633(engineering throughout mak)323.2 519.6 R 4.133(et)-.1 G -1.633(he softw)-4.133 F 1.634(are better than)-.1 F(man)323.2 531.6 Q -2.5(yo)-.15 G(ther systems.)-2.5 E(Berk)323.2 547.8 Q(ele)-.1 E 4.1(yD) --.15 G 4.1(Bi)-4.1 G 4.1(sa)-4.1 G 4.1(nO)-4.1 G 1.6 -(pen Source product, a)-4.1 F -.25(va)-.2 G 1.6(ilable at).25 F/F3 10 -/Times-Italic@0 SF(www)323.2 559.8 Q(.sleepycat.com)-.74 E F0 .654 -(for do)3.154 F 3.154(wnload. The)-.25 F(distrib)3.154 E .654(uted sys-) --.2 F .383(tem includes e)323.2 571.8 R -.15(ve)-.25 G .383 -(rything needed to b).15 F .382(uild and deplo)-.2 F 2.882(yt)-.1 G(he) --2.882 E(softw)323.2 583.8 Q(are or to port it to ne)-.1 E 2.5(ws)-.25 G -(ystems.)-2.5 E(Sleep)323.2 600 Q 2.633(ycat Softw)-.1 F 2.633 -(are distrib)-.1 F 2.633(utes Berk)-.2 F(ele)-.1 E 5.133(yD)-.15 G 5.134 -(Bu)-5.133 G 2.634(nder a)-5.134 F .764(license agreement that dra)323.2 -612 R .764(ws on both the UC Berk)-.15 F(ele)-.1 E(y)-.15 E(cop)323.2 -624 Q 2.377(yright and the GPL.)-.1 F 2.377(The license guarantees that) -7.377 F(Berk)323.2 636 Q(ele)-.1 E 3.384(yD)-.15 G 3.384(Bw)-3.384 G -.884(ill remain an Open Source product and)-3.384 F(pro)323.2 648 Q -1.493(vides Sleep)-.15 F 1.493(ycat with opportunities to mak)-.1 F -3.994(em)-.1 G(one)-3.994 E(y)-.15 E(to fund continued de)323.2 660 Q --.15(ve)-.25 G(lopment on the softw).15 E(are.)-.1 E EP -%%Page: 9 9 -%%BeginPageSetup -BP -%%EndPageSetup -/F0 12/Times-Bold@0 SF 3(8. Refer)79.2 84 R(ences)-.216 E/F1 10 -/Times-Roman@0 SF([Come79])79.2 100.2 Q(Comer)104.2 112.2 Q 3.127(,D)-.4 -G .627(., \231The Ubiquitous B-tree,)-3.127 F<9a>-.7 E/F2 10 -/Times-Italic@0 SF -.3(AC)3.126 G 3.126(MC).3 G(om-)-3.126 E .404 -(puting Surve)104.2 124.2 R(ys)-.3 E F1 -1.29(Vo)2.904 G .404 -(lume 11, number 2, June 1979.)1.29 F([Gray93])79.2 140.4 Q(Gray)104.2 -152.4 Q 2.982(,J)-.65 G .482(., and Reuter)-2.982 F 2.982(,A)-.4 G(.,) --2.982 E F2 -1.55 -.55(Tr a)2.981 H .481(nsaction Pr).55 F(ocessing:) --.45 E 6.776(Concepts and T)104.2 164.4 R(ec)-.92 E(hniques)-.15 E F1 -9.277(,M)C(or)-9.277 E -.05(ga)-.18 G(n-Kaufman).05 E(Publishers, 1993.) -104.2 176.4 Q([IEEE96])79.2 192.6 Q .364 -(Institute for Electrical and Electronics Engineers,)104.2 204.6 R F2 -(IEEE/ANSI Std 1003.1)104.2 216.6 Q F1 2.5(,1)C(996 Edition.)-2.5 E -([Litw80])79.2 232.8 Q 2.365(Litwin, W)104.2 244.8 R 2.366 -(., \231Linear Hashing: A Ne)-.92 F 4.866(wT)-.25 G 2.366(ool for)-5.666 -F 1.784(File and T)104.2 256.8 R 1.783(able Addressing,)-.8 F<9a>-.7 E -F2(Pr)4.283 E 1.783(oceedings of the)-.45 F 4.804 -(6th International Confer)104.2 268.8 R 4.804(ence on V)-.37 F 4.804 -(ery Lar)-1.11 F -.1(ge)-.37 G 1.983(Databases \(VLDB\))104.2 280.8 R F1 -4.483(,M)C 1.982(ontreal, Quebec, Canada,)-4.483 F(October 1980.)104.2 -292.8 Q([Open94])79.2 309 Q 4.068(The Open Group,)104.2 321 R F2 -(Distrib)6.568 E 4.069(uted TP: The XA+)-.2 F .78(Speci\214cation, V) -104.2 333 R(er)-1.11 E .78(sion 2)-.1 F F1 3.28(,T)C .78 -(he Open Group, 1994.)-3.28 F([Open99])79.2 349.2 Q(Opensource.or)104.2 -361.2 Q 8.307(g, \231Open Source De\214nition,)-.18 F<9a>-.7 E F2(www) -104.2 373.2 Q(.opensour)-.74 E(ce)-.37 E(.or)-.15 E(g/osd.html)-.37 E F1 -3.13(,v)C .63(ersion 1.4, 1999.)-3.28 F([Raym98])79.2 389.4 Q .718 -(Raymond, E.S., \231The Cathedral and the Bazaar)104.2 401.4 R -.7<2c9a> --.4 G F2(www)104.2 413.4 Q(.tuxedo.or)-.74 E(g/~esr/writings/cathedr) --.37 E(al-)-.15 E(bazaar/cathedr)104.2 425.4 Q(al-bazaar)-.15 E(.html) --1.11 E F1 2.5(,J)C(anuary 1998.)-2.5 E([Selt91])79.2 441.6 Q(Seltzer) -104.2 453.6 Q 2.578(,M)-.4 G .078(., and Y)-2.578 F .079(igit, O., \231) --.55 F 2.579(AN)-.8 G .579 -.25(ew H)-2.579 H .079(ashing P).25 F(ack-) --.15 E 6.704(age for UNIX,)104.2 465.6 R<9a>-.7 E F2(Pr)9.204 E 6.704 -(oceedings 1991 W)-.45 F(inter)-.55 E(USENIX Confer)104.2 477.6 Q(ence) --.37 E F1 2.5(,D)C(allas, TX, January 1991.)-2.5 E([Selt92])79.2 493.8 Q -(Seltzer)104.2 505.8 Q 5.365(,M)-.4 G 2.865 -(., and Olson, M., \231LIBTP: Portable)-5.365 F 2.845(Modular T)104.2 -517.8 R 2.845(ransactions for UNIX,)-.35 F<9a>-.7 E F2(Pr)5.345 E -(oceedings)-.45 E 1.49(1992 W)104.2 529.8 R 1.49(inter Usenix Confer) --.55 F(ence)-.37 E F1 3.99(,S)C 1.49(an Francisco,)-3.99 F -(CA, January 1992.)104.2 541.8 Q([Ston82])79.2 558 Q(Stonebrak)104.2 570 -Q(er)-.1 E 10.04(,M)-.4 G 7.54(., Stettner)-10.04 F 10.04(,H)-.4 G 7.54 -(., Kalash, J.,)-10.04 F .763(Guttman, A., and L)104.2 582 R .764 -(ynn, N., \231Document Process-)-.55 F .557 -(ing in a Relational Database System,)104.2 594 R 3.056<9a4d>-.7 G -(emoran-)-3.056 E .825(dum No. UCB/ERL M82/32, Uni)104.2 606 R -.15(ve) --.25 G .825(rsity of Cali-).15 F(fornia at Berk)104.2 618 Q(ele)-.1 E -1.3 -.65(y, B)-.15 H(erk).65 E(ele)-.1 E 1.3 -.65(y, C)-.15 H -(A, May 1982.).65 E EP -%%Trailer -end -%%EOF diff --git a/libdb/docs/ref/refs/embedded.html b/libdb/docs/ref/refs/embedded.html deleted file mode 100644 index b7641d931..000000000 --- a/libdb/docs/ref/refs/embedded.html +++ /dev/null @@ -1,672 +0,0 @@ -<html> -<head> -<title>Challenges in Embedded Database System Administration</title> -</head> -<body bgcolor=white> -<center> -<h1>Challenges in Embedded Database System Administration</h1> -<h3>Margo Seltzer, Harvard University</h3> -<h3>Michael Olson, Sleepycat Software, Inc.</h3> -<em>{margo,mao}@sleepycat.com</em> -</center> -<p> -Database configuration and maintenance have historically been complex tasks, -often -requiring expert knowledge of database design and application -behavior. -In an embedded environment, it is not feasible to require such -expertise and ongoing database maintenance. -This paper discusses the database administration -challenges posed by embedded systems and describes how the -Berkeley DB architecture addresses these challenges. - -<h2>1. Introduction</h2> - -Embedded systems provide a combination of opportunities and challenges -in application and system configuration and management. -As an embedded system is most often dedicated to a single application or -small set of tasks, the operating conditions of the system are -typically better understood than those of general purpose computing -environments. -Similarly, as embedded systems are dedicated to a small set of tasks, -one would expect that the software to manage them should be small -and simple. -On the other hand, once an embedded system is deployed, it must -continue to function without interruption and without administrator -intervention. -<p> -Database administration consists of two components, -initial configuration and ongoing maintenance. -Initial configuration consists of database design, manifestation, -and tuning. -The instantiation of the design includes decomposing the design -into tables, relations, or objects and designating proper indices -and their implementations (e.g., Btrees, hash tables, etc.). -Tuning a design requires selecting a location for the log and -data files, selecting appropriate database page sizes, specifying -the size of in-memory caches, and specifying the limits of -multi-threading and concurrency. -As embedded systems define a specific environment and set of tasks, -requiring expertise during the initial system -configuration process is acceptable, and we focus our efforts on -the ongoing maintenance of the system. -In this way, our emphasis differs from other projects such as -Microsoft's AutoAdmin project <a href="#Chaud982">[3]</a>, and the "no-knobs" -administration that is identified as an area of important future -research by the Asilomar authors<a href="#Bern98">[1]</a>. -<p> -In this paper, we focus on what the authors -of the Asilomar report call "gizmo" databases <a href="#Bern98"> [1]</a>, -databases -that reside in devices such as smart cards, toasters, or telephones. -The key characteristics of such databases are that their -functionality is completely transparent to users, no one ever -performs explicit database operations or -database maintenance, the database may crash at any time and -must recover instantly, the device may undergo a hard reset at -any time, requiring that the database return to its initial -state, and the semantic integrity of the database must be maintained -at all times. -In Section 2, we provide more detail on the sorts of tasks -typically performed by database administrators (DBAs) that must -be automated in an embedded system. -<p> -The rest of this paper is structured as follows. -In Section 2, we outline the requirements for embedded database support. -In Section 3, we discuss how Berkeley DB -is conducive to the hands-off management -required in embedded systems. -In Section 4, we discuss novel features that -enhance Berkeley -DB's suitability for the embedded applications. -In Section 5, we discuss issues of footprint size. -In Section 6 we discuss related work, and we conclude -in Section 7. - -<h2>2. Embedded Database Requirements</h2> -Historically, much of the commercial database industry has been driven -by the requirements of high performance online transaction -processing (OLTP), complex query processing, and the industry -standard benchmarks that have emerged (e.g., TPC-C <a href="#TPCC">[9]</a>, -TPC-D <a href="#TPCD">[10]</a>) to -allow for system comparisons. -As embedded systems typically perform fairly simple queries, -such metrics are not nearly as relevant for embedded database -systems as are ease of maintenance, robustness, and small footprint. -Of these three requirements, robustness and ease of maintenance -are the key issues. -Users must trust the data stored in their devices and must not need -to manually perform anything resembling system administration in order -to get their unit to work properly. -Fortunately, ease of use and robustness are important side -effects of simplicity and good design. -These, in turn, lead to a small size, providing the third -requirement of an embedded system. -<h3>2.1 The User Perspective</h3> -<p> -In the embedded database arena, it is the ongoing maintenance tasks -that must be automated, not necessarily the initial system configuration. -There are five tasks -that are traditionally performed by DBAs, -but must be performed automatically -in embedded database systems. -These tasks are -log archival and reclamation, -backup, -data compaction/reorganization, -automatic and rapid recovery, and -reinitialization from scratch. -<P> -Log archival and backup are tightly coupled. -Database backups are part of any -large database installation, and log archival is analogous to incremental -backup. -It is not clear what the implications of backup and archival are in -an embedded system. -Consumers do not back up their VCRs or refrigerators, yet they do -(or should) back up their personal computers or personal digital -assistants. -For the remainder of this paper, we assume that backups, in some form, -are required for gizmo databases (imagine having to reprogram, manually, -the television viewing access pattern learned by some set-top television -systems today). -Furthermore, we require that those backups are nearly instantaneous or -completely transparent, -as users should not be aware that their gizmos are being backed up -and should not have to explicitly initiate such backups. -<p> -Data compaction or reorganization has traditionally required periodic -dumping and restoration of -database tables and the recreation of indices. -In an embedded system, such reorganization must happen automatically. -<p> -Recovery issues are similar in embedded and traditional environments -with a few exceptions. -While a few seconds or even a minute recovery is acceptable -for a large server installation, no one is willing to wait -for their telephone or television to reboot. -As with archival, recovery must be nearly instantaneous in an embedded product. -Secondly, it is often the case that a system will be completely -reinitialized, rather than simply rebooted. -In this case, the embedded database must be restored to its initial -state, freeing all its resources. -This is not typically a requirement of large server systems. -<h3>2.2 The Developer Perspective</h3> -<p> -In addition to the maintenance-free operation required of the -embedded systems, there are a number of requirements that fall -out of the constrained resources typically found in the "gizmos" -using gizmo databases. These requirements are: -small footprint, -short code-path, -programmatic interface for tight application coupling and -to avoid the overhead (in both time and size) of -interfaces such as SQL and ODBC, -application configurability and flexibility, -support for complete memory-resident operation (e.g., these systems -must run on gizmos without file systems), and -support for multi-threading. -<p> -A small footprint and short code-path are self-explanatory, however -what is not as obvious is that the programmatic interface requirement -is the logical result of them. -Traditional interfaces such as ODBC and SQL add significant -size overhead and frequently add multiple context/thread switches -per operation, not to mention several IPC calls. -An embedded product is less likely to require the complex -query processing that SQL enables. -Instead, in the embedded space, the ability for an application -to configure the database for the specific tasks in question -is more important than a general query interface. -<p> -As some systems do not provide storage other than RAM and ROM, -it is essential that an embedded database work seemlessly -in memory-only environments. -Similarly, many of today's embedded operating systems provide a -single address space architecture, so a simple, multi-threaded -capability is essential for application requiring any concurrency. -<p> -In general, embedded applications run on gizmos whose native -operating system support varies tremendously. -For example, the embedded OS may or may -not support user-level processing or multi-threading. -Even if it does, a particular embedded -application may or may not need it. -Not all applications need more than one thread of control. -An embedded database must provide mechanisms to developers -without deciding policy. -For example, the threading model in an application is a matter of policy, -and depends -not on the database software, but on the hardware, operating -system, and the application's feature set. -Therefore, the data manager must provide for the use of multi-threading, -but not require it. - -<h2>3. Berkeley DB: A Database for Embedded Systems</h2> -Berkeley DB is the result of implementing database functionality -using the UNIX tool-based philosophy. -The current Berkeley DB package, as distributed by Sleepycat -Software, is a descendant of the hash and btree access methods -distributed with 4.4BSD and its descendents. -The original package (referred to as DB-1.85), -while intended as a public domain replacement for dbm and -its followers (e.g., ndbm, gdbm, etc), rapidly became widely -used as an efficient, easy-to-use data store. -It was incorporated into a number of Open Source packages including -Perl, Sendmail, Kerberos, and the GNU C-library. -<p> -Versions 2.X and higher are distributed by Sleepycat Software and -add functionality for concurrency, logging, transactions, and -recovery. -Each piece of additional functionality is implemented as an independent -module, which means that the subsystems can be used outside the -context of Berkeley DB. For example, the locking subsystem can -easily be used to implement locking for a non-DB application and -the shared memory buffer pool can be used for any application -caching data in main memory. -This subsystem design allows a designer to pick and choose -the functionality necessary for the application, minimizing -memory footprint and maximizing performance. -This addresses the small footprint and short code-path criteria -mentioned in the previous section. -<p> -As Berkeley DB grew out of a replacement for dbm, its primary -implementation language has always been C and its interface has -been programmatic. The C interface is the native interface, -unlike many database systems where the programmatic API is simply -a layer on top of an already-costly query interface (e.g. embedded -SQL). -Berkeley DB's heritage is also apparent in its data model; it has -none. -The database stores unstructured key/data pairs, specified as -variable length byte strings. -This leaves schema design and representation issues the responsibility -of the application, which is ideal for an embedded environment. -Applications retain full control over specification of their data -types, representation, index values, and index relationships. -In other words, Berkeley DB provides a robust, high-performance, -keyed storage system, not a particular database management system. -We have designed for simplicity and performance, trading off -complex, general purpose support that is better encapsulated in -applications. -<p> -Another element of Berkeley DB's programmatic interface is its -customizability; applications can specify Btree comparison and -prefix compression functions, hash functions, error routines, -and recovery models. -This means that embedded applications can tailor the underlying -database to best suit their data demands. -Similarly, the utilities traditionally bundled with a database -manager (e.g., recovery, dump/restore, archive) are implemented -as tiny wrapper programs around library routines. This means -that it is not necessary to run separate applications for the -utilities. Instead, independent threads can act as utility -daemons, or regular query threads can perform utility functions. -Many of the current products built on Berkeley DB are bundled as -a single large server with independent threads that perform functions -such as checkpoint, deadlock detection, and performance monitoring. -<p> -As mentioned earlier, living in an embedded environment requires -flexible management of storage. -Berkeley DB does not require any preallocation of disk space -for log or data files. -While many commercial database systems take complete control -of a raw device, Berkeley DB uses a normal file system, and -can therefore, safely and easily share a data space with other -programs. -All databases and log files are native files of the host environment, -so whatever utilities are provided by the environment can be used -to manage database files as well. -<p> -Berkeley DB provides three different memory models for its -management of shared information. -Applications can use the IEEE Std 1003.1b-1993 (POSIX) <tt>mmap</tt> -interface to share -data, they can use system shared memory, as frequently provided -by the shmget family of interfaces, or they can use per-process -heap memory (e.g., malloc). -Applications that require no permanent storage and do not provide -shared memory facilities can still use Berkeley DB by requesting -strictly private memory and specifying that all databases be -memory-resident. -This provides pure-memory operation. -<p> -Lastly, Berkeley DB is designed for rapid startup -- recovery can -happen automatically as part of system initialization. -This means that Berkeley DB works correctly in environments where -gizmos are suddenly shut down and restarted. - -<h2>4. Extensions for Embedded Environments </h2> -While the Berkeley DB library has been designed for use in -embedded systems, all the features described above are useful -in more conventional systems as well. -In this section, we discuss a number of features and "automatic -knobs" that are specifically geared -toward the more constrained environments found in gizmo databases. - -<h3>4.1 Automatic compression</h3> -Following the programmatic interface design philosophy, we -support application-specific (or default) compression routines. -These can be geared toward the particular data types present -in the application's dataset, thus providing better compression -than a general purpose routine. -Note that the application could instead specify an encryption -function and create encrypted databases instead of compressed ones. -Alternately, the application might specify a function that performs -both compression and encryption. -<p> -As applications are also permitted to specify comparison and hash -functions, the application can chose to organize its data based -either on uncompressed and clear-text data or compressed and encrypted -data. -If the application indicates that data should be compared in its -processed form (i.e., compressed and encrypted), then the compression -and encryption are performed on individual data items and the in-memory -representation retains these characteristics. -However, if the application indicates that data should be compared in -its original form, then entire pages are transformed upon being read -into or written out of the main memory buffer cache. -These two alternatives provide the flexibility to trade space -and security for performance. - -<h3>4.2 In-memory logging & transactions</h3> -One of the four key properties of transaction systems is durability. -This means that transaction systems are designed for permanent storage -(most commonly disk). However, as mentioned above, embedded systems -do not necessarily contain any such storage. -Nevertheless, transactions can be useful in this environment to -preserve the semantic integrity of the underlying storage. -Berkeley DB optionally provides logging functionality and -transaction support regardless of whether the database and logs -are on disk or in memory. - -<h3>4.3 Remote Logs</h3> -While we do not expect users to backup their television sets and -toasters, it is conceivable that a set-top box provided by a -cable carrier should, in fact, be backed up by that cable carrier. -The ability to store logs remotely can provide "information appliance" -functionality, and can also be used in conjunction with local logs -to enhance reliability. -Furthermore, remote logs provide for catastrophic recovery, e.g., loss -of the gizmo, destruction of the gizmo, etc. - -<h3>4.4 Application References to Database Buffers</h3> - -Typically, when data is returned to the user, it must be copied -from the data manager's buffer cache (or data page) into the -application's memory. -However, in an embedded environment, the robustness of the -total software package is of paramount importance, not the -isolation between the application and the data manager. -As a result, it is possible for the data manager to avoid -copies by giving applications direct references to data items -in a shared memory cache. -This is a significant performance optimization that can be -allowed when the application and data manager are tightly -integrated. - -<h3>4.5 Recoverable database creation/deletion</h3> - -In a conventional database management system, the creation of -database tables (relations) and indices are heavyweight operations -that are not recoverable. -This is not acceptable in a complex embedded environment where -instantaneous recovery and robust operation in the face of -all types of database operations is essential. -While Berkeley DB files can be removed using normal file system -utilities, we provide transaction protected utilities that -allow us to recover both database creation and deletion. - -<h3>4.6 Adaptive concurrency control</h3> -The Berkeley DB package uses page-level locking by default. -This trades off fine grain concurrency control for simplicity -during recovery. (Finer grain concurrency control can be -obtained by reducing the page size in the database.) -However, when multiple threads/processes perform page-locking -in the presence of writing operations, there is the -potential for deadlock. -As some environments do not need or desire the overhead of -logging and transactions, it is important to provide the -ability for concurrent access without the potential for -deadlock. -<p> -Berkeley DB provides an option to perform coarser grain, -deadlock-free locking. -Rather than locking on pages, locking is performed at the -interface to the database. -Multiple readers or a single writer are allowed to be -active in the database at any instant in time, with -conflicting requests queued automatically. -The presence of cursors, through which applications can both -read and write data, complicates this design. -If a cursor is currently being used for reading, but will later -be used to write, the system will be deadlock prone if no -special precautions are taken. -To handle this situation, we require that, when a cursor is -created, the application specify any future intention to write. -If there is an intention to write, the cursor is granted an -intention-to-write lock which does not conflict with readers, -but does conflict with other intention-to-write locks and write -locks. -The end result is that the application is limited to a single -potentially writing cursor accessing the database at any point -in time. -<p> -Under periods of low contention (but potentially high throughput), -the normal page-level locking provides the best overall throughput. -However, as contention rises, so does the potential for deadlock. -As some cross-over point, switching to the less concurrent, but -deadlock-free locking protocol will result in higher throughput -as operations must never be retried. -Given the operating conditions of an embedded database manager, -it is useful to make this change automatically as the system -itself detects high contention. - -<h3>4.7 Adaptive synchronization</h3> - -In addition to the logical locks that protect the integrity of the -database pages, Berkeley DB must synchronize access to shared memory -data structures, such as the lock table, in-memory buffer pool, and -in-memory log buffer. -Each independent module uses a single mutex to protect its shared -data structures, under the assumption that operations that require -the mutex are very short and the potential for conflict is -low. -Unfortunately, in highly concurrent environments with multiple processors -present, this assumption is not always true. -When this assumption becomes invalid (that is, we observe significant -contention for the subsystem mutexes), we can switch over to a finer-grained -concurrency model for the mutexes. -Once again, there is a performance trade-off. Fine-grain mutexes -impose a penalty of approximately 25% (due to the increased number -of mutexes required for each operation), but allow for higher throughput. -Using fine-grain mutexes under low contention would cause a decrease -in performance, so it is important to monitor the system carefully, -so that the change can be executed only when it will increase system -throughput without jeopardizing latency. - -<h2>5. Footprint of an Embedded System</h2> -While traditional systems compete on price-performance, the -embedded players will compete on price, features, and footprint. -The earlier sections have focused on features; in this section -we focus on footprint. -<p> -Oracle reports that Oracle Lite 3.0 requires 350 KB to 750 KB -of memory and approximately 2.5 MB of hard disk space <a href="#Oracle">[7]</a>. -This includes drivers for interfaces such as ODBC and JDBC. -In contrast, Berkeley DB ranges in size from 75 KB to under 200 KB, -foregoing heavyweight interfaces such as ODBC and JDBC and -providing a variety of deployed sizes that can be used depending -on application needs. At the low end, applications requiring -a simple single-user access method can choose from either extended -linear hashing, B+ trees, or record-number based retrieval and -pay only the 75 KB space requirement. -Applications requiring all three access methods will observe the -110 KB footprint. -At the high end, a fully recoverable, high-performance system -occupies less than a quarter megabyte of memory. -This is a system you can easily incorporate in your toaster oven. -Table 1 shows the per-module break down of the entire Berkeley DB -library. Note that this does not include memory used to cache database -pages. - -<table border> -<tr><th colspan=4>Object sizes in bytes</th></tr> -<tr><th align=left>Subsystem</th><th align=center>Text</th><th align=center>Data</th><th align=center>Bss</th></tr> -<tr><td>Btree-specific routines</td><td align=right>28812</td><td align=right>0</td><td align=right>0</td></tr> -<tr><td>Recno-specific routines</td><td align=right>7211</td><td align=right>0</td><td align=right>0</td></tr> -<tr><td>Hash-specific routines</td><td align=right>23742</td><td align=right>0</td><td align=right>0</td></tr> -<tr><td colspan=4></td></tr> -<tr><td>Memory Pool</td><td align=right>14535</td><td align=right>0</td><td align=right>0</td></tr> -<tr><td>Access method common code</td><td align=right>23252</td><td align=right>0</td><td align=right>0</td></tr> -<tr><td>OS compatibility library</td><td align=right>4980</td><td align=right>52</td><td align=right>0</td></tr> -<tr><td>Support utilities</td><td align=right>6165</td><td align=right>0</td><td align=right>0</td></tr> -<tr><td colspan=4></td></tr> -<tr><th>All modules for Btree access method only</th><td align=right>77744</td><td align=right>52</td><td align=right>0</td></tr> -<tr><th>All modules for Recno access method only</th><td align=right>84955</td><td align=right>52</td><td align=right>0</td></tr> -<tr><th>All modules for Hash access method only</th><td align=right>72674</td><td align=right>52</td><td align=right>0</td></tr> -<tr><td colspan=4></td></tr> -<tr><th align=left>All Access Methods</th><td align=right>108697</td><td align=right>52</td><td align=right>0</td></tr> -<tr><td colspan=4><br></td></tr> -<tr><td>Locking</td><td align=right>12533</td><td align=right>0</td><td align=right>0</td></tr> -<tr><td colspan=4></td></tr> -<tr><td>Recovery</td><td align=right>26948</td><td align=right>8</td><td align=right>4</td></tr> -<tr><td>Logging</td><td align=right>37367</td><td align=right>0</td><td align=right>0</td></tr> -<tr><td colspan=4></td></tr> -<tr><th align=left>Full Package</th><td align=right>185545</td><td align=right>60</td><td align=right>4</td></tr> -<tr><br></tr> -</table> - -<h2>6. Related Work</h2> - -Every three to five years, leading researchers in the database -community convene to identify future directions in database -research. -They produce a report of this meeting, named for the year and -location of the meeting. -The most recent of these reports, the 1998 Asilomar report, -identifies the embedded database market as one of the -high growth areas in database research <a href="#Bern98">[1]</a>. -Not surprisingly, market analysts identify the embedded database -market as a high-growth area in the commercial sector as well <a href="#Host98"> -[5]</a>. -<p> -The Asilomar report identifies a new class of database applications, which they -term "gizmo" databases, small databases embedded in tiny mobile -appliances, e.g., smart-cards, telephones, personal digital assistants. -Such databases must be self-managing, secure and reliable. -Thus, the idea is that gizmo databases require plug and play data -management with no database administrator (DBA), no human settable -parameters, and the ability to adapt to changing conditions. -More specifically, the Asilomar authors claim that the goal is -self-tuning, including defining the physical DB design, the -logical DB design, and automatic reports and utilities <a href="#Bern98">[1]</a> -To date, -few researchers have accepted this challenge, and there is a dearth -of research literature on the subject. -<p> -Our approach to embedded database administration is fundamentally -different than that described by the Asilomar authors. -We adopt their terminology, but view the challenge in supporting -gizmo databases to be that of self-sustenance <em>after</em> initial -deployment. Therefore, we find it, not only acceptable, but -desirable to assume that application developers control initial -database design and configuration. To the best of our knowledge, -none of the published work in this area addresses this approach. -<p> -As the research community has not provided guidance in this -arena, most work in embedded database administration has fallen -to the commercial vendors. -These vendors fall into two camps, companies selling databases -specifically designed for embedding or programmatic access -and the major database vendors (e.g., Oracle, Informix, Sybase). -<p> -The embedded vendors all acknowledge the need for automatic -administration, but fail to identify precisely how their -products actually accomplish this. -A notable exception is Interbase whose white paper -comparison with Sybase and Microsoft's SQL servers -explicitly address features of maintenance ease. -Interbase claims that as they use no log files, there is -no need for log reclamation, checkpoint tuning, or other -tasks associated with log management. However, Interbase -uses Transaction Information Pages, and it is unclear -how these are reused or reclaimed <a href="#Interbase">[6]</a>. -Additionally, with a log-free system, they must use -a FORCE policy (write all pages to disk at commit), -as defined by Haerder and Reuter <a href="#Haerder">[4]</a>. This has -serious performance consequences for disk-based systems. -The approach described in this paper does use logs and -therefore requires log reclamation, -but provides hooks so the application may reclaim logs -safely and programmatically. -While Berkeley DB does require checkpoints, the goal of -tuning the checkpoint interval is to bound recovery time. -Since the checkpoint interval in Berkeley DB can be expressed -by the amount of log data written, it requires no tuning. -The application designer sets a target recovery time, and -selects the amount of log data that can be read in that interval -and specifies the checkpoint interval appropriately. Even as -load changes, the time to recover does not. -<p> -The backup approaches taken by Interbase and Berkeley DB -are similar in that they both allow online backup, but -rather different in their affect on transactions running -during backup. As Interbase performs backups as transactions -<a href="#Interbase">[6]</a>, concurrent queries can suffer potentially long -delays. Berkeley DB uses native operating system system utilities -and recovery for backups, so there is no interference with -concurrent activity, other than potential contention on disk -arms. -<p> -There are a number of database vendors selling in -the embedded market (e.g., Raima, -Centura, Pervasive, Faircom), but none highlight -the special requirements of embedded database -applications. -On the other end of the spectrum, the major vendors, -Oracle, Sybase, Microsoft, are all becoming convinced -of the importance of the embedded market. -As mentioned earlier, Oracle has announced its -Oracle Lite server for embedded use. -Sybase has announced its UltraLite platform for "application-optimized, -high-performance, SQL database engine for professional -application developers building solutions for mobile and embedded platforms." -<a href="#Sybase">[8]</a>. -We believe that SQL is incompatible with the -gizmo database environment or truly embedded systems for which Berkeley -DB is most suitable. -Microsoft research is taking a different approach, developing -technology to assist in automating initial database design and -index specification <a href="#Chaud98">[2]</a><a href="#Chaud982">[3]</a>. -As mentioned earlier, we believe that such configuration is, not only -acceptable in the embedded market, but desirable so that applications -can tune their database management for the target environment. -<h2>7. Conclusions</h2> -The coming wave of embedded systems poses a new set of challenges -for data management. -The traditional server-based, big footprint systems designed for -high performance on big iron are not the right approach in this -environment. -Instead, application developers need small, fast, versatile systems -that can be tailored to a specific environment. -In this paper, we have identified several of the key issues in -providing these systems and shown how Berkeley DB provides -many of the characteristics necessary for such applications. - -<h2>8. References</h2> -<p> -[1] <a name="Bern98"> Bernstein, P., Brodie, M., Ceri, S., DeWitt, D., Franklin, M., -Garcia-Molina, H., Gray, J., Held, J., Hellerstein, J., -Jagadish, H., Lesk, M., Maier, D., Naughton, J., -Pirahesh, H., Stonebraker, M., Ullman, J., -"The Asilomar Report on Database Research," -SIGMOD Record 27(4): 74-80, 1998. -</a> -<p> -[2] <a name="Chaud98"> Chaudhuri, S., Narasayya, V., -"AutoAdmin 'What-If' Index Analysis Utility," -<em>Proceedings of the ACM SIGMOD Conference</em>, Seattle, 1998. -</a> -<p> -[3] <a name="Chaud982"> Chaudhuri, S., Narasayya, V., -"An Efficient, Cost-Driver Index Selection Tool for Microsoft SQL Server," -<em>Proceedings of the 23rd VLDB Conference</em>, Athens, Greece, 1997. -</a> -<p> -[4] <a name="Harder"> Haerder, T., Reuter, A., -"Principles of Transaction-Oriented Database Recovery," -<em>Computing Surveys 15</em>,4 (1983), 237-318. -</a> -<p> -[5] <a name="Host98"> Hostetler, M., "Cover Is Off A New Type of Database," -Embedded DB News, -http://www.theadvisors.com/embeddeddbnews.htm, -5/6/98. -</a> -<p> -[6] <a name="Interbase"> Interbase, "A Comparison of Borland InterBase 4.0 -Sybase SQL Server and Microsoft SQL Server," -http://web.interbase.com/products/doc_info_f.html. -</a> -<p> -[7] <a name="Oracle"> Oracle, "Oracle Delivers New Server, Application Suite -to Power the Web for Mission-Critical Business," -http://www.oracle.com.sg/partners/news/newserver.htm, -May 1998. -</a> -<p> -[8] <a name="Sybase"> Sybase, Sybase UltraLite, http://www.sybase.com/products/ultralite/beta. -</a> -<p> -[9] <a name="TPCC"> Transaction Processing Council, "TPC-C Benchmark Specification, -Version 3.4," San Jose, CA, August 1998. -</a> -<p> -[10] <a name="TPCD"> Transaction Processing Council, "TPC-D Benchmark Specification, -Version 2.1," San Jose, CA, April 1999. -</a> -</body> -</html> - - diff --git a/libdb/docs/ref/refs/hash_usenix.ps b/libdb/docs/ref/refs/hash_usenix.ps deleted file mode 100644 index acdea0992..000000000 --- a/libdb/docs/ref/refs/hash_usenix.ps +++ /dev/null @@ -1,12209 +0,0 @@ -%!PS-Adobe-1.0 -%%Creator: utopia:margo (& Seltzer,608-13E,8072,) -%%Title: stdin (ditroff) -%%CreationDate: Tue Dec 11 15:06:45 1990 -%%EndComments -% @(#)psdit.pro 1.3 4/15/88 -% lib/psdit.pro -- prolog for psdit (ditroff) files -% Copyright (c) 1984, 1985 Adobe Systems Incorporated. All Rights Reserved. -% last edit: shore Sat Nov 23 20:28:03 1985 -% RCSID: $Header$ - -% Changed by Edward Wang (edward@ucbarpa.berkeley.edu) to handle graphics, -% 17 Feb, 87. - -/$DITroff 140 dict def $DITroff begin -/fontnum 1 def /fontsize 10 def /fontheight 10 def /fontslant 0 def -/xi{0 72 11 mul translate 72 resolution div dup neg scale 0 0 moveto - /fontnum 1 def /fontsize 10 def /fontheight 10 def /fontslant 0 def F - /pagesave save def}def -/PB{save /psv exch def currentpoint translate - resolution 72 div dup neg scale 0 0 moveto}def -/PE{psv restore}def -/arctoobig 90 def /arctoosmall .05 def -/m1 matrix def /m2 matrix def /m3 matrix def /oldmat matrix def -/tan{dup sin exch cos div}def -/point{resolution 72 div mul}def -/dround {transform round exch round exch itransform}def -/xT{/devname exch def}def -/xr{/mh exch def /my exch def /resolution exch def}def -/xp{}def -/xs{docsave restore end}def -/xt{}def -/xf{/fontname exch def /slotno exch def fontnames slotno get fontname eq not - {fonts slotno fontname findfont put fontnames slotno fontname put}if}def -/xH{/fontheight exch def F}def -/xS{/fontslant exch def F}def -/s{/fontsize exch def /fontheight fontsize def F}def -/f{/fontnum exch def F}def -/F{fontheight 0 le{/fontheight fontsize def}if - fonts fontnum get fontsize point 0 0 fontheight point neg 0 0 m1 astore - fontslant 0 ne{1 0 fontslant tan 1 0 0 m2 astore m3 concatmatrix}if - makefont setfont .04 fontsize point mul 0 dround pop setlinewidth}def -/X{exch currentpoint exch pop moveto show}def -/N{3 1 roll moveto show}def -/Y{exch currentpoint pop exch moveto show}def -/S{show}def -/ditpush{}def/ditpop{}def -/AX{3 -1 roll currentpoint exch pop moveto 0 exch ashow}def -/AN{4 2 roll moveto 0 exch ashow}def -/AY{3 -1 roll currentpoint pop exch moveto 0 exch ashow}def -/AS{0 exch ashow}def -/MX{currentpoint exch pop moveto}def -/MY{currentpoint pop exch moveto}def -/MXY{moveto}def -/cb{pop}def % action on unknown char -- nothing for now -/n{}def/w{}def -/p{pop showpage pagesave restore /pagesave save def}def -/Dt{/Dlinewidth exch def}def 1 Dt -/Ds{/Ddash exch def}def -1 Ds -/Di{/Dstipple exch def}def 1 Di -/Dsetlinewidth{2 Dlinewidth mul setlinewidth}def -/Dsetdash{Ddash 4 eq{[8 12]}{Ddash 16 eq{[32 36]} - {Ddash 20 eq{[32 12 8 12]}{[]}ifelse}ifelse}ifelse 0 setdash}def -/Dstroke{gsave Dsetlinewidth Dsetdash 1 setlinecap stroke grestore - currentpoint newpath moveto}def -/Dl{rlineto Dstroke}def -/arcellipse{/diamv exch def /diamh exch def oldmat currentmatrix pop - currentpoint translate 1 diamv diamh div scale /rad diamh 2 div def - currentpoint exch rad add exch rad -180 180 arc oldmat setmatrix}def -/Dc{dup arcellipse Dstroke}def -/De{arcellipse Dstroke}def -/Da{/endv exch def /endh exch def /centerv exch def /centerh exch def - /cradius centerv centerv mul centerh centerh mul add sqrt def - /eradius endv endv mul endh endh mul add sqrt def - /endang endv endh atan def - /startang centerv neg centerh neg atan def - /sweep startang endang sub dup 0 lt{360 add}if def - sweep arctoobig gt - {/midang startang sweep 2 div sub def /midrad cradius eradius add 2 div def - /midh midang cos midrad mul def /midv midang sin midrad mul def - midh neg midv neg endh endv centerh centerv midh midv Da - Da} - {sweep arctoosmall ge - {/controldelt 1 sweep 2 div cos sub 3 sweep 2 div sin mul div 4 mul def - centerv neg controldelt mul centerh controldelt mul - endv neg controldelt mul centerh add endh add - endh controldelt mul centerv add endv add - centerh endh add centerv endv add rcurveto Dstroke} - {centerh endh add centerv endv add rlineto Dstroke} - ifelse} - ifelse}def -/Dpatterns[ -[%cf[widthbits] -[8<0000000000000010>] -[8<0411040040114000>] -[8<0204081020408001>] -[8<0000103810000000>] -[8<6699996666999966>] -[8<0000800100001008>] -[8<81c36666c3810000>] -[8<0f0e0c0800000000>] -[8<0000000000000010>] -[8<0411040040114000>] -[8<0204081020408001>] -[8<0000001038100000>] -[8<6699996666999966>] -[8<0000800100001008>] -[8<81c36666c3810000>] -[8<0f0e0c0800000000>] -[8<0042660000246600>] -[8<0000990000990000>] -[8<0804020180402010>] -[8<2418814242811824>] -[8<6699996666999966>] -[8<8000000008000000>] -[8<00001c3e363e1c00>] -[8<0000000000000000>] -[32<00000040000000c00000004000000040000000e0000000000000000000000000>] -[32<00000000000060000000900000002000000040000000f0000000000000000000>] -[32<000000000000000000e0000000100000006000000010000000e0000000000000>] -[32<00000000000000002000000060000000a0000000f00000002000000000000000>] -[32<0000000e0000000000000000000000000000000f000000080000000e00000001>] -[32<0000090000000600000000000000000000000000000007000000080000000e00>] -[32<00010000000200000004000000040000000000000000000000000000000f0000>] -[32<0900000006000000090000000600000000000000000000000000000006000000>]] -[%ug -[8<0000020000000000>] -[8<0000020000002000>] -[8<0004020000002000>] -[8<0004020000402000>] -[8<0004060000402000>] -[8<0004060000406000>] -[8<0006060000406000>] -[8<0006060000606000>] -[8<00060e0000606000>] -[8<00060e000060e000>] -[8<00070e000060e000>] -[8<00070e000070e000>] -[8<00070e020070e000>] -[8<00070e020070e020>] -[8<04070e020070e020>] -[8<04070e024070e020>] -[8<04070e064070e020>] -[8<04070e064070e060>] -[8<06070e064070e060>] -[8<06070e066070e060>] -[8<06070f066070e060>] -[8<06070f066070f060>] -[8<060f0f066070f060>] -[8<060f0f0660f0f060>] -[8<060f0f0760f0f060>] -[8<060f0f0760f0f070>] -[8<0e0f0f0760f0f070>] -[8<0e0f0f07e0f0f070>] -[8<0e0f0f0fe0f0f070>] -[8<0e0f0f0fe0f0f0f0>] -[8<0f0f0f0fe0f0f0f0>] -[8<0f0f0f0ff0f0f0f0>] -[8<1f0f0f0ff0f0f0f0>] -[8<1f0f0f0ff1f0f0f0>] -[8<1f0f0f8ff1f0f0f0>] -[8<1f0f0f8ff1f0f0f8>] -[8<9f0f0f8ff1f0f0f8>] -[8<9f0f0f8ff9f0f0f8>] -[8<9f0f0f9ff9f0f0f8>] -[8<9f0f0f9ff9f0f0f9>] -[8<9f8f0f9ff9f0f0f9>] -[8<9f8f0f9ff9f8f0f9>] -[8<9f8f1f9ff9f8f0f9>] -[8<9f8f1f9ff9f8f1f9>] -[8<bf8f1f9ff9f8f1f9>] -[8<bf8f1f9ffbf8f1f9>] -[8<bf8f1fdffbf8f1f9>] -[8<bf8f1fdffbf8f1fd>] -[8<ff8f1fdffbf8f1fd>] -[8<ff8f1fdffff8f1fd>] -[8<ff8f1ffffff8f1fd>] -[8<ff8f1ffffff8f1ff>] -[8<ff9f1ffffff8f1ff>] -[8<ff9f1ffffff9f1ff>] -[8<ff9f9ffffff9f1ff>] -[8<ff9f9ffffff9f9ff>] -[8<ffbf9ffffff9f9ff>] -[8<ffbf9ffffffbf9ff>] -[8<ffbfdffffffbf9ff>] -[8<ffbfdffffffbfdff>] -[8<ffffdffffffbfdff>] -[8<ffffdffffffffdff>] -[8<fffffffffffffdff>] -[8<ffffffffffffffff>]] -[%mg -[8<8000000000000000>] -[8<0822080080228000>] -[8<0204081020408001>] -[8<40e0400000000000>] -[8<66999966>] -[8<8001000010080000>] -[8<81c36666c3810000>] -[8<f0e0c08000000000>] -[16<07c00f801f003e007c00f800f001e003c007800f001f003e007c00f801f003e0>] -[16<1f000f8007c003e001f000f8007c003e001f800fc007e003f001f8007c003e00>] -[8<c3c300000000c3c3>] -[16<0040008001000200040008001000200040008000000100020004000800100020>] -[16<0040002000100008000400020001800040002000100008000400020001000080>] -[16<1fc03fe07df0f8f8f07de03fc01f800fc01fe03ff07df8f87df03fe01fc00f80>] -[8<80>] -[8<8040201000000000>] -[8<84cc000048cc0000>] -[8<9900009900000000>] -[8<08040201804020100800020180002010>] -[8<2418814242811824>] -[8<66999966>] -[8<8000000008000000>] -[8<70f8d8f870000000>] -[8<0814224180402010>] -[8<aa00440a11a04400>] -[8<018245aa45820100>] -[8<221c224180808041>] -[8<88000000>] -[8<0855800080550800>] -[8<2844004482440044>] -[8<0810204080412214>] -[8<00>]]]def -/Dfill{ - transform /maxy exch def /maxx exch def - transform /miny exch def /minx exch def - minx maxx gt{/minx maxx /maxx minx def def}if - miny maxy gt{/miny maxy /maxy miny def def}if - Dpatterns Dstipple 1 sub get exch 1 sub get - aload pop /stip exch def /stipw exch def /stiph 128 def - /imatrix[stipw 0 0 stiph 0 0]def - /tmatrix[stipw 0 0 stiph 0 0]def - /minx minx cvi stiph idiv stiph mul def - /miny miny cvi stipw idiv stipw mul def - gsave eoclip 0 setgray - miny stiph maxy{ - tmatrix exch 5 exch put - minx stipw maxx{ - tmatrix exch 4 exch put tmatrix setmatrix - stipw stiph true imatrix {stip} imagemask - }for - }for - grestore -}def -/Dp{Dfill Dstroke}def -/DP{Dfill currentpoint newpath moveto}def -end - -/ditstart{$DITroff begin - /nfonts 60 def % NFONTS makedev/ditroff dependent! - /fonts[nfonts{0}repeat]def - /fontnames[nfonts{()}repeat]def -/docsave save def -}def - -% character outcalls -/oc{ - /pswid exch def /cc exch def /name exch def - /ditwid pswid fontsize mul resolution mul 72000 div def - /ditsiz fontsize resolution mul 72 div def - ocprocs name known{ocprocs name get exec}{name cb}ifelse -}def -/fractm [.65 0 0 .6 0 0] def -/fraction{ - /fden exch def /fnum exch def gsave /cf currentfont def - cf fractm makefont setfont 0 .3 dm 2 copy neg rmoveto - fnum show rmoveto currentfont cf setfont(\244)show setfont fden show - grestore ditwid 0 rmoveto -}def -/oce{grestore ditwid 0 rmoveto}def -/dm{ditsiz mul}def -/ocprocs 50 dict def ocprocs begin -(14){(1)(4)fraction}def -(12){(1)(2)fraction}def -(34){(3)(4)fraction}def -(13){(1)(3)fraction}def -(23){(2)(3)fraction}def -(18){(1)(8)fraction}def -(38){(3)(8)fraction}def -(58){(5)(8)fraction}def -(78){(7)(8)fraction}def -(sr){gsave 0 .06 dm rmoveto(\326)show oce}def -(is){gsave 0 .15 dm rmoveto(\362)show oce}def -(->){gsave 0 .02 dm rmoveto(\256)show oce}def -(<-){gsave 0 .02 dm rmoveto(\254)show oce}def -(==){gsave 0 .05 dm rmoveto(\272)show oce}def -(uc){gsave currentpoint 400 .009 dm mul add translate - 8 -8 scale ucseal oce}def -end - -% an attempt at a PostScript FONT to implement ditroff special chars -% this will enable us to -% cache the little buggers -% generate faster, more compact PS out of psdit -% confuse everyone (including myself)! -50 dict dup begin -/FontType 3 def -/FontName /DIThacks def -/FontMatrix [.001 0 0 .001 0 0] def -/FontBBox [-260 -260 900 900] def% a lie but ... -/Encoding 256 array def -0 1 255{Encoding exch /.notdef put}for -Encoding - dup 8#040/space put %space - dup 8#110/rc put %right ceil - dup 8#111/lt put %left top curl - dup 8#112/bv put %bold vert - dup 8#113/lk put %left mid curl - dup 8#114/lb put %left bot curl - dup 8#115/rt put %right top curl - dup 8#116/rk put %right mid curl - dup 8#117/rb put %right bot curl - dup 8#120/rf put %right floor - dup 8#121/lf put %left floor - dup 8#122/lc put %left ceil - dup 8#140/sq put %square - dup 8#141/bx put %box - dup 8#142/ci put %circle - dup 8#143/br put %box rule - dup 8#144/rn put %root extender - dup 8#145/vr put %vertical rule - dup 8#146/ob put %outline bullet - dup 8#147/bu put %bullet - dup 8#150/ru put %rule - dup 8#151/ul put %underline - pop -/DITfd 100 dict def -/BuildChar{0 begin - /cc exch def /fd exch def - /charname fd /Encoding get cc get def - /charwid fd /Metrics get charname get def - /charproc fd /CharProcs get charname get def - charwid 0 fd /FontBBox get aload pop setcachedevice - 2 setlinejoin 40 setlinewidth - newpath 0 0 moveto gsave charproc grestore - end}def -/BuildChar load 0 DITfd put -/CharProcs 50 dict def -CharProcs begin -/space{}def -/.notdef{}def -/ru{500 0 rls}def -/rn{0 840 moveto 500 0 rls}def -/vr{0 800 moveto 0 -770 rls}def -/bv{0 800 moveto 0 -1000 rls}def -/br{0 840 moveto 0 -1000 rls}def -/ul{0 -140 moveto 500 0 rls}def -/ob{200 250 rmoveto currentpoint newpath 200 0 360 arc closepath stroke}def -/bu{200 250 rmoveto currentpoint newpath 200 0 360 arc closepath fill}def -/sq{80 0 rmoveto currentpoint dround newpath moveto - 640 0 rlineto 0 640 rlineto -640 0 rlineto closepath stroke}def -/bx{80 0 rmoveto currentpoint dround newpath moveto - 640 0 rlineto 0 640 rlineto -640 0 rlineto closepath fill}def -/ci{500 360 rmoveto currentpoint newpath 333 0 360 arc - 50 setlinewidth stroke}def - -/lt{0 -200 moveto 0 550 rlineto currx 800 2cx s4 add exch s4 a4p stroke}def -/lb{0 800 moveto 0 -550 rlineto currx -200 2cx s4 add exch s4 a4p stroke}def -/rt{0 -200 moveto 0 550 rlineto currx 800 2cx s4 sub exch s4 a4p stroke}def -/rb{0 800 moveto 0 -500 rlineto currx -200 2cx s4 sub exch s4 a4p stroke}def -/lk{0 800 moveto 0 300 -300 300 s4 arcto pop pop 1000 sub - 0 300 4 2 roll s4 a4p 0 -200 lineto stroke}def -/rk{0 800 moveto 0 300 s2 300 s4 arcto pop pop 1000 sub - 0 300 4 2 roll s4 a4p 0 -200 lineto stroke}def -/lf{0 800 moveto 0 -1000 rlineto s4 0 rls}def -/rf{0 800 moveto 0 -1000 rlineto s4 neg 0 rls}def -/lc{0 -200 moveto 0 1000 rlineto s4 0 rls}def -/rc{0 -200 moveto 0 1000 rlineto s4 neg 0 rls}def -end - -/Metrics 50 dict def Metrics begin -/.notdef 0 def -/space 500 def -/ru 500 def -/br 0 def -/lt 416 def -/lb 416 def -/rt 416 def -/rb 416 def -/lk 416 def -/rk 416 def -/rc 416 def -/lc 416 def -/rf 416 def -/lf 416 def -/bv 416 def -/ob 350 def -/bu 350 def -/ci 750 def -/bx 750 def -/sq 750 def -/rn 500 def -/ul 500 def -/vr 0 def -end - -DITfd begin -/s2 500 def /s4 250 def /s3 333 def -/a4p{arcto pop pop pop pop}def -/2cx{2 copy exch}def -/rls{rlineto stroke}def -/currx{currentpoint pop}def -/dround{transform round exch round exch itransform} def -end -end -/DIThacks exch definefont pop -ditstart -(psc)xT -576 1 1 xr -1(Times-Roman)xf 1 f -2(Times-Italic)xf 2 f -3(Times-Bold)xf 3 f -4(Times-BoldItalic)xf 4 f -5(Helvetica)xf 5 f -6(Helvetica-Bold)xf 6 f -7(Courier)xf 7 f -8(Courier-Bold)xf 8 f -9(Symbol)xf 9 f -10(DIThacks)xf 10 f -10 s -1 f -xi -%%EndProlog - -%%Page: 1 1 -10 s 10 xH 0 xS 1 f -3 f -22 s -1249 626(A)N -1420(N)X -1547(ew)X -1796(H)X -1933(ashing)X -2467(P)X -2574(ackage)X -3136(for)X -3405(U)X -3532(N)X -3659(IX)X -2 f -20 s -3855 562(1)N -1 f -12 s -1607 779(Margo)N -1887(Seltzer)X -9 f -2179(-)X -1 f -2256(University)X -2686(of)X -2790(California,)X -3229(Berkeley)X -2015 875(Ozan)N -2242(Yigit)X -9 f -2464(-)X -1 f -2541(York)X -2762(University)X -3 f -2331 1086(ABSTRACT)N -1 f -10 s -1152 1222(UNIX)N -1385(support)X -1657(of)X -1756(disk)X -1921(oriented)X -2216(hashing)X -2497(was)X -2654(originally)X -2997(provided)X -3314(by)X -2 f -3426(dbm)X -1 f -3595([ATT79])X -3916(and)X -1152 1310(subsequently)N -1595(improved)X -1927(upon)X -2112(in)X -2 f -2199(ndbm)X -1 f -2402([BSD86].)X -2735(In)X -2826(AT&T)X -3068(System)X -3327(V,)X -3429(in-memory)X -3809(hashed)X -1152 1398(storage)N -1420(and)X -1572(access)X -1814(support)X -2090(was)X -2251(added)X -2479(in)X -2577(the)X -2 f -2711(hsearch)X -1 f -3000(library)X -3249(routines)X -3542([ATT85].)X -3907(The)X -1152 1486(result)N -1367(is)X -1457(a)X -1530(system)X -1789(with)X -1968(two)X -2125(incompatible)X -2580(hashing)X -2865(schemes,)X -3193(each)X -3377(with)X -3555(its)X -3666(own)X -3840(set)X -3965(of)X -1152 1574(shortcomings.)N -1152 1688(This)N -1316(paper)X -1517(presents)X -1802(the)X -1922(design)X -2152(and)X -2289(performance)X -2717(characteristics)X -3198(of)X -3286(a)X -3343(new)X -3498(hashing)X -3768(package)X -1152 1776(providing)N -1483(a)X -1539(superset)X -1822(of)X -1909(the)X -2027(functionality)X -2456(provided)X -2761(by)X -2 f -2861(dbm)X -1 f -3019(and)X -2 f -3155(hsearch)X -1 f -3409(.)X -3469(The)X -3614(new)X -3768(package)X -1152 1864(uses)N -1322(linear)X -1537(hashing)X -1818(to)X -1912(provide)X -2189(ef\256cient)X -2484(support)X -2755(of)X -2853(both)X -3026(memory)X -3324(based)X -3538(and)X -3685(disk)X -3849(based)X -1152 1952(hash)N -1319(tables)X -1526(with)X -1688(performance)X -2115(superior)X -2398(to)X -2480(both)X -2 f -2642(dbm)X -1 f -2800(and)X -2 f -2936(hsearch)X -1 f -3210(under)X -3413(most)X -3588(conditions.)X -3 f -1380 2128(Introduction)N -1 f -892 2260(Current)N -1196(UNIX)X -1456(systems)X -1768(offer)X -1984(two)X -2163(forms)X -2409(of)X -720 2348(hashed)N -973(data)X -1137(access.)X -2 f -1413(Dbm)X -1 f -1599(and)X -1745(its)X -1850(derivatives)X -2231(provide)X -720 2436(keyed)N -939(access)X -1171(to)X -1259(disk)X -1418(resident)X -1698(data)X -1858(while)X -2 f -2062(hsearch)X -1 f -2342(pro-)X -720 2524(vides)N -929(access)X -1175(for)X -1309(memory)X -1616(resident)X -1910(data.)X -2124(These)X -2356(two)X -720 2612(access)N -979(methods)X -1302(are)X -1453(incompatible)X -1923(in)X -2037(that)X -2209(memory)X -720 2700(resident)N -1011(hash)X -1195(tables)X -1419(may)X -1593(not)X -1731(be)X -1843(stored)X -2075(on)X -2191(disk)X -2360(and)X -720 2788(disk)N -884(resident)X -1169(tables)X -1387(cannot)X -1632(be)X -1739(read)X -1909(into)X -2063(memory)X -2360(and)X -720 2876(accessed)N -1022(using)X -1215(the)X -1333(in-memory)X -1709(routines.)X -2 f -892 2990(Dbm)N -1 f -1091(has)X -1241(several)X -1512(shortcomings.)X -2026(Since)X -2247(data)X -2423(is)X -720 3078(assumed)N -1032(to)X -1130(be)X -1242(disk)X -1411(resident,)X -1721(each)X -1905(access)X -2146(requires)X -2440(a)X -720 3166(system)N -963(call,)X -1120(and)X -1257(almost)X -1491(certainly,)X -1813(a)X -1869(disk)X -2022(operation.)X -2365(For)X -720 3254(extremely)N -1072(large)X -1264(databases,)X -1623(where)X -1851(caching)X -2131(is)X -2214(unlikely)X -720 3342(to)N -810(be)X -914(effective,)X -1244(this)X -1386(is)X -1466(acceptable,)X -1853(however,)X -2177(when)X -2378(the)X -720 3430(database)N -1022(is)X -1100(small)X -1298(\(i.e.)X -1447(the)X -1569(password)X -1896(\256le\),)X -2069(performance)X -720 3518(improvements)N -1204(can)X -1342(be)X -1443(obtained)X -1744(through)X -2018(caching)X -2293(pages)X -720 3606(of)N -818(the)X -947(database)X -1255(in)X -1348(memory.)X -1685(In)X -1782(addition,)X -2 f -2094(dbm)X -1 f -2262(cannot)X -720 3694(store)N -902(data)X -1062(items)X -1261(whose)X -1492(total)X -1660(key)X -1802(and)X -1943(data)X -2102(size)X -2252(exceed)X -720 3782(the)N -850(page)X -1034(size)X -1191(of)X -1290(the)X -1420(hash)X -1599(table.)X -1827(Similarly,)X -2176(if)X -2257(two)X -2409(or)X -720 3870(more)N -907(keys)X -1076(produce)X -1357(the)X -1477(same)X -1664(hash)X -1833(value)X -2029(and)X -2166(their)X -2334(total)X -720 3958(size)N -876(exceeds)X -1162(the)X -1291(page)X -1474(size,)X -1650(the)X -1779(table)X -1966(cannot)X -2210(store)X -2396(all)X -720 4046(the)N -838(colliding)X -1142(keys.)X -892 4160(The)N -1050(in-memory)X -2 f -1439(hsearch)X -1 f -1725(routines)X -2015(have)X -2199(different)X -720 4248(shortcomings.)N -1219(First,)X -1413(the)X -1539(notion)X -1771(of)X -1865(a)X -1928(single)X -2146(hash)X -2320(table)X -720 4336(is)N -807(embedded)X -1171(in)X -1266(the)X -1397(interface,)X -1732(preventing)X -2108(an)X -2217(applica-)X -720 4424(tion)N -902(from)X -1116(accessing)X -1482(multiple)X -1806(tables)X -2050(concurrently.)X -720 4512(Secondly,)N -1063(the)X -1186(routine)X -1438(to)X -1525(create)X -1743(a)X -1804(hash)X -1976(table)X -2157(requires)X -2440(a)X -720 4600(parameter)N -1066(which)X -1286(declares)X -1573(the)X -1694(size)X -1842(of)X -1932(the)X -2053(hash)X -2223(table.)X -2422(If)X -720 4688(this)N -856(size)X -1001(is)X -1074(set)X -1183(too)X -1305(low,)X -1465(performance)X -1892(degradation)X -2291(or)X -2378(the)X -720 4776(inability)N -1008(to)X -1092(add)X -1230(items)X -1425(to)X -1509(the)X -1628(table)X -1805(may)X -1964(result.)X -2223(In)X -2311(addi-)X -720 4864(tion,)N -2 f -910(hsearch)X -1 f -1210(requires)X -1515(that)X -1681(the)X -1825(application)X -2226(allocate)X -720 4952(memory)N -1037(for)X -1181(the)X -1329(key)X -1495(and)X -1661(data)X -1845(items.)X -2108(Lastly,)X -2378(the)X -2 f -720 5040(hsearch)N -1 f -1013(routines)X -1310(provide)X -1594(no)X -1713(interface)X -2034(to)X -2135(store)X -2329(hash)X -720 5128(tables)N -927(on)X -1027(disk.)X -16 s -720 5593 MXY -864 0 Dl -2 f -8 s -760 5648(1)N -1 f -9 s -5673(UNIX)Y -990(is)X -1056(a)X -1106(registered)X -1408(trademark)X -1718(of)X -1796(AT&T.)X -10 s -2878 2128(The)N -3032(goal)X -3199(of)X -3295(our)X -3431(work)X -3625(was)X -3779(to)X -3870(design)X -4108(and)X -4253(imple-)X -2706 2216(ment)N -2900(a)X -2970(new)X -3138(package)X -3436(that)X -3590(provides)X -3899(a)X -3968(superset)X -4264(of)X -4364(the)X -2706 2304(functionality)N -3144(of)X -3240(both)X -2 f -3411(dbm)X -1 f -3578(and)X -2 f -3723(hsearch)X -1 f -3977(.)X -4045(The)X -4198(package)X -2706 2392(had)N -2871(to)X -2982(overcome)X -3348(the)X -3495(interface)X -3826(shortcomings)X -4306(cited)X -2706 2480(above)N -2930(and)X -3078(its)X -3185(implementation)X -3719(had)X -3867(to)X -3961(provide)X -4238(perfor-)X -2706 2568(mance)N -2942(equal)X -3142(or)X -3235(superior)X -3524(to)X -3612(that)X -3758(of)X -3851(the)X -3975(existing)X -4253(imple-)X -2706 2656(mentations.)N -3152(In)X -3274(order)X -3498(to)X -3614(provide)X -3913(a)X -4003(compact)X -4329(disk)X -2706 2744(representation,)N -3224(graceful)X -3531(table)X -3729(growth,)X -4018(and)X -4176(expected)X -2706 2832(constant)N -3033(time)X -3234(performance,)X -3720(we)X -3873(selected)X -4191(Litwin's)X -2706 2920(linear)N -2923(hashing)X -3206(algorithm)X -3551([LAR88,)X -3872(LIT80].)X -4178(We)X -4324(then)X -2706 3008(enhanced)N -3037(the)X -3161(algorithm)X -3498(to)X -3586(handle)X -3826(page)X -4004(over\257ows)X -4346(and)X -2706 3096(large)N -2900(key)X -3049(handling)X -3362(with)X -3537(a)X -3606(single)X -3830(mechanism,)X -4248(named)X -2706 3184(buddy-in-waiting.)N -3 f -2975 3338(Existing)N -3274(UNIX)X -3499(Hashing)X -3802(Techniques)X -1 f -2878 3470(Over)N -3076(the)X -3210(last)X -3357(decade,)X -3637(several)X -3901(dynamic)X -4213(hashing)X -2706 3558(schemes)N -3000(have)X -3174(been)X -3348(developed)X -3700(for)X -3816(the)X -3936(UNIX)X -4159(timeshar-)X -2706 3646(ing)N -2856(system,)X -3146(starting)X -3433(with)X -3622(the)X -3767(inclusion)X -4107(of)X -2 f -4221(dbm)X -1 f -4359(,)X -4426(a)X -2706 3734(minimal)N -3008(database)X -3321(library)X -3571(written)X -3834(by)X -3950(Ken)X -4120(Thompson)X -2706 3822([THOM90],)N -3141(in)X -3248(the)X -3391(Seventh)X -3694(Edition)X -3974(UNIX)X -4220(system.)X -2706 3910(Since)N -2916(then,)X -3106(an)X -3214(extended)X -3536(version)X -3804(of)X -3903(the)X -4032(same)X -4228(library,)X -2 f -2706 3998(ndbm)N -1 f -2884(,)X -2933(and)X -3078(a)X -3142(public-domain)X -3637(clone)X -3839(of)X -3934(the)X -4060(latter,)X -2 f -4273(sdbm)X -1 f -4442(,)X -2706 4086(have)N -2902(been)X -3098(developed.)X -3491(Another)X -3797 0.1645(interface-compatible)AX -2706 4174(library)N -2 f -2950(gdbm)X -1 f -3128(,)X -3178(was)X -3333(recently)X -3622(made)X -3826(available)X -4145(as)X -4241(part)X -4395(of)X -2706 4262(the)N -2829(Free)X -2997(Software)X -3312(Foundation's)X -3759(\(FSF\))X -3970(software)X -4271(distri-)X -2706 4350(bution.)N -2878 4464(All)N -3017(of)X -3121(these)X -3323(implementations)X -3893(are)X -4029(based)X -4248(on)X -4364(the)X -2706 4552(idea)N -2871(of)X -2969(revealing)X -3299(just)X -3445(enough)X -3711(bits)X -3856(of)X -3953(a)X -4019(hash)X -4196(value)X -4400(to)X -2706 4640(locate)N -2920(a)X -2978(page)X -3151(in)X -3234(a)X -3291(single)X -3503(access.)X -3770(While)X -2 f -3987(dbm/ndbm)X -1 f -4346(and)X -2 f -2706 4728(sdbm)N -1 f -2908(map)X -3079(the)X -3210(hash)X -3390(value)X -3597(directly)X -3874(to)X -3968(a)X -4036(disk)X -4201(address,)X -2 f -2706 4816(gdbm)N -1 f -2921(uses)X -3096(the)X -3231(hash)X -3414(value)X -3624(to)X -3722(index)X -3936(into)X -4096(a)X -2 f -4168(directory)X -1 f -2706 4904([ENB88])N -3020(containing)X -3378(disk)X -3531(addresses.)X -2878 5018(The)N -2 f -3033(hsearch)X -1 f -3317(routines)X -3605(in)X -3697(System)X -3962(V)X -4049(are)X -4177(designed)X -2706 5106(to)N -2804(provide)X -3085(memory-resident)X -3669(hash)X -3852(tables.)X -4115(Since)X -4328(data)X -2706 5194(access)N -2948(does)X -3131(not)X -3269(require)X -3533(disk)X -3702(access,)X -3964(simple)X -4213(hashing)X -2706 5282(schemes)N -3010(which)X -3238(may)X -3408(require)X -3667(multiple)X -3964(probes)X -4209(into)X -4364(the)X -2706 5370(table)N -2889(are)X -3015(used.)X -3209(A)X -3294(more)X -3486(interesting)X -3851(version)X -4114(of)X -2 f -4208(hsearch)X -1 f -2706 5458(is)N -2784(a)X -2845(public)X -3070(domain)X -3335(library,)X -2 f -3594(dynahash)X -1 f -3901(,)X -3945(that)X -4089(implements)X -2706 5546(Larson's)N -3036(in-memory)X -3440(adaptation)X -3822([LAR88])X -4164(of)X -4279(linear)X -2706 5634(hashing)N -2975([LIT80].)X -3 f -720 5960(USENIX)N -9 f -1042(-)X -3 f -1106(Winter)X -1371('91)X -9 f -1498(-)X -3 f -1562(Dallas,)X -1815(TX)X -1 f -4424(1)X - -2 p -%%Page: 2 2 -10 s 10 xH 0 xS 1 f -3 f -432 258(A)N -510(New)X -682(Hashing)X -985(Package)X -1290(for)X -1413(UNIX)X -3663(Seltzer)X -3920(&)X -4007(Yigit)X -2 f -1074 538(dbm)N -1 f -1232(and)X -2 f -1368(ndbm)X -1 f -604 670(The)N -2 f -760(dbm)X -1 f -928(and)X -2 f -1074(ndbm)X -1 f -1282(library)X -1526(implementations)X -2089(are)X -432 758(based)N -667(on)X -799(the)X -949(same)X -1166(algorithm)X -1529(by)X -1661(Ken)X -1846(Thompson)X -432 846([THOM90,)N -824(TOR88,)X -1113(WAL84],)X -1452(but)X -1582(differ)X -1789(in)X -1879(their)X -2054(pro-)X -432 934(grammatic)N -801(interfaces.)X -1160(The)X -1311(latter)X -1502(is)X -1581(a)X -1643(modi\256ed)X -1952(version)X -432 1022(of)N -533(the)X -665(former)X -918(which)X -1148(adds)X -1328(support)X -1601(for)X -1728(multiple)X -2027(data-)X -432 1110(bases)N -634(to)X -724(be)X -828(open)X -1011(concurrently.)X -1484(The)X -1636(discussion)X -1996(of)X -2090(the)X -432 1198(algorithm)N -774(that)X -925(follows)X -1196(is)X -1280(applicable)X -1640(to)X -1732(both)X -2 f -1904(dbm)X -1 f -2072(and)X -2 f -432 1286(ndbm)N -1 f -610(.)X -604 1400(The)N -760(basic)X -956(structure)X -1268(of)X -2 f -1366(dbm)X -1 f -1535(calls)X -1712(for)X -1836(\256xed-sized)X -432 1488(disk)N -612(blocks)X -868(\(buckets\))X -1214(and)X -1377(an)X -2 f -1499(access)X -1 f -1755(function)X -2068(that)X -432 1576(maps)N -623(a)X -681(key)X -819(to)X -902(a)X -959(bucket.)X -1234(The)X -1380(interface)X -1683(routines)X -1962(use)X -2090(the)X -2 f -432 1664(access)N -1 f -673(function)X -970(to)X -1062(obtain)X -1292(the)X -1420(appropriate)X -1816(bucket)X -2060(in)X -2152(a)X -432 1752(single)N -643(disk)X -796(access.)X -604 1866(Within)N -869(the)X -2 f -1010(access)X -1 f -1263(function,)X -1593(a)X -1672(bit-randomizing)X -432 1954(hash)N -610(function)X -2 f -8 s -877 1929(2)N -1 f -10 s -940 1954(is)N -1024(used)X -1202(to)X -1294(convert)X -1565(a)X -1631(key)X -1777(into)X -1931(a)X -1997(32-bit)X -432 2042(hash)N -605(value.)X -825(Out)X -971(of)X -1064(these)X -1254(32)X -1359(bits,)X -1519(only)X -1686(as)X -1778(many)X -1981(bits)X -2121(as)X -432 2130(necessary)N -773(are)X -900(used)X -1075(to)X -1165(determine)X -1514(the)X -1639(particular)X -1974(bucket)X -432 2218(on)N -533(which)X -750(a)X -807(key)X -944(resides.)X -1228(An)X -1347(in-memory)X -1724(bitmap)X -1967(is)X -2041(used)X -432 2306(to)N -533(determine)X -893(how)X -1070(many)X -1287(bits)X -1441(are)X -1579(required.)X -1905(Each)X -2104(bit)X -432 2394(indicates)N -746(whether)X -1033(its)X -1136(associated)X -1494(bucket)X -1736(has)X -1871(been)X -2051(split)X -432 2482(yet)N -562(\(a)X -657(0)X -728(indicating)X -1079(that)X -1230(the)X -1359(bucket)X -1604(has)X -1742(not)X -1875(yet)X -2004(split\).)X -432 2570(The)N -590(use)X -730(of)X -830(the)X -961(hash)X -1141(function)X -1441(and)X -1590(the)X -1720(bitmap)X -1974(is)X -2059(best)X -432 2658(described)N -769(by)X -878(stepping)X -1177(through)X -1454(database)X -1759(creation)X -2046(with)X -432 2746(multiple)N -718(invocations)X -1107(of)X -1194(a)X -2 f -1250(store)X -1 f -1430(operation.)X -604 2860(Initially,)N -906(the)X -1033(hash)X -1209(table)X -1394(contains)X -1690(a)X -1755(single)X -1974(bucket)X -432 2948(\(bucket)N -711(0\),)X -836(the)X -972(bit)X -1094(map)X -1270(contains)X -1575(a)X -1649(single)X -1878(bit)X -2000(\(bit)X -2148(0)X -432 3036(corresponding)N -913(to)X -997(bucket)X -1233(0\),)X -1342(and)X -1480(0)X -1542(bits)X -1699(of)X -1788(a)X -1846(hash)X -2014(value)X -432 3124(are)N -560(examined)X -901(to)X -992(determine)X -1342(where)X -1568(a)X -1633(key)X -1778(is)X -1860(placed)X -2099(\(in)X -432 3212(bucket)N -670(0\).)X -801(When)X -1017(bucket)X -1255(0)X -1319(is)X -1396(full,)X -1551(its)X -1650(bit)X -1758(in)X -1844(the)X -1966(bitmap)X -432 3300(\(bit)N -564(0\))X -652(is)X -726(set,)X -856(and)X -993(its)X -1089(contents)X -1377(are)X -1497(split)X -1655(between)X -1943(buckets)X -432 3388(0)N -499(and)X -641(1,)X -727(by)X -833(considering)X -1233(the)X -1357(0)X -2 f -7 s -3356(th)Y -10 s -1 f -1480 3388(bit)N -1590(\(the)X -1741(lowest)X -1976(bit)X -2086(not)X -432 3476(previously)N -800(examined\))X -1169(of)X -1266(the)X -1393(hash)X -1569(value)X -1772(for)X -1895(each)X -2072(key)X -432 3564(within)N -668(the)X -798(bucket.)X -1064(Given)X -1292(a)X -1359(well-designed)X -1840(hash)X -2018(func-)X -432 3652(tion,)N -613(approximately)X -1112(half)X -1273(of)X -1376(the)X -1510(keys)X -1693(will)X -1853(have)X -2041(hash)X -432 3740(values)N -666(with)X -837(the)X -964(0)X -2 f -7 s -3708(th)Y -10 s -1 f -1090 3740(bit)N -1203(set.)X -1341(All)X -1471(such)X -1646(keys)X -1821(and)X -1965(associ-)X -432 3828(ated)N -586(data)X -740(are)X -859(moved)X -1097(to)X -1179(bucket)X -1413(1,)X -1493(and)X -1629(the)X -1747(rest)X -1883(remain)X -2126(in)X -432 3916(bucket)N -666(0.)X -604 4030(After)N -804(this)X -949(split,)X -1135(the)X -1262(\256le)X -1393(now)X -1560(contains)X -1856(two)X -2005(buck-)X -432 4118(ets,)N -562(and)X -699(the)X -818(bitmap)X -1061(contains)X -1349(three)X -1530(bits:)X -1687(the)X -1805(0)X -2 f -7 s -4086(th)Y -10 s -1 f -1922 4118(bit)N -2026(is)X -2099(set)X -432 4206(to)N -525(indicate)X -810(a)X -876(bucket)X -1120(0)X -1190(split)X -1357(when)X -1561(no)X -1671(bits)X -1816(of)X -1913(the)X -2041(hash)X -432 4294(value)N -648(are)X -789(considered,)X -1199(and)X -1357(two)X -1519(more)X -1726(unset)X -1937(bits)X -2094(for)X -432 4382(buckets)N -706(0)X -775(and)X -920(1.)X -1029(The)X -1183(placement)X -1542(of)X -1638(an)X -1742(incoming)X -2072(key)X -432 4470(now)N -604(requires)X -897(examination)X -1327(of)X -1428(the)X -1560(0)X -2 f -7 s -4438(th)Y -10 s -1 f -1691 4470(bit)N -1809(of)X -1910(the)X -2041(hash)X -432 4558(value,)N -667(and)X -824(the)X -963(key)X -1119(is)X -1212(placed)X -1462(either)X -1685(in)X -1787(bucket)X -2041(0)X -2121(or)X -432 4646(bucket)N -674(1.)X -782(If)X -864(either)X -1075(bucket)X -1317(0)X -1385(or)X -1480(bucket)X -1722(1)X -1790(\256lls)X -1937(up,)X -2064(it)X -2135(is)X -432 4734(split)N -598(as)X -693(before,)X -947(its)X -1050(bit)X -1162(is)X -1243(set)X -1360(in)X -1450(the)X -1576(bitmap,)X -1846(and)X -1990(a)X -2054(new)X -432 4822(set)N -541(of)X -628(unset)X -817(bits)X -952(are)X -1071(added)X -1283(to)X -1365(the)X -1483(bitmap.)X -604 4936(Each)N -791(time)X -959(we)X -1079(consider)X -1376(a)X -1437(new)X -1596(bit)X -1705(\(bit)X -1841(n\),)X -1953(we)X -2072(add)X -432 5024(2)N -2 f -7 s -4992(n)Y -9 f -509(+)X -1 f -540(1)X -10 s -595 5024(bits)N -737(to)X -826(the)X -951(bitmap)X -1199(and)X -1341(obtain)X -1567(2)X -2 f -7 s -4992(n)Y -9 f -1644(+)X -1 f -1675(1)X -10 s -1729 5024(more)N -1920(address-)X -432 5112(able)N -595(buckets)X -869(in)X -960(the)X -1087(\256le.)X -1258(As)X -1376(a)X -1441(result,)X -1668(the)X -1795(bitmap)X -2045(con-)X -432 5200(tains)N -618(the)X -751(previous)X -1062(2)X -2 f -7 s -5168(n)Y -9 f -1139(+)X -1 f -1170(1)X -2 f -10 s -9 f -5200(-)Y -1 f -1242(1)X -1317(bits)X -1467(\(1)X -2 f -9 f -1534(+)X -1 f -1578(2)X -2 f -9 f -(+)S -1 f -1662(4)X -2 f -9 f -(+)S -1 f -1746(...)X -2 f -9 f -(+)S -1 f -1850(2)X -2 f -7 s -5168(n)Y -10 s -1 f -1931 5200(\))N -1992(which)X -432 5288(trace)N -649(the)X -807(entire)X -2 f -1050(split)X -1247(history)X -1 f -1529(of)X -1656(the)X -1813(addressable)X -16 s -432 5433 MXY -864 0 Dl -2 f -8 s -472 5488(2)N -1 f -9 s -523 5513(This)N -670(bit-randomizing)X -1153(property)X -1416(is)X -1482(important)X -1780(to)X -1854(obtain)X -2052(radi-)X -432 5593(cally)N -599(different)X -874(hash)X -1033(values)X -1244(for)X -1355(nearly)X -1562(identical)X -1836(keys,)X -2012(which)X -432 5673(in)N -506(turn)X -640(avoids)X -846(clustering)X -1148(of)X -1226(such)X -1376(keys)X -1526(in)X -1600(a)X -1650(single)X -1840(bucket.)X -10 s -2418 538(buckets.)N -2590 652(Given)N -2809(a)X -2868(key)X -3007(and)X -3146(the)X -3267(bitmap)X -3512(created)X -3768(by)X -3871(this)X -4009(algo-)X -2418 740(rithm,)N -2638(we)X -2759(\256rst)X -2910(examine)X -3209(bit)X -3320(0)X -3386(of)X -3479(the)X -3603(bitmap)X -3851(\(the)X -4002(bit)X -4112(to)X -2418 828(consult)N -2673(when)X -2871(0)X -2934(bits)X -3072(of)X -3162(the)X -3283(hash)X -3453(value)X -3650(are)X -3772(being)X -3973(exam-)X -2418 916(ined\).)N -2631(If)X -2713(it)X -2785(is)X -2866(set)X -2982(\(indicating)X -3356(that)X -3503(the)X -3628(bucket)X -3869(split\),)X -4080(we)X -2418 1004(begin)N -2617(considering)X -3012(the)X -3131(bits)X -3267(of)X -3355(the)X -3473(32-bit)X -3684(hash)X -3851(value.)X -4085(As)X -2418 1092(bit)N -2525(n)X -2587(is)X -2662(revealed,)X -2977(a)X -3035(mask)X -3226(equal)X -3422(to)X -3506(2)X -2 f -7 s -1060(n)Y -9 f -3583(+)X -1 f -3614(1)X -2 f -10 s -9 f -1092(-)Y -1 f -3686(1)X -3748(will)X -3894(yield)X -4076(the)X -2418 1180(current)N -2675(bucket)X -2918(address.)X -3228(Adding)X -3496(2)X -2 f -7 s -1148(n)Y -9 f -3573(+)X -1 f -3604(1)X -2 f -10 s -9 f -1180(-)Y -1 f -3676(1)X -3744(to)X -3834(the)X -3960(bucket)X -2418 1268(address)N -2701(identi\256es)X -3035(which)X -3272(bit)X -3397(in)X -3500(the)X -3639(bitmap)X -3902(must)X -4098(be)X -2418 1356(checked.)N -2743(We)X -2876(continue)X -3173(revealing)X -3493(bits)X -3628(of)X -3715(the)X -3833(hash)X -4000(value)X -2418 1444(until)N -2591(all)X -2698(set)X -2814(bits)X -2955(in)X -3043(the)X -3167(bitmap)X -3415(are)X -3540(exhausted.)X -3907(The)X -4058(fol-)X -2418 1532(lowing)N -2682(algorithm,)X -3055(a)X -3133(simpli\256cation)X -3614(of)X -3723(the)X -3863(algorithm)X -2418 1620(due)N -2565(to)X -2658(Ken)X -2823(Thompson)X -3196([THOM90,)X -3590(TOR88],)X -3908(uses)X -4076(the)X -2418 1708(hash)N -2625(value)X -2839(and)X -2995(the)X -3133(bitmap)X -3395(to)X -3497(calculate)X -3823(the)X -3960(bucket)X -2418 1796(address)N -2679(as)X -2766(discussed)X -3093(above.)X -0(Courier)xf 0 f -1 f -0 f -8 s -2418 2095(hash)N -2608(=)X -2684 -0.4038(calchash\(key\);)AX -2418 2183(mask)N -2608(=)X -2684(0;)X -2418 2271(while)N -2646 -0.4018(\(isbitset\(\(hash)AX -3254(&)X -3330(mask\))X -3558(+)X -3634(mask\)\))X -2706 2359(mask)N -2896(=)X -2972(\(mask)X -3200(<<)X -3314(1\))X -3428(+)X -3504(1;)X -2418 2447(bucket)N -2684(=)X -2760(hash)X -2950(&)X -3026(mask;)X -2 f -10 s -3211 2812(sdbm)N -1 f -2590 2944(The)N -2 f -2738(sdbm)X -1 f -2930(library)X -3167(is)X -3243(a)X -3302(public-domain)X -3791(clone)X -3987(of)X -4076(the)X -2 f -2418 3032(ndbm)N -1 f -2638(library,)X -2914(developed)X -3286(by)X -3408(Ozan)X -3620(Yigit)X -3826(to)X -3929(provide)X -2 f -2418 3120(ndbm)N -1 f -2596('s)X -2692(functionality)X -3139(under)X -3359(some)X -3565(versions)X -3869(of)X -3973(UNIX)X -2418 3208(that)N -2559(exclude)X -2830(it)X -2894(for)X -3008(licensing)X -3317(reasons)X -3578([YIG89].)X -3895(The)X -4040(pro-)X -2418 3296(grammer)N -2735(interface,)X -3064(and)X -3207(the)X -3332(basic)X -3524(structure)X -3832(of)X -2 f -3926(sdbm)X -1 f -4121(is)X -2418 3384(identical)N -2733(to)X -2 f -2834(ndbm)X -1 f -3051(but)X -3192(internal)X -3476(details)X -3723(of)X -3828(the)X -2 f -3964(access)X -1 f -2418 3472(function,)N -2726(such)X -2894(as)X -2982(the)X -3101(calculation)X -3474(of)X -3561(the)X -3679(bucket)X -3913(address,)X -2418 3560(and)N -2563(the)X -2690(use)X -2825(of)X -2920(different)X -3225(hash)X -3400(functions)X -3726(make)X -3928(the)X -4054(two)X -2418 3648(incompatible)N -2856(at)X -2934(the)X -3052(database)X -3349(level.)X -2590 3762(The)N -2 f -2740(sdbm)X -1 f -2934(library)X -3173(is)X -3251(based)X -3458(on)X -3562(a)X -3622(simpli\256ed)X -3965(imple-)X -2418 3850(mentation)N -2778(of)X -2885(Larson's)X -3206(1978)X -2 f -3406(dynamic)X -3717(hashing)X -1 f -4009(algo-)X -2418 3938(rithm)N -2616(including)X -2943(the)X -2 f -3066(re\256nements)X -3461(and)X -3605(variations)X -1 f -3953(of)X -4044(sec-)X -2418 4026(tion)N -2562(5)X -2622([LAR78].)X -2956(Larson's)X -3257(original)X -3526(algorithm)X -3857(calls)X -4024(for)X -4138(a)X -2418 4114(forest)N -2635(of)X -2736(binary)X -2975(hash)X -3156(trees)X -3341(that)X -3494(are)X -3626(accessed)X -3941(by)X -4054(two)X -2418 4202(hash)N -2586(functions.)X -2925(The)X -3071(\256rst)X -3216(hash)X -3384(function)X -3672(selects)X -3907(a)X -3964(partic-)X -2418 4290(ular)N -2571(tree)X -2720(within)X -2952(the)X -3078(forest.)X -3309(The)X -3462(second)X -3713(hash)X -3887(function,)X -2418 4378(which)N -2659(is)X -2757(required)X -3070(to)X -3177(be)X -3297(a)X -3377(boolean)X -3675(pseudo-random)X -2418 4466(number)N -2687(generator)X -3015(that)X -3159(is)X -3236(seeded)X -3479(by)X -3583(the)X -3705(key,)X -3865(is)X -3942(used)X -4112(to)X -2418 4554(traverse)N -2733(the)X -2890(tree)X -3070(until)X -3275(internal)X -3579(\(split\))X -3829(nodes)X -4075(are)X -2418 4642(exhausted)N -2763(and)X -2903(an)X -3003(external)X -3286(\(non-split\))X -3648(node)X -3827(is)X -3903(reached.)X -2418 4730(The)N -2571(bucket)X -2813(addresses)X -3149(are)X -3276(stored)X -3500(directly)X -3772(in)X -3861(the)X -3986(exter-)X -2418 4818(nal)N -2536(nodes.)X -2590 4932(Larson's)N -2903(re\256nements)X -3309(are)X -3440(based)X -3655(on)X -3767(the)X -3897(observa-)X -2418 5020(tion)N -2570(that)X -2718(the)X -2844(nodes)X -3059(can)X -3199(be)X -3303(represented)X -3702(by)X -3809(a)X -3872(single)X -4090(bit)X -2418 5108(that)N -2569(is)X -2653(set)X -2773(for)X -2898(internal)X -3174(nodes)X -3392(and)X -3539(not)X -3672(set)X -3791(for)X -3915(external)X -2418 5196(nodes,)N -2652(resulting)X -2959(in)X -3048(a)X -3111(radix)X -3303(search)X -3536(trie.)X -3709(Figure)X -3944(1)X -4010(illus-)X -2418 5284(trates)N -2621(this.)X -2804(Nodes)X -3037(A)X -3123(and)X -3267(B)X -3348(are)X -3475(internal)X -3748(\(split\))X -3967(nodes,)X -2418 5372(thus)N -2573(having)X -2813(no)X -2915(bucket)X -3151(addresses)X -3480(associated)X -3831(with)X -3994(them.)X -2418 5460(Instead,)N -2693(the)X -2814(external)X -3096(nodes)X -3306(\(C,)X -3429(D,)X -3530(and)X -3669(E\))X -3768(each)X -3938(need)X -4112(to)X -2418 5548(refer)N -2594(to)X -2679(a)X -2738(bucket)X -2975(address.)X -3279(These)X -3494(bucket)X -3731(addresses)X -4062(can)X -2418 5636(be)N -2529(stored)X -2760(in)X -2857(the)X -2990(trie)X -3132(itself)X -3327(where)X -3559(the)X -3691(subtries)X -3974(would)X -3 f -432 5960(2)N -2970(USENIX)X -9 f -3292(-)X -3 f -3356(Winter)X -3621('91)X -9 f -3748(-)X -3 f -3812(Dallas,)X -4065(TX)X - -3 p -%%Page: 3 3 -0(Courier)xf 0 f -10 s 10 xH 0 xS 0 f -3 f -720 258(Seltzer)N -977(&)X -1064(Yigit)X -3278(A)X -3356(New)X -3528(Hashing)X -3831(Package)X -4136(for)X -4259(UNIX)X -1 f -720 538(live)N -862(if)X -933(they)X -1092(existed)X -1340([KNU68].)X -1709(For)X -1841(example,)X -2154(if)X -2224(nodes)X -2432(F)X -720 626(and)N -858(G)X -938(were)X -1117(the)X -1237(children)X -1522(of)X -1610(node)X -1787(C,)X -1881(the)X -2000(bucket)X -2235(address)X -720 714(L00)N -886(could)X -1101(reside)X -1330(in)X -1429(the)X -1563(bits)X -1714(that)X -1870(will)X -2030(eventually)X -2400(be)X -720 802(used)N -887(to)X -969(store)X -1145(nodes)X -1352(F)X -1416(and)X -1552(G)X -1630(and)X -1766(all)X -1866(their)X -2033(children.)X -10 f -720 890 -0.0930(hhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhh)AN -3 f -1894 2247(L1)N -784 1925(A)N -1431(E)X -1106 2247(D)N -1428 1281(C)N -1109 1603(B)N -1884 1930(L01)N -1879 1286(L00)N -1221 1814(1)N -903 2131(1)N -1221 1402(0)N -903 1714(0)N -1 Dt -1397 1821 MXY --8 -32 Dl --5 19 Dl --20 6 Dl -33 7 Dl --187 -182 Dl -1397 1322 MXY --33 7 Dl -20 6 Dl -5 19 Dl -8 -32 Dl --187 182 Dl -1069 1639 MXY --32 7 Dl -20 6 Dl -5 19 Dl -7 -32 Dl --186 182 Dl -1374 1891 MXY -185 Dc -1779 2133 MXY -0 161 Dl -322 0 Dl -0 -161 Dl --322 0 Dl -1811 MY -0 161 Dl -322 0 Dl -0 -161 Dl --322 0 Dl -1166 MY -0 161 Dl -322 0 Dl -0 -161 Dl --322 0 Dl -1052 2213 MXY -185 Dc -1569 MY -185 Dc -720 1881 MXY -185 Dc -1779 2213 MXY --28 -17 Dl -10 17 Dl --10 18 Dl -28 -18 Dl --543 0 Dl -1769 1891 MXY --28 -18 Dl -10 18 Dl --10 18 Dl -28 -18 Dl --201 0 Dl -1364 1247 MXY -185 Dc -1769 MX --28 -18 Dl -10 18 Dl --10 18 Dl -28 -18 Dl --201 0 Dl -1064 2143 MXY --7 -32 Dl --5 19 Dl --20 6 Dl -32 7 Dl --181 -181 Dl -3 Dt --1 Ds -8 s -720 2482(Figure)N -925(1:)X -1 f -1002(Radix)X -1179(search)X -1365(trie)X -1474(with)X -1612(internal)X -1831(nodes)X -2004(A)X -2074(and)X -2189(B,)X -2271(external)X -720 2570(nodes)N -891(C,)X -972(D,)X -1056(and)X -1170(E,)X -1247(and)X -1361(bucket)X -1553(addresses)X -1819(stored)X -1997(in)X -2069(the)X -2168(unused)X -2370(por-)X -720 2658(tion)N -836(of)X -905(the)X -999(trie.)X -10 s -10 f -720 2922 -0.0930(hhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhh)AN -1 f -892 3124(Further)N -1153(simpli\256cations)X -1647(of)X -1738(the)X -1860(above)X -2076([YIG89])X -2377(are)X -720 3212(possible.)N -1038(Using)X -1265(a)X -1337(single)X -1564(radix)X -1765(trie)X -1908(to)X -2006(avoid)X -2219(the)X -2352(\256rst)X -720 3300(hash)N -904(function,)X -1227(replacing)X -1562(the)X -1696(pseudo-random)X -2231(number)X -720 3388(generator)N -1052(with)X -1222(a)X -1286(well)X -1452(designed,)X -1785(bit-randomizing)X -2329(hash)X -720 3476(function,)N -1053(and)X -1215(using)X -1434(the)X -1578(portion)X -1855(of)X -1967(the)X -2110(hash)X -2302(value)X -720 3564(exposed)N -1021(during)X -1268(the)X -1404(trie)X -1549(traversal)X -1864(as)X -1969(a)X -2042(direct)X -2262(bucket)X -720 3652(address)N -990(results)X -1228(in)X -1319(an)X -2 f -1424(access)X -1 f -1663(function)X -1959(that)X -2108(works)X -2333(very)X -720 3740(similar)N -974(to)X -1068(Thompson's)X -1499(algorithm)X -1841(above.)X -2084(The)X -2240(follow-)X -720 3828(ing)N -847(algorithm)X -1183(uses)X -1346(the)X -1469(hash)X -1641(value)X -1840(to)X -1927(traverse)X -2206(a)X -2266(linear-)X -720 3916(ized)N -874(radix)X -1059(trie)X -2 f -8 s -1166 3891(3)N -1 f -10 s -1218 3916(starting)N -1478(at)X -1556(the)X -1674(0)X -2 f -7 s -3884(th)Y -10 s -1 f -1791 3916(bit.)N -0 f -8 s -720 4215(tbit)N -910(=)X -986(0;)X -1296(/*)X -1410(radix)X -1638(trie)X -1828(index)X -2056(*/)X -720 4303(hbit)N -910(=)X -986(0;)X -1296(/*)X -1410(hash)X -1600(bit)X -1752(index)X -2056(*/)X -720 4391(mask)N -910(=)X -986(0;)X -720 4479(hash)N -910(=)X -986 -0.4038(calchash\(key\);)AX -720 4655(for)N -872(\(mask)X -1100(=)X -1176(0;)X -910 4743 -0.4018(isbitset\(tbit\);)AN -910 4831(mask)N -1100(=)X -1176(\(mask)X -1404(<<)X -1518(1\))X -1632(+)X -1708(1\))X -1008 4919(if)N -1122(\(hash)X -1350(&)X -1426(\(1)X -1540(<<)X -1654 -0.4219(hbit++\)\)\))AX -1160 5007(/*)N -1274(right)X -1502(son)X -1692(*/)X -1160 5095(tbit)N -1350(=)X -1426(2)X -1502(*)X -1578(tbit)X -1768(+)X -1844(2;)X -1008 5183(else)N -1 f -16 s -720 5353 MXY -864 0 Dl -2 f -8 s -760 5408(3)N -1 f -9 s -818 5433(A)N -896(linearized)X -1206(radix)X -1380(trie)X -1502(is)X -1576(merely)X -1802(an)X -1895(array)X -2068(representation)X -720 5513(of)N -800(the)X -908(radix)X -1076(search)X -1280(trie)X -1396(described)X -1692(above.)X -1920(The)X -2052(children)X -2308(of)X -2388(the)X -720 5593(node)N -885(with)X -1038(index)X -1223(i)X -1267(can)X -1391(be)X -1483(found)X -1675(at)X -1751(the)X -1863(nodes)X -2055(indexed)X -2307(2*i+1)X -720 5673(and)N -842(2*i+2.)X -0 f -8 s -3146 538(/*)N -3260(left)X -3450(son)X -3678(*/)X -3146 626(tbit)N -3336(=)X -3412(2)X -3488(*)X -3564(tbit)X -3754(+)X -3830(1;)X -2706 802(bucket)N -2972(=)X -3048(hash)X -3238(&)X -3314(mask;)X -2 f -10 s -3495 1167(gdbm)N -1 f -2878 1299(The)N -3027(gdbm)X -3233(\(GNU)X -3458(data)X -3616(base)X -3783(manager\))X -4111(library)X -4349(is)X -4426(a)X -2706 1387(UNIX)N -2933(database)X -3236(manager)X -3539(written)X -3792(by)X -3897(Philip)X -4112(A.)X -4215(Nelson,)X -2706 1475(and)N -2848(made)X -3048(available)X -3364(as)X -3457(a)X -3518(part)X -3668(of)X -3760(the)X -3883(FSF)X -4040(software)X -4342(dis-)X -2706 1563(tribution.)N -3052(The)X -3207(gdbm)X -3419(library)X -3663(provides)X -3969(the)X -4097(same)X -4292(func-)X -2706 1651(tionality)N -3028(of)X -3151(the)X -2 f -3304(dbm)X -1 f -3442(/)X -2 f -3464(ndbm)X -1 f -3697(libraries)X -4015([NEL90])X -4360(but)X -2706 1739(attempts)N -3018(to)X -3121(avoid)X -3340(some)X -3550(of)X -3658(their)X -3846(shortcomings.)X -4337(The)X -2706 1827(gdbm)N -2918(library)X -3162(allows)X -3401(for)X -3525(arbitrary-length)X -4059(data,)X -4242(and)X -4387(its)X -2706 1915(database)N -3027(is)X -3124(a)X -3203(singular,)X -3524(non-sparse)X -2 f -8 s -3872 1890(4)N -1 f -10 s -3947 1915(\256le.)N -4112(The)X -4280(gdbm)X -2706 2003(library)N -2947(also)X -3103(includes)X -2 f -3396(dbm)X -1 f -3560(and)X -2 f -3702(ndbm)X -1 f -3906(compatible)X -4288(inter-)X -2706 2091(faces.)N -2878 2205(The)N -3025(gdbm)X -3229(library)X -3465(is)X -3540(based)X -3745(on)X -2 f -3847(extensible)X -4189(hashing)X -1 f -4442(,)X -2706 2293(a)N -2766(dynamic)X -3066(hashing)X -3339(algorithm)X -3674(by)X -3778(Fagin)X -3984(et)X -4066(al)X -4148([FAG79].)X -2706 2381(This)N -2881(algorithm)X -3225(differs)X -3467(from)X -3655(the)X -3785(previously)X -4155(discussed)X -2706 2469(algorithms)N -3069(in)X -3152(that)X -3293(it)X -3358(uses)X -3517(a)X -2 f -3574(directory)X -1 f -3889(that)X -4030(is)X -4103(a)X -4159(collapsed)X -2706 2557(representation)N -3192([ENB88])X -3517(of)X -3615(the)X -3744(radix)X -3940(search)X -4177(trie)X -4315(used)X -2706 2645(by)N -2 f -2806(sdbm)X -1 f -2975(.)X -10 f -2706 2733 -0.0930(hhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhh)AN -3 f -7 s -3572 3761(L1)N -1 Dt -3485 3738 MXY --20 -13 Dl -7 13 Dl --7 13 Dl -20 -13 Dl --400 0 Dl -3180 3027 MXY -136 Dc -2706 3494 MXY -136 Dc -2950 3264 MXY -136 Dc -3738 MY -136 Dc -3485 2968 MXY -0 118 Dl -238 0 Dl -0 -118 Dl --238 0 Dl -3442 MY -0 119 Dl -238 0 Dl -0 -119 Dl --238 0 Dl -3679 MY -0 119 Dl -238 0 Dl -0 -119 Dl --238 0 Dl -3187 3501 MXY -136 Dc -2963 3316 MXY --24 5 Dl -15 4 Dl -4 15 Dl -5 -24 Dl --137 134 Dl -3204 3083 MXY --24 5 Dl -15 4 Dl -3 14 Dl -6 -23 Dl --137 133 Dl -3204 3450 MXY --6 -24 Dl --3 14 Dl --15 5 Dl -24 5 Dl --137 -134 Dl -2842 3369(0)N -3075 3139(0)N -2842 3676(1)N -3075 3443(1)N -3562 3054(L00)N -3565 3528(L01)N -4197 2968 MXY -0 118 Dl -237 0 Dl -0 -118 Dl --237 0 Dl -3205 MY -0 119 Dl -237 0 Dl -0 -119 Dl --237 0 Dl -3561 MY -0 118 Dl -237 0 Dl -0 -118 Dl --237 0 Dl -3960 2909 MXY -0 237 Dl -118 0 Dl -0 -237 Dl --118 0 Dl -3146 MY -0 237 Dl -118 0 Dl -0 -237 Dl --118 0 Dl -3383 MY -0 237 Dl -118 0 Dl -0 -237 Dl --118 0 Dl -3620 MY -0 237 Dl -118 0 Dl -0 -237 Dl --118 0 Dl -4197 3027 MXY --21 -13 Dl -8 13 Dl --8 13 Dl -21 -13 Dl --119 0 Dl -4197 3264 MXY --21 -13 Dl -8 13 Dl --8 13 Dl -21 -13 Dl --119 0 Dl -3501 MY -59 0 Dl -0 89 Dl -4078 3738 MXY -59 0 Dl -0 -88 Dl -4197 3590 MXY --21 -13 Dl -8 13 Dl --8 13 Dl -21 -13 Dl --60 0 Dl -4197 3650 MXY --21 -13 Dl -8 13 Dl --8 13 Dl -21 -13 Dl --60 0 Dl -3991 3050(00)N -3991 3287(01)N -3991 3524(10)N -3991 3761(11)N -4269 3050(L00)N -4269 3287(L01)N -4283 3643(L1)N -3485 3501 MXY --20 -13 Dl -7 13 Dl --7 13 Dl -20 -13 Dl --155 0 Dl -3485 3027 MXY --20 -13 Dl -7 13 Dl --7 13 Dl -20 -13 Dl --163 0 Dl -2967 3687 MXY --5 -24 Dl --4 14 Dl --15 4 Dl -24 6 Dl --141 -141 Dl -3 Dt --1 Ds -8 s -2706 4033(Figure)N -2903(2:)X -1 f -2972(A)X -3034(radix)X -3181(search)X -3359(trie)X -3460(and)X -3568(a)X -3612(directory)X -3858(representing)X -4189(the)X -4283(trie.)X -10 s -10 f -2706 4209 -0.0930(hhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhh)AN -1 f -2878 4411(In)N -2968(this)X -3106(algorithm,)X -3460(a)X -3519(directory)X -3832(consists)X -4108(of)X -4198(a)X -4256(search)X -2706 4499(trie)N -2847(of)X -2947(depth)X -2 f -3158(n)X -1 f -3211(,)X -3264(containing)X -3635(2)X -2 f -7 s -4467(n)Y -10 s -1 f -3749 4499(bucket)N -3996(addresses)X -4337(\(i.e.)X -2706 4587(each)N -2897(element)X -3194(of)X -3304(the)X -3445(trie)X -3594(is)X -3689(a)X -3767(bucket)X -4023(address\).)X -4373(To)X -2706 4675(access)N -2935(the)X -3056(hash)X -3226(table,)X -3425(a)X -3483(32-bit)X -3696(hash)X -3865(value)X -4061(is)X -4136(calculated)X -2706 4763(and)N -2 f -2861(n)X -1 f -2953(bits)X -3107(of)X -3213(the)X -3350(value)X -3563(are)X -3701(used)X -3886(to)X -3986(index)X -4202(into)X -4364(the)X -2706 4851(directory)N -3018(to)X -3102(obtain)X -3324(a)X -3382(bucket)X -3618(address.)X -3921(It)X -3992(is)X -4067(important)X -4400(to)X -2706 4939(note)N -2866(that)X -3008(multiple)X -3296(entries)X -3532(of)X -3620(this)X -3756(directory)X -4067(may)X -4226(contain)X -2706 5027(the)N -2833(same)X -3026(bucket)X -3268(address)X -3537(as)X -3632(a)X -3696(result)X -3902(of)X -3997(directory)X -4315(dou-)X -2706 5115(bling)N -2903(during)X -3145(bucket)X -3392(splitting.)X -3706(Figure)X -3948(2)X -4021(illustrates)X -4364(the)X -2706 5203(relationship)N -3126(between)X -3436(a)X -3513(typical)X -3772(\(skewed\))X -4108(search)X -4355(trie)X -2706 5291(and)N -2850(its)X -2953(directory)X -3271(representation.)X -3774(The)X -3927(formation)X -4270(of)X -4364(the)X -2706 5379(directory)N -3016(shown)X -3245(in)X -3327(the)X -3445(\256gure)X -3652(is)X -3725(as)X -3812(follows.)X -16 s -2706 5593 MXY -864 0 Dl -2 f -8 s -2746 5648(4)N -1 f -9 s -2796 5673(It)N -2858(does)X -3008(not)X -3118(contain)X -3348(holes.)X -3 f -10 s -720 5960(USENIX)N -9 f -1042(-)X -3 f -1106(Winter)X -1371('91)X -9 f -1498(-)X -3 f -1562(Dallas,)X -1815(TX)X -4424(3)X - -4 p -%%Page: 4 4 -0(Courier)xf 0 f -10 s 10 xH 0 xS 0 f -3 f -432 258(A)N -510(New)X -682(Hashing)X -985(Package)X -1290(for)X -1413(UNIX)X -3663(Seltzer)X -3920(&)X -4007(Yigit)X -1 f -604 538(Initially,)N -937(there)X -1158(is)X -1271(one)X -1446(slot)X -1620(in)X -1741(the)X -1898(directory)X -432 626(addressing)N -802(a)X -865(single)X -1083(bucket.)X -1364(The)X -1515(depth)X -1719(of)X -1812(the)X -1936(trie)X -2069(is)X -2148(0)X -432 714(and)N -577(0)X -646(bits)X -790(of)X -886(each)X -1063(hash)X -1239(value)X -1442(are)X -1570(examined)X -1910(to)X -2000(deter-)X -432 802(mine)N -624(in)X -718(which)X -946(bucket)X -1192(to)X -1286(place)X -1488(a)X -1556(key;)X -1726(all)X -1837(keys)X -2015(go)X -2126(in)X -432 890(bucket)N -682(0.)X -797(When)X -1024(this)X -1174(bucket)X -1423(is)X -1511(full,)X -1677(its)X -1787(contents)X -2089(are)X -432 978(divided)N -698(between)X -992(L0)X -1107(and)X -1249(L1)X -1363(as)X -1455(was)X -1605(done)X -1786(in)X -1873(the)X -1996(previ-)X -432 1066(ously)N -664(discussed)X -1030(algorithms.)X -1471(After)X -1700(this)X -1874(split,)X -2090(the)X -432 1154(address)N -710(of)X -814(the)X -948(second)X -1207(bucket)X -1457(must)X -1648(be)X -1760(stored)X -1992(in)X -2090(the)X -432 1242(directory.)N -796(To)X -939(accommodate)X -1438(the)X -1589(new)X -1776(address,)X -2090(the)X -432 1330(directory)N -752(is)X -835(split)X -2 f -8 s -972 1305(5)N -1 f -10 s -1330(,)Y -1054(by)X -1163(doubling)X -1476(it,)X -1569(thus)X -1731(increasing)X -2090(the)X -432 1418(depth)N -630(of)X -717(the)X -835(directory)X -1145(by)X -1245(one.)X -604 1532(After)N -813(this)X -967(split,)X -1163(a)X -1237(single)X -1466(bit)X -1588(of)X -1693(the)X -1829(hash)X -2014(value)X -432 1620(needs)N -663(to)X -773(be)X -896(examined)X -1255(to)X -1364(decide)X -1621(whether)X -1927(the)X -2072(key)X -432 1708(belongs)N -711(to)X -803(L0)X -922(or)X -1019(L1.)X -1158(Once)X -1358(one)X -1504(of)X -1601(these)X -1795(buckets)X -2069(\256lls)X -432 1796(\(L0)N -578(for)X -702(example\),)X -1051(it)X -1125(is)X -1208(split)X -1375(as)X -1472(before,)X -1728(and)X -1873(the)X -2000(direc-)X -432 1884(tory)N -585(is)X -662(split)X -823(again)X -1021(to)X -1107(make)X -1305(room)X -1498(for)X -1615(the)X -1736(address)X -2000(of)X -2090(the)X -432 1972(third)N -618(bucket.)X -927(This)X -1104(splitting)X -1400(causes)X -1645(the)X -1778(addresses)X -2121(of)X -432 2060(the)N -567(non-splitting)X -1012(bucket)X -1263(\(L1\))X -1443(to)X -1541(be)X -1653(duplicated.)X -2063(The)X -432 2148(directory)N -766(now)X -948(has)X -1099(four)X -1277(entries,)X -1555(a)X -1635(depth)X -1857(of)X -1968(2,)X -2072(and)X -432 2236(indexes)N -700(the)X -821(buckets)X -1089(L00,)X -1261(L01)X -1413(and)X -1552(L1,)X -1684(as)X -1774(shown)X -2006(in)X -2090(the)X -432 2324(Figure)N -661(2.)X -604 2438(The)N -756(crucial)X -1002(part)X -1154(of)X -1247(the)X -1371(algorithm)X -1708(is)X -1787(the)X -1911(observa-)X -432 2526(tion)N -580(that)X -724(L1)X -837(is)X -914(addressed)X -1255(twice)X -1453(in)X -1539(the)X -1661(directory.)X -1995(If)X -2073(this)X -432 2614(bucket)N -679(were)X -869(to)X -964(split)X -1134(now,)X -1324(the)X -1454(directory)X -1776(already)X -2045(con-)X -432 2702(tains)N -611(room)X -808(to)X -898(hold)X -1067(the)X -1192(address)X -1460(of)X -1554(the)X -1679(new)X -1840(bucket.)X -2121(In)X -432 2790(general,)N -711(the)X -831(relationship)X -1231(between)X -1521(the)X -1641(directory)X -1953(and)X -2090(the)X -432 2878(number)N -704(of)X -798(bucket)X -1039(addresses)X -1374(contained)X -1713(therein)X -1962(is)X -2041(used)X -432 2966(to)N -517(decide)X -750(when)X -947(to)X -1031(split)X -1190(the)X -1310(directory.)X -1662(Each)X -1845(bucket)X -2081(has)X -432 3054(a)N -505(depth,)X -740(\()X -2 f -767(n)X -7 s -3070(b)Y -10 s -1 f -848 3054(\),)N -932(associated)X -1299(with)X -1478(it)X -1558(and)X -1710(appears)X -1992(in)X -2090(the)X -432 3142(directory)N -744(exactly)X -998(2)X -2 f -7 s -3106(n)Y -9 f -1075(-)X -2 f -1106(n)X -4 s -3110(b)Y -7 s -1 f -10 s -1181 3142(times.)N -1396(When)X -1610(a)X -1668(bucket)X -1904(splits,)X -2113(its)X -432 3230(depth)N -638(increases)X -961(by)X -1069(one.)X -1253(The)X -1406(directory)X -1724(must)X -1907(split)X -2072(any)X -432 3318(time)N -602(a)X -665(bucket's)X -964(depth)X -1169(exceeds)X -1451(the)X -1576(depth)X -1781(of)X -1875(the)X -2000(direc-)X -432 3406(tory.)N -630(The)X -784(following)X -1123(code)X -1303(fragment)X -1621(helps)X -1818(to)X -1908(illustrate)X -432 3494(the)N -554(extendible)X -912(hashing)X -1185(algorithm)X -1520([FAG79])X -1838(for)X -1955(access-)X -432 3582(ing)N -554(individual)X -898(buckets)X -1163(and)X -1299(maintaining)X -1701(the)X -1819(directory.)X -0 f -8 s -432 3881(hash)N -622(=)X -698 -0.4038(calchash\(key\);)AX -432 3969(mask)N -622(=)X -698 -0.4018(maskvec[depth];)AX -432 4145(bucket)N -698(=)X -774 -0.4038(directory[hash)AX -1344(&)X -1420(mask];)X -432 4321(/*)N -546(Key)X -698 -0.4219(Insertion)AX -1078(*/)X -432 4409(if)N -546 -0.4038(\(store\(bucket,)AX -1116(key,)X -1306(data\))X -1534(==)X -1648(FAIL\))X -1876({)X -720 4497(newbl)N -948(=)X -1024 -0.4167(getpage\(\);)AX -720 4585 -0.4000(bucket->depth++;)AN -720 4673 -0.4091(newbl->depth)AN -1214(=)X -1290 -0.4038(bucket->depth;)AX -720 4761(if)N -834 -0.4038(\(bucket->depth)AX -1404(>)X -1480(depth\))X -1746({)X -1008 4849(/*)N -1122(double)X -1388 -0.4219(directory)AX -1768(*/)X -1008 4937(depth++;)N -1 f -16 s -432 5033 MXY -864 0 Dl -2 f -8 s -472 5088(5)N -1 f -9 s -534 5113(This)N -692(decision)X -962(to)X -1048(split)X -1202(the)X -1319(directory)X -1608(is)X -1685(based)X -1878(on)X -1979(a)X -2040(com-)X -432 5193(parison)N -666(of)X -748(the)X -858(depth)X -1040(of)X -1121(the)X -1230(page)X -1387(being)X -1568(split)X -1713(and)X -1838(the)X -1947(depth)X -2128(of)X -432 5273(the)N -543(trie.)X -698(In)X -781(Figure)X -992(2,)X -1069(the)X -1180(depths)X -1390(of)X -1472(both)X -1622(L00)X -1760(and)X -1886(L01)X -2024(are)X -2134(2,)X -432 5353(whereas)N -689(the)X -798(depth)X -979(of)X -1060(L1)X -1161(is)X -1230(1.)X -1323(Therefore,)X -1646(if)X -1710(L1)X -1810(were)X -1970(to)X -2046(split,)X -432 5433(the)N -543(directory)X -826(would)X -1029(not)X -1144(need)X -1303(to)X -1382(split.)X -1565(In)X -1648(reality,)X -1872(a)X -1926(bucket)X -2140(is)X -432 5513(allocated)N -727(for)X -846(the)X -969(directory)X -1264(at)X -1351(the)X -1474(time)X -1637(of)X -1732(\256le)X -1858(creation)X -2124(so)X -432 5593(although)N -707(the)X -818(directory)X -1100(splits)X -1274(logically,)X -1566(physical)X -1828(splits)X -2002(do)X -2096(not)X -432 5673(occur)N -610(until)X -760(the)X -866(\256le)X -976(becomes)X -1246(quite)X -1408(large.)X -0 f -8 s -2994 538 -0.4219(directory)AN -3374(=)X -3450 -0.3971(double\(directory\);)AX -2706 626(})N -2706 714 -0.3958(splitbucket\(bucket,)AN -3466(newbl\))X -2706 802(...)N -2418 890(})N -2 f -10 s -3169 1255(hsearch)N -1 f -2590 1387(Since)N -2 f -2807(hsearch)X -1 f -3100(does)X -3286(not)X -3427(have)X -3617(to)X -3717(translate)X -4027(hash)X -2418 1475(values)N -2659(into)X -2819(disk)X -2988(addresses,)X -3352(it)X -3432(can)X -3579(use)X -3721(much)X -3934(simpler)X -2418 1563(algorithms)N -2808(than)X -2994(those)X -3211(de\256ned)X -3495(above.)X -3775(System)X -4058(V's)X -2 f -2418 1651(hsearch)N -1 f -2708(constructs)X -3069(a)X -3141(\256xed-size)X -3489(hash)X -3671(table)X -3862(\(speci\256ed)X -2418 1739(by)N -2519(the)X -2637(user)X -2791(at)X -2869(table)X -3045(creation\).)X -3391(By)X -3504(default,)X -3767(a)X -3823(multiplica-)X -2418 1827(tive)N -2570(hash)X -2748(function)X -3046(based)X -3260(on)X -3371(that)X -3522(described)X -3861(in)X -3954(Knuth,)X -2418 1915(Volume)N -2710(3,)X -2804(section)X -3065(6.4)X -3199([KNU68])X -3541(is)X -3628(used)X -3809(to)X -3905(obtain)X -4138(a)X -2418 2003(primary)N -2694(bucket)X -2930(address.)X -3233(If)X -3309(this)X -3446(bucket)X -3681(is)X -3755(full,)X -3907(a)X -3964(secon-)X -2418 2091(dary)N -2593(multiplicative)X -3069(hash)X -3248(value)X -3454(is)X -3538(computed)X -3885(to)X -3978(de\256ne)X -2418 2179(the)N -2542(probe)X -2751(interval.)X -3062(The)X -3213(probe)X -3422(interval)X -3693(is)X -3772(added)X -3989(to)X -4076(the)X -2418 2267(original)N -2712(bucket)X -2971(address)X -3257(\(modulo)X -3573(the)X -3716(table)X -3916(size\))X -4112(to)X -2418 2355(obtain)N -2658(a)X -2734(new)X -2908(bucket)X -3162(address.)X -3483(This)X -3665(process)X -3946(repeats)X -2418 2443(until)N -2588(an)X -2688(empty)X -2911(bucket)X -3148(is)X -3224(found.)X -3474(If)X -3551(no)X -3654(bucket)X -3891(is)X -3967(found,)X -2418 2531(an)N -2514(insertion)X -2814(fails)X -2972(with)X -3134(a)X -3190(``table)X -3420(full'')X -3605(condition.)X -2590 2645(The)N -2768(basic)X -2986(algorithm)X -3350(may)X -3541(be)X -3670(modi\256ed)X -4006(by)X -4138(a)X -2418 2733(number)N -2705(of)X -2813(compile)X -3112(time)X -3295(options)X -3571(available)X -3902(to)X -4005(those)X -2418 2821(users)N -2604(with)X -2767(AT&T)X -3006(source)X -3237(code.)X -3450(First,)X -3637(the)X -3756(package)X -4040(pro-)X -2418 2909(vides)N -2638(two)X -2809(options)X -3094(for)X -3238(hash)X -3435(functions.)X -3803(Users)X -4036(may)X -2418 2997(specify)N -2690(their)X -2877(own)X -3055(hash)X -3242(function)X -3549(by)X -3669(compiling)X -4032(with)X -2418 3085(``USCR'')N -2757(de\256ned)X -3016(and)X -3155(declaring)X -3477(and)X -3616(de\256ning)X -3901(the)X -4022(vari-)X -2418 3173(able)N -2 f -2578(hcompar)X -1 f -2863(,)X -2909(a)X -2971(function)X -3263(taking)X -3488(two)X -3633(string)X -3840(arguments)X -2418 3261(and)N -2560(returning)X -2880(an)X -2982(integer.)X -3271(Users)X -3480(may)X -3643(also)X -3797(request)X -4054(that)X -2418 3349(hash)N -2587(values)X -2814(be)X -2912(computed)X -3250(simply)X -3489(by)X -3590(taking)X -3811(the)X -3930(modulo)X -2418 3437(of)N -2521(key)X -2673(\(using)X -2909(division)X -3201(rather)X -3424(than)X -3597(multiplication)X -4080(for)X -2418 3525(hash)N -2589(value)X -2787(calculation\).)X -3230(If)X -3308(this)X -3447(technique)X -3783(is)X -3859(used,)X -4049(col-)X -2418 3613(lisions)N -2651(are)X -2775(resolved)X -3072(by)X -3176(scanning)X -3485(sequentially)X -3896(from)X -4076(the)X -2418 3701(selected)N -2702(bucket)X -2941(\(linear)X -3176(probing\).)X -3517(This)X -3684(option)X -3913(is)X -3991(avail-)X -2418 3789(able)N -2572(by)X -2672(de\256ning)X -2954(the)X -3072(variable)X -3351(``DIV'')X -3622(at)X -3700(compile)X -3978(time.)X -2590 3903(A)N -2720(second)X -3015(option,)X -3311(based)X -3565(on)X -3716(an)X -3863(algorithm)X -2418 3991(discovered)N -2787(by)X -2888(Richard)X -3163(P.)X -3248(Brent,)X -3466(rearranges)X -3822(the)X -3940(table)X -4116(at)X -2418 4079(the)N -2549(time)X -2724(of)X -2824(insertion)X -3137(in)X -3232(order)X -3434(to)X -3528(speed)X -3743(up)X -3855(retrievals.)X -2418 4167(The)N -2571(basic)X -2764(idea)X -2926(is)X -3007(to)X -3097(shorten)X -3361(long)X -3531(probe)X -3741(sequences)X -4094(by)X -2418 4255(lengthening)N -2833(short)X -3030(probe)X -3249(sequences.)X -3651(Once)X -3857(the)X -3991(probe)X -2418 4343(chain)N -2613(has)X -2741(exceeded)X -3062(some)X -3252(threshold)X -3571(\(Brent)X -3796(suggests)X -4087(2\),)X -2418 4431(we)N -2541(attempt)X -2809(to)X -2899(shuf\257e)X -3145(any)X -3289(colliding)X -3601(keys)X -3776(\(keys)X -3978(which)X -2418 4519(appeared)N -2734(in)X -2821(the)X -2944(probe)X -3152(sequence)X -3471(of)X -3562(the)X -3684(new)X -3842(key\).)X -4049(The)X -2418 4607(details)N -2652(of)X -2744(this)X -2884(key)X -3025(shuf\257ing)X -3333(can)X -3469(be)X -3569(found)X -3780(in)X -3866([KNU68])X -2418 4695(and)N -2576([BRE73].)X -2946(This)X -3129(algorithm)X -3481(may)X -3660(be)X -3777(obtained)X -4094(by)X -2418 4783(de\256ning)N -2700(the)X -2818(variable)X -3097(``BRENT'')X -3487(at)X -3565(compile)X -3843(time.)X -2590 4897(A)N -2698(third)X -2899(set)X -3038(of)X -3154(options,)X -3458(obtained)X -3783(by)X -3912(de\256ning)X -2418 4985(``CHAINED'',)N -2943(use)X -3086(linked)X -3321(lists)X -3484(to)X -3581(resolve)X -3848(collisions.)X -2418 5073(Either)N -2647(of)X -2747(the)X -2878(primary)X -3164(hash)X -3343(function)X -3642(described)X -3982(above)X -2418 5161(may)N -2584(be)X -2688(used,)X -2882(but)X -3011(all)X -3118(collisions)X -3451(are)X -3577(resolved)X -3876(by)X -3983(build-)X -2418 5249(ing)N -2554(a)X -2623(linked)X -2856(list)X -2986(of)X -3086(entries)X -3333(from)X -3522(the)X -3653(primary)X -3940(bucket.)X -2418 5337(By)N -2542(default,)X -2816(new)X -2981(entries)X -3226(will)X -3381(be)X -3488(added)X -3711(to)X -3804(a)X -3871(bucket)X -4116(at)X -2418 5425(the)N -2541(beginning)X -2886(of)X -2978(the)X -3101(bucket)X -3339(chain.)X -3577(However,)X -3916(compile)X -2418 5513(options)N -2706(``SORTUP'')X -3173(or)X -3293(``SORTDOWN'')X -3908(may)X -4098(be)X -2418 5601(speci\256ed)N -2723(to)X -2805(order)X -2995(the)X -3113(hash)X -3280(chains)X -3505(within)X -3729(each)X -3897(bucket.)X -3 f -432 5960(4)N -2970(USENIX)X -9 f -3292(-)X -3 f -3356(Winter)X -3621('91)X -9 f -3748(-)X -3 f -3812(Dallas,)X -4065(TX)X - -5 p -%%Page: 5 5 -0(Courier)xf 0 f -10 s 10 xH 0 xS 0 f -3 f -720 258(Seltzer)N -977(&)X -1064(Yigit)X -3278(A)X -3356(New)X -3528(Hashing)X -3831(Package)X -4136(for)X -4259(UNIX)X -2 f -1444 538(dynahash)N -1 f -892 670(The)N -2 f -1054(dynahash)X -1 f -1398(library,)X -1669(written)X -1932(by)X -2048(Esmond)X -2346(Pitt,)X -720 758(implements)N -1183(Larson's)X -1554(linear)X -1827(hashing)X -2165(algorithm)X -720 846([LAR88])N -1097(with)X -1302(an)X -2 f -1440(hsearch)X -1 f -1756(compatible)X -2174(interface.)X -720 934(Intuitively,)N -1099(a)X -1161(hash)X -1334(table)X -1516(begins)X -1751(as)X -1844(a)X -1905(single)X -2121(bucket)X -2360(and)X -720 1022(grows)N -941(in)X -1028(generations,)X -1443(where)X -1665(a)X -1725(generation)X -2088(corresponds)X -720 1110(to)N -815(a)X -884(doubling)X -1201(in)X -1296(the)X -1427(size)X -1585(of)X -1685(the)X -1815(hash)X -1994(table.)X -2222(The)X -2379(0)X -2 f -7 s -1078(th)Y -10 s -1 f -720 1198(generation)N -1085(occurs)X -1321(as)X -1414(the)X -1538(table)X -1719(grows)X -1940(from)X -2121(one)X -2262(bucket)X -720 1286(to)N -814(two.)X -1006(In)X -1105(the)X -1235(next)X -1405(generation)X -1776(the)X -1906(table)X -2093(grows)X -2320(from)X -720 1374(two)N -862(to)X -946(four.)X -1122(During)X -1371(each)X -1541(generation,)X -1921(every)X -2121(bucket)X -2356(that)X -720 1462(existed)N -967(at)X -1045(the)X -1163(beginning)X -1503(of)X -1590(the)X -1708(generation)X -2067(is)X -2140(split.)X -892 1576(The)N -1041(table)X -1221(starts)X -1414(as)X -1505(a)X -1565(single)X -1780(bucket)X -2018(\(numbered)X -2389(0\),)X -720 1664(the)N -839(current)X -1088(split)X -1245(bucket)X -1479(is)X -1552(set)X -1661(to)X -1743(bucket)X -1977(0,)X -2057(and)X -2193(the)X -2311(max-)X -720 1752(imum)N -933(split)X -1097(point)X -1288(is)X -1368(set)X -1483(to)X -1571(twice)X -1771(the)X -1895(current)X -2149(split)X -2312(point)X -720 1840(\(0\).)N -863(When)X -1084(it)X -1157(is)X -1239(time)X -1410(for)X -1532(a)X -1596(bucket)X -1838(to)X -1928(split,)X -2113(the)X -2239(keys)X -2414(in)X -720 1928(the)N -872(current)X -1154(split)X -1345(bucket)X -1612(are)X -1764(divided)X -2057(between)X -2378(the)X -720 2016(current)N -981(split)X -1151(bucket)X -1397(and)X -1545(a)X -1613(new)X -1779(bucket)X -2025(whose)X -2262(bucket)X -720 2104(number)N -1000(is)X -1088(equal)X -1297(to)X -1394(1)X -1469(+)X -1549(current)X -1812(split)X -1984(bucket)X -2232(+)X -2311(max-)X -720 2192(imum)N -927(split)X -1085(point.)X -1310(We)X -1442(can)X -1574(determine)X -1915(which)X -2131(keys)X -2298(move)X -720 2280(to)N -807(the)X -929(new)X -1087(bucket)X -1325(by)X -1429(examining)X -1791(the)X -2 f -1913(n)X -7 s -1962 2248(th)N -10 s -1 f -2043 2280(bit)N -2151(of)X -2242(a)X -2302(key's)X -720 2368(hash)N -899(value)X -1105(where)X -1334(n)X -1406(is)X -1491(the)X -1620(generation)X -1990(number.)X -2306(After)X -720 2456(the)N -846(bucket)X -1088(at)X -1174(the)X -1300(maximum)X -1651(split)X -1815(point)X -2006(has)X -2140(been)X -2319(split,)X -720 2544(the)N -839(generation)X -1198(number)X -1463(is)X -1536(incremented,)X -1973(the)X -2091(current)X -2339(split)X -720 2632(point)N -908(is)X -985(set)X -1098(back)X -1274(to)X -1360(zero,)X -1543(and)X -1683(the)X -1805(maximum)X -2152(split)X -2312(point)X -720 2720(is)N -815(set)X -946(to)X -1050(the)X -1190(number)X -1477(of)X -1586(the)X -1725(last)X -1877(bucket)X -2132(in)X -2235(the)X -2374(\256le)X -720 2808(\(which)N -971(is)X -1052(equal)X -1253(to)X -1342(twice)X -1543(the)X -1668(old)X -1797(maximum)X -2148(split)X -2312(point)X -720 2896(plus)N -873(1\).)X -892 3010(To)N -1031(facilitate)X -1361(locating)X -1668(keys,)X -1884(we)X -2027(maintain)X -2356(two)X -720 3098(masks.)N -989(The)X -1143(low)X -1291(mask)X -1488(is)X -1569(equal)X -1771(to)X -1861(the)X -1987(maximum)X -2339(split)X -720 3186(bucket)N -967(and)X -1116(the)X -1247(high)X -1422(mask)X -1624(is)X -1710(equal)X -1917(to)X -2011(the)X -2141(next)X -2311(max-)X -720 3274(imum)N -931(split)X -1093(bucket.)X -1372(To)X -1486(locate)X -1703(a)X -1764(speci\256c)X -2033(key,)X -2193(we)X -2311(com-)X -720 3362(pute)N -881(a)X -940(32-bit)X -1154(hash)X -1324(value)X -1520(using)X -1715(a)X -1773(bit-randomizing)X -2311(algo-)X -720 3450(rithm)N -932(such)X -1118(as)X -1224(the)X -1361(one)X -1516(described)X -1862(in)X -1962([LAR88].)X -2334(This)X -720 3538(hash)N -893(value)X -1093(is)X -1172(then)X -1336(masked)X -1607(with)X -1775(the)X -1898(high)X -2065(mask.)X -2299(If)X -2378(the)X -720 3626(resulting)N -1026(number)X -1297(is)X -1376(greater)X -1626(than)X -1790(the)X -1913(maximum)X -2262(bucket)X -720 3714(in)N -823(the)X -962(table)X -1159(\(current)X -1455(split)X -1633(bucket)X -1888(+)X -1974(maximum)X -2339(split)X -720 3802(point\),)N -962(the)X -1091(hash)X -1269(value)X -1474(is)X -1558(masked)X -1834(with)X -2007(the)X -2136(low)X -2287(mask.)X -720 3890(In)N -825(either)X -1046(case,)X -1242(the)X -1377(result)X -1592(of)X -1696(the)X -1831(mask)X -2037(is)X -2127(the)X -2262(bucket)X -720 3978(number)N -989(for)X -1107(the)X -1229(given)X -1431(key.)X -1611(The)X -1759(algorithm)X -2093(below)X -2312(illus-)X -720 4066(trates)N -914(this)X -1049(process.)X -0 f -8 s -720 4365(h)N -796(=)X -872 -0.4038(calchash\(key\);)AX -720 4453(bucket)N -986(=)X -1062(h)X -1138(&)X -1214 -0.4167(high_mask;)AX -720 4541(if)N -834(\()X -910(bucket)X -1176(>)X -1252 -0.4167(max_bucket)AX -1670(\))X -1008 4629(bucket)N -1274(=)X -1350(h)X -1426(&)X -1502 -0.4219(low_mask;)AX -720 4717 -0.4018(return\(bucket\);)AN -1 f -10 s -892 5042(In)N -1013(order)X -1237(to)X -1353(decide)X -1617(when)X -1845(to)X -1961(split)X -2152(a)X -2242(bucket,)X -2 f -720 5130(dynahash)N -1 f -1050(uses)X -2 f -1210(controlled)X -1561(splitting)X -1 f -1822(.)X -1884(A)X -1964(hash)X -2133(table)X -2311(has)X -2440(a)X -720 5218(\256ll)N -837(factor)X -1054(which)X -1279(is)X -1361(expressed)X -1707(in)X -1798(terms)X -2004(of)X -2099(the)X -2225(average)X -720 5306(number)N -990(of)X -1082(keys)X -1253(in)X -1339(each)X -1511(bucket.)X -1789(Each)X -1974(time)X -2140(the)X -2262(table's)X -720 5394(total)N -885(number)X -1153(of)X -1243(keys)X -1413(divided)X -1676(by)X -1778(its)X -1875(number)X -2142(of)X -2231(buckets)X -720 5482(exceeds)N -995(this)X -1130(\256ll)X -1238(factor,)X -1466(a)X -1522(bucket)X -1756(is)X -1829(split.)X -2878 538(Since)N -3079(the)X -2 f -3200(hsearch)X -1 f -3477(create)X -3693(interface)X -3998(\()X -2 f -4025(hcreate)X -1 f -4266(\))X -4315(calls)X -2706 626(for)N -2842(an)X -2960(estimate)X -3269(of)X -3378(the)X -3518(\256nal)X -3702(size)X -3869(of)X -3978(the)X -4118(hash)X -4306(table)X -2706 714(\()N -2 f -2733(nelem)X -1 f -2925(\),)X -2 f -3007(dynahash)X -1 f -3349(uses)X -3522(this)X -3672(information)X -4085(to)X -4182(initialize)X -2706 802(the)N -2848(table.)X -3088(The)X -3257(initial)X -3486(number)X -3774(of)X -3884(buckets)X -4172(is)X -4268(set)X -4400(to)X -2 f -2706 890(nelem)N -1 f -2926(rounded)X -3217(to)X -3306(the)X -3431(next)X -3596(higher)X -3828(power)X -4056(of)X -4150(two.)X -4337(The)X -2706 978(current)N -2958(split)X -3118(point)X -3305(is)X -3381(set)X -3493(to)X -3578(0)X -3641(and)X -3780(the)X -3901(maximum)X -4248(bucket)X -2706 1066(and)N -2842(maximum)X -3186(split)X -3343(point)X -3527(are)X -3646(set)X -3755(to)X -3837(this)X -3972(rounded)X -4255(value.)X -3 f -3148 1220(The)N -3301(New)X -3473(Implementation)X -1 f -2878 1352(Our)N -3042(implementation)X -3583(is)X -3675(also)X -3842(based)X -4063(on)X -4181(Larson's)X -2706 1440(linear)N -2939(hashing)X -3238([LAR88])X -3582(algorithm)X -3943(as)X -4060(well)X -4248(as)X -4364(the)X -2 f -2706 1528(dynahash)N -1 f -3047(implementation.)X -3623(The)X -2 f -3782(dbm)X -1 f -3954(family)X -4197(of)X -4297(algo-)X -2706 1616(rithms)N -2942(decide)X -3184(dynamically)X -3612(which)X -3840(bucket)X -4085(to)X -4178(split)X -4346(and)X -2706 1704(when)N -2914(to)X -3010(split)X -3180(it)X -3257(\(when)X -3491(it)X -3568(over\257ows\))X -3944(while)X -2 f -4155(dynahash)X -1 f -2706 1792(splits)N -2933(in)X -3054(a)X -3149(prede\256ned)X -3547(order)X -3776(\(linearly\))X -4134(and)X -4309(at)X -4426(a)X -2706 1880(prede\256ned)N -3116(time)X -3328(\(when)X -3599(the)X -3767(table)X -3993(\256ll)X -4151(factor)X -4409(is)X -2706 1968(exceeded\).)N -3121(We)X -3280(use)X -3434(a)X -3517(hybrid)X -3773(of)X -3887(these)X -4099(techniques.)X -2706 2056(Splits)N -2913(occur)X -3118(in)X -3206(the)X -3330(prede\256ned)X -3695(order)X -3891(of)X -3984(linear)X -4193(hashing,)X -2706 2144(but)N -2845(the)X -2980(time)X -3159(at)X -3253(which)X -3485(pages)X -3704(are)X -3839(split)X -4012(is)X -4101(determined)X -2706 2232(both)N -2869(by)X -2970(page)X -3143(over\257ows)X -3480(\()X -2 f -3507(uncontrolled)X -3937(splitting)X -1 f -4198(\))X -4246(and)X -4382(by)X -2706 2320(exceeding)N -3052(the)X -3170(\256ll)X -3278(factor)X -3486(\()X -2 f -3513(controlled)X -3862(splitting)X -1 f -4123(\))X -2878 2434(A)N -2962(hash)X -3135(table)X -3317(is)X -3395(parameterized)X -3876(by)X -3981(both)X -4148(its)X -4248(bucket)X -2706 2522(size)N -2904(\()X -2 f -2931(bsize)X -1 f -(\))S -3191(and)X -3380(\256ll)X -3541(factor)X -3801(\()X -2 f -3828(ffactor)X -1 f -4041(\).)X -4180(Whereas)X -2 f -2706 2610(dynahash's)N -1 f -3095(buckets)X -3364(can)X -3500(be)X -3599(represented)X -3993(as)X -4083(a)X -4142(linked)X -4365(list)X -2706 2698(of)N -2798(elements)X -3108(in)X -3195(memory,)X -3507(our)X -3639(package)X -3928(needs)X -4136(to)X -4222(support)X -2706 2786(disk)N -2874(access,)X -3135(and)X -3286(must)X -3476(represent)X -3806(buckets)X -4086(in)X -4183(terms)X -4395(of)X -2706 2874(pages.)N -2955(The)X -2 f -3106(bsize)X -1 f -3291(is)X -3369(the)X -3492(size)X -3642(\(in)X -3756(bytes\))X -3977(of)X -4069(these)X -4259(pages.)X -2706 2962(As)N -2833(in)X -2933(linear)X -3154(hashing,)X -3461(the)X -3597(number)X -3879(of)X -3983(buckets)X -4265(in)X -4364(the)X -2706 3050(table)N -2906(is)X -3003(equal)X -3221(to)X -3327(the)X -3469(number)X -3758(of)X -3869(keys)X -4060(in)X -4165(the)X -4306(table)X -2706 3138(divided)N -2988(by)X -2 f -3110(ffactor)X -1 f -3323(.)X -2 f -8 s -3113(6)Y -1 f -10 s -3417 3138(The)N -3584(controlled)X -3950(splitting)X -4252(occurs)X -2706 3226(each)N -2878(time)X -3044(the)X -3166(number)X -3435(of)X -3526(keys)X -3697(in)X -3783(the)X -3905(table)X -4085(exceeds)X -4364(the)X -2706 3314(\256ll)N -2814(factor)X -3022(multiplied)X -3370(by)X -3470(the)X -3588(number)X -3853(of)X -3940(buckets.)X -2878 3428(Inserting)N -3187(keys)X -3358(and)X -3498(splitting)X -3783(buckets)X -4051(is)X -4127(performed)X -2706 3516(precisely)N -3018(as)X -3107(described)X -3437(previously)X -3796(for)X -2 f -3911(dynahash)X -1 f -4218(.)X -4279(How-)X -2706 3604(ever,)N -2897(since)X -3094(buckets)X -3371(are)X -3502(now)X -3671(comprised)X -4036(of)X -4134(pages,)X -4368(we)X -2706 3692(must)N -2883(be)X -2981(prepared)X -3284(to)X -3367(handle)X -3602(cases)X -3793(where)X -4011(the)X -4130(size)X -4276(of)X -4364(the)X -2706 3780(keys)N -2873(and)X -3009(data)X -3163(in)X -3245(a)X -3301(bucket)X -3535(exceed)X -3779(the)X -3897(bucket)X -4131(size.)X -3 f -3318 3934(Over\257ow)N -3654(Pages)X -1 f -2878 4066(There)N -3095(are)X -3223(two)X -3372(cases)X -3571(where)X -3797(a)X -3862(key)X -4007(may)X -4174(not)X -4305(\256t)X -4400(in)X -2706 4154(its)N -2802(designated)X -3166(bucket.)X -3441(In)X -3529(the)X -3647(\256rst)X -3791(case,)X -3970(the)X -4088(total)X -4250(size)X -4395(of)X -2706 4242(the)N -2833(key)X -2978(and)X -3123(data)X -3286(may)X -3453(exceed)X -3706(the)X -3833(bucket)X -4076(size.)X -4269(In)X -4364(the)X -2706 4330(second,)N -3008(addition)X -3328(of)X -3453(a)X -3547(new)X -3739(key)X -3913(could)X -4149(cause)X -4386(an)X -2706 4418(over\257ow,)N -3068(but)X -3227(the)X -3382(bucket)X -3652(in)X -3770(question)X -4097(is)X -4206(not)X -4364(yet)X -2706 4506(scheduled)N -3049(to)X -3133(be)X -3230(split.)X -3428(In)X -3516(existing)X -3790(implementations,)X -4364(the)X -2706 4594(second)N -2953(case)X -3115(never)X -3317(arises)X -3523(\(since)X -3738(buckets)X -4006(are)X -4128(split)X -4288(when)X -2706 4682(they)N -2871(over\257ow\))X -3210(and)X -3352(the)X -3476(\256rst)X -3626(case)X -3791(is)X -3870(not)X -3998(handled)X -4278(at)X -4362(all.)X -2706 4770(Although)N -3036(large)X -3225(key/data)X -3525(pair)X -3678(handling)X -3986(is)X -4066(dif\256cult)X -4346(and)X -2706 4858(expensive,)N -3083(it)X -3163(is)X -3252(essential.)X -3604(In)X -3706(a)X -3777(linear)X -3995(hashed)X -4253(imple-)X -2706 4946(mentation,)N -3087(over\257ow)X -3413(pages)X -3636(are)X -3775(required)X -4083(for)X -4217(buckets)X -2706 5034(which)N -2935(over\257ow)X -3253(before)X -3492(they)X -3662(are)X -3793(split,)X -3982(so)X -4085(we)X -4211(can)X -4355(use)X -2706 5122(the)N -2833(same)X -3027(mechanism)X -3421(for)X -3544(large)X -3734(key/data)X -4035(pairs)X -4220(that)X -4368(we)X -2706 5210(use)N -2837(for)X -2955(over\257ow)X -3264(pages.)X -3511(Logically,)X -3862(we)X -3980(chain)X -4177(over\257ow)X -16 s -2706 5353 MXY -864 0 Dl -2 f -8 s -2746 5408(6)N -1 f -9 s -2801 5433(This)N -2952(is)X -3023(not)X -3138(strictly)X -3361(true.)X -3532(The)X -3667(\256le)X -3782(does)X -3937(not)X -4052(contract)X -4306(when)X -2706 5513(keys)N -2861(are)X -2972(deleted,)X -3221(so)X -3308(the)X -3419(number)X -3662(of)X -3744(buckets)X -3986(is)X -4056(actually)X -4306(equal)X -2706 5593(to)N -2782(the)X -2890(maximum)X -3202(number)X -3441(of)X -3520(keys)X -3671(ever)X -3814(present)X -4041(in)X -4116(the)X -4223(table)X -4382(di-)X -2706 5673(vided)N -2884(by)X -2974(the)X -3080(\256ll)X -3178(factor.)X -3 f -10 s -720 5960(USENIX)N -9 f -1042(-)X -3 f -1106(Winter)X -1371('91)X -9 f -1498(-)X -3 f -1562(Dallas,)X -1815(TX)X -4424(5)X - -6 p -%%Page: 6 6 -0(Courier)xf 0 f -10 s 10 xH 0 xS 0 f -3 f -432 258(A)N -510(New)X -682(Hashing)X -985(Package)X -1290(for)X -1413(UNIX)X -3663(Seltzer)X -3920(&)X -4007(Yigit)X -1 f -432 538(pages)N -639(to)X -725(the)X -847(buckets)X -1116(\(also)X -1296(called)X -1512(primary)X -1789(pages\).)X -2062(In)X -2152(a)X -432 626(memory)N -730(based)X -943(representation,)X -1448(over\257ow)X -1763(pages)X -1976(do)X -2086(not)X -432 714(pose)N -628(any)X -792(special)X -1063(problems)X -1409(because)X -1712(we)X -1854(can)X -2014(chain)X -432 802(over\257ow)N -776(pages)X -1017(to)X -1137(primary)X -1449(pages)X -1690(using)X -1921(memory)X -432 890(pointers.)N -776(However,)X -1137(mapping)X -1463(these)X -1674(over\257ow)X -2005(pages)X -432 978(into)N -584(a)X -648(disk)X -809(\256le)X -939(is)X -1019(more)X -1211(of)X -1305(a)X -1368(challenge,)X -1723(since)X -1915(we)X -2036(need)X -432 1066(to)N -547(be)X -675(able)X -861(to)X -975(address)X -1268(both)X -1462(bucket)X -1728(pages,)X -1983(whose)X -432 1154(numbers)N -729(are)X -849(growing)X -1137(linearly,)X -1422(and)X -1558(some)X -1747(indeterminate)X -432 1242(number)N -715(of)X -820(over\257ow)X -1143(pages)X -1364(without)X -1646(reorganizing)X -2090(the)X -432 1330(\256le.)N -604 1444(One)N -789(simple)X -1053(solution)X -1361(would)X -1612(be)X -1739(to)X -1852(allocate)X -2152(a)X -432 1532(separate)N -737(\256le)X -880(for)X -1015(over\257ow)X -1341(pages.)X -1604(The)X -1769(disadvantage)X -432 1620(with)N -605(such)X -783(a)X -850(technique)X -1193(is)X -1276(that)X -1426(it)X -1500(requires)X -1789(an)X -1895(extra)X -2086(\256le)X -432 1708(descriptor,)N -794(an)X -891(extra)X -1073(system)X -1316(call)X -1453(on)X -1554(open)X -1731(and)X -1867(close,)X -2072(and)X -432 1796(logically)N -739(associating)X -1122(two)X -1269(independent)X -1687(\256les.)X -1886(For)X -2023(these)X -432 1884(reasons,)N -728(we)X -857(wanted)X -1123(to)X -1219(map)X -1391(both)X -1567(primary)X -1855(pages)X -2072(and)X -432 1972(over\257ow)N -737(pages)X -940(into)X -1084(the)X -1202(same)X -1387(\256le)X -1509(space.)X -604 2086(The)N -799(buddy-in-waiting)X -1425(algorithm)X -1806(provides)X -2152(a)X -432 2174(mechanism)N -851(to)X -966(support)X -1259(multiple)X -1578(pages)X -1814(per)X -1970(logical)X -432 2262(bucket)N -685(while)X -902(retaining)X -1226(the)X -1362(simple)X -1613(split)X -1788(sequence)X -2121(of)X -432 2350(linear)N -681(hashing.)X -1015(Over\257ow)X -1383(pages)X -1631(are)X -1795(preallocated)X -432 2438(between)N -781(generations)X -1232(of)X -1379(primary)X -1713(pages.)X -1996(These)X -432 2526(over\257ow)N -759(pages)X -984(are)X -1125(used)X -1314(by)X -1436(any)X -1594(bucket)X -1850(containing)X -432 2614(more)N -646(keys)X -842(than)X -1029(\256t)X -1144(on)X -1273(the)X -1420(primary)X -1723(page)X -1924(and)X -2089(are)X -432 2702(reclaimed,)N -808(if)X -896(possible,)X -1217(when)X -1430(the)X -1567(bucket)X -1819(later)X -2000(splits.)X -432 2790(Figure)N -687(3)X -773(depicts)X -1045(the)X -1188(layout)X -1433(of)X -1545(primary)X -1844(pages)X -2072(and)X -432 2878(over\257ow)N -752(pages)X -970(within)X -1209(the)X -1342(same)X -1542(\256le.)X -1699(Over\257ow)X -2036(page)X -432 2966(use)N -586(information)X -1011(is)X -1111(recorded)X -1440(in)X -1548(bitmaps)X -1847(which)X -2089(are)X -432 3054(themselves)N -819(stored)X -1046(on)X -1157(over\257ow)X -1472(pages.)X -1725(The)X -1880(addresses)X -432 3142(of)N -520(the)X -639(bitmap)X -882(pages)X -1086(and)X -1223(the)X -1342(number)X -1608(of)X -1695(pages)X -1898(allocated)X -432 3230(at)N -515(each)X -688(split)X -850(point)X -1039(are)X -1163(stored)X -1384(in)X -1470(the)X -1592(\256le)X -1718(header.)X -1997(Using)X -432 3318(this)N -577(information,)X -1005(both)X -1177(over\257ow)X -1492(addresses)X -1829(and)X -1974(bucket)X -432 3406(addresses)N -764(can)X -900(be)X -999(mapped)X -1276(to)X -1361(disk)X -1517(addresses)X -1848(by)X -1951(the)X -2072(fol-)X -432 3494(lowing)N -674(calculation:)X -0 f -8 s -432 3793(int)N -736(bucket;)X -1192(/*)X -1306(bucket)X -1572(address)X -1876(*/)X -432 3881(u_short)N -736(oaddr;)X -1192(/*)X -1306(OVERFLOW)X -1648(address)X -1952(*/)X -432 3969(int)N -736 -0.4125(nhdr_pages;)AX -1192(/*)X -1306(npages)X -1572(in)X -1686 -112.4062(\256le)AX -1838(header)X -2104(*/)X -432 4057(int)N -736 -0.4125(spares[32];)AX -1192(/*)X -1306(npages)X -1572(at)X -1686(each)X -1876(split)X -2104(*/)X -432 4145(int)N -736(log2\(\);)X -1198(/*)X -1312(ceil\(log)X -1654(base)X -1844(2\))X -1958(*/)X -432 4321(#DEFINE)N -736 -0.3929(BUCKET_TO_PAGE\(bucket\))AX -1610(\\)X -584 4409(bucket)N -850(+)X -926 -0.4167(nhdr_pages)AX -1344(+)X -1420(\\)X -584 4497 -0.3894(\(bucket?spares[logs2\(bucket)AN -1648(+)X -1724(1\)-1]:0\))X -432 4673(#DEFINE)N -736 -0.3947(OADDR_TO_PAGE\(oaddr\))AX -1534(\\)X -584 4761 -0.3984(BUCKET_TO_PAGE\(\(1)AN -1268(<<)X -1382 -0.4091(\(oaddr>>11\)\))AX -1876(-)X -1952(1\))X -2066(+)X -2142(\\)X -584 4849(oaddr)N -812(&)X -888(0x7ff;)X -1 f -10 s -604 5262(An)N -728(over\257ow)X -1039(page)X -1217(is)X -1295(addressed)X -1637(by)X -1742(its)X -1842(split)X -2004(point,)X -432 5350(identifying)N -858(the)X -1031(generations)X -1476(between)X -1819(which)X -2090(the)X -432 5438(over\257ow)N -740(page)X -915(is)X -991(allocated,)X -1324(and)X -1463(its)X -1561(page)X -1736(number,)X -2023(iden-)X -432 5526(tifying)N -665(the)X -783(particular)X -1111(page)X -1283(within)X -1507(the)X -1625(split)X -1782(point.)X -1986(In)X -2073(this)X -432 5614(implementation,)N -983(offsets)X -1225(within)X -1457(pages)X -1668(are)X -1795(16)X -1903(bits)X -2046(long)X -432 5702(\(limiting)N -732(the)X -851(maximum)X -1196(page)X -1368(size)X -1513(to)X -1595(32K\),)X -1800(so)X -1891(we)X -2005(select)X -2418 538(an)N -2535(over\257ow)X -2860(page)X -3052(addressing)X -3435(algorithm)X -3786(that)X -3946(can)X -4098(be)X -2418 626(expressed)N -2760(in)X -2847(16)X -2952(bits)X -3091(and)X -3231(which)X -3451(allows)X -3684(quick)X -3886(retrieval.)X -2418 714(The)N -2568(top)X -2695(\256ve)X -2840(bits)X -2980(indicate)X -3258(the)X -3380(split)X -3541(point)X -3729(and)X -3869(the)X -3991(lower)X -2418 802(eleven)N -2650(indicate)X -2926(the)X -3046(page)X -3220(number)X -3487(within)X -3713(the)X -3832(split)X -3990(point.)X -2418 890(Since)N -2633(\256ve)X -2789(bits)X -2940(are)X -3075(reserved)X -3384(for)X -3514(the)X -3648(split)X -3821(point,)X -4041(\256les)X -2418 978(may)N -2578(split)X -2737(32)X -2839(times)X -3034(yielding)X -3318(a)X -3376(maximum)X -3721(\256le)X -3844(size)X -3990(of)X -4078(2)X -7 s -946(32)Y -10 s -2418 1066(buckets)N -2698(and)X -2849(32)X -2 f -(*)S -1 f -2982(2)X -7 s -1034(11)Y -10 s -3113 1066(over\257ow)N -3433(pages.)X -3691(The)X -3850(maximum)X -2418 1154(page)N -2597(size)X -2749(is)X -2829(2)X -7 s -1122(15)Y -10 s -1154(,)Y -2971(yielding)X -3259(a)X -3321(maximum)X -3671(\256le)X -3799(size)X -3950(greater)X -2418 1242(than)N -2601(131,000)X -2906(GB)X -3061(\(on)X -3212(\256le)X -3358(systems)X -3655(supporting)X -4041(\256les)X -2418 1330(larger)N -2626(than)X -2784(4GB\).)X -10 f -2418 1418 -0.0930(hhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhh)AN -1 Dt -4014 2275 MXY -0 133 Dl -3881 2275 MXY -0 133 Dl -3748 2275 MXY -0 133 Dl -3083 2275 MXY -0 133 Dl -5 s -1 f -3523 2475(2/3)N -3390(2/2)X -3257(2/1)X -2859(1/2)X -2726(1/1)X -5 Dt -3814 1743 MXY -0 133 Dl -3282 1743 MXY -0 133 Dl -3017 1743 MXY -0 133 Dl -2884 1743 MXY -0 133 Dl -1 Dt -3681 1743 MXY -0 133 Dl -133 0 Dl -0 -133 Dl --133 0 Dl -3548 MX -0 133 Dl -133 0 Dl -0 -133 Dl --133 0 Dl -3415 MX -0 133 Dl -133 0 Dl -0 -133 Dl --133 0 Dl -3282 MX -0 133 Dl -133 0 Dl -0 -133 Dl --133 0 Dl -3150 MX -0 133 Dl -132 0 Dl -0 -133 Dl --132 0 Dl -3017 MX -0 133 Dl -133 0 Dl -0 -133 Dl --133 0 Dl -2884 MX -0 133 Dl -133 0 Dl -0 -133 Dl --133 0 Dl -3 f -8 s -3017 2601(Over\257ow)N -3285(Addresses)X -3515 2833(Over\257ow)N -3783(Pages)X -2850(Buckets)X -1 Di -3349 2740 MXY - 3349 2740 lineto - 3482 2740 lineto - 3482 2873 lineto - 3349 2873 lineto - 3349 2740 lineto -closepath 3 3349 2740 3482 2873 Dp -2684 MX -0 133 Dl -133 0 Dl -0 -133 Dl --133 0 Dl -5 Dt -4146 2275 MXY -0 133 Dl -3216 2275 MXY -0 133 Dl -2684 2275 MXY -0 133 Dl -2551 2275 MXY -0 133 Dl -1 f -3798 1963(3)N -3266 1980(2)N -3001(1)X -2868(0)X -1 Dt -2751 1743 MXY -0 133 Dl -133 0 Dl -0 -133 Dl --133 0 Dl -3548 2275 MXY --15 -22 Dl -2 16 Dl --13 11 Dl -26 -5 Dl --282 -117 Dl -3432 2275 MXY --10 -25 Dl --2 16 Dl --15 8 Dl -27 1 Dl --166 -117 Dl -3282 2275 MXY -12 -25 Dl --14 10 Dl --15 -6 Dl -17 21 Dl --16 -117 Dl -2884 2275 MXY -26 7 Dl --12 -12 Dl -3 -16 Dl --17 21 Dl -382 -117 Dl -2751 2275 MXY -25 9 Dl --11 -12 Dl -5 -17 Dl --19 20 Dl -515 -117 Dl -3 f -3070 2152(Over\257ow)N -3338(Pages)X -3482 2275 MXY - 3482 2275 lineto - 3615 2275 lineto - 3615 2408 lineto - 3482 2408 lineto - 3482 2275 lineto -closepath 3 3482 2275 3615 2408 Dp -3349 MX - 3349 2275 lineto - 3482 2275 lineto - 3482 2408 lineto - 3349 2408 lineto - 3349 2275 lineto -closepath 3 3349 2275 3482 2408 Dp -3216 MX - 3216 2275 lineto - 3349 2275 lineto - 3349 2408 lineto - 3216 2408 lineto - 3216 2275 lineto -closepath 3 3216 2275 3349 2408 Dp -2817 MX - 2817 2275 lineto - 2950 2275 lineto - 2950 2408 lineto - 2817 2408 lineto - 2817 2275 lineto -closepath 3 2817 2275 2950 2408 Dp -2684 MX - 2684 2275 lineto - 2817 2275 lineto - 2817 2408 lineto - 2684 2408 lineto - 2684 2275 lineto -closepath 3 2684 2275 2817 2408 Dp -3615 MX -0 133 Dl -531 0 Dl -0 -133 Dl --531 0 Dl -2950 MX -0 133 Dl -266 0 Dl -0 -133 Dl --266 0 Dl -2551 MX -0 133 Dl -133 0 Dl -0 -133 Dl --133 0 Dl -3798 1726 MXY --21 -18 Dl -6 16 Dl --10 13 Dl -25 -11 Dl --599 -99 Dl -3266 1726 MXY --1 -27 Dl --7 15 Dl --17 1 Dl -25 11 Dl --67 -99 Dl -3033 1726 MXY -27 1 Dl --14 -8 Dl --1 -17 Dl --12 24 Dl -166 -99 Dl -2900 1726 MXY -27 7 Dl --13 -11 Dl -3 -17 Dl --17 21 Dl -299 -99 Dl -3058 1621(Split)N -3203(Points)X -2418 2275 MXY -0 133 Dl -133 0 Dl -0 -133 Dl --133 0 Dl -3 Dt --1 Ds -3137(Figure)Y -2619(3:)X -1 f -2691(Split)X -2832(points)X -3008(occur)X -3168(between)X -3399(generations)X -3712(and)X -3823(are)X -3919(numbered)X -2418 3225(from)N -2560(0.)X -2642(In)X -2713(this)X -2824(\256gure)X -2991(there)X -3136(are)X -3231(two)X -3345(over\257ow)X -3590(pages)X -3753(allocated)X -4000(at)X -4063(split)X -2418 3313(point)N -2566(1)X -2614(and)X -2722(three)X -2865(allocated)X -3111(at)X -3173(split)X -3300(point)X -3448(2.)X -10 s -10 f -2418 3489 -0.0930(hhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhh)AN -3 f -2949 3731(Buffer)N -3192(Management)X -1 f -2590 3863(The)N -2744(hash)X -2920(table)X -3105(is)X -3187(stored)X -3412(in)X -3502(memory)X -3797(as)X -3892(a)X -3956(logical)X -2418 3951(array)N -2633(of)X -2749(bucket)X -3012(pointers.)X -3359(Physically,)X -3761(the)X -3907(array)X -4121(is)X -2418 4039(arranged)N -2728(in)X -2818(segments)X -3144(of)X -3239(256)X -3387(pointers.)X -3713(Initially,)X -4013(there)X -2418 4127(is)N -2530(space)X -2767(to)X -2887(allocate)X -3195(256)X -3373(segments.)X -3769(Reallocation)X -2418 4215(occurs)N -2651(when)X -2847(the)X -2967(number)X -3234(of)X -3323(buckets)X -3590(exceeds)X -3867(32K)X -4027(\(256)X -2418 4303(*)N -2508(256\).)X -2745(Primary)X -3053(pages)X -3286(may)X -3473(be)X -3598(accessed)X -3929(directly)X -2418 4391(through)N -2711(the)X -2853(array)X -3062(by)X -3185(bucket)X -3442(number)X -3730(and)X -3889(over\257ow)X -2418 4479(pages)N -2628(are)X -2754 0.4028(referenced)AX -3122(logically)X -3429(by)X -3536(their)X -3710(over\257ow)X -4022(page)X -2418 4567(address.)N -2726(For)X -2864(small)X -3063(hash)X -3236(tables,)X -3469(it)X -3539(is)X -3618(desirable)X -3934(to)X -4022(keep)X -2418 4655(all)N -2525(pages)X -2735(in)X -2823(main)X -3009(memory)X -3302(while)X -3506(on)X -3612(larger)X -3826(tables,)X -4059(this)X -2418 4743(is)N -2523(probably)X -2860(impossible.)X -3298(To)X -3438(satisfy)X -3698(both)X -3891(of)X -4009(these)X -2418 4831(requirements,)N -2900(the)X -3041(package)X -3348(includes)X -3658(buffer)X -3897(manage-)X -2418 4919(ment)N -2598(with)X -2760(LRU)X -2940(\(least)X -3134(recently)X -3413(used\))X -3607(replacement.)X -2590 5033(By)N -2730(default,)X -3020(the)X -3165(package)X -3475(allocates)X -3802(up)X -3928(to)X -4036(64K)X -2418 5121(bytes)N -2616(of)X -2712(buffered)X -3014(pages.)X -3246(All)X -3377(pages)X -3589(in)X -3680(the)X -3807(buffer)X -4032(pool)X -2418 5209(are)N -2542(linked)X -2766(in)X -2852(LRU)X -3036(order)X -3230(to)X -3316(facilitate)X -3621(fast)X -3761(replacement.)X -2418 5297(Whereas)N -2724(ef\256cient)X -3011(access)X -3241(to)X -3327(primary)X -3605(pages)X -3812(is)X -3889(provided)X -2418 5385(by)N -2521(the)X -2642(bucket)X -2879(array,)X -3087(ef\256cient)X -3372(access)X -3600(to)X -3684(over\257ow)X -3991(pages)X -2418 5473(is)N -2501(provided)X -2816(by)X -2926(linking)X -3182(over\257ow)X -3497(page)X -3679(buffers)X -3936(to)X -4027(their)X -2418 5561(predecessor)N -2827(page)X -3008(\(either)X -3247(the)X -3374(primary)X -3657(page)X -3838(or)X -3933(another)X -2418 5649(over\257ow)N -2742(page\).)X -3000(This)X -3181(means)X -3425(that)X -3584(an)X -3699(over\257ow)X -4022(page)X -3 f -432 5960(6)N -2970(USENIX)X -9 f -3292(-)X -3 f -3356(Winter)X -3621('91)X -9 f -3748(-)X -3 f -3812(Dallas,)X -4065(TX)X - -7 p -%%Page: 7 7 -0(Courier)xf 0 f -10 s 10 xH 0 xS 0 f -3 f -720 258(Seltzer)N -977(&)X -1064(Yigit)X -3278(A)X -3356(New)X -3528(Hashing)X -3831(Package)X -4136(for)X -4259(UNIX)X -1 f -720 538(cannot)N -955(be)X -1052(present)X -1305(in)X -1388(the)X -1507(buffer)X -1724(pool)X -1886(if)X -1955(its)X -2050(primary)X -2324(page)X -720 626(is)N -804(not)X -937(present.)X -1240(This)X -1413(does)X -1591(not)X -1724(impact)X -1972(performance)X -2409(or)X -720 714(functionality,)N -1209(because)X -1524(an)X -1660(over\257ow)X -2005(page)X -2217(will)X -2400(be)X -720 802(accessed)N -1048(only)X -1236(after)X -1430(its)X -1550(predecessor)X -1975(page)X -2172(has)X -2324(been)X -720 890(accessed.)N -1068(Figure)X -1303(4)X -1369(depicts)X -1622(the)X -1746(data)X -1905(structures)X -2242(used)X -2414(to)X -720 978(manage)N -990(the)X -1108(buffer)X -1325(pool.)X -892 1092(The)N -1040(in-memory)X -1419(bucket)X -1656(array)X -1845(contains)X -2134(pointers)X -2414(to)X -720 1180(buffer)N -975(header)X -1248(structures)X -1617(which)X -1870(represent)X -2222(primary)X -720 1268(pages.)N -968(Buffer)X -1203(headers)X -1474(contain)X -1735(modi\256ed)X -2043(bits,)X -2202(the)X -2324(page)X -720 1356(address)N -995(of)X -1096(the)X -1228(buffer,)X -1479(a)X -1548(pointer)X -1808(to)X -1903(the)X -2034(actual)X -2259(buffer,)X -720 1444(and)N -875(a)X -950(pointer)X -1216(to)X -1317(the)X -1454(buffer)X -1690(header)X -1944(for)X -2077(an)X -2191(over\257ow)X -720 1532(page)N -901(if)X -979(it)X -1052(exists,)X -1283(in)X -1374(addition)X -1665(to)X -1756(the)X -1883(LRU)X -2072(links.)X -2296(If)X -2378(the)X -720 1620(buffer)N -950(corresponding)X -1442(to)X -1537(a)X -1606(particular)X -1947(bucket)X -2194(is)X -2280(not)X -2414(in)X -720 1708(memory,)N -1048(its)X -1164(pointer)X -1432(is)X -1526(NULL.)X -1801(In)X -1909(effect,)X -2154(pages)X -2377(are)X -720 1796(linked)N -950(in)X -1042(three)X -1233(ways.)X -1468(Using)X -1689(the)X -1817(buffer)X -2043(headers,)X -2338(they)X -720 1884(are)N -851(linked)X -1083(physically)X -1444(through)X -1725(the)X -1854(LRU)X -2045(links)X -2231(and)X -2378(the)X -720 1972(over\257ow)N -1036(links.)X -1241(Using)X -1462(the)X -1590(pages)X -1803(themselves,)X -2209(they)X -2377(are)X -720 2060(linked)N -943(logically)X -1246(through)X -1518(the)X -1639(over\257ow)X -1946(addresses)X -2276(on)X -2378(the)X -720 2148(page.)N -948(Since)X -1162(over\257ow)X -1482(pages)X -1700(are)X -1834(accessed)X -2151(only)X -2328(after)X -720 2236(their)N -904(predecessor)X -1321(pages,)X -1560(they)X -1734(are)X -1869(removed)X -2186(from)X -2378(the)X -720 2324(buffer)N -937(pool)X -1099(when)X -1293(their)X -1460(primary)X -1734(is)X -1807(removed.)X -10 f -720 2412 -0.0930(hhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhh)AN -1 Dt -2309 3177 MXY -24 15 Dl --8 -15 Dl -8 -15 Dl --24 15 Dl -52 0 Dl -789 3160 MXY --35 0 Dl -0 -156 Dl -1607 0 Dl -0 173 Dl -789 3091 MXY --24 -15 Dl -9 15 Dl --9 15 Dl -24 -15 Dl --69 0 Dl -2309 3125 MXY -104 0 Dl -0 -155 Dl --1693 0 Dl -0 121 Dl -927 3160 MXY -24 15 Dl --9 -15 Dl -9 -15 Dl --24 15 Dl -553 0 Dl -1618 3177 MXY -8 27 Dl -4 -17 Dl -16 -6 Dl --28 -4 Dl -138 121 Dl -1895 3315 MXY -28 3 Dl --15 -9 Dl -1 -18 Dl --14 24 Dl -276 -138 Dl -3108 MY --28 -3 Dl -15 10 Dl --1 17 Dl -14 -24 Dl --276 138 Dl -1756 3229 MXY --8 -27 Dl --3 17 Dl --16 6 Dl -27 4 Dl --138 -121 Dl -1480 MX --24 -15 Dl -9 15 Dl --9 15 Dl -24 -15 Dl --553 0 Dl -3 f -5 s -1083 3073(LRU)N -1178(chain)X -4 Ds -1402 3851 MXY - 1402 3851 lineto - 1471 3851 lineto - 1471 3920 lineto - 1402 3920 lineto - 1402 3851 lineto -closepath 19 1402 3851 1471 3920 Dp -1445 3747(Over\257ow)N -1613(Address)X -1549 3609 MXY -0 69 Dl -1756 MX --23 -15 Dl -8 15 Dl --8 15 Dl -23 -15 Dl --207 0 Dl --1 Ds -3 Dt -1756 3419 MXY --6 -28 Dl --4 17 Dl --17 5 Dl -27 6 Dl --138 -138 Dl -2240 3471 MXY -15 -24 Dl --15 9 Dl --15 -9 Dl -15 24 Dl -0 -138 Dl -1826 3609 MXY -15 -24 Dl --15 9 Dl --16 -9 Dl -16 24 Dl -0 -138 Dl -1549 MX -15 -24 Dl --15 9 Dl --15 -9 Dl -15 24 Dl -0 -138 Dl -858 3471 MXY -15 -24 Dl --15 9 Dl --15 -9 Dl -15 24 Dl -0 -138 Dl -2240 3056 MXY -15 -24 Dl --15 9 Dl --15 -9 Dl -15 24 Dl -0 -138 Dl -1549 3056 MXY -15 -24 Dl --15 9 Dl --15 -9 Dl -15 24 Dl -0 -138 Dl -858 3056 MXY -15 -24 Dl --15 9 Dl --15 -9 Dl -15 24 Dl -0 -138 Dl -1 Dt -2171 3471 MXY - 2171 3471 lineto - 2448 3471 lineto - 2448 3609 lineto - 2171 3609 lineto - 2171 3471 lineto -closepath 19 2171 3471 2448 3609 Dp -1756 3609 MXY - 1756 3609 lineto - 2033 3609 lineto - 2033 3747 lineto - 1756 3747 lineto - 1756 3609 lineto -closepath 3 1756 3609 2033 3747 Dp -1480 3471 MXY - 1480 3471 lineto - 1756 3471 lineto - 1756 3609 lineto - 1480 3609 lineto - 1480 3471 lineto -closepath 19 1480 3471 1756 3609 Dp -789 MX - 789 3471 lineto - 1065 3471 lineto - 1065 3609 lineto - 789 3609 lineto - 789 3471 lineto -closepath 19 789 3471 1065 3609 Dp -962 3903(Buffer)N -1083(Header)X -849 3851 MXY - 849 3851 lineto - 918 3851 lineto - 918 3920 lineto - 849 3920 lineto - 849 3851 lineto -closepath 14 849 3851 918 3920 Dp -1756 3194 MXY - 1756 3194 lineto - 1895 3194 lineto - 1895 3471 lineto - 1756 3471 lineto - 1756 3194 lineto -closepath 14 1756 3194 1895 3471 Dp -2171 3056 MXY - 2171 3056 lineto - 2309 3056 lineto - 2309 3333 lineto - 2171 3333 lineto - 2171 3056 lineto -closepath 14 2171 3056 2309 3333 Dp -1480 MX - 1480 3056 lineto - 1618 3056 lineto - 1618 3333 lineto - 1480 3333 lineto - 1480 3056 lineto -closepath 14 1480 3056 1618 3333 Dp -789 MX - 789 3056 lineto - 927 3056 lineto - 927 3333 lineto - 789 3333 lineto - 789 3056 lineto -closepath 14 789 3056 927 3333 Dp -2780 MY -0 138 Dl -138 0 Dl -0 -138 Dl --138 0 Dl -927 MX -0 138 Dl -138 0 Dl -0 -138 Dl --138 0 Dl -1065 MX -0 138 Dl -138 0 Dl -0 -138 Dl --138 0 Dl -1203 MX -0 138 Dl -139 0 Dl -0 -138 Dl --139 0 Dl -1342 MX -0 138 Dl -138 0 Dl -0 -138 Dl --138 0 Dl -1480 MX -0 138 Dl -138 0 Dl -0 -138 Dl --138 0 Dl -1618 MX -0 138 Dl -138 0 Dl -0 -138 Dl --138 0 Dl -1756 MX -0 138 Dl -139 0 Dl -0 -138 Dl --139 0 Dl -1895 MX -0 138 Dl -138 0 Dl -0 -138 Dl --138 0 Dl -2033 MX -0 138 Dl -138 0 Dl -0 -138 Dl --138 0 Dl -2171 MX -0 138 Dl -138 0 Dl -0 -138 Dl --138 0 Dl -2309 MX -0 138 Dl -139 0 Dl -0 -138 Dl --139 0 Dl -13 s -1048 2720(In)N -1173(Memory)X -1580(Bucket)X -1918(Array)X -867 3584(B0)N -1558(B5)X -2223(B10)X -1788 3722(O1/1)N -5 s -1515 3903(Primay)N -1651(Buffer)X -4 Ds -1990 3851 MXY - 1990 3851 lineto - 2059 3851 lineto - 2059 3920 lineto - 1990 3920 lineto - 1990 3851 lineto -closepath 3 1990 3851 2059 3920 Dp -2102 3903(Over\257ow)N -2270(Buffer)X -3 Dt --1 Ds -8 s -720 4184(Figure)N -922(4:)X -1 f -996(Three)X -1164(primary)X -1386(pages)X -1551(\(B0,)X -1683(B5,)X -1794(B10\))X -1942(are)X -2039(accessed)X -2281(directly)X -720 4272(from)N -862(the)X -958(bucket)X -1146(array.)X -1326(The)X -1443(one)X -1553(over\257ow)X -1798(page)X -1935(\(O1/1\))X -2122(is)X -2182(linked)X -2359(phy-)X -720 4360(sically)N -915(from)X -1067(its)X -1155(primary)X -1384(page's)X -1577(buffer)X -1759(header)X -1955(as)X -2035(well)X -2172(as)X -2252(logically)X -720 4448(from)N -860(its)X -937(predecessor)X -1253(page)X -1389(buffer)X -1560(\(B5\).)X -10 s -10 f -720 4624 -0.0930(hhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhh)AN -3 f -1191 4954(Table)N -1406(Parameterization)X -1 f -892 5086(When)N -1107(a)X -1166(hash)X -1336(table)X -1515(is)X -1590(created,)X -1865(the)X -1985(bucket)X -2221(size,)X -2388(\256ll)X -720 5174(factor,)N -953(initial)X -1164(number)X -1434(of)X -1526(elements,)X -1856(number)X -2125(of)X -2216(bytes)X -2409(of)X -720 5262(main)N -919(memory)X -1225(used)X -1411(for)X -1543(caching,)X -1851(and)X -2005(a)X -2079(user-de\256ned)X -720 5350(hash)N -892(function)X -1184(may)X -1347(be)X -1448(speci\256ed.)X -1797(The)X -1946(bucket)X -2184(size)X -2333(\(and)X -720 5438(page)N -906(size)X -1064(for)X -1191(over\257ow)X -1509(pages\))X -1752(defaults)X -2039(to)X -2134(256)X -2287(bytes.)X -720 5526(For)N -858(tables)X -1072(with)X -1241(large)X -1429(data)X -1590(items,)X -1810(it)X -1881(may)X -2046(be)X -2149(preferable)X -720 5614(to)N -803(increase)X -1088(the)X -1207(page)X -1380(size,)X -1545(and,)X -1701(conversely,)X -2089(applications)X -720 5702(storing)N -1002(small)X -1235(items)X -1467(exclusively)X -1891(in)X -2012(memory)X -2338(may)X -2706 538(bene\256t)N -2966(from)X -3164(a)X -3242(smaller)X -3520(bucket)X -3776(size.)X -3983(A)X -4082(bucket)X -4337(size)X -2706 626(smaller)N -2962(than)X -3120(64)X -3220(bytes)X -3409(is)X -3482(not)X -3604(recommended.)X -2878 740(The)N -3031(\256ll)X -3147(factor)X -3363(indicates)X -3676(a)X -3740(desired)X -4000(density)X -4258(within)X -2706 828(the)N -2833(hash)X -3009(table.)X -3234(It)X -3312(is)X -3394(an)X -3499(approximation)X -3995(of)X -4091(the)X -4217(number)X -2706 916(of)N -2815(keys)X -3004(allowed)X -3300(to)X -3404(accumulate)X -3811(in)X -3914(any)X -4071(one)X -4228(bucket,)X -2706 1004(determining)N -3119(when)X -3319(the)X -3442(hash)X -3614(table)X -3795(grows.)X -4056(Its)X -4161(default)X -4409(is)X -2706 1092(eight.)N -2953(If)X -3054(the)X -3199(user)X -3380(knows)X -3636(the)X -3781(average)X -4079(size)X -4251(of)X -4364(the)X -2706 1180(key/data)N -3008(pairs)X -3194(being)X -3402(stored)X -3627(in)X -3718(the)X -3845(table,)X -4050(near)X -4218(optimal)X -2706 1268(bucket)N -2943(sizes)X -3122(and)X -3261(\256ll)X -3372(factors)X -3614(may)X -3775(be)X -3874(selected)X -4155(by)X -4257(apply-)X -2706 1356(ing)N -2828(the)X -2946(equation:)X -0 f -8 s -2706 1655(\(1\))N -2994 -0.3938(\(\(average_pair_length)AX -3830(+)X -3906(4\))X -4020(*)X -3032 1743(ffactor\))N -3374(>=)X -3488(bsize)X -1 f -10 s -2706 2042(For)N -2859(highly)X -3104(time)X -3287(critical)X -3551(applications,)X -3999(experimenting)X -2706 2130(with)N -2919(different)X -3266(bucket)X -3550(sizes)X -3776(and)X -3962(\256ll)X -4120(factors)X -4409(is)X -2706 2218(encouraged.)N -2878 2332(Figures)N -3144(5a,b,)X -3326(and)X -3468(c)X -3530(illustrate)X -3836(the)X -3960(effects)X -4200(of)X -4292(vary-)X -2706 2420(ing)N -2841(page)X -3026(sizes)X -3215(and)X -3363(\256ll)X -3483(factors)X -3734(for)X -3860(the)X -3990(same)X -4187(data)X -4353(set.)X -2706 2508(The)N -2864(data)X -3031(set)X -3152(consisted)X -3482(of)X -3581(24474)X -3813(keys)X -3992(taken)X -4198(from)X -4386(an)X -2706 2596(online)N -2931(dictionary.)X -3301(The)X -3451(data)X -3609(value)X -3807(for)X -3925(each)X -4097(key)X -4237(was)X -4386(an)X -2706 2684(ASCII)N -2938(string)X -3143(for)X -3260(an)X -3359(integer)X -3605(from)X -3784(1)X -3847(to)X -3931(24474)X -4153(inclusive.)X -2706 2772(The)N -2867(test)X -3013(run)X -3155(consisted)X -3488(of)X -3590(creating)X -3884(a)X -3955(new)X -4124(hash)X -4306(table)X -2706 2860(\(where)N -2966(the)X -3100(ultimate)X -3398(size)X -3559(of)X -3662(the)X -3796(table)X -3987(was)X -4147(known)X -4400(in)X -2706 2948(advance\),)N -3054(entering)X -3354(each)X -3539(key/data)X -3848(pair)X -4010(into)X -4171(the)X -4306(table)X -2706 3036(and)N -2849(then)X -3014(retrieving)X -3353(each)X -3528(key/data)X -3827(pair)X -3979(from)X -4162(the)X -4286(table.)X -2706 3124(Each)N -2898(of)X -2996(the)X -3125(graphs)X -3369(shows)X -3599(the)X -3727(timings)X -3996(resulting)X -4306(from)X -2706 3212(varying)N -2973(the)X -3093(pagesize)X -3392(from)X -3570(128)X -3712(bytes)X -3903(to)X -3986(1M)X -4118(and)X -4255(the)X -4374(\256ll)X -2706 3300(factor)N -2929(from)X -3120(1)X -3195(to)X -3292(128.)X -3486(For)X -3631(each)X -3813(run,)X -3974(the)X -4106(buffer)X -4337(size)X -2706 3388(was)N -2874(set)X -3006(at)X -3106(1M.)X -3299(The)X -3466(tests)X -3650(were)X -3849(all)X -3971(run)X -4120(on)X -4242(an)X -4360(HP)X -2706 3476(9000/370)N -3077(\(33.3)X -3312(Mhz)X -3527(MC68030\),)X -3966(with)X -4176(16M)X -4395(of)X -2706 3564(memory,)N -3042(64K)X -3228(physically)X -3605(addressed)X -3970(cache,)X -4222(and)X -4386(an)X -2706 3652(HP7959S)N -3055(disk)X -3231(drive,)X -3459(running)X -3751(4.3BSD-Reno)X -4244(single-)X -2706 3740(user.)N -2878 3854(Both)N -3066(system)X -3321(time)X -3496(\(Figure)X -3764(5a\))X -3899(and)X -4047(elapsed)X -4320(time)X -2706 3942(\(Figure)N -2966(5b\))X -3097(show)X -3290(that)X -3434(for)X -3552(all)X -3655(bucket)X -3892(sizes,)X -4091(the)X -4212(greatest)X -2706 4030(performance)N -3137(gains)X -3329(are)X -3451(made)X -3648(by)X -3751(increasing)X -4104(the)X -4225(\256ll)X -4336(fac-)X -2706 4118(tor)N -2822(until)X -2995(equation)X -3298(1)X -3365(is)X -3445(satis\256ed.)X -3774(The)X -3925(user)X -4085(time)X -4253(shown)X -2706 4206(in)N -2791(Figure)X -3023(5c)X -3122(gives)X -3314(a)X -3373(more)X -3561(detailed)X -3838(picture)X -4083(of)X -4172(how)X -4332(per-)X -2706 4294(formance)N -3054(varies.)X -3330(The)X -3499(smaller)X -3778(bucket)X -4035(sizes)X -4234(require)X -2706 4382(fewer)N -2921(keys)X -3099(per)X -3233(page)X -3416(to)X -3509(satisfy)X -3749(equation)X -4056(1)X -4127(and)X -4274(there-)X -2706 4470(fore)N -2860(incur)X -3049(fewer)X -3257(collisions.)X -3607(However,)X -3946(when)X -4144(the)X -4265(buffer)X -2706 4558(pool)N -2884(size)X -3045(is)X -3134(\256xed,)X -3349(smaller)X -3620(pages)X -3838(imply)X -4059(more)X -4259(pages.)X -2706 4646(An)N -2830(increased)X -3160(number)X -3430(of)X -3522(pages)X -3730(means)X -3960(more)X -2 f -4150(malloc\(3\))X -1 f -2706 4734(calls)N -2879(and)X -3021(more)X -3212(overhead)X -3533(in)X -3621(the)X -3745(hash)X -3918(package's)X -4265(buffer)X -2706 4822(manager)N -3003(to)X -3085(manage)X -3355(the)X -3473(additional)X -3813(pages.)X -2878 4936(The)N -3028(tradeoff)X -3308(works)X -3529(out)X -3655(most)X -3834(favorably)X -4166(when)X -4364(the)X -2706 5024(page)N -2886(size)X -3039(is)X -3120(256)X -3268(and)X -3412(the)X -3538(\256ll)X -3654(factor)X -3870(is)X -3950(8.)X -4057(Similar)X -4319(con-)X -2706 5112(clusions)N -3009(were)X -3207(obtained)X -3524(if)X -3614(the)X -3753(test)X -3905(was)X -4071(run)X -4218(without)X -2706 5200(knowing)N -3007(the)X -3126(\256nal)X -3289(table)X -3466(size)X -3612(in)X -3695(advance.)X -4020(If)X -4095(the)X -4214(\256le)X -4337(was)X -2706 5288(closed)N -2942(and)X -3088(written)X -3345(to)X -3437(disk,)X -3620(the)X -3748(conclusions)X -4156(were)X -4343(still)X -2706 5376(the)N -2832(same.)X -3065(However,)X -3408(rereading)X -3740(the)X -3865(\256le)X -3994(from)X -4177(disk)X -4337(was)X -2706 5464(slightly)N -2983(faster)X -3199(if)X -3285(a)X -3358(larger)X -3583(bucket)X -3834(size)X -3996(and)X -4149(\256ll)X -4274(factor)X -2706 5552(were)N -2898(used)X -3079(\(1K)X -3238(bucket)X -3486(size)X -3645(and)X -3795(32)X -3909(\256ll)X -4031(factor\).)X -4320(This)X -2706 5640(follows)N -2987(intuitively)X -3356(from)X -3553(the)X -3691(improved)X -4038(ef\256ciency)X -4395(of)X -3 f -720 5960(USENIX)N -9 f -1042(-)X -3 f -1106(Winter)X -1371('91)X -9 f -1498(-)X -3 f -1562(Dallas,)X -1815(TX)X -4424(7)X - -8 p -%%Page: 8 8 -0(Courier)xf 0 f -10 s 10 xH 0 xS 0 f -3 f -432 258(A)N -510(New)X -682(Hashing)X -985(Package)X -1290(for)X -1413(UNIX)X -3663(Seltzer)X -3920(&)X -4007(Yigit)X -1 f -432 538(performing)N -830(1K)X -965(reads)X -1172(from)X -1365(the)X -1500(disk)X -1670(rather)X -1894(than)X -2068(256)X -432 626(byte)N -609(reads.)X -857(In)X -962(general,)X -1257(performance)X -1702(for)X -1834(disk)X -2005(based)X -432 714(tables)N -639(is)X -712(best)X -861(when)X -1055(the)X -1173(page)X -1345(size)X -1490(is)X -1563(approximately)X -2046(1K.)X -10 f -432 802 -0.0930(hhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhh)AN -619 2380 MXY --12 24 Dl -24 0 Dl --12 -24 Dl -629 2437 MXY --12 24 Dl -24 0 Dl --12 -24 Dl -648 2504 MXY --12 25 Dl -24 0 Dl --12 -25 Dl -686 2515 MXY --12 24 Dl -24 0 Dl --12 -24 Dl -762 2516 MXY --12 24 Dl -25 0 Dl --13 -24 Dl -916 2515 MXY --13 24 Dl -25 0 Dl --12 -24 Dl -1222 2516 MXY --12 24 Dl -24 0 Dl --12 -24 Dl -1834 2515 MXY --12 24 Dl -24 0 Dl --12 -24 Dl -1 Dt -619 2392 MXY -10 57 Dl -19 67 Dl -38 11 Dl -76 1 Dl -154 -1 Dl -306 1 Dl -612 -1 Dl -8 s -1 f -1628 2522(128)N -3 Dt -607 2245 MXY -24 Dc -617 2375 MXY -23 Dc -635 2442 MXY -24 Dc -674 2525 MXY -23 Dc -750 2529 MXY -24 Dc -904 2527 MXY -23 Dc -1210 MX -23 Dc -1822 2528 MXY -23 Dc -20 Ds -1 Dt -619 2245 MXY -10 130 Dl -19 67 Dl -38 83 Dl -76 4 Dl -154 -2 Dl -306 0 Dl -612 1 Dl -678 2482(256)N --1 Ds -3 Dt -619 2127 MXY -0 24 Dl -0 -12 Dl -12 0 Dl --24 0 Dl -629 2191 MXY -0 25 Dl -0 -12 Dl -12 0 Dl --24 0 Dl -648 2334 MXY -0 24 Dl -0 -12 Dl -12 0 Dl --24 0 Dl -686 2409 MXY -0 25 Dl -0 -13 Dl -12 0 Dl --24 0 Dl -762 2516 MXY -0 25 Dl -0 -12 Dl -13 0 Dl --25 0 Dl -916 2516 MXY -0 24 Dl -0 -12 Dl -12 0 Dl --25 0 Dl -1222 2515 MXY -0 24 Dl -0 -12 Dl -12 0 Dl --24 0 Dl -1834 2515 MXY -0 24 Dl -0 -12 Dl -12 0 Dl --24 0 Dl -5 Dt -619 2139 MXY -10 65 Dl -19 142 Dl -38 75 Dl -76 108 Dl -154 -1 Dl -306 -1 Dl -612 0 Dl -694 2401(512)N -3 Dt -631 2064 MXY --24 24 Dl -12 -12 Dl --12 -12 Dl -24 24 Dl -641 2077 MXY --24 25 Dl -12 -12 Dl --12 -13 Dl -24 25 Dl -660 2132 MXY --24 24 Dl -12 -12 Dl --12 -12 Dl -24 24 Dl -698 2292 MXY --24 24 Dl -12 -12 Dl --12 -12 Dl -24 24 Dl -775 2382 MXY --25 24 Dl -12 -12 Dl --12 -12 Dl -25 24 Dl -928 2516 MXY --25 24 Dl -13 -12 Dl --13 -12 Dl -25 24 Dl -1234 2516 MXY --24 25 Dl -12 -12 Dl --12 -13 Dl -24 25 Dl -1846 2516 MXY --24 24 Dl -12 -12 Dl --12 -12 Dl -24 24 Dl -16 Ds -1 Dt -619 2076 MXY -10 14 Dl -19 54 Dl -38 160 Dl -76 90 Dl -154 134 Dl -306 1 Dl -612 -1 Dl -694 2257(1024)N --1 Ds -3 Dt -619 1877 MXY -12 -24 Dl --24 0 Dl -12 24 Dl -629 1855 MXY -12 -24 Dl --24 0 Dl -12 24 Dl -648 1838 MXY -12 -24 Dl --24 0 Dl -12 24 Dl -686 1860 MXY -12 -25 Dl --24 0 Dl -12 25 Dl -762 1923 MXY -13 -24 Dl --25 0 Dl -12 24 Dl -916 2087 MXY -12 -24 Dl --25 0 Dl -13 24 Dl -1222 2256 MXY -12 -24 Dl --24 0 Dl -12 24 Dl -1834 2541 MXY -12 -25 Dl --24 0 Dl -12 25 Dl -619 1865 MXY -10 -22 Dl -19 -17 Dl -38 21 Dl -76 64 Dl -154 164 Dl -306 169 Dl -612 285 Dl -1645 2427(4096)N -619 1243 MXY -0 24 Dl -0 -12 Dl -12 0 Dl --24 0 Dl -629 1196 MXY -0 24 Dl -0 -12 Dl -12 0 Dl --24 0 Dl -648 1146 MXY -0 24 Dl -0 -12 Dl -12 0 Dl --24 0 Dl -686 1174 MXY -0 25 Dl -0 -13 Dl -12 0 Dl --24 0 Dl -762 1249 MXY -0 24 Dl -0 -12 Dl -13 0 Dl --25 0 Dl -916 1371 MXY -0 24 Dl -0 -12 Dl -12 0 Dl --25 0 Dl -1222 1680 MXY -0 24 Dl -0 -12 Dl -12 0 Dl --24 0 Dl -1834 1999 MXY -0 24 Dl -0 -12 Dl -12 0 Dl --24 0 Dl -619 1255 MXY -10 -47 Dl -19 -50 Dl -38 28 Dl -76 75 Dl -154 122 Dl -306 309 Dl -612 319 Dl -1741 1934(8192)N -5 Dt -609 2531 MXY -1225 0 Dl -609 MX -0 -1553 Dl -2531 MY -0 16 Dl -4 Ds -1 Dt -2531 MY -0 -1553 Dl -593 2625(0)N --1 Ds -5 Dt -916 2531 MXY -0 16 Dl -4 Ds -1 Dt -2531 MY -0 -1553 Dl -884 2625(32)N --1 Ds -5 Dt -1222 2531 MXY -0 16 Dl -4 Ds -1 Dt -2531 MY -0 -1553 Dl -1190 2625(64)N --1 Ds -5 Dt -1528 2531 MXY -0 16 Dl -4 Ds -1 Dt -2531 MY -0 -1553 Dl -1496 2625(96)N --1 Ds -5 Dt -1834 2531 MXY -0 16 Dl -4 Ds -1 Dt -2531 MY -0 -1553 Dl -1786 2625(128)N --1 Ds -5 Dt -609 2531 MXY --16 0 Dl -4 Ds -1 Dt -609 MX -1225 0 Dl -545 2558(0)N --1 Ds -5 Dt -609 2013 MXY --16 0 Dl -4 Ds -1 Dt -609 MX -1225 0 Dl -481 2040(100)N --1 Ds -5 Dt -609 1496 MXY --16 0 Dl -4 Ds -1 Dt -609 MX -1225 0 Dl -481 1523(200)N --1 Ds -5 Dt -609 978 MXY --16 0 Dl -4 Ds -1 Dt -609 MX -1225 0 Dl -481 1005(300)N -1088 2724(Fill)N -1194(Factor)X -422 1611(S)N -426 1667(e)N -426 1724(c)N -424 1780(o)N -424 1837(n)N -424 1893(d)N -428 1949(s)N -3 Dt --1 Ds -3 f -432 2882(Figure)N -636(5a:)X -1 f -744(System)X -956(Time)X -1113(for)X -1209(dictionary)X -1490(data)X -1618(set)X -1711(with)X -1847(1M)X -1958(of)X -2033(buffer)X -432 2970(space)N -594(and)X -707(varying)X -923(bucket)X -1114(sizes)X -1259(and)X -1372(\256ll)X -1465(factors.)X -1675(Each)X -1823(line)X -1940(is)X -2004(labeled)X -432 3058(with)N -562(its)X -639(bucket)X -825(size.)X -10 s -10 f -432 3234 -0.0930(hhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhh)AN -8 s -1 f -428 4381(s)N -424 4325(d)N -424 4269(n)N -424 4212(o)N -426 4156(c)N -426 4099(e)N -422 4043(S)N -1116 5156(Fill)N -1222(Factor)X -506 3437(3200)N -4 Ds -1 Dt -666 3410 MXY -1168 0 Dl --1 Ds -5 Dt -666 MX --16 0 Dl -506 3825(2400)N -4 Ds -1 Dt -666 3799 MXY -1168 0 Dl --1 Ds -5 Dt -666 MX --16 0 Dl -506 4214(1600)N -4 Ds -1 Dt -666 4186 MXY -1168 0 Dl --1 Ds -5 Dt -666 MX --16 0 Dl -538 4602(800)N -4 Ds -1 Dt -666 4575 MXY -1168 0 Dl --1 Ds -5 Dt -666 MX --16 0 Dl -602 4990(0)N -4 Ds -1 Dt -666 4963 MXY -1168 0 Dl --1 Ds -5 Dt -666 MX --16 0 Dl -1786 5057(128)N -4 Ds -1 Dt -1834 4963 MXY -0 -1553 Dl --1 Ds -5 Dt -4963 MY -0 16 Dl -1510 5057(96)N -4 Ds -1 Dt -1542 4963 MXY -0 -1553 Dl --1 Ds -5 Dt -4963 MY -0 16 Dl -1218 5057(64)N -4 Ds -1 Dt -1250 4963 MXY -0 -1553 Dl --1 Ds -5 Dt -4963 MY -0 16 Dl -926 5057(32)N -4 Ds -1 Dt -958 4963 MXY -0 -1553 Dl --1 Ds -5 Dt -4963 MY -0 16 Dl -650 5057(0)N -4 Ds -1 Dt -666 4963 MXY -0 -1553 Dl --1 Ds -5 Dt -4963 MY -0 16 Dl -4963 MY -0 -1553 Dl -4963 MY -1168 0 Dl -1741 4752(8192)N -3 Dt -675 3732 MXY -9 -172 Dl -18 -118 Dl -37 128 Dl -73 -121 Dl -146 623 Dl -292 497 Dl -584 245 Dl -4802 MY -0 24 Dl -0 -12 Dl -12 0 Dl --24 0 Dl -1250 4557 MXY -0 25 Dl -0 -13 Dl -12 0 Dl --24 0 Dl -958 4060 MXY -0 24 Dl -0 -12 Dl -12 0 Dl --24 0 Dl -812 3437 MXY -0 24 Dl -0 -12 Dl -12 0 Dl --24 0 Dl -739 3558 MXY -0 24 Dl -0 -12 Dl -12 0 Dl --24 0 Dl -702 3430 MXY -0 25 Dl -0 -13 Dl -13 0 Dl --25 0 Dl -684 3548 MXY -0 24 Dl -0 -12 Dl -12 0 Dl --24 0 Dl -675 3720 MXY -0 24 Dl -0 -12 Dl -12 0 Dl --24 0 Dl -1637 4912(4096)N -675 4307 MXY -9 -58 Dl -18 30 Dl -37 89 Dl -73 144 Dl -146 235 Dl -292 122 Dl -584 89 Dl -4970 MY -12 -24 Dl --24 0 Dl -12 24 Dl -1250 4881 MXY -12 -24 Dl --24 0 Dl -12 24 Dl -958 4759 MXY -12 -24 Dl --24 0 Dl -12 24 Dl -812 4524 MXY -12 -24 Dl --24 0 Dl -12 24 Dl -739 4380 MXY -12 -24 Dl --24 0 Dl -12 24 Dl -702 4291 MXY -13 -24 Dl --25 0 Dl -12 24 Dl -684 4261 MXY -12 -24 Dl --24 0 Dl -12 24 Dl -675 4319 MXY -12 -24 Dl --24 0 Dl -12 24 Dl -734 4662(1024)N -16 Ds -1 Dt -675 4352 MXY -9 60 Dl -18 134 Dl -37 266 Dl -73 117 Dl -146 30 Dl -292 0 Dl -584 -1 Dl --1 Ds -3 Dt -1846 4946 MXY --24 24 Dl -12 -12 Dl --12 -12 Dl -24 24 Dl -1262 4946 MXY --24 25 Dl -12 -12 Dl --12 -13 Dl -24 25 Dl -970 4947 MXY --24 24 Dl -12 -12 Dl --12 -12 Dl -24 24 Dl -824 4917 MXY --24 24 Dl -12 -12 Dl --12 -12 Dl -24 24 Dl -751 4800 MXY --24 24 Dl -12 -12 Dl --12 -12 Dl -24 24 Dl -715 4534 MXY --25 25 Dl -12 -13 Dl --12 -12 Dl -25 25 Dl -696 4400 MXY --24 24 Dl -12 -12 Dl --12 -12 Dl -24 24 Dl -687 4339 MXY --24 25 Dl -12 -12 Dl --12 -13 Dl -24 25 Dl -718 4792(512)N -5 Dt -675 4422 MXY -9 137 Dl -18 278 Dl -37 105 Dl -73 18 Dl -146 -1 Dl -292 0 Dl -584 -1 Dl -3 Dt -4946 MY -0 24 Dl -0 -12 Dl -12 0 Dl --24 0 Dl -1250 4946 MXY -0 25 Dl -0 -12 Dl -12 0 Dl --24 0 Dl -958 4947 MXY -0 24 Dl -0 -12 Dl -12 0 Dl --24 0 Dl -812 4948 MXY -0 24 Dl -0 -12 Dl -12 0 Dl --24 0 Dl -739 4930 MXY -0 24 Dl -0 -12 Dl -12 0 Dl --24 0 Dl -702 4824 MXY -0 25 Dl -0 -12 Dl -13 0 Dl --25 0 Dl -684 4547 MXY -0 24 Dl -0 -12 Dl -12 0 Dl --24 0 Dl -675 4410 MXY -0 25 Dl -0 -13 Dl -12 0 Dl --24 0 Dl -750 4921(256)N -20 Ds -1 Dt -675 4597 MXY -9 246 Dl -18 106 Dl -37 10 Dl -73 0 Dl -146 0 Dl -292 0 Dl -584 -1 Dl --1 Ds -3 Dt -1822 MX -23 Dc -1238 4959 MXY -23 Dc -946 MX -23 Dc -800 MX -23 Dc -727 MX -23 Dc -691 4949 MXY -23 Dc -672 4843 MXY -24 Dc -663 4597 MXY -24 Dc -1395 4961(128)N -1 Dt -675 4855 MXY -9 93 Dl -18 10 Dl -37 1 Dl -73 0 Dl -146 -1 Dl -292 0 Dl -584 0 Dl -3 Dt -4946 MY --12 24 Dl -24 0 Dl --12 -24 Dl -1250 MX --12 24 Dl -24 0 Dl --12 -24 Dl -958 MX --12 24 Dl -24 0 Dl --12 -24 Dl -812 MX --12 25 Dl -24 0 Dl --12 -25 Dl -739 4947 MXY --12 24 Dl -24 0 Dl --12 -24 Dl -702 4946 MXY --12 24 Dl -25 0 Dl --13 -24 Dl -684 4936 MXY --12 24 Dl -24 0 Dl --12 -24 Dl -675 4843 MXY --12 24 Dl -24 0 Dl --12 -24 Dl -3 Dt --1 Ds -3 f -432 5314(Figure)N -634(5b:)X -1 f -744(Elapsed)X -967(Time)X -1123(for)X -1218(dictionary)X -1498(data)X -1625(set)X -1717(with)X -1851(1M)X -1960(of)X -2033(buffer)X -432 5402(space)N -593(and)X -705(varying)X -920(bucket)X -1110(sizes)X -1254(and)X -1366(\256ll)X -1457(factors.)X -1681(Each)X -1827(line)X -1942(is)X -2004(labeled)X -432 5490(with)N -562(its)X -639(bucket)X -825(size.)X -10 s -2590 538(If)N -2677(an)X -2785(approximation)X -3284(of)X -3383(the)X -3513(number)X -3790(of)X -3889(elements)X -2418 626(ultimately)N -2773(to)X -2866(be)X -2973(stored)X -3200(in)X -3293(the)X -3422(hash)X -3599(table)X -3785(is)X -3868(known)X -4116(at)X -2418 714(the)N -2564(time)X -2754(of)X -2869(creation,)X -3196(the)X -3342(hash)X -3536(package)X -3847(takes)X -4059(this)X -2418 802(number)N -2688(as)X -2779(a)X -2839(parameter)X -3185(and)X -3325(uses)X -3487(it)X -3555(to)X -3641(hash)X -3812(entries)X -4050(into)X -2418 890(the)N -2541(full)X -2677(sized)X -2867(table)X -3048(rather)X -3261(than)X -3424(growing)X -3716(the)X -3838(table)X -4018(from)X -2418 978(a)N -2477(single)X -2691(bucket.)X -2968(If)X -3044(this)X -3181(number)X -3448(is)X -3523(not)X -3647(known,)X -3907(the)X -4027(hash)X -2418 1066(table)N -2632(starts)X -2859(with)X -3059(a)X -3153(single)X -3402(bucket)X -3674(and)X -3848(gracefully)X -2418 1154(expands)N -2707(as)X -2800(elements)X -3111(are)X -3236(added,)X -3474(although)X -3780(a)X -3842(slight)X -4044(per-)X -2418 1242(formance)N -2747(degradation)X -3151(may)X -3313(be)X -3413(noticed.)X -3713(Figure)X -3946(6)X -4010(illus-)X -2418 1330(trates)N -2625(the)X -2756(difference)X -3116(in)X -3211(performance)X -3651(between)X -3952(storing)X -2418 1418(keys)N -2588(in)X -2673(a)X -2732(\256le)X -2857(when)X -3054(the)X -3174(ultimate)X -3458(size)X -3605(is)X -3680(known)X -3920(\(the)X -4067(left)X -2418 1506(bars)N -2581(in)X -2672(each)X -2849(set\),)X -3014(compared)X -3360(to)X -3450(building)X -3744(the)X -3870(\256le)X -4000(when)X -2418 1594(the)N -2550(ultimate)X -2846(size)X -3005(is)X -3091(unknown)X -3422(\(the)X -3580(right)X -3764(bars)X -3931(in)X -4026(each)X -2418 1682(set\).)N -2609(Once)X -2814(the)X -2947(\256ll)X -3069(factor)X -3291(is)X -3378(suf\256ciently)X -3772(high)X -3948(for)X -4076(the)X -2418 1770(page)N -2596(size)X -2747(\(8\),)X -2887(growing)X -3180(the)X -3304(table)X -3486(dynamically)X -3908(does)X -4081(lit-)X -2418 1858(tle)N -2518(to)X -2600(degrade)X -2875(performance.)X -10 f -2418 1946 -0.0930(hhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhh)AN -9 s -1 f -2413 3238(s)N -2409 3173(d)N -2409 3108(n)N -2409 3043(o)N -2411 2979(c)N -2411 2914(e)N -2407 2849(S)N -3143 4129(Fill)N -3261(Factor)X -2448 2152(15)N -4 Ds -1 Dt -2557 2122 MXY -1473 0 Dl --1 Ds -5 Dt -2557 MX --19 0 Dl -2448 2747(10)N -4 Ds -1 Dt -2557 2717 MXY -1473 0 Dl --1 Ds -5 Dt -2557 MX --19 0 Dl -2484 3343(5)N -4 Ds -1 Dt -2557 3313 MXY -1473 0 Dl --1 Ds -5 Dt -2557 MX --19 0 Dl -2484 3938(0)N -4 Ds -1 Dt -2557 3908 MXY -1473 0 Dl --1 Ds -5 Dt -2557 MX --19 0 Dl -3976 4015(128)N -4 Ds -1 Dt -4030 3908 MXY -0 -1786 Dl --1 Ds -5 Dt -3908 MY -0 19 Dl -3626 4015(96)N -4 Ds -1 Dt -3662 3908 MXY -0 -1786 Dl --1 Ds -5 Dt -3908 MY -0 19 Dl -3258 4015(64)N -4 Ds -1 Dt -3294 3908 MXY -0 -1786 Dl --1 Ds -5 Dt -3908 MY -0 19 Dl -2889 4015(32)N -4 Ds -1 Dt -2925 3908 MXY -0 -1786 Dl --1 Ds -5 Dt -3908 MY -0 19 Dl -2539 4015(0)N -4 Ds -1 Dt -2557 3908 MXY -0 -1786 Dl --1 Ds -5 Dt -3908 MY -0 19 Dl -3908 MY -0 -1786 Dl -3908 MY -1473 0 Dl -4053 2378(8192)N -3 Dt -2569 2277 MXY -11 0 Dl -23 48 Dl -46 -167 Dl -92 35 Dl -184 12 Dl -369 143 Dl -736 0 Dl -2334 MY -0 28 Dl -0 -14 Dl -14 0 Dl --28 0 Dl -3294 2334 MXY -0 28 Dl -0 -14 Dl -13 0 Dl --27 0 Dl -2925 2192 MXY -0 27 Dl -0 -14 Dl -14 0 Dl --28 0 Dl -2741 2180 MXY -0 27 Dl -0 -14 Dl -14 0 Dl --28 0 Dl -2649 2144 MXY -0 28 Dl -0 -14 Dl -14 0 Dl --28 0 Dl -2603 2311 MXY -0 27 Dl -0 -13 Dl -14 0 Dl --28 0 Dl -2580 2263 MXY -0 28 Dl -0 -14 Dl -14 0 Dl --28 0 Dl -2569 2263 MXY -0 28 Dl -0 -14 Dl -13 0 Dl --27 0 Dl -4053 2591(4096)N -2569 2348 MXY -11 -11 Dl -23 -96 Dl -46 71 Dl -92 72 Dl -184 226 Dl -369 48 Dl -736 -60 Dl -2612 MY -14 -28 Dl --28 0 Dl -14 28 Dl -3294 2672 MXY -13 -28 Dl --27 0 Dl -14 28 Dl -2925 2624 MXY -14 -28 Dl --28 0 Dl -14 28 Dl -2741 2398 MXY -14 -28 Dl --28 0 Dl -14 28 Dl -2649 2326 MXY -14 -27 Dl --28 0 Dl -14 27 Dl -2603 2255 MXY -14 -28 Dl --28 0 Dl -14 28 Dl -2580 2350 MXY -14 -27 Dl --28 0 Dl -14 27 Dl -2569 2362 MXY -13 -28 Dl --27 0 Dl -14 28 Dl -4053 2681(1024)N -16 Ds -1 Dt -2569 2300 MXY -11 48 Dl -23 96 Dl -46 95 Dl -92 274 Dl -184 202 Dl -369 -155 Dl -736 -190 Dl --1 Ds -3 Dt -4044 2656 MXY --28 28 Dl -14 -14 Dl --14 -14 Dl -28 28 Dl -3307 2846 MXY --27 28 Dl -14 -14 Dl --14 -14 Dl -27 28 Dl -2939 3001 MXY --28 28 Dl -14 -14 Dl --14 -14 Dl -28 28 Dl -2755 2799 MXY --28 28 Dl -14 -14 Dl --14 -14 Dl -28 28 Dl -2663 2525 MXY --28 28 Dl -14 -14 Dl --14 -14 Dl -28 28 Dl -2617 2430 MXY --28 28 Dl -14 -14 Dl --14 -14 Dl -28 28 Dl -2594 2334 MXY --28 28 Dl -14 -14 Dl --14 -14 Dl -28 28 Dl -2582 2287 MXY --27 27 Dl -14 -14 Dl --14 -13 Dl -27 27 Dl -4053 2851(512)N -5 Dt -2569 2372 MXY -11 -24 Dl -23 405 Dl -46 83 Dl -92 227 Dl -184 -72 Dl -369 -119 Dl -736 -107 Dl -3 Dt -2751 MY -0 28 Dl -0 -14 Dl -14 0 Dl --28 0 Dl -3294 2858 MXY -0 28 Dl -0 -14 Dl -13 0 Dl --27 0 Dl -2925 2977 MXY -0 28 Dl -0 -14 Dl -14 0 Dl --28 0 Dl -2741 3049 MXY -0 27 Dl -0 -13 Dl -14 0 Dl --28 0 Dl -2649 2823 MXY -0 27 Dl -0 -14 Dl -14 0 Dl --28 0 Dl -2603 2739 MXY -0 28 Dl -0 -14 Dl -14 0 Dl --28 0 Dl -2580 2334 MXY -0 28 Dl -0 -14 Dl -14 0 Dl --28 0 Dl -2569 2358 MXY -0 28 Dl -0 -14 Dl -13 0 Dl --27 0 Dl -4053 2795(256)N -20 Ds -1 Dt -2569 2456 MXY -11 285 Dl -23 95 Dl -46 251 Dl -92 -60 Dl -184 -84 Dl -369 -107 Dl -736 -71 Dl --1 Ds -3 Dt -4016 MX -27 Dc -3280 2836 MXY -27 Dc -2912 2943 MXY -27 Dc -2728 3027 MXY -27 Dc -2635 3087 MXY -28 Dc -2589 2836 MXY -28 Dc -2566 2741 MXY -27 Dc -2554 2456 MXY -28 Dc -4053 2741(128)N -1 Dt -2569 2729 MXY -11 203 Dl -23 131 Dl -46 -60 Dl -92 -119 Dl -184 -60 Dl -369 -83 Dl -736 -12 Dl -3 Dt -2716 MY --14 27 Dl -28 0 Dl --14 -27 Dl -3294 2727 MXY --14 28 Dl -27 0 Dl --13 -28 Dl -2925 2811 MXY --14 27 Dl -28 0 Dl --14 -27 Dl -2741 2870 MXY --14 28 Dl -28 0 Dl --14 -28 Dl -2649 2989 MXY --14 28 Dl -28 0 Dl --14 -28 Dl -2603 3049 MXY --14 27 Dl -28 0 Dl --14 -27 Dl -2580 2918 MXY --14 28 Dl -28 0 Dl --14 -28 Dl -2569 2716 MXY --14 27 Dl -27 0 Dl --13 -27 Dl -3 Dt --1 Ds -3 f -8 s -2418 4286(Figure)N -2628(5c:)X -1 f -2738(User)X -2887(Time)X -3051(for)X -3154(dictionary)X -3442(data)X -3577(set)X -3677(with)X -3820(1M)X -3938(of)X -4019(buffer)X -2418 4374(space)N -2579(and)X -2691(varying)X -2906(bucket)X -3096(sizes)X -3240(and)X -3352(\256ll)X -3443(factors.)X -3667(Each)X -3813(line)X -3928(is)X -3990(labeled)X -2418 4462(with)N -2548(its)X -2625(bucket)X -2811(size.)X -10 s -10 f -2418 4638 -0.0930(hhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhh)AN -1 f -2590 4840(Since)N -2796(no)X -2904(known)X -3150(hash)X -3325(function)X -3620(performs)X -3938(equally)X -2418 4928(well)N -2589(on)X -2702(all)X -2815(possible)X -3110(data,)X -3297(the)X -3428(user)X -3595(may)X -3766(\256nd)X -3923(that)X -4076(the)X -2418 5016(built-in)N -2678(hash)X -2849(function)X -3140(does)X -3311(poorly)X -3544(on)X -3648(a)X -3708(particular)X -4040(data)X -2418 5104(set.)N -2548(In)X -2636(this)X -2771(case,)X -2950(a)X -3006(hash)X -3173(function,)X -3480(taking)X -3700(two)X -3840(arguments)X -2418 5192(\(a)N -2507(pointer)X -2760(to)X -2848(a)X -2910(byte)X -3074(string)X -3282(and)X -3424(a)X -3486(length\))X -3739(and)X -3880(returning)X -2418 5280(an)N -2517(unsigned)X -2829(long)X -2993(to)X -3077(be)X -3175(used)X -3344(as)X -3433(the)X -3553(hash)X -3722(value,)X -3938(may)X -4098(be)X -2418 5368(speci\256ed)N -2731(at)X -2817(hash)X -2992(table)X -3176(creation)X -3463(time.)X -3673(When)X -3893(an)X -3996(exist-)X -2418 5456(ing)N -2570(hash)X -2767(table)X -2973(is)X -3076(opened)X -3358(and)X -3524(a)X -3609(hash)X -3805(function)X -4121(is)X -2418 5544(speci\256ed,)N -2752(the)X -2879(hash)X -3054(package)X -3346(will)X -3498(try)X -3615(to)X -3705(determine)X -4054(that)X -2418 5632(the)N -2546(hash)X -2723(function)X -3020(supplied)X -3321(is)X -3404(the)X -3532(one)X -3678(with)X -3850(which)X -4076(the)X -2418 5720(table)N -2630(was)X -2811(created.)X -3139(There)X -3382(are)X -3536(a)X -3627(variety)X -3905(of)X -4027(hash)X -3 f -432 5960(8)N -2970(USENIX)X -9 f -3292(-)X -3 f -3356(Winter)X -3621('91)X -9 f -3748(-)X -3 f -3812(Dallas,)X -4065(TX)X - -9 p -%%Page: 9 9 -0(Courier)xf 0 f -10 s 10 xH 0 xS 0 f -3 f -720 258(Seltzer)N -977(&)X -1064(Yigit)X -3278(A)X -3356(New)X -3528(Hashing)X -3831(Package)X -4136(for)X -4259(UNIX)X -1 f -720 538(functions)N -1065(provided)X -1397(with)X -1586(the)X -1731(package.)X -2082(The)X -2253(default)X -720 626(function)N -1014(for)X -1135(the)X -1260(package)X -1551(is)X -1631(the)X -1755(one)X -1897(which)X -2119(offered)X -2378(the)X -720 714(best)N -875(performance)X -1308(in)X -1396(terms)X -1600(of)X -1693(cycles)X -1920(executed)X -2232(per)X -2360(call)X -720 802(\(it)N -827(did)X -965(not)X -1103(produce)X -1398(the)X -1531(fewest)X -1776(collisions)X -2117(although)X -2432(it)X -720 890(was)N -866(within)X -1091(a)X -1148(small)X -1341(percentage)X -1710(of)X -1797(the)X -1915(function)X -2202(that)X -2342(pro-)X -720 978(duced)N -947(the)X -1080(fewest)X -1324(collisions\).)X -1731(Again,)X -1981(in)X -2077(time)X -2253(critical)X -720 1066(applications,)N -1152(users)X -1342(are)X -1466(encouraged)X -1862(to)X -1949(experiment)X -2334(with)X -720 1154(a)N -783(variety)X -1032(of)X -1125(hash)X -1298(functions)X -1622(to)X -1710(achieve)X -1982(optimal)X -2252(perfor-)X -720 1242(mance.)N -10 f -720 1330 -0.0930(hhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhh)AN -3 f -7 s -1038 2925(Full)N -1149(size)X -1251(table)X -1384(\(left\))X -1547 2718(Fill)N -1643(Factor)X -2268 2662(64)N -1964(32)X -1674(16)X -1384(8)X -1093(4)X -4 Ds -1 Dt -900 2280 MXY -1548 0 Dl -900 1879 MXY -1548 0 Dl -900 1506 MXY -1548 0 Dl -1563 2902 MXY -111 0 Dl --1 Ds -900 MX -110 0 Dl -1425 2828(System)N -983(User)X -1895 2778 MXY - 1895 2778 lineto - 1950 2778 lineto - 1950 2833 lineto - 1895 2833 lineto - 1895 2778 lineto -closepath 21 1895 2778 1950 2833 Dp -1342 MX - 1342 2778 lineto - 1397 2778 lineto - 1397 2833 lineto - 1342 2833 lineto - 1342 2778 lineto -closepath 14 1342 2778 1397 2833 Dp -900 MX - 900 2778 lineto - 955 2778 lineto - 955 2833 lineto - 900 2833 lineto - 900 2778 lineto -closepath 3 900 2778 955 2833 Dp -5 Dt -2283 2211 MXY -96 0 Dl -1992 MX -97 0 Dl -1702 MX -97 0 Dl -1411 2252 MXY -97 0 Dl -4 Ds -1 Dt -2283 2211 MXY - 2283 2211 lineto - 2379 2211 lineto - 2379 2252 lineto - 2283 2252 lineto - 2283 2211 lineto -closepath 14 2283 2211 2379 2252 Dp -1992 MX - 1992 2211 lineto - 2089 2211 lineto - 2089 2252 lineto - 1992 2252 lineto - 1992 2211 lineto -closepath 14 1992 2211 2089 2252 Dp -1702 MX - 1702 2211 lineto - 1799 2211 lineto - 1799 2252 lineto - 1702 2252 lineto - 1702 2211 lineto -closepath 14 1702 2211 1799 2252 Dp -1411 2252 MXY - 1411 2252 lineto - 1508 2252 lineto - 1508 2294 lineto - 1411 2294 lineto - 1411 2252 lineto -closepath 14 1411 2252 1508 2294 Dp -2283 MX - 2283 2252 lineto - 2379 2252 lineto - 2379 2612 lineto - 2283 2612 lineto - 2283 2252 lineto -closepath 3 2283 2252 2379 2612 Dp -1992 MX - 1992 2252 lineto - 2089 2252 lineto - 2089 2612 lineto - 1992 2612 lineto - 1992 2252 lineto -closepath 3 1992 2252 2089 2612 Dp -1702 MX - 1702 2252 lineto - 1799 2252 lineto - 1799 2612 lineto - 1702 2612 lineto - 1702 2252 lineto -closepath 3 1702 2252 1799 2612 Dp -1411 2294 MXY - 1411 2294 lineto - 1508 2294 lineto - 1508 2612 lineto - 1411 2612 lineto - 1411 2294 lineto -closepath 3 1411 2294 1508 2612 Dp --1 Ds -2158 2238 MXY - 2158 2238 lineto - 2255 2238 lineto - 2255 2252 lineto - 2158 2252 lineto - 2158 2238 lineto -closepath 21 2158 2238 2255 2252 Dp -1868 MX - 1868 2238 lineto - 1965 2238 lineto - 1965 2280 lineto - 1868 2280 lineto - 1868 2238 lineto -closepath 21 1868 2238 1965 2280 Dp -1577 MX - 1577 2238 lineto - 1674 2238 lineto - 1674 2308 lineto - 1577 2308 lineto - 1577 2238 lineto -closepath 21 1577 2238 1674 2308 Dp -1287 2308 MXY - 1287 2308 lineto - 1287 2280 lineto - 1384 2280 lineto - 1384 2308 lineto - 1287 2308 lineto -closepath 21 1287 2280 1384 2308 Dp -2158 2280 MXY - 2158 2280 lineto - 2158 2252 lineto - 2255 2252 lineto - 2255 2280 lineto - 2158 2280 lineto -closepath 14 2158 2252 2255 2280 Dp -1868 2308 MXY - 1868 2308 lineto - 1868 2280 lineto - 1965 2280 lineto - 1965 2308 lineto - 1868 2308 lineto -closepath 14 1868 2280 1965 2308 Dp -1577 2335 MXY - 1577 2335 lineto - 1577 2308 lineto - 1674 2308 lineto - 1674 2335 lineto - 1577 2335 lineto -closepath 14 1577 2308 1674 2335 Dp -1287 2363 MXY - 1287 2363 lineto - 1287 2308 lineto - 1384 2308 lineto - 1384 2363 lineto - 1287 2363 lineto -closepath 14 1287 2308 1384 2363 Dp -2158 2280 MXY - 2158 2280 lineto - 2255 2280 lineto - 2255 2612 lineto - 2158 2612 lineto - 2158 2280 lineto -closepath 3 2158 2280 2255 2612 Dp -1868 2308 MXY - 1868 2308 lineto - 1965 2308 lineto - 1965 2612 lineto - 1868 2612 lineto - 1868 2308 lineto -closepath 3 1868 2308 1965 2612 Dp -1577 2335 MXY - 1577 2335 lineto - 1674 2335 lineto - 1674 2612 lineto - 1577 2612 lineto - 1577 2335 lineto -closepath 3 1577 2335 1674 2612 Dp -1287 2363 MXY - 1287 2363 lineto - 1384 2363 lineto - 1384 2612 lineto - 1287 2612 lineto - 1287 2363 lineto -closepath 3 1287 2363 1384 2612 Dp -4 Ds -1121 2066 MXY - 1121 2066 lineto - 1218 2066 lineto - 1224 2080 lineto - 1127 2080 lineto - 1121 2066 lineto -closepath 21 1121 2066 1224 2080 Dp -2080 MY - 1121 2080 lineto - 1218 2080 lineto - 1218 2273 lineto - 1121 2273 lineto - 1121 2080 lineto -closepath 14 1121 2080 1218 2273 Dp -2273 MY - 1121 2273 lineto - 1218 2273 lineto - 1218 2612 lineto - 1121 2612 lineto - 1121 2273 lineto -closepath 3 1121 2273 1218 2612 Dp --1 Ds -997 1589 MXY - 997 1589 lineto - 1093 1589 lineto - 1093 1644 lineto - 997 1644 lineto - 997 1589 lineto -closepath 21 997 1589 1093 1644 Dp -1644 MY - 997 1644 lineto - 1093 1644 lineto - 1093 2280 lineto - 997 2280 lineto - 997 1644 lineto -closepath 14 997 1644 1093 2280 Dp -2280 MY - 997 2280 lineto - 1093 2280 lineto - 1093 2612 lineto - 997 2612 lineto - 997 2280 lineto -closepath 3 997 2280 1093 2612 Dp -10 s -719 2093(s)N -712 2037(d)N -712 1982(n)N -714 1927(o)N -716 1872(c)N -716 1816(e)N -712 1761(S)N -804 2286(10)N -804 1899(20)N -804 1540(30)N -3 Dt -900 1506 MXY -0 1106 Dl -1548 0 Dl -7 s -1978 2828(Elapsed)N -1701 2925(Dynamically)N -2018(grown)X -2184(table)X -2317(\(right\))X -3 Dt --1 Ds -8 s -720 3180(Figure)N -934(6:)X -1 f -1020(The)X -1152(total)X -1299(regions)X -1520(indicate)X -1755(the)X -1865(difference)X -2154(between)X -2398(the)X -720 3268(elapsed)N -931(time)X -1065(and)X -1177(the)X -1275(sum)X -1402(of)X -1475(the)X -1573(system)X -1771(and)X -1883(user)X -2008(time.)X -2173(The)X -2291(left)X -2395(bar)X -720 3356(of)N -798(each)X -939(set)X -1035(depicts)X -1241(the)X -1344(timing)X -1537(of)X -1615(the)X -1718(test)X -1831(run)X -1940(when)X -2102(the)X -2204(number)X -2423(of)X -720 3444(entries)N -910(is)X -973(known)X -1167(in)X -1237(advance.)X -1496(The)X -1614(right)X -1754(bars)X -1879(depict)X -2054(the)X -2151(timing)X -2338(when)X -720 3532(the)N -814(\256le)X -912(is)X -971(grown)X -1150(from)X -1290(a)X -1334(single)X -1503(bucket.)X -10 s -10 f -720 3708 -0.0930(hhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhh)AN -1 f -892 3910(Since)N -1131(this)X -1307(hashing)X -1617(package)X -1942(provides)X -2279(buffer)X -720 3998(management,)N -1188(the)X -1323(amount)X -1600(of)X -1704(space)X -1920(allocated)X -2247(for)X -2378(the)X -720 4086(buffer)N -948(pool)X -1121(may)X -1290(be)X -1397(speci\256ed)X -1713(by)X -1824(the)X -1953(user.)X -2157(Using)X -2378(the)X -720 4174(same)N -910(data)X -1069(set)X -1183(and)X -1324(test)X -1459(procedure)X -1805(as)X -1896(used)X -2067(to)X -2153(derive)X -2378(the)X -720 4262(graphs)N -962(in)X -1052(Figures)X -1320(5a-c,)X -1507(Figure)X -1744(7)X -1812(shows)X -2039(the)X -2164(impact)X -2409(of)X -720 4350(varying)N -997(the)X -1126(size)X -1282(of)X -1380(the)X -1509(buffer)X -1737(pool.)X -1950(The)X -2106(bucket)X -2351(size)X -720 4438(was)N -873(set)X -989(to)X -1078(256)X -1225(bytes)X -1421(and)X -1564(the)X -1689(\256ll)X -1804(factor)X -2019(was)X -2171(set)X -2287(to)X -2376(16.)X -720 4526(The)N -869(buffer)X -1090(pool)X -1256(size)X -1404(was)X -1552(varied)X -1776(from)X -1955(0)X -2018(\(the)X -2166(minimum)X -720 4614(number)N -986(of)X -1074(pages)X -1277(required)X -1565(to)X -1647(be)X -1743(buffered\))X -2063(to)X -2145(1M.)X -2316(With)X -720 4702(1M)N -854(of)X -944(buffer)X -1164(space,)X -1386(the)X -1507(package)X -1794(performed)X -2151(no)X -2253(I/O)X -2382(for)X -720 4790(this)N -871(data)X -1040(set.)X -1204(As)X -1328(Figure)X -1572(7)X -1647(illustrates,)X -2013(increasing)X -2378(the)X -720 4878(buffer)N -944(pool)X -1113(size)X -1265(can)X -1404(have)X -1583(a)X -1646(dramatic)X -1954(affect)X -2165(on)X -2271(result-)X -720 4966(ing)N -842(performance.)X -2 f -8 s -1269 4941(7)N -1 f -16 s -720 5353 MXY -864 0 Dl -2 f -8 s -760 5408(7)N -1 f -9 s -826 5433(Some)N -1024(allocators)X -1338(are)X -1460(extremely)X -1782(inef\256cient)X -2107(at)X -2192(allocating)X -720 5513(memory.)N -1029(If)X -1110(you)X -1251(\256nd)X -1396(that)X -1536(applications)X -1916(are)X -2036(running)X -2292(out)X -2416(of)X -720 5593(memory)N -1005(before)X -1234(you)X -1386(think)X -1578(they)X -1746(should,)X -2000(try)X -2124(varying)X -2388(the)X -720 5673(pagesize)N -986(to)X -1060(get)X -1166(better)X -1348(utilization)X -1658(from)X -1816(the)X -1922(memory)X -2180(allocator.)X -10 s -2830 1975 MXY -0 -28 Dl -28 0 Dl -0 28 Dl --28 0 Dl -2853 2004 MXY -0 -27 Dl -28 0 Dl -0 27 Dl --28 0 Dl -2876 2016 MXY -0 -27 Dl -27 0 Dl -0 27 Dl --27 0 Dl -2922 1998 MXY -0 -27 Dl -27 0 Dl -0 27 Dl --27 0 Dl -2967 2025 MXY -0 -28 Dl -28 0 Dl -0 28 Dl --28 0 Dl -3013 2031 MXY -0 -28 Dl -28 0 Dl -0 28 Dl --28 0 Dl -3059 MX -0 -28 Dl -27 0 Dl -0 28 Dl --27 0 Dl -3196 2052 MXY -0 -28 Dl -27 0 Dl -0 28 Dl --27 0 Dl -3561 2102 MXY -0 -28 Dl -28 0 Dl -0 28 Dl --28 0 Dl -4292 2105 MXY -0 -28 Dl -27 0 Dl -0 28 Dl --27 0 Dl -4 Ds -1 Dt -2844 1961 MXY -23 30 Dl -23 12 Dl -45 -18 Dl -46 26 Dl -46 6 Dl -45 0 Dl -137 21 Dl -366 50 Dl -730 3 Dl -9 s -4227 2158(User)N --1 Ds -3 Dt -2830 1211 MXY -27 Dc -2853 1261 MXY -27 Dc -2876 1267 MXY -27 Dc -2921 1341 MXY -27 Dc -2967 1385 MXY -27 Dc -3013 1450 MXY -27 Dc -3059 1497 MXY -27 Dc -3196 1686 MXY -27 Dc -3561 2109 MXY -27 Dc -4292 2295 MXY -27 Dc -20 Ds -1 Dt -2844 1211 MXY -23 50 Dl -23 6 Dl -45 74 Dl -46 44 Dl -46 65 Dl -45 47 Dl -137 189 Dl -366 423 Dl -730 186 Dl -4181 2270(System)N --1 Ds -3 Dt -2844 583 MXY -0 28 Dl -0 -14 Dl -14 0 Dl --28 0 Dl -2867 672 MXY -0 27 Dl -0 -14 Dl -14 0 Dl --28 0 Dl -2890 701 MXY -0 28 Dl -0 -14 Dl -13 0 Dl --27 0 Dl -2935 819 MXY -0 28 Dl -0 -14 Dl -14 0 Dl --27 0 Dl -2981 849 MXY -0 28 Dl -0 -14 Dl -14 0 Dl --28 0 Dl -3027 908 MXY -0 27 Dl -0 -13 Dl -14 0 Dl --28 0 Dl -3072 1026 MXY -0 27 Dl -0 -13 Dl -14 0 Dl --27 0 Dl -3209 1292 MXY -0 27 Dl -0 -14 Dl -14 0 Dl --27 0 Dl -3575 1823 MXY -0 28 Dl -0 -14 Dl -14 0 Dl --28 0 Dl -4305 2059 MXY -0 28 Dl -0 -14 Dl -14 0 Dl --27 0 Dl -5 Dt -2844 597 MXY -23 88 Dl -23 30 Dl -45 118 Dl -46 30 Dl -46 59 Dl -45 118 Dl -137 265 Dl -366 532 Dl -730 236 Dl -4328 2103(Total)N -2844 2310 MXY -1461 0 Dl -2844 MX -0 -1772 Dl -2310 MY -0 18 Dl -4 Ds -1 Dt -2310 MY -0 -1772 Dl -2826 2416(0)N --1 Ds -5 Dt -3209 2310 MXY -0 18 Dl -4 Ds -1 Dt -2310 MY -0 -1772 Dl -3155 2416(256)N --1 Ds -5 Dt -3575 2310 MXY -0 18 Dl -4 Ds -1 Dt -2310 MY -0 -1772 Dl -3521 2416(512)N --1 Ds -5 Dt -3940 2310 MXY -0 18 Dl -4 Ds -1 Dt -2310 MY -0 -1772 Dl -3886 2416(768)N --1 Ds -5 Dt -4305 2310 MXY -0 18 Dl -4 Ds -1 Dt -2310 MY -0 -1772 Dl -4233 2416(1024)N --1 Ds -5 Dt -2844 2310 MXY --18 0 Dl -4 Ds -1 Dt -2844 MX -1461 0 Dl -2771 2340(0)N --1 Ds -5 Dt -2844 2014 MXY --18 0 Dl -2844 1719 MXY --18 0 Dl -4 Ds -1 Dt -2844 MX -1461 0 Dl -2735 1749(20)N --1 Ds -5 Dt -2844 1423 MXY --18 0 Dl -2844 1128 MXY --18 0 Dl -4 Ds -1 Dt -2844 MX -1461 0 Dl -2735 1158(40)N --1 Ds -5 Dt -2844 833 MXY --18 0 Dl -2844 538 MXY --18 0 Dl -4 Ds -1 Dt -2844 MX -1461 0 Dl -2735 568(60)N -3239 2529(Buffer)N -3445(Pool)X -3595(Size)X -3737(\(in)X -3835(K\))X -2695 1259(S)N -2699 1324(e)N -2699 1388(c)N -2697 1452(o)N -2697 1517(n)N -2697 1581(d)N -2701 1645(s)N -3 Dt --1 Ds -3 f -8 s -2706 2773(Figure)N -2908(7:)X -1 f -2982(User)X -3123(time)X -3258(is)X -3322(virtually)X -3560(insensitive)X -3854(to)X -3924(the)X -4022(amount)X -4234(of)X -4307(buffer)X -2706 2861(pool)N -2852(available,)X -3130(however,)X -3396(both)X -3541(system)X -3750(time)X -3895(and)X -4018(elapsed)X -4240(time)X -4385(are)X -2706 2949(inversely)N -2960(proportional)X -3296(to)X -3366(the)X -3464(size)X -3583(of)X -3656(the)X -3753(buffer)X -3927(pool.)X -4092(Even)X -4242(for)X -4335(large)X -2706 3037(data)N -2831(sets)X -2946(where)X -3120(one)X -3230(expects)X -3439(few)X -3552(collisions,)X -3832(specifying)X -4116(a)X -4162(large)X -4307(buffer)X -2706 3125(pool)N -2836(dramatically)X -3171(improves)X -3425(performance.)X -10 s -10 f -2706 3301 -0.0930(hhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhh)AN -3 f -3175 3543(Enhanced)N -3536(Functionality)X -1 f -2878 3675(This)N -3046(hashing)X -3320(package)X -3609(provides)X -3910(a)X -3971(set)X -4085(of)X -4177(compati-)X -2706 3763(bility)N -2895(routines)X -3174(to)X -3257(implement)X -3620(the)X -2 f -3739(ndbm)X -1 f -3937(interface.)X -4279(How-)X -2706 3851(ever,)N -2893(when)X -3095(the)X -3220(native)X -3443(interface)X -3752(is)X -3832(used,)X -4026(the)X -4151(following)X -2706 3939(additional)N -3046(functionality)X -3475(is)X -3548(provided:)X -10 f -2798 4071(g)N -1 f -2946(Inserts)X -3197(never)X -3413(fail)X -3556(because)X -3847(too)X -3985(many)X -4199(keys)X -2946 4159(hash)N -3113(to)X -3195(the)X -3313(same)X -3498(value.)X -10 f -2798 4247(g)N -1 f -2946(Inserts)X -3187(never)X -3393(fail)X -3527(because)X -3808(key)X -3950(and/or)X -4181(asso-)X -2946 4335(ciated)N -3158(data)X -3312(is)X -3385(too)X -3507(large)X -10 f -2798 4423(g)N -1 f -2946(Hash)X -3131(functions)X -3449(may)X -3607(be)X -3703(user-speci\256ed.)X -10 f -2798 4511(g)N -1 f -2946(Multiple)X -3268(pages)X -3498(may)X -3683(be)X -3806(cached)X -4077(in)X -4186(main)X -2946 4599(memory.)N -2706 4731(It)N -2801(also)X -2976(provides)X -3298(a)X -3380(set)X -3514(of)X -3626(compatibility)X -4097(routines)X -4400(to)X -2706 4819(implement)N -3087(the)X -2 f -3224(hsearch)X -1 f -3516(interface.)X -3876(Again,)X -4130(the)X -4266(native)X -2706 4907(interface)N -3008(offers)X -3216(enhanced)X -3540(functionality:)X -10 f -2798 5039(g)N -1 f -2946(Files)X -3121(may)X -3279(grow)X -3464(beyond)X -2 f -3720(nelem)X -1 f -3932(elements.)X -10 f -2798 5127(g)N -1 f -2946(Multiple)X -3247(hash)X -3420(tables)X -3632(may)X -3795(be)X -3896(accessed)X -4203(con-)X -2946 5215(currently.)N -10 f -2798 5303(g)N -1 f -2946(Hash)X -3134(tables)X -3344(may)X -3505(be)X -3604(stored)X -3823(and)X -3962(accessed)X -4266(on)X -2946 5391(disk.)N -10 f -2798 5479(g)N -1 f -2946(Hash)X -3155(functions)X -3497(may)X -3679(be)X -3799(user-speci\256ed)X -4288(at)X -2946 5567(runtime.)N -3 f -720 5960(USENIX)N -9 f -1042(-)X -3 f -1106(Winter)X -1371('91)X -9 f -1498(-)X -3 f -1562(Dallas,)X -1815(TX)X -4424(9)X - -10 p -%%Page: 10 10 -0(Courier)xf 0 f -10 s 10 xH 0 xS 0 f -3 f -432 258(A)N -510(New)X -682(Hashing)X -985(Package)X -1290(for)X -1413(UNIX)X -3663(Seltzer)X -3920(&)X -4007(Yigit)X -459 538(Relative)N -760(Performance)X -1227(of)X -1314(the)X -1441(New)X -1613(Implementation)X -1 f -604 670(The)N -761(performance)X -1200(testing)X -1445(of)X -1544(the)X -1674(new)X -1840(package)X -2135(is)X -432 758(divided)N -711(into)X -874(two)X -1033(test)X -1183(suites.)X -1424(The)X -1588(\256rst)X -1751(suite)X -1941(of)X -2046(tests)X -432 846(requires)N -727(that)X -882(the)X -1015(tables)X -1237(be)X -1348(read)X -1522(from)X -1713(and)X -1864(written)X -2126(to)X -432 934(disk.)N -640(In)X -742(these)X -942(tests,)X -1139(the)X -1272(basis)X -1467(for)X -1595(comparison)X -2003(is)X -2090(the)X -432 1022(4.3BSD-Reno)N -908(version)X -1169(of)X -2 f -1260(ndbm)X -1 f -1438(.)X -1502(Based)X -1722(on)X -1826(the)X -1948(designs)X -432 1110(of)N -2 f -521(sdbm)X -1 f -712(and)X -2 f -850(gdbm)X -1 f -1028(,)X -1070(they)X -1230(are)X -1351(expected)X -1659(to)X -1743(perform)X -2024(simi-)X -432 1198(larly)N -605(to)X -2 f -693(ndbm)X -1 f -871(,)X -917(and)X -1059(we)X -1179(do)X -1285(not)X -1413(show)X -1608(their)X -1781(performance)X -432 1286(numbers.)N -800(The)X -977(second)X -1252(suite)X -1454(contains)X -1772(the)X -1921(memory)X -432 1374(resident)N -712(test)X -849(which)X -1071(does)X -1243(not)X -1370(require)X -1623(that)X -1768(the)X -1891(\256les)X -2049(ever)X -432 1462(be)N -533(written)X -784(to)X -870(disk,)X -1047(only)X -1213(that)X -1357(hash)X -1528(tables)X -1739(may)X -1901(be)X -2001(mani-)X -432 1550(pulated)N -692(in)X -778(main)X -961(memory.)X -1291(In)X -1381(this)X -1519(test,)X -1673(we)X -1790(compare)X -2090(the)X -432 1638(performance)N -859(to)X -941(that)X -1081(of)X -1168(the)X -2 f -1286(hsearch)X -1 f -1560(routines.)X -604 1752(For)N -760(both)X -947(suites,)X -1194(two)X -1358(different)X -1679(databases)X -2031(were)X -432 1840(used.)N -656(The)X -818(\256rst)X -979(is)X -1069(the)X -1204(dictionary)X -1566(database)X -1880(described)X -432 1928(previously.)N -836(The)X -987(second)X -1236(was)X -1386(constructed)X -1781(from)X -1962(a)X -2023(pass-)X -432 2016(word)N -647(\256le)X -799(with)X -990(approximately)X -1502(300)X -1671(accounts.)X -2041(Two)X -432 2104(records)N -700(were)X -887(constructed)X -1287(for)X -1411(each)X -1589(account.)X -1909(The)X -2064(\256rst)X -432 2192(used)N -604(the)X -727(logname)X -1028(as)X -1120(the)X -1243(key)X -1384(and)X -1525(the)X -1648(remainder)X -1999(of)X -2090(the)X -432 2280(password)N -768(entry)X -965(for)X -1091(the)X -1221(data.)X -1427(The)X -1584(second)X -1839(was)X -1996(keyed)X -432 2368(by)N -541(uid)X -672(and)X -817(contained)X -1157(the)X -1283(entire)X -1494(password)X -1825(entry)X -2018(as)X -2113(its)X -432 2456(data)N -589(\256eld.)X -794(The)X -942(tests)X -1107(were)X -1287(all)X -1389(run)X -1518(on)X -1620(the)X -1740(HP)X -1864(9000)X -2046(with)X -432 2544(the)N -574(same)X -783(con\256guration)X -1254(previously)X -1636(described.)X -2027(Each)X -432 2632(test)N -576(was)X -734(run)X -874(\256ve)X -1027(times)X -1232(and)X -1380(the)X -1510(timing)X -1750(results)X -1991(of)X -2090(the)X -432 2720(runs)N -602(were)X -791(averaged.)X -1154(The)X -1311(variance)X -1616(across)X -1849(the)X -1979(5)X -2050(runs)X -432 2808(was)N -591(approximately)X -1088(1%)X -1229(of)X -1330(the)X -1462(average)X -1746(yielding)X -2041(95%)X -432 2896(con\256dence)N -800(intervals)X -1096(of)X -1183(approximately)X -1666(2%.)X -3 f -1021 3050(Disk)N -1196(Based)X -1420(Tests)X -1 f -604 3182(In)N -693(these)X -880(tests,)X -1064(we)X -1180(use)X -1308(a)X -1365(bucket)X -1600(size)X -1746(of)X -1834(1024)X -2015(and)X -2152(a)X -432 3270(\256ll)N -540(factor)X -748(of)X -835(32.)X -3 f -432 3384(create)N -663(test)X -1 f -547 3498(The)N -703(keys)X -881(are)X -1011(entered)X -1279(into)X -1433(the)X -1561(hash)X -1738(table,)X -1944(and)X -2090(the)X -547 3586(\256le)N -669(is)X -742(\257ushed)X -993(to)X -1075(disk.)X -3 f -432 3700(read)N -608(test)X -1 f -547 3814(A)N -640(lookup)X -897(is)X -984(performed)X -1353(for)X -1481(each)X -1663(key)X -1813(in)X -1909(the)X -2041(hash)X -547 3902(table.)N -3 f -432 4016(verify)N -653(test)X -1 f -547 4130(A)N -640(lookup)X -897(is)X -984(performed)X -1353(for)X -1481(each)X -1663(key)X -1813(in)X -1909(the)X -2041(hash)X -547 4218(table,)N -759(and)X -911(the)X -1045(data)X -1215(returned)X -1519(is)X -1608(compared)X -1961(against)X -547 4306(that)N -687(originally)X -1018(stored)X -1234(in)X -1316(the)X -1434(hash)X -1601(table.)X -3 f -432 4420(sequential)N -798(retrieve)X -1 f -547 4534(All)N -674(keys)X -846(are)X -970(retrieved)X -1281(in)X -1367(sequential)X -1716(order)X -1910(from)X -2090(the)X -547 4622(hash)N -724(table.)X -950(The)X -2 f -1105(ndbm)X -1 f -1313(interface)X -1625(allows)X -1863(sequential)X -547 4710(retrieval)N -848(of)X -948(the)X -1079(keys)X -1259(from)X -1448(the)X -1578(database,)X -1907(but)X -2041(does)X -547 4798(not)N -701(return)X -945(the)X -1094(data)X -1279(associated)X -1660(with)X -1853(each)X -2052(key.)X -547 4886(Therefore,)N -929(we)X -1067(compare)X -1388(the)X -1530(performance)X -1980(of)X -2090(the)X -547 4974(new)N -703(package)X -989(to)X -1073(two)X -1215(different)X -1514(runs)X -1674(of)X -2 f -1763(ndbm)X -1 f -1941(.)X -2002(In)X -2090(the)X -547 5062(\256rst)N -697(case,)X -2 f -882(ndbm)X -1 f -1086(returns)X -1335(only)X -1503(the)X -1627(keys)X -1800(while)X -2003(in)X -2090(the)X -547 5150(second,)N -2 f -823(ndbm)X -1 f -1034(returns)X -1290(both)X -1465(the)X -1596(keys)X -1776(and)X -1924(the)X -2054(data)X -547 5238(\(requiring)N -894(a)X -956(second)X -1204(call)X -1345(to)X -1432(the)X -1555(library\).)X -1861(There)X -2074(is)X -2152(a)X -547 5326(single)N -764(run)X -897(for)X -1017(the)X -1141(new)X -1300(library)X -1539(since)X -1729(it)X -1798(returns)X -2046(both)X -547 5414(the)N -665(key)X -801(and)X -937(the)X -1055(data.)X -3 f -3014 538(In-Memory)N -3431(Test)X -1 f -2590 670(This)N -2757(test)X -2892(uses)X -3054(a)X -3114(bucket)X -3352(size)X -3501(of)X -3592(256)X -3736(and)X -3876(a)X -3936(\256ll)X -4048(fac-)X -2418 758(tor)N -2527(of)X -2614(8.)X -3 f -2418 872(create/read)N -2827(test)X -1 f -2533 986(In)N -2627(this)X -2769(test,)X -2927(a)X -2989(hash)X -3162(table)X -3344(is)X -3423(created)X -3682(by)X -3788(inserting)X -4094(all)X -2533 1074(the)N -2660(key/data)X -2961(pairs.)X -3186(Then)X -3380(a)X -3445(keyed)X -3666(retrieval)X -3963(is)X -4044(per-)X -2533 1162(formed)N -2801(for)X -2931(each)X -3115(pair,)X -3295(and)X -3446(the)X -3579(hash)X -3761(table)X -3952(is)X -4040(des-)X -2533 1250(troyed.)N -3 f -2938 1404(Performance)N -3405(Results)X -1 f -2590 1536(Figures)N -2866(8a)X -2978(and)X -3130(8b)X -3246(show)X -3451(the)X -3585(user)X -3755(time,)X -3952(system)X -2418 1624(time,)N -2608(and)X -2752(elapsed)X -3021(time)X -3191(for)X -3312(each)X -3487(test)X -3625(for)X -3746(both)X -3915(the)X -4040(new)X -2418 1712(implementation)N -2951(and)X -3098(the)X -3227(old)X -3360(implementation)X -3893(\()X -2 f -3920(hsearch)X -1 f -2418 1800(or)N -2 f -2528(ndbm)X -1 f -2706(,)X -2769(whichever)X -3147(is)X -3243(appropriate\))X -3678(as)X -3787(well)X -3967(as)X -4076(the)X -2418 1888(improvement.)N -2929(The)X -3098(improvement)X -3569(is)X -3666(expressed)X -4027(as)X -4138(a)X -2418 1976(percentage)N -2787(of)X -2874(the)X -2992(old)X -3114(running)X -3383(time:)X -0 f -8 s -2418 2275(%)N -2494(=)X -2570(100)X -2722(*)X -2798 -0.4219(\(old_time)AX -3178(-)X -3254 -0.4219(new_time\))AX -3634(/)X -3710(old_time)X -1 f -10 s -2590 2600(In)N -2700(nearly)X -2944(all)X -3067(cases,)X -3299(the)X -3439(new)X -3615(routines)X -3915(perform)X -2418 2688(better)N -2628(than)X -2793(the)X -2918(old)X -3047(routines)X -3332(\(both)X -2 f -3527(hsearch)X -1 f -3807(and)X -2 f -3949(ndbm)X -1 f -4127(\).)X -2418 2776(Although)N -2755(the)X -3 f -2888(create)X -1 f -3134(tests)X -3311(exhibit)X -3567(superior)X -3864(user)X -4032(time)X -2418 2864(performance,)N -2869(the)X -2991(test)X -3126(time)X -3292(is)X -3369(dominated)X -3731(by)X -3834(the)X -3955(cost)X -4107(of)X -2418 2952(writing)N -2677(the)X -2803(actual)X -3023(\256le)X -3153(to)X -3243(disk.)X -3444(For)X -3583(the)X -3709(large)X -3897(database)X -2418 3040(\(the)N -2564(dictionary\),)X -2957(this)X -3093(completely)X -3470(overwhelmed)X -3927(the)X -4045(sys-)X -2418 3128(tem)N -2570(time.)X -2783(However,)X -3129(for)X -3254(the)X -3383(small)X -3587(data)X -3752(base,)X -3946(we)X -4071(see)X -2418 3216(that)N -2569(differences)X -2958(in)X -3051(both)X -3224(user)X -3389(and)X -3536(system)X -3788(time)X -3960(contri-)X -2418 3304(bute)N -2576(to)X -2658(the)X -2776(superior)X -3059(performance)X -3486(of)X -3573(the)X -3691(new)X -3845(package.)X -2590 3418(The)N -3 f -2764(read)X -1 f -2920(,)X -3 f -2989(verify)X -1 f -3190(,)X -3259(and)X -3 f -3424(sequential)X -1 f -3818(results)X -4075(are)X -2418 3506(deceptive)N -2758(for)X -2883(the)X -3012(small)X -3216(database)X -3524(since)X -3720(the)X -3849(entire)X -4063(test)X -2418 3594(ran)N -2551(in)X -2643(under)X -2856(a)X -2922(second.)X -3215(However,)X -3560(on)X -3669(the)X -3796(larger)X -4013(data-)X -2418 3682(base)N -2590(the)X -3 f -2716(read)X -1 f -2900(and)X -3 f -3044(verify)X -1 f -3273(tests)X -3443(bene\256t)X -3689(from)X -3873(the)X -3999(cach-)X -2418 3770(ing)N -2546(of)X -2639(buckets)X -2910(in)X -2998(the)X -3122(new)X -3282(package)X -3571(to)X -3658(improve)X -3950(perfor-)X -2418 3858(mance)N -2666(by)X -2784(over)X -2965(80%.)X -3169(Since)X -3384(the)X -3519(\256rst)X -3 f -3680(sequential)X -1 f -4063(test)X -2418 3946(does)N -2598(not)X -2733(require)X -2 f -2994(ndbm)X -1 f -3205(to)X -3299(return)X -3523(the)X -3653(data)X -3819(values,)X -4076(the)X -2418 4034(user)N -2573(time)X -2735(is)X -2808(lower)X -3011(than)X -3169(for)X -3283(the)X -3401(new)X -3555(package.)X -3879(However)X -2418 4122(when)N -2613(we)X -2728(require)X -2977(both)X -3139(packages)X -3454(to)X -3536(return)X -3748(data,)X -3922(the)X -4040(new)X -2418 4210(package)N -2702(excels)X -2923(in)X -3005(all)X -3105(three)X -3286(timings.)X -2590 4324(The)N -2773(small)X -3003(database)X -3337(runs)X -3532(so)X -3660(quickly)X -3957(in)X -4076(the)X -2418 4412(memory-resident)N -3000(case)X -3173(that)X -3326(the)X -3457(results)X -3699(are)X -3831(uninterest-)X -2418 4500(ing.)N -2589(However,)X -2933(for)X -3056(the)X -3183(larger)X -3400(database)X -3706(the)X -3833(new)X -3995(pack-)X -2418 4588(age)N -2567(pays)X -2751(a)X -2824(small)X -3033(penalty)X -3305(in)X -3403(system)X -3661(time)X -3839(because)X -4130(it)X -2418 4676(limits)N -2636(its)X -2748(main)X -2944(memory)X -3247(utilization)X -3607(and)X -3759(swaps)X -3991(pages)X -2418 4764(out)N -2550(to)X -2642(temporary)X -3002(storage)X -3264(in)X -3356(the)X -3484(\256le)X -3616(system)X -3868(while)X -4076(the)X -2 f -2418 4852(hsearch)N -1 f -2698(package)X -2988(requires)X -3273(that)X -3419(the)X -3543(application)X -3924(allocate)X -2418 4940(enough)N -2692(space)X -2909(for)X -3041(all)X -3159(key/data)X -3468(pair.)X -3670(However,)X -4022(even)X -2418 5028(with)N -2600(the)X -2738(system)X -3000(time)X -3182(penalty,)X -3477(the)X -3614(resulting)X -3933(elapsed)X -2418 5116(time)N -2580(improves)X -2898(by)X -2998(over)X -3161(50%.)X -3 f -432 5960(10)N -2970(USENIX)X -9 f -3292(-)X -3 f -3356(Winter)X -3621('91)X -9 f -3748(-)X -3 f -3812(Dallas,)X -4065(TX)X - -11 p -%%Page: 11 11 -0(Courier)xf 0 f -10 s 10 xH 0 xS 0 f -3 f -720 258(Seltzer)N -977(&)X -1064(Yigit)X -3278(A)X -3356(New)X -3528(Hashing)X -3831(Package)X -4136(for)X -4259(UNIX)X -1 f -10 f -908 454(i)N -927(iiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii)X -2 f -1379 546(hash)N -1652(ndbm)X -1950(%change)X -1 f -10 f -908 550(i)N -927(iiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii)X -1 f -948 642(CREATE)N -10 f -908 646(i)N -927(iiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii)X -1 f -1125 738(user)N -1424(6.4)X -1671(12.2)X -2073(48)X -1157 826(sys)N -1384(32.5)X -1671(34.7)X -2113(6)X -3 f -1006 914(elapsed)N -10 f -1310 922(c)N -890(c)Y -810(c)Y -730(c)Y -3 f -1384 914(90.4)N -10 f -1581 922(c)N -890(c)Y -810(c)Y -730(c)Y -3 f -1671 914(99.6)N -10 f -1883 922(c)N -890(c)Y -810(c)Y -730(c)Y -3 f -2113 914(9)N -1 f -10 f -908 910(i)N -927(iiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii)X -908 926(i)N -927(iiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii)X -1 f -948 1010(READ)N -10 f -908 1014(i)N -927(iiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii)X -1 f -1125 1106(user)N -1424(3.4)X -1711(6.1)X -2073(44)X -1157 1194(sys)N -1424(1.2)X -1671(15.3)X -2073(92)X -3 f -1006 1282(elapsed)N -10 f -1310 1290(c)N -1258(c)Y -1178(c)Y -1098(c)Y -3 f -1424 1282(4.0)N -10 f -1581 1290(c)N -1258(c)Y -1178(c)Y -1098(c)Y -3 f -1671 1282(21.2)N -10 f -1883 1290(c)N -1258(c)Y -1178(c)Y -1098(c)Y -3 f -2073 1282(81)N -1 f -10 f -908 1278(i)N -927(iiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii)X -908 1294(i)N -927(iiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii)X -1 f -948 1378(VERIFY)N -10 f -908 1382(i)N -927(iiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii)X -1 f -1125 1474(user)N -1424(3.5)X -1711(6.3)X -2073(44)X -1157 1562(sys)N -1424(1.2)X -1671(15.3)X -2073(92)X -3 f -1006 1650(elapsed)N -10 f -1310 1658(c)N -1626(c)Y -1546(c)Y -1466(c)Y -3 f -1424 1650(4.0)N -10 f -1581 1658(c)N -1626(c)Y -1546(c)Y -1466(c)Y -3 f -1671 1650(21.2)N -10 f -1883 1658(c)N -1626(c)Y -1546(c)Y -1466(c)Y -3 f -2073 1650(81)N -1 f -10 f -908 1646(i)N -927(iiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii)X -908 1662(i)N -927(iiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii)X -1 f -948 1746(SEQUENTIAL)N -10 f -908 1750(i)N -927(iiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii)X -1 f -1125 1842(user)N -1424(2.7)X -1711(1.9)X -2046(-42)X -1157 1930(sys)N -1424(0.7)X -1711(3.9)X -2073(82)X -3 f -1006 2018(elapsed)N -10 f -1310 2026(c)N -1994(c)Y -1914(c)Y -1834(c)Y -3 f -1424 2018(3.0)N -10 f -1581 2026(c)N -1994(c)Y -1914(c)Y -1834(c)Y -3 f -1711 2018(5.0)N -10 f -1883 2026(c)N -1994(c)Y -1914(c)Y -1834(c)Y -3 f -2073 2018(40)N -1 f -10 f -908 2014(i)N -927(iiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii)X -908 2030(i)N -927(iiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii)X -1 f -948 2114(SEQUENTIAL)N -1467(\(with)X -1656(data)X -1810(retrieval\))X -10 f -908 2118(i)N -927(iiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii)X -1 f -1125 2210(user)N -1424(2.7)X -1711(8.2)X -2073(67)X -1157 2298(sys)N -1424(0.7)X -1711(4.3)X -2073(84)X -3 f -1006 2386(elapsed)N -1424(3.0)X -1671(12.0)X -2073(75)X -1 f -10 f -908 2390(i)N -927(iiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii)X -899 2394(c)N -2378(c)Y -2298(c)Y -2218(c)Y -2138(c)Y -2058(c)Y -1978(c)Y -1898(c)Y -1818(c)Y -1738(c)Y -1658(c)Y -1578(c)Y -1498(c)Y -1418(c)Y -1338(c)Y -1258(c)Y -1178(c)Y -1098(c)Y -1018(c)Y -938(c)Y -858(c)Y -778(c)Y -698(c)Y -618(c)Y -538(c)Y -1310 2394(c)N -2362(c)Y -2282(c)Y -2202(c)Y -1581 2394(c)N -2362(c)Y -2282(c)Y -2202(c)Y -1883 2394(c)N -2362(c)Y -2282(c)Y -2202(c)Y -2278 2394(c)N -2378(c)Y -2298(c)Y -2218(c)Y -2138(c)Y -2058(c)Y -1978(c)Y -1898(c)Y -1818(c)Y -1738(c)Y -1658(c)Y -1578(c)Y -1498(c)Y -1418(c)Y -1338(c)Y -1258(c)Y -1178(c)Y -1098(c)Y -1018(c)Y -938(c)Y -858(c)Y -778(c)Y -698(c)Y -618(c)Y -538(c)Y -905 2574(i)N -930(iiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii)X -2 f -1318 2666(hash)N -1585(hsearch)X -1953(%change)X -1 f -10 f -905 2670(i)N -930(iiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii)X -1 f -945 2762(CREATE/READ)N -10 f -905 2766(i)N -930(iiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii)X -1 f -1064 2858(user)N -1343(6.6)X -1642(17.2)X -2096(62)X -1096 2946(sys)N -1343(1.1)X -1682(0.3)X -2029(-266)X -3 f -945 3034(elapsed)N -1343(7.8)X -1642(17.0)X -2096(54)X -1 f -10 f -905 3038(i)N -930(iiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii)X -896 3050(c)N -2978(c)Y -2898(c)Y -2818(c)Y -2738(c)Y -2658(c)Y -1249 3034(c)N -3010(c)Y -2930(c)Y -2850(c)Y -1520 3034(c)N -3010(c)Y -2930(c)Y -2850(c)Y -1886 3034(c)N -3010(c)Y -2930(c)Y -2850(c)Y -2281 3050(c)N -2978(c)Y -2898(c)Y -2818(c)Y -2738(c)Y -2658(c)Y -3 f -720 3174(Figure)N -967(8a:)X -1 f -1094(Timing)X -1349(results)X -1578(for)X -1692(the)X -1810(dictionary)X -2155(database.)X -10 f -720 3262 -0.0930(hhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhh)AN -3 f -1407 3504(Conclusion)N -1 f -892 3636(This)N -1063(paper)X -1271(has)X -1407(presented)X -1744(the)X -1871(design,)X -2129(implemen-)X -720 3724(tation)N -928(and)X -1070(performance)X -1503(of)X -1596(a)X -1658(new)X -1818(hashing)X -2093(package)X -2382(for)X -720 3812(UNIX.)N -993(The)X -1150(new)X -1316(package)X -1612(provides)X -1919(a)X -1986(superset)X -2280(of)X -2378(the)X -720 3900(functionality)N -1159(of)X -1255(existing)X -1537(hashing)X -1815(packages)X -2139(and)X -2284(incor-)X -720 3988(porates)N -975(additional)X -1318(features)X -1596(such)X -1766(as)X -1855(large)X -2038(key)X -2176(handling,)X -720 4076(user)N -876(de\256ned)X -1134(hash)X -1302(functions,)X -1641(multiple)X -1928(hash)X -2096(tables,)X -2324(vari-)X -720 4164(able)N -894(sized)X -1099(pages,)X -1342(and)X -1498(linear)X -1721(hashing.)X -2050(In)X -2156(nearly)X -2396(all)X -720 4252(cases,)N -954(the)X -1096(new)X -1274(package)X -1582(provides)X -1902(improved)X -2252(perfor-)X -720 4340(mance)N -974(on)X -1098(the)X -1240(order)X -1454(of)X -1565(50-80%)X -1863(for)X -2001(the)X -2142(workloads)X -720 4428(shown.)N -990(Applications)X -1420(such)X -1588(as)X -1676(the)X -1794(loader,)X -2035(compiler,)X -2360(and)X -720 4516(mail,)N -921(which)X -1156(currently)X -1485(implement)X -1866(their)X -2051(own)X -2227(hashing)X -720 4604(routines,)N -1032(should)X -1279(be)X -1389(modi\256ed)X -1706(to)X -1801(use)X -1941(the)X -2072(generic)X -2342(rou-)X -720 4692(tines.)N -892 4806(This)N -1087(hashing)X -1389(package)X -1705(is)X -1810(one)X -1978(access)X -2236(method)X -720 4894(which)N -953(is)X -1043(part)X -1205(of)X -1309(a)X -1382(generic)X -1656(database)X -1970(access)X -2212(package)X -720 4982(being)N -955(developed)X -1342(at)X -1457(the)X -1612(University)X -2007(of)X -2131(California,)X -720 5070(Berkeley.)N -1089(It)X -1177(will)X -1340(include)X -1614(a)X -1688(btree)X -1887(access)X -2131(method)X -2409(as)X -720 5158(well)N -916(as)X -1041(\256xed)X -1259(and)X -1433(variable)X -1750(length)X -2007(record)X -2270(access)X -720 5246(methods)N -1024(in)X -1119(addition)X -1414(to)X -1509(the)X -1640(hashed)X -1896(support)X -2168(presented)X -720 5334(here.)N -948(All)X -1099(of)X -1215(the)X -1361(access)X -1615(methods)X -1934(are)X -2081(based)X -2312(on)X -2440(a)X -720 5422(key/data)N -1037(pair)X -1207(interface)X -1533(and)X -1693(appear)X -1952(identical)X -2272(to)X -2378(the)X -720 5510(application)N -1121(layer,)X -1347(allowing)X -1671(application)X -2071(implementa-)X -720 5598(tions)N -906(to)X -999(be)X -1106(largely)X -1360(independent)X -1783(of)X -1881(the)X -2010(database)X -2318(type.)X -720 5686(The)N -873(package)X -1165(is)X -1246(expected)X -1560(to)X -1650(be)X -1754(an)X -1858(integral)X -2131(part)X -2284(of)X -2378(the)X -2706 538(4.4BSD)N -3006(system,)X -3293(with)X -3479(various)X -3759(standard)X -4075(applications)X -2706 626(such)N -2879(as)X -2972(more\(1\),)X -3277(sort\(1\))X -3517(and)X -3659(vi\(1\))X -3841(based)X -4050(on)X -4156(it.)X -4266(While)X -2706 714(the)N -2833(current)X -3089(design)X -3326(does)X -3501(not)X -3631(support)X -3899(multi-user)X -4256(access)X -2706 802(or)N -2804(transactions,)X -3238(they)X -3407(could)X -3616(be)X -3723(incorporated)X -4159(relatively)X -2706 890(easily.)N -10 f -2894 938(i)N -2913(iiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii)X -2 f -3365 1030(hash)N -3638(ndbm)X -3936(%change)X -1 f -10 f -2894 1034(i)N -2913(iiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii)X -1 f -2934 1126(CREATE)N -10 f -2894 1130(i)N -2913(iiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii)X -1 f -3111 1222(user)N -3390(0.2)X -3677(0.4)X -4079(50)X -3143 1310(sys)N -3390(0.1)X -3677(1.0)X -4079(90)X -3 f -2992 1398(elapsed)N -10 f -3296 1406(c)N -1374(c)Y -1294(c)Y -1214(c)Y -3 f -3390 1398(0)N -10 f -3567 1406(c)N -1374(c)Y -1294(c)Y -1214(c)Y -3 f -3677 1398(3.2)N -10 f -3869 1406(c)N -1374(c)Y -1294(c)Y -1214(c)Y -3 f -4039 1398(100)N -1 f -10 f -2894 1394(i)N -2913(iiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii)X -2894 1410(i)N -2913(iiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii)X -1 f -2934 1494(READ)N -10 f -2894 1498(i)N -2913(iiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii)X -1 f -3111 1590(user)N -3390(0.1)X -3677(0.1)X -4119(0)X -3143 1678(sys)N -3390(0.1)X -3677(0.4)X -4079(75)X -3 f -2992 1766(elapsed)N -10 f -3296 1774(c)N -1742(c)Y -1662(c)Y -1582(c)Y -3 f -3390 1766(0.0)N -10 f -3567 1774(c)N -1742(c)Y -1662(c)Y -1582(c)Y -3 f -3677 1766(0.0)N -10 f -3869 1774(c)N -1742(c)Y -1662(c)Y -1582(c)Y -3 f -4119 1766(0)N -1 f -10 f -2894 1762(i)N -2913(iiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii)X -2894 1778(i)N -2913(iiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii)X -1 f -2934 1862(VERIFY)N -10 f -2894 1866(i)N -2913(iiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii)X -1 f -3111 1958(user)N -3390(0.1)X -3677(0.2)X -4079(50)X -3143 2046(sys)N -3390(0.1)X -3677(0.3)X -4079(67)X -3 f -2992 2134(elapsed)N -10 f -3296 2142(c)N -2110(c)Y -2030(c)Y -1950(c)Y -3 f -3390 2134(0.0)N -10 f -3567 2142(c)N -2110(c)Y -2030(c)Y -1950(c)Y -3 f -3677 2134(0.0)N -10 f -3869 2142(c)N -2110(c)Y -2030(c)Y -1950(c)Y -3 f -4119 2134(0)N -1 f -10 f -2894 2130(i)N -2913(iiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii)X -2894 2146(i)N -2913(iiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii)X -1 f -2934 2230(SEQUENTIAL)N -10 f -2894 2234(i)N -2913(iiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii)X -1 f -3111 2326(user)N -3390(0.1)X -3677(0.0)X -4012(-100)X -3143 2414(sys)N -3390(0.1)X -3677(0.1)X -4119(0)X -3 f -2992 2502(elapsed)N -10 f -3296 2510(c)N -2478(c)Y -2398(c)Y -2318(c)Y -3 f -3390 2502(0.0)N -10 f -3567 2510(c)N -2478(c)Y -2398(c)Y -2318(c)Y -3 f -3677 2502(0.0)N -10 f -3869 2510(c)N -2478(c)Y -2398(c)Y -2318(c)Y -3 f -4119 2502(0)N -1 f -10 f -2894 2498(i)N -2913(iiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii)X -2894 2514(i)N -2913(iiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii)X -1 f -2934 2598(SEQUENTIAL)N -3453(\(with)X -3642(data)X -3796(retrieval\))X -10 f -2894 2602(i)N -2913(iiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii)X -1 f -3111 2694(user)N -3390(0.1)X -3677(0.1)X -4119(0)X -3143 2782(sys)N -3390(0.1)X -3677(0.1)X -4119(0)X -3 f -2992 2870(elapsed)N -3390(0.0)X -3677(0.0)X -4119(0)X -1 f -10 f -2894 2874(i)N -2913(iiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii)X -2885 2878(c)N -2862(c)Y -2782(c)Y -2702(c)Y -2622(c)Y -2542(c)Y -2462(c)Y -2382(c)Y -2302(c)Y -2222(c)Y -2142(c)Y -2062(c)Y -1982(c)Y -1902(c)Y -1822(c)Y -1742(c)Y -1662(c)Y -1582(c)Y -1502(c)Y -1422(c)Y -1342(c)Y -1262(c)Y -1182(c)Y -1102(c)Y -1022(c)Y -3296 2878(c)N -2846(c)Y -2766(c)Y -2686(c)Y -3567 2878(c)N -2846(c)Y -2766(c)Y -2686(c)Y -3869 2878(c)N -2846(c)Y -2766(c)Y -2686(c)Y -4264 2878(c)N -2862(c)Y -2782(c)Y -2702(c)Y -2622(c)Y -2542(c)Y -2462(c)Y -2382(c)Y -2302(c)Y -2222(c)Y -2142(c)Y -2062(c)Y -1982(c)Y -1902(c)Y -1822(c)Y -1742(c)Y -1662(c)Y -1582(c)Y -1502(c)Y -1422(c)Y -1342(c)Y -1262(c)Y -1182(c)Y -1102(c)Y -1022(c)Y -2891 3058(i)N -2916(iiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii)X -2 f -3304 3150(hash)N -3571(hsearch)X -3939(%change)X -1 f -10 f -2891 3154(i)N -2916(iiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii)X -1 f -2931 3246(CREATE/READ)N -10 f -2891 3250(i)N -2916(iiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii)X -1 f -3050 3342(user)N -3329(0.3)X -3648(0.4)X -4048(25)X -3082 3430(sys)N -3329(0.0)X -3648(0.0)X -4088(0)X -3 f -2931 3518(elapsed)N -3329(0.0)X -3648(0.0)X -4088(0)X -1 f -10 f -2891 3522(i)N -2916(iiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii)X -2882 3534(c)N -3462(c)Y -3382(c)Y -3302(c)Y -3222(c)Y -3142(c)Y -3235 3518(c)N -3494(c)Y -3414(c)Y -3334(c)Y -3506 3518(c)N -3494(c)Y -3414(c)Y -3334(c)Y -3872 3518(c)N -3494(c)Y -3414(c)Y -3334(c)Y -4267 3534(c)N -3462(c)Y -3382(c)Y -3302(c)Y -3222(c)Y -3142(c)Y -3 f -2706 3658(Figure)N -2953(8b:)X -1 f -3084(Timing)X -3339(results)X -3568(for)X -3682(the)X -3800(password)X -4123(database.)X -10 f -2706 3746 -0.0930(hhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhh)AN -3 f -3396 3988(References)N -1 f -2706 4120([ATT79])N -3058(AT&T,)X -3358(DBM\(3X\),)X -2 f -3773(Unix)X -3990(Programmer's)X -2878 4208(Manual,)N -3194(Seventh)X -3491(Edition,)X -3793(Volume)X -4085(1)X -1 f -(,)S -4192(January,)X -2878 4296(1979.)N -2706 4472([ATT85])N -3027(AT&T,)X -3296(HSEARCH\(BA_LIB\),)X -2 f -4053(Unix)X -4239(System)X -2878 4560(User's)N -3112(Manual,)X -3401(System)X -3644(V.3)X -1 f -3753(,)X -3793(pp.)X -3913(506-508,)X -4220(1985.)X -2706 4736([BRE73])N -3025(Brent,)X -3253(Richard)X -3537(P.,)X -3651(``Reducing)X -4041(the)X -4168(Retrieval)X -2878 4824(Time)N -3071(of)X -3162(Scatter)X -3409(Storage)X -3678(Techniques'',)X -2 f -4146(Commun-)X -2878 4912(ications)N -3175(of)X -3281(the)X -3422(ACM)X -1 f -3591(,)X -3654(Volume)X -3955(16,)X -4098(No.)X -4259(2,)X -4362(pp.)X -2878 5000(105-109,)N -3185(February,)X -3515(1973.)X -2706 5176([BSD86])N -3055(NDBM\(3\),)X -2 f -3469(4.3BSD)X -3775(Unix)X -3990(Programmer's)X -2878 5264(Manual)N -3155(Reference)X -3505(Guide)X -1 f -3701(,)X -3749(University)X -4114(of)X -4208(Califor-)X -2878 5352(nia,)N -3016(Berkeley,)X -3346(1986.)X -2706 5528([ENB88])N -3025(Enbody,)X -3319(R.)X -3417(J.,)X -3533(Du,)X -3676(H.)X -3779(C.,)X -3897(``Dynamic)X -4270(Hash-)X -2878 5616(ing)N -3034(Schemes'',)X -2 f -3427(ACM)X -3630(Computing)X -4019(Surveys)X -1 f -4269(,)X -4322(Vol.)X -2878 5704(20,)N -2998(No.)X -3136(2,)X -3216(pp.)X -3336(85-113,)X -3603(June)X -3770(1988.)X -3 f -720 5960(USENIX)N -9 f -1042(-)X -3 f -1106(Winter)X -1371('91)X -9 f -1498(-)X -3 f -1562(Dallas,)X -1815(TX)X -4384(11)X - -12 p -%%Page: 12 12 -0(Courier)xf 0 f -10 s 10 xH 0 xS 0 f -3 f -432 258(A)N -510(New)X -682(Hashing)X -985(Package)X -1290(for)X -1413(UNIX)X -3663(Seltzer)X -3920(&)X -4007(Yigit)X -1 f -432 538([FAG79])N -776(Ronald)X -1057(Fagin,)X -1308(Jurg)X -1495(Nievergelt,)X -1903(Nicholas)X -604 626(Pippenger,)N -1003(H.)X -1135(Raymond)X -1500(Strong,)X -1787(``Extendible)X -604 714(Hashing)N -901(--)X -985(A)X -1073(Fast)X -1236(Access)X -1493(Method)X -1771(for)X -1894(Dynamic)X -604 802(Files'',)N -2 f -855(ACM)X -1046(Transactions)X -1485(on)X -1586(Database)X -1914(Systems)X -1 f -2168(,)X -604 890(Volume)N -882(4,)X -962(No.)X -1100(3.,)X -1200(September)X -1563(1979,)X -1763(pp)X -1863(315-34)X -432 1066([KNU68],)N -802(Knuth,)X -1064(D.E.,)X -2 f -1273(The)X -1434(Art)X -1577(of)X -1680(Computer)X -2041(Pro-)X -604 1154(gramming)N -971(Vol.)X -1140(3:)X -1245(Sorting)X -1518(and)X -1676(Searching)X -1 f -2001(,)X -2058(sec-)X -604 1242(tions)N -779(6.3-6.4,)X -1046(pp)X -1146(481-550.)X -432 1418([LAR78])N -747(Larson,)X -1011(Per-Ake,)X -1319(``Dynamic)X -1687(Hashing'',)X -2 f -2048(BIT)X -1 f -(,)S -604 1506(Vol.)N -764(18,)X -884(1978,)X -1084(pp.)X -1204(184-201.)X -432 1682([LAR88])N -752(Larson,)X -1021(Per-Ake,)X -1335(``Dynamic)X -1709(Hash)X -1900(Tables'',)X -2 f -604 1770(Communications)N -1183(of)X -1281(the)X -1415(ACM)X -1 f -1584(,)X -1640(Volume)X -1934(31,)X -2070(No.)X -604 1858(4.,)N -704(April)X -893(1988,)X -1093(pp)X -1193(446-457.)X -432 2034([LIT80])N -731(Witold,)X -1013(Litwin,)X -1286(``Linear)X -1590(Hashing:)X -1939(A)X -2036(New)X -604 2122(Tool)N -786(for)X -911(File)X -1065(and)X -1211(Table)X -1424(Addressing'',)X -2 f -1893(Proceed-)X -604 2210(ings)N -761(of)X -847(the)X -969(6th)X -1095(International)X -1540(Conference)X -1933(on)X -2036(Very)X -604 2298(Large)N -815(Databases)X -1 f -1153(,)X -1193(1980.)X -432 2474([NEL90])N -743(Nelson,)X -1011(Philip)X -1222(A.,)X -2 f -1341(Gdbm)X -1558(1.4)X -1679(source)X -1913(distribu-)X -604 2562(tion)N -748(and)X -888(README)X -1 f -1209(,)X -1249(August)X -1500(1990.)X -432 2738([THOM90])N -840(Ken)X -1011(Thompson,)X -1410(private)X -1670(communication,)X -604 2826(Nov.)N -782(1990.)X -432 3002([TOR87])N -790(Torek,)X -1066(C.,)X -1222(``Re:)X -1470(dbm.a)X -1751(and)X -1950(ndbm.a)X -604 3090(archives'',)N -2 f -966(USENET)X -1279(newsgroup)X -1650(comp.unix)X -1 f -2002(1987.)X -432 3266([TOR88])N -760(Torek,)X -1006(C.,)X -1133(``Re:)X -1351(questions)X -1686(regarding)X -2027(data-)X -604 3354(bases)N -826(created)X -1106(with)X -1295(dbm)X -1484(and)X -1647(ndbm)X -1876(routines'')X -2 f -604 3442(USENET)N -937(newsgroup)X -1328(comp.unix.questions)X -1 f -1982(,)X -2041(June)X -604 3530(1988.)N -432 3706([WAL84])N -773(Wales,)X -1018(R.,)X -1135(``Discussion)X -1564(of)X -1655("dbm")X -1887(data)X -2045(base)X -604 3794(system'',)N -2 f -973(USENET)X -1339(newsgroup)X -1762(unix.wizards)X -1 f -2168(,)X -604 3882(January,)N -894(1984.)X -432 4058([YIG89])N -751(Ozan)X -963(S.)X -1069(Yigit,)X -1294(``How)X -1545(to)X -1648(Roll)X -1826(Your)X -2032(Own)X -604 4146(Dbm/Ndbm'',)N -2 f -1087(unpublished)X -1504(manuscript)X -1 f -(,)S -1910(Toronto,)X -604 4234(July,)N -777(1989)X -3 f -432 5960(12)N -2970(USENIX)X -9 f -3292(-)X -3 f -3356(Winter)X -3621('91)X -9 f -3748(-)X -3 f -3812(Dallas,)X -4065(TX)X - -13 p -%%Page: 13 13 -0(Courier)xf 0 f -10 s 10 xH 0 xS 0 f -3 f -720 258(Seltzer)N -977(&)X -1064(Yigit)X -3278(A)X -3356(New)X -3528(Hashing)X -3831(Package)X -4136(for)X -4259(UNIX)X -1 f -720 538(Margo)N -960(I.)X -1033(Seltzer)X -1282(is)X -1361(a)X -1423(Ph.D.)X -1631(student)X -1887(in)X -1974(the)X -2097(Department)X -720 626(of)N -823(Electrical)X -1167(Engineering)X -1595(and)X -1747(Computer)X -2102(Sciences)X -2418(at)X -720 714(the)N -850(University)X -1220(of)X -1318(California,)X -1694(Berkeley.)X -2055(Her)X -2207(research)X -720 802(interests)N -1017(include)X -1283(\256le)X -1415(systems,)X -1718(databases,)X -2076(and)X -2221(transac-)X -720 890(tion)N -896(processing)X -1291(systems.)X -1636(She)X -1807(spent)X -2027(several)X -2306(years)X -720 978(working)N -1026(at)X -1123(startup)X -1380(companies)X -1762(designing)X -2112(and)X -2267(imple-)X -720 1066(menting)N -1048(\256le)X -1216(systems)X -1535(and)X -1716(transaction)X -2133(processing)X -720 1154(software)N -1026(and)X -1170(designing)X -1509(microprocessors.)X -2103(Ms.)X -2253(Seltzer)X -720 1242(received)N -1057(her)X -1223(AB)X -1397(in)X -1522(Applied)X -1843(Mathematics)X -2320(from)X -720 1330 0.1953(Harvard/Radcliffe)AN -1325(College)X -1594(in)X -1676(1983.)X -720 1444(In)N -810(her)X -936(spare)X -1129(time,)X -1313(Margo)X -1549(can)X -1683(usually)X -1936(be)X -2034(found)X -2243(prepar-)X -720 1532(ing)N -868(massive)X -1171(quantities)X -1527(of)X -1639(food)X -1831(for)X -1970(hungry)X -2242(hoards,)X -720 1620(studying)N -1022(Japanese,)X -1355(or)X -1449(playing)X -1716(soccer)X -1948(with)X -2116(an)X -2218(exciting)X -720 1708(Bay)N -912(Area)X -1132(Women's)X -1507(Soccer)X -1788(team,)X -2026(the)X -2186(Berkeley)X -720 1796(Bruisers.)N -720 1910(Ozan)N -915(\()X -3 f -942(Oz)X -1 f -1040(\))X -1092(Yigit)X -1281(is)X -1358(currently)X -1672(a)X -1732(software)X -2033(engineer)X -2334(with)X -720 1998(the)N -886(Communications)X -1499(Research)X -1861(and)X -2044(Development)X -720 2086(group,)N -948(Computing)X -1328(Services,)X -1641(York)X -1826(University.)X -2224(His)X -2355(for-)X -720 2174(mative)N -967(years)X -1166(were)X -1352(also)X -1510(spent)X -1708(at)X -1795(York,)X -2009(where)X -2234(he)X -2338(held)X -720 2262(system)N -985(programmer)X -1425(and)X -1583(administrator)X -2052(positions)X -2382(for)X -720 2350(various)N -995(mixtures)X -1314(of)X -1420(of)X -1526(UNIX)X -1765(systems)X -2056(starting)X -2334(with)X -720 2438(Berkeley)N -1031(4.1)X -1151(in)X -1233(1982,)X -1433(while)X -1631(at)X -1709(the)X -1827(same)X -2012(time)X -2174(obtaining)X -720 2526(a)N -776(degree)X -1011(in)X -1093(Computer)X -1433(Science.)X -720 2640(In)N -813(his)X -931(copious)X -1205(free)X -1356(time,)X -1543(Oz)X -1662(enjoys)X -1896(working)X -2188(on)X -2293(what-)X -720 2728(ever)N -890(software)X -1197(looks)X -1400(interesting,)X -1788(which)X -2014(often)X -2209(includes)X -720 2816(language)N -1044(interpreters,)X -1464(preprocessors,)X -1960(and)X -2110(lately,)X -2342(pro-)X -720 2904(gram)N -905(generators)X -1260(and)X -1396(expert)X -1617(systems.)X -720 3018(Oz)N -836(has)X -964(authored)X -1266(several)X -1515(public-domain)X -2003(software)X -2301(tools,)X -720 3106(including)N -1069(an)X -1191(nroff-like)X -1545(text)X -1711(formatter)X -2 f -2056(proff)X -1 f -2257(that)X -2423(is)X -720 3194(apparently)N -1083(still)X -1226(used)X -1397(in)X -1483(some)X -1676(basement)X -2002(PCs.)X -2173(His)X -2307(latest)X -720 3282(obsessions)N -1143(include)X -1460(the)X -1639(incredible)X -2040(programming)X -720 3370(language)N -1030(Scheme,)X -1324(and)X -1460(Chinese)X -1738(Brush)X -1949(painting.)X -3 f -720 5960(USENIX)N -9 f -1042(-)X -3 f -1106(Winter)X -1371('91)X -9 f -1498(-)X -3 f -1562(Dallas,)X -1815(TX)X -4384(13)X - -14 p -%%Page: 14 14 -0(Courier)xf 0 f -10 s 10 xH 0 xS 0 f -3 f -432 5960(14)N -2970(USENIX)X -9 f -3292(-)X -3 f -3356(Winter)X -3621('91)X -9 f -3748(-)X -3 f -3812(Dallas,)X -4065(TX)X - -14 p -%%Trailer -xt - -xs diff --git a/libdb/docs/ref/refs/libtp_usenix.ps b/libdb/docs/ref/refs/libtp_usenix.ps deleted file mode 100644 index 5b5ba6e1b..000000000 --- a/libdb/docs/ref/refs/libtp_usenix.ps +++ /dev/null @@ -1,12340 +0,0 @@ -%!PS-Adobe-1.0 -%%Creator: utopia:margo (& Seltzer,608-13E,8072,) -%%Title: stdin (ditroff) -%%CreationDate: Thu Dec 12 15:32:11 1991 -%%EndComments -% @(#)psdit.pro 1.3 4/15/88 -% lib/psdit.pro -- prolog for psdit (ditroff) files -% Copyright (c) 1984, 1985 Adobe Systems Incorporated. All Rights Reserved. -% last edit: shore Sat Nov 23 20:28:03 1985 -% RCSID: $Header$ - -% Changed by Edward Wang (edward@ucbarpa.berkeley.edu) to handle graphics, -% 17 Feb, 87. - -/$DITroff 140 dict def $DITroff begin -/fontnum 1 def /fontsize 10 def /fontheight 10 def /fontslant 0 def -/xi{0 72 11 mul translate 72 resolution div dup neg scale 0 0 moveto - /fontnum 1 def /fontsize 10 def /fontheight 10 def /fontslant 0 def F - /pagesave save def}def -/PB{save /psv exch def currentpoint translate - resolution 72 div dup neg scale 0 0 moveto}def -/PE{psv restore}def -/arctoobig 90 def /arctoosmall .05 def -/m1 matrix def /m2 matrix def /m3 matrix def /oldmat matrix def -/tan{dup sin exch cos div}def -/point{resolution 72 div mul}def -/dround {transform round exch round exch itransform}def -/xT{/devname exch def}def -/xr{/mh exch def /my exch def /resolution exch def}def -/xp{}def -/xs{docsave restore end}def -/xt{}def -/xf{/fontname exch def /slotno exch def fontnames slotno get fontname eq not - {fonts slotno fontname findfont put fontnames slotno fontname put}if}def -/xH{/fontheight exch def F}def -/xS{/fontslant exch def F}def -/s{/fontsize exch def /fontheight fontsize def F}def -/f{/fontnum exch def F}def -/F{fontheight 0 le{/fontheight fontsize def}if - fonts fontnum get fontsize point 0 0 fontheight point neg 0 0 m1 astore - fontslant 0 ne{1 0 fontslant tan 1 0 0 m2 astore m3 concatmatrix}if - makefont setfont .04 fontsize point mul 0 dround pop setlinewidth}def -/X{exch currentpoint exch pop moveto show}def -/N{3 1 roll moveto show}def -/Y{exch currentpoint pop exch moveto show}def -/S{show}def -/ditpush{}def/ditpop{}def -/AX{3 -1 roll currentpoint exch pop moveto 0 exch ashow}def -/AN{4 2 roll moveto 0 exch ashow}def -/AY{3 -1 roll currentpoint pop exch moveto 0 exch ashow}def -/AS{0 exch ashow}def -/MX{currentpoint exch pop moveto}def -/MY{currentpoint pop exch moveto}def -/MXY{moveto}def -/cb{pop}def % action on unknown char -- nothing for now -/n{}def/w{}def -/p{pop showpage pagesave restore /pagesave save def}def -/Dt{/Dlinewidth exch def}def 1 Dt -/Ds{/Ddash exch def}def -1 Ds -/Di{/Dstipple exch def}def 1 Di -/Dsetlinewidth{2 Dlinewidth mul setlinewidth}def -/Dsetdash{Ddash 4 eq{[8 12]}{Ddash 16 eq{[32 36]} - {Ddash 20 eq{[32 12 8 12]}{[]}ifelse}ifelse}ifelse 0 setdash}def -/Dstroke{gsave Dsetlinewidth Dsetdash 1 setlinecap stroke grestore - currentpoint newpath moveto}def -/Dl{rlineto Dstroke}def -/arcellipse{/diamv exch def /diamh exch def oldmat currentmatrix pop - currentpoint translate 1 diamv diamh div scale /rad diamh 2 div def - currentpoint exch rad add exch rad -180 180 arc oldmat setmatrix}def -/Dc{dup arcellipse Dstroke}def -/De{arcellipse Dstroke}def -/Da{/endv exch def /endh exch def /centerv exch def /centerh exch def - /cradius centerv centerv mul centerh centerh mul add sqrt def - /eradius endv endv mul endh endh mul add sqrt def - /endang endv endh atan def - /startang centerv neg centerh neg atan def - /sweep startang endang sub dup 0 lt{360 add}if def - sweep arctoobig gt - {/midang startang sweep 2 div sub def /midrad cradius eradius add 2 div def - /midh midang cos midrad mul def /midv midang sin midrad mul def - midh neg midv neg endh endv centerh centerv midh midv Da - Da} - {sweep arctoosmall ge - {/controldelt 1 sweep 2 div cos sub 3 sweep 2 div sin mul div 4 mul def - centerv neg controldelt mul centerh controldelt mul - endv neg controldelt mul centerh add endh add - endh controldelt mul centerv add endv add - centerh endh add centerv endv add rcurveto Dstroke} - {centerh endh add centerv endv add rlineto Dstroke} - ifelse} - ifelse}def -/Dpatterns[ -[%cf[widthbits] -[8<0000000000000010>] -[8<0411040040114000>] -[8<0204081020408001>] -[8<0000103810000000>] -[8<6699996666999966>] -[8<0000800100001008>] -[8<81c36666c3810000>] -[8<0f0e0c0800000000>] -[8<0000000000000010>] -[8<0411040040114000>] -[8<0204081020408001>] -[8<0000001038100000>] -[8<6699996666999966>] -[8<0000800100001008>] -[8<81c36666c3810000>] -[8<0f0e0c0800000000>] -[8<0042660000246600>] -[8<0000990000990000>] -[8<0804020180402010>] -[8<2418814242811824>] -[8<6699996666999966>] -[8<8000000008000000>] -[8<00001c3e363e1c00>] -[8<0000000000000000>] -[32<00000040000000c00000004000000040000000e0000000000000000000000000>] -[32<00000000000060000000900000002000000040000000f0000000000000000000>] -[32<000000000000000000e0000000100000006000000010000000e0000000000000>] -[32<00000000000000002000000060000000a0000000f00000002000000000000000>] -[32<0000000e0000000000000000000000000000000f000000080000000e00000001>] -[32<0000090000000600000000000000000000000000000007000000080000000e00>] -[32<00010000000200000004000000040000000000000000000000000000000f0000>] -[32<0900000006000000090000000600000000000000000000000000000006000000>]] -[%ug -[8<0000020000000000>] -[8<0000020000002000>] -[8<0004020000002000>] -[8<0004020000402000>] -[8<0004060000402000>] -[8<0004060000406000>] -[8<0006060000406000>] -[8<0006060000606000>] -[8<00060e0000606000>] -[8<00060e000060e000>] -[8<00070e000060e000>] -[8<00070e000070e000>] -[8<00070e020070e000>] -[8<00070e020070e020>] -[8<04070e020070e020>] -[8<04070e024070e020>] -[8<04070e064070e020>] -[8<04070e064070e060>] -[8<06070e064070e060>] -[8<06070e066070e060>] -[8<06070f066070e060>] -[8<06070f066070f060>] -[8<060f0f066070f060>] -[8<060f0f0660f0f060>] -[8<060f0f0760f0f060>] -[8<060f0f0760f0f070>] -[8<0e0f0f0760f0f070>] -[8<0e0f0f07e0f0f070>] -[8<0e0f0f0fe0f0f070>] -[8<0e0f0f0fe0f0f0f0>] -[8<0f0f0f0fe0f0f0f0>] -[8<0f0f0f0ff0f0f0f0>] -[8<1f0f0f0ff0f0f0f0>] -[8<1f0f0f0ff1f0f0f0>] -[8<1f0f0f8ff1f0f0f0>] -[8<1f0f0f8ff1f0f0f8>] -[8<9f0f0f8ff1f0f0f8>] -[8<9f0f0f8ff9f0f0f8>] -[8<9f0f0f9ff9f0f0f8>] -[8<9f0f0f9ff9f0f0f9>] -[8<9f8f0f9ff9f0f0f9>] -[8<9f8f0f9ff9f8f0f9>] -[8<9f8f1f9ff9f8f0f9>] -[8<9f8f1f9ff9f8f1f9>] -[8<bf8f1f9ff9f8f1f9>] -[8<bf8f1f9ffbf8f1f9>] -[8<bf8f1fdffbf8f1f9>] -[8<bf8f1fdffbf8f1fd>] -[8<ff8f1fdffbf8f1fd>] -[8<ff8f1fdffff8f1fd>] -[8<ff8f1ffffff8f1fd>] -[8<ff8f1ffffff8f1ff>] -[8<ff9f1ffffff8f1ff>] -[8<ff9f1ffffff9f1ff>] -[8<ff9f9ffffff9f1ff>] -[8<ff9f9ffffff9f9ff>] -[8<ffbf9ffffff9f9ff>] -[8<ffbf9ffffffbf9ff>] -[8<ffbfdffffffbf9ff>] -[8<ffbfdffffffbfdff>] -[8<ffffdffffffbfdff>] -[8<ffffdffffffffdff>] -[8<fffffffffffffdff>] -[8<ffffffffffffffff>]] -[%mg -[8<8000000000000000>] -[8<0822080080228000>] -[8<0204081020408001>] -[8<40e0400000000000>] -[8<66999966>] -[8<8001000010080000>] -[8<81c36666c3810000>] -[8<f0e0c08000000000>] -[16<07c00f801f003e007c00f800f001e003c007800f001f003e007c00f801f003e0>] -[16<1f000f8007c003e001f000f8007c003e001f800fc007e003f001f8007c003e00>] -[8<c3c300000000c3c3>] -[16<0040008001000200040008001000200040008000000100020004000800100020>] -[16<0040002000100008000400020001800040002000100008000400020001000080>] -[16<1fc03fe07df0f8f8f07de03fc01f800fc01fe03ff07df8f87df03fe01fc00f80>] -[8<80>] -[8<8040201000000000>] -[8<84cc000048cc0000>] -[8<9900009900000000>] -[8<08040201804020100800020180002010>] -[8<2418814242811824>] -[8<66999966>] -[8<8000000008000000>] -[8<70f8d8f870000000>] -[8<0814224180402010>] -[8<aa00440a11a04400>] -[8<018245aa45820100>] -[8<221c224180808041>] -[8<88000000>] -[8<0855800080550800>] -[8<2844004482440044>] -[8<0810204080412214>] -[8<00>]]]def -/Dfill{ - transform /maxy exch def /maxx exch def - transform /miny exch def /minx exch def - minx maxx gt{/minx maxx /maxx minx def def}if - miny maxy gt{/miny maxy /maxy miny def def}if - Dpatterns Dstipple 1 sub get exch 1 sub get - aload pop /stip exch def /stipw exch def /stiph 128 def - /imatrix[stipw 0 0 stiph 0 0]def - /tmatrix[stipw 0 0 stiph 0 0]def - /minx minx cvi stiph idiv stiph mul def - /miny miny cvi stipw idiv stipw mul def - gsave eoclip 0 setgray - miny stiph maxy{ - tmatrix exch 5 exch put - minx stipw maxx{ - tmatrix exch 4 exch put tmatrix setmatrix - stipw stiph true imatrix {stip} imagemask - }for - }for - grestore -}def -/Dp{Dfill Dstroke}def -/DP{Dfill currentpoint newpath moveto}def -end - -/ditstart{$DITroff begin - /nfonts 60 def % NFONTS makedev/ditroff dependent! - /fonts[nfonts{0}repeat]def - /fontnames[nfonts{()}repeat]def -/docsave save def -}def - -% character outcalls -/oc{ - /pswid exch def /cc exch def /name exch def - /ditwid pswid fontsize mul resolution mul 72000 div def - /ditsiz fontsize resolution mul 72 div def - ocprocs name known{ocprocs name get exec}{name cb}ifelse -}def -/fractm [.65 0 0 .6 0 0] def -/fraction{ - /fden exch def /fnum exch def gsave /cf currentfont def - cf fractm makefont setfont 0 .3 dm 2 copy neg rmoveto - fnum show rmoveto currentfont cf setfont(\244)show setfont fden show - grestore ditwid 0 rmoveto -}def -/oce{grestore ditwid 0 rmoveto}def -/dm{ditsiz mul}def -/ocprocs 50 dict def ocprocs begin -(14){(1)(4)fraction}def -(12){(1)(2)fraction}def -(34){(3)(4)fraction}def -(13){(1)(3)fraction}def -(23){(2)(3)fraction}def -(18){(1)(8)fraction}def -(38){(3)(8)fraction}def -(58){(5)(8)fraction}def -(78){(7)(8)fraction}def -(sr){gsave 0 .06 dm rmoveto(\326)show oce}def -(is){gsave 0 .15 dm rmoveto(\362)show oce}def -(->){gsave 0 .02 dm rmoveto(\256)show oce}def -(<-){gsave 0 .02 dm rmoveto(\254)show oce}def -(==){gsave 0 .05 dm rmoveto(\272)show oce}def -(uc){gsave currentpoint 400 .009 dm mul add translate - 8 -8 scale ucseal oce}def -end - -% an attempt at a PostScript FONT to implement ditroff special chars -% this will enable us to -% cache the little buggers -% generate faster, more compact PS out of psdit -% confuse everyone (including myself)! -50 dict dup begin -/FontType 3 def -/FontName /DIThacks def -/FontMatrix [.001 0 0 .001 0 0] def -/FontBBox [-260 -260 900 900] def% a lie but ... -/Encoding 256 array def -0 1 255{Encoding exch /.notdef put}for -Encoding - dup 8#040/space put %space - dup 8#110/rc put %right ceil - dup 8#111/lt put %left top curl - dup 8#112/bv put %bold vert - dup 8#113/lk put %left mid curl - dup 8#114/lb put %left bot curl - dup 8#115/rt put %right top curl - dup 8#116/rk put %right mid curl - dup 8#117/rb put %right bot curl - dup 8#120/rf put %right floor - dup 8#121/lf put %left floor - dup 8#122/lc put %left ceil - dup 8#140/sq put %square - dup 8#141/bx put %box - dup 8#142/ci put %circle - dup 8#143/br put %box rule - dup 8#144/rn put %root extender - dup 8#145/vr put %vertical rule - dup 8#146/ob put %outline bullet - dup 8#147/bu put %bullet - dup 8#150/ru put %rule - dup 8#151/ul put %underline - pop -/DITfd 100 dict def -/BuildChar{0 begin - /cc exch def /fd exch def - /charname fd /Encoding get cc get def - /charwid fd /Metrics get charname get def - /charproc fd /CharProcs get charname get def - charwid 0 fd /FontBBox get aload pop setcachedevice - 2 setlinejoin 40 setlinewidth - newpath 0 0 moveto gsave charproc grestore - end}def -/BuildChar load 0 DITfd put -/CharProcs 50 dict def -CharProcs begin -/space{}def -/.notdef{}def -/ru{500 0 rls}def -/rn{0 840 moveto 500 0 rls}def -/vr{0 800 moveto 0 -770 rls}def -/bv{0 800 moveto 0 -1000 rls}def -/br{0 840 moveto 0 -1000 rls}def -/ul{0 -140 moveto 500 0 rls}def -/ob{200 250 rmoveto currentpoint newpath 200 0 360 arc closepath stroke}def -/bu{200 250 rmoveto currentpoint newpath 200 0 360 arc closepath fill}def -/sq{80 0 rmoveto currentpoint dround newpath moveto - 640 0 rlineto 0 640 rlineto -640 0 rlineto closepath stroke}def -/bx{80 0 rmoveto currentpoint dround newpath moveto - 640 0 rlineto 0 640 rlineto -640 0 rlineto closepath fill}def -/ci{500 360 rmoveto currentpoint newpath 333 0 360 arc - 50 setlinewidth stroke}def - -/lt{0 -200 moveto 0 550 rlineto currx 800 2cx s4 add exch s4 a4p stroke}def -/lb{0 800 moveto 0 -550 rlineto currx -200 2cx s4 add exch s4 a4p stroke}def -/rt{0 -200 moveto 0 550 rlineto currx 800 2cx s4 sub exch s4 a4p stroke}def -/rb{0 800 moveto 0 -500 rlineto currx -200 2cx s4 sub exch s4 a4p stroke}def -/lk{0 800 moveto 0 300 -300 300 s4 arcto pop pop 1000 sub - 0 300 4 2 roll s4 a4p 0 -200 lineto stroke}def -/rk{0 800 moveto 0 300 s2 300 s4 arcto pop pop 1000 sub - 0 300 4 2 roll s4 a4p 0 -200 lineto stroke}def -/lf{0 800 moveto 0 -1000 rlineto s4 0 rls}def -/rf{0 800 moveto 0 -1000 rlineto s4 neg 0 rls}def -/lc{0 -200 moveto 0 1000 rlineto s4 0 rls}def -/rc{0 -200 moveto 0 1000 rlineto s4 neg 0 rls}def -end - -/Metrics 50 dict def Metrics begin -/.notdef 0 def -/space 500 def -/ru 500 def -/br 0 def -/lt 416 def -/lb 416 def -/rt 416 def -/rb 416 def -/lk 416 def -/rk 416 def -/rc 416 def -/lc 416 def -/rf 416 def -/lf 416 def -/bv 416 def -/ob 350 def -/bu 350 def -/ci 750 def -/bx 750 def -/sq 750 def -/rn 500 def -/ul 500 def -/vr 0 def -end - -DITfd begin -/s2 500 def /s4 250 def /s3 333 def -/a4p{arcto pop pop pop pop}def -/2cx{2 copy exch}def -/rls{rlineto stroke}def -/currx{currentpoint pop}def -/dround{transform round exch round exch itransform} def -end -end -/DIThacks exch definefont pop -ditstart -(psc)xT -576 1 1 xr -1(Times-Roman)xf 1 f -2(Times-Italic)xf 2 f -3(Times-Bold)xf 3 f -4(Times-BoldItalic)xf 4 f -5(Helvetica)xf 5 f -6(Helvetica-Bold)xf 6 f -7(Courier)xf 7 f -8(Courier-Bold)xf 8 f -9(Symbol)xf 9 f -10(DIThacks)xf 10 f -10 s -1 f -xi -%%EndProlog - -%%Page: 1 1 -10 s 10 xH 0 xS 1 f -3 f -14 s -1205 1206(LIBTP:)N -1633(Portable,)X -2100(M)X -2206(odular)X -2551(Transactions)X -3202(for)X -3374(UNIX)X -1 f -11 s -3661 1162(1)N -2 f -12 s -2182 1398(Margo)N -2467(Seltzer)X -2171 1494(Michael)N -2511(Olson)X -1800 1590(University)N -2225(of)X -2324(California,)X -2773(Berkeley)X -3 f -2277 1878(Abstract)N -1 f -10 s -755 2001(Transactions)N -1198(provide)X -1475(a)X -1543(useful)X -1771(programming)X -2239(paradigm)X -2574(for)X -2700(maintaining)X -3114(logical)X -3364(consistency,)X -3790(arbitrating)X -4156(con-)X -555 2091(current)N -808(access,)X -1059(and)X -1200(managing)X -1540(recovery.)X -1886(In)X -1977(traditional)X -2330(UNIX)X -2555(systems,)X -2852(the)X -2974(only)X -3140(easy)X -3307(way)X -3465(of)X -3556(using)X -3753(transactions)X -4160(is)X -4237(to)X -555 2181(purchase)N -876(a)X -947(database)X -1258(system.)X -1554(Such)X -1748(systems)X -2035(are)X -2168(often)X -2367(slow,)X -2572(costly,)X -2817(and)X -2967(may)X -3139(not)X -3275(provide)X -3554(the)X -3686(exact)X -3890(functionality)X -555 2271(desired.)N -848(This)X -1011(paper)X -1210(presents)X -1493(the)X -1611(design,)X -1860(implementation,)X -2402(and)X -2538(performance)X -2965(of)X -3052(LIBTP,)X -3314(a)X -3370(simple,)X -3623(non-proprietary)X -4147(tran-)X -555 2361(saction)N -809(library)X -1050(using)X -1249(the)X -1373(4.4BSD)X -1654(database)X -1957(access)X -2189(routines)X -2473(\()X -3 f -2500(db)X -1 f -2588(\(3\)\).)X -2775(On)X -2899(a)X -2961(conventional)X -3401(transaction)X -3779(processing)X -4148(style)X -555 2451(benchmark,)N -959(its)X -1061(performance)X -1495(is)X -1575(approximately)X -2065(85%)X -2239(that)X -2386(of)X -2480(the)X -2604(database)X -2907(access)X -3139(routines)X -3423(without)X -3693(transaction)X -4071(protec-)X -555 2541(tion,)N -725(200%)X -938(that)X -1084(of)X -1177(using)X -3 f -1376(fsync)X -1 f -1554(\(2\))X -1674(to)X -1761(commit)X -2030(modi\256cations)X -2490(to)X -2577(disk,)X -2755(and)X -2896(125%)X -3108(that)X -3253(of)X -3345(a)X -3406(commercial)X -3810(relational)X -4138(data-)X -555 2631(base)N -718(system.)X -3 f -555 2817(1.)N -655(Introduction)X -1 f -755 2940(Transactions)N -1186(are)X -1306(used)X -1474(in)X -1557(database)X -1855(systems)X -2129(to)X -2212(enable)X -2443(concurrent)X -2807(users)X -2992(to)X -3074(apply)X -3272(multi-operation)X -3790(updates)X -4055(without)X -555 3030(violating)N -863(the)X -985(integrity)X -1280(of)X -1371(the)X -1493(database.)X -1814(They)X -2003(provide)X -2271(the)X -2392(properties)X -2736(of)X -2826(atomicity,)X -3171(consistency,)X -3588(isolation,)X -3906(and)X -4045(durabil-)X -555 3120(ity.)N -701(By)X -816(atomicity,)X -1160(we)X -1276(mean)X -1472(that)X -1614(the)X -1734(set)X -1845(of)X -1934(updates)X -2200(comprising)X -2581(a)X -2638(transaction)X -3011(must)X -3187(be)X -3284(applied)X -3541(as)X -3629(a)X -3686(single)X -3898(unit;)X -4085(that)X -4226(is,)X -555 3210(they)N -714(must)X -890(either)X -1094(all)X -1195(be)X -1292(applied)X -1549(to)X -1632(the)X -1751(database)X -2049(or)X -2137(all)X -2238(be)X -2335(absent.)X -2601(Consistency)X -3013(requires)X -3293(that)X -3434(a)X -3491(transaction)X -3864(take)X -4019(the)X -4138(data-)X -555 3300(base)N -725(from)X -908(one)X -1051(logically)X -1358(consistent)X -1704(state)X -1877(to)X -1965(another.)X -2272(The)X -2423(property)X -2721(of)X -2814(isolation)X -3115(requires)X -3400(that)X -3546(concurrent)X -3916(transactions)X -555 3390(yield)N -750(results)X -994(which)X -1225(are)X -1358(indistinguishable)X -1938(from)X -2128(the)X -2260(results)X -2503(which)X -2733(would)X -2967(be)X -3077(obtained)X -3387(by)X -3501(running)X -3784(the)X -3916(transactions)X -555 3480(sequentially.)N -1002(Finally,)X -1268(durability)X -1599(requires)X -1878(that)X -2018(once)X -2190(transactions)X -2593(have)X -2765(been)X -2937(committed,)X -3319(their)X -3486(results)X -3715(must)X -3890(be)X -3986(preserved)X -555 3570(across)N -776(system)X -1018(failures)X -1279([TPCB90].)X -755 3693(Although)N -1080(these)X -1268(properties)X -1612(are)X -1734(most)X -1912(frequently)X -2265(discussed)X -2595(in)X -2680(the)X -2801(context)X -3060(of)X -3150(databases,)X -3501(they)X -3661(are)X -3782(useful)X -4000(program-)X -555 3783(ming)N -750(paradigms)X -1114(for)X -1238(more)X -1433(general)X -1700(purpose)X -1984(applications.)X -2441(There)X -2659(are)X -2788(several)X -3046(different)X -3353(situations)X -3689(where)X -3916(transactions)X -555 3873(can)N -687(be)X -783(used)X -950(to)X -1032(replace)X -1285(current)X -1533(ad-hoc)X -1772(mechanisms.)X -755 3996(One)N -910(situation)X -1206(is)X -1280(when)X -1475(multiple)X -1762(\256les)X -1916(or)X -2004(parts)X -2181(of)X -2269(\256les)X -2422(need)X -2594(to)X -2676(be)X -2772(updated)X -3046(in)X -3128(an)X -3224(atomic)X -3462(fashion.)X -3758(For)X -3889(example,)X -4201(the)X -555 4086(traditional)N -907(UNIX)X -1131(\256le)X -1256(system)X -1501(uses)X -1661(ordering)X -1955(constraints)X -2324(to)X -2408(achieve)X -2676(recoverability)X -3144(in)X -3228(the)X -3348(face)X -3505(of)X -3594(crashes.)X -3893(When)X -4107(a)X -4165(new)X -555 4176(\256le)N -678(is)X -752(created,)X -1026(its)X -1122(inode)X -1321(is)X -1395(written)X -1642(to)X -1724(disk)X -1877(before)X -2103(the)X -2221(new)X -2375(\256le)X -2497(is)X -2570(added)X -2782(to)X -2864(the)X -2982(directory)X -3292(structure.)X -3633(This)X -3795(guarantees)X -4159(that,)X -555 4266(if)N -627(the)X -748(system)X -993(crashes)X -1253(between)X -1544(the)X -1665(two)X -1808(I/O's,)X -2016(the)X -2137(directory)X -2450(does)X -2620(not)X -2744(contain)X -3002(a)X -3060 0.4531(reference)AX -3383(to)X -3467(an)X -3565(invalid)X -3809(inode.)X -4049(In)X -4138(actu-)X -555 4356(ality,)N -741(the)X -863(desired)X -1119(effect)X -1326(is)X -1402(that)X -1545(these)X -1733(two)X -1876(updates)X -2144(have)X -2319(the)X -2440(transactional)X -2873(property)X -3168(of)X -3258(atomicity)X -3583(\(either)X -3816(both)X -3981(writes)X -4200(are)X -555 4446(visible)N -790(or)X -879(neither)X -1124(is\).)X -1266(Rather)X -1501(than)X -1660(building)X -1947(special)X -2191(purpose)X -2466(recovery)X -2769(mechanisms)X -3186(into)X -3331(the)X -3450(\256le)X -3573(system)X -3816(or)X -3904(related)X -4144(tools)X -555 4536(\()N -2 f -582(e.g.)X -3 f -726(fsck)X -1 f -864(\(8\)\),)X -1033(one)X -1177(could)X -1383(use)X -1518(general)X -1783(purpose)X -2064(transaction)X -2443(recovery)X -2752(protocols)X -3077(after)X -3252(system)X -3501(failure.)X -3778(Any)X -3943(application)X -555 4626(that)N -705(needs)X -918(to)X -1010(keep)X -1192(multiple,)X -1508(related)X -1757(\256les)X -1920(\(or)X -2044(directories\))X -2440(consistent)X -2790(should)X -3032(do)X -3141(so)X -3241(using)X -3443(transactions.)X -3895(Source)X -4147(code)X -555 4716(control)N -805(systems,)X -1101(such)X -1271(as)X -1361(RCS)X -1534(and)X -1673(SCCS,)X -1910(should)X -2146(use)X -2276(transaction)X -2651(semantics)X -2990(to)X -3075(allow)X -3276(the)X -3397(``checking)X -3764(in'')X -3903(of)X -3992(groups)X -4232(of)X -555 4806(related)N -801(\256les.)X -1001(In)X -1095(this)X -1237(way,)X -1418(if)X -1493(the)X -1617 0.2841(``check-in'')AX -2028(fails,)X -2212(the)X -2336(transaction)X -2714(may)X -2878(be)X -2980(aborted,)X -3267(backing)X -3547(out)X -3675(the)X -3799(partial)X -4030(``check-)X -555 4896(in'')N -691(leaving)X -947(the)X -1065(source)X -1295(repository)X -1640(in)X -1722(a)X -1778(consistent)X -2118(state.)X -755 5019(A)N -842(second)X -1094(situation)X -1398(where)X -1624(transactions)X -2036(can)X -2177(be)X -2282(used)X -2458(to)X -2549(replace)X -2811(current)X -3068(ad-hoc)X -3316(mechanisms)X -3741(is)X -3822(in)X -3912(applications)X -555 5109(where)N -776(concurrent)X -1144(updates)X -1413(to)X -1499(a)X -1559(shared)X -1793(\256le)X -1919(are)X -2042(desired,)X -2318(but)X -2444(there)X -2629(is)X -2706(logical)X -2948(consistency)X -3345(of)X -3435(the)X -3556(data)X -3713(which)X -3932(needs)X -4138(to)X -4223(be)X -555 5199(preserved.)N -928(For)X -1059(example,)X -1371(when)X -1565(the)X -1683(password)X -2006(\256le)X -2128(is)X -2201(updated,)X -2495(\256le)X -2617(locking)X -2877(is)X -2950(used)X -3117(to)X -3199(disallow)X -3490(concurrent)X -3854(access.)X -4120(Tran-)X -555 5289(saction)N -804(semantics)X -1142(on)X -1244(the)X -1364(password)X -1689(\256les)X -1844(would)X -2066(allow)X -2266(concurrent)X -2632(updates,)X -2919(while)X -3119(preserving)X -3479(the)X -3598(logical)X -3837(consistency)X -4232(of)X -555 5379(the)N -681(password)X -1012(database.)X -1357(Similarly,)X -1702(UNIX)X -1930(utilities)X -2196(which)X -2419(rewrite)X -2674(\256les)X -2834(face)X -2996(a)X -3059(potential)X -3366(race)X -3528(condition)X -3857(between)X -4152(their)X -555 5469(rewriting)N -871(a)X -929(\256le)X -1053(and)X -1191(another)X -1453(process)X -1715(reading)X -1977(the)X -2096(\256le.)X -2259(For)X -2391(example,)X -2704(the)X -2823(compiler)X -3129(\(more)X -3342(precisely,)X -3673(the)X -3792(assembler\))X -4161(may)X -8 s -10 f -555 5541(hhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhh)N -5 s -1 f -727 5619(1)N -8 s -763 5644(To)N -850(appear)X -1035(in)X -1101(the)X -2 f -1195(Proceedings)X -1530(of)X -1596(the)X -1690(1992)X -1834(Winter)X -2024(Usenix)X -1 f -2201(,)X -2233(San)X -2345(Francisco,)X -2625(CA,)X -2746(January)X -2960(1992.)X - -2 p -%%Page: 2 2 -8 s 8 xH 0 xS 1 f -10 s -3 f -1 f -555 630(have)N -737(to)X -829(rewrite)X -1087(a)X -1152(\256le)X -1283(to)X -1374(which)X -1599(it)X -1672(has)X -1808(write)X -2002(permission)X -2382(in)X -2473(a)X -2538(directory)X -2857(to)X -2948(which)X -3173(it)X -3246(does)X -3422(not)X -3553(have)X -3734(write)X -3928(permission.)X -555 720(While)N -779(the)X -904(``.o'')X -1099(\256le)X -1228(is)X -1308(being)X -1513(written,)X -1787(another)X -2055(utility)X -2272(such)X -2446(as)X -3 f -2540(nm)X -1 f -2651(\(1\))X -2772(or)X -3 f -2866(ar)X -1 f -2942(\(1\))X -3063(may)X -3228(read)X -3394(the)X -3519(\256le)X -3648(and)X -3791(produce)X -4077(invalid)X -555 810(results)N -790(since)X -981(the)X -1105(\256le)X -1233(has)X -1366(not)X -1494(been)X -1672(completely)X -2054(written.)X -2347(Currently,)X -2700(some)X -2895(utilities)X -3160(use)X -3293(special)X -3542(purpose)X -3821(code)X -3998(to)X -4085(handle)X -555 900(such)N -722(cases)X -912(while)X -1110(others)X -1326(ignore)X -1551(the)X -1669(problem)X -1956(and)X -2092(force)X -2278(users)X -2463(to)X -2545(live)X -2685(with)X -2847(the)X -2965(consequences.)X -755 1023(In)N -845(this)X -983(paper,)X -1205(we)X -1322(present)X -1577(a)X -1635(simple)X -1870(library)X -2106(which)X -2324(provides)X -2622(transaction)X -2996(semantics)X -3334(\(atomicity,)X -3705(consistency,)X -4121(isola-)X -555 1113(tion,)N -720(and)X -857(durability\).)X -1236(The)X -1382(4.4BSD)X -1658(database)X -1956(access)X -2182(methods)X -2473(have)X -2645(been)X -2817(modi\256ed)X -3121(to)X -3203(use)X -3330(this)X -3465(library,)X -3719(optionally)X -4063(provid-)X -555 1203(ing)N -682(shared)X -917(buffer)X -1139(management)X -1574(between)X -1867(applications,)X -2298(locking,)X -2582(and)X -2722(transaction)X -3098(semantics.)X -3478(Any)X -3640(UNIX)X -3865(program)X -4161(may)X -555 1293(transaction)N -930(protect)X -1176(its)X -1274(data)X -1430(by)X -1532(requesting)X -1888(transaction)X -2262(protection)X -2609(with)X -2773(the)X -3 f -2893(db)X -1 f -2981(\(3\))X -3097(library)X -3333(or)X -3422(by)X -3524(adding)X -3764(appropriate)X -4152(calls)X -555 1383(to)N -646(the)X -773(transaction)X -1154(manager,)X -1480(buffer)X -1706(manager,)X -2032(lock)X -2199(manager,)X -2525(and)X -2670(log)X -2801(manager.)X -3147(The)X -3301(library)X -3543(routines)X -3829(may)X -3995(be)X -4099(linked)X -555 1473(into)N -708(the)X -834(host)X -995(application)X -1379(and)X -1523(called)X -1743(by)X -1851(subroutine)X -2217(interface,)X -2547(or)X -2642(they)X -2808(may)X -2974(reside)X -3194(in)X -3284(a)X -3348(separate)X -3640(server)X -3865(process.)X -4174(The)X -555 1563(server)N -772(architecture)X -1172(provides)X -1468(for)X -1582(network)X -1865(access)X -2091(and)X -2227(better)X -2430(protection)X -2775(mechanisms.)X -3 f -555 1749(2.)N -655(Related)X -938(Work)X -1 f -755 1872(There)N -1000(has)X -1164(been)X -1373(much)X -1608(discussion)X -1998(in)X -2117(recent)X -2371(years)X -2597(about)X -2831(new)X -3021(transaction)X -3429(models)X -3716(and)X -3888(architectures)X -555 1962 0.1172([SPEC88][NODI90][CHEN91][MOHA91].)AN -2009(Much)X -2220(of)X -2310(this)X -2448(work)X -2636(focuses)X -2900(on)X -3003(new)X -3160(ways)X -3348(to)X -3433(model)X -3656(transactions)X -4062(and)X -4201(the)X -555 2052(interactions)N -953(between)X -1245(them,)X -1449(while)X -1651(the)X -1772(work)X -1960(presented)X -2291(here)X -2453(focuses)X -2717(on)X -2820(the)X -2941(implementation)X -3466(and)X -3605(performance)X -4035(of)X -4125(tradi-)X -555 2142(tional)N -757(transaction)X -1129(techniques)X -1492(\(write-ahead)X -1919(logging)X -2183(and)X -2319(two-phase)X -2669(locking\))X -2956(on)X -3056(a)X -3112(standard)X -3404(operating)X -3727(system)X -3969(\(UNIX\).)X -755 2265(Such)N -947(traditional)X -1308(operating)X -1643(systems)X -1928(are)X -2059(often)X -2256(criticized)X -2587(for)X -2713(their)X -2892(inability)X -3190(to)X -3283(perform)X -3573(transaction)X -3956(processing)X -555 2355(adequately.)N -971([STON81])X -1342(cites)X -1517(three)X -1706(main)X -1894(areas)X -2088(of)X -2183(inadequate)X -2559(support:)X -2849(buffer)X -3074(management,)X -3532(the)X -3658(\256le)X -3788(system,)X -4058(and)X -4201(the)X -555 2445(process)N -823(structure.)X -1191(These)X -1410(arguments)X -1771(are)X -1897(summarized)X -2316(in)X -2405(table)X -2587(one.)X -2769(Fortunately,)X -3184(much)X -3388(has)X -3521(changed)X -3815(since)X -4006(1981.)X -4232(In)X -555 2535(the)N -683(area)X -848(of)X -945(buffer)X -1172(management,)X -1632(most)X -1817(UNIX)X -2048(systems)X -2331(provide)X -2606(the)X -2734(ability)X -2968(to)X -3060(memory)X -3357(map)X -3525(\256les,)X -3708(thus)X -3870(obviating)X -4201(the)X -555 2625(need)N -734(for)X -855(a)X -918(copy)X -1101(between)X -1396(kernel)X -1624(and)X -1766(user)X -1926(space.)X -2171(If)X -2251(a)X -2313(database)X -2616(system)X -2864(is)X -2943(going)X -3151(to)X -3239(use)X -3372(the)X -3496(\256le)X -3624(system)X -3872(buffer)X -4095(cache,)X -555 2715(then)N -719(a)X -781(system)X -1029(call)X -1171(is)X -1250(required.)X -1584(However,)X -1924(if)X -1998(buffering)X -2322(is)X -2400(provided)X -2710(at)X -2793(user)X -2952(level)X -3133(using)X -3331(shared)X -3566(memory,)X -3878(as)X -3970(in)X -4057(LIBTP,)X -555 2805(buffer)N -776(management)X -1210(is)X -1287(only)X -1452(as)X -1542(slow)X -1716(as)X -1806(access)X -2035(to)X -2120(shared)X -2353(memory)X -2643(and)X -2782(any)X -2921(replacement)X -3337(algorithm)X -3671(may)X -3832(be)X -3931(used.)X -4121(Since)X -555 2895(multiple)N -849(processes)X -1185(can)X -1325(access)X -1559(the)X -1685(shared)X -1923(data,)X -2105(prefetching)X -2499(may)X -2665(be)X -2769(accomplished)X -3238(by)X -3346(separate)X -3638(processes)X -3973(or)X -4067(threads)X -555 2985(whose)N -782(sole)X -932(purpose)X -1207(is)X -1281(to)X -1364(prefetch)X -1649(pages)X -1853(and)X -1990(wait)X -2149(on)X -2250(them.)X -2471(There)X -2680(is)X -2754(still)X -2894(no)X -2995(way)X -3150(to)X -3233(enforce)X -3496(write)X -3682(ordering)X -3975(other)X -4161(than)X -555 3075(keeping)N -829(pages)X -1032(in)X -1114(user)X -1268(memory)X -1555(and)X -1691(using)X -1884(the)X -3 f -2002(fsync)X -1 f -2180(\(3\))X -2294(system)X -2536(call)X -2672(to)X -2754(perform)X -3033(synchronous)X -3458(writes.)X -755 3198(In)N -845(the)X -966(area)X -1124(of)X -1214(\256le)X -1339(systems,)X -1635(the)X -1756(fast)X -1895(\256le)X -2020(system)X -2265(\(FFS\))X -2474([MCKU84])X -2871(allows)X -3103(allocation)X -3442(in)X -3527(units)X -3704(up)X -3806(to)X -3890(64KBytes)X -4232(as)X -555 3288(opposed)N -846(to)X -932(the)X -1054(4KByte)X -1327(and)X -1466(8KByte)X -1738(\256gures)X -1979(quoted)X -2220(in)X -2305([STON81].)X -2711(The)X -2859(measurements)X -3341(in)X -3426(this)X -3564(paper)X -3766(were)X -3946(taken)X -4143(from)X -555 3378(an)N -655(8KByte)X -928(FFS,)X -1104(but)X -1230(as)X -1320(LIBTP)X -1565(runs)X -1726(exclusively)X -2114(in)X -2199(user)X -2356(space,)X -2578(there)X -2762(is)X -2838(nothing)X -3105(to)X -3190(prevent)X -3454(it)X -3521(from)X -3700(being)X -3901(run)X -4031(on)X -4134(other)X -555 3468(UNIX)N -776(compatible)X -1152(\256le)X -1274(systems)X -1547(\(e.g.)X -1710(log-structured)X -2180([ROSE91],)X -2558(extent-based,)X -3004(or)X -3091(multi-block)X -3484([SELT91]\).)X -755 3591(Finally,)N -1029(with)X -1199(regard)X -1433(to)X -1523(the)X -1648(process)X -1916(structure,)X -2244(neither)X -2494(context)X -2757(switch)X -2993(time)X -3162(nor)X -3296(scheduling)X -3670(around)X -3920(semaphores)X -555 3681(seems)N -785(to)X -881(affect)X -1099(the)X -1231(system)X -1487(performance.)X -1968(However,)X -2317(the)X -2449(implementation)X -2984(of)X -3084(semaphores)X -3496(can)X -3641(impact)X -3892(performance)X -555 3771(tremendously.)N -1051(This)X -1213(is)X -1286(discussed)X -1613(in)X -1695(more)X -1880(detail)X -2078(in)X -2160(section)X -2407(4.3.)X -755 3894(The)N -908(Tuxedo)X -1181(system)X -1431(from)X -1615(AT&T)X -1861(is)X -1941(a)X -2004(transaction)X -2383(manager)X -2687(which)X -2910(coordinates)X -3307(distributed)X -3676(transaction)X -4055(commit)X -555 3984(from)N -738(a)X -801(variety)X -1051(of)X -1145(different)X -1449(local)X -1632(transaction)X -2011(managers.)X -2386(At)X -2493(this)X -2634(time,)X -2822(LIBTP)X -3070(does)X -3243(not)X -3371(have)X -3549(its)X -3650(own)X -3814(mechanism)X -4205(for)X -555 4074(distributed)N -942(commit)X -1231(processing,)X -1639(but)X -1786(could)X -2009(be)X -2130(used)X -2322(as)X -2434(a)X -2515(local)X -2716(transaction)X -3113(agent)X -3331(by)X -3455(systems)X -3752(such)X -3943(as)X -4054(Tuxedo)X -555 4164([ANDR89].)N -10 f -863 4393(i)N -870(iiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii)X -1 f -903 4483(Buffer)N -1133(Management)X -10 f -1672(g)X -1 f -1720(Data)X -1892(must)X -2067(be)X -2163(copied)X -2397(between)X -2685(kernel)X -2906(space)X -3105(and)X -3241(user)X -3395(space.)X -10 f -1672 4573(g)N -1 f -1720(Buffer)X -1950(pool)X -2112(access)X -2338(is)X -2411(too)X -2533(slow.)X -10 f -1672 4663(g)N -1 f -1720(There)X -1928(is)X -2001(no)X -2101(way)X -2255(to)X -2337(request)X -2589(prefetch.)X -10 f -1672 4753(g)N -1 f -1720(Replacement)X -2159(is)X -2232(usually)X -2483(LRU)X -2663(which)X -2879(may)X -3037(be)X -3133(suboptimal)X -3508(for)X -3622(databases.)X -10 f -1672 4843(g)N -1 f -1720(There)X -1928(is)X -2001(no)X -2101(way)X -2255(to)X -2337(guarantee)X -2670(write)X -2855(ordering.)X -10 f -863 4853(i)N -870(iiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii)X -1 f -903 4943(File)N -1047(System)X -10 f -1672(g)X -1 f -1720(Allocation)X -2078(is)X -2151(done)X -2327(in)X -2409(small)X -2602(blocks)X -2831(\(usually)X -3109(4K)X -3227(or)X -3314(8K\).)X -10 f -1672 5033(g)N -1 f -1720(Logical)X -1985(organization)X -2406(of)X -2493(\256les)X -2646(is)X -2719(redundantly)X -3122(expressed.)X -10 f -863 5043(i)N -870(iiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii)X -1 f -903 5133(Process)N -1168(Structure)X -10 f -1672(g)X -1 f -1720(Context)X -1993(switching)X -2324(and)X -2460(message)X -2752(passing)X -3012(are)X -3131(too)X -3253(slow.)X -10 f -1672 5223(g)N -1 f -1720(A)X -1798(process)X -2059(may)X -2217(be)X -2313(descheduled)X -2730(while)X -2928(holding)X -3192(a)X -3248(semaphore.)X -10 f -863 5233(i)N -870(iiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii)X -863(c)X -5193(c)Y -5113(c)Y -5033(c)Y -4953(c)Y -4873(c)Y -4793(c)Y -4713(c)Y -4633(c)Y -4553(c)Y -4473(c)Y -3990 5233(c)N -5193(c)Y -5113(c)Y -5033(c)Y -4953(c)Y -4873(c)Y -4793(c)Y -4713(c)Y -4633(c)Y -4553(c)Y -4473(c)Y -3 f -1156 5446(Table)N -1371(One:)X -1560(Shortcomings)X -2051(of)X -2138(UNIX)X -2363(transaction)X -2770(support)X -3056(cited)X -3241(in)X -3327([STON81].)X - -3 p -%%Page: 3 3 -10 s 10 xH 0 xS 3 f -1 f -755 630(The)N -901(transaction)X -1274(architecture)X -1675(presented)X -2004(in)X -2087([YOUN91])X -2474(is)X -2548(very)X -2712(similar)X -2955(to)X -3038(that)X -3179(implemented)X -3618(in)X -3701(the)X -3820(LIBTP.)X -4103(While)X -555 720([YOUN91])N -947(presents)X -1236(a)X -1298(model)X -1524(for)X -1644(providing)X -1981(transaction)X -2359(services,)X -2663(this)X -2803(paper)X -3007(focuses)X -3273(on)X -3378(the)X -3501(implementation)X -4028(and)X -4169(per-)X -555 810(formance)N -881(of)X -970(a)X -1028(particular)X -1358(system.)X -1642(In)X -1731(addition,)X -2034(we)X -2149(provide)X -2415(detailed)X -2690(comparisons)X -3116(with)X -3279(alternative)X -3639(solutions:)X -3970(traditional)X -555 900(UNIX)N -776(services)X -1055(and)X -1191(commercial)X -1590(database)X -1887(management)X -2317(systems.)X -3 f -555 1086(3.)N -655(Architecture)X -1 f -755 1209(The)N -906(library)X -1146(is)X -1224(designed)X -1534(to)X -1621(provide)X -1891(well)X -2054(de\256ned)X -2315(interfaces)X -2653(to)X -2740(the)X -2863(services)X -3147(required)X -3440(for)X -3559(transaction)X -3936(processing.)X -555 1299(These)N -777(services)X -1066(are)X -1195(recovery,)X -1527(concurrency)X -1955(control,)X -2232(and)X -2378(the)X -2506(management)X -2946(of)X -3043(shared)X -3283(data.)X -3487(First)X -3663(we)X -3787(will)X -3941(discuss)X -4201(the)X -555 1389(design)N -795(tradeoffs)X -1112(in)X -1205(the)X -1334(selection)X -1650(of)X -1748(recovery,)X -2081(concurrency)X -2510(control,)X -2787(and)X -2933(buffer)X -3160(management)X -3600(implementations,)X -4183(and)X -555 1479(then)N -713(we)X -827(will)X -971(present)X -1223(the)X -1341(overall)X -1584(library)X -1818(architecture)X -2218(and)X -2354(module)X -2614(descriptions.)X -3 f -555 1665(3.1.)N -715(Design)X -966(Tradeoffs)X -1 f -3 f -555 1851(3.1.1.)N -775(Crash)X -1004(Recovery)X -1 f -755 1974(The)N -909(recovery)X -1220(protocol)X -1516(is)X -1598(responsible)X -1992(for)X -2115(providing)X -2455(the)X -2582(transaction)X -2963(semantics)X -3308(discussed)X -3644(earlier.)X -3919(There)X -4136(are)X -4263(a)X -555 2064(wide)N -739(range)X -946(of)X -1041(recovery)X -1351(protocols)X -1677(available)X -1995([HAER83],)X -2395(but)X -2525(we)X -2647(can)X -2786(crudely)X -3054(divide)X -3281(them)X -3468(into)X -3619(two)X -3766(main)X -3953(categories.)X -555 2154(The)N -706(\256rst)X -856(category)X -1159(records)X -1422(all)X -1528(modi\256cations)X -1989(to)X -2077(the)X -2201(database)X -2504(in)X -2592(a)X -2653(separate)X -2942(\256le,)X -3089(and)X -3230(uses)X -3393(this)X -3533(\256le)X -3660(\(log\))X -3841(to)X -3928(back)X -4105(out)X -4232(or)X -555 2244(reapply)N -825(these)X -1019(modi\256cations)X -1483(if)X -1561(a)X -1626(transaction)X -2007(aborts)X -2232(or)X -2328(the)X -2455(system)X -2706(crashes.)X -3012(We)X -3153(call)X -3298(this)X -3442(set)X -3560(the)X -3 f -3687(logging)X -3963(protocols)X -1 f -4279(.)X -555 2334(The)N -703(second)X -949(category)X -1249(avoids)X -1481(the)X -1602(use)X -1732(of)X -1822(a)X -1881(log)X -2006(by)X -2109(carefully)X -2418(controlling)X -2792(when)X -2989(data)X -3146(are)X -3268(written)X -3518(to)X -3603(disk.)X -3799(We)X -3934(call)X -4073(this)X -4210(set)X -555 2424(the)N -3 f -673(non-logging)X -1096(protocols)X -1 f -1412(.)X -755 2547(Non-logging)N -1185(protocols)X -1504(hold)X -1666(dirty)X -1837(buffers)X -2085(in)X -2167(main)X -2347(memory)X -2634(or)X -2721(temporary)X -3071(\256les)X -3224(until)X -3390(commit)X -3654(and)X -3790(then)X -3948(force)X -4134(these)X -555 2637(pages)N -769(to)X -862(disk)X -1026(at)X -1115(transaction)X -1498(commit.)X -1813(While)X -2040(we)X -2165(can)X -2308(use)X -2446(temporary)X -2807(\256les)X -2971(to)X -3064(hold)X -3237(dirty)X -3418(pages)X -3631(that)X -3781(may)X -3949(need)X -4131(to)X -4223(be)X -555 2727(evicted)N -810(from)X -988(memory)X -1277(during)X -1508(a)X -1566(long-running)X -2006(transaction,)X -2400(the)X -2520(only)X -2684(user-level)X -3023(mechanism)X -3410(to)X -3494(force)X -3682(pages)X -3887(to)X -3971(disk)X -4126(is)X -4201(the)X -3 f -555 2817(fsync)N -1 f -733(\(2\))X -850(system)X -1095(call.)X -1274(Unfortunately,)X -3 f -1767(fsync)X -1 f -1945(\(2\))X -2062(is)X -2138(an)X -2237(expensive)X -2581(system)X -2826(call)X -2965(in)X -3050(that)X -3193(it)X -3260(forces)X -3480(all)X -3583(pages)X -3789(of)X -3879(a)X -3938(\256le)X -4062(to)X -4146(disk,)X -555 2907(and)N -691(transactions)X -1094(that)X -1234(manage)X -1504(more)X -1689(than)X -1847(one)X -1983(\256le)X -2105(must)X -2280(issue)X -2460(one)X -2596(call)X -2732(per)X -2855(\256le.)X -755 3030(In)N -853(addition,)X -3 f -1166(fsync)X -1 f -1344(\(2\))X -1469(provides)X -1776(no)X -1887(way)X -2051(to)X -2143(control)X -2400(the)X -2528(order)X -2728(in)X -2820(which)X -3046(dirty)X -3227(pages)X -3440(are)X -3569(written)X -3826(to)X -3918(disk.)X -4121(Since)X -555 3120(non-logging)N -976(protocols)X -1304(must)X -1489(sometimes)X -1861(order)X -2061(writes)X -2287(carefully)X -2603([SULL92],)X -2987(they)X -3155(are)X -3284(dif\256cult)X -3567(to)X -3659(implement)X -4030(on)X -4139(Unix)X -555 3210(systems.)N -868(As)X -977(a)X -1033(result,)X -1251(we)X -1365(have)X -1537(chosen)X -1780(to)X -1862(implement)X -2224(a)X -2280(logging)X -2544(protocol.)X -755 3333(Logging)N -1050(protocols)X -1372(may)X -1534(be)X -1634(categorized)X -2029(based)X -2236(on)X -2340(how)X -2502(information)X -2904(is)X -2981(logged)X -3223(\(physically)X -3602(or)X -3692(logically\))X -4022(and)X -4161(how)X -555 3423(much)N -767(is)X -854(logged)X -1106(\(before)X -1373(images,)X -1654(after)X -1836(images)X -2097(or)X -2198(both\).)X -2441(In)X -3 f -2542(physical)X -2855(logging)X -1 f -3103(,)X -3157(images)X -3417(of)X -3517(complete)X -3844(physical)X -4144(units)X -555 3513(\(pages)N -786(or)X -874(buffers\))X -1150(are)X -1270(recorded,)X -1593(while)X -1792(in)X -3 f -1875(logical)X -2118(logging)X -1 f -2387(a)X -2444(description)X -2820(of)X -2907(the)X -3025(operation)X -3348(is)X -3421(recorded.)X -3763(Therefore,)X -4121(while)X -555 3603(we)N -675(may)X -839(record)X -1071(entire)X -1280(pages)X -1489(in)X -1577(a)X -1639(physical)X -1932(log,)X -2080(we)X -2200(need)X -2378(only)X -2546(record)X -2777(the)X -2900(records)X -3162(being)X -3365(modi\256ed)X -3674(in)X -3761(a)X -3822(logical)X -4065(log.)X -4232(In)X -555 3693(fact,)N -718(physical)X -1006(logging)X -1271(can)X -1404(be)X -1501(thought)X -1766(of)X -1854(as)X -1942(a)X -1999(special)X -2243(case)X -2403(of)X -2491(logical)X -2730(logging,)X -3015(since)X -3201(the)X -3320 0.3125(``records'')AX -3686(that)X -3827(we)X -3942(log)X -4065(in)X -4148(logi-)X -555 3783(cal)N -673(logging)X -941(might)X -1151(be)X -1251(physical)X -1542(pages.)X -1789(Since)X -1991(logical)X -2233(logging)X -2501(is)X -2578(both)X -2743(more)X -2931(space-ef\256cient)X -3423(and)X -3562(more)X -3750(general,)X -4030(we)X -4147(have)X -555 3873(chosen)N -798(it)X -862(for)X -976(our)X -1103(logging)X -1367(protocol.)X -755 3996(In)N -3 f -843(before-image)X -1315(logging)X -1 f -1563(,)X -1604(we)X -1719(log)X -1842(a)X -1899(copy)X -2076(of)X -2164(the)X -2283(data)X -2438(before)X -2665(the)X -2784(update,)X -3039(while)X -3238(in)X -3 f -3321(after-image)X -3739(logging)X -1 f -3987(,)X -4027(we)X -4141(log)X -4263(a)X -555 4086(copy)N -740(of)X -836(the)X -963(data)X -1126(after)X -1303(the)X -1429(update.)X -1711(If)X -1793(we)X -1915(log)X -2045(only)X -2215(before-images,)X -2723(then)X -2889(there)X -3078(is)X -3159(suf\256cient)X -3485(information)X -3891(in)X -3981(the)X -4107(log)X -4237(to)X -555 4176(allow)N -761(us)X -860(to)X -3 f -950(undo)X -1 f -1150(the)X -1276(transaction)X -1656(\(go)X -1791(back)X -1971(to)X -2061(the)X -2187(state)X -2361(represented)X -2759(by)X -2866(the)X -2991(before-image\).)X -3514(However,)X -3876(if)X -3952(the)X -4077(system)X -555 4266(crashes)N -814(and)X -952(a)X -1010(committed)X -1374(transaction's)X -1806(changes)X -2087(have)X -2261(not)X -2385(reached)X -2658(the)X -2778(disk,)X -2953(we)X -3068(have)X -3241(no)X -3342(means)X -3568(to)X -3 f -3651(redo)X -1 f -3828(the)X -3947(transaction)X -555 4356(\(reapply)N -849(the)X -973(updates\).)X -1311(Therefore,)X -1675(logging)X -1945(only)X -2113(before-images)X -2599(necessitates)X -3004(forcing)X -3262(dirty)X -3439(pages)X -3648(at)X -3732(commit)X -4002(time.)X -4210(As)X -555 4446(mentioned)N -913(above,)X -1145(forcing)X -1397(pages)X -1600(at)X -1678(commit)X -1942(is)X -2015(considered)X -2383(too)X -2505(costly.)X -755 4569(If)N -834(we)X -953(log)X -1080(only)X -1247(after-images,)X -1694(then)X -1857(there)X -2043(is)X -2121(suf\256cient)X -2444(information)X -2847(in)X -2934(the)X -3057(log)X -3184(to)X -3271(allow)X -3474(us)X -3570(to)X -3657(redo)X -3825(the)X -3947(transaction)X -555 4659(\(go)N -687(forward)X -967(to)X -1054(the)X -1177(state)X -1348(represented)X -1743(by)X -1847(the)X -1969(after-image\),)X -2411(but)X -2537(we)X -2655(do)X -2759(not)X -2885(have)X -3061(the)X -3183(information)X -3585(required)X -3877(to)X -3963(undo)X -4147(tran-)X -555 4749(sactions)N -845(which)X -1073(aborted)X -1346(after)X -1526(dirty)X -1709(pages)X -1924(were)X -2113(written)X -2372(to)X -2466(disk.)X -2670(Therefore,)X -3039(logging)X -3314(only)X -3487(after-images)X -3920(necessitates)X -555 4839(holding)N -819(all)X -919(dirty)X -1090(buffers)X -1338(in)X -1420(main)X -1600(memory)X -1887(until)X -2053(commit)X -2317(or)X -2404(writing)X -2655(them)X -2835(to)X -2917(a)X -2973(temporary)X -3323(\256le.)X -755 4962(Since)N -956(neither)X -1202(constraint)X -1541(\(forcing)X -1823(pages)X -2029(on)X -2132(commit)X -2399(or)X -2489(buffering)X -2811(pages)X -3016(until)X -3184(commit\))X -3477(was)X -3624(feasible,)X -3916(we)X -4032(chose)X -4237(to)X -555 5052(log)N -683(both)X -851(before)X -1083(and)X -1225(after)X -1399(images.)X -1672(The)X -1823(only)X -1991(remaining)X -2342(consideration)X -2800(is)X -2879(when)X -3079(changes)X -3363(get)X -3486(written)X -3738(to)X -3825(disk.)X -4023(Changes)X -555 5142(affect)N -764(both)X -931(data)X -1090(pages)X -1298(and)X -1438(the)X -1560(log.)X -1726(If)X -1804(the)X -1926(changed)X -2218(data)X -2376(page)X -2552(is)X -2629(written)X -2880(before)X -3110(the)X -3232(log)X -3358(page,)X -3554(and)X -3694(the)X -3816(system)X -4062(crashes)X -555 5232(before)N -787(the)X -911(log)X -1039(page)X -1217(is)X -1296(written,)X -1569(the)X -1693(log)X -1820(will)X -1969(contain)X -2230(insuf\256cient)X -2615(information)X -3018(to)X -3105(undo)X -3290(the)X -3413(change.)X -3706(This)X -3873(violates)X -4147(tran-)X -555 5322(saction)N -803(semantics,)X -1160(since)X -1346(some)X -1536(changed)X -1825(data)X -1980(pages)X -2184(may)X -2343(not)X -2466(have)X -2638(been)X -2810(written,)X -3077(and)X -3213(the)X -3331(database)X -3628(cannot)X -3862(be)X -3958(restored)X -4237(to)X -555 5412(its)N -650(pre-transaction)X -1152(state.)X -755 5535(The)N -914(log)X -1050(record)X -1290(describing)X -1658(an)X -1768(update)X -2016(must)X -2205(be)X -2315(written)X -2576(to)X -2672(stable)X -2893(storage)X -3159(before)X -3398(the)X -3529(modi\256ed)X -3846(page.)X -4071(This)X -4246(is)X -3 f -555 5625(write-ahead)N -992(logging)X -1 f -1240(.)X -1307(If)X -1388(log)X -1517(records)X -1781(are)X -1907(safely)X -2126(written)X -2380(to)X -2469(disk,)X -2649(data)X -2810(pages)X -3020(may)X -3185(be)X -3288(written)X -3542(at)X -3627(any)X -3770(time)X -3939(afterwards.)X -555 5715(This)N -721(means)X -950(that)X -1094(the)X -1216(only)X -1382(\256le)X -1508(that)X -1652(ever)X -1815(needs)X -2022(to)X -2108(be)X -2208(forced)X -2438(to)X -2524(disk)X -2681(is)X -2758(the)X -2880(log.)X -3046(Since)X -3248(the)X -3370(log)X -3495(is)X -3571(append-only,)X -4015(modi\256ed)X - -4 p -%%Page: 4 4 -10 s 10 xH 0 xS 1 f -3 f -1 f -555 630(pages)N -760(always)X -1005(appear)X -1242(at)X -1322(the)X -1442(end)X -1580(and)X -1718(may)X -1878(be)X -1976(written)X -2224(to)X -2307(disk)X -2461(ef\256ciently)X -2807(in)X -2890(any)X -3027(\256le)X -3150(system)X -3393(that)X -3534(favors)X -3756(sequential)X -4102(order-)X -555 720(ing)N -677(\()X -2 f -704(e.g.)X -1 f -820(,)X -860(FFS,)X -1032(log-structured)X -1502(\256le)X -1624(system,)X -1886(or)X -1973(an)X -2069(extent-based)X -2495(system\).)X -3 f -555 906(3.1.2.)N -775(Concurrency)X -1245(Control)X -1 f -755 1029(The)N -918(concurrency)X -1354(control)X -1619(protocol)X -1923(is)X -2013(responsible)X -2415(for)X -2546(maintaining)X -2965(consistency)X -3376(in)X -3475(the)X -3610(presence)X -3929(of)X -4033(multiple)X -555 1119(accesses.)N -897(There)X -1114(are)X -1242(several)X -1499(alternative)X -1867(solutions)X -2183(such)X -2358(as)X -2453(locking,)X -2741(optimistic)X -3088(concurrency)X -3514(control)X -3769([KUNG81],)X -4183(and)X -555 1209(timestamp)N -912(ordering)X -1208([BERN80].)X -1619(Since)X -1821(optimistic)X -2164(methods)X -2459(and)X -2599(timestamp)X -2956(ordering)X -3252(are)X -3374(generally)X -3696(more)X -3884(complex)X -4183(and)X -555 1299(restrict)N -804(concurrency)X -1228(without)X -1498(eliminating)X -1888(starvation)X -2230(or)X -2323(deadlocks,)X -2690(we)X -2810(chose)X -3018(two-phase)X -3373(locking)X -3638(\(2PL\).)X -3890(Strict)X -4088(2PL)X -4246(is)X -555 1389(suboptimal)N -935(for)X -1054(certain)X -1297(data)X -1455(structures)X -1791(such)X -1962(as)X -2053(B-trees)X -2309(because)X -2588(it)X -2656(can)X -2792(limit)X -2966(concurrency,)X -3408(so)X -3503(we)X -3621(use)X -3752(a)X -3812(special)X -4059(locking)X -555 1479(protocol)N -842(based)X -1045(on)X -1145(one)X -1281(described)X -1609(in)X -1691([LEHM81].)X -755 1602(The)N -901(B-tree)X -1123(locking)X -1384(protocol)X -1672(we)X -1787(implemented)X -2226(releases)X -2502(locks)X -2691(at)X -2769(internal)X -3034(nodes)X -3241(in)X -3323(the)X -3441(tree)X -3582(as)X -3669(it)X -3733(descends.)X -4083(A)X -4161(lock)X -555 1692(on)N -658(an)X -757(internal)X -1025(page)X -1200(is)X -1276(always)X -1522(released)X -1808(before)X -2036(a)X -2094(lock)X -2254(on)X -2356(its)X -2453(child)X -2635(is)X -2710(obtained)X -3008(\(that)X -3177(is,)X -3272(locks)X -3463(are)X -3584(not)X -3 f -3708(coupled)X -1 f -3996([BAY77])X -555 1782(during)N -786(descent\).)X -1116(When)X -1330(a)X -1388(leaf)X -1531(\(or)X -1647(internal\))X -1941(page)X -2115(is)X -2190(split,)X -2369(a)X -2427(write)X -2614(lock)X -2774(is)X -2849(acquired)X -3148(on)X -3250(the)X -3370(parent)X -3593(before)X -3821(the)X -3941(lock)X -4100(on)X -4201(the)X -555 1872(just-split)N -855(page)X -1028(is)X -1102(released)X -1387(\(locks)X -1604(are)X -3 f -1724(coupled)X -1 f -2011(during)X -2241(ascent\).)X -2530(Write)X -2734(locks)X -2924(on)X -3025(internal)X -3291(pages)X -3495(are)X -3615(released)X -3899(immediately)X -555 1962(after)N -723(the)X -841(page)X -1013(is)X -1086(updated,)X -1380(but)X -1502(locks)X -1691(on)X -1791(leaf)X -1932(pages)X -2135(are)X -2254(held)X -2412(until)X -2578(the)X -2696(end)X -2832(of)X -2919(the)X -3037(transaction.)X -755 2085(Since)N -964(locks)X -1164(are)X -1294(released)X -1589(during)X -1828(descent,)X -2119(the)X -2247(structure)X -2558(of)X -2655(the)X -2783(tree)X -2934(may)X -3102(change)X -3360(above)X -3582(a)X -3648(node)X -3834(being)X -4042(used)X -4219(by)X -555 2175(some)N -752(process.)X -1061(If)X -1143(that)X -1291(process)X -1560(must)X -1743(later)X -1914(ascend)X -2161(the)X -2287(tree)X -2435(because)X -2717(of)X -2811(a)X -2874(page)X -3053(split,)X -3237(any)X -3380(such)X -3554(change)X -3809(must)X -3991(not)X -4120(cause)X -555 2265(confusion.)N -938(We)X -1077(use)X -1211(the)X -1336(technique)X -1675(described)X -2010(in)X -2099([LEHM81])X -2487(which)X -2710(exploits)X -2989(the)X -3113(ordering)X -3411(of)X -3504(data)X -3664(on)X -3770(a)X -3832(B-tree)X -4059(page)X -4237(to)X -555 2355(guarantee)N -888(that)X -1028(no)X -1128(process)X -1389(ever)X -1548(gets)X -1697(lost)X -1832(as)X -1919(a)X -1975(result)X -2173(of)X -2260(internal)X -2525(page)X -2697(updates)X -2962(made)X -3156(by)X -3256(other)X -3441(processes.)X -755 2478(If)N -836(a)X -899(transaction)X -1278(that)X -1425(updates)X -1697(a)X -1760(B-tree)X -1988(aborts,)X -2231(the)X -2356(user-visible)X -2757(changes)X -3043(to)X -3131(the)X -3255(tree)X -3402(must)X -3583(be)X -3685(rolled)X -3898(back.)X -4116(How-)X -555 2568(ever,)N -735(changes)X -1015(to)X -1097(the)X -1215(internal)X -1480(nodes)X -1687(of)X -1774(the)X -1892(tree)X -2033(need)X -2205(not)X -2327(be)X -2423(rolled)X -2630(back,)X -2822(since)X -3007(these)X -3192(pages)X -3395(contain)X -3651(no)X -3751(user-visible)X -4145(data.)X -555 2658(When)N -771(rolling)X -1008(back)X -1184(a)X -1244(transaction,)X -1640(we)X -1758(roll)X -1893(back)X -2069(all)X -2173(leaf)X -2318(page)X -2494(updates,)X -2783(but)X -2909(no)X -3013(internal)X -3281(insertions)X -3615(or)X -3705(page)X -3880(splits.)X -4111(In)X -4201(the)X -555 2748(worst)N -759(case,)X -944(this)X -1085(will)X -1235(leave)X -1431(a)X -1493(leaf)X -1640(page)X -1818(less)X -1964(than)X -2128(half)X -2279(full.)X -2456(This)X -2624(may)X -2788(cause)X -2993(poor)X -3166(space)X -3371(utilization,)X -3741(but)X -3869(does)X -4042(not)X -4170(lose)X -555 2838(user)N -709(data.)X -755 2961(Holding)N -1038(locks)X -1228(on)X -1329(leaf)X -1471(pages)X -1675(until)X -1842(transaction)X -2215(commit)X -2480(guarantees)X -2845(that)X -2986(no)X -3087(other)X -3273(process)X -3535(can)X -3668(insert)X -3866(or)X -3953(delete)X -4165(data)X -555 3051(that)N -711(has)X -854(been)X -1042(touched)X -1332(by)X -1448(this)X -1598(process.)X -1914(Rolling)X -2188(back)X -2375(insertions)X -2721(and)X -2872(deletions)X -3196(on)X -3311(leaf)X -3467(pages)X -3685(guarantees)X -4064(that)X -4219(no)X -555 3141(aborted)N -819(updates)X -1087(are)X -1209(ever)X -1371(visible)X -1607(to)X -1692(other)X -1880(transactions.)X -2326(Leaving)X -2612(page)X -2787(splits)X -2978(intact)X -3179(permits)X -3442(us)X -3536(to)X -3621(release)X -3867(internal)X -4134(write)X -555 3231(locks)N -744(early.)X -965(Thus)X -1145(transaction)X -1517(semantics)X -1853(are)X -1972(preserved,)X -2325(and)X -2461(locks)X -2650(are)X -2769(held)X -2927(for)X -3041(shorter)X -3284(periods.)X -755 3354(The)N -901(extra)X -1083(complexity)X -1464(introduced)X -1828(by)X -1929(this)X -2065(locking)X -2326(protocol)X -2614(appears)X -2881(substantial,)X -3264(but)X -3387(it)X -3452(is)X -3525(important)X -3856(for)X -3970(multi-user)X -555 3444(execution.)N -950(The)X -1118(bene\256ts)X -1410(of)X -1520(non-two-phase)X -2040(locking)X -2323(on)X -2446(B-trees)X -2721(are)X -2863(well)X -3044(established)X -3443(in)X -3548(the)X -3689(database)X -4009(literature)X -555 3534([BAY77],)N -899([LEHM81].)X -1320(If)X -1394(a)X -1450(process)X -1711(held)X -1869(locks)X -2058(until)X -2224(it)X -2288(committed,)X -2670(then)X -2828(a)X -2884(long-running)X -3322(update)X -3556(could)X -3754(lock)X -3912(out)X -4034(all)X -4134(other)X -555 3624(transactions)N -967(by)X -1076(preventing)X -1448(any)X -1593(other)X -1787(process)X -2057(from)X -2241(locking)X -2509(the)X -2635(root)X -2792(page)X -2972(of)X -3067(the)X -3193(tree.)X -3382(The)X -3535(B-tree)X -3764(locking)X -4032(protocol)X -555 3714(described)N -884(above)X -1096(guarantees)X -1460(that)X -1600(locks)X -1789(on)X -1889(internal)X -2154(pages)X -2357(are)X -2476(held)X -2634(for)X -2748(extremely)X -3089(short)X -3269(periods,)X -3545(thereby)X -3806(increasing)X -4156(con-)X -555 3804(currency.)N -3 f -555 3990(3.1.3.)N -775(Management)X -1245(of)X -1332(Shared)X -1596(Data)X -1 f -755 4113(Database)N -1075(systems)X -1353(permit)X -1587(many)X -1790(users)X -1980(to)X -2067(examine)X -2364(and)X -2505(update)X -2744(the)X -2866(same)X -3055(data)X -3213(concurrently.)X -3683(In)X -3774(order)X -3968(to)X -4054(provide)X -555 4203(this)N -702(concurrent)X -1078(access)X -1316(and)X -1464(enforce)X -1738(the)X -1868(write-ahead)X -2280(logging)X -2556(protocol)X -2855(described)X -3195(in)X -3289(section)X -3548(3.1.1,)X -3759(we)X -3884(use)X -4022(a)X -4089(shared)X -555 4293(memory)N -848(buffer)X -1071(manager.)X -1414(Not)X -1559(only)X -1726(does)X -1898(this)X -2038(provide)X -2308(the)X -2431(guarantees)X -2800(we)X -2919(require,)X -3192(but)X -3319(a)X -3380(user-level)X -3722(buffer)X -3944(manager)X -4246(is)X -555 4383(frequently)N -916(faster)X -1126(than)X -1295(using)X -1498(the)X -1626(\256le)X -1758(system)X -2010(buffer)X -2237(cache.)X -2491(Reads)X -2717(or)X -2814(writes)X -3040(involving)X -3376(the)X -3504(\256le)X -3636(system)X -3888(buffer)X -4115(cache)X -555 4473(often)N -746(require)X -1000(copying)X -1284(data)X -1444(between)X -1738(user)X -1898(and)X -2040(kernel)X -2266(space)X -2470(while)X -2673(a)X -2734(user-level)X -3076(buffer)X -3298(manager)X -3600(can)X -3737(return)X -3954(pointers)X -4237(to)X -555 4563(data)N -709(pages)X -912(directly.)X -1217(Additionally,)X -1661(if)X -1730(more)X -1915(than)X -2073(one)X -2209(process)X -2470(uses)X -2628(the)X -2746(same)X -2931(page,)X -3123(then)X -3281(fewer)X -3485(copies)X -3710(may)X -3868(be)X -3964(required.)X -3 f -555 4749(3.2.)N -715(Module)X -997(Architecture)X -1 f -755 4872(The)N -913(preceding)X -1262(sections)X -1552(described)X -1892(modules)X -2195(for)X -2321(managing)X -2669(the)X -2799(transaction)X -3183(log,)X -3337(locks,)X -3558(and)X -3706(a)X -3774(cache)X -3990(of)X -4089(shared)X -555 4962(buffers.)N -847(In)X -938(addition,)X -1244(we)X -1362(need)X -1538(to)X -1624(provide)X -1893(functionality)X -2326(for)X -2444(transaction)X -2 f -2819(begin)X -1 f -2997(,)X -2 f -3040(commit)X -1 f -3276(,)X -3319(and)X -2 f -3458(abort)X -1 f -3654(processing,)X -4040(necessi-)X -555 5052(tating)N -769(a)X -837(transaction)X -1221(manager.)X -1570(In)X -1669(order)X -1871(to)X -1965(arbitrate)X -2265(concurrent)X -2641(access)X -2879(to)X -2973(locks)X -3173(and)X -3320(buffers,)X -3599(we)X -3724(include)X -3991(a)X -4058(process)X -555 5142(management)N -995(module)X -1264(which)X -1489(manages)X -1799(a)X -1864(collection)X -2209(of)X -2305(semaphores)X -2713(used)X -2889(to)X -2980(block)X -3187(and)X -3332(release)X -3585(processes.)X -3962(Finally,)X -4237(in)X -555 5232(order)N -752(to)X -841(provide)X -1113(a)X -1176(simple,)X -1436(standard)X -1735(interface)X -2044(we)X -2165(have)X -2344(modi\256ed)X -2655(the)X -2780(database)X -3084(access)X -3317(routines)X -3602(\()X -3 f -3629(db)X -1 f -3717(\(3\)\).)X -3904(For)X -4041(the)X -4165(pur-)X -555 5322(poses)N -758(of)X -850(this)X -990(paper)X -1194(we)X -1313(call)X -1453(the)X -1575(modi\256ed)X -1883(package)X -2171(the)X -3 f -2293(Record)X -2567(Manager)X -1 f -2879(.)X -2943(Figure)X -3176(one)X -3316(shows)X -3540(the)X -3662(main)X -3846(interfaces)X -4183(and)X -555 5412(architecture)N -955(of)X -1042(LIBTP.)X - -5 p -%%Page: 5 5 -10 s 10 xH 0 xS 1 f -3 f -1 f -11 s -1851 1520(log_commit)N -2764 2077(buf_unpin)N -2764 1987(buf_get)N -3633 1408(buf_unpin)N -3633 1319(buf_pin)N -3633 1230(buf_get)N -3 f -17 s -1163 960(Txn)N -1430(M)X -1559(anager)X -2582(Record)X -3040(M)X -3169(anager)X -1 Dt -2363 726 MXY -0 355 Dl -1426 0 Dl -0 -355 Dl --1426 0 Dl -3255 1616 MXY -0 535 Dl -534 0 Dl -0 -535 Dl --534 0 Dl -2185 MX -0 535 Dl -535 0 Dl -0 -535 Dl --535 0 Dl -1116 MX -0 535 Dl -534 0 Dl -0 -535 Dl --534 0 Dl -726 MY -0 355 Dl -891 0 Dl -0 -355 Dl --891 0 Dl -1 f -11 s -2207 1297(lock)N -2564 1386(log)N -865(unlock_all)X -1851 1609(log_unroll)N -1650 2508 MXY -0 178 Dl -1605 0 Dl -0 -178 Dl --1605 0 Dl -1294 1616 MXY -19 -30 Dl --19 11 Dl --20 -11 Dl -20 30 Dl -0 -535 Dl -2319 2508 MXY --22 -30 Dl -4 23 Dl --18 14 Dl -36 -7 Dl --936 -357 Dl -3277 2455(sleep_on)N -1405 1616 MXY -36 4 Dl --18 -13 Dl -1 -22 Dl --19 31 Dl -1070 -535 Dl -2631 2508 MXY -36 6 Dl --18 -14 Dl -3 -22 Dl --21 30 Dl -891 -357 Dl -1426 2455(sleep_on)N -3255 1884 MXY --31 -20 Dl -11 20 Dl --11 19 Dl -31 -19 Dl --535 0 Dl -1554 2366(wake)N -3277(wake)X -2185 1884 MXY --31 -20 Dl -12 20 Dl --12 19 Dl -31 -19 Dl --356 0 Dl -0 -803 Dl -3 f -17 s -1236 1851(Lock)N -1118 2030(M)N -1247(anager)X -2339 1851(Log)N -2187 2030(M)N -2316(anager)X -3333 1851(Buffer)N -3257 2030(M)N -3386(anager)X -3522 1616 MXY -20 -30 Dl --20 11 Dl --20 -11 Dl -20 30 Dl -0 -535 Dl -1950 2654(Process)N -2424(M)X -2553(anager)X -2542 1616 MXY -19 -30 Dl --19 11 Dl --20 -11 Dl -20 30 Dl -0 -535 Dl -1 f -11 s -2207 1364(unlock)N -2452 2508 MXY -20 -31 Dl --20 11 Dl --19 -11 Dl -19 31 Dl -0 -357 Dl -2497 2322(sleep_on)N -2497 2233(wake)N -3 Dt --1 Ds -3 f -10 s -1790 2830(Figure)N -2037(1:)X -2144(Library)X -2435(module)X -2708(interfaces.)X -1 f -10 f -555 3010(h)N -579(hhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhh)X -3 f -555 3286(3.2.1.)N -775(The)X -928(Log)X -1081(Manager)X -1 f -755 3409(The)N -3 f -907(Log)X -1067(Manager)X -1 f -1406(enforces)X -1706(the)X -1831(write-ahead)X -2238(logging)X -2509(protocol.)X -2843(Its)X -2949(primitive)X -3268(operations)X -3628(are)X -2 f -3753(log)X -1 f -3855(,)X -2 f -3901(log_commit)X -1 f -4279(,)X -2 f -555 3499(log_read)N -1 f -844(,)X -2 f -889(log_roll)X -1 f -1171(and)X -2 f -1312(log_unroll)X -1 f -1649(.)X -1714(The)X -2 f -1864(log)X -1 f -1991(call)X -2132(performs)X -2447(a)X -2508(buffered)X -2806(write)X -2996(of)X -3088(the)X -3211(speci\256ed)X -3520(log)X -3646(record)X -3876(and)X -4016(returns)X -4263(a)X -555 3589(unique)N -809(log)X -947(sequence)X -1278(number)X -1559(\(LSN\).)X -1840(This)X -2017(LSN)X -2203(may)X -2376(then)X -2549(be)X -2660(used)X -2842(to)X -2939(retrieve)X -3220(a)X -3291(record)X -3532(from)X -3723(the)X -3856(log)X -3993(using)X -4201(the)X -2 f -555 3679(log_read)N -1 f -865(call.)X -1042(The)X -2 f -1188(log)X -1 f -1311(interface)X -1614(knows)X -1844(very)X -2008(little)X -2175(about)X -2374(the)X -2493(internal)X -2759(format)X -2993(of)X -3080(the)X -3198(log)X -3320(records)X -3577(it)X -3641(receives.)X -3965(Rather,)X -4219(all)X -555 3769(log)N -681(records)X -942(are)X -1065 0.4028(referenced)AX -1430(by)X -1534(a)X -1594(header)X -1833(structure,)X -2158(a)X -2218(log)X -2344(record)X -2574(type,)X -2756(and)X -2896(a)X -2956(character)X -3276(buffer)X -3497(containing)X -3859(the)X -3981(data)X -4138(to)X -4223(be)X -555 3859(logged.)N -834(The)X -980(log)X -1103(record)X -1330(type)X -1489(is)X -1563(used)X -1731(to)X -1814(call)X -1951(the)X -2070(appropriate)X -2457(redo)X -2621(and)X -2758(undo)X -2939(routines)X -3217(during)X -2 f -3446(abort)X -1 f -3639(and)X -2 f -3775(commit)X -1 f -4031(process-)X -555 3949(ing.)N -721(While)X -941(we)X -1059(have)X -1235(used)X -1406(the)X -3 f -1528(Log)X -1684(Manager)X -1 f -2019(to)X -2104(provide)X -2372(before)X -2601(and)X -2740(after)X -2911(image)X -3130(logging,)X -3417(it)X -3484(may)X -3645(also)X -3797(be)X -3896(used)X -4066(for)X -4183(any)X -555 4039(of)N -642(the)X -760(logging)X -1024(algorithms)X -1386(discussed.)X -755 4162(The)N -2 f -905(log_commit)X -1 f -1308(operation)X -1636(behaves)X -1920(exactly)X -2177(like)X -2322(the)X -2 f -2445(log)X -1 f -2572(operation)X -2900(but)X -3026(guarantees)X -3394(that)X -3538(the)X -3660(log)X -3786(has)X -3917(been)X -4093(forced)X -555 4252(to)N -643(disk)X -802(before)X -1034(returning.)X -1394(A)X -1478(discussion)X -1837(of)X -1930(our)X -2063(commit)X -2333(strategy)X -2613(appears)X -2884(in)X -2971(the)X -3094(implementation)X -3621(section)X -3873(\(section)X -4152(4.2\).)X -2 f -555 4342(Log_unroll)N -1 f -935(reads)X -1126(log)X -1249(records)X -1507(from)X -1684(the)X -1803(log,)X -1946(following)X -2278(backward)X -2611(transaction)X -2983(pointers)X -3261(and)X -3397(calling)X -3635(the)X -3753(appropriate)X -4139(undo)X -555 4432(routines)N -839(to)X -927(implement)X -1295(transaction)X -1673(abort.)X -1904(In)X -1997(a)X -2059(similar)X -2307(manner,)X -2 f -2594(log_roll)X -1 f -2877(reads)X -3073(log)X -3201(records)X -3464(sequentially)X -3877(forward,)X -4178(cal-)X -555 4522(ling)N -699(the)X -817(appropriate)X -1203(redo)X -1366(routines)X -1644(to)X -1726(recover)X -1988(committed)X -2350(transactions)X -2753(after)X -2921(a)X -2977(system)X -3219(crash.)X -3 f -555 4708(3.2.2.)N -775(The)X -928(Buffer)X -1171(Manager)X -1 f -755 4831(The)N -3 f -912(Buffer)X -1167(Manager)X -1 f -1511(uses)X -1681(a)X -1749(pool)X -1923(of)X -2022(shared)X -2264(memory)X -2563(to)X -2657(provide)X -2934(a)X -3002(least-recently-used)X -3641(\(LRU\))X -3886(block)X -4095(cache.)X -555 4921(Although)N -886(the)X -1013(current)X -1270(library)X -1513(provides)X -1818(an)X -1923(LRU)X -2112(cache,)X -2345(it)X -2418(would)X -2647(be)X -2752(simple)X -2994(to)X -3085(add)X -3229(alternate)X -3534(replacement)X -3955(policies)X -4232(as)X -555 5011(suggested)N -903(by)X -1015([CHOU85])X -1408(or)X -1507(to)X -1601(provide)X -1878(multiple)X -2176(buffer)X -2405(pools)X -2610(with)X -2784(different)X -3092(policies.)X -3412(Transactions)X -3853(request)X -4116(pages)X -555 5101(from)N -736(the)X -859(buffer)X -1081(manager)X -1383(and)X -1524(keep)X -1701(them)X -3 f -1886(pinned)X -1 f -2145(to)X -2232(ensure)X -2466(that)X -2610(they)X -2772(are)X -2895(not)X -3021(written)X -3272(to)X -3358(disk)X -3515(while)X -3717(they)X -3879(are)X -4002(in)X -4088(a)X -4148(logi-)X -555 5191(cally)N -732(inconsistent)X -1135(state.)X -1343(When)X -1556(page)X -1729(replacement)X -2143(is)X -2217(necessary,)X -2571(the)X -3 f -2689(Buffer)X -2932(Manager)X -1 f -3264(\256nds)X -3439(an)X -3535(unpinned)X -3853(page)X -4025(and)X -4161(then)X -555 5281(checks)N -794(with)X -956(the)X -3 f -1074(Log)X -1227(Manager)X -1 f -1559(to)X -1641(ensure)X -1871(that)X -2011(the)X -2129(write-ahead)X -2529(protocol)X -2816(is)X -2889(enforced.)X -3 f -555 5467(3.2.3.)N -775(The)X -928(Lock)X -1121(Manager)X -1 f -755 5590(The)N -3 f -901(Lock)X -1095(Manager)X -1 f -1428(supports)X -1720(general)X -1978(purpose)X -2253(locking)X -2514(\(single)X -2753(writer,)X -2986(multiple)X -3273(readers\))X -3553(which)X -3769(is)X -3842(currently)X -4152(used)X -555 5680(to)N -638(provide)X -904(two-phase)X -1254(locking)X -1514(and)X -1650(high)X -1812(concurrency)X -2230(B-tree)X -2451(locking.)X -2751(However,)X -3086(the)X -3204(general)X -3461(purpose)X -3735(nature)X -3956(of)X -4043(the)X -4161(lock)X - -6 p -%%Page: 6 6 -10 s 10 xH 0 xS 1 f -3 f -1 f -555 630(manager)N -857(provides)X -1158(the)X -1281(ability)X -1510(to)X -1597(support)X -1862(a)X -1923(variety)X -2171(of)X -2263(locking)X -2528(protocols.)X -2890(Currently,)X -3241(all)X -3345(locks)X -3538(are)X -3661(issued)X -3885(at)X -3967(the)X -4089(granu-)X -555 720(larity)N -747(of)X -837(a)X -896(page)X -1071(\(the)X -1219(size)X -1367(of)X -1457(a)X -1516(buffer)X -1736(in)X -1821(the)X -1942(buffer)X -2161(pool\))X -2352(which)X -2570(is)X -2645(identi\256ed)X -2969(by)X -3071(two)X -3213(4-byte)X -3440(integers)X -3716(\(a)X -3801(\256le)X -3925(id)X -4009(and)X -4147(page)X -555 810(number\).)N -898(This)X -1071(provides)X -1378(the)X -1507(necessary)X -1851(information)X -2259(to)X -2351(extend)X -2595(the)X -3 f -2723(Lock)X -2926(Manager)X -1 f -3268(to)X -3360(perform)X -3649(hierarchical)X -4059(locking)X -555 900([GRAY76].)N -982(The)X -1133(current)X -1387(implementation)X -1915(does)X -2088(not)X -2216(support)X -2482(locks)X -2677(at)X -2760(other)X -2950(granularities)X -3376(and)X -3517(does)X -3689(not)X -3816(promote)X -4108(locks;)X -555 990(these)N -740(are)X -859(obvious)X -1132(future)X -1344(additions)X -1657(to)X -1739(the)X -1857(system.)X -755 1113(If)N -831(an)X -929(incoming)X -1253(lock)X -1413(request)X -1667(cannot)X -1903(be)X -2001(granted,)X -2284(the)X -2404(requesting)X -2760(process)X -3023(is)X -3098(queued)X -3352(for)X -3467(the)X -3586(lock)X -3745(and)X -3882(descheduled.)X -555 1203(When)N -769(a)X -827(lock)X -987(is)X -1062(released,)X -1368(the)X -1488(wait)X -1647(queue)X -1860(is)X -1934(traversed)X -2250(and)X -2387(any)X -2524(newly)X -2741(compatible)X -3118(locks)X -3308(are)X -3428(granted.)X -3730(Locks)X -3947(are)X -4067(located)X -555 1293(via)N -680(a)X -743(\256le)X -872(and)X -1015(page)X -1194(hash)X -1368(table)X -1551(and)X -1694(are)X -1820(chained)X -2097(both)X -2266(by)X -2373(object)X -2595(and)X -2737(by)X -2843(transaction,)X -3241(facilitating)X -3614(rapid)X -3805(traversal)X -4108(of)X -4201(the)X -555 1383(lock)N -713(table)X -889(during)X -1118(transaction)X -1490(commit)X -1754(and)X -1890(abort.)X -755 1506(The)N -907(primary)X -1188(interfaces)X -1528(to)X -1617(the)X -1742(lock)X -1907(manager)X -2211(are)X -2 f -2337(lock)X -1 f -2471(,)X -2 f -2518(unlock)X -1 f -2732(,)X -2779(and)X -2 f -2922(lock_unlock_all)X -1 f -3434(.)X -2 f -3500(Lock)X -1 f -3682(obtains)X -3939(a)X -4001(new)X -4161(lock)X -555 1596(for)N -680(a)X -747(speci\256c)X -1023(object.)X -1290(There)X -1509(are)X -1638(also)X -1797(two)X -1947(variants)X -2231(of)X -2328(the)X -2 f -2456(lock)X -1 f -2620(request,)X -2 f -2902(lock_upgrade)X -1 f -3373(and)X -2 f -3519(lock_downgrade)X -1 f -4053(,)X -4103(which)X -555 1686(allow)N -755(the)X -875(caller)X -1076(to)X -1160(atomically)X -1519(trade)X -1701(a)X -1758(lock)X -1917(of)X -2005(one)X -2142(type)X -2301(for)X -2416(a)X -2473(lock)X -2632(of)X -2720(another.)X -2 f -3022(Unlock)X -1 f -3275(releases)X -3551(a)X -3608(speci\256c)X -3874(mode)X -4073(of)X -4161(lock)X -555 1776(on)N -655(a)X -711(speci\256c)X -976(object.)X -2 f -1232(Lock_unlock_all)X -1 f -1786(releases)X -2061(all)X -2161(the)X -2279(locks)X -2468(associated)X -2818(with)X -2980(a)X -3036(speci\256c)X -3301(transaction.)X -3 f -555 1962(3.2.4.)N -775(The)X -928(Process)X -1207(Manager)X -1 f -755 2085(The)N -3 f -900(Process)X -1179(Manager)X -1 f -1511(acts)X -1656(as)X -1743(a)X -1799(user-level)X -2136(scheduler)X -2464(to)X -2546(make)X -2740(processes)X -3068(wait)X -3226(on)X -3326(unavailable)X -3716(locks)X -3905(and)X -4041(pending)X -555 2175(buffer)N -778(cache)X -988(I/O.)X -1161(For)X -1297(each)X -1470(process,)X -1756(a)X -1817(semaphore)X -2190(is)X -2268(maintained)X -2649(upon)X -2834(which)X -3055(that)X -3200(process)X -3466(waits)X -3660(when)X -3859(it)X -3928(needs)X -4136(to)X -4223(be)X -555 2265(descheduled.)N -1014(When)X -1228(a)X -1286(process)X -1549(needs)X -1754(to)X -1838(be)X -1936(run,)X -2084(its)X -2180(semaphore)X -2549(is)X -2623(cleared,)X -2897(and)X -3034(the)X -3153(operating)X -3477(system)X -3720(reschedules)X -4116(it.)X -4201(No)X -555 2355(sophisticated)N -1002(scheduling)X -1378(algorithm)X -1718(is)X -1799(applied;)X -2085(if)X -2162(the)X -2288(lock)X -2454(for)X -2576(which)X -2800(a)X -2864(process)X -3133(was)X -3286(waiting)X -3554(becomes)X -3863(available,)X -4201(the)X -555 2445(process)N -824(is)X -905(made)X -1107(runnable.)X -1456(It)X -1533(would)X -1761(have)X -1941(been)X -2121(possible)X -2411(to)X -2501(change)X -2757(the)X -2883(kernel's)X -3170(process)X -3439(scheduler)X -3775(to)X -3865(interact)X -4134(more)X -555 2535(ef\256ciently)N -900(with)X -1062(the)X -1180(lock)X -1338(manager,)X -1655(but)X -1777(doing)X -1979(so)X -2070(would)X -2290(have)X -2462(compromised)X -2918(our)X -3045(commitment)X -3469(to)X -3551(a)X -3607(user-level)X -3944(package.)X -3 f -555 2721(3.2.5.)N -775(The)X -928(Transaction)X -1361(Manager)X -1 f -755 2844(The)N -3 f -901(Transaction)X -1335(Manager)X -1 f -1668(provides)X -1965(the)X -2084(standard)X -2377(interface)X -2680(of)X -2 f -2768(txn_begin)X -1 f -3084(,)X -2 f -3125(txn_commit)X -1 f -3499(,)X -3540(and)X -2 f -3676(txn_abort)X -1 f -3987(.)X -4047(It)X -4116(keeps)X -555 2934(track)N -742(of)X -835(all)X -941(active)X -1159(transactions,)X -1588(assigns)X -1845(unique)X -2089(transaction)X -2467(identi\256ers,)X -2833(and)X -2974(directs)X -3213(the)X -3336(abort)X -3526(and)X -3667(commit)X -3936(processing.)X -555 3024(When)N -772(a)X -2 f -833(txn_begin)X -1 f -1174(is)X -1252(issued,)X -1497(the)X -3 f -1620(Transaction)X -2058(Manager)X -1 f -2395(assigns)X -2651(the)X -2773(next)X -2935(available)X -3249(transaction)X -3625(identi\256er,)X -3958(allocates)X -4263(a)X -555 3114(per-process)N -948(transaction)X -1322(structure)X -1625(in)X -1709(shared)X -1941(memory,)X -2249(increments)X -2622(the)X -2741(count)X -2940(of)X -3028(active)X -3241(transactions,)X -3665(and)X -3802(returns)X -4046(the)X -4165(new)X -555 3204(transaction)N -937(identi\256er)X -1256(to)X -1348(the)X -1476(calling)X -1724(process.)X -2034(The)X -2188(in-memory)X -2573(transaction)X -2954(structure)X -3264(contains)X -3560(a)X -3625(pointer)X -3881(into)X -4034(the)X -4161(lock)X -555 3294(table)N -734(for)X -851(locks)X -1043(held)X -1204(by)X -1307(this)X -1445(transaction,)X -1840(the)X -1961(last)X -2095(log)X -2220(sequence)X -2538(number,)X -2826(a)X -2885(transaction)X -3260(state)X -3430(\()X -2 f -3457(idle)X -1 f -(,)S -2 f -3620(running)X -1 f -3873(,)X -2 f -3915(aborting)X -1 f -4190(,)X -4232(or)X -2 f -555 3384(committing\))N -1 f -942(,)X -982(an)X -1078(error)X -1255(code,)X -1447(and)X -1583(a)X -1639(semaphore)X -2007(identi\256er.)X -755 3507(At)N -859(commit,)X -1147(the)X -3 f -1269(Transaction)X -1706(Manager)X -1 f -2042(calls)X -2 f -2213(log_commit)X -1 f -2615(to)X -2700(record)X -2929(the)X -3050(end)X -3189(of)X -3279(transaction)X -3654(and)X -3793(to)X -3878(\257ush)X -4056(the)X -4177(log.)X -555 3597(Then)N -743(it)X -810(directs)X -1047(the)X -3 f -1168(Lock)X -1364(Manager)X -1 f -1699(to)X -1784(release)X -2031(all)X -2134(locks)X -2325(associated)X -2677(with)X -2841(the)X -2961(given)X -3161(transaction.)X -3575(If)X -3651(a)X -3709(transaction)X -4083(aborts,)X -555 3687(the)N -3 f -680(Transaction)X -1120(Manager)X -1 f -1459(calls)X -1633(on)X -2 f -1739(log_unroll)X -1 f -2102(to)X -2190(read)X -2355(the)X -2479(transaction's)X -2915(log)X -3043(records)X -3306(and)X -3448(undo)X -3634(any)X -3776(modi\256cations)X -4237(to)X -555 3777(the)N -673(database.)X -1010(As)X -1119(in)X -1201(the)X -1319(commit)X -1583(case,)X -1762(it)X -1826(then)X -1984(calls)X -2 f -2151(lock_unlock_all)X -1 f -2683(to)X -2765(release)X -3009(the)X -3127(transaction's)X -3557(locks.)X -3 f -555 3963(3.2.6.)N -775(The)X -928(Record)X -1198(Manager)X -1 f -755 4086(The)N -3 f -919(Record)X -1208(Manager)X -1 f -1559(supports)X -1869(the)X -2006(abstraction)X -2397(of)X -2503(reading)X -2783(and)X -2938(writing)X -3208(records)X -3484(to)X -3585(a)X -3660(database.)X -3996(We)X -4147(have)X -555 4176(modi\256ed)N -861(the)X -981(the)X -1101(database)X -1399(access)X -1626(routines)X -3 f -1905(db)X -1 f -1993(\(3\))X -2108([BSD91])X -2418(to)X -2501(call)X -2638(the)X -2757(log,)X -2900(lock,)X -3079(and)X -3216(buffer)X -3434(managers.)X -3803(In)X -3891(order)X -4082(to)X -4165(pro-)X -555 4266(vide)N -718(functionality)X -1152(to)X -1239(perform)X -1523(undo)X -1708(and)X -1849(redo,)X -2037(the)X -3 f -2160(Record)X -2434(Manager)X -1 f -2770(de\256nes)X -3021(a)X -3081(collection)X -3421(of)X -3512(log)X -3638(record)X -3868(types)X -4061(and)X -4201(the)X -555 4356(associated)N -920(undo)X -1115(and)X -1266(redo)X -1444(routines.)X -1777(The)X -3 f -1937(Log)X -2105(Manager)X -1 f -2452(performs)X -2777(a)X -2848(table)X -3039(lookup)X -3296(on)X -3411(the)X -3543(record)X -3783(type)X -3955(to)X -4051(call)X -4201(the)X -555 4446(appropriate)N -951(routines.)X -1299(For)X -1440(example,)X -1762(the)X -1890(B-tree)X -2121(access)X -2356(method)X -2625(requires)X -2913(two)X -3062(log)X -3193(record)X -3428(types:)X -3648(insert)X -3855(and)X -4000(delete.)X -4241(A)X -555 4536(replace)N -808(operation)X -1131(is)X -1204(implemented)X -1642(as)X -1729(a)X -1785(delete)X -1997(followed)X -2302(by)X -2402(an)X -2498(insert)X -2696(and)X -2832(is)X -2905(logged)X -3143(accordingly.)X -3 f -555 4722(3.3.)N -715(Application)X -1134(Architectures)X -1 f -755 4845(The)N -907(structure)X -1215(of)X -1309(LIBTP)X -1558(allows)X -1794(application)X -2177(designers)X -2507(to)X -2596(trade)X -2784(off)X -2905(performance)X -3339(and)X -3481(protection.)X -3872(Since)X -4076(a)X -4138(large)X -555 4935(portion)N -810(of)X -901(LIBTP's)X -1205(functionality)X -1638(is)X -1715(provided)X -2024(by)X -2128(managing)X -2468(structures)X -2804(in)X -2889(shared)X -3122(memory,)X -3432(its)X -3530(structures)X -3865(are)X -3987(subject)X -4237(to)X -555 5025(corruption)N -926(by)X -1043(applications)X -1467(when)X -1678(the)X -1813(library)X -2064(is)X -2154(linked)X -2391(directly)X -2673(with)X -2852(the)X -2987(application.)X -3420(For)X -3568(this)X -3720(reason,)X -3987(LIBTP)X -4246(is)X -555 5115(designed)N -864(to)X -950(allow)X -1152(compilation)X -1558(into)X -1706(a)X -1766(separate)X -2053(server)X -2273(process)X -2537(which)X -2756(may)X -2917(be)X -3016(accessed)X -3321(via)X -3442(a)X -3501(socket)X -3729(interface.)X -4094(In)X -4184(this)X -555 5205(way)N -712(LIBTP's)X -1015(data)X -1172(structures)X -1507(are)X -1629(protected)X -1951(from)X -2130(application)X -2509(code,)X -2704(but)X -2829(communication)X -3349(overhead)X -3666(is)X -3741(increased.)X -4107(When)X -555 5295(applications)N -975(are)X -1107(trusted,)X -1377(LIBTP)X -1631(may)X -1801(be)X -1909(compiled)X -2239(directly)X -2516(into)X -2672(the)X -2802(application)X -3190(providing)X -3533(improved)X -3872(performance.)X -555 5385(Figures)N -815(two)X -955(and)X -1091(three)X -1272(show)X -1461(the)X -1579(two)X -1719(alternate)X -2016(application)X -2392(architectures.)X -755 5508(There)N -964(are)X -1084(potentially)X -1447(two)X -1588(modes)X -1818(in)X -1901(which)X -2118(one)X -2255(might)X -2462(use)X -2590(LIBTP)X -2833(in)X -2916(a)X -2972(server)X -3189(based)X -3392(architecture.)X -3832(In)X -3919(the)X -4037(\256rst,)X -4201(the)X -555 5598(server)N -778(would)X -1004(provide)X -1275(the)X -1399(capability)X -1741(to)X -1829(respond)X -2109(to)X -2197(requests)X -2486(to)X -2574(each)X -2747(of)X -2839(the)X -2962(low)X -3107(level)X -3288(modules)X -3584(\(lock,)X -3794(log,)X -3941(buffer,)X -4183(and)X -555 5688(transaction)N -944(managers\).)X -1356(Unfortunately,)X -1863(the)X -1998(performance)X -2442(of)X -2546(such)X -2730(a)X -2803(system)X -3062(is)X -3152(likely)X -3371(to)X -3470(be)X -3583(blindingly)X -3947(slow)X -4134(since)X - -7 p -%%Page: 7 7 -10 s 10 xH 0 xS 1 f -3 f -1 f -1 Dt -1864 1125 MXY -15 -26 Dl --15 10 Dl --14 -10 Dl -14 26 Dl -0 -266 Dl -1315 1125 MXY -15 -26 Dl --15 10 Dl --14 -10 Dl -14 26 Dl -0 -266 Dl -3 Dt -1133 1125 MXY -0 798 Dl -931 0 Dl -0 -798 Dl --931 0 Dl -1 Dt -1266 1257 MXY -0 133 Dl -665 0 Dl -0 -133 Dl --665 0 Dl -3 f -8 s -1513 1351(driver)N -1502 1617(LIBTP)N -1266 1390 MXY -0 400 Dl -665 0 Dl -0 -400 Dl --665 0 Dl -3 Dt -1133 726 MXY -0 133 Dl -931 0 Dl -0 -133 Dl --931 0 Dl -1 f -1029 1098(txn_abort)N -964 1015(txn_commit)N -1018 932(txn_begin)N -1910 1015(db_ops)N -3 f -1308 820(Application)N -1645(Program)X -1398 1218(Server)N -1594(Process)X -1 f -1390 986(socket)N -1569(interface)X -1 Dt -1848 967 MXY --23 -14 Dl -8 14 Dl --8 15 Dl -23 -15 Dl --50 0 Dl -1324 MX -23 15 Dl --9 -15 Dl -9 -14 Dl --23 14 Dl -50 0 Dl -3 Dt -2862 859 MXY -0 1064 Dl -932 0 Dl -0 -1064 Dl --932 0 Dl -1 Dt -3178 1390 MXY -24 -12 Dl --17 0 Dl --8 -15 Dl -1 27 Dl -150 -265 Dl -3494 1390 MXY -0 -27 Dl --8 15 Dl --16 1 Dl -24 11 Dl --166 -265 Dl -3 f -3232 1617(LIBTP)N -2995 1390 MXY -0 400 Dl -666 0 Dl -0 -400 Dl --666 0 Dl -992 MY -0 133 Dl -666 0 Dl -0 -133 Dl --666 0 Dl -3168 1086(Application)N -1 f -2939 1201(txn_begin)N -2885 1284(txn_commit)N -2950 1368(txn_abort)N -3465 1284(db_ops)N -3 f -3155 766(Single)N -3339(Process)X -3 Dt --1 Ds -811 2100(Figure)N -1023(2:)X -1107(Server)X -1318(Architecture.)X -1 f -1727(In)X -1811(this)X -1934(con\256guration,)X -811 2190(the)N -916(library)X -1113(is)X -1183(loaded)X -1380(into)X -1507(a)X -1562(server)X -1744(process)X -1962(which)X -2145(is)X -2214(ac-)X -811 2280(cessed)N -993(via)X -1087(a)X -1131(socket)X -1310(interface.)X -3 f -2563 2100(Figure)N -2803(3:)X -2914(Single)X -3140(Process)X -3403(Architecture.)X -1 f -3839(In)X -3950(this)X -2563 2190(con\256guration,)N -2948(the)X -3053(library)X -3250(routines)X -3483(are)X -3587(loaded)X -3784(as)X -3864(part)X -3990(of)X -2563 2280(the)N -2657(application)X -2957(and)X -3065(accessed)X -3303(via)X -3397(a)X -3441(subroutine)X -3727(interface.)X -10 s -10 f -555 2403(h)N -579(hhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhh)X -1 f -555 2679(modifying)N -909(a)X -966(piece)X -1157(of)X -1245(data)X -1400(would)X -1621(require)X -1870(three)X -2051(or)X -2138(possibly)X -2424(four)X -2578(separate)X -2862(communications:)X -3433(one)X -3569(to)X -3651(lock)X -3809(the)X -3927(data,)X -4101(one)X -4237(to)X -555 2769(obtain)N -781(the)X -905(data,)X -1085(one)X -1227(to)X -1315(log)X -1443(the)X -1567(modi\256cation,)X -2017(and)X -2159(possibly)X -2451(one)X -2593(to)X -2681(transmit)X -2969(the)X -3093(modi\256ed)X -3403(data.)X -3583(Figure)X -3817(four)X -3976(shows)X -4201(the)X -555 2859(relative)N -826(performance)X -1263(for)X -1387(retrieving)X -1728(a)X -1793(single)X -2013(record)X -2248(using)X -2450(the)X -2577(record)X -2812(level)X -2997(call)X -3142(versus)X -3376(using)X -3578(the)X -3705(lower)X -3917(level)X -4102(buffer)X -555 2949(management)N -987(and)X -1125(locking)X -1387(calls.)X -1616(The)X -1763(2:1)X -1887(ratio)X -2056(observed)X -2367(in)X -2450(the)X -2569(single)X -2781(process)X -3043(case)X -3203(re\257ects)X -3456(the)X -3575(additional)X -3916(overhead)X -4232(of)X -555 3039(parsing)N -819(eight)X -1006(commands)X -1380(rather)X -1595(than)X -1760(one)X -1903(while)X -2108(the)X -2233(3:1)X -2362(ratio)X -2536(observed)X -2853(in)X -2942(the)X -3067(client/server)X -3491(architecture)X -3898(re\257ects)X -4157(both)X -555 3129(the)N -679(parsing)X -941(and)X -1083(the)X -1207(communication)X -1731(overheard.)X -2118(Although)X -2445(there)X -2631(may)X -2794(be)X -2895(applications)X -3307(which)X -3528(could)X -3731(tolerate)X -3997(such)X -4169(per-)X -555 3219(formance,)N -904(it)X -973(seems)X -1194(far)X -1309(more)X -1499(feasible)X -1774(to)X -1861(support)X -2126(a)X -2187(higher)X -2417(level)X -2597(interface,)X -2923(such)X -3094(as)X -3185(that)X -3329(provided)X -3638(by)X -3742(a)X -3802(query)X -4009(language)X -555 3309(\()N -2 f -582(e.g.)X -1 f -718(SQL)X -889([SQL86]\).)X -755 3432(Although)N -1081(LIBTP)X -1327(does)X -1498(not)X -1624(have)X -1800(an)X -1900(SQL)X -2075(parser,)X -2316(we)X -2433(have)X -2608(built)X -2777(a)X -2836(server)X -3056(application)X -3435(using)X -3631(the)X -3752(toolkit)X -3983(command)X -555 3522(language)N -882(\(TCL\))X -1124([OUST90].)X -1544(The)X -1706(server)X -1940(supports)X -2248(a)X -2321(command)X -2674(line)X -2831(interface)X -3150(similar)X -3409(to)X -3508(the)X -3643(subroutine)X -4017(interface)X -555 3612(de\256ned)N -811(in)X -3 f -893(db)X -1 f -981(\(3\).)X -1135(Since)X -1333(it)X -1397(is)X -1470(based)X -1673(on)X -1773(TCL,)X -1964(it)X -2028(provides)X -2324(control)X -2571(structures)X -2903(as)X -2990(well.)X -3 f -555 3798(4.)N -655(Implementation)X -1 f -3 f -555 3984(4.1.)N -715(Locking)X -1014(and)X -1162(Deadlock)X -1502(Detection)X -1 f -755 4107(LIBTP)N -1007(uses)X -1175(two-phase)X -1535(locking)X -1805(for)X -1929(user)X -2093(data.)X -2297(Strictly)X -2562(speaking,)X -2897(the)X -3024(two)X -3173(phases)X -3416(in)X -3507(two-phase)X -3866(locking)X -4135(are)X -4263(a)X -3 f -555 4197(grow)N -1 f -756(phase,)X -986(during)X -1221(which)X -1443(locks)X -1638(are)X -1763(acquired,)X -2086(and)X -2228(a)X -3 f -2290(shrink)X -1 f -2537(phase,)X -2766(during)X -3001(which)X -3223(locks)X -3418(are)X -3543(released.)X -3873(No)X -3997(lock)X -4161(may)X -555 4287(ever)N -720(be)X -822(acquired)X -1124(during)X -1358(the)X -1481(shrink)X -1706(phase.)X -1954(The)X -2104(grow)X -2294(phase)X -2502(lasts)X -2669(until)X -2840(the)X -2963(\256rst)X -3112(release,)X -3381(which)X -3602(marks)X -3823(the)X -3946(start)X -4109(of)X -4201(the)X -555 4377(shrink)N -780(phase.)X -1028(In)X -1120(practice,)X -1420(the)X -1543(grow)X -1733(phase)X -1941(lasts)X -2108(for)X -2227(the)X -2350(duration)X -2642(of)X -2734(a)X -2795(transaction)X -3172(in)X -3259(LIBTP)X -3506(and)X -3647(in)X -3734(commercial)X -4138(data-)X -555 4467(base)N -721(systems.)X -1037(The)X -1184(shrink)X -1406(phase)X -1611(takes)X -1798(place)X -1990(during)X -2221(transaction)X -2595(commit)X -2861(or)X -2950(abort.)X -3177(This)X -3341(means)X -3568(that)X -3710(locks)X -3901(are)X -4022(acquired)X -555 4557(on)N -655(demand)X -929(during)X -1158(the)X -1276(lifetime)X -1545(of)X -1632(a)X -1688(transaction,)X -2080(and)X -2216(held)X -2374(until)X -2540(commit)X -2804(time,)X -2986(at)X -3064(which)X -3280(point)X -3464(all)X -3564(locks)X -3753(are)X -3872(released.)X -755 4680(If)N -832(multiple)X -1121(transactions)X -1527(are)X -1649(active)X -1864(concurrently,)X -2313(deadlocks)X -2657(can)X -2792(occur)X -2994(and)X -3133(must)X -3311(be)X -3410(detected)X -3701(and)X -3840(resolved.)X -4174(The)X -555 4770(lock)N -715(table)X -893(can)X -1027(be)X -1125(thought)X -1391(of)X -1480(as)X -1569(a)X -1627(representation)X -2104(of)X -2193(a)X -2251(directed)X -2532(graph.)X -2777(The)X -2924(nodes)X -3133(in)X -3216(the)X -3335(graph)X -3539(are)X -3659(transactions.)X -4103(Edges)X -555 4860(represent)N -878(the)X -3 f -1004(waits-for)X -1 f -1340(relation)X -1613(between)X -1909(transactions;)X -2342(if)X -2419(transaction)X -2 f -2799(A)X -1 f -2876(is)X -2957(waiting)X -3225(for)X -3347(a)X -3411(lock)X -3577(held)X -3743(by)X -3851(transaction)X -2 f -4230(B)X -1 f -4279(,)X -555 4950(then)N -716(a)X -775(directed)X -1057(edge)X -1232(exists)X -1437(from)X -2 f -1616(A)X -1 f -1687(to)X -2 f -1771(B)X -1 f -1842(in)X -1926(the)X -2046(graph.)X -2291(A)X -2371(deadlock)X -2683(exists)X -2887(if)X -2958(a)X -3016(cycle)X -3208(appears)X -3476(in)X -3560(the)X -3680(graph.)X -3925(By)X -4040(conven-)X -555 5040(tion,)N -719(no)X -819(transaction)X -1191(ever)X -1350(waits)X -1539(for)X -1653(a)X -1709(lock)X -1867(it)X -1931(already)X -2188(holds,)X -2401(so)X -2492(re\257exive)X -2793(edges)X -2996(are)X -3115(impossible.)X -755 5163(A)N -836(distinguished)X -1285(process)X -1549(monitors)X -1856(the)X -1977(lock)X -2138(table,)X -2337(searching)X -2668(for)X -2785(cycles.)X -3048(The)X -3195(frequency)X -3539(with)X -3703(which)X -3921(this)X -4058(process)X -555 5253(runs)N -716(is)X -792(user-settable;)X -1243(for)X -1360(the)X -1481(multi-user)X -1833(tests)X -1998(discussed)X -2328(in)X -2413(section)X -2663(5.1.2,)X -2866(it)X -2933(has)X -3063(been)X -3238(set)X -3350(to)X -3435(wake)X -3628(up)X -3731(every)X -3932(second,)X -4197(but)X -555 5343(more)N -742(sophisticated)X -1182(schedules)X -1516(are)X -1636(certainly)X -1938(possible.)X -2261(When)X -2474(a)X -2531(cycle)X -2722(is)X -2796(detected,)X -3105(one)X -3242(of)X -3330(the)X -3449(transactions)X -3853(in)X -3936(the)X -4055(cycle)X -4246(is)X -555 5433(nominated)N -917(and)X -1057(aborted.)X -1362(When)X -1578(the)X -1700(transaction)X -2076(aborts,)X -2315(it)X -2382(rolls)X -2547(back)X -2722(its)X -2820(changes)X -3102(and)X -3241(releases)X -3519(its)X -3617(locks,)X -3829(thereby)X -4093(break-)X -555 5523(ing)N -677(the)X -795(cycle)X -985(in)X -1067(the)X -1185(graph.)X - -8 p -%%Page: 8 8 -10 s 10 xH 0 xS 1 f -3 f -1 f -4 Ds -1 Dt -1866 865 MXY -1338 0 Dl -1866 1031 MXY -1338 0 Dl -1866 1199 MXY -1338 0 Dl -1866 1366 MXY -1338 0 Dl -1866 1533 MXY -1338 0 Dl -1866 1701 MXY -1338 0 Dl --1 Ds -5 Dt -1866 1868 MXY -1338 0 Dl -1 Dt -1 Di -2981 MX - 2981 1868 lineto - 2981 1575 lineto - 3092 1575 lineto - 3092 1868 lineto - 2981 1868 lineto -closepath 21 2981 1575 3092 1868 Dp -2646 MX - 2646 1868 lineto - 2646 949 lineto - 2758 949 lineto - 2758 1868 lineto - 2646 1868 lineto -closepath 14 2646 949 2758 1868 Dp -2312 MX - 2312 1868 lineto - 2312 1701 lineto - 2423 1701 lineto - 2423 1868 lineto - 2312 1868 lineto -closepath 3 2312 1701 2423 1868 Dp -1977 MX - 1977 1868 lineto - 1977 1512 lineto - 2089 1512 lineto - 2089 1868 lineto - 1977 1868 lineto -closepath 19 1977 1512 2089 1868 Dp -3 f -2640 2047(Client/Server)N -1957(Single)X -2185(Process)X -7 s -2957 1957(record)N -2570(component)X -2289(record)X -1890(components)X -1733 1724(.1)N -1733 1556(.2)N -1733 1389(.3)N -1733 1222(.4)N -1733 1055(.5)N -1733 889(.6)N -1590 726(Elapsed)N -1794(Time)X -1613 782(\(in)N -1693(seconds\))X -3 Dt --1 Ds -8 s -555 2255(Figure)N -756(4:)X -829(Comparison)X -1187(of)X -1260(High)X -1416(and)X -1540(Low)X -1681(Level)X -1850(Interfaces.)X -1 f -2174(Elapsed)X -2395(time)X -2528(in)X -2597(seconds)X -2818(to)X -2887(perform)X -3111(a)X -3158(single)X -3330(record)X -3511(retrieval)X -3742(from)X -3885(a)X -3932(command)X -4203(line)X -555 2345(\(rather)N -751(than)X -888(a)X -943(procedural)X -1241(interface\))X -1510(is)X -1579(shown)X -1772(on)X -1862(the)X -1966(y)X -2024(axis.)X -2185(The)X -2310(``component'')X -2704(numbers)X -2950(re\257ect)X -3135(the)X -3239(timings)X -3458(when)X -3622(the)X -3726(record)X -3914(is)X -3983(retrieved)X -4235(by)X -555 2435(separate)N -785(calls)X -924(to)X -996(the)X -1096(lock)X -1228(manager)X -1469(and)X -1583(buffer)X -1760(manager)X -2001(while)X -2165(the)X -2264(``record'')X -2531(timings)X -2745(were)X -2889(obtained)X -3130(by)X -3215(using)X -3375(a)X -3424(single)X -3598(call)X -3711(to)X -3782(the)X -3881(record)X -4064(manager.)X -555 2525(The)N -674(2:1)X -776(ratio)X -913(observed)X -1163(for)X -1257(the)X -1355(single)X -1528(process)X -1739(case)X -1868(is)X -1930(a)X -1977(re\257ection)X -2237(of)X -2309(the)X -2406(parsing)X -2613(overhead)X -2865(for)X -2958(executing)X -3225(eight)X -3372(separate)X -3599(commands)X -3895(rather)X -4062(than)X -4191(one.)X -555 2615(The)N -673(additional)X -948(factor)X -1115(of)X -1187(one)X -1298(re\257ected)X -1536(in)X -1605(the)X -1702(3:1)X -1803(ratio)X -1939(for)X -2031(the)X -2127(client/server)X -2460(architecture)X -2794(is)X -2855(due)X -2965(to)X -3033(the)X -3129(communication)X -3545(overhead.)X -3828(The)X -3945(true)X -4062(ratios)X -4222(are)X -555 2705(actually)N -775(worse)X -945(since)X -1094(the)X -1190(component)X -1492(timings)X -1703(do)X -1785(not)X -1884(re\257ect)X -2060(the)X -2155(search)X -2334(times)X -2490(within)X -2671(each)X -2804(page)X -2941(or)X -3011(the)X -3106(time)X -3237(required)X -3466(to)X -3533(transmit)X -3760(the)X -3855(page)X -3992(between)X -4221(the)X -555 2795(two)N -667(processes.)X -10 s -10 f -555 2885(h)N -579(hhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhh)X -3 f -555 3161(4.2.)N -715(Group)X -961(Commit)X -1 f -755 3284(Since)N -959(the)X -1083(log)X -1211(must)X -1392(be)X -1494(\257ushed)X -1751(to)X -1839(disk)X -1997(at)X -2080(commit)X -2349(time,)X -2536(disk)X -2694(bandwidth)X -3057(fundamentally)X -3545(limits)X -3751(the)X -3874(rate)X -4020(at)X -4103(which)X -555 3374(transactions)N -959(complete.)X -1314(Since)X -1513(most)X -1688(transactions)X -2091(write)X -2276(only)X -2438(a)X -2494(few)X -2635(small)X -2828(records)X -3085(to)X -3167(the)X -3285(log,)X -3427(the)X -3545(last)X -3676(page)X -3848(of)X -3935(the)X -4053(log)X -4175(will)X -555 3464(be)N -658(\257ushed)X -916(once)X -1095(by)X -1202(every)X -1408(transaction)X -1787(which)X -2010(writes)X -2233(to)X -2322(it.)X -2433(In)X -2527(the)X -2652(naive)X -2853(implementation,)X -3402(these)X -3593(\257ushes)X -3841(would)X -4067(happen)X -555 3554(serially.)N -755 3677(LIBTP)N -1008(uses)X -3 f -1177(group)X -1412(commit)X -1 f -1702([DEWI84])X -2077(in)X -2170(order)X -2371(to)X -2464(amortize)X -2775(the)X -2903(cost)X -3062(of)X -3159(one)X -3305(synchronous)X -3740(disk)X -3903(write)X -4098(across)X -555 3767(multiple)N -851(transactions.)X -1304(Group)X -1539(commit)X -1812(provides)X -2117(a)X -2182(way)X -2345(for)X -2468(a)X -2533(group)X -2749(of)X -2845(transactions)X -3257(to)X -3348(commit)X -3621(simultaneously.)X -4174(The)X -555 3857(\256rst)N -709(several)X -967(transactions)X -1380(to)X -1472(commit)X -1745(write)X -1939(their)X -2115(changes)X -2403(to)X -2494(the)X -2621(in-memory)X -3006(log)X -3137(page,)X -3338(then)X -3505(sleep)X -3699(on)X -3808(a)X -3873(distinguished)X -555 3947(semaphore.)N -966(Later,)X -1179(a)X -1238(committing)X -1629(transaction)X -2004(\257ushes)X -2249(the)X -2370(page)X -2545(to)X -2630(disk,)X -2805(and)X -2943(wakes)X -3166(up)X -3268(all)X -3370(its)X -3467(sleeping)X -3756(peers.)X -3988(The)X -4135(point)X -555 4037(at)N -635(which)X -853(changes)X -1134(are)X -1255(actually)X -1531(written)X -1780(is)X -1855(determined)X -2238(by)X -2340(three)X -2523(thresholds.)X -2914(The)X -3061(\256rst)X -3207(is)X -3281(the)X -2 f -3400(group)X -3612(threshold)X -1 f -3935(and)X -4072(de\256nes)X -555 4127(the)N -674(minimum)X -1005(number)X -1271(of)X -1359(transactions)X -1763(which)X -1979(must)X -2154(be)X -2250(active)X -2462(in)X -2544(the)X -2662(system)X -2904(before)X -3130(transactions)X -3533(are)X -3652(forced)X -3878(to)X -3960(participate)X -555 4217(in)N -646(a)X -711(group)X -927(commit.)X -1240(The)X -1394(second)X -1646(is)X -1728(the)X -2 f -1855(wait)X -2021(threshold)X -1 f -2352(which)X -2577(is)X -2658(expressed)X -3003(as)X -3098(the)X -3224(percentage)X -3601(of)X -3696(active)X -3916(transactions)X -555 4307(waiting)N -826(to)X -919(be)X -1026(committed.)X -1439(The)X -1595(last)X -1737(is)X -1821(the)X -2 f -1950(logdelay)X -2257(threshold)X -1 f -2590(which)X -2816(indicates)X -3131(how)X -3299(much)X -3507(un\257ushed)X -3848(log)X -3980(should)X -4223(be)X -555 4397(allowed)N -829(to)X -911(accumulate)X -1297(before)X -1523(a)X -1579(waiting)X -1839(transaction's)X -2289(commit)X -2553(record)X -2779(is)X -2852(\257ushed.)X -755 4520(Group)N -981(commit)X -1246(can)X -1379(substantially)X -1803(improve)X -2090(performance)X -2517(for)X -2631(high-concurrency)X -3218(environments.)X -3714(If)X -3788(only)X -3950(a)X -4006(few)X -4147(tran-)X -555 4610(sactions)N -836(are)X -957(running,)X -1248(it)X -1314(is)X -1389(unlikely)X -1673(to)X -1757(improve)X -2046(things)X -2263(at)X -2343(all.)X -2485(The)X -2632(crossover)X -2962(point)X -3148(is)X -3223(the)X -3343(point)X -3529(at)X -3609(which)X -3827(the)X -3947(transaction)X -555 4700(commit)N -823(rate)X -968(is)X -1045(limited)X -1295(by)X -1399(the)X -1521(bandwidth)X -1883(of)X -1974(the)X -2096(device)X -2330(on)X -2434(which)X -2654(the)X -2776(log)X -2902(resides.)X -3189(If)X -3267(processes)X -3599(are)X -3722(trying)X -3937(to)X -4023(\257ush)X -4201(the)X -555 4790(log)N -677(faster)X -876(than)X -1034(the)X -1152(log)X -1274(disk)X -1427(can)X -1559(accept)X -1785(data,)X -1959(then)X -2117(group)X -2324(commit)X -2588(will)X -2732(increase)X -3016(the)X -3134(commit)X -3398(rate.)X -3 f -555 4976(4.3.)N -715(Kernel)X -971(Intervention)X -1418(for)X -1541(Synchronization)X -1 f -755 5099(Since)N -954(LIBTP)X -1197(uses)X -1356(data)X -1511(in)X -1594(shared)X -1825(memory)X -2113(\()X -2 f -2140(e.g.)X -1 f -2277(the)X -2395(lock)X -2553(table)X -2729(and)X -2865(buffer)X -3082(pool\))X -3271(it)X -3335(must)X -3510(be)X -3606(possible)X -3888(for)X -4002(a)X -4058(process)X -555 5189(to)N -640(acquire)X -900(exclusive)X -1226(access)X -1454(to)X -1538(shared)X -1770(data)X -1926(in)X -2010(order)X -2202(to)X -2286(prevent)X -2549(corruption.)X -2945(In)X -3034(addition,)X -3338(the)X -3458(process)X -3721(manager)X -4020(must)X -4197(put)X -555 5279(processes)N -886(to)X -971(sleep)X -1159(when)X -1356(the)X -1477(lock)X -1638(or)X -1728(buffer)X -1948(they)X -2109(request)X -2364(is)X -2440(in)X -2525(use)X -2655(by)X -2758(some)X -2950(other)X -3138(process.)X -3441(In)X -3530(the)X -3650(LIBTP)X -3894(implementa-)X -555 5385(tion)N -705(under)X -914(Ultrix)X -1131(4.0)X -7 s -5353(2)Y -10 s -5385(,)Y -1305(we)X -1424(use)X -1556(System)X -1816(V)X -1899(semaphores)X -2303(to)X -2390(provide)X -2660(this)X -2800(synchronization.)X -3377(Semaphores)X -3794(implemented)X -4237(in)X -555 5475(this)N -701(fashion)X -968(turn)X -1128(out)X -1261(to)X -1354(be)X -1461(an)X -1568(expensive)X -1920(choice)X -2161(for)X -2285(synchronization,)X -2847(because)X -3132(each)X -3310(access)X -3546(traps)X -3732(to)X -3824(the)X -3952(kernel)X -4183(and)X -8 s -10 f -555 5547(hhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhh)N -5 s -1 f -727 5625(2)N -8 s -763 5650(Ultrix)N -932(and)X -1040(DEC)X -1184(are)X -1277(trademarks)X -1576(of)X -1645(Digital)X -1839(Equipment)X -2136(Corporation.)X - -9 p -%%Page: 9 9 -8 s 8 xH 0 xS 1 f -10 s -3 f -1 f -555 630(executes)N -852(atomically)X -1210(there.)X -755 753(On)N -878(architectures)X -1314(that)X -1459(support)X -1724(atomic)X -1967(test-and-set,)X -2382(a)X -2443(much)X -2646(better)X -2854(choice)X -3089(would)X -3314(be)X -3415(to)X -3502(attempt)X -3767(to)X -3854(obtain)X -4079(a)X -4139(spin-)X -555 843(lock)N -714(with)X -877(a)X -934(test-and-set,)X -1345(and)X -1482(issue)X -1663(a)X -1720(system)X -1963(call)X -2100(only)X -2263(if)X -2333(the)X -2452(spinlock)X -2744(is)X -2818(unavailable.)X -3249(Since)X -3447(virtually)X -3738(all)X -3838(semaphores)X -4237(in)X -555 933(LIBTP)N -801(are)X -924(uncontested)X -1330(and)X -1469(are)X -1591(held)X -1752(for)X -1869(very)X -2035(short)X -2218(periods)X -2477(of)X -2567(time,)X -2752(this)X -2890(would)X -3113(improve)X -3403(performance.)X -3873(For)X -4007(example,)X -555 1023(processes)N -885(must)X -1062(acquire)X -1321(exclusive)X -1646(access)X -1874(to)X -1958(buffer)X -2177(pool)X -2341(metadata)X -2653(in)X -2737(order)X -2929(to)X -3013(\256nd)X -3159(and)X -3297(pin)X -3421(a)X -3479(buffer)X -3698(in)X -3781(shared)X -4012(memory.)X -555 1113(This)N -721(semaphore)X -1093(is)X -1170(requested)X -1502(most)X -1681(frequently)X -2034(in)X -2119(LIBTP.)X -2404(However,)X -2742(once)X -2917(it)X -2984(is)X -3060(acquired,)X -3380(only)X -3545(a)X -3604(few)X -3748(instructions)X -4144(must)X -555 1203(be)N -656(executed)X -966(before)X -1196(it)X -1264(is)X -1341(released.)X -1669(On)X -1791(one)X -1931(architecture)X -2335(for)X -2453(which)X -2673(we)X -2791(were)X -2972(able)X -3130(to)X -3216(gather)X -3441(detailed)X -3719(pro\256ling)X -4018(informa-)X -555 1293(tion,)N -729(the)X -857(cost)X -1015(of)X -1111(the)X -1238(semaphore)X -1615(calls)X -1791(accounted)X -2146(for)X -2269(25%)X -2445(of)X -2541(the)X -2668(total)X -2839(time)X -3010(spent)X -3208(updating)X -3517(the)X -3644(metadata.)X -4003(This)X -4174(was)X -555 1383(fairly)N -749(consistent)X -1089(across)X -1310(most)X -1485(of)X -1572(the)X -1690(critical)X -1933(sections.)X -755 1506(In)N -848(an)X -950(attempt)X -1216(to)X -1304(quantify)X -1597(the)X -1720(overhead)X -2040(of)X -2132(kernel)X -2358(synchronization,)X -2915(we)X -3034(ran)X -3162(tests)X -3329(on)X -3434(a)X -3495(version)X -3756(of)X -3848(4.3BSD-Reno)X -555 1596(which)N -786(had)X -937(been)X -1123(modi\256ed)X -1441(to)X -1537(support)X -1811(binary)X -2050(semaphore)X -2432(facilities)X -2742(similar)X -2998(to)X -3094(those)X -3297(described)X -3639(in)X -3735([POSIX91].)X -4174(The)X -555 1686(hardware)N -880(platform)X -1181(consisted)X -1504(of)X -1595(an)X -1695(HP300)X -1941(\(33MHz)X -2237(MC68030\))X -2612(workstation)X -3014(with)X -3180(16MBytes)X -3537(of)X -3628(main)X -3812(memory,)X -4123(and)X -4263(a)X -555 1776(600MByte)N -920(HP7959)X -1205(SCSI)X -1396(disk)X -1552(\(17)X -1682(ms)X -1798(average)X -2072(seek)X -2237(time\).)X -2468(We)X -2602(ran)X -2727(three)X -2910(sets)X -3052(of)X -3141(comparisons)X -3568(which)X -3786(are)X -3907(summarized)X -555 1866(in)N -645(\256gure)X -860(\256ve.)X -1028(In)X -1123(each)X -1299(comparison)X -1701(we)X -1823(ran)X -1954(two)X -2102(tests,)X -2292(one)X -2436(using)X -2637(hardware)X -2965(spinlocks)X -3295(and)X -3438(the)X -3563(other)X -3755(using)X -3955(kernel)X -4183(call)X -555 1956(synchronization.)N -1135(Since)X -1341(the)X -1467(test)X -1606(was)X -1758(run)X -1892(single-user,)X -2291(none)X -2474(of)X -2568(the)X -2693(the)X -2818(locks)X -3014(were)X -3198(contested.)X -3568(In)X -3662(the)X -3787(\256rst)X -3938(two)X -4085(sets)X -4232(of)X -555 2046(tests,)N -743(we)X -863(ran)X -992(the)X -1116(full)X -1253(transaction)X -1631(processing)X -2000(benchmark)X -2383(described)X -2717(in)X -2805(section)X -3058(5.1.)X -3223(In)X -3315(one)X -3456(case)X -3620(we)X -3739(ran)X -3867(with)X -4034(both)X -4201(the)X -555 2136(database)N -854(and)X -992(log)X -1116(on)X -1218(the)X -1338(same)X -1525(disk)X -1680(\(1)X -1769(Disk\))X -1969(and)X -2107(in)X -2191(the)X -2311(second,)X -2576(we)X -2692(ran)X -2817(with)X -2981(the)X -3101(database)X -3400(and)X -3538(log)X -3661(on)X -3762(separate)X -4047(disks)X -4232(\(2)X -555 2226(Disk\).)N -800(In)X -894(the)X -1019(last)X -1157(test,)X -1315(we)X -1436(wanted)X -1695(to)X -1784(create)X -2004(a)X -2067(CPU)X -2249(bound)X -2476(environment,)X -2928(so)X -3026(we)X -3146(used)X -3319(a)X -3381(database)X -3684(small)X -3883(enough)X -4145(to)X -4233(\256t)X -555 2316(completely)N -941(in)X -1033(the)X -1161(cache)X -1375(and)X -1521(issued)X -1751(read-only)X -2089(transactions.)X -2541(The)X -2695(results)X -2933(in)X -3024(\256gure)X -3240(\256ve)X -3389(express)X -3659(the)X -3786(kernel)X -4016(call)X -4161(syn-)X -555 2406(chronization)N -980(performance)X -1411(as)X -1502(a)X -1562(percentage)X -1935(of)X -2026(the)X -2148(spinlock)X -2443(performance.)X -2914(For)X -3049(example,)X -3365(in)X -3451(the)X -3573(1)X -3637(disk)X -3794(case,)X -3977(the)X -4098(kernel)X -555 2496(call)N -697(implementation)X -1225(achieved)X -1537(4.4)X -1662(TPS)X -1824(\(transactions)X -2259(per)X -2387(second\))X -2662(while)X -2865(the)X -2988(semaphore)X -3361(implementation)X -3888(achieved)X -4199(4.6)X -555 2586(TPS,)N -735(and)X -874(the)X -995(relative)X -1259(performance)X -1689(of)X -1779(the)X -1900(kernel)X -2123(synchronization)X -2657(is)X -2732(96%)X -2901(that)X -3043(of)X -3132(the)X -3252(spinlock)X -3545(\(100)X -3714(*)X -3776(4.4)X -3898(/)X -3942(4.6\).)X -4111(There)X -555 2676(are)N -674(two)X -814(striking)X -1078(observations)X -1503(from)X -1679(these)X -1864(results:)X -10 f -635 2799(g)N -1 f -755(even)X -927(when)X -1121(the)X -1239(system)X -1481(is)X -1554(disk)X -1707(bound,)X -1947(the)X -2065(CPU)X -2240(cost)X -2389(of)X -2476(synchronization)X -3008(is)X -3081(noticeable,)X -3451(and)X -10 f -635 2922(g)N -1 f -755(when)X -949(we)X -1063(are)X -1182(CPU)X -1357(bound,)X -1597(the)X -1715(difference)X -2062(is)X -2135(dramatic)X -2436(\(67%\).)X -3 f -555 3108(4.4.)N -715(Transaction)X -1148(Protected)X -1499(Access)X -1747(Methods)X -1 f -755 3231(The)N -903(B-tree)X -1127(and)X -1266(\256xed)X -1449(length)X -1671(recno)X -1872(\(record)X -2127(number\))X -2421(access)X -2649(methods)X -2942(have)X -3116(been)X -3290(modi\256ed)X -3596(to)X -3680(provide)X -3947(transaction)X -555 3321(protection.)N -941(Whereas)X -1244(the)X -1363(previously)X -1722(published)X -2054(interface)X -2357(to)X -2440(the)X -2559(access)X -2786(routines)X -3065(had)X -3202(separate)X -3487(open)X -3664(calls)X -3832(for)X -3946(each)X -4114(of)X -4201(the)X -10 f -555 3507(h)N -579(hhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhh)X -1 Dt -2978 5036 MXY - 2978 5036 lineto - 2978 4662 lineto - 3093 4662 lineto - 3093 5036 lineto - 2978 5036 lineto -closepath 21 2978 4662 3093 5036 Dp -2518 MX - 2518 5036 lineto - 2518 3960 lineto - 2633 3960 lineto - 2633 5036 lineto - 2518 5036 lineto -closepath 3 2518 3960 2633 5036 Dp -2059 MX - 2059 5036 lineto - 2059 3946 lineto - 2174 3946 lineto - 2174 5036 lineto - 2059 5036 lineto -closepath 1 2059 3946 2174 5036 Dp -3 f -7 s -2912 5141(Read-only)N -1426 3767(of)N -1487(Spinlock)X -1710(Throughput)X -1480 3710(Throughput)N -1786(as)X -1850(a)X -1892(%)X -11 s -1670 4843(20)N -1670 4614(40)N -1670 4384(60)N -1670 4155(80)N -1648 3925(100)N -7 s -2041 5141(1)N -2083(Disk)X -2490(2)X -2532(Disks)X -5 Dt -1829 5036 MXY -1494 0 Dl -4 Ds -1 Dt -1829 4806 MXY -1494 0 Dl -1829 4577 MXY -1494 0 Dl -1829 4347 MXY -1494 0 Dl -1829 4118 MXY -1494 0 Dl -1829 3888 MXY -1494 0 Dl -3 Dt --1 Ds -8 s -555 5360(Figure)N -753(5:)X -823(Kernel)X -1028(Overhead)X -1315(for)X -1413(System)X -1625(Call)X -1756(Synchronization.)X -1 f -2254(The)X -2370(performance)X -2708(of)X -2778(the)X -2873(kernel)X -3049(call)X -3158(synchronization)X -3583(is)X -3643(expressed)X -3911(as)X -3980(a)X -4024(percentage)X -555 5450(of)N -625(the)X -720(spinlock)X -954(synchronization)X -1379(performance.)X -1749(In)X -1819(disk)X -1943(bound)X -2120(cases)X -2271(\(1)X -2341(Disk)X -2479(and)X -2588(2)X -2637(Disks\),)X -2837(we)X -2928(see)X -3026(that)X -3139(4-6%)X -3294(of)X -3364(the)X -3459(performance)X -3797(is)X -3857(lost)X -3966(due)X -4074(to)X -4140(kernel)X -555 5540(calls)N -688(while)X -846(in)X -912(the)X -1006(CPU)X -1147(bound)X -1323(case,)X -1464(we)X -1554(have)X -1690(lost)X -1799(67%)X -1932(of)X -2001(the)X -2095(performance)X -2432(due)X -2540(to)X -2606(kernel)X -2781(calls.)X - -10 p -%%Page: 10 10 -8 s 8 xH 0 xS 1 f -10 s -3 f -1 f -555 630(access)N -781(methods,)X -1092(we)X -1206(now)X -1364(have)X -1536(an)X -1632(integrated)X -1973(open)X -2149(call)X -2285(with)X -2447(the)X -2565(following)X -2896(calling)X -3134(conventions:)X -7 f -715 753(DB)N -859(*dbopen)X -1243(\(const)X -1579(char)X -1819(*file,)X -2155(int)X -2347(flags,)X -2683(int)X -2875(mode,)X -3163(DBTYPE)X -3499(type,)X -1291 843(int)N -1483(dbflags,)X -1915(const)X -2203(void)X -2443(*openinfo\))X -1 f -555 966(where)N -2 f -774(\256le)X -1 f -894(is)X -969(the)X -1089(name)X -1285(of)X -1374(the)X -1494(\256le)X -1618(being)X -1818(opened,)X -2 f -2092(\257ags)X -1 f -2265(and)X -2 f -2402(mode)X -1 f -2597(are)X -2717(the)X -2836(standard)X -3129(arguments)X -3484(to)X -3 f -3567(open)X -1 f -3731(\(2\),)X -2 f -3866(type)X -1 f -4021(is)X -4095(one)X -4232(of)X -555 1056(the)N -680(access)X -913(method)X -1180(types,)X -2 f -1396(db\257ags)X -1 f -1654(indicates)X -1966(the)X -2091(mode)X -2296(of)X -2390(the)X -2515(buffer)X -2739(pool)X -2907(and)X -3049(transaction)X -3427(protection,)X -3798(and)X -2 f -3940(openinfo)X -1 f -4246(is)X -555 1146(the)N -681(access)X -915(method)X -1183(speci\256c)X -1456(information.)X -1902(Currently,)X -2257(the)X -2383(possible)X -2673(values)X -2906(for)X -2 f -3028(db\257ags)X -1 f -3287(are)X -3414(DB_SHARED)X -3912(and)X -4055(DB_TP)X -555 1236(indicating)N -895(that)X -1035(buffers)X -1283(should)X -1516(be)X -1612(kept)X -1770(in)X -1852(a)X -1908(shared)X -2138(buffer)X -2355(pool)X -2517(and)X -2653(that)X -2793(the)X -2911(\256le)X -3033(should)X -3266(be)X -3362(transaction)X -3734(protected.)X -755 1359(The)N -900(modi\256cations)X -1355(required)X -1643(to)X -1725(add)X -1861(transaction)X -2233(protection)X -2578(to)X -2660(an)X -2756(access)X -2982(method)X -3242(are)X -3361(quite)X -3541(simple)X -3774(and)X -3910(localized.)X -715 1482(1.)N -795(Replace)X -1074(\256le)X -2 f -1196(open)X -1 f -1372(with)X -2 f -1534(buf_open)X -1 f -1832(.)X -715 1572(2.)N -795(Replace)X -1074(\256le)X -2 f -1196(read)X -1 f -1363(and)X -2 f -1499(write)X -1 f -1683(calls)X -1850(with)X -2012(buffer)X -2229(manager)X -2526(calls)X -2693(\()X -2 f -2720(buf_get)X -1 f -(,)S -2 f -3000(buf_unpin)X -1 f -3324(\).)X -715 1662(3.)N -795(Precede)X -1070(buffer)X -1287(manager)X -1584(calls)X -1751(with)X -1913(an)X -2009(appropriate)X -2395(\(read)X -2581(or)X -2668(write\))X -2880(lock)X -3038(call.)X -715 1752(4.)N -795(Before)X -1034(updates,)X -1319(issue)X -1499(a)X -1555(logging)X -1819(operation.)X -715 1842(5.)N -795(After)X -985(data)X -1139(have)X -1311(been)X -1483(accessed,)X -1805(release)X -2049(the)X -2167(buffer)X -2384(manager)X -2681(pin.)X -715 1932(6.)N -795(Provide)X -1064(undo/redo)X -1409(code)X -1581(for)X -1695(each)X -1863(type)X -2021(of)X -2108(log)X -2230(record)X -2456(de\256ned.)X -555 2071(The)N -702(following)X -1035(code)X -1209(fragments)X -1552(show)X -1743(how)X -1903(to)X -1987(transaction)X -2361(protect)X -2606(several)X -2856(updates)X -3123(to)X -3206(a)X -3263(B-tree.)X -7 s -3484 2039(3)N -10 s -3533 2071(In)N -3621(the)X -3740(unprotected)X -4140(case,)X -555 2161(an)N -652(open)X -829(call)X -966(is)X -1040(followed)X -1346(by)X -1447(a)X -1504(read)X -1664(call)X -1801(to)X -1884(obtain)X -2105(the)X -2224(meta-data)X -2562(for)X -2677(the)X -2796(B-tree.)X -3058(Instead,)X -3331(we)X -3446(issue)X -3627(an)X -3724(open)X -3901(to)X -3984(the)X -4102(buffer)X -555 2251(manager)N -852(to)X -934(obtain)X -1154(a)X -1210(\256le)X -1332(id)X -1414(and)X -1550(a)X -1606(buffer)X -1823(request)X -2075(to)X -2157(obtain)X -2377(the)X -2495(meta-data)X -2832(as)X -2919(shown)X -3148(below.)X -7 f -715 2374(char)N -955(*path;)X -715 2464(int)N -907(fid,)X -1147(flags,)X -1483(len,)X -1723(mode;)X -715 2644(/*)N -859(Obtain)X -1195(a)X -1291(file)X -1531(id)X -1675(with)X -1915(which)X -2203(to)X -2347(access)X -2683(the)X -2875(buffer)X -3211(pool)X -3451(*/)X -715 2734(fid)N -907(=)X -1003(buf_open\(path,)X -1723(flags,)X -2059(mode\);)X -715 2914(/*)N -859(Read)X -1099(the)X -1291(meta)X -1531(data)X -1771(\(page)X -2059(0\))X -2203(for)X -2395(the)X -2587(B-tree)X -2923(*/)X -715 3004(if)N -859(\(tp_lock\(fid,)X -1531(0,)X -1675(READ_LOCK\)\))X -1003 3094(return)N -1339(error;)X -715 3184(meta_data_ptr)N -1387(=)X -1483(buf_get\(fid,)X -2107(0,)X -2251(BF_PIN,)X -2635(&len\);)X -1 f -555 3307(The)N -714(BF_PIN)X -1014(argument)X -1350(to)X -2 f -1445(buf_get)X -1 f -1718(indicates)X -2036(that)X -2189(we)X -2316(wish)X -2500(to)X -2595(leave)X -2798(this)X -2946(page)X -3131(pinned)X -3382(in)X -3477(memory)X -3777(so)X -3881(that)X -4034(it)X -4111(is)X -4197(not)X -555 3397(swapped)N -862(out)X -990(while)X -1194(we)X -1314(are)X -1439(accessing)X -1772(it.)X -1881(The)X -2031(last)X -2167(argument)X -2495(to)X -2 f -2582(buf_get)X -1 f -2847(returns)X -3095(the)X -3218(number)X -3488(of)X -3580(bytes)X -3774(on)X -3879(the)X -4002(page)X -4179(that)X -555 3487(were)N -732(valid)X -912(so)X -1003(that)X -1143(the)X -1261(access)X -1487(method)X -1747(may)X -1905(initialize)X -2205(the)X -2323(page)X -2495(if)X -2564(necessary.)X -755 3610(Next,)N -955(consider)X -1251(inserting)X -1555(a)X -1615(record)X -1845(on)X -1949(a)X -2009(particular)X -2341(page)X -2517(of)X -2608(a)X -2668(B-tree.)X -2932(In)X -3022(the)X -3143(unprotected)X -3545(case,)X -3727(we)X -3844(read)X -4006(the)X -4127(page,)X -555 3700(call)N -2 f -693(_bt_insertat)X -1 f -1079(,)X -1121(and)X -1258(write)X -1444(the)X -1563(page.)X -1776(Instead,)X -2049(we)X -2164(lock)X -2323(the)X -2442(page,)X -2635(request)X -2888(the)X -3007(buffer,)X -3245(log)X -3368(the)X -3487(change,)X -3756(modify)X -4008(the)X -4127(page,)X -555 3790(and)N -691(release)X -935(the)X -1053(buffer.)X -7 f -715 3913(int)N -907(fid,)X -1147(len,)X -1387(pageno;)X -1867(/*)X -2011(Identifies)X -2539(the)X -2731(buffer)X -3067(*/)X -715 4003(int)N -907(index;)X -1867(/*)X -2011(Location)X -2443(at)X -2587(which)X -2875(to)X -3019(insert)X -3355(the)X -3547(new)X -3739(pair)X -3979(*/)X -715 4093(DBT)N -907(*keyp,)X -1243(*datap;)X -1867(/*)X -2011(Key/Data)X -2443(pair)X -2683(to)X -2827(be)X -2971(inserted)X -3403(*/)X -715 4183(DATUM)N -1003(*d;)X -1867(/*)X -2011(Key/data)X -2443(structure)X -2923(to)X -3067(insert)X -3403(*/)X -715 4363(/*)N -859(Lock)X -1099(and)X -1291(request)X -1675(the)X -1867(buffer)X -2203(*/)X -715 4453(if)N -859(\(tp_lock\(fid,)X -1531(pageno,)X -1915(WRITE_LOCK\)\))X -1003 4543(return)N -1339(error;)X -715 4633(buffer_ptr)N -1243(=)X -1339(buf_get\(fid,)X -1963(pageno,)X -2347(BF_PIN,)X -2731(&len\);)X -715 4813(/*)N -859(Log)X -1051(and)X -1243(perform)X -1627(the)X -1819(update)X -2155(*/)X -715 4903(log_insdel\(BTREE_INSERT,)N -1915(fid,)X -2155(pageno,)X -2539(keyp,)X -2827(datap\);)X -715 4993(_bt_insertat\(buffer_ptr,)N -1915(d,)X -2059(index\);)X -715 5083(buf_unpin\(buffer_ptr\);)N -1 f -555 5206(Succinctly,)N -942(the)X -1068(algorithm)X -1407(for)X -1529(turning)X -1788(unprotected)X -2195(code)X -2375(into)X -2527(protected)X -2854(code)X -3034(is)X -3115(to)X -3205(replace)X -3466(read)X -3633(operations)X -3995(with)X -2 f -4165(lock)X -1 f -555 5296(and)N -2 f -691(buf_get)X -1 f -951(operations)X -1305(and)X -1441(write)X -1626(operations)X -1980(with)X -2 f -2142(log)X -1 f -2264(and)X -2 f -2400(buf_unpin)X -1 f -2744(operations.)X -8 s -10 f -555 5458(hhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhh)N -5 s -1 f -727 5536(3)N -8 s -766 5561(The)N -884(following)X -1152(code)X -1291(fragments)X -1565(are)X -1661(examples,)X -1937(but)X -2038(do)X -2120(not)X -2220(de\256ne)X -2394(the)X -2490(\256nal)X -2622(interface.)X -2894(The)X -3011(\256nal)X -3143(interface)X -3383(will)X -3501(be)X -3579(determined)X -3884(after)X -4018(LIBTP)X -4214(has)X -555 5633(been)N -691(fully)X -828(integrated)X -1099(with)X -1229(the)X -1323(most)X -1464(recent)X -3 f -1635(db)X -1 f -1707(\(3\))X -1797(release)X -1989(from)X -2129(the)X -2223(Computer)X -2495(Systems)X -2725(Research)X -2974(Group)X -3153(at)X -3215(University)X -3501(of)X -3570(California,)X -3861(Berkeley.)X - -11 p -%%Page: 11 11 -8 s 8 xH 0 xS 1 f -10 s -3 f -555 630(5.)N -655(Performance)X -1 f -755 753(In)N -845(this)X -983(section,)X -1253(we)X -1370(present)X -1625(the)X -1746(results)X -1978(of)X -2067(two)X -2209(very)X -2374(different)X -2673(benchmarks.)X -3103(The)X -3250(\256rst)X -3396(is)X -3471(an)X -3569(online)X -3791(transaction)X -4165(pro-)X -555 843(cessing)N -824(benchmark,)X -1234(similar)X -1489(to)X -1584(the)X -1715(standard)X -2020(TPCB,)X -2272(but)X -2407(has)X -2547(been)X -2732(adapted)X -3015(to)X -3110(run)X -3250(in)X -3345(a)X -3414(desktop)X -3696(environment.)X -4174(The)X -555 933(second)N -798(emulates)X -1103(a)X -1159(computer-aided)X -1683(design)X -1912(environment)X -2337(and)X -2473(provides)X -2769(more)X -2954(complex)X -3250(query)X -3453(processing.)X -3 f -555 1119(5.1.)N -715(Transaction)X -1148(Processing)X -1533(Benchmark)X -1 f -755 1242(For)N -887(this)X -1023(section,)X -1291(all)X -1392(performance)X -1820(numbers)X -2117(shown)X -2346(except)X -2576(for)X -2690(the)X -2808(commercial)X -3207(database)X -3504(system)X -3746(were)X -3923(obtained)X -4219(on)X -555 1332(a)N -614(DECstation)X -1009(5000/200)X -1333(with)X -1497(32MBytes)X -1852(of)X -1941(memory)X -2230(running)X -2501(Ultrix)X -2714(V4.0,)X -2914(accessing)X -3244(a)X -3302(DEC)X -3484(RZ57)X -3688(1GByte)X -3959(disk)X -4114(drive.)X -555 1422(The)N -720(commercial)X -1139(relational)X -1482(database)X -1799(system)X -2061(tests)X -2242(were)X -2438(run)X -2584(on)X -2703(a)X -2778(comparable)X -3192(machine,)X -3523(a)X -3598(Sparcstation)X -4033(1+)X -4157(with)X -555 1512(32MBytes)N -915(memory)X -1209(and)X -1352(a)X -1415(1GByte)X -1691(external)X -1976(disk)X -2135(drive.)X -2366(The)X -2517(database,)X -2840(binaries)X -3120(and)X -3262(log)X -3390(resided)X -3648(on)X -3754(the)X -3878(same)X -4069(device.)X -555 1602(Reported)N -869(times)X -1062(are)X -1181(the)X -1299(means)X -1524(of)X -1611(\256ve)X -1751(tests)X -1913(and)X -2049(have)X -2221(standard)X -2513(deviations)X -2862(within)X -3086(two)X -3226(percent)X -3483(of)X -3570(the)X -3688(mean.)X -755 1725(The)N -905(test)X -1041(database)X -1343(was)X -1493(con\256gured)X -1861(according)X -2203(to)X -2290(the)X -2413(TPCB)X -2637(scaling)X -2889(rules)X -3070(for)X -3189(a)X -3250(10)X -3355(transaction)X -3732(per)X -3860(second)X -4108(\(TPS\))X -555 1815(system)N -817(with)X -999(1,000,000)X -1359(account)X -1649(records,)X -1946(100)X -2106(teller)X -2311(records,)X -2607(and)X -2762(10)X -2881(branch)X -3139(records.)X -3455(Where)X -3709(TPS)X -3885(numbers)X -4200(are)X -555 1905(reported,)N -865(we)X -981(are)X -1102(running)X -1373(a)X -1431(modi\256ed)X -1737(version)X -1995(of)X -2084(the)X -2203(industry)X -2486(standard)X -2779(transaction)X -3152(processing)X -3516(benchmark,)X -3914(TPCB.)X -4174(The)X -555 1995(TPCB)N -780(benchmark)X -1163(simulates)X -1491(a)X -1553(withdrawal)X -1940(performed)X -2301(by)X -2407(a)X -2469(hypothetical)X -2891(teller)X -3082(at)X -3166(a)X -3228(hypothetical)X -3650(bank.)X -3872(The)X -4022(database)X -555 2085(consists)N -831(of)X -921(relations)X -1220(\(\256les\))X -1430(for)X -1547(accounts,)X -1871(branches,)X -2200(tellers,)X -2439(and)X -2578(history.)X -2863(For)X -2997(each)X -3168(transaction,)X -3563(the)X -3684(account,)X -3976(teller,)X -4183(and)X -555 2175(branch)N -795(balances)X -1093(must)X -1269(be)X -1366(updated)X -1641(to)X -1724(re\257ect)X -1946(the)X -2065(withdrawal)X -2447(and)X -2584(a)X -2640(history)X -2882(record)X -3108(is)X -3181(written)X -3428(which)X -3644(contains)X -3931(the)X -4049(account)X -555 2265(id,)N -657(branch)X -896(id,)X -998(teller)X -1183(id,)X -1285(and)X -1421(the)X -1539(amount)X -1799(of)X -1886(the)X -2004(withdrawal)X -2385([TPCB90].)X -755 2388(Our)N -914(implementation)X -1450(of)X -1551(the)X -1683(benchmark)X -2074(differs)X -2317(from)X -2506(the)X -2637(speci\256cation)X -3075(in)X -3170(several)X -3431(aspects.)X -3736(The)X -3894(speci\256cation)X -555 2478(requires)N -840(that)X -985(the)X -1108(database)X -1410(keep)X -1587(redundant)X -1933(logs)X -2091(on)X -2196(different)X -2498(devices,)X -2784(but)X -2911(we)X -3030(use)X -3162(a)X -3223(single)X -3439(log.)X -3606(Furthermore,)X -4052(all)X -4157(tests)X -555 2568(were)N -734(run)X -863(on)X -965(a)X -1023(single,)X -1256(centralized)X -1631(system)X -1875(so)X -1968(there)X -2151(is)X -2226(no)X -2328(notion)X -2553(of)X -2641(remote)X -2885(accesses.)X -3219(Finally,)X -3486(we)X -3601(calculated)X -3948(throughput)X -555 2658(by)N -662(dividing)X -955(the)X -1080(total)X -1249(elapsed)X -1517(time)X -1686(by)X -1793(the)X -1918(number)X -2190(of)X -2284(transactions)X -2694(processed)X -3038(rather)X -3253(than)X -3418(by)X -3525(computing)X -3894(the)X -4018(response)X -555 2748(time)N -717(for)X -831(each)X -999(transaction.)X -755 2871(The)N -912(performance)X -1351(comparisons)X -1788(focus)X -1993(on)X -2104(traditional)X -2464(Unix)X -2655(techniques)X -3029(\(unprotected,)X -3486(using)X -3 f -3690(\257ock)X -1 f -3854(\(2\))X -3979(and)X -4126(using)X -3 f -555 2961(fsync)N -1 f -733(\(2\)\))X -884(and)X -1030(a)X -1096(commercial)X -1504(relational)X -1836(database)X -2142(system.)X -2433(Well-behaved)X -2913(applications)X -3329(using)X -3 f -3531(\257ock)X -1 f -3695(\(2\))X -3818(are)X -3946(guaranteed)X -555 3051(that)N -704(concurrent)X -1077(processes')X -1441(updates)X -1715(do)X -1824(not)X -1955(interact)X -2225(with)X -2396(one)X -2541(another,)X -2831(but)X -2962(no)X -3070(guarantees)X -3442(about)X -3648(atomicity)X -3978(are)X -4105(made.)X -555 3141(That)N -731(is,)X -833(if)X -911(the)X -1038(system)X -1289(crashes)X -1555(in)X -1646(mid-transaction,)X -2198(only)X -2369(parts)X -2554(of)X -2649(that)X -2797(transaction)X -3177(will)X -3329(be)X -3433(re\257ected)X -3738(in)X -3828(the)X -3954 0.3125(after-crash)AX -555 3231(state)N -725(of)X -815(the)X -936(database.)X -1276(The)X -1424(use)X -1554(of)X -3 f -1643(fsync)X -1 f -1821(\(2\))X -1937(at)X -2017(transaction)X -2391(commit)X -2657(time)X -2821(provides)X -3119(guarantees)X -3485(of)X -3574(durability)X -3907(after)X -4077(system)X -555 3321(failure.)N -825(However,)X -1160(there)X -1341(is)X -1414(no)X -1514(mechanism)X -1899(to)X -1981(perform)X -2260(transaction)X -2632(abort.)X -3 f -555 3507(5.1.1.)N -775(Single-User)X -1191(Tests)X -1 f -755 3630(These)N -978(tests)X -1151(compare)X -1459(LIBTP)X -1712(in)X -1804(a)X -1870(variety)X -2123(of)X -2220(con\256gurations)X -2708(to)X -2800(traditional)X -3159(UNIX)X -3390(solutions)X -3708(and)X -3854(a)X -3920(commercial)X -555 3720(relational)N -884(database)X -1187(system)X -1435(\(RDBMS\).)X -1814(To)X -1929(demonstrate)X -2347(the)X -2471(server)X -2694(architecture)X -3100(we)X -3220(built)X -3392(a)X -3454(front)X -3636(end)X -3777(test)X -3913(process)X -4179(that)X -555 3810(uses)N -732(TCL)X -922([OUST90])X -1304(to)X -1405(parse)X -1614(database)X -1930(access)X -2175(commands)X -2561(and)X -2716(call)X -2870(the)X -3006(database)X -3321(access)X -3565(routines.)X -3901(In)X -4006(one)X -4160(case)X -555 3900(\(SERVER\),)N -956(frontend)X -1249(and)X -1386(backend)X -1675(processes)X -2004(were)X -2181(created)X -2434(which)X -2650(communicated)X -3142(via)X -3260(an)X -3356(IP)X -3447(socket.)X -3712(In)X -3799(the)X -3917(second)X -4160(case)X -555 3990(\(TCL\),)N -802(a)X -860(single)X -1073(process)X -1336(read)X -1497(queries)X -1751(from)X -1929(standard)X -2223(input,)X -2429(parsed)X -2660(them,)X -2861(and)X -2998(called)X -3211(the)X -3330(database)X -3628(access)X -3855(routines.)X -4174(The)X -555 4080(performance)N -987(difference)X -1338(between)X -1630(the)X -1752(TCL)X -1927(and)X -2067(SERVER)X -2397(tests)X -2563(quanti\256es)X -2898(the)X -3020(communication)X -3542(overhead)X -3861(of)X -3952(the)X -4074(socket.)X -555 4170(The)N -732(RDBMS)X -1063(implementation)X -1617(used)X -1816(embedded)X -2198(SQL)X -2401(in)X -2515(C)X -2620(with)X -2814(stored)X -3062(database)X -3391(procedures.)X -3835(Therefore,)X -4224(its)X -555 4260(con\256guration)N -1003(is)X -1076(a)X -1132(hybrid)X -1361(of)X -1448(the)X -1566(single)X -1777(process)X -2038(architecture)X -2438(and)X -2574(the)X -2692(server)X -2909(architecture.)X -3349(The)X -3494(graph)X -3697(in)X -3779(\256gure)X -3986(six)X -4099(shows)X -555 4350(a)N -611(comparison)X -1005(of)X -1092(the)X -1210(following)X -1541(six)X -1654(con\256gurations:)X -1126 4506(LIBTP)N -1552(Uses)X -1728(the)X -1846(LIBTP)X -2088(library)X -2322(in)X -2404(a)X -2460(single)X -2671(application.)X -1126 4596(TCL)N -1552(Uses)X -1728(the)X -1846(LIBTP)X -2088(library)X -2322(in)X -2404(a)X -2460(single)X -2671(application,)X -3067(requires)X -3346(query)X -3549(parsing.)X -1126 4686(SERVER)N -1552(Uses)X -1728(the)X -1846(LIBTP)X -2088(library)X -2322(in)X -2404(a)X -2460(server)X -2677(con\256guration,)X -3144(requires)X -3423(query)X -3626(parsing.)X -1126 4776(NOTP)N -1552(Uses)X -1728(no)X -1828(locking,)X -2108(logging,)X -2392(or)X -2479(concurrency)X -2897(control.)X -1126 4866(FLOCK)N -1552(Uses)X -3 f -1728(\257ock)X -1 f -1892(\(2\))X -2006(for)X -2120(concurrency)X -2538(control)X -2785(and)X -2921(nothing)X -3185(for)X -3299(durability.)X -1126 4956(FSYNC)N -1552(Uses)X -3 f -1728(fsync)X -1 f -1906(\(2\))X -2020(for)X -2134(durability)X -2465(and)X -2601(nothing)X -2865(for)X -2979(concurrency)X -3397(control.)X -1126 5046(RDBMS)N -1552(Uses)X -1728(a)X -1784(commercial)X -2183(relational)X -2506(database)X -2803(system.)X -755 5235(The)N -902(results)X -1133(show)X -1324(that)X -1466(LIBTP,)X -1730(both)X -1894(in)X -1978(the)X -2098(procedural)X -2464(and)X -2602(parsed)X -2834(environments,)X -3312(is)X -3387(competitive)X -3787(with)X -3951(a)X -4009(commer-)X -555 5325(cial)N -692(system)X -935(\(comparing)X -1326(LIBTP,)X -1589(TCL,)X -1781(and)X -1917(RDBMS\).)X -2263(Compared)X -2617(to)X -2699(existing)X -2972(UNIX)X -3193(solutions,)X -3521(LIBTP)X -3763(is)X -3836(approximately)X -555 5415(15%)N -738(slower)X -988(than)X -1162(using)X -3 f -1371(\257ock)X -1 f -1535(\(2\))X -1665(or)X -1768(no)X -1884(protection)X -2245(but)X -2383(over)X -2562(80%)X -2745(better)X -2964(than)X -3137(using)X -3 f -3345(fsync)X -1 f -3523(\(2\))X -3652(\(comparing)X -4057(LIBTP,)X -555 5505(FLOCK,)N -857(NOTP,)X -1106(and)X -1242(FSYNC\).)X - -12 p -%%Page: 12 12 -10 s 10 xH 0 xS 1 f -3 f -8 s -3500 2184(RDBMS)N -1 Dt -3553 2085 MXY - 3553 2085 lineto - 3676 2085 lineto - 3676 1351 lineto - 3553 1351 lineto - 3553 2085 lineto -closepath 16 3553 1351 3676 2085 Dp -2018 2184(SERVER)N -1720 1168 MXY -0 917 Dl -122 0 Dl -0 -917 Dl --122 0 Dl -1715 2184(TCL)N -2087 1534 MXY - 2087 1534 lineto - 2209 1534 lineto - 2209 2085 lineto - 2087 2085 lineto - 2087 1534 lineto -closepath 12 2087 1534 2209 2085 Dp -3187 MX - 3187 1534 lineto - 3309 1534 lineto - 3309 2085 lineto - 3187 2085 lineto - 3187 1534 lineto -closepath 19 3187 1534 3309 2085 Dp -3142 2184(FSYNC)N -2425(NOTP)X -2453 955 MXY - 2453 955 lineto - 2576 955 lineto - 2576 2085 lineto - 2453 2085 lineto - 2453 955 lineto -closepath 21 2453 955 2576 2085 Dp -2820 1000 MXY - 2820 1000 lineto - 2942 1000 lineto - 2942 2085 lineto - 2820 2085 lineto - 2820 1000 lineto -closepath 14 2820 1000 2942 2085 Dp -5 Dt -1231 2085 MXY -2567 0 Dl -4 Ds -1 Dt -1231 1840 MXY -2567 0 Dl -1231 1596 MXY -2567 0 Dl -1231 1351 MXY -2567 0 Dl -1231 1108 MXY -2567 0 Dl -1231 863 MXY -2567 0 Dl -11 s -1087 1877(2)N -1087 1633(4)N -1087 1388(6)N -1087 1145(8)N -1065 900(10)N -1028 763(TPS)N --1 Ds -1353 2085 MXY - 1353 2085 lineto - 1353 1151 lineto - 1476 1151 lineto - 1476 2085 lineto - 1353 2085 lineto -closepath 3 1353 1151 1476 2085 Dp -8 s -1318 2184(LIBTP)N -2767(FLOCK)X -3 Dt --1 Ds -10 s -1597 2399(Figure)N -1844(6:)X -1931(Single-User)X -2347(Performance)X -2814(Comparison.)X -1 f -10 f -555 2579(h)N -579(hhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhh)X -3 f -555 2855(5.1.2.)N -775(Multi-User)X -1174(Tests)X -1 f -755 2978(While)N -975(the)X -1097(single-user)X -1473(tests)X -1639(form)X -1819(a)X -1878(basis)X -2061(for)X -2178(comparing)X -2544(LIBTP)X -2789(to)X -2874(other)X -3062(systems,)X -3358(our)X -3488(goal)X -3649(in)X -3734(multi-user)X -4086(testing)X -555 3068(was)N -714(to)X -810(analyze)X -1089(its)X -1197(scalability.)X -1579(To)X -1701(this)X -1849(end,)X -2018(we)X -2145(have)X -2330(run)X -2470(the)X -2601(benchmark)X -2991(in)X -3086(three)X -3280(modes,)X -3542(the)X -3673(normal)X -3933(disk)X -4099(bound)X -555 3158(con\256guration)N -1010(\(\256gure)X -1252(seven\),)X -1510(a)X -1573(CPU)X -1755(bound)X -1982(con\256guration)X -2436(\(\256gure)X -2677(eight,)X -2884(READ-ONLY\),)X -3426(and)X -3569(lock)X -3734(contention)X -4099(bound)X -555 3248(\(\256gure)N -796(eight,)X -1003(NO_FSYNC\).)X -1510(Since)X -1715(the)X -1840(normal)X -2094(con\256guration)X -2548(is)X -2628(completely)X -3011(disk)X -3171(bound)X -3398(\(each)X -3600(transaction)X -3978(requires)X -4263(a)X -555 3354(random)N -823(read,)X -1005(a)X -1064(random)X -1332(write,)X -1540(and)X -1679(a)X -1738(sequential)X -2086(write)X -7 s -2251 3322(4)N -10 s -3354(\))Y -2329(we)X -2446(expect)X -2679(to)X -2764(see)X -2890(little)X -3059(performance)X -3489(improvement)X -3939(as)X -4028(the)X -4148(mul-)X -555 3444(tiprogramming)N -1064(level)X -1249(increases.)X -1613(In)X -1709(fact,)X -1879(\256gure)X -2095(seven)X -2307(reveals)X -2564(that)X -2713(we)X -2836(are)X -2964(able)X -3127(to)X -3218(overlap)X -3487(CPU)X -3670(and)X -3814(disk)X -3975(utilization)X -555 3534(slightly)N -825(producing)X -1181(approximately)X -1674(a)X -1740(10%)X -1917(performance)X -2354(improvement)X -2811(with)X -2983(two)X -3133(processes.)X -3511(After)X -3711(that)X -3861(point,)X -4075(perfor-)X -555 3624(mance)N -785(drops)X -983(off,)X -1117(and)X -1253(at)X -1331(a)X -1387(multi-programming)X -2038(level)X -2214(of)X -2301(4,)X -2381(we)X -2495(are)X -2614(performing)X -2995(worse)X -3207(than)X -3365(in)X -3447(the)X -3565(single)X -3776(process)X -4037(case.)X -755 3747(Similar)N -1021(behavior)X -1333(was)X -1489(reported)X -1787(on)X -1897(the)X -2025(commercial)X -2434(relational)X -2767(database)X -3074(system)X -3326(using)X -3529(the)X -3657(same)X -3852(con\256guration.)X -555 3837(The)N -707(important)X -1045(conclusion)X -1419(to)X -1508(draw)X -1696(from)X -1879(this)X -2021(is)X -2101(that)X -2248(you)X -2395(cannot)X -2636(attain)X -2841(good)X -3028(multi-user)X -3384(scaling)X -3638(on)X -3745(a)X -3808(badly)X -4013(balanced)X -555 3927(system.)N -839(If)X -915(multi-user)X -1266(performance)X -1695(on)X -1797(applications)X -2205(of)X -2293(this)X -2429(sort)X -2570(is)X -2644(important,)X -2996(one)X -3133(must)X -3309(have)X -3482(a)X -3539(separate)X -3824(logging)X -4089(device)X -555 4017(and)N -697(horizontally)X -1110(partition)X -1407(the)X -1531(database)X -1834(to)X -1921(allow)X -2124(a)X -2185(suf\256ciently)X -2570(high)X -2737(degree)X -2977(of)X -3069(multiprogramming)X -3698(that)X -3843(group)X -4055(commit)X -555 4107(can)N -687(amortize)X -988(the)X -1106(cost)X -1255(of)X -1342(log)X -1464(\257ushing.)X -755 4230(By)N -871(using)X -1067(a)X -1126(very)X -1292(small)X -1488(database)X -1788(\(one)X -1954(that)X -2097(can)X -2232(be)X -2331(entirely)X -2599(cached)X -2846(in)X -2930(main)X -3112(memory\))X -3428(and)X -3566(read-only)X -3896(transactions,)X -555 4320(we)N -670(generated)X -1004(a)X -1061(CPU)X -1236(bound)X -1456(environment.)X -1921(By)X -2034(using)X -2227(the)X -2345(same)X -2530(small)X -2723(database,)X -3040(the)X -3158(complete)X -3472(TPCB)X -3691(transaction,)X -4083(and)X -4219(no)X -3 f -555 4410(fsync)N -1 f -733(\(2\))X -862(on)X -977(the)X -1110(log)X -1247(at)X -1340(commit,)X -1639(we)X -1768(created)X -2036(a)X -2107(lock)X -2280(contention)X -2652(bound)X -2886(environment.)X -3365(The)X -3524(small)X -3731(database)X -4042(used)X -4223(an)X -555 4500(account)N -828(\256le)X -953(containing)X -1314(only)X -1479(1000)X -1662(records)X -1922(rather)X -2133(than)X -2294(the)X -2415(full)X -2549(1,000,000)X -2891(records)X -3150(and)X -3288(ran)X -3413(enough)X -3671(transactions)X -4076(to)X -4160(read)X -555 4590(the)N -677(entire)X -883(database)X -1183(into)X -1330(the)X -1451(buffer)X -1671(pool)X -1836(\(2000\))X -2073(before)X -2302(beginning)X -2645(measurements.)X -3147(The)X -3295(read-only)X -3626(transaction)X -4001(consisted)X -555 4680(of)N -646(three)X -831(database)X -1132(reads)X -1326(\(from)X -1533(the)X -1655(1000)X -1839(record)X -2069(account)X -2343(\256le,)X -2489(the)X -2611(100)X -2754(record)X -2983(teller)X -3171(\256le,)X -3316(and)X -3455(the)X -3576(10)X -3679(record)X -3908(branch)X -4150(\256le\).)X -555 4770(Since)N -759(no)X -865(data)X -1025(were)X -1208(modi\256ed)X -1518(and)X -1660(no)X -1766(history)X -2014(records)X -2277(were)X -2460(written,)X -2733(no)X -2839(log)X -2966(records)X -3228(were)X -3410(written.)X -3702(For)X -3838(the)X -3961(contention)X -555 4860(bound)N -780(con\256guration,)X -1252(we)X -1371(used)X -1543(the)X -1666(normal)X -1918(TPCB)X -2142(transaction)X -2519(\(against)X -2798(the)X -2920(small)X -3117(database\))X -3445(and)X -3585(disabled)X -3876(the)X -3998(log)X -4124(\257ush.)X -555 4950(Figure)N -784(eight)X -964(shows)X -1184(both)X -1346(of)X -1433(these)X -1618(results.)X -755 5073(The)N -902(read-only)X -1231(test)X -1363(indicates)X -1669(that)X -1810(we)X -1925(barely)X -2147(scale)X -2329(at)X -2408(all)X -2509(in)X -2592(the)X -2711(CPU)X -2887(bound)X -3108(case.)X -3308(The)X -3454(explanation)X -3849(for)X -3964(that)X -4105(is)X -4179(that)X -555 5163(even)N -735(with)X -905(a)X -969(single)X -1188(process,)X -1477(we)X -1599(are)X -1726(able)X -1888(to)X -1978(drive)X -2171(the)X -2297(CPU)X -2480(utilization)X -2832(to)X -2922(96%.)X -3137(As)X -3254(a)X -3317(result,)X -3542(that)X -3689(gives)X -3885(us)X -3983(very)X -4153(little)X -555 5253(room)N -753(for)X -876(improvement,)X -1352(and)X -1497(it)X -1570(takes)X -1764(a)X -1829(multiprogramming)X -2462(level)X -2647(of)X -2743(four)X -2906(to)X -2997(approach)X -3321(100%)X -3537(CPU)X -3721(saturation.)X -4106(In)X -4201(the)X -555 5343(case)N -718(where)X -939(we)X -1057(do)X -1161(perform)X -1444(writes,)X -1684(we)X -1802(are)X -1925(interested)X -2261(in)X -2347(detecting)X -2665(when)X -2863(lock)X -3025(contention)X -3387(becomes)X -3691(a)X -3750(dominant)X -4075(perfor-)X -555 5433(mance)N -787(factor.)X -1037(Contention)X -1414(will)X -1560(cause)X -1761(two)X -1903(phenomena;)X -2317(we)X -2433(will)X -2579(see)X -2704(transactions)X -3109(queueing)X -3425(behind)X -3665(frequently)X -4017(accessed)X -555 5523(data,)N -731(and)X -869(we)X -985(will)X -1131(see)X -1256(transaction)X -1629(abort)X -1815(rates)X -1988(increasing)X -2339(due)X -2476(to)X -2559(deadlock.)X -2910(Given)X -3127(that)X -3268(the)X -3387(branch)X -3627(\256le)X -3750(contains)X -4038(only)X -4201(ten)X -8 s -10 f -555 5595(hhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhh)N -5 s -1 f -727 5673(4)N -8 s -763 5698(Although)N -1021(the)X -1115(log)X -1213(is)X -1272(written)X -1469(sequentially,)X -1810(we)X -1900(do)X -1980(not)X -2078(get)X -2172(the)X -2266(bene\256t)X -2456(of)X -2525(sequentiality)X -2868(since)X -3015(the)X -3109(log)X -3207(and)X -3315(database)X -3550(reside)X -3718(on)X -3798(the)X -3892(same)X -4039(disk.)X - -13 p -%%Page: 13 13 -8 s 8 xH 0 xS 1 f -10 s -3 f -1 f -3187 2051 MXY -0 18 Dl -0 -9 Dl -9 0 Dl --18 0 Dl -3286 2028 MXY -0 17 Dl -0 -9 Dl -9 0 Dl --18 0 Dl -3384 1926 MXY -0 18 Dl -0 -9 Dl -9 0 Dl --18 0 Dl -3483 1910 MXY -0 18 Dl -0 -9 Dl -9 0 Dl --18 0 Dl -3581 1910 MXY -0 18 Dl -0 -9 Dl -9 0 Dl --18 0 Dl -3680 1832 MXY -0 18 Dl -0 -9 Dl -9 0 Dl --18 0 Dl -3778 1909 MXY -0 18 Dl -0 -9 Dl -9 0 Dl --18 0 Dl -3877 1883 MXY -0 18 Dl -0 -9 Dl -9 0 Dl --18 0 Dl -3975 1679 MXY -0 17 Dl -0 -8 Dl -9 0 Dl --18 0 Dl -4074 1487 MXY -0 17 Dl -0 -8 Dl -9 0 Dl --18 0 Dl -5 Dt -3187 2060 MXY -99 -24 Dl -98 -101 Dl -99 -16 Dl -98 0 Dl -99 -78 Dl -98 77 Dl -99 -26 Dl -98 -204 Dl -99 -192 Dl -3 f -6 s -4088 1516(SMALL)N -3 Dt -3187 2051 MXY -0 18 Dl -0 -9 Dl -9 0 Dl --18 0 Dl -3286 2051 MXY -0 18 Dl -0 -9 Dl -9 0 Dl --18 0 Dl -3384 2041 MXY -0 18 Dl -0 -9 Dl -9 0 Dl --18 0 Dl -3483 1990 MXY -0 18 Dl -0 -9 Dl -9 0 Dl --18 0 Dl -3581 1843 MXY -0 17 Dl -0 -8 Dl -9 0 Dl --18 0 Dl -3680 1578 MXY -0 18 Dl -0 -9 Dl -9 0 Dl --18 0 Dl -3778 1496 MXY -0 18 Dl -0 -9 Dl -9 0 Dl --18 0 Dl -3877 1430 MXY -0 18 Dl -0 -9 Dl -9 0 Dl --18 0 Dl -3975 1269 MXY -0 18 Dl -0 -9 Dl -9 0 Dl --18 0 Dl -4074 1070 MXY -0 18 Dl -0 -9 Dl -9 0 Dl --18 0 Dl -1 Dt -3187 2060 MXY -99 0 Dl -98 -10 Dl -99 -51 Dl -98 -147 Dl -99 -265 Dl -98 -82 Dl -99 -66 Dl -98 -161 Dl -99 -199 Dl -4088 1099(LARGE)N -5 Dt -3089 2060 MXY -985 0 Dl -3089 MX -0 -1174 Dl -4 Ds -1 Dt -3581 2060 MXY -0 -1174 Dl -4074 2060 MXY -0 -1174 Dl -3089 1825 MXY -985 0 Dl -9 s -2993 1855(25)N -3089 1591 MXY -985 0 Dl -2993 1621(50)N -3089 1356 MXY -985 0 Dl -2993 1386(75)N -3089 1121 MXY -985 0 Dl -2957 1151(100)N -3089 886 MXY -985 0 Dl -2957 916(125)N -3281 2199(Multiprogramming)N -3071 2152(0)N -3569(5)X -4038(10)X -2859 787(Aborts)N -3089(per)X -3211(500)X -2901 847(transactions)N --1 Ds -3 Dt -2037 1342 MXY -0 18 Dl -0 -9 Dl -9 0 Dl --18 0 Dl -2125 1358 MXY -0 18 Dl -0 -9 Dl -9 0 Dl --18 0 Dl -2213 1341 MXY -0 18 Dl -0 -9 Dl -9 0 Dl --18 0 Dl -2301 1191 MXY -0 18 Dl -0 -9 Dl -9 0 Dl --18 0 Dl -2388 1124 MXY -0 18 Dl -0 -9 Dl -9 0 Dl --17 0 Dl -2476 1157 MXY -0 18 Dl -0 -9 Dl -9 0 Dl --18 0 Dl -2564 1157 MXY -0 18 Dl -0 -9 Dl -9 0 Dl --18 0 Dl -2652 1161 MXY -0 18 Dl -0 -9 Dl -9 0 Dl --18 0 Dl -2740 1153 MXY -0 18 Dl -0 -9 Dl -9 0 Dl --18 0 Dl -2828 1150 MXY -0 18 Dl -0 -9 Dl -8 0 Dl --17 0 Dl -5 Dt -2037 1351 MXY -88 16 Dl -88 -17 Dl -88 -150 Dl -87 -67 Dl -88 33 Dl -88 0 Dl -88 4 Dl -88 -8 Dl -88 -3 Dl -6 s -2685 1234(READ-ONLY)N -3 Dt -2037 1464 MXY -0 18 Dl -0 -9 Dl -9 0 Dl --18 0 Dl -2125 1640 MXY -0 18 Dl -0 -9 Dl -9 0 Dl --18 0 Dl -2213 1854 MXY -0 18 Dl -0 -9 Dl -9 0 Dl --18 0 Dl -2301 1872 MXY -0 18 Dl -0 -9 Dl -9 0 Dl --18 0 Dl -2388 1871 MXY -0 17 Dl -0 -9 Dl -9 0 Dl --17 0 Dl -2476 1933 MXY -0 18 Dl -0 -9 Dl -9 0 Dl --18 0 Dl -2564 1914 MXY -0 18 Dl -0 -9 Dl -9 0 Dl --18 0 Dl -2652 1903 MXY -0 18 Dl -0 -9 Dl -9 0 Dl --18 0 Dl -2740 1980 MXY -0 18 Dl -0 -9 Dl -9 0 Dl --18 0 Dl -2828 2004 MXY -0 18 Dl -0 -9 Dl -8 0 Dl --17 0 Dl -1 Dt -2037 1473 MXY -88 176 Dl -88 214 Dl -88 18 Dl -87 -2 Dl -88 63 Dl -88 -19 Dl -88 -11 Dl -88 77 Dl -88 24 Dl -2759 1997(NO-FSYNC)N -5 Dt -1949 2060 MXY -879 0 Dl -1949 MX -0 -1174 Dl -4 Ds -1 Dt -2388 2060 MXY -0 -1174 Dl -2828 2060 MXY -0 -1174 Dl -1949 1825 MXY -879 0 Dl -9 s -1842 1855(40)N -1949 1591 MXY -879 0 Dl -1842 1621(80)N -1949 1356 MXY -879 0 Dl -1806 1386(120)N -1949 1121 MXY -879 0 Dl -1806 1151(160)N -1949 886 MXY -879 0 Dl -1806 916(200)N -2088 2199(Multiprogramming)N -1844 863(in)N -1922(TPS)X -1761 792(Throughput)N -1931 2121(0)N -2370 2133(5)N -2792(10)X -6 s -1679 1833(LIBTP)N --1 Ds -3 Dt -837 1019 MXY -0 17 Dl -0 -9 Dl -9 0 Dl --18 0 Dl -929 878 MXY -0 17 Dl -0 -9 Dl -9 0 Dl --18 0 Dl -1021 939 MXY -0 18 Dl -0 -9 Dl -9 0 Dl --18 0 Dl -1113 1043 MXY -0 18 Dl -0 -9 Dl -9 0 Dl --18 0 Dl -1205 1314 MXY -0 18 Dl -0 -9 Dl -9 0 Dl --18 0 Dl -1297 1567 MXY -0 18 Dl -0 -9 Dl -9 0 Dl --18 0 Dl -1389 1665 MXY -0 18 Dl -0 -9 Dl -9 0 Dl --18 0 Dl -1481 1699 MXY -0 18 Dl -0 -9 Dl -9 0 Dl --18 0 Dl -1573 1828 MXY -0 18 Dl -0 -9 Dl -9 0 Dl --18 0 Dl -1665 1804 MXY -0 18 Dl -0 -9 Dl -8 0 Dl --17 0 Dl -5 Dt -837 1027 MXY -92 -141 Dl -92 62 Dl -92 104 Dl -92 271 Dl -92 253 Dl -92 98 Dl -92 34 Dl -92 129 Dl -92 -24 Dl -745 2060 MXY -920 0 Dl -745 MX -0 -1174 Dl -4 Ds -1 Dt -1205 2060 MXY -0 -1174 Dl -1665 2060 MXY -0 -1174 Dl -745 1766 MXY -920 0 Dl -9 s -673 1796(3)N -745 1473 MXY -920 0 Dl -673 1503(5)N -745 1180 MXY -920 0 Dl -673 1210(8)N -745 886 MXY -920 0 Dl -637 916(10)N -905 2199(Multiprogramming)N -622 851(in)N -700(TPS)X -575 792(Throughput)N -733 2152(0)N -1196(5)X -1629(10)X -3 Dt --1 Ds -8 s -655 2441(Figure)N -872(7:)X -960(Multi-user)X -1286(Performance.)X -1 f -655 2531(Since)N -825(the)X -931(con\256guration)X -1300(is)X -1371(completely)X -655 2621(disk)N -790(bound,)X -994(we)X -1096(see)X -1204(only)X -1345(a)X -1400(small)X -1566(im-)X -655 2711(provement)N -964(by)X -1064(adding)X -1274(a)X -1337(second)X -1549(pro-)X -655 2801(cess.)N -849(Adding)X -1081(any)X -1213(more)X -1383(concurrent)X -655 2891(processes)N -935(causes)X -1137(performance)X -1493(degra-)X -655 2981(dation.)N -3 f -1927 2441(Figure)N -2149(8:)X -2243(Multi-user)X -2574(Performance)X -1927 2531(on)N -2021(a)X -2079(small)X -2251(database.)X -1 f -2551(With)X -2704(one)X -2821(pro-)X -1927 2621(cess,)N -2075(we)X -2174(are)X -2276(driving)X -2486(the)X -2589(CPU)X -2739(at)X -2810(96%)X -1927 2711(utilization)N -2215(leaving)X -2430(little)X -2575(room)X -2737(for)X -2838(im-)X -1927 2801(provement)N -2238(as)X -2328(the)X -2443(multiprogramming)X -1927 2891(level)N -2091(increases.)X -2396(In)X -2489(the)X -2607(NO-FSYNC)X -1927 2981(case,)N -2076(lock)X -2209(contention)X -2502(degrades)X -2751(perfor-)X -1927 3071(mance)N -2117(as)X -2194(soon)X -2339(as)X -2416(a)X -2468(second)X -2669(process)X -2884(is)X -1927 3161(added.)N -3 f -3199 2441(Figure)N -3405(9:)X -3482(Abort)X -3669(rates)X -3827(on)X -3919(the)X -4028(TPCB)X -3199 2531(Benchmark.)N -1 f -3589(The)X -3726(abort)X -3895(rate)X -4028(climbs)X -3199 2621(more)N -3366(quickly)X -3594(for)X -3704(the)X -3818(large)X -3980(database)X -3199 2711(test)N -3324(since)X -3491(processes)X -3771(are)X -3884(descheduled)X -3199 2801(more)N -3409(frequently,)X -3766(allowing)X -4068(more)X -3199 2891(processes)N -3459(to)X -3525(vie)X -3619(for)X -3709(the)X -3803(same)X -3950(locks.)X -10 s -10 f -555 3284(h)N -579(hhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhh)X -1 f -555 3560(records,)N -835(we)X -952(expect)X -1185(contention)X -1546(to)X -1631(become)X -1904(a)X -1963(factor)X -2174(quickly)X -2437(and)X -2576(the)X -2697(NO-FSYNC)X -3120(line)X -3263(in)X -3348(\256gure)X -3557(eight)X -3739(demonstrates)X -4184(this)X -555 3650(dramatically.)N -1022(Each)X -1209(additional)X -1555(process)X -1822(causes)X -2058(both)X -2226(more)X -2417(waiting)X -2682(and)X -2823(more)X -3013(deadlocking.)X -3470(Figure)X -3704(nine)X -3867(shows)X -4092(that)X -4237(in)X -555 3740(the)N -681(small)X -882(database)X -1187(case)X -1353(\(SMALL\),)X -1725(waiting)X -1992(is)X -2072(the)X -2197(dominant)X -2526(cause)X -2732(of)X -2826(declining)X -3151(performance)X -3585(\(the)X -3737(number)X -4009(of)X -4103(aborts)X -555 3830(increases)N -878(less)X -1026(steeply)X -1281(than)X -1447(the)X -1573(performance)X -2008(drops)X -2214(off)X -2336(in)X -2426(\256gure)X -2641(eight\),)X -2876(while)X -3082(in)X -3172(the)X -3298(large)X -3487(database)X -3792(case)X -3958(\(LARGE\),)X -555 3920(deadlocking)N -967(contributes)X -1343(more)X -1528(to)X -1610(the)X -1728(declining)X -2046(performance.)X -755 4043(Deadlocks)N -1116(are)X -1237(more)X -1424(likely)X -1628(to)X -1712(occur)X -1913(in)X -1997(the)X -2116(LARGE)X -2404(test)X -2536(than)X -2695(in)X -2778(the)X -2897(SMALL)X -3189(test)X -3321(because)X -3597(there)X -3779(are)X -3899(more)X -4085(oppor-)X -555 4133(tunities)N -814(to)X -900(wait.)X -1082(In)X -1173(the)X -1295(SMALL)X -1590(case,)X -1773(processes)X -2105(never)X -2307(do)X -2410(I/O)X -2540(and)X -2679(are)X -2801(less)X -2944(likely)X -3149(to)X -3234(be)X -3333(descheduled)X -3753(during)X -3985(a)X -4044(transac-)X -555 4223(tion.)N -740(In)X -828(the)X -947(LARGE)X -1235(case,)X -1415(processes)X -1744(will)X -1889(frequently)X -2240(be)X -2337(descheduled)X -2755(since)X -2941(they)X -3100(have)X -3273(to)X -3356(perform)X -3636(I/O.)X -3804(This)X -3967(provides)X -4263(a)X -555 4313(window)N -837(where)X -1058(a)X -1118(second)X -1365(process)X -1630(can)X -1766(request)X -2022(locks)X -2215(on)X -2318(already)X -2578(locked)X -2815(pages,)X -3041(thus)X -3197(increasing)X -3550(the)X -3671(likelihood)X -4018(of)X -4108(build-)X -555 4403(ing)N -677(up)X -777(long)X -939(chains)X -1164(of)X -1251(waiting)X -1511(processes.)X -1879(Eventually,)X -2266(this)X -2401(leads)X -2586(to)X -2668(deadlock.)X -3 f -555 4589(5.2.)N -715(The)X -868(OO1)X -1052(Benchmark)X -1 f -755 4712(The)N -903(TPCB)X -1125(benchmark)X -1505(described)X -1836(in)X -1921(the)X -2042(previous)X -2341(section)X -2591(measures)X -2913(performance)X -3343(under)X -3549(a)X -3608(conventional)X -4044(transac-)X -555 4802(tion)N -706(processing)X -1076(workload.)X -1446(Other)X -1656(application)X -2039(domains,)X -2357(such)X -2531(as)X -2625(computer-aided)X -3156(design,)X -3412(have)X -3591(substantially)X -4022(different)X -555 4892(access)N -786(patterns.)X -1105(In)X -1197(order)X -1392(to)X -1479(measure)X -1772(the)X -1895(performance)X -2327(of)X -2418(LIBTP)X -2664(under)X -2871(workloads)X -3229(of)X -3320(this)X -3459(type,)X -3641(we)X -3759(implemented)X -4201(the)X -555 4982(OO1)N -731(benchmark)X -1108(described)X -1436(in)X -1518([CATT91].)X -755 5105(The)N -908(database)X -1213(models)X -1472(a)X -1535(set)X -1651(of)X -1745(electronics)X -2120(components)X -2534(with)X -2703(connections)X -3113(among)X -3358(them.)X -3585(One)X -3746(table)X -3929(stores)X -4143(parts)X -555 5195(and)N -696(another)X -962(stores)X -1174(connections.)X -1622(There)X -1835(are)X -1959(three)X -2145(connections)X -2552(originating)X -2927(at)X -3009(any)X -3149(given)X -3351(part.)X -3540(Ninety)X -3782(percent)X -4043(of)X -4134(these)X -555 5285(connections)N -960(are)X -1081(to)X -1165(nearby)X -1406(parts)X -1584(\(those)X -1802(with)X -1966(nearby)X -2 f -2207(ids)X -1 f -2300(\))X -2348(to)X -2431(model)X -2652(the)X -2771(spatial)X -3001(locality)X -3262(often)X -3448(exhibited)X -3767(in)X -3850(CAD)X -4040(applica-)X -555 5375(tions.)N -779(Ten)X -933(percent)X -1198(of)X -1293(the)X -1419(connections)X -1830(are)X -1957(randomly)X -2292(distributed)X -2662(among)X -2908(all)X -3016(other)X -3209(parts)X -3393(in)X -3483(the)X -3609(database.)X -3954(Every)X -4174(part)X -555 5465(appears)N -829(exactly)X -1089(three)X -1278(times)X -1479(in)X -1569(the)X -2 f -1695(from)X -1 f -1874(\256eld)X -2043(of)X -2137(a)X -2200(connection)X -2579(record,)X -2832(and)X -2975(zero)X -3141(or)X -3235(more)X -3427(times)X -3627(in)X -3716(the)X -2 f -3841(to)X -1 f -3930(\256eld.)X -4139(Parts)X -555 5555(have)N -2 f -727(x)X -1 f -783(and)X -2 f -919(y)X -1 f -975(locations)X -1284(set)X -1393(randomly)X -1720(in)X -1802(an)X -1898(appropriate)X -2284(range.)X - -14 p -%%Page: 14 14 -10 s 10 xH 0 xS 1 f -3 f -1 f -755 630(The)N -900(intent)X -1102(of)X -1189(OO1)X -1365(is)X -1438(to)X -1520(measure)X -1808(the)X -1926(overall)X -2169(cost)X -2318(of)X -2405(a)X -2461(query)X -2664(mix)X -2808(characteristic)X -3257(of)X -3344(engineering)X -3743(database)X -4040(applica-)X -555 720(tions.)N -770(There)X -978(are)X -1097(three)X -1278(tests:)X -10 f -635 843(g)N -2 f -755(Lookup)X -1 f -1022(generates)X -1353(1,000)X -1560(random)X -1832(part)X -2 f -1984(ids)X -1 f -2077(,)X -2124(fetches)X -2378(the)X -2502(corresponding)X -2987(parts)X -3169(from)X -3351(the)X -3475(database,)X -3798(and)X -3940(calls)X -4113(a)X -4175(null)X -755 933(procedure)N -1097(in)X -1179(the)X -1297(host)X -1450(programming)X -1906(language)X -2216(with)X -2378(the)X -2496(parts')X -2 f -2699(x)X -1 f -2755(and)X -2 f -2891(y)X -1 f -2947(positions.)X -10 f -635 1056(g)N -2 f -755(Traverse)X -1 f -1067(retrieves)X -1371(a)X -1434(random)X -1706(part)X -1858(from)X -2041(the)X -2166(database)X -2470(and)X -2613(follows)X -2880(connections)X -3290(from)X -3473(it)X -3544(to)X -3632(other)X -3823(parts.)X -4045(Each)X -4232(of)X -755 1146(those)N -947(parts)X -1126(is)X -1202(retrieved,)X -1531(and)X -1670(all)X -1773(connections)X -2179(from)X -2358(it)X -2424(followed.)X -2771(This)X -2935(procedure)X -3279(is)X -3354(repeated)X -3649(depth-\256rst)X -4000(for)X -4116(seven)X -755 1236(hops)N -930(from)X -1110(the)X -1232(original)X -1505(part,)X -1674(for)X -1792(a)X -1852(total)X -2018(of)X -2109(3280)X -2293(parts.)X -2513(Backward)X -2862(traversal)X -3162(also)X -3314(exists,)X -3539(and)X -3678(follows)X -3941(all)X -4044(connec-)X -755 1326(tions)N -930(into)X -1074(a)X -1130(given)X -1328(part)X -1473(to)X -1555(their)X -1722(origin.)X -10 f -635 1449(g)N -2 f -755(Insert)X -1 f -962(adds)X -1129(100)X -1269(new)X -1423(parts)X -1599(and)X -1735(their)X -1902(connections.)X -755 1572(The)N -913(benchmark)X -1303(is)X -1389(single-user,)X -1794(but)X -1929(multi-user)X -2291(access)X -2530(controls)X -2821(\(locking)X -3120(and)X -3268(transaction)X -3652(protection\))X -4036(must)X -4223(be)X -555 1662(enforced.)N -898(It)X -968(is)X -1042(designed)X -1348(to)X -1431(be)X -1528(run)X -1656(on)X -1757(a)X -1814(database)X -2112(with)X -2275(20,000)X -2516(parts,)X -2713(and)X -2850(on)X -2951(one)X -3087(with)X -3249(200,000)X -3529(parts.)X -3745(Because)X -4033(we)X -4147(have)X -555 1752(insuf\256cient)N -935(disk)X -1088(space)X -1287(for)X -1401(the)X -1519(larger)X -1727(database,)X -2044(we)X -2158(report)X -2370(results)X -2599(only)X -2761(for)X -2875(the)X -2993(20,000)X -3233(part)X -3378(database.)X -3 f -555 1938(5.2.1.)N -775(Implementation)X -1 f -755 2061(The)N -920(LIBTP)X -1182(implementation)X -1724(of)X -1831(OO1)X -2027(uses)X -2205(the)X -2342(TCL)X -2532([OUST90])X -2914(interface)X -3235(described)X -3582(earlier.)X -3867(The)X -4031(backend)X -555 2151(accepts)N -813(commands)X -1181(over)X -1345(an)X -1442(IP)X -1534(socket)X -1760(and)X -1897(performs)X -2208(the)X -2327(requested)X -2656(database)X -2954(actions.)X -3242(The)X -3387(frontend)X -3679(opens)X -3886(and)X -4022(executes)X -555 2241(a)N -618(TCL)X -796(script.)X -1041(This)X -1210(script)X -1415(contains)X -1709(database)X -2013(accesses)X -2313(interleaved)X -2697(with)X -2866(ordinary)X -3165(program)X -3463(control)X -3716(statements.)X -4120(Data-)X -555 2331(base)N -718(commands)X -1085(are)X -1204(submitted)X -1539(to)X -1621(the)X -1739(backend)X -2027(and)X -2163(results)X -2392(are)X -2511(bound)X -2731(to)X -2813(program)X -3105(variables.)X -755 2454(The)N -903(parts)X -1082(table)X -1261(was)X -1409(stored)X -1628(as)X -1718(a)X -1776(B-tree)X -1999(indexed)X -2275(by)X -2 f -2377(id)X -1 f -2439(.)X -2501(The)X -2648(connection)X -3022(table)X -3200(was)X -3347(stored)X -3565(as)X -3654(a)X -3712(set)X -3823(of)X -3912(\256xed-length)X -555 2544(records)N -824(using)X -1029(the)X -1159(4.4BSD)X -1446(recno)X -1657(access)X -1895(method.)X -2207(In)X -2306(addition,)X -2620(two)X -2771(B-tree)X -3003(indices)X -3261(were)X -3449(maintained)X -3836(on)X -3947(connection)X -555 2634(table)N -732(entries.)X -1007(One)X -1162(index)X -1360(mapped)X -1634(the)X -2 f -1752(from)X -1 f -1923(\256eld)X -2085(to)X -2167(a)X -2223(connection)X -2595(record)X -2821(number,)X -3106(and)X -3242(the)X -3360(other)X -3545(mapped)X -3819(the)X -2 f -3937(to)X -1 f -4019(\256eld)X -4181(to)X -4263(a)X -555 2724(connection)N -932(record)X -1163(number.)X -1473(These)X -1690(indices)X -1941(support)X -2205(fast)X -2345(lookups)X -2622(on)X -2726(connections)X -3133(in)X -3219(both)X -3385(directions.)X -3765(For)X -3900(the)X -4022(traversal)X -555 2814(tests,)N -743(the)X -867(frontend)X -1165(does)X -1338(an)X -1439(index)X -1642(lookup)X -1889(to)X -1976(discover)X -2273(the)X -2396(connected)X -2747(part's)X -2 f -2955(id)X -1 f -3017(,)X -3062(and)X -3203(then)X -3366(does)X -3538(another)X -3804(lookup)X -4051(to)X -4138(fetch)X -555 2904(the)N -673(part)X -818(itself.)X -3 f -555 3090(5.2.2.)N -775(Performance)X -1242(Measurements)X -1766(for)X -1889(OO1)X -1 f -755 3213(We)N -888(compare)X -1186(LIBTP's)X -1487(OO1)X -1664(performance)X -2092(to)X -2174(that)X -2314(reported)X -2602(in)X -2684([CATT91].)X -3087(Those)X -3303(results)X -3532(were)X -3709(collected)X -4019(on)X -4119(a)X -4175(Sun)X -555 3303(3/280)N -759(\(25)X -888(MHz)X -1075(MC68020\))X -1448(with)X -1612(16)X -1714(MBytes)X -1989(of)X -2078(memory)X -2367(and)X -2505(two)X -2647(Hitachi)X -2904(892MByte)X -3267(disks)X -3452(\(15)X -3580(ms)X -3694(average)X -3966(seek)X -4130(time\))X -555 3393(behind)N -793(an)X -889(SMD-4)X -1149(controller.)X -1521(Frontends)X -1861(ran)X -1984(on)X -2084(an)X -2180(8MByte)X -2462(Sun)X -2606(3/260.)X -755 3516(In)N -844(order)X -1036(to)X -1120(measure)X -1410(performance)X -1839(on)X -1941(a)X -1999(machine)X -2293(of)X -2382(roughly)X -2653(equivalent)X -3009(processor)X -3339(power,)X -3582(we)X -3698(ran)X -3822(one)X -3959(set)X -4069(of)X -4157(tests)X -555 3606(on)N -666(a)X -733(standalone)X -1107(MC68030-based)X -1671(HP300)X -1923(\(33MHz)X -2225(MC68030\).)X -2646(The)X -2801(database)X -3108(was)X -3263(stored)X -3489(on)X -3599(a)X -3665(300MByte)X -4037(HP7959)X -555 3696(SCSI)N -744(disk)X -898(\(17)X -1026(ms)X -1139(average)X -1410(seek)X -1573(time\).)X -1802(Since)X -2000(this)X -2135(machine)X -2427(is)X -2500(not)X -2622(connected)X -2968(to)X -3050(a)X -3106(network,)X -3409(we)X -3523(ran)X -3646(local)X -3822(tests)X -3984(where)X -4201(the)X -555 3786(frontend)N -855(and)X -999(backend)X -1295(run)X -1430(on)X -1538(the)X -1664(same)X -1856(machine.)X -2195(We)X -2334(compare)X -2638(these)X -2830(measurements)X -3316(with)X -3485(Cattell's)X -3783(local)X -3966(Sun)X -4117(3/280)X -555 3876(numbers.)N -755 3999(Because)N -1051(the)X -1177(benchmark)X -1562(requires)X -1849(remote)X -2100(access,)X -2354(we)X -2476(ran)X -2607(another)X -2876(set)X -2993(of)X -3088(tests)X -3258(on)X -3365(a)X -3428(DECstation)X -3828(5000/200)X -4157(with)X -555 4089(32M)N -732(of)X -825(memory)X -1118(running)X -1393(Ultrix)X -1610(V4.0)X -1794(and)X -1936(a)X -1998(DEC)X -2184(1GByte)X -2459(RZ57)X -2666(SCSI)X -2859(disk.)X -3057(We)X -3194(compare)X -3496(the)X -3619(local)X -3800(performance)X -4232(of)X -555 4179(OO1)N -734(on)X -837(the)X -958(DECstation)X -1354(to)X -1439(its)X -1536(remote)X -1781(performance.)X -2250(For)X -2383(the)X -2503(remote)X -2748(case,)X -2929(we)X -3045(ran)X -3170(the)X -3290(frontend)X -3584(on)X -3686(a)X -3744(DECstation)X -4139(3100)X -555 4269(with)N -717(16)X -817(MBytes)X -1090(of)X -1177(main)X -1357(memory.)X -755 4392(The)N -900(databases)X -1228(tested)X -1435(in)X -1517([CATT91])X -1880(are)X -10 f -635 4515(g)N -1 f -755(INDEX,)X -1045(a)X -1101(highly-optimized)X -1672(access)X -1898(method)X -2158(package)X -2442(developed)X -2792(at)X -2870(Sun)X -3014(Microsystems.)X -10 f -635 4638(g)N -1 f -755(OODBMS,)X -1137(a)X -1193(beta)X -1347(release)X -1591(of)X -1678(a)X -1734(commercial)X -2133(object-oriented)X -2639(database)X -2936(management)X -3366(system.)X -10 f -635 4761(g)N -1 f -755(RDBMS,)X -1076(a)X -1133(UNIX-based)X -1565(commercial)X -1965(relational)X -2289(data)X -2444(manager)X -2742(at)X -2821(production)X -3189(release.)X -3474(The)X -3620(OO1)X -3797(implementation)X -755 4851(used)N -922(embedded)X -1272(SQL)X -1443(in)X -1525(C.)X -1638(Stored)X -1867(procedures)X -2240(were)X -2417(de\256ned)X -2673(to)X -2755(reduce)X -2990(client-server)X -3412(traf\256c.)X -755 4974(Table)N -974(two)X -1130(shows)X -1366(the)X -1500(measurements)X -1995(from)X -2187([CATT91])X -2566(and)X -2718(LIBTP)X -2976(for)X -3106(a)X -3178(local)X -3370(test)X -3517(on)X -3632(the)X -3765(MC680x0-based)X -555 5064(hardware.)N -915(All)X -1037(caches)X -1272(are)X -1391(cleared)X -1644(before)X -1870(each)X -2038(test.)X -2209(All)X -2331(times)X -2524(are)X -2643(in)X -2725(seconds.)X -755 5187(Table)N -960(two)X -1102(shows)X -1324(that)X -1466(LIBTP)X -1710(outperforms)X -2123(the)X -2242(commercial)X -2642(relational)X -2966(system,)X -3229(but)X -3352(is)X -3426(slower)X -3661(than)X -3820(OODBMS)X -4183(and)X -555 5277(INDEX.)N -872(Since)X -1077(the)X -1202(caches)X -1444(were)X -1628(cleared)X -1888(at)X -1973(the)X -2098(start)X -2263(of)X -2356(each)X -2530(test,)X -2687(disk)X -2846(throughput)X -3223(is)X -3302(critical)X -3551(in)X -3639(this)X -3780(test.)X -3957(The)X -4108(single)X -555 5367(SCSI)N -749(HP)X -877(drive)X -1068(used)X -1241(by)X -1347(LIBTP)X -1595(is)X -1674(approximately)X -2163(13%)X -2336(slower)X -2576(than)X -2739(the)X -2862(disks)X -3051(used)X -3223(in)X -3310([CATT91])X -3678(which)X -3899(accounts)X -4205(for)X -555 5457(part)N -700(of)X -787(the)X -905(difference.)X -755 5580(OODBMS)N -1118(and)X -1255(INDEX)X -1525(outperform)X -1906(LIBTP)X -2148(most)X -2323(dramatically)X -2744(on)X -2844(traversal.)X -3181(This)X -3343(is)X -3416(because)X -3691(we)X -3805(use)X -3932(index)X -4130(look-)X -555 5670(ups)N -689(to)X -774(\256nd)X -921(connections,)X -1347(whereas)X -1634(the)X -1755(other)X -1942(two)X -2084(systems)X -2359(use)X -2488(a)X -2546(link)X -2692(access)X -2920(method.)X -3222(The)X -3369(index)X -3569(requires)X -3850(us)X -3943(to)X -4027(examine)X - -15 p -%%Page: 15 15 -10 s 10 xH 0 xS 1 f -3 f -1 f -10 f -555 679(iiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii)N -2 f -606 769(Measure)N -1 f -1019(INDEX)X -1389(OODBMS)X -1851(RDBMS)X -2250(LIBTP)X -10 f -555 771(iiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii)N -555 787(iiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii)N -1 f -595 869(Lookup)N -1114(5.4)X -1490(12.9)X -1950(27)X -2291(27.2)X -595 959(Traversal)N -1074(13)X -1530(9.8)X -1950(90)X -2291(47.3)X -595 1049(Insert)N -1114(7.4)X -1530(1.5)X -1950(22)X -2331(9.7)X -10 f -555 1059(iiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii)N -555(c)X -999(c)Y -919(c)Y -839(c)Y -759(c)Y -959 1059(c)N -999(c)Y -919(c)Y -839(c)Y -759(c)Y -1329 1059(c)N -999(c)Y -919(c)Y -839(c)Y -759(c)Y -1791 1059(c)N -999(c)Y -919(c)Y -839(c)Y -759(c)Y -2190 1059(c)N -999(c)Y -919(c)Y -839(c)Y -759(c)Y -2512 1059(c)N -999(c)Y -919(c)Y -839(c)Y -759(c)Y -2618 679(i)N -2629(iiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii)X -2 f -2829 769(Measure)N -3401(Cache)X -3726(Local)X -4028(Remote)X -1 f -10 f -2618 771(i)N -2629(iiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii)X -2618 787(i)N -2629(iiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii)X -1 f -2658 869(Lookup)N -3401(cold)X -3747(15.7)X -4078(20.6)X -3401 959(warm)N -3787(7.8)X -4078(12.4)X -10 f -2618 969(i)N -2629(iiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii)X -1 f -2658 1059(Forward)N -2950(traversal)X -3401(cold)X -3747(28.4)X -4078(52.6)X -3401 1149(warm)N -3747(23.5)X -4078(47.4)X -10 f -2618 1159(i)N -2629(iiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii)X -1 f -2658 1249(Backward)N -3004(traversal)X -3401(cold)X -3747(24.2)X -4078(47.4)X -3401 1339(warm)N -3747(24.3)X -4078(47.6)X -10 f -2618 1349(i)N -2629(iiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii)X -1 f -2658 1439(Insert)N -3401(cold)X -3787(7.5)X -4078(10.3)X -3401 1529(warm)N -3787(6.7)X -4078(10.9)X -10 f -2618 1539(i)N -2629(iiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii)X -2618(c)X -1479(c)Y -1399(c)Y -1319(c)Y -1239(c)Y -1159(c)Y -1079(c)Y -999(c)Y -919(c)Y -839(c)Y -759(c)Y -3341 1539(c)N -1479(c)Y -1399(c)Y -1319(c)Y -1239(c)Y -1159(c)Y -1079(c)Y -999(c)Y -919(c)Y -839(c)Y -759(c)Y -3666 1539(c)N -1479(c)Y -1399(c)Y -1319(c)Y -1239(c)Y -1159(c)Y -1079(c)Y -999(c)Y -919(c)Y -839(c)Y -759(c)Y -3968 1539(c)N -1479(c)Y -1399(c)Y -1319(c)Y -1239(c)Y -1159(c)Y -1079(c)Y -999(c)Y -919(c)Y -839(c)Y -759(c)Y -4309 1539(c)N -1479(c)Y -1399(c)Y -1319(c)Y -1239(c)Y -1159(c)Y -1079(c)Y -999(c)Y -919(c)Y -839(c)Y -759(c)Y -3 f -587 1785(Table)N -823(2:)X -931(Local)X -1163(MC680x0)X -1538(Performance)X -2026(of)X -2133(Several)X -587 1875(Systems)N -883(on)X -987(OO1.)X -2667 1785(Table)N -2909(3:)X -3023(Local)X -3260(vs.)X -3397(Remote)X -3707(Performance)X -4200(of)X -2667 1875(LIBTP)N -2926(on)X -3030(OO1.)X -1 f -10 f -555 1998(h)N -579(hhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhh)X -1 f -555 2274(two)N -696(disk)X -850(pages,)X -1074(but)X -1197(the)X -1316(links)X -1492(require)X -1741(only)X -1904(one,)X -2061(regardless)X -2408(of)X -2496(database)X -2794(size.)X -2980(Cattell)X -3214(reports)X -3458(that)X -3599(lookups)X -3873(using)X -4067(B-trees)X -555 2364(instead)N -808(of)X -901(links)X -1082(makes)X -1313(traversal)X -1616(take)X -1776(twice)X -1976(as)X -2069(long)X -2237(in)X -2325(INDEX.)X -2641(Adding)X -2907(a)X -2969(link)X -3119(access)X -3351(method)X -3617(to)X -3 f -3704(db)X -1 f -3792(\(3\))X -3911(or)X -4003(using)X -4201(the)X -555 2454(existing)N -828(hash)X -995(method)X -1255(would)X -1475(apparently)X -1834(be)X -1930(a)X -1986(good)X -2166(idea.)X -755 2577(Both)N -936(OODBMS)X -1304(and)X -1446(INDEX)X -1722(issue)X -1908 0.1944(coarser-granularity)AX -2545(locks)X -2739(than)X -2902(LIBTP.)X -3189(This)X -3356(limits)X -3562(concurrency)X -3985(for)X -4104(multi-)X -555 2667(user)N -711(applications,)X -1140(but)X -1264(helps)X -1455(single-user)X -1829(applications.)X -2278(In)X -2367(addition,)X -2671(the)X -2791(fact)X -2934(that)X -3076(LIBTP)X -3319(releases)X -3595(B-tree)X -3817(locks)X -4007(early)X -4189(is)X -4263(a)X -555 2757(drawback)N -896(in)X -986(OO1.)X -1210(Since)X -1416(there)X -1605(is)X -1686(no)X -1793(concurrency)X -2218(in)X -2307(the)X -2432(benchmark,)X -2836(high-concurrency)X -3430(strategies)X -3760(only)X -3929(show)X -4125(up)X -4232(as)X -555 2847(increased)N -882(locking)X -1145(overhead.)X -1503(Finally,)X -1772(the)X -1892(architecture)X -2294(of)X -2383(the)X -2503(LIBTP)X -2747(implementation)X -3271(was)X -3418(substantially)X -3844(different)X -4143(from)X -555 2937(that)N -702(of)X -796(either)X -1006(OODBMS)X -1375(or)X -1469(INDEX.)X -1786(Both)X -1968(of)X -2062(those)X -2258(systems)X -2538(do)X -2645(the)X -2770(searches)X -3070(in)X -3159(the)X -3284(user's)X -3503(address)X -3771(space,)X -3997(and)X -4139(issue)X -555 3027(requests)N -844(for)X -964(pages)X -1173(to)X -1260(the)X -1383(server)X -1605(process.)X -1911(Pages)X -2123(are)X -2247(cached)X -2496(in)X -2583(the)X -2706(client,)X -2929(and)X -3070(many)X -3273(queries)X -3530(can)X -3667(be)X -3768(satis\256ed)X -4055(without)X -555 3117(contacting)N -910(the)X -1029(server)X -1247(at)X -1326(all.)X -1467(LIBTP)X -1710(submits)X -1979(all)X -2080(the)X -2199(queries)X -2452(to)X -2535(the)X -2653(server)X -2870(process,)X -3151(and)X -3287(receives)X -3571(database)X -3868(records)X -4125(back;)X -555 3207(it)N -619(does)X -786(no)X -886(client)X -1084(caching.)X -755 3330(The)N -911(RDBMS)X -1221(architecture)X -1632(is)X -1716(much)X -1925(closer)X -2148(to)X -2241(that)X -2392(of)X -2490(LIBTP.)X -2783(A)X -2872(server)X -3100(process)X -3372(receives)X -3667(queries)X -3930(and)X -4076(returns)X -555 3420(results)N -786(to)X -870(a)X -928(client.)X -1168(The)X -1315(timing)X -1545(results)X -1776(in)X -1860(table)X -2038(two)X -2180(clearly)X -2421(show)X -2612(that)X -2754(the)X -2874(conventional)X -3309(database)X -3607(client/server)X -4025(model)X -4246(is)X -555 3510(expensive.)N -941(LIBTP)X -1188(outperforms)X -1605(the)X -1728(RDBMS)X -2032(on)X -2136(traversal)X -2437(and)X -2577(insertion.)X -2921(We)X -3057(speculate)X -3380(that)X -3524(this)X -3663(is)X -3740(due)X -3880(in)X -3966(part)X -4115(to)X -4201(the)X -555 3600(overhead)N -870(of)X -957(query)X -1160(parsing,)X -1436(optimization,)X -1880(and)X -2016(repeated)X -2309(interpretation)X -2761(of)X -2848(the)X -2966(plan)X -3124(tree)X -3265(in)X -3347(the)X -3465(RDBMS')X -3791(query)X -3994(executor.)X -755 3723(Table)N -962(three)X -1147(shows)X -1371(the)X -1492(differences)X -1873(between)X -2164(local)X -2343(and)X -2482(remote)X -2728(execution)X -3063(of)X -3153(LIBTP's)X -3456(OO1)X -3635(implementation)X -4160(on)X -4263(a)X -555 3813(DECstation.)N -989(We)X -1122(measured)X -1451(performance)X -1879(with)X -2042(a)X -2099(populated)X -2436(\(warm\))X -2694(cache)X -2899(and)X -3036(an)X -3133(empty)X -3354(\(cold\))X -3567(cache.)X -3812(Reported)X -4126(times)X -555 3903(are)N -681(the)X -806(means)X -1037(of)X -1130(twenty)X -1374(tests,)X -1562(and)X -1704(are)X -1829(in)X -1917(seconds.)X -2237(Standard)X -2548(deviations)X -2903(were)X -3086(within)X -3316(seven)X -3525(percent)X -3788(of)X -3881(the)X -4005(mean)X -4205(for)X -555 3993(remote,)N -818(and)X -954(two)X -1094(percent)X -1351(of)X -1438(the)X -1556(mean)X -1750(for)X -1864(local.)X -755 4116(The)N -914(20ms)X -1121(overhead)X -1450(of)X -1551(TCP/IP)X -1824(on)X -1938(an)X -2048(Ethernet)X -2354(entirely)X -2633(accounts)X -2948(for)X -3076(the)X -3207(difference)X -3567(in)X -3662(speed.)X -3918(The)X -4076(remote)X -555 4206(traversal)N -857(times)X -1055(are)X -1179(nearly)X -1405(double)X -1648(the)X -1771(local)X -1952(times)X -2150(because)X -2430(we)X -2549(do)X -2653(index)X -2855(lookups)X -3132(and)X -3272(part)X -3421(fetches)X -3673(in)X -3759(separate)X -4047(queries.)X -555 4296(It)N -629(would)X -854(make)X -1053(sense)X -1252(to)X -1339(do)X -1444(indexed)X -1723(searches)X -2021(on)X -2126(the)X -2248(server,)X -2489(but)X -2615(we)X -2733(were)X -2914(unwilling)X -3244(to)X -3330(hard-code)X -3676(knowledge)X -4052(of)X -4143(OO1)X -555 4386(indices)N -803(into)X -948(our)X -1075(LIBTP)X -1317(TCL)X -1488(server.)X -1745(Cold)X -1920(and)X -2056(warm)X -2259(insertion)X -2559(times)X -2752(are)X -2871(identical)X -3167(since)X -3352(insertions)X -3683(do)X -3783(not)X -3905(bene\256t)X -4143(from)X -555 4476(caching.)N -755 4599(One)N -915(interesting)X -1279(difference)X -1632(shown)X -1867(by)X -1973(table)X -2155(three)X -2342(is)X -2421(the)X -2545(cost)X -2700(of)X -2793(forward)X -3074(versus)X -3305(backward)X -3644(traversal.)X -3987(When)X -4205(we)X -555 4689(built)N -725(the)X -847(database,)X -1168(we)X -1285(inserted)X -1562(parts)X -1741(in)X -1826(part)X -2 f -1974(id)X -1 f -2059(order.)X -2292(We)X -2427(built)X -2596(the)X -2717(indices)X -2967(at)X -3048(the)X -3169(same)X -3357(time.)X -3562(Therefore,)X -3923(the)X -4044(forward)X -555 4779(index)N -757(had)X -897(keys)X -1068(inserted)X -1346(in)X -1432(order,)X -1646(while)X -1848(the)X -1970(backward)X -2307(index)X -2509(had)X -2649(keys)X -2820(inserted)X -3098(more)X -3286(randomly.)X -3656(In-order)X -3943(insertion)X -4246(is)X -555 4885(pessimal)N -858(for)X -975(B-tree)X -1199(indices,)X -1469(so)X -1563(the)X -1684(forward)X -1962(index)X -2163(is)X -2239(much)X -2440(larger)X -2651(than)X -2812(the)X -2933(backward)X -3269(one)X -7 s -3385 4853(5)N -10 s -4885(.)Y -3476(This)X -3640(larger)X -3850(size)X -3997(shows)X -4219(up)X -555 4975(as)N -642(extra)X -823(disk)X -976(reads)X -1166(in)X -1248(the)X -1366(cold)X -1524(benchmark.)X -3 f -555 5161(6.)N -655(Conclusions)X -1 f -755 5284(LIBTP)N -1006(provides)X -1311(the)X -1438(basic)X -1632(building)X -1927(blocks)X -2165(to)X -2256(support)X -2525(transaction)X -2906(protection.)X -3300(In)X -3396(comparison)X -3799(with)X -3970(traditional)X -555 5374(Unix)N -746(libraries)X -1040(and)X -1187(commercial)X -1597(systems,)X -1900(it)X -1974(offers)X -2192(a)X -2258(variety)X -2511(of)X -2608(tradeoffs.)X -2964(Using)X -3185(complete)X -3509(transaction)X -3891(protection)X -4246(is)X -555 5464(more)N -747(complicated)X -1166(than)X -1331(simply)X -1575(adding)X -3 f -1820(fsync)X -1 f -1998(\(2\))X -2119(and)X -3 f -2262(\257ock)X -1 f -2426(\(2\))X -2547(calls)X -2721(to)X -2810(code,)X -3008(but)X -3136(it)X -3206(is)X -3285(faster)X -3490(in)X -3578(some)X -3773(cases)X -3969(and)X -4111(offers)X -8 s -10 f -555 5536(hhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhh)N -5 s -1 f -727 5614(5)N -8 s -763 5639(The)N -878(next)X -1004(release)X -1196(of)X -1265(the)X -1359(4.4BSD)X -1580(access)X -1758(method)X -1966(will)X -2082(automatically)X -2446(detect)X -2614(and)X -2722(compensate)X -3039(for)X -3129(in-order)X -3350(insertion,)X -3606(eliminating)X -3914(this)X -4023(problem.)X - -16 p -%%Page: 16 16 -8 s 8 xH 0 xS 1 f -10 s -3 f -1 f -555 630(stricter)N -801(guarantees)X -1168(\(atomicity,)X -1540(consistency,)X -1957(isolation,)X -2275(and)X -2414(durability\).)X -2815(If)X -2892(the)X -3013(data)X -3170(to)X -3255(be)X -3354(protected)X -3676(are)X -3798(already)X -4058(format-)X -555 720(ted)N -675(\()X -2 f -702(i.e.)X -1 f -821(use)X -949(one)X -1086(of)X -1174(the)X -1293(database)X -1591(access)X -1818(methods\),)X -2157(then)X -2316(adding)X -2555(transaction)X -2928(protection)X -3274(requires)X -3554(no)X -3655(additional)X -3996(complex-)X -555 810(ity,)N -679(but)X -801(incurs)X -1017(a)X -1073(performance)X -1500(penalty)X -1756(of)X -1843(approximately)X -2326(15%.)X -755 933(In)N -844(comparison)X -1240(with)X -1404(commercial)X -1805(database)X -2104(systems,)X -2399(the)X -2519(tradeoffs)X -2827(are)X -2948(more)X -3135(complex.)X -3473(LIBTP)X -3717(does)X -3886(not)X -4009(currently)X -555 1023(support)N -825(a)X -891(standard)X -1193(query)X -1406(language.)X -1766(The)X -1921(TCL-based)X -2312(server)X -2539(process)X -2810(allows)X -3049(a)X -3115(certain)X -3364(ease)X -3533(of)X -3630(use)X -3767(which)X -3993(would)X -4223(be)X -555 1113(enhanced)N -882(with)X -1047(a)X -1106(more)X -1294(user-friendly)X -1732(interface)X -2037(\()X -2 f -2064(e.g.)X -1 f -2203(a)X -2261(windows)X -2572(based)X -2777(query-by-form)X -3272(application\),)X -3697(for)X -3813(which)X -4031(we)X -4147(have)X -555 1203(a)N -620(working)X -916(prototype.)X -1292(When)X -1513(accesses)X -1815(do)X -1924(not)X -2055(require)X -2312(sophisticated)X -2758(query)X -2969(processing,)X -3360(the)X -3486(TCL)X -3665(interface)X -3975(is)X -4056(an)X -4160(ade-)X -555 1293(quate)N -756(solution.)X -1080(What)X -1281(LIBTP)X -1529(fails)X -1693(to)X -1781(provide)X -2052(in)X -2140(functionality,)X -2595(it)X -2665(makes)X -2896(up)X -3002(for)X -3122(in)X -3210(performance)X -3643(and)X -3785(\257exibility.)X -4161(Any)X -555 1383(application)N -931(may)X -1089(make)X -1283(use)X -1410(of)X -1497(its)X -1592(record)X -1818(interface)X -2120(or)X -2207(the)X -2325(more)X -2510(primitive)X -2823(log,)X -2965(lock,)X -3143(and)X -3279(buffer)X -3496(calls.)X -755 1506(Future)N -987(work)X -1175(will)X -1322(focus)X -1519(on)X -1621(overcoming)X -2026(some)X -2217(of)X -2306(the)X -2426(areas)X -2614(in)X -2698(which)X -2916(LIBTP)X -3160(is)X -3235(currently)X -3547(de\256cient)X -3845(and)X -3983(extending)X -555 1596(its)N -652(transaction)X -1026(model.)X -1288(The)X -1435(addition)X -1719(of)X -1808(an)X -1905(SQL)X -2077(parser)X -2295(and)X -2432(forms)X -2640(front)X -2817(end)X -2954(will)X -3099(improve)X -3387(the)X -3506(system's)X -3807(ease)X -3967(of)X -4055(use)X -4183(and)X -555 1686(make)N -750(it)X -815(more)X -1001(competitive)X -1400(with)X -1563(commercial)X -1963(systems.)X -2277(In)X -2365(the)X -2484(long)X -2647(term,)X -2835(we)X -2950(would)X -3170(like)X -3310(to)X -3392(add)X -3528(generalized)X -3919(hierarchical)X -555 1776(locking,)N -836(nested)X -1062(transactions,)X -1486(parallel)X -1748(transactions,)X -2171(passing)X -2431(of)X -2518(transactions)X -2921(between)X -3209(processes,)X -3557(and)X -3693(distributed)X -4055(commit)X -555 1866(handling.)N -900(In)X -992(the)X -1115(short)X -1300(term,)X -1492(the)X -1614(next)X -1776(step)X -1929(is)X -2006(to)X -2092(integrate)X -2397(LIBTP)X -2643(with)X -2809(the)X -2931(most)X -3110(recent)X -3331(release)X -3579(of)X -3670(the)X -3792(database)X -4093(access)X -555 1956(routines)N -833(and)X -969(make)X -1163(it)X -1227(freely)X -1435(available)X -1745(via)X -1863(anonymous)X -2252(ftp.)X -3 f -555 2142(7.)N -655(Acknowledgements)X -1 f -755 2265(We)N -888(would)X -1109(like)X -1250(to)X -1332(thank)X -1530(John)X -1701(Wilkes)X -1948(and)X -2084(Carl)X -2242(Staelin)X -2484(of)X -2571(Hewlett-Packard)X -3131(Laboratories)X -3557(and)X -3693(Jon)X -3824(Krueger.)X -4148(John)X -555 2355(and)N -694(Carl)X -855(provided)X -1162(us)X -1255(with)X -1419(an)X -1517(extra)X -1700(disk)X -1855(for)X -1971(the)X -2091(HP)X -2215(testbed)X -2464(less)X -2606(than)X -2766(24)X -2868(hours)X -3068(after)X -3238(we)X -3354(requested)X -3684(it.)X -3770(Jon)X -3903(spent)X -4094(count-)X -555 2445(less)N -699(hours)X -901(helping)X -1164(us)X -1258(understand)X -1633(the)X -1754(intricacies)X -2107(of)X -2197(commercial)X -2599(database)X -2899(products)X -3198(and)X -3337(their)X -3507(behavior)X -3811(under)X -4017(a)X -4076(variety)X -555 2535(of)N -642(system)X -884(con\256gurations.)X -3 f -555 2721(8.)N -655(References)X -1 f -555 2901([ANDR89])N -942(Andrade,)X -1265(J.,)X -1361(Carges,)X -1629(M.,)X -1765(Kovach,)X -2060(K.,)X -2183(``Building)X -2541(an)X -2642(On-Line)X -2939(Transaction)X -3343(Processing)X -3715(System)X -3975(On)X -4098(UNIX)X -727 2991(System)N -982(V'',)X -2 f -1134(CommUNIXations)X -1 f -1725(,)X -1765 0.2188(November/December)AX -2477(1989.)X -555 3171([BAY77])N -878(Bayer,)X -1110(R.,)X -1223(Schkolnick,)X -1623(M.,)X -1754(``Concurrency)X -2243(of)X -2330(Operations)X -2702(on)X -2802(B-Trees'',)X -2 f -3155(Acta)X -3322(Informatica)X -1 f -3700(,)X -3740(1977.)X -555 3351([BERN80])N -936(Bernstein,)X -1297(P.,)X -1415(Goodman,)X -1785(N.,)X -1917(``Timestamp)X -2365(Based)X -2595(Algorithms)X -2992(for)X -3119(Concurrency)X -3567(Control)X -3844(in)X -3939(Distributed)X -727 3441(Database)N -1042(Systems'',)X -2 f -1402(Proceedings)X -1823(6th)X -1945(International)X -2387(Conference)X -2777(on)X -2877(Very)X -3049(Large)X -3260(Data)X -3440(Bases)X -1 f -3627(,)X -3667(October)X -3946(1980.)X -555 3621([BSD91])N -864(DB\(3\),)X -2 f -1109(4.4BSD)X -1376(Unix)X -1552(Programmer's)X -2044(Manual)X -2313(Reference)X -2655(Guide)X -1 f -2851(,)X -2891(University)X -3249(of)X -3336(California,)X -3701(Berkeley,)X -4031(1991.)X -555 3801([CATT91])N -923(Cattell,)X -1181(R.G.G.,)X -1455(``An)X -1632(Engineering)X -2049(Database)X -2369(Benchmark'',)X -2 f -2838(The)X -2983(Benchmark)X -3373(Handbook)X -3731(for)X -3848(Database)X -4179(and)X -727 3891(Transaction)N -1133(Processing)X -1509(Systems)X -1 f -1763(,)X -1803(J.)X -1874(Gray,)X -2075(editor,)X -2302(Morgan)X -2576(Kaufman)X -2895(1991.)X -555 4071([CHEN91])N -929(Cheng,)X -1180(E.,)X -1291(Chang,)X -1542(E.,)X -1653(Klein,)X -1872(J.,)X -1964(Lee,)X -2126(D.,)X -2245(Lu,)X -2375(E.,)X -2485(Lutgardo,)X -2820(A.,)X -2939(Obermarck,)X -3342(R.,)X -3456(``An)X -3629(Open)X -3824(and)X -3961(Extensible)X -727 4161(Event-Based)N -1157(Transaction)X -1556(Manager'',)X -2 f -1936(Proceedings)X -2357(1991)X -2537(Summer)X -2820(Usenix)X -1 f -3043(,)X -3083(Nashville,)X -3430(TN,)X -3577(June)X -3744(1991.)X -555 4341([CHOU85])N -943(Chou,)X -1163(H.,)X -1288(DeWitt,)X -1570(D.,)X -1694(``An)X -1872(Evaluation)X -2245(of)X -2338(Buffer)X -2574(Management)X -3019(Strategies)X -3361(for)X -3481(Relational)X -3836(Database)X -4157(Sys-)X -727 4431(tems'',)N -2 f -972(Proceedings)X -1393(of)X -1475(the)X -1593(11th)X -1755(International)X -2197(Conference)X -2587(on)X -2687(Very)X -2859(Large)X -3070(Databases)X -1 f -3408(,)X -3448(1985.)X -555 4611([DEWI84])N -925(DeWitt,)X -1207(D.,)X -1331(Katz,)X -1529(R.,)X -1648(Olken,)X -1890(F.,)X -2000(Shapiro,)X -2295(L.,)X -2410(Stonebraker,)X -2843(M.,)X -2979(Wood,)X -3220(D.,)X -3343(``Implementation)X -3929(Techniques)X -727 4701(for)N -841(Main)X -1030(Memory)X -1326(Database)X -1641(Systems'',)X -2 f -2001(Proceedings)X -2422(of)X -2504(SIGMOD)X -1 f -2812(,)X -2852(pp.)X -2972(1-8,)X -3119(June)X -3286(1984.)X -555 4881([GRAY76])N -944(Gray,)X -1153(J.,)X -1252(Lorie,)X -1474(R.,)X -1595(Putzolu,)X -1887(F.,)X -1999(and)X -2143(Traiger,)X -2428(I.,)X -2522(``Granularity)X -2973(of)X -3067(locks)X -3263(and)X -3406(degrees)X -3679(of)X -3773(consistency)X -4174(in)X -4263(a)X -727 4971(large)N -909(shared)X -1140(data)X -1295(base'',)X -2 f -1533(Modeling)X -1861(in)X -1944(Data)X -2125(Base)X -2301(Management)X -2740(Systems)X -1 f -2994(,)X -3034(Elsevier)X -3317(North)X -3524(Holland,)X -3822(New)X -3994(York,)X -4199(pp.)X -727 5061(365-394.)N -555 5241([HAER83])N -931(Haerder,)X -1235(T.)X -1348(Reuter,)X -1606(A.)X -1728(``Principles)X -2126(of)X -2217(Transaction-Oriented)X -2928(Database)X -3246(Recovery'',)X -2 f -3651(Computing)X -4029(Surveys)X -1 f -4279(,)X -727 5331(15\(4\);)N -943(237-318,)X -1250(1983.)X -555 5511([KUNG81])N -943(Kung,)X -1162(H.)X -1261(T.,)X -1371(Richardson,)X -1777(J.,)X -1869(``On)X -2042(Optimistic)X -2400(Methods)X -2701(for)X -2816(Concurrency)X -3252(Control'',)X -2 f -3591(ACM)X -3781(Transactions)X -4219(on)X -727 5601(Database)N -1054(Systems)X -1 f -1328(6\(2\);)X -1504(213-226,)X -1811(1981.)X - -17 p -%%Page: 17 17 -10 s 10 xH 0 xS 1 f -3 f -1 f -555 630([LEHM81])N -939(Lehman,)X -1245(P.,)X -1352(Yao,)X -1529(S.,)X -1636(``Ef\256cient)X -1989(Locking)X -2279(for)X -2396(Concurrent)X -2780(Operations)X -3155(on)X -3258(B-trees'',)X -2 f -3587(ACM)X -3779(Transactions)X -4219(on)X -727 720(Database)N -1054(Systems)X -1 f -1308(,)X -1348(6\(4\),)X -1522(December)X -1873(1981.)X -555 900([MOHA91])N -964(Mohan,)X -1241(C.,)X -1364(Pirahesh,)X -1690(H.,)X -1818(``ARIES-RRH:)X -2366(Restricted)X -2721(Repeating)X -3076(of)X -3173(History)X -3442(in)X -3533(the)X -3660(ARIES)X -3920(Transaction)X -727 990(Recovery)N -1055(Method'',)X -2 f -1398(Proceedings)X -1819(7th)X -1941(International)X -2383(Conference)X -2773(on)X -2873(Data)X -3053(Engineering)X -1 f -3449(,)X -3489(Kobe,)X -3703(Japan,)X -3926(April)X -4115(1991.)X -555 1170([NODI90])N -914(Nodine,)X -1194(M.,)X -1328(Zdonik,)X -1602(S.,)X -1709(``Cooperative)X -2178(Transaction)X -2580(Hierarchies:)X -2996(A)X -3077(Transaction)X -3479(Model)X -3711(to)X -3796(Support)X -4072(Design)X -727 1260(Applications'',)N -2 f -1242(Proceedings)X -1675(16th)X -1849(International)X -2303(Conference)X -2704(on)X -2815(Very)X -2998(Large)X -3220(Data)X -3411(Bases)X -1 f -3598(,)X -3649(Brisbane,)X -3985(Australia,)X -727 1350(August)N -978(1990.)X -555 1530([OUST90])N -923(Ousterhout,)X -1324(J.,)X -1420(``Tcl:)X -1648(An)X -1771(Embeddable)X -2197(Command)X -2555(Language'',)X -2 f -2971(Proceedings)X -3396(1990)X -3580(Winter)X -3822(Usenix)X -1 f -4045(,)X -4089(Wash-)X -727 1620(ington,)N -971(D.C.,)X -1162(January)X -1432(1990.)X -555 1800([POSIX91])N -955(``Unapproved)X -1441(Draft)X -1645(for)X -1773(Realtime)X -2096(Extension)X -2450(for)X -2578(Portable)X -2879(Operating)X -3234(Systems'',)X -3608(Draft)X -3812(11,)X -3946(October)X -4239(7,)X -727 1890(1991,)N -927(IEEE)X -1121(Computer)X -1461(Society.)X -555 2070([ROSE91])N -925(Rosenblum,)X -1341(M.,)X -1484(Ousterhout,)X -1892(J.,)X -1995(``The)X -2206(Design)X -2464(and)X -2611(Implementation)X -3149(of)X -3247(a)X -3314(Log-Structured)X -3835(File)X -3990(System'',)X -2 f -727 2160(Proceedings)N -1148(of)X -1230(the)X -1348(13th)X -1510(Symposium)X -1895(on)X -1995(Operating)X -2344(Systems)X -2618(Principles)X -1 f -2947(,)X -2987(1991.)X -555 2340([SELT91])N -904(Seltzer,)X -1171(M.,)X -1306(Stonebraker,)X -1738(M.,)X -1873(``Read)X -2116(Optimized)X -2478(File)X -2626(Systems:)X -2938(A)X -3020(Performance)X -3454(Evaluation'',)X -2 f -3898(Proceedings)X -727 2430(7th)N -849(Annual)X -1100(International)X -1542(Conference)X -1932(on)X -2032(Data)X -2212(Engineering)X -1 f -2608(,)X -2648(Kobe,)X -2862(Japan,)X -3085(April)X -3274(1991.)X -555 2610([SPEC88])N -907(Spector,)X -1200(Rausch,)X -1484(Bruell,)X -1732(``Camelot:)X -2107(A)X -2192(Flexible,)X -2501(Distributed)X -2888(Transaction)X -3294(Processing)X -3668(System'',)X -2 f -4004(Proceed-)X -727 2700(ings)N -880(of)X -962(Spring)X -1195(COMPCON)X -1606(1988)X -1 f -(,)S -1806(February)X -2116(1988.)X -555 2880([SQL86])N -862(American)X -1201(National)X -1499(Standards)X -1836(Institute,)X -2139(``Database)X -2509(Language)X -2847(SQL'',)X -3093(ANSI)X -3301(X3.135-1986)X -3747(\(ISO)X -3924(9075\),)X -4152(May)X -727 2970(1986.)N -555 3150([STON81])N -919(Stonebraker,)X -1348(M.,)X -1480(``Operating)X -1876(System)X -2132(Support)X -2406(for)X -2520(Database)X -2835(Management'',)X -2 f -3348(Communications)X -3910(of)X -3992(the)X -4110(ACM)X -1 f -4279(,)X -727 3240(1981.)N -555 3420([SULL92])N -925(Sullivan,)X -1247(M.,)X -1394(Olson,)X -1641(M.,)X -1788(``An)X -1976(Index)X -2195(Implementation)X -2737(Supporting)X -3127(Fast)X -3295(Recovery)X -3638(for)X -3767(the)X -3900(POSTGRES)X -727 3510(Storage)N -1014(System'',)X -1365(to)X -1469(appear)X -1726(in)X -2 f -1830(Proceedings)X -2272(8th)X -2415(Annual)X -2687(International)X -3150(Conference)X -3561(on)X -3682(Data)X -3883(Engineering)X -1 f -4279(,)X -727 3600(Tempe,)N -990(Arizona,)X -1289(February)X -1599(1992.)X -555 3780([TPCB90])N -914(Transaction)X -1319(Processing)X -1692(Performance)X -2129(Council,)X -2428(``TPC)X -2653(Benchmark)X -3048(B'',)X -3200(Standard)X -3510(Speci\256cation,)X -3973(Waterside)X -727 3870(Associates,)N -1110(Fremont,)X -1421(CA.,)X -1592(1990.)X -555 4050([YOUN91])N -947(Young,)X -1211(M.)X -1328(W.,)X -1470(Thompson,)X -1858(D.)X -1962(S.,)X -2072(Jaffe,)X -2274(E.,)X -2388(``A)X -2525(Modular)X -2826(Architecture)X -3253(for)X -3372(Distributed)X -3757(Transaction)X -4161(Pro-)X -727 4140(cessing'',)N -2 f -1057(Proceedings)X -1478(1991)X -1658(Winter)X -1896(Usenix)X -1 f -2119(,)X -2159(Dallas,)X -2404(TX,)X -2551(January)X -2821(1991.)X -3 f -755 4263(Margo)N -1008(I.)X -1080(Seltzer)X -1 f -1338(is)X -1411(a)X -1467(Ph.D.)X -1669(student)X -1920(in)X -2002(the)X -2120(Department)X -2519(of)X -2606(Electrical)X -2934(Engineering)X -3346(and)X -3482(Computer)X -3822(Sciences)X -4123(at)X -4201(the)X -555 4353(University)N -919(of)X -1012(California,)X -1383(Berkeley.)X -1739(Her)X -1886(research)X -2181(interests)X -2474(include)X -2735(\256le)X -2862(systems,)X -3160(databases,)X -3513(and)X -3654(transaction)X -4031(process-)X -555 4443(ing)N -686(systems.)X -1008(She)X -1157(spent)X -1355(several)X -1612(years)X -1811(working)X -2107(at)X -2194(startup)X -2441(companies)X -2813(designing)X -3153(and)X -3298(implementing)X -3771(\256le)X -3902(systems)X -4183(and)X -555 4533(transaction)N -929(processing)X -1294(software)X -1592(and)X -1729(designing)X -2061(microprocessors.)X -2648(Ms.)X -2791(Seltzer)X -3035(received)X -3329(her)X -3453(AB)X -3585(in)X -3668(Applied)X -3947(Mathemat-)X -555 4623(ics)N -664(from)X -840 0.1953(Harvard/Radcliffe)AX -1445(College)X -1714(in)X -1796(1983.)X -755 4746(In)N -845(her)X -971(spare)X -1163(time,)X -1347(Margo)X -1583(can)X -1717(usually)X -1970(be)X -2068(found)X -2277(preparing)X -2607(massive)X -2887(quantities)X -3220(of)X -3309(food)X -3478(for)X -3594(hungry)X -3843(hordes,)X -4099(study-)X -555 4836(ing)N -677(Japanese,)X -1003(or)X -1090(playing)X -1350(soccer)X -1576(with)X -1738(an)X -1834(exciting)X -2112(Bay)X -2261(Area)X -2438(Women's)X -2770(Soccer)X -3009(team,)X -3205(the)X -3323(Berkeley)X -3633(Bruisers.)X -3 f -755 5049(Michael)N -1056(A.)X -1159(Olson)X -1 f -1383(is)X -1461(a)X -1522(Master's)X -1828(student)X -2084(in)X -2170(the)X -2292(Department)X -2695(of)X -2786(Electrical)X -3118(Engineering)X -3534(and)X -3674(Computer)X -4018(Sciences)X -555 5139(at)N -645(the)X -774(University)X -1143(of)X -1241(California,)X -1617(Berkeley.)X -1978(His)X -2120(primary)X -2405(interests)X -2703(are)X -2833(database)X -3141(systems)X -3425(and)X -3572(mass)X -3763(storage)X -4026(systems.)X -555 5229(Mike)N -759(spent)X -963(two)X -1118(years)X -1323(working)X -1625(for)X -1754(a)X -1825(commercial)X -2239(database)X -2551(system)X -2808(vendor)X -3066(before)X -3307(joining)X -3567(the)X -3699(Postgres)X -4004(Research)X -555 5319(Group)N -780(at)X -858(Berkeley)X -1168(in)X -1250(1988.)X -1470(He)X -1584(received)X -1877(his)X -1990(B.A.)X -2161(in)X -2243(Computer)X -2583(Science)X -2853(from)X -3029(Berkeley)X -3339(in)X -3421(May)X -3588(1991.)X -755 5442(Mike)N -945(only)X -1108(recently)X -1388(transferred)X -1758(into)X -1903(Sin)X -2030(City,)X -2208(but)X -2330(is)X -2403(rapidly)X -2650(adopting)X -2950(local)X -3126(customs)X -3408(and)X -3544(coloration.)X -3929(In)X -4016(his)X -4129(spare)X -555 5532(time,)N -742(he)X -843(organizes)X -1176(informal)X -1477(Friday)X -1711(afternoon)X -2043(study)X -2240(groups)X -2482(to)X -2568(discuss)X -2823(recent)X -3044(technical)X -3358(and)X -3498(economic)X -3834(developments.)X -555 5622(Among)N -815(his)X -928(hobbies)X -1197(are)X -1316(Charles)X -1581(Dickens,)X -1884(Red)X -2033(Rock,)X -2242(and)X -2378(speaking)X -2683(Dutch)X -2899(to)X -2981(anyone)X -3233(who)X -3391(will)X -3535(permit)X -3764(it.)X - -17 p -%%Trailer -xt - -xs - diff --git a/libdb/docs/ref/refs/refs.html b/libdb/docs/ref/refs/refs.html deleted file mode 100644 index b72666eb3..000000000 --- a/libdb/docs/ref/refs/refs.html +++ /dev/null @@ -1,76 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Additional references</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Additional References</dl></h3></td> -<td align=right><a href="../../ref/distrib/layout.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a> -</td></tr></table> -<p> -<h1 align=center>Additional references</h1> -<p>For more information on Berkeley DB or on database systems theory in general, -we recommend the following sources: -<h3>Technical Papers on Berkeley DB</h3> -<p>These papers have appeared in refereed conference proceedings, and are -subject to copyrights held by the conference organizers and the authors -of the papers. Sleepycat Software makes them available here as a courtesy -with the permission of the copyright holders. -<p><dl compact> -<p><dt><i>Berkeley DB</i> (<a href="bdb_usenix.html">HTML</a>, <a href="bdb_usenix.ps">Postscript</a>)<dd>Michael Olson, Keith Bostic, and Margo Seltzer, Proceedings of the 1999 -Summer Usenix Technical Conference, Monterey, California, June 1999. This -paper describes recent commercial releases of Berkeley DB, its most important -features, the history of the software, and Sleepycat's Open Source -licensing policies. -<p><dt><i>Challenges in Embedded Database System Administration</i> -(<a href="embedded.html">HTML</a>)<dd>Margo Seltzer and Michael Olson, First Workshop on Embedded Systems, -Cambridge, Massachusetts, March 1999. This paper describes the challenges -that face embedded systems developers, and how Berkeley DB has been designed to -address them. -<p><dt><i>LIBTP: Portable Modular Transactions for UNIX</i> -(<a href="libtp_usenix.ps">Postscript</a>)<dd>Margo Seltzer and Michael Olson, USENIX Conference Proceedings, Winter -1992. This paper describes an early prototype of the transactional system -for Berkeley DB. -<p><dt><i>A New Hashing Package for UNIX</i> -(<a href="hash_usenix.ps">Postscript</a>)<dd>Margo Seltzer and Oz Yigit, USENIX Conference Proceedings, Winter 1991. -This paper describes the Extended Linear Hashing techniques used by Berkeley DB. -</dl> -<h3>Background on Berkeley DB Features</h3> -<p>These papers, although not specific to Berkeley DB, give a good overview of the -way different Berkeley DB features were implemented. -<p><dl compact> -<p><dt><i>Operating System Support for Database Management</i><dd>Michael Stonebraker, Communications of the ACM 24(7), 1981, pp. 412-418. -<p><dt><i>Dynamic Hash Tables</i><dd>Per-Ake Larson, Communications of the ACM, April 1988. -<p><dt><i>Linear Hashing: A New Tool for File and Table Addressing</i><dd><a href="witold.html">Witold Litwin</a>, Proceedings of the 6th International -Conference on Very Large Databases (VLDB), 1980 -<p><dt><i>The Ubiquitous B-tree</i><dd>Douglas Comer, ACM Comput. Surv. 11, 2 (June 1979), pp. 121-138. -<p><dt><i>Prefix B-trees</i><dd>Bayer and Unterauer, ACM Transactions on Database Systems, Vol. 2, 1 -(March 1977), pp. 11-26. -<p><dt><i>The Art of Computer Programming Vol. 3: Sorting and Searching</i><dd>D.E. Knuth, 1968, pp. 471-480. -<p><dt><i>Document Processing in a Relational Database System</i><dd>Michael Stonebraker, Heidi Stettner, Joseph Kalash, Antonin Guttman, -Nadene Lynn, Memorandum No. UCB/ERL M82/32, May 1982. -</dl> -<h3>Database Systems Theory</h3> -<p>These publications are standard reference works on the design and -implementation of database systems. Berkeley DB uses many of the ideas they -describe. -<p><dl compact> -<p><dt><i>Transaction Processing Concepts and Techniques</i><dd>by Jim Gray and Andreas Reuter, Morgan Kaufmann Publishers. -We recommend chapters 1, 4 (skip 4.6, 4.7, 4.9, 4.10 and 4.11), -7, 9, 10.3, and 10.4. -<p><dt><i>An Introduction to Database Systems, Volume 1</i><dd>by C.J. Date, Addison Wesley Longman Publishers. -In the 5th Edition, we recommend chapters 1, 2, 3, 16 and 17. -<p><dt><i>Concurrency Control and Recovery in Database Systems</i><dd>by Bernstein, Goodman, Hadzilaco. Currently out of print, but available -from <a href="http://research.microsoft.com/pubs/ccontrol/">http://research.microsoft.com/pubs/ccontrol/</a>. -</dl> -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/distrib/layout.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a> -</td></tr></table> -<p><font size=1><a href="http://www.sleepycat.com">Copyright Sleepycat Software</a></font> -</body> -</html> diff --git a/libdb/docs/ref/refs/witold.html b/libdb/docs/ref/refs/witold.html deleted file mode 100644 index 9b72c76fe..000000000 --- a/libdb/docs/ref/refs/witold.html +++ /dev/null @@ -1,24 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Witold Litwin</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Additional References</dl></h3></td> -<td align=right><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a> -</td></tr></table> -<p> -<h1 align=center>Witold Litwin</h1> -<p>Witold is a hell of a guy to take you on a late-night high-speed car -chase up the mountains of Austria in search of very green wine. -<table width="100%"><tr><td><br></td><td align=right><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a> -</td></tr></table> -<p><font size=1><a href="http://www.sleepycat.com">Copyright Sleepycat Software</a></font> -</body> -</html> diff --git a/libdb/docs/ref/rep/app.html b/libdb/docs/ref/rep/app.html deleted file mode 100644 index 1397a7144..000000000 --- a/libdb/docs/ref/rep/app.html +++ /dev/null @@ -1,96 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Building replicated applications</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Berkeley DB Replication</dl></h3></td> -<td align=right><a href="../../ref/rep/pri.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/rep/comm.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Building replicated applications</h1> -<p>The simplest way to build a replicated Berkeley DB application is to first -build (and debug!) the transactional version of the same application. -Then, add a thin replication layer to the application. All highly available -applications use the following additional four Berkeley DB methods: -<a href="../../api_c/rep_elect.html">DB_ENV->rep_elect</a>, <a href="../../api_c/rep_message.html">DB_ENV->rep_process_message</a>, <a href="../../api_c/rep_start.html">DB_ENV->rep_start</a> and -<a href="../../api_c/rep_transport.html">DB_ENV->set_rep_transport</a> and may also use the configuration method -<a href="../../api_c/rep_limit.html">DB_ENV->set_rep_limit</a>: -<p><dl compact> -<p><dt><a href="../../api_c/rep_transport.html">DB_ENV->set_rep_transport</a><dd>The <a href="../../api_c/rep_transport.html">DB_ENV->set_rep_transport</a> method configures the replication system's -communications infrastructure. -<p><dt><a href="../../api_c/rep_start.html">DB_ENV->rep_start</a><dd>The <a href="../../api_c/rep_start.html">DB_ENV->rep_start</a> method configures (or reconfigures) an existing database -environment to be a replication master or client. -<p><dt><a href="../../api_c/rep_message.html">DB_ENV->rep_process_message</a><dd>The <a href="../../api_c/rep_message.html">DB_ENV->rep_process_message</a> method is used to process incoming messages from other -environments in the replication group. For clients, it is responsible -for accepting log records and updating the local databases based on -messages from the master. For both the master and the clients, it is -responsible for handling administrative functions (for example, the -protocol for dealing with lost messages), and permitting new clients to -join an active replication group. -<p><dt><a href="../../api_c/rep_elect.html">DB_ENV->rep_elect</a><dd>The <a href="../../api_c/rep_elect.html">DB_ENV->rep_elect</a> method causes the replication group to elect a new -master; it is called whenever contact with the master is lost. -<p><dt><a href="../../api_c/rep_limit.html">DB_ENV->set_rep_limit</a><dd>The <a href="../../api_c/rep_limit.html">DB_ENV->set_rep_limit</a> imposes an upper bound on the amount of data -that will be sent in response to a single call to <a href="../../api_c/rep_message.html">DB_ENV->rep_process_message</a>. -</dl> -<p>To add replication to a Berkeley DB application, application initialization -must be changed and the application's communications infrastructure must -be written. The application initialization changes are relatively -simple, but the communications infrastructure code can be complex. -<p>During application initialization, the application performs two -additional tasks: first, it must provide Berkeley DB information about its -communications infrastructure, and second, it must start the Berkeley DB -replication system. Generally, a replicated application will do normal -Berkeley DB recovery and configuration, exactly like any other transactional -application. Then, once the database environment has been opened, it -will call the <a href="../../api_c/rep_transport.html">DB_ENV->set_rep_transport</a> method to configure Berkeley DB for replication, -and then will call the <a href="../../api_c/rep_start.html">DB_ENV->rep_start</a> method to join or create the -replication group. -<p>When calling <a href="../../api_c/rep_start.html">DB_ENV->rep_start</a>, the application has two choices: -specifically configure the master for the replication group, or, -alternatively, configure all group members as clients and then call an -election, letting the clients select the master from among themselves. -Either is correct, and the choice is entirely up to the application. -The result of calling <a href="../../api_c/rep_start.html">DB_ENV->rep_start</a> is usually the discovery of a -master, or the declaration of the local environment as the master. If -a master has not been discovered after a reasonable amount of time, the -application should call <a href="../../api_c/rep_elect.html">DB_ENV->rep_elect</a> to call for an election. -<p>In the case of multiple processes accessing a replicated environment, -all of the threads of control expecting to modify databases in the -environment or process replication messages must call the -<a href="../../api_c/rep_start.html">DB_ENV->rep_start</a> method. Note that not all processes running in replicated -environments need to call <a href="../../api_c/rep_transport.html">DB_ENV->set_rep_transport</a> or <a href="../../api_c/rep_start.html">DB_ENV->rep_start</a>. -Read-only processes running in a master environment do not need to be -configured for replication in any way. Processes running in a client -environment are read-only by definition, and so do not need to be -configured for replication either (although, in the case of clients that -may become masters, it is usually simplest to configure for replication -on process startup rather than trying to reconfigure when the client -becomes a master). Obviously, at least one thread of control on each -client must be configured for replication as messages must be passed -between the master and the client. -<p>Databases are generally opened read-write on both clients and masters -in order to simplify upgrading replication clients to be masters. (If -databases are opened read-only on clients, and the client is then -upgraded to be the master, the client would have to close and reopen -all of its databases in order to support database update queries.) -However, even though the database is opened read-write on the client, -any attempt to update it will result in an error until the client is -reconfigured as a master. No databases can be opened on clients before -calling <a href="../../api_c/rep_start.html">DB_ENV->rep_start</a>, and attempting to do so will result in an -error. -<p>There are no additional interface calls required to shut down a database -environment participating in a replication group. The application -should shut down the environment in the usual manner, by calling the -<a href="../../api_c/env_close.html">DB_ENV->close</a> method. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/rep/pri.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/rep/comm.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/libdb/docs/ref/rep/comm.html b/libdb/docs/ref/rep/comm.html deleted file mode 100644 index dd3864c92..000000000 --- a/libdb/docs/ref/rep/comm.html +++ /dev/null @@ -1,79 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Building the communications infrastructure</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Berkeley DB Replication</dl></h3></td> -<td align=right><a href="../../ref/rep/app.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/rep/newsite.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Building the communications infrastructure</h1> -<p>The replication support in an application is typically written with one -or more threads of control looping on one or more communication -channels, receiving and sending messages. These threads accept messages -from remote environments for the local database environment, and accept -messages from the local environment for remote environments. Messages -from remote environments are passed to the local database environment -using the <a href="../../api_c/rep_message.html">DB_ENV->rep_process_message</a> method. Messages from the local environment -are passed to the application for transmission using the callback -interface specified to the <a href="../../api_c/rep_transport.html">DB_ENV->set_rep_transport</a> method. -<p>Processes establish communication channels by calling the -<a href="../../api_c/rep_transport.html">DB_ENV->set_rep_transport</a> method, regardless of whether they are running in client -or server environments. This method specifies the <b>send</b> -interface, a callback interface used by Berkeley DB for sending messages to -other database environments in the replication group. The <b>send</b> -interface takes an environment ID and two opaque data objects. It is -the responsibility of the <b>send</b> interface to transmit the -information in the two data objects to the database environment -corresponding to the ID, with the receiving application then calling -the <a href="../../api_c/rep_message.html">DB_ENV->rep_process_message</a> method to process the message. -<p>The details of the transport mechanism are left entirely to the -application; the only requirement is that the data buffer and size of -each of the control and rec <a href="../../api_c/dbt_class.html">DBT</a>s passed to the <b>send</b> -function on the sending site be faithfully copied and delivered to the -receiving site by means of a call to <a href="../../api_c/rep_message.html">DB_ENV->rep_process_message</a> with -corresponding arguments. The <a href="../../api_c/rep_message.html">DB_ENV->rep_process_message</a> method is free-threaded; it -is safe to deliver any number of messages simultaneously, and from any -arbitrary thread or process in the Berkeley DB environment. -<p>There are a number of informational returns from the -<a href="../../api_c/rep_message.html">DB_ENV->rep_process_message</a> method: -<p><dl compact> -<p><dt><a href="../../api_c/rep_message.html#DB_REP_DUPMASTER">DB_REP_DUPMASTER</a><dd>When <a href="../../api_c/rep_message.html">DB_ENV->rep_process_message</a> returns <a href="../../api_c/rep_message.html#DB_REP_DUPMASTER">DB_REP_DUPMASTER</a>, it means that -another database environment in the replication group also believes -itself to be the master. The application should complete all active -transactions, close all open database handles, reconfigure itself as -a client using the <a href="../../api_c/rep_start.html">DB_ENV->rep_start</a> method, and then call for an election by -calling the <a href="../../api_c/rep_elect.html">DB_ENV->rep_elect</a> method. -<p><dt><a href="../../api_c/rep_message.html#DB_REP_HOLDELECTION">DB_REP_HOLDELECTION</a><dd>When <a href="../../api_c/rep_message.html">DB_ENV->rep_process_message</a> returns <a href="../../api_c/rep_message.html#DB_REP_HOLDELECTION">DB_REP_HOLDELECTION</a>, it means -that another database environment in the replication group has called -for an election. The application should call the <a href="../../api_c/rep_elect.html">DB_ENV->rep_elect</a> method. -<p><dt><a href="../../api_c/rep_message.html#DB_REP_NEWMASTER">DB_REP_NEWMASTER</a><dd>When <a href="../../api_c/rep_message.html">DB_ENV->rep_process_message</a> returns <a href="../../api_c/rep_message.html#DB_REP_NEWMASTER">DB_REP_NEWMASTER</a>, it means that -a new master has been elected. The call will also return the local -environment's ID for that master. If the ID of the master has changed, -the application may need to reconfigure itself (for example, to redirect -update queries to the new master rather then the old one). If the new -master is the local environment, then the application must call the -<a href="../../api_c/rep_start.html">DB_ENV->rep_start</a> method, and reconfigure the supporting Berkeley DB library as a -replication master. -<p><dt><a href="../../api_c/rep_message.html#DB_REP_NEWSITE">DB_REP_NEWSITE</a><dd>When <a href="../../api_c/rep_message.html">DB_ENV->rep_process_message</a> returns <a href="../../api_c/rep_message.html#DB_REP_NEWSITE">DB_REP_NEWSITE</a>, it means that -a message from a previously unknown member of the replication group has -been received. The application should reconfigure itself as necessary -so it is able to send messages to this site. -<p><dt><a href="../../api_c/rep_message.html#DB_REP_OUTDATED">DB_REP_OUTDATED</a><dd>When <a href="../../api_c/rep_message.html">DB_ENV->rep_process_message</a> returns <a href="../../api_c/rep_message.html#DB_REP_OUTDATED">DB_REP_OUTDATED</a>, it means that -the environment has been partitioned from the master for too long a -time, and the master no longer has the necessary log files to update -the local client. The application should shut down, and the client -should be reinitialized (see <a href="../../ref/rep/init.html">Initializing a new site</a> for more information). -</dl> -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/rep/app.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/rep/newsite.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/libdb/docs/ref/rep/elect.html b/libdb/docs/ref/rep/elect.html deleted file mode 100644 index 7237c97e9..000000000 --- a/libdb/docs/ref/rep/elect.html +++ /dev/null @@ -1,97 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Elections</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Berkeley DB Replication</dl></h3></td> -<td align=right><a href="../../ref/rep/init.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/rep/logonly.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Elections</h1> -<p>Berkeley DB never initiates elections, that is the responsibility of the -application. It is not dangerous to hold an election, as the Berkeley DB -election process ensures there is never more than a single master -environment. Clients should initiate an election whenever they lose -contact with the master environment, whenever they see a return of -<a href="../../api_c/rep_message.html#DB_REP_HOLDELECTION">DB_REP_HOLDELECTION</a> from the <a href="../../api_c/rep_message.html">DB_ENV->rep_process_message</a> method, or when, for -whatever reason, they do not know who the master is. It is not -necessary for applications to immediately hold elections when they -start, as any existing master will be quickly discovered after calling -<a href="../../api_c/rep_start.html">DB_ENV->rep_start</a>. If no master has been found after a short wait -period, then the application should call for an election. -<p>For a client to become the master, the client must win an election. To -win an election, the replication group must currently have no master, -the client must have the highest priority of the database environments -participating in the election, and at least (N / 2 + 1) of the members -of the replication group must participate in the election. In the case -of multiple database environments with equal priorities, the environment -with the most recent log records will win. -<p>It is dangerous to configure more than one master environment using the -<a href="../../api_c/rep_start.html">DB_ENV->rep_start</a> method, and applications should be careful not to do so. -Applications should only configure themselves as the master environment -if they are the only possible master, or if they have won an election. -An application can only know it has won an election if the -<a href="../../api_c/rep_elect.html">DB_ENV->rep_elect</a> method returns success and the local database environment's -ID as the new master environment ID, or if the <a href="../../api_c/rep_message.html">DB_ENV->rep_process_message</a> method -returns <a href="../../api_c/rep_message.html#DB_REP_NEWMASTER">DB_REP_NEWMASTER</a> and the local database environment's -ID as the new master environment ID. -<p>To add a database environment to the replication group with the intent -of it becoming the master, first add it as a client. Since it may be -out-of-date with respect to the current master, allow it to update -itself from the current master. Then, shut the current master down. -Presumably, the added client will win the subsequent election. If the -client does not win the election, it is likely that it was not given -sufficient time to update itself with respect to the current master. -<p>If a client is unable to find a master or win an election, it means that -the network has been partitioned and there are not enough environments -participating in the election for one of the participants to win. In -this case, the application should repeatedly call <a href="../../api_c/rep_start.html">DB_ENV->rep_start</a> and -<a href="../../api_c/rep_elect.html">DB_ENV->rep_elect</a>, alternating between attempting to discover an -existing master, and holding an election to declare a new one. In -desperate circumstances, an application could simply declare itself the -master by calling <a href="../../api_c/rep_start.html">DB_ENV->rep_start</a>, or by reducing the number of -participants required to win an election until the election is won. -Neither of these solutions is recommended: in the case of a network -partition, either of these choices can result in there being two masters -in one replication group, and the databases in the environment might -irretrievably diverge as they are modified in different ways by the -masters. -<p>It is possible for a less-preferred database environment to win an -election if a number of systems crash at the same time. Because an -election winner is declared as soon as enough environments participate -in the election, the environment on a slow booting but well-connected -machine might lose to an environment on a badly connected but faster -booting machine. In the case of a number of environments crashing at -the same time (for example, a set of replicated servers in a single -machine room), applications should bring the database environments on -line as clients initially (which will allow them to process read queries -immediately), and then hold an election after sufficient time has passed -for the slower booting machines to catch up. -<p>If, for any reason, a less-preferred database environment becomes the -master, it is possible to switch masters in a replicated environment, -although it is not a simple operation. For example, the preferred -master crashes, and one of the replication group clients becomes the -group master. In order to restore the preferred master to master -status, take the following steps: -<p><ol> -<p><li>The preferred master should reboot and re-join the replication group -as a client. -<li>Once the preferred master has caught up with the replication group, the -application on the current master should complete all active -transactions, close all open database handles, and reconfigure itself -as a client using the <a href="../../api_c/rep_start.html">DB_ENV->rep_start</a> method. -<li>Then, the current or preferred master should call for an election using -the <a href="../../api_c/rep_elect.html">DB_ENV->rep_elect</a> method. -</ol> -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/rep/init.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/rep/logonly.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/libdb/docs/ref/rep/ex.html b/libdb/docs/ref/rep/ex.html deleted file mode 100644 index 623674445..000000000 --- a/libdb/docs/ref/rep/ex.html +++ /dev/null @@ -1,65 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Ex_repquote: a replication example</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Berkeley DB Replication</dl></h3></td> -<td align=right><a href="../../ref/rep/faq.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/rep/ex_comm.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Ex_repquote: a replication example</h1> -<p>Ex_repquote, found in the <b>examples_c/ex_repquote</b> subdirectory -of the Berkeley DB distribution, is a simple but complete demonstration of a -replicated application. The application is a mock stock ticker. The -master accepts a stock symbol and an integer value as input, stores this -information into a replicated database; the clients display the contents -of the database every few seconds. -<p>The ex_repquote application's communication infrastructure is based on -TCP/IP sockets, and uses POSIX 1003.1 style networking/socket support. -As a result, it is not as portable as the Berkeley DB library itself. The -Makefile created by the standard UNIX configuration will build the -ex_repquote application on most platforms. Enter "make ex_repquote" to -attempt to build it. -<p>The synopsis for ex_repquote is as follows: -<pre>ex_repquote [<b>-MC</b>] [<b>-h home</b>] [<b>-m host:port</b>] [<b>-o host:port</b>] [<b>-n sites</b>] [<b>-p priority</b>]</pre> -<p>The options to ex_repquote are as follows: -<p><dl compact> -<p><dt><b>-M</b><dd>Configure this process as a master. -<p><dt><b>-C</b><dd>Configure this process as a client. -<p><dt><b>-h</b><dd>Specify a home directory for the database environment; by -default, the current working directory is used. -<p><dt><b>-m</b><dd>Listen on port "port" of host "host" for incoming connections. -<p><dt><b>-o</b><dd>Attempt to connect to another member of the replication group which is -listening on host "host" at port "port". Members of a replication group -should be able to find all other members of a replication group so long -as they are in contact with at least one other member of the replication -group. -<p><dt><b>-n</b><dd>Specify the total number of sites in the replication group. -<p><dt><b>-p</b><dd>Set the election priority. See <a href="../../api_c/rep_elect.html">DB_ENV->rep_elect</a> for more -information. -</dl> -<p>A typical ex_repquote session begins with a command such as the -following, to start a master: -<p><blockquote><pre>ex_repquote -M -p 100 -n 4 -h DIR1 -m localhost:5000</pre></blockquote> -<p>and several clients: -<p><blockquote><pre>ex_repquote -C -p 50 -n 4 -h DIR2 -m localhost:5001 -o localhost:5000 -ex_repquote -C -p 10 -n 4 -h DIR3 -m localhost:5002 -o localhost:5000 -ex_repquote -C -p 0 -n 4 -h DIR4 -m localhost:5003 -o localhost:5000</pre></blockquote> -<p>In this example, the client with home directory DIR4 can never become -a master (its priority is 0). Both of the other clients can become -masters, but the one with home directory DIR2 is preferred. Priorities -are assigned by the application and should reflect the desirability of -having particular clients take over as master in the case that the -master fails. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/rep/faq.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/rep/ex_comm.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/libdb/docs/ref/rep/ex_comm.html b/libdb/docs/ref/rep/ex_comm.html deleted file mode 100644 index 4a87c6e31..000000000 --- a/libdb/docs/ref/rep/ex_comm.html +++ /dev/null @@ -1,177 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Ex_repquote: a TCP/IP based communication infrastructure</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Berkeley DB Replication</dl></h3></td> -<td align=right><a href="../../ref/rep/ex.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/rep/ex_rq.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Ex_repquote: a TCP/IP based communication infrastructure</h1> -<p>All Berkeley DB replication applications must implement a communication -infrastructure. The communication infrastructure consists of three -parts: a way to map environment IDs to particular sites, the functions -to get and receive messages, and the application architecture that -supports the particular communication infrastructure used (for example, -individual threads per communicating site, a shared message handler for -all sites, a hybrid solution). The communication infrastructure is -implemented in the file <b>ex_repquote/ex_rq_net.c</b>, and each part -of that infrastructure is described as follows. -<p>Ex_repquote maintains a table of environment ID to TCP/IP port mappings. -This table is stored in the app_private field of the <a href="../../api_c/env_class.html">DB_ENV</a> -object so it can be accessed by any function that has the database -environment handle. The table is represented by a machtab_t structure -which contains a reference to a linked list of member_t's, both of which -are defined in <b>ex_repquote/ex_rq_net.c</b>. Each member_t contains -the host and port identification, the environment ID, and a file -descriptor. The table is maintained by the following interfaces: -<p><blockquote><pre>int machtab_add(machtab_t *machtab, int fd, u_int32_t hostaddr, int port, int *eidp); -int machtab_init(machtab_t **machtabp, int priority, int nsites); -int machtab_getinfo(machtab_t *machtab, int eid, u_int32_t *hostp, int *portp); -void machtab_parm(machtab_t *machtab, int *nump, int *priorityp, u_int32_t *timeoutp); -int machtab_rem(machtab_t *machtab, int eid, int lock); -</pre></blockquote> -<p>These interfaces are particular to this application and communication -infrastructure, but provide an indication of the sort of functionality -that is needed to maintain the application-specific state for a -TCP/IP-based infrastructure. The goal of the table and its interfaces -is threefold: First, it must guarantee that given an environment ID, -the send function can send a message to the appropriate place. Second, -when given the special environment ID <a href="../../api_c/rep_transport.html#DB_EID_BROADCAST">DB_EID_BROADCAST</a>, the send -function can send messages to all the machines in the group. Third, -upon receipt of an incoming message, the receive function can correctly -identify the sender and pass the appropriate environment ID to the -<a href="../../api_c/rep_message.html">DB_ENV->rep_process_message</a> method. -<p>Mapping a particular environment ID to a specific port is accomplished -by looping through the linked list until the desired environment ID is -found. Broadcast communication is implemented by looping through the -linked list and sending to each member found. Since each port -communicates with only a single other environment, receipt of a message -on a particular port precisely identifies the sender. -<p>The example provided is merely one way to satisfy these requirements, -and there are alternative implementations as well. For instance, -instead of associating separate socket connections with each remote -environment, an application might instead label each message with a -sender identifier; instead of looping through a table and sending a -copy of a message to each member of the replication group, the -application could send a single message using a broadcast protocol. -<p>In ex_repquote's case, the send function (slightly simplified) is as -follows: -<pre><p><blockquote>int -quote_send(dbenv, control, rec, eid, flags) - DB_ENV *dbenv; - const DBT *control, *rec; - int eid; - u_int32_t flags; -{ - int fd, n, ret; - machtab_t *machtab; - member_t *m; -<p> - machtab = (machtab_t *)dbenv->app_private; -<p> - /* - * If this is a broadcast, call a separate function to - * iterate through the table of environment (a/k/a - * machine) IDs and call quote_send_one on each. - * (This function is not reproduced here, but can be - * seen in ex_rq_net.c.) - */ - if (eid == DB_EID_BROADCAST) { - n = quote_send_broadcast(machtab, rec, control, flags); - if (n < 0) - return (DB_REP_UNAVAIL); - return (0); - } -<p> - /* Find the fild descriptor, fd, associated with this EID. */ - fd = 0; - if ((ret = pthread_mutex_lock(&machtab->mtmutex)) != 0) - return (0); - for (m = LIST_FIRST(&machtab->machlist); m != NULL; - m = LIST_NEXT(m, links)) { - if (m->eid == eid) { - fd = m->fd; - break; - } - } - if (pthread_mutex_unlock(&machtab->mtmutex) != 0) - return (-1); -<p> - if (fd == 0) - return (DB_REP_UNAVAIL); -<p> - /* We have a file descriptor; write the data over it. */ - ret = quote_send_one(rec, control, fd, flags); -<p> - return (ret); -} -<p> -int -quote_send_broadcast(machtab, rec, control, flags) - machtab_t *machtab; - const DBT *rec, *control; - u_int32_t flags; -{ - int ret, sent; - member_t *m, *next; - if ((ret = pthread_mutex_lock(&machtab->mtmutex)) != 0) - return (0); - sent = 0; - for (m = LIST_FIRST(&machtab->machlist); m != NULL; m = next) { - next = LIST_NEXT(m, links); - if ((ret = quote_send_one(rec, control, m->fd, flags)) != 0) { - (void)machtab_rem(machtab, m->eid, 0); - } else - sent++; - } - if (pthread_mutex_unlock(&machtab->mtmutex) != 0) - return (-1); - return (sent); -}</blockquote></pre> -<p>The quote_send_one function has been omitted as it simply writes the -data requested over the file descriptor that it is passed. It contains -nothing specific to Berkeley DB or this communication infrastructure. The -complete code can be found in <b>ex_repquote/ex_rq_net.c</b>. -<p>The quote_send function is passed as the callback to <a href="../../api_c/rep_transport.html">DB_ENV->set_rep_transport</a>; -Berkeley DB automatically sends messages as needed for replication. The -receive function is a mirror to the quote_send_one function. It is not -a callback function (the application is responsible for collecting -messages and calling <a href="../../api_c/rep_message.html">DB_ENV->rep_process_message</a> on them as is convenient). In -the sample application, all messages transmitted are Berkeley DB messages that -get handled by <a href="../../api_c/rep_message.html">DB_ENV->rep_process_message</a>, however, this is not always going -to be the case. The application may want to pass its own messages -across the same channels, distinguish between its own messages and those -of Berkeley DB, and then pass only the Berkeley DB ones to <a href="../../api_c/rep_message.html">DB_ENV->rep_process_message</a>. -<p>The final component of the communication infrastructure is the process -model used to communicate with all the sites in the replication group. -Each site creates a thread of control that listens on its designated -socket (as specified by the <b>-m</b> command line argument) and -then creates a new channel for each site that contacts it. In addition, -each site explicitly connects to the sites specified in the -<b>-o</b> command line argument. This is a fairly standard TCP/IP -process architecture and is implemented by the following functions (all -in <b>ex_repquote/ex_rq_net.c</b>). -<p><blockquote><pre>int get_connected_socket(machtab_t *machtab, char *progname, char *remotehost, -int port, int *is_open, int *eidp): Connect to the specified host/port, add the -site to the machtab, and return a file descriptor for communication with this -site. -<p> -int listen_socket_init(char *progname, int port): Initialize a socket for -listening on a particular part. -<p> -int listen_socket_accept(machtab_t *machtab, char *progname, int socket, -int *eidp): Accept a connection on a socket and add it to the machtab. -int listen_socket_connect</pre></blockquote> -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/rep/ex.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/rep/ex_rq.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/libdb/docs/ref/rep/ex_rq.html b/libdb/docs/ref/rep/ex_rq.html deleted file mode 100644 index 80b7cd2ce..000000000 --- a/libdb/docs/ref/rep/ex_rq.html +++ /dev/null @@ -1,236 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Ex_repquote: putting it all together</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Berkeley DB Replication</dl></h3></td> -<td align=right><a href="../../ref/rep/ex_comm.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/xa/intro.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Ex_repquote: putting it all together</h1> -<p>A replicated application must initialize a replicated environment, set -up its communication infrastructure, and then make sure that incoming -messages are received and processed. -<p>To initialize replication, ex_repquote creates a Berkeley DB environment and -calls <a href="../../api_c/rep_transport.html">DB_ENV->set_rep_transport</a> to establish a send function. The following -code fragment (from the env_init function, found in -<b>ex_repquote/ex_rq_main.c</b>) demonstrates this. Prior to calling -this function, the application has called machtab_init to initialize -its environment ID to port mapping structure and passed this structure -into env_init. -<pre><p><blockquote>if ((ret = db_env_create(&dbenv, 0)) != 0) { - fprintf(stderr, "%s: env create failed: %s\n", - progname, db_strerror(ret)); - return (ret); -} -dbenv->set_errfile(dbenv, stderr); -dbenv->set_errpfx(dbenv, prefix); -(void)dbenv->set_cachesize(dbenv, 0, CACHESIZE, 0); -<p> -dbenv->app_private = machtab; -(void)dbenv->set_rep_transport(dbenv, SELF_EID, quote_send); -<p> -flags = DB_CREATE | DB_THREAD | - DB_INIT_LOCK | DB_INIT_LOG | DB_INIT_MPOOL | DB_INIT_TXN; -<p> -ret = dbenv->open(dbenv, home, flags, 0);</blockquote></pre> -<p>ex_repquote opens a listening socket for incoming connections and opens -an outgoing connection to every machine that it knows about (that is, -all the sites listed in the <b>-o</b> command line argument). -Applications can structure the details of this in different ways, but -ex_repquote creates a user-level thread to listen on its socket, plus -a thread to loop and handle messages on each socket, in addition to the -threads needed to manage the user interface, update the database on the -master, and read from the database on the client (in other words, in -addition to the normal functionality of any database application). -<p>Once the initial threads have all been started and the communications -infrastructure is initialized, the application signals that it is ready -for replication and joins a replication group by calling -<a href="../../api_c/rep_start.html">DB_ENV->rep_start</a>: -<pre><p><blockquote>if (whoami == MASTER) { - if ((ret = dbenv->rep_start(dbenv, NULL, DB_REP_MASTER)) != 0) { - /* Complain and exit on error. */ - } - /* Go run the master application code. */ -} else { - memset(&local, 0, sizeof(local)); - local.data = myaddr; - local.size = strlen(myaddr) + 1; - if ((ret = - dbenv->rep_start(dbenv, &local, DB_REP_CLIENT)) != 0) { - /* Complain and exit on error. */ - } - /* Sleep to give ourselves a minute to find a master. */ - sleep(5); - /* Go run the client application code. */ -}</blockquote></pre> -<p>Note the use of the optional second argument to <a href="../../api_c/rep_start.html">DB_ENV->rep_start</a> in -the client initialization code. The argument "myaddr" is a piece of -data, opaque to Berkeley DB, that will be broadcast to each member of a -replication group; it allows new clients to join a replication group, -without knowing the location of all its members; the new client will -be contacted by the members it does not know about, who will receive -the new client's contact information that was specified in "myaddr." -See <a href="../../ref/rep/newsite.html">Connecting to a new site</a> for more -information. -<p>The final piece of a replicated application is the code that loops, -receives, and processes messages from a given remote environment. -ex_repquote runs one of these loops in a parallel thread for each socket -connection; other applications may want to queue messages somehow and -process them asynchronously, or select() on a number of sockets and -either look up the correct environment ID for each or encapsulate the -ID in the communications protocol. The details may thus vary from -application to application, but in ex_repquote the message-handling loop -is as follows (code fragment from the hm_loop function, found in -<b>ex_repquote/ex_rq_util.c</b>): -<pre><p><blockquote>DB_ENV *dbenv; -DBT rec, control; /* Structures encapsulating a received message. */ -elect_args *ea; /* Parameters to the elect thread. */ -machtab_t *tab; /* The environment ID to fd mapping table. */ -pthread_t elect_thr; /* Election thread spawned. */ -repsite_t self; /* My host and port identification. */ -int eid; /* Environment from whom I am receiving messages. */ -int fd; /* FD on which I am receiving messages. */ -int master_eid; /* Global indicating the current master eid. */ -int n; /* Number of sites; obtained from machtab_parm. */ -int newm; /* New master EID. */ -int open; /* Boolean indicating if connection already exists. */ -int pri; /* My priority. */ -int r, ret; /* Return values. */ -int timeout; /* My election timeout value. */ -int tmpid; /* Used to call dbenv->rep_process_message. */ -char *c; /* Temp used in parsing host:port names. */ -char *myaddr; /* My host/port address. */ -char *progname; /* Program name for error messages. */ -void *status; /* Pthread return status. */ -for (ret = 0; ret == 0;) { - if ((ret = get_next_message(fd, &rec, &control)) != 0) { - /* - * There was some sort of network error; close this - * connection and remove it from the table of - * environment IDs. - */ - close(fd); - if ((ret = machtab_rem(tab, eid, 1)) != 0) - break; -<p> - /* - * If I'm the master, I just lost a client and this - * thread is done. - */ - if (master_eid == SELF_EID) - break; -<p> - /* - * If I was talking with the master and the master - * went away, I need to call an election; else I'm - * done. - */ - if (master_eid != eid) - break; -<p> - master_eid = DB_EID_INVALID; - /* - * In ex_repquote, the environment ID table stores - * election parameters. - */ - machtab_parm(tab, &n, &pri, &timeout); - if ((ret = dbenv->rep_elect(dbenv, - n, pri, timeout, &newm)) != 0) - continue; -<p> - /* - * If I won the election, become the master. - * Otherwise, just exit. - */ - if (newm == SELF_EID && (ret = - dbenv->rep_start(dbenv, NULL, DB_REP_MASTER)) == 0) - ret = domaster(dbenv, progname); - break; - } -<p> - /* If we get here, we have a message to process. */ -<p> - tmpid = eid; - switch(r = dbenv->rep_process_message(dbenv, - &control, &rec, &tmpid)) { - case DB_REP_NEWSITE: - /* - * Check if we got sent connect information and if we - * did, if this is me or if we already have a - * connection to this new site. If we don't, - * establish a new one. - */ -<p> - /* No connect info. */ - if (rec.size == 0) - break; -<p> - /* It's me, do nothing. */ - if (strncmp(myaddr, rec.data, rec.size) == 0) - break; -<p> - self.host = (char *)rec.data; - self.host = strtok(self.host, ":"); - if ((c = strtok(NULL, ":")) == NULL) { - dbenv->errx(dbenv, "Bad host specification"); - goto err; - } - self.port = atoi(c); -<p> - /* - * We try to connect to the new site. If we can't, - * we treat it as an error since we know that the site - * should be up if we got a message from it (even - * indirectly). - */ - if ((ret = connect_site(dbenv, - tab, progname, &self, &open, &eid)) != 0) - goto err; - break; - case DB_REP_HOLDELECTION: - if (master_eid == SELF_EID) - break; - /* Make sure that previous election has finished. */ - if (ea != NULL) { - (void)pthread_join(elect_thr, &status); - ea = NULL; - } - if ((ea = calloc(sizeof(elect_args), 1)) == NULL) { - ret = errno; - goto err; - } - ea->dbenv = dbenv; - ea->machtab = tab; - ret = pthread_create(&elect_thr, - NULL, elect_thread, (void *)ea); - break; - case DB_REP_NEWMASTER: - /* Check if it's us. */ - master_eid = tmpid; - if (tmpid == SELF_EID) { - if ((ret = dbenv->rep_start(dbenv, - NULL, DB_REP_MASTER)) != 0) - goto err; - ret = domaster(dbenv, progname); - } - break; - case 0: - break; - default: - dbenv->err(dbenv, r, "DBENV->rep_process_message"); - break; - } -}</blockquote></pre> -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/rep/ex_comm.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/xa/intro.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/libdb/docs/ref/rep/faq.html b/libdb/docs/ref/rep/faq.html deleted file mode 100644 index cb2941534..000000000 --- a/libdb/docs/ref/rep/faq.html +++ /dev/null @@ -1,105 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Replication FAQ</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Berkeley DB Replication</dl></h3></td> -<td align=right><a href="../../ref/rep/partition.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/rep/ex.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Replication FAQ</h1> -<p><ol> -<p><li><b>Does Berkeley DB provide support for forwarding write queries from -clients to masters?</b> -<p>No, it does not. The Berkeley DB RPC server code could be modified to support -this functionality, but in general this protocol is left entirely to -the application. Note, there is no reason not to use the communications -channels the application establishes for replication support to forward -database update messages to the master, Berkeley DB does not require that -those channels be used exclusively for replication messages. -<p><li><b>Can I use replication to partition my environment across -multiple sites?</b> -<p>No, this is not possible. All replicated databases must be equally -shared by all environments in the replication group. -<p><li><b>How can I distinguish Berkeley DB messages from application messages?</b> -<p>There is no way to distinguish Berkeley DB messages from application-specific -messages, nor does Berkeley DB offer any way to wrap application messages -inside of Berkeley DB messages. Distributed applications exchanging their -own messages should either enclose Berkeley DB messages in their own wrappers, -or use separate network connections to send and receive Berkeley DB messages. -The one exception to this rule is connection information for new sites; -Berkeley DB offers a simple method for sites joining replication groups to -send connection information to the other database environments in the -group (see <a href="../../ref/rep/newsite.html">Connecting to a new site</a> -for more information). -<p><li><b>How should I build my <b>send</b> function?</b> -<p>This depends on the specifics of the application. One common way is to -write the <b>rec</b> and <b>control</b> arguments' sizes and data to -a socket connected to each remote site. On a fast, local area net, the -simplest method is likely to be construct broadcast messages. Each -Berkeley DB message would be encapsulated inside an application specific -message, with header information specifying the intended recipient(s) -for the message. This will likely require a global numbering scheme, -however, as the Berkeley DB library has to be able to send specific log -records to clients apart from the general broadcast of new log records -intended for all members of a replication group. -<p><li><b>Does every one of my threads of control on the master have to -set up its own connection to every client? And, does every one of my -threads of control on the client have to set up its own connection to -every master?</b> -<p>This is not always necessary. In the Berkeley DB replication model, any -thread of control which modifies a database in the master environment -must be prepared to send a message to the client environments, and any -thread of control which delivers a message to a client environment must -be prepared to send a message to the master. There are many ways in -which these requirements can be satisfied. -<p>The simplest case is probably a single, multithreaded process running -on the master and clients. The process running on the master would -require a single write connection to each client and a single read -connection from each client. A process running on each client would -require a single read connection from the master and a single write -connection to the master. Threads running in these processes on the -master and clients would use the same network connections to pass -messages back and forth. -<p>A common complication is when there are multiple processes running on -the master and clients. A straight-forward solution is to increase the -numbers of connections on the master -- each process running on the -master has its own write connection to each client. However, this -requires only one additional connection for each possible client in the -master process. The master environment still requires only a single -read connection from each client (this can be done by allocating a -separate thread of control which does nothing other than receive client -messages and forward them into the database). Similarly, each client -still only requires a single thread of control that receives master -messages and forwards them into the database, and which also takes -database messages and forwards them back to the master. This model -requires the networking infrastructure support many-to-one -writers-to-readers, of course. -<p>If the number of network connections is a problem in the multiprocess -model, and inter-process communication on the system is inexpensive -enough, an alternative is have a single process which communicates -between the master the each client, and whenever a process' -<b>send</b> function is called, the process passes the message to the -communications process which is responsible for forwarding the message -to the appropriate client. Alternatively, a broadcast mechanism will -simplify the entire networking infrastructure, as processes will likely -no longer have to maintain their own specific network connections. -<p><li><b>Can I use replication to replicate just the database -environment's log files?</b> -<p>Yes. If the <a href="../../api_c/rep_start.html#DB_REP_LOGSONLY">DB_REP_LOGSONLY</a> flag is specified to -<a href="../../api_c/rep_start.html">DB_ENV->rep_start</a>, the client site acts as a repository for logfiles -(see <a href="../../ref/rep/logonly.html">Log file only clients</a> for more -information). -</ol> -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/rep/partition.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/rep/ex.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/libdb/docs/ref/rep/id.html b/libdb/docs/ref/rep/id.html deleted file mode 100644 index eb4beed20..000000000 --- a/libdb/docs/ref/rep/id.html +++ /dev/null @@ -1,45 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Replication environment IDs</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Berkeley DB Replication</dl></h3></td> -<td align=right><a href="../../ref/rep/intro.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/rep/pri.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Replication environment IDs</h1> -<p>Each database environment included in a replication group must have a -unique identifier for itself and for the other members of the -replication group. The identifiers do not need to be global, that is, -each database environment can assign local identifiers to members of -the replication group as it encounters them. For example, given three -sites: A, B and C, site A might assign the identifiers 1 and 2 to sites -B and C respectively, while site B might assign the identifiers 301 and -302 to sites A and C respectively. Note that it is not wrong to have -global identifiers, it is just not a requirement. -<p>It is the responsibility of the application to label each incoming -replication message passed to <a href="../../api_c/rep_message.html">DB_ENV->rep_process_message</a> method with the appropriate -identifier. Subsequently, Berkeley DB will label outgoing messages to the -<b>send</b> interface with those same identifiers. -<p>Negative identifiers are reserved for use by Berkeley DB, and should never be -assigned to environments by the application. Two of these reserved -identifiers are intended for application use, as follows: -<p><dl compact> -<p><dt><a href="../../api_c/rep_transport.html#DB_EID_BROADCAST">DB_EID_BROADCAST</a><dd>The <a href="../../api_c/rep_transport.html#DB_EID_BROADCAST">DB_EID_BROADCAST</a> identifier indicates a message should be -broadcast to all members of a replication group. -<p><dt><a href="../../api_c/rep_transport.html#DB_EID_INVALID">DB_EID_INVALID</a><dd>The <a href="../../api_c/rep_transport.html#DB_EID_INVALID">DB_EID_INVALID</a> identifier is an invalid environment ID, and -may be used to initialize environment ID variables that are subsequently -checked for validity. -</dl> -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/rep/intro.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/rep/pri.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/libdb/docs/ref/rep/init.html b/libdb/docs/ref/rep/init.html deleted file mode 100644 index 63028a03a..000000000 --- a/libdb/docs/ref/rep/init.html +++ /dev/null @@ -1,47 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Initializing a new site</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Berkeley DB Replication</dl></h3></td> -<td align=right><a href="../../ref/rep/newsite.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/rep/elect.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Initializing a new site</h1> -<p>Perform the following steps to add a new site to the replication -group: -<p><ol> -<p><li>Do an archival backup of the master's environment, as described in -<a href="../../ref/transapp/archival.html">Database and log file -archival</a>. The backup can either be a conventional backup or a hot -backup. -<p><li>Copy the archival backup into a clean environment directory on the -client. -<p><li>Run catastrophic recovery on the client's new environment, as described -in <a href="../../ref/transapp/recovery.html">Recovery procedures</a>. -<p><li>Reconfigure and reopen the environment as a client member of the -replication group. -</ol> -<p>If copying the backup to the client takes a long time relative to the -frequency with which log files are reclaimed using the -<a href="../../utility/db_archive.html">db_archive</a> utility or the <a href="../../api_c/log_archive.html">DB_ENV->log_archive</a> method, it may be -necessary to suppress log reclamation until the newly restarted client -has "caught up" and applied all log records generated during its -downtime. -<p>As with any Berkeley DB application, the database environment must be in a -consistent state at application startup. This is most easily assured -by running recovery at startup time in one thread or process; it is -harmless to do this on both clients and masters even when not strictly -necessary. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/rep/newsite.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/rep/elect.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/libdb/docs/ref/rep/intro.html b/libdb/docs/ref/rep/intro.html deleted file mode 100644 index 671544188..000000000 --- a/libdb/docs/ref/rep/intro.html +++ /dev/null @@ -1,73 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Introduction</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Berkeley DB Replication</dl></h3></td> -<td align=right><a href="../../ref/transapp/faq.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/rep/id.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Introduction</h1> -<p>Berkeley DB includes support for building highly available applications based -on replication. Berkeley DB replication groups consist of some number of -independently configured database environments. There is a single -<i>master</i> database environment and one or more <i>client</i> -database environments. Master environments support both database reads -and writes; client environments support only database reads. If the -master environment fails, applications may upgrade a client to be the -new master. The database environments might be on separate computers, -on separate hardware partitions in a non-uniform memory access (NUMA) -system, or on separate disks in a single server. As always with Berkeley DB -environments, any number of concurrent processes or threads may access -a database environment. In the case of a master environment, any number -of threads of control may read and write the environment, and in the -case of a client environment, any number of threads of control may read -the environment. -<p>Applications may be written to provide various degrees of consistency -between the master and clients. The system can be run synchronously -such that replicas are guaranteed to be up-to-date with all committed -transactions, but doing so may incur a significant performance penalty. -Higher performance solutions sacrifice total consistency, allowing the -clients to be out of date for an application-controlled amount of time. -<p>While Berkeley DB includes the database infrastructure necessary to construct -highly available database environments, applications must still provide -some critical components: -<p><ol> -<p><li>The application is responsible for providing the communication -infrastructure. Applications may use whatever wire protocol is -appropriate for their application (for example, RPC, TCP/IP, UDP, VI or -message-passing over the backplane). -<p><li>The application is responsible for naming. Berkeley DB refers to the members -of a replication group using an application-provided ID, and -applications must map that ID to a particular database environment or -communication channel. -<p><li>The application is responsible for monitoring the status of the master -and clients, and identifying any unavailable database environments. -<p><li>The application must provide whatever security policies are needed. -For example, the application may choose to encrypt data, use a secure -socket layer, or do nothing at all. The level of security is left to -the sole discretion of the application. -</ol> -<!--$Id$--> -<p><table border=1 align=center> -<tr><th>Replication and Related Methods</th><th>Description</th></tr> -<tr><td><a href="../../api_c/rep_transport.html">DB_ENV->set_rep_transport</a></td><td>Configure replication transport</td></tr> -<tr><td><a href="../../api_c/rep_elect.html">DB_ENV->rep_elect</a></td><td>Hold a replication election</td></tr> -<tr><td><a href="../../api_c/rep_limit.html">DB_ENV->set_rep_limit</a></td><td>Limit data sent in response to a single message</td></tr> -<tr><td><a href="../../api_c/rep_message.html">DB_ENV->rep_process_message</a></td><td>Process a replication message</td></tr> -<tr><td><a href="../../api_c/rep_start.html">DB_ENV->rep_start</a></td><td>Configure an environment for replication</td></tr> -<tr><td><a href="../../api_c/rep_stat.html">DB_ENV->rep_stat</a></td><td>Replication statistics</td></tr> -</table> -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/transapp/faq.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/rep/id.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/libdb/docs/ref/rep/logonly.html b/libdb/docs/ref/rep/logonly.html deleted file mode 100644 index 45e06ebb2..000000000 --- a/libdb/docs/ref/rep/logonly.html +++ /dev/null @@ -1,58 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Log file only clients</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Berkeley DB Replication</dl></h3></td> -<td align=right><a href="../../ref/rep/elect.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/rep/trans.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Log file only clients</h1> -<p>Applications wanting to use replication to support recovery after -catastrophic failure of the master may want to configure a site as a -logs-file-only replica. Such clients cannot respond to read (or write) -queries but they still receive a complete copy the log files, so that in the -event of master failure, a copy of the logs is available. -<p>Log file only clients are configured like other client sites, except -they should specify the <a href="../../api_c/rep_start.html#DB_REP_LOGSONLY">DB_REP_LOGSONLY</a> flag to the -<a href="../../api_c/rep_start.html">DB_ENV->rep_start</a> method and should specify a priority of 0 to the -<a href="../../api_c/rep_elect.html">DB_ENV->rep_elect</a> method. -<p>There are two ways to recover using a log-file-only replica. -The simplest way is to copy the log files from the log-file-only -replica onto another site (either master or replica) and run catastrophic -recovery there. If that is not an option, then -recovery must be run on the log-file-only replica, using the log files -that have accumulated there. -If the log files are entirely -self-contained, that is, they start with log file number 1, then a log -replica can simply run catastrophic recovery. Obviously, if there are -a large number of log files in this case, recovery may take a long time. -If the log files are not self-contained, an archival copy of the -databases must first be restored onto the replica before running -catastrophic recovery. In the latter case (that is, running recovery -on the log-file-only replica), once the site returns to being a log-file-only -replica, the database files on the log-file-only replica should be removed, -and if the log files do not begin with log file number 1, -a new set of archival databases should be created from -the current master. -<p>More specifically, the log files accumulating on the log-file-only -replica can take the place of the log files described in -<i>catastrophic recovery</i> section of the -<a href="../../ref/transapp/recovery.html">Recovery procedures</a> Berkeley DB -Reference Guide. -<p>In all other ways, a log-file-only site behaves as other replication -clients do. It should have a thread or process receiving messages and -passing them to <a href="../../api_c/rep_message.html">DB_ENV->rep_process_message</a> and must respond to all returns -described for that interface. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/rep/elect.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/rep/trans.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/libdb/docs/ref/rep/newsite.html b/libdb/docs/ref/rep/newsite.html deleted file mode 100644 index d61645877..000000000 --- a/libdb/docs/ref/rep/newsite.html +++ /dev/null @@ -1,44 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Connecting to a new site</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Berkeley DB Replication</dl></h3></td> -<td align=right><a href="../../ref/rep/comm.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/rep/init.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Connecting to a new site</h1> -<p>Connecting to a new site in the replication group happens whenever the -<a href="../../api_c/rep_message.html">DB_ENV->rep_process_message</a> method returns <a href="../../api_c/rep_message.html#DB_REP_NEWSITE">DB_REP_NEWSITE</a>. The application -should assign the new site a local environment ID number, and all future -messages from the site passed to <a href="../../api_c/rep_message.html">DB_ENV->rep_process_message</a> should include that -environment ID number. It is possible, of course, for the application -to be aware of a new site before the return of <a href="../../api_c/rep_message.html">DB_ENV->rep_process_message</a> (for -example, applications using connection-oriented protocols are likely to -detect new sites immediately, while applications using broadcast -protocols may not). -<p>Regardless, in applications supporting the dynamic addition of database -environments to replication groups, environments joining an existing -replication group may need to provide contact information. (For -example, in an application using TCP/IP sockets, a DNS name or IP -address might be a reasonable value to provide.) This can be done using -the <b>cdata</b> parameter to the <a href="../../api_c/rep_start.html">DB_ENV->rep_start</a> method. The information -referenced by <b>cdata</b> is wrapped in the initial contact message -sent by the new environment, and is provided to the existing members of -the group using the <b>rec</b> parameter returned by <a href="../../api_c/rep_message.html">DB_ENV->rep_process_message</a>. -If no additional information was provided for Berkeley DB to forward to the -existing members of the group, the <b>data</b> field of the <b>rec</b> -parameter passed to the <a href="../../api_c/rep_message.html">DB_ENV->rep_process_message</a> method will be NULL after -<a href="../../api_c/rep_message.html">DB_ENV->rep_process_message</a> returns <a href="../../api_c/rep_message.html#DB_REP_NEWSITE">DB_REP_NEWSITE</a>. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/rep/comm.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/rep/init.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/libdb/docs/ref/rep/partition.html b/libdb/docs/ref/rep/partition.html deleted file mode 100644 index a89f5c1c8..000000000 --- a/libdb/docs/ref/rep/partition.html +++ /dev/null @@ -1,90 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Network partitions</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Berkeley DB Replication</dl></h3></td> -<td align=right><a href="../../ref/rep/trans.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/rep/faq.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Network partitions</h1> -<p>The Berkeley DB replication implementation can be affected by network -partitioning problems. -<p>For example, consider a replication group with N members. The network -partitions with the master on one side and more than N/2 of the sites -on the other side. The sites on the side with the master will continue -forward, and the master will continue to accept write queries for the -databases. Unfortunately, the sites on the other side of the partition, -realizing they no longer have a master, will hold an election. The -election will succeed as there are more than N/2 of the total sites -participating, and there will then be two masters for the replication -group. Since both masters are potentially accepting write queries, the -databases could diverge in incompatible ways. -<p>If multiple masters are ever found to exist in a replication group, a -master detecting the problem will return <a href="../../api_c/rep_message.html#DB_REP_DUPMASTER">DB_REP_DUPMASTER</a>. If -the application sees this return, it should reconfigure itself as a -client (by calling <a href="../../api_c/rep_start.html">DB_ENV->rep_start</a>), and then call for an election -(by calling <a href="../../api_c/rep_elect.html">DB_ENV->rep_elect</a>). The site that wins the election may be -one of the two previous masters, or it may be another site entirely. -Regardless, the winning system will bring all of the other systems into -conformance. -<p>As another example, consider a replication group with a master -environment and two clients A and B, where client A may upgrade to -master status and client B cannot. Then, assume client A is partitioned -from the other two database environments, and it becomes out-of-date -with respect to the master. Then, assume the master crashes and does -not come back on-line. Subsequently, the network partition is restored, -and clients A and B hold an election. As client B cannot win the -election, client A will win by default, and in order to get back into -sync with client B, possibly committed transactions on client B will be -unrolled until the two sites can once again move forward together. -<p>In both of these examples, there is a phase where a newly elected master -brings the members of a replication group into conformance with itself -so that it can start sending new information to them. This can result -in the loss of information as previously committed transactions are -unrolled. -<p>In architectures where network partitions are an issue, applications -may want to implement a heart-beat protocol to minimize the consequences -of a bad network partition. As long as a master is able to contact at -least half of the sites in the replication group, it is impossible for -there to be two masters. If the master can no longer contact a -sufficient number of systems, it should reconfigure itself as a client, -and hold an election. -<p>There is another tool applications can use to minimize the damage in -the case of a network partition. By specifying a <b>nsites</b> -argument to <a href="../../api_c/rep_elect.html">DB_ENV->rep_elect</a> that is larger than the actual number of -database environments in the replication group, applications can keep -systems from declaring themselves the master unless they can talk to at -a large percentage of the sites in the system. For example, if there -are 20 database environments in the replication group, and an argument -of 30 is specified to the <a href="../../api_c/rep_elect.html">DB_ENV->rep_elect</a> method, then a system will have -to be able to talk to at least 16 of the sites to declare itself the -master. -<p>Specifying a <b>nsites</b> argument to <a href="../../api_c/rep_elect.html">DB_ENV->rep_elect</a> that is -smaller than the actual number of database environments in the -replication group has its uses as well. For example, consider a -replication group with 2 environments. If they are partitioned from -each other, neither of the sites could ever get enough votes to become -the master. A reasonable alternative would be to specify a -<b>nsites</b> argument of 2 to one of the systems and a <b>nsites</b> -argument of 1 to the other. That way, one of the systems could win -elections even when partitioned, while the other one could not. This -would allow at one of the systems to continue accepting write queries -after the partition. -<p>These scenarios stress the importance of good network infrastructure in -Berkeley DB replicated environments. When replicating database environments -over sufficiently lossy networking, the best solution may well be to -pick a single master, and only hold elections when human intervention -has determined the selected master is unable to recover at all. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/rep/trans.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/rep/faq.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/libdb/docs/ref/rep/pri.html b/libdb/docs/ref/rep/pri.html deleted file mode 100644 index c40d14396..000000000 --- a/libdb/docs/ref/rep/pri.html +++ /dev/null @@ -1,35 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Replication environment priorities</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Berkeley DB Replication</dl></h3></td> -<td align=right><a href="../../ref/rep/id.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/rep/app.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Replication environment priorities</h1> -<p>Each database environment included in a replication group must have a -priority, which specifies a relative ordering among the different -environments in a replication group. This ordering determines which -environment will be selected as a new master in case the existing master -fails. -<p>Priorities must be a non-negative integer, but do not need to be unique -throughout the replication group. A priority of 0 means the system can -never become a master, regardless. Otherwise, larger valued priorities -indicate a more desirable master. For example, if a replication group -consists of three database environments, two of which are connected by -an OC3 and the third of which is connected by a T1, the third database -environment should be assigned a priority value which is lower than -either of the other two. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/rep/id.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/rep/app.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/libdb/docs/ref/rep/trans.html b/libdb/docs/ref/rep/trans.html deleted file mode 100644 index f59d57f59..000000000 --- a/libdb/docs/ref/rep/trans.html +++ /dev/null @@ -1,104 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Transactional guarantees</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Berkeley DB Replication</dl></h3></td> -<td align=right><a href="../../ref/rep/logonly.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/rep/partition.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Transactional guarantees</h1> -<p>It is important to consider replication in the context of the overall -database environment's transactional guarantees. To briefly review, -transactional guarantees in a non-replicated application are based on -the writing of log file records to "stable storage", usually a disk -drive. If the application or system then fails, the Berkeley DB logging -information is reviewed during recovery, and the databases are updated -so that all changes made as part of committed transactions appear, and -all changes made as part of uncommitted transactions do not appear. In -this case, no information will have been lost. -<p>If a database environment does not require that the log be flushed to -stable storage on transaction commit (using the <a href="../../api_c/env_set_flags.html#DB_TXN_NOSYNC">DB_TXN_NOSYNC</a> -flag to increase performance at the cost of sacrificing transactional -durability), Berkeley DB recovery will only be able to restore the system to -the state of the last commit found on stable storage. In this case, -information may have been lost (for example, the changes made by some -committed transactions may not appear in the databases after recovery). -<p>Further, if there is database or log file loss or corruption (for -example, if a disk drive fails), then catastrophic recovery is -necessary, and Berkeley DB recovery will only be able to restore the system -to the state of the last archived log file. In this case, information -may also have been lost. -<p>Replicating the database environment extends this model, by adding a -new component to "stable storage": the client's replicated information. -If a database environment is replicated, there is no lost information -in the case of database or log file loss, because the replicated system -can be configured to contain a complete set of databases and log records -up to the point of failure. A database environment that loses a disk -drive can have the drive replaced, and it can rejoin the replication -group as a client. -<p>Because of this new component of stable storage, specifying -<a href="../../api_c/env_set_flags.html#DB_TXN_NOSYNC">DB_TXN_NOSYNC</a> in a replicated environment no longer sacrifices -durability, as long as one or more clients have acknowledged receipt of -the messages sent by the master. Since network connections are often -faster than local disk writes, replication becomes a way for -applications to significantly improve their performance as well as their -reliability. -<p>The return status from the <b>send</b> interface specified to the -<a href="../../api_c/rep_transport.html">DB_ENV->set_rep_transport</a> method must be set by the application to ensure the -transactional guarantees the application wants to provide. The effect -of the <b>send</b> interface returning failure is to flush the local -database environment's log as necessary to ensure that any information -critical to database integrity is not lost. Because this flush is an -expensive operation in terms of database performance, applications will -want to avoid returning an error from the <b>send</b> interface, if at -all possible: -<p>First, there is no reason for the <b>send</b> interface to ever return -failure unless the <a href="../../api_c/rep_transport.html#DB_REP_PERMANENT">DB_REP_PERMANENT</a> flag is specified. Messages -without that flag do not make visible changes to databases, and -therefore the application's <b>send</b> interface can return success -to Berkeley DB for such messages as soon as the message has been sent or even -just copied to local memory. -<p>Further, unless the master's database environment has been configured -to not synchronously flush the log on transaction commit, there is no -reason for the <b>send</b> interface to ever return failure, as any -information critical to database integrity has already been flushed to -the local log before <b>send</b> was called. Again, the <b>send</b> -interface should return success to Berkeley DB as soon as possible. However, -in this case, in order to avoid potential loss of information after the -master database environment fails, the master database environment -should be recovered before holding an election, as only the master -database environment is guaranteed to have the most up-to-date logs. -<p>To sum up, the only reason for the <b>send</b> interface to return -failure is when the master database environment has been configured to -not synchronously flush the log on transaction commit, the -<a href="../../api_c/rep_transport.html#DB_REP_PERMANENT">DB_REP_PERMANENT</a> flag is specified for the message, and the -<b>send</b> interface was unable to determine that some number of -clients have received the current message (and all messages preceding -the current message). How many clients should receive the message -before the <b>send</b> interface can return success is an application -choice (and may not depend as much on a specific number of clients -reporting success as one or more geographically distributed clients). -<p>Of course, it is important to ensure that the replicated master and -client environments are truly independent of each other. For example, -it does not help matters that a client has acknowledged receipt of a -message if both master and clients are on the same power supply, as the -failure of the power supply will still potentially lose information. -<p>Finally, the Berkeley DB replication implementation has one other additional -feature to increase application reliability. Replication in Berkeley DB is -implemented to perform database updates using a different code path than -the standard ones. This means operations which manage to crash the -replication master due to a software bug will not necessarily also crash -replication clients. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/rep/logonly.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/rep/partition.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/libdb/docs/ref/rpc/client.html b/libdb/docs/ref/rpc/client.html deleted file mode 100644 index fed24a0a7..000000000 --- a/libdb/docs/ref/rpc/client.html +++ /dev/null @@ -1,84 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Client program</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>RPC Client/Server</dl></h3></td> -<td align=right><a href="../../ref/rpc/intro.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/rpc/server.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Client program</h1> -<p>Changing a Berkeley DB application to remotely call a server program requires -only a few changes on the client side: -<p><ol> -<p><li>The client application must create and use a Berkeley DB environment; that -is, it cannot simply call the <a href="../../api_c/db_create.html">db_create</a> interface, but must -first call the <a href="../../api_c/env_create.html">db_env_create</a> interface to create an environment -in which the database will live. -<p><li>The client application must call <a href="../../api_c/env_create.html">db_env_create</a> using the -<a href="../../api_c/env_create.html#DB_CLIENT">DB_CLIENT</a> flag. -<p><li>The client application must call the additional <a href="../../api_c/env_class.html">DB_ENV</a> method -<a href="../../api_c/env_set_rpc_server.html">DB_ENV->set_rpc_server</a> to specify the database server. This call must -be made before opening the environment with the <a href="../../api_c/env_open.html">DB_ENV->open</a> -call. -</ol> -<p>The client application provides a few pieces of information to Berkeley DB as -part of the <a href="../../api_c/env_set_rpc_server.html">DB_ENV->set_rpc_server</a> call: -<p><ol> -<p><li>A client structure. Applications wishing to control their own client -structures can pass one in, and Berkeley DB will use it to connect to the -server. Most applications will not make use of this argument and should pass -in NULL. If this argument is used, the hostname and client timeout -arguments are ignored. Applications using this mechanism must -create their client structures using DB_RPC_SERVERPROG as the program -number and DB_RPC_SERVERVERS as the version number. -<p><li>The hostname of the server. The hostname format is not specified by -Berkeley DB, but must be in a format acceptable to the local network support --- specifically, the RPC clnt_create interface. -<p><li>The client -timeout. This is the number of seconds the client will wait for the -server to respond to its requests. A default is used if this value is -zero. -<p><li>The server timeout. This is the number of seconds the server will allow -client resources to remain idle before releasing those resources. The -resources this applies to are transactions and cursors because those -objects hold locks; and if a client dies, the server needs to release -those resources in a timely manner. This value is really a hint to the -server because the server may choose to override this value with its -own. -</ol> -<p>The only other item of interest to the client is the home directory -that is given to the <a href="../../api_c/env_open.html">DB_ENV->open</a> call. -The server is started with a list of allowed home directories. -The client must use one of those names (where a name is the last -component of the home directory). This allows the pathname structure -on the server to change without client applications needing to be -aware of it. -<p>Once the <a href="../../api_c/env_set_rpc_server.html">DB_ENV->set_rpc_server</a> call has been made, the client is -connected to the server, and all subsequent Berkeley DB -operations will be forwarded to the server. The client does not need to -be otherwise aware that it is using a database server rather than -accessing the database locally. -<p>It is important to realize that the client portion of the Berkeley DB library -acts as a simple conduit, forwarding Berkeley DB interface arguments to the -server without interpretation. This has two important implications. -First, all pathnames must be specified relative to the server. For -example, the home directory and other configuration information passed -by the application when creating its environment or databases must be -pathnames for the server, not the client system. In addition, because -there is no logical bundling of operations at the server, performance -is usually significantly less than when Berkeley DB is embedded within the -client's address space, even if the RPC is to a local address. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/rpc/intro.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/rpc/server.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/libdb/docs/ref/rpc/faq.html b/libdb/docs/ref/rpc/faq.html deleted file mode 100644 index 75f3267ba..000000000 --- a/libdb/docs/ref/rpc/faq.html +++ /dev/null @@ -1,32 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: RPC FAQ</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>RPC Client/Server</dl></h3></td> -<td align=right><a href="../../ref/rpc/server.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/java/conf.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>RPC FAQ</h1> -<p><ol> -<p><li><b>I get the <a href="../../api_c/env_set_rpc_server.html#DB_NOSERVER">DB_NOSERVER</a> error back from a -<a href="../../api_c/env_set_rpc_server.html">DB_ENV->set_rpc_server</a> call that is using the default client -timeout value.</b> -<p>Some systems have a default RPC client timeout value that is too small, -and the client times out the request before the server has a chance to -process and reply. If you get this error, try explicitly setting the -client timeout value. -</ol> -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/rpc/server.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/java/conf.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/libdb/docs/ref/rpc/intro.html b/libdb/docs/ref/rpc/intro.html deleted file mode 100644 index d6460baf9..000000000 --- a/libdb/docs/ref/rpc/intro.html +++ /dev/null @@ -1,80 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Introduction</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>RPC Client/Server</dl></h3></td> -<td align=right><a href="../../ref/txn/limits.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/rpc/client.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Introduction</h1> -<p>Berkeley DB includes an implementation of a client-server protocol using Sun -Microsystem's Remote Procedure Call Protocol. RPC support is -available only for UNIX systems, and is not included in the Berkeley DB library by -default, but must be enabled during configuration. See -<a href="../../ref/build_unix/conf.html">Configuring Berkeley DB</a> for more -information. For more information on RPC itself, see your UNIX system -documentation or <i>RPC: Remote Procedure Call Protocol -Specification, RFC1831, Sun Microsystems, Inc., USC-ISI</i>. -<p>Only some of the complete Berkeley DB functionality is available when using RPC. -The following functionality is available: -<p><ol> -<li>The <a href="../../api_c/env_create.html">db_env_create</a> interface and the <a href="../../api_c/env_class.html">DB_ENV</a> handle -methods. -<li>The <a href="../../api_c/db_create.html">db_create</a> interface and the <a href="../../api_c/db_class.html">DB</a> handle methods. -<li>The <a href="../../api_c/txn_begin.html">DB_ENV->txn_begin</a>, <a href="../../api_c/txn_commit.html">DB_TXN->commit</a>, and <a href="../../api_c/txn_abort.html">DB_TXN->abort</a> -interfaces. -</ol> -<p>The <a href="../../api_c/env_open.html#DB_THREAD">DB_THREAD</a> flag to the <a href="../../api_c/env_open.html">DB_ENV->open</a> and <a href="../../api_c/db_open.html">DB->open</a> methods -may not be specified, that is, <a href="../../api_c/env_class.html">DB_ENV</a> and <a href="../../api_c/db_class.html">DB</a> handles used -in RPC clients are not free-threaded. -<p>The RPC client/server code does not support any of the user-defined -comparison or allocation functions; for example, an application using -the RPC support may not specify its own Btree comparison function. If -your application requires only those portions of Berkeley DB, then using RPC -is fairly simple. If your application requires other Berkeley DB -functionality, such as direct access to locking, logging or shared -memory buffer memory pools, then your application cannot use the RPC -support. -<p>Although a client cannot specify a callback, Berkeley DB does support the -<a href="../../api_c/db_associate.html">DB->associate</a> call in a limited manner. A client program -wishing to use a secondary index may do so only in a read-only fashion. -The primary and secondary databases must have been created locally on -the server machine. Client programs must then open both the primary -and secondary databases with the <a href="../../api_c/db_open.html#DB_RDONLY">DB_RDONLY</a> flag set. The client -must also specify a NULL callback for the <a href="../../api_c/db_associate.html">DB->associate</a> call. -<p>The Berkeley DB RPC code requires that the client and server programs be -running the exact same version numbers. -The Berkeley DB RPC protocol version number is tied to the Berkeley DB major -and minor release numbers. -As such, the server program will reject requests from clients -using a different version number. -<p><b>The Berkeley DB RPC support does not provide any security or authentication of -any kind.</b> Sites needing any kind of data security measures must modify -the client and server code to provide whatever level of security they -require. -<p>One particularly interesting use of the RPC support is for debugging Berkeley DB -applications. The seamless nature of the interface means that with very -minor application code changes, an application can run outside of the -Berkeley DB address space, making it far easier to track down many types of -errors -- such as memory misuse. -<p>Using the RPC mechanisms in Berkeley DB involves two basic steps: -<p><ol> -<p><li>Modify your Berkeley DB application to act as a client and call the RPC -server. -<li>Run the <a href="../../utility/berkeley_db_svc.html">berkeley_db_svc</a> server program on the system where the -database resides. -</ol> -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/txn/limits.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/rpc/client.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/libdb/docs/ref/rpc/server.html b/libdb/docs/ref/rpc/server.html deleted file mode 100644 index f73a48d4f..000000000 --- a/libdb/docs/ref/rpc/server.html +++ /dev/null @@ -1,55 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Server program</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>RPC Client/Server</dl></h3></td> -<td align=right><a href="../../ref/rpc/client.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/rpc/faq.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Server program</h1> -<p>The Berkeley DB server utility, <a href="../../utility/berkeley_db_svc.html">berkeley_db_svc</a>, handles all the -client application requests. -<p>Currently, the <a href="../../utility/berkeley_db_svc.html">berkeley_db_svc</a> utility is single-threaded, -limiting the number of requests that it can handle. Modifying the -server implementation to run in multithread or multiprocess mode -requires modification of the server code automatically generated by the -rpcgen program. -<p>There are two different types of timeouts used by <a href="../../utility/berkeley_db_svc.html">berkeley_db_svc</a>. -The first timeout (which can be modified within some constraints by the -client application), is the resource timeout. When clients use -transactions or cursors, those resources hold locks in Berkeley DB across calls -to the server. If a client application dies or loses its connection to -the server while holding those resources, it prevents any other client -from acquiring them. Therefore, it is important to detect that a client -has not used a resource for some period of time and release them. In the -case of transactions, the server aborts the transaction. In the case of -cursors, the server closes the cursor. -<p>The second timeout is an idle timeout. A client application may remain -idle with an open handle to an environment and a database. Doing so -simply consumes some memory; it does not hold locks. However, the Berkeley DB -server may want to eventually reclaim resources if a client dies or -remains disconnected for a long period of time, so there is a separate -idle timeout for open Berkeley DB handles. -<p>The list of home directories specified to <a href="../../utility/berkeley_db_svc.html">berkeley_db_svc</a> are -the only ones client applications are allowed to use. When -<a href="../../utility/berkeley_db_svc.html">berkeley_db_svc</a> is started, it is given a list of pathnames. -Clients are expected to specify the name of the home directory (defined -as the last component in the directory pathname) as the database -environment they are opening. In this manner, clients need to know only -the name of their home environment; not its full pathname on the server -machine. This means, of course, that only one environment of a -particular name is allowed on the server at any given time. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/rpc/client.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/rpc/faq.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/libdb/docs/ref/sendmail/intro.html b/libdb/docs/ref/sendmail/intro.html deleted file mode 100644 index 9aaacaca6..000000000 --- a/libdb/docs/ref/sendmail/intro.html +++ /dev/null @@ -1,52 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Using Berkeley DB with Sendmail</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Sendmail</dl></h3></td> -<td align=right><a href="../../ref/tcl/faq.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/dumpload/utility.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Using Berkeley DB with Sendmail</h1> -<p>If you are attempting to use Berkeley DB with Sendmail 8.8.X, you must use -Berkeley DB version 1.85 (see the Sleepycat Software web site's -<a href="http://www.sleepycat.com/historic.html">historic releases</a> -of Berkeley DB page for more information). -<p>Berkeley DB versions 2.0 and later are only supported by Sendmail versions 8.9.X -and later. -<p>Berkeley DB versions 3.0 and later are only supported by Sendmail versions -8.10.X and later. -<p>We strongly recommend that you not use Berkeley DB version 1.85. It is no longer -maintained or supported and has known bugs that can cause Sendmail to -fail. Instead, please upgrade to Sendmail version 8.9.X or later and use -a later version of Berkeley DB. For more information on using Berkeley DB with -Sendmail, please review the README and src/README files in the Sendmail -distribution. -<p>To load sendmail against Berkeley DB, add the following lines to -BuildTools/Site/site.config.m4: -<p><blockquote><pre>APPENDDEF(`confINCDIRS', `-I/usr/local/BerkeleyDB.4.1/include') -APPENDDEF(`confLIBDIRS', `-L/usr/local/BerkeleyDB.4.1/lib')</pre></blockquote> -<p>where those are the paths to #include <db.h> and libdb.a respectively. -Then, run "Build -c" from the src directory. -<p>Note that this Build script will use -DNEWDB on the compiles -and -L/path/to/libdb/directory -ldb on the link if it can find libdb.a; -the search path is $LIBDIRS:/lib:/usr/lib:/usr/shlib. $LIBDIRS is -NULL by default for most systems, but some set it in BuildTools/OS/foo. -Anyone can append to it as above (confLIBDIRS is the m4 variable name; -LIBDIRS is the shell-script variable name). -<p>To download Sendmail, or to obtain more information on Sendmail, see the -<a href="http://www.sendmail.org">Sendmail home page</a>, which includes -FAQ pages and problem addresses. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/tcl/faq.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/dumpload/utility.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/libdb/docs/ref/simple_tut/close.html b/libdb/docs/ref/simple_tut/close.html deleted file mode 100644 index dc0bf4470..000000000 --- a/libdb/docs/ref/simple_tut/close.html +++ /dev/null @@ -1,102 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<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> -<table width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Simple Tutorial</dl></h3></td> -<td align=right><a href="../../ref/simple_tut/del.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/am_conf/intro.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Closing a database</h1> -<p>The only other operation that we need for our simple example is closing -the database, and cleaning up the DB handle. -<p>It is necessary that the database be closed. The most important reason -for this is that Berkeley DB runs on top of an underlying buffer cache. If -the modified database pages are never explicitly flushed to disk and -the database is never closed, changes made to the database may never -make it out to disk, because they are held in the Berkeley DB cache. As the -default behavior of the close function is to flush the Berkeley DB cache, -closing the database will update the on-disk information. -<p>The <a href="../../api_c/db_close.html">DB->close</a> interface takes two arguments: -<p><dl compact> -<p><dt>db<dd>The database handle returned by <a href="../../api_c/db_create.html">db_create</a>. -<p><dt>flags<dd>Optional flags modifying the underlying behavior of the <a href="../../api_c/db_close.html">DB->close</a> -interface. -</dl> -<p>Here's what the code to call <a href="../../api_c/db_close.html">DB->close</a> looks like: -<p><blockquote><pre>#include <sys/types.h> -#include <stdio.h> -#include <db.h> -<p> -#define DATABASE "access.db" -<p> -int -main() -{ - DB *dbp; - DBT key, data; - <b>int ret, t_ret;</b> -<p> - if ((ret = db_create(&dbp, NULL, 0)) != 0) { - fprintf(stderr, "db_create: %s\n", db_strerror(ret)); - exit (1); - } - if ((ret = dbp->open(dbp, - NULL, DATABASE, NULL, DB_BTREE, DB_CREATE, 0664)) != 0) { - dbp->err(dbp, ret, "%s", DATABASE); - goto err; - } -<p> - memset(&key, 0, sizeof(key)); - memset(&data, 0, sizeof(data)); - key.data = "fruit"; - key.size = sizeof("fruit"); - data.data = "apple"; - data.size = sizeof("apple"); -<p> - if ((ret = dbp->put(dbp, NULL, &key, &data, 0)) == 0) - printf("db: %s: key stored.\n", (char *)key.data); - else { - dbp->err(dbp, ret, "DB->put"); - goto err; - } -<p> - if ((ret = dbp->get(dbp, NULL, &key, &data, 0)) == 0) - printf("db: %s: key retrieved: data was %s.\n", - (char *)key.data, (char *)data.data); - else { - dbp->err(dbp, ret, "DB->get"); - goto err; - } -<p> - if ((ret = dbp->del(dbp, NULL, &key, 0)) == 0) - printf("db: %s: key was deleted.\n", (char *)key.data); - else { - dbp->err(dbp, ret, "DB->del"); - goto err; - } -<p> - if ((ret = dbp->get(dbp, NULL, &key, &data, 0)) == 0) - printf("db: %s: key retrieved: data was %s.\n", - (char *)key.data, (char *)data.data); - else - dbp->err(dbp, ret, "DB->get"); -<p><b>err: if ((t_ret = dbp->close(dbp, 0)) != 0 && ret == 0) - ret = t_ret; </b> -<p> - exit(ret); -}</pre></blockquote> -<p>Note that we do not necessarily overwrite the <b>ret</b> variable, as it -may contain error return information from a previous Berkeley DB call. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/simple_tut/del.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/am_conf/intro.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/libdb/docs/ref/simple_tut/del.html b/libdb/docs/ref/simple_tut/del.html deleted file mode 100644 index e21b23b14..000000000 --- a/libdb/docs/ref/simple_tut/del.html +++ /dev/null @@ -1,94 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Removing elements from 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> -<table width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Simple Tutorial</dl></h3></td> -<td align=right><a href="../../ref/simple_tut/get.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/simple_tut/close.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Removing elements from a database</h1> -<p>The simplest way to remove elements from a database is the <a href="../../api_c/db_del.html">DB->del</a> -interface. -<p>The <a href="../../api_c/db_del.html">DB->del</a> interface takes four of the same five arguments that -the <a href="../../api_c/db_get.html">DB->get</a> and <a href="../../api_c/db_put.html">DB->put</a> interfaces take. The difference -is that there is no need to specify a data item, as the delete operation -is only interested in the key that you want to remove. -<p><dl compact> -<p><dt>db<dd>The database handle returned by <a href="../../api_c/db_create.html">db_create</a>. -<p><dt>txnid<dd>A transaction ID. -In our simple case, we aren't expecting to recover the database after -application or system crash, so we aren't using transactions, and will -leave this argument unspecified. -<p><dt>key<dd>The key item for the key/data pair that we want to delete from the -database. -<p><dt>flags<dd>Optional flags modifying the underlying behavior of the <a href="../../api_c/db_del.html">DB->del</a> -interface. There are currently no available flags for this interface, -so the flags argument should always be set to 0. -</dl> -<p>Here's what the code to call <a href="../../api_c/db_del.html">DB->del</a> looks like: -<p><blockquote><pre>#include <sys/types.h> -#include <stdio.h> -#include <db.h> -<p> -#define DATABASE "access.db" -<p> -int -main() -{ - DB *dbp; - DBT key, data; - int ret; -<p> - if ((ret = db_create(&dbp, NULL, 0)) != 0) { - fprintf(stderr, "db_create: %s\n", db_strerror(ret)); - exit (1); - } - if ((ret = dbp->open(dbp, - NULL, DATABASE, NULL, DB_BTREE, DB_CREATE, 0664)) != 0) { - dbp->err(dbp, ret, "%s", DATABASE); - goto err; - } -<p> - memset(&key, 0, sizeof(key)); - memset(&data, 0, sizeof(data)); - key.data = "fruit"; - key.size = sizeof("fruit"); - data.data = "apple"; - data.size = sizeof("apple"); -<p> - if ((ret = dbp->put(dbp, NULL, &key, &data, 0)) == 0) - printf("db: %s: key stored.\n", (char *)key.data); - else { - dbp->err(dbp, ret, "DB->put"); - goto err; - } -<p> - if ((ret = dbp->get(dbp, NULL, &key, &data, 0)) == 0) - printf("db: %s: key retrieved: data was %s.\n", - (char *)key.data, (char *)data.data); - else { - dbp->err(dbp, ret, "DB->get"); - goto err; - } -<p><b> if ((ret = dbp->del(dbp, NULL, &key, 0)) == 0) - printf("db: %s: key was deleted.\n", (char *)key.data); - else { - dbp->err(dbp, ret, "DB->del"); - goto err; - } -</b></pre></blockquote> -<p>After the <a href="../../api_c/db_del.html">DB->del</a> call returns, the entry to which the key -<b>fruit</b> refers has been removed from the database. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/simple_tut/get.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/simple_tut/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/libdb/docs/ref/simple_tut/errors.html b/libdb/docs/ref/simple_tut/errors.html deleted file mode 100644 index 1ff0c945a..000000000 --- a/libdb/docs/ref/simple_tut/errors.html +++ /dev/null @@ -1,47 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Error returns</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Simple Tutorial</dl></h3></td> -<td align=right><a href="../../ref/simple_tut/handles.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/simple_tut/open.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Error returns</h1> -<p>The Berkeley DB interfaces always return a value of 0 on success. If the -operation does not succeed for any reason, the return value will be -non-zero. -<p>If a system error occurred (for example, Berkeley DB ran out of disk space, -or permission to access a file was denied, or an illegal argument was -specified to one of the interfaces), Berkeley DB returns an <b>errno</b> -value. All of the possible values of <b>errno</b> are greater than -0. -<p>If the operation didn't fail due to a system error, but wasn't -successful either, Berkeley DB returns a special error value. For example, -if you tried to retrieve the data item associated with the key -<b>fruit</b>, and there was no such key/data pair in the database, -Berkeley DB would return <a href="../../ref/program/errorret.html#DB_NOTFOUND">DB_NOTFOUND</a>, a special error value that means -the requested key does not appear in the database. All of the possible -special error values are less than 0. -<p>Berkeley DB also offers programmatic support for displaying error return values. -First, 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>Second, there are two error functions, <a href="../../api_c/db_err.html">DB->err</a> and <a href="../../api_c/db_err.html">DB->errx</a>. -These functions work like the ANSI C printf interface, taking a -printf-style format string and argument list, and optionally appending -the standard error string to a message constructed from the format string -and other arguments. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/simple_tut/handles.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/simple_tut/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/libdb/docs/ref/simple_tut/example.cs b/libdb/docs/ref/simple_tut/example.cs deleted file mode 100644 index 598ba150f..000000000 --- a/libdb/docs/ref/simple_tut/example.cs +++ /dev/null @@ -1,73 +0,0 @@ -#include <sys/types.h> - -#include <stdio.h> -#include <stdlib.h> -#include <string.h> - -#include "db.h" - -#define DATABASE "access.db" - -int -main() -{ - DB *dbp; - DBT key, data; - int ret, t_ret; - - /* Create the database handle and open the underlying database. */ - if ((ret = db_create(&dbp, NULL, 0)) != 0) { - fprintf(stderr, "db_create: %s\n", db_strerror(ret)); - exit (1); - } - if ((ret = dbp->open(dbp, - NULL, DATABASE, NULL, DB_BTREE, DB_CREATE, 0664)) != 0) { - dbp->err(dbp, ret, "%s", DATABASE); - goto err; - } - - /* Initialize key/data structures. */ - memset(&key, 0, sizeof(key)); - memset(&data, 0, sizeof(data)); - key.data = "fruit"; - key.size = sizeof("fruit"); - data.data = "apple"; - data.size = sizeof("apple"); - - /* Store a key/data pair. */ - if ((ret = dbp->put(dbp, NULL, &key, &data, 0)) == 0) - printf("db: %s: key stored.\n", (char *)key.data); - else { - dbp->err(dbp, ret, "DB->put"); - goto err; - } - - /* Retrieve a key/data pair. */ - if ((ret = dbp->get(dbp, NULL, &key, &data, 0)) == 0) - printf("db: %s: key retrieved: data was %s.\n", - (char *)key.data, (char *)data.data); - else { - dbp->err(dbp, ret, "DB->get"); - goto err; - } - - /* Delete a key/data pair. */ - if ((ret = dbp->del(dbp, NULL, &key, 0)) == 0) - printf("db: %s: key was deleted.\n", (char *)key.data); - else { - dbp->err(dbp, ret, "DB->del"); - goto err; - } - - /* Retrieve a key/data pair. */ - if ((ret = dbp->get(dbp, NULL, &key, &data, 0)) == 0) - printf("db: %s: key retrieved: data was %s.\n", - (char *)key.data, (char *)data.data); - else - dbp->err(dbp, ret, "DB->get"); - -err: if ((t_ret = dbp->close(dbp, 0)) != 0 && ret == 0) - ret = t_ret; - - exit(ret); -} diff --git a/libdb/docs/ref/simple_tut/get.html b/libdb/docs/ref/simple_tut/get.html deleted file mode 100644 index 1c808850e..000000000 --- a/libdb/docs/ref/simple_tut/get.html +++ /dev/null @@ -1,98 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Retrieving elements from 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> -<table width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Simple Tutorial</dl></h3></td> -<td align=right><a href="../../ref/simple_tut/put.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/simple_tut/del.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Retrieving elements from a database</h1> -<p>The simplest way to retrieve elements from a database is the -<a href="../../api_c/db_get.html">DB->get</a> interface. -<p>The <a href="../../api_c/db_get.html">DB->get</a> interface takes the same five arguments that the -<a href="../../api_c/db_put.html">DB->put</a> interface takes: -<p><dl compact> -<p><dt>db<dd>The database handle returned by <a href="../../api_c/db_create.html">db_create</a>. -<p><dt>txnid<dd>A transaction ID. In our simple case, we aren't expecting to recover -the database after application or system crash, so we aren't using -transactions, and will leave this argument NULL. -<p><dt>key<dd>The key item for the key/data pair that we want to retrieve from the -database. -<p><dt>data<dd>The data item for the key/data pair that we want to retrieve from the -database. -<p><dt>flags<dd>Optional flags modifying the underlying behavior of the <a href="../../api_c/db_get.html">DB->get</a> -interface. -</dl> -<p>Here's what the code to call <a href="../../api_c/db_get.html">DB->get</a> looks like: -<p><blockquote><pre>#include <sys/types.h> -#include <stdio.h> -#include <db.h> -<p> -#define DATABASE "access.db" -<p> -int -main() -{ - DB *dbp; - DBT key, data; - int ret; -<p> - if ((ret = db_create(&dbp, NULL, 0)) != 0) { - fprintf(stderr, "db_create: %s\n", db_strerror(ret)); - exit (1); - } - if ((ret = dbp->open(dbp, - NULL, DATABASE, NULL, DB_BTREE, DB_CREATE, 0664)) != 0) { - dbp->err(dbp, ret, "%s", DATABASE); - goto err; - } -<p> - memset(&key, 0, sizeof(key)); - memset(&data, 0, sizeof(data)); - key.data = "fruit"; - key.size = sizeof("fruit"); - data.data = "apple"; - data.size = sizeof("apple"); -<p> - if ((ret = dbp->put(dbp, NULL, &key, &data, 0)) == 0) - printf("db: %s: key stored.\n", (char *)key.data); - else { - dbp->err(dbp, ret, "DB->put"); - goto err; - } -<p><b> if ((ret = dbp->get(dbp, NULL, &key, &data, 0)) == 0) - printf("db: %s: key retrieved: data was %s.\n", - (char *)key.data, (char *)data.data); - else { - dbp->err(dbp, ret, "DB->get"); - goto err; - } -</b></pre></blockquote> -<p>It is not usually necessary to clear the <a href="../../api_c/dbt_class.html">DBT</a> structures passed -to the Berkeley DB functions between calls. This is not always true, when -some of the less commonly used flags for <a href="../../api_c/dbt_class.html">DBT</a> structures are -used. The <a href="../../api_c/dbt_class.html">DBT</a> manual page specified the details of those cases. -<p>It is possible, of course, to distinguish between system errors and the -key/data pair simply not existing in the database. There are three -standard returns from <a href="../../api_c/db_get.html">DB->get</a>: -<p><ol> -<p><li>The call might be successful and the key found, in which case the return -value will be 0. -<li>The call might be successful, but the key not found, in which case the -return value will be <a href="../../ref/program/errorret.html#DB_NOTFOUND">DB_NOTFOUND</a>. -<li>The call might not be successful, in which case the return value will -be a system error. -</ol> -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/simple_tut/put.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/simple_tut/del.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/libdb/docs/ref/simple_tut/handles.html b/libdb/docs/ref/simple_tut/handles.html deleted file mode 100644 index c243a4a9e..000000000 --- a/libdb/docs/ref/simple_tut/handles.html +++ /dev/null @@ -1,30 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Object handles</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Simple Tutorial</dl></h3></td> -<td align=right><a href="../../ref/simple_tut/keydata.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/simple_tut/errors.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Object handles</h1> -<p>With a few minor exceptions, Berkeley DB functionality is accessed by creating -a structure and then calling functions that are fields in that structure. -This is, of course, similar to object-oriented concepts, of instances and -methods on them. For simplicity, we will often refer to these structure -fields as methods of the handle. -<p>The manual pages will show these methods as C structure references. For -example, the open-a-database method for a database handle is represented -as <a href="../../api_c/db_open.html">DB->open</a>. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/simple_tut/keydata.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/simple_tut/errors.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/libdb/docs/ref/simple_tut/intro.html b/libdb/docs/ref/simple_tut/intro.html deleted file mode 100644 index 6b91aa26e..000000000 --- a/libdb/docs/ref/simple_tut/intro.html +++ /dev/null @@ -1,42 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Introduction</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Simple Tutorial</dl></h3></td> -<td align=right><a href="../../ref/intro/products.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/simple_tut/keydata.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Introduction</h1> -<p>As an introduction to Berkeley DB, we will present a few Berkeley DB programming -concepts, and then a simple database application. -<p>The programming concepts are: -<p><ul type=disc> -<li><a href="keydata.html">Key/data pairs</a> -<li><a href="handles.html">Object handles</a> -<li><a href="errors.html">Error returns</a> -</ul> -<p>This database application will: -<p><ul type=disc> -<li><a href="open.html">Create a simple database</a> -<li><a href="put.html">Store items</a> -<li><a href="get.html">Retrieve items</a> -<li><a href="del.html">Remove items</a> -<li><a href="close.html">Close the database</a> -</ul> -<p>The introduction will be presented using the programming language C. The -<a href="example.cs">complete source</a> of the final version of the -example program is included in the Berkeley DB distribution. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/intro/products.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/simple_tut/keydata.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/libdb/docs/ref/simple_tut/keydata.html b/libdb/docs/ref/simple_tut/keydata.html deleted file mode 100644 index b7eb00527..000000000 --- a/libdb/docs/ref/simple_tut/keydata.html +++ /dev/null @@ -1,49 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Key/data pairs</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Simple Tutorial</dl></h3></td> -<td align=right><a href="../../ref/simple_tut/intro.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/simple_tut/handles.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Key/data pairs</h1> -<p>Berkeley DB uses key/data pairs to identify elements in the database. -That is, in the general case, whenever you call a Berkeley DB interface, -you present a key to identify the key/data pair on which you intend -to operate. -<p>For example, you might store some key/data pairs as follows: -<p><table border=1> -<tr><th>Key:</th><th>Data:</th></tr> -<tr><td>fruit</td><td>apple</td></tr> -<tr><td>sport</td><td>cricket</td></tr> -<tr><td>drink</td><td>water</td></tr> -</table> -<p>In each case, the first element of the pair is the key, and the second is -the data. To store the first of these key/data pairs into the database, -you would call the Berkeley DB interface to store items, with <b>fruit</b> as -the key, and <b>apple</b> as the data. At some future time, you could -then retrieve the data item associated with <b>fruit</b>, and the Berkeley DB -retrieval interface would return <b>apple</b> to you. While there are -many variations and some subtleties, all accesses to data in Berkeley DB come -down to key/data pairs. -<p>Both key and data items are stored in simple structures (called -<a href="../../api_c/dbt_class.html">DBT</a>s) that contain a reference to memory and a length, counted -in bytes. (The name <a href="../../api_c/dbt_class.html">DBT</a> is an acronym for <i>database -thang</i>, chosen because nobody could think of a sensible name that wasn't -already in use somewhere else.) Key and data items can be arbitrary -binary data of practically any length, including 0 bytes. There is a -single data item for each key item, by default, but databases can be -configured to support multiple data items for each key item. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/simple_tut/intro.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/simple_tut/handles.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/libdb/docs/ref/simple_tut/open.html b/libdb/docs/ref/simple_tut/open.html deleted file mode 100644 index bc598bd53..000000000 --- a/libdb/docs/ref/simple_tut/open.html +++ /dev/null @@ -1,91 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<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> -<table width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Simple Tutorial</dl></h3></td> -<td align=right><a href="../../ref/simple_tut/errors.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/simple_tut/put.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Opening a database</h1> -<p>Opening a database is done in two steps: first, a <a href="../../api_c/db_class.html">DB</a> handle is -created using the Berkeley DB <a href="../../api_c/db_create.html">db_create</a> interface, and then the -actual database is opened using the <a href="../../api_c/db_open.html">DB->open</a> function. -<p>The <a href="../../api_c/db_create.html">db_create</a> interface takes three arguments: -<p><dl compact> -<p><dt>dbp<dd>A location to store a reference to the created structure. -<p><dt>environment<dd>A location to specify an enclosing Berkeley DB environment, not used in our -example. -<p><dt>flags<dd>A placeholder for flags, not used in our example. -</dl> -<p>The <a href="../../api_c/db_open.html">DB->open</a> interface takes five arguments: -<p><dl compact> -<p><dt>file<dd>The name of the database file to be opened. -<p><dt>database<dd>The optional database name, not used in this example. -<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>flags<dd>Various flags that modify the behavior of <a href="../../api_c/db_open.html">DB->open</a>. In our -simple case, the only interesting flag is <a href="../../api_c/env_open.html#DB_CREATE">DB_CREATE</a>. This flag -behaves similarly to the IEEE/ANSI Std 1003.1 (POSIX) O_CREATE flag to the open system -call, causing Berkeley DB to create the underlying database if it does not -yet exist. -<p><dt>mode<dd>The file mode of any underlying files that <a href="../../api_c/db_open.html">DB->open</a> will create. -The mode behaves as does the IEEE/ANSI Std 1003.1 (POSIX) mode argument to the open -system call, and specifies file read, write and execute permissions. -Of course, only the read and write permissions are relevant to Berkeley DB. -</dl> -<p>Here's what the code to create the handle and then call <a href="../../api_c/db_open.html">DB->open</a> -looks like: -<p><blockquote><pre><b>#include <sys/types.h> -#include <stdio.h> -#include <db.h> -<p> -#define DATABASE "access.db" -<p> -int -main() -{ - DB *dbp; - int ret; -<p> - if ((ret = db_create(&dbp, NULL, 0)) != 0) { - fprintf(stderr, "db_create: %s\n", db_strerror(ret)); - exit (1); - } - if ((ret = dbp->open(dbp, - NULL, DATABASE, NULL, DB_BTREE, DB_CREATE, 0664)) != 0) { - dbp->err(dbp, ret, "%s", DATABASE); - goto err; - }</b> -</pre></blockquote> -<p>If the call to <a href="../../api_c/db_create.html">db_create</a> is successful, the variable <b>dbp</b> -will contain a database handle that will be used to configure and access -an underlying database. -<p>As you see, the program opens a database named <b>access.db</b>. The -underlying database is a Btree. Because the <a href="../../api_c/env_open.html#DB_CREATE">DB_CREATE</a> flag was -specified, the file will be created if it does not already exist. The -mode of any created files will be 0664 (that is, readable and writable by -the owner and the group, and readable by everyone else). -<p>One additional function call is used in this code sample, <a href="../../api_c/db_err.html">DB->err</a>. -This method works like the ANSI C printf interface. The second argument -is the error return from a Berkeley DB function, and the rest of the arguments -are a printf-style format string and argument list. The error message -associated with the error return will be appended to a message constructed -from the format string and other arguments. In the above code, if the -<a href="../../api_c/db_open.html">DB->open</a> call were to fail, the message it would display would be -something like -<p><blockquote><pre>access.db: Operation not permitted</pre></blockquote> -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/simple_tut/errors.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/simple_tut/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/libdb/docs/ref/simple_tut/put.html b/libdb/docs/ref/simple_tut/put.html deleted file mode 100644 index 9d35e826d..000000000 --- a/libdb/docs/ref/simple_tut/put.html +++ /dev/null @@ -1,128 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Adding elements to 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> -<table width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Simple Tutorial</dl></h3></td> -<td align=right><a href="../../ref/simple_tut/open.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/simple_tut/get.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Adding elements to a database</h1> -<p>The simplest way to add elements to a database is the <a href="../../api_c/db_put.html">DB->put</a> -interface. -<p>The <a href="../../api_c/db_put.html">DB->put</a> interface takes five arguments: -<p><dl compact> -<p><dt>db<dd>The database handle returned by <a href="../../api_c/db_create.html">db_create</a>. -<p><dt>txnid<dd>A transaction handle. In our simple case, we aren't expecting to -recover the database after application or system crash, so we aren't -using transactions, and will leave this argument NULL. -<p><dt>key<dd>The key item for the key/data pair that we want to add to the database. -<p><dt>data<dd>The data item for the key/data pair that we want to add to the database. -<p><dt>flags<dd>Optional flags modifying the underlying behavior of the <a href="../../api_c/db_put.html">DB->put</a> -interface. -</dl> -<p>Here's what the code to call <a href="../../api_c/db_put.html">DB->put</a> looks like: -<p><blockquote><pre>#include <sys/types.h> -#include <stdio.h> -#include <db.h> -<p> -#define DATABASE "access.db" -<p> -int -main() -{ - DB *dbp; - <b>DBT key, data;</b> - int ret; -<p> - if ((ret = db_create(&dbp, NULL, 0)) != 0) { - fprintf(stderr, "db_create: %s\n", db_strerror(ret)); - exit (1); - } - if ((ret = dbp->open(dbp, - NULL, DATABASE, NULL, DB_BTREE, DB_CREATE, 0664)) != 0) { - dbp->err(dbp, ret, "%s", DATABASE); - goto err; - } -<p><b> memset(&key, 0, sizeof(key)); - memset(&data, 0, sizeof(data)); - key.data = "fruit"; - key.size = sizeof("fruit"); - data.data = "apple"; - data.size = sizeof("apple"); -<p> - if ((ret = dbp->put(dbp, NULL, &key, &data, 0)) == 0) - printf("db: %s: key stored.\n", (char *)key.data); - else { - dbp->err(dbp, ret, "DB->put"); - goto err; - } -</b></pre></blockquote> -<p>The first thing to notice about this new code is that we clear the -<a href="../../api_c/dbt_class.html">DBT</a> structures that we're about to pass as arguments to Berkeley DB -functions. This is very important, and being careful to do so will -result in fewer errors in your programs. All Berkeley DB structures -instantiated in the application and handed to Berkeley DB should be cleared -before use, without exception. This is necessary so that future -versions of Berkeley DB may add additional fields to the structures. If -applications clear the structures before use, it will be possible for -Berkeley DB to change those structures without requiring that the applications -be rewritten to be aware of the changes. -<p>Notice also that we're storing the trailing nul byte found in the C -strings <b>"fruit"</b> and <b>"apple"</b> in both the key and data -items, that is, the trailing nul byte is part of the stored key, and -therefore has to be specified in order to access the data item. There is -no requirement to store the trailing nul byte, it simply makes it easier -for us to display strings that we've stored in programming languages that -use nul bytes to terminate strings. -<p>In many applications, it is important not to overwrite existing data. -For example, we might not want to store the key/data pair -<b>fruit/apple</b> if it already existed, for example, if the key/data -pair <b>fruit/cherry</b> had been previously stored into the -database. -<p>This is easily accomplished by adding the <a href="../../api_c/db_put.html#DB_NOOVERWRITE">DB_NOOVERWRITE</a> flag to -the <a href="../../api_c/db_put.html">DB->put</a> call: -<p><blockquote><pre><b>if ((ret = - dbp->put(dbp, NULL, &key, &data, DB_NOOVERWRITE)) == 0) - printf("db: %s: key stored.\n", (char *)key.data); -else { - dbp->err(dbp, ret, "DB->put"); - goto err; -}</b></pre></blockquote> -<p>This flag causes the underlying database functions to not overwrite any -previously existing key/data pair. (Note that the value of the previously -existing data doesn't matter in this case. The only question is if a -key/data pair already exists where the key matches the key that we are -trying to store.) -<p>Specifying <a href="../../api_c/db_put.html#DB_NOOVERWRITE">DB_NOOVERWRITE</a> opens up the possibility of a new -Berkeley DB return value from the <a href="../../api_c/db_put.html">DB->put</a> function, <a href="../../api_c/dbc_put.html#DB_KEYEXIST">DB_KEYEXIST</a>, -which means we were unable to add the key/data pair to the database -because the key already existed in the database. While the above sample -code simply displays a message in this case: -<p><blockquote><pre>DB->put: DB_KEYEXIST: Key/data pair already exists</pre></blockquote> -<p>The following code shows an explicit check for this possibility: -<p><blockquote><pre><b>switch (ret = - dbp->put(dbp, NULL, &key, &data, DB_NOOVERWRITE)) { -case 0: - printf("db: %s: key stored.\n", (char *)key.data); - break; -case DB_KEYEXIST: - printf("db: %s: key previously stored.\n", - (char *)key.data); - break; -default: - dbp->err(dbp, ret, "DB->put"); - goto err; -}</b></pre></blockquote> -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/simple_tut/open.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/simple_tut/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/libdb/docs/ref/tcl/error.html b/libdb/docs/ref/tcl/error.html deleted file mode 100644 index 3193b9fe3..000000000 --- a/libdb/docs/ref/tcl/error.html +++ /dev/null @@ -1,71 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Tcl error handling</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Tcl API</dl></h3></td> -<td align=right><a href="../../ref/tcl/program.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/tcl/faq.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Tcl error handling</h1> -<p>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. -<p>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: -<p><blockquote><pre>% 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</pre></blockquote> -<p>To simplify parsing, it is recommended that the initial Berkeley DB error name -be checked; for example, <a href="../../api_c/dbc_put.html#DB_KEYEXIST">DB_KEYEXIST</a> 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: -<p><blockquote><pre>DB_NOTFOUND: No matching key/data pair found -DB_KEYEMPTY: Nonexistent key/data pair -DB_KEYEXIST: Key/data pair already exists</pre></blockquote> -<p>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. -<p>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. -<p>Also, the two calls to open an environment and open a database take an -option, <b>-errfile filename</b>, which sets an output file to which -these additional error messages should be written. -<p>Additionally, the two calls to open an environment and open a database -take an option, <b>-errpfx string</b>, 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. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/tcl/program.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/tcl/faq.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/libdb/docs/ref/tcl/faq.html b/libdb/docs/ref/tcl/faq.html deleted file mode 100644 index 58db9605f..000000000 --- a/libdb/docs/ref/tcl/faq.html +++ /dev/null @@ -1,58 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Tcl FAQ</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Tcl API</dl></h3></td> -<td align=right><a href="../../ref/tcl/error.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/sendmail/intro.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Tcl FAQ</h1> -<p><ol> -<p><li><b>I have several versions of Tcl installed. How do I configure -Berkeley DB to use a particular version?</b> -<p>To compile the Tcl interface with a particular version of Tcl, use the ---with-tcl option to specify the Tcl installation directory that -contains the tclConfig.sh file. See -<a href="../../ref/build_unix/flags.html">Changing compile or load -options</a> for more information. -<hr size=1 noshade> -<p><li><b>Berkeley DB was configured using --enable-tcl or --with-tcl and fails -to build.</b> -<p>The Berkeley DB Tcl interface requires Tcl version 8.1 or greater. -<hr size=1 noshade> -<p><li><b>Berkeley DB was configured using --enable-tcl or --with-tcl and fails -to build.</b> -<p>If the Tcl installation was moved after it was configured and installed, -try reconfiguring and reinstalling Tcl. -<p>Also, some systems do not search for shared libraries by default, or do -not search for shared libraries named the way the Tcl installation names -them, or are searching for a different kind of library than those in -your Tcl installation. For example, Linux systems often require linking -"libtcl.a" to "libtcl#.#.a", whereas AIX systems often require adding the -"-brtl" flag to the linker. A simpler solution that almost always works -on all systems is to create a link from "libtcl.#.#.a" or "libtcl.so" -(or whatever you happen to have) to "libtcl.a" and reconfigure. -<hr size=1 noshade> -<p><li><b>Loading the Berkeley DB library into Tcl on AIX causes a core dump.</b> -<p>In some versions of Tcl, the "tclConfig.sh" autoconfiguration script -created by the Tcl installation does not work properly under AIX, and -you may have to modify values in the tclConfig.sh file to in order to -load the Berkeley DB library into Tcl. Specifically, the TCL_LIB_SPEC -variable should contain sufficient linker flags to find and link against -the installed libtcl library. In some circumstances, the tclConfig.sh -file built by Tcl does not. -</ol> -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/tcl/error.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/sendmail/intro.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/libdb/docs/ref/tcl/intro.html b/libdb/docs/ref/tcl/intro.html deleted file mode 100644 index 528964bef..000000000 --- a/libdb/docs/ref/tcl/intro.html +++ /dev/null @@ -1,71 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Loading Berkeley DB with Tcl</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Tcl API</dl></h3></td> -<td align=right><a href="../../ref/perl/intro.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/tcl/using.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Loading Berkeley DB with Tcl</h1> -<p>Berkeley DB includes a dynamically loadable Tcl API, which requires that -Tcl/Tk 8.1 or later already be installed on your system. We recommend -that you install later releases of Tcl/Tk than 8.1 if possible, -especially on Windows platforms, because we found that we had to make -local fixes to the 8.1 release in a few cases. You can download a copy -of Tcl from the <a href="http://dev.scriptics.com/">Tcl Developer -Xchange</a> Web site. -<p>This document assumes that you already configured Berkeley DB for Tcl -support, and you have built and installed everything where you want it -to be. If you have not done so, see -<a href="../../ref/build_unix/conf.html">Configuring Berkeley DB</a> or -<a href="../../ref/build_win/intro.html">Building for Win32</a> for more -information. -<h3>Installing as a Tcl Package</h3> -<p>Once enabled, the Berkeley DB shared library for Tcl is automatically installed -as part of the standard installation process. However, if you want to be -able to dynamically load it as a Tcl package into your script, there are -several steps that must be performed: -<p><ol> -<p><li>Run the Tcl shell in the install directory. -<li>Append this directory to your auto_path variable. -<li>Run the pkg_mkIndex proc, giving the name of the Berkeley DB Tcl library. -</ol> -<p>For example: -<p><blockquote><pre># tclsh8.3 -% lappend auto_path /usr/local/BerkeleyDB.4.1/lib -% pkg_mkIndex /usr/local/BerkeleyDB.4.1/lib libdb_tcl-4.1.so</pre></blockquote> -<p>Note that your Tcl and Berkeley DB version numbers may differ from the -example, and so your tclsh and library names may be different. -<h3>Loading Berkeley DB with Tcl</h3> -<p>The Berkeley DB package may be loaded into the user's interactive Tcl script -(or wish session) via the <b>load</b> command. For example: -<p><blockquote><pre>load /usr/local/BerkeleyDB.4.1/lib/libdb_tcl-4.1.so</pre></blockquote> -<p>Note that your Berkeley DB version numbers may differ from the example, and so -the library name may be different. -<p>If you installed your library to run as a Tcl package, Tcl application -scripts should use the <b>package</b> command to indicate to the Tcl -interpreter that it needs the Berkeley DB package and where to find it. For -example: -<p><blockquote><pre>lappend auto_path "/usr/local/BerkeleyDB.4.1/lib" -package require Db_tcl</pre></blockquote> -<p>No matter which way the library gets loaded, it creates a command named -<b>berkdb</b>. All the Berkeley DB functionality is accessed via this -command and additional commands it creates on behalf of the application. -A simple test to determine whether everything is loaded and ready is to -display the library version, as follows: -<p><blockquote><pre>berkdb version -string</pre></blockquote> -<p>This should return you the Berkeley DB version in a string format. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/perl/intro.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/tcl/using.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/libdb/docs/ref/tcl/program.html b/libdb/docs/ref/tcl/program.html deleted file mode 100644 index 7b2764a25..000000000 --- a/libdb/docs/ref/tcl/program.html +++ /dev/null @@ -1,31 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Tcl API programming notes</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Tcl API</dl></h3></td> -<td align=right><a href="../../ref/tcl/using.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/tcl/error.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Tcl API programming notes</h1> -<p>The Tcl API closely parallels the Berkeley DB programmatic interfaces. If you -are already familiar with one of those interfaces, there will not be many -surprises in the Tcl API. -<p>Several pieces of Berkeley DB functionality are not available in the Tcl API. -Any of the functions that require a user-provided function are not -supported via the Tcl API. For example, there is no equivalent to the -<a href="../../api_c/db_set_dup_compare.html">DB->set_dup_compare</a> or the <a href="../../api_c/env_set_errcall.html">DB_ENV->set_errcall</a> -methods. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/tcl/using.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/tcl/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> diff --git a/libdb/docs/ref/tcl/using.html b/libdb/docs/ref/tcl/using.html deleted file mode 100644 index d509b9305..000000000 --- a/libdb/docs/ref/tcl/using.html +++ /dev/null @@ -1,55 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Using Berkeley DB with Tcl</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Tcl API</dl></h3></td> -<td align=right><a href="../../ref/tcl/intro.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/tcl/program.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Using Berkeley DB with Tcl</h1> -<p>All commands in the Berkeley DB Tcl interface are in the following form: -<p><blockquote><pre>command_handle operation options</pre></blockquote> -<p>The <i>command handle</i> is <b>berkdb</b> or one of the additional -commands that may be created. The <i>operation</i> is what you want -to do to that handle, and the <i>options</i> apply to the operation. -Commands that get created on behalf of the application have their own sets -of operations. Generally, any calls in DB that result in new object -handles will translate into a new command handle in Tcl. Then, the user -can access the operations of the handle via the new Tcl command handle. -<p>Newly created commands are named with an abbreviated form of their -objects, followed by a number. Some created commands are subcommands of -other created commands and will be the first command, followed by a -period (.), and then followed by the new subcommand. For example, -suppose that you have a database already existing called my_data.db. -The following example shows the commands created when you open the -database and when you open a cursor: -<p><blockquote><pre># First open the database and get a database command handle -% berkdb open my_data.db -db0 -#Get some data from that database -% db0 get my_key -{{my_key my_data0}{my_key my_data1}} -#Open a cursor in this database, get a new cursor handle -% db0 cursor -db0.c0 -#Get the first data from the cursor -% db0.c0 get -first -{{first_key first_data}}</pre></blockquote> -<p>All commands in the library support a special option <b>-?</b> that will -list the correct operations for a command or the correct options. -<p>A list of commands and operations can be found in the -<a href="../../api_tcl/tcl_index.html">Tcl Interface</a> documentation. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/tcl/intro.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/tcl/program.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/libdb/docs/ref/test/faq.html b/libdb/docs/ref/test/faq.html deleted file mode 100644 index eed831ee7..000000000 --- a/libdb/docs/ref/test/faq.html +++ /dev/null @@ -1,33 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Test suite FAQ</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Test Suite</dl></h3></td> -<td align=right><a href="../../ref/test/run.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/distrib/port.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Test suite FAQ</h1> -<p><ol> -<p><li><b>The test suite has been running for over a day. What's wrong?</b> -<p>The test suite can take anywhere from some number of hours to several -days to run, depending on your hardware configuration. As long as the -run is making forward progress and new lines are being written to the -<b>ALL.OUT</b> file, everything is probably fine. -<p><li><b>The test suite hangs.</b> -<p>The test suite requires Tcl 8.1 or greater, preferably at least Tcl 8.3. -If you are using an earlier version of Tcl, the test suite may simply -hang at some point. -</ol> -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/test/run.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/distrib/port.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/libdb/docs/ref/test/run.html b/libdb/docs/ref/test/run.html deleted file mode 100644 index 5b8112924..000000000 --- a/libdb/docs/ref/test/run.html +++ /dev/null @@ -1,80 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Running the test suite</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Test Suite</dl></h3></td> -<td align=right><a href="../../ref/upgrade.4.1/disk.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/test/faq.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Running the test suite</h1> -<p>Once you have started tclsh and have loaded the test.tcl source file (see -<a href="../../ref/build_unix/test.html">Running the test suite under UNIX</a> -and <a href="../../ref/build_win/test.html">Running the test suite under -Windows</a> for more information), you are ready to run the test suite. At -the tclsh prompt, to run the entire test suite, enter the following: -<p><blockquote><pre>% run_std</pre></blockquote> -<p>Running all the tests can take from several hours to a few days to -complete, depending on your hardware. For this reason, the output from -this command is redirected to a file in the current directory named -<b>ALL.OUT</b>. Periodically, a line will be written to the standard -output, indicating what test is being run. When the test suite has -finished, a single message indicating that the test suite completed -successfully or that it failed will be written. If the run failed, you -should review the file <b>ALL.OUT</b> to determine which tests failed. -Errors will appear in that file as output lines, beginning with the -string "FAIL". -<p>It is also possible to run specific tests or tests for a particular -subsystem: -<p><blockquote><pre>% r archive -% r btree -% r env -% r frecno -% r hash -% r join -% r join -% r lock -% r log -% r mpool -% r mutex -% r queue -% r rbtree -% r recno -% r rrecno -% r subdb -% r txn</pre></blockquote> -<p>Or to run a single, individual test: -<p><blockquote><pre>% test001 btree</pre></blockquote> -<p>It is also possible to modify the test run based on arguments on the -command line. For example, the following command will run a greatly -abbreviated form of test001, doing 10 operations instead of 10,000: -<p><blockquote><pre>% test001 btree 10</pre></blockquote> -<p>In all cases, when not running the entire test suite as described -previously, a successful test run will return you to the tclsh prompt. -On failure, a message is displayed indicating what failed. -<p>Tests are run, by default, in the directory <b>TESTDIR</b>. However, -the test files are often very large. To use a different directory for -the test directory, edit the file include.tcl in your build directory, -and change the following line to a more appropriate value for your -system: -<p><blockquote><pre>set testdir ./TESTDIR</pre></blockquote> -<p>For example, you might change it to the following: -<p><blockquote><pre>set testdir /var/tmp/db.test</pre></blockquote> -<p>Alternatively, you can create a symbolic link named TESTDIR in your -build directory to an appropriate location for running the tests. -Regardless of where you run the tests, the TESTDIR directory should be -on a local filesystem, using a remote filesystem (for example, NFS) will -almost certainly cause spurious test failures. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/upgrade.4.1/disk.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/test/faq.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/libdb/docs/ref/transapp/admin.html b/libdb/docs/ref/transapp/admin.html deleted file mode 100644 index 70a18d94f..000000000 --- a/libdb/docs/ref/transapp/admin.html +++ /dev/null @@ -1,48 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Environment infrastructure</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Berkeley DB Transactional Data Store Applications</dl></h3></td> -<td align=right><a href="../../ref/transapp/nested.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/transapp/deadlock.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Environment infrastructure</h1> -<p>When building transactional applications, it is usually necessary to -build an administrative infrastructure around the database environment. -There are five components to this infrastructure, and each is -supported by the Berkeley DB package in two different ways: a standalone -utility and one or more library interfaces. -<p><ul type=disc> -<li>Deadlock detection: <a href="../../utility/db_deadlock.html">db_deadlock</a>, -<a href="../../api_c/lock_detect.html">DB_ENV->lock_detect</a>, <a href="../../api_c/env_set_lk_detect.html">DB_ENV->set_lk_detect</a> -<li>Checkpoints: <a href="../../utility/db_checkpoint.html">db_checkpoint</a>, <a href="../../api_c/txn_checkpoint.html">DB_ENV->txn_checkpoint</a> -<li>Database and log file archival: -<a href="../../utility/db_archive.html">db_archive</a>, <a href="../../api_c/log_archive.html">DB_ENV->log_archive</a> -<li>Log file removal: <a href="../../utility/db_archive.html">db_archive</a>, <a href="../../api_c/log_archive.html">DB_ENV->log_archive</a> -<li>Recovery procedures: <a href="../../utility/db_recover.html">db_recover</a>, <a href="../../api_c/env_open.html">DB_ENV->open</a> -</ul> -<p>When writing multithreaded server applications and/or applications -intended for download from the Web, it is usually simpler to create -local threads that are responsible for administration of the database -environment as scheduling is often simpler in a single-process model, -and only a single binary need be installed and run. However, the -supplied utilities can be generally useful tools even when the -application is responsible for doing its own administration because -applications rarely offer external interfaces to database -administration. The utilities are required when programming to a Berkeley DB -scripting interface because the scripting APIs do not always offer -interfaces to the administrative functionality. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/transapp/nested.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/transapp/deadlock.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/libdb/docs/ref/transapp/app.html b/libdb/docs/ref/transapp/app.html deleted file mode 100644 index a5051e24a..000000000 --- a/libdb/docs/ref/transapp/app.html +++ /dev/null @@ -1,130 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Application structure</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Berkeley DB Transactional Data Store Applications</dl></h3></td> -<td align=right><a href="../../ref/transapp/term.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/transapp/env_open.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Application structure</h1> -<p>When building transactionally protected applications, there are some -special issues that must be considered. The most important one is that -if any thread of control exits for any reason while holding Berkeley DB -resources, recovery must be performed to do the following: -<p><ul type=disc> -<li>Recover the Berkeley DB resources. -<li>Release any locks or mutexes that may have been held to avoid starvation -as the remaining threads of control convoy behind the failed thread's -locks. -<li>Clean up any partially completed operations that may have left a -database in an inconsistent or corrupted state. -</ul> -<p>Complicating this problem is the fact that the Berkeley DB library itself -cannot determine whether recovery is required; the application itself -<b>must</b> make that decision. A further complication is that -recovery must be single-threaded; that is, one thread of control or -process must perform recovery before any other thread of control or -processes attempts to create or join the Berkeley DB environment. -<p>There are two approaches to handling this problem: -<p><dl compact> -<p><dt>The hard way:<dd>An application can track its own state carefully enough that it knows -when recovery needs to be performed. Specifically, the rule to use is -that recovery must be performed before using a Berkeley DB environment any -time the threads of control previously using the Berkeley DB environment did -not shut the environment down cleanly before exiting the environment -for any reason (including application or system failure). -<p>Requirements for shutting down the environment cleanly differ, depending -on the type of environment created. If the environment is public and -persistent (that is, the <a href="../../api_c/env_open.html#DB_PRIVATE">DB_PRIVATE</a> flag was not specified to -the <a href="../../api_c/env_open.html">DB_ENV->open</a> method), recovery must be performed if any transaction -was not committed or aborted, or <a href="../../api_c/env_close.html">DB_ENV->close</a> method was not called -for any open <a href="../../api_c/env_class.html">DB_ENV</a> handle. -<p>If the environment is private and temporary (that is, the -<a href="../../api_c/env_open.html#DB_PRIVATE">DB_PRIVATE</a> flag was specified to the <a href="../../api_c/env_open.html">DB_ENV->open</a> method), -recovery must be performed if any transaction was not committed or -aborted, or <a href="../../api_c/env_close.html">DB_ENV->close</a> method was not called for any open -<a href="../../api_c/env_class.html">DB_ENV</a> handle. In addition, at least one transaction checkpoint -must be performed after all existing transactions have been committed -or aborted. -<p><dt>The easy way:<dd>It greatly simplifies matters that recovery may be performed regardless -of whether recovery strictly needs to be performed; that is, it is not -an error to run recovery on a database for which no recovery is -necessary. Because of this fact, it is almost invariably simpler to -ignore the previous rules about shutting an application down cleanly, -and simply run recovery each time a thread of control accessing a -database environment fails for any reason, as well as before accessing -any database environment after system reboot. -</dl> -<p>There are two common ways to build transactionally protected Berkeley DB -applications. The most common way is as a single, usually -multithreaded, process. This architecture is simplest because it -requires no monitoring of other threads of control. When the -application starts, it opens and potentially creates the environment, -runs recovery (whether it was needed or not), and then opens its -databases. From then on, the application can create new threads of -control as it chooses. All threads of control share the open Berkeley DB -<a href="../../api_c/env_class.html">DB_ENV</a> and <a href="../../api_c/db_class.html">DB</a> handles. In this model, databases are -rarely opened or closed when more than a single thread of control is -running; that is, they are opened when only a single thread is running, -and closed after all threads but one have exited. The last thread of -control to exit closes the databases and the environment. -<p>An alternative way to build Berkeley DB applications is as a set of -cooperating processes, which may or may not be multithreaded. This -architecture is more complicated. -<p>First, this architecture requires that the order in which threads of -control are created and subsequently access the Berkeley DB environment be -controlled because recovery must be single-threaded. The first thread -of control to access the environment must run recovery, and no other -thread should attempt to access the environment until recovery is -complete. (Note that this ordering requirement does not apply to -environment creation without recovery. If multiple threads attempt to -create a Berkeley DB environment, only one will perform the creation and the -others will join the already existing environment.) -<p>Second, this architecture requires that threads of control be monitored. -If any thread of control that owns Berkeley DB resources exits without first -cleanly discarding those resources, recovery is usually necessary. -Before running recovery, all threads using the Berkeley DB environment must -relinquish all of their Berkeley DB resources (it does not matter if they do -so gracefully or because they are forced to exit). Then, recovery can -be run and the threads of control continued or restarted. -<p>We have found that the safest way to structure groups of cooperating -processes is to first create a single process (often a shell script) -that opens/creates the Berkeley DB environment and runs recovery, and that -then creates the processes or threads that will actually perform work. -The initial thread has no further responsibilities other than to monitor -the threads of control it has created, to ensure that none of them -unexpectedly exits. If one exits, the initial process then forces all -of the threads of control using the Berkeley DB environment to exit, runs -recovery, and restarts the working threads of control. -<p>If it is not practical to have a single parent for the processes sharing -a Berkeley DB environment, each process sharing the environment should log -their connection to and exit from the environment in a way that allows -a monitoring process to detect if a thread of control might have -acquired Berkeley DB resources and never released them. In this model, an -initial "watcher" process opens/creates the Berkeley DB environment and runs -recovery, and then creates a sentinel file. Any other process wanting -to use the Berkeley DB environment checks for the sentinel file; if the -sentinel file exists, the other process registers its process ID with -the watcher and joins the database environment. When the other process -finishes with the environment, it unregisters its process ID with the -water. The watcher periodically checks to ensure that no process has -failed while using the environment. If a process does fail while using -the environment, the watcher removes the sentinel file, kills all -processes currently using the environment, runs recovery, and re-creates -the sentinel file. -<p>Obviously, it is important that the monitoring process in either case -be as simple and well-tested as possible because there is no recourse -if it fails. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/transapp/term.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/transapp/env_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/libdb/docs/ref/transapp/archival.html b/libdb/docs/ref/transapp/archival.html deleted file mode 100644 index fa4f93b25..000000000 --- a/libdb/docs/ref/transapp/archival.html +++ /dev/null @@ -1,154 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Database and log file archival</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Berkeley DB Transactional Data Store Applications</dl></h3></td> -<td align=right><a href="../../ref/transapp/checkpoint.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/transapp/logfile.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Database and log file archival</h1> -<p>The third component of the administrative infrastructure, archival for -catastrophic recovery, concerns the recoverability of the database in -the face of catastrophic failure. Recovery after catastrophic failure -is intended to minimize data loss when physical hardware has been -destroyed -- for example, loss of a disk that contains databases or log -files. Although the application may still experience data loss in this -case, it is possible to minimize it. -<p>First, you may want to periodically create snapshots (that is, backups) -of your databases to make it possible to recover from catastrophic -failure. These snapshots are either a standard backup, which creates a -consistent picture of the databases as of a single instant in time; or -an on-line backup (also known as a <i>hot</i> backup), which creates -a consistent picture of the databases as of an unspecified instant -during the period of time when the snapshot was made. The advantage of -a hot backup is that applications may continue to read and write the -databases while the snapshot is being taken. The disadvantage of a hot -backup is that more information must be archived, and recovery based on -a hot backup is to an unspecified time between the start of the backup -and when the backup is completed. -<p>Second, after taking a snapshot, you should periodically archive the -log files being created in the environment. It is often helpful to -think of database archival in terms of full and incremental filesystem -backups. A snapshot is a full backup, whereas the periodic archival of -the current log files is an incremental backup. For example, it might -be reasonable to take a full snapshot of a database environment weekly -or monthly, and archive additional log files daily. Using both the -snapshot and the log files, a catastrophic crash at any time can be -recovered to the time of the most recent log archival; a time long after -the original snapshot. -<p>To create a standard backup of your database that can be used to recover -from catastrophic failure, take the following steps: -<p><ol> -<p><li>Commit or abort all ongoing transactions. -<p><li>Stop writing your databases until the backup has completed. Read-only -operations are permitted, but no write operations and no filesystem -operations may be performed (for example, the <a href="../../api_c/env_remove.html">DB_ENV->remove</a> and -<a href="../../api_c/db_open.html">DB->open</a> methods may not be called). -<p><li>Force an environment checkpoint (see <a href="../../utility/db_checkpoint.html">db_checkpoint</a> for more -information). -<p><li>Run <a href="../../utility/db_archive.html">db_archive</a> <b>-s</b> to identify all the database data -files, and copy them to a backup device such as CD-ROM, alternate disk, -or tape. -<p>If the database files are stored in a separate directory from the other -Berkeley DB files, it may be simpler to archive the directory itself instead -of the individual files (see <a href="../../api_c/env_set_data_dir.html">DB_ENV->set_data_dir</a> for additional -information). <b>Note: if any of the database files did not have -an open <a href="../../api_c/db_class.html">DB</a> handle during the lifetime of the current log files, -<a href="../../utility/db_archive.html">db_archive</a> will not list them in its output!</b> This is another -reason it may be simpler to use a separate database file directory and -archive the entire directory instead of archiving only the files listed -by <a href="../../utility/db_archive.html">db_archive</a>. -<p><li>Run <a href="../../utility/db_archive.html">db_archive</a> <b>-l</b> to identify all the log files, -and copy the last one (that is, the one with the highest number) to a -backup device such as CD-ROM, alternate disk, or tape. -</ol> -<a name="4"><!--meow--></a> -<p>To create a <i>hot</i> backup of your database that can be used to -recover from catastrophic failure, take the following steps: -<p><ol> -<p><li>Archive your databases, as described in the previous step #4. -You do not have to halt ongoing transactions or force a -checkpoint. In the case of a hot backup, the utility you use to copy -the databases must read database pages atomically (as described by -<a href="../../ref/transapp/reclimit.html">Berkeley DB recoverability</a>). -<p><li>When performing a hot backup, you must additionally archive all of the -log files. Note that the order of these two operations is required, -and the database files must be archived before the log files. This -means that if the database files and log files are in the same -directory, you cannot simply archive the directory; you must make sure -that the correct order of archival is maintained. -<p>To archive your log files, run the <a href="../../utility/db_archive.html">db_archive</a> utility using -the <b>-l</b> option to identify all the database log files, and -copy them to your backup media. If the database log files are stored -in a separate directory from the other database files, it may be simpler -to archive the directory itself instead of the individual files (see -the <a href="../../api_c/env_set_lg_dir.html">DB_ENV->set_lg_dir</a> method for more information). -</ol> -<p>Once these steps are completed, your database can be recovered from -catastrophic failure (see <a href="recovery.html">Recovery procedures</a> for -more information). -<p>To update your snapshot so that recovery from catastrophic failure is -possible up to a new point in time, repeat step 2 under the hot backup -instructions -- copying all existing log files to a backup device. This -is applicable to both standard and hot backups; that is, you can update -snapshots made either way. Each time both the database and log files -are copied to backup media, you may discard all previous database -snapshots and saved log files. Archiving additional log files does not -allow you to discard either previous database snapshots or log files. -<p>The time to restore from catastrophic failure is a function of the -number of log records that have been written since the snapshot was -originally created. Perhaps more importantly, the more separate pieces -of backup media you use, the more likely it is that you will have a -problem reading from one of them. For these reasons, it is often best -to make snapshots on a regular basis. -<p><b>Obviously, the reliability of your archive media will affect the safety -of your data. For archival safety, ensure that you have multiple copies -of your database backups, verify that your archival media is error-free -and readable, and that copies of your backups are stored offsite!</b> -<p>The functionality provided by the <a href="../../utility/db_archive.html">db_archive</a> utility is also -available directly from the Berkeley DB library. The following code fragment -prints out a list of log and database files that need to be archived: -<p><blockquote><pre>void -log_archlist(DB_ENV *dbenv) -{ - int ret; - char **begin, **list; -<p> - /* Get the list of database files. */ - if ((ret = dbenv->log_archive(dbenv, - &list, DB_ARCH_ABS | DB_ARCH_DATA)) != 0) { - dbenv->err(dbenv, ret, "DB_ENV->log_archive: DB_ARCH_DATA"); - exit (1); - } - if (list != NULL) { - for (begin = list; *list != NULL; ++list) - printf("database file: %s\n", *list); - free (begin); - } -<p> - /* Get the list of log files. */ - if ((ret = dbenv->log_archive(dbenv, - &list, DB_ARCH_ABS | DB_ARCH_LOG)) != 0) { - dbenv->err(dbenv, ret, "DB_ENV->log_archive: DB_ARCH_LOG"); - exit (1); - } - if (list != NULL) { - for (begin = list; *list != NULL; ++list) - printf("log file: %s\n", *list); - free (begin); - } -}</pre></blockquote> -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/transapp/checkpoint.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/transapp/logfile.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/libdb/docs/ref/transapp/atomicity.html b/libdb/docs/ref/transapp/atomicity.html deleted file mode 100644 index c8fbf2089..000000000 --- a/libdb/docs/ref/transapp/atomicity.html +++ /dev/null @@ -1,63 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Atomicity</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Berkeley DB Transactional Data Store Applications</dl></h3></td> -<td align=right><a href="../../ref/transapp/put.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/transapp/inc.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Atomicity</h1> -<p>The second reason listed for using transactions was <i>atomicity</i>. -Atomicity means that multiple operations can be grouped into a single -logical entity, that is, other threads of control accessing the database -will either see all of the changes or none of the changes. Atomicity -is important for applications wanting to update two related databases -(for example, a primary database and secondary index) in a single -logical action. Or, for an application wanting to update multiple -records in one database in a single logical action. -<p>Any number of operations on any number of databases can be included in -a single transaction to ensure the atomicity of the operations. There -is, however, a trade-off between the number of operations included in -a single transaction and both throughput and the possibility of -deadlock. The reason for this is because transactions acquire locks -throughout their lifetime and do not release the locks until commit or -abort time. So, the more operations included in a transaction, the more -likely it is that a transaction will block other operations and that -deadlock will occur. However, each transaction commit requires a -synchronous disk I/O, so grouping multiple operations into a transaction -can increase overall throughput. (There is one exception to this: the -<a href="../../api_c/env_set_flags.html#DB_TXN_WRITE_NOSYNC">DB_TXN_WRITE_NOSYNC</a> and <a href="../../api_c/env_set_flags.html#DB_TXN_NOSYNC">DB_TXN_NOSYNC</a> flags cause -transactions to exhibit the ACI (atomicity, consistency and isolation) -properties, but not D (durability); avoiding the write and/or -synchronous disk I/O on transaction commit greatly increases transaction -throughput for some applications.) -<p>When applications do create complex transactions, they often avoid -having more than one complex transaction at a time because simple -operations like a single <a href="../../api_c/db_put.html">DB->put</a> are unlikely to deadlock with -each other or the complex transaction; while multiple complex -transactions are likely to deadlock with each other because they will -both acquire many locks over their lifetime. Alternatively, complex -transactions can be broken up into smaller sets of operations, and each -of those sets may be encapsulated in a nested transaction. Because -nested transactions may be individually aborted and retried without -causing the entire transaction to be aborted, this allows complex -transactions to proceed even in the face of heavy contention, repeatedly -trying the suboperations until they succeed. -<p>It is also helpful to order operations within a transaction; that is, -access the databases and items within the databases in the same order, -to the extent possible, in all transactions. Accessing databases and -items in different orders greatly increases the likelihood of operations -being blocked and failing due to deadlocks. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/transapp/put.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/transapp/inc.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/libdb/docs/ref/transapp/checkpoint.html b/libdb/docs/ref/transapp/checkpoint.html deleted file mode 100644 index 900153861..000000000 --- a/libdb/docs/ref/transapp/checkpoint.html +++ /dev/null @@ -1,124 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Checkpoints</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Berkeley DB Transactional Data Store Applications</dl></h3></td> -<td align=right><a href="../../ref/transapp/deadlock.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/transapp/archival.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Checkpoints</h1> -<p>The second component of the infrastructure is performing checkpoints of -the log files. As transactions commit, change records are written into -the log files, but the actual changes to the database are not -necessarily written to disk. When a checkpoint is performed, the -changes to the database that are part of committed transactions are -written into the backing database file. -<p>Performing checkpoints is necessary for two reasons. First, you can -remove the Berkeley DB log files from your system only after a checkpoint. -Second, the frequency of your checkpoints is inversely proportional to -the amount of time it takes to run database recovery after a system or -application failure. -<p>Once the database pages are written, log files can be archived and removed -from the system because they will never be needed for anything other than -catastrophic failure. In addition, recovery after system or application -failure has to redo or undo changes only since the last checkpoint since -changes before the checkpoint have all been flushed to the filesystem. -<p>Berkeley DB provides a separate utility, <a href="../../utility/db_checkpoint.html">db_checkpoint</a>, which can be -used to perform checkpoints. Alternatively, applications can write -their own checkpoint utility using the underlying <a href="../../api_c/txn_checkpoint.html">DB_ENV->txn_checkpoint</a> -function. The following code fragment checkpoints the database -environment every 60 seconds: -<p><blockquote><pre>int -main(int argc, char *argv) -{ - extern char *optarg; - extern int optind; - DB *db_cats, *db_color, *db_fruit; - DB_ENV *dbenv; - pthread_t ptid; - int ch; -<p> - while ((ch = getopt(argc, argv, "")) != EOF) - switch (ch) { - case '?': - default: - usage(); - } - argc -= optind; - argv += optind; -<p> - env_dir_create(); - env_open(&dbenv); -<p> -<b> /* Start a checkpoint thread. */ - if ((errno = pthread_create( - &ptid, NULL, checkpoint_thread, (void *)dbenv)) != 0) { - fprintf(stderr, - "txnapp: failed spawning checkpoint thread: %s\n", - strerror(errno)); - exit (1); - }</b> -<p> - /* Open database: Key is fruit class; Data is specific type. */ - db_open(dbenv, &db_fruit, "fruit", 0); -<p> - /* Open database: Key is a color; Data is an integer. */ - db_open(dbenv, &db_color, "color", 0); -<p> - /* - * Open database: - * Key is a name; Data is: company name, cat breeds. - */ - db_open(dbenv, &db_cats, "cats", 1); -<p> - add_fruit(dbenv, db_fruit, "apple", "yellow delicious"); -<p> - add_color(dbenv, db_color, "blue", 0); - add_color(dbenv, db_color, "blue", 3); -<p> - add_cat(dbenv, db_cats, - "Amy Adams", - "Sleepycat Software", - "abyssinian", - "bengal", - "chartreaux", - NULL); -<p> - return (0); -} -<p> -<b>void * -checkpoint_thread(void *arg) -{ - DB_ENV *dbenv; - int ret; -<p> - dbenv = arg; - dbenv->errx(dbenv, "Checkpoint thread: %lu", (u_long)pthread_self()); -<p> - /* Checkpoint once a minute. */ - for (;; sleep(60)) - if ((ret = dbenv->txn_checkpoint(dbenv, 0, 0, 0)) != 0) { - dbenv->err(dbenv, ret, "checkpoint thread"); - exit (1); - } -<p> - /* NOTREACHED */ -}</b></pre></blockquote> -<p>Because checkpoints can be quite expensive, choosing how often to -perform a checkpoint is a common tuning parameter for Berkeley DB -applications. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/transapp/deadlock.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/transapp/archival.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/libdb/docs/ref/transapp/cursor.html b/libdb/docs/ref/transapp/cursor.html deleted file mode 100644 index 6a323cc06..000000000 --- a/libdb/docs/ref/transapp/cursor.html +++ /dev/null @@ -1,171 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Transactional 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> -<table width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Berkeley DB Transactional Data Store Applications</dl></h3></td> -<td align=right><a href="../../ref/transapp/read.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/transapp/nested.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Transactional cursors</h1> -<p>Berkeley DB cursors may be used inside a transaction, exactly as any other -<a href="../../api_c/db_class.html">DB</a> method. The enclosing transaction ID must be specified when -the cursor is created, but it does not then need to be further specified -on operations performed using the cursor. One important point to -remember is that a cursor <b>must be closed</b> before the enclosing -transaction is committed or aborted. -<p>The following code fragment uses a cursor to store a new key in the cats -database with four associated data items. The key is a name. The data -items are a company name, an address, and a list of the breeds of cat -owned. Each of the data entries is stored as a duplicate data item. -In this example, transactions are necessary to ensure that either all or none -of the data items appear in case of system or application failure. -<p><blockquote><pre>int -main(int argc, char *argv) -{ - extern char *optarg; - extern int optind; - DB *db_cats, *db_color, *db_fruit; - DB_ENV *dbenv; - pthread_t ptid; - int ch; -<p> - while ((ch = getopt(argc, argv, "")) != EOF) - switch (ch) { - case '?': - default: - usage(); - } - argc -= optind; - argv += optind; -<p> - env_dir_create(); - env_open(&dbenv); -<p> - /* Open database: Key is fruit class; Data is specific type. */ - db_open(dbenv, &db_fruit, "fruit", 0); -<p> - /* Open database: Key is a color; Data is an integer. */ - db_open(dbenv, &db_color, "color", 0); -<p> - /* - * Open database: - * Key is a name; Data is: company name, cat breeds. - */ - db_open(dbenv, &db_cats, "cats", 1); -<p> - add_fruit(dbenv, db_fruit, "apple", "yellow delicious"); -<p> - add_color(dbenv, db_color, "blue", 0); - add_color(dbenv, db_color, "blue", 3); -<p> -<b> add_cat(dbenv, db_cats, - "Amy Adams", - "Sleepycat Software", - "abyssinian", - "bengal", - "chartreaux", - NULL);</b> -<p> - return (0); -} -<p> -<b>int -add_cat(DB_ENV *dbenv, DB *db, char *name, ...) -{ - va_list ap; - DBC *dbc; - DBT key, data; - DB_TXN *tid; - int fail, ret, t_ret; - char *s; -<p> - /* Initialization. */ - fail = 0; -<p> - memset(&key, 0, sizeof(key)); - memset(&data, 0, sizeof(data)); - key.data = name; - key.size = strlen(name); -<p> -retry: /* Begin the transaction. */ - if ((ret = dbenv->txn_begin(dbenv, NULL, &tid, 0)) != 0) { - dbenv->err(dbenv, ret, "DB_ENV->txn_begin"); - exit (1); - } -<p> - /* Delete any previously existing item. */ - switch (ret = db->del(db, tid, &key, 0)) { - case 0: - case DB_NOTFOUND: - break; - case DB_LOCK_DEADLOCK: - default: - /* Retry the operation. */ - if ((t_ret = tid->abort(tid)) != 0) { - dbenv->err(dbenv, t_ret, "DB_TXN->abort"); - exit (1); - } - if (++fail == MAXIMUM_RETRY) - return (ret); - goto retry; - } -<p> - /* Create a cursor. */ - if ((ret = db->cursor(db, tid, &dbc, 0)) != 0) { - dbenv->err(dbenv, ret, "db->cursor"); - exit (1); - } -<p> - /* Append the items, in order. */ - va_start(ap, name); - while ((s = va_arg(ap, char *)) != NULL) { - data.data = s; - data.size = strlen(s); - switch (ret = dbc->c_put(dbc, &key, &data, DB_KEYLAST)) { - case 0: - break; - case DB_LOCK_DEADLOCK: - default: - va_end(ap); -<p> - /* Retry the operation. */ - if ((t_ret = dbc->c_close(dbc)) != 0) { - dbenv->err( - dbenv, t_ret, "dbc->c_close"); - exit (1); - } - if ((t_ret = tid->abort(tid)) != 0) { - dbenv->err(dbenv, t_ret, "DB_TXN->abort"); - exit (1); - } - if (++fail == MAXIMUM_RETRY) - return (ret); - goto retry; - } - } - va_end(ap); -<p> - /* Success: commit the change. */ - if ((ret = dbc->c_close(dbc)) != 0) { - dbenv->err(dbenv, ret, "dbc->c_close"); - exit (1); - } - if ((ret = tid->commit(tid, 0)) != 0) { - dbenv->err(dbenv, ret, "DB_TXN->commit"); - exit (1); - } - return (0); -}</b></pre></blockquote> -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/transapp/read.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/transapp/nested.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/libdb/docs/ref/transapp/data_open.html b/libdb/docs/ref/transapp/data_open.html deleted file mode 100644 index ff22d2863..000000000 --- a/libdb/docs/ref/transapp/data_open.html +++ /dev/null @@ -1,143 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Opening the 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> -<table width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Berkeley DB Transactional Data Store Applications</dl></h3></td> -<td align=right><a href="../../ref/transapp/env_open.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/transapp/put.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Opening the databases</h1> -<p>Next, we open three databases ("color" and "fruit" and "cats"), in the -database environment. Again, our <a href="../../api_c/db_class.html">DB</a> database handles are -declared to be free-threaded using the <a href="../../api_c/env_open.html#DB_THREAD">DB_THREAD</a> flag, and so -may be used by any number of threads we subsequently create. -<p><blockquote><pre>int -main(int argc, char *argv) -{ - extern char *optarg; - extern int optind; - DB *db_cats, *db_color, *db_fruit; - DB_ENV *dbenv; - int ch; -<p> - while ((ch = getopt(argc, argv, "")) != EOF) - switch (ch) { - case '?': - default: - usage(); - } - argc -= optind; - argv += optind; -<p> - env_dir_create(); - env_open(&dbenv); -<p> -<b> /* Open database: Key is fruit class; Data is specific type. */ - if (db_open(dbenv, &db_fruit, "fruit", 0)) - return (1); -<p> - /* Open database: Key is a color; Data is an integer. */ - if (db_open(dbenv, &db_color, "color", 0)) - return (1); -<p> - /* - * Open database: - * Key is a name; Data is: company name, cat breeds. - */ - if (db_open(dbenv, &db_cats, "cats", 1)) - return (1);</b> -<p> - return (0); -} -<p> -<b>int -db_open(DB_ENV *dbenv, DB **dbp, char *name, int dups) -{ - DB *db; - int ret; -<p> - /* Create the database handle. */ - if ((ret = db_create(&db, dbenv, 0)) != 0) { - dbenv->err(dbenv, ret, "db_create"); - return (1); - } -<p> - /* Optionally, turn on duplicate data items. */ - if (dups && (ret = db->set_flags(db, DB_DUP)) != 0) { - (void)db->close(db, 0); - dbenv->err(dbenv, ret, "db->set_flags: DB_DUP"); - return (1); - } -<p> - /* - * Open a database in the environment: - * create if it doesn't exist - * free-threaded handle - * read/write owner only - */ - if ((ret = db->open(db, NULL, name, NULL, DB_BTREE, - DB_CREATE | DB_THREAD | DB_AUTO_COMMIT, S_IRUSR | S_IWUSR)) != 0) { - (void)db->close(db, 0); - dbenv->err(dbenv, ret, "db->open: %s", name); - return (1); - } -<p> - *dbp = db; - return (0); -}</b></pre></blockquote> -<p>After opening the database, we can use the <a href="../../utility/db_stat.html">db_stat</a> utility to -display information about a database we have created: -<p><blockquote><pre>prompt> db_stat -h TXNAPP -d color -53162 Btree magic number. -8 Btree version number. -Flags: -2 Minimum keys per-page. -8192 Underlying database page size. -1 Number of levels in the tree. -0 Number of unique keys in the tree. -0 Number of data items in the tree. -0 Number of tree internal pages. -0 Number of bytes free in tree internal pages (0% ff). -1 Number of tree leaf pages. -8166 Number of bytes free in tree leaf pages (0.% ff). -0 Number of tree duplicate pages. -0 Number of bytes free in tree duplicate pages (0% ff). -0 Number of tree overflow pages. -0 Number of bytes free in tree overflow pages (0% ff). -0 Number of pages on the free list.</pre></blockquote> -<p>The database open must be enclosed within a transaction in order to be -recoverable. The transaction will ensure that created files are -re-created in recovered environments (or do not appear at all). -Additional database operations or operations on other databases can be -included in the same transaction, of course. In the simple case, where -the open is the only operation in the transaction, an application can -set the <a href="../../api_c/env_set_flags.html#DB_AUTO_COMMIT">DB_AUTO_COMMIT</a> flag instead of creating and managing -its own transaction handle. The <a href="../../api_c/env_set_flags.html#DB_AUTO_COMMIT">DB_AUTO_COMMIT</a> flag will -internally wrap the operation in a transaction, simplifying application -code. -<p>The previous example is the simplest case of transaction protection for -database open. Obviously, additional database operations can be done -in the scope of the same transaction. For example, an application -maintaining a list of the databases in a database environment in a -well-known file might include an update of the list in the same -transaction in which the database is created. Or, an application might -create both a primary and secondary database in a single transaction. -<p><a href="../../api_c/db_class.html">DB</a> handles that will later be used for transactionally protected -operations must be opened within a transaction. Specifying a -transaction handle to operations using handles not opened within a -transaction will return an error. Similarly, not specifying a -transaction handle to operations using handles that were opened within -a transaction will also return an error. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/transapp/env_open.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/transapp/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/libdb/docs/ref/transapp/deadlock.html b/libdb/docs/ref/transapp/deadlock.html deleted file mode 100644 index f188a89db..000000000 --- a/libdb/docs/ref/transapp/deadlock.html +++ /dev/null @@ -1,109 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Deadlock detection</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Berkeley DB Transactional Data Store Applications</dl></h3></td> -<td align=right><a href="../../ref/transapp/admin.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/transapp/checkpoint.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Deadlock detection</h1> -<p>The first component of the infrastructure, <i>deadlock -detection</i>, is not so much a requirement specific to -transaction-protected applications, but instead is necessary for almost -all applications in which more than a single thread of control will be -accessing the database at one time. Even when Berkeley DB automatically -handles database locking, it is normally possible for deadlock to occur. -Because the underlying database access methods may update multiple pages -during a single Berkeley DB API call, deadlock is possible even when threads -of control are making only single update calls into the database. The -exception to this rule is when all the threads of control accessing the -database are read-only or when the Berkeley DB Concurrent Data Store product is used; the Berkeley DB Concurrent Data Store -product guarantees deadlock-free operation at the expense of reduced -concurrency. -<p>When the deadlock occurs, two (or more) threads of control each request -additional locks that can never be granted because one of the threads -of control waiting holds the requested resource. For example, consider -two processes: A and B. Let's say that A obtains a write lock on item -X, and B obtains a write lock on item Y. Then, A requests a lock on Y, -and B requests a lock on X. A will wait until resource Y becomes -available and B will wait until resource X becomes available. -Unfortunately, because both A and B are waiting, neither will release -the locks they hold and neither will ever obtain the resource on which -it is waiting. For another example, consider two transactions, A and -B, each of which may want to modify item X. Assume that transaction A -obtains a read lock on X and confirms that a modification is needed. -Then it is descheduled and the thread containing transaction B runs. -At that time, transaction B obtains a read lock on X and confirms that -it also wants to make a modification. Both transactions A and B will -block when they attempt to upgrade their read locks to write locks -because the other already holds a read lock. This is a deadlock. -Transaction A cannot make forward progress until Transaction B releases -its read lock on X, but Transaction B cannot make forward progress until -Transaction A releases its read lock on X. -<p>In order to detect that deadlock has happened, a separate process or -thread must review the locks currently held in the database. If -deadlock has occurred, a victim must be selected, and that victim will -then return the error <a href="../../ref/program/errorret.html#DB_LOCK_DEADLOCK">DB_LOCK_DEADLOCK</a> from whatever Berkeley DB call -it was making. Berkeley DB provides a separate UNIX-style utility that can -be used to perform this deadlock detection, named <a href="../../utility/db_deadlock.html">db_deadlock</a>. -Alternatively, applications can create their own deadlock utility or -thread using the underlying <a href="../../api_c/lock_detect.html">DB_ENV->lock_detect</a> function, or specify -that Berkeley DB run the deadlock detector internally whenever there is a -conflict over a lock (see <a href="../../api_c/env_set_lk_detect.html">DB_ENV->set_lk_detect</a> for more -information). The following code fragment does the latter: -<p><blockquote><pre>void -env_open(DB_ENV **dbenvp) -{ - DB_ENV *dbenv; - int ret; -<p> - /* Create the environment handle. */ - if ((ret = db_env_create(&dbenv, 0)) != 0) { - fprintf(stderr, - "txnapp: db_env_create: %s\n", db_strerror(ret)); - exit (1); - } -<p> - /* Set up error handling. */ - dbenv->set_errpfx(dbenv, "txnapp"); -<p> -<b> /* Do deadlock detection internally. */ - if ((ret = dbenv->set_lk_detect(dbenv, DB_LOCK_DEFAULT)) != 0) { - dbenv->err(dbenv, ret, "set_lk_detect: DB_LOCK_DEFAULT"); - exit (1); - }</b> -<p> - /* - * Open a transactional environment: - * create if it doesn't exist - * free-threaded handle - * run recovery - * read/write owner only - */ - if ((ret = dbenv->open(dbenv, ENV_DIRECTORY, - DB_CREATE | DB_INIT_LOCK | DB_INIT_LOG | - DB_INIT_MPOOL | DB_INIT_TXN | DB_RECOVER | DB_THREAD, - S_IRUSR | S_IWUSR)) != 0) { - dbenv->err(dbenv, ret, "dbenv->open: %s", ENV_DIRECTORY); - exit (1); - } -<p> - *dbenvp = dbenv; -}</pre></blockquote> -<p>Deciding how often to run the deadlock detector and which of the -deadlocked transactions will be forced to abort when the deadlock is -detected is a common tuning parameter for Berkeley DB applications. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/transapp/admin.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/transapp/checkpoint.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/libdb/docs/ref/transapp/env_open.html b/libdb/docs/ref/transapp/env_open.html deleted file mode 100644 index ef2ad0db4..000000000 --- a/libdb/docs/ref/transapp/env_open.html +++ /dev/null @@ -1,175 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Opening the environment</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Berkeley DB Transactional Data Store Applications</dl></h3></td> -<td align=right><a href="../../ref/transapp/app.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/transapp/data_open.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Opening the environment</h1> -<p>Creating transaction-protected applications using the Berkeley DB library is -quite easy. Applications first use <a href="../../api_c/env_open.html">DB_ENV->open</a> to initialize -the database environment. Transaction-protected applications normally -require all four Berkeley DB subsystems, so the <a href="../../api_c/env_open.html#DB_INIT_MPOOL">DB_INIT_MPOOL</a>, -<a href="../../api_c/env_open.html#DB_INIT_LOCK">DB_INIT_LOCK</a>, <a href="../../api_c/env_open.html#DB_INIT_LOG">DB_INIT_LOG</a>, and <a href="../../api_c/env_open.html#DB_INIT_TXN">DB_INIT_TXN</a> flags -should be specified. -<p>Once the application has called <a href="../../api_c/env_open.html">DB_ENV->open</a>, it opens its -databases within the environment. Once the databases are opened, the -application makes changes to the databases inside of transactions. Each -set of changes that entails a unit of work should be surrounded by the -appropriate <a href="../../api_c/txn_begin.html">DB_ENV->txn_begin</a>, <a href="../../api_c/txn_commit.html">DB_TXN->commit</a>, and <a href="../../api_c/txn_abort.html">DB_TXN->abort</a> -calls. The Berkeley DB access methods will make the appropriate calls into -the Lock, Log and Memory Pool subsystems in order to guarantee -transaction semantics. When the application is ready to exit, all -outstanding transactions should have been committed or aborted. -<p>Databases accessed by a transaction must not be closed during the -transaction. Once all outstanding transactions are finished, all open -Berkeley DB files should be closed. When the Berkeley DB database files have been -closed, the environment should be closed by calling -<a href="../../api_c/env_close.html">DB_ENV->close</a>. -<p>The following code fragment creates the database environment directory -then opens the environment, running recovery. Our <a href="../../api_c/env_class.html">DB_ENV</a> -database environment handle is declared to be free-threaded using the -<a href="../../api_c/env_open.html#DB_THREAD">DB_THREAD</a> flag, and so may be used by any number of threads that -we may subsequently create. -<p><blockquote><pre>#include <sys/types.h> -#include <sys/stat.h> -<p> -#include <errno.h> -#include <stdarg.h> -#include <stdlib.h> -#include <string.h> -#include <unistd.h> -<p> -#include <db.h> -<p> -#define ENV_DIRECTORY "TXNAPP" -<p> -void env_dir_create(void); -void env_open(DB_ENV **); -<p> -int -main(int argc, char *argv) -{ - extern char *optarg; - extern int optind; - DB *db_cats, *db_color, *db_fruit; - DB_ENV *dbenv; - int ch; -<p> - while ((ch = getopt(argc, argv, "")) != EOF) - switch (ch) { - case '?': - default: - usage(); - } - argc -= optind; - argv += optind; -<p> - env_dir_create(); - env_open(&dbenv); -<p> - return (0); -} -<p> -void -env_dir_create() -{ - struct stat sb; -<p> - /* - * If the directory exists, we're done. We do not further check - * the type of the file, DB will fail appropriately if it's the - * wrong type. - */ - if (stat(ENV_DIRECTORY, &sb) == 0) - return; -<p> - /* Create the directory, read/write/access owner only. */ - if (mkdir(ENV_DIRECTORY, S_IRWXU) != 0) { - fprintf(stderr, - "txnapp: mkdir: %s: %s\n", ENV_DIRECTORY, strerror(errno)); - exit (1); - } -} -<p> -void -env_open(DB_ENV **dbenvp) -{ - DB_ENV *dbenv; - int ret; -<p> - /* Create the environment handle. */ - if ((ret = db_env_create(&dbenv, 0)) != 0) { - fprintf(stderr, - "txnapp: db_env_create: %s\n", db_strerror(ret)); - exit (1); - } -<p> - /* Set up error handling. */ - dbenv->set_errpfx(dbenv, "txnapp"); -<p> - /* - * Open a transactional environment: - * create if it doesn't exist - * free-threaded handle - * run recovery - * read/write owner only - */ - if ((ret = dbenv->open(dbenv, ENV_DIRECTORY, - DB_CREATE | DB_INIT_LOCK | DB_INIT_LOG | - DB_INIT_MPOOL | DB_INIT_TXN | DB_RECOVER | DB_THREAD, - S_IRUSR | S_IWUSR)) != 0) { - (void)dbenv->close(dbenv, 0); - dbenv->err(dbenv, ret, "dbenv->open: %s", ENV_DIRECTORY); - exit (1); - } -<p> - *dbenvp = dbenv; -}</pre></blockquote> -<p>After running this initial program, we can use the <a href="../../utility/db_stat.html">db_stat</a> -utility to display the contents of the environment directory: -<p><blockquote><pre>prompt> db_stat -e -h TXNAPP -3.2.1 Environment version. -120897 Magic number. -0 Panic value. -1 References. -6 Locks granted without waiting. -0 Locks granted after waiting. -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= -Mpool Region: 4. -264KB Size (270336 bytes). --1 Segment ID. -1 Locks granted without waiting. -0 Locks granted after waiting. -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= -Log Region: 3. -96KB Size (98304 bytes). --1 Segment ID. -3 Locks granted without waiting. -0 Locks granted after waiting. -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= -Lock Region: 2. -240KB Size (245760 bytes). --1 Segment ID. -1 Locks granted without waiting. -0 Locks granted after waiting. -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= -Txn Region: 5. -8KB Size (8192 bytes). --1 Segment ID. -1 Locks granted without waiting. -0 Locks granted after waiting.</pre></blockquote> -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/transapp/app.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/transapp/data_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/libdb/docs/ref/transapp/faq.html b/libdb/docs/ref/transapp/faq.html deleted file mode 100644 index fbb74ddf7..000000000 --- a/libdb/docs/ref/transapp/faq.html +++ /dev/null @@ -1,95 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Transaction FAQ</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Berkeley DB Transactional Data Store Applications</dl></h3></td> -<td align=right><a href="../../ref/transapp/throughput.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/rep/intro.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Transaction FAQ</h1> -<p><ol> -<p><li><b>What should a transactional program do when an error occurs?</b> -<p>Any time an error occurs, such that a transactionally protected set of -operations cannot complete successfully, the transaction must be -aborted. While deadlock is by far the most common of these errors, -there are other possibilities; for example, running out of disk space -for the filesystem. In Berkeley DB transactional applications, there are -three classes of error returns: "expected" errors, "unexpected but -recoverable" errors, and a single "unrecoverable" error. Expected -errors are errors like <a href="../../ref/program/errorret.html#DB_NOTFOUND">DB_NOTFOUND</a>, which indicates that a -searched-for key item is not present in the database. Applications may -want to explicitly test for and handle this error, or, in the case where -the absence of a key implies the enclosing transaction should fail, -simply call <a href="../../api_c/txn_abort.html">DB_TXN->abort</a>. Unexpected but recoverable errors are -errors like <a href="../../ref/program/errorret.html#DB_LOCK_DEADLOCK">DB_LOCK_DEADLOCK</a>, which indicates that an operation -has been selected to resolve a deadlock, or a system error such as EIO, -which likely indicates that the filesystem has no available disk space. -Applications must immediately call <a href="../../api_c/txn_abort.html">DB_TXN->abort</a> when these returns -occur, as it is not possible to proceed otherwise. The only -unrecoverable error is <a href="../../ref/program/errorret.html#DB_RUNRECOVERY">DB_RUNRECOVERY</a>, which indicates that the -system must stop and recovery must be run. -<p><li><b>How can hot backups work? Can't you get an inconsistent picture -of the database when you copy it?</b> -<p>First, Berkeley DB is based on the technique of "write-ahead logging", which -means that before any change is made to a database, a log record is -written that describes the change. Further, Berkeley DB guarantees that the -log record that describes the change will always be written to stable -storage (that is, disk) before the database page where the change was -made is written to stable storage. Because of this guarantee, we know -that any change made to a database will appear either in just a log -file, or both the database and a log file, but never in just the -database. -<p>Second, you can always create a consistent and correct database based -on the log files and the databases from a database environment. So, -during a hot backup, we first make a copy of the databases and then a -copy of the log files. The tricky part is that there may be pages in -the database that are related for which we won't get a consistent -picture during this copy. For example, let's say that we copy pages -1-4 of the database, and then are swapped out. For whatever reason -(perhaps because we needed to flush pages from the cache, or because of -a checkpoint), the database pages 1 and 5 are written. Then, the hot -backup process is re-scheduled, and it copies page 5. Obviously, we -have an inconsistent database snapshot, because we have a copy of page -1 from before it was written by the other thread of control, and a copy -of page 5 after it was written by the other thread. What makes this -work is the order of operations in a hot backup. Because of the -write-ahead logging guarantees, we know that any page written to the -database will first be referenced in the log. If we copy the database -first, then we can also know that any inconsistency in the database will -be described in the log files, and so we know that we can fix everything -up during recovery. -<p><li><b>How can I move a database from one transactional environment -into another?</b> -<p>Because database pages contain references to log records, databases -cannot be simply moved into different database environments. To move -a database into a different environment, dump and reload the database -before moving it. If the database is too large to dump and reload, the -database may be prepared in place by setting the first eight bytes of -each database page in the file to 0. -<p><li><b>I'm seeing the error "log_flush: LSN past current end-of-log", -what does that mean?</b> -<p>The most common cause of this error is that a system administrator has -removed all of the log files from a database environment. You should -shut down your database environment as gracefully as possible, first -flushing the database environment cache to disk, if that's possible. -Then, dump and reload your databases. If your databases are too large -to dump and reload, the database may be repaired in place by setting -the first eight bytes of each database page in the file to 0, but if -you do that, you must verify your databases before using them again. -(It is possible for the databases to be corrupted when this happens, -and the longer the application runs, the worse it can get.) -</ol> -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/transapp/throughput.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/rep/intro.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/libdb/docs/ref/transapp/filesys.html b/libdb/docs/ref/transapp/filesys.html deleted file mode 100644 index 419781e6a..000000000 --- a/libdb/docs/ref/transapp/filesys.html +++ /dev/null @@ -1,66 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Recovery and filesystem 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> -<a name="2"><!--meow--></a> -<table width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Berkeley DB Transactional Data Store Applications</dl></h3></td> -<td align=right><a href="../../ref/transapp/hotfail.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/transapp/reclimit.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Recovery and filesystem operations</h1> -<p>The Berkeley DB API supports creating, removing and renaming files. Creating -files is supported by the <a href="../../api_c/db_open.html">DB->open</a> method. Removing files is -supported by the <a href="../../api_c/env_dbremove.html">DB_ENV->dbremove</a> and <a href="../../api_c/db_remove.html">DB->remove</a> methods. -Renaming files is supported by the <a href="../../api_c/env_dbrename.html">DB_ENV->dbrename</a> and -<a href="../../api_c/db_rename.html">DB->rename</a> methods. (There are two methods for removing and renaming -files because one of the methods is transactionally protected and one -is not.) -<p>Berkeley DB does not permit specifying the <a href="../../api_c/db_open.html#DB_TRUNCATE">DB_TRUNCATE</a> flag when -opening a file in a transaction-protected environment. This is an -implicit file deletion, but one that does not always require the same -operating system file permissions as deleting and creating a file do. -<p>If you have changed the name of a file or deleted it outside of the -Berkeley DB library (for example, you explicitly removed a file using your -normal operating system utilities), then it is possible that recovery -will not be able to find a database to which the log refers. In this -case, <a href="../../utility/db_recover.html">db_recover</a> will produce a warning message, saying it was -unable to locate a file it expected to find. This message is only a -warning because the file may have been subsequently deleted as part of -normal database operations before the failure occurred, so is not -necessarily a problem. -<p>Generally, any filesystem operations that are performed outside the -Berkeley DB interface should be performed at the same time as making a -snapshot of the database. To perform filesystem operations correctly, -do the following: -<p><ol> -<p><li>Cleanly shut down database operations. -<p>To shut down database operations cleanly, all applications accessing -the database environment must be shut down and a transaction checkpoint -must be taken. If the applications are not implemented so they can be -shut down gracefully (that is, closing all references to the database -environment), recovery must be performed after all applications have -been killed to ensure that the underlying databases are consistent on -disk. -<p><li>Perform the filesystem operations; for example, remove or rename one or -more files. -<p><li>Make an archival snapshot of the database. -<p>Although this step is not strictly necessary, it is strongly -recommended. If this step is not performed, recovery from catastrophic -failure will require that recovery first be performed up to the time of -the filesystem operations, the filesystem operations be redone, and then -recovery be performed from the filesystem operations forward. -<p><li>Restart the database applications. -</ol> -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/transapp/hotfail.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/transapp/reclimit.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/libdb/docs/ref/transapp/hotfail.html b/libdb/docs/ref/transapp/hotfail.html deleted file mode 100644 index e6d84a5bc..000000000 --- a/libdb/docs/ref/transapp/hotfail.html +++ /dev/null @@ -1,83 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Hot failover</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Berkeley DB Transactional Data Store Applications</dl></h3></td> -<td align=right><a href="../../ref/transapp/recovery.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/transapp/filesys.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Hot failover</h1> -<p>For some applications, it may be useful to periodically snapshot the -database environment for use as a hot failover should the primary system -fail. The following steps can be taken to keep a backup environment in -close synchrony with an active environment. The active environment is -entirely unaffected by these procedures, and both read and write -operations are allowed during all steps described here. -<p><ol> -<p><li>Run <a href="../../utility/db_archive.html">db_archive</a> <b>-s</b> in the active environment to -identify all of the active environment's database files, and copy them -to the backup directory. -<p>If the database files are stored in a separate directory from the other -Berkeley DB files, it may be simpler to copy the directory itself instead of -the individual files (see <a href="../../api_c/env_set_data_dir.html">DB_ENV->set_data_dir</a> for additional -information). <b>Note: if any of the database files did not have -an open <a href="../../api_c/db_class.html">DB</a> handle during the lifetime of the current log files, -<a href="../../utility/db_archive.html">db_archive</a> will not list them in its output!</b> This is another -reason it may be simpler to use a separate database file directory and -copy the entire directory instead of archiving only the files listed by -<a href="../../utility/db_archive.html">db_archive</a>. -<p><li>Remove all existing log files from the backup directory. -<p><li>Run <a href="../../utility/db_archive.html">db_archive</a> <b>-l</b> in the active environment to -identify all of the active environment's log files, and copy them to -the backup directory. -<p><li>Run <a href="../../utility/db_recover.html">db_recover</a> <b>-c</b> in the backup directory to -catastrophically recover the copied environment. -</ol> -<p>Steps 2, 3 and 4 may be repeated as often as you like. If Step 1 (the -initial copy of the database files) is repeated, then Steps 2, 3 and 4 -<b>must</b> be performed at least once in order to ensure a consistent -database environment snapshot. -<p>These procedures must be integrated with your other archival procedures, -of course. If you are periodically removing log files from your active -environment, you must be sure to copy them to the backup directory -before removing them from the active directory. Not copying a log file -to the backup directory and subsequently running recovery with it -present may leave the backup snapshot of the environment corrupted. A -simple way to ensure this never happens is to archive the log files in -Step 2 as you remove them from the backup directory, and move inactive -log files from your active environment into your backup directory -(rather than copying them), in Step 3. The following steps describe -this procedure in more detail: -<p><ol> -<p><li>Run <a href="../../utility/db_archive.html">db_archive</a> <b>-s</b> in the active environment to -identify all of the active environment's database files, and copy them -to the backup directory. -<p><li>Archive all existing log files from the backup directory, moving them -to a backup device such as CD-ROM, alternate disk, or tape. -<p><li>Run <a href="../../utility/db_archive.html">db_archive</a> (without any option) in the active environment -to identify all of the log files in the active environment that are no -longer in use, and <b>move</b> them to the backup directory. -<p><li>Run <a href="../../utility/db_archive.html">db_archive</a> <b>-l</b> in the active environment to -identify all of the remaining log files in the active environment, and -<b>copy</b> the log files to the backup directory. -<p><li>Run <a href="../../utility/db_recover.html">db_recover</a> <b>-c</b> in the backup directory to -catastrophically recover the copied environment. -</ol> -<p>As before, steps 2, 3, 4 and 5 may be repeated as often as you like. -If Step 1 (the initial copy of the database files) is repeated, then -Steps 2 through 5 <b>must</b> be performed at least once in order to -ensure a consistent database environment snapshot. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/transapp/recovery.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/transapp/filesys.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/libdb/docs/ref/transapp/inc.html b/libdb/docs/ref/transapp/inc.html deleted file mode 100644 index d22887c0f..000000000 --- a/libdb/docs/ref/transapp/inc.html +++ /dev/null @@ -1,166 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Isolation</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Berkeley DB Transactional Data Store Applications</dl></h3></td> -<td align=right><a href="../../ref/transapp/atomicity.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/transapp/read.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Isolation</h1> -<p>The third reason listed for using transactions was <i>isolation</i>. -Consider an application suite in which multiple threads of control -(multiple processes or threads in one or more processes) are changing -the values associated with a key in one or more databases. Specifically, -they are taking the current value, incrementing it, and then storing it -back into the database. -<p>Such an application requires isolation. Because we want to change a value -in the database, we must make sure that after we read it, no other thread -of control modifies it. For example, assume that both thread #1 and -thread #2 are doing similar operations in the database, where thread #1 -is incrementing records by 3, and thread #2 is incrementing records by -5. We want to increment the record by a total of 8. If the operations -interleave in the right (well, wrong) order, that is not what will -happen: -<p><blockquote><pre>thread #1 <b>read</b> record: the value is 2 -thread #2 <b>read</b> record: the value is 2 -thread #2 <b>write</b> record + 5 back into the database (new value 7) -thread #1 <b>write</b> record + 3 back into the database (new value 5)</pre></blockquote> -<p>As you can see, instead of incrementing the record by a total of 8, -we've incremented it only by 3 because thread #1 overwrote thread #2's -change. By wrapping the operations in transactions, we ensure that this -cannot happen. In a transaction, when the first thread reads the -record, locks are acquired that will not be released until the -transaction finishes, guaranteeing that all other readers and writers -will block, waiting for the first thread's transaction to complete (or -to be aborted). -<p>Here is an example function that does transaction-protected increments -on database records to ensure isolation: -<p><blockquote><pre>int -main(int argc, char *argv) -{ - extern char *optarg; - extern int optind; - DB *db_cats, *db_color, *db_fruit; - DB_ENV *dbenv; - pthread_t ptid; - int ch; -<p> - while ((ch = getopt(argc, argv, "")) != EOF) - switch (ch) { - case '?': - default: - usage(); - } - argc -= optind; - argv += optind; -<p> - env_dir_create(); - env_open(&dbenv); -<p> - /* Open database: Key is fruit class; Data is specific type. */ - db_open(dbenv, &db_fruit, "fruit", 0); -<p> - /* Open database: Key is a color; Data is an integer. */ - db_open(dbenv, &db_color, "color", 0); -<p> - /* - * Open database: - * Key is a name; Data is: company name, cat breeds. - */ - db_open(dbenv, &db_cats, "cats", 1); -<p> - add_fruit(dbenv, db_fruit, "apple", "yellow delicious"); -<p> -<b> add_color(dbenv, db_color, "blue", 0); - add_color(dbenv, db_color, "blue", 3);</b> -<p> - return (0); -} -<p> -<b>int -add_color(DB_ENV *dbenv, DB *dbp, char *color, int increment) -{ - DBT key, data; - DB_TXN *tid; - int fail, original, ret, t_ret; - char buf64; -<p> - /* Initialization. */ - memset(&key, 0, sizeof(key)); - key.data = color; - key.size = strlen(color); - memset(&data, 0, sizeof(data)); - data.flags = DB_DBT_MALLOC; -<p> - for (fail = 0;;) { - /* Begin the transaction. */ - if ((ret = dbenv->txn_begin(dbenv, NULL, &tid, 0)) != 0) { - dbenv->err(dbenv, ret, "DB_ENV->txn_begin"); - exit (1); - } -<p> - /* - * Get the key. If it exists, we increment the value. If it - * doesn't exist, we create it. - */ - switch (ret = dbp->get(dbp, tid, &key, &data, 0)) { - case 0: - original = atoi(data.data); - break; - case DB_LOCK_DEADLOCK: - default: - /* Retry the operation. */ - if ((t_ret = tid->abort(tid)) != 0) { - dbenv->err(dbenv, t_ret, "DB_TXN->abort"); - exit (1); - } - if (++fail == MAXIMUM_RETRY) - return (ret); - continue; - case DB_NOTFOUND: - original = 0; - break; - } - if (data.data != NULL) - free(data.data); -<p> - /* Create the new data item. */ - (void)snprintf(buf, sizeof(buf), "%d", original + increment); - data.data = buf; - data.size = strlen(buf) + 1; -<p> - /* Store the new value. */ - switch (ret = dbp->put(dbp, tid, &key, &data, 0)) { - case 0: - /* Success: commit the change. */ - if ((ret = tid->commit(tid, 0)) != 0) { - dbenv->err(dbenv, ret, "DB_TXN->commit"); - exit (1); - } - return (0); - case DB_LOCK_DEADLOCK: - default: - /* Retry the operation. */ - if ((t_ret = tid->abort(tid)) != 0) { - dbenv->err(dbenv, t_ret, "DB_TXN->abort"); - exit (1); - } - if (++fail == MAXIMUM_RETRY) - return (ret); - break; - } - } -}</b></pre></blockquote> -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/transapp/atomicity.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/transapp/read.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/libdb/docs/ref/transapp/intro.html b/libdb/docs/ref/transapp/intro.html deleted file mode 100644 index 2faa48eb9..000000000 --- a/libdb/docs/ref/transapp/intro.html +++ /dev/null @@ -1,42 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Berkeley DB Transactional Data Store applications</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Berkeley DB Transactional Data Store Applications</dl></h3></td> -<td align=right><a href="../../ref/cam/intro.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/transapp/why.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Berkeley DB Transactional Data Store applications</h1> -<p>It is difficult to write a useful transactional tutorial and still keep -within reasonable bounds of documentation; that is, without writing a -book on transactional programming. We have two goals in this section: -to familiarize readers with the transactional interfaces of Berkeley DB and -to provide code building blocks that will be useful for creating -applications. -<p>We have not attempted to present this information using a real-world -application. First, transactional applications are often complex and -time-consuming to explain. Also, one of our goals is to give you an -understanding of the wide variety of tools Berkeley DB makes available to you, -and no single application would use most of the interfaces included in -the Berkeley DB library. For these reasons, we have chosen to simply present -the Berkeley DB data structures and programming solutions, using examples that -differ from page to page. All the examples are included in a standalone -program you can examine, modify, and run; and from which you will be able -to extract code blocks for your own applications. Fragments of the -program will be presented throughout this chapter, and the complete text -of the <a href="transapp.cs">example program</a> for IEEE/ANSI Std 1003.1 (POSIX) -standard systems is included in the Berkeley DB distribution. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/cam/intro.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/transapp/why.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/libdb/docs/ref/transapp/logfile.html b/libdb/docs/ref/transapp/logfile.html deleted file mode 100644 index 9ae85f9ed..000000000 --- a/libdb/docs/ref/transapp/logfile.html +++ /dev/null @@ -1,100 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Log file removal</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Berkeley DB Transactional Data Store Applications</dl></h3></td> -<td align=right><a href="../../ref/transapp/archival.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/transapp/recovery.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Log file removal</h1> -<p>The fourth component of the infrastructure, log file removal, concerns -the ongoing disk consumption of the database log files. Depending on -the rate at which the application writes to the databases and the -available disk space, the number of log files may increase quickly -enough so that disk space will be a resource problem. For this reason, -you will periodically want to remove log files in order to conserve disk -space. This procedure is distinct from database and log file archival -for catastrophic recovery, and you cannot remove the current log files -simply because you have created a database snapshot or copied log files -to archival media. -<p>Log files may be removed at any time, as long as: -<p><ul type=disc> -<li>the log file is not involved in an active transaction. -<li>a checkpoint has been written subsequent to the log file's -creation. -<li>the log file is not the only log file in the environment. -</ul> -<p>Obviously, if you are preparing for catastrophic failure, you will want -to copy the log files to archival media before you remove them. -<p>To remove log files, take the following steps: -<p><ol> -<p><li>If you are concerned with catastrophic failure, first copy the log files -to backup media as described in -<a href="archival.html">Archival for catastrophic recovery</a>. -<p><li>Run <a href="../../utility/db_archive.html">db_archive</a> without options to identify all the log files -that are no longer in use (for example, are no longer involved in an -active transaction.) -<p><li>Remove those log files from the system. -</ol> -<p>The functionality provided by the <a href="../../utility/db_archive.html">db_archive</a> utility is also -available directly from the Berkeley DB library. The following code fragment -removes log files no longer needed by the database environment: -<p><blockquote><pre>int -main(int argc, char *argv) -{ -<b> /* Start a logfile removal thread. */ - if ((ret = pthread_create( - &ptid, NULL, logfile_thread, (void *)dbenv)) != 0) { - fprintf(stderr, - "txnapp: failed spawning log file removal thread: %s\n", - strerror(ret)); - exit (1); - }</b> -} -<p> -<b>void * -logfile_thread(void *arg) -{ - DB_ENV *dbenv; - int ret; - char **begin, **list; -<p> - dbenv = arg; - dbenv->errx(dbenv, - "Log file removal thread: %lu", (u_long)pthread_self()); -<p> - /* Check once every 5 minutes. */ - for (;; sleep(300)) { - /* Get the list of log files. */ - if ((ret = dbenv->log_archive(dbenv, &list, DB_ARCH_ABS)) != 0) { - dbenv->err(dbenv, ret, "DB_ENV->log_archive"); - exit (1); - } -<p> - /* Remove the log files. */ - if (list != NULL) { - for (begin = list; *list != NULL; ++list) - if ((ret = remove(*list)) != 0) { - dbenv->err(dbenv, - ret, "remove %s", *list); - exit (1); - } - free (begin); - } - } - /* NOTREACHED */ -}</b></pre></blockquote> -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/transapp/archival.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/transapp/recovery.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/libdb/docs/ref/transapp/nested.html b/libdb/docs/ref/transapp/nested.html deleted file mode 100644 index 4d5e3ada3..000000000 --- a/libdb/docs/ref/transapp/nested.html +++ /dev/null @@ -1,66 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Nested transactions</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Berkeley DB Transactional Data Store Applications</dl></h3></td> -<td align=right><a href="../../ref/transapp/cursor.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/transapp/admin.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Nested transactions</h1> -<p>Berkeley DB provides support for nested transactions. Nested transactions -allow an application to decompose a large or long-running transaction -into smaller units that may be independently aborted. -<p>Normally, when beginning a transaction, the application will pass a NULL -value for the parent argument to <a href="../../api_c/txn_begin.html">DB_ENV->txn_begin</a>. If, however, the -parent argument is a <a href="../../api_c/txn_class.html">DB_TXN</a> handle, the newly created transaction -will be treated as a nested transaction within the parent. Transactions -may nest arbitrarily deeply. For the purposes of this discussion, -transactions created with a parent identifier will be called -<i>child transactions</i>. -<p>Once a transaction becomes a parent, as long as any of its child -transactions are unresolved (that is, they have neither committed nor -aborted), the parent may not issue any Berkeley DB calls except to begin more -child transactions, or to commit or abort. For example, it may not -issue any access method or cursor calls. After all of a parent's -children have committed or aborted, the parent may again request -operations on its own behalf. -<p>The semantics of nested transactions are as follows. When a child -transaction is begun, it inherits all the locks of its parent. This -means that the child will never block waiting on a lock held by its -parent. Further, locks held by two children of the same parent will -also conflict. To make this concrete, consider the following set of -transactions and lock acquisitions. -<p>Transaction T1 is the parent transaction. It acquires a write lock on -item A and then begins two child transactions: C1 and C2. C1 also -wishes to acquire a write lock on A; this succeeds. If C2 attempts to -acquire a write lock on A, it will block until C1 releases the lock, at -which point it will succeed. Now, let's say that C1 acquires a write -lock on B. If C2 now attempts to obtain a lock on B, it will block. -However, let's now assume that C1 commits. Its locks are -anti-inherited, which means they are given to T1, so T1 will now hold -a lock on B. At this point, C2 would be unblocked and would then -acquire a lock on B. -<p>Child transactions are entirely subservient to their parent transaction. -They may abort, undoing their operations regardless of the eventual fate -of the parent. However, even if a child transaction commits, if its -parent transaction is eventually aborted, the child's changes are undone -and the child's transaction is effectively aborted. Any child -transactions that are not yet resolved when the parent commits or aborts -are resolved based on the parent's resolution -- committing if the -parent commits and aborting if the parent aborts. Any child -transactions that are not yet resolved when the parent prepares are also -prepared. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/transapp/cursor.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/transapp/admin.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/libdb/docs/ref/transapp/put.html b/libdb/docs/ref/transapp/put.html deleted file mode 100644 index 621cc4746..000000000 --- a/libdb/docs/ref/transapp/put.html +++ /dev/null @@ -1,205 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Recoverability and deadlock handling</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Berkeley DB Transactional Data Store Applications</dl></h3></td> -<td align=right><a href="../../ref/transapp/data_open.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/transapp/atomicity.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Recoverability and deadlock handling</h1> -<p>The first reason listed for using transactions was recoverability. Any -logical change to a database may require multiple changes to underlying -data structures. For example, modifying a record in a Btree may require -leaf and internal pages to split, so a single <a href="../../api_c/db_put.html">DB->put</a> method -call can potentially require that multiple physical database pages be -written. If only some of those pages are written and then the system -or application fails, the database is left inconsistent and cannot be -used until it has been recovered; that is, until the partially completed -changes have been undone. -<p><i>Write-ahead-logging</i> is the term that describes the underlying -implementation that Berkeley DB uses to ensure recoverability. What it means -is that before any change is made to a database, information about the -change is written to a database log. During recovery, the log is read, -and databases are checked to ensure that changes described in the log -for committed transactions appear in the database. Changes that appear -in the database but are related to aborted or unfinished transactions -in the log are undone from the database. -<p>For recoverability after application or system failure, operations that -modify the database must be protected by transactions. More -specifically, operations are not recoverable unless a transaction is -begun and each operation is associated with the transaction via the -Berkeley DB interfaces, and then the transaction successfully committed. This -is true even if logging is turned on in the database environment. -<p>Here is an example function that updates a record in a database in a -transactionally protected manner. The function takes a key and data -items as arguments and then attempts to store them into the database. -<p><blockquote><pre>int -main(int argc, char *argv) -{ - extern char *optarg; - extern int optind; - DB *db_cats, *db_color, *db_fruit; - DB_ENV *dbenv; - pthread_t ptid; - int ch; -<p> - while ((ch = getopt(argc, argv, "")) != EOF) - switch (ch) { - case '?': - default: - usage(); - } - argc -= optind; - argv += optind; -<p> - env_dir_create(); - env_open(&dbenv); -<p> - /* Open database: Key is fruit class; Data is specific type. */ - db_open(dbenv, &db_fruit, "fruit", 0); -<p> - /* Open database: Key is a color; Data is an integer. */ - db_open(dbenv, &db_color, "color", 0); -<p> - /* - * Open database: - * Key is a name; Data is: company name, cat breeds. - */ - db_open(dbenv, &db_cats, "cats", 1); -<p> -<b> add_fruit(dbenv, db_fruit, "apple", "yellow delicious");</b> -<p> - return (0); -} -<p> -<b>int -add_fruit(DB_ENV *dbenv, DB *db, char *fruit, char *name) -{ - DBT key, data; - DB_TXN *tid; - int fail, ret, t_ret; -<p> - /* Initialization. */ - memset(&key, 0, sizeof(key)); - memset(&data, 0, sizeof(data)); - key.data = fruit; - key.size = strlen(fruit); - data.data = name; - data.size = strlen(name); -<p> - for (fail = 0;;) { - /* Begin the transaction. */ - if ((ret = dbenv->txn_begin(dbenv, NULL, &tid, 0)) != 0) { - dbenv->err(dbenv, ret, "DB_ENV->txn_begin"); - exit (1); - } -<p> - /* Store the value. */ - switch (ret = db->put(db, tid, &key, &data, 0)) { - case 0: - /* Success: commit the change. */ - if ((ret = tid->commit(tid, 0)) != 0) { - dbenv->err(dbenv, ret, "DB_TXN->commit"); - exit (1); - } - return (0); - case DB_LOCK_DEADLOCK: - default: - /* Retry the operation. */ - if ((t_ret = tid->abort(tid)) != 0) { - dbenv->err(dbenv, t_ret, "DB_TXN->abort"); - exit (1); - } - if (++fail == MAXIMUM_RETRY) - return (ret); - break; - } - } -}</b></pre></blockquote> -<p>Berkeley DB also uses transactions to recover from deadlock. Database -operations (that is, any call to a function underlying the handles -returned by <a href="../../api_c/db_open.html">DB->open</a> and <a href="../../api_c/db_cursor.html">DB->cursor</a>) are usually -performed on behalf of a unique locker. Transactions can be used to -perform multiple calls on behalf of the same locker within a single -thread of control. For example, consider the case in which a cursor -scan locates a record and then accesses some other item in the database, -based on that record. If these operations are done using the handle's -default locker IDs, they may conflict. If the locks are obtained on -behalf of a transaction, using the transaction's locker ID instead of -the handle's locker ID, the operations will not conflict. -<p>There is a new error return in this function that you may not have seen -before. In transactional (not Concurrent Data Store) applications -supporting both readers and writers, or just multiple writers, Berkeley DB -functions have an additional possible error return: -<a href="../../ref/program/errorret.html#DB_LOCK_DEADLOCK">DB_LOCK_DEADLOCK</a>. This means that two thread of controls -deadlocked, and the thread receiving the <a href="../../ref/program/errorret.html#DB_LOCK_DEADLOCK">DB_LOCK_DEADLOCK</a> error -return has been selected to discard its locks in order to resolve the -problem. When an application receives a <a href="../../ref/program/errorret.html#DB_LOCK_DEADLOCK">DB_LOCK_DEADLOCK</a> -return, the correct action is to close any cursors involved in the -operation and abort any enclosing transaction. In the sample code, any -time the <a href="../../api_c/db_put.html">DB->put</a> method returns <a href="../../ref/program/errorret.html#DB_LOCK_DEADLOCK">DB_LOCK_DEADLOCK</a>, -<a href="../../api_c/txn_abort.html">DB_TXN->abort</a> is called (which releases the transaction's Berkeley DB -resources and undoes any partial changes to the databases), and then -the transaction is retried from the beginning. -<p>There is no requirement that the transaction be attempted again, but -that is a common course of action for applications. Applications may -want to set an upper bound on the number of times an operation will be -retried because some operations on some data sets may simply be unable -to succeed. For example, updating all of the pages on a large Web site -during prime business hours may simply be impossible because of the high -access rate to the database. -<p>The <a href="../../api_c/txn_abort.html">DB_TXN->abort</a> method is called in error cases other than deadlock. -Any time an error occurs, such that a transactionally protected set of -operations cannot complete successfully, the transaction must be -aborted. While deadlock is by far the most common of these errors, -there are other possibilities; for example, running out of disk space -for the filesystem. In Berkeley DB transactional applications, there are -three classes of error returns: "expected" errors, "unexpected but -recoverable" errors, and a single "unrecoverable" error. Expected -errors are errors like <a href="../../ref/program/errorret.html#DB_NOTFOUND">DB_NOTFOUND</a>, which indicates that a -searched-for key item is not present in the database. Applications may -want to explicitly test for and handle this error, or, in the case where -the absence of a key implies the enclosing transaction should fail, -simply call <a href="../../api_c/txn_abort.html">DB_TXN->abort</a>. Unexpected but recoverable errors are -errors like <a href="../../ref/program/errorret.html#DB_LOCK_DEADLOCK">DB_LOCK_DEADLOCK</a>, which indicates that an operation -has been selected to resolve a deadlock, or a system error such as EIO, -which likely indicates that the filesystem has no available disk space. -Applications must immediately call <a href="../../api_c/txn_abort.html">DB_TXN->abort</a> when these returns -occur, as it is not possible to proceed otherwise. The only -unrecoverable error is <a href="../../ref/program/errorret.html#DB_RUNRECOVERY">DB_RUNRECOVERY</a>, which indicates that the -system must stop and recovery must be run. -<p>It is possible to simplify the above code in the case of a transaction -comprised entirely of a single database put or delete operation. The -<a href="../../api_c/db_put.html">DB->put</a> and <a href="../../api_c/db_del.html">DB->del</a> method (and other) calls support the -<a href="../../api_c/env_set_flags.html#DB_AUTO_COMMIT">DB_AUTO_COMMIT</a> flag that allows applications to implicitly wrap -the operation in a transaction. For example, with the -<a href="../../api_c/env_set_flags.html#DB_AUTO_COMMIT">DB_AUTO_COMMIT</a> flag, the above code could be more simply written -as: -<p><blockquote><pre><b> for (fail = 0; fail++ <= MAXIMUM_RETRY && (ret = - db->put(db, NULL, &key, &data, DB_AUTO_COMMIT)) == DB_LOCK_DEADLOCK;) - ; - return (ret == 0 ? 0 : 1);</b></pre></blockquote> -<p>Programmers should not attempt to enumerate all possible error returns -in their software. Instead, they should explicitly handle expected -returns and default to aborting the transaction for the rest. It is -entirely the choice of the programmer whether to check for -<a href="../../ref/program/errorret.html#DB_RUNRECOVERY">DB_RUNRECOVERY</a> explicitly or not -- attempting new Berkeley DB -operations after <a href="../../ref/program/errorret.html#DB_RUNRECOVERY">DB_RUNRECOVERY</a> is returned does not worsen the -situation. Alternatively, using the <a href="../../api_c/env_set_paniccall.html">DB_ENV->set_paniccall</a> method to -handle an unrecoverable error and simply doing some number of -abort-and-retry cycles for any unexpected Berkeley DB or system error in the -mainline code often results in the simplest and cleanest application -code. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/transapp/data_open.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/transapp/atomicity.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/libdb/docs/ref/transapp/read.html b/libdb/docs/ref/transapp/read.html deleted file mode 100644 index ccd522420..000000000 --- a/libdb/docs/ref/transapp/read.html +++ /dev/null @@ -1,56 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Degrees of isolation</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Berkeley DB Transactional Data Store Applications</dl></h3></td> -<td align=right><a href="../../ref/transapp/inc.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/transapp/cursor.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Degrees of isolation</h1> -<a name="2"><!--meow--></a> -<p>Transactions can be isolated from each other to different degrees. -<i>Repeatable reads</i> provide the most isolation, and mean that, -for the life of the transaction, every time a thread of control reads -a data item, it will be unchanged from its previous value (assuming, of -course, the thread of control does not itself modify the item). Berkeley DB -enforces repeatable reads whenever database reads are wrapped in -transactions. -<p>Most applications do not need to enclose reads in transactions, and when -possible, transactionally protected reads should be avoided as they can -cause performance problems. For example, a transactionally protected -cursor sequentially reading each key/data pair in a database, will -acquire a read lock on most of the pages in the database and so will -gradually block all write operations on the databases until the -transaction commits or aborts. Note, however, that if there are update -transactions present in the application, the read operations must still -use locking, and must be prepared to repeat any operation (possibly -closing and reopening a cursor) that fails with a return value of -<a href="../../ref/program/errorret.html#DB_LOCK_DEADLOCK">DB_LOCK_DEADLOCK</a>. Applications that need repeatable reads are -ones that require the ability to repeatedly access a data item knowing -that it will not have changed (for example, an operation modifying a -data item based on its existing value). -<a name="3"><!--meow--></a> -<a name="4"><!--meow--></a> -<p>Berkeley DB optionally supports reading uncommitted data; that is, read -operations may request data which has been modified but not yet -committed by another transaction. This is done by first specifying the -<a href="../../api_c/db_open.html#DB_DIRTY_READ">DB_DIRTY_READ</a> flag when opening the underlying database, and -then specifying the <a href="../../api_c/db_open.html#DB_DIRTY_READ">DB_DIRTY_READ</a> flag when beginning a -transaction, opening a cursor, or performing a read operation. The -advantage of using <a href="../../api_c/db_open.html#DB_DIRTY_READ">DB_DIRTY_READ</a> is that read operations will -not block when another transaction holds a write lock on the requested -data; the disadvantage is that read operations may return data that will -disappear should the transaction holding the write lock abort. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/transapp/inc.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/transapp/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/libdb/docs/ref/transapp/reclimit.html b/libdb/docs/ref/transapp/reclimit.html deleted file mode 100644 index 24e6fd645..000000000 --- a/libdb/docs/ref/transapp/reclimit.html +++ /dev/null @@ -1,148 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Berkeley DB recoverability</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Berkeley DB Transactional Data Store Applications</dl></h3></td> -<td align=right><a href="../../ref/transapp/filesys.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/transapp/tune.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Berkeley DB recoverability</h1> -<p>Berkeley DB recovery is based on write-ahead logging. This means that -when a change is made to a database page, a description of the change is -written into a log file. This description in the log file is guaranteed -to be written to stable storage before the database pages that were -changed are written to stable storage. This is the fundamental feature -of the logging system that makes durability and rollback work. -<p>If the application or system crashes, the log is reviewed during -recovery. Any database changes described in the log that were part of -committed transactions and that were never written to the actual -database itself are written to the database as part of recovery. Any -database changes described in the log that were never committed and that -were written to the actual database itself are backed-out of the -database as part of recovery. This design allows the database to be -written lazily, and only blocks from the log file have to be forced to -disk as part of transaction commit. -<p>There are two interfaces that are a concern when considering Berkeley DB -recoverability: -<p><ol> -<p><li>The interface between Berkeley DB and the operating system/filesystem. -<li>The interface between the operating system/filesystem and the -underlying stable storage hardware. -</ol> -<p>Berkeley DB uses the operating system interfaces and its underlying filesystem -when writing its files. This means that Berkeley DB can fail if the underlying -filesystem fails in some unrecoverable way. Otherwise, the interface -requirements here are simple: The system call that Berkeley DB uses to flush -data to disk (normally <b>fsync</b>(2)), must guarantee that all the -information necessary for a file's recoverability has been written to -stable storage before it returns to Berkeley DB, and that no possible -application or system crash can cause that file to be unrecoverable. -<p>In addition, Berkeley DB implicitly uses the interface between the operating -system and the underlying hardware. The interface requirements here are -not as simple. -<p>First, it is necessary to consider the underlying page size of the Berkeley DB -databases. The Berkeley DB library performs all database writes using the -page size specified by the application, and Berkeley DB assumes pages are written -atomically. This means that if the operating system performs filesystem -I/O in blocks of different sizes than the database page size, it may -increase the possibility for database corruption. For example, assume -that Berkeley DB is writing 32KB pages for a database, and the operating -system does filesystem I/O in 16KB blocks. If the operating system -writes the first 16KB of the database page successfully, but crashes -before being able to write the second 16KB of the database, the database -has been corrupted and this corruption may or may not be detected during -recovery. For this reason, it may be important to select database page -sizes that will be written as single block transfers by the underlying -operating system. If you do not select a page size that the underlying -operating system will write as a single block, you may want to configure -the database to use checksums (see the <a href="../../api_c/db_set_flags.html#DB_CHKSUM_SHA1">DB_CHKSUM_SHA1</a> flag for -more information). By configuring checksums, you guarantee this kind -of corruption will be detected at the expense of the CPU required to -generate the checksums. When such an error is detected, the only -course of recovery is to perform catastrophic recovery to restore the -database. -<p>Second, if you are copying database files (either as part of doing a -hot backup or creation of a hot failover area), there is an additional -question related to the page size of the Berkeley DB databases. You must copy -databases atomically, in units of the database page size. In other -words, the reads made by the copy program must not be interleaved with -writes by other threads of control, and the copy program must read the -databases in chunks that are a multiple of the underlying database page -size. Generally, this is not a problem, as operating systems already -make this guarantee and system utilities normally read in power-of-2 -sized chunks, which are larger than the largest possible Berkeley DB database -page size. -<p>However, we have seen one problem in this area because some releases of -Solaris implemented the cp utility using the mmap system call rather -than the read system call. Because the Solaris' mmap system call did -not make the same guarantee of read atomicity as the read system call, -using the cp utility could create corrupted copies of the databases. -Using the dd utility instead of the cp utility (and specifying an -appropriate block size), fixed the problem. If you plan to use a system -utility to copy database files, you may want to use a system call trace -utility (for example, ktrace or truss) to check for an I/O size smaller -or not a multiple of the database page size and system calls other than -read. -<p>Third, it is necessary to consider the behavior of the system's -underlying stable storage hardware. For example, consider a SCSI -controller that has been configured to cache data and return to the -operating system that the data has been written to stable storage, when, -in fact, it has only been written into the controller RAM cache. If -power is lost before the controller is able to flush its cache to disk, -and the controller cache is not stable (that is, the writes will not be -flushed to disk when power returns), the writes will be lost. If the -writes include database blocks, there is no loss because recovery will -correctly update the database. If the writes include log file blocks, -it is possible that transactions that were already committed may not -appear in the recovered database, although the recovered database will -be coherent after a crash. -<p>If the underlying hardware can fail in any way so that only part of the -block was written, the failure conditions are the same as those -described previously for an operating system failure that writes only -part of a logical database block. In such cases, configuring the -database for checksums will ensure the corruption is detected. -<p>For these reasons, it may be important to select hardware that does not -do partial writes and does not cache data writes (or does not return -that the data has been written to stable storage until it has either -been written to stable storage or the actual writing of all of the data -is guaranteed, barring catastrophic hardware failure -- that is, your -disk drive exploding). -<p>If the disk drive on which you are storing your databases explodes, you -can perform normal Berkeley DB catastrophic recovery, because it requires only -a snapshot of your databases plus the log files you have archived since -those snapshots were taken. In this case, you should lose no database -changes at all. -<p>If the disk drive on which you are storing your log files explodes, you -can also perform catastrophic recovery, but you will lose any database -changes made as part of transactions committed since your last archival -of the log files. Alternatively, if your database environment and -databases are still available after you lose the log file disk, you -should be able to dump your databases. However, you may see an -inconsistent snapshot of your data after doing the dump, because -changes that were part of transactions that were not yet committed -may appear in the database dump. Depending on the value of the data, -a reasonable alternative may be to perform both the database dump and -the catastrophic recovery and then compare the databases created by -the two methods. -<p>Regardless, for these reasons, storing your databases and log files on -different disks should be considered a safety measure as well as a -performance enhancement. -<p>Finally, you should be aware that Berkeley DB does not protect against all -cases of stable storage hardware failure, nor does it protect against -simple hardware misbehavior (for example, a disk controller writing -incorrect data to the disk). However, configuring the database for -checksums will ensure that any such corruption is detected. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/transapp/filesys.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/transapp/tune.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/libdb/docs/ref/transapp/recovery.html b/libdb/docs/ref/transapp/recovery.html deleted file mode 100644 index b2f61d2d9..000000000 --- a/libdb/docs/ref/transapp/recovery.html +++ /dev/null @@ -1,95 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Recovery procedures</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Berkeley DB Transactional Data Store Applications</dl></h3></td> -<td align=right><a href="../../ref/transapp/logfile.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/transapp/hotfail.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Recovery procedures</h1> -<p>The fifth component of the infrastructure, recovery procedures, concerns -the recoverability of the database. After any application or system -failure, there are two possible approaches to database recovery: -<p><ol> -<p><li>There is no need for recoverability, and all databases can be re-created -from scratch. Although these applications may still need transaction -protection for other reasons, recovery usually consists of removing the -Berkeley DB environment home directory and all files it contains, and then -restarting the application. -<p><li>It is necessary to recover information after system or application -failure. In this case, recovery processing must be performed on any -database environments that were active at the time of the failure. -Recovery processing involves running the <a href="../../utility/db_recover.html">db_recover</a> utility or -calling the <a href="../../api_c/env_open.html">DB_ENV->open</a> method with the <a href="../../api_c/env_open.html#DB_RECOVER">DB_RECOVER</a> or -<a href="../../api_c/env_open.html#DB_RECOVER_FATAL">DB_RECOVER_FATAL</a> flags. -<p>During recovery processing, all database changes made by aborted or -unfinished transactions are undone, and all database changes made by -committed transactions are redone, as necessary. Database applications -must not be restarted until recovery completes. After recovery -finishes, the environment is properly initialized so that applications -may be restarted. -</ol> -<p>If performing recovery, there are two types of recovery processing: -<i>normal</i> and <i>catastrophic</i>. Which you choose depends -on the source for the database and log files you are using to recover. -<p>If up-to-the-minute database and log files are accessible on a stable -filesystem, normal recovery is usually sufficient. Run the -<a href="../../utility/db_recover.html">db_recover</a> utility or call the <a href="../../api_c/env_open.html">DB_ENV->open</a> method specifying -the <a href="../../api_c/env_open.html#DB_RECOVER">DB_RECOVER</a> flag. Note this case never includes recovery -using archival snapshots of the database environment. For example, you -cannot archive databases and log files, restore the backup and then run -normal recovery -- you must always run catastrophic recovery when using -archived files. -<p>If the database or log files have been destroyed or corrupted, or normal -recovery fails, catastrophic recovery is required. For example, -catastrophic failure includes the case where the disk drive on which -the database or log files are stored has been physically destroyed, or -when the underlying filesystem is corrupted and the operating system's -normal filesystem checking procedures cannot bring that filesystem to -a consistent state. This is often difficult to detect, and a common -sign of the need for catastrophic recovery is when normal Berkeley DB recovery -procedures fail, or when checksum errors are displayed during normal -database procedures. When catastrophic recovery is necessary, take the -following steps: -<p><ol> -<p><li>Restore the most recent snapshots of the database and log files from -the backup media into the directory where recovery will be performed. -<p><li>If any log files were archived since the last snapshot was made, they -should be restored into the directory where recovery will be performed. -<p>If any log files are available from the database environment that failed -(for example, the disk holding the database files crashed, but the disk -holding the log files is fine), those log files should be copied into -the directory where recovery will be performed. -<p>Be sure to restore all log files in the order they were written. The -order is important because it's possible the same log file appears on -multiple backups, and you want to run recovery using the most recent -version of each log file. -<p><li>Run the <a href="../../utility/db_recover.html">db_recover</a> utility, specifying its <b>-c</b> option; -or call the <a href="../../api_c/env_open.html">DB_ENV->open</a> method, specifying the <a href="../../api_c/env_open.html#DB_RECOVER_FATAL">DB_RECOVER_FATAL</a> -flag. The catastrophic recovery process will review the logs and -database files to bring the environment databases to a consistent state -as of the time of the last uncorrupted log file that is found. It is -important to realize that only transactions committed before that date -will appear in the databases. -<p>It is possible to re-create the database in a location different from -the original by specifying appropriate pathnames to the <b>-h</b> -option of the <a href="../../utility/db_recover.html">db_recover</a> utility. In order for this to work -properly, it is important that your application refer to files by names -relative to the database home directory or the pathname(s) specified in -calls to <a href="../../api_c/env_set_data_dir.html">DB_ENV->set_data_dir</a>, instead of using full -pathnames. -</ol> -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/transapp/logfile.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/transapp/hotfail.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/libdb/docs/ref/transapp/term.html b/libdb/docs/ref/transapp/term.html deleted file mode 100644 index c95f52e72..000000000 --- a/libdb/docs/ref/transapp/term.html +++ /dev/null @@ -1,65 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Terminology</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Berkeley DB Transactional Data Store Applications</dl></h3></td> -<td align=right><a href="../../ref/transapp/why.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/transapp/app.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Terminology</h1> -<p>Here are some definitions that will be helpful in understanding -transactions: -<p><dl compact> -<p><dt>Thread of control<dd>Berkeley DB is indifferent to the type or style of threads being used by the -application; or, for that matter, if threads are being used at all -- -because Berkeley DB supports multiprocess access. In the Berkeley DB documentation, -any time we refer to a <i>thread of control</i>, it can be read as -a true thread (one of many in an application's address space) or a -process. -<p><dt>Free-threaded<dd>A Berkeley DB handle that can be used by multiple threads simultaneously -without any application-level synchronization is called -<i>free-threaded</i>. -<p><dt>Transaction<dd>A <i>transaction</i> is a one or more operations on one or more -databases that should be treated as a single unit of work. For example, -changes to a set of databases, in which either all of the changes must be -applied to the database(s) or none of them should. Applications specify -when each transaction starts, what database operations are included in -it, and when it ends. -<p><dt>Transaction abort/commit<dd>Every transaction ends by <i>committing</i> or <i>aborting</i>. -If a transaction commits, Berkeley DB guarantees that any database changes -included in the transaction will never be lost, even after system or -application failure. If a transaction aborts, or is uncommitted when -the system or application fails, then the changes involved will never -appear in the database. -<p><dt>System or application failure<dd><i>System or application failure</i> is the phrase we use to -describe something bad happening near your data. It can be an -application dumping core, being interrupted by a signal, the disk -filling up, or the entire system crashing. In any case, for whatever -reason, the application can no longer make forward progress, and its -databases are left in an unknown state. -<p><dt>Recovery<dd><i>Recovery</i> is what makes the database consistent after a system -or application failure. The recovery process includes review of log -files and databases to ensure that the changes from each committed -transaction appear in the database, and that no changes from an -unfinished (or aborted) transaction do. Whenever system or application -failure occurs, applications must usually run recovery. -<p><dt>Deadlock<dd><i>Deadlock</i>, in its simplest form, happens when one thread of -control owns resource A, but needs resource B; while another thread of -control owns resource B, but needs resource A. Neither thread of -control can make progress, and so one has to give up and release all -its resources, at which time the remaining thread of control can make -forward progress. -</dl> -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/transapp/why.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/transapp/app.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/libdb/docs/ref/transapp/throughput.html b/libdb/docs/ref/transapp/throughput.html deleted file mode 100644 index 163f4db00..000000000 --- a/libdb/docs/ref/transapp/throughput.html +++ /dev/null @@ -1,125 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Transaction throughput</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Berkeley DB Transactional Data Store Applications</dl></h3></td> -<td align=right><a href="../../ref/transapp/tune.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/transapp/faq.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Transaction throughput</h1> -<p>Generally, the speed of a database system is measured by the -<i>transaction throughput</i>, expressed as a number of -transactions per second. The two gating factors for Berkeley DB performance -in a transactional system are usually the underlying database files and -the log file. Both are factors because they require disk I/O, which is -slow relative to other system resources such as CPU. -<p>In the worst-case scenario: -<p><ul type=disc> -<li>Database access is truly random and the database is too large for any -significant percentage of it to fit into the cache, resulting in a -single I/O per requested key/data pair. -<li>Both the database and the log are on a single disk. -</ul> -<p>This means that for each transaction, Berkeley DB is potentially performing -several filesystem operations: -<p><ul type=disc> -<li>Disk seek to database file -<li>Database file read -<li>Disk seek to log file -<li>Log file write -<li>Flush log file information to disk -<li>Disk seek to update log file metadata (for example, inode information) -<li>Log metadata write -<li>Flush log file metadata to disk -</ul> -<p>There are a number of ways to increase transactional throughput, all of -which attempt to decrease the number of filesystem operations per -transaction. First, the Berkeley DB software includes support for -<i>group commit</i>. Group commit simply means that when the -information about one transaction is flushed to disk, the information -for any other waiting transactions will be flushed to disk at the same -time, potentially amortizing a single log write over a large number of -transactions. There are additional tuning parameters which may be -useful to application writers: -<p><ul type=disc> -<li>Tune the size of the database cache. If the Berkeley DB key/data pairs used -during the transaction are found in the database cache, the seek and read -from the database are no longer necessary, resulting in two fewer -filesystem operations per transaction. To determine whether your cache -size is too small, see <a href="../../ref/am_conf/cachesize.html">Selecting -a cache size</a>. -<li>Put the database and the log files on different disks. This allows reads -and writes to the log files and the database files to be performed -concurrently. -<li>Set the filesystem configuration so that file access and modification times -are not updated. Note that although the file access and modification times -are not used by Berkeley DB, this may affect other programs -- so be careful. -<li>Upgrade your hardware. When considering the hardware on which to run your -application, however, it is important to consider the entire system. The -controller and bus can have as much to do with the disk performance as -the disk itself. It is also important to remember that throughput is -rarely the limiting factor, and that disk seek times are normally the true -performance issue for Berkeley DB. -<li>Turn on the <a href="../../api_c/env_set_flags.html#DB_TXN_WRITE_NOSYNC">DB_TXN_WRITE_NOSYNC</a> or <a href="../../api_c/env_set_flags.html#DB_TXN_NOSYNC">DB_TXN_NOSYNC</a> flags. -This changes the Berkeley DB behavior so that the log files are not written -and/or flushed when transactions are committed. Although this change -will greatly increase your transaction throughput, it means that -transactions will exhibit the ACI (atomicity, consistency, and -isolation) properties, but not D (durability). Database integrity will -be maintained, but it is possible that some number of the most recently -committed transactions may be undone during recovery instead of being -redone. -</ul> -<p>If you are bottlenecked on logging, the following test will help you -confirm that the number of transactions per second that your application -does is reasonable for the hardware on which you're running. Your test -program should repeatedly perform the following operations: -<p><ul type=disc> -<li>Seek to the beginning of a file -<li>Write to the file -<li>Flush the file write to disk -</ul> -<p>The number of times that you can perform these three operations per -second is a rough measure of the minimum number of transactions per -second of which the hardware is capable. This test simulates the -operations applied to the log file. (As a simplifying assumption in this -experiment, we assume that the database files are either on a separate -disk; or that they fit, with some few exceptions, into the database -cache.) We do not have to directly simulate updating the log file -directory information because it will normally be updated and flushed -to disk as a result of flushing the log file write to disk. -<p>Running this test program, in which we write 256 bytes for 1000 operations -on reasonably standard commodity hardware (Pentium II CPU, SCSI disk), -returned the following results: -<p><blockquote><pre>% testfile -b256 -o1000 -running: 1000 ops -Elapsed time: 16.641934 seconds -1000 ops: 60.09 ops per second</pre></blockquote> -<p>Note that the number of bytes being written to the log as part of each -transaction can dramatically affect the transaction throughput. The -test run used 256, which is a reasonable size log write. Your log -writes may be different. To determine your average log write size, use -the <a href="../../utility/db_stat.html">db_stat</a> utility to display your log statistics. -<p>As a quick sanity check, the average seek time is 9.4 msec for this -particular disk, and the average latency is 4.17 msec. That results in -a minimum requirement for a data transfer to the disk of 13.57 msec, or -a maximum of 74 transfers per second. This is close enough to the -previous 60 operations per second (which wasn't done on a quiescent -disk) that the number is believable. -<p>An implementation of the previous <a href="writetest.cs">example test -program</a> for IEEE/ANSI Std 1003.1 (POSIX) standard systems is included in the Berkeley DB -distribution. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/transapp/tune.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/transapp/faq.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/libdb/docs/ref/transapp/transapp.cs b/libdb/docs/ref/transapp/transapp.cs deleted file mode 100644 index 61fa3146e..000000000 --- a/libdb/docs/ref/transapp/transapp.cs +++ /dev/null @@ -1,489 +0,0 @@ -#include <sys/types.h> -#include <sys/stat.h> - -#include <errno.h> -#include <pthread.h> -#include <stdarg.h> -#include <stdlib.h> -#include <string.h> -#include <unistd.h> - -#include <db.h> - -#define ENV_DIRECTORY "TXNAPP" - -void add_cat(DB_ENV *, DB *, char *, ...); -void add_color(DB_ENV *, DB *, char *, int); -void add_fruit(DB_ENV *, DB *, char *, char *); -void *checkpoint_thread(void *); -void log_archlist(DB_ENV *); -void *logfile_thread(void *); -void db_open(DB_ENV *, DB **, char *, int); -void env_dir_create(void); -void env_open(DB_ENV **); -void usage(void); - -int -main(int argc, char *argv[]) -{ - extern char *optarg; - extern int optind; - DB *db_cats, *db_color, *db_fruit; - DB_ENV *dbenv; - pthread_t ptid; - int ch, ret; - - while ((ch = getopt(argc, argv, "")) != EOF) - switch (ch) { - case '?': - default: - usage(); - } - argc -= optind; - argv += optind; - - env_dir_create(); - env_open(&dbenv); - - /* Start a checkpoint thread. */ - if ((ret = pthread_create( - &ptid, NULL, checkpoint_thread, (void *)dbenv)) != 0) { - fprintf(stderr, - "txnapp: failed spawning checkpoint thread: %s\n", - strerror(ret)); - exit (1); - } - - /* Start a logfile removal thread. */ - if ((ret = pthread_create( - &ptid, NULL, logfile_thread, (void *)dbenv)) != 0) { - fprintf(stderr, - "txnapp: failed spawning log file removal thread: %s\n", - strerror(ret)); - exit (1); - } - - /* Open database: Key is fruit class; Data is specific type. */ - db_open(dbenv, &db_fruit, "fruit", 0); - - /* Open database: Key is a color; Data is an integer. */ - db_open(dbenv, &db_color, "color", 0); - - /* - * Open database: - * Key is a name; Data is: company name, address, cat breeds. - */ - db_open(dbenv, &db_cats, "cats", 1); - - add_fruit(dbenv, db_fruit, "apple", "yellow delicious"); - - add_color(dbenv, db_color, "blue", 0); - add_color(dbenv, db_color, "blue", 3); - - add_cat(dbenv, db_cats, - "Amy Adams", - "Sleepycat Software", - "394 E. Riding Dr., Carlisle, MA 01741, USA", - "abyssinian", - "bengal", - "chartreaux", - NULL); - - return (0); -} - -void -env_dir_create() -{ - struct stat sb; - - /* - * If the directory exists, we're done. We do not further check - * the type of the file, DB will fail appropriately if it's the - * wrong type. - */ - if (stat(ENV_DIRECTORY, &sb) == 0) - return; - - /* Create the directory, read/write/access owner only. */ - if (mkdir(ENV_DIRECTORY, S_IRWXU) != 0) { - fprintf(stderr, - "txnapp: mkdir: %s: %s\n", ENV_DIRECTORY, strerror(errno)); - exit (1); - } -} - -void -env_open(DB_ENV **dbenvp) -{ - DB_ENV *dbenv; - int ret; - - /* Create the environment handle. */ - if ((ret = db_env_create(&dbenv, 0)) != 0) { - fprintf(stderr, - "txnapp: db_env_create: %s\n", db_strerror(ret)); - exit (1); - } - - /* Set up error handling. */ - dbenv->set_errpfx(dbenv, "txnapp"); - - /* Do deadlock detection internally. */ - if ((ret = dbenv->set_lk_detect(dbenv, DB_LOCK_DEFAULT)) != 0) { - dbenv->err(dbenv, ret, "set_lk_detect: DB_LOCK_DEFAULT"); - exit (1); - } - - /* - * Open a transactional environment: - * create if it doesn't exist - * free-threaded handle - * run recovery - * read/write owner only - */ - if ((ret = dbenv->open(dbenv, ENV_DIRECTORY, - DB_CREATE | DB_INIT_LOCK | DB_INIT_LOG | - DB_INIT_MPOOL | DB_INIT_TXN | DB_RECOVER | DB_THREAD, - S_IRUSR | S_IWUSR)) != 0) { - dbenv->err(dbenv, ret, "dbenv->open: %s", ENV_DIRECTORY); - exit (1); - } - - *dbenvp = dbenv; -} - -void * -checkpoint_thread(void *arg) -{ - DB_ENV *dbenv; - int ret; - - dbenv = arg; - dbenv->errx(dbenv, "Checkpoint thread: %lu", (u_long)pthread_self()); - - /* Checkpoint once a minute. */ - for (;; sleep(60)) - if ((ret = dbenv->txn_checkpoint(dbenv, 0, 0, 0)) != 0) { - dbenv->err(dbenv, ret, "checkpoint thread"); - exit (1); - } - - /* NOTREACHED */ -} - -void * -logfile_thread(void *arg) -{ - DB_ENV *dbenv; - int ret; - char **begin, **list; - - dbenv = arg; - dbenv->errx(dbenv, - "Log file removal thread: %lu", (u_long)pthread_self()); - - /* Check once every 5 minutes. */ - for (;; sleep(300)) { - /* Get the list of log files. */ - if ((ret = - dbenv->log_archive(dbenv, &list, DB_ARCH_ABS)) != 0) { - dbenv->err(dbenv, ret, "DB_ENV->log_archive"); - exit (1); - } - - /* Remove the log files. */ - if (list != NULL) { - for (begin = list; *list != NULL; ++list) - if ((ret = remove(*list)) != 0) { - dbenv->err(dbenv, - ret, "remove %s", *list); - exit (1); - } - free (begin); - } - } - /* NOTREACHED */ -} - -void -log_archlist(DB_ENV *dbenv) -{ - int ret; - char **begin, **list; - - /* Get the list of database files. */ - if ((ret = dbenv->log_archive(dbenv, - &list, DB_ARCH_ABS | DB_ARCH_DATA)) != 0) { - dbenv->err(dbenv, ret, "DB_ENV->log_archive: DB_ARCH_DATA"); - exit (1); - } - if (list != NULL) { - for (begin = list; *list != NULL; ++list) - printf("database file: %s\n", *list); - free (begin); - } - - /* Get the list of log files. */ - if ((ret = dbenv->log_archive(dbenv, - &list, DB_ARCH_ABS | DB_ARCH_LOG)) != 0) { - dbenv->err(dbenv, ret, "DB_ENV->log_archive: DB_ARCH_LOG"); - exit (1); - } - if (list != NULL) { - for (begin = list; *list != NULL; ++list) - printf("log file: %s\n", *list); - free (begin); - } -} - -void -db_open(DB_ENV *dbenv, DB **dbp, char *name, int dups) -{ - DB *db; - int ret; - - /* Create the database handle. */ - if ((ret = db_create(&db, dbenv, 0)) != 0) { - dbenv->err(dbenv, ret, "db_create"); - exit (1); - } - - /* Optionally, turn on duplicate data items. */ - if (dups && (ret = db->set_flags(db, DB_DUP)) != 0) { - dbenv->err(dbenv, ret, "db->set_flags: DB_DUP"); - exit (1); - } - - /* - * Open a database in the environment: - * create if it doesn't exist - * free-threaded handle - * read/write owner only - */ - if ((ret = db->open(db, NULL, name, NULL, - DB_BTREE, DB_CREATE | DB_THREAD, S_IRUSR | S_IWUSR)) != 0) { - dbenv->err(dbenv, ret, "db->open: %s", name); - exit (1); - } - - *dbp = db; -} - -void -add_fruit(DB_ENV *dbenv, DB *db, char *fruit, char *name) -{ - DBT key, data; - DB_TXN *tid; - int ret; - - /* Initialization. */ - memset(&key, 0, sizeof(key)); - memset(&data, 0, sizeof(data)); - key.data = fruit; - key.size = strlen(fruit); - data.data = name; - data.size = strlen(name); - - for (;;) { - /* Begin the transaction. */ - if ((ret = dbenv->txn_begin(dbenv, NULL, &tid, 0)) != 0) { - dbenv->err(dbenv, ret, "DB_ENV->txn_begin"); - exit (1); - } - - /* Store the value. */ - switch (ret = db->put(db, tid, &key, &data, 0)) { - case 0: - /* Success: commit the change. */ - if ((ret = tid->commit(tid, 0)) != 0) { - dbenv->err(dbenv, ret, "DB_TXN->commit"); - exit (1); - } - return; - case DB_LOCK_DEADLOCK: - /* Deadlock: retry the operation. */ - if ((ret = tid->abort(tid)) != 0) { - dbenv->err(dbenv, ret, "DB_TXN->abort"); - exit (1); - } - break; - default: - /* Error: run recovery. */ - dbenv->err(dbenv, ret, "dbc->put: %s/%s", fruit, name); - exit (1); - } - } -} - -void -add_color(DB_ENV *dbenv, DB *dbp, char *color, int increment) -{ - DBT key, data; - DB_TXN *tid; - int original, ret; - char buf[64]; - - /* Initialization. */ - memset(&key, 0, sizeof(key)); - key.data = color; - key.size = strlen(color); - memset(&data, 0, sizeof(data)); - data.flags = DB_DBT_MALLOC; - - for (;;) { - /* Begin the transaction. */ - if ((ret = dbenv->txn_begin(dbenv, NULL, &tid, 0)) != 0) { - dbenv->err(dbenv, ret, "DB_ENV->txn_begin"); - exit (1); - } - - /* - * Get the key. If it exists, we increment the value. If it - * doesn't exist, we create it. - */ - switch (ret = dbp->get(dbp, tid, &key, &data, 0)) { - case 0: - original = atoi(data.data); - break; - case DB_LOCK_DEADLOCK: - /* Deadlock: retry the operation. */ - if ((ret = tid->abort(tid)) != 0) { - dbenv->err(dbenv, ret, "DB_TXN->abort"); - exit (1); - } - continue; - case DB_NOTFOUND: - original = 0; - break; - default: - /* Error: run recovery. */ - dbenv->err( - dbenv, ret, "dbc->get: %s/%d", color, increment); - exit (1); - } - if (data.data != NULL) - free(data.data); - - /* Create the new data item. */ - (void)snprintf(buf, sizeof(buf), "%d", original + increment); - data.data = buf; - data.size = strlen(buf) + 1; - - /* Store the new value. */ - switch (ret = dbp->put(dbp, tid, &key, &data, 0)) { - case 0: - /* Success: commit the change. */ - if ((ret = tid->commit(tid, 0)) != 0) { - dbenv->err(dbenv, ret, "DB_TXN->commit"); - exit (1); - } - return; - case DB_LOCK_DEADLOCK: - /* Deadlock: retry the operation. */ - if ((ret = tid->abort(tid)) != 0) { - dbenv->err(dbenv, ret, "DB_TXN->abort"); - exit (1); - } - break; - default: - /* Error: run recovery. */ - dbenv->err( - dbenv, ret, "dbc->put: %s/%d", color, increment); - exit (1); - } - } -} - -void -add_cat(DB_ENV *dbenv, DB *db, char *name, ...) -{ - va_list ap; - DBC *dbc; - DBT key, data; - DB_TXN *tid; - int ret; - char *s; - - /* Initialization. */ - memset(&key, 0, sizeof(key)); - memset(&data, 0, sizeof(data)); - key.data = name; - key.size = strlen(name); - -retry: /* Begin the transaction. */ - if ((ret = dbenv->txn_begin(dbenv, NULL, &tid, 0)) != 0) { - dbenv->err(dbenv, ret, "DB_ENV->txn_begin"); - exit (1); - } - - /* Delete any previously existing item. */ - switch (ret = db->del(db, tid, &key, 0)) { - case 0: - case DB_NOTFOUND: - break; - case DB_LOCK_DEADLOCK: - /* Deadlock: retry the operation. */ - if ((ret = tid->abort(tid)) != 0) { - dbenv->err(dbenv, ret, "DB_TXN->abort"); - exit (1); - } - goto retry; - default: - dbenv->err(dbenv, ret, "db->del: %s", name); - exit (1); - } - - /* Create a cursor. */ - if ((ret = db->cursor(db, tid, &dbc, 0)) != 0) { - dbenv->err(dbenv, ret, "db->cursor"); - exit (1); - } - - /* Append the items, in order. */ - va_start(ap, name); - while ((s = va_arg(ap, char *)) != NULL) { - data.data = s; - data.size = strlen(s); - switch (ret = dbc->c_put(dbc, &key, &data, DB_KEYLAST)) { - case 0: - break; - case DB_LOCK_DEADLOCK: - va_end(ap); - - /* Deadlock: retry the operation. */ - if ((ret = dbc->c_close(dbc)) != 0) { - dbenv->err( - dbenv, ret, "dbc->c_close"); - exit (1); - } - if ((ret = tid->abort(tid)) != 0) { - dbenv->err(dbenv, ret, "DB_TXN->abort"); - exit (1); - } - goto retry; - default: - /* Error: run recovery. */ - dbenv->err(dbenv, ret, "dbc->put: %s/%s", name, s); - exit (1); - } - } - va_end(ap); - - /* Success: commit the change. */ - if ((ret = dbc->c_close(dbc)) != 0) { - dbenv->err(dbenv, ret, "dbc->c_close"); - exit (1); - } - if ((ret = tid->commit(tid, 0)) != 0) { - dbenv->err(dbenv, ret, "DB_TXN->commit"); - exit (1); - } -} - -void -usage() -{ - (void)fprintf(stderr, "usage: txnapp\n"); - exit(1); -} diff --git a/libdb/docs/ref/transapp/tune.html b/libdb/docs/ref/transapp/tune.html deleted file mode 100644 index 6114df666..000000000 --- a/libdb/docs/ref/transapp/tune.html +++ /dev/null @@ -1,110 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Transaction tuning</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Berkeley DB Transactional Data Store Applications</dl></h3></td> -<td align=right><a href="../../ref/transapp/reclimit.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/transapp/throughput.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Transaction tuning</h1> -<p>There are a few different issues to consider when tuning the performance -of Berkeley DB transactional applications. First, you should review -<a href="../../ref/am_misc/tune.html">Access method tuning</a>, as the -tuning issues for access method applications are applicable to -transactional applications as well. The following are additional tuning -issues for Berkeley DB transactional applications: -<p><dl compact> -<p><dt>access method<dd>Highly concurrent applications should use the Queue access method, where -possible, as it provides finer-granularity of locking than the other -access methods. Otherwise, applications usually see better concurrency -when using the Btree access method than when using either the Hash or -Recno access methods. -<p><dt>record numbers<dd>Using record numbers outside of the Queue access method will often slow -down concurrent applications as they limit the degree of concurrency -available in the database. -Using the Recno access method, or the Btree access -method with retrieval by record number configured can slow applications -down. -<p><dt>Btree database size<dd>When using the Btree access method, applications supporting concurrent -access may see excessive numbers of deadlocks in small databases. There -are two different approaches to resolving this problem. First, as the -Btree access method uses page-level locking, decreasing the database -page size can result in fewer lock conflicts. Second, in the case of -databases that are cyclically growing and shrinking, turning off reverse -splits can leave the database with enough pages that there will be fewer -lock conflicts. -<p><dt>transactionally protected read operations<dd>Most applications do not need repeatable reads. Performing all read -operations outside of transactions can often significantly increase -application throughput. In addition, limiting the lifetime of -non-transactional cursors will reduce the length of times locks are -held, thereby improving concurrency. -<p><dt><a href="../../api_c/env_set_flags.html#DB_DIRECT_DB">DB_DIRECT_DB</a>, <a href="../../api_c/env_set_flags.html#DB_DIRECT_LOG">DB_DIRECT_LOG</a><dd>Consider using the <a href="../../api_c/env_set_flags.html#DB_DIRECT_DB">DB_DIRECT_DB</a> and <a href="../../api_c/env_set_flags.html#DB_DIRECT_LOG">DB_DIRECT_LOG</a> flags. -On some systems, avoiding caching in the operating system can improve -write throughput and allow the creation of larger Berkeley DB caches. -<p><dt><a href="../../api_c/db_open.html#DB_DIRTY_READ">DB_DIRTY_READ</a><dd>Consider using the <a href="../../api_c/db_open.html#DB_DIRTY_READ">DB_DIRTY_READ</a> flag for transactions, cursors -or individual read operations. This flag allows read operations to -potentially return data which has been modified but not yet committed, -and can significantly increase application throughput in applications -that do not require data be guaranteed to be permanent in the database. -<p><dt><a href="../../api_c/dbc_get.html#DB_RMW">DB_RMW</a><dd>Consider using the <a href="../../api_c/dbc_get.html#DB_RMW">DB_RMW</a> flag to immediate acquire write locks -when reading data items that will subsequently be modified. Although -this flag may increase contention (because write locks are held longer -than they would otherwise be), it may decrease the number of deadlocks -that occur. -<p><dt><a href="../../api_c/env_set_flags.html#DB_TXN_WRITE_NOSYNC">DB_TXN_WRITE_NOSYNC</a>, <a href="../../api_c/env_set_flags.html#DB_TXN_NOSYNC">DB_TXN_NOSYNC</a><dd>By default, transactional commit in Berkeley DB implies durability, that is, -all committed operations will be present in the database after recovery -from any application or system failure. For applications not requiring -that level of certainty, specifying the <a href="../../api_c/env_set_flags.html#DB_TXN_NOSYNC">DB_TXN_NOSYNC</a> flag will -often provide a significant performance improvement. In this case, the -database will still be fully recoverable, but some number of committed -transactions might be lost after application or system failure. -<p><dt>access databases in order<dd>When modifying multiple databases in a single transaction, always access -physical files and databases within physical files, in the same order -where possible. In addition, avoid returning to a physical file or -database, that is, avoid accessing a database, moving on to another -database and then returning to the first database. This can -significantly reduce the chance of deadlock between threads of -control. -<p><dt>large key/data items<dd>Transactional protections in Berkeley DB are guaranteed by before and after -physical image logging. This means applications modifying large -key/data items also write large log records, and, in the case of the -default transaction commit, threads of control must wait until those -log records have been flushed to disk. Applications supporting -concurrent access should try and keep key/data items small wherever -possible. -<p><dt><a href="../../ref/build_unix/conf.html#--enable-posixmutexes">--enable-posixmutexes</a><dd>By default, the Berkeley DB library will only select the POSIX pthread mutex -implementation if it supports mutexes shared between multiple processes. -If your application does not share its database environment between -processes and your system's POSIX mutex support was not selected because -it did not support inter-process mutexes, you may be able to increase -performance and transactional throughput by configuring with the -<a href="../../ref/build_unix/conf.html#--enable-posixmutexes">--enable-posixmutexes</a> argument. -<p><dt>log buffer size<dd>Berkeley DB internally maintains a buffer of log writes. The buffer is -written to disk at transaction commit, by default, or, whenever it -is filled. If it is consistently being filled before transaction -commit, it will be written multiple times per transaction, costing -application performance. In these cases, increasing the size of the -log buffer can increase application throughput. -<p><dt>trickle write<dd>In some applications, the cache is sufficiently active and dirty that -readers frequently need to write a dirty page in order to have space in -which to read a new page from the backing database file. You can use -the <a href="../../utility/db_stat.html">db_stat</a> utility (or the statistics returned by the -<a href="../../api_c/memp_stat.html">DB_ENV->memp_stat</a> method) to see how often this is happening in your -application's cache. In this case, using a separate thread of control -and the <a href="../../api_c/memp_trickle.html">DB_ENV->memp_trickle</a> interface to trickle-write pages can often -increase the overall throughput of the application. -</dl> -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/transapp/reclimit.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/transapp/throughput.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/libdb/docs/ref/transapp/why.html b/libdb/docs/ref/transapp/why.html deleted file mode 100644 index f31d79bf8..000000000 --- a/libdb/docs/ref/transapp/why.html +++ /dev/null @@ -1,40 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Why transactions?</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Berkeley DB Transactional Data Store Applications</dl></h3></td> -<td align=right><a href="../../ref/transapp/intro.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/transapp/term.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Why transactions?</h1> -<p>Perhaps the first question to answer is "Why transactions?" There are -a number of reasons to include transactional support in your applications. -The most common ones are the following: -<p><dl compact> -<p><dt>Recoverability<dd>Applications often need to ensure that no matter how the system or -application fails, previously saved data is available the next time the -application runs. -<p><dt>Atomicity<dd>Applications may need to make multiple changes to one or more databases, -but ensure that either all of the changes happen, or none of them -happens. Transactions guarantee that a group of changes are atomic; -that is, if the application or system fails, either all of the changes -to the databases will appear when the application next runs, or none of -them. -<p><dt>Isolation<dd>Applications may need to make changes in isolation, that is, ensure that -only a single thread of control is modifying a key/data pair at a time. -Transactions ensure each thread of control sees all records as if all -other transactions either completed before or after its transaction. -</dl> -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/transapp/intro.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/transapp/term.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/libdb/docs/ref/transapp/writetest.cs b/libdb/docs/ref/transapp/writetest.cs deleted file mode 100644 index 45cd0d9b4..000000000 --- a/libdb/docs/ref/transapp/writetest.cs +++ /dev/null @@ -1,104 +0,0 @@ -/* - * writetest -- - * - * $Id$ - */ -#include <sys/types.h> - -#include <errno.h> -#include <fcntl.h> -#include <stdio.h> -#include <stdlib.h> -#include <string.h> -#include <time.h> -#include <unistd.h> - -void usage __P((void)); - -int -main(argc, argv) - int argc; - char *argv[]; -{ - struct timeval start_time, end_time; - long usecs; - int bytes, ch, cnt, fd, ops; - char *fname, buf[100 * 1024]; - - bytes = 256; - fname = "testfile"; - ops = 1000; - while ((ch = getopt(argc, argv, "b:f:o:")) != EOF) - switch (ch) { - case 'b': - if ((bytes = atoi(optarg)) > sizeof(buf)) { - fprintf(stderr, - "max -b option %d\n", sizeof(buf)); - exit (1); - } - break; - case 'f': - fname = optarg; - break; - case 'o': - if ((ops = atoi(optarg)) <= 0) { - fprintf(stderr, "illegal -o option value\n"); - exit (1); - } - break; - case '?': - default: - usage(); - } - argc -= optind; - argv += optind; - - (void)unlink(fname); - if ((fd = open(fname, O_RDWR | O_CREAT, 0666)) == -1) { - perror(fname); - exit (1); - } - - memset(buf, 0, bytes); - - printf("running: %d ops\n", ops); - - (void)gettimeofday(&start_time, NULL); - for (cnt = 0; cnt < ops; ++cnt) { - if (write(fd, buf, bytes) != bytes) { - fprintf(stderr, "write: %s\n", strerror(errno)); - exit (1); - } - if (lseek(fd, (off_t)0, SEEK_SET) == -1) { - fprintf(stderr, "lseek: %s\n", strerror(errno)); - exit (1); - } - if (fsync(fd) != 0) { - fprintf(stderr, "fsync: %s\n", strerror(errno)); - exit (1); - } - } - (void)gettimeofday(&end_time, NULL); - - if (end_time.tv_sec != start_time.tv_sec) { - end_time.tv_usec += 1000000; - --end_time.tv_sec; - } - usecs = (end_time.tv_sec - start_time.tv_sec) * 1000000 + - end_time.tv_usec - start_time.tv_usec; - printf("Elapsed time: %ld.%06ld seconds\n", - usecs / 1000000, usecs % 1000000); - printf("%d ops: %7.2f ops per second\n", - ops, (float)1000000 * ops/usecs); - - (void)unlink(fname); - exit (0); -} - -void -usage() -{ - (void)fprintf(stderr, - "usage: testfile [-b bytes] [-f file] [-o ops]\n"); - exit(1); -} diff --git a/libdb/docs/ref/txn/config.html b/libdb/docs/ref/txn/config.html deleted file mode 100644 index e01f3016b..000000000 --- a/libdb/docs/ref/txn/config.html +++ /dev/null @@ -1,41 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Configuring transactions</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Transaction Subsystem</dl></h3></td> -<td align=right><a href="../../ref/txn/intro.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/txn/limits.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Configuring transactions</h1> -<p>The application may change the number of simultaneous outstanding -transactions supported by the Berkeley DB environment by calling the -<a href="../../api_c/env_set_tx_max.html">DB_ENV->set_tx_max</a> method. This will also set the size of the -underlying transaction subsystem's region. When the number of -outstanding transactions is reached, additional calls to -<a href="../../api_c/txn_begin.html">DB_ENV->txn_begin</a> will fail until some active transactions complete. -<p>There is an additional parameter used in configuring transactions; the -<a href="../../api_c/env_set_flags.html#DB_TXN_NOSYNC">DB_TXN_NOSYNC</a> flag. Setting the <a href="../../api_c/env_set_flags.html#DB_TXN_NOSYNC">DB_TXN_NOSYNC</a> flag to -<a href="../../api_c/env_set_flags.html">DB_ENV->set_flags</a> when opening a transaction region changes the -behavior of transactions to not write or synchronously flush the log -during transaction commit. -<p>This change may significantly increase application transactional -throughput. However, it means that although transactions will continue -to exhibit the ACI (atomicity, consistency, and isolation) properties, -they will not have D (durability). Database integrity will be -maintained, but it is possible that some number of the most recently -committed transactions may be undone during recovery instead of being -redone. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/txn/intro.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/txn/limits.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/libdb/docs/ref/txn/intro.html b/libdb/docs/ref/txn/intro.html deleted file mode 100644 index 7c59a6b6d..000000000 --- a/libdb/docs/ref/txn/intro.html +++ /dev/null @@ -1,96 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Berkeley DB and transactions</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Transaction Subsystem</dl></h3></td> -<td align=right><a href="../../ref/mp/config.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/txn/config.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Berkeley DB and transactions</h1> -<p>The Transaction subsystem makes operations atomic, consistent, isolated, -and durable in the face of system and application failures. The subsystem -requires that the data be properly logged and locked in order to attain -these properties. Berkeley DB contains all the components necessary to -transaction-protect the Berkeley DB access methods, and other forms of data may -be protected if they are logged and locked appropriately. -<p>The Transaction subsystem is created, initialized, and opened by calls to -<a href="../../api_c/env_open.html">DB_ENV->open</a> with the <a href="../../api_c/env_open.html#DB_INIT_TXN">DB_INIT_TXN</a> flag specified. Note -that enabling transactions automatically enables logging, but does not -enable locking because a single thread of control that needed atomicity -and recoverability would not require it. -<p>The <a href="../../api_c/txn_begin.html">DB_ENV->txn_begin</a> function starts a transaction, returning an opaque -handle to a transaction. If the parent parameter to <a href="../../api_c/txn_begin.html">DB_ENV->txn_begin</a> is -non-NULL, the new transaction is a child of the designated parent -transaction. -<p>The <a href="../../api_c/txn_abort.html">DB_TXN->abort</a> function ends the designated transaction and causes -all updates performed by the transaction to be undone. The end result is -that the database is left in a state identical to the state that existed -prior to the <a href="../../api_c/txn_begin.html">DB_ENV->txn_begin</a>. If the aborting transaction has any child -transactions associated with it (even ones that have already been -committed), they are also aborted. Any transactions that are unresolved -(neither committed nor aborted) when the application or system fails -are aborted during recovery. -<p>The <a href="../../api_c/txn_commit.html">DB_TXN->commit</a> function ends the designated transaction and makes -all the updates performed by the transaction permanent, even in the face -of application or system failure. If this is a parent transaction -committing, all child transactions that individually committed or -had not been resolved are also committed. -<p>Transactions are identified by 32-bit unsigned integers. The ID -associated with any transaction can be obtained using the <a href="../../api_c/txn_id.html">DB_TXN->id</a> -function. If an application is maintaining information outside of Berkeley DB -that it wishes to transaction-protect, it should use this transaction ID -as the locking ID. -<p>The <a href="../../api_c/txn_checkpoint.html">DB_ENV->txn_checkpoint</a> function causes a transaction checkpoint. A -checkpoint is performed using to a specific log sequence number (LSN), -referred to as the checkpoint LSN. When a checkpoint completes -successfully, it means that all data buffers whose updates are described -by LSNs less than the checkpoint LSN have been written to disk. This, in -turn, means that the log records less than the checkpoint LSN are no -longer necessary for normal recovery (although they would be required for -catastrophic recovery if the database files were lost), and all log files -containing only records prior to the checkpoint LSN may be safely archived -and removed. -<p>The time required to run normal recovery is proportional to the amount -of work done between checkpoints. If a large number of modifications -happen between checkpoints, many updates recorded in the log may -not have been written to disk when failure occurred, and recovery may -take longer to run. Generally, if the interval between checkpoints is -short, data may be being written to disk more frequently, but the -recovery time will be shorter. Often, the checkpoint interval is tuned -for each specific application. -<p>The <a href="../../api_c/txn_stat.html">DB_ENV->txn_stat</a> function returns information about the status of -the transaction subsystem. It is the programmatic interface used by the -<a href="../../utility/db_stat.html">db_stat</a> utility. -<p>The transaction system is closed by a call to <a href="../../api_c/env_close.html">DB_ENV->close</a>. -<p>Finally, the entire transaction system may be removed using the -<a href="../../api_c/env_remove.html">DB_ENV->remove</a> interface. -<!--$Id$--> -<p><table border=1 align=center> -<tr><th>Transaction Subsystem and Related Methods</th><th>Description</th></tr> -<tr><td><a href="../../api_c/env_set_tx_max.html">DB_ENV->set_tx_max</a></td><td>Set maximum number of transactions</td></tr> -<tr><td><a href="../../api_c/env_set_tx_timestamp.html">DB_ENV->set_tx_timestamp</a></td><td>Set recovery timestamp</td></tr> -<tr><td><a href="../../api_c/txn_checkpoint.html">DB_ENV->txn_checkpoint</a></td><td>Checkpoint the transaction subsystem</td></tr> -<tr><td><a href="../../api_c/txn_recover.html">DB_ENV->txn_recover</a></td><td>Distributed transaction recovery</td></tr> -<tr><td><a href="../../api_c/txn_stat.html">DB_ENV->txn_stat</a></td><td>Return transaction subsystem statistics</td></tr> -<tr><td><a href="../../api_c/txn_begin.html">DB_ENV->txn_begin</a></td><td>Begin a transaction</td></tr> -<tr><td><a href="../../api_c/txn_abort.html">DB_TXN->abort</a></td><td>Abort a transaction</td></tr> -<tr><td><a href="../../api_c/txn_commit.html">DB_TXN->commit</a></td><td>Commit a transaction</td></tr> -<tr><td><a href="../../api_c/txn_discard.html">DB_TXN->discard</a></td><td>Discard a prepared but not resolved transaction handle</td></tr> -<tr><td><a href="../../api_c/txn_id.html">DB_TXN->id</a></td><td>Return a transaction's ID</td></tr> -<tr><td><a href="../../api_c/txn_prepare.html">DB_TXN->prepare</a></td><td>Prepare a transaction for commit</td></tr> -<tr><td><a href="../../api_c/txn_set_timeout.html">DB_TXN->set_timeout</a></td><td>Set transaction timeout</td></tr> -</table> -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/mp/config.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/txn/config.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/libdb/docs/ref/txn/limits.html b/libdb/docs/ref/txn/limits.html deleted file mode 100644 index bd857da99..000000000 --- a/libdb/docs/ref/txn/limits.html +++ /dev/null @@ -1,56 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Transaction limits</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Transaction Subsystem</dl></h3></td> -<td align=right><a href="../../ref/txn/config.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/rpc/intro.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Transaction limits</h1> -<h3>Transaction IDs</h3> -<p>Transactions are identified by 31-bit unsigned integers, which means -there are just over two billion unique transaction IDs. When a database -environment is initially created or recovery is run, the transaction ID -name space is reset, and new transactions are numbered starting from -0x80000000 (2,147,483,648). The IDs will wrap if the maximum -transaction ID is reached, starting again from 0x80000000. The most -recently allocated transaction ID is the <b>st_last_txnid</b> value in -the transaction statistics information, and can be displayed by the -<a href="../../utility/db_stat.html">db_stat</a> utility. -<h3>Cursors</h3> -<p>When using transactions, cursors are localized to a single transaction. -That is, a cursor may not span transactions, and must be opened and -closed within a single transaction. In addition, intermingling -transaction-protected cursor operations and non-transaction-protected -cursor operations on the same database in a single thread of control is -practically guaranteed to deadlock because the locks obtained for -transactions and non-transactions can conflict. -<h3>Multiple Threads of Control</h3> -<p>Because transactions must hold all their locks until commit, a single -transaction may accumulate a large number of long-term locks during its -lifetime. As a result, when two concurrently running transactions -access the same database, there is strong potential for conflict. -Although Berkeley DB allows an application to have multiple outstanding -transactions active within a single thread of control, great care must -be taken to ensure that the transactions do not block each other (for -example, attempt to obtain conflicting locks on the same data). If two -concurrently active transactions in the same thread of control do -encounter a lock conflict, the thread of control will deadlock so that -the deadlock detector cannot detect the problem. In this case, there -is no true deadlock, but because the transaction on which a transaction -is waiting is in the same thread of control, no forward progress can be -made. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/txn/config.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/rpc/intro.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/libdb/docs/ref/upgrade.2.0/convert.html b/libdb/docs/ref/upgrade.2.0/convert.html deleted file mode 100644 index f9e67c172..000000000 --- a/libdb/docs/ref/upgrade.2.0/convert.html +++ /dev/null @@ -1,75 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Release 2.0: converting applications</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Upgrading Berkeley DB Applications</dl></h3></td> -<td align=right><a href="../../ref/upgrade.2.0/system.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.2.0/disk.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Release 2.0: converting applications</h1> -<p>Mapping the Berkeley DB 1.85 functionality into Berkeley DB version 2 is almost always -simple. The manual page <a href="../../api_c/db_open.html">DB->open</a> replaces the Berkeley DB 1.85 manual -pages <b>dbopen</b>(3), <b>btree</b>(3), <b>hash</b>(3) and -<b>recno</b>(3). You should be able to convert each 1.85 function -call into a Berkeley DB version 2 function call using just the <a href="../../api_c/db_open.html">DB->open</a> -documentation. -<p>Some guidelines and things to watch out for: -<p><ol> -<p><li>Most access method functions have exactly the same semantics as in Berkeley DB -1.85, although the arguments to the functions have changed in some cases. -To get your code to compile, the most common change is to add the -transaction ID as an argument (NULL, since Berkeley DB 1.85 did not support -transactions.) -<p><li>You must always initialize DBT structures to zero before using them with -any Berkeley DB version 2 function. (They do not normally have to be -reinitialized each time, only when they are first allocated. Do this by -declaring the DBT structure external or static, or by calling the C -library routine <b>bzero</b>(3) or <b>memset</b>(3).) -<p><li>The error returns are completely different in the two versions. In Berkeley DB -1.85, < 0 meant an error, and > 0 meant a minor Berkeley DB exception. -In Berkeley DB 2.0, > 0 means an error (the Berkeley DB version 2 functions -return <b>errno</b> on error) and < 0 means a Berkeley DB exception. -See <a href="../../ref/program/errorret.html">Error Returns to Applications</a> -for more information. -<p><li>The Berkeley DB 1.85 DB->seq function has been replaced by cursors in Berkeley DB -version 2. The semantics are approximately the same, but cursors require -the creation of an extra object (the DBC object), which is then used to -access the database. -<p>Specifically, the partial key match and range search functionality of the -R_CURSOR flag in DB->seq has been replaced by the -<a href="../../api_c/dbc_get.html#DB_SET_RANGE">DB_SET_RANGE</a> flag in <a href="../../api_c/dbc_get.html">DBcursor->c_get</a>. -<p><li>In version 2 of the Berkeley DB library, additions or deletions into Recno -(fixed and variable-length record) databases no longer automatically -logically renumber all records after the add/delete point, by default. -The default behavior is that deleting records does not cause subsequent -records to be renumbered, and it is an error to attempt to add new records -between records already in the database. Applications wanting the -historic Recno access method semantics should call the -<a href="../../api_c/db_set_flags.html">DB->set_flags</a> method with the <a href="../../api_c/db_set_flags.html#DB_RENUMBER">DB_RENUMBER</a> flag. -<p><li>Opening a database in Berkeley DB version 2 is a much heavier-weight operation -than it was in Berkeley DB 1.85. Therefore, if your historic applications were -written to open a database, perform a single operation, and close the -database, you may observe performance degradation. In most cases, this -is due to the expense of creating the environment upon each open. While -we encourage restructuring your application to avoid repeated opens and -closes, you can probably recover most of the lost performance by simply -using a persistent environment across invocations. -</ol> -<p>While simply converting Berkeley DB 1.85 function calls to Berkeley DB version 2 -function calls will work, we recommend that you eventually reconsider your -application's interface to the Berkeley DB database library in light of the -additional functionality supplied by Berkeley DB version 2, as it is likely to -result in enhanced application performance. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/upgrade.2.0/system.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.2.0/disk.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/libdb/docs/ref/upgrade.2.0/disk.html b/libdb/docs/ref/upgrade.2.0/disk.html deleted file mode 100644 index fa163b5ae..000000000 --- a/libdb/docs/ref/upgrade.2.0/disk.html +++ /dev/null @@ -1,28 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Release 2.0: upgrade requirements</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Upgrading Berkeley DB Applications</dl></h3></td> -<td align=right><a href="../../ref/upgrade.2.0/convert.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.3.0/intro.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Release 2.0: upgrade requirements</h1> -<p>You will need to upgrade your on-disk databases, as all access method -database formats changed in the Berkeley DB 2.0 release. For information on -converting databases from Berkeley DB 1.85 to Berkeley DB 2.0, see the -<a href="../../utility/db_dump.html">db_dump185</a> and <a href="../../utility/db_load.html">db_load</a> documentation. As database -environments did not exist prior to the 2.0 release, there is no -question of upgrading existing database environments. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/upgrade.2.0/convert.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.3.0/intro.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/libdb/docs/ref/upgrade.2.0/intro.html b/libdb/docs/ref/upgrade.2.0/intro.html deleted file mode 100644 index 9d304b0fe..000000000 --- a/libdb/docs/ref/upgrade.2.0/intro.html +++ /dev/null @@ -1,33 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Release 2.0: introduction</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Upgrading Berkeley DB Applications</dl></h3></td> -<td align=right><a href="../../ref/upgrade/process.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.2.0/system.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Release 2.0: introduction</h1> -<p>The following pages describe how to upgrade applications coded against -the Berkeley DB 1.85 and 1.86 release interfaces to the Berkeley DB 2.0 release -interfaces. They do not describe how to upgrade to the current Berkeley DB -release interfaces. -<p>It is not difficult to upgrade Berkeley DB 1.85 applications to use the Berkeley DB -version 2 library. The Berkeley DB version 2 library has a Berkeley DB 1.85 -compatibility API, which you can use by either recompiling your -application's source code or by relinking its object files against the -version 2 library. The underlying databases must be converted, however, -as the Berkeley DB version 2 library has a different underlying database format. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/upgrade/process.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.2.0/system.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/libdb/docs/ref/upgrade.2.0/system.html b/libdb/docs/ref/upgrade.2.0/system.html deleted file mode 100644 index 373996476..000000000 --- a/libdb/docs/ref/upgrade.2.0/system.html +++ /dev/null @@ -1,85 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Release 2.0: system integration</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Upgrading Berkeley DB Applications</dl></h3></td> -<td align=right><a href="../../ref/upgrade.2.0/intro.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.2.0/convert.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Release 2.0: system integration</h1> -<p><ol> -<p><li>It is possible to maintain both the Berkeley DB 1.85 and Berkeley DB version 2 -libraries on your system. However, the <b>db.h</b> include file that -was distributed with Berkeley DB 1.85 is not compatible with the <b>db.h</b> -file distributed with Berkeley DB version 2, so you will have to install them -in different locations. In addition, both the Berkeley DB 1.85 and Berkeley DB -version 2 libraries are named <b>libdb.a</b>. -<p>As the Berkeley DB 1.85 library did not have an installation target in the -Makefile, there's no way to know exactly where it was installed on the -system. In addition, many vendors included it in the C library instead -of as a separate library, and so it may actually be part of libc and the -<b>db.h</b> include file may be installed in <b>/usr/include</b>. -<p>For these reasons, the simplest way to maintain both libraries is to -install Berkeley DB version 2 in a completely separate area of your system. -The Berkeley DB version 2 installation process allows you to install into a -standalone directory hierarchy on your system. See the -<a href="../../ref/build_unix/intro.html">Building for UNIX systems</a> -documentation for more information and instructions on how to install the -Berkeley DB version 2 library, include files and documentation into specific -locations. -<p><li>Alternatively, you can replace Berkeley DB 1.85 on your system with Berkeley DB -version 2. In this case, you'll probably want to install Berkeley DB version -2 in the normal place on your system, wherever that may be, and delete -the Berkeley DB 1.85 include files, manual pages and libraries. -<p>To replace 1.85 with version 2, you must either convert your 1.85 -applications to use the version 2 API or build the Berkeley DB version 2 library -to include Berkeley DB 1.85 interface compatibility code. Whether converting -your applications to use the version 2 interface or using the version 1.85 -compatibility API, you will need to recompile or relink your 1.85 -applications, and you must convert any persistent application databases -to the Berkeley DB version 2 database formats. -<p>If you want to recompile your Berkeley DB 1.85 applications, you will have to -change them to include the file <b>db_185.h</b> instead of -<b>db.h</b>. (The <b>db_185.h</b> file is automatically installed -during the Berkeley DB version 2 installation process.) You can then recompile -the applications, linking them against the Berkeley DB version 2 library. -<p>For more information on compiling the Berkeley DB 1.85 compatibility code into -the Berkeley DB version 2 library, see <a href="../../ref/build_unix/intro.html">Building for UNIX platforms</a>. -<p>For more information on converting databases from the Berkeley DB 1.85 formats -to the Berkeley DB version 2 formats, see the <a href="../../utility/db_dump.html">db_dump185</a> and -<a href="../../utility/db_load.html">db_load</a> documentation. -<p><li>Finally, although we certainly do not recommend it, it is possible to -load both Berkeley DB 1.85 and Berkeley DB version 2 into the same library. -Similarly, it is possible to use both Berkeley DB 1.85 and Berkeley DB version 2 -within a single application, although it is not possible to use them from -within the same file. -<p>The name space in Berkeley DB version 2 has been changed from that of previous -Berkeley DB versions, notably version 1.85, for portability and consistency -reasons. The only name collisions in the two libraries are the names used -by the historic <a href="../../api_c/dbm.html">dbm</a>, <a href="../../api_c/dbm.html">ndbm</a> and <a href="../../api_c/hsearch.html">hsearch</a> interfaces, -and the Berkeley DB 1.85 compatibility interfaces in the Berkeley DB version 2 -library. -<p>If you are loading both Berkeley DB 1.85 and Berkeley DB version 2 into a single -library, remove the historic interfaces from one of the two library -builds, and configure the Berkeley DB version 2 build to not include the Berkeley DB -1.85 compatibility API, otherwise you could have collisions and undefined -behavior. This can be done by editing the library Makefiles and -reconfiguring and rebuilding the Berkeley DB version 2 library. Obviously, if -you use the historic interfaces, you will get the version in the library -from which you did not remove them. Similarly, you will not be able to -access Berkeley DB version 2 files using the Berkeley DB 1.85 compatibility interface, -since you have removed that from the library as well. -</ol> -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/upgrade.2.0/intro.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.2.0/convert.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/libdb/docs/ref/upgrade.2.0/toc.html b/libdb/docs/ref/upgrade.2.0/toc.html deleted file mode 100644 index e917e40fb..000000000 --- a/libdb/docs/ref/upgrade.2.0/toc.html +++ /dev/null @@ -1,28 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Upgrading Berkeley DB 1.XX applications to Berkeley DB 2.0</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Upgrading Berkeley DB Applications</dl></h3></td> -<td align=right><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a> -</td></tr></table> -<p> -<h1 align=center>Upgrading Berkeley DB 1.XX applications to Berkeley DB 2.0</h1> -<p><ol> -<p><li><a href="intro.html">Release 2.0: introduction</a> -<li><a href="system.html">Release 2.0: system integration</a> -<li><a href="convert.html">Release 2.0: converting applications</a> -<li><a href="disk.html">Release 2.0: upgrade requirements</a> -</ol> -<table width="100%"><tr><td><br></td><td align=right><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a> -</td></tr></table> -<p><font size=1><a href="http://www.sleepycat.com">Copyright Sleepycat Software</a></font> -</body> -</html> diff --git a/libdb/docs/ref/upgrade.3.0/close.html b/libdb/docs/ref/upgrade.3.0/close.html deleted file mode 100644 index 4b2f14b01..000000000 --- a/libdb/docs/ref/upgrade.3.0/close.html +++ /dev/null @@ -1,35 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Release 3.0: DB->sync and DB->close</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Upgrading Berkeley DB Applications</dl></h3></td> -<td align=right><a href="../../ref/upgrade.3.0/stat.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.3.0/lock_put.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Release 3.0: DB->sync and DB->close</h1> -<p>In previous Berkeley DB releases, the <a href="../../api_c/db_close.html">DB->close</a> and <a href="../../api_c/db_sync.html">DB->sync</a> methods -discarded any return of DB_INCOMPLETE from the underlying buffer -pool interfaces, and returned success to its caller. (The -DB_INCOMPLETE error will be returned if the buffer pool functions -are unable to flush all of the database's dirty blocks from the pool. -This often happens if another thread is reading or writing the database's -pages in the pool.) -<p>In the 3.X release, <a href="../../api_c/db_sync.html">DB->sync</a> and <a href="../../api_c/db_close.html">DB->close</a> will return -DB_INCOMPLETE to the application. The best solution is to not -call <a href="../../api_c/db_sync.html">DB->sync</a> and specify the <a href="../../api_c/db_close.html#DB_NOSYNC">DB_NOSYNC</a> flag to the -<a href="../../api_c/db_close.html">DB->close</a> method when multiple threads are expected to be accessing the -database. Alternatively, the caller can ignore any error return of -DB_INCOMPLETE. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/upgrade.3.0/stat.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.3.0/lock_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/libdb/docs/ref/upgrade.3.0/cxx.html b/libdb/docs/ref/upgrade.3.0/cxx.html deleted file mode 100644 index 081909f1e..000000000 --- a/libdb/docs/ref/upgrade.3.0/cxx.html +++ /dev/null @@ -1,32 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Release 3.0: additional C++ changes</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Upgrading Berkeley DB Applications</dl></h3></td> -<td align=right><a href="../../ref/upgrade.3.0/db_cxx.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.3.0/java.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Release 3.0: additional C++ changes</h1> -<p>The Db::set_error_model method is gone. The way to change the C++ API to -return errors rather than throw exceptions is via a flag on the DbEnv or -Db constructor. For example: -<p><blockquote><pre>int dberr; -DbEnv *dbenv = new DbEnv(DB_CXX_NO_EXCEPTIONS);</pre></blockquote> -<p>creates an environment that will never throw exceptions, and method -returns should be checked instead. -<p>There are a number of smaller changes to the API that bring the C, C++ -and Java APIs much closer in terms of functionality and usage. Please -refer to the pages for upgrading C applications for further details. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/upgrade.3.0/db_cxx.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.3.0/java.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/libdb/docs/ref/upgrade.3.0/db.html b/libdb/docs/ref/upgrade.3.0/db.html deleted file mode 100644 index f50514f41..000000000 --- a/libdb/docs/ref/upgrade.3.0/db.html +++ /dev/null @@ -1,49 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Release 3.0: the DB structure</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Upgrading Berkeley DB Applications</dl></h3></td> -<td align=right><a href="../../ref/upgrade.3.0/xa.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.3.0/dbinfo.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Release 3.0: the DB structure</h1> -<p>The <a href="../../api_c/db_class.html">DB</a> structure is now opaque for applications in the Berkeley DB 3.0 -release. Accesses to any fields within that structure by the application -should be replaced with method calls. The following example illustrates -this using the historic type structure field. In the Berkeley DB 2.X releases, -applications could find the type of an underlying database using code -similar to the following: -<p><blockquote><pre>DB *db; -DB_TYPE type; -<p> - type = db->type;</pre></blockquote> -<p>in the Berkeley DB 3.X releases, this should be done using the -<a href="../../api_c/db_get_type.html">DB->get_type</a> method, as follows: -<p><blockquote><pre>DB *db; -DB_TYPE type; -<p> - type = db->get_type(db);</pre></blockquote> -<p>The following table lists the <a href="../../api_c/db_class.html">DB</a> fields previously used by -applications and the methods that should now be used to get or set them. -<p><table border=1 align=center> -<tr><th><a href="../../api_c/db_class.html">DB</a> field</th><th>Berkeley DB 3.X method</th></tr> -<tr><td>byteswapped</td><td><a href="../../api_c/db_get_byteswapped.html">DB->get_byteswapped</a></td></tr> -<tr><td>db_errcall</td><td><a href="../../api_c/db_set_errcall.html">DB->set_errcall</a></td></tr> -<tr><td>db_errfile</td><td><a href="../../api_c/db_set_errfile.html">DB->set_errfile</a></td></tr> -<tr><td>db_errpfx</td><td><a href="../../api_c/db_set_errpfx.html">DB->set_errpfx</a></td></tr> -<tr><td>db_paniccall</td><td><a href="../../api_c/db_set_paniccall.html">DB->set_paniccall</a></td></tr> -<tr><td>type</td><td><a href="../../api_c/db_get_type.html">DB->get_type</a></td></tr> -</table> -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/upgrade.3.0/xa.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.3.0/dbinfo.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/libdb/docs/ref/upgrade.3.0/db_cxx.html b/libdb/docs/ref/upgrade.3.0/db_cxx.html deleted file mode 100644 index 0295b66e0..000000000 --- a/libdb/docs/ref/upgrade.3.0/db_cxx.html +++ /dev/null @@ -1,48 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Release 3.0: the Db class for C++ and Java</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Upgrading Berkeley DB Applications</dl></h3></td> -<td align=right><a href="../../ref/upgrade.3.0/dbenv_cxx.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.3.0/cxx.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Release 3.0: the Db class for C++ and Java</h1> -<p>The static Db::open method and the DbInfo class have been removed in the -Berkeley DB 3.0 release. The way to open a database file is to use the new Db -constructor with two arguments, followed by set_XXX methods to configure -the Db object, and finally a call to the new (nonstatic) Db::open(). In -comparing the Berkeley DB 3.0 release open method with the 2.X static open -method, the second argument is new. It is a database name, which can -be null. The DbEnv argument has been removed, as the environment is now -specified in the constructor. The open method no longer returns a Db, -since it operates on one. -<p>Here's a C++ example opening a Berkeley DB database using the 2.X interface: -<p><blockquote><pre>// Note: by default, errors are thrown as exceptions -Db *table; -Db::open("lookup.db", DB_BTREE, DB_CREATE, 0644, dbenv, 0, &table);</pre></blockquote> -<p>In the Berkeley DB 3.0 release, this code would be written as: -<p><blockquote><pre>// Note: by default, errors are thrown as exceptions -Db *table = new Db(dbenv, 0); -table->open("lookup.db", NULL, DB_BTREE, DB_CREATE, 0644);</pre></blockquote> -<p>Here's a Java example opening a Berkeley DB database using the 2.X interface: -<p><blockquote><pre>// Note: errors are thrown as exceptions -Db table = Db.open("lookup.db", Db.DB_BTREE, Db.DB_CREATE, 0644, dbenv, 0);</pre></blockquote> -<p>In the Berkeley DB 3.0 release, this code would be written as: -<p><blockquote><pre>// Note: errors are thrown as exceptions -Db table = new Db(dbenv, 0); -table.open("lookup.db", null, Db.DB_BTREE, Db.DB_CREATE, 0644);</pre></blockquote> -<p>Note that if the dbenv argument is null, the database will not exist -within an environment. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/upgrade.3.0/dbenv_cxx.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.3.0/cxx.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/libdb/docs/ref/upgrade.3.0/dbenv.html b/libdb/docs/ref/upgrade.3.0/dbenv.html deleted file mode 100644 index 912753d66..000000000 --- a/libdb/docs/ref/upgrade.3.0/dbenv.html +++ /dev/null @@ -1,69 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Release 3.0: the DB_ENV structure</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Upgrading Berkeley DB Applications</dl></h3></td> -<td align=right><a href="../../ref/upgrade.3.0/func.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.3.0/open.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Release 3.0: the DB_ENV structure</h1> -<p>The <a href="../../api_c/env_class.html">DB_ENV</a> structure is now opaque for applications in the Berkeley DB -3.0 release. Accesses to any fields within that structure by the -application should be replaced with method calls. The following example -illustrates this using the historic errpfx structure field. In the Berkeley DB -2.X releases, applications set error prefixes using code similar to the -following: -<p><blockquote><pre>DB_ENV *dbenv; -<p> - dbenv->errpfx = "my prefix";</pre></blockquote> -<p>in the Berkeley DB 3.X releases, this should be done using the -<a href="../../api_c/env_set_errpfx.html">DB_ENV->set_errpfx</a> method, as follows: -<p><blockquote><pre>DB_ENV *dbenv; -<p> - dbenv->set_errpfx(dbenv, "my prefix");</pre></blockquote> -<p>The following table lists the <a href="../../api_c/env_class.html">DB_ENV</a> fields previously used by -applications and the methods that should now be used to set them. -<p><table border=1 align=center> -<tr><th><a href="../../api_c/env_class.html">DB_ENV</a> field</th><th>Berkeley DB 3.X method</th></tr> -<tr><td>db_errcall</td><td><a href="../../api_c/env_set_errcall.html">DB_ENV->set_errcall</a></td></tr> -<tr><td>db_errfile</td><td><a href="../../api_c/env_set_errfile.html">DB_ENV->set_errfile</a></td></tr> -<tr><td>db_errpfx</td><td><a href="../../api_c/env_set_errpfx.html">DB_ENV->set_errpfx</a></td></tr> -<tr><td>db_lorder</td><td>This field was removed from the <a href="../../api_c/env_class.html">DB_ENV</a> structure in the Berkeley DB -3.0 release as no application should have ever used it. Any code using -it should be evaluated for potential bugs.</td></tr> -<tr><td>db_paniccall</td><td><a href="../../api_c/env_set_paniccall.html">DB_ENV->set_paniccall</a></td></tr> -<tr><td>db_verbose</td><td><a href="../../api_c/env_set_verbose.html">DB_ENV->set_verbose</a> -<p>Note: the db_verbose field was a simple boolean toggle, the -<a href="../../api_c/env_set_verbose.html">DB_ENV->set_verbose</a> method takes arguments that specify exactly -which verbose messages are desired.</td></tr> -<tr><td>lg_max</td><td><a href="../../api_c/env_set_lg_max.html">DB_ENV->set_lg_max</a></td></tr> -<tr><td>lk_conflicts</td><td><a href="../../api_c/env_set_lk_conflicts.html">DB_ENV->set_lk_conflicts</a></td></tr> -<tr><td>lk_detect</td><td><a href="../../api_c/env_set_lk_detect.html">DB_ENV->set_lk_detect</a></td></tr> -<tr><td>lk_max</td><td>dbenv->set_lk_max</td></tr> -<tr><td>lk_modes</td><td><a href="../../api_c/env_set_lk_conflicts.html">DB_ENV->set_lk_conflicts</a></td></tr> -<tr><td>mp_mmapsize</td><td><a href="../../api_c/env_set_mp_mmapsize.html">DB_ENV->set_mp_mmapsize</a></td></tr> -<tr><td>mp_size</td><td><a href="../../api_c/env_set_cachesize.html">DB_ENV->set_cachesize</a> -<p>Note: the <a href="../../api_c/env_set_cachesize.html">DB_ENV->set_cachesize</a> function takes additional arguments. -Setting both the second argument (the number of GB in the pool) and the -last argument (the number of memory pools to create) to 0 will result in -behavior that is backward-compatible with previous Berkeley DB releases.</td></tr> -<tr><td>tx_info</td><td>This field was used by applications as an argument to the transaction -subsystem functions. As those functions take references to a -<a href="../../api_c/env_class.html">DB_ENV</a> structure as arguments in the Berkeley DB 3.0 release, it should -no longer be used by any application.</td></tr> -<tr><td>tx_max</td><td><a href="../../api_c/env_set_tx_max.html">DB_ENV->set_tx_max</a></td></tr> -<tr><td>tx_recover</td><td>dbenv->set_tx_recover</td></tr> -</table> -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/upgrade.3.0/func.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.3.0/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/libdb/docs/ref/upgrade.3.0/dbenv_cxx.html b/libdb/docs/ref/upgrade.3.0/dbenv_cxx.html deleted file mode 100644 index 2dcc18917..000000000 --- a/libdb/docs/ref/upgrade.3.0/dbenv_cxx.html +++ /dev/null @@ -1,73 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Release 3.0: the DbEnv class for C++ and Java</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Upgrading Berkeley DB Applications</dl></h3></td> -<td align=right><a href="../../ref/upgrade.3.0/value_set.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.3.0/db_cxx.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Release 3.0: the DbEnv class for C++ and Java</h1> -<p>The DbEnv::appinit() method and two constructors for the DbEnv class are -gone. There is now a single way to create and initialize the environment. -The way to create an environment is to use the new DbEnv constructor with -one argument. After this call, the DbEnv can be configured with various -set_XXX methods. Finally, a call to DbEnv::open is made to initialize -the environment. -<p>Here's a C++ example creating a Berkeley DB environment using the 2.X interface -<p><blockquote><pre>int dberr; -DbEnv *dbenv = new DbEnv(); -<p> -dbenv->set_error_stream(&cerr); -dbenv->set_errpfx("myprog"); -<p> -if ((dberr = dbenv->appinit("/database/home", - NULL, DB_CREATE | DB_INIT_LOCK | DB_INIT_MPOOL)) != 0) { - cerr << "failure: " << strerror(dberr); - exit (1); -}</pre></blockquote> -<p>In the Berkeley DB 3.0 release, this code would be written as: -<p><blockquote><pre>int dberr; -DbEnv *dbenv = new DbEnv(0); -<p> -dbenv->set_error_stream(&cerr); -dbenv->set_errpfx("myprog"); -<p> -if ((dberr = dbenv->open("/database/home", - NULL, DB_CREATE | DB_INIT_LOCK | DB_INIT_MPOOL, 0)) != 0) { - cerr << "failure: " << dbenv->strerror(dberr); - exit (1); -}</pre></blockquote> -<p>Here's a Java example creating a Berkeley DB environment using the 2.X interface: -<p><blockquote><pre>int dberr; -DbEnv dbenv = new DbEnv(); -<p> -dbenv.set_error_stream(System.err); -dbenv.set_errpfx("myprog"); -<p> -dbenv.appinit("/database/home", - null, Db.DB_CREATE | Db.DB_INIT_LOCK | Db.DB_INIT_MPOOL);</pre></blockquote> -<p>In the Berkeley DB 3.0 release, this code would be written as: -<p><blockquote><pre>int dberr; -DbEnv dbenv = new DbEnv(0); -<p> -dbenv.set_error_stream(System.err); -dbenv.set_errpfx("myprog"); -<p> -dbenv.open("/database/home", - null, Db.DB_CREATE | Db.DB_INIT_LOCK | Db.DB_INIT_MPOOL, 0);</pre></blockquote> -<p>In the Berkeley DB 2.X release, DbEnv had accessors to obtain "managers" of type -DbTxnMgr, DbMpool, DbLog, DbTxnMgr. If you used any of these managers, -all their methods are now found directly in the DbEnv class. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/upgrade.3.0/value_set.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.3.0/db_cxx.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/libdb/docs/ref/upgrade.3.0/dbinfo.html b/libdb/docs/ref/upgrade.3.0/dbinfo.html deleted file mode 100644 index cf4796d97..000000000 --- a/libdb/docs/ref/upgrade.3.0/dbinfo.html +++ /dev/null @@ -1,73 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Release 3.0: the DBINFO structure</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Upgrading Berkeley DB Applications</dl></h3></td> -<td align=right><a href="../../ref/upgrade.3.0/db.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.3.0/join.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Release 3.0: the DBINFO structure</h1> -<p>The DB_INFO structure has been removed from the Berkeley DB 3.0 release. -Accesses to any fields within that structure by the application should be -replaced with method calls on the <a href="../../api_c/db_class.html">DB</a> handle. The following -example illustrates this using the historic db_cachesize structure field. -In the Berkeley DB 2.X releases, applications could set the size of an -underlying database cache using code similar to the following: -<p><blockquote><pre>DB_INFO dbinfo; -<p> - memset(dbinfo, 0, sizeof(dbinfo)); - dbinfo.db_cachesize = 1024 * 1024;</pre></blockquote> -<p>in the Berkeley DB 3.X releases, this should be done using the -<a href="../../api_c/db_set_cachesize.html">DB->set_cachesize</a> method, as follows: -<p><blockquote><pre>DB *db; -int ret; -<p> - ret = db->set_cachesize(db, 0, 1024 * 1024, 0);</pre></blockquote> -<p>The DB_INFO structure is no longer used in any way by the Berkeley DB 3.0 -release, and should be removed from the application. -<p>The following table lists the DB_INFO fields previously used by -applications and the methods that should now be used to set -them. Because these calls provide configuration for the -database open, they must precede the call to <a href="../../api_c/db_open.html">DB->open</a>. -Calling them after the call to <a href="../../api_c/db_open.html">DB->open</a> will return an -error. -<p><table border=1 align=center> -<tr><th>DB_INFO field</th><th>Berkeley DB 3.X method</th></tr> -<tr><td>bt_compare</td><td><a href="../../api_c/db_set_bt_compare.html">DB->set_bt_compare</a></td></tr> -<tr><td>bt_minkey</td><td><a href="../../api_c/db_set_bt_minkey.html">DB->set_bt_minkey</a></td></tr> -<tr><td>bt_prefix</td><td><a href="../../api_c/db_set_bt_prefix.html">DB->set_bt_prefix</a></td></tr> -<tr><td>db_cachesize</td><td><a href="../../api_c/db_set_cachesize.html">DB->set_cachesize</a> -<p>Note: the <a href="../../api_c/db_set_cachesize.html">DB->set_cachesize</a> function takes additional arguments. -Setting both the second argument (the number of GB in the pool) and the -last argument (the number of memory pools to create) to 0 will result in -behavior that is backward-compatible with previous Berkeley DB releases.</td></tr> -<tr><td>db_lorder</td><td><a href="../../api_c/db_set_lorder.html">DB->set_lorder</a></td></tr> -<tr><td>db_malloc</td><td>DB->set_malloc</td></tr> -<tr><td>db_pagesize</td><td><a href="../../api_c/db_set_pagesize.html">DB->set_pagesize</a></td></tr> -<tr><td>dup_compare</td><td><a href="../../api_c/db_set_dup_compare.html">DB->set_dup_compare</a></td></tr> -<tr><td>flags</td><td><a href="../../api_c/db_set_flags.html">DB->set_flags</a> -<p>Note: the DB_DELIMITER, DB_FIXEDLEN and DB_PAD flags no longer need to be -set as there are specific methods off the <a href="../../api_c/db_class.html">DB</a> handle that set the -file delimiter, the length of fixed-length records and the fixed-length -record pad character. They should simply be discarded from the application.</td></tr> -<tr><td>h_ffactor</td><td><a href="../../api_c/db_set_h_ffactor.html">DB->set_h_ffactor</a></td></tr> -<tr><td>h_hash</td><td><a href="../../api_c/db_set_h_hash.html">DB->set_h_hash</a></td></tr> -<tr><td>h_nelem</td><td><a href="../../api_c/db_set_h_nelem.html">DB->set_h_nelem</a></td></tr> -<tr><td>re_delim</td><td><a href="../../api_c/db_set_re_delim.html">DB->set_re_delim</a></td></tr> -<tr><td>re_len</td><td><a href="../../api_c/db_set_re_len.html">DB->set_re_len</a></td></tr> -<tr><td>re_pad</td><td><a href="../../api_c/db_set_re_pad.html">DB->set_re_pad</a></td></tr> -<tr><td>re_source</td><td><a href="../../api_c/db_set_re_source.html">DB->set_re_source</a></td></tr> -</table> -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/upgrade.3.0/db.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.3.0/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/libdb/docs/ref/upgrade.3.0/disk.html b/libdb/docs/ref/upgrade.3.0/disk.html deleted file mode 100644 index 86fefc608..000000000 --- a/libdb/docs/ref/upgrade.3.0/disk.html +++ /dev/null @@ -1,31 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Release 3.0: upgrade requirements</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Upgrading Berkeley DB Applications</dl></h3></td> -<td align=right><a href="../../ref/upgrade.3.0/java.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.3.1/intro.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Release 3.0: upgrade requirements</h1> -<p>Log file formats and the Btree, Recno and Hash Access Method database -formats changed in the Berkeley DB 3.0 release. (The on-disk Btree/Recno -format changed from version 6 to version 7. The on-disk Hash format -changed from version 5 to version 6.) Until the underlying databases -are upgraded, the <a href="../../api_c/db_open.html">DB->open</a> method will return a <a href="../../api_c/db_open.html#DB_OLD_VERSION">DB_OLD_VERSION</a> -error. -<p>For further information on upgrading Berkeley DB installations, see -<a href="../../ref/upgrade/process.html">Upgrading Berkeley DB -installations</a>. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/upgrade.3.0/java.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.3.1/intro.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/libdb/docs/ref/upgrade.3.0/eacces.html b/libdb/docs/ref/upgrade.3.0/eacces.html deleted file mode 100644 index c4edfc9d2..000000000 --- a/libdb/docs/ref/upgrade.3.0/eacces.html +++ /dev/null @@ -1,29 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Release 3.0: EACCES</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Upgrading Berkeley DB Applications</dl></h3></td> -<td align=right><a href="../../ref/upgrade.3.0/eagain.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.3.0/jump_set.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Release 3.0: EACCES</h1> -<p>There was an error in previous releases of the Berkeley DB documentation that -said that the lock_put and lock_vec interfaces could return EACCES as -an error to indicate that a lock could not be released because it was -held by another locker. The application should be searched for any -occurrences of EACCES. For each of these, any that are checking for an -error return from lock_put or lock_vec should have the test and any -error handling removed. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/upgrade.3.0/eagain.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.3.0/jump_set.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/libdb/docs/ref/upgrade.3.0/eagain.html b/libdb/docs/ref/upgrade.3.0/eagain.html deleted file mode 100644 index e33f618e7..000000000 --- a/libdb/docs/ref/upgrade.3.0/eagain.html +++ /dev/null @@ -1,35 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Release 3.0: EAGAIN</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Upgrading Berkeley DB Applications</dl></h3></td> -<td align=right><a href="../../ref/upgrade.3.0/lock_notheld.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.3.0/eacces.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Release 3.0: EAGAIN</h1> -<p>Historically, the Berkeley DB interfaces have returned the POSIX error value -EAGAIN to indicate a deadlock. This has been removed from the Berkeley DB 3.0 -release in order to make it possible for applications to distinguish -between EAGAIN errors returned by the system and returns from Berkeley DB -indicating deadlock. -<p>The application should be searched for any occurrences of EAGAIN. For -each of these, any that are checking for a deadlock return from Berkeley DB -should be changed to check for the DB_LOCK_DEADLOCK return value. -<p>If, for any reason, this is a difficult change for the application to -make, the <b>include/db.src</b> distribution file should be modified to -translate all returns of DB_LOCK_DEADLOCK to EAGAIN. Search for the -string EAGAIN in that file, there is a comment that describes how to make -the change. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/upgrade.3.0/lock_notheld.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.3.0/eacces.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/libdb/docs/ref/upgrade.3.0/envopen.html b/libdb/docs/ref/upgrade.3.0/envopen.html deleted file mode 100644 index 8fad811fb..000000000 --- a/libdb/docs/ref/upgrade.3.0/envopen.html +++ /dev/null @@ -1,156 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Release 3.0: environment open/close/unlink</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Upgrading Berkeley DB Applications</dl></h3></td> -<td align=right><a href="../../ref/upgrade.3.0/intro.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.3.0/func.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Release 3.0: environment open/close/unlink</h1> -<p>The hardest part of upgrading your application from a 2.X code base to -the 3.0 release is translating the Berkeley DB environment open, close and -remove calls. -<p>There were two logical changes in this part of the Berkeley DB interface. -First, in Berkeley DB 3.0, there are no longer separate structures that -represent each subsystem (for example, DB_LOCKTAB or DB_TXNMGR) and an -overall <a href="../../api_c/env_class.html">DB_ENV</a> environment structure. Instead there is only the -<a href="../../api_c/env_class.html">DB_ENV</a> structure. This means that <a href="../../api_c/env_class.html">DB_ENV</a> references -should be passed around by your application instead of passing around -DB_LOCKTAB or DB_TXNMGR references. This is likely to be a simple -change for most applications as few applications use the lock_XXX, -log_XXX, memp_XXX or txn_XXX interfaces to create Berkeley DB environments. -<p>The second change is that there are no longer separate open, close, and -unlink interfaces to the Berkeley DB subsystems. For example, in previous -releases, it was possible to open a lock subsystem either using -db_appinit or using the lock_open call. In the 3.0 release the XXX_open -interfaces to the subsystems have been removed, and subsystems must now -be opened using the 3.0 replacement for the db_appinit call. -<p>To upgrade your application, first find each place your application opens, -closes and/or removes a Berkeley DB environment. This will be code of the form: -<p><blockquote><pre>db_appinit, db_appexit -lock_open, lock_close, lock_unlink -log_open, log_close, log_unlink -memp_open, memp_close, memp_unlink -txn_open, txn_close, txn_unlink</pre></blockquote> -<p>Each of these groups of calls should be replaced with calls to: -<p><blockquote><pre><a href="../../api_c/env_create.html">db_env_create</a>, <a href="../../api_c/env_open.html">DB_ENV->open</a>, <a href="../../api_c/env_close.html">DB_ENV->close</a>, -<a href="../../api_c/env_remove.html">DB_ENV->remove</a></pre></blockquote> -<p>The <a href="../../api_c/env_create.html">db_env_create</a> call and the call to the <a href="../../api_c/env_open.html">DB_ENV->open</a> -method replace the db_appinit, lock_open, log_open, memp_open and txn_open -calls. The <a href="../../api_c/env_close.html">DB_ENV->close</a> method replaces the db_appexit, -lock_close, log_close, memp_close and txn_close calls. The -<a href="../../api_c/env_remove.html">DB_ENV->remove</a> call replaces the lock_unlink, log_unlink, -memp_unlink and txn_unlink calls. -<p>Here's an example creating a Berkeley DB environment using the 2.X interface: -<p><blockquote><pre>/* - * db_init -- - * Initialize the environment. - */ -DB_ENV * -db_init(home) - char *home; -{ - DB_ENV *dbenv; -<p> - if ((dbenv = (DB_ENV *)calloc(sizeof(DB_ENV), 1)) == NULL) - return (errno); -<p> - if ((errno = db_appinit(home, NULL, dbenv, - DB_INIT_LOCK | DB_INIT_LOG | DB_INIT_MPOOL | DB_INIT_TXN | - DB_USE_ENVIRON)) == 0) - return (dbenv); -<p> - free(dbenv); - return (NULL); -}</pre></blockquote> -<p>In the Berkeley DB 3.0 release, this code would be written as: -<p><blockquote><pre>/* - * db_init -- - * Initialize the environment. - */ -int -db_init(home, dbenvp) - char *home; - DB_ENV **dbenvp; -{ - int ret; - DB_ENV *dbenv; -<p> - if ((ret = db_env_create(&dbenv, 0)) != 0) - return (ret); -<p> - if ((ret = dbenv->open(dbenv, home, NULL, - DB_INIT_LOCK | DB_INIT_LOG | DB_INIT_MPOOL | DB_INIT_TXN | - DB_USE_ENVIRON, 0)) == 0) { - *dbenvp = dbenv; - return (0); - } -<p> - (void)dbenv->close(dbenv, 0); - return (ret); -}</pre></blockquote> -<p>As you can see, the arguments to db_appinit and to <a href="../../api_c/env_open.html">DB_ENV->open</a> are -largely the same. There is some minor re-organization: the mapping is -that arguments #1, 2, 3, and 4 to db_appinit become arguments #2, 3, 1 -and 4 to <a href="../../api_c/env_open.html">DB_ENV->open</a>. There is one additional argument to -<a href="../../api_c/env_open.html">DB_ENV->open</a>, argument #5. For backward compatibility with the 2.X -Berkeley DB releases, simply set that argument to 0. -<p>It is only slightly more complex to translate calls to XXX_open to the -<a href="../../api_c/env_open.html">DB_ENV->open</a> method. Here's an example of creating a lock region -using the 2.X interface: -<p><blockquote><pre>lock_open(dir, DB_CREATE, 0664, dbenv, ®ionp);</pre></blockquote> -<p>In the Berkeley DB 3.0 release, this code would be written as: -<p><blockquote><pre>if ((ret = db_env_create(&dbenv, 0)) != 0) - return (ret); -<p> -if ((ret = dbenv->open(dbenv, - dir, NULL, DB_CREATE | DB_INIT_LOCK, 0664)) == 0) { - *dbenvp = dbenv; - return (0); -}</pre></blockquote> -<p>Note that in this example, you no longer need the DB_LOCKTAB structure -reference that was required in Berkeley DB 2.X releases. -<p>The final issue with upgrading the db_appinit call is the DB_MPOOL_PRIVATE -option previously provided for the db_appinit interface. If your -application is using this flag, it should almost certainly use the new -<a href="../../api_c/env_open.html#DB_PRIVATE">DB_PRIVATE</a> flag to the <a href="../../api_c/env_open.html">DB_ENV->open</a> interface. Regardless, -you should carefully consider this change before converting to use the -<a href="../../api_c/env_open.html#DB_PRIVATE">DB_PRIVATE</a> flag. -<p>Translating db_appexit or XXX_close calls to <a href="../../api_c/env_close.html">DB_ENV->close</a> is equally -simple. Instead of taking a reference to a per-subsystem structure such -as DB_LOCKTAB or DB_TXNMGR, all calls take a reference to a <a href="../../api_c/env_class.html">DB_ENV</a> -structure. The calling sequence is otherwise unchanged. Note that as -the application no longer allocates the memory for the DB_ENV structure, -application code to discard it after the call to db_appexit() is no longer -needed. -<p>Translating XXX_unlink calls to <a href="../../api_c/env_remove.html">DB_ENV->remove</a> is slightly more complex. -As with <a href="../../api_c/env_close.html">DB_ENV->close</a>, the call takes a reference to a <a href="../../api_c/env_class.html">DB_ENV</a> -structure instead of a per-subsystem structure. The calling sequence is -slightly different, however. Here is an example of removing a lock region -using the 2.X interface: -<p><blockquote><pre>DB_ENV *dbenv; -<p> -ret = lock_unlink(dir, 1, dbenv);</pre></blockquote> -<p>In the Berkeley DB 3.0 release, this code fragment would be written as: -<p><blockquote><pre>DB_ENV *dbenv; -<p> -ret = dbenv->remove(dbenv, dir, NULL, DB_FORCE);</pre></blockquote> -<p>The additional argument to the <a href="../../api_c/env_remove.html">DB_ENV->remove</a> function is a -configuration argument similar to that previously taken by db_appinit and -now taken by the <a href="../../api_c/env_open.html">DB_ENV->open</a> method. For backward compatibility -this new argument should simply be set to NULL. The force argument to -XXX_unlink is now a flag value that is set by bitwise inclusively <b>OR</b>'ing it the -<a href="../../api_c/env_remove.html">DB_ENV->remove</a> flag argument. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/upgrade.3.0/intro.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.3.0/func.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/libdb/docs/ref/upgrade.3.0/func.html b/libdb/docs/ref/upgrade.3.0/func.html deleted file mode 100644 index d8e32c2e4..000000000 --- a/libdb/docs/ref/upgrade.3.0/func.html +++ /dev/null @@ -1,70 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Release 3.0: function arguments</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Upgrading Berkeley DB Applications</dl></h3></td> -<td align=right><a href="../../ref/upgrade.3.0/envopen.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.3.0/dbenv.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Release 3.0: function arguments</h1> -<p>In Berkeley DB 3.0, there are no longer separate structures that represent -each subsystem (for example, DB_LOCKTAB or DB_TXNMGR), and an overall -<a href="../../api_c/env_class.html">DB_ENV</a> environment structure. Instead there is only the -<a href="../../api_c/env_class.html">DB_ENV</a> structure. This means that <a href="../../api_c/env_class.html">DB_ENV</a> references -should be passed around by your application instead of passing around -DB_LOCKTAB or DB_TXNMGR references. -<p>Each of the following functions: -<p><blockquote><pre>lock_detect -lock_get -lock_id -lock_put -lock_stat -lock_vec</pre></blockquote> -<p>should have its first argument, a reference to the DB_LOCKTAB structure, -replaced with a reference to the enclosing <a href="../../api_c/env_class.html">DB_ENV</a> structure. For -example, the following line of code from a Berkeley DB 2.X application: -<p><blockquote><pre>DB_LOCKTAB *lt; -DB_LOCK lock; - ret = lock_put(lt, lock);</pre></blockquote> -<p>should now be written as follows: -<p><blockquote><pre>DB_ENV *dbenv; -DB_LOCK *lock; - ret = lock_put(dbenv, lock);</pre></blockquote> -<p>Similarly, all of the functions: -<p><blockquote><pre>log_archive -log_compare -log_file -log_flush -log_get -log_put -log_register -log_stat -log_unregister</pre></blockquote> -<p>should have their DB_LOG argument replaced with a reference to a -<a href="../../api_c/env_class.html">DB_ENV</a> structure, and the functions: -<p><blockquote><pre>memp_fopen -memp_register -memp_stat -memp_sync -memp_trickle</pre></blockquote> -<p>should have their DB_MPOOL argument replaced with a reference to a -<a href="../../api_c/env_class.html">DB_ENV</a> structure. -<p>You should remove all references to DB_LOCKTAB, DB_LOG, DB_MPOOL, and -DB_TXNMGR structures from your application, they are no longer useful -in any way. In fact, a simple way to identify all of the places that -need to be upgraded is to remove all such structures and variables -they declare, and then compile. You will see a warning message from -your compiler in each case that needs to be upgraded. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/upgrade.3.0/envopen.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.3.0/dbenv.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/libdb/docs/ref/upgrade.3.0/intro.html b/libdb/docs/ref/upgrade.3.0/intro.html deleted file mode 100644 index 2f33d578a..000000000 --- a/libdb/docs/ref/upgrade.3.0/intro.html +++ /dev/null @@ -1,27 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Release 3.0: introduction</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Upgrading Berkeley DB Applications</dl></h3></td> -<td align=right><a href="../../ref/upgrade.2.0/disk.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.3.0/envopen.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Release 3.0: introduction</h1> -<p>The following pages describe how to upgrade applications coded against -the Berkeley DB 2.X release interfaces to the Berkeley DB 3.0 release interfaces. -This information does not describe how to upgrade Berkeley DB 1.85 release -applications. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/upgrade.2.0/disk.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.3.0/envopen.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/libdb/docs/ref/upgrade.3.0/java.html b/libdb/docs/ref/upgrade.3.0/java.html deleted file mode 100644 index 66c8f564a..000000000 --- a/libdb/docs/ref/upgrade.3.0/java.html +++ /dev/null @@ -1,35 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Release 3.0: additional Java changes</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Upgrading Berkeley DB Applications</dl></h3></td> -<td align=right><a href="../../ref/upgrade.3.0/cxx.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.3.0/disk.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Release 3.0: additional Java changes</h1> -<p>There are several additional types of exceptions thrown in the Berkeley DB 3.0 -Java API. -<p>DbMemoryException and DbDeadlockException can be caught independently of -DbException if you want to do special handling for these kinds of errors. -Since they are subclassed from DbException, a try block that catches -DbException will catch these also, so code is not required to change. -The catch clause for these new exceptions should appear before the catch -clause for DbException. -<p>You will need to add a catch clause for java.io.FileNotFoundException, -since that can be thrown by the <a href="../../api_java/db_open.html">Db.open</a> and <a href="../../api_java/env_open.html">DbEnv.open</a> methods. -<p>There are a number of smaller changes to the API that bring the C, C++ -and Java APIs much closer in terms of functionality and usage. Please -refer to the pages for upgrading C applications for further details. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/upgrade.3.0/cxx.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.3.0/disk.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/libdb/docs/ref/upgrade.3.0/join.html b/libdb/docs/ref/upgrade.3.0/join.html deleted file mode 100644 index e2e0eb788..000000000 --- a/libdb/docs/ref/upgrade.3.0/join.html +++ /dev/null @@ -1,29 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Release 3.0: DB->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> -<table width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Upgrading Berkeley DB Applications</dl></h3></td> -<td align=right><a href="../../ref/upgrade.3.0/dbinfo.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.3.0/stat.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Release 3.0: DB->join</h1> -<p>Historically, the last two arguments to the Berkeley DB <a href="../../api_c/db_join.html">DB->join</a> -interface were a flags value followed by a reference to a memory location -to store the returned cursor object. In the Berkeley DB 3.0 release, the -order of those two arguments has been swapped for consistency with other -Berkeley DB interfaces. -<p>The application should be searched for any occurrences of <a href="../../api_c/db_join.html">DB->join</a>. -For each of these, the order of the last two arguments should be swapped. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/upgrade.3.0/dbinfo.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.3.0/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/libdb/docs/ref/upgrade.3.0/jump_set.html b/libdb/docs/ref/upgrade.3.0/jump_set.html deleted file mode 100644 index 3b61bf6c5..000000000 --- a/libdb/docs/ref/upgrade.3.0/jump_set.html +++ /dev/null @@ -1,49 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Release 3.0: db_jump_set</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Upgrading Berkeley DB Applications</dl></h3></td> -<td align=right><a href="../../ref/upgrade.3.0/eacces.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.3.0/value_set.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Release 3.0: db_jump_set</h1> -<p>The db_jump_set interface has been removed from the Berkeley DB 3.0 release, -replaced by method calls on the <a href="../../api_c/env_class.html">DB_ENV</a> handle. -<p>The following table lists the db_jump_set arguments previously used by -applications and the methods that should now be used instead. -<p><table border=1 align=center> -<tr><th>db_jump_set argument</th><th>Berkeley DB 3.X method</th></tr> -<tr><td>DB_FUNC_CLOSE</td><td><a href="../../api_c/set_func_close.html">db_env_set_func_close</a></td></tr> -<tr><td>DB_FUNC_DIRFREE</td><td><a href="../../api_c/set_func_dirfree.html">db_env_set_func_dirfree</a></td></tr> -<tr><td>DB_FUNC_DIRLIST</td><td><a href="../../api_c/set_func_dirlist.html">db_env_set_func_dirlist</a></td></tr> -<tr><td>DB_FUNC_EXISTS</td><td><a href="../../api_c/set_func_exists.html">db_env_set_func_exists</a></td></tr> -<tr><td>DB_FUNC_FREE</td><td><a href="../../api_c/set_func_free.html">db_env_set_func_free</a></td></tr> -<tr><td>DB_FUNC_FSYNC</td><td><a href="../../api_c/set_func_fsync.html">db_env_set_func_fsync</a></td></tr> -<tr><td>DB_FUNC_IOINFO</td><td><a href="../../api_c/set_func_ioinfo.html">db_env_set_func_ioinfo</a></td></tr> -<tr><td>DB_FUNC_MALLOC</td><td><a href="../../api_c/set_func_malloc.html">db_env_set_func_malloc</a></td></tr> -<tr><td>DB_FUNC_MAP</td><td><a href="../../api_c/set_func_map.html">db_env_set_func_map</a></td></tr> -<tr><td>DB_FUNC_OPEN</td><td><a href="../../api_c/set_func_open.html">db_env_set_func_open</a></td></tr> -<tr><td>DB_FUNC_READ</td><td><a href="../../api_c/set_func_read.html">db_env_set_func_read</a></td></tr> -<tr><td>DB_FUNC_REALLOC</td><td><a href="../../api_c/set_func_realloc.html">db_env_set_func_realloc</a></td></tr> -<tr><td>DB_FUNC_RUNLINK</td><td>The DB_FUNC_RUNLINK functionality has been removed from the Berkeley DB -3.0 release, and should be removed from the application.</td></tr> -<tr><td>DB_FUNC_SEEK</td><td><a href="../../api_c/set_func_seek.html">db_env_set_func_seek</a></td></tr> -<tr><td>DB_FUNC_SLEEP</td><td><a href="../../api_c/set_func_sleep.html">db_env_set_func_sleep</a></td></tr> -<tr><td>DB_FUNC_UNLINK</td><td><a href="../../api_c/set_func_unlink.html">db_env_set_func_unlink</a></td></tr> -<tr><td>DB_FUNC_UNMAP</td><td><a href="../../api_c/set_func_unmap.html">db_env_set_func_unmap</a></td></tr> -<tr><td>DB_FUNC_WRITE</td><td><a href="../../api_c/set_func_write.html">db_env_set_func_write</a></td></tr> -<tr><td>DB_FUNC_YIELD</td><td><a href="../../api_c/set_func_yield.html">db_env_set_func_yield</a></td></tr> -</table> -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/upgrade.3.0/eacces.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.3.0/value_set.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/libdb/docs/ref/upgrade.3.0/lock_detect.html b/libdb/docs/ref/upgrade.3.0/lock_detect.html deleted file mode 100644 index 4f644f35b..000000000 --- a/libdb/docs/ref/upgrade.3.0/lock_detect.html +++ /dev/null @@ -1,25 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Release 3.0: lock_detect</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Upgrading Berkeley DB Applications</dl></h3></td> -<td align=right><a href="../../ref/upgrade.3.0/lock_put.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.3.0/lock_stat.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Release 3.0: lock_detect</h1> -<p>An additional argument has been added to the lock_detect interface. -<p>The application should be searched for any occurrences of lock_detect. -For each one, a NULL argument should be appended to the current arguments. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/upgrade.3.0/lock_put.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.3.0/lock_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/libdb/docs/ref/upgrade.3.0/lock_notheld.html b/libdb/docs/ref/upgrade.3.0/lock_notheld.html deleted file mode 100644 index 99a13451b..000000000 --- a/libdb/docs/ref/upgrade.3.0/lock_notheld.html +++ /dev/null @@ -1,28 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Release 3.0: DB_LOCK_NOTHELD</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Upgrading Berkeley DB Applications</dl></h3></td> -<td align=right><a href="../../ref/upgrade.3.0/rmw.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.3.0/eagain.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Release 3.0: DB_LOCK_NOTHELD</h1> -<p>Historically, the Berkeley DB lock_put and lock_vec interfaces could return -the DB_LOCK_NOTHELD error to indicate that a lock could not be released -as it was held by another locker. This error can no longer be returned -under any circumstances. The application should be searched for any -occurrences of DB_LOCK_NOTHELD. For each of these, the test and any -error processing should be removed. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/upgrade.3.0/rmw.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.3.0/eagain.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/libdb/docs/ref/upgrade.3.0/lock_put.html b/libdb/docs/ref/upgrade.3.0/lock_put.html deleted file mode 100644 index 40ab194cf..000000000 --- a/libdb/docs/ref/upgrade.3.0/lock_put.html +++ /dev/null @@ -1,26 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Release 3.0: lock_put</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Upgrading Berkeley DB Applications</dl></h3></td> -<td align=right><a href="../../ref/upgrade.3.0/close.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.3.0/lock_detect.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Release 3.0: lock_put</h1> -<p>An argument change has been made in the lock_put interface. -<p>The application should be searched for any occurrences of lock_put. -For each one, instead of passing a DB_LOCK variable as the last argument -to the function, the address of the DB_LOCK variable should be passed. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/upgrade.3.0/close.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.3.0/lock_detect.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/libdb/docs/ref/upgrade.3.0/lock_stat.html b/libdb/docs/ref/upgrade.3.0/lock_stat.html deleted file mode 100644 index 0c06fc429..000000000 --- a/libdb/docs/ref/upgrade.3.0/lock_stat.html +++ /dev/null @@ -1,25 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Release 3.0: lock_stat</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Upgrading Berkeley DB Applications</dl></h3></td> -<td align=right><a href="../../ref/upgrade.3.0/lock_detect.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.3.0/log_register.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Release 3.0: lock_stat</h1> -<p>The <b>st_magic</b>, <b>st_version</b>, <b>st_numobjs</b> and -<b>st_refcnt</b> fields returned from the lock_stat interface -have been removed, and this information is no longer available. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/upgrade.3.0/lock_detect.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.3.0/log_register.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/libdb/docs/ref/upgrade.3.0/log_register.html b/libdb/docs/ref/upgrade.3.0/log_register.html deleted file mode 100644 index 77f9a4098..000000000 --- a/libdb/docs/ref/upgrade.3.0/log_register.html +++ /dev/null @@ -1,26 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Release 3.0: log_register</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Upgrading Berkeley DB Applications</dl></h3></td> -<td align=right><a href="../../ref/upgrade.3.0/lock_stat.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.3.0/log_stat.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Release 3.0: log_register</h1> -<p>An argument has been removed from the log_register interface. The -application should be searched for any occurrences of log_register. In -each of these, the DBTYPE argument (it is the fourth argument) should -be removed. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/upgrade.3.0/lock_stat.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.3.0/log_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/libdb/docs/ref/upgrade.3.0/log_stat.html b/libdb/docs/ref/upgrade.3.0/log_stat.html deleted file mode 100644 index fc7f0a4da..000000000 --- a/libdb/docs/ref/upgrade.3.0/log_stat.html +++ /dev/null @@ -1,24 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Release 3.0: log_stat</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Upgrading Berkeley DB Applications</dl></h3></td> -<td align=right><a href="../../ref/upgrade.3.0/log_register.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.3.0/memp_stat.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Release 3.0: log_stat</h1> -<p>The <b>st_refcnt</b> field returned from the log_stat interface -has been removed, and this information is no longer available. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/upgrade.3.0/log_register.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.3.0/memp_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/libdb/docs/ref/upgrade.3.0/memp_stat.html b/libdb/docs/ref/upgrade.3.0/memp_stat.html deleted file mode 100644 index 5d7acd73e..000000000 --- a/libdb/docs/ref/upgrade.3.0/memp_stat.html +++ /dev/null @@ -1,27 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Release 3.0: memp_stat</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Upgrading Berkeley DB Applications</dl></h3></td> -<td align=right><a href="../../ref/upgrade.3.0/log_stat.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.3.0/txn_begin.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Release 3.0: memp_stat</h1> -<p>The <b>st_refcnt</b> field returned from the memp_stat interface -has been removed, and this information is no longer available. -<p>The <b>st_cachesize</b> field returned from the memp_stat interface -has been replaced with two new fields, <b>st_gbytes</b> and -<b>st_bytes</b>. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/upgrade.3.0/log_stat.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.3.0/txn_begin.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/libdb/docs/ref/upgrade.3.0/open.html b/libdb/docs/ref/upgrade.3.0/open.html deleted file mode 100644 index 995942f00..000000000 --- a/libdb/docs/ref/upgrade.3.0/open.html +++ /dev/null @@ -1,66 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Release 3.0: database open/close</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Upgrading Berkeley DB Applications</dl></h3></td> -<td align=right><a href="../../ref/upgrade.3.0/dbenv.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.3.0/xa.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Release 3.0: database open/close</h1> -<p>Database opens were changed in the Berkeley DB 3.0 release in a similar way to -environment opens. -<p>To upgrade your application, first find each place your application opens -a database, that is, calls the db_open function. Each of these calls -should be replaced with calls to <a href="../../api_c/db_create.html">db_create</a> and <a href="../../api_c/db_open.html">DB->open</a>. -<p>Here's an example creating a Berkeley DB database using the 2.X interface: -<p><blockquote><pre>DB *dbp; -DB_ENV *dbenv; -int ret; -<p> -if ((ret = db_open(DATABASE, - DB_BTREE, DB_CREATE, 0664, dbenv, NULL, &dbp)) != 0) - return (ret);</pre></blockquote> -<p>In the Berkeley DB 3.0 release, this code would be written as: -<p><blockquote><pre>DB *dbp; -DB_ENV *dbenv; -int ret; -<p> -if ((ret = db_create(&dbp, dbenv, 0)) != 0) - return (ret); -<p> -if ((ret = dbp->open(dbp, - DATABASE, NULL, DB_BTREE, DB_CREATE, 0664)) != 0) { - (void)dbp->close(dbp, 0); - return (ret); -}</pre></blockquote> -<p>As you can see, the arguments to db_open and to <a href="../../api_c/db_open.html">DB->open</a> are -largely the same. There is some re-organization, and note that the -enclosing <a href="../../api_c/env_class.html">DB_ENV</a> structure is specified when the <a href="../../api_c/db_class.html">DB</a> object -is created using the <a href="../../api_c/db_create.html">db_create</a> interface. There is one -additional argument to <a href="../../api_c/db_open.html">DB->open</a>, argument #3. For backward -compatibility with the 2.X Berkeley DB releases, simply set that argument to -NULL. -<p>There are two additional issues with the db_open call. -<p>First, it was possible in the 2.X releases for an application to provide -an environment that did not contain a shared memory buffer pool as the -database environment, and Berkeley DB would create a private one automatically. -This functionality is no longer available, applications must specify the -<a href="../../api_c/env_open.html#DB_INIT_MPOOL">DB_INIT_MPOOL</a> flag if databases are going to be opened in the -environment. -<p>The final issue with upgrading the db_open call is that the DB_INFO -structure is no longer used, having been replaced by individual methods -on the <a href="../../api_c/db_class.html">DB</a> handle. That change is discussed in detail later in -this chapter. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/upgrade.3.0/dbenv.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.3.0/xa.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/libdb/docs/ref/upgrade.3.0/rmw.html b/libdb/docs/ref/upgrade.3.0/rmw.html deleted file mode 100644 index 926e3bb1e..000000000 --- a/libdb/docs/ref/upgrade.3.0/rmw.html +++ /dev/null @@ -1,32 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Release 3.0: DB_RMW</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Upgrading Berkeley DB Applications</dl></h3></td> -<td align=right><a href="../../ref/upgrade.3.0/txn_stat.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.3.0/lock_notheld.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Release 3.0: DB_RMW</h1> -<p>The following change applies only to applications using the -Berkeley DB Concurrent Data Store product. If your application is not using that product, -you can ignore this change. -<p>Historically, the Berkeley DB <a href="../../api_c/db_cursor.html">DB->cursor</a> interface took the DB_RMW flag -to indicate that the created cursor would be used for write operations on -the database. This flag has been renamed to the <a href="../../api_c/db_cursor.html#DB_WRITECURSOR">DB_WRITECURSOR</a> -flag. -<p>The application should be searched for any occurrences of DB_RMW. For -each of these, any that are arguments to the <a href="../../api_c/db_cursor.html">DB->cursor</a> function -should be changed to pass in the <a href="../../api_c/db_cursor.html#DB_WRITECURSOR">DB_WRITECURSOR</a> flag instead. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/upgrade.3.0/txn_stat.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.3.0/lock_notheld.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/libdb/docs/ref/upgrade.3.0/stat.html b/libdb/docs/ref/upgrade.3.0/stat.html deleted file mode 100644 index 18f7b9090..000000000 --- a/libdb/docs/ref/upgrade.3.0/stat.html +++ /dev/null @@ -1,25 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Release 3.0: DB->stat</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Upgrading Berkeley DB Applications</dl></h3></td> -<td align=right><a href="../../ref/upgrade.3.0/join.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.3.0/close.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Release 3.0: DB->stat</h1> -<p>The <b>bt_flags</b> field returned from the <a href="../../api_c/db_stat.html">DB->stat</a> interface -for Btree and Recno databases has been removed, and this information is -no longer available. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/upgrade.3.0/join.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.3.0/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/libdb/docs/ref/upgrade.3.0/toc.html b/libdb/docs/ref/upgrade.3.0/toc.html deleted file mode 100644 index 5942806a6..000000000 --- a/libdb/docs/ref/upgrade.3.0/toc.html +++ /dev/null @@ -1,55 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Upgrading Berkeley DB 2.X.X applications to Berkeley DB 3.0</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Upgrading Berkeley DB Applications</dl></h3></td> -<td align=right><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a> -</td></tr></table> -<p> -<h1 align=center>Upgrading Berkeley DB 2.X.X applications to Berkeley DB 3.0</h1> -<p><ol> -<p><li><a href="intro.html">Release 3.0: introduction</a> -<li><a href="envopen.html">Release 3.0: environment open/close/unlink</a> -<li><a href="func.html">Release 3.0: function arguments</a> -<li><a href="dbenv.html">Release 3.0: the DB_ENV structure</a> -<li><a href="open.html">Release 3.0: database open/close</a> -<li><a href="xa.html">Release 3.0: db_xa_open</a> -<li><a href="db.html">Release 3.0: the DB structure</a> -<li><a href="dbinfo.html">Release 3.0: the DBINFO structure</a> -<li><a href="join.html">Release 3.0: DB->join</a> -<li><a href="stat.html">Release 3.0: DB->stat</a> -<li><a href="close.html">Release 3.0: DB->sync and DB->close</a> -<li><a href="lock_put.html">Release 3.0: lock_put</a> -<li><a href="lock_detect.html">Release 3.0: lock_detect</a> -<li><a href="lock_stat.html">Release 3.0: lock_stat</a> -<li><a href="log_register.html">Release 3.0: log_register</a> -<li><a href="log_stat.html">Release 3.0: log_stat</a> -<li><a href="memp_stat.html">Release 3.0: memp_stat</a> -<li><a href="txn_begin.html">Release 3.0: txn_begin</a> -<li><a href="txn_commit.html">Release 3.0: txn_commit</a> -<li><a href="txn_stat.html">Release 3.0: txn_stat</a> -<li><a href="rmw.html">Release 3.0: DB_RMW</a> -<li><a href="lock_notheld.html">Release 3.0: DB_LOCK_NOTHELD</a> -<li><a href="eagain.html">Release 3.0: EAGAIN</a> -<li><a href="eacces.html">Release 3.0: EACCES</a> -<li><a href="jump_set.html">Release 3.0: db_jump_set</a> -<li><a href="value_set.html">Release 3.0: db_value_set</a> -<li><a href="dbenv_cxx.html">Release 3.0: the DbEnv class for C++ and Java</a> -<li><a href="db_cxx.html">Release 3.0: the Db class for C++ and Java</a> -<li><a href="cxx.html">Release 3.0: additional C++ changes</a> -<li><a href="java.html">Release 3.0: additional Java changes</a> -<li><a href="disk.html">Release 3.0: upgrade requirements</a> -</ol> -<table width="100%"><tr><td><br></td><td align=right><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a> -</td></tr></table> -<p><font size=1><a href="http://www.sleepycat.com">Copyright Sleepycat Software</a></font> -</body> -</html> diff --git a/libdb/docs/ref/upgrade.3.0/txn_begin.html b/libdb/docs/ref/upgrade.3.0/txn_begin.html deleted file mode 100644 index a723eca69..000000000 --- a/libdb/docs/ref/upgrade.3.0/txn_begin.html +++ /dev/null @@ -1,26 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Release 3.0: txn_begin</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Upgrading Berkeley DB Applications</dl></h3></td> -<td align=right><a href="../../ref/upgrade.3.0/memp_stat.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.3.0/txn_commit.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Release 3.0: txn_begin</h1> -<p>An additional argument has been added to the txn_begin interface. -<p>The application should be searched for any occurrences of txn_begin. -For each one, an argument of 0 should be appended to the current -arguments. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/upgrade.3.0/memp_stat.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.3.0/txn_commit.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/libdb/docs/ref/upgrade.3.0/txn_commit.html b/libdb/docs/ref/upgrade.3.0/txn_commit.html deleted file mode 100644 index 47567b577..000000000 --- a/libdb/docs/ref/upgrade.3.0/txn_commit.html +++ /dev/null @@ -1,26 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Release 3.0: txn_commit</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Upgrading Berkeley DB Applications</dl></h3></td> -<td align=right><a href="../../ref/upgrade.3.0/txn_begin.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.3.0/txn_stat.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Release 3.0: txn_commit</h1> -<p>An additional argument has been added to the txn_commit interface. -<p>The application should be searched for any occurrences of txn_commit. -For each one, an argument of 0 should be appended to the current -arguments. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/upgrade.3.0/txn_begin.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.3.0/txn_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/libdb/docs/ref/upgrade.3.0/txn_stat.html b/libdb/docs/ref/upgrade.3.0/txn_stat.html deleted file mode 100644 index 9e8f98e34..000000000 --- a/libdb/docs/ref/upgrade.3.0/txn_stat.html +++ /dev/null @@ -1,24 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Release 3.0: txn_stat</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Upgrading Berkeley DB Applications</dl></h3></td> -<td align=right><a href="../../ref/upgrade.3.0/txn_commit.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.3.0/rmw.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Release 3.0: txn_stat</h1> -<p>The <b>st_refcnt</b> field returned from the txn_stat interface -has been removed, and this information is no longer available. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/upgrade.3.0/txn_commit.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.3.0/rmw.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/libdb/docs/ref/upgrade.3.0/value_set.html b/libdb/docs/ref/upgrade.3.0/value_set.html deleted file mode 100644 index d51412e24..000000000 --- a/libdb/docs/ref/upgrade.3.0/value_set.html +++ /dev/null @@ -1,42 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Release 3.0: db_value_set</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Upgrading Berkeley DB Applications</dl></h3></td> -<td align=right><a href="../../ref/upgrade.3.0/jump_set.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.3.0/dbenv_cxx.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Release 3.0: db_value_set</h1> -<p>The db_value_set interface has been removed from the Berkeley DB 3.0 release, -replaced by method calls on the <a href="../../api_c/env_class.html">DB_ENV</a> handle. -<p>The following table lists the db_value_set arguments previously used by -applications and the interfaces that should now be used instead. -<p><table border=1 align=center> -<tr><th>db_value_set argument</th><th>Berkeley DB 3.X method</th></tr> -<tr><td>DB_MUTEX_LOCKS</td><td>dbenv_set_mutexlocks</td></tr> -<tr><td>DB_REGION_ANON</td><td>The DB_REGION_ANON functionality has -been replaced by the <a href="../../api_c/env_open.html#DB_SYSTEM_MEM">DB_SYSTEM_MEM</a> and <a href="../../api_c/env_open.html#DB_PRIVATE">DB_PRIVATE</a> flags -to the <a href="../../api_c/env_open.html">DB_ENV->open</a> function. A direct translation is not -available, please review the <a href="../../api_c/env_open.html">DB_ENV->open</a> manual page for more -information.</td></tr> -<tr><td>DB_REGION_INIT</td><td>dbenv_set_region_init</td></tr> -<tr><td>DB_REGION_NAME</td><td>The DB_REGION_NAME functionality has -been replaced by the <a href="../../api_c/env_open.html#DB_SYSTEM_MEM">DB_SYSTEM_MEM</a> and <a href="../../api_c/env_open.html#DB_PRIVATE">DB_PRIVATE</a> flags -to the <a href="../../api_c/env_open.html">DB_ENV->open</a> function. A direct translation is not -available, please review the <a href="../../api_c/env_open.html">DB_ENV->open</a> manual page for more -information.</td></tr> -<tr><td>DB_TSL_SPINS</td><td>dbenv_set_tas_spins</td></tr> -</table> -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/upgrade.3.0/jump_set.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.3.0/dbenv_cxx.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/libdb/docs/ref/upgrade.3.0/xa.html b/libdb/docs/ref/upgrade.3.0/xa.html deleted file mode 100644 index 2756e69dc..000000000 --- a/libdb/docs/ref/upgrade.3.0/xa.html +++ /dev/null @@ -1,34 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Release 3.0: db_xa_open</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Upgrading Berkeley DB Applications</dl></h3></td> -<td align=right><a href="../../ref/upgrade.3.0/open.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.3.0/db.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Release 3.0: db_xa_open</h1> -<p>The following change applies only to applications using Berkeley DB as an XA -Resource Manager. If your application is not using Berkeley DB in this way, -you can ignore this change. -<p>The db_xa_open function has been replaced with the <a href="../../api_c/db_create.html#DB_XA_CREATE">DB_XA_CREATE</a> -flag to the <a href="../../api_c/db_create.html">db_create</a> function. All calls to db_xa_open should -be replaced with calls to <a href="../../api_c/db_create.html">db_create</a> with the <a href="../../api_c/db_create.html#DB_XA_CREATE">DB_XA_CREATE</a> -flag set, followed by a call to the <a href="../../api_c/db_open.html">DB->open</a> function. -<p>A similar change has been made for the C++ API, where the -<a href="../../api_c/db_create.html#DB_XA_CREATE">DB_XA_CREATE</a> flag should be specified to the Db constructor. All -calls to the Db::xa_open method should be replaced with the -<a href="../../api_c/db_create.html#DB_XA_CREATE">DB_XA_CREATE</a> flag to the Db constructor, followed by a call to -the DB::open method. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/upgrade.3.0/open.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.3.0/db.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/libdb/docs/ref/upgrade.3.1/btstat.html b/libdb/docs/ref/upgrade.3.1/btstat.html deleted file mode 100644 index c077e8893..000000000 --- a/libdb/docs/ref/upgrade.3.1/btstat.html +++ /dev/null @@ -1,51 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Release 3.1: DB->stat</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Upgrading Berkeley DB Applications</dl></h3></td> -<td align=right><a href="../../ref/upgrade.3.1/dup.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.3.1/sysmem.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Release 3.1: DB->stat</h1> -<p>For Btree database statistics, the <a href="../../api_c/db_stat.html">DB->stat</a> interface field -<b>bt_nrecs</b> has been removed, replaced by two fields: -<b>bt_nkeys</b> and <b>bt_ndata</b>. The <b>bt_nkeys</b> field returns -a count of the unique keys in the database. The <b>bt_ndata</b> field -returns a count of the key/data pairs in the database. Neither exactly -matches the previous value of the <b>bt_nrecs</b> field, which returned -a count of keys in the database, but, in the case of Btree databases, -could overcount as it sometimes counted duplicate data items as unique -keys. The application should be searched for any uses of the -<b>bt_nrecs</b> field and the field should be changed to be either -<b>bt_nkeys</b> or <b>bt_ndata</b>, whichever is more appropriate. -<p>For Hash database statistics, the <a href="../../api_c/db_stat.html">DB->stat</a> interface field -<b>hash_nrecs</b> has been removed, replaced by two fields: -<b>hash_nkeys</b> and <b>hash_ndata</b>. The <b>hash_nkeys</b> field -returns a count of the unique keys in the database. The -<b>hash_ndata</b> field returns a count of the key/data pairs in the -database. The new <b>hash_nkeys</b> field exactly matches the previous -value of the <b>hash_nrecs</b> field. The application should be searched -for any uses of the <b>hash_nrecs</b> field, and the field should be -changed to be <b>hash_nkeys</b>. -<p>For Queue database statistics, the <a href="../../api_c/db_stat.html">DB->stat</a> interface field -<b>qs_nrecs</b> has been removed, replaced by two fields: -<b>qs_nkeys</b> and <b>qs_ndata</b>. The <b>qs_nkeys</b> field returns -a count of the unique keys in the database. The <b>qs_ndata</b> field -returns a count of the key/data pairs in the database. The new -<b>qs_nkeys</b> field exactly matches the previous value of the -<b>qs_nrecs</b> field. The application should be searched for any uses -of the <b>qs_nrecs</b> field, and the field should be changed to be -<b>qs_nkeys</b>. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/upgrade.3.1/dup.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.3.1/sysmem.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/libdb/docs/ref/upgrade.3.1/config.html b/libdb/docs/ref/upgrade.3.1/config.html deleted file mode 100644 index 756767f0e..000000000 --- a/libdb/docs/ref/upgrade.3.1/config.html +++ /dev/null @@ -1,36 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Release 3.1: DB_ENV->open, DB_ENV->remove</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Upgrading Berkeley DB Applications</dl></h3></td> -<td align=right><a href="../../ref/upgrade.3.1/intro.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.3.1/set_tx_recover.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Release 3.1: DB_ENV->open, DB_ENV->remove</h1> -<p>In the Berkeley DB 3.1 release, the <b>config</b> argument to the -<a href="../../api_c/env_open.html">DB_ENV->open</a>, <a href="../../api_c/env_remove.html">DB_ENV->remove</a> methods has been removed, -replaced by additional methods on the <a href="../../api_c/env_class.html">DB_ENV</a> handle. If your -application calls <a href="../../api_c/env_open.html">DB_ENV->open</a> or <a href="../../api_c/env_remove.html">DB_ENV->remove</a> with a NULL -<b>config</b> argument, find those functions and remove the config -argument from the call. If your application has non-NULL <b>config</b> -argument, the strings values in that argument are replaced with calls to -<a href="../../api_c/env_class.html">DB_ENV</a> methods as follows: -<p><table border=1 align=center> -<tr><th>Previous config string</th><th>Berkeley DB 3.1 version method</th></tr> -<tr><td>DB_DATA_DIR</td><td><a href="../../api_c/env_set_data_dir.html">DB_ENV->set_data_dir</a></td></tr> -<tr><td>DB_LOG_DIR</td><td><a href="../../api_c/env_set_lg_dir.html">DB_ENV->set_lg_dir</a></td></tr> -<tr><td>DB_TMP_DIR</td><td><a href="../../api_c/env_set_tmp_dir.html">DB_ENV->set_tmp_dir</a></td></tr> -</table> -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/upgrade.3.1/intro.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.3.1/set_tx_recover.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/libdb/docs/ref/upgrade.3.1/disk.html b/libdb/docs/ref/upgrade.3.1/disk.html deleted file mode 100644 index d4c1b3485..000000000 --- a/libdb/docs/ref/upgrade.3.1/disk.html +++ /dev/null @@ -1,35 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Release 3.1: upgrade requirements</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Upgrading Berkeley DB Applications</dl></h3></td> -<td align=right><a href="../../ref/upgrade.3.1/logalloc.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.3.2/intro.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Release 3.1: upgrade requirements</h1> -<p>Log file formats and the Btree, Queue, Recno and Hash Access Method -database formats changed in the Berkeley DB 3.1 release. (The on-disk -Btree/Recno format changed from version 7 to version 8. The on-disk -Hash format changed from version 6 to version 7. The on-disk Queue -format changed from version 1 to version 2.) Until the underlying -databases are upgraded, the <a href="../../api_c/db_open.html">DB->open</a> method will return a -<a href="../../api_c/db_open.html#DB_OLD_VERSION">DB_OLD_VERSION</a> error. -<p>An additional flag, <a href="../../api_c/db_set_flags.html#DB_DUPSORT">DB_DUPSORT</a>, has been added to the -<a href="../../api_c/db_upgrade.html">DB->upgrade</a> method for this upgrade. Please review the -<a href="../../api_c/db_upgrade.html">DB->upgrade</a> documentation for further information. -<p>For further information on upgrading Berkeley DB installations, see -<a href="../../ref/upgrade/process.html">Upgrading Berkeley DB -installations</a>. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/upgrade.3.1/logalloc.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.3.2/intro.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/libdb/docs/ref/upgrade.3.1/dup.html b/libdb/docs/ref/upgrade.3.1/dup.html deleted file mode 100644 index 786364b4a..000000000 --- a/libdb/docs/ref/upgrade.3.1/dup.html +++ /dev/null @@ -1,32 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Release 3.1: identical duplicate data items</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Upgrading Berkeley DB Applications</dl></h3></td> -<td align=right><a href="../../ref/upgrade.3.1/put.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.3.1/btstat.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Release 3.1: identical duplicate data items</h1> -<p>In previous releases of Berkeley DB, it was not an error to store identical -duplicate data items, or, for those that just like the way it sounds, -duplicate duplicates. However, there were implementation bugs where -storing duplicate duplicates could cause database corruption. -<p>In this release, applications may store identical duplicate data items -as long as the data items are unsorted. It is an error to attempt to -store identical duplicate data items when duplicates are being stored -in a sorted order. This restriction is expected to be lifted in a future -release. See <a href="../../ref/am_conf/dup.html">Duplicate data items</a> -for more information. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/upgrade.3.1/put.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.3.1/btstat.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/libdb/docs/ref/upgrade.3.1/env.html b/libdb/docs/ref/upgrade.3.1/env.html deleted file mode 100644 index 096cc9211..000000000 --- a/libdb/docs/ref/upgrade.3.1/env.html +++ /dev/null @@ -1,54 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Release 3.1: environment configuration</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Upgrading Berkeley DB Applications</dl></h3></td> -<td align=right><a href="../../ref/upgrade.3.1/txn_check.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.3.1/tcl.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Release 3.1: environment configuration</h1> -<p>A set of <a href="../../api_c/env_class.html">DB_ENV</a> configuration methods which were not environment -specific, but which instead affected the entire application space, have -been removed from the <a href="../../api_c/env_class.html">DB_ENV</a> object and replaced by static -functions. The following table lists the <a href="../../api_c/env_class.html">DB_ENV</a> methods previously -available to applications and the static functions that should now be used -instead. -<p><table border=1 align=center> -<tr><th><a href="../../api_c/env_class.html">DB_ENV</a> method</th><th>Berkeley DB 3.1 function</th></tr> -<tr><td>DB_ENV->set_func_close</td><td><a href="../../api_c/set_func_close.html">db_env_set_func_close</a></td></tr> -<tr><td>DB_ENV->set_func_dirfree</td><td><a href="../../api_c/set_func_dirfree.html">db_env_set_func_dirfree</a></td></tr> -<tr><td>DB_ENV->set_func_dirlist</td><td><a href="../../api_c/set_func_dirlist.html">db_env_set_func_dirlist</a></td></tr> -<tr><td>DB_ENV->set_func_exists</td><td><a href="../../api_c/set_func_exists.html">db_env_set_func_exists</a></td></tr> -<tr><td>DB_ENV->set_func_free</td><td><a href="../../api_c/set_func_free.html">db_env_set_func_free</a></td></tr> -<tr><td>DB_ENV->set_func_fsync</td><td><a href="../../api_c/set_func_fsync.html">db_env_set_func_fsync</a></td></tr> -<tr><td>DB_ENV->set_func_ioinfo</td><td><a href="../../api_c/set_func_ioinfo.html">db_env_set_func_ioinfo</a></td></tr> -<tr><td>DB_ENV->set_func_malloc</td><td><a href="../../api_c/set_func_malloc.html">db_env_set_func_malloc</a></td></tr> -<tr><td>DB_ENV->set_func_map</td><td><a href="../../api_c/set_func_map.html">db_env_set_func_map</a></td></tr> -<tr><td>DB_ENV->set_func_open</td><td><a href="../../api_c/set_func_open.html">db_env_set_func_open</a></td></tr> -<tr><td>DB_ENV->set_func_read</td><td><a href="../../api_c/set_func_read.html">db_env_set_func_read</a></td></tr> -<tr><td>DB_ENV->set_func_realloc</td><td><a href="../../api_c/set_func_realloc.html">db_env_set_func_realloc</a></td></tr> -<tr><td>DB_ENV->set_func_rename</td><td><a href="../../api_c/set_func_rename.html">db_env_set_func_rename</a></td></tr> -<tr><td>DB_ENV->set_func_seek</td><td><a href="../../api_c/set_func_seek.html">db_env_set_func_seek</a></td></tr> -<tr><td>DB_ENV->set_func_sleep</td><td><a href="../../api_c/set_func_sleep.html">db_env_set_func_sleep</a></td></tr> -<tr><td>DB_ENV->set_func_unlink</td><td><a href="../../api_c/set_func_unlink.html">db_env_set_func_unlink</a></td></tr> -<tr><td>DB_ENV->set_func_unmap</td><td><a href="../../api_c/set_func_unmap.html">db_env_set_func_unmap</a></td></tr> -<tr><td>DB_ENV->set_func_write</td><td><a href="../../api_c/set_func_write.html">db_env_set_func_write</a></td></tr> -<tr><td>DB_ENV->set_func_yield</td><td><a href="../../api_c/set_func_yield.html">db_env_set_func_yield</a></td></tr> -<tr><td>DB_ENV->set_pageyield</td><td>dbenv_set_pageyield</td></tr> -<tr><td>DB_ENV->set_region_init</td><td>dbenv_set_region_init</td></tr> -<tr><td>DB_ENV->set_mutexlocks</td><td>dbenv_set_mutexlocks</td></tr> -<tr><td>DB_ENV->set_tas_spins</td><td>dbenv_set_tas_spins</td></tr> -</table> -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/upgrade.3.1/txn_check.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.3.1/tcl.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/libdb/docs/ref/upgrade.3.1/intro.html b/libdb/docs/ref/upgrade.3.1/intro.html deleted file mode 100644 index 8206afc56..000000000 --- a/libdb/docs/ref/upgrade.3.1/intro.html +++ /dev/null @@ -1,27 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Release 3.1: introduction</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Upgrading Berkeley DB Applications</dl></h3></td> -<td align=right><a href="../../ref/upgrade.3.0/disk.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.3.1/config.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Release 3.1: introduction</h1> -<p>The following pages describe how to upgrade applications coded against -the Berkeley DB 3.0 release interfaces to the Berkeley DB 3.1 release interfaces. -This information does not describe how to upgrade Berkeley DB 1.85 release -applications. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/upgrade.3.0/disk.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.3.1/config.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/libdb/docs/ref/upgrade.3.1/log_register.html b/libdb/docs/ref/upgrade.3.1/log_register.html deleted file mode 100644 index 1b319980c..000000000 --- a/libdb/docs/ref/upgrade.3.1/log_register.html +++ /dev/null @@ -1,29 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Release 3.1: log_register</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Upgrading Berkeley DB Applications</dl></h3></td> -<td align=right><a href="../../ref/upgrade.3.1/sysmem.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.3.1/memp_register.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Release 3.1: log_register</h1> -<p>The arguments to the log_register and log_unregister interfaces have -changed. Instead of returning (and passing in) a logging file ID, a -reference to the <a href="../../api_c/db_class.html">DB</a> structure being registered (or unregistered) -is passed. The application should be searched for any occurrences of -log_register and log_unregister. For each one, change the arguments to -be a reference to the <a href="../../api_c/db_class.html">DB</a> structure being registered or -unregistered. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/upgrade.3.1/sysmem.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.3.1/memp_register.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/libdb/docs/ref/upgrade.3.1/logalloc.html b/libdb/docs/ref/upgrade.3.1/logalloc.html deleted file mode 100644 index 9f54e86bc..000000000 --- a/libdb/docs/ref/upgrade.3.1/logalloc.html +++ /dev/null @@ -1,28 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Release 3.1: log file pre-allocation</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Upgrading Berkeley DB Applications</dl></h3></td> -<td align=right><a href="../../ref/upgrade.3.1/tmp.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.3.1/disk.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Release 3.1: log file pre-allocation</h1> -<p>This change only affects Win/32 applications. -<p>On Win/32 platforms Berkeley DB no longer pre-allocates log files. The problem -was a noticeable performance spike as each log file was created. To turn -this feature back on, search for the flag DB_OSO_LOG in the source file -<b>log/log_put.c</b> and make the change described there, or contact -Sleepycat Software for assistance. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/upgrade.3.1/tmp.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.3.1/disk.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/libdb/docs/ref/upgrade.3.1/memp_register.html b/libdb/docs/ref/upgrade.3.1/memp_register.html deleted file mode 100644 index b0ce4403e..000000000 --- a/libdb/docs/ref/upgrade.3.1/memp_register.html +++ /dev/null @@ -1,31 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Release 3.1: memp_register</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Upgrading Berkeley DB Applications</dl></h3></td> -<td align=right><a href="../../ref/upgrade.3.1/log_register.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.3.1/txn_check.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Release 3.1: memp_register</h1> -<p>An additional argument has been added to the <b>pgin</b> and -<b>pgout</b> functions provided to the memp_register interface. -The application should be searched for any occurrences of -memp_register. For each one, if <b>pgin</b> or <b>pgout</b> -functions are specified, the <b>pgin</b> and <b>pgout</b> functions -should be modified to take an initial argument of a <b>DB_ENV *</b>. -This argument is intended to support better error reporting for -applications, and may be entirely ignored by the <b>pgin</b> and -<b>pgout</b> functions themselves. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/upgrade.3.1/log_register.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.3.1/txn_check.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/libdb/docs/ref/upgrade.3.1/put.html b/libdb/docs/ref/upgrade.3.1/put.html deleted file mode 100644 index f0d583147..000000000 --- a/libdb/docs/ref/upgrade.3.1/put.html +++ /dev/null @@ -1,65 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Release 3.1: DB->put</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Upgrading Berkeley DB Applications</dl></h3></td> -<td align=right><a href="../../ref/upgrade.3.1/set_paniccall.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.3.1/dup.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Release 3.1: DB->put</h1> -<p>For the Queue and Recno access methods, when the <a href="../../api_c/db_put.html#DB_APPEND">DB_APPEND</a> flag -is specified to the <a href="../../api_c/db_put.html">DB->put</a> interface, the allocated record -number is returned to the application in the <b>key</b> <a href="../../api_c/dbt_class.html">DBT</a> -argument. In previous releases of Berkeley DB, this <a href="../../api_c/dbt_class.html">DBT</a> structure -did not follow the usual <a href="../../api_c/dbt_class.html">DBT</a> conventions. For example, it was -not possible to cause Berkeley DB to allocate space for the returned record -number. Rather, it was always assumed that the <b>data</b> field of -the <b>key</b> structure referred to memory that could be used as -storage for a db_recno_t type. -<p>As of the Berkeley DB 3.1.0 release, the <b>key</b> structure behaves as -described in the <a href="../../api_c/dbt_class.html">DBT</a> C++/Java class or C structure documentation. -<p>Applications which are using the <a href="../../api_c/db_put.html#DB_APPEND">DB_APPEND</a> flag for Queue and -Recno access method databases will require a change to upgrade to the -Berkeley DB 3.1 releases. The simplest change is likely to be to add the -<a href="../../api_c/dbt_class.html#DB_DBT_USERMEM">DB_DBT_USERMEM</a> flag to the <b>key</b> structure. For example, -code that appears as follows: -<p><blockquote><pre>DBT key; -db_recno_t recno; -<p> -memset(&key, 0, sizeof(DBT)); -key.data = &recno; -key.size = sizeof(recno); -DB->put(DB, NULL, &key, &data, DB_APPEND); -printf("new record number is %lu\n", (u_long)recno);</pre></blockquote> -<p>would be changed to: -<p><blockquote><pre>DBT key; -db_recno_t recno; -<p> -memset(&key, 0, sizeof(DBT)); -key.data = &recno; -key.ulen = sizeof(recno); -key.flags = DB_DBT_USERMEM; -DB->put(DB, NULL, &key, &data, DB_APPEND); -printf("new record number is %lu\n", (u_long)recno);</pre></blockquote> -<p>Note that the <b>ulen</b> field is now set as well as the flag value. -An alternative change would be: -<p><blockquote><pre>DBT key; -db_recno_t recno; -<p> -memset(&key, 0, sizeof(DBT)); -DB->put(DB, NULL, &key, &data, DB_APPEND); -recno = *(db_recno_t *)key->data; -printf("new record number is %lu\n", (u_long)recno);</pre></blockquote> -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/upgrade.3.1/set_paniccall.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.3.1/dup.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/libdb/docs/ref/upgrade.3.1/set_feedback.html b/libdb/docs/ref/upgrade.3.1/set_feedback.html deleted file mode 100644 index ceb8d7586..000000000 --- a/libdb/docs/ref/upgrade.3.1/set_feedback.html +++ /dev/null @@ -1,28 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Release 3.1: DB_ENV->set_feedback, DB->set_feedback</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Upgrading Berkeley DB Applications</dl></h3></td> -<td align=right><a href="../../ref/upgrade.3.1/set_tx_recover.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.3.1/set_paniccall.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Release 3.1: DB_ENV->set_feedback, DB->set_feedback</h1> -<p>Starting with the 3.1 release of Berkeley DB, the <a href="../../api_c/env_set_feedback.html">DB_ENV->set_feedback</a> -and <a href="../../api_c/db_set_feedback.html">DB->set_feedback</a> methods may return an error value, that is, they -are no longer declared as returning no value, instead they return an int -or throw an exception as appropriate when an error occurs. -<p>If your application calls these functions, you may want to check for a -possible error on return. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/upgrade.3.1/set_tx_recover.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.3.1/set_paniccall.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/libdb/docs/ref/upgrade.3.1/set_paniccall.html b/libdb/docs/ref/upgrade.3.1/set_paniccall.html deleted file mode 100644 index fff271d73..000000000 --- a/libdb/docs/ref/upgrade.3.1/set_paniccall.html +++ /dev/null @@ -1,28 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Release 3.1: DB_ENV->set_paniccall, DB->set_paniccall</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Upgrading Berkeley DB Applications</dl></h3></td> -<td align=right><a href="../../ref/upgrade.3.1/set_feedback.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.3.1/put.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Release 3.1: DB_ENV->set_paniccall, DB->set_paniccall</h1> -<p>Starting with the 3.1 release of Berkeley DB, the <a href="../../api_c/env_set_paniccall.html">DB_ENV->set_paniccall</a> -and <a href="../../api_c/db_set_paniccall.html">DB->set_paniccall</a> methods may return an error value, that is, they -are no longer declared as returning no value, instead they return an int -or throw an exception as appropriate when an error occurs. -<p>If your application calls these functions, you may want to check for a -possible error on return. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/upgrade.3.1/set_feedback.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.3.1/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/libdb/docs/ref/upgrade.3.1/set_tx_recover.html b/libdb/docs/ref/upgrade.3.1/set_tx_recover.html deleted file mode 100644 index b23080780..000000000 --- a/libdb/docs/ref/upgrade.3.1/set_tx_recover.html +++ /dev/null @@ -1,37 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Release 3.1: DB_ENV->set_tx_recover</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Upgrading Berkeley DB Applications</dl></h3></td> -<td align=right><a href="../../ref/upgrade.3.1/config.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.3.1/set_feedback.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Release 3.1: DB_ENV->set_tx_recover</h1> -<p>The redo parameter of the function passed to DB_ENV->set_tx_recover -used to be an integer set to any one of a number of #defined values. In -the 3.1 release of Berkeley DB, the redo parameter has been replaced by the op -parameter which is an enumerated type of type db_recops. -<p>If your application calls DB_ENV->set_tx_recover, then find the -function referred to by the call. Replace the flag values in that -function as follows: -<p><table border=1 align=center> -<tr><th>Previous flag</th><th>Berkeley DB 3.1 version flag</th></tr> -<tr><td>TXN_BACKWARD_ROLL</td><td>DB_TXN_BACKWARD_ROLL</td></tr> -<tr><td>TXN_FORWARD_ROLL</td><td>DB_TXN_FORWARD_ROLL</td></tr> -<tr><td>TXN_OPENFILES</td><td>DB_TXN_OPENFILES</td></tr> -<tr><td>TXN_REDO</td><td>DB_TXN_FORWARD_ROLL</td></tr> -<tr><td>TXN_UNDO</td><td>DB_TXN_ABORT</td></tr> -</table> -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/upgrade.3.1/config.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.3.1/set_feedback.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/libdb/docs/ref/upgrade.3.1/sysmem.html b/libdb/docs/ref/upgrade.3.1/sysmem.html deleted file mode 100644 index f73eaf112..000000000 --- a/libdb/docs/ref/upgrade.3.1/sysmem.html +++ /dev/null @@ -1,26 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Release 3.1: DB_SYSTEM_MEM</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Upgrading Berkeley DB Applications</dl></h3></td> -<td align=right><a href="../../ref/upgrade.3.1/btstat.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.3.1/log_register.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Release 3.1: DB_SYSTEM_MEM</h1> -<p>Using the <a href="../../api_c/env_open.html#DB_SYSTEM_MEM">DB_SYSTEM_MEM</a> option on UNIX systems now requires the -specification of a base system memory segment ID, using the -<a href="../../api_c/env_set_shm_key.html">DB_ENV->set_shm_key</a> method. Any valid segment ID may be specified, for -example, one returned by the UNIX <b>ftok</b>(3) interface. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/upgrade.3.1/btstat.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.3.1/log_register.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/libdb/docs/ref/upgrade.3.1/tcl.html b/libdb/docs/ref/upgrade.3.1/tcl.html deleted file mode 100644 index 14cda3ded..000000000 --- a/libdb/docs/ref/upgrade.3.1/tcl.html +++ /dev/null @@ -1,32 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Release 3.1: Tcl API</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Upgrading Berkeley DB Applications</dl></h3></td> -<td align=right><a href="../../ref/upgrade.3.1/env.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.3.1/tmp.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Release 3.1: Tcl API</h1> -<p>The Berkeley DB Tcl API has been modified so that the <b>-mpool</b> option to -the <b>berkdb env</b> command is now the default behavior. The Tcl API -has also been modified so that the <b>-txn</b> option to the -<b>berkdb env</b> command implies the <b>-lock</b> and <b>-log</b> -options. Tcl scripts should be updated to remove the <b>-mpool</b>, -<b>-lock</b> and <b>-log</b> options. -<p>The Berkeley DB Tcl API has been modified to follow the Tcl standard rules -for integer conversion, for example, if the first two characters of a -record number are "0x", the record number is expected to be in -hexadecimal form. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/upgrade.3.1/env.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.3.1/tmp.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/libdb/docs/ref/upgrade.3.1/tmp.html b/libdb/docs/ref/upgrade.3.1/tmp.html deleted file mode 100644 index f183b9b4b..000000000 --- a/libdb/docs/ref/upgrade.3.1/tmp.html +++ /dev/null @@ -1,35 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Release 3.1: DB_TMP_DIR</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Upgrading Berkeley DB Applications</dl></h3></td> -<td align=right><a href="../../ref/upgrade.3.1/tcl.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.3.1/logalloc.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Release 3.1: DB_TMP_DIR</h1> -<p>This change only affects Win/32 applications that create in-memory -databases. -<p>On Win/32 platforms an additional test has been added when searching for -the appropriate directory in which to create the temporary files that are -used to back in-memory databases. Berkeley DB now uses any return value from -the GetTempPath interface as the temporary file directory name before -resorting to the static list of compiled-in pathnames. -<p>If the system registry does not return the same directory as Berkeley DB has -been using previously, this change could cause temporary backing files to -move to a new directory when applications are upgraded to the 3.1 release. -In extreme cases, this could create (or fix) security problems if the file -protection modes for the system registry directory are different from -those on the directory previously used by Berkeley DB. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/upgrade.3.1/tcl.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.3.1/logalloc.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/libdb/docs/ref/upgrade.3.1/toc.html b/libdb/docs/ref/upgrade.3.1/toc.html deleted file mode 100644 index 327924b30..000000000 --- a/libdb/docs/ref/upgrade.3.1/toc.html +++ /dev/null @@ -1,41 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Upgrading Berkeley DB 3.0.X applications to Berkeley DB 3.1</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Upgrading Berkeley DB Applications</dl></h3></td> -<td align=right><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a> -</td></tr></table> -<p> -<h1 align=center>Upgrading Berkeley DB 3.0.X applications to Berkeley DB 3.1</h1> -<p><ol> -<p><li><a href="intro.html">Release 3.1: introduction</a> -<li><a href="config.html">Release 3.1: DB_ENV->open, DB_ENV->remove</a> -<li><a href="set_tx_recover.html">Release 3.1: DB_ENV->set_tx_recover</a> -<li><a href="set_feedback.html">Release 3.1: DB_ENV->set_feedback, DB->set_feedback</a> -<li><a href="set_paniccall.html">Release 3.1: DB_ENV->set_paniccall, DB->set_paniccall</a> -<li><a href="put.html">Release 3.1: DB->put</a> -<li><a href="dup.html">Release 3.1: identical duplicate data items</a> -<li><a href="btstat.html">Release 3.1: DB->stat</a> -<li><a href="sysmem.html">Release 3.1: DB_SYSTEM_MEM</a> -<li><a href="log_register.html">Release 3.1: log_register</a> -<li><a href="memp_register.html">Release 3.1: memp_register</a> -<li><a href="txn_check.html">Release 3.1: txn_checkpoint</a> -<li><a href="env.html">Release 3.1: environment configuration</a> -<li><a href="tcl.html">Release 3.1: Tcl API</a> -<li><a href="tmp.html">Release 3.1: DB_TMP_DIR</a> -<li><a href="logalloc.html">Release 3.1: log file pre-allocation</a> -<li><a href="disk.html">Release 3.1: upgrade requirements</a> -</ol> -<table width="100%"><tr><td><br></td><td align=right><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a> -</td></tr></table> -<p><font size=1><a href="http://www.sleepycat.com">Copyright Sleepycat Software</a></font> -</body> -</html> diff --git a/libdb/docs/ref/upgrade.3.1/txn_check.html b/libdb/docs/ref/upgrade.3.1/txn_check.html deleted file mode 100644 index de490bff4..000000000 --- a/libdb/docs/ref/upgrade.3.1/txn_check.html +++ /dev/null @@ -1,26 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Release 3.1: txn_checkpoint</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Upgrading Berkeley DB Applications</dl></h3></td> -<td align=right><a href="../../ref/upgrade.3.1/memp_register.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.3.1/env.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Release 3.1: txn_checkpoint</h1> -<p>An additional argument has been added to the txn_checkpoint interface. -<p>The application should be searched for any occurrences of -txn_checkpoint. For each one, an argument of 0 should be appended to -the current arguments. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/upgrade.3.1/memp_register.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.3.1/env.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/libdb/docs/ref/upgrade.3.2/callback.html b/libdb/docs/ref/upgrade.3.2/callback.html deleted file mode 100644 index 35d37f44b..000000000 --- a/libdb/docs/ref/upgrade.3.2/callback.html +++ /dev/null @@ -1,40 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Release 3.2: DB callback functions, app_private field</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Upgrading Berkeley DB Applications</dl></h3></td> -<td align=right><a href="../../ref/upgrade.3.2/set_flags.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.3.2/renumber.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Release 3.2: DB callback functions, app_private field</h1> -<p>In the Berkeley DB 3.2 release, four application callback functions (the -callback functions set by <a href="../../api_c/db_set_bt_compare.html">DB->set_bt_compare</a>, -<a href="../../api_c/db_set_bt_prefix.html">DB->set_bt_prefix</a>, <a href="../../api_c/db_set_dup_compare.html">DB->set_dup_compare</a> and -<a href="../../api_c/db_set_h_hash.html">DB->set_h_hash</a>) were modified to take a reference to a -<a href="../../api_c/db_class.html">DB</a> object as their first argument. This change allows the Berkeley DB -Java API to reasonably support these interfaces. There is currently no -need for the callback functions to do anything with this additional -argument. -<p>C and C++ applications that specify their own Btree key comparison, -Btree prefix comparison, duplicate data item comparison or Hash -functions should modify these functions to take a reference to a -<a href="../../api_c/db_class.html">DB</a> structure as their first argument. No further change is -required. -<p>The app_private field of the <a href="../../api_c/dbt_class.html">DBT</a> structure (accessible only from -the Berkeley DB C API) has been removed in the 3.2 release. It was replaced -with app_private fields in the <a href="../../api_c/env_class.html">DB_ENV</a> and <a href="../../api_c/db_class.html">DB</a> handles. -Applications using this field will have to convert to using one of the -replacement fields. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/upgrade.3.2/set_flags.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.3.2/renumber.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/libdb/docs/ref/upgrade.3.2/db_dump.html b/libdb/docs/ref/upgrade.3.2/db_dump.html deleted file mode 100644 index e4be20223..000000000 --- a/libdb/docs/ref/upgrade.3.2/db_dump.html +++ /dev/null @@ -1,30 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Release 3.2: db_dump</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Upgrading Berkeley DB Applications</dl></h3></td> -<td align=right><a href="../../ref/upgrade.3.2/notfound.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.3.2/disk.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Release 3.2: db_dump</h1> -<p>In previous releases of Berkeley DB, the <a href="../../utility/db_dump.html">db_dump</a> utility dumped Recno -access method database keys as numeric strings. For consistency, the -<a href="../../utility/db_dump.html">db_dump</a> utility has been changed in the 3.2 release to dump -record numbers as hex pairs when the data items are being dumped as hex -pairs. (See the <b>-k</b> and <b>-p</b> options to the -<a href="../../utility/db_dump.html">db_dump</a> utility for more information.) Any applications or -scripts post-processing the <a href="../../utility/db_dump.html">db_dump</a> output of Recno databases -under these conditions may require modification. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/upgrade.3.2/notfound.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.3.2/disk.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/libdb/docs/ref/upgrade.3.2/disk.html b/libdb/docs/ref/upgrade.3.2/disk.html deleted file mode 100644 index bd9942728..000000000 --- a/libdb/docs/ref/upgrade.3.2/disk.html +++ /dev/null @@ -1,29 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Release 3.2: upgrade requirements</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Upgrading Berkeley DB Applications</dl></h3></td> -<td align=right><a href="../../ref/upgrade.3.2/db_dump.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.3.3/intro.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Release 3.2: upgrade requirements</h1> -<p>Log file formats and the Queue Access Method database formats changed -in the Berkeley DB 3.2 release. (The on-disk Queue format changed from -version 2 to version 3.) Until the underlying databases are upgraded, -the <a href="../../api_c/db_open.html">DB->open</a> method will return a <a href="../../api_c/db_open.html#DB_OLD_VERSION">DB_OLD_VERSION</a> error. -<p>For further information on upgrading Berkeley DB installations, see -<a href="../../ref/upgrade/process.html">Upgrading Berkeley DB -installations</a>. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/upgrade.3.2/db_dump.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.3.3/intro.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/libdb/docs/ref/upgrade.3.2/handle.html b/libdb/docs/ref/upgrade.3.2/handle.html deleted file mode 100644 index 8d8a2b554..000000000 --- a/libdb/docs/ref/upgrade.3.2/handle.html +++ /dev/null @@ -1,28 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Release 3.2: Java and C++ object reuse</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Upgrading Berkeley DB Applications</dl></h3></td> -<td align=right><a href="../../ref/upgrade.3.2/mutexlock.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.3.2/notfound.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Release 3.2: Java and C++ object reuse</h1> -<p>In previous releases of Berkeley DB, Java <a href="../../api_java/env_class.html">DbEnv</a> and <a href="../../api_java/db_class.html">Db</a> -objects, and C++ <a href="../../api_cxx/env_class.html">DbEnv</a> and <a href="../../api_cxx/db_class.html">Db</a> objects could be -reused after they were closed, by calling open on them again. This is -no longer permitted, and these objects no longer allow any operations -after a close. Applications reusing these objects should be modified -to create new objects instead. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/upgrade.3.2/mutexlock.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.3.2/notfound.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/libdb/docs/ref/upgrade.3.2/incomplete.html b/libdb/docs/ref/upgrade.3.2/incomplete.html deleted file mode 100644 index 830d314e4..000000000 --- a/libdb/docs/ref/upgrade.3.2/incomplete.html +++ /dev/null @@ -1,40 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Release 3.2: DB_INCOMPLETE</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Upgrading Berkeley DB Applications</dl></h3></td> -<td align=right><a href="../../ref/upgrade.3.2/renumber.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.3.2/tx_recover.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Release 3.2: DB_INCOMPLETE</h1> -<p>There are a number of functions that flush pages from the Berkeley DB shared -memory buffer pool to disk. Most of those functions can potentially -fail because a page that needs to be flushed is not currently available. -However, this is not a hard failure and is rarely cause for concern. -In the Berkeley DB 3.2 release, the C++ API (if that API is configured to -throw exceptions) and the Java API have been changed so that this -failure does not throw an exception, but rather returns a non-zero error -code of DB_INCOMPLETE. -<p>The following C++ methods will return DB_INCOMPLETE rather than throw -an exception: <a href="../../api_cxx/db_close.html">Db::close</a>, <a href="../../api_cxx/db_sync.html">Db::sync</a>, DbEnv::memp_sync, -DbEnv::txn_checkpoint, DbMpoolFile::memp_fsync. -<p>The following Java methods are now declared "public int" rather than -"public void", and will return Db.DB_INCOMPLETE rather than -throw an exception: <a href="../../api_java/db_close.html">Db.close</a>, <a href="../../api_java/db_sync.html">Db.sync</a>, -DbEnv.txn_checkpoint. -<p>It is likely that the only change required by any application will be -those currently checking for a DB_INCOMPLETE return that has -been encapsulated in an exception. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/upgrade.3.2/renumber.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.3.2/tx_recover.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/libdb/docs/ref/upgrade.3.2/intro.html b/libdb/docs/ref/upgrade.3.2/intro.html deleted file mode 100644 index 52bc236c6..000000000 --- a/libdb/docs/ref/upgrade.3.2/intro.html +++ /dev/null @@ -1,27 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Release 3.2: introduction</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Upgrading Berkeley DB Applications</dl></h3></td> -<td align=right><a href="../../ref/upgrade.3.1/disk.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.3.2/set_flags.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Release 3.2: introduction</h1> -<p>The following pages describe how to upgrade applications coded against -the Berkeley DB 3.1 release interfaces to the Berkeley DB 3.2 release interfaces. -This information does not describe how to upgrade Berkeley DB 1.85 release -applications. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/upgrade.3.1/disk.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.3.2/set_flags.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/libdb/docs/ref/upgrade.3.2/mutexlock.html b/libdb/docs/ref/upgrade.3.2/mutexlock.html deleted file mode 100644 index a20c1d578..000000000 --- a/libdb/docs/ref/upgrade.3.2/mutexlock.html +++ /dev/null @@ -1,29 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Release 3.2: DB_ENV->set_mutexlocks</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Upgrading Berkeley DB Applications</dl></h3></td> -<td align=right><a href="../../ref/upgrade.3.2/tx_recover.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.3.2/handle.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Release 3.2: DB_ENV->set_mutexlocks</h1> -<p>Previous Berkeley DB releases included the db_env_set_mutexlocks interface, -intended for debugging, that allows applications to always obtain -requested mutual exclusion mutexes without regard for their -availability. This interface has been replaced with -dbenv_set_mutexlocks, which provides the same functionality on a -per-database environment basis. Applications using the old interface -should be updated to use the new one. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/upgrade.3.2/tx_recover.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.3.2/handle.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/libdb/docs/ref/upgrade.3.2/notfound.html b/libdb/docs/ref/upgrade.3.2/notfound.html deleted file mode 100644 index 085ef06a6..000000000 --- a/libdb/docs/ref/upgrade.3.2/notfound.html +++ /dev/null @@ -1,26 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Release 3.2: Java java.io.FileNotFoundException</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Upgrading Berkeley DB Applications</dl></h3></td> -<td align=right><a href="../../ref/upgrade.3.2/handle.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.3.2/db_dump.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Release 3.2: Java java.io.FileNotFoundException</h1> -<p>The Java <a href="../../api_java/env_remove.html">DbEnv.remove</a>, <a href="../../api_java/db_remove.html">Db.remove</a> and -<a href="../../api_java/db_rename.html">Db.rename</a> methods now throw java.io.FileNotFoundException -in the case where the named file does not exist. Applications should -be modified to catch this exception where appropriate. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/upgrade.3.2/handle.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.3.2/db_dump.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/libdb/docs/ref/upgrade.3.2/renumber.html b/libdb/docs/ref/upgrade.3.2/renumber.html deleted file mode 100644 index 10bee1ee0..000000000 --- a/libdb/docs/ref/upgrade.3.2/renumber.html +++ /dev/null @@ -1,40 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Release 3.2: Logically renumbering 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> -<table width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Upgrading Berkeley DB Applications</dl></h3></td> -<td align=right><a href="../../ref/upgrade.3.2/callback.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.3.2/incomplete.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Release 3.2: Logically renumbering records</h1> -<p>In the Berkeley DB 3.2 release, cursor adjustment semantics changed for Recno -databases with mutable record numbers. Before the 3.2 release, cursors -were adjusted to point to the previous or next record at the time the -record to which the cursor referred was deleted. This could lead to -unexpected behaviors. For example, two cursors referring to sequential -records that were both deleted would lose their relationship to each -other and would refer to the same position in the database instead of -their original sequential relationship. There were also command -sequences that would have unexpected results. For example, DB_AFTER -and DB_BEFORE cursor put operations, using a cursor previously used to -delete an item, would perform the put relative to the cursor's adjusted -position and not its original position. -<p>In the Berkeley DB 3.2 release, cursors maintain their position in the tree -regardless of deletion operations using the cursor. Applications that -perform database operations, using cursors previously used to delete -entries in Recno databases with mutable record numbers, should be -evaluated to ensure that the new semantics do not cause application -failure. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/upgrade.3.2/callback.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.3.2/incomplete.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/libdb/docs/ref/upgrade.3.2/set_flags.html b/libdb/docs/ref/upgrade.3.2/set_flags.html deleted file mode 100644 index 3844db89d..000000000 --- a/libdb/docs/ref/upgrade.3.2/set_flags.html +++ /dev/null @@ -1,36 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Release 3.2: DB_ENV->set_flags</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Upgrading Berkeley DB Applications</dl></h3></td> -<td align=right><a href="../../ref/upgrade.3.2/intro.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.3.2/callback.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Release 3.2: DB_ENV->set_flags</h1> -<p>A new method has been added to the Berkeley DB environment handle, -<a href="../../api_c/env_set_flags.html">DB_ENV->set_flags</a>. This interface currently takes three flags: -<a href="../../api_c/env_set_flags.html#DB_CDB_ALLDB">DB_CDB_ALLDB</a>, <a href="../../api_c/env_set_flags.html#DB_NOMMAP">DB_NOMMAP</a> and <a href="../../api_c/env_set_flags.html#DB_TXN_NOSYNC">DB_TXN_NOSYNC</a>. The -first of these flags, <a href="../../api_c/env_set_flags.html#DB_CDB_ALLDB">DB_CDB_ALLDB</a>, provides new functionality, -allowing Berkeley DB Concurrent Data Store applications to do locking across multiple databases. -<p>The other two flags, <a href="../../api_c/env_set_flags.html#DB_NOMMAP">DB_NOMMAP</a> and <a href="../../api_c/env_set_flags.html#DB_TXN_NOSYNC">DB_TXN_NOSYNC</a>, were -specified to the <a href="../../api_c/env_open.html">DB_ENV->open</a> method in previous releases. In -the 3.2 release, they have been moved to the <a href="../../api_c/env_set_flags.html">DB_ENV->set_flags</a> method -because this allows the database environment's value to be toggled -during the life of the application as well as because it is a more -appropriate place for them. Applications specifying either the -<a href="../../api_c/env_set_flags.html#DB_NOMMAP">DB_NOMMAP</a> or <a href="../../api_c/env_set_flags.html#DB_TXN_NOSYNC">DB_TXN_NOSYNC</a> flags to the -<a href="../../api_c/env_open.html">DB_ENV->open</a> method should replace those flags with calls to the -<a href="../../api_c/env_set_flags.html">DB_ENV->set_flags</a> method. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/upgrade.3.2/intro.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.3.2/callback.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/libdb/docs/ref/upgrade.3.2/toc.html b/libdb/docs/ref/upgrade.3.2/toc.html deleted file mode 100644 index e94a43cc2..000000000 --- a/libdb/docs/ref/upgrade.3.2/toc.html +++ /dev/null @@ -1,35 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Upgrading Berkeley DB 3.1.X applications to Berkeley DB 3.2</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Upgrading Berkeley DB Applications</dl></h3></td> -<td align=right><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a> -</td></tr></table> -<p> -<h1 align=center>Upgrading Berkeley DB 3.1.X applications to Berkeley DB 3.2</h1> -<p><ol> -<p><li><a href="intro.html">Release 3.2: introduction</a> -<li><a href="set_flags.html">Release 3.2: DB_ENV->set_flags</a> -<li><a href="callback.html">Release 3.2: DB callback functions, app_private field</a> -<li><a href="renumber.html">Release 3.2: logically renumbering records</a> -<li><a href="incomplete.html">Release 3.2: DB_INCOMPLETE</a> -<li><a href="tx_recover.html">Release 3.2: DB_ENV->set_tx_recover</a> -<li><a href="mutexlock.html">Release 3.2: DB_ENV->set_mutexlocks</a> -<li><a href="handle.html">Release 3.2: Java and C++ object reuse</a> -<li><a href="notfound.html">Release 3.2: Java java.io.FileNotFoundException</a> -<li><a href="db_dump.html">Release 3.2: db_dump</a> -<li><a href="disk.html">Release 3.2: upgrade requirements</a> -</ol> -<table width="100%"><tr><td><br></td><td align=right><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a> -</td></tr></table> -<p><font size=1><a href="http://www.sleepycat.com">Copyright Sleepycat Software</a></font> -</body> -</html> diff --git a/libdb/docs/ref/upgrade.3.2/tx_recover.html b/libdb/docs/ref/upgrade.3.2/tx_recover.html deleted file mode 100644 index e29d0dcba..000000000 --- a/libdb/docs/ref/upgrade.3.2/tx_recover.html +++ /dev/null @@ -1,33 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Release 3.2: DB_ENV->set_tx_recover</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Upgrading Berkeley DB Applications</dl></h3></td> -<td align=right><a href="../../ref/upgrade.3.2/incomplete.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.3.2/mutexlock.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Release 3.2: DB_ENV->set_tx_recover</h1> -<p>The <b>info</b> parameter of the function passed to -DB_ENV->set_tx_recover is no longer needed. If your application -calls DB_ENV->set_tx_recover, find the callback function referred -to by that call and remove the <b>info</b> parameter. -<p>In addition, the called function no longer needs to handle Berkeley DB log -records, Berkeley DB will handle them internally as well as call the -application-specified function. Any handling of Berkeley DB log records in the -application's callback function may be removed. -<p>In addition, the callback function will no longer be called with the -<a href="../../api_c/env_set_app_dispatch.html#DB_TXN_FORWARD_ROLL">DB_TXN_FORWARD_ROLL</a> flag specified unless the transaction -enclosing the operation successfully committed. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/upgrade.3.2/incomplete.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.3.2/mutexlock.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/libdb/docs/ref/upgrade.3.3/alloc.html b/libdb/docs/ref/upgrade.3.3/alloc.html deleted file mode 100644 index 470ee7945..000000000 --- a/libdb/docs/ref/upgrade.3.3/alloc.html +++ /dev/null @@ -1,67 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Release 3.3: DB->set_malloc, DB->set_realloc</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Upgrading Berkeley DB Applications</dl></h3></td> -<td align=right><a href="../../ref/upgrade.3.3/getswap.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.3.3/conflict.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Release 3.3: DB->set_malloc, DB->set_realloc</h1> -<p>There are two new interfaces in the Berkeley DB 3.3 release: -<a href="../../api_c/env_set_alloc.html">DB_ENV->set_alloc</a> and <a href="../../api_c/db_set_alloc.html">DB->set_alloc</a>. These functions -allow applications to specify a set of allocation functions for the -Berkeley DB library to use when allocating memory to be owned by the -application and when freeing memory that was originally allocated by -the application. -<p>The new interfaces affect or replace the following historic -interfaces: -<p><dl compact> -<p><dt>DB->set_malloc<dd>The DB->set_malloc interface has been replaced in its entirety. -Applications using this interface should replace the call with a call -to <a href="../../api_c/db_set_alloc.html">DB->set_alloc</a>. -<p><dt>DB->set_realloc<dd>The DB->set_realloc interface has been replaced in its entirety. -Applications using this interface should replace the call with a call -to <a href="../../api_c/db_set_alloc.html">DB->set_alloc</a>. -<p><dt><a href="../../api_c/db_stat.html">DB->stat</a><dd>The historic <b>db_malloc</b> argument to the <a href="../../api_c/db_stat.html">DB->stat</a> method has -been replaced. Applications using this interface should do as follows: -if the argument is NULL, it should simply be removed. If non-NULL, -it should be replaced with a call to <a href="../../api_c/db_set_alloc.html">DB->set_alloc</a>. -<p><dt>lock_stat<dd>The historic <b>db_malloc</b> argument to the lock_stat interface has -been replaced. Applications using this interface should do as follows: -if the argument is NULL, it should simply be removed. If -non-NULL, it should be replaced with a call to <a href="../../api_c/env_set_alloc.html">DB_ENV->set_alloc</a>. -<p><dt>log_archive<dd>The historic <b>db_malloc</b> argument to the log_archive interface has -been replaced. Applications using this interface should do as follows: -if the argument is NULL, it should simply be removed. If non-NULL, -it should be replaced with a call to <a href="../../api_c/env_set_alloc.html">DB_ENV->set_alloc</a>. -<p><dt>log_stat<dd>The historic <b>db_malloc</b> argument to the log_stat interface has -been replaced. Applications using this interface should do as follows: -if the argument is NULL, it should simply be removed. If non-NULL, -it should be replaced with a call to <a href="../../api_c/env_set_alloc.html">DB_ENV->set_alloc</a>. -<p><dt>memp_stat<dd>The historic <b>db_malloc</b> argument to the memp_stat function has -been replaced. Applications using this interface should do as follows: -if the argument is NULL, it should simply be removed. If non-NULL, -it should be replaced with a call to <a href="../../api_c/env_set_alloc.html">DB_ENV->set_alloc</a>. -<p><dt>txn_stat<dd>The historic <b>db_malloc</b> argument to the txn_stat function has -been replaced. Applications using this interface should do as follows: -if the argument is NULL, it should simply be removed. If non-NULL, -it should be replaced with a call to <a href="../../api_c/env_set_alloc.html">DB_ENV->set_alloc</a>. -</dl> -<p>One potential incompatibility for historic applications is that the -allocation functions for a database environment must now be set before -the environment is opened. Historically, Berkeley DB applications could open -the environment first, and subsequently call the DB->set_malloc -and DB->set_realloc interfaces; that use is no longer supported. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/upgrade.3.3/getswap.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.3.3/conflict.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/libdb/docs/ref/upgrade.3.3/bigfile.html b/libdb/docs/ref/upgrade.3.3/bigfile.html deleted file mode 100644 index c0daefda6..000000000 --- a/libdb/docs/ref/upgrade.3.3/bigfile.html +++ /dev/null @@ -1,29 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Release 3.3: --disable-bigfile</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Upgrading Berkeley DB Applications</dl></h3></td> -<td align=right><a href="../../ref/upgrade.3.3/shared.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.3.3/disk.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Release 3.3: --disable-bigfile</h1> -<p>In previous releases, Berkeley DB UNIX used the --disable-bigfile configuration -option for systems that could not, for whatever reason, include large -file support in a particular Berkeley DB configuration. However, large file -support has been integrated into the autoconf configuration tool as of -version 2.50. For that reason, Berkeley DB configuration no longer supports ---disable-bigfile, the autoconf standard --disable-largefile should be -used instead. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/upgrade.3.3/shared.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.3.3/disk.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/libdb/docs/ref/upgrade.3.3/conflict.html b/libdb/docs/ref/upgrade.3.3/conflict.html deleted file mode 100644 index da8d12288..000000000 --- a/libdb/docs/ref/upgrade.3.3/conflict.html +++ /dev/null @@ -1,25 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Release 3.3: DB_LOCK_CONFLICT</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Upgrading Berkeley DB Applications</dl></h3></td> -<td align=right><a href="../../ref/upgrade.3.3/alloc.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.3.3/memp_fget.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Release 3.3: DB_LOCK_CONFLICT</h1> -<p>The DB_LOCK_CONFLICT flag has been removed from the lock_detect interface. -Applications specifying the DB_LOCK_CONFLICT flag should simply replace -it with a flags argument of 0. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/upgrade.3.3/alloc.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.3.3/memp_fget.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/libdb/docs/ref/upgrade.3.3/disk.html b/libdb/docs/ref/upgrade.3.3/disk.html deleted file mode 100644 index 828a7166c..000000000 --- a/libdb/docs/ref/upgrade.3.3/disk.html +++ /dev/null @@ -1,25 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Release 3.3: upgrade requirements</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Upgrading Berkeley DB Applications</dl></h3></td> -<td align=right><a href="../../ref/upgrade.3.3/bigfile.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.4.0/intro.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Release 3.3: upgrade requirements</h1> -<p>No database formats or log file formats changed in the Berkeley DB 3.3 release. -<p>For further information on upgrading Berkeley DB installations, see -<a href="../../ref/upgrade/process.html">Upgrading Berkeley DB installations</a>. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/upgrade.3.3/bigfile.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.4.0/intro.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/libdb/docs/ref/upgrade.3.3/getswap.html b/libdb/docs/ref/upgrade.3.3/getswap.html deleted file mode 100644 index 9c7bd21a1..000000000 --- a/libdb/docs/ref/upgrade.3.3/getswap.html +++ /dev/null @@ -1,29 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Release 3.3: DB->get_byteswapped</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Upgrading Berkeley DB Applications</dl></h3></td> -<td align=right><a href="../../ref/upgrade.3.3/gettype.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.3.3/alloc.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Release 3.3: DB->get_byteswapped</h1> -<p>The <a href="../../api_c/db_get_byteswapped.html">DB->get_byteswapped</a> method method can return an error in the Berkeley DB -3.3 release, and so requires an interface change. C and C++ -applications calling <a href="../../api_c/db_get_byteswapped.html">DB->get_byteswapped</a> should be changed to -treat the method's return as an error code, and to pass an additional -second argument of type <b>int *</b> to the method. The additional -argument is used as a memory location in which to store the requested -information. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/upgrade.3.3/gettype.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.3.3/alloc.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/libdb/docs/ref/upgrade.3.3/gettype.html b/libdb/docs/ref/upgrade.3.3/gettype.html deleted file mode 100644 index c48c9180c..000000000 --- a/libdb/docs/ref/upgrade.3.3/gettype.html +++ /dev/null @@ -1,28 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Release 3.3: DB->get_type</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Upgrading Berkeley DB Applications</dl></h3></td> -<td align=right><a href="../../ref/upgrade.3.3/rpc.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.3.3/getswap.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Release 3.3: DB->get_type</h1> -<p>The <a href="../../api_c/db_get_type.html">DB->get_type</a> method method can return an error in the Berkeley DB 3.3 -release, and so requires an interface change. C and C++ applications -calling <a href="../../api_c/db_get_type.html">DB->get_type</a> should be changed to treat the method's -return as an error code, and to pass an additional second argument of -type <b>DBTYPE *</b> to the method. The additional argument is used -as a memory location in which to store the requested information. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/upgrade.3.3/rpc.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.3.3/getswap.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/libdb/docs/ref/upgrade.3.3/intro.html b/libdb/docs/ref/upgrade.3.3/intro.html deleted file mode 100644 index be348d7b1..000000000 --- a/libdb/docs/ref/upgrade.3.3/intro.html +++ /dev/null @@ -1,27 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Release 3.3: introduction</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Upgrading Berkeley DB Applications</dl></h3></td> -<td align=right><a href="../../ref/upgrade.3.2/disk.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.3.3/rpc.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Release 3.3: introduction</h1> -<p>The following pages describe how to upgrade applications coded against -the Berkeley DB 3.2 release interfaces to the Berkeley DB 3.3 release interfaces. -This information does not describe how to upgrade Berkeley DB 1.85 release -applications. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/upgrade.3.2/disk.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.3.3/rpc.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/libdb/docs/ref/upgrade.3.3/memp_fget.html b/libdb/docs/ref/upgrade.3.3/memp_fget.html deleted file mode 100644 index 1e1dca0ec..000000000 --- a/libdb/docs/ref/upgrade.3.3/memp_fget.html +++ /dev/null @@ -1,37 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Release 3.3: memp_fget, EIO</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Upgrading Berkeley DB Applications</dl></h3></td> -<td align=right><a href="../../ref/upgrade.3.3/conflict.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.3.3/txn_prepare.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Release 3.3: memp_fget, EIO</h1> -<p>Previous releases of Berkeley DB returned the system error EIO when the -memp_fget interface was called to retrieve a page, the page did not -exist, and the <a href="../../api_c/memp_fget.html#DB_MPOOL_CREATE">DB_MPOOL_CREATE</a> flag was not set. In the 3.3 -release, the error <a href="../../api_c/memp_fget.html#DB_PAGE_NOTFOUND">DB_PAGE_NOTFOUND</a> is returned instead, to -allow applications to distinguish between recoverable and -non-recoverable errors. Applications calling the memp_fget interface -and checking for a return of EIO should check for -<a href="../../api_c/memp_fget.html#DB_PAGE_NOTFOUND">DB_PAGE_NOTFOUND</a> instead. -<p>Previous releases of Berkeley DB treated filesystem I/O failure (the most -common of which the filesystem running out of space), as a fatal error, -returning <a href="../../ref/program/errorret.html#DB_RUNRECOVERY">DB_RUNRECOVERY</a>. When a filesystem failure happens in -the 3.3 release Berkeley DB returns the underlying system error (usually EIO), -but can continue to run. Applications should abort any enclosing -transaction when a recoverable system error occurs in order to recover -from the error. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/upgrade.3.3/conflict.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.3.3/txn_prepare.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/libdb/docs/ref/upgrade.3.3/rpc.html b/libdb/docs/ref/upgrade.3.3/rpc.html deleted file mode 100644 index e2eb15e0b..000000000 --- a/libdb/docs/ref/upgrade.3.3/rpc.html +++ /dev/null @@ -1,29 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Release 3.3: DB_ENV->set_server</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Upgrading Berkeley DB Applications</dl></h3></td> -<td align=right><a href="../../ref/upgrade.3.3/intro.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.3.3/gettype.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Release 3.3: DB_ENV->set_server</h1> -<p>The DB_ENV->set_server interface has been deprecated and replaced -with the <a href="../../api_c/env_set_rpc_server.html">DB_ENV->set_rpc_server</a> method. The DB_ENV->set_server -interface will be removed in a future release, and so applications using -it should convert. The DB_ENV->set_server interface can be easily -converted to the <a href="../../api_c/env_set_rpc_server.html">DB_ENV->set_rpc_server</a> method by changing the name, -and specifying a NULL for the added argument, second in the argument -list. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/upgrade.3.3/intro.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.3.3/gettype.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/libdb/docs/ref/upgrade.3.3/shared.html b/libdb/docs/ref/upgrade.3.3/shared.html deleted file mode 100644 index 036e89631..000000000 --- a/libdb/docs/ref/upgrade.3.3/shared.html +++ /dev/null @@ -1,31 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Release 3.3: --enable-dynamic, --enable-shared</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Upgrading Berkeley DB Applications</dl></h3></td> -<td align=right><a href="../../ref/upgrade.3.3/txn_prepare.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.3.3/bigfile.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Release 3.3: --enable-dynamic, --enable-shared</h1> -<p>In previous releases, Berkeley DB required separate configuration and builds -to create both static and shared libraries. This has changed in the -3.3 release, and Berkeley DB now builds and installs both shared and static -versions of the Berkeley DB libraries by default. This change was based on -Berkeley DB upgrading to release 1.4 of the GNU Project's Libtool distribution. -For this reason, Berkeley DB no longer supports the previous --enable-dynamic -and --enable-shared configuration options. Instead, as Berkeley DB now builds -both static and shared libraries by default, the useful options are -Libtool's --disable-shared and --disable-static options. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/upgrade.3.3/txn_prepare.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.3.3/bigfile.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/libdb/docs/ref/upgrade.3.3/toc.html b/libdb/docs/ref/upgrade.3.3/toc.html deleted file mode 100644 index 56fa10b5a..000000000 --- a/libdb/docs/ref/upgrade.3.3/toc.html +++ /dev/null @@ -1,35 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Upgrading Berkeley DB 3.2.X applications to Berkeley DB 3.3</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Upgrading Berkeley DB Applications</dl></h3></td> -<td align=right><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a> -</td></tr></table> -<p> -<h1 align=center>Upgrading Berkeley DB 3.2.X applications to Berkeley DB 3.3</h1> -<p><ol> -<p><li><a href="intro.html">Release 3.3: introduction</a> -<li><a href="rpc.html">Release 3.3: DB_ENV->set_server</a> -<li><a href="gettype.html">Release 3.3: DB->get_type</a> -<li><a href="getswap.html">Release 3.3: DB->get_byteswapped</a> -<li><a href="alloc.html">Release 3.3: DB->set_malloc, DB->set_realloc</a> -<li><a href="conflict.html">Release 3.3: DB_LOCK_CONFLICT</a> -<li><a href="memp_fget.html">Release 3.3: memp_fget, EIO</a> -<li><a href="txn_prepare.html">Release 3.3: txn_prepare</a> -<li><a href="shared.html">Release 3.3: --enable-dynamic, --enable-shared</a> -<li><a href="bigfile.html">Release 3.3: --disable-bigfile</a> -<li><a href="disk.html">Release 3.3: upgrade requirements</a> -</ol> -<table width="100%"><tr><td><br></td><td align=right><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a> -</td></tr></table> -<p><font size=1><a href="http://www.sleepycat.com">Copyright Sleepycat Software</a></font> -</body> -</html> diff --git a/libdb/docs/ref/upgrade.3.3/txn_prepare.html b/libdb/docs/ref/upgrade.3.3/txn_prepare.html deleted file mode 100644 index f437f1acd..000000000 --- a/libdb/docs/ref/upgrade.3.3/txn_prepare.html +++ /dev/null @@ -1,27 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Release 3.3: txn_prepare</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Upgrading Berkeley DB Applications</dl></h3></td> -<td align=right><a href="../../ref/upgrade.3.3/memp_fget.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.3.3/shared.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Release 3.3: txn_prepare</h1> -<p>An additional argument has been added to the txn_prepare interface. If -your application calls txn_prepare (that is, is performing two-phase -commit using Berkeley DB as a local resource manager), see -<a href="../../ref/xa/intro.html">Distributed Transactions</a> for more -information. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/upgrade.3.3/memp_fget.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.3.3/shared.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/libdb/docs/ref/upgrade.4.0/asr.html b/libdb/docs/ref/upgrade.4.0/asr.html deleted file mode 100644 index 8fc202531..000000000 --- a/libdb/docs/ref/upgrade.4.0/asr.html +++ /dev/null @@ -1,40 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Release 4.0: application-specific recovery</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Upgrading Berkeley DB Applications</dl></h3></td> -<td align=right><a href="../../ref/upgrade.4.0/cxx.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.4.0/disk.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Release 4.0: application-specific recovery</h1> -<p>If you have created your own logging and recovery routines, you may need -to upgrade them to the Berkeley DB 4.0 release. -<p>First, you should regenerate your logging, print, read and the other -automatically generated routines, using the dist/gen_rec.awk tool -included in the Berkeley DB distribution. -<p>Next, compare the template file code generated by the gen_rec.awk tool -against the code generated by the last release in which you built a -template file. Any changes in the templates should be incorporated into -the recovery routines you have written. -<p>Third, if your recovery functions refer to <a href="../../api_c/env_set_app_dispatch.html#DB_TXN_FORWARD_ROLL">DB_TXN_FORWARD_ROLL</a> -(that is, your code checks for that particular operation code), you -should replace it with DB_REDO(op) which compares the operation code to -both <a href="../../api_c/env_set_app_dispatch.html#DB_TXN_FORWARD_ROLL">DB_TXN_FORWARD_ROLL</a> and <a href="../../api_c/env_set_app_dispatch.html#DB_TXN_APPLY">DB_TXN_APPLY</a>. -(<a href="../../api_c/env_set_app_dispatch.html#DB_TXN_APPLY">DB_TXN_APPLY</a> is a potential value for the operation code as of -the 4.0 release.) -<p>Finally, if you have created your own logging and recovery routines, we -recommend that you contact Sleepycat support and ask us to review those -routines for you. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/upgrade.4.0/cxx.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.4.0/disk.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/libdb/docs/ref/upgrade.4.0/cxx.html b/libdb/docs/ref/upgrade.4.0/cxx.html deleted file mode 100644 index 2c0163dec..000000000 --- a/libdb/docs/ref/upgrade.4.0/cxx.html +++ /dev/null @@ -1,49 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Release 4.0: C++ ostream objects</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Upgrading Berkeley DB Applications</dl></h3></td> -<td align=right><a href="../../ref/upgrade.4.0/java.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.4.0/asr.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Release 4.0: C++ ostream objects</h1> -<p>In the 4.0 release, the Berkeley DB C++ API has been changed to use the ISO -standard C++ API in preference to the older, less portable interfaces, -where available. This means the Berkeley DB methods that used to take an -ostream object as a parameter now expect a std::ostream. Specifically, -the following methods have changed: -<p><blockquote><pre>DbEnv::set_error_stream -Db::set_error_stream -Db::verify</pre></blockquote> -<p>On many platforms, the old and the new C++ styles are interchangeable; -on some platforms (notably Win32), they are incompatible. If your code -uses these methods and you have trouble with the 4.0 release, you should -update code that looks like this: -<p><blockquote><pre>#include <iostream.h> -#include <db_cxx.h> -<p> -void foo(Db db) { - db.set_error_stream(&cerr); -}</pre></blockquote> -<p>to look like this: -<p><blockquote><pre>#include <iostream> -#include <db_cxx.h> -<p> -using std::cerr; -<p> -void foo(Db db) { - db.set_error_stream(&cerr); -}</pre></blockquote> -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/upgrade.4.0/java.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.4.0/asr.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/libdb/docs/ref/upgrade.4.0/deadlock.html b/libdb/docs/ref/upgrade.4.0/deadlock.html deleted file mode 100644 index 3226da98a..000000000 --- a/libdb/docs/ref/upgrade.4.0/deadlock.html +++ /dev/null @@ -1,26 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Release 4.0: db_deadlock</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Upgrading Berkeley DB Applications</dl></h3></td> -<td align=right><a href="../../ref/upgrade.4.0/intro.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.4.0/lock.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Release 4.0: db_deadlock</h1> -<p>The <b>-w</b> option to the <a href="../../utility/db_deadlock.html">db_deadlock</a> utility has been -deprecated. Applications can get the functionality of the <b>-w</b> -option by using the <b>-t</b> option with an argument of -<b>.100000</b>. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/upgrade.4.0/intro.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.4.0/lock.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/libdb/docs/ref/upgrade.4.0/disk.html b/libdb/docs/ref/upgrade.4.0/disk.html deleted file mode 100644 index d824aef9e..000000000 --- a/libdb/docs/ref/upgrade.4.0/disk.html +++ /dev/null @@ -1,26 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Release 4.0: upgrade requirements</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Upgrading Berkeley DB Applications</dl></h3></td> -<td align=right><a href="../../ref/upgrade.4.0/asr.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.4.1/intro.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Release 4.0: upgrade requirements</h1> -<p>The log file format changed in the Berkeley DB 4.0 release. No database -formats changed in the Berkeley DB 4.0 release. -<p>For further information on upgrading Berkeley DB installations, see -<a href="../../ref/upgrade/process.html">Upgrading Berkeley DB installations</a>. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/upgrade.4.0/asr.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.4.1/intro.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/libdb/docs/ref/upgrade.4.0/env.html b/libdb/docs/ref/upgrade.4.0/env.html deleted file mode 100644 index 74a118fc8..000000000 --- a/libdb/docs/ref/upgrade.4.0/env.html +++ /dev/null @@ -1,82 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Release 4.0: db_env_set_XXX</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Upgrading Berkeley DB Applications</dl></h3></td> -<td align=right><a href="../../ref/upgrade.4.0/txn.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.4.0/rpc.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Release 4.0: db_env_set_XXX</h1> -<p>The db_env_set_region_init interface was removed in the 4.0 release and -replaced with the <a href="../../api_c/env_set_flags.html#DB_REGION_INIT">DB_REGION_INIT</a> flag to the -<a href="../../api_c/env_set_flags.html">DB_ENV->set_flags</a> interface. This is an interface change: -historically, the db_env_set_region_init interface operated on the -entire Berkeley DB library, not a single environment. The new interface only -operates on a single <a href="../../api_c/env_class.html">DB_ENV</a> handle (and any handles created in -the scope of that handle). Applications calling the -db_env_set_region_init interface should update their calls: calls to -the historic routine with an argument of 1 (0) are equivalent to calling -<a href="../../api_c/env_set_flags.html">DB_ENV->set_flags</a> with the <a href="../../api_c/env_set_flags.html#DB_REGION_INIT">DB_REGION_INIT</a> flag and an -argument of 1 (0). -<p>The db_env_set_tas_spins interface was removed in the 4.0 release and -replaced with the <a href="../../api_c/env_set_tas_spins.html">DB_ENV->set_tas_spins</a> method. This is an interface -change: historically, the db_env_set_tas_spins interface operated on -the entire Berkeley DB library, not a single environment. The new interface -only operates on a single <a href="../../api_c/env_class.html">DB_ENV</a> handle (and any handles created -in the scope of that handle). Applications calling the -db_env_set_tas_spins interface should update their calls: calls to the -historic routine are equivalent to calling <a href="../../api_c/env_set_tas_spins.html">DB_ENV->set_tas_spins</a> method -with the same argument. In addition, for consistent behavior, all -<a href="../../api_c/env_class.html">DB_ENV</a> handles opened by the application should make the same -configuration call, or the value will need to be entered into the -environment's <b>DB_CONFIG</b> file. -<p>Also, three of the standard Berkeley DB debugging interfaces changed in the -4.0 release. It is quite unlikely that Berkeley DB applications use these -interfaces. -<p>The DB_ENV->set_mutexlocks interface was removed in the 4.0 release -and replaced with the <a href="../../api_c/env_set_flags.html#DB_NOLOCKING">DB_NOLOCKING</a> flag to the -<a href="../../api_c/env_set_flags.html">DB_ENV->set_flags</a> interface. Applications calling the -DB_ENV->set_mutexlocks interface should update their calls: calls -to the historic routine with an argument of 1 (0) are equivalent to -calling <a href="../../api_c/env_set_flags.html">DB_ENV->set_flags</a> with the <a href="../../api_c/env_set_flags.html#DB_NOLOCKING">DB_NOLOCKING</a> flag and -an argument of 1 (0). -<p>The db_env_set_pageyield interface was removed in the 4.0 release and -replaced with the <a href="../../api_c/env_set_flags.html#DB_YIELDCPU">DB_YIELDCPU</a> flag to the -<a href="../../api_c/env_set_flags.html">DB_ENV->set_flags</a> interface. This is an interface change: -historically, the db_env_set_pageyield interface operated on the entire -Berkeley DB library, not a single environment. The new interface only -operates on a single <a href="../../api_c/env_class.html">DB_ENV</a> handle (and any handles created in -the scope of that handle). Applications calling the -db_env_set_pageyield interface should update their calls: calls to the -historic routine with an argument of 1 (0) are equivalent to calling -<a href="../../api_c/env_set_flags.html">DB_ENV->set_flags</a> with the <a href="../../api_c/env_set_flags.html#DB_YIELDCPU">DB_YIELDCPU</a> flag and an -argument of 1 (0). In addition, all <a href="../../api_c/env_class.html">DB_ENV</a> handles opened by -the application will need to make the same call, or the -<a href="../../api_c/env_set_flags.html#DB_YIELDCPU">DB_YIELDCPU</a> flag will need to be entered into the environment's -<b>DB_CONFIG</b> file. -<p>The db_env_set_panicstate interface was removed in the 4.0 release, -replaced with the <a href="../../api_c/env_set_flags.html#DB_PANIC_ENVIRONMENT">DB_PANIC_ENVIRONMENT</a> and <a href="../../api_c/env_set_flags.html#DB_NOPANIC">DB_NOPANIC</a> -flags to the <a href="../../api_c/env_set_flags.html">DB_ENV->set_flags</a> interface. (The -<a href="../../api_c/env_set_flags.html#DB_PANIC_ENVIRONMENT">DB_PANIC_ENVIRONMENT</a> flag will cause an environment to panic, -affecting all threads of control using that environment. The -<a href="../../api_c/env_set_flags.html#DB_NOPANIC">DB_NOPANIC</a> flag will cause a single <a href="../../api_c/env_class.html">DB_ENV</a> handle to -ignore the current panic state of the environment.) This is an -interface change: historically the db_env_set_panicstate interface -operated on the entire Berkeley DB library, not a single environment. -Applications calling the db_env_set_panicstate interface should update -their calls, replacing the historic call with a call to -<a href="../../api_c/env_set_flags.html">DB_ENV->set_flags</a> and the appropriate flag, depending on their -usage of the historic interface. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/upgrade.4.0/txn.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.4.0/rpc.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/libdb/docs/ref/upgrade.4.0/intro.html b/libdb/docs/ref/upgrade.4.0/intro.html deleted file mode 100644 index e0dbaa6b3..000000000 --- a/libdb/docs/ref/upgrade.4.0/intro.html +++ /dev/null @@ -1,27 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Release 4.0: introduction</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Upgrading Berkeley DB Applications</dl></h3></td> -<td align=right><a href="../../ref/upgrade.3.3/disk.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.4.0/deadlock.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Release 4.0: introduction</h1> -<p>The following pages describe how to upgrade applications coded against -the Berkeley DB 3.3 release interfaces to the Berkeley DB 4.0 release interfaces. -This information does not describe how to upgrade Berkeley DB 1.85 release -applications. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/upgrade.3.3/disk.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.4.0/deadlock.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/libdb/docs/ref/upgrade.4.0/java.html b/libdb/docs/ref/upgrade.4.0/java.html deleted file mode 100644 index 9f8753dc1..000000000 --- a/libdb/docs/ref/upgrade.4.0/java.html +++ /dev/null @@ -1,33 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Release 4.0: Java CLASSPATH environment variable</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Upgrading Berkeley DB Applications</dl></h3></td> -<td align=right><a href="../../ref/upgrade.4.0/lock_id_free.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.4.0/cxx.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Release 4.0: Java CLASSPATH environment variable</h1> -<p>The Berkeley DB Java class files are now packaged as jar files. In the 4.0 -release, the <b>CLASSPATH</b> environment variable must change to -include at least the <b>db.jar</b> file. It can optionally include -the <b>dbexamples.jar</b> file if you want to run the examples. For -example, on UNIX: -<p><blockquote><pre>export CLASSPATH="/usr/local/BerkeleyDB.4.1/lib/db.jar:/usr/local/BerkeleyDB.4.1/lib/dbexamples.jar"</pre></blockquote> -<p>For example, on Windows: -<p><blockquote><pre>set CLASSPATH="D:\db\build_win32\Release\db.jar;D:\db\build_win32\Release\dbexamples.jar"</pre></blockquote> -<p>For more information on Java configuration, please see -<a href="../../ref/java/conf.html">Java configuration</a> and -<a href="../../ref/build_win/intro.html">Building for Win32</a>. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/upgrade.4.0/lock_id_free.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.4.0/cxx.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/libdb/docs/ref/upgrade.4.0/lock.html b/libdb/docs/ref/upgrade.4.0/lock.html deleted file mode 100644 index cfafb203d..000000000 --- a/libdb/docs/ref/upgrade.4.0/lock.html +++ /dev/null @@ -1,46 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Release 4.0: lock_XXX</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Upgrading Berkeley DB Applications</dl></h3></td> -<td align=right><a href="../../ref/upgrade.4.0/deadlock.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.4.0/log.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Release 4.0: lock_XXX</h1> -<p>The C API for the Berkeley DB Locking subsystem was reworked in the 4.0 -release as follows: -<p><table border=1 align=center> -<tr><th>Historic functional interface</th><th>Berkeley DB 4.X method</th></tr> -<tr><td>lock_detect</td><td><a href="../../api_c/lock_detect.html">DB_ENV->lock_detect</a></td></tr> -<tr><td>lock_get</td><td><a href="../../api_c/lock_get.html">DB_ENV->lock_get</a></td></tr> -<tr><td>lock_id</td><td><a href="../../api_c/lock_id.html">DB_ENV->lock_id</a></td></tr> -<tr><td>lock_put</td><td><a href="../../api_c/lock_put.html">DB_ENV->lock_put</a></td></tr> -<tr><td>lock_stat</td><td><a href="../../api_c/lock_stat.html">DB_ENV->lock_stat</a></td></tr> -<tr><td>lock_vec</td><td><a href="../../api_c/lock_vec.html">DB_ENV->lock_vec</a></td></tr> -</table> -<p>Applications calling any of these functions should update their calls -to use the enclosing <a href="../../api_c/env_class.html">DB_ENV</a> handle's method (easily done as the -first argument to the existing call is the correct handle to use). -<p>In addition, the <a href="../../api_c/lock_stat.html">DB_ENV->lock_stat</a> call has been changed in the 4.0 -release to take a flags argument. To leave their historic behavior -unchanged, applications should add a final argument of 0 to any calls -made to <a href="../../api_c/lock_stat.html">DB_ENV->lock_stat</a>. -<p>The C++ and Java APIs for the DbLock::put (DbLock.put) method was -reworked in the 4.0 release to make the lock put interface a method of -the <a href="../../api_c/env_class.html">DB_ENV</a> handle rather than the DbLock handle. Applications -calling the DbLock::put or DbLock.put method should update their calls -to use the enclosing <a href="../../api_c/env_class.html">DB_ENV</a> handle's method (easily done as the -first argument to the existing call is the correct handle to use). -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/upgrade.4.0/deadlock.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.4.0/log.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/libdb/docs/ref/upgrade.4.0/lock_id_free.html b/libdb/docs/ref/upgrade.4.0/lock_id_free.html deleted file mode 100644 index c14554570..000000000 --- a/libdb/docs/ref/upgrade.4.0/lock_id_free.html +++ /dev/null @@ -1,26 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Release 4.0: DB_ENV->lock_id_free</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Upgrading Berkeley DB Applications</dl></h3></td> -<td align=right><a href="../../ref/upgrade.4.0/set_lk_max.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.4.0/java.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Release 4.0: DB_ENV->lock_id_free</h1> -<p>A new locker ID related API, the <a href="../../api_c/lock_id_free.html">DB_ENV->lock_id_free</a> method, was added to -Berkeley DB 4.0 release. Applications using the <a href="../../api_c/lock_id.html">DB_ENV->lock_id</a> method to allocate -locker IDs may want to update their applications to free the locker ID -when it is no longer needed. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/upgrade.4.0/set_lk_max.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.4.0/java.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/libdb/docs/ref/upgrade.4.0/log.html b/libdb/docs/ref/upgrade.4.0/log.html deleted file mode 100644 index 6e0509772..000000000 --- a/libdb/docs/ref/upgrade.4.0/log.html +++ /dev/null @@ -1,56 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Release 4.0: log_XXX</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Upgrading Berkeley DB Applications</dl></h3></td> -<td align=right><a href="../../ref/upgrade.4.0/lock.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.4.0/mp.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Release 4.0: log_XXX</h1> -<p>The C API for the Berkeley DB Logging subsystem was reworked in the 4.0 -release as follows: -<p><table border=1 align=center> -<tr><th>Historic functional interface</th><th>Berkeley DB 4.X method</th></tr> -<tr><td>log_archive</td><td><a href="../../api_c/log_archive.html">DB_ENV->log_archive</a></td></tr> -<tr><td>log_file</td><td><a href="../../api_c/log_file.html">DB_ENV->log_file</a></td></tr> -<tr><td>log_flush</td><td><a href="../../api_c/log_flush.html">DB_ENV->log_flush</a></td></tr> -<tr><td>log_get</td><td><a href="../../api_c/log_cursor.html">DB_ENV->log_cursor</a>, <a href="../../api_c/logc_get.html">DB_LOGC->get</a>, <a href="../../api_c/logc_close.html">DB_LOGC->close</a></td></tr> -<tr><td>log_put</td><td><a href="../../api_c/log_put.html">DB_ENV->log_put</a></td></tr> -<tr><td>log_register</td><td>DB_ENV->log_register</td></tr> -<tr><td>log_stat</td><td><a href="../../api_c/log_stat.html">DB_ENV->log_stat</a></td></tr> -<tr><td>log_unregister</td><td>DB_ENV->log_unregister</td></tr> -</table> -<p>Applications calling any of these functions should update their calls -to use the enclosing <a href="../../api_c/env_class.html">DB_ENV</a> handle's method (in all cases other -than the log_get call, this is easily done as the first argument to the -existing call is the correct handle to use). -<p>Application calls to the historic log_get interface must be replaced -with the creation of a log file cursor (a <a href="../../api_c/logc_class.html">DB_LOGC</a> object), using -the <a href="../../api_c/log_cursor.html">DB_ENV->log_cursor</a> method, calls to the <a href="../../api_c/logc_get.html">DB_LOGC->get</a> method to retrieve log -records and calls to the <a href="../../api_c/logc_close.html">DB_LOGC->close</a> method to destroy the cursor. It -may also be possible to simplify some applications. In previous -releases of Berkeley DB, the DB_CURRENT, DB_NEXT, and DB_PREV flags to the -log_get function could not be used by a free-threaded <a href="../../api_c/env_class.html">DB_ENV</a> -handle. If their <a href="../../api_c/env_class.html">DB_ENV</a> handle was free-threaded, applications -had to create an additional, unique environment handle by separately -calling <a href="../../api_c/env_open.html">DB_ENV->open</a> without specifying <a href="../../api_c/env_open.html#DB_THREAD">DB_THREAD</a>. This -is no longer an issue in the log cursor interface, and applications may -be able to remove the now unnecessary creation of the additional -<a href="../../api_c/env_class.html">DB_ENV</a> object. -<p>Finally, the <a href="../../api_c/log_stat.html">DB_ENV->log_stat</a> call has been changed in the 4.0 release -to take a flags argument. To leave their historic behavior unchanged, -applications should add a final argument of 0 to any calls made to -<a href="../../api_c/log_stat.html">DB_ENV->log_stat</a>. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/upgrade.4.0/lock.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.4.0/mp.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/libdb/docs/ref/upgrade.4.0/mp.html b/libdb/docs/ref/upgrade.4.0/mp.html deleted file mode 100644 index 6b1a0fe12..000000000 --- a/libdb/docs/ref/upgrade.4.0/mp.html +++ /dev/null @@ -1,66 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Release 4.0: memp_XXX</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Upgrading Berkeley DB Applications</dl></h3></td> -<td align=right><a href="../../ref/upgrade.4.0/log.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.4.0/txn.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Release 4.0: memp_XXX</h1> -<p>The C API for the Berkeley DB Memory Pool subsystem was reworked in the 4.0 -release as follows: -<p><table border=1 align=center> -<tr><th>Historic functional interface</th><th>Berkeley DB 4.X method</th></tr> -<tr><td>memp_register</td><td><a href="../../api_c/memp_register.html">DB_ENV->memp_register</a></td></tr> -<tr><td>memp_stat</td><td><a href="../../api_c/memp_stat.html">DB_ENV->memp_stat</a></td></tr> -<tr><td>memp_sync</td><td><a href="../../api_c/memp_sync.html">DB_ENV->memp_sync</a></td></tr> -<tr><td>memp_trickle</td><td><a href="../../api_c/memp_trickle.html">DB_ENV->memp_trickle</a></td></tr> -<tr><td>memp_fopen</td><td><a href="../../api_c/memp_fcreate.html">DB_ENV->memp_fcreate</a></td></tr> -<tr><td>DB_MPOOL_FINFO: ftype</td><td><a href="../../api_c/memp_set_ftype.html">DB_MPOOLFILE->set_ftype</a></td></tr> -<tr><td>DB_MPOOL_FINFO: pgcookie</td><td><a href="../../api_c/memp_set_pgcookie.html">DB_MPOOLFILE->set_pgcookie</a></td></tr> -<tr><td>DB_MPOOL_FINFO: fileid</td><td><a href="../../api_c/memp_set_fileid.html">DB_MPOOLFILE->set_fileid</a></td></tr> -<tr><td>DB_MPOOL_FINFO: lsn_offset</td><td><a href="../../api_c/memp_set_lsn_offset.html">DB_MPOOLFILE->set_lsn_offset</a></td></tr> -<tr><td>DB_MPOOL_FINFO: clear_len</td><td><a href="../../api_c/memp_set_clear_len.html">DB_MPOOLFILE->set_clear_len</a></td></tr> -<tr><td>memp_fopen</td><td><a href="../../api_c/memp_fopen.html">DB_MPOOLFILE->open</a></td></tr> -<tr><td>memp_fclose</td><td><a href="../../api_c/memp_fclose.html">DB_MPOOLFILE->close</a></td></tr> -<tr><td>memp_fput</td><td><a href="../../api_c/memp_fput.html">DB_MPOOLFILE->put</a></td></tr> -<tr><td>memp_fset</td><td><a href="../../api_c/memp_fset.html">DB_MPOOLFILE->set</a></td></tr> -<tr><td>memp_fsync</td><td><a href="../../api_c/memp_fsync.html">DB_MPOOLFILE->sync</a></td></tr> -</table> -<p>Applications calling any of the memp_register, memp_stat, memp_sync or -memp_trickle interfaces should update those calls to use the enclosing -<a href="../../api_c/env_class.html">DB_ENV</a> handle's method (easily done as the first argument to the -existing call is the correct <a href="../../api_c/env_class.html">DB_ENV</a> handle). -<p>In addition, the <a href="../../api_c/memp_stat.html">DB_ENV->memp_stat</a> call has been changed in the 4.0 -release to take a flags argument. To leave their historic behavior -unchanged, applications should add a final argument of 0 to any calls -made to <a href="../../api_c/memp_stat.html">DB_ENV->memp_stat</a>. -<p>Applications calling the memp_fopen interface should update those calls -as follows: First, acquire a <a href="../../api_c/mempfile_class.html">DB_MPOOLFILE</a> handle using the -<a href="../../api_c/memp_fcreate.html">DB_ENV->memp_fcreate</a> method. Second, if the DB_MPOOL_FINFO structure -reference passed to the memp_fopen interface was non-NULL, call the -<a href="../../api_c/mempfile_class.html">DB_MPOOLFILE</a> method corresponding to each initialized field in -the DB_MPOOL_FINFO structure. Third, call the <a href="../../api_c/memp_fopen.html">DB_MPOOLFILE->open</a> method -method to open the underlying file. If the <a href="../../api_c/memp_fopen.html">DB_MPOOLFILE->open</a> method call -fails, then <a href="../../api_c/memp_fclose.html">DB_MPOOLFILE->close</a> method must be called to destroy the allocated -handle. -<p>Applications calling the memp_fopen, memp_fclose, memp_fput, memp_fset, -or memp_fsync interfaces should update those calls to use the enclosing -<a href="../../api_c/mempfile_class.html">DB_MPOOLFILE</a> handle's method. Again, this is easily done as the -first argument to the existing call is the correct <a href="../../api_c/mempfile_class.html">DB_MPOOLFILE</a> -handle. With one exception, the calling conventions of the old a new -interfaces are identical; the one exception is the <a href="../../api_c/memp_fclose.html">DB_MPOOLFILE->close</a> method, -which requires an additional flag parameter that should be set to 0. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/upgrade.4.0/log.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.4.0/txn.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/libdb/docs/ref/upgrade.4.0/rpc.html b/libdb/docs/ref/upgrade.4.0/rpc.html deleted file mode 100644 index 2755245c8..000000000 --- a/libdb/docs/ref/upgrade.4.0/rpc.html +++ /dev/null @@ -1,27 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Release 4.0: DB_ENV->set_server</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Upgrading Berkeley DB Applications</dl></h3></td> -<td align=right><a href="../../ref/upgrade.4.0/env.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.4.0/set_lk_max.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Release 4.0: DB_ENV->set_server</h1> -<p>The DB_ENV->set_server interface has been replaced with the -<a href="../../api_c/env_set_rpc_server.html">DB_ENV->set_rpc_server</a> method. The DB_ENV->set_server interface -can be easily converted to the <a href="../../api_c/env_set_rpc_server.html">DB_ENV->set_rpc_server</a> method by changing -the name, and specifying a NULL for the added argument, second in -the argument list. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/upgrade.4.0/env.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.4.0/set_lk_max.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/libdb/docs/ref/upgrade.4.0/set_lk_max.html b/libdb/docs/ref/upgrade.4.0/set_lk_max.html deleted file mode 100644 index 1ba5bf076..000000000 --- a/libdb/docs/ref/upgrade.4.0/set_lk_max.html +++ /dev/null @@ -1,27 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Release 4.0: DB_ENV->set_lk_max</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Upgrading Berkeley DB Applications</dl></h3></td> -<td align=right><a href="../../ref/upgrade.4.0/rpc.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.4.0/lock_id_free.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Release 4.0: DB_ENV->set_lk_max</h1> -<p>The DB_ENV->set_lk_max interface has been deprecated in favor of -the <a href="../../api_c/env_set_lk_max_locks.html">DB_ENV->set_lk_max_locks</a>, <a href="../../api_c/env_set_lk_max_lockers.html">DB_ENV->set_lk_max_lockers</a>, -and <a href="../../api_c/env_set_lk_max_objects.html">DB_ENV->set_lk_max_objects</a> methods. The DB_ENV->set_lk_max -interface continues to be available, but is no longer documented and -is expected to be removed in a future release. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/upgrade.4.0/rpc.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.4.0/lock_id_free.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/libdb/docs/ref/upgrade.4.0/toc.html b/libdb/docs/ref/upgrade.4.0/toc.html deleted file mode 100644 index 108d7f283..000000000 --- a/libdb/docs/ref/upgrade.4.0/toc.html +++ /dev/null @@ -1,38 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Upgrading Berkeley DB 3.3.X applications to Berkeley DB 4.0</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Upgrading Berkeley DB Applications</dl></h3></td> -<td align=right><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a> -</td></tr></table> -<p> -<h1 align=center>Upgrading Berkeley DB 3.3.X applications to Berkeley DB 4.0</h1> -<p><ol> -<p><li><a href="intro.html">Release 4.0: introduction</a> -<li><a href="deadlock.html">Release 4.0: db_deadlock</a> -<li><a href="lock.html">Release 4.0: lock_XXX</a> -<li><a href="log.html">Release 4.0: log_XXX</a> -<li><a href="mp.html">Release 4.0: memp_XXX</a> -<li><a href="txn.html">Release 4.0: txn_XXX</a> -<li><a href="env.html">Release 4.0: db_env_set_XXX</a> -<li><a href="rpc.html">Release 4.0: DB_ENV->set_server</a> -<li><a href="set_lk_max.html">Release 4.0: DB_ENV->set_lk_max</a> -<li><a href="lock_id_free.html">Release 4.0: DB_ENV->lock_id_free</a> -<li><a href="java.html">Release 4.0: Java CLASSPATH environment variable</a> -<li><a href="cxx.html">Release 4.0: C++ ostream objects</a> -<li><a href="asr.html">Release 4.0: application-specific recovery</a> -<li><a href="disk.html">Release 4.0: upgrade requirements</a> -</ol> -<table width="100%"><tr><td><br></td><td align=right><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a> -</td></tr></table> -<p><font size=1><a href="http://www.sleepycat.com">Copyright Sleepycat Software</a></font> -</body> -</html> diff --git a/libdb/docs/ref/upgrade.4.0/txn.html b/libdb/docs/ref/upgrade.4.0/txn.html deleted file mode 100644 index 536867f9c..000000000 --- a/libdb/docs/ref/upgrade.4.0/txn.html +++ /dev/null @@ -1,47 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Release 4.0: txn_XXX</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Upgrading Berkeley DB Applications</dl></h3></td> -<td align=right><a href="../../ref/upgrade.4.0/mp.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.4.0/env.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Release 4.0: txn_XXX</h1> -<p>The C API for the Berkeley DB Transaction subsystem was reworked in the 4.0 -release as follows: -<p><table border=1 align=center> -<tr><th>Historic functional interface</th><th>Berkeley DB 4.X method</th></tr> -<tr><td>txn_abort</td><td><a href="../../api_c/txn_abort.html">DB_TXN->abort</a></td></tr> -<tr><td>txn_begin</td><td><a href="../../api_c/txn_begin.html">DB_ENV->txn_begin</a></td></tr> -<tr><td>txn_checkpoint</td><td><a href="../../api_c/txn_checkpoint.html">DB_ENV->txn_checkpoint</a></td></tr> -<tr><td>txn_commit</td><td><a href="../../api_c/txn_commit.html">DB_TXN->commit</a></td></tr> -<tr><td>txn_discard</td><td><a href="../../api_c/txn_discard.html">DB_TXN->discard</a></td></tr> -<tr><td>txn_id</td><td><a href="../../api_c/txn_id.html">DB_TXN->id</a></td></tr> -<tr><td>txn_prepare</td><td><a href="../../api_c/txn_prepare.html">DB_TXN->prepare</a></td></tr> -<tr><td>txn_recover</td><td><a href="../../api_c/txn_recover.html">DB_ENV->txn_recover</a></td></tr> -<tr><td>txn_stat</td><td><a href="../../api_c/txn_stat.html">DB_ENV->txn_stat</a></td></tr> -</table> -<p>Applications calling any of these functions should update their calls -to use the enclosing <a href="../../api_c/env_class.html">DB_ENV</a> or <a href="../../api_c/txn_class.html">DB_TXN</a> handle's method -(easily done as the first argument to the existing call is the correct -handle to use). -<p>As a special case, since applications might potentially have many calls -to the txn_abort, txn_begin and txn_commit functions, those interfaces -continue to work unchanged in the Berkeley DB 4.0 release. -<p>In addition, the <a href="../../api_c/txn_stat.html">DB_ENV->txn_stat</a> call has been changed in the 4.0 -release to take a flags argument. To leave their historic behavior -unchanged, applications should add a final argument of 0 to any calls -made to <a href="../../api_c/txn_stat.html">DB_ENV->txn_stat</a>. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/upgrade.4.0/mp.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.4.0/env.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/libdb/docs/ref/upgrade.4.1/app_dispatch.html b/libdb/docs/ref/upgrade.4.1/app_dispatch.html deleted file mode 100644 index 9f1081003..000000000 --- a/libdb/docs/ref/upgrade.4.1/app_dispatch.html +++ /dev/null @@ -1,32 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Release 4.1: Application-specific logging and recovery</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Upgrading Berkeley DB Applications</dl></h3></td> -<td align=right><a href="../../ref/upgrade.4.1/cxx.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.4.1/disk.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Release 4.1: Application-specific logging and recovery</h1> -<p>The application-specific logging and recovery tools and interfaces have -been reworked in the 4.1 release to make it simpler for applications to -use Berkeley DB to support their own logging and recovery of non-Berkeley DB -objects. Specifically, the DB_ENV->set_recovery_init and -DB_ENV->set_tx_recover interfaces have been removed, replaced by -<a href="../../api_c/env_set_app_dispatch.html">DB_ENV->set_app_dispatch</a>. Applications using either of the -removed interfaces should be updated to call -<a href="../../api_c/env_set_app_dispatch.html">DB_ENV->set_app_dispatch</a>. For more information see -<a href="../../ref/apprec/intro.html">"Application-specific logging and -recovery"</a> and the <a href="../../api_c/env_set_app_dispatch.html">DB_ENV->set_app_dispatch</a> documentation. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/upgrade.4.1/cxx.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.4.1/disk.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/libdb/docs/ref/upgrade.4.1/checkpoint.html b/libdb/docs/ref/upgrade.4.1/checkpoint.html deleted file mode 100644 index d0a9a26ab..000000000 --- a/libdb/docs/ref/upgrade.4.1/checkpoint.html +++ /dev/null @@ -1,30 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Release 4.1: DB_CHECKPOINT, DB_CURLSN</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Upgrading Berkeley DB Applications</dl></h3></td> -<td align=right><a href="../../ref/upgrade.4.1/log_stat.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.4.1/incomplete.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Release 4.1: DB_CHECKPOINT, DB_CURLSN</h1> -<p>The DB_CHECKPOINT flag has been removed from the <a href="../../api_c/logc_get.html">DB_LOGC->get</a> and -<a href="../../api_c/log_put.html">DB_ENV->log_put</a> methods. It is very unlikely application programs used this -flag. If your application used this flag, please contact Sleepycat -Software support for help in upgrading. -<p>The DB_CURLSN flag has been removed from the <a href="../../api_c/log_put.html">DB_ENV->log_put</a> method. It is -very unlikely application programs used this flag. If your application -used this flag, please contact Sleepycat Software support for help in -upgrading. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/upgrade.4.1/log_stat.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.4.1/incomplete.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/libdb/docs/ref/upgrade.4.1/cxx.html b/libdb/docs/ref/upgrade.4.1/cxx.html deleted file mode 100644 index a90735a6b..000000000 --- a/libdb/docs/ref/upgrade.4.1/cxx.html +++ /dev/null @@ -1,48 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Release 4.1: C++ exceptions</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Upgrading Berkeley DB Applications</dl></h3></td> -<td align=right><a href="../../ref/upgrade.4.1/java.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.4.1/app_dispatch.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Release 4.1: C++ exceptions</h1> -<p>With default flags, the C++ <a href="../../api_cxx/env_class.html">DbEnv</a> and <a href="../../api_cxx/db_class.html">Db</a> classes -can throw exceptions from their constructors. For example, this can -happen if invalid parameters are passed in or the underlying C -structures could not be created. If the objects are created in an -environment that is not configured for exceptions (that is, the -<a href="../../api_c/env_class.html#DB_CXX_NO_EXCEPTIONS">DB_CXX_NO_EXCEPTIONS</a> flag is specified), errors from the -constructor will be returned when the handle's open method is called. -<p>In addition, the behavior of the <a href="../../api_cxx/env_class.html">DbEnv</a> and <a href="../../api_cxx/db_class.html">Db</a> -destructors has changed to simplify exception handling in applications. -The destructors will now close the handle if the handle's close method -was not called prior to the object being destroyed. The return value -of the call is discarded, and no exceptions will be thrown. -Applications should call the close method in normal situations so any -errors while closing can be handled by the application. -<p>This change allows applications to be structured as follows: -<p><blockquote><pre>try { - DbEnv env(0); - env.open(/* ... */); - Db db(&env, 0); - db.open(/* ... */); - /* ... */ - db.close(0); - env.close(0); -} catch (DbException &dbe) { - // Handle the exception, the handles have already been closed. -}</pre></blockquote> -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/upgrade.4.1/java.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.4.1/app_dispatch.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/libdb/docs/ref/upgrade.4.1/disk.html b/libdb/docs/ref/upgrade.4.1/disk.html deleted file mode 100644 index e216f13d3..000000000 --- a/libdb/docs/ref/upgrade.4.1/disk.html +++ /dev/null @@ -1,31 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Release 4.1: upgrade requirements</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Upgrading Berkeley DB Applications</dl></h3></td> -<td align=right><a href="../../ref/upgrade.4.1/app_dispatch.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/test/run.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Release 4.1: upgrade requirements</h1> -<p>All of the access method database formats changed in the Berkeley DB 4.1 -release (Btree/Recno: version 8 to version 9, Hash: version 7 to version -8, and Queue: version 3 to version 4). <b>The format changes are -entirely backward-compatible, and no database upgrades are needed.</b> -Note, however, that databases created using the 4.1 release may not be -usable with earlier Berkeley DB releases. -<p>The log file format changed in the Berkeley DB 4.1 release. -<p>For further information on upgrading Berkeley DB installations, see -<a href="../../ref/upgrade/process.html">Upgrading Berkeley DB installations</a>. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/upgrade.4.1/app_dispatch.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/test/run.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/libdb/docs/ref/upgrade.4.1/excl.html b/libdb/docs/ref/upgrade.4.1/excl.html deleted file mode 100644 index 302a92611..000000000 --- a/libdb/docs/ref/upgrade.4.1/excl.html +++ /dev/null @@ -1,26 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Release 4.1: DB_EXCL</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Upgrading Berkeley DB Applications</dl></h3></td> -<td align=right><a href="../../ref/upgrade.4.1/intro.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.4.1/fop.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Release 4.1: DB_EXCL</h1> -<p>The <a href="../../api_c/db_open.html#DB_EXCL">DB_EXCL</a> flag to the <a href="../../api_c/db_open.html">DB->open</a> method now works for -subdatabases as well as physical files, and it is now possible to use -the <a href="../../api_c/db_open.html#DB_EXCL">DB_EXCL</a> flag to check for the previous existence of -subdatabases. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/upgrade.4.1/intro.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.4.1/fop.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/libdb/docs/ref/upgrade.4.1/fop.html b/libdb/docs/ref/upgrade.4.1/fop.html deleted file mode 100644 index ed7d56637..000000000 --- a/libdb/docs/ref/upgrade.4.1/fop.html +++ /dev/null @@ -1,128 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Release 4.1: DB->associate, DB->open, DB->remove, DB->rename</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Upgrading Berkeley DB Applications</dl></h3></td> -<td align=right><a href="../../ref/upgrade.4.1/excl.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.4.1/log_register.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Release 4.1: DB->associate, DB->open, DB->remove, DB->rename</h1> -<p>Historic releases of Berkeley DB transaction-protected the <a href="../../api_c/db_open.html">DB->open</a>, -<a href="../../api_c/db_remove.html">DB->remove</a> and <a href="../../api_c/db_rename.html">DB->rename</a> methods, but did it in an implicit -way, that is, applications did not specify the <a href="../../api_c/txn_class.html">DB_TXN</a> handles -associated with the operations. This approach had a number of problems, -the most significant of which was there was no way to group operations -that included database creation, removal or rename. For example, -applications wanting to maintain a list of the databases in an -environment in a well-known database had no way to update the well-known -database and create a database within a single transaction, and so there -was no way to guarantee the list of databases was correct for the -environment after system or application failure. Another example might -be the creation of both a primary database and a database intended to -serve as a secondary index, where again there was no way to group the -creation of both databases in a single atomic operation. -<p>In the 4.1 release of Berkeley DB, this is no longer the case. The -<a href="../../api_c/db_open.html">DB->open</a> and <a href="../../api_c/db_associate.html">DB->associate</a> methods now take a <a href="../../api_c/txn_class.html">DB_TXN</a> -handle returned by <a href="../../api_c/txn_begin.html">DB_ENV->txn_begin</a> as an optional argument. New -<a href="../../api_c/env_dbremove.html">DB_ENV->dbremove</a> and <a href="../../api_c/env_dbrename.html">DB_ENV->dbrename</a> methods taking a -<a href="../../api_c/txn_class.html">DB_TXN</a> handle as an optional argument have been added. -<p>To upgrade, applications must add a <a href="../../api_c/txn_class.html">DB_TXN</a> parameter in the -appropriate location for the <a href="../../api_c/db_open.html">DB->open</a> method calls, and the -<a href="../../api_c/db_associate.html">DB->associate</a> method calls (in both cases, the second argument for -the C API, the first for the C++ or Java APIs). -<p>Applications wanting to transaction-protect their <a href="../../api_c/db_open.html">DB->open</a> and -<a href="../../api_c/db_associate.html">DB->associate</a> method calls can add a NULL <a href="../../api_c/txn_class.html">DB_TXN</a> -argument and specify the <a href="../../api_c/env_set_flags.html#DB_AUTO_COMMIT">DB_AUTO_COMMIT</a> flag to the two calls, -which wraps the operation in an internal Berkeley DB transaction. -Applications wanting to transaction-protect the remove and rename -operations must rewrite their calls to the <a href="../../api_c/db_remove.html">DB->remove</a> and -<a href="../../api_c/db_rename.html">DB->rename</a> methods to be, instead, calls to the new -<a href="../../api_c/env_dbremove.html">DB_ENV->dbremove</a> and <a href="../../api_c/env_dbrename.html">DB_ENV->dbrename</a> methods. Applications not -wanting to transaction-protect any of the operations can add a NULL -argument to their <a href="../../api_c/db_open.html">DB->open</a> and <a href="../../api_c/db_associate.html">DB->associate</a> method calls and -require no further changes. -<p>For example, an application currently opening and closing a database as -follows: -<p><blockquote><pre>DB *dbp; -DB_ENV *dbenv; -int ret; -<p> -if ((ret = db_create(&dbp, dbenv, 0)) != 0) - goto err_handler; -<p> -if ((ret = dbp->open(dbp, "file", NULL, DB_BTREE, DB_CREATE, 0664)) != 0) { - (void)dbp->close(dbp); - goto err_handler; -}</pre></blockquote> -<p>could transaction-protect the <a href="../../api_c/db_open.html">DB->open</a> call as follows: -<p><blockquote><pre>DB *dbp; -DB_ENV *dbenv; -int ret; -<p> -if ((ret = db_create(&dbp, dbenv, 0)) != 0) - goto err_handler; -<p> -if ((ret = dbp->open(dbp, - NULL, "file", NULL, DB_BTREE, DB_CREATE | DB_AUTO_COMMIT, 0664)) != 0) { - (void)dbp->close(dbp); - goto err_handler; -}</pre></blockquote> -<p>An application currently removing a database as follows: -<p><blockquote><pre>DB *dbp; -DB_ENV *dbenv; -int ret; -<p> -if ((ret = db_create(&dbp, dbenv, 0)) != 0) - goto err_handler; -<p> -if ((ret = dbp->remove(dbp, "file", NULL, 0)) != 0) - goto err_handler;</pre></blockquote> -<p>could transaction-protect the database removal as follows: -<p><blockquote><pre>DB *dbp; -DB_ENV *dbenv; -int ret; -<p> -if ((ret = - dbenv->dbremove(dbenv, NULL, "file", NULL, DB_AUTO_COMMIT)) != 0) - goto err_handler;</pre></blockquote> -<p>An application currently renaming a database as follows: -<p><blockquote><pre>DB *dbp; -DB_ENV *dbenv; -int ret; -<p> -if ((ret = db_create(&dbp, dbenv, 0)) != 0) - goto err_handler; -<p> -if ((ret = dbp->rename(dbp, "file", NULL, "newname", 0)) != 0) - goto err_handler;</pre></blockquote> -<p>could transaction-protect the database renaming as follows: -<p><blockquote><pre>DB *dbp; -DB_ENV *dbenv; -int ret; -<p> -if ((ret = dbenv->dbrename( - dbenv, NULL, "file", NULL, "newname", DB_AUTO_COMMIT)) != 0) - goto err_handler;</pre></blockquote> -<p>These examples are the simplest possible translation, and will result in -behavior matching that of previous releases. For further discussion on -how to transaction-protect <a href="../../api_c/db_open.html">DB->open</a> method calls, see -<a href="../../ref/transapp/data_open.html">Opening the databases</a>. -<p><a href="../../api_c/db_class.html">DB</a> handles that will later be used for transaction-protected -operations must be opened within a transaction. Specifying a -transaction handle to operations using handles not opened within a -transaction will return an error. Similarly, not specifying a -transaction handle to operations using handles that were opened within -a transaction will also return an error. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/upgrade.4.1/excl.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.4.1/log_register.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/libdb/docs/ref/upgrade.4.1/hash_nelem.html b/libdb/docs/ref/upgrade.4.1/hash_nelem.html deleted file mode 100644 index ea1471156..000000000 --- a/libdb/docs/ref/upgrade.4.1/hash_nelem.html +++ /dev/null @@ -1,25 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Release 4.1: DB->stat.hash_nelem</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Upgrading Berkeley DB Applications</dl></h3></td> -<td align=right><a href="../../ref/upgrade.4.1/memp_sync.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.4.1/java.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Release 4.1: DB->stat.hash_nelem</h1> -<p>The <b>hash_nelem</b> field of the <a href="../../api_c/db_stat.html">DB->stat</a> method for Hash -databases has been removed from the 4.1 release, this information is no -longer available to applications. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/upgrade.4.1/memp_sync.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.4.1/java.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/libdb/docs/ref/upgrade.4.1/incomplete.html b/libdb/docs/ref/upgrade.4.1/incomplete.html deleted file mode 100644 index 07520e351..000000000 --- a/libdb/docs/ref/upgrade.4.1/incomplete.html +++ /dev/null @@ -1,30 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Release 4.1: DB_INCOMPLETE</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Upgrading Berkeley DB Applications</dl></h3></td> -<td align=right><a href="../../ref/upgrade.4.1/checkpoint.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.4.1/memp_sync.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Release 4.1: DB_INCOMPLETE</h1> -<p>The DB_INCOMPLETE error has been removed from the 4.1 release, and is -no longer returned by the Berkeley DB library. Applications no longer need -to check for this error return, as the underlying Berkeley DB interfaces that -could historically fail to checkpoint or flush the cache and return this -error can no longer fail for that reason. Applications should remove -all uses of DB_INCOMPLETE. -<p>Additionally, the <a href="../../api_java/txn_checkpoint.html">DbEnv.txn_checkpoint</a> and <a href="../../api_java/db_sync.html">Db.sync</a> -methods have been changed from returning int to returning void. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/upgrade.4.1/checkpoint.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.4.1/memp_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/libdb/docs/ref/upgrade.4.1/intro.html b/libdb/docs/ref/upgrade.4.1/intro.html deleted file mode 100644 index f9d9f31b3..000000000 --- a/libdb/docs/ref/upgrade.4.1/intro.html +++ /dev/null @@ -1,27 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Release 4.1: introduction</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Upgrading Berkeley DB Applications</dl></h3></td> -<td align=right><a href="../../ref/upgrade.4.0/disk.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.4.1/excl.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Release 4.1: introduction</h1> -<p>The following pages describe how to upgrade applications coded against -the Berkeley DB 4.0 release interfaces to the Berkeley DB 4.1 release interfaces. -This information does not describe how to upgrade Berkeley DB 1.85 release -applications. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/upgrade.4.0/disk.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.4.1/excl.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/libdb/docs/ref/upgrade.4.1/java.html b/libdb/docs/ref/upgrade.4.1/java.html deleted file mode 100644 index 6a6647af2..000000000 --- a/libdb/docs/ref/upgrade.4.1/java.html +++ /dev/null @@ -1,29 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Release 4.1: Java exceptions</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Upgrading Berkeley DB Applications</dl></h3></td> -<td align=right><a href="../../ref/upgrade.4.1/hash_nelem.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.4.1/cxx.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Release 4.1: Java exceptions</h1> -<p>The Java <a href="../../api_java/env_class.html">DbEnv</a> constructor is now marked with "throws -DbException". This means applications must construct <a href="../../api_java/env_class.html">DbEnv</a> -objects in a context where <a href="../../api_java/except_class.html">DbException</a> throwables are -handled (either in a try/catch block or in a method that propagates the -exception up the stack). Note that previous versions of the Berkeley DB Java -API could throw this exception from the constructor but it was not -marked. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/upgrade.4.1/hash_nelem.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.4.1/cxx.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/libdb/docs/ref/upgrade.4.1/log_register.html b/libdb/docs/ref/upgrade.4.1/log_register.html deleted file mode 100644 index 81137d8e8..000000000 --- a/libdb/docs/ref/upgrade.4.1/log_register.html +++ /dev/null @@ -1,27 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Release 4.1: DB_ENV->log_register</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Upgrading Berkeley DB Applications</dl></h3></td> -<td align=right><a href="../../ref/upgrade.4.1/fop.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.4.1/log_stat.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Release 4.1: DB_ENV->log_register</h1> -<p>The DB_ENV->log_register and DB_ENV->log_unregister interfaces -were removed from the Berkeley DB 4.1 release. It is very unlikely -application programs used these interfaces. If your application used -these interfaces, please contact Sleepycat Software support for help in -upgrading. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/upgrade.4.1/fop.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.4.1/log_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/libdb/docs/ref/upgrade.4.1/log_stat.html b/libdb/docs/ref/upgrade.4.1/log_stat.html deleted file mode 100644 index 7b7057e90..000000000 --- a/libdb/docs/ref/upgrade.4.1/log_stat.html +++ /dev/null @@ -1,26 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Release 4.1: st_flushcommit</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Upgrading Berkeley DB Applications</dl></h3></td> -<td align=right><a href="../../ref/upgrade.4.1/log_register.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.4.1/checkpoint.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Release 4.1: st_flushcommit</h1> -<p>The DB_ENV->log_stat "st_flushcommits" statistic has been removed -from Berkeley DB, as it is now the same as the "st_scount" statistic. Any -application using the "st_flushcommits" statistic should remove it, or -replace it with the "st_count" statistic. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/upgrade.4.1/log_register.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.4.1/checkpoint.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/libdb/docs/ref/upgrade.4.1/memp_sync.html b/libdb/docs/ref/upgrade.4.1/memp_sync.html deleted file mode 100644 index 40b0cc588..000000000 --- a/libdb/docs/ref/upgrade.4.1/memp_sync.html +++ /dev/null @@ -1,31 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Release 4.1: DB_ENV->memp_sync</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Upgrading Berkeley DB Applications</dl></h3></td> -<td align=right><a href="../../ref/upgrade.4.1/incomplete.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.4.1/hash_nelem.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Release 4.1: DB_ENV->memp_sync</h1> -<p>Historical documentation for the <a href="../../api_c/memp_sync.html">DB_ENV->memp_sync</a> interface stated: -<p><blockquote><pre>In addition, if <a href="../../api_c/memp_sync.html">DB_ENV->memp_sync</a> returns success, the value of -<b>lsn</b> will be overwritten with the largest log sequence number -from any page that was written by <a href="../../api_c/memp_sync.html">DB_ENV->memp_sync</a> to satisfy this -request.</pre></blockquote> -<p>This functionality was never correctly implemented, and has been removed -in the Berkeley DB 4.1 release. It is very unlikely application programs used -this information. If your application used this information, please -contact Sleepycat Software support for help in upgrading. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/upgrade.4.1/incomplete.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.4.1/hash_nelem.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/libdb/docs/ref/upgrade.4.1/toc.html b/libdb/docs/ref/upgrade.4.1/toc.html deleted file mode 100644 index de2a0d5ca..000000000 --- a/libdb/docs/ref/upgrade.4.1/toc.html +++ /dev/null @@ -1,37 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Upgrading Berkeley DB 4.0.X applications to Berkeley DB 4.1</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Upgrading Berkeley DB Applications</dl></h3></td> -<td align=right><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a> -</td></tr></table> -<p> -<h1 align=center>Upgrading Berkeley DB 4.0.X applications to Berkeley DB 4.1</h1> -<p><ol> -<p><li><a href="intro.html">Release 4.1: introduction</a> -<li><a href="excl.html">Release 4.1: DB_EXCL</a> -<li><a href="fop.html">Release 4.1: DB->associate, DB->open, DB->remove, DB->rename</a> -<li><a href="log_register.html">Release 4.1: DB_ENV->log_register</a> -<li><a href="log_stat.html">Release 4.1: st_flushcommit</a> -<li><a href="checkpoint.html">Release 4.1: DB_CHECKPOINT, DB_CURLSN</a> -<li><a href="incomplete.html">Release 4.1: DB_INCOMPLETE</a> -<li><a href="memp_sync.html">Release 4.1: DB_ENV->memp_sync</a> -<li><a href="hash_nelem.html">Release 4.1: DB->stat.hash_nelem</a> -<li><a href="java.html">Release 4.1: Java exceptions</a> -<li><a href="cxx.html">Release 4.1: C++ exceptions</a> -<li><a href="app_dispatch.html">Release 4.1: Application-specific logging and recovery</a> -<li><a href="disk.html">Release 4.1: upgrade requirements</a> -</ol> -<table width="100%"><tr><td><br></td><td align=right><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a> -</td></tr></table> -<p><font size=1><a href="http://www.sleepycat.com">Copyright Sleepycat Software</a></font> -</body> -</html> diff --git a/libdb/docs/ref/upgrade/process.html b/libdb/docs/ref/upgrade/process.html deleted file mode 100644 index a4d20cf2f..000000000 --- a/libdb/docs/ref/upgrade/process.html +++ /dev/null @@ -1,131 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Upgrading Berkeley DB installations</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Upgrading Berkeley DB Applications</dl></h3></td> -<td align=right><a href="../../ref/upgrade/version.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.2.0/intro.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Upgrading Berkeley DB installations</h1> -<p>The following information describes the general process of upgrading -Berkeley DB installations. There are four areas to be considered when -upgrading Berkeley DB applications and database environments: the application -API, the database environment's region files, the underlying database -formats, and, in the case of transactional database environments, the -log files. The upgrade procedures required depend on whether or not -the release is a major or minor release (in which either the major or -minor number of the version changed), or a patch release (in which only -the patch number in the version changed). Berkeley DB major and minor -releases may optionally include changes in all four areas, that is, the -application API, region files, database formats, and log files may not -be backward-compatible with previous releases. -<p>Each Berkeley DB major or minor release has information in this chapter of -the Reference Guide, describing how to upgrade to the new release. The -section describes any API changes made in the release. Application -maintainers should review the API changes and update their applications -as necessary before recompiling with the new release. In addition, each -section includes a page specifying whether the log file format or -database formats changed in non-backward-compatible ways as part of the -release. Because there are several underlying Berkeley DB database formats, -and they do not all necessarily change in the same release, changes to -a database format in a release may not affect any particular -application. Further, database and log file formats may have changed -but be entirely backward-compatible, in which case no upgrade will be -necessary. -<p>A Berkeley DB patch release will never modify the API, regions, log files, or -database formats in incompatible ways, and so applications need only be -relinked (or, in the case of a shared library, pointed at the new -version of the shared library) to upgrade to a new release. Note that -internal Berkeley DB interfaces may change at any time and in any release -(including patch releases) without warning. This means the library must -be entirely recompiled and reinstalled when upgrading to new releases -of the library because there is no guarantee that modules from one -version of the library will interact correctly with modules from another -release. -<p>If the release is a patch release, do the following: -<p><ol> -<p><li>Shut down the old version of the application. -<li>Install the new version of the application by relinking or installing -a new version of the Berkeley DB shared library. -<li>Restart the application. -</ol> -<p>Otherwise, if the application <b>does not</b> have a Berkeley DB -transactional environment, the application may be installed in the field -using the following steps: -<p><ol> -<p><li>Shut down the old version of the application. -<li>Remove any Berkeley DB environment using the <a href="../../api_c/env_remove.html">DB_ENV->remove</a> method or an -appropriate system utility. -<li>Recompile and install the new version of the application. -<li>If necessary, upgrade the application's databases. See -<a href="../../ref/am/upgrade.html">Upgrading databases</a> for more -information. -<li>Restart the application. -</ol> -<p>Otherwise, if the application has a Berkeley DB transactional environment, -but neither the log file nor database formats need upgrading, the -application may be installed in the field using the following steps: -<p><ol> -<p><li>Shut down the old version of the application. -<li>Run recovery on the database environment using the <a href="../../api_c/env_open.html">DB_ENV->open</a> method -or the <a href="../../utility/db_recover.html">db_recover</a> utility. -<li>Remove any Berkeley DB environment using the <a href="../../api_c/env_remove.html">DB_ENV->remove</a> method or an -appropriate system utility. -<li>Recompile and install the new version of the application. -<li>Restart the application. -</ol> -<p>If the application has a Berkeley DB transactional environment, and the log -files needs upgrading but the databases do not, the application may be -installed in the field using the following steps: -<p><ol> -<p><li>Shut down the old version of the application. -<li>Run recovery on the database environment using the <a href="../../api_c/env_open.html">DB_ENV->open</a> method -or the <a href="../../utility/db_recover.html">db_recover</a> utility. -<li>Remove any Berkeley DB environment using the <a href="../../api_c/env_remove.html">DB_ENV->remove</a> method or an -appropriate system utility. -<li>Archive the database environment for catastrophic recovery. See -<a href="../../ref/transapp/archival.html">Archival procedures</a> for more -information. -<li>Recompile and install the new version of the application. -<li>Restart the application. -</ol> -<p>Otherwise, if the application has a Berkeley DB transactional environment and -the databases need upgrading, the application may be installed in the -field using the following steps: -<p><ol> -<p><li>Shut down the old version of the application. -<li>Run recovery on the database environment using the <a href="../../api_c/env_open.html">DB_ENV->open</a> method -or the <a href="../../utility/db_recover.html">db_recover</a> utility. -<li>Remove any Berkeley DB environment using the <a href="../../api_c/env_remove.html">DB_ENV->remove</a> method or an -appropriate system utility. -<li>Archive the database environment for catastrophic recovery. See -<a href="../../ref/transapp/archival.html">Archival procedures</a> for more -information. -<li>Recompile and install the new version of the application. -<li>Upgrade the application's databases. See -<a href="../../ref/am/upgrade.html">Upgrading databases</a> for more -information. -<li>Archive the database for catastrophic recovery again (using different -media than before, of course). Note: This archival is not strictly -necessary. However, if you have to perform catastrophic recovery after -restarting the application, that recovery must be done based on the -last archive you have made. If you make this second archive, you can -use it as the basis of that catastrophic recovery. If you do not make -this second archive, you have to use the archive you made in step 4 as -the basis of your recovery, and you have to do a full upgrade on it -before you can apply log files created after the upgrade to it. -<li>Restart the application. -</ol> -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/upgrade/version.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.2.0/intro.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/libdb/docs/ref/upgrade/version.html b/libdb/docs/ref/upgrade/version.html deleted file mode 100644 index 26a64ae88..000000000 --- a/libdb/docs/ref/upgrade/version.html +++ /dev/null @@ -1,47 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Library version information</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Upgrading Berkeley DB Applications</dl></h3></td> -<td align=right><a href="../../ref/build_vxworks/faq.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade/process.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Library version information</h1> -<p>Each release of the Berkeley DB library has a major version number, a minor -version number, and a patch number. -<p>The major version number changes only when major portions of the Berkeley DB -functionality have been changed. In this case, it may be necessary to -significantly modify applications in order to upgrade them to use the new -version of the library. -<p>The minor version number changes when Berkeley DB interfaces have changed, -and the new release is not entirely backward-compatible with previous -releases. To upgrade applications to the new version, they must be -recompiled and potentially, minor modifications made (for example, the -order of arguments to a function might have changed). -<p>The patch number changes on each release. If only the patch number has -changed in a release, applications do not need to be recompiled, and -they can be upgraded to the new version by installing the new version -of a shared library or by relinking the application to the new version -of a static library. -<p>Internal Berkeley DB interfaces may change at any time and during any release, -without warning. This means that the library must be entirely recompiled -and reinstalled when upgrading to new releases of the library because -there is no guarantee that modules from the current version of the -library will interact correctly with modules from a previous release. -<p>To retrieve the Berkeley DB version information, applications should use the -<a href="../../api_c/env_version.html">db_version</a> interface. In addition to the previous -information, the <a href="../../api_c/env_version.html">db_version</a> interface returns a string -encapsulating the version information, suitable for display to a user. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/build_vxworks/faq.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade/process.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/libdb/docs/ref/xa/build.html b/libdb/docs/ref/xa/build.html deleted file mode 100644 index 6c90cd76a..000000000 --- a/libdb/docs/ref/xa/build.html +++ /dev/null @@ -1,178 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Building a Global Transaction Manager</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Distributed Transactions</dl></h3></td> -<td align=right><a href="../../ref/xa/intro.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/xa/xa_intro.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Building a Global Transaction Manager</h1> -<p>Managing distributed transactions and using the two-phase commit -protocol of Berkeley DB from an application requires the application provide -the functionality of a global transaction manager (GTM). The GTM is -responsible for the following: -<p><ul type=disc> -<li>Communicating with the multiple environments (potentially on separate -systems). -<li>Managing the global transaction ID name space. -<li>Maintaining state information about each distributed transaction. -<li>Recovering from failures of individual environments. -<li>Recovering the global transaction state after failure of the global -transaction manager. -</ul> -<h3>Communicating with multiple Berkeley DB environments</h3> -<p>Two-phase commit is required if an application wants to transaction -protect Berkeley DB calls across multiple environments. If the environments -reside on the same machine, the application can communicate with each -environment through its own address space with no additional complexity. -If the environments reside on separate machines, the application can -either use the Berkeley DB RPC server to manage the remote environments or it -may use its own messaging capability, translating messages on the remote -machine into calls into the Berkeley DB library (including the recovery -calls). For some applications, it might be sufficient to use Tcl's -remote invocation to remote copies of the tclsh utility into which the -Berkeley DB library has been dynamically loaded. -<h3>Managing the Global Transaction ID (GID) name space</h3> -<p>A global transaction is a transaction that spans multiple environments. -Each global transaction must have a unique transaction ID. This unique -ID is the global transaction ID (GID). In Berkeley DB, global transaction -IDs must be represented with the confines of a <a href="../../api_c/txn_prepare.html#DB_XIDDATASIZE">DB_XIDDATASIZE</a> -size (currently 128 bytes) array. It is the responsibility of the -global transaction manager to assign GIDs, guarantee their uniqueness, -and manage the mapping of local transactions to GID. That is, for each -GID, the GTM should know which local transactions managers participated. -The Berkeley DB logging system or a Berkeley DB table could be used to record this -information. -<h3>Maintaining state for each distributed transaction.</h3> -<p>In addition to knowing which local environments participate in each -global transaction, the GTM must also know the state of each active -global transaction. As soon as a transaction becomes distributed (that -is, a second environment participates), the GTM must record the -existence of the global transaction and all participants (whether this -must reside on stable storage or not depends on the exact configuration -of the system). As new environments participate, the GTM must keep this -information up to date. -<p>When the GTM is ready to begin commit processing, it should issue -<a href="../../api_c/txn_prepare.html">DB_TXN->prepare</a> calls to each participating environment, indicating -the GID of the global transaction. Once all the participants have -successfully prepared, then the GTM must record that the global -transaction will be committed. This record should go to stable -storage. Once written to stable storage, the GTM can send -<a href="../../api_c/txn_commit.html">DB_TXN->commit</a> requests to each participating environment. Once -all environments have successfully completed the commit, the GTM can -either record the successful commit or can somehow "forget" the global -transaction. -<p>If nested transactions are used (that is, the <b>parent</b> parameter -is specified to <a href="../../api_c/txn_begin.html">DB_ENV->txn_begin</a>), no <a href="../../api_c/txn_prepare.html">DB_TXN->prepare</a> call should -be made on behalf of any child transaction. Only the ultimate parent -should even issue a <a href="../../api_c/txn_prepare.html">DB_TXN->prepare</a>. -<p>Should any participant fail to prepare, then the GTM must abort the -global transaction. The fact that the transaction is going to be -aborted should be written to stable storage. Once written, the GTM can -then issue <a href="../../api_c/txn_abort.html">DB_TXN->abort</a> requests to each environment. When all -aborts have returned successfully, the GTM can either record the -successful abort or "forget" the global transaction. -<p>In summary, for each transaction, the GTM must maintain the following: -<p><ul type=disc> -<li>A list of participating environments -<li>The current state of each transaction (pre-prepare, preparing, -committing, aborting, done) -</ul> -<h3>Recovering from the failure of a single environment</h3> -<p>If a single environment fails, there is no need to bring down or recover -other environments (the only exception to this is if all environments -are managed in the same application address space and there is a risk -that the failure of the environment corrupted other environments). -Instead, once the failing environment comes back up, it should be -recovered (that is, conventional recovery, via <a href="../../utility/db_recover.html">db_recover</a> or by -specifying the <a href="../../api_c/env_open.html#DB_RECOVER">DB_RECOVER</a> flag to <a href="../../api_c/env_open.html">DB_ENV->open</a> should be -run). -If the <a href="../../utility/db_recover.html">db_recover</a> utility is used, then the -e option must be -specified. In this case, the application will almost certainly want -to specify environmental parameters via a DB_CONFIG file in the -environment's home directory, so that <a href="../../utility/db_recover.html">db_recover</a> can create -an appropriately configured environment. -If the <a href="../../utility/db_recover.html">db_recover</a> utility is not used, then <a href="../../api_c/env_open.html#DB_PRIVATE">DB_PRIVATE</a> -should not be specified, unless all processing including recovery, calls -to <a href="../../api_c/txn_recover.html">DB_ENV->txn_recover</a>, and calls to finish prepared, but not yet -complete transactions take place using the same database environment -handle. -The GTM should then issue a <a href="../../api_c/txn_recover.html">DB_ENV->txn_recover</a> call to the environment. -This call will return a list of prepared, but not yet committed or -aborted transactions. For each transaction, the GTM should look up the -GID in its local store to determine if the transaction should commit or -abort. -If the GTM is running in a system with multiple GTMs, it is possible that -some of the transactions returned via <a href="../../api_c/txn_recover.html">DB_ENV->txn_recover</a> do not belong -to the current environment. The GTM should detect this and call -<a href="../../api_c/txn_discard.html">DB_TXN->discard</a> on each such transaction handle. -Furthermore, it is important to note that the environment does not -retain information about which GTM has issued <a href="../../api_c/txn_recover.html">DB_ENV->txn_recover</a> -operations. Therefore, each GTM should issue all its <a href="../../api_c/txn_recover.html">DB_ENV->txn_recover</a> -calls, before another GTM issues its calls. If the calls are interleaved, -each GTM may not get a complete and consistent set of transactions. -The simplest way to enforce this is for each GTM to make sure it can -receive all its outstanding transactions in a single <a href="../../api_c/txn_recover.html">DB_ENV->txn_recover</a> -call. The maximum number of possible outstanding transactions is bounded -by the maximum number of active transactions in the environment. This -number can be obtained by using the <a href="../../api_c/txn_stat.html">DB_ENV->txn_stat</a> interface or the -<a href="../../utility/db_stat.html">db_stat</a> utility. -<p>The newly recovered environment will forbid any new transactions from -being started until the prepared but not yet committed/aborted -transactions have been resolved. In the multiple GTM case, this means -that all GTMs must recover before any GTM can begin issuing new transactions. -<p>Because Berkeley DB flushed both commit and abort records to disk for -two-phase transaction, once the global transaction has either committed -or aborted, no action will be necessary in any environment. If local -environments are running with the <a href="../../api_c/env_set_flags.html#DB_TXN_WRITE_NOSYNC">DB_TXN_WRITE_NOSYNC</a> or -<a href="../../api_c/env_set_flags.html#DB_TXN_NOSYNC">DB_TXN_NOSYNC</a> options (that is, is not writing and/or flushing -the log synchronously at commit time), then it is possible that a commit -or abort operation may not have been written in the environment. In -this case, the GTM must always have a record of completed transactions -to determine if prepared transactions should be committed or aborted. -<h3>Recovering from GTM failure</h3> -<p>If the GTM fails, it must first recover its local state. Assuming the -GTM uses Berkeley DB tables to maintain state, it should run -<a href="../../utility/db_recover.html">db_recover</a> (or the <a href="../../api_c/env_open.html#DB_RECOVER">DB_RECOVER</a> option to -<a href="../../api_c/env_open.html">DB_ENV->open</a>) upon startup. Once the GTM is back up and running, -it needs to review all its outstanding global transactions, that is all -transaction which are recorded, but not yet committed or aborted. -<p>Any global transactions which have not yet reached the prepare phase -should be aborted. If these transactions were on remote systems, the -remote systems should eventually time them out and abort them. If these -transactions are on the local system, we assume they crashed and were -aborted as part of GTM startup. -<p>The GTM must then identify all environments which need to have their -<a href="../../api_c/txn_recover.html">DB_ENV->txn_recover</a> interface called. This includes all environments -that participate in any transaction that is in the preparing, aborting, -or committing state. For each environment, the GTM should issue a -<a href="../../api_c/txn_recover.html">DB_ENV->txn_recover</a> call. Once each environment has responded, the GTM -can determine the fate of each transaction. The correct behavior is -defined depending on the state of the global transaction according to -the table below. -<p><dl compact> -<p><dt>preparing<dd>if all participating environments return the transaction in the prepared -but not yet committed/aborted state, then the GTM should commit the -transaction. If any participating environment fails to return it, then -the GTM should issue an abort to all environments that did return it. -<p><dt>committing<dd>the GTM should send a commit to any environment that returned this -transaction in its list of prepared but not yet committed/aborted -transactions. -<p><dt>aborting<dd>the GTM should send an abort to any environment that returned this -transaction in its list of prepared but not yet committed/aborted -transactions. -</dl> -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/xa/intro.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/xa/xa_intro.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/libdb/docs/ref/xa/faq.html b/libdb/docs/ref/xa/faq.html deleted file mode 100644 index d383cfc6d..000000000 --- a/libdb/docs/ref/xa/faq.html +++ /dev/null @@ -1,66 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: XA FAQ</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Distributed Transactions</dl></h3></td> -<td align=right><a href="../../ref/xa/xa_config.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/apprec/intro.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>XA FAQ</h1> -<p><ol> -<p><li><b>Is it possible to mix XA and non-XA transactions?</b> -<p>Yes. It is also possible for XA and non-XA transactions to coexist in -the same Berkeley DB environment. To do this, specify the same environment -to the non-XA <a href="../../api_c/env_open.html">DB_ENV->open</a> calls as was specified in the Tuxedo -configuration file. -<hr size=1 noshade> -<p><li><b>Does converting an application to run within XA change any of -the already existing C/C++ API calls it does?</b> -<p>When converting an application to run under XA, the application's Berkeley DB -calls are unchanged, with three exceptions: -<p><ol> -<p><li>The application must specify the <a href="../../api_c/db_create.html#DB_XA_CREATE">DB_XA_CREATE</a> flag to -the <a href="../../api_c/db_create.html">db_create</a> interface. -<p><li>Unless the application is performing an operation for a non-XA -transaction, the application should never explicitly call -<a href="../../api_c/txn_commit.html">DB_TXN->commit</a>, <a href="../../api_c/txn_abort.html">DB_TXN->abort</a> or <a href="../../api_c/txn_begin.html">DB_ENV->txn_begin</a>, and those -calls should be replaced by calls into the Tuxedo transaction manager. -<p><li>Unless the application is performing an operation for a non-XA -transaction, the application should specify a transaction argument of NULL -to Berkeley DB methods taking transaction arguments (for example, <a href="../../api_c/db_put.html">DB->put</a> -or <a href="../../api_c/db_cursor.html">DB->cursor</a>). -</ol> -<p>Otherwise, the application should be unchanged. -<hr size=1 noshade> -<p><li><b>How does Berkeley DB recovery interact with recovery by the Tuxedo -transaction manager?</b> -<p>Recovery is completed in two steps. First, each resource manager should -recover its environment(s). This can be done via a program that calls -<a href="../../api_c/env_open.html">DB_ENV->open</a> or by calling the <a href="../../utility/db_recover.html">db_recover</a> utility. If -using the <a href="../../utility/db_recover.html">db_recover</a> utility, then the <b>-e</b> option -should be specified so that the regions that are recovered persist after -the utility exits. Any transactions that were prepared, but neither -completed nor aborted, are restored to their prepared state so that they -may be aborted or committed via the Tuxedo recovery mechanisms. After -each resource manager has recovered, then Tuxedo recovery may begin. -Tuxedo will interact with each resource manager via the __db_xa_recover -function which returns the list of prepared, but not yet completed -transactions. It should issue a commit or abort for each one, and only -after having completed each transaction will normal processing resume. -<p>Finally, standard log file archival and catastrophic recovery procedures -should occur independently of XA operation. -</ol> -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/xa/xa_config.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/apprec/intro.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/libdb/docs/ref/xa/intro.html b/libdb/docs/ref/xa/intro.html deleted file mode 100644 index 49021d0fd..000000000 --- a/libdb/docs/ref/xa/intro.html +++ /dev/null @@ -1,53 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Introduction</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Distributed Transactions</dl></h3></td> -<td align=right><a href="../../ref/rep/ex_rq.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/xa/build.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Introduction</h1> -<p>Berkeley DB provides support for distributed transactions using a two-phase -commit protocol via its <a href="../../api_c/txn_prepare.html">DB_TXN->prepare</a> and <a href="../../api_c/txn_recover.html">DB_ENV->txn_recover</a> -interfaces. The <a href="../../api_c/txn_prepare.html">DB_TXN->prepare</a> method performs the first phase of a -two-phase commit, flushing the log to disk, and associating a global -transaction ID with the underlying Berkeley DB transaction. This global -transaction ID should be used by the global transaction manager to -identify the Berkeley DB transaction, and will be returned by the -<a href="../../api_c/txn_recover.html">DB_ENV->txn_recover</a> method when it is called during recovery. -<p>Distributed transactions are necessary whenever an application wants to -transaction-protect data in multiple Berkeley DB environments, even if those -environments are on the same machine. However, Berkeley DB does not perform -distributed deadlock detection, therefore it is the responsibility of -the application to ensure that accesses in different environments cannot -deadlock (this can be accomplished through careful ordering of -operations to the multiple environments), or by using the -<a href="../../api_c/lock_vec.html#DB_LOCK_NOWAIT">DB_LOCK_NOWAIT</a> option and eventually abort transactions that -have been waiting "too long" (where "too long" is determined by an -application-specific timeout). -<p>In order to use the two-phase commit feature of Berkeley DB, an application -must either implement its own global transaction manager or use an -XA-compliant transaction manager (as Berkeley DB can act as an XA-compliant -resource manager). -<p>When using distributed transactions, there is no way to perform -hot backups of multiple environments and guarantee that the backups -are global-transaction-consistent across these multiple environments. -If backups are desired, then all write transactions should be suspended; -that is, active write transactions must be allowed to complete and no -new write transactions should be begun. Once there are no active write -transactions, the logs may be copied for backup purposes and the backup -will be consistent across the multiple environments. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/rep/ex_rq.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/xa/build.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/libdb/docs/ref/xa/xa_config.html b/libdb/docs/ref/xa/xa_config.html deleted file mode 100644 index a94d4fc33..000000000 --- a/libdb/docs/ref/xa/xa_config.html +++ /dev/null @@ -1,81 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: Configuring Berkeley DB with the Tuxedo System</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Distributed Transactions</dl></h3></td> -<td align=right><a href="../../ref/xa/xa_intro.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/xa/faq.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>Configuring Berkeley DB with the Tuxedo System</h1> -<p>This information assumes that you have already installed the Berkeley DB -library. -<p>First, you must update the resource manager file in Tuxedo. For the -purposes of this discussion, assume that the Tuxedo home directory is in -<p><blockquote><pre>/home/tuxedo</pre></blockquote> -In that case, the resource manager file will be located in -<p><blockquote><pre>/home/tuxedo/udataobj/RM</pre></blockquote> -Edit the resource manager file, adding the line -<p><blockquote><pre>BERKELEY-DB:db_xa_switch:-L${DB_INSTALL}/lib -ldb \ - -lsocket -ldl -lm</pre></blockquote> -<p>where ${DB_INSTALLHOME} is the directory into which you installed the Berkeley DB -library. -<p><b>Note that the previous load options are for a Sun Microsystems -Solaris 5.6 Sparc installation of Tuxedo, and may not be correct for -your system.</b> -<p>Next, you must build the transaction manager server. To do this, use the -Tuxedo <b>buildtms</b>(1) utility. The buildtms utility will create -the Berkeley-DB resource manager in the directory from which it was run. -The parameters to buildtms should be -<p><blockquote><pre>buildtms -v -o DBRM -r BERKELEY-DB</pre></blockquote> -<p>This will create an executable transaction manager server, DBRM, which is -called by Tuxedo to process begins, commits, and aborts. -<p>Finally, you must make sure that your TUXCONFIG environment variable -identifies an ubbconfig file that properly identifies your resource -managers. In the GROUPS section of the ubb file, you should identify the -group's LMID and GRPNO, as well as the transaction manager server name -"TMSNAME=DBRM." You must also specify the OPENINFO parameter, setting it -equal to the string -<p><blockquote><pre>rm_name:dir</pre></blockquote> -<p>where rm_name is the resource name specified in the RM file (that is, -BERKELEY-DB) and dir is the directory for the Berkeley DB home environment -(see <a href="../../api_c/env_open.html">DB_ENV->open</a> for a discussion of Berkeley DB environments). -<p>Because Tuxedo resource manager startup accepts only a single string -for configuration, any environment customization that might have been -done via the config parameter to <a href="../../api_c/env_open.html">DB_ENV->open</a> must instead be done -by placing a <a href="../../ref/env/db_config.html#DB_CONFIG">DB_CONFIG</a> file in the Berkeley DB environment directory. -See <a href="../../ref/env/naming.html">Berkeley DB File Naming</a> for further -information. -<p>Consider the following configuration. We have built a transaction -manager server, as described previously. We want the Berkeley DB environment -to be <b>/home/dbhome</b>, our database files to be maintained in -<b>/home/datafiles</b>, our log files to be maintained in -<b>/home/log</b>, and we want a duplexed server. -<p>The GROUPS section of the ubb file might look like the following -<p><blockquote><pre>group_tm LMID=myname GRPNO=1 TMSNAME=DBRM TMSCOUNT=2 \ - OPENINFO="BERKELEY-DB:/home/dbhome"</pre></blockquote> -<p>There would be a <a href="../../ref/env/db_config.html#DB_CONFIG">DB_CONFIG</a> configuration file in the directory -<b>/home/dbhome</b> that contained the following two lines: -<p><blockquote><pre>set_data_dir /home/datafiles -set_log_dir /home/log -</pre></blockquote> -<p>Finally, the ubb file must be translated into a binary version using -Tuxedo's <b>tmloadcf</b>(1) utility, and then the pathname of that -binary file must be specified as your TUXCONFIG environment variable. -<p>At this point, your system is properly initialized to use the Berkeley DB -resource manager. -<p>See <a href="../../api_c/db_create.html">db_create</a> for further information on accessing data files -using XA. -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/xa/xa_intro.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/xa/faq.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/libdb/docs/ref/xa/xa_intro.html b/libdb/docs/ref/xa/xa_intro.html deleted file mode 100644 index 829abf112..000000000 --- a/libdb/docs/ref/xa/xa_intro.html +++ /dev/null @@ -1,62 +0,0 @@ -<!--$Id$--> -<!--Copyright 1997-2002 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<!--See the file LICENSE for redistribution information.--> -<html> -<head> -<title>Berkeley DB Reference Guide: XA Introduction</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 width="100%"><tr valign=top> -<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Distributed Transactions</dl></h3></td> -<td align=right><a href="../../ref/xa/build.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/xa/xa_config.html"><img src="../../images/next.gif" alt="Next"></a> -</td></tr></table> -<p> -<h1 align=center>XA Introduction</h1> -<p>Berkeley DB can be used as an XA-compliant resource manager. The XA -implementation is known to work with the Tuxedo(tm) transaction -manager. -<p>The XA support is encapsulated in the resource manager switch -db_xa_switch, which defines the following functions: -<p><blockquote><pre>__db_xa_close Close the resource manager. -__db_xa_commit Commit the specified transaction. -__db_xa_complete Wait for asynchronous operations to - complete. -__db_xa_end Disassociate the application from a - transaction. -__db_xa_forget Forget about a transaction that was heuristically - completed. (Berkeley DB does not support heuristic - completion.) -__db_xa_open Open the resource manager. -__db_xa_prepare Prepare the specified transaction. -__db_xa_recover Return a list of prepared, but not yet - committed transactions. -__db_xa_rollback Abort the specified transaction. -__db_xa_start Associate the application with a - transaction. -</pre></blockquote> -<p>The Berkeley DB resource manager does not support the following optional -XA features: -<p><ul type=disc> -<li>Asynchronous operations -<li>Transaction migration -</ul> -<p>The Tuxedo System is available from <a href="http://www.beasys.com">BEA Systems, Inc.</a> -<p>For additional information on Tuxedo, see -<p><blockquote><i>Building Client/Server Applications Using Tuxedo</i>, -by Hall (John Wiley & Sons, Inc.).</blockquote> -<p>For additional information on XA Resource Managers, see -<p><blockquote>X/Open CAE Specification -<i>Distributed Transaction Processing: The XA Specification</i>, -X/Open Document Number: XO/CAE/91/300.</blockquote> -<p>For additional information on The Tuxedo System, see -<p><blockquote><i>The Tuxedo System</i>, -by Andrade, Carges, Dwyer and Felts (Addison Wesley Longman).</blockquote> -<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/xa/build.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/xa/xa_config.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> |
