                                   BerkeleyDB

                                  Version 0.05

                                  9th  Nov 1998 

	Copyright (c) 1997/8 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
	This is alpha quality code. Do not assume that the interface
	defined here is stable. Do not assume that the code is stable
	enough to write real applications. Consider yourself warned.



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

BerkeleyDB is a module which allows Perl programs to make use of the
facilities provided by Berkeley DB version 2. (Note: if you want to use
version 1 of Berkeley DB with Perl you need the DB_File module).

Berkeley DB is a C library which provides a consistent interface to a
number of database formats. BerkeleyDB 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 BerkeleyDB.pm.

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

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

    * Perl 5.004_04 or greater. 

    * Berkeley DB. Version 2.3.14 or greater 

      The official web site for Berkeley DB is
      http://www.sleepycat.com/db. The ftp equivalent is
      ftp.sleepycat.com:/pub. 


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

Assuming you have met all the prerequisites, building the module should
be relatively straightforward. If you are running either Solaris 2.5 or
HP-UX 10 have a look at one of the Solaris Notes or HP-UX Notes sections
below before building this module.


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


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

    make install


Solaris Notes
-------------

If you are running Solaris 2.5, and you get this error when you run the
BerkeleyDB 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 this module 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.
    



FEEDBACK
--------

How to report a problem with BerkeleyDB.

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 BerkeleyDB.  You should consider upgrading. The problem you
    have might already be fixed.

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

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

    If you haven't installed BerkeleyDB then search BerkeleyDB.pm for a
    line like this:

      $VERSION = "1.20" ;

 3. The version of Berkeley DB you have installed. 

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

 5. Now the difficult one. If you think you have found a bug in
    BerkeleyDB 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 <pmarquess@bfsec.bt.co.uk>

