DB_File

                                 Version 1.54

                                 19th Sept 1997

       Copyright (c) 1995/6/7 Paul Marquess. All rights reserved. This
       program is free software; you can redistribute it and/or modify
       it under the same terms as Perl itself.


                                  WARNING
       The support for Berkeley DB 2.0 in this release should be
       considered as beta quality code. The support for Berkeley DB
       1.x should be ok.



DESCRIPTION
-----------

DB_File is a module which allows Perl programs to make use of the
facilities provided by Berkeley DB version 1. (DB_File can be built
version 2 of Berkeley DB, but it will only support the 1.x features),

A future version of DB_File will support the new features available in
Berkeley DB 2.x.

Berkeley DB is a C library which provides a consistent interface to a
number of database formats. DB_File provides an interface to all three
of the database types (hash, btree and recno) currently supported by
Berkeley DB.

For further details see the documentation included at the end of the
file DB_File.pm.

PREREQUISITES
-------------

Before you can build DB_File you need to have the following installed
on your system:

   * Perl 5.004 or greater.

   * Berkeley DB.

     For version 1 of Berkeley DB either 1.85 or 1.86 are best.
     For version 2 of Berkeley DB you must have 2.0.5 or greater.

     The official web site for Berkeley DB is
     http://www.sleepycat.com/db. The ftp equivalent is
     ftp.sleepycat.com:/pub. Both versions 1 and 2 of Berkeley DB are
     available there.

     Alternatively, Berkeley DB version 1 is available at your nearest
     CPAN archive (see the section on CPAN in the perlmod manpage for
     a list) in src/misc/db.1.85.tar.gz

     If you are running IRIX, then get Berkeley DB version 1 from
     http://reality.sgi.com/ariel. It has the patches necessary to
     compile properly on IRIX 5.3.


BUILDING THE MODULE
-------------------

Assuming you have met all the prerequisites, building the module should
be relatively straightforward.

The first step is to edit the file config.in to suit you local
installation. Instructions are given in the file.

The module can now be built and tested using this sequence of
commands:

   perl Makefile.PL
   make
   make test


 NOTE:
     If you have a very old version of Berkeley DB, three of the tests
     in the recno test hasness may fail (tests 51, 53 and 55). You can
     safely ignore the errors if you're never going to use the broken
     functionality (recno databases with a modified bval).
     Otherwise you'll have to upgrade your DB library.

INSTALLATION
------------

   make install

FEEDBACK
--------

How to report a problem with DB_File.

To help me help you, I need of the following information:

1. The version of Perl and the operating system name and version you
   are running. If you are running a newish version of Perl, the
   output from running "perl -V" will tell me all I need to know.
   If your perl doesn't understand the -V flag, then not only do you
   have quite an old version of Perl, you very likely have an old
   version of DB_File.  You should consider upgrading. The problem you
   have might already be fixed.

2. The version of DB_File you have. If you have successfully installed
   DB_File, this one-liner will tell you:

      perl -e 'use DB_File; print "DB_File ver $DB_File::VERSION\n"'

   If you haven't installed DB_File then search DB_File for a line
   like this:

     $VERSION = "1.20" ;

3. The version of Berkeley DB you have installed. The most recent
   recommended versions are 1.85, 1.86 and 2.0.5. Again, if you have
   an older version, think about upgrading. One point to note if you
   are considering upgrading Berkeley DB - the file formats for 1.85,
   1.86 and 2.0 are all different.

4. If you are having problems building DB_File, send me a complete log
   of what happened.

5. Now the difficult one. If you think you have found a bug in DB_File
   and you want me to fix it, you will *greatly* enhance the chances
   of me being able to track it down by sending me a small
   self-contained Perl script that illustrates the problem you are
   encountering. Include a summary of what you think the problem is
   and a log of what happens when you run the script, in case I can't
   reproduce your problem on my system. If possible, don't have the
   script dependent on an existing 20Meg database. If the script you
   send me can create the database itself then that is preferred.

   I realise that in some cases this is easier said than done, so if
   you can only reproduce the problem in your existing script, then
   you can post me that if you want. Just don't expect me to find your
   problem in a hurry, or at all. :-)


CHANGES
-------

See the Changes file.

Paul Marquess <[email protected]>