diff options
Diffstat (limited to 'bdb/docs/api_tcl/db_open.html')
| -rw-r--r-- | bdb/docs/api_tcl/db_open.html | 300 |
1 files changed, 0 insertions, 300 deletions
diff --git a/bdb/docs/api_tcl/db_open.html b/bdb/docs/api_tcl/db_open.html deleted file mode 100644 index 4f7b651e552..00000000000 --- a/bdb/docs/api_tcl/db_open.html +++ /dev/null @@ -1,300 +0,0 @@ -<!--$Id: db_open.so,v 11.18 2000/11/27 18:14:47 sue Exp $--> -<!--$Id: m4.tcl,v 11.17 2000/04/24 17:31:11 sue Exp $--> -<!--Copyright 1997, 1998, 1999, 2000 by Sleepycat Software, Inc.--> -<!--All rights reserved.--> -<html> -<head> -<title>Berkeley DB: berkdb 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><tr valign=top> -<td> -<h1><b>berkdb open</b></h1> -</td> -<td width="1%"> -<a href="../api_tcl/tcl_index.html"><img src="../images/api.gif" alt="API"></a><a href="../ref/toc.html"><img src="../images/ref.gif" alt="Ref"></a> -</td></tr></table> -<hr size=1 noshade> -<tt> -<h3><pre>berkdb open - [-btree | -hash | -recno | -queue | -unknown] - [-cachesize {gbytes bytes ncache}] - [-create] - [-delim delim] - [-dup] - [-dupsort] - [-env env] - [-errfile filename] - [-excl] - [-extent size] - [-ffactor density] - [-len len] - [-mode mode] - [-nelem size] - [-pad pad] - [-pagesize pagesize] - [-rdonly] - [-recnum] - [-renumber] - [-snapshot] - [-source file] - [-truncate] - [-upgrade] - [--] - [file [database]] -</pre></h3> -<h1>Description</h1> -<p>The <b>berkdb open</b> command opens, and optionally creates, a database. -The returned database handle is bound to a Tcl command of the form -<b>dbN</b>, where N is an integer starting at 0 (e.g., db0 and db1). -It is through this Tcl command that the script accesses the database -methods. -<p>The options are as follows: -<p><dl compact> -<p><dt>-btree<dd>Open/create a database of type Btree. The Btree format -is a representation of a sorted, balanced tree structure. -<p><dt>-hash<dd>Open/create a database of type Hash. The Hash format is -an extensible, dynamic hashing scheme. -<p><dt>-queue<dd>Open/create a database of type Queue. The Queue format -supports fast access to fixed-length records accessed by sequentially or -logical record number. -<p><dt>-recno<dd>Open/create a database of type Recno. The Recno format -supports fixed- or variable-length records, accessed sequentially or by -logical record number, and optionally retrieved from a flat text file. -<p><dt>-unknown<dd>The database is of an unknown type, and must already exist. -<p><dt>-cachesize {gbytes bytes ncache}<dd>Set the size of the database's shared memory buffer pool, i.e., the cache, -to <b>gbytes</b> gigabytes plus <b>bytes</b>. The cache should be the -size of the normal working data set of the application, with some small -amount of additional memory for unusual situations. (Note, the working -set is not the same as the number of simultaneously referenced pages, and -should be quite a bit larger!) -<p>The default cache size is 256KB, and may not be specified as less than -20KB. Any cache size less than 500MB is automatically increased by 25% -to account for buffer pool overhead, cache sizes larger than 500MB are -used as specified. -<p>It is possible to specify caches to Berkeley DB that are large enough so that -they cannot be allocated contiguously on some architectures, e.g., some -releases of Solaris limit the amount of memory that may be allocated -contiguously by a process. If <b>ncache</b> is 0 or 1, the cache will -be allocated contiguously in memory. If it is greater than 1, the cache -will be broken up into <b>ncache</b> equally sized separate pieces of -memory. -<p>For information on tuning the Berkeley DB cache size, see -<a href="../ref/am_conf/cachesize.html">Selecting a cache size</a>. -<p>As databases opened within Berkeley DB environments use the cache specified to -the environment, it is an error to attempt to set a cache in a database -created within an environment. -<p><dt>-create<dd>Create any underlying files, as necessary. If the files do not already -exist and the <b>-create</b> argument is not specified, the call will -fail. -<p><dt>-delim delim<dd>Set the delimiting byte used to mark the end of a record in the backing -source file for the Recno access method. -<p>This byte is used for variable length records, if the <b>-source</b> -argument file is specified. If the <b>-source</b> argument file is -specified and no delimiting byte was specified, <newline> -characters (i.e. ASCII 0x0a) are interpreted as end-of-record markers. -<p><dt>-dup<dd>Permit duplicate data items in the tree, i.e. insertion when the key of the -key/data pair being inserted already exists in the tree will be successful. -The ordering of duplicates in the tree is determined by the order of -insertion, unless the ordering is otherwise specified by use of a cursor or -a duplicate comparison function. -<p>It is an error to specify both <b>-dup</b> and <b>-recnum</b>. -<p><dt>-dupsort<dd>Sort duplicates within a set of data items. A default, lexical comparison -will be used. Specifying that duplicates are to be sorted changes the -behavior of the <i>db</i> <b>put</b> operation as well as the <i>dbc</i> <b>put</b> -operation when the <b>-keyfirst</b>, <b>-keylast</b> and -<b>-current</b> options are specified. -<p><dt>-env env<dd>If no <b>-env</b> argument is given, the database is standalone, i.e., -it is not part of any Berkeley DB environment. -<p>If a <b>-env</b> argument is given, the database is created within the -specified Berkeley DB environment. The database access methods automatically -make calls to the other subsystems in Berkeley DB based on the enclosing -environment. For example, if the environment has been configured to use -locking, then the access methods will automatically acquire the correct -locks when reading and writing pages of the database. -<p><dt>-errfile filename<dd> -<p>When an error occurs in the Berkeley DB library, a Berkeley DB error or an error -return value is returned by the function. In some cases, however, the -errno value may be insufficient to completely describe the cause of the -error especially during initial application debugging. -<p>The <b>-errfile</b> argument is used to enhance the mechanism for -reporting error messages to the application by specifying a file to be -used for displaying additional Berkeley DB error messages. In some cases, when -an error occurs, Berkeley DB will output an additional error message to the -specified file reference. -<p>The error message will consist of a Tcl command name and a colon (":"), -an error string, and a trailing <newline> character. If the -database was opened in an environment the Tcl command name will be the -environment name (e.g., env0), otherwise it will be the database command -name (e.g., db0). -<p>This error logging enhancement does not slow performance or significantly -increase application size, and may be run during normal operation as well -as during application debugging. -<p>For database handles opened inside of Berkeley DB environments, specifying the -<b>-errfile</b> argument affects the entire environment and is equivalent -to specifying the same argument to the <b>berkdb env</b> command. -<p><dt>-excl<dd>Return an error if the file already exists. Underlying filesystem -primitives are used to implement this flag. For this reason it is only -applicable to the physical database file and cannot be used to test if a -database in a file already exists. -<p><dt>-extent size<dd>Set the size of the extents of the Queue database, The size is specified -as the number of pages in an extent. -Each extent is created as a separate physical file. If no extent size -is set, the default behavior is to create only -a single underlying database file. -<p>For information on tuning the extent size, see -<a href="../ref/am_conf/extentsize.html">Selecting a extent size</a>. -<p><dt>-ffactor density<dd>Set the desired density within the hash table. -<p>The density is an approximation of the number of keys allowed to -accumulate in any one bucket -<p><dt>-len len<dd>For the Queue access method, specify that the records are of length -<b>len</b>. -<p>For the Recno access method, specify that the records are fixed-length, -not byte delimited, and are of length <b>len</b>. -<p>Any records added to the database that are less than <b>len</b> bytes -long are automatically padded (see the <b>-pad</b> argument for more -information). -<p>Any attempt to insert records into the database that are greater than -<b>len</b> bytes long will cause the call to fail immediately and return -an error. -<p><dt>-mode mode<dd> -<p>On UNIX systems, or in IEEE/ANSI Std 1003.1 (POSIX) environments, all files created by the access methods -are created with mode <b>mode</b> (as described in <b>chmod</b>(2)) and -modified by the process' umask value at the time of creation (see -<b>umask</b>(2)). The group ownership of created files is based on -the system and directory defaults, and is not further specified by Berkeley DB. -If <b>mode</b> is 0, files are created readable and writeable by both -owner and group. On Windows systems, the mode argument is ignored. -<p><dt>-nelem size<dd>Set an estimate of the final size of the hash table. -<p>If not set or set too low, hash tables will still expand gracefully as -keys are entered, although a slight performance degradation may be -noticed. -<p><dt>-pad pad<dd>Set the padding character for short, fixed-length records for the Queue -and Recno access methods. -<p>If no pad character is specified, <space> characters (i.e., -ASCII 0x20) are used for padding. -<p><dt>-pagesize pagesize<dd>Set the size of the pages used to hold items in the database, in bytes. -The minimum page size is 512 bytes and the maximum page size is 64K bytes. -If the page size is not explicitly set, one is selected based on the -underlying filesystem I/O block size. The automatically selected size -has a lower limit of 512 bytes and an upper limit of 16K bytes. -<p>For information on tuning the Berkeley DB page size, see -<a href="../ref/am_conf/pagesize.html">Selecting a page size</a>. -<p><dt>-rdonly<dd>Open the database for reading only. Any attempt to modify items in the -database will fail regardless of the actual permissions of any underlying -files. -<p><dt>-recnum<dd>Support retrieval from the Btree using record numbers. -<p>Logical record numbers in Btree databases are mutable in the face of -record insertion or deletion. See the <b>-renumber</b> argument for -further discussion. -<p>Maintaining record counts within a Btree introduces a serious point of -contention, namely the page locations where the record counts are stored. In -addition, the entire tree must be locked during both insertions and -deletions, effectively single-threading the tree for those operations. -Specifying <b>-recnum</b> can result in serious performance degradation -for some applications and data sets. -<p>It is an error to specify both <b>-dup</b> and <b>-recnum</b>. -<p><dt>-renumber<dd>Specifying the <b>-renumber</b> argument causes the logical record -numbers to be mutable, and change as records are added to and deleted from -the database. For example, the deletion of record number 4 causes records -numbered 5 and greater to be renumbered downward by 1. If a cursor was -positioned to record number 4 before the deletion, it will reference the -new record number 4, if any such record exists, after the deletion. If a -cursor was positioned after record number 4 before the deletion, it will -be shifted downward 1 logical record, continuing to reference the same -record as it did before. -<p>Using the <i>db</i> <b>put</b> or <i>dbc</i> <b>put</b> interfaces to create new records will -cause the creation of multiple records if the record number is more than one -greater than the largest record currently in the database. For example, -creating record 28, when record 25 was previously the last record in the -database, will create records 26 and 27 as well as 28. -<p>If a created record is not at the end of the database, all records following -the new record will be automatically renumbered upward by 1. For example, -the creation of a new record numbered 8 causes records numbered 8 and -greater to be renumbered upward by 1. If a cursor was positioned to record -number 8 or greater before the insertion, it will be shifted upward 1 -logical record, continuing to reference the same record as it did before. -<p>For these reasons, concurrent access to a Recno database with the -<b>-renumber</b> flag specified may be largely meaningless, although it -is supported. -<p><dt>-snapshot<dd>This argument specifies that any specified <b>-source</b> file be read -in its entirety when the database is opened. If this argument is not -specified, the <b>-source</b> file may be read lazily. -<p><dt>-source file<dd>Set the underlying source file for the Recno access method. The purpose -of the <b>-source</b> file is to provide fast access and modification -to databases that are normally stored as flat text files. -<p>If the <b>-source</b> argument is give, it specifies an underlying flat -text database file that is read to initialize a transient record number -index. In the case of variable length records, the records are separated -as specified by <b>-delim</b>. For example, standard UNIX byte stream -files can be interpreted as a sequence of variable length records -separated by <newline> characters. -<p>In addition, when cached data would normally be written back to the -underlying database file (e.g., the <i>db</i> <b>close</b> or <i>db</i> <b>sync</b> -commands are called), the in-memory copy of the database will be written -back to the <b>-source</b> file. -<p>By default, the backing source file is read lazily, i.e., records are not -read from the file until they are requested by the application. -<b>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 argument as part of the <b>berkdb open</b> call. See the <b>-snapshot</b> -argument for more information.</b> -<p><b>Reading and writing the backing source file specified by <b>-source</b> -cannot be transactionally protected because it involves filesystem -operations that are not part of the Berkeley DB transaction methodology.</b> -For this reason, if a temporary database is used to hold the records, -i.e., no <b>file</b> argument was specified to the <b>berkdb open</b> call, -it is possible to lose the contents of the <b>-file</b> file, e.g., if -the system crashes at the right instant. If a file is used to hold the -database, i.e., a file name was specified as the <b>file</b> argument -to <b>berkdb open</b>, normal database recovery on that file can be used to -prevent information loss, although it is still possible that the contents -of <b>-source</b> will be lost if the system crashes. -<p>The <b>-source</b> file must already exist (but may be zero-length) when -<b>berkdb open</b> is called. -<p>It is not an error to specify a read-only <b>-source</b> file when -creating a database, nor is it an error to modify the resulting database. -However, any attempt to write the changes to the backing source file using -either the <i>db</i> <b>close</b> or <i>db</i> <b>sync</b> commands will fail, of course. -Specify the <b>-nosync</b> argument to the <i>db</i> <b>close</b> command will -stop it from attempting to write the changes to the backing file, instead, -they will be silently discarded. -<p>For all of the above reasons, the <b>-source</b> 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, e.g., a text editor. -<p><dt>-truncate<dd>Physically truncate the underlying file, discarding all previous databases -it might have held. 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 databases within a file. -<p>The <b>-truncate</b> argument cannot be transaction protected, and it is -an error to specify it in a transaction protected environment. -<p><dt>-upgrade<dd>Upgrade the database represented by <b>file</b>, if necessary. -<p><b>Note: Database upgrades are done in place and are -destructive, e.g., if pages need to be allocated and no disk space is -available, the database may be left corrupted. Backups should be made -before databases are upgraded. See <a href="../ref/am/upgrade.html">Upgrading databases</a> for more information.</b> -<p><dt>--<dd>Mark the end of the command arguments. -<p><dt>file<dd>The name of a single physical file on disk that will be used to back the -database. -<p><dt>database<dd>The <b>database</b> argument allows applications to have multiple -databases inside of 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. It is an error to attempt -to open a second database file that was not initially created using a -<b>database</b> name. -</dl> -<p>The <b>berkdb open</b> command returns a database handle on success. -<p>In the case of error, a Tcl error is thrown. -</tt> -<table><tr><td><br></td><td width="1%"> -<a href="../api_tcl/tcl_index.html"><img src="../images/api.gif" alt="API"></a><a href="../ref/toc.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> |