Database Commands

> berkdb open [-env env]
    [-btree|-hash|-recno|-queue|-unknown]
    [-create] [-excl] [-nommap] [-rdonly] [-truncate] [-mode mode] [-errfile filename]
    [-dup] [-dupsort] [-recnum] [-renumber] [-revsplitoff] [-snapshot]
    [-extent size]
    [-ffactor density]
    [-nelem size]
    [-lorder order]
    [-delim delim]
    [-len len]
    [-pad pad]
    [-source file]
    [-minkey minkey]
    [-cachesize {gbytes bytes ncaches}]
    [-pagesize pagesize]
    [--]
    [filename [subdbname]]

This command will invoke the db_create function.  If the command is given the -env option, then we will accordingly creating the database within the context of that environment.  After it successfully gets a handle to a database, we bind it to a new Tcl command of the form dbX, where X is an integer starting at 0 (e.g. db0, db1, etc).  We use the Tcl_CreateObjCommand()  to create the top level database function.  It is through this handle that the user can access all of the commands described in the Database Commands section.  Internally, the database handle is sent as the ClientData portion of the new command set so that all future database calls access the appropriate handle.

After parsing all of the optional arguments affecting the setup of the database and making the appropriate calls to DB to manipulate those values, we open the database for the user. It  translates to the DB->open method call after parsing all of the various optional arguments.  We automatically set the DB_THREAD flag.  The arguments are:

• -- - Terminate the list of options and use remaining arguments as the file or subdb names (thus allowing the use of filenames beginning with a dash '-')
• -btree - DB_BTREE database
• -hash -  DB_HASH database
• -recno  - DB_RECNO database
• -queue - DB_QUEUE database
• -create selects the DB_CREATE flag  to create underlying files
• -excl selects the DB_EXCL flag  to exclusively create underlying files
• -nommap selects the DB_NOMMAP flag to forbid mmaping of files
• -rdonly selects the DB_RDONLY flag for opening in read-only mode
• -truncate selects the DB_TRUNCATE flag to truncate the database
• -mode mode specifies the mode for created files
• -errfile specifies the error file to use for this environment to filename by calling DB->set_errfile. If the file already exists then we will append to the end of the file
• -dup selects the DB_DUP flag to permit duplicates in the database
• -dupsort selects the DB_DUPSORT flag to support sorted duplicates
• -recnum selects the DB_RECNUM flag to support record numbers in btrees
• -renumber selects the DB_RENUMBER flag to support mutable record numbers
• -revsplitoff selects the DB_REVSPLITOFF flag to suppress reverse splitting of pages on deletion
• -snapshot selects the DB_SNAPSHOT flag to support database snapshots
• -extent sets the size of a Queue database extent to the given size using the DB->set_q_extentsize method
• -ffactor sets the hash table key density to the given density using the DB->set_h_ffactor method
• -nelem sets the hash table size estimate to the given size using the DB->set_h_nelem method
• -lorder sets the byte order for integers stored in the database meta-data to the given order using the DB->set_lorder method
• -delim sets the delimiting byte for variable length records to delim using the DB->set_re_delim method
• -len sets the length of fixed-length records to len using the DB->set_re_len method
• -pad sets the pad character used for fixed length records to pad  using the DB->set_re_pad method
• -source sets the backing source file name to file using the DB->set_re_source method
• -minkey sets the minimum number of keys per Btree page to minkey using the DB->set_bt_minkey method
• -cachesize sets the size of the database cache to the size  specified by gbytes and bytes, broken up into ncaches number of caches using the DB->set_cachesize method
• -pagesize sets the size of the database page to pagesize using the DB->set_pagesize method
• filename indicates the name of the database
• subdbname indicate the name of the sub-database

This command will invoke the DB->upgrade function.  If the command is given the -env option, then we will accordingly upgrade the database filename within the context of that environment. The -dupsort option selects the DB_DUPSORT flag for upgrading. The use of -- terminates the list of options, thus allowing filenames beginning with a dash.

This command will invoke the DB->verify function.  If the command is given the -env option, then we will accordingly verify the database filename within the context of that environment.  The use of -- terminates the list of options, thus allowing filenames beginning with a dash.

This command will invoke the db_join function.  After it successfully joins a database, we bind it to a new Tcl command of the form dbN.cX, where X is an integer starting at 0 (e.g. db2.c0, db3.c0, etc).  We use the Tcl_CreateObjCommand()  to create the top level database function.  It is through this cursor handle that the user can access the joined data items.

The options are:

• -nosort - This flag causes DB not to sort the cursors based on the number of data items they reference.  It results in the DB_JOIN_NOSORT flag being set.

This command performs a join operation on the keys specified and returns a list of the joined {key data} pairs.

The options are:

• -nosort This flag causes DB not to sort the cursors based on the number of data items they reference.  It results in the DB_JOIN_NOSORT flag being set.

This command returns the range for the given key.  It returns a list of 3 double elements of the form {less equal greater} where less is the percentage of keys less than the given key, equal is the percentage equal to the given key and greater is the percentage greater than the given key.  If the -txn option is specified it performs this operation under transaction protection.

The undocumented options are:

• -nodupdata This flag causes DB not to insert the key/data pair if it already exists, that is, both the key and data items are already in the database. The -nodupdata flag may only be specified if the underlying database has been configured to support sorted duplicates.

The undocumented options are:

• -cachedcounts This flag causes DB to return the cached key/record counts, similar to the DB_CACHED_COUNTS flags to DB->stat.

The undocumented options are:

• -nodupdata This flag causes DB not to insert the key/data pair if it already exists, that is, both the key and data items are already in the database. The -nodupdata flag may only be specified if the underlying database has been configured to support sorted duplicates.