<!--$Id: db_open.html,v 1.1.1.1 2003/02/15 04:55:50 zarzycki Exp $--> <!--$Id: db_open.html,v 1.1.1.1 2003/02/15 04:55:50 zarzycki Exp $--> <!--Copyright 1997-2002 by Sleepycat Software, Inc.--> <!--All rights reserved.--> <!--See the file LICENSE for redistribution information.--> <html> <head> <title>Berkeley DB: Db.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> <h1>Db.open</h1> </td> <td align=right> <a href="../api_java/c_index.html"><img src="../images/api.gif" alt="API"></a><a href="../reftoc.html"><img src="../images/ref.gif" alt="Ref"></a> </td></tr></table> <hr size=1 noshade> <tt> <h3><pre> import com.sleepycat.db.*; import java.io.FileNotFoundException; <p> public void open(DbTxn txnid, String file, String database, int type, int flags, int mode) throws DbException, FileNotFoundException; </pre></h3> <h1>Description</h1> <p>The currently supported Berkeley DB file formats (or <i>access methods</i>) are Btree, Hash, Queue, and Recno. The Btree format is a representation of a sorted, balanced tree structure. The Hash format is an extensible, dynamic hashing scheme. The Queue format supports fast access to fixed-length records accessed sequentially or by logical record number. The Recno format supports fixed- or variable-length records, accessed sequentially or by logical record number, and optionally backed by a flat text file. <p>Storage and retrieval for the Berkeley DB access methods are based on key/data pairs; see <a href="../api_java/dbt_class.html">Dbt</a> for more information. <p>The Db.open interface opens the database represented by the <b>file</b> and <b>database</b> arguments for both reading and writing. The <b>file</b> argument is used as the name of an underlying file that will be used to back the database. The <b>database</b> argument is optional, and allows applications to have multiple databases in a single file. Although no <b>database</b> argument needs to be specified, it is an error to attempt to open a second database in a <b>file</b> that was not initially created using a <b>database</b> name. Further, the <b>database</b> argument is not supported by the Queue format. Finally, when opening multiple databases in the same physical file, it is important to consider locking and memory cache issues; see <a href="../ref/am/opensub.html">Opening multiple databases in a single file</a> for more information. <p>In-memory databases never intended to be preserved on disk may be created by setting both the <b>file</b> and <b>database</b> arguments to null. Note that in-memory databases can only ever be shared by sharing the single database handle that created them, in circumstances where doing so is safe. <p>The <b>type</b> argument is of type int, and must be set to one of <a name="Db.DB_BTREE">Db.DB_BTREE</a>, <a name="Db.DB_HASH">Db.DB_HASH</a>, <a name="Db.DB_QUEUE">Db.DB_QUEUE</a>, <a name="Db.DB_RECNO">Db.DB_RECNO</a>, or <a name="Db.DB_UNKNOWN">Db.DB_UNKNOWN</a>. If <b>type</b> is Db.DB_UNKNOWN, the database must already exist and Db.open will automatically determine its type. The <a href="../api_java/db_get_type.html">Db.get_type</a> method may be used to determine the underlying type of databases opened using Db.DB_UNKNOWN. <p>If the operation is to be transaction-protected (other than by specifying the Db.DB_AUTO_COMMIT flag), the <b>txnid</b> parameter is a transaction handle returned from <a href="../api_java/txn_begin.html">DbEnv.txn_begin</a>; otherwise, null. <p>The <b>flags</b> and <b>mode</b> arguments specify how files will be opened and/or created if they do not already exist. <p>The <b>flags</b> value must be set to 0 or by bitwise inclusively <b>OR</b>'ing together one or more of the following values: <p><dl compact> <p><dt><a name="Db.DB_AUTO_COMMIT">Db.DB_AUTO_COMMIT</a><dd>Enclose the Db.open call within a transaction. If the call succeeds, the open operation will be recoverable. If the call fails, no database will have been created. <p><dt><a name="Db.DB_CREATE">Db.DB_CREATE</a><dd>Create the database. If the database does not already exist and the Db.DB_CREATE flag is not specified, the Db.open will fail. <p><dt><a name="Db.DB_DIRTY_READ">Db.DB_DIRTY_READ</a><dd>Support dirty reads; that is, read operations on the database may request the return of modified but not yet committed data. <p><dt><a name="Db.DB_EXCL">Db.DB_EXCL</a><dd>Return an error if the database already exists. The Db.DB_EXCL flag is only meaningful when specified with the Db.DB_CREATE flag. <p><dt><a name="Db.DB_NOMMAP">Db.DB_NOMMAP</a><dd>Do not map this database into process memory (see the description of the <a href="../api_java/env_set_mp_mmapsize.html">DbEnv.set_mp_mmapsize</a> method for further information). <p><dt><a name="Db.DB_RDONLY">Db.DB_RDONLY</a><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><a name="Db.DB_THREAD">Db.DB_THREAD</a><dd>Cause the <a href="../api_java/db_class.html">Db</a> handle returned by Db.open to be <i>free-threaded</i>; that is, usable by multiple threads within a single address space. <p>Threading is always assumed in the Java API, so no special flags are required, and Berkeley DB functions will always behave as if the <a href="../api_java/env_open.html#DB_THREAD">Db.DB_THREAD</a> flag was specified. <p><dt><a name="Db.DB_TRUNCATE">Db.DB_TRUNCATE</a><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 applicable only to the file and cannot be used to discard databases within a file. <p>The Db.DB_TRUNCATE flag cannot be transaction-protected, and it is an error to specify it in a transaction-protected environment. </dl> <p>On UNIX systems or in IEEE/ANSI Std 1003.1 (POSIX) environments, all files created by the database open 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)). If <b>mode</b> is 0, the database open will use a default mode of readable and writable by both owner and group. On Windows systems, the mode argument is ignored. The group ownership of created files is based on the system and directory defaults, and is not further specified by Berkeley DB. <p>Calling Db.open is a reasonably expensive operation, and maintaining a set of open databases will normally be preferable to repeatedly opening and closing the database for each new query. <p>The Db.open method throws an exception that encapsulates a non-zero error value on failure. If Db.open fails, the <a href="../api_java/db_close.html">Db.close</a> method should be called to discard the <a href="../api_java/db_class.html">Db</a> handle. <h1>Environment Variables</h1> <p><dl compact> <p><dt>DB_HOME<dd>If a <b>dbenv</b> argument to <a href="../api_c/db_create.html">db_create</a> was specified, the environment variable <b>DB_HOME</b> may be used as the path of the database environment home. <p>Db.open is affected by any database directory specified using the <a href="../api_java/env_set_data_dir.html">DbEnv.set_data_dir</a> method, or by setting the "set_data_dir" string in the environment's <b>DB_CONFIG</b> file. </dl> <p><dl compact> <p><dt>TMPDIR<dd>If the <b>file</b> and <b>dbenv</b> arguments to Db.open are null, the environment variable <b>TMPDIR</b> may be used as a directory in which to create temporary backing files </dl> <h1>Errors</h1> <p>The Db.open method may fail and throw an exception encapsulating a non-zero error for the following conditions: <p><dl compact> <p><dt><a name="Db.DB_OLD_VERSION">Db.DB_OLD_VERSION</a><dd>The database cannot be opened without being first upgraded. <p><dt>EEXIST<dd>DB_CREATE and DB_EXCL were specified and the database exists. <p><dt>EINVAL<dd>An invalid flag value or parameter was specified. (For example, unknown database type, page size, hash function, pad byte, byte order) or a flag value or parameter that is incompatible with the specified database. <p> The <a href="../api_java/env_open.html#DB_THREAD">Db.DB_THREAD</a> flag was specified and fast mutexes are not available for this architecture. <p>The <a href="../api_java/env_open.html#DB_THREAD">Db.DB_THREAD</a> flag was specified to Db.open, but was not specified to the <a href="../api_java/env_open.html">DbEnv.open</a> call for the environment in which the <a href="../api_java/db_class.html">Db</a> handle was created. <p>A backing flat text file was specified with either the <a href="../api_java/env_open.html#DB_THREAD">Db.DB_THREAD</a> flag or the provided database environment supports transaction processing. <p><dt>ENOENT<dd>A nonexistent <b>re_source</b> file was specified. </dl> <p>The Db.open method may fail and throw an exception for errors specified for other Berkeley DB and C library or system methods. If a catastrophic error has occurred, the Db.open method may fail and throw a <a href="../api_java/runrec_class.html">DbRunRecoveryException</a>, in which case all subsequent Berkeley DB calls will fail in the same way. <h1>Class</h1> <a href="../api_java/db_class.html">Db</a> <h1>See Also</h1> <a href="../api_java/db_list.html">Databases and Related Methods</a> </tt> <table width="100%"><tr><td><br></td><td align=right> <a href="../api_java/c_index.html"><img src="../images/api.gif" alt="API"></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>