Dbopen is the library interface to database files. The supported file format are btree, hashed ans UNIX file-oriented.
The btree format is a representation of a sorted, balanced tree structure.
The hashed format is an extensible, dynamic hashing scheme.
The flat-file format is a byte stream file with fixed or variable length records.
The formats and file format-specific information is described in detail in the manual pages included with the dbopen package.
Dbopen was written by Keith Bostic (bostic@cs.berkeley.edu) of the University of California at Berkeley.
Unlike most traditional Unix "db" implementations, both key and data byte strings may be of essentially unlimited length.
The Tcl interface to dbopen was written by NeoSoft, and is based on a Tcl/dbopen interface written by Poul-Henning Kamp (phk@data.fls.dk).
NeoSoft added shared and exclusive file locking, non-blocking access, "db forall" and "db searchall" access methods, code cleanup and reformatting, plus some other stuff.
A summary of the dbopen function and methods follows:
Opens the specified database file <file> using <mode>. A dbopen session ID is returned.
<type> can be "hash" for a hashtable, "btree" for a btree. If the file already exists, you can set <type> to "unknown", and the package will determine the correct type. In fact, if you do not specify a type at all, it will default to "unknown". It is an error to use an unknown type to create a new file--it must already exist.
<flags> is a subset of these chars: (default: w)
Notice: DB 2.X files will correctly handle locking without the use of the locking switches listed above. You may still use the switches above, but they will be ignored. The current behavior is as follows:
When a process opens a file, it will "snapshot" the file, and for the entire session, it will seem as though no other process has access to the file. If two processes write out the same key, the file that "syncs" or "closes" the file last will win out over the other one. Please use transactions to ensure that your changes are correctly reflected.
<mode> is a octal integer used for creating files. (default 644)
NOT CURRENTLY SUPPORTED.
"db get" will try to get the value addressed by <key>.
If <var> is specified, the result will be written into it, and the return value will be a boolean: 1 for success, 0 for failure.
If a variable is not specified, found value will be returned, and failures will result in a Tcl error being generated.
"db put" stores <data> under <key>. 'replace' is the default mode. "db put" returns an error on failure.
"insert" is only valid in the case of btrees. In this case, multiple key-value pairs may have the same key.
Delete the entry with the specified <key>.
If the record is deleted, "1" is returned, else "0" is returned.
If the record wasn't deleted, it's probably because the <key> wasn't there to begin with.
Sequential read.
<flag> can be:
if <var> is specified: if no keys found: <var> is set to "" and "0" is returned else <var> is set to the key and "1" is returned. If <var> is not specified, if no keys were found, "" is returned, else the key is returned.
executes <proc> for all keys found in the database.
The actual key_value is available in $<key_var>.
Example:
db forall $db key { puts stdout "$key: [db get $db $key]" }
db searchall $db key -glob "*foo*" { puts stdout "$key: [db get $key]" }db sync <sess> causes the database to be synced to disk.
$Id: db.html,v 1.1.1.1 1999/03/31 20:34:36 damon Exp $