home *** CD-ROM | disk | FTP | other *** search
/ BURKS 2 / BURKS_AUG97.ISO / SLAKWARE / D12 / PERL1.TGZ / perl1.tar / usr / lib / perl5 / DB_File.pm < prev    next >
Text File  |  1996-06-28  |  16KB  |  674 lines
  1. # DB_File.pm -- Perl 5 interface to Berkeley DB 
  2. #
  3. # written by Paul Marquess (pmarquess@bfsec.bt.co.uk)
  4. # last modified 14th November 1995
  5. # version 1.01
  6.  
  7. package DB_File::HASHINFO ;
  8.  
  9. use strict;
  10. use vars qw(%elements);
  11. use Carp;
  12.  
  13. sub TIEHASH
  14. {
  15.     bless {} ;
  16. }
  17.  
  18. %elements = ( 'bsize'     => 0,
  19.               'ffactor'   => 0,
  20.               'nelem'     => 0,
  21.               'cachesize' => 0,
  22.               'hash'      => 0,
  23.               'lorder'    => 0
  24.             ) ;
  25.  
  26. sub FETCH 
  27. {  
  28.     return $_[0]{$_[1]} if defined $elements{$_[1]}  ;
  29.  
  30.     croak "DB_File::HASHINFO::FETCH - Unknown element '$_[1]'" ;
  31. }
  32.  
  33.  
  34. sub STORE 
  35. {
  36.     if ( defined $elements{$_[1]} )
  37.     {
  38.         $_[0]{$_[1]} = $_[2] ;
  39.         return ;
  40.     }
  41.     
  42.     croak "DB_File::HASHINFO::STORE - Unknown element '$_[1]'" ;
  43. }
  44.  
  45. sub DELETE 
  46. {
  47.     if ( defined $elements{$_[1]} )
  48.     {
  49.         delete ${$_[0]}{$_[1]} ;
  50.         return ;
  51.     }
  52.     
  53.     croak "DB_File::HASHINFO::DELETE - Unknown element '$_[1]'" ;
  54. }
  55.  
  56.  
  57. sub DESTROY {undef %{$_[0]} }
  58. sub FIRSTKEY { croak "DB_File::HASHINFO::FIRSTKEY is not implemented" }
  59. sub NEXTKEY { croak "DB_File::HASHINFO::NEXTKEY is not implemented" }
  60. sub EXISTS { croak "DB_File::HASHINFO::EXISTS is not implemented" }
  61. sub CLEAR { croak "DB_File::HASHINFO::CLEAR is not implemented" }
  62.  
  63. package DB_File::BTREEINFO ;
  64.  
  65. use strict;
  66. use vars qw(%elements);
  67. use Carp;
  68.  
  69. sub TIEHASH
  70. {
  71.     bless {} ;
  72. }
  73.  
  74. %elements = ( 'flags'    => 0,
  75.               'cachesize'  => 0,
  76.               'maxkeypage' => 0,
  77.               'minkeypage' => 0,
  78.               'psize'      => 0,
  79.               'compare'    => 0,
  80.               'prefix'     => 0,
  81.               'lorder'     => 0
  82.             ) ;
  83.  
  84. sub FETCH 
  85. {  
  86.     return $_[0]{$_[1]} if defined $elements{$_[1]}  ;
  87.  
  88.     croak "DB_File::BTREEINFO::FETCH - Unknown element '$_[1]'" ;
  89. }
  90.  
  91.  
  92. sub STORE 
  93. {
  94.     if ( defined $elements{$_[1]} )
  95.     {
  96.         $_[0]{$_[1]} = $_[2] ;
  97.         return ;
  98.     }
  99.     
  100.     croak "DB_File::BTREEINFO::STORE - Unknown element '$_[1]'" ;
  101. }
  102.  
  103. sub DELETE 
  104. {
  105.     if ( defined $elements{$_[1]} )
  106.     {
  107.         delete ${$_[0]}{$_[1]} ;
  108.         return ;
  109.     }
  110.     
  111.     croak "DB_File::BTREEINFO::DELETE - Unknown element '$_[1]'" ;
  112. }
  113.  
  114.  
  115. sub DESTROY {undef %{$_[0]} }
  116. sub FIRSTKEY { croak "DB_File::BTREEINFO::FIRSTKEY is not implemented" }
  117. sub NEXTKEY { croak "DB_File::BTREEINFO::NEXTKEY is not implemented" }
  118. sub EXISTS { croak "DB_File::BTREEINFO::EXISTS is not implemented" }
  119. sub CLEAR { croak "DB_File::BTREEINFO::CLEAR is not implemented" }
  120.  
  121. package DB_File::RECNOINFO ;
  122.  
  123. use strict;
  124. use vars qw(%elements);
  125. use Carp;
  126.  
  127. sub TIEHASH
  128. {
  129.     bless {} ;
  130. }
  131.  
  132. %elements = ( 'bval'      => 0,
  133.               'cachesize' => 0,
  134.               'psize'     => 0,
  135.               'flags'     => 0,
  136.               'lorder'    => 0,
  137.               'reclen'    => 0,
  138.               'bfname'    => 0
  139.             ) ;
  140. sub FETCH 
  141. {  
  142.     return $_[0]{$_[1]} if defined $elements{$_[1]}  ;
  143.  
  144.     croak "DB_File::RECNOINFO::FETCH - Unknown element '$_[1]'" ;
  145. }
  146.  
  147.  
  148. sub STORE 
  149. {
  150.     if ( defined $elements{$_[1]} )
  151.     {
  152.         $_[0]{$_[1]} = $_[2] ;
  153.         return ;
  154.     }
  155.     
  156.     croak "DB_File::RECNOINFO::STORE - Unknown element '$_[1]'" ;
  157. }
  158.  
  159. sub DELETE 
  160. {
  161.     if ( defined $elements{$_[1]} )
  162.     {
  163.         delete ${$_[0]}{$_[1]} ;
  164.         return ;
  165.     }
  166.     
  167.     croak "DB_File::RECNOINFO::DELETE - Unknown element '$_[1]'" ;
  168. }
  169.  
  170.  
  171. sub DESTROY {undef %{$_[0]} }
  172. sub FIRSTKEY { croak "DB_File::RECNOINFO::FIRSTKEY is not implemented" }
  173. sub NEXTKEY { croak "DB_File::RECNOINFO::NEXTKEY is not implemented" }
  174. sub EXISTS { croak "DB_File::BTREEINFO::EXISTS is not implemented" }
  175. sub CLEAR { croak "DB_File::BTREEINFO::CLEAR is not implemented" }
  176.  
  177.  
  178.  
  179. package DB_File ;
  180.  
  181. use strict;
  182. use vars qw($VERSION @ISA @EXPORT $AUTOLOAD $DB_BTREE $DB_HASH $DB_RECNO) ;
  183. use Carp;
  184.  
  185.  
  186. $VERSION = "1.01" ;
  187.  
  188. #typedef enum { DB_BTREE, DB_HASH, DB_RECNO } DBTYPE;
  189. $DB_BTREE = TIEHASH DB_File::BTREEINFO ;
  190. $DB_HASH  = TIEHASH DB_File::HASHINFO ;
  191. $DB_RECNO = TIEHASH DB_File::RECNOINFO ;
  192.  
  193. require Tie::Hash;
  194. require Exporter;
  195. use AutoLoader;
  196. require DynaLoader;
  197. @ISA = qw(Tie::Hash Exporter DynaLoader);
  198. @EXPORT = qw(
  199.         $DB_BTREE $DB_HASH $DB_RECNO 
  200.     BTREEMAGIC
  201.     BTREEVERSION
  202.     DB_LOCK
  203.     DB_SHMEM
  204.     DB_TXN
  205.     HASHMAGIC
  206.     HASHVERSION
  207.     MAX_PAGE_NUMBER
  208.     MAX_PAGE_OFFSET
  209.     MAX_REC_NUMBER
  210.     RET_ERROR
  211.     RET_SPECIAL
  212.     RET_SUCCESS
  213.     R_CURSOR
  214.     R_DUP
  215.     R_FIRST
  216.     R_FIXEDLEN
  217.     R_IAFTER
  218.     R_IBEFORE
  219.     R_LAST
  220.     R_NEXT
  221.     R_NOKEY
  222.     R_NOOVERWRITE
  223.     R_PREV
  224.     R_RECNOSYNC
  225.     R_SETCURSOR
  226.     R_SNAPSHOT
  227.     __R_UNUSED
  228. );
  229.  
  230. sub AUTOLOAD {
  231.     my($constname);
  232.     ($constname = $AUTOLOAD) =~ s/.*:://;
  233.     my $val = constant($constname, @_ ? $_[0] : 0);
  234.     if ($! != 0) {
  235.     if ($! =~ /Invalid/) {
  236.         $AutoLoader::AUTOLOAD = $AUTOLOAD;
  237.         goto &AutoLoader::AUTOLOAD;
  238.     }
  239.     else {
  240.         my($pack,$file,$line) = caller;
  241.         croak "Your vendor has not defined DB macro $constname, used at $file line $line.
  242. ";
  243.     }
  244.     }
  245.     eval "sub $AUTOLOAD { $val }";
  246.     goto &$AUTOLOAD;
  247. }
  248.  
  249. bootstrap DB_File $VERSION;
  250.  
  251. # Preloaded methods go here.  Autoload methods go after __END__, and are
  252. # processed by the autosplit program.
  253.  
  254. 1;
  255. __END__
  256.  
  257. =cut
  258.  
  259. =head1 NAME
  260.  
  261. DB_File - Perl5 access to Berkeley DB
  262.  
  263. =head1 SYNOPSIS
  264.  
  265.  use DB_File ;
  266.   
  267.  [$X =] tie %hash,  DB_File, $filename [, $flags, $mode, $DB_HASH] ;
  268.  [$X =] tie %hash,  DB_File, $filename, $flags, $mode, $DB_BTREE ;
  269.  [$X =] tie @array, DB_File, $filename, $flags, $mode, $DB_RECNO ;
  270.    
  271.  $status = $X->del($key [, $flags]) ;
  272.  $status = $X->put($key, $value [, $flags]) ;
  273.  $status = $X->get($key, $value [, $flags]) ;
  274.  $status = $X->seq($key, $value [, $flags]) ;
  275.  $status = $X->sync([$flags]) ;
  276.  $status = $X->fd ;
  277.     
  278.  untie %hash ;
  279.  untie @array ;
  280.  
  281. =head1 DESCRIPTION
  282.  
  283. B<DB_File> is a module which allows Perl programs to make use of the
  284. facilities provided by Berkeley DB.  If you intend to use this
  285. module you should really have a copy of the Berkeley DB manualpage at
  286. hand. The interface defined here mirrors the Berkeley DB interface
  287. closely.
  288.  
  289. Berkeley DB is a C library which provides a consistent interface to a
  290. number of database formats.  B<DB_File> provides an interface to all
  291. three of the database types currently supported by Berkeley DB.
  292.  
  293. The file types are:
  294.  
  295. =over 5
  296.  
  297. =item DB_HASH
  298.  
  299. This database type allows arbitrary key/data pairs to be stored in data
  300. files. This is equivalent to the functionality provided by other
  301. hashing packages like DBM, NDBM, ODBM, GDBM, and SDBM. Remember though,
  302. the files created using DB_HASH are not compatible with any of the
  303. other packages mentioned.
  304.  
  305. A default hashing algorithm, which will be adequate for most
  306. applications, is built into Berkeley DB. If you do need to use your own
  307. hashing algorithm it is possible to write your own in Perl and have
  308. B<DB_File> use it instead.
  309.  
  310. =item DB_BTREE
  311.  
  312. The btree format allows arbitrary key/data pairs to be stored in a
  313. sorted, balanced binary tree.
  314.  
  315. As with the DB_HASH format, it is possible to provide a user defined
  316. Perl routine to perform the comparison of keys. By default, though, the
  317. keys are stored in lexical order.
  318.  
  319. =item DB_RECNO
  320.  
  321. DB_RECNO allows both fixed-length and variable-length flat text files
  322. to be manipulated using the same key/value pair interface as in DB_HASH
  323. and DB_BTREE.  In this case the key will consist of a record (line)
  324. number.
  325.  
  326. =back
  327.  
  328. =head2 How does DB_File interface to Berkeley DB?
  329.  
  330. B<DB_File> allows access to Berkeley DB files using the tie() mechanism
  331. in Perl 5 (for full details, see L<perlfunc/tie()>). This facility
  332. allows B<DB_File> to access Berkeley DB files using either an
  333. associative array (for DB_HASH & DB_BTREE file types) or an ordinary
  334. array (for the DB_RECNO file type).
  335.  
  336. In addition to the tie() interface, it is also possible to use most of
  337. the functions provided in the Berkeley DB API.
  338.  
  339. =head2 Differences with Berkeley DB
  340.  
  341. Berkeley DB uses the function dbopen() to open or create a database.
  342. Below is the C prototype for dbopen().
  343.  
  344.       DB*
  345.       dbopen (const char * file, int flags, int mode, 
  346.               DBTYPE type, const void * openinfo)
  347.  
  348. The parameter C<type> is an enumeration which specifies which of the 3
  349. interface methods (DB_HASH, DB_BTREE or DB_RECNO) is to be used.
  350. Depending on which of these is actually chosen, the final p