This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
More fixups for thrperl integration.
[perl5.git] / ext / DB_File / DB_File.pm
1 # DB_File.pm -- Perl 5 interface to Berkeley DB 
2 #
3 # written by Paul Marquess (pmarquess@bfsec.bt.co.uk)
4 # last modified 31st May 1997
5 # version 1.15
6 #
7 #     Copyright (c) 1995, 1996, 1997 Paul Marquess. All rights reserved.
8 #     This program is free software; you can redistribute it and/or
9 #     modify it under the same terms as Perl itself.
10
11
12 package DB_File::HASHINFO ;
13
14 require 5.003 ;
15
16 use strict;
17 use Carp;
18 require Tie::Hash;
19 @DB_File::HASHINFO::ISA = qw(Tie::Hash);
20
21 sub new
22 {
23     my $pkg = shift ;
24     my %x ;
25     tie %x, $pkg ;
26     bless \%x, $pkg ;
27 }
28
29
30 sub TIEHASH
31 {
32     my $pkg = shift ;
33
34     bless { VALID => { map {$_, 1} 
35                        qw( bsize ffactor nelem cachesize hash lorder)
36                      }, 
37             GOT   => {}
38           }, $pkg ;
39 }
40
41
42 sub FETCH 
43 {  
44     my $self  = shift ;
45     my $key   = shift ;
46
47     return $self->{GOT}{$key} if exists $self->{VALID}{$key}  ;
48
49     my $pkg = ref $self ;
50     croak "${pkg}::FETCH - Unknown element '$key'" ;
51 }
52
53
54 sub STORE 
55 {
56     my $self  = shift ;
57     my $key   = shift ;
58     my $value = shift ;
59
60     if ( exists $self->{VALID}{$key} )
61     {
62         $self->{GOT}{$key} = $value ;
63         return ;
64     }
65     
66     my $pkg = ref $self ;
67     croak "${pkg}::STORE - Unknown element '$key'" ;
68 }
69
70 sub DELETE 
71 {
72     my $self = shift ;
73     my $key  = shift ;
74
75     if ( exists $self->{VALID}{$key} )
76     {
77         delete $self->{GOT}{$key} ;
78         return ;
79     }
80     
81     my $pkg = ref $self ;
82     croak "DB_File::HASHINFO::DELETE - Unknown element '$key'" ;
83 }
84
85 sub EXISTS
86 {
87     my $self = shift ;
88     my $key  = shift ;
89
90     exists $self->{VALID}{$key} ;
91 }
92
93 sub NotHere
94 {
95     my $self = shift ;
96     my $method = shift ;
97
98     croak ref($self) . " does not define the method ${method}" ;
99 }
100
101 sub DESTROY  { undef %{$_[0]} }
102 sub FIRSTKEY { my $self = shift ; $self->NotHere("FIRSTKEY") }
103 sub NEXTKEY  { my $self = shift ; $self->NotHere("NEXTKEY") }
104 sub CLEAR    { my $self = shift ; $self->NotHere("CLEAR") }
105
106 package DB_File::RECNOINFO ;
107
108 use strict ;
109
110 @DB_File::RECNOINFO::ISA = qw(DB_File::HASHINFO) ;
111
112 sub TIEHASH
113 {
114     my $pkg = shift ;
115
116     bless { VALID => { map {$_, 1} 
117                        qw( bval cachesize psize flags lorder reclen bfname )
118                      },
119             GOT   => {},
120           }, $pkg ;
121 }
122
123 package DB_File::BTREEINFO ;
124
125 use strict ;
126
127 @DB_File::BTREEINFO::ISA = qw(DB_File::HASHINFO) ;
128
129 sub TIEHASH
130 {
131     my $pkg = shift ;
132
133     bless { VALID => { map {$_, 1} 
134                        qw( flags cachesize maxkeypage minkeypage psize 
135                            compare prefix lorder )
136                      },
137             GOT   => {},
138           }, $pkg ;
139 }
140
141
142 package DB_File ;
143
144 use strict;
145 use vars qw($VERSION @ISA @EXPORT $AUTOLOAD $DB_BTREE $DB_HASH $DB_RECNO) ;
146 use Carp;
147
148
149 $VERSION = "1.15" ;
150
151 #typedef enum { DB_BTREE, DB_HASH, DB_RECNO } DBTYPE;
152 $DB_BTREE = new DB_File::BTREEINFO ;
153 $DB_HASH  = new DB_File::HASHINFO ;
154 $DB_RECNO = new DB_File::RECNOINFO ;
155
156 require Tie::Hash;
157 require Exporter;
158 use AutoLoader;
159 require DynaLoader;
160 @ISA = qw(Tie::Hash Exporter DynaLoader);
161 @EXPORT = qw(
162         $DB_BTREE $DB_HASH $DB_RECNO 
163
164         BTREEMAGIC
165         BTREEVERSION
166         DB_LOCK
167         DB_SHMEM
168         DB_TXN
169         HASHMAGIC
170         HASHVERSION
171         MAX_PAGE_NUMBER
172         MAX_PAGE_OFFSET
173         MAX_REC_NUMBER
174         RET_ERROR
175         RET_SPECIAL
176         RET_SUCCESS
177         R_CURSOR
178         R_DUP
179         R_FIRST
180         R_FIXEDLEN
181         R_IAFTER
182         R_IBEFORE
183         R_LAST
184         R_NEXT
185         R_NOKEY
186         R_NOOVERWRITE
187         R_PREV
188         R_RECNOSYNC
189         R_SETCURSOR
190         R_SNAPSHOT
191         __R_UNUSED
192
193 );
194
195 sub AUTOLOAD {
196     my($constname);
197     ($constname = $AUTOLOAD) =~ s/.*:://;
198     my $val = constant($constname, @_ ? $_[0] : 0);
199     if ($! != 0) {
200         if ($! =~ /Invalid/) {
201             $AutoLoader::AUTOLOAD = $AUTOLOAD;
202             goto &AutoLoader::AUTOLOAD;
203         }
204         else {
205             my($pack,$file,$line) = caller;
206             croak "Your vendor has not defined DB macro $constname, used at $file line $line.
207 ";
208         }
209     }
210     eval "sub $AUTOLOAD { $val }";
211     goto &$AUTOLOAD;
212 }
213
214
215 # import borrowed from IO::File
216 #   exports Fcntl constants if available.
217 sub import {
218     my $pkg = shift;
219     my $callpkg = caller;
220     Exporter::export $pkg, $callpkg, @_;
221     eval {
222         require Fcntl;
223         Exporter::export 'Fcntl', $callpkg, '/^O_/';
224     };
225 }
226
227 bootstrap DB_File $VERSION;
228
229 # Preloaded methods go here.  Autoload methods go after __END__, and are
230 # processed by the autosplit program.
231
232 sub tie_hash_or_array
233 {
234     my (@arg) = @_ ;
235     my $tieHASH = ( (caller(1))[3] =~ /TIEHASH/ ) ;
236
237     $arg[4] = tied %{ $arg[4] } 
238         if @arg >= 5 && ref $arg[4] && $arg[4] =~ /=HASH/ && tied %{ $arg[4] } ;
239
240     DoTie_($tieHASH, @arg) ;
241 }
242
243 sub TIEHASH
244 {
245     tie_hash_or_array(@_) ;
246 }
247
248 sub TIEARRAY
249 {
250     tie_hash_or_array(@_) ;
251 }
252
253 sub get_dup
254 {
255     croak "Usage: \$db->get_dup(key [,flag])\n"
256         unless @_ == 2 or @_ == 3 ;
257  
258     my $db        = shift ;
259     my $key       = shift ;
260     my $flag      = shift ;
261     my $value     = 0 ;
262     my $origkey   = $key ;
263     my $wantarray = wantarray ;
264     my %values    = () ;
265     my @values    = () ;
266     my $counter   = 0 ;
267     my $status    = 0 ;
268  
269     # iterate through the database until either EOF ($status == 0)
270     # or a different key is encountered ($key ne $origkey).
271     for ($status = $db->seq($key, $value, R_CURSOR()) ;
272          $status == 0 and $key eq $origkey ;
273          $status = $db->seq($key, $value, R_NEXT()) ) {
274  
275         # save the value or count number of matches
276         if ($wantarray) {
277             if ($flag)
278                 { ++ $values{$value} }
279             else
280                 { push (@values, $value) }
281         }
282         else
283             { ++ $counter }
284      
285     }
286  
287     return ($wantarray ? ($flag ? %values : @values) : $counter) ;
288 }
289
290
291 1;
292 __END__
293
294 =head1 NAME
295
296 DB_File - Perl5 access to Berkeley DB
297
298 =head1 SYNOPSIS
299
300  use DB_File ;
301  
302  [$X =] tie %hash,  'DB_File', [$filename, $flags, $mode, $DB_HASH] ;
303  [$X =] tie %hash,  'DB_File', $filename, $flags, $mode, $DB_BTREE ;
304  [$X =] tie @array, 'DB_File', $filename, $flags, $mode, $DB_RECNO ;
305
306  $status = $X->del($key [, $flags]) ;
307  $status = $X->put($key, $value [, $flags]) ;
308  $status = $X->get($key, $value [, $flags]) ;
309  $status = $X->seq($key, $value, $flags) ;
310  $status = $X->sync([$flags]) ;
311  $status = $X->fd ;
312
313  # BTREE only
314  $count = $X->get_dup($key) ;
315  @list  = $X->get_dup($key) ;
316  %list  = $X->get_dup($key, 1) ;
317
318  # RECNO only
319  $a = $X->length;
320  $a = $X->pop ;
321  $X->push(list);
322  $a = $X->shift;
323  $X->unshift(list);
324
325  untie %hash ;
326  untie @array ;
327
328 =head1 DESCRIPTION
329
330 B<DB_File> is a module which allows Perl programs to make use of the
331 facilities provided by Berkeley DB.  If you intend to use this
332 module you should really have a copy of the Berkeley DB manual pages at
333 hand. The interface defined here mirrors the Berkeley DB interface
334 closely.
335
336 Please note that this module will only work with version 1.x of
337 Berkeley DB. Once Berkeley DB version 2 is released, B<DB_File> will be
338 upgraded to work with it.
339
340 Berkeley DB is a C library which provides a consistent interface to a
341 number of database formats.  B<DB_File> provides an interface to all
342 three of the database types currently supported by Berkeley DB.
343
344 The file types are:
345
346 =over 5
347
348 =item B<DB_HASH>
349
350 This database type allows arbitrary key/value pairs to be stored in data
351 files. This is equivalent to the functionality provided by other
352 hashing packages like DBM, NDBM, ODBM, GDBM, and SDBM. Remember though,
353 the files created using DB_HASH are not compatible with any of the
354 other packages mentioned.
355
356 A default hashing algorithm, which will be adequate for most
357 applications, is built into Berkeley DB. If you do need to use your own
358 hashing algorithm it is possible to write your own in Perl and have
359 B<DB_File> use it instead.
360
361 =item B<DB_BTREE>
362
363 The btree format allows arbitrary key/value pairs to be stored in a
364 sorted, balanced binary tree.
365
366 As with the DB_HASH format, it is possible to provide a user defined
367 Perl routine to perform the comparison of keys. By default, though, the
368 keys are stored in lexical order.
369
370 =item B<DB_RECNO>
371
372 DB_RECNO allows both fixed-length and variable-length flat text files
373 to be manipulated using the same key/value pair interface as in DB_HASH
374 and DB_BTREE.  In this case the key will consist of a record (line)
375 number.
376
377 =back
378
379 =head2 Interface to Berkeley DB
380
381 B<DB_File> allows access to Berkeley DB files using the tie() mechanism
382 in Perl 5 (for full details, see L<perlfunc/tie()>). This facility
383 allows B<DB_File> to access Berkeley DB files using either an
384 associative array (for DB_HASH & DB_BTREE file types) or an ordinary
385 array (for the DB_RECNO file type).
386
387 In addition to the tie() interface, it is also possible to access most
388 of the functions provided in the Berkeley DB API directly.
389 See L<THE API INTERFACE>.
390
391 =head2 Opening a Berkeley DB Database File
392
393 Berkeley DB uses the function dbopen() to open or create a database.
394 Here is the C prototype for dbopen():
395
396       DB*
397       dbopen (const char * file, int flags, int mode, 
398               DBTYPE type, const void * openinfo)
399
400 The parameter C<type> is an enumeration which specifies which of the 3
401 interface methods (DB_HASH, DB_BTREE or DB_RECNO) is to be used.
402 Depending on which of these is actually chosen, the final parameter,
403 I<openinfo> points to a data structure which allows tailoring of the
404 specific interface method.
405
406 This interface is handled slightly differently in B<DB_File>. Here is
407 an equivalent call using B<DB_File>:
408
409         tie %array, 'DB_File', $filename, $flags, $mode, $DB_HASH ;
410
411 The C<filename>, C<flags> and C<mode> parameters are the direct
412 equivalent of their dbopen() counterparts. The final parameter $DB_HASH
413 performs the function of both the C<type> and C<openinfo> parameters in
414 dbopen().
415
416 In the example above $DB_HASH is actually a pre-defined reference to a
417 hash object. B<DB_File> has three of these pre-defined references.
418 Apart from $DB_HASH, there is also $DB_BTREE and $DB_RECNO.
419
420 The keys allowed in each of these pre-defined references is limited to
421 the names used in the equivalent C structure. So, for example, the
422 $DB_HASH reference will only allow keys called C<bsize>, C<cachesize>,
423 C<ffactor>, C<hash>, C<lorder> and C<nelem>. 
424
425 To change one of these elements, just assign to it like this:
426
427         $DB_HASH->{'cachesize'} = 10000 ;
428
429 The three predefined variables $DB_HASH, $DB_BTREE and $DB_RECNO are
430 usually adequate for most applications.  If you do need to create extra
431 instances of these objects, constructors are available for each file
432 type.
433
434 Here are examples of the constructors and the valid options available
435 for DB_HASH, DB_BTREE and DB_RECNO respectively.
436
437      $a = new DB_File::HASHINFO ;
438      $a->{'bsize'} ;
439      $a->{'cachesize'} ;
440      $a->{'ffactor'};
441      $a->{'hash'} ;
442      $a->{'lorder'} ;
443      $a->{'nelem'} ;
444
445      $b = new DB_File::BTREEINFO ;
446      $b->{'flags'} ;
447      $b->{'cachesize'} ;
448      $b->{'maxkeypage'} ;
449      $b->{'minkeypage'} ;
450      $b->{'psize'} ;
451      $b->{'compare'} ;
452      $b->{'prefix'} ;
453      $b->{'lorder'} ;
454
455      $c = new DB_File::RECNOINFO ;
456      $c->{'bval'} ;
457      $c->{'cachesize'} ;
458      $c->{'psize'} ;
459      $c->{'flags'} ;
460      $c->{'lorder'} ;
461      $c->{'reclen'} ;
462      $c->{'bfname'} ;
463
464 The values stored in the hashes above are mostly the direct equivalent
465 of their C counterpart. Like their C counterparts, all are set to a
466 default values - that means you don't have to set I<all> of the
467 values when you only want to change one. Here is an example:
468
469      $a = new DB_File::HASHINFO ;
470      $a->{'cachesize'} =  12345 ;
471      tie %y, 'DB_File', "filename", $flags, 0777, $a ;
472
473 A few of the options need extra discussion here. When used, the C
474 equivalent of the keys C<hash>, C<compare> and C<prefix> store pointers
475 to C functions. In B<DB_File> these keys are used to store references
476 to Perl subs. Below are templates for each of the subs:
477
478     sub hash
479     {
480         my ($data) = @_ ;
481         ...
482         # return the hash value for $data
483         return $hash ;
484     }
485
486     sub compare
487     {
488         my ($key, $key2) = @_ ;
489         ...
490         # return  0 if $key1 eq $key2
491         #        -1 if $key1 lt $key2
492         #         1 if $key1 gt $key2
493         return (-1 , 0 or 1) ;
494     }
495
496     sub prefix
497     {
498         my ($key, $key2) = @_ ;
499         ...
500         # return number of bytes of $key2 which are 
501         # necessary to determine that it is greater than $key1
502         return $bytes ;
503     }
504
505 See L<Changing the BTREE sort order> for an example of using the
506 C<compare> template.
507
508 If you are using the DB_RECNO interface and you intend making use of
509 C<bval>, you should check out L<The 'bval' Option>.
510
511 =head2 Default Parameters
512
513 It is possible to omit some or all of the final 4 parameters in the
514 call to C<tie> and let them take default values. As DB_HASH is the most
515 common file format used, the call:
516
517     tie %A, "DB_File", "filename" ;
518
519 is equivalent to:
520
521     tie %A, "DB_File", "filename", O_CREAT|O_RDWR, 0666, $DB_HASH ;
522
523 It is also possible to omit the filename parameter as well, so the
524 call:
525
526     tie %A, "DB_File" ;
527
528 is equivalent to:
529
530     tie %A, "DB_File", undef, O_CREAT|O_RDWR, 0666, $DB_HASH ;
531
532 See L<In Memory Databases> for a discussion on the use of C<undef>
533 in place of a filename.
534
535 =head2 In Memory Databases
536
537 Berkeley DB allows the creation of in-memory databases by using NULL
538 (that is, a C<(char *)0> in C) in place of the filename.  B<DB_File>
539 uses C<undef> instead of NULL to provide this functionality.
540
541 =head1 DB_HASH
542
543 The DB_HASH file format is probably the most commonly used of the three
544 file formats that B<DB_File> supports. It is also very straightforward
545 to use.
546
547 =head2 A Simple Example
548
549 This example shows how to create a database, add key/value pairs to the
550 database, delete keys/value pairs and finally how to enumerate the
551 contents of the database.
552
553     use strict ;
554     use DB_File ;
555     use vars qw( %h $k $v ) ;
556
557     tie %h, "DB_File", "fruit", O_RDWR|O_CREAT, 0640, $DB_HASH 
558         or die "Cannot open file 'fruit': $!\n";
559
560     # Add a few key/value pairs to the file
561     $h{"apple"} = "red" ;
562     $h{"orange"} = "orange" ;
563     $h{"banana"} = "yellow" ;
564     $h{"tomato"} = "red" ;
565
566     # Check for existence of a key
567     print "Banana Exists\n\n" if $h{"banana"} ;
568
569     # Delete a key/value pair.
570     delete $h{"apple"} ;
571
572     # print the contents of the file
573     while (($k, $v) = each %h)
574       { print "$k -> $v\n" }
575
576     untie %h ;
577
578 here is the output:
579
580     Banana Exists
581  
582     orange -> orange
583     tomato -> red
584     banana -> yellow
585
586 Note that the like ordinary associative arrays, the order of the keys
587 retrieved is in an apparently random order.
588
589 =head1 DB_BTREE
590
591 The DB_BTREE format is useful when you want to store data in a given
592 order. By default the keys will be stored in lexical order, but as you
593 will see from the example shown in the next section, it is very easy to
594 define your own sorting function.
595
596 =head2 Changing the BTREE sort order
597
598 This script shows how to override the default sorting algorithm that
599 BTREE uses. Instead of using the normal lexical ordering, a case
600 insensitive compare function will be used.
601
602     use strict ;
603     use DB_File ;
604
605     my %h ;
606
607     sub Compare
608     {
609         my ($key1, $key2) = @_ ;
610         "\L$key1" cmp "\L$key2" ;
611     }
612
613     # specify the Perl sub that will do the comparison
614     $DB_BTREE->{'compare'} = \&Compare ;
615
616     tie %h, "DB_File", "tree", O_RDWR|O_CREAT, 0640, $DB_BTREE 
617         or die "Cannot open file 'tree': $!\n" ;
618
619     # Add a key/value pair to the file
620     $h{'Wall'} = 'Larry' ;
621     $h{'Smith'} = 'John' ;
622     $h{'mouse'} = 'mickey' ;
623     $h{'duck'}  = 'donald' ;
624
625     # Delete
626     delete $h{"duck"} ;
627
628     # Cycle through the keys printing them in order.
629     # Note it is not necessary to sort the keys as
630     # the btree will have kept them in order automatically.
631     foreach (keys %h)
632       { print "$_\n" }
633
634     untie %h ;
635
636 Here is the output from the code above.
637
638     mouse
639     Smith
640     Wall
641
642 There are a few point to bear in mind if you want to change the
643 ordering in a BTREE database:
644
645 =over 5
646
647 =item 1.
648
649 The new compare function must be specified when you create the database.
650
651 =item 2.
652
653 You cannot change the ordering once the database has been created. Thus
654 you must use the same compare function every time you access the
655 database.
656
657 =back 
658
659 =head2 Handling Duplicate Keys 
660
661 The BTREE file type optionally allows a single key to be associated
662 with an arbitrary number of values. This option is enabled by setting
663 the flags element of C<$DB_BTREE> to R_DUP when creating the database.
664
665 There are some difficulties in using the tied hash interface if you
666 want to manipulate a BTREE database with duplicate keys. Consider this
667 code:
668
669     use strict ;
670     use DB_File ;
671
672     use vars qw($filename %h ) ;
673
674     $filename = "tree" ;
675     unlink $filename ;
676  
677     # Enable duplicate records
678     $DB_BTREE->{'flags'} = R_DUP ;
679  
680     tie %h, "DB_File", $filename, O_RDWR|O_CREAT, 0640, $DB_BTREE 
681         or die "Cannot open $filename: $!\n";
682  
683     # Add some key/value pairs to the file
684     $h{'Wall'} = 'Larry' ;
685     $h{'Wall'} = 'Brick' ; # Note the duplicate key
686     $h{'Wall'} = 'Brick' ; # Note the duplicate key and value
687     $h{'Smith'} = 'John' ;
688     $h{'mouse'} = 'mickey' ;
689
690     # iterate through the associative array
691     # and print each key/value pair.
692     foreach (keys %h)
693       { print "$_  -> $h{$_}\n" }
694
695     untie %h ;
696
697 Here is the output:
698
699     Smith   -> John
700     Wall    -> Larry
701     Wall    -> Larry
702     Wall    -> Larry
703     mouse   -> mickey
704
705 As you can see 3 records have been successfully created with key C<Wall>
706 - the only thing is, when they are retrieved from the database they
707 I<seem> to have the same value, namely C<Larry>. The problem is caused
708 by the way that the associative array interface works. Basically, when
709 the associative array interface is used to fetch the value associated
710 with a given key, it will only ever retrieve the first value.
711
712 Although it may not be immediately obvious from the code above, the
713 associative array interface can be used to write values with duplicate
714 keys, but it cannot be used to read them back from the database.
715
716 The way to get around this problem is to use the Berkeley DB API method
717 called C<seq>.  This method allows sequential access to key/value
718 pairs. See L<THE API INTERFACE> for details of both the C<seq> method
719 and the API in general.
720
721 Here is the script above rewritten using the C<seq> API method.
722
723     use strict ;
724     use DB_File ;
725  
726     use vars qw($filename $x %h $status $key $value) ;
727
728     $filename = "tree" ;
729     unlink $filename ;
730  
731     # Enable duplicate records
732     $DB_BTREE->{'flags'} = R_DUP ;
733  
734     $x = tie %h, "DB_File", $filename, O_RDWR|O_CREAT, 0640, $DB_BTREE 
735         or die "Cannot open $filename: $!\n";
736  
737     # Add some key/value pairs to the file
738     $h{'Wall'} = 'Larry' ;
739     $h{'Wall'} = 'Brick' ; # Note the duplicate key
740     $h{'Wall'} = 'Brick' ; # Note the duplicate key and value
741     $h{'Smith'} = 'John' ;
742     $h{'mouse'} = 'mickey' ;
743  
744     # iterate through the btree using seq
745     # and print each key/value pair.
746     $key = $value = 0 ;
747     for ($status = $x->seq($key, $value, R_FIRST) ;
748          $status == 0 ;
749          $status = $x->seq($key, $value, R_NEXT) )
750       {  print "$key -> $value\n" }
751  
752     undef $x ;
753     untie %h ;
754
755 that prints:
756
757     Smith   -> John
758     Wall    -> Brick
759     Wall    -> Brick
760     Wall    -> Larry
761     mouse   -> mickey
762
763 This time we have got all the key/value pairs, including the multiple
764 values associated with the key C<Wall>.
765
766 =head2 The get_dup() Method
767
768 B<DB_File> comes with a utility method, called C<get_dup>, to assist in
769 reading duplicate values from BTREE databases. The method can take the
770 following forms:
771
772     $count = $x->get_dup($key) ;
773     @list  = $x->get_dup($key) ;
774     %list  = $x->get_dup($key, 1) ;
775
776 In a scalar context the method returns the number of values associated
777 with the key, C<$key>.
778
779 In list context, it returns all the values which match C<$key>. Note
780 that the values will be returned in an apparently random order.
781
782 In list context, if the second parameter is present and evaluates
783 TRUE, the method returns an associative array. The keys of the
784 associative array correspond to the values that matched in the BTREE
785 and the values of the array are a count of the number of times that
786 particular value occurred in the BTREE.
787
788 So assuming the database created above, we can use C<get_dup> like
789 this:
790
791     my $cnt  = $x->get_dup("Wall") ;
792     print "Wall occurred $cnt times\n" ;
793
794     my %hash = $x->get_dup("Wall", 1) ;
795     print "Larry is there\n" if $hash{'Larry'} ;
796     print "There are $hash{'Brick'} Brick Walls\n" ;
797
798     my @list = $x->get_dup("Wall") ;
799     print "Wall =>      [@list]\n" ;
800
801     @list = $x->get_dup("Smith") ;
802     print "Smith =>     [@list]\n" ;
803  
804     @list = $x->get_dup("Dog") ;
805     print "Dog =>       [@list]\n" ;
806
807
808 and it will print:
809
810     Wall occurred 3 times
811     Larry is there
812     There are 2 Brick Walls
813     Wall =>     [Brick Brick Larry]
814     Smith =>    [John]
815     Dog =>      []
816
817 =head2 Matching Partial Keys 
818
819 The BTREE interface has a feature which allows partial keys to be
820 matched. This functionality is I<only> available when the C<seq> method
821 is used along with the R_CURSOR flag.
822
823     $x->seq($key, $value, R_CURSOR) ;
824
825 Here is the relevant quote from the dbopen man page where it defines
826 the use of the R_CURSOR flag with seq:
827
828     Note, for the DB_BTREE access method, the returned key is not
829     necessarily an exact match for the specified key. The returned key
830     is the smallest key greater than or equal to the specified key,
831     permitting partial key matches and range searches.
832
833 In the example script below, the C<match> sub uses this feature to find
834 and print the first matching key/value pair given a partial key.
835
836     use strict ;
837     use DB_File ;
838     use Fcntl ;
839
840     use vars qw($filename $x %h $st $key $value) ;
841
842     sub match
843     {
844         my $key = shift ;
845         my $value = 0;
846         my $orig_key = $key ;
847         $x->seq($key, $value, R_CURSOR) ;
848         print "$orig_key\t-> $key\t-> $value\n" ;
849     }
850
851     $filename = "tree" ;
852     unlink $filename ;
853
854     $x = tie %h, "DB_File", $filename, O_RDWR|O_CREAT, 0640, $DB_BTREE
855         or die "Cannot open $filename: $!\n";
856  
857     # Add some key/value pairs to the file
858     $h{'mouse'} = 'mickey' ;
859     $h{'Wall'} = 'Larry' ;
860     $h{'Walls'} = 'Brick' ; 
861     $h{'Smith'} = 'John' ;
862  
863
864     $key = $value = 0 ;
865     print "IN ORDER\n" ;
866     for ($st = $x->seq($key, $value, R_FIRST) ;
867          $st == 0 ;
868          $st = $x->seq($key, $value, R_NEXT) )
869         
870       {  print "$key -> $value\n" }
871  
872     print "\nPARTIAL MATCH\n" ;
873
874     match "Wa" ;
875     match "A" ;
876     match "a" ;
877
878     undef $x ;
879     untie %h ;
880
881 Here is the output:
882
883     IN ORDER
884     Smith -> John
885     Wall  -> Larry
886     Walls -> Brick
887     mouse -> mickey
888
889     PARTIAL MATCH
890     Wa -> Wall  -> Larry
891     A  -> Smith -> John
892     a  -> mouse -> mickey
893
894 =head1 DB_RECNO
895
896 DB_RECNO provides an interface to flat text files. Both variable and
897 fixed length records are supported.
898
899 In order to make RECNO more compatible with Perl the array offset for
900 all RECNO arrays begins at 0 rather than 1 as in Berkeley DB.
901
902 As with normal Perl arrays, a RECNO array can be accessed using
903 negative indexes. The index -1 refers to the last element of the array,
904 -2 the second last, and so on. Attempting to access an element before
905 the start of the array will raise a fatal run-time error.
906
907 =head2 The 'bval' Option
908
909 The operation of the bval option warrants some discussion. Here is the
910 definition of bval from the Berkeley DB 1.85 recno manual page:
911
912     The delimiting byte to be used to mark  the  end  of  a
913     record for variable-length records, and the pad charac-
914     ter for fixed-length records.  If no  value  is  speci-
915     fied,  newlines  (``\n'')  are  used to mark the end of
916     variable-length records and  fixed-length  records  are
917     padded with spaces.
918
919 The second sentence is wrong. In actual fact bval will only default to
920 C<"\n"> when the openinfo parameter in dbopen is NULL. If a non-NULL
921 openinfo parameter is used at all, the value that happens to be in bval
922 will be used. That means you always have to specify bval when making
923 use of any of the options in the openinfo parameter. This documentation
924 error will be fixed in the next release of Berkeley DB.
925
926 That clarifies the situation with regards Berkeley DB itself. What
927 about B<DB_File>? Well, the behavior defined in the quote above is
928 quite useful, so B<DB_File> conforms it.
929
930 That means that you can specify other options (e.g. cachesize) and
931 still have bval default to C<"\n"> for variable length records, and
932 space for fixed length records.
933
934 =head2 A Simple Example
935
936 Here is a simple example that uses RECNO.
937
938     use strict ;
939     use DB_File ;
940
941     my @h ;
942     tie @h, "DB_File", "text", O_RDWR|O_CREAT, 0640, $DB_RECNO 
943         or die "Cannot open file 'text': $!\n" ;
944
945     # Add a few key/value pairs to the file
946     $h[0] = "orange" ;
947     $h[1] = "blue" ;
948     $h[2] = "yellow" ;
949
950     # Check for existence of a key
951     print "Element 1 Exists with value $h[1]\n" if $h[1] ;
952
953     # use a negative index
954     print "The last element is $h[-1]\n" ;
955     print "The 2nd last element is $h[-2]\n" ;
956
957     untie @h ;
958
959 Here is the output from the script:
960
961
962     Element 1 Exists with value blue
963     The last element is yellow
964     The 2nd last element is blue
965
966 =head2 Extra Methods
967
968 As you can see from the example above, the tied array interface is
969 quite limited. To make the interface more useful, a number of methods
970 are supplied with B<DB_File> to simulate the standard array operations
971 that are not currently implemented in Perl's tied array interface. All
972 these methods are accessed via the object returned from the tie call.
973
974 Here are the methods:
975
976 =over 5
977
978 =item B<$X-E<gt>push(list) ;>
979
980 Pushes the elements of C<list> to the end of the array.
981
982 =item B<$value = $X-E<gt>pop ;>
983
984 Removes and returns the last element of the array.
985
986 =item B<$X-E<gt>shift>
987
988 Removes and returns the first element of the array.
989
990 =item B<$X-E<gt>unshift(list) ;>
991
992 Pushes the elements of C<list> to the start of the array.
993
994 =item B<$X-E<gt>length>
995
996 Returns the number of elements in the array.
997
998 =back
999
1000 =head2 Another Example
1001
1002 Here is a more complete example that makes use of some of the methods
1003 described above. It also makes use of the API interface directly (see 
1004 L<THE API INTERFACE>).
1005
1006     use strict ;
1007     use vars qw(@h $H $file $i) ;
1008     use DB_File ;
1009     use Fcntl ;
1010     
1011     $file = "text" ;
1012
1013     unlink $file ;
1014
1015     $H = tie @h, "DB_File", $file, O_RDWR|O_CREAT, 0640, $DB_RECNO 
1016         or die "Cannot open file $file: $!\n" ;
1017     
1018     # first create a text file to play with
1019     $h[0] = "zero" ;
1020     $h[1] = "one" ;
1021     $h[2] = "two" ;
1022     $h[3] = "three" ;
1023     $h[4] = "four" ;
1024
1025     
1026     # Print the records in order.
1027     #
1028     # The length method is needed here because evaluating a tied
1029     # array in a scalar context does not return the number of
1030     # elements in the array.  
1031
1032     print "\nORIGINAL\n" ;
1033     foreach $i (0 .. $H->length - 1) {
1034         print "$i: $h[$i]\n" ;
1035     }
1036
1037     # use the push & pop methods
1038     $a = $H->pop ;
1039     $H->push("last") ;
1040     print "\nThe last record was [$a]\n" ;
1041
1042     # and the shift & unshift methods
1043     $a = $H->shift ;
1044     $H->unshift("first") ;
1045     print "The first record was [$a]\n" ;
1046
1047     # Use the API to add a new record after record 2.
1048     $i = 2 ;
1049     $H->put($i, "Newbie", R_IAFTER) ;
1050
1051     # and a new record before record 1.
1052     $i = 1 ;
1053     $H->put($i, "New One", R_IBEFORE) ;
1054
1055     # delete record 3
1056     $H->del(3) ;
1057
1058     # now print the records in reverse order
1059     print "\nREVERSE\n" ;
1060     for ($i = $H->length - 1 ; $i >= 0 ; -- $i)
1061       { print "$i: $h[$i]\n" }
1062
1063     # same again, but use the API functions instead
1064     print "\nREVERSE again\n" ;
1065     my ($s, $k, $v)  = (0, 0, 0) ;
1066     for ($s = $H->seq($k, $v, R_LAST) ; 
1067              $s == 0 ; 
1068              $s = $H->seq($k, $v, R_PREV))
1069       { print "$k: $v\n" }
1070
1071     undef $H ;
1072     untie @h ;
1073
1074 and this is what it outputs:
1075
1076     ORIGINAL
1077     0: zero
1078     1: one
1079     2: two
1080     3: three
1081     4: four
1082
1083     The last record was [four]
1084     The first record was [zero]
1085
1086     REVERSE
1087     5: last
1088     4: three
1089     3: Newbie
1090     2: one
1091     1: New One
1092     0: first
1093
1094     REVERSE again
1095     5: last
1096     4: three
1097     3: Newbie
1098     2: one
1099     1: New One
1100     0: first
1101
1102 Notes:
1103
1104 =over 5
1105
1106 =item 1.
1107
1108 Rather than iterating through the array, C<@h> like this:
1109
1110     foreach $i (@h)
1111
1112 it is necessary to use either this:
1113
1114     foreach $i (0 .. $H->length - 1) 
1115
1116 or this:
1117
1118     for ($a = $H->get($k, $v, R_FIRST) ;
1119          $a == 0 ;
1120          $a = $H->get($k, $v, R_NEXT) )
1121
1122 =item 2.
1123
1124 Notice that both times the C<put> method was used the record index was
1125 specified using a variable, C<$i>, rather than the literal value
1126 itself. This is because C<put> will return the record number of the
1127 inserted line via that parameter.
1128
1129 =back
1130
1131 =head1 THE API INTERFACE
1132
1133 As well as accessing Berkeley DB using a tied hash or array, it is also
1134 possible to make direct use of most of the API functions defined in the
1135 Berkeley DB documentation.
1136
1137 To do this you need to store a copy of the object returned from the tie.
1138
1139         $db = tie %hash, "DB_File", "filename" ;
1140
1141 Once you have done that, you can access the Berkeley DB API functions
1142 as B<DB_File> methods directly like this:
1143
1144         $db->put($key, $value, R_NOOVERWRITE) ;
1145
1146 B<Important:> If you have saved a copy of the object returned from
1147 C<tie>, the underlying database file will I<not> be closed until both
1148 the tied variable is untied and all copies of the saved object are
1149 destroyed. 
1150
1151     use DB_File ;
1152     $db = tie %hash, "DB_File", "filename" 
1153         or die "Cannot tie filename: $!" ;
1154     ...
1155     undef $db ;
1156     untie %hash ;
1157
1158 See L<The untie() Gotcha> for more details.
1159
1160 All the functions defined in L<dbopen> are available except for
1161 close() and dbopen() itself. The B<DB_File> method interface to the
1162 supported functions have been implemented to mirror the way Berkeley DB
1163 works whenever possible. In particular note that:
1164
1165 =over 5
1166
1167 =item *
1168
1169 The methods return a status value. All return 0 on success.
1170 All return -1 to signify an error and set C<$!> to the exact
1171 error code. The return code 1 generally (but not always) means that the
1172 key specified did not exist in the database.
1173
1174 Other return codes are defined. See below and in the Berkeley DB
1175 documentation for details. The Berkeley DB documentation should be used
1176 as the definitive source.
1177
1178 =item *
1179
1180 Whenever a Berkeley DB function returns data via one of its parameters,
1181 the equivalent B<DB_File> method does exactly the same.
1182
1183 =item *
1184
1185 If you are careful, it is possible to mix API calls with the tied
1186 hash/array interface in the same piece of code. Although only a few of
1187 the methods used to implement the tied interface currently make use of
1188 the cursor, you should always assume that the cursor has been changed
1189 any time the tied hash/array interface is used. As an example, this
1190 code will probably not do what you expect:
1191
1192     $X = tie %x, 'DB_File', $filename, O_RDWR|O_CREAT, 0777, $DB_BTREE
1193         or die "Cannot tie $filename: $!" ;
1194
1195     # Get the first key/value pair and set  the cursor
1196     $X->seq($key, $value, R_FIRST) ;
1197
1198     # this line will modify the cursor
1199     $count = scalar keys %x ; 
1200
1201     # Get the second key/value pair.
1202     # oops, it didn't, it got the last key/value pair!
1203     $X->seq($key, $value, R_NEXT) ;
1204
1205 The code above can be rearranged to get around the problem, like this:
1206
1207     $X = tie %x, 'DB_File', $filename, O_RDWR|O_CREAT, 0777, $DB_BTREE
1208         or die "Cannot tie $filename: $!" ;
1209
1210     # this line will modify the cursor
1211     $count = scalar keys %x ; 
1212
1213     # Get the first key/value pair and set  the cursor
1214     $X->seq($key, $value, R_FIRST) ;
1215
1216     # Get the second key/value pair.
1217     # worked this time.
1218     $X->seq($key, $value, R_NEXT) ;
1219
1220 =back
1221
1222 All the constants defined in L<dbopen> for use in the flags parameters
1223 in the methods defined below are also available. Refer to the Berkeley
1224 DB documentation for the precise meaning of the flags values.
1225
1226 Below is a list of the methods available.
1227
1228 =over 5
1229
1230 =item B<$status = $X-E<gt>get($key, $value [, $flags]) ;>
1231
1232 Given a key (C<$key>) this method reads the value associated with it
1233 from the database. The value read from the database is returned in the
1234 C<$value> parameter.
1235
1236 If the key does not exist the method returns 1.
1237
1238 No flags are currently defined for this method.
1239
1240 =item B<$status = $X-E<gt>put($key, $value [, $flags]) ;>
1241
1242 Stores the key/value pair in the database.
1243
1244 If you use either the R_IAFTER or R_IBEFORE flags, the C<$key> parameter
1245 will have the record number of the inserted key/value pair set.
1246
1247 Valid flags are R_CURSOR, R_IAFTER, R_IBEFORE, R_NOOVERWRITE and
1248 R_SETCURSOR.
1249
1250 =item B<$status = $X-E<gt>del($key [, $flags]) ;>
1251
1252 Removes all key/value pairs with key C<$key> from the database.
1253
1254 A return code of 1 means that the requested key was not in the
1255 database.
1256
1257 R_CURSOR is the only valid flag at present.
1258
1259 =item B<$status = $X-E<gt>fd ;>
1260
1261 Returns the file descriptor for the underlying database.
1262
1263 See L<Locking Databases> for an example of how to make use of the
1264 C<fd> method to lock your database.
1265
1266 =item B<$status = $X-E<gt>seq($key, $value, $flags) ;>
1267
1268 This interface allows sequential retrieval from the database. See
1269 L<dbopen> for full details.
1270
1271 Both the C<$key> and C<$value> parameters will be set to the key/value
1272 pair read from the database.
1273
1274 The flags parameter is mandatory. The valid flag values are R_CURSOR,
1275 R_FIRST, R_LAST, R_NEXT and R_PREV.
1276
1277 =item B<$status = $X-E<gt>sync([$flags]) ;>
1278
1279 Flushes any cached buffers to disk.
1280
1281 R_RECNOSYNC is the only valid flag at present.
1282
1283 =back
1284
1285 =head1 HINTS AND TIPS 
1286
1287
1288 =head2 Locking Databases
1289
1290 Concurrent access of a read-write database by several parties requires
1291 them all to use some kind of locking.  Here's an example of Tom's that
1292 uses the I<fd> method to get the file descriptor, and then a careful
1293 open() to give something Perl will flock() for you.  Run this repeatedly
1294 in the background to watch the locks granted in proper order.
1295
1296     use DB_File;
1297
1298     use strict;
1299
1300     sub LOCK_SH { 1 }
1301     sub LOCK_EX { 2 }
1302     sub LOCK_NB { 4 }
1303     sub LOCK_UN { 8 }
1304
1305     my($oldval, $fd, $db, %db, $value, $key);
1306
1307     $key = shift || 'default';
1308     $value = shift || 'magic';
1309
1310     $value .= " $$";
1311
1312     $db = tie(%db, 'DB_File', '/tmp/foo.db', O_CREAT|O_RDWR, 0644) 
1313             || die "dbcreat /tmp/foo.db $!";
1314     $fd = $db->fd;
1315     print "$$: db fd is $fd\n";
1316     open(DB_FH, "+<&=$fd") || die "dup $!";
1317
1318
1319     unless (flock (DB_FH, LOCK_SH | LOCK_NB)) {
1320         print "$$: CONTENTION; can't read during write update!
1321                     Waiting for read lock ($!) ....";
1322         unless (flock (DB_FH, LOCK_SH)) { die "flock: $!" }
1323     } 
1324     print "$$: Read lock granted\n";
1325
1326     $oldval = $db{$key};
1327     print "$$: Old value was $oldval\n";
1328     flock(DB_FH, LOCK_UN);
1329
1330     unless (flock (DB_FH, LOCK_EX | LOCK_NB)) {
1331         print "$$: CONTENTION; must have exclusive lock!
1332                     Waiting for write lock ($!) ....";
1333         unless (flock (DB_FH, LOCK_EX)) { die "flock: $!" }
1334     } 
1335
1336     print "$$: Write lock granted\n";
1337     $db{$key} = $value;
1338     $db->sync;  # to flush
1339     sleep 10;
1340
1341     flock(DB_FH, LOCK_UN);
1342     undef $db;
1343     untie %db;
1344     close(DB_FH);
1345     print "$$: Updated db to $key=$value\n";
1346
1347 =head2 Sharing Databases With C Applications
1348
1349 There is no technical reason why a Berkeley DB database cannot be
1350 shared by both a Perl and a C application.
1351
1352 The vast majority of problems that are reported in this area boil down
1353 to the fact that C strings are NULL terminated, whilst Perl strings are
1354 not. 
1355
1356 Here is a real example. Netscape 2.0 keeps a record of the locations you
1357 visit along with the time you last visited them in a DB_HASH database.
1358 This is usually stored in the file F<~/.netscape/history.db>. The key
1359 field in the database is the location string and the value field is the
1360 time the location was last visited stored as a 4 byte binary value.
1361
1362 If you haven't already guessed, the location string is stored with a
1363 terminating NULL. This means you need to be careful when accessing the
1364 database.
1365
1366 Here is a snippet of code that is loosely based on Tom Christiansen's
1367 I<ggh> script (available from your nearest CPAN archive in
1368 F<authors/id/TOMC/scripts/nshist.gz>).
1369
1370     use strict ;
1371     use DB_File ;
1372     use Fcntl ;
1373
1374     use vars qw( $dotdir $HISTORY %hist_db $href $binary_time $date ) ;
1375     $dotdir = $ENV{HOME} || $ENV{LOGNAME};
1376
1377     $HISTORY = "$dotdir/.netscape/history.db";
1378
1379     tie %hist_db, 'DB_File', $HISTORY
1380         or die "Cannot open $HISTORY: $!\n" ;;
1381
1382     # Dump the complete database
1383     while ( ($href, $binary_time) = each %hist_db ) {
1384
1385         # remove the terminating NULL
1386         $href =~ s/\x00$// ;
1387
1388         # convert the binary time into a user friendly string
1389         $date = localtime unpack("V", $binary_time);
1390         print "$date $href\n" ;
1391     }
1392
1393     # check for the existence of a specific key
1394     # remember to add the NULL
1395     if ( $binary_time = $hist_db{"http://mox.perl.com/\x00"} ) {
1396         $date = localtime unpack("V", $binary_time) ;
1397         print "Last visited mox.perl.com on $date\n" ;
1398     }
1399     else {
1400         print "Never visited mox.perl.com\n"
1401     }
1402
1403     untie %hist_db ;
1404
1405 =head2 The untie() Gotcha
1406
1407 If you make use of the Berkeley DB API, it is I<very> strongly
1408 recommended that you read L<perltie/The untie Gotcha>. 
1409
1410 Even if you don't currently make use of the API interface, it is still
1411 worth reading it.
1412
1413 Here is an example which illustrates the problem from a B<DB_File>
1414 perspective:
1415
1416     use DB_File ;
1417     use Fcntl ;
1418
1419     my %x ;
1420     my $X ;
1421
1422     $X = tie %x, 'DB_File', 'tst.fil' , O_RDWR|O_TRUNC
1423         or die "Cannot tie first time: $!" ;
1424
1425     $x{123} = 456 ;
1426
1427     untie %x ;
1428
1429     tie %x, 'DB_File', 'tst.fil' , O_RDWR|O_CREAT
1430         or die "Cannot tie second time: $!" ;
1431
1432     untie %x ;
1433
1434 When run, the script will produce this error message:
1435
1436     Cannot tie second time: Invalid argument at bad.file line 14.
1437
1438 Although the error message above refers to the second tie() statement
1439 in the script, the source of the problem is really with the untie()
1440 statement that precedes it.
1441
1442 Having read L<perltie> you will probably have already guessed that the
1443 error is caused by the extra copy of the tied object stored in C<$X>.
1444 If you haven't, then the problem boils down to the fact that the
1445 B<DB_File> destructor, DESTROY, will not be called until I<all>
1446 references to the tied object are destroyed. Both the tied variable,
1447 C<%x>, and C<$X> above hold a reference to the object. The call to
1448 untie() will destroy the first, but C<$X> still holds a valid
1449 reference, so the destructor will not get called and the database file
1450 F<tst.fil> will remain open. The fact that Berkeley DB then reports the
1451 attempt to open a database that is alreday open via the catch-all
1452 "Invalid argument" doesn't help.
1453
1454 If you run the script with the C<-w> flag the error message becomes:
1455
1456     untie attempted while 1 inner references still exist at bad.file line 12.
1457     Cannot tie second time: Invalid argument at bad.file line 14.
1458
1459 which pinpoints the real problem. Finally the script can now be
1460 modified to fix the original problem by destroying the API object
1461 before the untie:
1462
1463     ...
1464     $x{123} = 456 ;
1465
1466     undef $X ;
1467     untie %x ;
1468
1469     $X = tie %x, 'DB_File', 'tst.fil' , O_RDWR|O_CREAT
1470     ...
1471
1472
1473 =head1 COMMON QUESTIONS
1474
1475 =head2 Why is there Perl source in my database?
1476
1477 If you look at the contents of a database file created by DB_File,
1478 there can sometimes be part of a Perl script included in it.
1479
1480 This happens because Berkeley DB uses dynamic memory to allocate
1481 buffers which will subsequently be written to the database file. Being
1482 dynamic, the memory could have been used for anything before DB
1483 malloced it. As Berkeley DB doesn't clear the memory once it has been
1484 allocated, the unused portions will contain random junk. In the case
1485 where a Perl script gets written to the database, the random junk will
1486 correspond to an area of dynamic memory that happened to be used during
1487 the compilation of the script.
1488
1489 Unless you don't like the possibility of there being part of your Perl
1490 scripts embedded in a database file, this is nothing to worry about.
1491
1492 =head2 How do I store complex data structures with DB_File?
1493
1494 Although B<DB_File> cannot do this directly, there is a module which
1495 can layer transparently over B<DB_File> to accomplish this feat.
1496
1497 Check out the MLDBM module, available on CPAN in the directory
1498 F<modules/by-module/MLDBM>.
1499
1500 =head2 What does "Invalid Argument" mean?
1501
1502 You will get this error message when one of the parameters in the
1503 C<tie> call is wrong. Unfortunately there are quite a few parameters to
1504 get wrong, so it can be difficult to figure out which one it is.
1505
1506 Here are a couple of possibilities:
1507
1508 =over 5
1509
1510 =item 1.
1511
1512 Attempting to reopen a database without closing it. 
1513
1514 =item 2.
1515
1516 Using the O_WRONLY flag.
1517
1518 =back
1519
1520 =head2 What does "Bareword 'DB_File' not allowed" mean? 
1521
1522 You will encounter this particular error message when you have the
1523 C<strict 'subs'> pragma (or the full strict pragma) in your script.
1524 Consider this script:
1525
1526     use strict ;
1527     use DB_File ;
1528     use vars qw(%x) ;
1529     tie %x, DB_File, "filename" ;
1530
1531 Running it produces the error in question:
1532
1533     Bareword "DB_File" not allowed while "strict subs" in use 
1534
1535 To get around the error, place the word C<DB_File> in either single or
1536 double quotes, like this:
1537
1538     tie %x, "DB_File", "filename" ;
1539
1540 Although it might seem like a real pain, it is really worth the effort
1541 of having a C<use strict> in all your scripts.
1542
1543 =head1 HISTORY
1544
1545 =over
1546
1547 =item 0.1
1548
1549 First Release.
1550
1551 =item 0.2
1552
1553 When B<DB_File> is opening a database file it no longer terminates the
1554 process if I<dbopen> returned an error. This allows file protection
1555 errors to be caught at run time. Thanks to Judith Grass
1556 E<lt>grass@cybercash.comE<gt> for spotting the bug.
1557
1558 =item 0.3
1559
1560 Added prototype support for multiple btree compare callbacks.
1561
1562 =item 1.0
1563
1564 B<DB_File> has been in use for over a year. To reflect that, the
1565 version number has been incremented to 1.0.
1566
1567 Added complete support for multiple concurrent callbacks.
1568
1569 Using the I<push> method on an empty list didn't work properly. This
1570 has been fixed.
1571
1572 =item 1.01
1573
1574 Fixed a core dump problem with SunOS.
1575
1576 The return value from TIEHASH wasn't set to NULL when dbopen returned
1577 an error.
1578
1579 =item 1.02
1580
1581 Merged OS/2 specific code into DB_File.xs
1582
1583 Removed some redundant code in DB_File.xs.
1584
1585 Documentation update.
1586
1587 Allow negative subscripts with RECNO interface.
1588
1589 Changed the default flags from O_RDWR to O_CREAT|O_RDWR.
1590
1591 The example code which showed how to lock a database needed a call to
1592 C<sync> added. Without it the resultant database file was empty.
1593
1594 Added get_dup method.
1595
1596 =item 1.03
1597
1598 Documentation update.
1599
1600 B<DB_File> now imports the constants (O_RDWR, O_CREAT etc.) from Fcntl
1601 automatically.
1602
1603 The standard hash function C<exists> is now supported.
1604
1605 Modified the behavior of get_dup. When it returns an associative
1606 array, the value is the count of the number of matching BTREE values.
1607
1608 =item 1.04
1609
1610 Minor documentation changes.
1611
1612 Fixed a bug in hash_cb. Patches supplied by Dave Hammen,
1613 E<lt>hammen@gothamcity.jsc.nasa.govE<gt>.
1614
1615 Fixed a bug with the constructors for DB_File::HASHINFO,
1616 DB_File::BTREEINFO and DB_File::RECNOINFO. Also tidied up the
1617 constructors to make them C<-w> clean.
1618
1619 Reworked part of the test harness to be more locale friendly.
1620
1621 =item 1.05
1622
1623 Made all scripts in the documentation C<strict> and C<-w> clean.
1624
1625 Added logic to F<DB_File.xs> to allow the module to be built after Perl
1626 is installed.
1627
1628 =item 1.06
1629
1630 Minor namespace cleanup: Localized C<PrintBtree>.
1631
1632 =item 1.07
1633
1634 Fixed bug with RECNO, where bval wasn't defaulting to "\n".
1635
1636 =item 1.08
1637
1638 Documented operation of bval.
1639
1640 =item 1.09
1641
1642 Minor bug fix in DB_File::HASHINFO, DB_File::RECNOINFO and
1643 DB_File::BTREEINFO.
1644
1645 Changed default mode to 0666.
1646
1647 =item 1.10
1648
1649 Fixed fd method so that it still returns -1 for in-memory files when db
1650 1.86 is used.
1651
1652 =item 1.11
1653
1654 Documented the untie gotcha.
1655
1656 =item 1.12
1657
1658 Documented the incompatibility with version 2 of Berkeley DB.
1659
1660 =item 1.13
1661
1662 Minor changes to DB_FIle.xs and DB_File.pm
1663
1664 =item 1.14
1665
1666 Made it illegal to tie an associative array to a RECNO database and an
1667 ordinary array to a HASH or BTREE database.
1668
1669 =item 1.15
1670
1671 Minor changes to DB_File.xs to support multithreaded perl.
1672
1673 =back
1674
1675 =head1 BUGS
1676
1677 Some older versions of Berkeley DB had problems with fixed length
1678 records using the RECNO file format. The newest version at the time of
1679 writing was 1.85 - this seems to have fixed the problems with RECNO.
1680
1681 I am sure there are bugs in the code. If you do find any, or can
1682 suggest any enhancements, I would welcome your comments.
1683
1684 =head1 AVAILABILITY
1685
1686 B<DB_File> comes with the standard Perl source distribution. Look in
1687 the directory F<ext/DB_File>.
1688
1689 This version of B<DB_File> will only work with version 1.x of Berkeley
1690 DB. It is I<not> yet compatible with version 2.
1691
1692 Version 1 of Berkeley DB is available at your nearest CPAN archive (see
1693 L<perlmod/"CPAN"> for a list) in F<src/misc/db.1.85.tar.gz>, or via the
1694 host F<ftp.cs.berkeley.edu> in F</ucb/4bsd/db.tar.gz>.  Alternatively,
1695 check out the Berkeley DB home page at F<http://www.bostic.com/db>. It
1696 is I<not> under the GPL.
1697
1698 If you are running IRIX, then get Berkeley DB from
1699 F<http://reality.sgi.com/ariel>. It has the patches necessary to
1700 compile properly on IRIX 5.3.
1701
1702 As of January 1997, version 1.86 of Berkeley DB is available from the
1703 Berkeley DB home page. Although this release does fix a number of bugs
1704 that were present in 1.85 you should be aware of the following
1705 information (taken from the Berkeley DB home page) before you consider
1706 using it:
1707
1708     DB version 1.86 includes a new implementation of the hash access
1709     method that fixes a variety of hashing problems found in DB version
1710     1.85. We are making it available as an interim solution until DB
1711     2.0 is available.
1712
1713     PLEASE NOTE: the underlying file format for the hash access method
1714     changed between version 1.85 and version 1.86, so you will have to
1715     dump and reload all of your databases to convert from version 1.85
1716     to version 1.86. If you do not absolutely require the fixes from
1717     version 1.86, we strongly urge you to wait until DB 2.0 is released
1718     before upgrading from 1.85.  
1719
1720
1721 =head1 SEE ALSO
1722
1723 L<perl(1)>, L<dbopen(3)>, L<hash(3)>, L<recno(3)>, L<btree(3)> 
1724
1725 =head1 AUTHOR
1726
1727 The DB_File interface was written by Paul Marquess
1728 E<lt>pmarquess@bfsec.bt.co.ukE<gt>.
1729 Questions about the DB system itself may be addressed to
1730 E<lt>db@sleepycat.com<gt>.
1731
1732 =cut