mirror of
https://github.com/berkeleydb/libdb.git
synced 2024-11-17 01:26:25 +00:00
712 lines
34 KiB
HTML
712 lines
34 KiB
HTML
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
|
||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
||
<html xmlns="http://www.w3.org/1999/xhtml">
|
||
<head>
|
||
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
|
||
<title>berkdb open</title>
|
||
<link rel="stylesheet" href="apiReference.css" type="text/css" />
|
||
<meta name="generator" content="DocBook XSL Stylesheets V1.73.2" />
|
||
<link rel="start" href="index.html" title="Berkeley DB TCL API Reference" />
|
||
<link rel="up" href="tclapi.html" title="Chapter 1. Berkeley DB Tcl APIs" />
|
||
<link rel="prev" href="db_join.html" title="db join" />
|
||
<link rel="next" href="db_put.html" title="db put" />
|
||
</head>
|
||
<body>
|
||
<div xmlns="" class="navheader">
|
||
<div class="libver">
|
||
<p>Library Version 11.2.5.2</p>
|
||
</div>
|
||
<table width="100%" summary="Navigation header">
|
||
<tr>
|
||
<th colspan="3" align="center">berkdb open</th>
|
||
</tr>
|
||
<tr>
|
||
<td width="20%" align="left"><a accesskey="p" href="db_join.html">Prev</a> </td>
|
||
<th width="60%" align="center">Chapter 1.
|
||
Berkeley DB Tcl APIs
|
||
</th>
|
||
<td width="20%" align="right"> <a accesskey="n" href="db_put.html">Next</a></td>
|
||
</tr>
|
||
</table>
|
||
<hr />
|
||
</div>
|
||
<div class="sect1" lang="en" xml:lang="en">
|
||
<div class="titlepage">
|
||
<div>
|
||
<div>
|
||
<h2 class="title" style="clear: both"><a id="db_open"></a>berkdb open</h2>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<pre class="programlisting">berkdb open
|
||
[-auto_commit]
|
||
[-btree | -hash | -recno | -queue | -unknown]
|
||
[-cachesize {gbytes bytes ncache}]
|
||
[-create]
|
||
[-delim delim]
|
||
[-dup]
|
||
[-dupsort]
|
||
[-encrypt]
|
||
[-encryptaes passwd]
|
||
[-encryptany passwd]
|
||
[-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]
|
||
[-txn txnid]
|
||
[--]
|
||
[file [database]] </pre>
|
||
<p>
|
||
The <span class="bold"><strong>berkdb open</strong></span> command opens and
|
||
optionally creates a database. The returned database handle is bound
|
||
to a Tcl command of the form <span class="bold"><strong>dbN</strong></span>,
|
||
where N is an integer starting at 0 (for example, db0 and db1). It is
|
||
through this Tcl command that the script accesses the database
|
||
methods.
|
||
</p>
|
||
<p>
|
||
The options are as follows:
|
||
</p>
|
||
<div class="itemizedlist">
|
||
<ul type="disc">
|
||
<li>
|
||
<p>
|
||
<span class="bold"><strong>-auto_commit</strong></span>
|
||
</p>
|
||
<p>
|
||
Enclose the call within an implicit transaction (you do not need to provide a transaction handle
|
||
as a transaction is internally created and commited for you). If the call succeeds, the open
|
||
operation will be recoverable and all subsequent database modification
|
||
operations based on this handle will be transactionally protected. If
|
||
the call fails, no database will have been created.
|
||
</p>
|
||
</li>
|
||
<li>
|
||
<p>
|
||
<span class="bold"><strong>-btree</strong></span>
|
||
</p>
|
||
<p>
|
||
Open/create a database of type Btree. The Btree format is a
|
||
representation of a sorted, balanced tree structure.
|
||
</p>
|
||
</li>
|
||
<li>
|
||
<p>
|
||
<span class="bold"><strong>-hash</strong></span>
|
||
</p>
|
||
<p>
|
||
Open/create a database of type Hash. The Hash format is an
|
||
extensible, dynamic hashing scheme.
|
||
</p>
|
||
</li>
|
||
<li>
|
||
<p>
|
||
<span class="bold"><strong>-queue</strong></span>
|
||
</p>
|
||
<p>
|
||
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>
|
||
</li>
|
||
<li>
|
||
<p>
|
||
<span class="bold"><strong>-recno</strong></span>
|
||
</p>
|
||
<p>
|
||
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>
|
||
</li>
|
||
<li>
|
||
<p>
|
||
<span class="bold"><strong>-unknown</strong></span>
|
||
</p>
|
||
<p>
|
||
The database is of an unknown type, and must already exist.
|
||
</p>
|
||
</li>
|
||
<li>
|
||
<p>
|
||
<span class="bold"><strong>-cachesize {gbytes bytes ncache}</strong></span>
|
||
</p>
|
||
<p>
|
||
Set the size of the database's shared memory buffer pool (that is, the
|
||
cache), to <span class="bold"><strong>gbytes</strong></span> gigabytes plus
|
||
<span class="bold"><strong>bytes</strong></span>. 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>
|
||
<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>
|
||
<p>
|
||
It is possible to specify caches to Berkeley DB that are large enough
|
||
so that they cannot be allocated contiguously on some architectures;
|
||
for example, some releases of Solaris limit the amount of memory that
|
||
may be allocated contiguously by a process. If <span class="bold"><strong>ncache</strong></span> 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 <span class="bold"><strong>ncache</strong></span> equally sized
|
||
separate pieces of memory.
|
||
</p>
|
||
<p>
|
||
For information on tuning the Berkeley DB cache size, see
|
||
<a href="../../programmer_reference/general_am_conf.html#am_conf_cachesize" class="olink">Selecting a Cache Size</a>
|
||
in the <em class="citetitle">Berkeley DB Programmer's Reference Guide</em>.
|
||
</p>
|
||
<p>
|
||
Because 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>
|
||
</li>
|
||
<li>
|
||
<p>
|
||
<span class="bold"><strong>-create</strong></span>
|
||
</p>
|
||
<p>
|
||
Create any underlying files, as necessary. If the files do not already
|
||
exist and the <span class="bold"><strong>-create</strong></span> argument is not
|
||
specified, the call will fail.
|
||
</p>
|
||
</li>
|
||
<li>
|
||
<p>
|
||
<span class="bold"><strong>-delim delim</strong></span>
|
||
</p>
|
||
<p>
|
||
Set the delimiting byte used to mark the end of a record in the
|
||
backing source file for the Recno access method.
|
||
</p>
|
||
<p>
|
||
This byte is used for variable length records if the <span class="bold"><strong>-source</strong></span> argument file is specified. If the
|
||
<span class="bold"><strong>-source</strong></span> argument file is specified
|
||
and no delimiting byte was specified, <newline> characters (that
|
||
is, ASCII 0x0a) are interpreted as end-of-record markers.
|
||
</p>
|
||
</li>
|
||
<li>
|
||
<p>
|
||
<span class="bold"><strong>-dup</strong></span>
|
||
</p>
|
||
<p>
|
||
Permit duplicate data items in the tree, that is, 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>
|
||
<p>
|
||
It is an error to specify both <span class="bold"><strong>-dup</strong></span> and
|
||
<span class="bold"><strong>-recnum</strong></span>.
|
||
</p>
|
||
</li>
|
||
<li>
|
||
<p>
|
||
<span class="bold"><strong>-dupsort</strong></span>
|
||
</p>
|
||
<p>
|
||
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 <span class="emphasis"><em>db</em></span> <span class="bold"><strong>put</strong></span> operation as well as the
|
||
<span class="emphasis"><em>dbc</em></span> <span class="bold"><strong>put</strong></span>
|
||
operation when the <span class="bold"><strong>-keyfirst</strong></span>,
|
||
<span class="bold"><strong>-keylast</strong></span> and <span class="bold"><strong>-current</strong></span> options are specified.
|
||
</p>
|
||
</li>
|
||
<li>
|
||
<p>
|
||
<span class="bold"><strong>-encrypt</strong></span>
|
||
</p>
|
||
<p>
|
||
Specify the database in an environment should be encrypted with the
|
||
same password that is being used in the environment.
|
||
</p>
|
||
</li>
|
||
<li>
|
||
<p>
|
||
<span class="bold"><strong>-encryptaes passwd</strong></span>
|
||
</p>
|
||
<p>
|
||
Specify the database should be encrypted with the given password using
|
||
the Rijndael/AES (also known as the Advanced Encryption Standard and
|
||
Federal Information Processing Standard (FIPS) 197) algorithm.
|
||
</p>
|
||
</li>
|
||
<li>
|
||
<p>
|
||
<span class="bold"><strong>-encryptany passwd</strong></span>
|
||
</p>
|
||
<p>
|
||
Specify the already existing database should be opened with the given
|
||
password. This option is used if the database is known to be
|
||
encrypted, but the specific algorithm used is not known.
|
||
</p>
|
||
</li>
|
||
<li>
|
||
<p>
|
||
<span class="bold"><strong>-env env</strong></span>
|
||
</p>
|
||
<p>
|
||
If no <span class="bold"><strong>-env</strong></span> argument is given, the
|
||
database is standalone; that is, it is not part of any Berkeley DB
|
||
environment.
|
||
</p>
|
||
<p>
|
||
If a <span class="bold"><strong>-env</strong></span> 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, the
|
||
access methods will automatically acquire the correct locks when
|
||
reading and writing pages of the database.
|
||
</p>
|
||
</li>
|
||
<li>
|
||
<p>
|
||
<span class="bold"><strong>-errfile filename</strong></span>
|
||
</p>
|
||
<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>
|
||
<p>
|
||
The <span class="bold"><strong>-errfile</strong></span> 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>
|
||
<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 (for example, env0), otherwise it will be the
|
||
database command name (for example, db0).
|
||
</p>
|
||
<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>
|
||
<p>
|
||
For database handles opened inside of Berkeley DB environments,
|
||
specifying the <span class="bold"><strong>-errfile</strong></span> argument
|
||
affects the entire environment and is equivalent to specifying the
|
||
same argument to the <span class="bold"><strong>berkdb env</strong></span>
|
||
command.
|
||
</p>
|
||
</li>
|
||
<li>
|
||
<p>
|
||
<span class="bold"><strong>-excl</strong></span>
|
||
</p>
|
||
<p>
|
||
Return an error if the database already exists.
|
||
</p>
|
||
</li>
|
||
<li>
|
||
<p>
|
||
<span class="bold"><strong>-extent size</strong></span>
|
||
</p>
|
||
<p>
|
||
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>
|
||
<p>
|
||
For information on tuning the extent size, see
|
||
<a href="../../programmer_reference/rq_conf.html#am_conf_extentsize" class="olink">Selecting an Extent Size</a>
|
||
in the <em class="citetitle">Berkeley DB Programmer's Reference Guide</em>.
|
||
</p>
|
||
</li>
|
||
<li>
|
||
<p>
|
||
<span class="bold"><strong>-ffactor density</strong></span>
|
||
</p>
|
||
<p>
|
||
Set the desired density within the hash table.
|
||
</p>
|
||
<p>
|
||
The density is an approximation of the number of keys allowed to
|
||
accumulate in any one bucket
|
||
</p>
|
||
</li>
|
||
<li>
|
||
<p>
|
||
<span class="bold"><strong>-len len</strong></span>
|
||
</p>
|
||
<p>
|
||
For the Queue access method, specify that the records are of length
|
||
<span class="bold"><strong>len</strong></span>.
|
||
</p>
|
||
<p>
|
||
For the Recno access method, specify that the records are
|
||
fixed-length, not byte-delimited, and are of length <span class="bold"><strong>len</strong></span>.
|
||
</p>
|
||
<p>
|
||
Any records added to the database that are less than <span class="bold"><strong>len</strong></span> bytes long are automatically padded (see
|
||
the <span class="bold"><strong>-pad</strong></span> argument for more
|
||
information).
|
||
</p>
|
||
<p>
|
||
Any attempt to insert records into the database that are greater than
|
||
<span class="bold"><strong>len</strong></span> bytes long will cause the call to
|
||
fail immediately and return an error.
|
||
</p>
|
||
</li>
|
||
<li>
|
||
<p>
|
||
<span class="bold"><strong>-mode mode</strong></span>
|
||
</p>
|
||
<p>
|
||
On UNIX systems, or in IEEE/ANSI Std 1003.1 (POSIX) environments, all
|
||
files created by the access methods are created with mode <span class="bold"><strong>mode</strong></span> (as described in <span class="bold"><strong>chmod</strong></span>(2)) and modified by the process' umask
|
||
value at the time of creation (see <span class="bold"><strong>umask</strong></span>(2)). The group ownership of created
|
||
files is based on the system and directory defaults, and is not
|
||
further specified by Berkeley DB. If <span class="bold"><strong>mode</strong></span> is 0, files are created readable and
|
||
writable by both owner and group. On Windows systems, the mode
|
||
argument is ignored.
|
||
</p>
|
||
</li>
|
||
<li>
|
||
<p>
|
||
<span class="bold"><strong>-nelem size</strong></span>
|
||
</p>
|
||
<p>
|
||
Set an estimate of the final size of the hash table.
|
||
</p>
|
||
<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>
|
||
</li>
|
||
<li>
|
||
<p>
|
||
<span class="bold"><strong>-pad pad</strong></span>
|
||
</p>
|
||
<p>
|
||
Set the padding character for short, fixed-length records for the
|
||
Queue and Recno access methods.
|
||
</p>
|
||
<p>
|
||
If no pad character is specified, <space> characters (that is,
|
||
ASCII 0x20) are used for padding.
|
||
</p>
|
||
</li>
|
||
<li>
|
||
<p>
|
||
<span class="bold"><strong>-pagesize pagesize</strong></span>
|
||
</p>
|
||
<p>
|
||
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>
|
||
<p>
|
||
For information on tuning the Berkeley DB page size, see
|
||
<a href="../../programmer_reference/general_am_conf.html#am_conf_pagesize" class="olink">Selecting a Page Size</a>
|
||
in the <em class="citetitle">Berkeley DB Programmer's Reference Guide</em>.
|
||
</p>
|
||
</li>
|
||
<li>
|
||
<p>
|
||
<span class="bold"><strong>-rdonly</strong></span>
|
||
</p>
|
||
<p>
|
||
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>
|
||
</li>
|
||
<li>
|
||
<p>
|
||
<span class="bold"><strong>-recnum</strong></span>
|
||
</p>
|
||
<p>
|
||
Support retrieval from the Btree using record numbers.
|
||
</p>
|
||
<p>
|
||
Logical record numbers in Btree databases are mutable in the face of
|
||
record insertion or deletion. See the <span class="bold"><strong>-renumber</strong></span> argument for further discussion.
|
||
</p>
|
||
<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 <span class="bold"><strong>-recnum</strong></span>
|
||
can result in serious performance degradation for some applications
|
||
and data sets.
|
||
</p>
|
||
<p>
|
||
It is an error to specify both <span class="bold"><strong>-dup</strong></span>
|
||
and <span class="bold"><strong>-recnum</strong></span>.
|
||
</p>
|
||
</li>
|
||
<li>
|
||
<p>
|
||
<span class="bold"><strong>-renumber</strong></span>
|
||
</p>
|
||
<p>
|
||
Specifying the <span class="bold"><strong>-renumber</strong></span> 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 one. If a cursor was positioned to record
|
||
number 4 before the deletion, it will refer to 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 one logical record, continuing to refer to the same
|
||
record as it did before.
|
||
</p>
|
||
<p>
|
||
Using the <span class="emphasis"><em>db</em></span> <span class="bold"><strong>put</strong></span>
|
||
or <span class="emphasis"><em>dbc</em></span> <span class="bold"><strong>put</strong></span>
|
||
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>
|
||
<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
|
||
one. For example, the creation of a new record numbered 8 causes
|
||
records numbered 8 and greater to be renumbered upward by one. If a
|
||
cursor was positioned to record number 8 or greater before the
|
||
insertion, it will be shifted upward one logical record, continuing to
|
||
refer to the same record as it did before.
|
||
</p>
|
||
<p>
|
||
For these reasons, concurrent access to a Recno database with the
|
||
<span class="bold"><strong>-renumber</strong></span> flag specified may be
|
||
largely meaningless, although it is supported.
|
||
</p>
|
||
</li>
|
||
<li>
|
||
<p>
|
||
<span class="bold"><strong>-snapshot</strong></span>
|
||
</p>
|
||
<p>
|
||
This argument specifies that any specified <span class="bold"><strong>-source</strong></span> file be read in its entirety when the
|
||
database is opened. If this argument is not specified, the <span class="bold"><strong>-source</strong></span> file may be read lazily.
|
||
</p>
|
||
</li>
|
||
<li>
|
||
<p>
|
||
<span class="bold"><strong>-source file</strong></span>
|
||
</p>
|
||
<p>
|
||
Set the underlying source file for the Recno access method. The
|
||
purpose of the <span class="bold"><strong>-source</strong></span> file is to
|
||
provide fast access and modification to databases that are normally
|
||
stored as flat text files.
|
||
</p>
|
||
<p>
|
||
If the <span class="bold"><strong>-source</strong></span> 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 <span class="bold"><strong>-delim</strong></span>. For example, standard UNIX byte stream
|
||
files can be interpreted as a sequence of variable length records
|
||
separated by <newline> characters.
|
||
</p>
|
||
<p>
|
||
In addition, when cached data would normally be written back to the
|
||
underlying database file (for example, when the
|
||
<span class="emphasis"><em>db</em></span> <span class="bold"><strong>close</strong></span> or
|
||
<span class="emphasis"><em>db</em></span> <span class="bold"><strong>sync</strong></span> commands
|
||
are called), the in-memory copy of the database will be written back
|
||
to the <span class="bold"><strong>-source</strong></span> file.
|
||
</p>
|
||
<p>
|
||
By default, the backing source file is read lazily, that is, records
|
||
are not read from the file until they are requested by the
|
||
application. <span class="bold"><strong>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
|
||
<span class="bold"><strong>berkdb open</strong></span> call. See the <span class="bold"><strong>-snapshot</strong></span> argument for more
|
||
information.</strong></span>
|
||
</p>
|
||
<p>
|
||
<span class="bold"><strong>Reading and writing the backing source file
|
||
specified by <span class="bold"><strong>-source</strong></span> cannot be
|
||
transaction protected because it involves filesystem operations that
|
||
are not part of the Berkeley DB transaction methodology.</strong></span>
|
||
For this reason, if a temporary database is used to hold the records,
|
||
it is possible to lose the contents of the <span class="bold"><strong>-source</strong></span> file, for example, if the system crashes
|
||
at the right instant. If a file is used to hold the database, that
|
||
is, a filename was specified as the <span class="bold"><strong>file</strong></span> argument to <span class="bold"><strong>berkdb
|
||
open</strong></span>, normal database recovery on that file can be used to
|
||
prevent information loss, although it is still possible that the
|
||
contents of <span class="bold"><strong>-source</strong></span> file will be lost if
|
||
the system crashes.
|
||
</p>
|
||
<p>
|
||
The <span class="bold"><strong>-source</strong></span> file must already exist
|
||
(but may be zero-length) when <span class="bold"><strong>berkdb
|
||
open</strong></span> is called.
|
||
</p>
|
||
<p>
|
||
It is not an error to specify a read-only <span class="bold"><strong>-source</strong></span> 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
|
||
<span class="emphasis"><em>db</em></span> <span class="bold"><strong>close</strong></span> or
|
||
<span class="emphasis"><em>db</em></span> <span class="bold"><strong>sync</strong></span> commands
|
||
will fail, of course. Specifying the <span class="bold"><strong>-nosync</strong></span> argument to the <span class="emphasis"><em>db</em></span>
|
||
<span class="bold"><strong>close</strong></span> command will stop it from
|
||
attempting to write the changes to the backing file; instead, they
|
||
will be silently discarded.
|
||
</p>
|
||
<p>
|
||
For all of the previous reasons, the <span class="bold"><strong>-source</strong></span> 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 such as a text editor.
|
||
</p>
|
||
</li>
|
||
<li>
|
||
<p>
|
||
<span class="bold"><strong>-truncate</strong></span>
|
||
</p>
|
||
<p>
|
||
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>
|
||
<p>
|
||
The <span class="bold"><strong>-truncate</strong></span> argument cannot be
|
||
transaction-protected, and it is an error to specify it in a
|
||
transaction-protected environment.
|
||
</p>
|
||
</li>
|
||
<li>
|
||
<p>
|
||
<span class="bold"><strong>-txn txnid</strong></span>
|
||
</p>
|
||
<p>
|
||
If the operation is part of an application-specified transaction, the
|
||
<span class="bold"><strong>txnid</strong></span> parameter is a transaction
|
||
handle returned from <span class="emphasis"><em>env</em></span> <span class="bold"><strong>txn</strong></span>. If no transaction handle is specified,
|
||
but the -auto_commit flag is specified, the operation will be
|
||
implicitly transaction protected.
|
||
</p>
|
||
</li>
|
||
<li>
|
||
<p>
|
||
<span class="bold"><strong>--</strong></span>
|
||
</p>
|
||
<p>
|
||
Mark the end of the command arguments.
|
||
</p>
|
||
</li>
|
||
<li>
|
||
<p>
|
||
<span class="bold"><strong>file</strong></span>
|
||
</p>
|
||
<p>
|
||
The name of a single physical file on disk that will be used to back
|
||
the database.
|
||
</p>
|
||
<p>
|
||
An in-memory database never intended to be preserved on
|
||
disk may be created by not specifying a file name. For
|
||
example:
|
||
</p>
|
||
<pre class="programlisting">berkdb open -create -btree </pre>
|
||
<p>
|
||
creates an in-memory database.
|
||
</p>
|
||
</li>
|
||
<li>
|
||
<p>
|
||
<span class="bold"><strong>database</strong></span>
|
||
</p>
|
||
<p>
|
||
The <span class="bold"><strong>database</strong></span> 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 <span class="bold"><strong>database</strong></span> name.
|
||
</p>
|
||
<p>
|
||
Applications opening multiple databases in a single file will almost
|
||
certainly need to create a shared database environment. See
|
||
<a href="../../programmer_reference/am_opensub.html" class="olink">Opening multiple databases in a single file</a>
|
||
in the <em class="citetitle">Berkeley DB Programmer's Reference Guide</em> for more
|
||
information.
|
||
</p>
|
||
<p>
|
||
If more than one in-memory database is desired, it is
|
||
necessary to specify an empty string as the database name.
|
||
For example:
|
||
</p>
|
||
<pre class="programlisting">berkdb open -create -btree "" foo
|
||
berkdb open -create -btree "" bar </pre>
|
||
<p>
|
||
will create two databases, neither of which will appear on
|
||
disk.
|
||
</p>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
<p>
|
||
The <span class="bold"><strong>berkdb open</strong></span> command returns a
|
||
database handle on success.
|
||
</p>
|
||
<p>
|
||
In the case of error, a Tcl error is thrown.
|
||
</p>
|
||
</div>
|
||
<div class="navfooter">
|
||
<hr />
|
||
<table width="100%" summary="Navigation footer">
|
||
<tr>
|
||
<td width="40%" align="left"><a accesskey="p" href="db_join.html">Prev</a> </td>
|
||
<td width="20%" align="center">
|
||
<a accesskey="u" href="tclapi.html">Up</a>
|
||
</td>
|
||
<td width="40%" align="right"> <a accesskey="n" href="db_put.html">Next</a></td>
|
||
</tr>
|
||
<tr>
|
||
<td width="40%" align="left" valign="top"><span class="emphasis"><em>db</em></span> join </td>
|
||
<td width="20%" align="center">
|
||
<a accesskey="h" href="index.html">Home</a>
|
||
</td>
|
||
<td width="40%" align="right" valign="top"> <span class="emphasis"><em>db</em></span> put</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
</body>
|
||
</html>
|