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