Lines Matching +refs:mouse +refs:list +refs:to +refs:mouse +refs:code
1 # DB_File.pm -- Perl 5 interface to Berkeley DB
70 croak "Key '$key' not associated with a code reference"
247 Fcntl->import(@O); # first we import what we want to export
350 my @list = @_;
446 while (defined (my $elem = shift @list)) {
470 die "pos unexpectedly changed from $old_pos to $pos with R_IBEFORE"
478 # 'In list context, returns the elements removed from the
579 DB_File - Perl5 access to Berkeley DB version 1.x
598 @list = $X->get_dup($key) ;
599 %list = $X->get_dup($key, 1) ;
606 $X->push(list);
608 $X->unshift(list);
622 B<DB_File> is a module which allows Perl programs to make use of the
629 Berkeley DB is a C library which provides a consistent interface to a
630 number of database formats. B<DB_File> provides an interface to all
639 This database type allows arbitrary key/value pairs to be stored in data
640 files. This is equivalent to the functionality provided by other
646 applications, is built into Berkeley DB. If you do need to use your own
647 hashing algorithm it is possible to write your own in Perl and have
652 The btree format allows arbitrary key/value pairs to be stored in a
655 As with the DB_HASH format, it is possible to provide a user defined
656 Perl routine to perform the comparison of keys. By default, though, the
662 to be manipulated using the same key/value pair interface as in DB_HASH
670 Although B<DB_File> is intended to be used with Berkeley DB version 1,
672 limited to the functionality provided by Berkeley DB 1.x. Anywhere the
673 version 2 or greater interface differs, B<DB_File> arranges for it to work
675 with version 1 to be migrated to version 2 or greater without any changes.
677 If you want to make use of the new features available in Berkeley DB
684 Once you have rebuilt DB_File to use Berkeley DB version 2 or greater,
685 your databases can be recreated using C<db_load>. Refer to the Berkeley DB
691 =head2 Interface to Berkeley DB
693 B<DB_File> allows access to Berkeley DB files using the tie() mechanism
695 allows B<DB_File> to access Berkeley DB files using either an
699 In addition to the tie() interface, it is also possible to access most
705 Berkeley DB uses the function dbopen() to open or create a database.
713 interface methods (DB_HASH, DB_BTREE or DB_RECNO) is to be used.
715 I<openinfo> points to a data structure which allows tailoring of the
728 In the example above $DB_HASH is actually a pre-defined reference to a
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:
742 usually adequate for most applications. If you do need to create extra
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
779 values when you only want to change one. Here is an example:
787 to C functions. In B<DB_File> these keys are used to store references
788 to Perl subs. Below are templates for each of the subs:
813 # necessary to determine that it is greater than $key1
825 It is possible to omit some or all of the final 4 parameters in the
826 call to C<tie> and let them take default values. As DB_HASH is the most
831 is equivalent to:
835 It is also possible to omit the filename parameter as well, so the
840 is equivalent to:
851 uses C<undef> instead of NULL to provide this functionality.
857 to use.
861 This example shows how to create a database, add key/value pairs to the
862 database, delete keys/value pairs and finally how to enumerate the
874 # Add a few key/value pairs to the file
905 The DB_BTREE format is useful when you want to store data in a given
907 will see from the example shown in the next section, it is very easy to
912 This script shows how to override the default sorting algorithm that
935 # Add a key/value pair to the file
938 $h{'mouse'} = 'mickey' ;
945 # Note it is not necessary to sort the keys as
952 Here is the output from the code above.
954 mouse
958 There are a few point to bear in mind if you want to change the
977 would be considered duplicates, and assigning to the second one
981 three values to the keys: 'KEY', 'Key', and 'key' would leave just
984 to provide fully qualified comparison functions when necessary.
985 For example, the above comparison routine could be modified to
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
1006 The BTREE file type optionally allows a single key to be associated
1008 the flags element of C<$DB_BTREE> to R_DUP when creating the database.
1011 want to manipulate a BTREE database with duplicate keys. Consider this
1012 code:
1029 # Add some key/value pairs to the file
1034 $h{'mouse'} = 'mickey' ;
1049 mouse -> mickey
1053 I<seem> to have the same value, namely C<Larry>. The problem is caused
1055 the associative array interface is used to fetch the value associated
1058 Although it may not be immediately obvious from the code above, the
1059 associative array interface can be used to write values with duplicate
1060 keys, but it cannot be used to read them back from the database.
1062 The way to get around this problem is to use the Berkeley DB API method
1063 called C<seq>. This method allows sequential access to key/value
1084 # Add some key/value pairs to the file
1089 $h{'mouse'} = 'mickey' ;
1108 mouse -> mickey
1123 @list = $x->get_dup($key) ;
1124 %list = $x->get_dup($key, 1) ;
1129 In list context, it returns all the values which match C<$key>. Note
1132 In list context, if the second parameter is present and evaluates
1134 associative array correspond to the values that matched in the BTREE
1162 my @list = sort $x->get_dup("Wall") ;
1163 print "Wall => [@list]\n" ;
1165 @list = $x->get_dup("Smith") ;
1166 print "Smith => [@list]\n" ;
1168 @list = $x->get_dup("Dog") ;
1169 print "Dog => [@list]\n" ;
1186 pair exists, the cursor is left pointing to the pair and the method
1258 The BTREE interface has a feature which allows partial keys to be
1269 is the smallest key greater than or equal to the specified key,
1272 In the example script below, the C<match> sub uses this feature to find
1297 # Add some key/value pairs to the file
1298 $h{'mouse'} = 'mickey' ;
1327 mouse -> mickey
1332 a -> mouse -> mickey
1336 DB_RECNO provides an interface to flat text files. Both variable and
1339 In order to make RECNO more compatible with Perl, the array offset for
1343 negative indexes. The index -1 refers to the last element of the array,
1344 -2 the second last, and so on. Attempting to access an element before
1352 The delimiting byte to be used to mark the end of a
1355 fied, newlines (``\n'') are used to mark the end of
1359 The second sentence is wrong. In actual fact bval will only default to
1361 openinfo parameter is used at all, the value that happens to be in bval
1362 will be used. That means you always have to specify bval when making
1368 quite useful, so B<DB_File> conforms to it.
1371 still have bval default to C<"\n"> for variable length records, and
1374 Also note that the bval option only allows you to specify a single byte
1394 # Add a few key/value pairs to the file
1437 of methods are supplied with B<DB_File> to simulate the missing array
1445 =item B<$X-E<gt>push(list) ;>
1447 Pushes the elements of C<list> to the end of the array.
1457 =item B<$X-E<gt>unshift(list) ;>
1459 Pushes the elements of C<list> to the start of the array.
1490 # first create a text file to play with
1519 # Use the API to add a new record after record 2.
1584 it is necessary to use either this:
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.
1633 close() and dbopen() itself. The B<DB_File> method interface to the
1634 supported functions have been implemented to mirror the way Berkeley DB
1642 All return -1 to signify an error and set C<$!> to the exact
1643 error code. The return code 1 generally (but not always) means that the
1657 If you are careful, it is possible to mix API calls with the tied
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
1662 code will probably not do what you expect:
1677 The code above can be rearranged to get around the problem, like this:
1695 in the methods defined below are also available. Refer to the Berkeley
1698 Below is a list of the methods available.
1726 A return code of 1 means that the requested key was not in the
1736 not use C<fd> to lock your database.
1743 Both the C<$key> and C<$value> parameters will be set to the key/value
1751 Flushes any cached buffers to disk.
1759 A DBM Filter is a piece of code that is be used when you I<always>
1760 want to make the same transformation to all keys and/or values in a
1764 and each is used to install (or uninstall) a single DBM Filter. Each
1765 expects a single parameter, namely a reference to a sub. The only
1775 every time you write a key to a DBM database.
1780 every time you write a value to a DBM database.
1795 You can use any combination of the methods, from none, to all four.
1800 To delete a filter pass C<undef> to it.
1805 the key or value to be filtered. Filtering is achieved by modifying
1806 the contents of C<$_>. The return code from the filter is ignored.
1811 that you need to share with a third-party C application. The C application
1813 when Perl writes to DBM databases it doesn't use NULL termination, so
1814 your Perl application will have to manage NULL termination itself. When
1815 you write to the database you will have to use something like this:
1819 Similarly the NULL needs to be taken into account when you are considering
1823 in the main application code and have a mechanism that automatically
1824 added the terminating NULL to all keys and values whenever you write to
1859 Here is another real-life example. By default, whenever Perl writes to
1866 "12345". If you actually want the key to be stored in the DBM database
1867 as a C int, you will have to use C<pack> when writing, and C<unpack>
1890 This time only two filters have been used -- we only need to manipulate
1891 the contents of the key, so it wasn't necessary to install any value
1900 B<DB_File> databases was to flock the filehandle returned from the "fd"
1901 function. Unfortunately this technique has been shown to be fundamentally
1902 flawed (Kudos to David Harris for tracking this down). Use it at your own
1926 Use "tie" to open the database.
1934 Read & Write to the database.
1947 say "A" and "B", both want to update the same B<DB_File> database
1951 process "B" tries to open the same database - step 1 will succeed,
1953 important thing to notice here is that at this point in time both
1956 Now process "A" updates the database and happens to change some of the
1958 all cached data to disk and releasing the database lock. At this point
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.
1974 =head2 Safe ways to lock a database
1977 The companion module to this one, B<BerkeleyDB>, provides an interface
1978 to this locking functionality. If you are serious about locking
1982 available on CPAN that can be used to implement locking. Each one
1998 A B<DB_File> wrapper that has the ability to lock and unlock the database
2010 one to use the same lockfile for multiple databases to avoid deadlock
2022 to the fact that C strings are NULL terminated, whilst Perl strings are
2023 not. See L<DBM FILTERS> for a generic way to work around this problem.
2032 terminating NULL. This means you need to be careful when accessing the
2035 Here is a snippet of code that is loosely based on Tom Christiansen's
2064 # remember to add the NULL
2108 Although the error message above refers to the second tie() statement
2114 If you haven't, then the problem boils down to the fact that the
2116 references to the tied object are destroyed. Both the tied variable,
2117 C<%x>, and C<$X> above hold a reference to the object. The call to
2121 attempt to open a database that is already open via the catch-all
2130 modified to fix the original problem by destroying the API object
2150 This happens because Berkeley DB uses dynamic memory to allocate
2151 buffers which will subsequently be written to the database file. Being
2155 where a Perl script gets written to the database, the random junk will
2156 correspond to an area of dynamic memory that happened to be used during
2160 scripts embedded in a database file, this is nothing to worry about.
2165 can layer transparently over B<DB_File> to accomplish this feat.
2173 C<tie> call is wrong. Unfortunately there are quite a few parameters to
2174 get wrong, so it can be difficult to figure out which one it is.
2182 Attempting to reopen a database without closing it.
2229 Moved to the Changes file.
2237 I am sure there are bugs in the code. If you do find any, or can
2244 of Perl the version that ships with Perl is quite likely to be out of
2250 3.x of Berkeley DB, but is limited to the functionality provided by
2260 F<http://reality.sgi.com/ariel>. It has the patches necessary to
2271 copyright and its own license. Please take the time to read it.
2276 Do I have to license DB to use it in Perl scripts?