1
<!--$Id: db_open.so,v 10.67 2001/06/19 19:49:24 bostic Exp $-->
2
<!--Copyright 1997-2001 by Sleepycat Software, Inc.-->
3
<!--All rights reserved.-->
6
<title>Berkeley DB: Db.open</title>
7
<meta name="description" content="Berkeley DB: An embedded database programmatic toolkit.">
8
<meta name="keywords" content="embedded,database,programmatic,toolkit,b+tree,btree,hash,hashing,transaction,transactions,locking,logging,access method,access methods,java,C,C++">
11
<a name="2"><!--meow--></a>
12
<table width="100%"><tr valign=top>
17
<a href="../api_java/java_index.html"><img src="../images/api.gif" alt="API"></a><a href="../reftoc.html"><img src="../images/ref.gif" alt="Ref"></a>
22
import com.sleepycat.db.*;
23
import java.io.FileNotFoundException;
25
public void open(String file,
26
String database, int type, int flags, int mode)
27
throws DbException, FileNotFoundException;
30
<p>The currently supported Berkeley DB file formats (or <i>access methods</i>)
31
are Btree, Hash, Queue, and Recno. The Btree format is a representation
32
of a sorted, balanced tree structure. The Hash format is an extensible,
33
dynamic hashing scheme. The Queue format supports fast access to
34
fixed-length records accessed sequentially or by logical record number.
35
The Recno format supports fixed- or variable-length records, accessed
36
sequentially or by logical record number, and optionally backed by a
38
<p>Storage and retrieval for the Berkeley DB access methods are based on key/data
39
pairs; see <a href="../api_java/dbt_class.html">Dbt</a> for more information.
40
<p>The Db.open interface opens the database represented by the
41
<b>file</b> and <b>database</b> arguments for both reading and
42
writing. The <b>file</b> argument is used as the name of an underlying
43
file that will be used to back the database. The <b>database</b>
44
argument is optional, and allows applications to have multiple databases
45
in a single file. Although no <b>database</b> argument needs to be
46
specified, it is an error to attempt to open a second database in a
47
<b>file</b> that was not initially created using a <b>database</b>
48
name. Further, the <b>database</b> argument is not supported by the
50
<p>In-memory databases never intended to be preserved on disk may be
51
created by setting both the <b>file</b> and <b>database</b> arguments
52
to null. Note that in-memory databases can only ever be shared by
53
sharing the single database handle that created them, in circumstances
54
where doing so is safe.
55
<p>The <b>type</b> argument is of type int, and must be set to one of Db.DB_BTREE, Db.DB_HASH,
56
Db.DB_QUEUE, Db.DB_RECNO, or Db.DB_UNKNOWN. If
57
<b>type</b> is Db.DB_UNKNOWN, the database must already exist
58
and Db.open will automatically determine its type. The
59
<a href="../api_java/db_get_type.html">Db.get_type</a> method may be used to determine the underlying type of
60
databases opened using Db.DB_UNKNOWN.
61
<p>The <b>flags</b> and <b>mode</b> arguments specify how files will be opened
62
and/or created if they do not already exist.
63
<p>The <b>flags</b> value must be set to 0 or by bitwise inclusively <b>OR</b>'ing together one or
64
more of the following values:
66
<p><dt><a name="Db.DB_CREATE">Db.DB_CREATE</a><dd>Create any underlying files, as necessary. If the files do not already
67
exist and the DB_CREATE flag is not specified, the call will fail.
68
<p><dt><a name="Db.DB_DIRTY_READ">Db.DB_DIRTY_READ</a><dd>Support dirty reads; that is, transactions, cursors and read operations
69
in the database may request the return of modified but not yet committed
71
<p><dt><a name="Db.DB_EXCL">Db.DB_EXCL</a><dd>Return an error if the file already exists. Underlying filesystem
72
primitives are used to implement this flag. For this reason, it is only
73
applicable to the file and cannot be used to test whether a database in a
75
<p>The Db.DB_EXCL flag is only meaningful when specified with the
77
<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
78
<a href="../api_java/env_set_mp_mmapsize.html">DbEnv.set_mp_mmapsize</a> method for further information).
79
<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
80
database will fail, regardless of the actual permissions of any underlying
82
<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
83
<i>free-threaded</i>; that is, usable by multiple threads within a
85
<p>Threading is always assumed in the Java API, so no special flags are
86
required, and Berkeley DB functions will always behave as if the
87
<a href="../api_java/env_open.html#DB_THREAD">Db.DB_THREAD</a> flag was specified.
88
<p><dt><a name="Db.DB_TRUNCATE">Db.DB_TRUNCATE</a><dd>Physically truncate the underlying file, discarding all previous
89
databases it might have held. Underlying filesystem primitives are used
90
to implement this flag. For this reason, it is applicable only to the
91
file and cannot be used to discard databases within a file.
92
<p>The Db.DB_TRUNCATE flag cannot be transaction-protected, and it is
93
an error to specify it in a transaction-protected environment.
95
<p>On UNIX systems or in IEEE/ANSI Std 1003.1 (POSIX) environments, all files created by
96
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
97
(see <b>umask</b>(2)). If <b>mode</b> is 0, the access methods will use a default
98
mode of readable and writable by both owner and group. On Windows
99
systems, the mode argument is ignored. The group ownership of created
100
files is based on the system and directory defaults, and is not further
101
specified by Berkeley DB.
102
<p>Calling Db.open is a reasonably expensive operation, and
103
maintaining a set of open databases will normally be preferable to
104
repeatedly opening and closing the database for each new query.
105
<p>The Db.open method throws an exception that encapsulates a non-zero error value on
107
<h1>Environment Variables</h1>
109
<p><dt>DB_HOME<dd>If the <b>dbenv</b> argument to <a href="../api_c/db_create.html">db_create</a> was initialized using
110
<a href="../api_java/env_open.html">DbEnv.open</a>, the environment variable <b>DB_HOME</b> may be used
111
as the path of the database environment home. Specifically, Db.open
112
is affected by the configuration value DB_DATA_DIR.
115
<p><dt>TMPDIR<dd>If the <b>file</b> and <b>dbenv</b> arguments to Db.open are
116
null, the environment variable <b>TMPDIR</b> may be used as a
117
directory in which to create a temporary backing file.
120
<p>The Db.open method may fail and throw an exception encapsulating a non-zero error for the following conditions:
122
<p><dt><a name="Db.DB_OLD_VERSION">Db.DB_OLD_VERSION</a><dd>The database cannot be opened without being first upgraded.
123
<p><dt>EEXIST<dd>DB_CREATE and DB_EXCL were specified and the file exists.
124
<p><dt>EINVAL<dd>An invalid flag value or parameter was specified (for example, unknown
125
database type, page size, hash function, pad byte, byte order) or a flag
126
value or parameter that is incompatible with the specified database.
128
The <a href="../api_java/env_open.html#DB_THREAD">Db.DB_THREAD</a> flag was specified and fast mutexes are not
129
available for this architecture.
130
<p>The <a href="../api_java/env_open.html#DB_THREAD">Db.DB_THREAD</a> flag was specified to Db.open, but was not
131
specified to the <a href="../api_java/env_open.html">DbEnv.open</a> call for the environment in which the
132
<a href="../api_java/db_class.html">Db</a> handle was created.
133
<p>A backing flat text file was specified with either the <a href="../api_java/env_open.html#DB_THREAD">Db.DB_THREAD</a>
134
flag or the provided database environment supports transaction
136
<p><dt>ENOENT<dd>A nonexistent <b>re_source</b> file was specified.
138
<p>The Db.open method may fail and throw an exception for errors specified for other Berkeley DB and C library or system methods.
139
If a catastrophic error has occurred, the Db.open method may fail and throw
140
a <a href="../api_java/runrec_class.html">DbRunRecoveryException</a>, in which case all subsequent Berkeley DB calls
141
will fail in the same way.
143
<a href="../api_java/db_class.html">Db</a>
145
<a href="../api_java/db_associate.html">Db.associate</a>,
146
<a href="../api_java/db_close.html">Db.close</a>,
147
<a href="../api_java/db_cursor.html">Db.cursor</a>,
148
<a href="../api_java/db_del.html">Db.del</a>,
149
<a href="../api_java/db_fd.html">Db.fd</a>,
150
<a href="../api_java/db_get.html">Db.get</a>,
151
<a href="../api_java/db_get.html">Db.pget</a>,
152
<a href="../api_java/db_get_byteswapped.html">Db.get_byteswapped</a>,
153
<a href="../api_java/db_get_type.html">Db.get_type</a>,
154
<a href="../api_java/db_join.html">Db.join</a>,
155
<a href="../api_java/db_key_range.html">Db.key_range</a>,
156
<a href="../api_java/db_open.html">Db.open</a>,
157
<a href="../api_java/db_put.html">Db.put</a>,
158
<a href="../api_java/db_remove.html">Db.remove</a>,
159
<a href="../api_java/db_rename.html">Db.rename</a>,
160
<a href="../api_java/db_set_append_recno.html">Db.set_append_recno</a>,
161
<a href="../api_java/db_set_bt_minkey.html">Db.set_bt_minkey</a>,
162
<a href="../api_java/db_set_cachesize.html">Db.set_cachesize</a>,
163
<a href="../api_java/db_set_errcall.html">Db.set_errcall</a>,
164
<a href="../api_java/db_set_errpfx.html">Db.set_errpfx</a>,
165
<a href="../api_java/db_set_feedback.html">Db.set_feedback</a>,
166
<a href="../api_java/db_set_flags.html">Db.set_flags</a>,
167
<a href="../api_java/db_set_h_ffactor.html">Db.set_h_ffactor</a>,
168
<a href="../api_java/db_set_h_nelem.html">Db.set_h_nelem</a>,
169
<a href="../api_java/db_set_lorder.html">Db.set_lorder</a>,
170
<a href="../api_java/db_set_pagesize.html">Db.set_pagesize</a>,
171
<a href="../api_java/db_set_q_extentsize.html">Db.set_q_extentsize</a>,
172
<a href="../api_java/db_set_re_delim.html">Db.set_re_delim</a>,
173
<a href="../api_java/db_set_re_len.html">Db.set_re_len</a>,
174
<a href="../api_java/db_set_re_pad.html">Db.set_re_pad</a>,
175
<a href="../api_java/db_set_re_source.html">Db.set_re_source</a>,
176
<a href="../api_java/db_stat.html">Db.stat</a>,
177
<a href="../api_java/db_sync.html">Db.sync</a>,
178
<a href="../api_java/db_truncate.html">Db.truncate</a>,
179
<a href="../api_java/db_upgrade.html">Db.upgrade</a>,
181
<a href="../api_java/db_verify.html">Db.verify</a>.
183
<table width="100%"><tr><td><br></td><td align=right>
184
<a href="../api_java/java_index.html"><img src="../images/api.gif" alt="API"></a><a href="../reftoc.html"><img src="../images/ref.gif" alt="Ref"></a>
186
<p><font size=1><a href="http://www.sleepycat.com">Copyright Sleepycat Software</a></font>
added
removed
db/docs/api_java/db_open.html
