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## simpleHash 657 658here is the output: 659 660 Banana Exists 661 662 orange -> orange 663 tomato -> red 664 banana -> yellow 665 666Note that the like ordinary associative arrays, the order of the keys 667retrieved from a Hash database are in an apparently random order. 668 669=head2 Another Simple Hash Example 670 671Do the same as the previous example but not using tie. 672 673## simpleHash2 674 675=head2 Duplicate keys 676 677The code below is a variation on the examples above. This time the hash has 678been inverted. The key this time is colour and the value is the fruit name. 679The B<DB_DUP> flag has been specified to allow duplicates. 680 681##dupHash 682 683here is the output: 684 685 orange -> orange 686 yellow -> banana 687 red -> apple 688 red -> tomato 689 green -> banana 690 green -> apple 691 692=head2 Sorting Duplicate Keys 693 694In the previous example, when there were duplicate keys, the values are 695sorted in the order they are stored in. The code below is 696identical to the previous example except the B<DB_DUPSORT> flag is 697specified. 698 699##dupSortHash 700 701Notice that in the output below the duplicate values are sorted. 702 703 orange -> orange 704 yellow -> banana 705 red -> apple 706 red -> tomato 707 green -> apple 708 green -> banana 709 710=head2 Custom Sorting Duplicate Keys 711 712Another variation 713 714TODO 715 716=head2 Changing the hash 717 718TODO 719 720=head2 Using db_stat 721 722TODO 723 724=head1 BerkeleyDB::Btree 725 726Equivalent to calling B<db_open> with type B<DB_BTREE> in Berkeley DB 2.x and 727calling B<db_create> followed by B<DB-E<gt>open> with type B<DB_BTREE> in 728Berkeley DB 3.x or greater. 729 730Two forms of constructor are supported: 731 732 733 $db = new BerkeleyDB::Btree 734 [ -Filename => "filename", ] 735 [ -Subname => "sub-database name", ] 736 [ -Flags => flags,] 737 [ -Property => flags,] 738 [ -Mode => number,] 739 [ -Cachesize => number,] 740 [ -Lorder => number,] 741 [ -Pagesize => number,] 742 [ -Env => $env,] 743 [ -Txn => $txn,] 744 [ -Encrypt => { Password => "string", 745 Flags => number }, ], 746 # BerkeleyDB::Btree specific 747 [ -Minkey => number,] 748 [ -Compare => code reference,] 749 [ -DupCompare => code reference,] 750 [ -Prefix => code reference,] 751 752and this 753 754 [$db =] tie %hash, 'BerkeleyDB::Btree', 755 [ -Filename => "filename", ] 756 [ -Subname => "sub-database name", ] 757 [ -Flags => flags,] 758 [ -Property => flags,] 759 [ -Mode => number,] 760 [ -Cachesize => number,] 761 [ -Lorder => number,] 762 [ -Pagesize => number,] 763 [ -Env => $env,] 764 [ -Txn => $txn,] 765 [ -Encrypt => { Password => "string", 766 Flags => number }, ], 767 # BerkeleyDB::Btree specific 768 [ -Minkey => number,] 769 [ -Compare => code reference,] 770 [ -DupCompare => code reference,] 771 [ -Prefix => code reference,] 772 773=head2 Options 774 775In addition to the standard set of options (see L<COMMON OPTIONS>) 776B<BerkeleyDB::Btree> supports these options: 777 778=over 5 779 780=item -Property 781 782Used to specify extra flags when opening a database. The following 783flags may be specified by bitwise OR'ing together one or more of the 784following values: 785 786B<DB_DUP> 787 788When creating a new database, this flag enables the storing of duplicate 789keys in the database. If B<DB_DUPSORT> is not specified as well, the 790duplicates are stored in the order they are created in the database. 791 792B<DB_DUPSORT> 793 794Enables the sorting of duplicate keys in the database. Ignored if 795B<DB_DUP> isn't also specified. 796 797=item Minkey 798 799TODO 800 801=item Compare 802 803Allow you to override the default sort order used in the database. See 804L<"Changing the sort order"> for an example. 805 806 sub compare 807 { 808 my ($key, $key2) = @_ ; 809 ... 810 # return 0 if $key1 eq $key2 811 # -1 if $key1 lt $key2 812 # 1 if $key1 gt $key2 813 return (-1 , 0 or 1) ; 814 } 815 816 tie %h, "BerkeleyDB::Hash", 817 -Filename => $filename, 818 -Compare => \&compare, 819 ... 820 821=item Prefix 822 823 sub prefix 824 { 825 my ($key, $key2) = @_ ; 826 ... 827 # return number of bytes of $key2 which are 828 # necessary to determine that it is greater than $key1 829 return $bytes ; 830 } 831 832 tie %h, "BerkeleyDB::Hash", 833 -Filename => $filename, 834 -Prefix => \&prefix, 835 ... 836=item DupCompare 837 838 sub compare 839 { 840 my ($key, $key2) = @_ ; 841 ... 842 # return 0 if $key1 eq $key2 843 # -1 if $key1 lt $key2 844 # 1 if $key1 gt $key2 845 return (-1 , 0 or 1) ; 846 } 847 848 tie %h, "BerkeleyDB::Hash", 849 -Filename => $filename, 850 -DupCompare => \&compare, 851 ... 852 853=back 854 855=head2 Methods 856 857B<BerkeleyDB::Btree> supports the following database methods. 858See also L<COMMON DATABASE METHODS>. 859 860All the methods below return 0 to indicate success. 861 862=over 5 863 864=item $status = $db->db_key_range($key, $less, $equal, $greater [, $flags]) 865 866Given a key, C<$key>, this method returns the proportion of keys less than 867C<$key> in C<$less>, the proportion equal to C<$key> in C<$equal> and the 868proportion greater than C<$key> in C<$greater>. 869 870The proportion is returned as a double in the range 0.0 to 1.0. 871 872=back 873 874=head2 A Simple Btree Example 875 876The code below is a simple example of using a btree database. 877 878## btreeSimple 879 880Here is the output from the code above. The keys have been sorted using 881Berkeley DB's default sorting algorithm. 882 883 Smith 884 Wall 885 mouse 886 887 888=head2 Changing the sort order 889 890It is possible to supply your own sorting algorithm if the one that Berkeley 891DB used isn't suitable. The code below is identical to the previous example 892except for the case insensitive compare function. 893 894## btreeSortOrder 895 896Here is the output from the code above. 897 898 mouse 899 Smith 900 Wall 901 902There are a few point to bear in mind if you want to change the 903ordering in a BTREE database: 904 905=over 5 906 907=item 1. 908 909The new compare function must be specified when you create the database. 910 911=item 2. 912 913You cannot change the ordering once the database has been created. Thus 914you must use the same compare function every time you access the 915database. 916 917=back 918 919=head2 Using db_stat 920 921TODO 922 923=head1 BerkeleyDB::Recno 924 925Equivalent to calling B<db_open> with type B<DB_RECNO> in Berkeley DB 2.x and 926calling B<db_create> followed by B<DB-E<gt>open> with type B<DB_RECNO> in 927Berkeley DB 3.x or greater. 928 929Two forms of constructor are supported: 930 931 $db = new BerkeleyDB::Recno 932 [ -Filename => "filename", ] 933 [ -Subname => "sub-database name", ] 934 [ -Flags => flags,] 935 [ -Property => flags,] 936 [ -Mode => number,] 937 [ -Cachesize => number,] 938 [ -Lorder => number,] 939 [ -Pagesize => number,] 940 [ -Env => $env,] 941 [ -Txn => $txn,] 942 [ -Encrypt => { Password => "string", 943 Flags => number }, ], 944 # BerkeleyDB::Recno specific 945 [ -Delim => byte,] 946 [ -Len => number,] 947 [ -Pad => byte,] 948 [ -Source => filename,] 949 950and this 951 952 [$db =] tie @arry, 'BerkeleyDB::Recno', 953 [ -Filename => "filename", ] 954 [ -Subname => "sub-database name", ] 955 [ -Flags => flags,] 956 [ -Property => flags,] 957 [ -Mode => number,] 958 [ -Cachesize => number,] 959 [ -Lorder => number,] 960 [ -Pagesize => number,] 961 [ -Env => $env,] 962 [ -Txn => $txn,] 963 [ -Encrypt => { Password => "string", 964 Flags => number }, ], 965 # BerkeleyDB::Recno specific 966 [ -Delim => byte,] 967 [ -Len => number,] 968 [ -Pad => byte,] 969 [ -Source => filename,] 970 971=head2 A Recno Example 972 973Here is a simple example that uses RECNO (if you are using a version 974of Perl earlier than 5.004_57 this example won't work -- see 975L<Extra RECNO Methods> for a workaround). 976 977## simpleRecno 978 979Here is the output from the script: 980 981 The array contains 5 entries 982 popped black 983 shifted white 984 Element 1 Exists with value blue 985 The last element is green 986 The 2nd last element is yellow 987 988=head1 BerkeleyDB::Queue 989 990Equivalent to calling B<db_create> followed by B<DB-E<gt>open> with 991type B<DB_QUEUE> in Berkeley DB 3.x or greater. This database format 992isn't available if you use Berkeley DB 2.x. 993 994Two forms of constructor are supported: 995 996 $db = new BerkeleyDB::Queue 997 [ -Filename => "filename", ] 998 [ -Subname => "sub-database name", ] 999 [ -Flags => flags,] 1000 [ -Property => flags,] 1001 [ -Mode => number,] 1002 [ -Cachesize => number,] 1003 [ -Lorder => number,] 1004 [ -Pagesize => number,] 1005 [ -Env => $env,] 1006 [ -Txn => $txn,] 1007 [ -Encrypt => { Password => "string", 1008 Flags => number }, ], 1009 # BerkeleyDB::Queue specific 1010 [ -Len => number,] 1011 [ -Pad => byte,] 1012 [ -ExtentSize => number, ] 1013 1014and this 1015 1016 [$db =] tie @arry, 'BerkeleyDB::Queue', 1017 [ -Filename => "filename", ] 1018 [ -Subname => "sub-database name", ] 1019 [ -Flags => flags,] 1020 [ -Property => flags,] 1021 [ -Mode => number,] 1022 [ -Cachesize => number,] 1023 [ -Lorder => number,] 1024 [ -Pagesize => number,] 1025 [ -Env => $env,] 1026 [ -Txn => $txn,] 1027 [ -Encrypt => { Password => "string", 1028 Flags => number }, ], 1029 # BerkeleyDB::Queue specific 1030 [ -Len => number,] 1031 [ -Pad => byte,] 1032 1033 1034=head1 BerkeleyDB::Unknown 1035 1036This class is used to open an existing database. 1037 1038Equivalent to calling B<db_open> with type B<DB_UNKNOWN> in Berkeley DB 2.x and 1039calling B<db_create> followed by B<DB-E<gt>open> with type B<DB_UNKNOWN> in 1040Berkeley DB 3.x or greater. 1041 1042The constructor looks like this: 1043 1044 $db = new BerkeleyDB::Unknown 1045 [ -Filename => "filename", ] 1046 [ -Subname => "sub-database name", ] 1047 [ -Flags => flags,] 1048 [ -Property => flags,] 1049 [ -Mode => number,] 1050 [ -Cachesize => number,] 1051 [ -Lorder => number,] 1052 [ -Pagesize => number,] 1053 [ -Env => $env,] 1054 [ -Txn => $txn,] 1055 [ -Encrypt => { Password => "string", 1056 Flags => number }, ], 1057 1058 1059=head2 An example 1060 1061=head1 COMMON OPTIONS 1062 1063All database access class constructors support the common set of 1064options defined below. All are optional. 1065 1066=over 5 1067 1068=item -Filename 1069 1070The database filename. If no filename is specified, a temporary file will 1071be created and removed once the program terminates. 1072 1073=item -Subname 1074 1075Specifies the name of the sub-database to open. 1076This option is only valid if you are using Berkeley DB 3.x or greater. 1077 1078=item -Flags 1079 1080Specify how the database will be opened/created. The valid flags are: 1081 1082B<DB_CREATE> 1083 1084Create any underlying files, as necessary. If the files do not already 1085exist and the B<DB_CREATE> flag is not specified, the call will fail. 1086 1087B<DB_NOMMAP> 1088 1089Not supported by BerkeleyDB. 1090 1091B<DB_RDONLY> 1092 1093Opens the database in read-only mode. 1094 1095B<DB_THREAD> 1096 1097Not supported by BerkeleyDB. 1098 1099B<DB_TRUNCATE> 1100 1101If the database file already exists, remove all the data before 1102opening it. 1103 1104=item -Mode 1105 1106Determines the file protection when the database is created. Defaults 1107to 0666. 1108 1109=item -Cachesize 1110 1111=item -Lorder 1112 1113=item -Pagesize 1114 1115=item -Env 1116 1117When working under a Berkeley DB environment, this parameter 1118 1119Defaults to no environment. 1120 1121=item -Encrypt 1122 1123If present, this parameter will enable encryption of all data before 1124it is written to the database. This parameters must be given a hash 1125reference. The format is shown below. 1126 1127 -Encrypt => { -Password => "abc", Flags => DB_ENCRYPT_AES } 1128 1129Valid values for the Flags are 0 or C<DB_ENCRYPT_AES>. 1130 1131This option requires Berkeley DB 4.1 or better. 1132 1133=item -Txn 1134 1135TODO. 1136 1137=back 1138 1139=head1 COMMON DATABASE METHODS 1140 1141All the database interfaces support the common set of methods defined 1142below. 1143 1144All the methods below return 0 to indicate success. 1145 1146=head2 $status = $db->db_get($key, $value [, $flags]) 1147 1148Given a key (C<$key>) this method reads the value associated with it 1149from the database. If it exists, the value read from the database is 1150returned in the C<$value> parameter. 1151 1152The B<$flags> parameter is optional. If present, it must be set to B<one> 1153of the following values: 1154 1155=over 5 1156 1157=item B<DB_GET_BOTH> 1158 1159When the B<DB_GET_BOTH> flag is specified, B<db_get> checks for the 1160existence of B<both> the C<$key> B<and> C<$value> in the database. 1161 1162=item B<DB_SET_RECNO> 1163 1164TODO. 1165 1166=back 1167 1168In addition, the following value may be set by bitwise OR'ing it into 1169the B<$flags> parameter: 1170 1171=over 5 1172 1173=item B<DB_RMW> 1174 1175TODO 1176 1177=back 1178 1179 1180=head2 $status = $db->db_put($key, $value [, $flags]) 1181 1182Stores a key/value pair in the database. 1183 1184The B<$flags> parameter is optional. If present it must be set to B<one> 1185of the following values: 1186 1187=over 5 1188 1189=item B<DB_APPEND> 1190 1191This flag is only applicable when accessing a B<BerkeleyDB::Recno> 1192database. 1193 1194TODO. 1195 1196 1197=item B<DB_NOOVERWRITE> 1198 1199If this flag is specified and C<$key> already exists in the database, 1200the call to B<db_put> will return B<DB_KEYEXIST>. 1201 1202=back 1203 1204=head2 $status = $db->db_del($key [, $flags]) 1205 1206Deletes a key/value pair in the database associated with C<$key>. 1207If duplicate keys are enabled in the database, B<db_del> will delete 1208B<all> key/value pairs with key C<$key>. 1209 1210The B<$flags> parameter is optional and is currently unused. 1211 1212=head2 $status = $db->db_sync() 1213 1214If any parts of the database are in memory, write them to the database. 1215 1216=head2 $cursor = $db->db_cursor([$flags]) 1217 1218Creates a cursor object. This is used to access the contents of the 1219database sequentially. See L<CURSORS> for details of the methods 1220available when working with cursors. 1221 1222The B<$flags> parameter is optional. If present it must be set to B<one> 1223of the following values: 1224 1225=over 5 1226 1227=item B<DB_RMW> 1228 1229TODO. 1230 1231=back 1232 1233=head2 ($flag, $old_offset, $old_length) = $db->partial_set($offset, $length) ; 1234 1235TODO 1236 1237=head2 ($flag, $old_offset, $old_length) = $db->partial_clear() ; 1238 1239TODO 1240 1241=head2 $db->byteswapped() 1242 1243TODO 1244 1245=head2 $db->type() 1246 1247Returns the type of the database. The possible return code are B<DB_HASH> 1248for a B<BerkeleyDB::Hash> database, B<DB_BTREE> for a B<BerkeleyDB::Btree> 1249database and B<DB_RECNO> for a B<BerkeleyDB::Recno> database. This method 1250is typically used when a database has been opened with 1251B<BerkeleyDB::Unknown>. 1252 1253=head2 $bool = $env->cds_enabled(); 1254 1255Returns true if the Berkeley DB environment C<$env> has been opened on 1256CDS mode. 1257 1258=head2 $bool = $db->cds_enabled(); 1259 1260Returns true if the database C<$db> has been opened on CDS mode. 1261 1262=head2 $lock = $db->cds_lock(); 1263 1264Creates a CDS write lock object C<$lock>. 1265 1266It is a fatal error to attempt to create a cds_lock if the Berkeley DB 1267environment has not been opened in CDS mode. 1268 1269=head2 $lock->cds_unlock(); 1270 1271Removes a CDS lock. The destruction of the CDS lock object automatically 1272calls this method. 1273 1274Note that if multiple CDS lock objects are created, the underlying write 1275lock will not be released until all CDS lock objects are either explictly 1276unlocked with this method, or the CDS lock objects have been destroyed. 1277 1278=head2 $ref = $db->db_stat() 1279 1280Returns a reference to an associative array containing information about 1281the database. The keys of the associative array correspond directly to the 1282names of the fields defined in the Berkeley DB documentation. For example, 1283in the DB documentation, the field B<bt_version> stores the version of the 1284Btree database. Assuming you called B<db_stat> on a Btree database the 1285equivalent field would be accessed as follows: 1286 1287 $version = $ref->{'bt_version'} ; 1288 1289If you are using Berkeley DB 3.x or better, this method will work will 1290all database formats. When DB 2.x is used, it only works with 1291B<BerkeleyDB::Btree>. 1292 1293=head2 $status = $db->status() 1294 1295Returns the status of the last C<$db> method called. 1296 1297=head2 $status = $db->truncate($count) 1298 1299Truncates the datatabase and returns the number or records deleted 1300in C<$count>. 1301 1302=head2 $status = $db->compact($start, $stop, $c_data, $flags, $end); 1303 1304Compacts the database C<$db>. 1305 1306All the parameters are optional - if only want to make use of some of them, 1307use C<undef> for those you don't want. Trailing unusused parameters can be 1308omitted. For example, if you only want to use the C<$c_data> parameter to 1309set the C<compact_fillpercent>, write you code like this 1310 1311 my %hash; 1312 $hash{compact_fillpercent} = 50; 1313 $db->compact(undef, undef, \%hash); 1314 1315The parameters operate identically to the C equivalent of this method. 1316The C<$c_data> needs a bit of explanation - it must be a hash reference. 1317The values of the following keys can be set before calling C<compact> and 1318will affect the operation of the compaction. 1319 1320=over 5 1321 1322=item * compact_fillpercent 1323 1324=item * compact_timeout 1325 1326=back 1327 1328The following keys, along with associated values, will be created in the 1329hash reference if the C<compact> operation was successful. 1330 1331=over 5 1332 1333=item * compact_deadlock 1334 1335=item * compact_levels 1336 1337=item * compact_pages_free 1338 1339=item * compact_pages_examine 1340 1341=item * compact_pages_truncated 1342 1343=back 1344 1345You need to be running Berkeley DB 4.4 or better if you wan to make use of 1346C<compact>. 1347 1348=head1 CURSORS 1349 1350A cursor is used whenever you want to access the contents of a database 1351in sequential order. 1352A cursor object is created with the C<db_cursor> 1353 1354A cursor object has the following methods available: 1355 1356=head2 $newcursor = $cursor->c_dup($flags) 1357 1358Creates a duplicate of C<$cursor>. This method needs Berkeley DB 3.0.x or better. 1359 1360The C<$flags> parameter is optional and can take the following value: 1361 1362=over 5 1363 1364=item DB_POSITION 1365 1366When present this flag will position the new cursor at the same place as the 1367existing cursor. 1368 1369=back 1370 1371=head2 $status = $cursor->c_get($key, $value, $flags) 1372 1373Reads a key/value pair from the database, returning the data in C<$key> 1374and C<$value>. The key/value pair actually read is controlled by the 1375C<$flags> parameter, which can take B<one> of the following values: 1376 1377=over 5 1378 1379=item B<DB_FIRST> 1380 1381Set the cursor to point to the first key/value pair in the 1382database. Return the key/value pair in C<$key> and C<$value>. 1383 1384=item B<DB_LAST> 1385 1386Set the cursor to point to the last key/value pair in the database. Return 1387the key/value pair in C<$key> and C<$value>. 1388 1389=item B<DB_NEXT> 1390 1391If the cursor is already pointing to a key/value pair, it will be 1392incremented to point to the next key/value pair and return its contents. 1393 1394If the cursor isn't initialised, B<DB_NEXT> works just like B<DB_FIRST>. 1395 1396If the cursor is already positioned at the last key/value pair, B<c_get> 1397will return B<DB_NOTFOUND>. 1398 1399=item B<DB_NEXT_DUP> 1400 1401This flag is only valid when duplicate keys have been enabled in 1402a database. 1403If the cursor is already pointing to a key/value pair and the key of 1404the next key/value pair is identical, the cursor will be incremented to 1405point to it and their contents returned. 1406 1407=item B<DB_PREV> 1408 1409If the cursor is already pointing to a key/value pair, it will be 1410decremented to point to the previous key/value pair and return its 1411contents. 1412 1413If the cursor isn't initialised, B<DB_PREV> works just like B<DB_LAST>. 1414 1415If the cursor is already positioned at the first key/value pair, B<c_get> 1416will return B<DB_NOTFOUND>. 1417 1418=item B<DB_CURRENT> 1419 1420If the cursor has been set to point to a key/value pair, return their 1421contents. 1422If the key/value pair referenced by the cursor has been deleted, B<c_get> 1423will return B<DB_KEYEMPTY>. 1424 1425=item B<DB_SET> 1426 1427Set the cursor to point to the key/value pair referenced by B<$key> 1428and return the value in B<$value>. 1429 1430=item B<DB_SET_RANGE> 1431 1432This flag is a variation on the B<DB_SET> flag. As well as returning 1433the value, it also returns the key, via B<$key>. 1434When used with a B<BerkeleyDB::Btree> database the key matched by B<c_get> 1435will be the shortest key (in length) which is greater than or equal to 1436the key supplied, via B<$key>. This allows partial key searches. 1437See ??? for an example of how to use this flag. 1438 1439=item B<DB_GET_BOTH> 1440 1441Another variation on B<DB_SET>. This one returns both the key and 1442the value. 1443 1444=item B<DB_SET_RECNO> 1445 1446TODO. 1447 1448=item B<DB_GET_RECNO> 1449 1450TODO. 1451 1452=back 1453 1454In addition, the following value may be set by bitwise OR'ing it into 1455the B<$flags> parameter: 1456 1457=over 5 1458 1459=item B<DB_RMW> 1460 1461TODO. 1462 1463=back 1464 1465=head2 $status = $cursor->c_put($key, $value, $flags) 1466 1467Stores the key/value pair in the database. The position that the data is 1468stored in the database is controlled by the C<$flags> parameter, which 1469must take B<one> of the following values: 1470 1471=over 5 1472 1473=item B<DB_AFTER> 1474 1475When used with a Btree or Hash database, a duplicate of the key referenced 1476by the current cursor position will be created and the contents of 1477B<$value> will be associated with it - B<$key> is ignored. 1478The new key/value pair will be stored immediately after the current 1479cursor position. 1480Obviously the database has to have been opened with B<DB_DUP>. 1481 1482When used with a Recno ... TODO 1483 1484 1485=item B<DB_BEFORE> 1486 1487When used with a Btree or Hash database, a duplicate of the key referenced 1488by the current cursor position will be created and the contents of 1489B<$value> will be associated with it - B<$key> is ignored. 1490The new key/value pair will be stored immediately before the current 1491cursor position. 1492Obviously the database has to have been opened with B<DB_DUP>. 1493 1494When used with a Recno ... TODO 1495 1496=item B<DB_CURRENT> 1497 1498If the cursor has been initialised, replace the value of the key/value 1499pair stored in the database with the contents of B<$value>. 1500 1501=item B<DB_KEYFIRST> 1502 1503Only valid with a Btree or Hash database. This flag is only really 1504used when duplicates are enabled in the database and sorted duplicates 1505haven't been specified. 1506In this case the key/value pair will be inserted as the first entry in 1507the duplicates for the particular key. 1508 1509=item B<DB_KEYLAST> 1510 1511Only valid with a Btree or Hash database. This flag is only really 1512used when duplicates are enabled in the database and sorted duplicates 1513haven't been specified. 1514In this case the key/value pair will be inserted as the last entry in 1515the duplicates for the particular key. 1516 1517=back 1518 1519=head2 $status = $cursor->c_del([$flags]) 1520 1521This method deletes the key/value pair associated with the current cursor 1522position. The cursor position will not be changed by this operation, so 1523any subsequent cursor operation must first initialise the cursor to 1524point to a valid key/value pair. 1525 1526If the key/value pair associated with the cursor have already been 1527deleted, B<c_del> will return B<DB_KEYEMPTY>. 1528 1529The B<$flags> parameter is not used at present. 1530 1531=head2 $status = $cursor->c_count($cnt [, $flags]) 1532 1533Stores the number of duplicates at the current cursor position in B<$cnt>. 1534 1535The B<$flags> parameter is not used at present. This method needs 1536Berkeley DB 3.1 or better. 1537 1538=head2 $status = $cursor->status() 1539 1540Returns the status of the last cursor method as a dual type. 1541 1542=head2 $status = $cursor->c_pget() ; 1543 1544TODO 1545 1546=head2 $status = $cursor->c_close() 1547 1548Closes the cursor B<$cursor>. 1549 1550=head2 Cursor Examples 1551 1552TODO 1553 1554Iterating from first to last, then in reverse. 1555 1556examples of each of the flags. 1557 1558=head1 JOIN 1559 1560Join support for BerkeleyDB is in progress. Watch this space. 1561 1562TODO 1563 1564=head1 TRANSACTIONS 1565 1566TODO. 1567 1568=head1 CDS Mode 1569 1570The Berkeley Db Concurrent Data Store is a lightweight locking mechanism 1571that is useful in scenarios where transactions are overkill. See the 1572accompanying document .. for details of using this module in CDS mode. 1573 1574=head1 DBM Filters 1575 1576A DBM Filter is a piece of code that is be used when you I<always> 1577want to make the same transformation to all keys and/or values in a DBM 1578database. All of the database classes (BerkeleyDB::Hash, 1579BerkeleyDB::Btree and BerkeleyDB::Recno) support DBM Filters. 1580 1581There are four methods associated with DBM Filters. All work 1582identically, and each is used to install (or uninstall) a single DBM 1583Filter. Each expects a single parameter, namely a reference to a sub. 1584The only difference between them is the place that the filter is 1585installed. 1586 1587To summarise: 1588 1589=over 5 1590 1591=item B<filter_store_key> 1592 1593If a filter has been installed with this method, it will be invoked 1594every time you write a key to a DBM database. 1595 1596=item B<filter_store_value> 1597 1598If a filter has been installed with this method, it will be invoked 1599every time you write a value to a DBM database. 1600 1601 1602=item B<filter_fetch_key> 1603 1604If a filter has been installed with this method, it will be invoked 1605every time you read a key from a DBM database. 1606 1607=item B<filter_fetch_value> 1608 1609If a filter has been installed with this method, it will be invoked 1610every time you read a value from a DBM database. 1611 1612=back 1613 1614You can use any combination of the methods, from none, to all four. 1615 1616All filter methods return the existing filter, if present, or C<undef> 1617in not. 1618 1619To delete a filter pass C<undef> to it. 1620 1621=head2 The Filter 1622 1623When each filter is called by Perl, a local copy of C<$_> will contain 1624the key or value to be filtered. Filtering is achieved by modifying 1625the contents of C<$_>. The return code from the filter is ignored. 1626 1627=head2 An Example -- the NULL termination problem. 1628 1629Consider the following scenario. You have a DBM database that you need 1630to share with a third-party C application. The C application assumes 1631that I<all> keys and values are NULL terminated. Unfortunately when 1632Perl writes to DBM databases it doesn't use NULL termination, so your 1633Perl application will have to manage NULL termination itself. When you 1634write to the database you will have to use something like this: 1635 1636 $hash{"$key\0"} = "$value\0" ; 1637 1638Similarly the NULL needs to be taken into account when you are considering 1639the length of existing keys/values. 1640 1641It would be much better if you could ignore the NULL terminations issue 1642in the main application code and have a mechanism that automatically 1643added the terminating NULL to all keys and values whenever you write to 1644the database and have them removed when you read from the database. As I'm 1645sure you have already guessed, this is a problem that DBM Filters can 1646fix very easily. 1647 1648## nullFilter 1649 1650Hopefully the contents of each of the filters should be 1651self-explanatory. Both "fetch" filters remove the terminating NULL, 1652and both "store" filters add a terminating NULL. 1653 1654 1655=head2 Another Example -- Key is a C int. 1656 1657Here is another real-life example. By default, whenever Perl writes to 1658a DBM database it always writes the key and value as strings. So when 1659you use this: 1660 1661 $hash{12345} = "something" ; 1662 1663the key 12345 will get stored in the DBM database as the 5 byte string 1664"12345". If you actually want the key to be stored in the DBM database 1665as a C int, you will have to use C<pack> when writing, and C<unpack> 1666when reading. 1667 1668Here is a DBM Filter that does it: 1669 1670## intFilter 1671 1672This time only two filters have been used -- we only need to manipulate 1673the contents of the key, so it wasn't necessary to install any value 1674filters. 1675 1676=head1 Using BerkeleyDB with MLDBM 1677 1678Both BerkeleyDB::Hash and BerkeleyDB::Btree can be used with the MLDBM 1679module. The code fragment below shows how to open associate MLDBM with 1680BerkeleyDB::Btree. To use BerkeleyDB::Hash just replace 1681BerkeleyDB::Btree with BerkeleyDB::Hash. 1682 1683 use strict ; 1684 use BerkeleyDB ; 1685 use MLDBM qw(BerkeleyDB::Btree) ; 1686 use Data::Dumper; 1687 1688 my $filename = 'testmldbm' ; 1689 my %o ; 1690 1691 unlink $filename ; 1692 tie %o, 'MLDBM', -Filename => $filename, 1693 -Flags => DB_CREATE 1694 or die "Cannot open database '$filename: $!\n"; 1695 1696See the MLDBM documentation for information on how to use the module 1697and for details of its limitations. 1698 1699=head1 EXAMPLES 1700 1701TODO. 1702 1703=head1 HINTS & TIPS 1704 1705=head2 Sharing Databases With C Applications 1706 1707There is no technical reason why a Berkeley DB database cannot be 1708shared by both a Perl and a C application. 1709 1710The vast majority of problems that are reported in this area boil down 1711to the fact that C strings are NULL terminated, whilst Perl strings 1712are not. See L<An Example -- the NULL termination problem.> in the DBM 1713FILTERS section for a generic way to work around this problem. 1714 1715 1716=head2 The untie Gotcha 1717 1718TODO 1719 1720=head1 COMMON QUESTIONS 1721 1722This section attempts to answer some of the more common questions that 1723I get asked. 1724 1725 1726=head2 Relationship with DB_File 1727 1728Before Berkeley DB 2.x was written there was only one Perl module that 1729interfaced to Berkeley DB. That module is called B<DB_File>. Although 1730B<DB_File> can be build with Berkeley DB 1.x, 2.x, 3.x or 4.x, it only 1731provides an interface to the functionality available in Berkeley DB 17321.x. That means that it doesn't support transactions, locking or any of 1733the other new features available in DB 2.x or better. 1734 1735=head2 How do I store Perl data structures with BerkeleyDB? 1736 1737See L<Using BerkeleyDB with MLDBM>. 1738 1739=head1 HISTORY 1740 1741See the Changes file. 1742 1743=head1 AVAILABILITY 1744 1745The most recent version of B<BerkeleyDB> can always be found 1746on CPAN (see L<perlmod/CPAN> for details), in the directory 1747F<modules/by-module/BerkeleyDB>. 1748 1749The official web site for Berkeley DB is F<http://www.oracle.com/technology/products/berkeley-db/db/index.html>. 1750 1751=head1 COPYRIGHT 1752 1753Copyright (c) 1997-2004 Paul Marquess. All rights reserved. This program 1754is free software; you can redistribute it and/or modify it under the 1755same terms as Perl itself. 1756 1757Although B<BerkeleyDB> is covered by the Perl license, the library it 1758makes use of, namely Berkeley DB, is not. Berkeley DB has its own 1759copyright and its own license. Please take the time to read it. 1760 1761Here are few words taken from the Berkeley DB FAQ (at 1762F<http://www.oracle.com/technology/products/berkeley-db/db/index.html>) regarding the license: 1763 1764 Do I have to license DB to use it in Perl scripts? 1765 1766 No. The Berkeley DB license requires that software that uses 1767 Berkeley DB be freely redistributable. In the case of Perl, that 1768 software is Perl, and not your scripts. Any Perl scripts that you 1769 write are your property, including scripts that make use of Berkeley 1770 DB. Neither the Perl license nor the Berkeley DB license 1771 place any restriction on what you may do with them. 1772 1773If you are in any doubt about the license situation, contact either the 1774Berkeley DB authors or the author of BerkeleyDB. 1775See L<"AUTHOR"> for details. 1776 1777 1778=head1 AUTHOR 1779 1780Paul Marquess E<lt>pmqs@cpan.orgE<gt>. 1781 1782 1783=head1 SEE ALSO 1784 1785perl(1), DB_File, Berkeley DB. 1786 1787=cut 1788