1
<!--$Id: env_open.so,v 10.69 2001/05/15 14:44:07 bostic Exp $-->
2
<!--Copyright 1997-2001 by Sleepycat Software, Inc.-->
3
<!--All rights reserved.-->
6
<title>Berkeley DB: DbEnv.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 db_home, int flags, int mode)
26
throws DbException, FileNotFoundException;
29
<p>The DbEnv.open method is the interface for opening the Berkeley DB
30
environment. It provides a structure for creating a consistent
31
environment for processes using one or more of the features of Berkeley DB.
32
<p>The <b>db_home</b> argument to DbEnv.open (and filename
33
resolution in general) is described in
34
<a href="../ref/env/naming.html">Berkeley DB File Naming</a>.
35
<p>The <b>flags</b> argument specifies the subsystems that are initialized
36
and how the application's environment affects Berkeley DB file naming, among
38
<p>The <b>flags</b> value must be set to 0 or by bitwise inclusively <b>OR</b>'ing together one or
39
more of the following values:
40
<p>Because there are a large number of flags that can be specified, they
41
have been grouped together by functionality. The first group of flags
42
indicates which of the Berkeley DB subsystems should be initialized:
44
<p><dt><a name="Db.DB_JOINENV">Db.DB_JOINENV</a><dd>Join an existing environment. This option allows applications to
45
join an existing environment without knowing which Berkeley DB subsystems
46
the environment supports.
47
<p><dt><a name="Db.DB_INIT_CDB">Db.DB_INIT_CDB</a><dd>Initialize locking for the <a href="../ref/cam/intro.html">Berkeley DB Concurrent Data Store</a>
48
product. In this mode, Berkeley DB provides multiple reader/single writer
49
access. The only other subsystem that should be specified with the
50
Db.DB_INIT_CDB flag is Db.DB_INIT_MPOOL.
51
<p><dt><a name="Db.DB_INIT_LOCK">Db.DB_INIT_LOCK</a><dd>Initialize the locking subsystem. This subsystem should be used when
52
multiple processes or threads are going to be reading and writing a
53
Berkeley DB database, so that they do not interfere with each other. If all
54
threads are accessing the database(s) read-only, locking is unnecessary.
55
When the Db.DB_INIT_LOCK flag is specified, it is usually necessary
56
to run a deadlock detector, as well. See <a href="../utility/db_deadlock.html">db_deadlock</a> and
57
<a href="../api_java/lock_detect.html">DbEnv.lock_detect</a> for more information.
58
<p><dt><a name="Db.DB_INIT_LOG">Db.DB_INIT_LOG</a><dd>Initialize the logging subsystem. This subsystem should be used when
59
recovery from application or system failure is necessary. If the log
60
region is being created and log files are already present, the log files
61
are reviewed; subsequent log writes are appended to the end of the log,
62
rather than overwriting current log entries.
63
<p><dt><a name="Db.DB_INIT_MPOOL">Db.DB_INIT_MPOOL</a><dd>Initialize the shared memory buffer pool subsystem. This subsystem
64
should be used whenever an application is using any Berkeley DB access
66
<p><dt><a name="Db.DB_INIT_TXN">Db.DB_INIT_TXN</a><dd>Initialize the transaction subsystem. This subsystem should be used
67
when recovery and atomicity of multiple operations are important. The
68
Db.DB_INIT_TXN flag implies the Db.DB_INIT_LOG flag.
70
<p>The second group of flags govern what recovery, if any, is performed when
71
the environment is initialized:
73
<p><dt><a name="Db.DB_RECOVER">Db.DB_RECOVER</a><dd>Run normal recovery on this environment before opening it for normal
74
use. If this flag is set, the Db.DB_CREATE flag must also be set
75
because the regions will be removed and re-created.
76
<p><dt><a name="Db.DB_RECOVER_FATAL">Db.DB_RECOVER_FATAL</a><dd>Run catastrophic recovery on this environment before opening it for
77
normal use. If this flag is set, the Db.DB_CREATE flag must also
78
be set because the regions will be removed and re-created.
80
<p>A standard part of the recovery process is to remove the existing Berkeley DB
81
environment and create a new one in which to perform recovery. If the
82
thread of control performing recovery does not specify the correct
83
region initialization information (for example, the correct memory pool
84
cache size), the result can be an application running in an environment
85
with incorrect cache and other subsystem sizes. For this reason, the
86
thread of control performing recovery should specify correct
87
configuration information before calling the DbEnv.open method; or it
88
should remove the environment after recovery is completed, leaving
89
creation of the correctly sized environment to a subsequent call to
91
<p>All Berkeley DB recovery processing must be single-threaded; that is, only a
92
single thread of control may perform recovery or access a Berkeley DB
93
environment while recovery is being performed. Because it is not an
94
error to specify Db.DB_RECOVER for an environment for which no
95
recovery is required, it is reasonable programming practice for the
96
thread of control responsible for performing recovery and creating the
97
environment to always specify the Db.DB_CREATE and
98
Db.DB_RECOVER flags during startup.
99
<p>The DbEnv.open function returns successfully if Db.DB_RECOVER
100
or Db.DB_RECOVER_FATAL is specified and no log files exist, so it
101
is necessary to ensure that all necessary log files are present before
102
running recovery. For further information, consult <a href="../utility/db_archive.html">db_archive</a>
103
and <a href="../utility/db_recover.html">db_recover</a>.
104
<p>The third group of flags govern file-naming extensions in the environment:
106
<a name="3"><!--meow--></a>
107
<p><dt><a name="Db.DB_USE_ENVIRON">Db.DB_USE_ENVIRON</a><dd>The Berkeley DB process' environment may be permitted to specify information
108
to be used when naming files; see <a href="../ref/env/naming.html">Berkeley DB File Naming</a>. Because permitting users to specify which files
109
are used can create security problems, environment information will be
110
used in file naming for all users only if the DB_USE_ENVIRON flag is
112
<p><dt><a name="Db.DB_USE_ENVIRON_ROOT">Db.DB_USE_ENVIRON_ROOT</a><dd>The Berkeley DB process' environment may be permitted to specify information
113
to be used when naming files; see <a href="../ref/env/naming.html">Berkeley DB File Naming</a>. Because permitting users to specify which files
114
are used can create security problems, if the DB_USE_ENVIRON_ROOT flag
115
is set, environment information will be used for file naming only for
116
users with appropriate permissions (for example, users with a user-ID
117
of 0 on UNIX systems).
119
<p>Finally, there are a few additional unrelated flags:
121
<p><dt><a name="Db.DB_CREATE">Db.DB_CREATE</a><dd>Cause Berkeley DB subsystems to create any underlying files, as necessary.
122
<p><dt><a name="Db.DB_LOCKDOWN">Db.DB_LOCKDOWN</a><dd>Lock shared Berkeley DB environment files and memory-mapped databases into
124
<p><dt><a name="Db.DB_PRIVATE">Db.DB_PRIVATE</a><dd>Specify that the environment will only be accessed by a single process
125
(although that process may be multithreaded). This flag has two effects
126
on the Berkeley DB environment. First, all underlying data structures are
127
allocated from per-process memory instead of from shared memory that is
128
potentially accessible to more than a single process. Second, mutexes
129
are only configured to work between threads.
130
<p>This flag should not be specified if more than a single process is
131
accessing the environment because it is likely to cause database
132
corruption and unpredictable behavior. For example, if both a server
133
application and the Berkeley DB utility <a href="../utility/db_stat.html">db_stat</a> are expected to access
134
the environment, the Db.DB_PRIVATE flag should not be
136
<p><dt><a name="Db.DB_SYSTEM_MEM">Db.DB_SYSTEM_MEM</a><dd>Allocate memory from system shared memory instead of from memory backed
137
by the filesystem. See <a href="../ref/env/region.html">Shared Memory
138
Regions</a> for more information.
139
<p><dt><a name="Db.DB_THREAD">Db.DB_THREAD</a><dd>Cause the <a href="../api_java/dbenv_class.html">DbEnv</a> handle returned by DbEnv.open to be
140
<i>free-threaded</i>; that is, usable by multiple threads within a
141
single address space.
142
<p>Threading is always assumed in the Java API, so no special flags are
143
required and Berkeley DB functions will always behave as if the Db.DB_THREAD
146
<p>On UNIX systems or in IEEE/ANSI Std 1003.1 (POSIX) environments, all files created by
147
Berkeley DB 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
148
(see <b>umask</b>(2)). If <b>mode</b> is 0, Berkeley DB will use a default
149
mode of readable and writable by both owner and group. On Windows
150
systems, the mode argument is ignored. The group ownership of created
151
files is based on the system and directory defaults, and is not further
152
specified by Berkeley DB.
153
<p>The DbEnv.open method throws an exception that encapsulates a non-zero error value on
155
<h1>Environment Variables</h1>
157
<p><dt>DB_HOME<dd>The environment variable <b>DB_HOME</b> may be used as the path of
158
the database home, as described in
159
<a href="../ref/env/naming.html">Berkeley DB File Naming</a>.
162
<p>The DbEnv.open method may fail and throw an exception encapsulating a non-zero error for the following conditions:
164
<p><dt>EAGAIN<dd>The shared memory region was locked and (repeatedly) unavailable.
167
<p><dt>EINVAL<dd>An invalid flag value or parameter was specified.
169
The Db.DB_THREAD flag was specified and fast mutexes are not
170
available for this architecture.
171
<p>The DB_HOME or TMPDIR environment variables were set, but empty.
172
<p>An incorrectly formatted <b>NAME VALUE</b> entry or line was found.
175
<p><dt>ENOSPC<dd>HP-UX only: a previously created Berkeley DB environment for this process still
178
<p>If the file or directory does not exist, the DbEnv.open method will
180
throw a FileNotFoundException exception.
181
<p>The DbEnv.open method may fail and throw an exception for errors specified for other Berkeley DB and C library or system methods.
182
If a catastrophic error has occurred, the DbEnv.open method may fail and throw
183
a <a href="../api_java/runrec_class.html">DbRunRecoveryException</a>, in which case all subsequent Berkeley DB calls
184
will fail in the same way.
186
<a href="../api_java/dbenv_class.html">DbEnv</a>
188
<a href="../api_java/env_close.html">DbEnv.close</a>,
189
<a href="../api_java/env_version.html">DbEnv.get_version_string</a>,
190
<a href="../api_java/env_open.html">DbEnv.open</a>,
191
<a href="../api_java/env_remove.html">DbEnv.remove</a>,
192
<a href="../api_java/env_set_cachesize.html">DbEnv.set_cachesize</a>,
193
<a href="../api_java/env_set_data_dir.html">DbEnv.set_data_dir</a>,
194
<a href="../api_java/env_set_errcall.html">DbEnv.set_errcall</a>,
195
<a href="../api_java/env_set_error_stream.html">DbEnv.set_error_stream</a>,
196
<a href="../api_java/env_set_errpfx.html">DbEnv.set_errpfx</a>,
197
<a href="../api_java/env_set_feedback.html">DbEnv.set_feedback</a>,
198
<a href="../api_java/env_set_flags.html">DbEnv.set_flags</a>,
199
<a href="../api_java/env_set_mutexlocks.html">DbEnv.set_mutexlocks</a>,
200
<a href="../api_java/env_set_pageyield.html">DbEnv.set_pageyield</a>,
201
<a href="../api_java/env_set_panicstate.html">DbEnv.set_panicstate</a>,
202
<a href="../api_java/env_set_rec_init.html">DbEnv.set_recovery_init</a>,
203
<a href="../api_java/env_set_rpc_server.html">DbEnv.set_rpc_server</a>,
204
<a href="../api_java/env_set_region_init.html">DbEnv.set_region_init</a>,
205
<a href="../api_java/env_set_shm_key.html">DbEnv.set_shm_key</a>,
206
<a href="../api_java/env_set_tas_spins.html">DbEnv.set_tas_spins</a>,
207
<a href="../api_java/env_set_tmp_dir.html">DbEnv.set_tmp_dir</a>,
208
<a href="../api_java/env_set_verbose.html">DbEnv.set_verbose</a>,
209
and <a href="../api_java/env_strerror.html">DbEnv.strerror</a>.
211
<table width="100%"><tr><td><br></td><td align=right>
212
<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>
214
<p><font size=1><a href="http://www.sleepycat.com">Copyright Sleepycat Software</a></font>
added
removed
db/docs/api_java/env_open.html
