| 1 |
.\" -*- mode: troff; coding: utf-8 -*- |
| 2 |
.\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45) |
| 3 |
.\" |
| 4 |
.\" Standard preamble: |
| 5 |
.\" ======================================================================== |
| 6 |
.de Sp \" Vertical space (when we can't use .PP) |
| 7 |
.if t .sp .5v |
| 8 |
.if n .sp |
| 9 |
.. |
| 10 |
.de Vb \" Begin verbatim text |
| 11 |
.ft CW |
| 12 |
.nf |
| 13 |
.ne \\$1 |
| 14 |
.. |
| 15 |
.de Ve \" End verbatim text |
| 16 |
.ft R |
| 17 |
.fi |
| 18 |
.. |
| 19 |
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. |
| 20 |
.ie n \{\ |
| 21 |
. ds C` "" |
| 22 |
. ds C' "" |
| 23 |
'br\} |
| 24 |
.el\{\ |
| 25 |
. ds C` |
| 26 |
. ds C' |
| 27 |
'br\} |
| 28 |
.\" |
| 29 |
.\" Escape single quotes in literal strings from groff's Unicode transform. |
| 30 |
.ie \n(.g .ds Aq \(aq |
| 31 |
.el .ds Aq ' |
| 32 |
.\" |
| 33 |
.\" If the F register is >0, we'll generate index entries on stderr for |
| 34 |
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index |
| 35 |
.\" entries marked with X<> in POD. Of course, you'll have to process the |
| 36 |
.\" output yourself in some meaningful fashion. |
| 37 |
.\" |
| 38 |
.\" Avoid warning from groff about undefined register 'F'. |
| 39 |
.de IX |
| 40 |
.. |
| 41 |
.nr rF 0 |
| 42 |
.if \n(.g .if rF .nr rF 1 |
| 43 |
.if (\n(rF:(\n(.g==0)) \{\ |
| 44 |
. if \nF \{\ |
| 45 |
. de IX |
| 46 |
. tm Index:\\$1\t\\n%\t"\\$2" |
| 47 |
.. |
| 48 |
. if !\nF==2 \{\ |
| 49 |
. nr % 0 |
| 50 |
. nr F 2 |
| 51 |
. \} |
| 52 |
. \} |
| 53 |
.\} |
| 54 |
.rr rF |
| 55 |
.\" ======================================================================== |
| 56 |
.\" |
| 57 |
.IX Title "DB_File 3perl" |
| 58 |
.TH DB_File 3perl 2025-11-16 "perl v5.40.1" "Perl Programmers Reference Guide" |
| 59 |
.\" For nroff, turn off justification. Always turn off hyphenation; it makes |
| 60 |
.\" way too many mistakes in technical documents. |
| 61 |
.if n .ad l |
| 62 |
.nh |
| 63 |
.SH NAME |
| 64 |
DB_File \- Perl5 access to Berkeley DB version 1.x |
| 65 |
.SH SYNOPSIS |
| 66 |
.IX Header "SYNOPSIS" |
| 67 |
.Vb 1 |
| 68 |
\& use DB_File; |
| 69 |
\& |
| 70 |
\& [$X =] tie %hash, \*(AqDB_File\*(Aq, [$filename, $flags, $mode, $DB_HASH] ; |
| 71 |
\& [$X =] tie %hash, \*(AqDB_File\*(Aq, $filename, $flags, $mode, $DB_BTREE ; |
| 72 |
\& [$X =] tie @array, \*(AqDB_File\*(Aq, $filename, $flags, $mode, $DB_RECNO ; |
| 73 |
\& |
| 74 |
\& $status = $X\->del($key [, $flags]) ; |
| 75 |
\& $status = $X\->put($key, $value [, $flags]) ; |
| 76 |
\& $status = $X\->get($key, $value [, $flags]) ; |
| 77 |
\& $status = $X\->seq($key, $value, $flags) ; |
| 78 |
\& $status = $X\->sync([$flags]) ; |
| 79 |
\& $status = $X\->fd ; |
| 80 |
\& |
| 81 |
\& # BTREE only |
| 82 |
\& $count = $X\->get_dup($key) ; |
| 83 |
\& @list = $X\->get_dup($key) ; |
| 84 |
\& %list = $X\->get_dup($key, 1) ; |
| 85 |
\& $status = $X\->find_dup($key, $value) ; |
| 86 |
\& $status = $X\->del_dup($key, $value) ; |
| 87 |
\& |
| 88 |
\& # RECNO only |
| 89 |
\& $a = $X\->length; |
| 90 |
\& $a = $X\->pop ; |
| 91 |
\& $X\->push(list); |
| 92 |
\& $a = $X\->shift; |
| 93 |
\& $X\->unshift(list); |
| 94 |
\& @r = $X\->splice(offset, length, elements); |
| 95 |
\& |
| 96 |
\& # DBM Filters |
| 97 |
\& $old_filter = $db\->filter_store_key ( sub { ... } ) ; |
| 98 |
\& $old_filter = $db\->filter_store_value( sub { ... } ) ; |
| 99 |
\& $old_filter = $db\->filter_fetch_key ( sub { ... } ) ; |
| 100 |
\& $old_filter = $db\->filter_fetch_value( sub { ... } ) ; |
| 101 |
\& |
| 102 |
\& untie %hash ; |
| 103 |
\& untie @array ; |
| 104 |
.Ve |
| 105 |
.SH DESCRIPTION |
| 106 |
.IX Header "DESCRIPTION" |
| 107 |
\&\fBDB_File\fR is a module which allows Perl programs to make use of the |
| 108 |
facilities provided by Berkeley DB version 1.x (if you have a newer |
| 109 |
version of DB, see "Using DB_File with Berkeley DB version 2 or greater"). |
| 110 |
It is assumed that you have a copy of the Berkeley DB manual pages at |
| 111 |
hand when reading this documentation. The interface defined here |
| 112 |
mirrors the Berkeley DB interface closely. |
| 113 |
.PP |
| 114 |
Berkeley DB is a C library which provides a consistent interface to a |
| 115 |
number of database formats. \fBDB_File\fR provides an interface to all |
| 116 |
three of the database types currently supported by Berkeley DB. |
| 117 |
.PP |
| 118 |
The file types are: |
| 119 |
.IP \fBDB_HASH\fR 5 |
| 120 |
.IX Item "DB_HASH" |
| 121 |
This database type allows arbitrary key/value pairs to be stored in data |
| 122 |
files. This is equivalent to the functionality provided by other |
| 123 |
hashing packages like DBM, NDBM, ODBM, GDBM, and SDBM. Remember though, |
| 124 |
the files created using DB_HASH are not compatible with any of the |
| 125 |
other packages mentioned. |
| 126 |
.Sp |
| 127 |
A default hashing algorithm, which will be adequate for most |
| 128 |
applications, is built into Berkeley DB. If you do need to use your own |
| 129 |
hashing algorithm it is possible to write your own in Perl and have |
| 130 |
\&\fBDB_File\fR use it instead. |
| 131 |
.IP \fBDB_BTREE\fR 5 |
| 132 |
.IX Item "DB_BTREE" |
| 133 |
The btree format allows arbitrary key/value pairs to be stored in a |
| 134 |
sorted, balanced binary tree. |
| 135 |
.Sp |
| 136 |
As with the DB_HASH format, it is possible to provide a user defined |
| 137 |
Perl routine to perform the comparison of keys. By default, though, the |
| 138 |
keys are stored in lexical order. |
| 139 |
.IP \fBDB_RECNO\fR 5 |
| 140 |
.IX Item "DB_RECNO" |
| 141 |
DB_RECNO allows both fixed-length and variable-length flat text files |
| 142 |
to be manipulated using the same key/value pair interface as in DB_HASH |
| 143 |
and DB_BTREE. In this case the key will consist of a record (line) |
| 144 |
number. |
| 145 |
.SS "Using DB_File with Berkeley DB version 2 or greater" |
| 146 |
.IX Subsection "Using DB_File with Berkeley DB version 2 or greater" |
| 147 |
Although \fBDB_File\fR is intended to be used with Berkeley DB version 1, |
| 148 |
it can also be used with version 2, 3 or 4. In this case the interface is |
| 149 |
limited to the functionality provided by Berkeley DB 1.x. Anywhere the |
| 150 |
version 2 or greater interface differs, \fBDB_File\fR arranges for it to work |
| 151 |
like version 1. This feature allows \fBDB_File\fR scripts that were built |
| 152 |
with version 1 to be migrated to version 2 or greater without any changes. |
| 153 |
.PP |
| 154 |
If you want to make use of the new features available in Berkeley DB |
| 155 |
2.x or greater, use the Perl module BerkeleyDB <https://metacpan.org/pod/BerkeleyDB> instead. |
| 156 |
.PP |
| 157 |
\&\fBNote:\fR The database file format has changed multiple times in Berkeley |
| 158 |
DB version 2, 3 and 4. If you cannot recreate your databases, you |
| 159 |
must dump any existing databases with either the \f(CW\*(C`db_dump\*(C'\fR or the |
| 160 |
\&\f(CW\*(C`db_dump185\*(C'\fR utility that comes with Berkeley DB. |
| 161 |
Once you have rebuilt DB_File to use Berkeley DB version 2 or greater, |
| 162 |
your databases can be recreated using \f(CW\*(C`db_load\*(C'\fR. Refer to the Berkeley DB |
| 163 |
documentation for further details. |
| 164 |
.PP |
| 165 |
Please read "COPYRIGHT" before using version 2.x or greater of Berkeley |
| 166 |
DB with DB_File. |
| 167 |
.SS "Interface to Berkeley DB" |
| 168 |
.IX Subsection "Interface to Berkeley DB" |
| 169 |
\&\fBDB_File\fR allows access to Berkeley DB files using the \fBtie()\fR mechanism |
| 170 |
in Perl 5 (for full details, see "\fBtie()\fR" in perlfunc). This facility |
| 171 |
allows \fBDB_File\fR to access Berkeley DB files using either an |
| 172 |
associative array (for DB_HASH & DB_BTREE file types) or an ordinary |
| 173 |
array (for the DB_RECNO file type). |
| 174 |
.PP |
| 175 |
In addition to the \fBtie()\fR interface, it is also possible to access most |
| 176 |
of the functions provided in the Berkeley DB API directly. |
| 177 |
See "THE API INTERFACE". |
| 178 |
.SS "Opening a Berkeley DB Database File" |
| 179 |
.IX Subsection "Opening a Berkeley DB Database File" |
| 180 |
Berkeley DB uses the function \fBdbopen()\fR to open or create a database. |
| 181 |
Here is the C prototype for \fBdbopen()\fR: |
| 182 |
.PP |
| 183 |
.Vb 3 |
| 184 |
\& DB* |
| 185 |
\& dbopen (const char * file, int flags, int mode, |
| 186 |
\& DBTYPE type, const void * openinfo) |
| 187 |
.Ve |
| 188 |
.PP |
| 189 |
The parameter \f(CW\*(C`type\*(C'\fR is an enumeration which specifies which of the 3 |
| 190 |
interface methods (DB_HASH, DB_BTREE or DB_RECNO) is to be used. |
| 191 |
Depending on which of these is actually chosen, the final parameter, |
| 192 |
\&\fIopeninfo\fR points to a data structure which allows tailoring of the |
| 193 |
specific interface method. |
| 194 |
.PP |
| 195 |
This interface is handled slightly differently in \fBDB_File\fR. Here is |
| 196 |
an equivalent call using \fBDB_File\fR: |
| 197 |
.PP |
| 198 |
.Vb 1 |
| 199 |
\& tie %array, \*(AqDB_File\*(Aq, $filename, $flags, $mode, $DB_HASH ; |
| 200 |
.Ve |
| 201 |
.PP |
| 202 |
The \f(CW\*(C`filename\*(C'\fR, \f(CW\*(C`flags\*(C'\fR and \f(CW\*(C`mode\*(C'\fR parameters are the direct |
| 203 |
equivalent of their \fBdbopen()\fR counterparts. The final parameter \f(CW$DB_HASH\fR |
| 204 |
performs the function of both the \f(CW\*(C`type\*(C'\fR and \f(CW\*(C`openinfo\*(C'\fR parameters in |
| 205 |
\&\fBdbopen()\fR. |
| 206 |
.PP |
| 207 |
In the example above \f(CW$DB_HASH\fR is actually a pre-defined reference to a |
| 208 |
hash object. \fBDB_File\fR has three of these pre-defined references. |
| 209 |
Apart from \f(CW$DB_HASH\fR, there is also \f(CW$DB_BTREE\fR and \f(CW$DB_RECNO\fR. |
| 210 |
.PP |
| 211 |
The keys allowed in each of these pre-defined references is limited to |
| 212 |
the names used in the equivalent C structure. So, for example, the |
| 213 |
\&\f(CW$DB_HASH\fR reference will only allow keys called \f(CW\*(C`bsize\*(C'\fR, \f(CW\*(C`cachesize\*(C'\fR, |
| 214 |
\&\f(CW\*(C`ffactor\*(C'\fR, \f(CW\*(C`hash\*(C'\fR, \f(CW\*(C`lorder\*(C'\fR and \f(CW\*(C`nelem\*(C'\fR. |
| 215 |
.PP |
| 216 |
To change one of these elements, just assign to it like this: |
| 217 |
.PP |
| 218 |
.Vb 1 |
| 219 |
\& $DB_HASH\->{\*(Aqcachesize\*(Aq} = 10000 ; |
| 220 |
.Ve |
| 221 |
.PP |
| 222 |
The three predefined variables \f(CW$DB_HASH\fR, \f(CW$DB_BTREE\fR and \f(CW$DB_RECNO\fR are |
| 223 |
usually adequate for most applications. If you do need to create extra |
| 224 |
instances of these objects, constructors are available for each file |
| 225 |
type. |
| 226 |
.PP |
| 227 |
Here are examples of the constructors and the valid options available |
| 228 |
for DB_HASH, DB_BTREE and DB_RECNO respectively. |
| 229 |
.PP |
| 230 |
.Vb 7 |
| 231 |
\& $a = DB_File::HASHINFO\->new(); |
| 232 |
\& $a\->{\*(Aqbsize\*(Aq} ; |
| 233 |
\& $a\->{\*(Aqcachesize\*(Aq} ; |
| 234 |
\& $a\->{\*(Aqffactor\*(Aq}; |
| 235 |
\& $a\->{\*(Aqhash\*(Aq} ; |
| 236 |
\& $a\->{\*(Aqlorder\*(Aq} ; |
| 237 |
\& $a\->{\*(Aqnelem\*(Aq} ; |
| 238 |
\& |
| 239 |
\& $b = DB_File::BTREEINFO\->new(); |
| 240 |
\& $b\->{\*(Aqflags\*(Aq} ; |
| 241 |
\& $b\->{\*(Aqcachesize\*(Aq} ; |
| 242 |
\& $b\->{\*(Aqmaxkeypage\*(Aq} ; |
| 243 |
\& $b\->{\*(Aqminkeypage\*(Aq} ; |
| 244 |
\& $b\->{\*(Aqpsize\*(Aq} ; |
| 245 |
\& $b\->{\*(Aqcompare\*(Aq} ; |
| 246 |
\& $b\->{\*(Aqprefix\*(Aq} ; |
| 247 |
\& $b\->{\*(Aqlorder\*(Aq} ; |
| 248 |
\& |
| 249 |
\& $c = DB_File::RECNOINFO\->new(); |
| 250 |
\& $c\->{\*(Aqbval\*(Aq} ; |
| 251 |
\& $c\->{\*(Aqcachesize\*(Aq} ; |
| 252 |
\& $c\->{\*(Aqpsize\*(Aq} ; |
| 253 |
\& $c\->{\*(Aqflags\*(Aq} ; |
| 254 |
\& $c\->{\*(Aqlorder\*(Aq} ; |
| 255 |
\& $c\->{\*(Aqreclen\*(Aq} ; |
| 256 |
\& $c\->{\*(Aqbfname\*(Aq} ; |
| 257 |
.Ve |
| 258 |
.PP |
| 259 |
The values stored in the hashes above are mostly the direct equivalent |
| 260 |
of their C counterpart. Like their C counterparts, all are set to a |
| 261 |
default values \- that means you don't have to set \fIall\fR of the |
| 262 |
values when you only want to change one. Here is an example: |
| 263 |
.PP |
| 264 |
.Vb 3 |
| 265 |
\& $a = DB_File::HASHINFO\->new(); |
| 266 |
\& $a\->{\*(Aqcachesize\*(Aq} = 12345 ; |
| 267 |
\& tie %y, \*(AqDB_File\*(Aq, "filename", $flags, 0777, $a ; |
| 268 |
.Ve |
| 269 |
.PP |
| 270 |
A few of the options need extra discussion here. When used, the C |
| 271 |
equivalent of the keys \f(CW\*(C`hash\*(C'\fR, \f(CW\*(C`compare\*(C'\fR and \f(CW\*(C`prefix\*(C'\fR store pointers |
| 272 |
to C functions. In \fBDB_File\fR these keys are used to store references |
| 273 |
to Perl subs. Below are templates for each of the subs: |
| 274 |
.PP |
| 275 |
.Vb 7 |
| 276 |
\& sub hash |
| 277 |
\& { |
| 278 |
\& my ($data) = @_ ; |
| 279 |
\& ... |
| 280 |
\& # return the hash value for $data |
| 281 |
\& return $hash ; |
| 282 |
\& } |
| 283 |
\& |
| 284 |
\& sub compare |
| 285 |
\& { |
| 286 |
\& my ($key, $key2) = @_ ; |
| 287 |
\& ... |
| 288 |
\& # return 0 if $key1 eq $key2 |
| 289 |
\& # \-1 if $key1 lt $key2 |
| 290 |
\& # 1 if $key1 gt $key2 |
| 291 |
\& return (\-1 , 0 or 1) ; |
| 292 |
\& } |
| 293 |
\& |
| 294 |
\& sub prefix |
| 295 |
\& { |
| 296 |
\& my ($key, $key2) = @_ ; |
| 297 |
\& ... |
| 298 |
\& # return number of bytes of $key2 which are |
| 299 |
\& # necessary to determine that it is greater than $key1 |
| 300 |
\& return $bytes ; |
| 301 |
\& } |
| 302 |
.Ve |
| 303 |
.PP |
| 304 |
See "Changing the BTREE sort order" for an example of using the |
| 305 |
\&\f(CW\*(C`compare\*(C'\fR template. |
| 306 |
.PP |
| 307 |
If you are using the DB_RECNO interface and you intend making use of |
| 308 |
\&\f(CW\*(C`bval\*(C'\fR, you should check out "The 'bval' Option". |
| 309 |
.SS "Default Parameters" |
| 310 |
.IX Subsection "Default Parameters" |
| 311 |
It is possible to omit some or all of the final 4 parameters in the |
| 312 |
call to \f(CW\*(C`tie\*(C'\fR and let them take default values. As DB_HASH is the most |
| 313 |
common file format used, the call: |
| 314 |
.PP |
| 315 |
.Vb 1 |
| 316 |
\& tie %A, "DB_File", "filename" ; |
| 317 |
.Ve |
| 318 |
.PP |
| 319 |
is equivalent to: |
| 320 |
.PP |
| 321 |
.Vb 1 |
| 322 |
\& tie %A, "DB_File", "filename", O_CREAT|O_RDWR, 0666, $DB_HASH ; |
| 323 |
.Ve |
| 324 |
.PP |
| 325 |
It is also possible to omit the filename parameter as well, so the |
| 326 |
call: |
| 327 |
.PP |
| 328 |
.Vb 1 |
| 329 |
\& tie %A, "DB_File" ; |
| 330 |
.Ve |
| 331 |
.PP |
| 332 |
is equivalent to: |
| 333 |
.PP |
| 334 |
.Vb 1 |
| 335 |
\& tie %A, "DB_File", undef, O_CREAT|O_RDWR, 0666, $DB_HASH ; |
| 336 |
.Ve |
| 337 |
.PP |
| 338 |
See "In Memory Databases" for a discussion on the use of \f(CW\*(C`undef\*(C'\fR |
| 339 |
in place of a filename. |
| 340 |
.SS "In Memory Databases" |
| 341 |
.IX Subsection "In Memory Databases" |
| 342 |
Berkeley DB allows the creation of in-memory databases by using NULL |
| 343 |
(that is, a \f(CW\*(C`(char *)0\*(C'\fR in C) in place of the filename. \fBDB_File\fR |
| 344 |
uses \f(CW\*(C`undef\*(C'\fR instead of NULL to provide this functionality. |
| 345 |
.SH DB_HASH |
| 346 |
.IX Header "DB_HASH" |
| 347 |
The DB_HASH file format is probably the most commonly used of the three |
| 348 |
file formats that \fBDB_File\fR supports. It is also very straightforward |
| 349 |
to use. |
| 350 |
.SS "A Simple Example" |
| 351 |
.IX Subsection "A Simple Example" |
| 352 |
This example shows how to create a database, add key/value pairs to the |
| 353 |
database, delete keys/value pairs and finally how to enumerate the |
| 354 |
contents of the database. |
| 355 |
.PP |
| 356 |
.Vb 4 |
| 357 |
\& use warnings ; |
| 358 |
\& use strict ; |
| 359 |
\& use DB_File ; |
| 360 |
\& our (%h, $k, $v) ; |
| 361 |
\& |
| 362 |
\& unlink "fruit" ; |
| 363 |
\& tie %h, "DB_File", "fruit", O_RDWR|O_CREAT, 0666, $DB_HASH |
| 364 |
\& or die "Cannot open file \*(Aqfruit\*(Aq: $!\en"; |
| 365 |
\& |
| 366 |
\& # Add a few key/value pairs to the file |
| 367 |
\& $h{"apple"} = "red" ; |
| 368 |
\& $h{"orange"} = "orange" ; |
| 369 |
\& $h{"banana"} = "yellow" ; |
| 370 |
\& $h{"tomato"} = "red" ; |
| 371 |
\& |
| 372 |
\& # Check for existence of a key |
| 373 |
\& print "Banana Exists\en\en" if $h{"banana"} ; |
| 374 |
\& |
| 375 |
\& # Delete a key/value pair. |
| 376 |
\& delete $h{"apple"} ; |
| 377 |
\& |
| 378 |
\& # print the contents of the file |
| 379 |
\& while (($k, $v) = each %h) |
| 380 |
\& { print "$k \-> $v\en" } |
| 381 |
\& |
| 382 |
\& untie %h ; |
| 383 |
.Ve |
| 384 |
.PP |
| 385 |
here is the output: |
| 386 |
.PP |
| 387 |
.Vb 1 |
| 388 |
\& Banana Exists |
| 389 |
\& |
| 390 |
\& orange \-> orange |
| 391 |
\& tomato \-> red |
| 392 |
\& banana \-> yellow |
| 393 |
.Ve |
| 394 |
.PP |
| 395 |
Note that the like ordinary associative arrays, the order of the keys |
| 396 |
retrieved is in an apparently random order. |
| 397 |
.SH DB_BTREE |
| 398 |
.IX Header "DB_BTREE" |
| 399 |
The DB_BTREE format is useful when you want to store data in a given |
| 400 |
order. By default the keys will be stored in lexical order, but as you |
| 401 |
will see from the example shown in the next section, it is very easy to |
| 402 |
define your own sorting function. |
| 403 |
.SS "Changing the BTREE sort order" |
| 404 |
.IX Subsection "Changing the BTREE sort order" |
| 405 |
This script shows how to override the default sorting algorithm that |
| 406 |
BTREE uses. Instead of using the normal lexical ordering, a case |
| 407 |
insensitive compare function will be used. |
| 408 |
.PP |
| 409 |
.Vb 3 |
| 410 |
\& use warnings ; |
| 411 |
\& use strict ; |
| 412 |
\& use DB_File ; |
| 413 |
\& |
| 414 |
\& my %h ; |
| 415 |
\& |
| 416 |
\& sub Compare |
| 417 |
\& { |
| 418 |
\& my ($key1, $key2) = @_ ; |
| 419 |
\& "\eL$key1" cmp "\eL$key2" ; |
| 420 |
\& } |
| 421 |
\& |
| 422 |
\& # specify the Perl sub that will do the comparison |
| 423 |
\& $DB_BTREE\->{\*(Aqcompare\*(Aq} = \e&Compare ; |
| 424 |
\& |
| 425 |
\& unlink "tree" ; |
| 426 |
\& tie %h, "DB_File", "tree", O_RDWR|O_CREAT, 0666, $DB_BTREE |
| 427 |
\& or die "Cannot open file \*(Aqtree\*(Aq: $!\en" ; |
| 428 |
\& |
| 429 |
\& # Add a key/value pair to the file |
| 430 |
\& $h{\*(AqWall\*(Aq} = \*(AqLarry\*(Aq ; |
| 431 |
\& $h{\*(AqSmith\*(Aq} = \*(AqJohn\*(Aq ; |
| 432 |
\& $h{\*(Aqmouse\*(Aq} = \*(Aqmickey\*(Aq ; |
| 433 |
\& $h{\*(Aqduck\*(Aq} = \*(Aqdonald\*(Aq ; |
| 434 |
\& |
| 435 |
\& # Delete |
| 436 |
\& delete $h{"duck"} ; |
| 437 |
\& |
| 438 |
\& # Cycle through the keys printing them in order. |
| 439 |
\& # Note it is not necessary to sort the keys as |
| 440 |
\& # the btree will have kept them in order automatically. |
| 441 |
\& foreach (keys %h) |
| 442 |
\& { print "$_\en" } |
| 443 |
\& |
| 444 |
\& untie %h ; |
| 445 |
.Ve |
| 446 |
.PP |
| 447 |
Here is the output from the code above. |
| 448 |
.PP |
| 449 |
.Vb 3 |
| 450 |
\& mouse |
| 451 |
\& Smith |
| 452 |
\& Wall |
| 453 |
.Ve |
| 454 |
.PP |
| 455 |
There are a few point to bear in mind if you want to change the |
| 456 |
ordering in a BTREE database: |
| 457 |
.IP 1. 5 |
| 458 |
The new compare function must be specified when you create the database. |
| 459 |
.IP 2. 5 |
| 460 |
You cannot change the ordering once the database has been created. Thus |
| 461 |
you must use the same compare function every time you access the |
| 462 |
database. |
| 463 |
.IP 3. 5 |
| 464 |
Duplicate keys are entirely defined by the comparison function. |
| 465 |
In the case-insensitive example above, the keys: 'KEY' and 'key' |
| 466 |
would be considered duplicates, and assigning to the second one |
| 467 |
would overwrite the first. If duplicates are allowed for (with the |
| 468 |
R_DUP flag discussed below), only a single copy of duplicate keys |
| 469 |
is stored in the database \-\-\- so (again with example above) assigning |
| 470 |
three values to the keys: 'KEY', 'Key', and 'key' would leave just |
| 471 |
the first key: 'KEY' in the database with three values. For some |
| 472 |
situations this results in information loss, so care should be taken |
| 473 |
to provide fully qualified comparison functions when necessary. |
| 474 |
For example, the above comparison routine could be modified to |
| 475 |
additionally compare case-sensitively if two keys are equal in the |
| 476 |
case insensitive comparison: |
| 477 |
.Sp |
| 478 |
.Vb 5 |
| 479 |
\& sub compare { |
| 480 |
\& my($key1, $key2) = @_; |
| 481 |
\& lc $key1 cmp lc $key2 || |
| 482 |
\& $key1 cmp $key2; |
| 483 |
\& } |
| 484 |
.Ve |
| 485 |
.Sp |
| 486 |
And now you will only have duplicates when the keys themselves |
| 487 |
are truly the same. (note: in versions of the db library prior to |
| 488 |
about November 1996, such duplicate keys were retained so it was |
| 489 |
possible to recover the original keys in sets of keys that |
| 490 |
compared as equal). |
| 491 |
.SS "Handling Duplicate Keys" |
| 492 |
.IX Subsection "Handling Duplicate Keys" |
| 493 |
The BTREE file type optionally allows a single key to be associated |
| 494 |
with an arbitrary number of values. This option is enabled by setting |
| 495 |
the flags element of \f(CW$DB_BTREE\fR to R_DUP when creating the database. |
| 496 |
.PP |
| 497 |
There are some difficulties in using the tied hash interface if you |
| 498 |
want to manipulate a BTREE database with duplicate keys. Consider this |
| 499 |
code: |
| 500 |
.PP |
| 501 |
.Vb 3 |
| 502 |
\& use warnings ; |
| 503 |
\& use strict ; |
| 504 |
\& use DB_File ; |
| 505 |
\& |
| 506 |
\& my ($filename, %h) ; |
| 507 |
\& |
| 508 |
\& $filename = "tree" ; |
| 509 |
\& unlink $filename ; |
| 510 |
\& |
| 511 |
\& # Enable duplicate records |
| 512 |
\& $DB_BTREE\->{\*(Aqflags\*(Aq} = R_DUP ; |
| 513 |
\& |
| 514 |
\& tie %h, "DB_File", $filename, O_RDWR|O_CREAT, 0666, $DB_BTREE |
| 515 |
\& or die "Cannot open $filename: $!\en"; |
| 516 |
\& |
| 517 |
\& # Add some key/value pairs to the file |
| 518 |
\& $h{\*(AqWall\*(Aq} = \*(AqLarry\*(Aq ; |
| 519 |
\& $h{\*(AqWall\*(Aq} = \*(AqBrick\*(Aq ; # Note the duplicate key |
| 520 |
\& $h{\*(AqWall\*(Aq} = \*(AqBrick\*(Aq ; # Note the duplicate key and value |
| 521 |
\& $h{\*(AqSmith\*(Aq} = \*(AqJohn\*(Aq ; |
| 522 |
\& $h{\*(Aqmouse\*(Aq} = \*(Aqmickey\*(Aq ; |
| 523 |
\& |
| 524 |
\& # iterate through the associative array |
| 525 |
\& # and print each key/value pair. |
| 526 |
\& foreach (sort keys %h) |
| 527 |
\& { print "$_ \-> $h{$_}\en" } |
| 528 |
\& |
| 529 |
\& untie %h ; |
| 530 |
.Ve |
| 531 |
.PP |
| 532 |
Here is the output: |
| 533 |
.PP |
| 534 |
.Vb 5 |
| 535 |
\& Smith \-> John |
| 536 |
\& Wall \-> Larry |
| 537 |
\& Wall \-> Larry |
| 538 |
\& Wall \-> Larry |
| 539 |
\& mouse \-> mickey |
| 540 |
.Ve |
| 541 |
.PP |
| 542 |
As you can see 3 records have been successfully created with key \f(CW\*(C`Wall\*(C'\fR |
| 543 |
\&\- the only thing is, when they are retrieved from the database they |
| 544 |
\&\fIseem\fR to have the same value, namely \f(CW\*(C`Larry\*(C'\fR. The problem is caused |
| 545 |
by the way that the associative array interface works. Basically, when |
| 546 |
the associative array interface is used to fetch the value associated |
| 547 |
with a given key, it will only ever retrieve the first value. |
| 548 |
.PP |
| 549 |
Although it may not be immediately obvious from the code above, the |
| 550 |
associative array interface can be used to write values with duplicate |
| 551 |
keys, but it cannot be used to read them back from the database. |
| 552 |
.PP |
| 553 |
The way to get around this problem is to use the Berkeley DB API method |
| 554 |
called \f(CW\*(C`seq\*(C'\fR. This method allows sequential access to key/value |
| 555 |
pairs. See "THE API INTERFACE" for details of both the \f(CW\*(C`seq\*(C'\fR method |
| 556 |
and the API in general. |
| 557 |
.PP |
| 558 |
Here is the script above rewritten using the \f(CW\*(C`seq\*(C'\fR API method. |
| 559 |
.PP |
| 560 |
.Vb 3 |
| 561 |
\& use warnings ; |
| 562 |
\& use strict ; |
| 563 |
\& use DB_File ; |
| 564 |
\& |
| 565 |
\& my ($filename, $x, %h, $status, $key, $value) ; |
| 566 |
\& |
| 567 |
\& $filename = "tree" ; |
| 568 |
\& unlink $filename ; |
| 569 |
\& |
| 570 |
\& # Enable duplicate records |
| 571 |
\& $DB_BTREE\->{\*(Aqflags\*(Aq} = R_DUP ; |
| 572 |
\& |
| 573 |
\& $x = tie %h, "DB_File", $filename, O_RDWR|O_CREAT, 0666, $DB_BTREE |
| 574 |
\& or die "Cannot open $filename: $!\en"; |
| 575 |
\& |
| 576 |
\& # Add some key/value pairs to the file |
| 577 |
\& $h{\*(AqWall\*(Aq} = \*(AqLarry\*(Aq ; |
| 578 |
\& $h{\*(AqWall\*(Aq} = \*(AqBrick\*(Aq ; # Note the duplicate key |
| 579 |
\& $h{\*(AqWall\*(Aq} = \*(AqBrick\*(Aq ; # Note the duplicate key and value |
| 580 |
\& $h{\*(AqSmith\*(Aq} = \*(AqJohn\*(Aq ; |
| 581 |
\& $h{\*(Aqmouse\*(Aq} = \*(Aqmickey\*(Aq ; |
| 582 |
\& |
| 583 |
\& # iterate through the btree using seq |
| 584 |
\& # and print each key/value pair. |
| 585 |
\& $key = $value = 0 ; |
| 586 |
\& for ($status = $x\->seq($key, $value, R_FIRST) ; |
| 587 |
\& $status == 0 ; |
| 588 |
\& $status = $x\->seq($key, $value, R_NEXT) ) |
| 589 |
\& { print "$key \-> $value\en" } |
| 590 |
\& |
| 591 |
\& undef $x ; |
| 592 |
\& untie %h ; |
| 593 |
.Ve |
| 594 |
.PP |
| 595 |
that prints: |
| 596 |
.PP |
| 597 |
.Vb 5 |
| 598 |
\& Smith \-> John |
| 599 |
\& Wall \-> Brick |
| 600 |
\& Wall \-> Brick |
| 601 |
\& Wall \-> Larry |
| 602 |
\& mouse \-> mickey |
| 603 |
.Ve |
| 604 |
.PP |
| 605 |
This time we have got all the key/value pairs, including the multiple |
| 606 |
values associated with the key \f(CW\*(C`Wall\*(C'\fR. |
| 607 |
.PP |
| 608 |
To make life easier when dealing with duplicate keys, \fBDB_File\fR comes with |
| 609 |
a few utility methods. |
| 610 |
.SS "The \fBget_dup()\fP Method" |
| 611 |
.IX Subsection "The get_dup() Method" |
| 612 |
The \f(CW\*(C`get_dup\*(C'\fR method assists in |
| 613 |
reading duplicate values from BTREE databases. The method can take the |
| 614 |
following forms: |
| 615 |
.PP |
| 616 |
.Vb 3 |
| 617 |
\& $count = $x\->get_dup($key) ; |
| 618 |
\& @list = $x\->get_dup($key) ; |
| 619 |
\& %list = $x\->get_dup($key, 1) ; |
| 620 |
.Ve |
| 621 |
.PP |
| 622 |
In a scalar context the method returns the number of values associated |
| 623 |
with the key, \f(CW$key\fR. |
| 624 |
.PP |
| 625 |
In list context, it returns all the values which match \f(CW$key\fR. Note |
| 626 |
that the values will be returned in an apparently random order. |
| 627 |
.PP |
| 628 |
In list context, if the second parameter is present and evaluates |
| 629 |
TRUE, the method returns an associative array. The keys of the |
| 630 |
associative array correspond to the values that matched in the BTREE |
| 631 |
and the values of the array are a count of the number of times that |
| 632 |
particular value occurred in the BTREE. |
| 633 |
.PP |
| 634 |
So assuming the database created above, we can use \f(CW\*(C`get_dup\*(C'\fR like |
| 635 |
this: |
| 636 |
.PP |
| 637 |
.Vb 3 |
| 638 |
\& use warnings ; |
| 639 |
\& use strict ; |
| 640 |
\& use DB_File ; |
| 641 |
\& |
| 642 |
\& my ($filename, $x, %h) ; |
| 643 |
\& |
| 644 |
\& $filename = "tree" ; |
| 645 |
\& |
| 646 |
\& # Enable duplicate records |
| 647 |
\& $DB_BTREE\->{\*(Aqflags\*(Aq} = R_DUP ; |
| 648 |
\& |
| 649 |
\& $x = tie %h, "DB_File", $filename, O_RDWR|O_CREAT, 0666, $DB_BTREE |
| 650 |
\& or die "Cannot open $filename: $!\en"; |
| 651 |
\& |
| 652 |
\& my $cnt = $x\->get_dup("Wall") ; |
| 653 |
\& print "Wall occurred $cnt times\en" ; |
| 654 |
\& |
| 655 |
\& my %hash = $x\->get_dup("Wall", 1) ; |
| 656 |
\& print "Larry is there\en" if $hash{\*(AqLarry\*(Aq} ; |
| 657 |
\& print "There are $hash{\*(AqBrick\*(Aq} Brick Walls\en" ; |
| 658 |
\& |
| 659 |
\& my @list = sort $x\->get_dup("Wall") ; |
| 660 |
\& print "Wall => [@list]\en" ; |
| 661 |
\& |
| 662 |
\& @list = $x\->get_dup("Smith") ; |
| 663 |
\& print "Smith => [@list]\en" ; |
| 664 |
\& |
| 665 |
\& @list = $x\->get_dup("Dog") ; |
| 666 |
\& print "Dog => [@list]\en" ; |
| 667 |
.Ve |
| 668 |
.PP |
| 669 |
and it will print: |
| 670 |
.PP |
| 671 |
.Vb 6 |
| 672 |
\& Wall occurred 3 times |
| 673 |
\& Larry is there |
| 674 |
\& There are 2 Brick Walls |
| 675 |
\& Wall => [Brick Brick Larry] |
| 676 |
\& Smith => [John] |
| 677 |
\& Dog => [] |
| 678 |
.Ve |
| 679 |
.SS "The \fBfind_dup()\fP Method" |
| 680 |
.IX Subsection "The find_dup() Method" |
| 681 |
.Vb 1 |
| 682 |
\& $status = $X\->find_dup($key, $value) ; |
| 683 |
.Ve |
| 684 |
.PP |
| 685 |
This method checks for the existence of a specific key/value pair. If the |
| 686 |
pair exists, the cursor is left pointing to the pair and the method |
| 687 |
returns 0. Otherwise the method returns a non-zero value. |
| 688 |
.PP |
| 689 |
Assuming the database from the previous example: |
| 690 |
.PP |
| 691 |
.Vb 3 |
| 692 |
\& use warnings ; |
| 693 |
\& use strict ; |
| 694 |
\& use DB_File ; |
| 695 |
\& |
| 696 |
\& my ($filename, $x, %h, $found) ; |
| 697 |
\& |
| 698 |
\& $filename = "tree" ; |
| 699 |
\& |
| 700 |
\& # Enable duplicate records |
| 701 |
\& $DB_BTREE\->{\*(Aqflags\*(Aq} = R_DUP ; |
| 702 |
\& |
| 703 |
\& $x = tie %h, "DB_File", $filename, O_RDWR|O_CREAT, 0666, $DB_BTREE |
| 704 |
\& or die "Cannot open $filename: $!\en"; |
| 705 |
\& |
| 706 |
\& $found = ( $x\->find_dup("Wall", "Larry") == 0 ? "" : "not") ; |
| 707 |
\& print "Larry Wall is $found there\en" ; |
| 708 |
\& |
| 709 |
\& $found = ( $x\->find_dup("Wall", "Harry") == 0 ? "" : "not") ; |
| 710 |
\& print "Harry Wall is $found there\en" ; |
| 711 |
\& |
| 712 |
\& undef $x ; |
| 713 |
\& untie %h ; |
| 714 |
.Ve |
| 715 |
.PP |
| 716 |
prints this |
| 717 |
.PP |
| 718 |
.Vb 2 |
| 719 |
\& Larry Wall is there |
| 720 |
\& Harry Wall is not there |
| 721 |
.Ve |
| 722 |
.SS "The \fBdel_dup()\fP Method" |
| 723 |
.IX Subsection "The del_dup() Method" |
| 724 |
.Vb 1 |
| 725 |
\& $status = $X\->del_dup($key, $value) ; |
| 726 |
.Ve |
| 727 |
.PP |
| 728 |
This method deletes a specific key/value pair. It returns |
| 729 |
0 if they exist and have been deleted successfully. |
| 730 |
Otherwise the method returns a non-zero value. |
| 731 |
.PP |
| 732 |
Again assuming the existence of the \f(CW\*(C`tree\*(C'\fR database |
| 733 |
.PP |
| 734 |
.Vb 3 |
| 735 |
\& use warnings ; |
| 736 |
\& use strict ; |
| 737 |
\& use DB_File ; |
| 738 |
\& |
| 739 |
\& my ($filename, $x, %h, $found) ; |
| 740 |
\& |
| 741 |
\& $filename = "tree" ; |
| 742 |
\& |
| 743 |
\& # Enable duplicate records |
| 744 |
\& $DB_BTREE\->{\*(Aqflags\*(Aq} = R_DUP ; |
| 745 |
\& |
| 746 |
\& $x = tie %h, "DB_File", $filename, O_RDWR|O_CREAT, 0666, $DB_BTREE |
| 747 |
\& or die "Cannot open $filename: $!\en"; |
| 748 |
\& |
| 749 |
\& $x\->del_dup("Wall", "Larry") ; |
| 750 |
\& |
| 751 |
\& $found = ( $x\->find_dup("Wall", "Larry") == 0 ? "" : "not") ; |
| 752 |
\& print "Larry Wall is $found there\en" ; |
| 753 |
\& |
| 754 |
\& undef $x ; |
| 755 |
\& untie %h ; |
| 756 |
.Ve |
| 757 |
.PP |
| 758 |
prints this |
| 759 |
.PP |
| 760 |
.Vb 1 |
| 761 |
\& Larry Wall is not there |
| 762 |
.Ve |
| 763 |
.SS "Matching Partial Keys" |
| 764 |
.IX Subsection "Matching Partial Keys" |
| 765 |
The BTREE interface has a feature which allows partial keys to be |
| 766 |
matched. This functionality is \fIonly\fR available when the \f(CW\*(C`seq\*(C'\fR method |
| 767 |
is used along with the R_CURSOR flag. |
| 768 |
.PP |
| 769 |
.Vb 1 |
| 770 |
\& $x\->seq($key, $value, R_CURSOR) ; |
| 771 |
.Ve |
| 772 |
.PP |
| 773 |
Here is the relevant quote from the dbopen man page where it defines |
| 774 |
the use of the R_CURSOR flag with seq: |
| 775 |
.PP |
| 776 |
.Vb 4 |
| 777 |
\& Note, for the DB_BTREE access method, the returned key is not |
| 778 |
\& necessarily an exact match for the specified key. The returned key |
| 779 |
\& is the smallest key greater than or equal to the specified key, |
| 780 |
\& permitting partial key matches and range searches. |
| 781 |
.Ve |
| 782 |
.PP |
| 783 |
In the example script below, the \f(CW\*(C`match\*(C'\fR sub uses this feature to find |
| 784 |
and print the first matching key/value pair given a partial key. |
| 785 |
.PP |
| 786 |
.Vb 4 |
| 787 |
\& use warnings ; |
| 788 |
\& use strict ; |
| 789 |
\& use DB_File ; |
| 790 |
\& use Fcntl ; |
| 791 |
\& |
| 792 |
\& my ($filename, $x, %h, $st, $key, $value) ; |
| 793 |
\& |
| 794 |
\& sub match |
| 795 |
\& { |
| 796 |
\& my $key = shift ; |
| 797 |
\& my $value = 0; |
| 798 |
\& my $orig_key = $key ; |
| 799 |
\& $x\->seq($key, $value, R_CURSOR) ; |
| 800 |
\& print "$orig_key\et\-> $key\et\-> $value\en" ; |
| 801 |
\& } |
| 802 |
\& |
| 803 |
\& $filename = "tree" ; |
| 804 |
\& unlink $filename ; |
| 805 |
\& |
| 806 |
\& $x = tie %h, "DB_File", $filename, O_RDWR|O_CREAT, 0666, $DB_BTREE |
| 807 |
\& or die "Cannot open $filename: $!\en"; |
| 808 |
\& |
| 809 |
\& # Add some key/value pairs to the file |
| 810 |
\& $h{\*(Aqmouse\*(Aq} = \*(Aqmickey\*(Aq ; |
| 811 |
\& $h{\*(AqWall\*(Aq} = \*(AqLarry\*(Aq ; |
| 812 |
\& $h{\*(AqWalls\*(Aq} = \*(AqBrick\*(Aq ; |
| 813 |
\& $h{\*(AqSmith\*(Aq} = \*(AqJohn\*(Aq ; |
| 814 |
\& |
| 815 |
\& |
| 816 |
\& $key = $value = 0 ; |
| 817 |
\& print "IN ORDER\en" ; |
| 818 |
\& for ($st = $x\->seq($key, $value, R_FIRST) ; |
| 819 |
\& $st == 0 ; |
| 820 |
\& $st = $x\->seq($key, $value, R_NEXT) ) |
| 821 |
\& |
| 822 |
\& { print "$key \-> $value\en" } |
| 823 |
\& |
| 824 |
\& print "\enPARTIAL MATCH\en" ; |
| 825 |
\& |
| 826 |
\& match "Wa" ; |
| 827 |
\& match "A" ; |
| 828 |
\& match "a" ; |
| 829 |
\& |
| 830 |
\& undef $x ; |
| 831 |
\& untie %h ; |
| 832 |
.Ve |
| 833 |
.PP |
| 834 |
Here is the output: |
| 835 |
.PP |
| 836 |
.Vb 5 |
| 837 |
\& IN ORDER |
| 838 |
\& Smith \-> John |
| 839 |
\& Wall \-> Larry |
| 840 |
\& Walls \-> Brick |
| 841 |
\& mouse \-> mickey |
| 842 |
\& |
| 843 |
\& PARTIAL MATCH |
| 844 |
\& Wa \-> Wall \-> Larry |
| 845 |
\& A \-> Smith \-> John |
| 846 |
\& a \-> mouse \-> mickey |
| 847 |
.Ve |
| 848 |
.SH DB_RECNO |
| 849 |
.IX Header "DB_RECNO" |
| 850 |
DB_RECNO provides an interface to flat text files. Both variable and |
| 851 |
fixed length records are supported. |
| 852 |
.PP |
| 853 |
In order to make RECNO more compatible with Perl, the array offset for |
| 854 |
all RECNO arrays begins at 0 rather than 1 as in Berkeley DB. |
| 855 |
.PP |
| 856 |
As with normal Perl arrays, a RECNO array can be accessed using |
| 857 |
negative indexes. The index \-1 refers to the last element of the array, |
| 858 |
\&\-2 the second last, and so on. Attempting to access an element before |
| 859 |
the start of the array will raise a fatal run-time error. |
| 860 |
.SS "The 'bval' Option" |
| 861 |
.IX Subsection "The 'bval' Option" |
| 862 |
The operation of the bval option warrants some discussion. Here is the |
| 863 |
definition of bval from the Berkeley DB 1.85 recno manual page: |
| 864 |
.PP |
| 865 |
.Vb 6 |
| 866 |
\& The delimiting byte to be used to mark the end of a |
| 867 |
\& record for variable\-length records, and the pad charac\- |
| 868 |
\& ter for fixed\-length records. If no value is speci\- |
| 869 |
\& fied, newlines (\`\`\en\*(Aq\*(Aq) are used to mark the end of |
| 870 |
\& variable\-length records and fixed\-length records are |
| 871 |
\& padded with spaces. |
| 872 |
.Ve |
| 873 |
.PP |
| 874 |
The second sentence is wrong. In actual fact bval will only default to |
| 875 |
\&\f(CW"\en"\fR when the openinfo parameter in dbopen is NULL. If a non-NULL |
| 876 |
openinfo parameter is used at all, the value that happens to be in bval |
| 877 |
will be used. That means you always have to specify bval when making |
| 878 |
use of any of the options in the openinfo parameter. This documentation |
| 879 |
error will be fixed in the next release of Berkeley DB. |
| 880 |
.PP |
| 881 |
That clarifies the situation with regards Berkeley DB itself. What |
| 882 |
about \fBDB_File\fR? Well, the behavior defined in the quote above is |
| 883 |
quite useful, so \fBDB_File\fR conforms to it. |
| 884 |
.PP |
| 885 |
That means that you can specify other options (e.g. cachesize) and |
| 886 |
still have bval default to \f(CW"\en"\fR for variable length records, and |
| 887 |
space for fixed length records. |
| 888 |
.PP |
| 889 |
Also note that the bval option only allows you to specify a single byte |
| 890 |
as a delimiter. |
| 891 |
.SS "A Simple Example" |
| 892 |
.IX Subsection "A Simple Example" |
| 893 |
Here is a simple example that uses RECNO (if you are using a version |
| 894 |
of Perl earlier than 5.004_57 this example won't work \-\- see |
| 895 |
"Extra RECNO Methods" for a workaround). |
| 896 |
.PP |
| 897 |
.Vb 3 |
| 898 |
\& use warnings ; |
| 899 |
\& use strict ; |
| 900 |
\& use DB_File ; |
| 901 |
\& |
| 902 |
\& my $filename = "text" ; |
| 903 |
\& unlink $filename ; |
| 904 |
\& |
| 905 |
\& my @h ; |
| 906 |
\& tie @h, "DB_File", $filename, O_RDWR|O_CREAT, 0666, $DB_RECNO |
| 907 |
\& or die "Cannot open file \*(Aqtext\*(Aq: $!\en" ; |
| 908 |
\& |
| 909 |
\& # Add a few key/value pairs to the file |
| 910 |
\& $h[0] = "orange" ; |
| 911 |
\& $h[1] = "blue" ; |
| 912 |
\& $h[2] = "yellow" ; |
| 913 |
\& |
| 914 |
\& push @h, "green", "black" ; |
| 915 |
\& |
| 916 |
\& my $elements = scalar @h ; |
| 917 |
\& print "The array contains $elements entries\en" ; |
| 918 |
\& |
| 919 |
\& my $last = pop @h ; |
| 920 |
\& print "popped $last\en" ; |
| 921 |
\& |
| 922 |
\& unshift @h, "white" ; |
| 923 |
\& my $first = shift @h ; |
| 924 |
\& print "shifted $first\en" ; |
| 925 |
\& |
| 926 |
\& # Check for existence of a key |
| 927 |
\& print "Element 1 Exists with value $h[1]\en" if $h[1] ; |
| 928 |
\& |
| 929 |
\& # use a negative index |
| 930 |
\& print "The last element is $h[\-1]\en" ; |
| 931 |
\& print "The 2nd last element is $h[\-2]\en" ; |
| 932 |
\& |
| 933 |
\& untie @h ; |
| 934 |
.Ve |
| 935 |
.PP |
| 936 |
Here is the output from the script: |
| 937 |
.PP |
| 938 |
.Vb 6 |
| 939 |
\& The array contains 5 entries |
| 940 |
\& popped black |
| 941 |
\& shifted white |
| 942 |
\& Element 1 Exists with value blue |
| 943 |
\& The last element is green |
| 944 |
\& The 2nd last element is yellow |
| 945 |
.Ve |
| 946 |
.SS "Extra RECNO Methods" |
| 947 |
.IX Subsection "Extra RECNO Methods" |
| 948 |
If you are using a version of Perl earlier than 5.004_57, the tied |
| 949 |
array interface is quite limited. In the example script above |
| 950 |
\&\f(CW\*(C`push\*(C'\fR, \f(CW\*(C`pop\*(C'\fR, \f(CW\*(C`shift\*(C'\fR, \f(CW\*(C`unshift\*(C'\fR |
| 951 |
or determining the array length will not work with a tied array. |
| 952 |
.PP |
| 953 |
To make the interface more useful for older versions of Perl, a number |
| 954 |
of methods are supplied with \fBDB_File\fR to simulate the missing array |
| 955 |
operations. All these methods are accessed via the object returned from |
| 956 |
the tie call. |
| 957 |
.PP |
| 958 |
Here are the methods: |
| 959 |
.ie n .IP "\fR\fB$X\fR\fB\->push(list) ;\fR" 5 |
| 960 |
.el .IP "\fR\f(CB$X\fR\fB\->push(list) ;\fR" 5 |
| 961 |
.IX Item "$X->push(list) ;" |
| 962 |
Pushes the elements of \f(CW\*(C`list\*(C'\fR to the end of the array. |
| 963 |
.ie n .IP "\fR\fB$value\fR\fB = \fR\fB$X\fR\fB\->pop ;\fR" 5 |
| 964 |
.el .IP "\fR\f(CB$value\fR\fB = \fR\f(CB$X\fR\fB\->pop ;\fR" 5 |
| 965 |
.IX Item "$value = $X->pop ;" |
| 966 |
Removes and returns the last element of the array. |
| 967 |
.ie n .IP \fR\fB$X\fR\fB\->shift\fR 5 |
| 968 |
.el .IP \fR\f(CB$X\fR\fB\->shift\fR 5 |
| 969 |
.IX Item "$X->shift" |
| 970 |
Removes and returns the first element of the array. |
| 971 |
.ie n .IP "\fR\fB$X\fR\fB\->unshift(list) ;\fR" 5 |
| 972 |
.el .IP "\fR\f(CB$X\fR\fB\->unshift(list) ;\fR" 5 |
| 973 |
.IX Item "$X->unshift(list) ;" |
| 974 |
Pushes the elements of \f(CW\*(C`list\*(C'\fR to the start of the array. |
| 975 |
.ie n .IP \fR\fB$X\fR\fB\->length\fR 5 |
| 976 |
.el .IP \fR\f(CB$X\fR\fB\->length\fR 5 |
| 977 |
.IX Item "$X->length" |
| 978 |
Returns the number of elements in the array. |
| 979 |
.ie n .IP "\fR\fB$X\fR\fB\->splice(offset, length, elements);\fR" 5 |
| 980 |
.el .IP "\fR\f(CB$X\fR\fB\->splice(offset, length, elements);\fR" 5 |
| 981 |
.IX Item "$X->splice(offset, length, elements);" |
| 982 |
Returns a splice of the array. |
| 983 |
.SS "Another Example" |
| 984 |
.IX Subsection "Another Example" |
| 985 |
Here is a more complete example that makes use of some of the methods |
| 986 |
described above. It also makes use of the API interface directly (see |
| 987 |
"THE API INTERFACE"). |
| 988 |
.PP |
| 989 |
.Vb 5 |
| 990 |
\& use warnings ; |
| 991 |
\& use strict ; |
| 992 |
\& my (@h, $H, $file, $i) ; |
| 993 |
\& use DB_File ; |
| 994 |
\& use Fcntl ; |
| 995 |
\& |
| 996 |
\& $file = "text" ; |
| 997 |
\& |
| 998 |
\& unlink $file ; |
| 999 |
\& |
| 1000 |
\& $H = tie @h, "DB_File", $file, O_RDWR|O_CREAT, 0666, $DB_RECNO |
| 1001 |
\& or die "Cannot open file $file: $!\en" ; |
| 1002 |
\& |
| 1003 |
\& # first create a text file to play with |
| 1004 |
\& $h[0] = "zero" ; |
| 1005 |
\& $h[1] = "one" ; |
| 1006 |
\& $h[2] = "two" ; |
| 1007 |
\& $h[3] = "three" ; |
| 1008 |
\& $h[4] = "four" ; |
| 1009 |
\& |
| 1010 |
\& |
| 1011 |
\& # Print the records in order. |
| 1012 |
\& # |
| 1013 |
\& # The length method is needed here because evaluating a tied |
| 1014 |
\& # array in a scalar context does not return the number of |
| 1015 |
\& # elements in the array. |
| 1016 |
\& |
| 1017 |
\& print "\enORIGINAL\en" ; |
| 1018 |
\& foreach $i (0 .. $H\->length \- 1) { |
| 1019 |
\& print "$i: $h[$i]\en" ; |
| 1020 |
\& } |
| 1021 |
\& |
| 1022 |
\& # use the push & pop methods |
| 1023 |
\& $a = $H\->pop ; |
| 1024 |
\& $H\->push("last") ; |
| 1025 |
\& print "\enThe last record was [$a]\en" ; |
| 1026 |
\& |
| 1027 |
\& # and the shift & unshift methods |
| 1028 |
\& $a = $H\->shift ; |
| 1029 |
\& $H\->unshift("first") ; |
| 1030 |
\& print "The first record was [$a]\en" ; |
| 1031 |
\& |
| 1032 |
\& # Use the API to add a new record after record 2. |
| 1033 |
\& $i = 2 ; |
| 1034 |
\& $H\->put($i, "Newbie", R_IAFTER) ; |
| 1035 |
\& |
| 1036 |
\& # and a new record before record 1. |
| 1037 |
\& $i = 1 ; |
| 1038 |
\& $H\->put($i, "New One", R_IBEFORE) ; |
| 1039 |
\& |
| 1040 |
\& # delete record 3 |
| 1041 |
\& $H\->del(3) ; |
| 1042 |
\& |
| 1043 |
\& # now print the records in reverse order |
| 1044 |
\& print "\enREVERSE\en" ; |
| 1045 |
\& for ($i = $H\->length \- 1 ; $i >= 0 ; \-\- $i) |
| 1046 |
\& { print "$i: $h[$i]\en" } |
| 1047 |
\& |
| 1048 |
\& # same again, but use the API functions instead |
| 1049 |
\& print "\enREVERSE again\en" ; |
| 1050 |
\& my ($s, $k, $v) = (0, 0, 0) ; |
| 1051 |
\& for ($s = $H\->seq($k, $v, R_LAST) ; |
| 1052 |
\& $s == 0 ; |
| 1053 |
\& $s = $H\->seq($k, $v, R_PREV)) |
| 1054 |
\& { print "$k: $v\en" } |
| 1055 |
\& |
| 1056 |
\& undef $H ; |
| 1057 |
\& untie @h ; |
| 1058 |
.Ve |
| 1059 |
.PP |
| 1060 |
and this is what it outputs: |
| 1061 |
.PP |
| 1062 |
.Vb 6 |
| 1063 |
\& ORIGINAL |
| 1064 |
\& 0: zero |
| 1065 |
\& 1: one |
| 1066 |
\& 2: two |
| 1067 |
\& 3: three |
| 1068 |
\& 4: four |
| 1069 |
\& |
| 1070 |
\& The last record was [four] |
| 1071 |
\& The first record was [zero] |
| 1072 |
\& |
| 1073 |
\& REVERSE |
| 1074 |
\& 5: last |
| 1075 |
\& 4: three |
| 1076 |
\& 3: Newbie |
| 1077 |
\& 2: one |
| 1078 |
\& 1: New One |
| 1079 |
\& 0: first |
| 1080 |
\& |
| 1081 |
\& REVERSE again |
| 1082 |
\& 5: last |
| 1083 |
\& 4: three |
| 1084 |
\& 3: Newbie |
| 1085 |
\& 2: one |
| 1086 |
\& 1: New One |
| 1087 |
\& 0: first |
| 1088 |
.Ve |
| 1089 |
.PP |
| 1090 |
Notes: |
| 1091 |
.IP 1. 5 |
| 1092 |
Rather than iterating through the array, \f(CW@h\fR like this: |
| 1093 |
.Sp |
| 1094 |
.Vb 1 |
| 1095 |
\& foreach $i (@h) |
| 1096 |
.Ve |
| 1097 |
.Sp |
| 1098 |
it is necessary to use either this: |
| 1099 |
.Sp |
| 1100 |
.Vb 1 |
| 1101 |
\& foreach $i (0 .. $H\->length \- 1) |
| 1102 |
.Ve |
| 1103 |
.Sp |
| 1104 |
or this: |
| 1105 |
.Sp |
| 1106 |
.Vb 3 |
| 1107 |
\& for ($a = $H\->get($k, $v, R_FIRST) ; |
| 1108 |
\& $a == 0 ; |
| 1109 |
\& $a = $H\->get($k, $v, R_NEXT) ) |
| 1110 |
.Ve |
| 1111 |
.IP 2. 5 |
| 1112 |
Notice that both times the \f(CW\*(C`put\*(C'\fR method was used the record index was |
| 1113 |
specified using a variable, \f(CW$i\fR, rather than the literal value |
| 1114 |
itself. This is because \f(CW\*(C`put\*(C'\fR will return the record number of the |
| 1115 |
inserted line via that parameter. |
| 1116 |
.SH "THE API INTERFACE" |
| 1117 |
.IX Header "THE API INTERFACE" |
| 1118 |
As well as accessing Berkeley DB using a tied hash or array, it is also |
| 1119 |
possible to make direct use of most of the API functions defined in the |
| 1120 |
Berkeley DB documentation. |
| 1121 |
.PP |
| 1122 |
To do this you need to store a copy of the object returned from the tie. |
| 1123 |
.PP |
| 1124 |
.Vb 1 |
| 1125 |
\& $db = tie %hash, "DB_File", "filename" ; |
| 1126 |
.Ve |
| 1127 |
.PP |
| 1128 |
Once you have done that, you can access the Berkeley DB API functions |
| 1129 |
as \fBDB_File\fR methods directly like this: |
| 1130 |
.PP |
| 1131 |
.Vb 1 |
| 1132 |
\& $db\->put($key, $value, R_NOOVERWRITE) ; |
| 1133 |
.Ve |
| 1134 |
.PP |
| 1135 |
\&\fBImportant:\fR If you have saved a copy of the object returned from |
| 1136 |
\&\f(CW\*(C`tie\*(C'\fR, the underlying database file will \fInot\fR be closed until both |
| 1137 |
the tied variable is untied and all copies of the saved object are |
| 1138 |
destroyed. |
| 1139 |
.PP |
| 1140 |
.Vb 6 |
| 1141 |
\& use DB_File ; |
| 1142 |
\& $db = tie %hash, "DB_File", "filename" |
| 1143 |
\& or die "Cannot tie filename: $!" ; |
| 1144 |
\& ... |
| 1145 |
\& undef $db ; |
| 1146 |
\& untie %hash ; |
| 1147 |
.Ve |
| 1148 |
.PP |
| 1149 |
See "The \fBuntie()\fR Gotcha" for more details. |
| 1150 |
.PP |
| 1151 |
All the functions defined in dbopen are available except for |
| 1152 |
\&\fBclose()\fR and \fBdbopen()\fR itself. The \fBDB_File\fR method interface to the |
| 1153 |
supported functions have been implemented to mirror the way Berkeley DB |
| 1154 |
works whenever possible. In particular note that: |
| 1155 |
.IP \(bu 5 |
| 1156 |
The methods return a status value. All return 0 on success. |
| 1157 |
All return \-1 to signify an error and set \f(CW$!\fR to the exact |
| 1158 |
error code. The return code 1 generally (but not always) means that the |
| 1159 |
key specified did not exist in the database. |
| 1160 |
.Sp |
| 1161 |
Other return codes are defined. See below and in the Berkeley DB |
| 1162 |
documentation for details. The Berkeley DB documentation should be used |
| 1163 |
as the definitive source. |
| 1164 |
.IP \(bu 5 |
| 1165 |
Whenever a Berkeley DB function returns data via one of its parameters, |
| 1166 |
the equivalent \fBDB_File\fR method does exactly the same. |
| 1167 |
.IP \(bu 5 |
| 1168 |
If you are careful, it is possible to mix API calls with the tied |
| 1169 |
hash/array interface in the same piece of code. Although only a few of |
| 1170 |
the methods used to implement the tied interface currently make use of |
| 1171 |
the cursor, you should always assume that the cursor has been changed |
| 1172 |
any time the tied hash/array interface is used. As an example, this |
| 1173 |
code will probably not do what you expect: |
| 1174 |
.Sp |
| 1175 |
.Vb 2 |
| 1176 |
\& $X = tie %x, \*(AqDB_File\*(Aq, $filename, O_RDWR|O_CREAT, 0777, $DB_BTREE |
| 1177 |
\& or die "Cannot tie $filename: $!" ; |
| 1178 |
\& |
| 1179 |
\& # Get the first key/value pair and set the cursor |
| 1180 |
\& $X\->seq($key, $value, R_FIRST) ; |
| 1181 |
\& |
| 1182 |
\& # this line will modify the cursor |
| 1183 |
\& $count = scalar keys %x ; |
| 1184 |
\& |
| 1185 |
\& # Get the second key/value pair. |
| 1186 |
\& # oops, it didn\*(Aqt, it got the last key/value pair! |
| 1187 |
\& $X\->seq($key, $value, R_NEXT) ; |
| 1188 |
.Ve |
| 1189 |
.Sp |
| 1190 |
The code above can be rearranged to get around the problem, like this: |
| 1191 |
.Sp |
| 1192 |
.Vb 2 |
| 1193 |
\& $X = tie %x, \*(AqDB_File\*(Aq, $filename, O_RDWR|O_CREAT, 0777, $DB_BTREE |
| 1194 |
\& or die "Cannot tie $filename: $!" ; |
| 1195 |
\& |
| 1196 |
\& # this line will modify the cursor |
| 1197 |
\& $count = scalar keys %x ; |
| 1198 |
\& |
| 1199 |
\& # Get the first key/value pair and set the cursor |
| 1200 |
\& $X\->seq($key, $value, R_FIRST) ; |
| 1201 |
\& |
| 1202 |
\& # Get the second key/value pair. |
| 1203 |
\& # worked this time. |
| 1204 |
\& $X\->seq($key, $value, R_NEXT) ; |
| 1205 |
.Ve |
| 1206 |
.PP |
| 1207 |
All the constants defined in dbopen for use in the flags parameters |
| 1208 |
in the methods defined below are also available. Refer to the Berkeley |
| 1209 |
DB documentation for the precise meaning of the flags values. |
| 1210 |
.PP |
| 1211 |
Below is a list of the methods available. |
| 1212 |
.ie n .IP "\fR\fB$status\fR\fB = \fR\fB$X\fR\fB\->get($key, \fR\fB$value\fR\fB [, \fR\fB$flags\fR\fB]) ;\fR" 5 |
| 1213 |
.el .IP "\fR\f(CB$status\fR\fB = \fR\f(CB$X\fR\fB\->get($key, \fR\f(CB$value\fR\fB [, \fR\f(CB$flags\fR\fB]) ;\fR" 5 |
| 1214 |
.IX Item "$status = $X->get($key, $value [, $flags]) ;" |
| 1215 |
Given a key (\f(CW$key\fR) this method reads the value associated with it |
| 1216 |
from the database. The value read from the database is returned in the |
| 1217 |
\&\f(CW$value\fR parameter. |
| 1218 |
.Sp |
| 1219 |
If the key does not exist the method returns 1. |
| 1220 |
.Sp |
| 1221 |
No flags are currently defined for this method. |
| 1222 |
.ie n .IP "\fR\fB$status\fR\fB = \fR\fB$X\fR\fB\->put($key, \fR\fB$value\fR\fB [, \fR\fB$flags\fR\fB]) ;\fR" 5 |
| 1223 |
.el .IP "\fR\f(CB$status\fR\fB = \fR\f(CB$X\fR\fB\->put($key, \fR\f(CB$value\fR\fB [, \fR\f(CB$flags\fR\fB]) ;\fR" 5 |
| 1224 |
.IX Item "$status = $X->put($key, $value [, $flags]) ;" |
| 1225 |
Stores the key/value pair in the database. |
| 1226 |
.Sp |
| 1227 |
If you use either the R_IAFTER or R_IBEFORE flags, the \f(CW$key\fR parameter |
| 1228 |
will have the record number of the inserted key/value pair set. |
| 1229 |
.Sp |
| 1230 |
Valid flags are R_CURSOR, R_IAFTER, R_IBEFORE, R_NOOVERWRITE and |
| 1231 |
R_SETCURSOR. |
| 1232 |
.ie n .IP "\fR\fB$status\fR\fB = \fR\fB$X\fR\fB\->del($key [, \fR\fB$flags\fR\fB]) ;\fR" 5 |
| 1233 |
.el .IP "\fR\f(CB$status\fR\fB = \fR\f(CB$X\fR\fB\->del($key [, \fR\f(CB$flags\fR\fB]) ;\fR" 5 |
| 1234 |
.IX Item "$status = $X->del($key [, $flags]) ;" |
| 1235 |
Removes all key/value pairs with key \f(CW$key\fR from the database. |
| 1236 |
.Sp |
| 1237 |
A return code of 1 means that the requested key was not in the |
| 1238 |
database. |
| 1239 |
.Sp |
| 1240 |
R_CURSOR is the only valid flag at present. |
| 1241 |
.ie n .IP "\fR\fB$status\fR\fB = \fR\fB$X\fR\fB\->fd ;\fR" 5 |
| 1242 |
.el .IP "\fR\f(CB$status\fR\fB = \fR\f(CB$X\fR\fB\->fd ;\fR" 5 |
| 1243 |
.IX Item "$status = $X->fd ;" |
| 1244 |
Returns the file descriptor for the underlying database. |
| 1245 |
.Sp |
| 1246 |
See "Locking: The Trouble with fd" for an explanation for why you should |
| 1247 |
not use \f(CW\*(C`fd\*(C'\fR to lock your database. |
| 1248 |
.ie n .IP "\fR\fB$status\fR\fB = \fR\fB$X\fR\fB\->seq($key, \fR\fB$value\fR\fB, \fR\fB$flags\fR\fB) ;\fR" 5 |
| 1249 |
.el .IP "\fR\f(CB$status\fR\fB = \fR\f(CB$X\fR\fB\->seq($key, \fR\f(CB$value\fR\fB, \fR\f(CB$flags\fR\fB) ;\fR" 5 |
| 1250 |
.IX Item "$status = $X->seq($key, $value, $flags) ;" |
| 1251 |
This interface allows sequential retrieval from the database. See |
| 1252 |
dbopen for full details. |
| 1253 |
.Sp |
| 1254 |
Both the \f(CW$key\fR and \f(CW$value\fR parameters will be set to the key/value |
| 1255 |
pair read from the database. |
| 1256 |
.Sp |
| 1257 |
The flags parameter is mandatory. The valid flag values are R_CURSOR, |
| 1258 |
R_FIRST, R_LAST, R_NEXT and R_PREV. |
| 1259 |
.ie n .IP "\fR\fB$status\fR\fB = \fR\fB$X\fR\fB\->sync([$flags]) ;\fR" 5 |
| 1260 |
.el .IP "\fR\f(CB$status\fR\fB = \fR\f(CB$X\fR\fB\->sync([$flags]) ;\fR" 5 |
| 1261 |
.IX Item "$status = $X->sync([$flags]) ;" |
| 1262 |
Flushes any cached buffers to disk. |
| 1263 |
.Sp |
| 1264 |
R_RECNOSYNC is the only valid flag at present. |
| 1265 |
.SH "DBM FILTERS" |
| 1266 |
.IX Header "DBM FILTERS" |
| 1267 |
A DBM Filter is a piece of code that is be used when you \fIalways\fR want to |
| 1268 |
make the same transformation to all keys and/or values in a DBM database. |
| 1269 |
An example is when you need to encode your data in UTF\-8 before writing to |
| 1270 |
the database and then decode the UTF\-8 when reading from the database file. |
| 1271 |
.PP |
| 1272 |
There are two ways to use a DBM Filter. |
| 1273 |
.IP 1. 5 |
| 1274 |
Using the low-level API defined below. |
| 1275 |
.IP 2. 5 |
| 1276 |
Using the DBM_Filter module. |
| 1277 |
This module hides the complexity of the API defined below and comes |
| 1278 |
with a number of "canned" filters that cover some of the common use-cases. |
| 1279 |
.PP |
| 1280 |
Use of the DBM_Filter module is recommended. |
| 1281 |
.SS "DBM Filter Low-level API" |
| 1282 |
.IX Subsection "DBM Filter Low-level API" |
| 1283 |
There are four methods associated with DBM Filters. All work identically, |
| 1284 |
and each is used to install (or uninstall) a single DBM Filter. Each |
| 1285 |
expects a single parameter, namely a reference to a sub. The only |
| 1286 |
difference between them is the place that the filter is installed. |
| 1287 |
.PP |
| 1288 |
To summarise: |
| 1289 |
.IP \fBfilter_store_key\fR 5 |
| 1290 |
.IX Item "filter_store_key" |
| 1291 |
If a filter has been installed with this method, it will be invoked |
| 1292 |
every time you write a key to a DBM database. |
| 1293 |
.IP \fBfilter_store_value\fR 5 |
| 1294 |
.IX Item "filter_store_value" |
| 1295 |
If a filter has been installed with this method, it will be invoked |
| 1296 |
every time you write a value to a DBM database. |
| 1297 |
.IP \fBfilter_fetch_key\fR 5 |
| 1298 |
.IX Item "filter_fetch_key" |
| 1299 |
If a filter has been installed with this method, it will be invoked |
| 1300 |
every time you read a key from a DBM database. |
| 1301 |
.IP \fBfilter_fetch_value\fR 5 |
| 1302 |
.IX Item "filter_fetch_value" |
| 1303 |
If a filter has been installed with this method, it will be invoked |
| 1304 |
every time you read a value from a DBM database. |
| 1305 |
.PP |
| 1306 |
You can use any combination of the methods, from none, to all four. |
| 1307 |
.PP |
| 1308 |
All filter methods return the existing filter, if present, or \f(CW\*(C`undef\*(C'\fR |
| 1309 |
in not. |
| 1310 |
.PP |
| 1311 |
To delete a filter pass \f(CW\*(C`undef\*(C'\fR to it. |
| 1312 |
.SS "The Filter" |
| 1313 |
.IX Subsection "The Filter" |
| 1314 |
When each filter is called by Perl, a local copy of \f(CW$_\fR will contain |
| 1315 |
the key or value to be filtered. Filtering is achieved by modifying |
| 1316 |
the contents of \f(CW$_\fR. The return code from the filter is ignored. |
| 1317 |
.SS "An Example \-\- the NULL termination problem." |
| 1318 |
.IX Subsection "An Example -- the NULL termination problem." |
| 1319 |
Consider the following scenario. You have a DBM database |
| 1320 |
that you need to share with a third-party C application. The C application |
| 1321 |
assumes that \fIall\fR keys and values are NULL terminated. Unfortunately |
| 1322 |
when Perl writes to DBM databases it doesn't use NULL termination, so |
| 1323 |
your Perl application will have to manage NULL termination itself. When |
| 1324 |
you write to the database you will have to use something like this: |
| 1325 |
.PP |
| 1326 |
.Vb 1 |
| 1327 |
\& $hash{"$key\e0"} = "$value\e0" ; |
| 1328 |
.Ve |
| 1329 |
.PP |
| 1330 |
Similarly the NULL needs to be taken into account when you are considering |
| 1331 |
the length of existing keys/values. |
| 1332 |
.PP |
| 1333 |
It would be much better if you could ignore the NULL terminations issue |
| 1334 |
in the main application code and have a mechanism that automatically |
| 1335 |
added the terminating NULL to all keys and values whenever you write to |
| 1336 |
the database and have them removed when you read from the database. As I'm |
| 1337 |
sure you have already guessed, this is a problem that DBM Filters can |
| 1338 |
fix very easily. |
| 1339 |
.PP |
| 1340 |
.Vb 3 |
| 1341 |
\& use warnings ; |
| 1342 |
\& use strict ; |
| 1343 |
\& use DB_File ; |
| 1344 |
\& |
| 1345 |
\& my %hash ; |
| 1346 |
\& my $filename = "filt" ; |
| 1347 |
\& unlink $filename ; |
| 1348 |
\& |
| 1349 |
\& my $db = tie %hash, \*(AqDB_File\*(Aq, $filename, O_CREAT|O_RDWR, 0666, $DB_HASH |
| 1350 |
\& or die "Cannot open $filename: $!\en" ; |
| 1351 |
\& |
| 1352 |
\& # Install DBM Filters |
| 1353 |
\& $db\->filter_fetch_key ( sub { s/\e0$// } ) ; |
| 1354 |
\& $db\->filter_store_key ( sub { $_ .= "\e0" } ) ; |
| 1355 |
\& $db\->filter_fetch_value( sub { s/\e0$// } ) ; |
| 1356 |
\& $db\->filter_store_value( sub { $_ .= "\e0" } ) ; |
| 1357 |
\& |
| 1358 |
\& $hash{"abc"} = "def" ; |
| 1359 |
\& my $a = $hash{"ABC"} ; |
| 1360 |
\& # ... |
| 1361 |
\& undef $db ; |
| 1362 |
\& untie %hash ; |
| 1363 |
.Ve |
| 1364 |
.PP |
| 1365 |
Hopefully the contents of each of the filters should be |
| 1366 |
self-explanatory. Both "fetch" filters remove the terminating NULL, |
| 1367 |
and both "store" filters add a terminating NULL. |
| 1368 |
.SS "Another Example \-\- Key is a C int." |
| 1369 |
.IX Subsection "Another Example -- Key is a C int." |
| 1370 |
Here is another real-life example. By default, whenever Perl writes to |
| 1371 |
a DBM database it always writes the key and value as strings. So when |
| 1372 |
you use this: |
| 1373 |
.PP |
| 1374 |
.Vb 1 |
| 1375 |
\& $hash{12345} = "something" ; |
| 1376 |
.Ve |
| 1377 |
.PP |
| 1378 |
the key 12345 will get stored in the DBM database as the 5 byte string |
| 1379 |
"12345". If you actually want the key to be stored in the DBM database |
| 1380 |
as a C int, you will have to use \f(CW\*(C`pack\*(C'\fR when writing, and \f(CW\*(C`unpack\*(C'\fR |
| 1381 |
when reading. |
| 1382 |
.PP |
| 1383 |
Here is a DBM Filter that does it: |
| 1384 |
.PP |
| 1385 |
.Vb 6 |
| 1386 |
\& use warnings ; |
| 1387 |
\& use strict ; |
| 1388 |
\& use DB_File ; |
| 1389 |
\& my %hash ; |
| 1390 |
\& my $filename = "filt" ; |
| 1391 |
\& unlink $filename ; |
| 1392 |
\& |
| 1393 |
\& |
| 1394 |
\& my $db = tie %hash, \*(AqDB_File\*(Aq, $filename, O_CREAT|O_RDWR, 0666, $DB_HASH |
| 1395 |
\& or die "Cannot open $filename: $!\en" ; |
| 1396 |
\& |
| 1397 |
\& $db\->filter_fetch_key ( sub { $_ = unpack("i", $_) } ) ; |
| 1398 |
\& $db\->filter_store_key ( sub { $_ = pack ("i", $_) } ) ; |
| 1399 |
\& $hash{123} = "def" ; |
| 1400 |
\& # ... |
| 1401 |
\& undef $db ; |
| 1402 |
\& untie %hash ; |
| 1403 |
.Ve |
| 1404 |
.PP |
| 1405 |
This time only two filters have been used \-\- we only need to manipulate |
| 1406 |
the contents of the key, so it wasn't necessary to install any value |
| 1407 |
filters. |
| 1408 |
.SH "HINTS AND TIPS" |
| 1409 |
.IX Header "HINTS AND TIPS" |
| 1410 |
.SS "Locking: The Trouble with fd" |
| 1411 |
.IX Subsection "Locking: The Trouble with fd" |
| 1412 |
Until version 1.72 of this module, the recommended technique for locking |
| 1413 |
\&\fBDB_File\fR databases was to flock the filehandle returned from the "fd" |
| 1414 |
function. Unfortunately this technique has been shown to be fundamentally |
| 1415 |
flawed (Kudos to David Harris for tracking this down). Use it at your own |
| 1416 |
peril! |
| 1417 |
.PP |
| 1418 |
The locking technique went like this. |
| 1419 |
.PP |
| 1420 |
.Vb 12 |
| 1421 |
\& $db = tie(%db, \*(AqDB_File\*(Aq, \*(Aqfoo.db\*(Aq, O_CREAT|O_RDWR, 0644) |
| 1422 |
\& || die "dbcreat foo.db $!"; |
| 1423 |
\& $fd = $db\->fd; |
| 1424 |
\& open(DB_FH, "+<&=$fd") || die "dup $!"; |
| 1425 |
\& flock (DB_FH, LOCK_EX) || die "flock: $!"; |
| 1426 |
\& ... |
| 1427 |
\& $db{"Tom"} = "Jerry" ; |
| 1428 |
\& ... |
| 1429 |
\& flock(DB_FH, LOCK_UN); |
| 1430 |
\& undef $db; |
| 1431 |
\& untie %db; |
| 1432 |
\& close(DB_FH); |
| 1433 |
.Ve |
| 1434 |
.PP |
| 1435 |
In simple terms, this is what happens: |
| 1436 |
.IP 1. 5 |
| 1437 |
Use "tie" to open the database. |
| 1438 |
.IP 2. 5 |
| 1439 |
Lock the database with fd & flock. |
| 1440 |
.IP 3. 5 |
| 1441 |
Read & Write to the database. |
| 1442 |
.IP 4. 5 |
| 1443 |
Unlock and close the database. |
| 1444 |
.PP |
| 1445 |
Here is the crux of the problem. A side-effect of opening the \fBDB_File\fR |
| 1446 |
database in step 2 is that an initial block from the database will get |
| 1447 |
read from disk and cached in memory. |
| 1448 |
.PP |
| 1449 |
To see why this is a problem, consider what can happen when two processes, |
| 1450 |
say "A" and "B", both want to update the same \fBDB_File\fR database |
| 1451 |
using the locking steps outlined above. Assume process "A" has already |
| 1452 |
opened the database and has a write lock, but it hasn't actually updated |
| 1453 |
the database yet (it has finished step 2, but not started step 3 yet). Now |
| 1454 |
process "B" tries to open the same database \- step 1 will succeed, |
| 1455 |
but it will block on step 2 until process "A" releases the lock. The |
| 1456 |
important thing to notice here is that at this point in time both |
| 1457 |
processes will have cached identical initial blocks from the database. |
| 1458 |
.PP |
| 1459 |
Now process "A" updates the database and happens to change some of the |
| 1460 |
data held in the initial buffer. Process "A" terminates, flushing |
| 1461 |
all cached data to disk and releasing the database lock. At this point |
| 1462 |
the database on disk will correctly reflect the changes made by process |
| 1463 |
"A". |
| 1464 |
.PP |
| 1465 |
With the lock released, process "B" can now continue. It also updates the |
| 1466 |
database and unfortunately it too modifies the data that was in its |
| 1467 |
initial buffer. Once that data gets flushed to disk it will overwrite |
| 1468 |
some/all of the changes process "A" made to the database. |
| 1469 |
.PP |
| 1470 |
The result of this scenario is at best a database that doesn't contain |
| 1471 |
what you expect. At worst the database will corrupt. |
| 1472 |
.PP |
| 1473 |
The above won't happen every time competing process update the same |
| 1474 |
\&\fBDB_File\fR database, but it does illustrate why the technique should |
| 1475 |
not be used. |
| 1476 |
.SS "Safe ways to lock a database" |
| 1477 |
.IX Subsection "Safe ways to lock a database" |
| 1478 |
Starting with version 2.x, Berkeley DB has internal support for locking. |
| 1479 |
The companion module to this one, BerkeleyDB <https://metacpan.org/pod/BerkeleyDB>, provides an interface |
| 1480 |
to this locking functionality. If you are serious about locking |
| 1481 |
Berkeley DB databases, I strongly recommend using BerkeleyDB <https://metacpan.org/pod/BerkeleyDB>. |
| 1482 |
.PP |
| 1483 |
If using BerkeleyDB <https://metacpan.org/pod/BerkeleyDB> isn't an option, there are a number of modules |
| 1484 |
available on CPAN that can be used to implement locking. Each one |
| 1485 |
implements locking differently and has different goals in mind. It is |
| 1486 |
therefore worth knowing the difference, so that you can pick the right |
| 1487 |
one for your application. Here are the three locking wrappers: |
| 1488 |
.IP \fBTie::DB_Lock\fR 5 |
| 1489 |
.IX Item "Tie::DB_Lock" |
| 1490 |
A \fBDB_File\fR wrapper which creates copies of the database file for |
| 1491 |
read access, so that you have a kind of a multiversioning concurrent read |
| 1492 |
system. However, updates are still serial. Use for databases where reads |
| 1493 |
may be lengthy and consistency problems may occur. |
| 1494 |
.IP \fBTie::DB_LockFile\fR 5 |
| 1495 |
.IX Item "Tie::DB_LockFile" |
| 1496 |
A \fBDB_File\fR wrapper that has the ability to lock and unlock the database |
| 1497 |
while it is being used. Avoids the tie-before-flock problem by simply |
| 1498 |
re-tie-ing the database when you get or drop a lock. Because of the |
| 1499 |
flexibility in dropping and re-acquiring the lock in the middle of a |
| 1500 |
session, this can be massaged into a system that will work with long |
| 1501 |
updates and/or reads if the application follows the hints in the POD |
| 1502 |
documentation. |
| 1503 |
.IP \fBDB_File::Lock\fR 5 |
| 1504 |
.IX Item "DB_File::Lock" |
| 1505 |
An extremely lightweight \fBDB_File\fR wrapper that simply flocks a lockfile |
| 1506 |
before tie-ing the database and drops the lock after the untie. Allows |
| 1507 |
one to use the same lockfile for multiple databases to avoid deadlock |
| 1508 |
problems, if desired. Use for databases where updates are reads are |
| 1509 |
quick and simple flock locking semantics are enough. |
| 1510 |
.SS "Sharing Databases With C Applications" |
| 1511 |
.IX Subsection "Sharing Databases With C Applications" |
| 1512 |
There is no technical reason why a Berkeley DB database cannot be |
| 1513 |
shared by both a Perl and a C application. |
| 1514 |
.PP |
| 1515 |
The vast majority of problems that are reported in this area boil down |
| 1516 |
to the fact that C strings are NULL terminated, whilst Perl strings are |
| 1517 |
not. See "DBM FILTERS" for a generic way to work around this problem. |
| 1518 |
.PP |
| 1519 |
Here is a real example. Netscape 2.0 keeps a record of the locations you |
| 1520 |
visit along with the time you last visited them in a DB_HASH database. |
| 1521 |
This is usually stored in the file \fI~/.netscape/history.db\fR. The key |
| 1522 |
field in the database is the location string and the value field is the |
| 1523 |
time the location was last visited stored as a 4 byte binary value. |
| 1524 |
.PP |
| 1525 |
If you haven't already guessed, the location string is stored with a |
| 1526 |
terminating NULL. This means you need to be careful when accessing the |
| 1527 |
database. |
| 1528 |
.PP |
| 1529 |
Here is a snippet of code that is loosely based on Tom Christiansen's |
| 1530 |
\&\fIggh\fR script (available from your nearest CPAN archive in |
| 1531 |
\&\fIauthors/id/TOMC/scripts/nshist.gz\fR). |
| 1532 |
.PP |
| 1533 |
.Vb 4 |
| 1534 |
\& use warnings ; |
| 1535 |
\& use strict ; |
| 1536 |
\& use DB_File ; |
| 1537 |
\& use Fcntl ; |
| 1538 |
\& |
| 1539 |
\& my ($dotdir, $HISTORY, %hist_db, $href, $binary_time, $date) ; |
| 1540 |
\& $dotdir = $ENV{HOME} || $ENV{LOGNAME}; |
| 1541 |
\& |
| 1542 |
\& $HISTORY = "$dotdir/.netscape/history.db"; |
| 1543 |
\& |
| 1544 |
\& tie %hist_db, \*(AqDB_File\*(Aq, $HISTORY |
| 1545 |
\& or die "Cannot open $HISTORY: $!\en" ;; |
| 1546 |
\& |
| 1547 |
\& # Dump the complete database |
| 1548 |
\& while ( ($href, $binary_time) = each %hist_db ) { |
| 1549 |
\& |
| 1550 |
\& # remove the terminating NULL |
| 1551 |
\& $href =~ s/\ex00$// ; |
| 1552 |
\& |
| 1553 |
\& # convert the binary time into a user friendly string |
| 1554 |
\& $date = localtime unpack("V", $binary_time); |
| 1555 |
\& print "$date $href\en" ; |
| 1556 |
\& } |
| 1557 |
\& |
| 1558 |
\& # check for the existence of a specific key |
| 1559 |
\& # remember to add the NULL |
| 1560 |
\& if ( $binary_time = $hist_db{"http://mox.perl.com/\ex00"} ) { |
| 1561 |
\& $date = localtime unpack("V", $binary_time) ; |
| 1562 |
\& print "Last visited mox.perl.com on $date\en" ; |
| 1563 |
\& } |
| 1564 |
\& else { |
| 1565 |
\& print "Never visited mox.perl.com\en" |
| 1566 |
\& } |
| 1567 |
\& |
| 1568 |
\& untie %hist_db ; |
| 1569 |
.Ve |
| 1570 |
.SS "The \fBuntie()\fP Gotcha" |
| 1571 |
.IX Subsection "The untie() Gotcha" |
| 1572 |
If you make use of the Berkeley DB API, it is \fIvery\fR strongly |
| 1573 |
recommended that you read "The untie Gotcha" in perltie. |
| 1574 |
.PP |
| 1575 |
Even if you don't currently make use of the API interface, it is still |
| 1576 |
worth reading it. |
| 1577 |
.PP |
| 1578 |
Here is an example which illustrates the problem from a \fBDB_File\fR |
| 1579 |
perspective: |
| 1580 |
.PP |
| 1581 |
.Vb 2 |
| 1582 |
\& use DB_File ; |
| 1583 |
\& use Fcntl ; |
| 1584 |
\& |
| 1585 |
\& my %x ; |
| 1586 |
\& my $X ; |
| 1587 |
\& |
| 1588 |
\& $X = tie %x, \*(AqDB_File\*(Aq, \*(Aqtst.fil\*(Aq , O_RDWR|O_TRUNC |
| 1589 |
\& or die "Cannot tie first time: $!" ; |
| 1590 |
\& |
| 1591 |
\& $x{123} = 456 ; |
| 1592 |
\& |
| 1593 |
\& untie %x ; |
| 1594 |
\& |
| 1595 |
\& tie %x, \*(AqDB_File\*(Aq, \*(Aqtst.fil\*(Aq , O_RDWR|O_CREAT |
| 1596 |
\& or die "Cannot tie second time: $!" ; |
| 1597 |
\& |
| 1598 |
\& untie %x ; |
| 1599 |
.Ve |
| 1600 |
.PP |
| 1601 |
When run, the script will produce this error message: |
| 1602 |
.PP |
| 1603 |
.Vb 1 |
| 1604 |
\& Cannot tie second time: Invalid argument at bad.file line 14. |
| 1605 |
.Ve |
| 1606 |
.PP |
| 1607 |
Although the error message above refers to the second \fBtie()\fR statement |
| 1608 |
in the script, the source of the problem is really with the \fBuntie()\fR |
| 1609 |
statement that precedes it. |
| 1610 |
.PP |
| 1611 |
Having read perltie you will probably have already guessed that the |
| 1612 |
error is caused by the extra copy of the tied object stored in \f(CW$X\fR. |
| 1613 |
If you haven't, then the problem boils down to the fact that the |
| 1614 |
\&\fBDB_File\fR destructor, DESTROY, will not be called until \fIall\fR |
| 1615 |
references to the tied object are destroyed. Both the tied variable, |
| 1616 |
\&\f(CW%x\fR, and \f(CW$X\fR above hold a reference to the object. The call to |
| 1617 |
\&\fBuntie()\fR will destroy the first, but \f(CW$X\fR still holds a valid |
| 1618 |
reference, so the destructor will not get called and the database file |
| 1619 |
\&\fItst.fil\fR will remain open. The fact that Berkeley DB then reports the |
| 1620 |
attempt to open a database that is already open via the catch-all |
| 1621 |
"Invalid argument" doesn't help. |
| 1622 |
.PP |
| 1623 |
If you run the script with the \f(CW\*(C`\-w\*(C'\fR flag the error message becomes: |
| 1624 |
.PP |
| 1625 |
.Vb 2 |
| 1626 |
\& untie attempted while 1 inner references still exist at bad.file line 12. |
| 1627 |
\& Cannot tie second time: Invalid argument at bad.file line 14. |
| 1628 |
.Ve |
| 1629 |
.PP |
| 1630 |
which pinpoints the real problem. Finally the script can now be |
| 1631 |
modified to fix the original problem by destroying the API object |
| 1632 |
before the untie: |
| 1633 |
.PP |
| 1634 |
.Vb 2 |
| 1635 |
\& ... |
| 1636 |
\& $x{123} = 456 ; |
| 1637 |
\& |
| 1638 |
\& undef $X ; |
| 1639 |
\& untie %x ; |
| 1640 |
\& |
| 1641 |
\& $X = tie %x, \*(AqDB_File\*(Aq, \*(Aqtst.fil\*(Aq , O_RDWR|O_CREAT |
| 1642 |
\& ... |
| 1643 |
.Ve |
| 1644 |
.SH "COMMON QUESTIONS" |
| 1645 |
.IX Header "COMMON QUESTIONS" |
| 1646 |
.SS "Why is there Perl source in my database?" |
| 1647 |
.IX Subsection "Why is there Perl source in my database?" |
| 1648 |
If you look at the contents of a database file created by DB_File, |
| 1649 |
there can sometimes be part of a Perl script included in it. |
| 1650 |
.PP |
| 1651 |
This happens because Berkeley DB uses dynamic memory to allocate |
| 1652 |
buffers which will subsequently be written to the database file. Being |
| 1653 |
dynamic, the memory could have been used for anything before DB |
| 1654 |
malloced it. As Berkeley DB doesn't clear the memory once it has been |
| 1655 |
allocated, the unused portions will contain random junk. In the case |
| 1656 |
where a Perl script gets written to the database, the random junk will |
| 1657 |
correspond to an area of dynamic memory that happened to be used during |
| 1658 |
the compilation of the script. |
| 1659 |
.PP |
| 1660 |
Unless you don't like the possibility of there being part of your Perl |
| 1661 |
scripts embedded in a database file, this is nothing to worry about. |
| 1662 |
.SS "How do I store complex data structures with DB_File?" |
| 1663 |
.IX Subsection "How do I store complex data structures with DB_File?" |
| 1664 |
Although \fBDB_File\fR cannot do this directly, there is a module which |
| 1665 |
can layer transparently over \fBDB_File\fR to accomplish this feat. |
| 1666 |
.PP |
| 1667 |
Check out the MLDBM module, available on CPAN in the directory |
| 1668 |
\&\fImodules/by\-module/MLDBM\fR. |
| 1669 |
.SS "What does ""wide character in subroutine entry"" mean?" |
| 1670 |
.IX Subsection "What does ""wide character in subroutine entry"" mean?" |
| 1671 |
You will usually get this message if you are working with UTF\-8 data and |
| 1672 |
want to read/write it from/to a Berkeley DB database file. |
| 1673 |
.PP |
| 1674 |
The easist way to deal with this issue is to use the pre-defined "utf8" |
| 1675 |
\&\fBDBM_Filter\fR (see DBM_Filter) that was designed to deal with this |
| 1676 |
situation. |
| 1677 |
.PP |
| 1678 |
The example below shows what you need if \fIboth\fR the key and value are |
| 1679 |
expected to be in UTF\-8. |
| 1680 |
.PP |
| 1681 |
.Vb 2 |
| 1682 |
\& use DB_File; |
| 1683 |
\& use DBM_Filter; |
| 1684 |
\& |
| 1685 |
\& my $db = tie %h, \*(AqDB_File\*(Aq, \*(Aq/tmp/try.db\*(Aq, O_CREAT|O_RDWR, 0666, $DB_BTREE; |
| 1686 |
\& $db\->Filter_Key_Push(\*(Aqutf8\*(Aq); |
| 1687 |
\& $db\->Filter_Value_Push(\*(Aqutf8\*(Aq); |
| 1688 |
\& |
| 1689 |
\& my $key = "\eN{LATIN SMALL LETTER A WITH ACUTE}"; |
| 1690 |
\& my $value = "\eN{LATIN SMALL LETTER E WITH ACUTE}"; |
| 1691 |
\& $h{ $key } = $value; |
| 1692 |
.Ve |
| 1693 |
.SS "What does ""Invalid Argument"" mean?" |
| 1694 |
.IX Subsection "What does ""Invalid Argument"" mean?" |
| 1695 |
You will get this error message when one of the parameters in the |
| 1696 |
\&\f(CW\*(C`tie\*(C'\fR call is wrong. Unfortunately there are quite a few parameters to |
| 1697 |
get wrong, so it can be difficult to figure out which one it is. |
| 1698 |
.PP |
| 1699 |
Here are a couple of possibilities: |
| 1700 |
.IP 1. 5 |
| 1701 |
Attempting to reopen a database without closing it. |
| 1702 |
.IP 2. 5 |
| 1703 |
Using the O_WRONLY flag. |
| 1704 |
.SS "What does ""Bareword 'DB_File' not allowed"" mean?" |
| 1705 |
.IX Subsection "What does ""Bareword 'DB_File' not allowed"" mean?" |
| 1706 |
You will encounter this particular error message when you have the |
| 1707 |
\&\f(CW\*(C`strict \*(Aqsubs\*(Aq\*(C'\fR pragma (or the full strict pragma) in your script. |
| 1708 |
Consider this script: |
| 1709 |
.PP |
| 1710 |
.Vb 5 |
| 1711 |
\& use warnings ; |
| 1712 |
\& use strict ; |
| 1713 |
\& use DB_File ; |
| 1714 |
\& my %x ; |
| 1715 |
\& tie %x, DB_File, "filename" ; |
| 1716 |
.Ve |
| 1717 |
.PP |
| 1718 |
Running it produces the error in question: |
| 1719 |
.PP |
| 1720 |
.Vb 1 |
| 1721 |
\& Bareword "DB_File" not allowed while "strict subs" in use |
| 1722 |
.Ve |
| 1723 |
.PP |
| 1724 |
To get around the error, place the word \f(CW\*(C`DB_File\*(C'\fR in either single or |
| 1725 |
double quotes, like this: |
| 1726 |
.PP |
| 1727 |
.Vb 1 |
| 1728 |
\& tie %x, "DB_File", "filename" ; |
| 1729 |
.Ve |
| 1730 |
.PP |
| 1731 |
Although it might seem like a real pain, it is really worth the effort |
| 1732 |
of having a \f(CW\*(C`use strict\*(C'\fR in all your scripts. |
| 1733 |
.SH REFERENCES |
| 1734 |
.IX Header "REFERENCES" |
| 1735 |
Articles that are either about \fBDB_File\fR or make use of it. |
| 1736 |
.IP 1. 5 |
| 1737 |
\&\fIFull-Text Searching in Perl\fR, Tim Kientzle ([email protected]), |
| 1738 |
Dr. Dobb's Journal, Issue 295, January 1999, pp 34\-41 |
| 1739 |
.SH HISTORY |
| 1740 |
.IX Header "HISTORY" |
| 1741 |
Moved to the Changes file. |
| 1742 |
.SH BUGS |
| 1743 |
.IX Header "BUGS" |
| 1744 |
Some older versions of Berkeley DB had problems with fixed length |
| 1745 |
records using the RECNO file format. This problem has been fixed since |
| 1746 |
version 1.85 of Berkeley DB. |
| 1747 |
.PP |
| 1748 |
I am sure there are bugs in the code. If you do find any, or can |
| 1749 |
suggest any enhancements, I would welcome your comments. |
| 1750 |
.SH SUPPORT |
| 1751 |
.IX Header "SUPPORT" |
| 1752 |
General feedback/questions/bug reports should be sent to |
| 1753 |
<https://github.com/pmqs/DB_File/issues> (preferred) or |
| 1754 |
<https://rt.cpan.org/Public/Dist/Display.html?Name=DB_File>. |
| 1755 |
.SH AVAILABILITY |
| 1756 |
.IX Header "AVAILABILITY" |
| 1757 |
\&\fBDB_File\fR comes with the standard Perl source distribution. Look in |
| 1758 |
the directory \fIext/DB_File\fR. Given the amount of time between releases |
| 1759 |
of Perl the version that ships with Perl is quite likely to be out of |
| 1760 |
date, so the most recent version can always be found on CPAN (see |
| 1761 |
"CPAN" in perlmodlib for details), in the directory |
| 1762 |
\&\fImodules/by\-module/DB_File\fR. |
| 1763 |
.PP |
| 1764 |
\&\fBDB_File\fR is designed to work with any version of Berkeley DB, but is limited to the functionality provided by |
| 1765 |
version 1. If you want to make use of the new features available in Berkeley DB |
| 1766 |
2.x, or greater, use the Perl module BerkeleyDB <https://metacpan.org/pod/BerkeleyDB> instead. |
| 1767 |
.PP |
| 1768 |
The official web site for Berkeley DB is <http://www.oracle.com/technology/products/berkeley\-db/db/index.html>. |
| 1769 |
All versions of Berkeley DB are available there. |
| 1770 |
.PP |
| 1771 |
Alternatively, Berkeley DB version 1 is available at your nearest CPAN |
| 1772 |
archive in \fIsrc/misc/db.1.85.tar.gz\fR. |
| 1773 |
.SH COPYRIGHT |
| 1774 |
.IX Header "COPYRIGHT" |
| 1775 |
Copyright (c) 1995\-2023 Paul Marquess. All rights reserved. This program |
| 1776 |
is free software; you can redistribute it and/or modify it under the |
| 1777 |
same terms as Perl itself. |
| 1778 |
.PP |
| 1779 |
Although \fBDB_File\fR is covered by the Perl license, the library it |
| 1780 |
makes use of, namely Berkeley DB, is not. Berkeley DB has its own |
| 1781 |
copyright and its own license. |
| 1782 |
See AGPL <https://www.oracle.com/downloads/licenses/berkeleydb-oslicense.html> for more details. |
| 1783 |
Please take the time to read the Berkeley DB license and decide how it impacts your use of this Perl module. |
| 1784 |
.SH "SEE ALSO" |
| 1785 |
.IX Header "SEE ALSO" |
| 1786 |
perl, \fBdbopen\fR\|(3), \fBhash\fR\|(3), \fBrecno\fR\|(3), \fBbtree\fR\|(3), |
| 1787 |
perldbmfilter, DBM_Filter |
| 1788 |
.SH AUTHOR |
| 1789 |
.IX Header "AUTHOR" |
| 1790 |
The DB_File interface was written by Paul Marquess |
| 1791 |
<[email protected]>. |