The module comes in source form or as compiled binary. Binary is usually available for the Win32 platforms and for Linux in Debian and RedHat packages only. The compilation of the source code is simple. Compile the source files to a .dll or to .so shared library. To help compile the module under Win32 the Visual C++ workspace and project files are delivered in the source distribution. To successfully link the application you need the static library version of the Berkeley DB system. The Windows NT version linkable using the Microsoft Visual C++ linker can be downloaded from the ScriptBasic web site in a separate ZIP file along with the library files of the other modules.
The library file is called `libdb30s.lib'. If for some reason you miss this file or perhaps you want to try (at your own risk) a newer version of the Berkeley DB than provided with the source you should download the Berkeley source distribution from Sleepy Cat Software. They usually provide Visual C++ v5.0 workspace and project files.
To use Visual C++ v6.0 you have to start the integrated environment and open the workspace. The Visual C++ development environment automatically converts the workspace and the projects. Note that you should not try to start Visual C++ v6.0 clicking on a v5.0 workspace file. In that case Visual C++ starts to convert the workspace and then crashes. So start the development environment from the start menu and use the menu "file/open workspace".
If you do not have the project file for the module, create a project file that creates a Win32 dll. Specify /nodefaultlib:"LIBCMT" in the project link options.
The source distribution of the Windows version compiles the module when ScriptBasic is built. Note that this `Makefile.nt' is generated from `Makefile.nt.jam' during executing the command file `precompile'.
On UNIX systems you have to download the Berkeley DB from its original location. Note that the module uses a specific version and may not work with further versions. However we will try to follow the version updates of the DB system.
Before starting to compile the module you have to configure and compile the Berkeley DB library file that results the files db.h and libdb.a (among other files, but we specifically need these two files). These are usually created in the directory ~/db-3.0.55/build_unix/. Copy these files into the ScriptBasic source directory ~/scriba/source/extensions/berkeley_db/.
After you have successfully performed these operations compile and install the module typing make install.
The compiled module contains a dynamic load binary file and a basic include file named `bdb.bas'. If your configuration is different from the default the include file `bdb.bas' should be placed in a module include directory file configured in the configuration file. The configuration file usually named scriba.conf.unix.lsp should include a line
include "/etc/scriba/include/"
defining the include files location for the modules and other generally used include files. The actual directory can be different.
The binary part of the module should be placed in another directory specified in the configuration file, like
module "/usr/scriba/modules/"
There can be more than one include and module statements in the configuration file. In that case the interpreter searches the directories in the order they are specified until the include file or the module is found.
Before starting any program using the module bdb you almost certainly have to edit the ScriptBasic configuration file. The keys in the configuration file included in the bdb configuration group control the initialization and use of the underlying Berkeley Database module.
We describe the keys here briefly in a manner that allows most implementations to start using the database from ScriptBasic programs. However at some cases we refer to the original documentation, deep understanding of the behavior of the software can be gained reading the original documentation.
The configuration keys the module supports:
home This key defines the database home directory. This string is passed to the db_appinit function as argument db_home. If this value is specified the databases will be located in this directory. Use of this configuration parameter gives you flexibility to move your actual database files. CGI scripts may also gain some level of security not containing the actual path of the database files.
data This key defines where the Berkeley DB stored the database files.
log This key defines where the Berkeley DB stores the database log files.
temp This key defines where the Berkeley DB stores the temporary files.
limits This key is a group that contains sub-key and their values. These sub-keys define the limits that the system manager sets for the local installation of the Berkeley DB.
Note that although these values are numeric they should be specified between " characters as string. This is because ScriptBasic v1.0build19 does not deliver support function for the external modules to access numeric configuration parameters. (n.b. older versions of ScriptBasic did not support numeric configuration parameters at all.)
lg_max The maximum size of a single file in the log, in bytes. This value is passed to the log subsystem in the variable dbenv.lg_max.
mp_mmapsize Files that are opened read-only in the pool (and that satisfy a few other criteria) are, by default, mapped into the process address space instead of being copied into the local cache. This can result in better-than-usual performance, as available virtual memory is normally much larger than the local cache, and page faults are faster than page copying on many systems. However, in the presence of limited virtual memory it can cause resource starvation, and in the presence of large databases, it can result in immense process sizes. If mp_mmapsize is non-zero, it specifies the maximum file size, in bytes, for a file to be mapped into the process address space. By default, it is set to 10Mb.
mp_size The suggested size of the shared memory buffer pool, i.e., the cache, in bytes. This should be the size of the normal working data set of the application, with some small amount of additional memory for unusual situations. (Note, the working set is not the same as the number of simultaneously referenced pages, and should be quite a bit larger!) The default cache size is 128K bytes, and may not be specified as less than 20K bytes.
tx_max The maximum number of simultaneous transactions that are supported. This bounds the size of backing files and is used to derive limits for the size of the lock region and log files. When there are more than tx_max concurrent transactions, calls to txn_begin may cause backing files to grow. If tx_max is 0, a default value is used.
The bdb module provides a very simple interface to the BASIC programmer. There is only a single transaction allowed at a time and there is no support for transaction hierarchy. However the single transaction at the level of the BASIC program is supported creating a unique Berkeley DB transaction for each opened table.
lk_max The maximum number of locks to be held or requested in the table. This value is used by the Berkeley DB function lock_open to estimate how much space to allocate for various lock-table data structures. If lk_max is 0, a default value is used.
The following keys define the behavior of the deadlock detector. If any of these keys are used the deadlock detector runs when a conflict occurs and this key defines which transaction should be aborted.
lockstrategy This configuration key defines what lock strategy the Berkeley DB should use. The value can be one of the keywords: default, oldest, random, youngest.
flags This key is a group that contains sub-key and their values. These sub-keys define certain flags for the operation of the Berkeley DB. Any of the keys may exist in the configuration having the value yes or having any other value. A missing key has the same effect as having the key with any value other than yes.
In the following lines we list the configuration keys and their respective Berkeley DB constants that are used to pass to the function DBENV->open.
create --> DB_CREATE
init_cdb --> DB_INIT_CDB
init_lock --> DB_INIT_LOCK
init_log --> DB_INIT_LOG
init_mpool --> DB_INIT_MPOOL
init_txn --> DB_INIT_TXN
private --> DB_PRIVATE
nommap --> DB_NOMMAP
recover --> DB_RECOVER
recover_fatal --> DB_RECOVER_FATAL
thread --> DB_THREAD
txn_nosync --> DB_TXN_NOSYNC
use_environ --> DB_USE_ENVIRON
use_environ_root --> DB_USE_ENVIRON_ROOT
lockdown --> DB_LOCKDOWN
system_mem --> DB_SYSTEM_MEM
mode This configuration value may specify the access value of the created databases under UNIX when the mode value is not specified in the command bdb::open. If not specified the value zero is used. Because this mode value grants no access to anyone the underlying Berkeley Database ignores the value and uses the default file mode instead.
To specify the value you have to specify the access value as decimal number between " double-quote characters.