berkeleydb.pod.p

File system using stacked.

    tie %h, "BerkeleyDB::Hash", 
        -Filename   => $filename, 
	-Property   => DB_DUP|DB_DUPSORT,
    	-DupCompare => \&compare,
	...

=back


=head2 Methods

B<BerkeleyDB::Hash> only supports the standard database methods.
See L<COMMON DATABASE METHODS>.

=head2 A Simple Tied Hash Example

## simpleHash

here is the output:

    Banana Exists
    
    orange -> orange
    tomato -> red
    banana -> yellow

Note that the like ordinary associative arrays, the order of the keys
retrieved from a Hash database are in an apparently random order.

=head2 Another Simple Hash Example

Do the same as the previous example but not using tie.

## simpleHash2

=head2 Duplicate keys

The code below is a variation on the examples above. This time the hash has
been inverted. The key this time is colour and the value is the fruit name.
The B<DB_DUP> flag has been specified to allow duplicates.

##dupHash

here is the output:

    orange -> orange
    yellow -> banana
    red -> apple
    red -> tomato
    green -> banana
    green -> apple

=head2 Sorting Duplicate Keys

In the previous example, when there were duplicate keys, the values are
sorted in the order they are stored in. The code below is
identical to the previous example except the B<DB_DUPSORT> flag is
specified.

##dupSortHash

Notice that in the output below the duplicate values are sorted.

    orange -> orange
    yellow -> banana
    red -> apple
    red -> tomato
    green -> apple
    green -> banana

=head2 Custom Sorting Duplicate Keys

Another variation 

TODO

=head2 Changing the hash

TODO

=head2 Using db_stat

TODO

=head1 BerkeleyDB::Btree

Equivalent to calling B<db_open> with type B<DB_BTREE> in Berkeley DB 2.x and
calling B<db_create> followed by B<DB-E<gt>open> with type B<DB_BTREE> in
Berkeley DB 3.x or greater. 

Two forms of constructor are supported:


    $db = new BerkeleyDB::Btree
                [ -Filename      => "filename", ]
                [ -Subname       => "sub-database name", ]
                [ -Flags         => flags,]
                [ -Property      => flags,]
                [ -Mode          => number,]
                [ -Cachesize     => number,]
                [ -Lorder        => number,]
                [ -Pagesize      => number,]
                [ -Env           => $env,]
                [ -Txn           => $txn,]
                # BerkeleyDB::Btree specific
                [ -Minkey        => number,]
                [ -Compare       => code reference,]
                [ -DupCompare    => code reference,]
                [ -Prefix        => code reference,]

and this

    [$db =] tie %hash, 'BerkeleyDB::Btree', 
                [ -Filename      => "filename", ]
                [ -Subname       => "sub-database name", ]
                [ -Flags         => flags,]
                [ -Property      => flags,]
                [ -Mode          => number,]
                [ -Cachesize     => number,]
                [ -Lorder        => number,]
                [ -Pagesize      => number,]
                [ -Env           => $env,]
                [ -Txn           => $txn,]
                # BerkeleyDB::Btree specific
                [ -Minkey        => number,]
                [ -Compare       => code reference,]
                [ -DupCompare    => code reference,]
                [ -Prefix        => code reference,]

=head2 Options

In addition to the standard set of options (see L<COMMON OPTIONS>)
B<BerkeleyDB::Btree> supports these options:

=over 5

=item -Property

Used to specify extra flags when opening a database. The following
flags may be specified by logically OR'ing together one or more of the
following values:

B<DB_DUP>

When creating a new database, this flag enables the storing of duplicate
keys in the database. If B<DB_DUPSORT> is not specified as well, the
duplicates are stored in the order they are created in the database.

B<DB_DUPSORT>

Enables the sorting of duplicate keys in the database. Ignored if
B<DB_DUP> isn't also specified.

=item Minkey

TODO

=item Compare

Allow you to override the default sort order used in the database. See
L<"Changing the sort order"> for an example.

    sub compare
    {
	my ($key, $key2) = @_ ;
        ...
        # return  0 if $key1 eq $key2
        #        -1 if $key1 lt $key2
        #         1 if $key1 gt $key2
        return (-1 , 0 or 1) ;
    }

    tie %h, "BerkeleyDB::Hash", 
        -Filename   => $filename, 
    	-Compare    => \&compare,
	...

=item Prefix

    sub prefix
    {
	my ($key, $key2) = @_ ;
        ...
        # return number of bytes of $key2 which are 
        # necessary to determine that it is greater than $key1
        return $bytes ;
    }

    tie %h, "BerkeleyDB::Hash", 
        -Filename   => $filename, 
    	-Prefix     => \&prefix,
	...
=item DupCompare

    sub compare
    {
	my ($key, $key2) = @_ ;
        ...
        # return  0 if $key1 eq $key2
        #        -1 if $key1 lt $key2
        #         1 if $key1 gt $key2
        return (-1 , 0 or 1) ;
    }

    tie %h, "BerkeleyDB::Hash", 
        -Filename   => $filename, 
    	-DupCompare => \&compare,
	...

=back

=head2 Methods

B<BerkeleyDB::Btree> supports the following database methods.
See also L<COMMON DATABASE METHODS>.

All the methods below return 0 to indicate success.

=over 5

=item $status = $db->db_key_range($key, $less, $equal, $greater [, $flags])

Given a key, C<$key>, this method returns the proportion of keys less than 
C<$key> in C<$less>, the proportion equal to C<$key> in C<$equal> and the
proportion greater than C<$key> in C<$greater>.

The proportion is returned as a double in the range 0.0 to 1.0.

=back

=head2 A Simple Btree Example

The code below is a simple example of using a btree database.

## btreeSimple

Here is the output from the code above. The keys have been sorted using
Berkeley DB's default sorting algorithm.

    Smith
    Wall
    mouse


=head2 Changing the sort order

It is possible to supply your own sorting algorithm if the one that Berkeley
DB used isn't suitable. The code below is identical to the previous example
except for the case insensitive compare function.

## btreeSortOrder

Here is the output from the code above.

    mouse
    Smith
    Wall

There are a few point to bear in mind if you want to change the
ordering in a BTREE database:

=over 5

=item 1.

The new compare function must be specified when you create the database.

=item 2.

You cannot change the ordering once the database has been created. Thus
you must use the same compare function every time you access the
database.

=back 

=head2 Using db_stat

TODO

=head1 BerkeleyDB::Recno

Equivalent to calling B<db_open> with type B<DB_RECNO> in Berkeley DB 2.x and
calling B<db_create> followed by B<DB-E<gt>open> with type B<DB_RECNO> in
Berkeley DB 3.x or greater. 

Two forms of constructor are supported:

    $db = new BerkeleyDB::Recno
                [ -Filename      => "filename", ]
                [ -Subname       => "sub-database name", ]
                [ -Flags         => flags,]
                [ -Property      => flags,]
                [ -Mode          => number,]
                [ -Cachesize     => number,]
                [ -Lorder        => number,]
                [ -Pagesize      => number,]
                [ -Env           => $env,]
                [ -Txn           => $txn,]
                # BerkeleyDB::Recno specific
                [ -Delim           => byte,]
                [ -Len             => number,]
                [ -Pad             => byte,]
                [ -Source          => filename,]

and this

    [$db =] tie @arry, 'BerkeleyDB::Recno', 
                [ -Filename      => "filename", ]
                [ -Subname       => "sub-database name", ]
                [ -Flags         => flags,]
                [ -Property      => flags,]
                [ -Mode          => number,]
                [ -Cachesize     => number,]
                [ -Lorder        => number,]
                [ -Pagesize      => number,]
                [ -Env           => $env,]
                [ -Txn           => $txn,]
                # BerkeleyDB::Recno specific
                [ -Delim           => byte,]
                [ -Len             => number,]
                [ -Pad             => byte,]
                [ -Source          => filename,]

=head2 A Recno Example

Here is a simple example that uses RECNO (if you are using a version 
of Perl earlier than 5.004_57 this example won't work -- see 
L<Extra RECNO Methods> for a workaround).

## simpleRecno

Here is the output from the script:

    The array contains 5 entries
    popped black
    shifted white
    Element 1 Exists with value blue
    The last element is green
    The 2nd last element is yellow

=head1 BerkeleyDB::Queue

Equivalent to calling B<db_create> followed by B<DB-E<gt>open> with
type B<DB_QUEUE> in Berkeley DB 3.x or greater. This database format
isn't available if you use Berkeley DB 2.x.

Two forms of constructor are supported:

    $db = new BerkeleyDB::Queue
                [ -Filename      => "filename", ]
                [ -Subname       => "sub-database name", ]
                [ -Flags         => flags,]
                [ -Property      => flags,]
                [ -Mode          => number,]
                [ -Cachesize     => number,]
                [ -Lorder        => number,]
                [ -Pagesize      => number,]
                [ -Env           => $env,]
                [ -Txn           => $txn,]
                # BerkeleyDB::Queue specific
                [ -Len             => number,]
                [ -Pad             => byte,]
                [ -ExtentSize    => number, ]

and this

    [$db =] tie @arry, 'BerkeleyDB::Queue', 
                [ -Filename      => "filename", ]
                [ -Subname       => "sub-database name", ]
                [ -Flags         => flags,]
                [ -Property      => flags,]
                [ -Mode          => number,]
                [ -Cachesize     => number,]
                [ -Lorder        => number,]
                [ -Pagesize      => number,]
                [ -Env           => $env,]
                [ -Txn           => $txn,]
                # BerkeleyDB::Queue specific
                [ -Len             => number,]
                [ -Pad             => byte,]


=head1 BerkeleyDB::Unknown

This class is used to open an existing database. 

Equivalent to calling B<db_open> with type B<DB_UNKNOWN> in Berkeley DB 2.x and
calling B<db_create> followed by B<DB-E<gt>open> with type B<DB_UNKNOWN> in
Berkeley DB 3.x or greater. 

The constructor looks like this:

    $db = new BerkeleyDB::Unknown
                [ -Filename      => "filename", ]
                [ -Subname       => "sub-database name", ]
                [ -Flags         => flags,]
                [ -Property      => flags,]
                [ -Mode          => number,]
                [ -Cachesize     => number,]
                [ -Lorder        => number,]
                [ -Pagesize      => number,]
                [ -Env           => $env,]
                [ -Txn           => $txn,]


=head2 An example 

=head1 COMMON OPTIONS

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

=over 5

=item -Filename

The database filename. If no filename is specified, a temporary file will
be created and removed once the program terminates.

=item -Subname

Specifies the name of the sub-database to open.
This option is only valid if you are using Berkeley DB 3.x or greater.

=item -Flags

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

B<DB_CREATE>

Create any underlying files, as necessary. If the files do not already
exist and the B<DB_CREATE> flag is not specified, the call will fail.

B<DB_NOMMAP>

Not supported by BerkeleyDB.

B<DB_RDONLY>

Opens the database in read-only mode.

B<DB_THREAD>

Not supported by BerkeleyDB.

B<DB_TRUNCATE>

If the database file already exists, remove all the data before
opening it.

=item -Mode

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

=item -Cachesize

=item -Lorder

=item -Pagesize

=item -Env

When working under a Berkeley DB environment, this parameter

Defaults to no environment.

=item -Txn

TODO.

=back

=head1 COMMON DATABASE METHODS

All the database interfaces support the common set of methods defined
below.

All the methods below return 0 to indicate success.

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

Given a key (C<$key>) this method reads the value associated with it
from the database. If it exists, the value read from the database is
returned in the C<$value> parameter.

The B<$flags> parameter is optional. If present, it must be set to B<one>
of the following values:

=over 5

=item B<DB_GET_BOTH>

When the B<DB_GET_BOTH> flag is specified, B<db_get> checks for the
existence of B<both> the C<$key> B<and> C<$value> in the database.

=item B<DB_SET_RECNO>

TODO.

=back

In addition, the following value may be set by logically OR'ing it into
the B<$flags> parameter:

=over 5

=item B<DB_RMW>

TODO

=back


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

Stores a key/value pair in the database.

The B<$flags> parameter is optional. If present it must be set to B<one>