[Contents]

6. Berkeley DB Module Functions Reference

6.1. Open

DB = bdb::Open(DataBase,type,flags,unixmode)

This function opens a database and returns a handle to it. This handle is a string of four or eight bytes on 32bit and 64bit machines. The actual value of this string contains the bytes of the pointer to the opened database structure that the Berkeley subsystem returns. Pass this variable as argument to subsequent database handling functions and better do not play around with it. Altering it will almost certainly result process failure or more serious damage. You can copy this value from one variable to another, pass it to user defined functions.

Do not depend on the actual value of the handle as later versions of the module may alter the way it handles the database handles.

The argument DataBase should be a string specifying the name of the database file. This is either an absolute file name, or a relative file name. The actual location of the database file depends on the configuration of the underlying Berkeley DB system.

The argument type specifies the type of the database. This can be one of the followings:

• Bdb::Btree
• Bdb::Hash
• Bdb::Recno
• Bdb::Queue
• Bdb::Unknown

You most probably want to use Bdb::Btree. The constant Bdb::Unknown can be used when opening an already existing database file. Bdb::Btree opens or creates a database using the B-Tree indexing structure. Bdb::Hash opens or creates a database using Hash indexing structure. Bdb::Recno opens or creates a "Recno" type database. Bdb::Queue opens a queue type database.

The argument flags can specify certain parameters how to open the database file. This value can be zero or some of the following constants defined in bdb.bas connected using the numeric operator And:

• Bdb::Create create the database file if it did not exist.
• Bdb::NoMap do not map this file into memory.
• Bdb::RdOnly open the database read only.
• Bdb::Thread return a database handle, which can be used in multiple threads. Because ScriptBasic interpreter threads do not share Berkeley DB handles you need not use this value.
• Bdb::Trunc Logically truncate the database if it exists, i.e., behave as if the database were just created, discarding any previous contents.

The argument unixmode specifies the UNIX level file access control bits. On Windows NT it is ignored.

The flags and the Unix mode parameters are optional.

If the database can not be opened for some reason an error is raised that can be captured using the statement on error goto.

When opening a database the module automatically creates a cursor for that database. If there is a transaction started before calling the function bdb::open the module automatically creates a new Berkeley DB transaction and creates the cursor under the transaction.

When a transaction is started, committed or aborted all opened database cursors are closed and reopened with a new transaction or without transaction.