/ 
BerkeleyDB-0.05
River stage two • 30 direct dependents • 41 total dependents
/ BerkeleyDB

NAME

BerkeleyDB - Perl extension for Berkeley DB version 2

SYNOPSIS

use BerkeleyDB;

$env = new BerkeleyDB::Env [OPTIONS] ;

$db  = tie %hash, 'BerkeleyDB::Hash', [OPTIONS] ;
$db  = new BerkeleyDB::Hash [OPTIONS] ;

$db  = tie %hash, 'BerkeleyDB::Btree', [OPTIONS] ;
$db  = new BerkeleyDB::Btree [OPTIONS] ;

$db  = tie %hash, 'BerkeleyDB::Recno', [OPTIONS] ;
$db  = new BerkeleyDB::Recno [OPTIONS] ;

$db  = tie %hash, 'BerkeleyDB::Unknown', [OPTIONS] ;
$db  = new BerkeleyDB::Unknown [OPTIONS] ;

$hash{$key} = $value ;
$value = $hash{$key} ;
each %hash ;
keys %hash ;
values %hash ;

$status = $db->db_get()
$status = $db->db_put() ;
$status = $db->db_del() ;
$status = $db->db_sync() ;
$hash_ref = $db->db_stat() ;
$type = $db->type() ;
$type = $db->status() ;
$type = $db->byteswapped() ;

($flag, $old_offset, $old_length) = $db->partial_set($offset, $length) ;
($flag, $old_offset, $old_length) = $db->partial_clear() ;

$cursor = $db->db_cursor() ;
$status = $cursor->c_get() ;
$status = $cursor->c_put() ;
$status = $cursor->c_del() ;
$status = $cursor->status() ;

$txn_mgr = $env->TxnMgr();
$status = $txn_mgr->txn_checkpoint()
$hash_ref = $txn_mgr->txn_stat()

$txn = $txn_mgr->txn_begin() ;
$status = $txn->txn_prepare()
$status = $txn->txn_commit()
$status = $txn->txn_abort()
$status = $txn->txn_id()

$BerkeleyDB::Error
$BerkeleyDB::db_version

DESCRIPTION

NOTE: This document is still under construction, so it is likely to be incomplete.

This Perl module provides an interface to most of the functionality available in Berkeley DB version 2.

The reader is expected to be familiar with the Berkeley DB documentation. The db_appinit, db_cursor, db_open and db_txn man pages are particularly relevant.

The interface to Berkeley DB is implemented with a number of Perl classes.

ENVIRONMENT CLASS

The equivalent of the Berkeley DB function db_appinit. It is only needed when you want to make use of locking, logging or transactions.

Synopsis

$env = new BerkeleyDB::Env 
         [ -Home         => $path, ]
         [ -Config       => { name => value, name => value }, ]
         [ -ErrFile      => filename or filehandle, ]
         [ -ErrPrefix    => "string", ]
         [ -Flags        => number, ]
         [ -Verbose      => boolean, ]
         [ -LockMax      => number, ]
         [ -LogMax       => number, ]
         [ -TxnMax       => number, ]
-Home

Directory name

-Config

A reference to a hash. Valid keys are:

DB_DATA_DIR
DB_LOG_DIR
DB_TMP_DIR

Values are directory names.

-ErrFile

Expects either the name of a file or a reference to a filehandle.

-ErrPrefix
-Flags

The Flags option can consist of one of more of the following or'ed together.

DB_CREATE
DB_INIT_LOCK
DB_INIT_LOG
DB_INIT_MPOOL
DB_INIT_TXN
DB_MPOOL_PRIVATE
DB_NOMMAP
DB_RECOVER
DB_RECOVER_FATAL
DB_THREAD
DB_TXN_NOSYNC
DB_USE_ENVIRON
DB_USE_ENVIRON_ROOT
-Verbose
-LockMax
-LogMax
-TxnMax

Methods

The environment class has the following methods:

txn_begin
$txn = $env->txn_begin() ;
errPrefix
$db->errPrefix("string") ;

THE HASH CLASS

The equivalent of db_open with type DB_HASH. Two forms

$db = new BerkeleyDB::Hash
            [ -Filename      => "filename" ]
            [ -Flags         => ]
            [ -Property      => ]
            [ -Mode          => ]
            [ -Cachesize     => ]
            [ -Lorder        => ]
            [ -Pagesize      => ]
            [ -Env           => ]
            [ -Txn           => ]
            [ -Ffactor       => ]
            [ -Nelem         => ]
            [ -Hash          => ]

and this

$db = tie %hash, 'BerkeleyDB::Hash', OPTIONS

where OPTIONS are the same as for the new constructor. In addition to the standard set of options (see "COMMON OPTIONS") BerkeleyDB::Hash supports these:

-Property

Used to specify additional flags.

DB_DUP
-Ffactor
-Nelem
-Hash

Methods

See "COMMON DATABASE METHODS".

A Simple Hash Example

use strict ;
use BerkeleyDB ;

my %hash ;
my $filename = "database" ;
tie %hash, 'BerkeleyDB::Hash',
            -Filename  => $filename,
            -Flags     => DB_CREATE
    or die "Cannot open file $filename: $! $BerkeleyDB::Error\n" ;

$hash{"fred"} = "barney" ;
$hash{"joe"} = "harry" ;

untie %hash ;

THE BTREE CLASS

Methods

See "COMMON DATABASE METHODS".

Btree supports one extra method

$ref = $db->db_stat() ;

THE RECNO CLASS

Not implemented yet.

COMMON OPTIONS

All database access class constructors support the common set of parameters defined below. All parameters are optional.

-Filename

The database filename. If no filename is specified, the database will be created in-memory, and removed once the program terminates.

-Flags

Specify how the database will be opened/created. The valid flags are:

DB_CREATE
DB_NOMMAP
DB_RDONLY
DB_THREAD
DB_TRUNCATE

The default is none.

-Mode

Determines the file protection when the database is created. Defaults to 0666.

-Cachesize

A suggested maximum size for the memory pool cache. Defaults to an appropriate value.

-Lorder

The byte order for integers. For example the big endian orderis 4321, and little endian is 1234. Defaults to the ordering of the host where the Berkeley DB library was built.

-Pagesize

The size of the pages used to hold items in the database, in bytes. The minimum is 512 bytes and the maximum is 64K bytes.

Defaults to a page size based on the underlying filesystem I/O block size.

-Env

When working under a Berkeley DB environment, this parameter

Defaults to no environment.

-Txn

If the database connection is to be under the control of a transaction, this parameter must be an object returned from

COMMON DATABASE METHODS

All the database interfaces support a common set of methods.

$status = $db->db_get($key, $value [, $flags])

$status = $db->db_put($key, $value [, $flags])

$status = $db->db_del($key [, $flags])

$status = $db->db_sync()

$cursor = $db->db_cursor()

Creates a cursor object. See CURSORS for details of the methods available when working with cursore.

$fd = $db->db_fd()

($flag, $old_offset, $old_length) = $db->partial_set($offset, $length) ;

($flag, $old_offset, $old_length) = $db->partial_clear() ;

When the "tie" interface is used, reading from and writing to the database is achieved via the tied hash.

CURSORS

A cursor is created with the db_cursor

$status = $cursor->c_get($key, $value [,$flags])

$status = $cursor->c_put($key, $value [,$flags])

$status = $cursor->c_del($key, [,$flags])

TRANSACTIONS

EXAMPLES

todo.

HISTORY

See the Changes file.

AVAILABILITY

The most recent version of BerkeleyDB can always be found on CPAN (see "CPAN" in perlmod for details), in the directory modules/by-module/BerkeleyDB.

The official web site for Berkeley DB is http://www.sleepycat.com/db. The ftp equivalent is ftp.sleepycat.com:/pub.

COPYRIGHT

Copyright (c) 1997/8 Paul Marquess. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

Although BerkeleyDB is covered by the Perl license, the library it makes use of, namely Berkeley DB, is not. Berkeley DB has its own copyright and its own license. Please take the time to read it.

Here are are few words taken from the Berkeley DB FAQ (at http://www.sleepycat.com) regarding the license:

Do I have to license DB to use it in Perl scripts?

No. The Berkeley DB license requires that software that uses
Berkeley DB be freely redistributable. In the case of Perl, that
software is Perl, and not your scripts. Any Perl scripts that you
write are your property, including scripts that make use of
Berkeley DB. Neither the Perl license nor the Berkeley DB license
place any restriction on what you may do with them.

If you are in any doubt about the license situation, contact either the Berkeley DB authors or the author of BerkeleyDB. See "AUTHOR" for details.

AUTHOR

Paul Marquess <pmarquess@bfsec.bt.co.uk<gt>.

Questions about Berkeley DB may be addressed to <db@sleepycat.com<gt>.

SEE ALSO

perl(1), DB_File, Berkeley DB.