berkeleydb.pod

关于Berkelay数据库的共享源码

	        -Flags      => DB_CREATE,
		-Compare    => sub { lc $_[0] cmp lc $_[1] }
      or die "Cannot open $filename: $!\n" ;

    # Add a key/value pair to the file
    $h{'Wall'} = 'Larry' ;
    $h{'Smith'} = 'John' ;
    $h{'mouse'} = 'mickey' ;
    $h{'duck'}  = 'donald' ;

    # Delete
    delete $h{"duck"} ;

    # Cycle through the keys printing them in order.
    # Note it is not necessary to sort the keys as
    # the btree will have kept them in order automatically.
    foreach (keys %h)
      { print "$_\n" }

    untie %h ;

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,]
                [ -Encrypt       => { Password => "string",
	                              Flags    => number }, ],
                # 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,]
                [ -Encrypt       => { Password => "string",
	                              Flags    => number }, ],
                # 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).

    use strict ;
    use BerkeleyDB ;

    my $filename = "text" ;
    unlink $filename ;

    my @h ;
    tie @h, 'BerkeleyDB::Recno',
    		-Filename   => $filename,
	        -Flags      => DB_CREATE,
		-Property   => DB_RENUMBER
      or die "Cannot open $filename: $!\n" ;

    # Add a few key/value pairs to the file
    $h[0] = "orange" ;
    $h[1] = "blue" ;
    $h[2] = "yellow" ;

    push @h, "green", "black" ;

    my $elements = scalar @h ;
    print "The array contains $elements entries\n" ;

    my $last = pop @h ;
    print "popped $last\n" ;

    unshift @h, "white" ;
    my $first = shift @h ;
    print "shifted $first\n" ;

    # Check for existence of a key
    print "Element 1 Exists with value $h[1]\n" if $h[1] ;

    untie @h ;

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,]
                [ -Encrypt       => { Password => "string",
	                              Flags    => number }, ],
                # 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,]
                [ -Encrypt       => { Password => "string",
	                              Flags    => number }, ],
                # 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,]
                [ -Encrypt       => { Password => "string",
	                              Flags    => number }, ],


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

If present, this parameter will enable encryption of  all data before
it is written to the database. This parameters must be given a hash
reference. The format is shown below.

    -Encrypt => { -Password => "abc", Flags => DB_ENCRYPT_AES }

Valid values for the Flags are 0 or C<DB_ENCRYPT_AES>.

This option requires Berkeley DB 4.1 or better.

=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 bitwise 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>
of the following values:

=over 5

=item B<DB_APPEND>

This flag is only applicable when accessing a B<BerkeleyDB::Recno>
database.

TODO.


=item B<DB_NOOVERWRITE>

If this flag is specified and C<$key> already exists in the database,
the call to B<db_put> will return B<DB_KEYEXIST>.

=back

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

Deletes a key/value pair in the database associated with C<$key>.
If duplicate keys are enabled in the database, B<db_del> will delete
B<all> key/value pairs with key C<$key>.

The B<$flags> parameter is optional and is currently unused.

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

If any parts of the database are in memory, write them to the database.

=head2 $cursor = $db->db_cursor([$flags])

Creates a cursor object. This is used to access the contents of the
database sequentially. See L<CURSORS> for details of the methods
available when working with cursors.

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

=over 5

=item B<DB_RMW>

TODO.

=back

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

TODO

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

TODO

=head2 $db->byteswapped()

TODO

=head2 $db->type()

Returns the type of the database. The possible return code are B<DB_HASH>
for a B<BerkeleyDB::Hash> database, B<DB_BTREE> for a B<BerkeleyDB::Btree>
database and B<DB_RECNO> for a B<BerkeleyDB::Recno> database. This method
is typically used when a database has been opened with
B<BerkeleyDB::Unknown>.

=head2   $bool = $env->cds_enabled();

Returns true if the Berkeley DB environment C<$env> has been opened on
CDS mode.

=head2   $bool = $db->cds_enabled();

Returns true if the database C<$db> has been opened on CDS mode.

=head2 $lock = $db->cds_lock();

Creates a CDS write lock object C<$lock>.

It is a fatal error to attempt to create a cds_lock if the Berkeley DB
environment has not been opened in CDS mode.

=head2 $lock->cds_unlock();

Removes a CDS lock. The destruction of the CDS lock object automatically
calls this method.

Note that if multiple CDS lock objects are created, the underlying write
lock will not be released until all CDS lock objects are either explictly
unlocked with this method, or the CDS lock objects have been destroyed.

=head2 $ref = $db->db_stat()

Returns a reference to an associative array containing information about
the database. The keys of the associative array correspond directly to the
names of the fields defined in the Berkeley DB documentation. For example,
in the DB documentation, the field B<bt_version> stores the version of the
Btree database. Assuming you called B<db_stat> on a Btree database the
equivalent field would be accessed as follows:

    $version = $ref->{'bt_version'} ;

If you are using Berkeley DB 3.x or better, this method will work will
all database formats. When DB 2.x is used, it only works with
B<BerkeleyDB::Btree>.

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

Returns the status of the last C<$db> method called.

=head2 $status = $db->truncate($count)

Truncates the datatabase and returns the number or records deleted
in C<$count>.

=head2  $status = $db->compact($start, $stop, $c_data, $flags, $end);

Compacts the database C<$db>. 

All the parameters are optional - if only want to make use of some of them,
use C<undef> for those you don't want.  Trailing unusused parameters can be
omitted. For example, if you only want to use the C<$c_data> parameter to
set the C<compact_fillpercent>, write you code like this

    my %hash;
    $hash{compact_fillpercent} = 50;
    $db->commit(undef, undef, \%hash);

The parameters operate identically to the C equivalent of this method.
The C<$c_data> needs a bit of explanation - it must be a hash reference.
The values of the following keys can be set before calling C<compact> and
will affect the operation of the compaction.

=over 5
=item * compact_fillpercent
=item * compact_timeout
    
=back

The following keys, along with associated values, will be created in the
hash reference if the C<compact> operation was successful.

=over 5

=item * compact_deadlock
=item * compact_levels
=item * compact_pages_free