1=head1 NAME 2 3BerkeleyDB - Perl extension for Berkeley DB version 2, 3 or 4 4 5=head1 SYNOPSIS 6 7 use BerkeleyDB; 8 9 $env = new BerkeleyDB::Env [OPTIONS] ; 10 11 $db = tie %hash, 'BerkeleyDB::Hash', [OPTIONS] ; 12 $db = new BerkeleyDB::Hash [OPTIONS] ; 13 14 $db = tie %hash, 'BerkeleyDB::Btree', [OPTIONS] ; 15 $db = new BerkeleyDB::Btree [OPTIONS] ; 16 17 $db = tie @array, 'BerkeleyDB::Recno', [OPTIONS] ; 18 $db = new BerkeleyDB::Recno [OPTIONS] ; 19 20 $db = tie @array, 'BerkeleyDB::Queue', [OPTIONS] ; 21 $db = new BerkeleyDB::Queue [OPTIONS] ; 22 23 $db = new BerkeleyDB::Unknown [OPTIONS] ; 24 25 $status = BerkeleyDB::db_remove [OPTIONS] 26 $status = BerkeleyDB::db_rename [OPTIONS] 27 $status = BerkeleyDB::db_verify [OPTIONS] 28 29 $hash{$key} = $value ; 30 $value = $hash{$key} ; 31 each %hash ; 32 keys %hash ; 33 values %hash ; 34 35 $status = $db->db_get() 36 $status = $db->db_put() ; 37 $status = $db->db_del() ; 38 $status = $db->db_sync() ; 39 $status = $db->db_close() ; 40 $status = $db->db_pget() 41 $hash_ref = $db->db_stat() ; 42 $status = $db->db_key_range(); 43 $type = $db->type() ; 44 $status = $db->status() ; 45 $boolean = $db->byteswapped() ; 46 $status = $db->truncate($count) ; 47 $status = $db->compact($start, $stop, $c_data, $flags, $end); 48 49 $bool = $env->cds_enabled(); 50 $bool = $db->cds_enabled(); 51 $lock = $db->cds_lock(); 52 $lock->cds_unlock(); 53 54 ($flag, $old_offset, $old_length) = $db->partial_set($offset, $length) ; 55 ($flag, $old_offset, $old_length) = $db->partial_clear() ; 56 57 $cursor = $db->db_cursor([$flags]) ; 58 $newcursor = $cursor->c_dup([$flags]); 59 $status = $cursor->c_get() ; 60 $status = $cursor->c_put() ; 61 $status = $cursor->c_del() ; 62 $status = $cursor->c_count() ; 63 $status = $cursor->c_pget() ; 64 $status = $cursor->status() ; 65 $status = $cursor->c_close() ; 66 67 $cursor = $db->db_join() ; 68 $status = $cursor->c_get() ; 69 $status = $cursor->c_close() ; 70 71 $status = $env->txn_checkpoint() 72 $hash_ref = $env->txn_stat() 73 $status = $env->setmutexlocks() 74 $status = $env->set_flags() 75 $status = $env->set_timeout() 76 $status = $env->lsn_reset() 77 78 $txn = $env->txn_begin() ; 79 $db->Txn($txn); 80 $txn->Txn($db1, $db2,...); 81 $status = $txn->txn_prepare() 82 $status = $txn->txn_commit() 83 $status = $txn->txn_abort() 84 $status = $txn->txn_id() 85 $status = $txn->txn_discard() 86 $status = $txn->set_timeout() 87 88 $status = $env->set_lg_dir(); 89 $status = $env->set_lg_bsize(); 90 $status = $env->set_lg_max(); 91 92 $status = $env->set_data_dir() ; 93 $status = $env->set_tmp_dir() ; 94 $status = $env->set_verbose() ; 95 $db_env_ptr = $env->DB_ENV() ; 96 97 $BerkeleyDB::Error 98 $BerkeleyDB::db_version 99 100 # DBM Filters 101 $old_filter = $db->filter_store_key ( sub { ... } ) ; 102 $old_filter = $db->filter_store_value( sub { ... } ) ; 103 $old_filter = $db->filter_fetch_key ( sub { ... } ) ; 104 $old_filter = $db->filter_fetch_value( sub { ... } ) ; 105 106 # deprecated, but supported 107 $txn_mgr = $env->TxnMgr(); 108 $status = $txn_mgr->txn_checkpoint() 109 $hash_ref = $txn_mgr->txn_stat() 110 $txn = $txn_mgr->txn_begin() ; 111 112=head1 DESCRIPTION 113 114B<NOTE: This document is still under construction. Expect it to be 115incomplete in places.> 116 117This Perl module provides an interface to most of the functionality 118available in Berkeley DB versions 2, 3 and 4. In general it is safe to assume 119that the interface provided here to be identical to the Berkeley DB 120interface. The main changes have been to make the Berkeley DB API work 121in a Perl way. Note that if you are using Berkeley DB 2.x, the new 122features available in Berkeley DB 3.x or DB 4.x are not available via 123this module. 124 125The reader is expected to be familiar with the Berkeley DB 126documentation. Where the interface provided here is identical to the 127Berkeley DB library and the... TODO 128 129The B<db_appinit>, B<db_cursor>, B<db_open> and B<db_txn> man pages are 130particularly relevant. 131 132The interface to Berkeley DB is implemented with a number of Perl 133classes. 134 135=head1 The BerkeleyDB::Env Class 136 137The B<BerkeleyDB::Env> class provides an interface to the Berkeley DB 138function B<db_appinit> in Berkeley DB 2.x or B<db_env_create> and 139B<DBENV-E<gt>open> in Berkeley DB 3.x/4.x. Its purpose is to initialise a 140number of sub-systems that can then be used in a consistent way in all 141the databases you make use of in the environment. 142 143If you don't intend using transactions, locking or logging, then you 144shouldn't need to make use of B<BerkeleyDB::Env>. 145 146Note that an environment consists of a number of files that Berkeley DB 147manages behind the scenes for you. When you first use an environment, it 148needs to be explicitly created. This is done by including C<DB_CREATE> 149with the C<Flags> parameter, described below. 150 151=head2 Synopsis 152 153 $env = new BerkeleyDB::Env 154 [ -Home => $path, ] 155 [ -Server => $name, ] 156 [ -CacheSize => $number, ] 157 [ -Config => { name => value, name => value }, ] 158 [ -ErrFile => filename, ] 159 [ -ErrPrefix => "string", ] 160 [ -Flags => number, ] 161 [ -SetFlags => bitmask, ] 162 [ -LockDetect => number, ] 163 [ -SharedMemKey => number, ] 164 [ -Verbose => boolean, ] 165 [ -Encrypt => { Password => "string", 166 Flags => number }, ] 167 168All the parameters to the BerkeleyDB::Env constructor are optional. 169 170=over 5 171 172=item -Home 173 174If present, this parameter should point to an existing directory. Any 175files that I<aren't> specified with an absolute path in the sub-systems 176that are initialised by the BerkeleyDB::Env class will be assumed to 177live in the B<Home> directory. 178 179For example, in the code fragment below the database "fred.db" will be 180opened in the directory "/home/databases" because it was specified as a 181relative path, but "joe.db" will be opened in "/other" because it was 182part of an absolute path. 183 184 $env = new BerkeleyDB::Env 185 -Home => "/home/databases" 186 ... 187 188 $db1 = new BerkeleyDB::Hash 189 -Filename => "fred.db", 190 -Env => $env 191 ... 192 193 $db2 = new BerkeleyDB::Hash 194 -Filename => "/other/joe.db", 195 -Env => $env 196 ... 197 198=item -Server 199 200If present, this parameter should be the hostname of a server that is running 201the Berkeley DB RPC server. All databases will be accessed via the RPC server. 202 203=item -Encrypt 204 205If present, this parameter will enable encryption of all data before 206it is written to the database. This parameters must be given a hash 207reference. The format is shown below. 208 209 -Encrypt => { -Password => "abc", Flags => DB_ENCRYPT_AES } 210 211Valid values for the Flags are 0 or C<DB_ENCRYPT_AES>. 212 213This option requires Berkeley DB 4.1 or better. 214 215=item -Cachesize 216 217If present, this parameter sets the size of the environments shared memory 218buffer pool. 219 220=item -SharedMemKey 221 222If present, this parameter sets the base segment ID for the shared memory 223region used by Berkeley DB. 224 225This option requires Berkeley DB 3.1 or better. 226 227Use C<$env-E<gt>get_shm_key($id)> to find out the base segment ID used 228once the environment is open. 229 230=item -ThreadCount 231 232If present, this parameter declares the approximate number of threads that 233will be used in the database environment. This parameter is only necessary 234when the $env->failchk method will be used. It does not actually set the 235maximum number of threads but rather is used to determine memory sizing. 236 237This option requires Berkeley DB 4.4 or better. It is only supported on 238Unix/Linux. 239 240=item -Config 241 242This is a variation on the C<-Home> parameter, but it allows finer 243control of where specific types of files will be stored. 244 245The parameter expects a reference to a hash. Valid keys are: 246B<DB_DATA_DIR>, B<DB_LOG_DIR> and B<DB_TMP_DIR> 247 248The code below shows an example of how it can be used. 249 250 $env = new BerkeleyDB::Env 251 -Config => { DB_DATA_DIR => "/home/databases", 252 DB_LOG_DIR => "/home/logs", 253 DB_TMP_DIR => "/home/tmp" 254 } 255 ... 256 257=item -ErrFile 258 259Expects a filename or filenhandle. Any errors generated internally by 260Berkeley DB will be logged to this file. A useful debug setting is to 261open environments with either 262 263 -ErrFile => *STDOUT 264 265or 266 267 -ErrFile => *STDERR 268 269=item -ErrPrefix 270 271Allows a prefix to be added to the error messages before they are sent 272to B<-ErrFile>. 273 274=item -Flags 275 276The B<Flags> parameter specifies both which sub-systems to initialise, 277as well as a number of environment-wide options. 278See the Berkeley DB documentation for more details of these options. 279 280Any of the following can be specified by OR'ing them: 281 282B<DB_CREATE> 283 284If any of the files specified do not already exist, create them. 285 286B<DB_INIT_CDB> 287 288Initialise the Concurrent Access Methods 289 290B<DB_INIT_LOCK> 291 292Initialise the Locking sub-system. 293 294B<DB_INIT_LOG> 295 296Initialise the Logging sub-system. 297 298B<DB_INIT_MPOOL> 299 300Initialise the ... 301 302B<DB_INIT_TXN> 303 304Initialise the ... 305 306B<DB_MPOOL_PRIVATE> 307 308Initialise the ... 309 310B<DB_INIT_MPOOL> is also specified. 311 312Initialise the ... 313 314B<DB_NOMMAP> 315 316Initialise the ... 317 318B<DB_RECOVER> 319 320 321 322B<DB_RECOVER_FATAL> 323 324B<DB_THREAD> 325 326B<DB_TXN_NOSYNC> 327 328B<DB_USE_ENVIRON> 329 330B<DB_USE_ENVIRON_ROOT> 331 332=item -SetFlags 333 334Calls ENV->set_flags with the supplied bitmask. Use this when you need to make 335use of DB_ENV->set_flags before DB_ENV->open is called. 336 337Only valid when Berkeley DB 3.x or better is used. 338 339=item -LockDetect 340 341Specifies what to do when a lock conflict occurs. The value should be one of 342 343B<DB_LOCK_DEFAULT> 344 345B<DB_LOCK_OLDEST> 346 347B<DB_LOCK_RANDOM> 348 349B<DB_LOCK_YOUNGEST> 350 351=item -Verbose 352 353Add extra debugging information to the messages sent to B<-ErrFile>. 354 355=back 356 357=head2 Methods 358 359The environment class has the following methods: 360 361=over 5 362 363=item $env->errPrefix("string") ; 364 365This method is identical to the B<-ErrPrefix> flag. It allows the 366error prefix string to be changed dynamically. 367 368=item $env->set_flags(bitmask, 1|0); 369 370=item $txn = $env->TxnMgr() 371 372Constructor for creating a B<TxnMgr> object. 373See L<"TRANSACTIONS"> for more details of using transactions. 374 375This method is deprecated. Access the transaction methods using the B<txn_> 376methods below from the environment object directly. 377 378=item $env->txn_begin() 379 380TODO 381 382=item $env->txn_stat() 383 384TODO 385 386=item $env->txn_checkpoint() 387 388TODO 389 390=item $env->status() 391 392Returns the status of the last BerkeleyDB::Env method. 393 394 395=item $env->DB_ENV() 396 397Returns a pointer to the underlying DB_ENV data structure that Berkeley 398DB uses. 399 400=item $env->get_shm_key($id) 401 402Writes the base segment ID for the shared memory region used by the 403Berkeley DB environment into C<$id>. Returns 0 on success. 404 405This option requires Berkeley DB 4.2 or better. 406 407Use the C<-SharedMemKey> option when opening the environemt to set the 408base segment ID. 409 410=item $env->set_isalive() 411 412Set the callback that determines if the thread of control, identified by 413the pid and tid arguments, is still running. This method should only be 414used in combination with $env->failchk. 415 416This option requires Berkeley DB 4.4 or better. 417 418=item $env->failchk($flags) 419 420The $env->failchk method checks for threads of control (either a true 421thread or a process) that have exited while manipulating Berkeley DB 422library data structures, while holding a logical database lock, or with an 423unresolved transaction (that is, a transaction that was never aborted or 424committed). 425 426If $env->failchk determines a thread of control exited while holding 427database read locks, it will release those locks. If $env->failchk 428determines a thread of control exited with an unresolved transaction, the 429transaction will be aborted. 430 431Applications calling the $env->failchk method must have already called the 432$env->set_isalive method, on the same DB environement, and must have 433configured their database environment using the -ThreadCount flag. The 434ThreadCount flag cannot be used on an environment that wasn't previously 435initialized with it. 436 437This option requires Berkeley DB 4.4 or better. 438 439=item $env->lock_stat_print 440 441Prints locking subsystem statistics. 442 443This option requires Berkeley DB 4.3 or better. 444 445=item $env->mutex_stat_print 446 447Prints mutex subsystem statistics. 448 449This option requires Berkeley DB 4.4 or better. 450 451 452=item $env->set_timeout($timeout, $flags) 453 454=item $env->status() 455 456Returns the status of the last BerkeleyDB::Env method. 457 458=back 459 460=head2 Examples 461 462TODO. 463 464=head1 Global Classes 465 466 $status = BerkeleyDB::db_remove [OPTIONS] 467 $status = BerkeleyDB::db_rename [OPTIONS] 468 $status = BerkeleyDB::db_verify [OPTIONS] 469 470=head1 THE DATABASE CLASSES 471 472B<BerkeleyDB> supports the following database formats: 473 474=over 5 475 476=item B<BerkeleyDB::Hash> 477 478This database type allows arbitrary key/value pairs to be stored in data 479files. This is equivalent to the functionality provided by other 480hashing packages like DBM, NDBM, ODBM, GDBM, and SDBM. Remember though, 481the files created using B<BerkeleyDB::Hash> are not compatible with any 482of the other packages mentioned. 483 484A default hashing algorithm, which will be adequate for most applications, 485is built into BerkeleyDB. If you do need to use your own hashing algorithm 486it is possible to write your own in Perl and have B<BerkeleyDB> use 487it instead. 488 489=item B<BerkeleyDB::Btree> 490 491The Btree format allows arbitrary key/value pairs to be stored in a 492B+tree. 493 494As with the B<BerkeleyDB::Hash> format, it is possible to provide a 495user defined Perl routine to perform the comparison of keys. By default, 496though, the keys are stored in lexical order. 497 498=item B<BerkeleyDB::Recno> 499 500TODO. 501 502 503=item B<BerkeleyDB::Queue> 504 505TODO. 506 507=item B<BerkeleyDB::Unknown> 508 509This isn't a database format at all. It is used when you want to open an 510existing Berkeley DB database without having to know what type is it. 511 512=back 513 514 515Each of the database formats described above is accessed via a 516corresponding B<BerkeleyDB> class. These will be described in turn in 517the next sections. 518 519=head1 BerkeleyDB::Hash 520 521Equivalent to calling B<db_open> with type B<DB_HASH> in Berkeley DB 2.x and 522calling B<db_create> followed by B<DB-E<gt>open> with type B<DB_HASH> in 523Berkeley DB 3.x or greater. 524 525Two forms of constructor are supported: 526 527 $db = new BerkeleyDB::Hash 528 [ -Filename => "filename", ] 529 [ -Subname => "sub-database name", ] 530 [ -Flags => flags,] 531 [ -Property => flags,] 532 [ -Mode => number,] 533 [ -Cachesize => number,] 534 [ -Lorder => number,] 535 [ -Pagesize => number,] 536 [ -Env => $env,] 537 [ -Txn => $txn,] 538 [ -Encrypt => { Password => "string", 539 Flags => number }, ], 540 # BerkeleyDB::Hash specific 541 [ -Ffactor => number,] 542 [ -Nelem => number,] 543 [ -Hash => code reference,] 544 [ -DupCompare => code reference,] 545 546and this 547 548 [$db =] tie %hash, 'BerkeleyDB::Hash', 549 [ -Filename => "filename", ] 550 [ -Subname => "sub-database name", ] 551 [ -Flags => flags,] 552 [ -Property => flags,] 553 [ -Mode => number,] 554 [ -Cachesize => number,] 555 [ -Lorder => number,] 556 [ -Pagesize => number,] 557 [ -Env => $env,] 558 [ -Txn => $txn,] 559 [ -Encrypt => { Password => "string", 560 Flags => number }, ], 561 # BerkeleyDB::Hash specific 562 [ -Ffactor => number,] 563 [ -Nelem => number,] 564 [ -Hash => code reference,] 565 [ -DupCompare => code reference,] 566 567 568When the "tie" interface is used, reading from and writing to the database 569is achieved via the tied hash. In this case the database operates like 570a Perl associative array that happens to be stored on disk. 571 572In addition to the high-level tied hash interface, it is possible to 573make use of the underlying methods provided by Berkeley DB 574 575=head2 Options 576 577In addition to the standard set of options (see L<COMMON OPTIONS>) 578B<BerkeleyDB::Hash> supports these options: 579 580=over 5 581 582=item -Property 583 584Used to specify extra flags when opening a database. The following 585flags may be specified by bitwise OR'ing together one or more of the 586following values: 587 588B<DB_DUP> 589 590When creating a new database, this flag enables the storing of duplicate 591keys in the database. If B<DB_DUPSORT> is not specified as well, the 592duplicates are stored in the order they are created in the database. 593 594B<DB_DUPSORT> 595 596Enables the sorting of duplicate keys in the database. Ignored if 597B<DB_DUP> isn't also specified. 598 599=item -Ffactor 600 601=item -Nelem 602 603See the Berkeley DB documentation for details of these options. 604 605=item -Hash 606 607Allows you to provide a user defined hash function. If not specified, 608a default hash function is used. Here is a template for a user-defined 609hash function 610 611 sub hash 612 { 613 my ($data) = shift ; 614 ... 615 # return the hash value for $data 616 return $hash ; 617 } 618 619 tie %h, "BerkeleyDB::Hash", 620 -Filename => $filename, 621 -Hash => \&hash, 622 ... 623 624See L<""> for an example. 625 626=item -DupCompare 627 628Used in conjunction with the B<DB_DUPOSRT> flag. 629 630 sub compare 631 { 632 my ($key, $key2) = @_ ; 633 ... 634 # return 0 if $key1 eq $key2 635 # -1 if $key1 lt $key2 636 # 1 if $key1 gt $key2 637 return (-1 , 0 or 1) ; 638 } 639 640 tie %h, "BerkeleyDB::Hash", 641 -Filename => $filename, 642 -Property => DB_DUP|DB_DUPSORT, 643 -DupCompare => \&compare, 644 ... 645 646=back 647 648 649=head2 Methods 650 651B<BerkeleyDB::Hash> only supports the standard database methods. 652See L<COMMON DATABASE METHODS>. 653 654=head2 A Simple Tied Hash Example 655 656 use strict ; 657 use BerkeleyDB ; 658 use vars qw( %h $k $v ) ; 659 660 my $filename = "fruit" ; 661 unlink $filename ; 662 tie %h, "BerkeleyDB::Hash", 663 -Filename => $filename, 664 -Flags => DB_CREATE 665 or die "Cannot open file $filename: $! $BerkeleyDB::Error\n" ; 666 667 # Add a few key/value pairs to the file 668 $h{"apple"} = "red" ; 669 $h{"orange"} = "orange" ; 670 $h{"banana"} = "yellow" ; 671 $h{"tomato"} = "red" ; 672 673 # Check for existence of a key 674 print "Banana Exists\n\n" if $h{"banana"} ; 675 676 # Delete a key/value pair. 677 delete $h{"apple"} ; 678 679 # print the contents of the file 680 while (($k, $v) = each %h) 681 { print "$k -> $v\n" } 682 683 untie %h ; 684 685here is the output: 686 687 Banana Exists 688 689 orange -> orange 690 tomato -> red 691 banana -> yellow 692 693Note that the like ordinary associative arrays, the order of the keys 694retrieved from a Hash database are in an apparently random order. 695 696=head2 Another Simple Hash Example 697 698Do the same as the previous example but not using tie. 699 700 use strict ; 701 use BerkeleyDB ; 702 703 my $filename = "fruit" ; 704 unlink $filename ; 705 my $db = new BerkeleyDB::Hash 706 -Filename => $filename, 707 -Flags => DB_CREATE 708 or die "Cannot open file $filename: $! $BerkeleyDB::Error\n" ; 709 710 # Add a few key/value pairs to the file 711 $db->db_put("apple", "red") ; 712 $db->db_put("orange", "orange") ; 713 $db->db_put("banana", "yellow") ; 714 $db->db_put("tomato", "red") ; 715 716 # Check for existence of a key 717 print "Banana Exists\n\n" if $db->db_get("banana", $v) == 0; 718 719 # Delete a key/value pair. 720 $db->db_del("apple") ; 721 722 # print the contents of the file 723 my ($k, $v) = ("", "") ; 724 my $cursor = $db->db_cursor() ; 725 while ($cursor->c_get($k, $v, DB_NEXT) == 0) 726 { print "$k -> $v\n" } 727 728 undef $cursor ; 729 undef $db ; 730 731=head2 Duplicate keys 732 733The code below is a variation on the examples above. This time the hash has 734been inverted. The key this time is colour and the value is the fruit name. 735The B<DB_DUP> flag has been specified to allow duplicates. 736 737 use strict ; 738 use BerkeleyDB ; 739 740 my $filename = "fruit" ; 741 unlink $filename ; 742 my $db = new BerkeleyDB::Hash 743 -Filename => $filename, 744 -Flags => DB_CREATE, 745 -Property => DB_DUP 746 or die "Cannot open file $filename: $! $BerkeleyDB::Error\n" ; 747 748 # Add a few key/value pairs to the file 749 $db->db_put("red", "apple") ; 750 $db->db_put("orange", "orange") ; 751 $db->db_put("green", "banana") ; 752 $db->db_put("yellow", "banana") ; 753 $db->db_put("red", "tomato") ; 754 $db->db_put("green", "apple") ; 755 756 # print the contents of the file 757 my ($k, $v) = ("", "") ; 758 my $cursor = $db->db_cursor() ; 759 while ($cursor->c_get($k, $v, DB_NEXT) == 0) 760 { print "$k -> $v\n" } 761 762 undef $cursor ; 763 undef $db ; 764 765here is the output: 766 767 orange -> orange 768 yellow -> banana 769 red -> apple 770 red -> tomato 771 green -> banana 772 green -> apple 773 774=head2 Sorting Duplicate Keys 775 776In the previous example, when there were duplicate keys, the values are 777sorted in the order they are stored in. The code below is 778identical to the previous example except the B<DB_DUPSORT> flag is 779specified. 780 781 use strict ; 782 use BerkeleyDB ; 783 784 my $filename = "fruit" ; 785 unlink $filename ; 786 my $db = new BerkeleyDB::Hash 787 -Filename => $filename, 788 -Flags => DB_CREATE, 789 -Property => DB_DUP | DB_DUPSORT 790 or die "Cannot open file $filename: $! $BerkeleyDB::Error\n" ; 791 792 # Add a few key/value pairs to the file 793 $db->db_put("red", "apple") ; 794 $db->db_put("orange", "orange") ; 795 $db->db_put("green", "banana") ; 796 $db->db_put("yellow", "banana") ; 797 $db->db_put("red", "tomato") ; 798 $db->db_put("green", "apple") ; 799 800 # print the contents of the file 801 my ($k, $v) = ("", "") ; 802 my $cursor = $db->db_cursor() ; 803 while ($cursor->c_get($k, $v, DB_NEXT) == 0) 804 { print "$k -> $v\n" } 805 806 undef $cursor ; 807 undef $db ; 808 809Notice that in the output below the duplicate values are sorted. 810 811 orange -> orange 812 yellow -> banana 813 red -> apple 814 red -> tomato 815 green -> apple 816 green -> banana 817 818=head2 Custom Sorting Duplicate Keys 819 820Another variation 821 822TODO 823 824=head2 Changing the hash 825 826TODO 827 828=head2 Using db_stat 829 830TODO 831 832=head1 BerkeleyDB::Btree 833 834Equivalent to calling B<db_open> with type B<DB_BTREE> in Berkeley DB 2.x and 835calling B<db_create> followed by B<DB-E<gt>open> with type B<DB_BTREE> in 836Berkeley DB 3.x or greater. 837 838Two forms of constructor are supported: 839 840 841 $db = new BerkeleyDB::Btree 842 [ -Filename => "filename", ] 843 [ -Subname => "sub-database name", ] 844 [ -Flags => flags,] 845 [ -Property => flags,] 846 [ -Mode => number,] 847 [ -Cachesize => number,] 848 [ -Lorder => number,] 849 [ -Pagesize => number,] 850 [ -Env => $env,] 851 [ -Txn => $txn,] 852 [ -Encrypt => { Password => "string", 853 Flags => number }, ], 854 # BerkeleyDB::Btree specific 855 [ -Minkey => number,] 856 [ -Compare => code reference,] 857 [ -DupCompare => code reference,] 858 [ -Prefix => code reference,] 859 860and this 861 862 [$db =] tie %hash, 'BerkeleyDB::Btree', 863 [ -Filename => "filename", ] 864 [ -Subname => "sub-database name", ] 865 [ -Flags => flags,] 866 [ -Property => flags,] 867 [ -Mode => number,] 868 [ -Cachesize => number,] 869 [ -Lorder => number,] 870 [ -Pagesize => number,] 871 [ -Env => $env,] 872 [ -Txn => $txn,] 873 [ -Encrypt => { Password => "string", 874 Flags => number }, ], 875 # BerkeleyDB::Btree specific 876 [ -Minkey => number,] 877 [ -Compare => code reference,] 878 [ -DupCompare => code reference,] 879 [ -Prefix => code reference,] 880 881=head2 Options 882 883In addition to the standard set of options (see L<COMMON OPTIONS>) 884B<BerkeleyDB::Btree> supports these options: 885 886=over 5 887 888=item -Property 889 890Used to specify extra flags when opening a database. The following 891flags may be specified by bitwise OR'ing together one or more of the 892following values: 893 894B<DB_DUP> 895 896When creating a new database, this flag enables the storing of duplicate 897keys in the database. If B<DB_DUPSORT> is not specified as well, the 898duplicates are stored in the order they are created in the database. 899 900B<DB_DUPSORT> 901 902Enables the sorting of duplicate keys in the database. Ignored if 903B<DB_DUP> isn't also specified. 904 905=item Minkey 906 907TODO 908 909=item Compare 910 911Allow you to override the default sort order used in the database. See 912L<"Changing the sort order"> for an example. 913 914 sub compare 915 { 916 my ($key, $key2) = @_ ; 917 ... 918 # return 0 if $key1 eq $key2 919 # -1 if $key1 lt $key2 920 # 1 if $key1 gt $key2 921 return (-1 , 0 or 1) ; 922 } 923 924 tie %h, "BerkeleyDB::Hash", 925 -Filename => $filename, 926 -Compare => \&compare, 927 ... 928 929=item Prefix 930 931 sub prefix 932 { 933 my ($key, $key2) = @_ ; 934 ... 935 # return number of bytes of $key2 which are 936 # necessary to determine that it is greater than $key1 937 return $bytes ; 938 } 939 940 tie %h, "BerkeleyDB::Hash", 941 -Filename => $filename, 942 -Prefix => \&prefix, 943 ... 944=item DupCompare 945 946 sub compare 947 { 948 my ($key, $key2) = @_ ; 949 ... 950 # return 0 if $key1 eq $key2 951 # -1 if $key1 lt $key2 952 # 1 if $key1 gt $key2 953 return (-1 , 0 or 1) ; 954 } 955 956 tie %h, "BerkeleyDB::Hash", 957 -Filename => $filename, 958 -DupCompare => \&compare, 959 ... 960 961=back 962 963=head2 Methods 964 965B<BerkeleyDB::Btree> supports the following database methods. 966See also L<COMMON DATABASE METHODS>. 967 968All the methods below return 0 to indicate success. 969 970=over 5 971 972=item $status = $db->db_key_range($key, $less, $equal, $greater [, $flags]) 973 974Given a key, C<$key>, this method returns the proportion of keys less than 975C<$key> in C<$less>, the proportion equal to C<$key> in C<$equal> and the 976proportion greater than C<$key> in C<$greater>. 977 978The proportion is returned as a double in the range 0.0 to 1.0. 979 980=back 981 982=head2 A Simple Btree Example 983 984The code below is a simple example of using a btree database. 985 986 use strict ; 987 use BerkeleyDB ; 988 989 my $filename = "tree" ; 990 unlink $filename ; 991 my %h ; 992 tie %h, 'BerkeleyDB::Btree', 993 -Filename => $filename, 994 -Flags => DB_CREATE 995 or die "Cannot open $filename: $! $BerkeleyDB::Error\n" ; 996 997 # Add a key/value pair to the file 998 $h{'Wall'} = 'Larry' ; 999 $h{'Smith'} = 'John' ; 1000 $h{'mouse'} = 'mickey' ; 1001 $h{'duck'} = 'donald' ; 1002 1003 # Delete 1004 delete $h{"duck"} ; 1005 1006 # Cycle through the keys printing them in order. 1007 # Note it is not necessary to sort the keys as 1008 # the btree will have kept them in order automatically. 1009 foreach (keys %h) 1010 { print "$_\n" } 1011 1012 untie %h ; 1013 1014Here is the output from the code above. The keys have been sorted using 1015Berkeley DB's default sorting algorithm. 1016 1017 Smith 1018 Wall 1019 mouse 1020 1021 1022=head2 Changing the sort order 1023 1024It is possible to supply your own sorting algorithm if the one that Berkeley 1025DB used isn't suitable. The code below is identical to the previous example 1026except for the case insensitive compare function. 1027 1028 use strict ; 1029 use BerkeleyDB ; 1030 1031 my $filename = "tree" ; 1032 unlink $filename ; 1033 my %h ; 1034 tie %h, 'BerkeleyDB::Btree', 1035 -Filename => $filename, 1036 -Flags => DB_CREATE, 1037 -Compare => sub { lc $_[0] cmp lc $_[1] } 1038 or die "Cannot open $filename: $!\n" ; 1039 1040 # Add a key/value pair to the file 1041 $h{'Wall'} = 'Larry' ; 1042 $h{'Smith'} = 'John' ; 1043 $h{'mouse'} = 'mickey' ; 1044 $h{'duck'} = 'donald' ; 1045 1046 # Delete 1047 delete $h{"duck"} ; 1048 1049 # Cycle through the keys printing them in order. 1050 # Note it is not necessary to sort the keys as 1051 # the btree will have kept them in order automatically. 1052 foreach (keys %h) 1053 { print "$_\n" } 1054 1055 untie %h ; 1056 1057Here is the output from the code above. 1058 1059 mouse 1060 Smith 1061 Wall 1062 1063There are a few point to bear in mind if you want to change the 1064ordering in a BTREE database: 1065 1066=over 5 1067 1068=item 1. 1069 1070The new compare function must be specified when you create the database. 1071 1072=item 2. 1073 1074You cannot change the ordering once the database has been created. Thus 1075you must use the same compare function every time you access the 1076database. 1077 1078=back 1079 1080=head2 Using db_stat 1081 1082TODO 1083 1084=head1 BerkeleyDB::Recno 1085 1086Equivalent to calling B<db_open> with type B<DB_RECNO> in Berkeley DB 2.x and 1087calling B<db_create> followed by B<DB-E<gt>open> with type B<DB_RECNO> in 1088Berkeley DB 3.x or greater. 1089 1090Two forms of constructor are supported: 1091 1092 $db = new BerkeleyDB::Recno 1093 [ -Filename => "filename", ] 1094 [ -Subname => "sub-database name", ] 1095 [ -Flags => flags,] 1096 [ -Property => flags,] 1097 [ -Mode => number,] 1098 [ -Cachesize => number,] 1099 [ -Lorder => number,] 1100 [ -Pagesize => number,] 1101 [ -Env => $env,] 1102 [ -Txn => $txn,] 1103 [ -Encrypt => { Password => "string", 1104 Flags => number }, ], 1105 # BerkeleyDB::Recno specific 1106 [ -Delim => byte,] 1107 [ -Len => number,] 1108 [ -Pad => byte,] 1109 [ -Source => filename,] 1110 1111and this 1112 1113 [$db =] tie @arry, 'BerkeleyDB::Recno', 1114 [ -Filename => "filename", ] 1115 [ -Subname => "sub-database name", ] 1116 [ -Flags => flags,] 1117 [ -Property => flags,] 1118 [ -Mode => number,] 1119 [ -Cachesize => number,] 1120 [ -Lorder => number,] 1121 [ -Pagesize => number,] 1122 [ -Env => $env,] 1123 [ -Txn => $txn,] 1124 [ -Encrypt => { Password => "string", 1125 Flags => number }, ], 1126 # BerkeleyDB::Recno specific 1127 [ -Delim => byte,] 1128 [ -Len => number,] 1129 [ -Pad => byte,] 1130 [ -Source => filename,] 1131 1132=head2 A Recno Example 1133 1134Here is a simple example that uses RECNO (if you are using a version 1135of Perl earlier than 5.004_57 this example won't work -- see 1136L<Extra RECNO Methods> for a workaround). 1137 1138 use strict ; 1139 use BerkeleyDB ; 1140 1141 my $filename = "text" ; 1142 unlink $filename ; 1143 1144 my @h ; 1145 tie @h, 'BerkeleyDB::Recno', 1146 -Filename => $filename, 1147 -Flags => DB_CREATE, 1148 -Property => DB_RENUMBER 1149 or die "Cannot open $filename: $!\n" ; 1150 1151 # Add a few key/value pairs to the file 1152 $h[0] = "orange" ; 1153 $h[1] = "blue" ; 1154 $h[2] = "yellow" ; 1155 1156 push @h, "green", "black" ; 1157 1158 my $elements = scalar @h ; 1159 print "The array contains $elements entries\n" ; 1160 1161 my $last = pop @h ; 1162 print "popped $last\n" ; 1163 1164 unshift @h, "white" ; 1165 my $first = shift @h ; 1166 print "shifted $first\n" ; 1167 1168 # Check for existence of a key 1169 print "Element 1 Exists with value $h[1]\n" if $h[1] ; 1170 1171 untie @h ; 1172 1173Here is the output from the script: 1174 1175 The array contains 5 entries 1176 popped black 1177 shifted white 1178 Element 1 Exists with value blue 1179 The last element is green 1180 The 2nd last element is yellow 1181 1182=head1 BerkeleyDB::Queue 1183 1184Equivalent to calling B<db_create> followed by B<DB-E<gt>open> with 1185type B<DB_QUEUE> in Berkeley DB 3.x or greater. This database format 1186isn't available if you use Berkeley DB 2.x. 1187 1188Two forms of constructor are supported: 1189 1190 $db = new BerkeleyDB::Queue 1191 [ -Filename => "filename", ] 1192 [ -Subname => "sub-database name", ] 1193 [ -Flags => flags,] 1194 [ -Property => flags,] 1195 [ -Mode => number,] 1196 [ -Cachesize => number,] 1197 [ -Lorder => number,] 1198 [ -Pagesize => number,] 1199 [ -Env => $env,] 1200 [ -Txn => $txn,] 1201 [ -Encrypt => { Password => "string", 1202 Flags => number }, ], 1203 # BerkeleyDB::Queue specific 1204 [ -Len => number,] 1205 [ -Pad => byte,] 1206 [ -ExtentSize => number, ] 1207 1208and this 1209 1210 [$db =] tie @arry, 'BerkeleyDB::Queue', 1211 [ -Filename => "filename", ] 1212 [ -Subname => "sub-database name", ] 1213 [ -Flags => flags,] 1214 [ -Property => flags,] 1215 [ -Mode => number,] 1216 [ -Cachesize => number,] 1217 [ -Lorder => number,] 1218 [ -Pagesize => number,] 1219 [ -Env => $env,] 1220 [ -Txn => $txn,] 1221 [ -Encrypt => { Password => "string", 1222 Flags => number }, ], 1223 # BerkeleyDB::Queue specific 1224 [ -Len => number,] 1225 [ -Pad => byte,] 1226 1227 1228=head1 BerkeleyDB::Unknown 1229 1230This class is used to open an existing database. 1231 1232Equivalent to calling B<db_open> with type B<DB_UNKNOWN> in Berkeley DB 2.x and 1233calling B<db_create> followed by B<DB-E<gt>open> with type B<DB_UNKNOWN> in 1234Berkeley DB 3.x or greater. 1235 1236The constructor looks like this: 1237 1238 $db = new BerkeleyDB::Unknown 1239 [ -Filename => "filename", ] 1240 [ -Subname => "sub-database name", ] 1241 [ -Flags => flags,] 1242 [ -Property => flags,] 1243 [ -Mode => number,] 1244 [ -Cachesize => number,] 1245 [ -Lorder => number,] 1246 [ -Pagesize => number,] 1247 [ -Env => $env,] 1248 [ -Txn => $txn,] 1249 [ -Encrypt => { Password => "string", 1250 Flags => number }, ], 1251 1252 1253=head2 An example 1254 1255=head1 COMMON OPTIONS 1256 1257All database access class constructors support the common set of 1258options defined below. All are optional. 1259 1260=over 5 1261 1262=item -Filename 1263 1264The database filename. If no filename is specified, a temporary file will 1265be created and removed once the program terminates. 1266 1267=item -Subname 1268 1269Specifies the name of the sub-database to open. 1270This option is only valid if you are using Berkeley DB 3.x or greater. 1271 1272=item -Flags 1273 1274Specify how the database will be opened/created. The valid flags are: 1275 1276B<DB_CREATE> 1277 1278Create any underlying files, as necessary. If the files do not already 1279exist and the B<DB_CREATE> flag is not specified, the call will fail. 1280 1281B<DB_NOMMAP> 1282 1283Not supported by BerkeleyDB. 1284 1285B<DB_RDONLY> 1286 1287Opens the database in read-only mode. 1288 1289B<DB_THREAD> 1290 1291Not supported by BerkeleyDB. 1292 1293B<DB_TRUNCATE> 1294 1295If the database file already exists, remove all the data before 1296opening it. 1297 1298=item -Mode 1299 1300Determines the file protection when the database is created. Defaults 1301to 0666. 1302 1303=item -Cachesize 1304 1305=item -Lorder 1306 1307=item -Pagesize 1308 1309=item -Env 1310 1311When working under a Berkeley DB environment, this parameter 1312 1313Defaults to no environment. 1314 1315=item -Encrypt 1316 1317If present, this parameter will enable encryption of all data before 1318it is written to the database. This parameters must be given a hash 1319reference. The format is shown below. 1320 1321 -Encrypt => { -Password => "abc", Flags => DB_ENCRYPT_AES } 1322 1323Valid values for the Flags are 0 or C<DB_ENCRYPT_AES>. 1324 1325This option requires Berkeley DB 4.1 or better. 1326 1327=item -Txn 1328 1329TODO. 1330 1331=back 1332 1333=head1 COMMON DATABASE METHODS 1334 1335All the database interfaces support the common set of methods defined 1336below. 1337 1338All the methods below return 0 to indicate success. 1339 1340=head2 $status = $db->db_get($key, $value [, $flags]) 1341 1342Given a key (C<$key>) this method reads the value associated with it 1343from the database. If it exists, the value read from the database is 1344returned in the C<$value> parameter. 1345 1346The B<$flags> parameter is optional. If present, it must be set to B<one> 1347of the following values: 1348 1349=over 5 1350 1351=item B<DB_GET_BOTH> 1352 1353When the B<DB_GET_BOTH> flag is specified, B<db_get> checks for the 1354existence of B<both> the C<$key> B<and> C<$value> in the database. 1355 1356=item B<DB_SET_RECNO> 1357 1358TODO. 1359 1360=back 1361 1362In addition, the following value may be set by bitwise OR'ing it into 1363the B<$flags> parameter: 1364 1365=over 5 1366 1367=item B<DB_RMW> 1368 1369TODO 1370 1371=back 1372 1373 1374=head2 $status = $db->db_put($key, $value [, $flags]) 1375 1376Stores a key/value pair in the database. 1377 1378The B<$flags> parameter is optional. If present it must be set to B<one> 1379of the following values: 1380 1381=over 5 1382 1383=item B<DB_APPEND> 1384 1385This flag is only applicable when accessing a B<BerkeleyDB::Recno> 1386database. 1387 1388TODO. 1389 1390 1391=item B<DB_NOOVERWRITE> 1392 1393If this flag is specified and C<$key> already exists in the database, 1394the call to B<db_put> will return B<DB_KEYEXIST>. 1395 1396=back 1397 1398=head2 $status = $db->db_del($key [, $flags]) 1399 1400Deletes a key/value pair in the database associated with C<$key>. 1401If duplicate keys are enabled in the database, B<db_del> will delete 1402B<all> key/value pairs with key C<$key>. 1403 1404The B<$flags> parameter is optional and is currently unused. 1405 1406=head2 $status = $db->db_sync() 1407 1408If any parts of the database are in memory, write them to the database. 1409 1410=head2 $cursor = $db->db_cursor([$flags]) 1411 1412Creates a cursor object. This is used to access the contents of the 1413database sequentially. See L<CURSORS> for details of the methods 1414available when working with cursors. 1415 1416The B<$flags> parameter is optional. If present it must be set to B<one> 1417of the following values: 1418 1419=over 5 1420 1421=item B<DB_RMW> 1422 1423TODO. 1424 1425=back 1426 1427=head2 ($flag, $old_offset, $old_length) = $db->partial_set($offset, $length) ; 1428 1429TODO 1430 1431=head2 ($flag, $old_offset, $old_length) = $db->partial_clear() ; 1432 1433TODO 1434 1435=head2 $db->byteswapped() 1436 1437TODO 1438 1439=head2 $db->type() 1440 1441Returns the type of the database. The possible return code are B<DB_HASH> 1442for a B<BerkeleyDB::Hash> database, B<DB_BTREE> for a B<BerkeleyDB::Btree> 1443database and B<DB_RECNO> for a B<BerkeleyDB::Recno> database. This method 1444is typically used when a database has been opened with 1445B<BerkeleyDB::Unknown>. 1446 1447=head2 $bool = $env->cds_enabled(); 1448 1449Returns true if the Berkeley DB environment C<$env> has been opened on 1450CDS mode. 1451 1452=head2 $bool = $db->cds_enabled(); 1453 1454Returns true if the database C<$db> has been opened on CDS mode. 1455 1456=head2 $lock = $db->cds_lock(); 1457 1458Creates a CDS write lock object C<$lock>. 1459 1460It is a fatal error to attempt to create a cds_lock if the Berkeley DB 1461environment has not been opened in CDS mode. 1462 1463=head2 $lock->cds_unlock(); 1464 1465Removes a CDS lock. The destruction of the CDS lock object automatically 1466calls this method. 1467 1468Note that if multiple CDS lock objects are created, the underlying write 1469lock will not be released until all CDS lock objects are either explictly 1470unlocked with this method, or the CDS lock objects have been destroyed. 1471 1472=head2 $ref = $db->db_stat() 1473 1474Returns a reference to an associative array containing information about 1475the database. The keys of the associative array correspond directly to the 1476names of the fields defined in the Berkeley DB documentation. For example, 1477in the DB documentation, the field B<bt_version> stores the version of the 1478Btree database. Assuming you called B<db_stat> on a Btree database the 1479equivalent field would be accessed as follows: 1480 1481 $version = $ref->{'bt_version'} ; 1482 1483If you are using Berkeley DB 3.x or better, this method will work will 1484all database formats. When DB 2.x is used, it only works with 1485B<BerkeleyDB::Btree>. 1486 1487=head2 $status = $db->status() 1488 1489Returns the status of the last C<$db> method called. 1490 1491=head2 $status = $db->truncate($count) 1492 1493Truncates the datatabase and returns the number or records deleted 1494in C<$count>. 1495 1496=head2 $status = $db->compact($start, $stop, $c_data, $flags, $end); 1497 1498Compacts the database C<$db>. 1499 1500All the parameters are optional - if only want to make use of some of them, 1501use C<undef> for those you don't want. Trailing unusused parameters can be 1502omitted. For example, if you only want to use the C<$c_data> parameter to 1503set the C<compact_fillpercent>, write you code like this 1504 1505 my %hash; 1506 $hash{compact_fillpercent} = 50; 1507 $db->compact(undef, undef, \%hash); 1508 1509The parameters operate identically to the C equivalent of this method. 1510The C<$c_data> needs a bit of explanation - it must be a hash reference. 1511The values of the following keys can be set before calling C<compact> and 1512will affect the operation of the compaction. 1513 1514=over 5 1515 1516=item * compact_fillpercent 1517 1518=item * compact_timeout 1519 1520=back 1521 1522The following keys, along with associated values, will be created in the 1523hash reference if the C<compact> operation was successful. 1524 1525=over 5 1526 1527=item * compact_deadlock 1528 1529=item * compact_levels 1530 1531=item * compact_pages_free 1532 1533=item * compact_pages_examine 1534 1535=item * compact_pages_truncated 1536 1537=back 1538 1539You need to be running Berkeley DB 4.4 or better if you wan to make use of 1540C<compact>. 1541 1542=head1 CURSORS 1543 1544A cursor is used whenever you want to access the contents of a database 1545in sequential order. 1546A cursor object is created with the C<db_cursor> 1547 1548A cursor object has the following methods available: 1549 1550=head2 $newcursor = $cursor->c_dup($flags) 1551 1552Creates a duplicate of C<$cursor>. This method needs Berkeley DB 3.0.x or better. 1553 1554The C<$flags> parameter is optional and can take the following value: 1555 1556=over 5 1557 1558=item DB_POSITION 1559 1560When present this flag will position the new cursor at the same place as the 1561existing cursor. 1562 1563=back 1564 1565=head2 $status = $cursor->c_get($key, $value, $flags) 1566 1567Reads a key/value pair from the database, returning the data in C<$key> 1568and C<$value>. The key/value pair actually read is controlled by the 1569C<$flags> parameter, which can take B<one> of the following values: 1570 1571=over 5 1572 1573=item B<DB_FIRST> 1574 1575Set the cursor to point to the first key/value pair in the 1576database. Return the key/value pair in C<$key> and C<$value>. 1577 1578=item B<DB_LAST> 1579 1580Set the cursor to point to the last key/value pair in the database. Return 1581the key/value pair in C<$key> and C<$value>. 1582 1583=item B<DB_NEXT> 1584 1585If the cursor is already pointing to a key/value pair, it will be 1586incremented to point to the next key/value pair and return its contents. 1587 1588If the cursor isn't initialised, B<DB_NEXT> works just like B<DB_FIRST>. 1589 1590If the cursor is already positioned at the last key/value pair, B<c_get> 1591will return B<DB_NOTFOUND>. 1592 1593=item B<DB_NEXT_DUP> 1594 1595This flag is only valid when duplicate keys have been enabled in 1596a database. 1597If the cursor is already pointing to a key/value pair and the key of 1598the next key/value pair is identical, the cursor will be incremented to 1599point to it and their contents returned. 1600 1601=item B<DB_PREV> 1602 1603If the cursor is already pointing to a key/value pair, it will be 1604decremented to point to the previous key/value pair and return its 1605contents. 1606 1607If the cursor isn't initialised, B<DB_PREV> works just like B<DB_LAST>. 1608 1609If the cursor is already positioned at the first key/value pair, B<c_get> 1610will return B<DB_NOTFOUND>. 1611 1612=item B<DB_CURRENT> 1613 1614If the cursor has been set to point to a key/value pair, return their 1615contents. 1616If the key/value pair referenced by the cursor has been deleted, B<c_get> 1617will return B<DB_KEYEMPTY>. 1618 1619=item B<DB_SET> 1620 1621Set the cursor to point to the key/value pair referenced by B<$key> 1622and return the value in B<$value>. 1623 1624=item B<DB_SET_RANGE> 1625 1626This flag is a variation on the B<DB_SET> flag. As well as returning 1627the value, it also returns the key, via B<$key>. 1628When used with a B<BerkeleyDB::Btree> database the key matched by B<c_get> 1629will be the shortest key (in length) which is greater than or equal to 1630the key supplied, via B<$key>. This allows partial key searches. 1631See ??? for an example of how to use this flag. 1632 1633=item B<DB_GET_BOTH> 1634 1635Another variation on B<DB_SET>. This one returns both the key and 1636the value. 1637 1638=item B<DB_SET_RECNO> 1639 1640TODO. 1641 1642=item B<DB_GET_RECNO> 1643 1644TODO. 1645 1646=back 1647 1648In addition, the following value may be set by bitwise OR'ing it into 1649the B<$flags> parameter: 1650 1651=over 5 1652 1653=item B<DB_RMW> 1654 1655TODO. 1656 1657=back 1658 1659=head2 $status = $cursor->c_put($key, $value, $flags) 1660 1661Stores the key/value pair in the database. The position that the data is 1662stored in the database is controlled by the C<$flags> parameter, which 1663must take B<one> of the following values: 1664 1665=over 5 1666 1667=item B<DB_AFTER> 1668 1669When used with a Btree or Hash database, a duplicate of the key referenced 1670by the current cursor position will be created and the contents of 1671B<$value> will be associated with it - B<$key> is ignored. 1672The new key/value pair will be stored immediately after the current 1673cursor position. 1674Obviously the database has to have been opened with B<DB_DUP>. 1675 1676When used with a Recno ... TODO 1677 1678 1679=item B<DB_BEFORE> 1680 1681When used with a Btree or Hash database, a duplicate of the key referenced 1682by the current cursor position will be created and the contents of 1683B<$value> will be associated with it - B<$key> is ignored. 1684The new key/value pair will be stored immediately before the current 1685cursor position. 1686Obviously the database has to have been opened with B<DB_DUP>. 1687 1688When used with a Recno ... TODO 1689 1690=item B<DB_CURRENT> 1691 1692If the cursor has been initialised, replace the value of the key/value 1693pair stored in the database with the contents of B<$value>. 1694 1695=item B<DB_KEYFIRST> 1696 1697Only valid with a Btree or Hash database. This flag is only really 1698used when duplicates are enabled in the database and sorted duplicates 1699haven't been specified. 1700In this case the key/value pair will be inserted as the first entry in 1701the duplicates for the particular key. 1702 1703=item B<DB_KEYLAST> 1704 1705Only valid with a Btree or Hash database. This flag is only really 1706used when duplicates are enabled in the database and sorted duplicates 1707haven't been specified. 1708In this case the key/value pair will be inserted as the last entry in 1709the duplicates for the particular key. 1710 1711=back 1712 1713=head2 $status = $cursor->c_del([$flags]) 1714 1715This method deletes the key/value pair associated with the current cursor 1716position. The cursor position will not be changed by this operation, so 1717any subsequent cursor operation must first initialise the cursor to 1718point to a valid key/value pair. 1719 1720If the key/value pair associated with the cursor have already been 1721deleted, B<c_del> will return B<DB_KEYEMPTY>. 1722 1723The B<$flags> parameter is not used at present. 1724 1725=head2 $status = $cursor->c_count($cnt [, $flags]) 1726 1727Stores the number of duplicates at the current cursor position in B<$cnt>. 1728 1729The B<$flags> parameter is not used at present. This method needs 1730Berkeley DB 3.1 or better. 1731 1732=head2 $status = $cursor->status() 1733 1734Returns the status of the last cursor method as a dual type. 1735 1736=head2 $status = $cursor->c_pget() ; 1737 1738TODO 1739 1740=head2 $status = $cursor->c_close() 1741 1742Closes the cursor B<$cursor>. 1743 1744=head2 Cursor Examples 1745 1746TODO 1747 1748Iterating from first to last, then in reverse. 1749 1750examples of each of the flags. 1751 1752=head1 JOIN 1753 1754Join support for BerkeleyDB is in progress. Watch this space. 1755 1756TODO 1757 1758=head1 TRANSACTIONS 1759 1760TODO. 1761 1762=head1 CDS Mode 1763 1764The Berkeley Db Concurrent Data Store is a lightweight locking mechanism 1765that is useful in scenarios where transactions are overkill. See the 1766accompanying document .. for details of using this module in CDS mode. 1767 1768=head1 DBM Filters 1769 1770A DBM Filter is a piece of code that is be used when you I<always> 1771want to make the same transformation to all keys and/or values in a DBM 1772database. All of the database classes (BerkeleyDB::Hash, 1773BerkeleyDB::Btree and BerkeleyDB::Recno) support DBM Filters. 1774 1775There are four methods associated with DBM Filters. All work 1776identically, and each is used to install (or uninstall) a single DBM 1777Filter. Each expects a single parameter, namely a reference to a sub. 1778The only difference between them is the place that the filter is 1779installed. 1780 1781To summarise: 1782 1783=over 5 1784 1785=item B<filter_store_key> 1786 1787If a filter has been installed with this method, it will be invoked 1788every time you write a key to a DBM database. 1789 1790=item B<filter_store_value> 1791 1792If a filter has been installed with this method, it will be invoked 1793every time you write a value to a DBM database. 1794 1795 1796=item B<filter_fetch_key> 1797 1798If a filter has been installed with this method, it will be invoked 1799every time you read a key from a DBM database. 1800 1801=item B<filter_fetch_value> 1802 1803If a filter has been installed with this method, it will be invoked 1804every time you read a value from a DBM database. 1805 1806=back 1807 1808You can use any combination of the methods, from none, to all four. 1809 1810All filter methods return the existing filter, if present, or C<undef> 1811in not. 1812 1813To delete a filter pass C<undef> to it. 1814 1815=head2 The Filter 1816 1817When each filter is called by Perl, a local copy of C<$_> will contain 1818the key or value to be filtered. Filtering is achieved by modifying 1819the contents of C<$_>. The return code from the filter is ignored. 1820 1821=head2 An Example -- the NULL termination problem. 1822 1823Consider the following scenario. You have a DBM database that you need 1824to share with a third-party C application. The C application assumes 1825that I<all> keys and values are NULL terminated. Unfortunately when 1826Perl writes to DBM databases it doesn't use NULL termination, so your 1827Perl application will have to manage NULL termination itself. When you 1828write to the database you will have to use something like this: 1829 1830 $hash{"$key\0"} = "$value\0" ; 1831 1832Similarly the NULL needs to be taken into account when you are considering 1833the length of existing keys/values. 1834 1835It would be much better if you could ignore the NULL terminations issue 1836in the main application code and have a mechanism that automatically 1837added the terminating NULL to all keys and values whenever you write to 1838the database and have them removed when you read from the database. As I'm 1839sure you have already guessed, this is a problem that DBM Filters can 1840fix very easily. 1841 1842 use strict ; 1843 use BerkeleyDB ; 1844 1845 my %hash ; 1846 my $filename = "filt.db" ; 1847 unlink $filename ; 1848 1849 my $db = tie %hash, 'BerkeleyDB::Hash', 1850 -Filename => $filename, 1851 -Flags => DB_CREATE 1852 or die "Cannot open $filename: $!\n" ; 1853 1854 # Install DBM Filters 1855 $db->filter_fetch_key ( sub { s/\0$// } ) ; 1856 $db->filter_store_key ( sub { $_ .= "\0" } ) ; 1857 $db->filter_fetch_value( sub { s/\0$// } ) ; 1858 $db->filter_store_value( sub { $_ .= "\0" } ) ; 1859 1860 $hash{"abc"} = "def" ; 1861 my $a = $hash{"ABC"} ; 1862 # ... 1863 undef $db ; 1864 untie %hash ; 1865 1866Hopefully the contents of each of the filters should be 1867self-explanatory. Both "fetch" filters remove the terminating NULL, 1868and both "store" filters add a terminating NULL. 1869 1870 1871=head2 Another Example -- Key is a C int. 1872 1873Here is another real-life example. By default, whenever Perl writes to 1874a DBM database it always writes the key and value as strings. So when 1875you use this: 1876 1877 $hash{12345} = "something" ; 1878 1879the key 12345 will get stored in the DBM database as the 5 byte string 1880"12345". If you actually want the key to be stored in the DBM database 1881as a C int, you will have to use C<pack> when writing, and C<unpack> 1882when reading. 1883 1884Here is a DBM Filter that does it: 1885 1886 use strict ; 1887 use BerkeleyDB ; 1888 my %hash ; 1889 my $filename = "filt.db" ; 1890 unlink $filename ; 1891 1892 1893 my $db = tie %hash, 'BerkeleyDB::Btree', 1894 -Filename => $filename, 1895 -Flags => DB_CREATE 1896 or die "Cannot open $filename: $!\n" ; 1897 1898 $db->filter_fetch_key ( sub { $_ = unpack("i", $_) } ) ; 1899 $db->filter_store_key ( sub { $_ = pack ("i", $_) } ) ; 1900 $hash{123} = "def" ; 1901 # ... 1902 undef $db ; 1903 untie %hash ; 1904 1905This time only two filters have been used -- we only need to manipulate 1906the contents of the key, so it wasn't necessary to install any value 1907filters. 1908 1909=head1 Using BerkeleyDB with MLDBM 1910 1911Both BerkeleyDB::Hash and BerkeleyDB::Btree can be used with the MLDBM 1912module. The code fragment below shows how to open associate MLDBM with 1913BerkeleyDB::Btree. To use BerkeleyDB::Hash just replace 1914BerkeleyDB::Btree with BerkeleyDB::Hash. 1915 1916 use strict ; 1917 use BerkeleyDB ; 1918 use MLDBM qw(BerkeleyDB::Btree) ; 1919 use Data::Dumper; 1920 1921 my $filename = 'testmldbm' ; 1922 my %o ; 1923 1924 unlink $filename ; 1925 tie %o, 'MLDBM', -Filename => $filename, 1926 -Flags => DB_CREATE 1927 or die "Cannot open database '$filename: $!\n"; 1928 1929See the MLDBM documentation for information on how to use the module 1930and for details of its limitations. 1931 1932=head1 EXAMPLES 1933 1934TODO. 1935 1936=head1 HINTS & TIPS 1937 1938=head2 Sharing Databases With C Applications 1939 1940There is no technical reason why a Berkeley DB database cannot be 1941shared by both a Perl and a C application. 1942 1943The vast majority of problems that are reported in this area boil down 1944to the fact that C strings are NULL terminated, whilst Perl strings 1945are not. See L<An Example -- the NULL termination problem.> in the DBM 1946FILTERS section for a generic way to work around this problem. 1947 1948 1949=head2 The untie Gotcha 1950 1951TODO 1952 1953=head1 COMMON QUESTIONS 1954 1955This section attempts to answer some of the more common questions that 1956I get asked. 1957 1958 1959=head2 Relationship with DB_File 1960 1961Before Berkeley DB 2.x was written there was only one Perl module that 1962interfaced to Berkeley DB. That module is called B<DB_File>. Although 1963B<DB_File> can be build with Berkeley DB 1.x, 2.x, 3.x or 4.x, it only 1964provides an interface to the functionality available in Berkeley DB 19651.x. That means that it doesn't support transactions, locking or any of 1966the other new features available in DB 2.x or better. 1967 1968=head2 How do I store Perl data structures with BerkeleyDB? 1969 1970See L<Using BerkeleyDB with MLDBM>. 1971 1972=head1 HISTORY 1973 1974See the Changes file. 1975 1976=head1 AVAILABILITY 1977 1978The most recent version of B<BerkeleyDB> can always be found 1979on CPAN (see L<perlmod/CPAN> for details), in the directory 1980F<modules/by-module/BerkeleyDB>. 1981 1982The official web site for Berkeley DB is F<http://www.oracle.com/technology/products/berkeley-db/db/index.html>. 1983 1984=head1 COPYRIGHT 1985 1986Copyright (c) 1997-2004 Paul Marquess. All rights reserved. This program 1987is free software; you can redistribute it and/or modify it under the 1988same terms as Perl itself. 1989 1990Although B<BerkeleyDB> is covered by the Perl license, the library it 1991makes use of, namely Berkeley DB, is not. Berkeley DB has its own 1992copyright and its own license. Please take the time to read it. 1993 1994Here are few words taken from the Berkeley DB FAQ (at 1995F<http://www.oracle.com/technology/products/berkeley-db/db/index.html>) regarding the license: 1996 1997 Do I have to license DB to use it in Perl scripts? 1998 1999 No. The Berkeley DB license requires that software that uses 2000 Berkeley DB be freely redistributable. In the case of Perl, that 2001 software is Perl, and not your scripts. Any Perl scripts that you 2002 write are your property, including scripts that make use of Berkeley 2003 DB. Neither the Perl license nor the Berkeley DB license 2004 place any restriction on what you may do with them. 2005 2006If you are in any doubt about the license situation, contact either the 2007Berkeley DB authors or the author of BerkeleyDB. 2008See L<"AUTHOR"> for details. 2009 2010 2011=head1 AUTHOR 2012 2013Paul Marquess E<lt>pmqs@cpan.orgE<gt>. 2014 2015 2016=head1 SEE ALSO 2017 2018perl(1), DB_File, Berkeley DB. 2019 2020=cut 2021