360 lines
15 KiB
Plaintext
360 lines
15 KiB
Plaintext
m4_comment([$Id: db_open.so,v 11.34 2004/12/16 19:13:04 bostic Exp $])
|
|
|
|
define(M4PAGELOCAL, )
|
|
include(tcl/m4.tcl)
|
|
|
|
m4_tcl_header(berkdb open, m4_tcl_db_open, [dnl
|
|
berkdb open
|
|
m4_tcl_arg([-auto_commit])
|
|
m4_tcl_arg([-btree | -hash | -recno | -queue | -unknown])
|
|
m4_tcl_arg([-cachesize {gbytes bytes ncache}])
|
|
m4_tcl_arg([-create])
|
|
m4_tcl_arg([-delim delim])
|
|
m4_tcl_arg([-dup])
|
|
m4_tcl_arg([-dupsort])
|
|
m4_tcl_arg([-encrypt])
|
|
m4_tcl_arg([-encryptaes passwd])
|
|
m4_tcl_arg([-encryptany passwd])
|
|
m4_tcl_arg([-env env])
|
|
m4_tcl_arg([-errfile filename])
|
|
m4_tcl_arg([-excl])
|
|
m4_tcl_arg([-extent size])
|
|
m4_tcl_arg([-ffactor density])
|
|
m4_tcl_arg([-len len])
|
|
m4_tcl_arg([-mode mode])
|
|
m4_tcl_arg([-nelem size])
|
|
m4_tcl_arg([-pad pad])
|
|
m4_tcl_arg([-pagesize pagesize])
|
|
m4_tcl_arg([-rdonly])
|
|
m4_tcl_arg([-recnum])
|
|
m4_tcl_arg([-renumber])
|
|
m4_tcl_arg([-snapshot])
|
|
m4_tcl_arg([-source file])
|
|
m4_tcl_arg([-truncate])
|
|
m4_tcl_arg([-txn txnid])
|
|
m4_tcl_arg([--])
|
|
m4_tcl_arg([file __LB__database__RB__])
|
|
])
|
|
|
|
m4_p([dnl
|
|
The m4_tcl_db_open command opens and optionally creates a database.
|
|
The returned database handle is bound to a Tcl command of the form
|
|
m4_bold(dbN), 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.])
|
|
|
|
m4_p([dnl
|
|
The options are as follows:])
|
|
|
|
m4_tagbegin
|
|
|
|
m4_tag([-auto_commit], [dnl
|
|
Enclose the call within a transaction. 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.])
|
|
|
|
m4_tag([-btree], [Open/create a database of type Btree. The Btree format
|
|
is a representation of a sorted, balanced tree structure.])
|
|
|
|
m4_tag([-hash], [Open/create a database of type Hash. The Hash format is
|
|
an extensible, dynamic hashing scheme.])
|
|
|
|
m4_tag([-queue], [Open/create a database of type Queue. The Queue format
|
|
supports fast access to fixed-length records accessed by sequentially or
|
|
logical record number.])
|
|
|
|
m4_tag([-recno], [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.])
|
|
|
|
m4_tag([-unknown], [dnl
|
|
The database is of an unknown type, and must already exist.])
|
|
|
|
m4_tag([-cachesize {gbytes bytes ncache}], [dnl
|
|
m4_set_cachesize
|
|
m4_p([dnl
|
|
Because databases opened within m4_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.])])
|
|
|
|
m4_tag([-create], [dnl
|
|
Create any underlying files, as necessary. If the files do not already
|
|
exist and the m4_arg(-create) argument is not specified, the call will
|
|
fail.])
|
|
|
|
m4_tag([-delim delim], [dnl
|
|
Set the delimiting byte used to mark the end of a record in the backing
|
|
source file for the Recno access method.
|
|
m4_p([dnl
|
|
This byte is used for variable length records if the m4_arg(-source)
|
|
argument file is specified. If the m4_arg(-source) argument file is
|
|
specified and no delimiting byte was specified, m4_htmlquote(newline)
|
|
characters (that is, ASCII 0x0a) are interpreted as end-of-record
|
|
markers.])])
|
|
|
|
m4_tag([-dup], [dnl
|
|
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. m4_p([dnl It is an
|
|
error to specify both m4_arg(-dup) and m4_arg(-recnum).])])
|
|
|
|
m4_tag([-dupsort], [dnl
|
|
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 m4_tcl_db_put operation as well as the
|
|
m4_tcl_dbc_put operation when the m4_arg(-keyfirst), m4_arg(-keylast)
|
|
and m4_arg(-current) options are specified.])
|
|
|
|
m4_tag([-encrypt], [dnl
|
|
Specify the database in an environment should be encrypted with the
|
|
same password that is being used in the environment.])
|
|
|
|
m4_tag([-encryptaes passwd], [dnl
|
|
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.])
|
|
|
|
m4_tag([-encryptany passwd], [dnl
|
|
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.])
|
|
|
|
m4_tag([-env env], [dnl
|
|
If no m4_arg(-env) argument is given, the database is standalone; that
|
|
is, it is not part of any m4_db environment.
|
|
m4_p([dnl
|
|
If a m4_arg(-env) argument is given, the database is created within the
|
|
specified m4_db environment. The database access methods automatically
|
|
make calls to the other subsystems in m4_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.])])
|
|
|
|
m4_tag([-errfile filename], [dnl
|
|
m4_tcl_errfile(db)
|
|
m4_p([dnl
|
|
For database handles opened inside of m4_db environments, specifying the
|
|
m4_arg(-errfile) argument affects the entire environment and is equivalent
|
|
to specifying the same argument to the m4_tcl_env_open command.])])
|
|
|
|
m4_tag([-excl], [dnl
|
|
Return an error if the database already exists.])
|
|
|
|
m4_tag([-extent size], [dnl
|
|
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.])
|
|
|
|
m4_p([dnl
|
|
For information on tuning the extent size, see
|
|
m4_link(M4RELDIR/ref/am_conf/extentsize, [Selecting a extent size]).])
|
|
|
|
m4_tag([-ffactor density],
|
|
Set the desired density within the hash table.
|
|
m4_p([dnl
|
|
The density is an approximation of the number of keys allowed to
|
|
accumulate in any one bucket, determining when the hash table grows or
|
|
shrinks. If you know the average sizes of the keys and data in your data
|
|
set, setting the fill factor can enhance performance. A reasonable rule
|
|
computing fill factor is to set it to:])
|
|
|
|
m4_indent([dnl
|
|
(pagesize - 32) / (average_key_size + average_data_size + 8)])
|
|
|
|
m4_p([dnl
|
|
If no value is specified, the fill factor will be selected dynamically as
|
|
pages are filled.])])
|
|
|
|
m4_tag([-len len], [dnl
|
|
For the Queue access method, specify that the records are of length
|
|
m4_arg(len).
|
|
m4_p([dnl
|
|
For the Recno access method, specify that the records are fixed-length,
|
|
not byte-delimited, and are of length m4_arg(len).])
|
|
m4_p([dnl
|
|
Any records added to the database that are less than m4_arg(len) bytes
|
|
long are automatically padded (see the m4_arg(-pad) argument for more
|
|
information).])
|
|
m4_p([dnl
|
|
Any attempt to insert records into the database that are greater than
|
|
m4_arg(len) bytes long will cause the call to fail immediately and return
|
|
an error.])])
|
|
|
|
m4_tag([-mode mode], [m4_tcl_filemode([the access methods])])
|
|
|
|
m4_tag([-nelem size], [dnl
|
|
Set an estimate of the final size of the hash table.
|
|
m4_p([dnl
|
|
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.])])
|
|
|
|
m4_tag([-pad pad], [dnl
|
|
Set the padding character for short, fixed-length records for the Queue
|
|
and Recno access methods.
|
|
m4_p([dnl
|
|
If no pad character is specified, __LT__space__GT__ characters (that is,
|
|
ASCII 0x20) are used for padding.])])
|
|
|
|
m4_tag([-pagesize pagesize], [dnl
|
|
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.
|
|
m4_p([dnl
|
|
For information on tuning the m4_db page size, see
|
|
m4_link(M4RELDIR/ref/am_conf/pagesize, [Selecting a page size]).])])
|
|
|
|
m4_tag([-rdonly], [dnl
|
|
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.])
|
|
|
|
m4_tag([-recnum], [dnl
|
|
Support retrieval from the Btree using record numbers.
|
|
m4_p([dnl
|
|
Logical record numbers in Btree databases are mutable in the face of
|
|
record insertion or deletion. See the m4_arg(-renumber) argument for
|
|
further discussion.])
|
|
m4_p([dnl
|
|
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 m4_arg(-recnum) can result in serious performance degradation
|
|
for some applications and data sets.])
|
|
m4_p([dnl
|
|
It is an error to specify both m4_arg(-dup) and m4_arg(-recnum).])])
|
|
|
|
m4_tag([-renumber], [dnl
|
|
Specifying the m4_arg(-renumber) 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.
|
|
m4_p([dnl
|
|
Using the m4_tcl_db_put or m4_tcl_dbc_put 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.])
|
|
m4_p([dnl
|
|
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.])
|
|
m4_p([dnl
|
|
For these reasons, concurrent access to a Recno database with the
|
|
m4_arg(-renumber) flag specified may be largely meaningless, although it
|
|
is supported.])])
|
|
|
|
m4_tag([-snapshot], [dnl
|
|
This argument specifies that any specified m4_arg(-source) file be read
|
|
in its entirety when the database is opened. If this argument is not
|
|
specified, the m4_arg(-source) file may be read lazily.])
|
|
|
|
m4_tag([-source file], [dnl
|
|
Set the underlying source file for the Recno access method. The purpose
|
|
of the m4_arg(-source) file is to provide fast access and modification
|
|
to databases that are normally stored as flat text files.
|
|
m4_p([dnl
|
|
If the m4_arg(-source) 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 m4_arg(-delim). For example, standard UNIX byte stream
|
|
files can be interpreted as a sequence of variable length records
|
|
separated by m4_htmlquote(newline) characters.])
|
|
m4_p([dnl
|
|
In addition, when cached data would normally be written back to the
|
|
underlying database file (for example, when the m4_tcl_db_close or
|
|
m4_tcl_db_sync commands are called), the in-memory copy of the database
|
|
will be written back to the m4_arg(-source) file.])
|
|
m4_p([dnl
|
|
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.
|
|
m4_bold([dnl
|
|
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 m4_tcl_db_open call. See the m4_arg(-snapshot)
|
|
argument for more information.])])
|
|
m4_p([m4_bold([dnl
|
|
Reading and writing the backing source file specified by m4_arg(-source)
|
|
cannot be transaction protected because it involves filesystem
|
|
operations that are not part of the m4_db transaction methodology.])
|
|
For this reason, if a temporary database is used to hold the records,
|
|
it is possible to lose the contents of the m4_arg(-file) 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
|
|
m4_arg(file) argument to m4_tcl_db_open, normal database recovery on
|
|
that file can be used to prevent information loss, although it is still
|
|
possible that the contents of m4_arg(-source) will be lost if the system
|
|
crashes.])
|
|
m4_p([dnl
|
|
The m4_arg(-source) file must already exist (but may be zero-length) when
|
|
m4_tcl_db_open is called.])
|
|
m4_p([dnl
|
|
It is not an error to specify a read-only m4_arg(-source) 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 m4_tcl_db_close or m4_tcl_db_sync commands will fail, of course.
|
|
Specify the m4_arg(-nosync) argument to the m4_tcl_db_close command will
|
|
stop it from attempting to write the changes to the backing file; instead,
|
|
they will be silently discarded.])
|
|
m4_p([dnl
|
|
For all of the previous reasons, the m4_arg(-source) file is generally
|
|
used to specify databases that are read-only for m4_db applications,
|
|
and that are either generated on the fly by software tools, or modified
|
|
using a different mechanism such as a text editor.])])
|
|
|
|
m4_tag([-truncate], [dnl
|
|
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.
|
|
m4_p([dnl
|
|
The m4_arg(-truncate) argument cannot be transaction-protected, and it is
|
|
an error to specify it in a transaction-protected environment.])])
|
|
|
|
m4_tcl_txnopt(auto)
|
|
|
|
m4_tag([--], [Mark the end of the command arguments.])
|
|
|
|
m4_tag([file], [dnl
|
|
The name of a single physical file on disk that will be used to back the
|
|
database.])
|
|
|
|
m4_tag([database], [dnl
|
|
The m4_arg(database) 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
|
|
m4_arg(database) name.
|
|
m4_p([dnl
|
|
Applications opening multiple databases in a single file will almost
|
|
certainly need to create a shared database environment. See
|
|
m4_link(M4RELDIR/ref/am/opensub, [Opening multiple databases in a single
|
|
file]) for more information.])])
|
|
|
|
m4_tagend
|
|
|
|
m4_p([dnl
|
|
The m4_tcl_db_open command returns a database handle on success.])
|
|
|
|
m4_tcl_ret_error
|
|
|
|
m4_page_footer
|