=head1 NAME

BerkeleyDB - Perl extension for Berkeley DB version 2

=head1 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


=head1 DESCRIPTION

B<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.

=head1 ENVIRONMENT CLASS

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

=head2 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, ]



=over 5

=item -Home

Directory name

=item -Config

A reference to a hash. Valid keys are:

    DB_DATA_DIR
    DB_LOG_DIR
    DB_TMP_DIR

Values are directory names.


=item -ErrFile

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

=item -ErrPrefix

=item -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

=item -Verbose

=item -LockMax

=item -LogMax

=item -TxnMax

=back

=head2 Methods

The environment class has the following methods:

=over 5

=item txn_begin

    $txn = $env->txn_begin() ;

=item errPrefix

    $db->errPrefix("string") ;


=back

=head1 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 L<COMMON OPTIONS>) BerkeleyDB::Hash
supports these:

=over 5

=item -Property

Used to specify additional flags.

    DB_DUP

=item -Ffactor

=item -Nelem

=item -Hash

=back


=head2 Methods

See L<COMMON DATABASE METHODS>.


=head2 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 ;

=head1 THE BTREE CLASS

=head2 Methods

See L<COMMON DATABASE METHODS>.

Btree supports one extra method

    $ref = $db->db_stat() ;

=head1 THE RECNO CLASS

Not implemented yet.

=head1 COMMON OPTIONS

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

=over 5

=item -Filename

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

=item -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.

=item -Mode

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

=item -Cachesize

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

=item -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.

=item -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.

=item -Env

When working under a Berkeley DB environment, this parameter 

Defaults to no environment.

=item -Txn

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


=back

=head1 COMMON DATABASE METHODS

All the database interfaces support a common set of methods.

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

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

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

=head2 $status = $db->db_sync()

=head2 $cursor = $db->db_cursor()

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

=head2 $fd = $db->db_fd()

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

=head2 ($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.

=head1 CURSORS

A cursor is created with the C<db_cursor>


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

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

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


=head1 TRANSACTIONS

=head1 EXAMPLES

todo.

=head1 HISTORY
 
See the Changes file.

=head1 AVAILABILITY
 
The most recent version of B<BerkeleyDB> can always be found on CPAN
(see L<perlmod/CPAN> for details), in the directory
F<modules/by-module/BerkeleyDB>.

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

=head1 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 B<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 L<"AUTHOR"> for details.


=head1 AUTHOR

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

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

=head1 SEE ALSO

perl(1), DB_File, Berkeley DB.

=cut
