diff options
Diffstat (limited to 'lang/perl/BerkeleyDB/BerkeleyDB.pod')
| -rw-r--r-- | lang/perl/BerkeleyDB/BerkeleyDB.pod | 162 |
1 files changed, 152 insertions, 10 deletions
diff --git a/lang/perl/BerkeleyDB/BerkeleyDB.pod b/lang/perl/BerkeleyDB/BerkeleyDB.pod index 19fcba83..ba1c8dd3 100644 --- a/lang/perl/BerkeleyDB/BerkeleyDB.pod +++ b/lang/perl/BerkeleyDB/BerkeleyDB.pod @@ -49,6 +49,8 @@ BerkeleyDB - Perl extension for Berkeley DB version 2, 3, 4 or 5 $boolean = $db->byteswapped() ; $status = $db->truncate($count) ; $status = $db->compact($start, $stop, $c_data, $flags, $end); + $status = $db->get_blob_threshold($t1) ; + $status = $db->get_blob_dir($dir) ; $bool = $env->cds_enabled(); $bool = $db->cds_enabled(); @@ -67,11 +69,16 @@ BerkeleyDB - Perl extension for Berkeley DB version 2, 3, 4 or 5 $status = $cursor->c_pget() ; $status = $cursor->status() ; $status = $cursor->c_close() ; + $stream = $cursor->db_stream() ; $cursor = $db->db_join() ; $status = $cursor->c_get() ; $status = $cursor->c_close() ; + $status = $stream->size($S); + $status = $stream->read($data, $offset, $size); + $status = $stream->write($data, $offset); + $status = $env->txn_checkpoint() $hash_ref = $env->txn_stat() $status = $env->set_mutexlocks() @@ -79,6 +86,8 @@ BerkeleyDB - Perl extension for Berkeley DB version 2, 3, 4 or 5 $status = $env->set_timeout() $status = $env->lock_detect() $status = $env->lsn_reset() + $status = $env->get_blob_threshold($t1) ; + $status = $env->get_blob_dir($dir) ; $txn = $env->txn_begin() ; $db->Txn($txn); @@ -120,11 +129,11 @@ B<NOTE: This document is still under construction. Expect it to be incomplete in places.> This Perl module provides an interface to most of the functionality -available in Berkeley DB versions 2, 3 and 4. In general it is safe to assume +available in Berkeley DB versions 2, 3, 5 and 6. In general it is safe to assume that the interface provided here to be identical to the Berkeley DB interface. The main changes have been to make the Berkeley DB API work in a Perl way. Note that if you are using Berkeley DB 2.x, the new -features available in Berkeley DB 3.x or DB 4.x are not available via +features available in Berkeley DB 3.x or later are not available via this module. The reader is expected to be familiar with the Berkeley DB @@ -141,7 +150,7 @@ classes. The B<BerkeleyDB::Env> class provides an interface to the Berkeley DB function B<db_appinit> in Berkeley DB 2.x or B<db_env_create> and -B<DBENV-E<gt>open> in Berkeley DB 3.x/4.x. Its purpose is to initialise a +B<DBENV-E<gt>open> in Berkeley DB 3.x (or later). Its purpose is to initialise a number of sub-systems that can then be used in a consistent way in all the databases you make use of in the environment. @@ -173,6 +182,8 @@ with the C<Flags> parameter, described below. [ -MaxObjects => number, ] [ -SharedMemKey => number, ] [ -Verbose => boolean, ] + [ -BlobThreshold=> $number, ] + [ -BlobDir => directory, ] [ -Encrypt => { Password => "string", Flags => number }, ] @@ -273,6 +284,22 @@ maximum number of threads but rather is used to determine memory sizing. This option requires Berkeley DB 4.4 or better. It is only supported on Unix/Linux. +=item -BlobThreshold + +Sets the size threshold that will be used to decide when data is stored as +a BLOB. This option must be set for a blobs to be used. + +This option requires Berkeley DB 6.0 or better. + +=item -BlobDir + +The directory where the BLOB objects are stored. + +If not specified blob files are stores in the environment directoy. + + +This option requires Berkeley DB 6.0 or better. + =item -Config This is a variation on the C<-Home> parameter, but it allows finer @@ -292,7 +319,7 @@ The code below shows an example of how it can be used. =item -ErrFile -Expects a filename or filenhandle. Any errors generated internally by +Expects a filename or filehandle. Any errors generated internally by Berkeley DB will be logged to this file. A useful debug setting is to open environments with either @@ -468,7 +495,7 @@ Berkeley DB environment into C<$id>. Returns 0 on success. This option requires Berkeley DB 4.2 or better. -Use the C<-SharedMemKey> option when opening the environemt to set the +Use the C<-SharedMemKey> option when opening the environmet to set the base segment ID. =item $env->set_isalive() @@ -493,7 +520,7 @@ determines a thread of control exited with an unresolved transaction, the transaction will be aborted. Applications calling the $env->failchk method must have already called the -$env->set_isalive method, on the same DB environement, and must have +$env->set_isalive method, on the same DB environment, and must have configured their database environment using the -ThreadCount flag. The ThreadCount flag cannot be used on an environment that wasn't previously initialized with it. @@ -527,6 +554,14 @@ file. Otherwise output is sent to standard output. This option requires Berkeley DB 4.4 or better. +=item $status = $env->get_blob_threshold($t1) ; + +Sets the parameter $t1 to the threshold value (in bytes) that is used to +determine when a data item is stored as a Blob. + +=item $status = $env->get_blob_dir($dir) ; + +Sets the $dir parameter to the directory where blob files are stored. =item $env->set_timeout($timeout, $flags) @@ -620,6 +655,8 @@ Two forms of constructor are supported: [ -Txn => $txn,] [ -Encrypt => { Password => "string", Flags => number }, ], + [ -BlobThreshold=> $number, ] + [ -BlobDir => directory, ] # BerkeleyDB::Hash specific [ -Ffactor => number,] [ -Nelem => number,] @@ -641,6 +678,8 @@ and this [ -Txn => $txn,] [ -Encrypt => { Password => "string", Flags => number }, ], + [ -BlobThreshold=> $number, ] + [ -BlobDir => directory, ] # BerkeleyDB::Hash specific [ -Ffactor => number,] [ -Nelem => number,] @@ -934,6 +973,8 @@ Two forms of constructor are supported: [ -Txn => $txn,] [ -Encrypt => { Password => "string", Flags => number }, ], + [ -BlobThreshold=> $number, ] + [ -BlobDir => directory, ] # BerkeleyDB::Btree specific [ -Minkey => number,] [ -Compare => code reference,] @@ -955,6 +996,8 @@ and this [ -Txn => $txn,] [ -Encrypt => { Password => "string", Flags => number }, ], + [ -BlobThreshold=> $number, ] + [ -BlobDir => directory, ] # BerkeleyDB::Btree specific [ -Minkey => number,] [ -Compare => code reference,] @@ -1334,6 +1377,8 @@ One form of constructor is supported: [ -Txn => $txn,] [ -Encrypt => { Password => "string", Flags => number }, ], + [ -BlobThreshold=> $number, ] + [ -BlobDir => directory, ] # BerkeleyDB::Heap specific [ -HeapSize => number, ] [ -HeapSizeGb => number, ] @@ -1575,6 +1620,15 @@ TODO TODO +=head2 $status = $db->get_blob_threshold($t1) ; + +Sets the parameter $t1 to the threshold value (in bytes) that is used to +determine when a data item is stored as a Blob. + +=head2 $status = $db->get_blob_dir($dir) ; + +Sets the $dir parameter to the directory where blob files are stored. + =head2 $db->type() Returns the type of the database. The possible return code are B<DB_HASH> @@ -1605,7 +1659,7 @@ 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 +lock will not be released until all CDS lock objects are either explicitly unlocked with this method, or the CDS lock objects have been destroyed. =head2 $ref = $db->db_stat() @@ -1629,7 +1683,7 @@ 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 +Truncates the database and returns the number or records deleted in C<$count>. =head2 $status = $db->compact($start, $stop, $c_data, $flags, $end); @@ -1637,7 +1691,7 @@ in C<$count>. 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 +use C<undef> for those you don't want. Trailing unused 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 @@ -1921,6 +1975,19 @@ See C<db_pget> Closes the cursor B<$cursor>. +=head2 $stream = $cursor->db_stream($flags); + +Create a BerkeleyDB::DbStream object to read the blob at the current cursor location. +See L<Blob> for details of the the BerkeleyDB::DbStream object. + +$flags must be one or more of the following OR'ed together + +DB_STREAM_READ +DB_STREAM_WRITE +DB_STREAM_SYNC_WRITE + +For full information on the flags refer to the Berkeley DB Reference Guide. + =head2 Cursor Examples TODO @@ -1970,6 +2037,81 @@ and to roll back call abort: After committing or aborting a child transaction you need to set the active transaction again using C<Txn>. +=head1 BerkeleyDBB::DbStream -- support for BLOB + +Blob support is available in Berkeley DB starting with version 6.0. Refer +to the section "Blob Support" in the Berkeley DB Programmer Reference for +details of how Blob supports works. + +A Blob is access via a BerkeleyDBB::DbStream object. This is created via a +cursor object. + + # Note - error handling not shown below. + + # Set the key we want + my $k = "some key"; + + # Don't want the value retrieved by the cursor, + # so use partial_set to make sure no data is retrieved. + my $v = ''; + $cursor->partial_set(0,0) ; + $cursor->c_get($k, $v, DB_SET) ; + $cursor->partial_clear() ; + + # Now create a stream to the blob + my $stream = $cursor->db_stream(DB_STREAM_WRITE) ; + + # get the size of the blob + $stream->size(my $s) ; + + # Read the first 1k of data from the blob + my $data ; + $stream->read($data, 0, 1024); + +A BerkeleyDB::DbStream object has the following methods available: + + +=head2 $status = $stream->size($SIZE); + +Outputs the length of the Blob in the $SIZE parameter. + +=head2 $status = $stream->read($data, $offset, $size); + +Read from the blob. $offset is the number of bytes from the start of the +blob to read from. $size if the number of bytes to read. + +=head2 $status = $stream->write($data, $offset, $flags); + +Write $data to the blob, starting at offset $offset. + +Example + +Below is an example of how to walk through a database when you don't know +beforehand which entries are blobs and which are not. + + while (1) + { + my $k = ''; + my $v = ''; + $cursor->partial_set(0,0) ; + my $status = $cursor->c_get($k, $v, DB_NEXT) ; + $cursor->partial_clear(); + + last if $status != 0 ; + + my $stream = $cursor->db_stream(DB_STREAM_WRITE); + + if (defined $stream) + { + # It's a Blob + $stream->size(my $s) ; + } + else + { + # Not a Blob + $cursor->c_get($k, $v, DB_CURRENT) ; + } + } =head1 Berkeley DB Concurrent Data Store (CDS) @@ -2553,7 +2695,7 @@ The official web site for Berkeley DB is F<http://www.oracle.com/technology/prod =head1 COPYRIGHT -Copyright (c) 1997-2004 Paul Marquess. All rights reserved. This program +Copyright (c) 1997-2013 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. |