perl/DB_File/DB_File.pm

175         ($splice_end_array =~ /^splice\(\) offset past end of array at /);
341 	warnings::warnif('uninitialized', 'Use of uninitialized value in splice');
354     # 'If OFFSET is negative then it start that far from the end of
360 	    die "Modification of non-creatable array value attempted, "
367 	warnings::warnif('uninitialized', 'Use of uninitialized value in splice');
373 	warnings::warnif('misc', 'splice() offset past end of array')
382     # 'If LENGTH is negative, leave that many elements off the end of
390 	    # length of the array passed in.  But perl's splice()
401     # $num_elems holds the current number of elements in the database.
444     # ...'and replaces them with the elements of LIST, if any.'
558         # save the value or count number of matches
622 B<DB_File> is a module which allows Perl programs to make use of the
624 version of DB, see L<Using DB_File with Berkeley DB version 2 or greater>).
625 It is assumed that you have a copy of the Berkeley DB manual pages at
630 number of database formats.  B<DB_File> provides an interface to all
631 three of the database types currently supported by Berkeley DB.
642 the files created using DB_HASH are not compatible with any of the
656 Perl routine to perform the comparison of keys. By default, though, the
663 and DB_BTREE.  In this case the key will consist of a record (line)
677 If you want to make use of the new features available in Berkeley DB
688 Please read L<"COPYRIGHT"> before using version 2.x or greater of Berkeley
700 of the functions provided in the Berkeley DB API directly.
712 The parameter C<type> is an enumeration which specifies which of the 3
714 Depending on which of these is actually chosen, the final parameter,
715 I<openinfo> points to a data structure which allows tailoring of the
724 equivalent of their dbopen() counterparts. The final parameter $DB_HASH
725 performs the function of both the C<type> and C<openinfo> parameters in
729 hash object. B<DB_File> has three of these pre-defined references.
732 The keys allowed in each of these pre-defined references is limited to
737 To change one of these elements, just assign to it like this:
743 instances of these objects, constructors are available for each file
746 Here are examples of the constructors and the valid options available
777 of their C counterpart. Like their C counterparts, all are set to a
778 default values - that means you don't have to set I<all> of the
785 A few of the options need extra discussion here. When used, the C
786 equivalent of the keys C<hash>, C<compare> and C<prefix> store pointers
788 to Perl subs. Below are templates for each of the subs:
812         # return number of bytes of $key2 which are
817 See L<Changing the BTREE sort order> for an example of using the
820 If you are using the DB_RECNO interface and you intend making use of
825 It is possible to omit some or all of the final 4 parameters in the
844 See L<In Memory Databases> for a discussion on the use of C<undef>
845 in place of a filename.
849 Berkeley DB allows the creation of in-memory databases by using NULL
850 (that is, a C<(char *)0> in C) in place of the filename.  B<DB_File>
851 uses C<undef> instead of NULL to provide this functionality.
855 The DB_HASH file format is probably the most commonly used of the three
863 contents of the database.
880     # Check for existence of a key
886     # print the contents of the file
900 Note that the like ordinary associative arrays, the order of the keys
913 BTREE uses. Instead of using the normal lexical ordering, a case
979 R_DUP flag discussed below), only a single copy of duplicate keys
996 are truly the same. (note: in versions of the db library prior to
998 possible to recover the original keys in sets of keys that
1007 with an arbitrary number of values. This option is enabled by setting
1008 the flags element of C<$DB_BTREE> to R_DUP when creating the database.
1064 pairs. See L<THE API INTERFACE> for details of both the C<seq> method
1126 In a scalar context the method returns the number of values associated
1133 TRUE, the method returns an associative array. The keys of the
1135 and the values of the array are a count of the number of times that
1185 This method checks for the existence of a specific key/value pair. If the
1228 Again assuming the existence of the C<tree> database
1265 the use of the R_CURSOR flag with seq:
1343 negative indexes. The index -1 refers to the last element of the array,
1345 the start of the array will raise a fatal run-time error.
1349 The operation of the bval option warrants some discussion. Here is the
1350 definition of bval from the Berkeley DB 1.85 recno manual page:
1352     The delimiting byte to be used to mark  the  end  of  a
1355     fied,  newlines  (``\n'')  are  used to mark the end of
1363 use of any of the options in the openinfo parameter. This documentation
1364 error will be fixed in the next release of Berkeley DB.
1380 of Perl earlier than 5.004_57 this example won't work -- see
1411     # Check for existence of a key
1431 If you are using a version of Perl earlier than 5.004_57, the tied
1436 To make the interface more useful for older versions of Perl, a number
1437 of methods are supplied with B<DB_File> to simulate the missing array
1447 Pushes the elements of C<list> to the end of the array.
1451 Removes and returns the last element of the array.
1455 Removes and returns the first element of the array.
1459 Pushes the elements of C<list> to the start of the array.
1463 Returns the number of elements in the array.
1467 Returns a splice of the array.
1473 Here is a more complete example that makes use of some of the methods
1474 described above. It also makes use of the API interface directly (see
1501     # array in a scalar context does not return the number of
1598 itself. This is because C<put> will return the record number of the
1606 possible to make direct use of most of the API functions defined in the
1609 To do this you need to store a copy of the object returned from the tie.
1618 B<Important:> If you have saved a copy of the object returned from
1620 the tied variable is untied and all copies of the saved object are
1652 Whenever a Berkeley DB function returns data via one of its parameters,
1658 hash/array interface in the same piece of code. Although only a few of
1659 the methods used to implement the tied interface currently make use of
1696 DB documentation for the precise meaning of the flags values.
1698 Below is a list of the methods available.
1717 will have the record number of the inserted key/value pair set.
1726 A return code of 1 means that the requested key was not in the
1759 A DBM Filter is a piece of code that is be used when you I<always>
1795 You can use any combination of the methods, from none, to all four.
1804 When each filter is called by Perl, a local copy of C<$_> will contain
1806 the contents of C<$_>. The return code from the filter is ignored.
1820 the length of existing keys/values.
1852 Hopefully the contents of each of the filters should be
1891 the contents of the key, so it wasn't necessary to install any value
1899 Until version 1.72 of this module, the recommended technique for locking
1942 Here is the crux of the problem. A side-effect of opening the B<DB_File>
1956 Now process "A" updates the database and happens to change some of the
1957 data held in the initial buffer. Process "A" terminates, flushing
1964 initial buffer. Once that data gets flushed to disk it will overwrite
1965 some/all of the changes process "A" made to the database.
1967 The result of this scenario is at best a database that doesn't contain
1981 If using B<BerkeleyDB> isn't an option, there are a number of modules
1991 A B<DB_File> wrapper which creates copies of the database file for
1992 read access, so that you have a kind of a multiversioning concurrent read
2000 re-tie-ing the database when you get or drop a lock.  Because of the
2001 flexibility in dropping and re-acquiring the lock in the middle of a
2021 The vast majority of problems that are reported in this area boil down
2025 Here is a real example. Netscape 2.0 keeps a record of the locations you
2035 Here is a snippet of code that is loosely based on Tom Christiansen's
2063     # check for the existence of a specific key
2077 If you make use of the Berkeley DB API, it is I<very> strongly
2080 Even if you don't currently make use of the API interface, it is still
2109 in the script, the source of the problem is really with the untie()
2113 error is caused by the extra copy of the tied object stored in C<$X>.
2147 If you look at the contents of a database file created by DB_File,
2148 there can sometimes be part of a Perl script included in it.
2156 correspond to an area of dynamic memory that happened to be used during
2157 the compilation of the script.
2159 Unless you don't like the possibility of there being part of your Perl
2172 You will get this error message when one of the parameters in the
2176 Here are a couple of possibilities:
2212 of having a C<use strict> in all your scripts.
2216 Articles that are either about B<DB_File> or make use of it.
2233 Some older versions of Berkeley DB had problems with fixed length
2235 version 1.85 of Berkeley DB.
2243 the directory F<ext/DB_File>. Given the amount of time between releases
2244 of Perl the version that ships with Perl is quite likely to be out of
2249 This version of B<DB_File> will work with either version 1.x, 2.x or
2250 3.x of Berkeley DB, but is limited to the functionality provided by
2254 All versions of Berkeley DB are available there.
2270 makes use of, namely Berkeley DB, is not. Berkeley DB has its own
2279     Berkeley DB be freely redistributable. In the case of Perl, that
2281     write are your property, including scripts that make use of
2286 Berkeley DB authors or the author of DB_File. See L<"AUTHOR"> for details.