DB_File

                                  Version 1.65

                                 6th March 1999  

 	Copyright (c) 1995-1999 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.


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),

If you want to make use of the new features available in Berkeley DB
2.x, use the Perl module BerkeleyDB instead.
 
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 must have the following installed on
your system:

    * Perl 5.004 or greater.

    * Berkeley DB. 

      The official web site for Berkeley DB is http://www.sleepycat.com/db. 
      The latest version of Berkeley DB is always available there. It
      is recommended that you use the most recent version available at
      the Sleepycat site.

      The one exception to this advice is where you want to use DB_File
      to access database files created by a third-party application, like
      Sendmail or Netscape. In these cases you must build DB_File with a
      compatible version of Berkeley DB.

      If you want to use Berkeley DB 2.x, you must have version 2.3.4
      or greater.  For Berkeley DB 1.x, use either version 1.85 or 1.86.


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

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

Step 1 : If you are running either Solaris 2.5 or HP-UX 10 and want
         to use Berkeley DB version 2, read either the Solaris Notes or
         HP-UX Notes sections below.

Step 2 : Edit the file config.in to suit you local installation. 
         Instructions are given in the file.

Step 3 : Build and test the module using 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 harness 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


TROUBLESHOOTING
===============

Here are some of the problems that people encounter when building DB_File.

Missing db.h or libdb.a
-----------------------

If you get an error like this:

  cc -c -I/usr/local/include -Dbool=char -DHAS_BOOL
  -O2    -DVERSION=\"1.64\" -DXS_VERSION=\"1.64\" -fpic
  -I/usr/local/lib/perl5/i586-linux/5.00404/CORE -DmDB_Prefix_t=size_t
  -DmDB_Hash_t=u_int32_t DB_File.c 
  DB_File.xs:101: db.h: No such file or directory

or this:

  LD_RUN_PATH="/lib" cc -o blib/arch/auto/DB_File/DB_File.so  -shared
  -L/usr/local/lib DB_File.o    -L/usr/local/lib -ldb 
  ld: cannot open -ldb: No such file or directory

This symptom can imply:

 1. You don't have Berkeley DB installed on your system at all.
    Solution: get & install Berkeley DB.

 2. You do have Berkeley DB installed, but it isn't in a standard place.
    Solution: Edit config.in and set the LIB and INCLUDE variables to point
              to the directories where libdb.a and db.h are installed.
  

Undefined symbol db_version
---------------------------

DB_File seems to have built correctly, but you get an error like this
when you run the test harness:

  $ make test
  PERL_DL_NONLAZY=1 /usr/bin/perl5.00404 -I./blib/arch -I./blib/lib
  -I/usr/local/lib/perl5/i586-linux/5.00404 -I/usr/local/lib/perl5 -e 'use
  Test::Harness qw(&runtests $verbose); $verbose=0; runtests @ARGV;' t/*.t
  t/db-btree..........Can't load './blib/arch/auto/DB_File/DB_File.so' for
  module DB_File: ./blib/arch/auto/DB_File/DB_File.so: undefined symbol:
  db_version at /usr/local/lib/perl5/i586-linux/5.00404/DynaLoader.pm
  line 166.

  at t/db-btree.t line 21
  BEGIN failed--compilation aborted at t/db-btree.t line 21.
  dubious Test returned status 2 (wstat 512, 0x200)

This error usually happens when you have both version 1 and version
2 of Berkeley DB installed on your system and DB_File attempts to
build using the db.h for Berkeley DB version 2 and the version 1
library. Unfortunately the two versions aren't compatible with each
other. The undefined symbol error is actually caused because Berkeley
DB version 1 doesn't have the symbol db_version.

Solution: Setting the LIB & INCLUDE variables in config.in to point to the
          correct directories can sometimes be enough to fix this
          problem. If that doesn't work the easiest way to fix the
          problem is to either delete or temporarily rename the copies
          of db.h and libdb.a that you don't want DB_File to use.

Solaris Notes
-------------
 
If you are running Solaris 2.5, and you get this error when you run the
DB_File test harness:
 
    libc internal error: _rmutex_unlock: rmutex not held.
 
you probably need to install a Sun patch. It has been reported that
Sun patch 103187-25 (or later revisions) fixes this problem.
 
To find out if you have the patch installed, the command "showrev -p"
will display the patches that are currently installed on your system.


HP-UX Notes
-----------

Some people running HP-UX 10 have reported getting an error like this
when building DB_File with the native HP-UX compiler.

    ld: (Warning) At least one PA 2.0 object file (DB_File.o) was detected. 
    The linked output may not run on a PA 1.x system.
    ld: Invalid loader fixup for symbol "$000000A5".

If this is the case for you, Berkeley DB needs to be recompiled with
the +z or +Z option and the resulting library placed in a .sl file. The
following steps should do the trick:

  1: Configure the Berkeley DB distribution with the +z or +Z C compiler
     flag:

        env "CFLAGS=+z" ../dist/configure ...

  2: Edit the Berkeley DB Makefile and change:

        "libdb= libdb.a" to "libdb= libdb.sl".


  3: Build and install the Berkeley DB distribution as usual.


IRIX NOTES
----------

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


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.pm for a line
    like this:

      $VERSION = "1.20" ;

 3. The version of Berkeley DB you have installed.
    If you are using a version older than 1.85, 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 <Paul.Marquess@btinternet.com>