1<!--$Id: db_open.so,v 11.34 2004/12/16 19:13:04 bostic Exp $--> 2<!--$Id: m4.tcl,v 11.28 2004/12/16 19:13:05 bostic Exp $--> 3<!--Copyright (c) 1997,2008 Oracle. All rights reserved.--> 4<!--See the file LICENSE for redistribution information.--> 5<html> 6<head> 7<title>Berkeley DB: berkdb open</title> 8<meta name="description" content="Berkeley DB: An embedded database programmatic toolkit."> 9<meta name="keywords" content="embedded,database,programmatic,toolkit,btree,hash,hashing,transaction,transactions,locking,logging,access method,access methods,Java,C,C++"> 10</head> 11<body bgcolor=white> 12<table width="100%"><tr valign=top> 13<td> 14<b><b>berkdb open</b></b> 15</td> 16<td align=right> 17<a href="../api_tcl/api_tcl.html"><img src="../images/api.gif" alt="API"></a> 18<a href="../ref/toc.html"><img src="../images/ref.gif" alt="Ref"></a></td> 19</tr></table> 20<hr size=1 noshade> 21<tt> 22<b><pre>berkdb open 23 [-auto_commit] 24 [-btree | -hash | -recno | -queue | -unknown] 25 [-cachesize {gbytes bytes ncache}] 26 [-create] 27 [-delim delim] 28 [-dup] 29 [-dupsort] 30 [-encrypt] 31 [-encryptaes passwd] 32 [-encryptany passwd] 33 [-env env] 34 [-errfile filename] 35 [-excl] 36 [-extent size] 37 [-ffactor density] 38 [-len len] 39 [-mode mode] 40 [-nelem size] 41 [-pad pad] 42 [-pagesize pagesize] 43 [-rdonly] 44 [-recnum] 45 [-renumber] 46 [-snapshot] 47 [-source file] 48 [-truncate] 49 [-txn txnid] 50 [--] 51 [file [database]] 52</pre></b> 53<b>Description(berkdb open)</b> 54<p>The <b>berkdb open</b> command opens and optionally creates a database. 55The returned database handle is bound to a Tcl command of the form 56<b>dbN</b>, where N is an integer starting at 0 (for example, db0 and 57db1). It is through this Tcl command that the script accesses the 58database methods.</p> 59<p>The options are as follows:</p> 60<br> 61<b>-auto_commit</b><ul compact><li>Enclose the call within a transaction. If the call succeeds, the open 62operation will be recoverable and all subsequent database modification 63operations based on this handle will be transactionally protected. If 64the call fails, no database will have been created.</ul> 65<b>-btree</b><ul compact><li>Open/create a database of type Btree. The Btree format 66is a representation of a sorted, balanced tree structure.</ul> 67<b>-hash</b><ul compact><li>Open/create a database of type Hash. The Hash format is 68an extensible, dynamic hashing scheme.</ul> 69<b>-queue</b><ul compact><li>Open/create a database of type Queue. The Queue format 70supports fast access to fixed-length records accessed by sequentially or 71logical record number.</ul> 72<b>-recno</b><ul compact><li>Open/create a database of type Recno. The Recno format 73supports fixed- or variable-length records, accessed sequentially or by 74logical record number, and optionally retrieved from a flat text file.</ul> 75<b>-unknown</b><ul compact><li>The database is of an unknown type, and must already exist.</ul> 76<b>-cachesize {gbytes bytes ncache}</b><ul compact><li>Set the size of the database's shared memory buffer pool (that is, the 77cache), to <b>gbytes</b> gigabytes plus <b>bytes</b>. The cache 78should be the size of the normal working data set of the application, 79with some small amount of additional memory for unusual situations. 80(Note: The working set is not the same as the number of simultaneously 81referenced pages, and should be quite a bit larger!) 82<p>The default cache size is 256KB, and may not be specified as less than 8320KB. Any cache size less than 500MB is automatically increased by 25% 84to account for buffer pool overhead; cache sizes larger than 500MB are 85used as specified.</p> 86<p>It is possible to specify caches to Berkeley DB that are large enough so that 87they cannot be allocated contiguously on some architectures; for example, 88some releases of Solaris limit the amount of memory that may be 89allocated contiguously by a process. If <b>ncache</b> is 0 or 1, the 90cache will be allocated contiguously in memory. If it is greater than 911, the cache will be broken up into <b>ncache</b> equally sized 92separate pieces of memory.</p> 93<p>For information on tuning the Berkeley DB cache size, see 94<a href="../ref/am_conf/cachesize.html">Selecting a cache size</a>.</p> 95<p>Because databases opened within Berkeley DB environments use the cache 96specified to the environment, it is an error to attempt to set a cache 97in a database created within an environment.</p></ul> 98<b>-create</b><ul compact><li>Create any underlying files, as necessary. If the files do not already 99exist and the <b>-create</b> argument is not specified, the call will 100fail.</ul> 101<b>-delim delim</b><ul compact><li>Set the delimiting byte used to mark the end of a record in the backing 102source file for the Recno access method. 103<p>This byte is used for variable length records if the <b>-source</b> 104argument file is specified. If the <b>-source</b> argument file is 105specified and no delimiting byte was specified, <newline> 106characters (that is, ASCII 0x0a) are interpreted as end-of-record 107markers.</p></ul> 108<b>-dup</b><ul compact><li>Permit duplicate data items in the tree, that is, insertion when the 109key of the key/data pair being inserted already exists in the tree will 110be successful. The ordering of duplicates in the tree is determined by 111the order of insertion unless the ordering is otherwise specified by 112use of a cursor or a duplicate comparison function. <p>error to specify both <b>-dup</b> and <b>-recnum</b>.</p></ul> 113<b>-dupsort</b><ul compact><li>Sort duplicates within a set of data items. A default lexical 114comparison will be used. Specifying that duplicates are to be sorted 115changes the behavior of the <i>db</i> <b>put</b> operation as well as the 116<i>dbc</i> <b>put</b> operation when the <b>-keyfirst</b>, <b>-keylast</b> 117and <b>-current</b> options are specified.</ul> 118<b>-encrypt</b><ul compact><li>Specify the database in an environment should be encrypted with the 119same password that is being used in the environment.</ul> 120<b>-encryptaes passwd</b><ul compact><li>Specify the database should be encrypted with the given password 121using the Rijndael/AES (also known as the Advanced Encryption Standard 122and Federal Information Processing Standard (FIPS) 197) algorithm.</ul> 123<b>-encryptany passwd</b><ul compact><li>Specify the already existing database should be opened 124with the given password. This option is used if the database is 125known to be encrypted, but the specific algorithm used is not known.</ul> 126<b>-env env</b><ul compact><li>If no <b>-env</b> argument is given, the database is standalone; that 127is, it is not part of any Berkeley DB environment. 128<p>If a <b>-env</b> argument is given, the database is created within the 129specified Berkeley DB environment. The database access methods automatically 130make calls to the other subsystems in Berkeley DB, based on the enclosing 131environment. For example, if the environment has been configured to use 132locking, the access methods will automatically acquire the correct locks 133when reading and writing pages of the database.</p></ul> 134<b>-errfile filename</b><ul compact><li><p>When an error occurs in the Berkeley DB library, a Berkeley DB error or an error 135return value is returned by the function. In some cases, however, the 136errno value may be insufficient to completely describe the cause of the 137error especially during initial application debugging.</p> 138<p>The <b>-errfile</b> argument is used to enhance the mechanism for 139reporting error messages to the application by specifying a file to be 140used for displaying additional Berkeley DB error messages. In some cases, when 141an error occurs, Berkeley DB will output an additional error message to the 142specified file reference.</p> 143<p>The error message will consist of a Tcl command name and a colon (":"), 144an error string, and a trailing <newline> character. If 145the database was opened in an environment, the Tcl command name will be 146the environment name (for example, env0), otherwise it will be the 147database command name (for example, db0).</p> 148<p>This error-logging enhancement does not slow performance or significantly 149increase application size, and may be run during normal operation as well 150as during application debugging.</p> 151<p>For database handles opened inside of Berkeley DB environments, specifying the 152<b>-errfile</b> argument affects the entire environment and is equivalent 153to specifying the same argument to the <b>berkdb env</b> command.</p></ul> 154<b>-excl</b><ul compact><li>Return an error if the database already exists.</ul> 155<b>-extent size</b><ul compact><li>Set the size of the extents of the Queue database; the size is specified 156as the number of pages in an extent. Each extent is created as a 157separate physical file. If no extent size is set, the default behavior 158is to create only a single underlying database file.</ul> 159<p>For information on tuning the extent size, see 160<a href="../ref/am_conf/extentsize.html">Selecting a extent size</a>.</p> 161<b>-ffactor density</b><ul compact><li>Set the desired density within the hash table. 162<p>The density is an approximation of the number of keys allowed to 163accumulate in any one bucket</ul> 164<b>-len len</b><ul compact><li>For the Queue access method, specify that the records are of length 165<b>len</b>. 166<p>For the Recno access method, specify that the records are fixed-length, 167not byte-delimited, and are of length <b>len</b>.</p> 168<p>Any records added to the database that are less than <b>len</b> bytes 169long are automatically padded (see the <b>-pad</b> argument for more 170information).</p> 171<p>Any attempt to insert records into the database that are greater than 172<b>len</b> bytes long will cause the call to fail immediately and return 173an error.</p></ul> 174<b>-mode mode</b><ul compact><li><p>On UNIX systems, or in IEEE/ANSI Std 1003.1 (POSIX) environments, all files created by the access methods 175are created with mode <b>mode</b> (as described in <b>chmod</b>(2)) and 176modified by the process' umask value at the time of creation (see 177<b>umask</b>(2)). The group ownership of created files is based on 178the system and directory defaults, and is not further specified by Berkeley DB. 179If <b>mode</b> is 0, files are created readable and writable by both 180owner and group. On Windows systems, the mode argument is ignored.</p></ul> 181<b>-nelem size</b><ul compact><li>Set an estimate of the final size of the hash table. 182<p>If not set or set too low, hash tables will still expand gracefully as 183keys are entered, although a slight performance degradation may be 184noticed.</p></ul> 185<b>-pad pad</b><ul compact><li>Set the padding character for short, fixed-length records for the Queue 186and Recno access methods. 187<p>If no pad character is specified, <space> characters (that is, 188ASCII 0x20) are used for padding.</p></ul> 189<b>-pagesize pagesize</b><ul compact><li>Set the size of the pages used to hold items in the database, in bytes. 190The minimum page size is 512 bytes, and the maximum page size is 64K 191bytes. If the page size is not explicitly set, one is selected based 192on the underlying filesystem I/O block size. The automatically selected 193size has a lower limit of 512 bytes and an upper limit of 16K bytes. 194<p>For information on tuning the Berkeley DB page size, see 195<a href="../ref/am_conf/pagesize.html">Selecting a page size</a>.</p></ul> 196<b>-rdonly</b><ul compact><li>Open the database for reading only. Any attempt to modify items in the 197database will fail, regardless of the actual permissions of any 198underlying files.</ul> 199<b>-recnum</b><ul compact><li>Support retrieval from the Btree using record numbers. 200<p>Logical record numbers in Btree databases are mutable in the face of 201record insertion or deletion. See the <b>-renumber</b> argument for 202further discussion.</p> 203<p>Maintaining record counts within a Btree introduces a serious point of 204contention, namely the page locations where the record counts are stored. In 205addition, the entire tree must be locked during both insertions and 206deletions, effectively single-threading the tree for those operations. 207Specifying <b>-recnum</b> can result in serious performance degradation 208for some applications and data sets.</p> 209<p>It is an error to specify both <b>-dup</b> and <b>-recnum</b>.</p></ul> 210<b>-renumber</b><ul compact><li>Specifying the <b>-renumber</b> argument causes the logical record 211numbers to be mutable, and change as records are added to and deleted from 212the database. For example, the deletion of record number 4 causes records 213numbered 5 and greater to be renumbered downward by one. If a cursor was 214positioned to record number 4 before the deletion, it will refer to the 215new record number 4, if any such record exists, after the deletion. If a 216cursor was positioned after record number 4 before the deletion, it will 217be shifted downward one logical record, continuing to refer to the same 218record as it did before. 219<p>Using the <i>db</i> <b>put</b> or <i>dbc</i> <b>put</b> interfaces to create new records will 220cause the creation of multiple records if the record number is more than one 221greater than the largest record currently in the database. For example, 222creating record 28 when record 25 was previously the last record in the 223database, will create records 26 and 27 as well as 28.</p> 224<p>If a created record is not at the end of the database, all records following 225the new record will be automatically renumbered upward by one. For example, 226the creation of a new record numbered 8 causes records numbered 8 and 227greater to be renumbered upward by one. If a cursor was positioned to record 228number 8 or greater before the insertion, it will be shifted upward one 229logical record, continuing to refer to the same record as it did before.</p> 230<p>For these reasons, concurrent access to a Recno database with the 231<b>-renumber</b> flag specified may be largely meaningless, although it 232is supported.</p></ul> 233<b>-snapshot</b><ul compact><li>This argument specifies that any specified <b>-source</b> file be read 234in its entirety when the database is opened. If this argument is not 235specified, the <b>-source</b> file may be read lazily.</ul> 236<b>-source file</b><ul compact><li>Set the underlying source file for the Recno access method. The purpose 237of the <b>-source</b> file is to provide fast access and modification 238to databases that are normally stored as flat text files. 239<p>If the <b>-source</b> argument is give, it specifies an underlying flat 240text database file that is read to initialize a transient record number 241index. In the case of variable length records, the records are separated 242as specified by <b>-delim</b>. For example, standard UNIX byte stream 243files can be interpreted as a sequence of variable length records 244separated by <newline> characters.</p> 245<p>In addition, when cached data would normally be written back to the 246underlying database file (for example, when the <i>db</i> <b>close</b> or 247<i>db</i> <b>sync</b> commands are called), the in-memory copy of the database 248will be written back to the <b>-source</b> file.</p> 249<p>By default, the backing source file is read lazily, that is, records 250are not read from the file until they are requested by the application. 251<b>If multiple processes (not threads) are accessing a Recno database 252concurrently and either inserting or deleting records, the backing source 253file must be read in its entirety before more than a single process 254accesses the database, and only that process should specify the backing 255source argument as part of the <b>berkdb open</b> call. See the <b>-snapshot</b> 256argument for more information.</b></p> 257<p><b>Reading and writing the backing source file specified by <b>-source</b> 258cannot be transaction protected because it involves filesystem 259operations that are not part of the Berkeley DB transaction methodology.</b> 260For this reason, if a temporary database is used to hold the records, 261it is possible to lose the contents of the <b>-file</b> file, for 262example, if the system crashes at the right instant. If a file is used 263to hold the database, that is, a filename was specified as the 264<b>file</b> argument to <b>berkdb open</b>, normal database recovery on 265that file can be used to prevent information loss, although it is still 266possible that the contents of <b>-source</b> will be lost if the system 267crashes.</p> 268<p>The <b>-source</b> file must already exist (but may be zero-length) when 269<b>berkdb open</b> is called.</p> 270<p>It is not an error to specify a read-only <b>-source</b> file when 271creating a database, nor is it an error to modify the resulting database. 272However, any attempt to write the changes to the backing source file using 273either the <i>db</i> <b>close</b> or <i>db</i> <b>sync</b> commands will fail, of course. 274Specify the <b>-nosync</b> argument to the <i>db</i> <b>close</b> command will 275stop it from attempting to write the changes to the backing file; instead, 276they will be silently discarded.</p> 277<p>For all of the previous reasons, the <b>-source</b> file is generally 278used to specify databases that are read-only for Berkeley DB applications, 279and that are either generated on the fly by software tools, or modified 280using a different mechanism such as a text editor.</p></ul> 281<b>-truncate</b><ul compact><li>Physically truncate the underlying file, discarding all previous databases 282it might have held. Underlying filesystem primitives are used to 283implement this flag. For this reason, it is only applicable to the 284physical file and cannot be used to discard databases within a file. 285<p>The <b>-truncate</b> argument cannot be transaction-protected, and it is 286an error to specify it in a transaction-protected environment.</p></ul> 287<b>-txn txnid</b><ul compact><li>If the operation is part of an application-specified transaction, the 288<b>txnid</b> parameter is a transaction handle returned from 289<i>env</i> <b>txn</b>. If no transaction handle is specified, but the 290-auto_commit flag is specified, 291the operation will be implicitly transaction protected.</ul> 292<b>--</b><ul compact><li>Mark the end of the command arguments.</ul> 293<b>file</b><ul compact><li>The name of a single physical file on disk that will be used to back the 294database.</ul> 295<b>database</b><ul compact><li>The <b>database</b> argument allows applications to have multiple 296databases inside of a single physical file. This is useful when the 297databases are both numerous and reasonably small, in order to avoid 298creating a large number of underlying files. It is an error to attempt 299to open a second database file that was not initially created using a 300<b>database</b> name. 301<p>Applications opening multiple databases in a single file will almost 302certainly need to create a shared database environment. See 303<a href="../ref/am/opensub.html">Opening multiple databases in a single 304file</a> for more information.</p></ul> 305<br> 306<p>The <b>berkdb open</b> command returns a database handle on success.</p> 307<p>In the case of error, a Tcl error is thrown.</p> 308</tt> 309<table width="100%"><tr><td><br></td><td align=right> 310<a href="../api_tcl/api_tcl.html"><img src="../images/api.gif" alt="API"></a><a href="../ref/toc.html"><img src="../images/ref.gif" alt="Ref"></a> 311</td></tr></table> 312<p><font size=1>Copyright (c) 1996,2008 Oracle. All rights reserved.</font> 313</body> 314</html> 315