                   Empress Perl Interface DBD::EmpressNet

                  an Empress interface for Perl 5 using DBI

------------------------------------------------------------------------

Portions Copyright (c) 1997, 1999 Empress Software Inc

You may distribute under the terms of either the GNU General Public License
or the Artistic License, as specified in the Perl README file.

-- The following is a standard warning for all DBI and DBD::* software --

WARNING: THIS IS ALPHA SOFTWARE. IT IS POSSIBLY UNRELIABLE!

------------------------------------------------------------------------

Introduction

The Empress Perl interface DBD::EmpressNet is a module which can be added to
an existing perl 5 installation to allow users to access Empress databases
through perl scripts.

This interface between the Empress RDBMS and Perl uses the DBI database
interface module. Details about this perl module can be found at:

        ftp://ftp.demon.co.uk:/pub/perl/db
        http://www.hermetica.com/technologia/perl/DBI/index.html

as well as at a number of CPAN sites which mirror perl and perl-related
modules.

This module was developed using the following software

        perl            5.004
        DBI             0.89
        db engine       Empress version 6.10

It will probably not work with earlier versions of either perl or the DBI
module. In particular, it will _not_ work with perl v4.x. Both of these
pieces of software can be retrieved from any of the official perl 'CPAN'
(Comprehensive Perl Archive Network) sites.

A good starting point for retrieving data about Perl and its modules is:

        http://www.perl.com/


Note

If you installed Empress Perl Interface DBD::EmpressNet through Empress
Hypermedia Installation, you do not need to install DBD::EmpressNet again
using the following instructions. The Empress Hypermedia Installation
program can install a pre-configured Perl, Perl DBI and DBD::EmpressNet for
you. However, if you are advance Perl programmer/administrator, you may
choose to DBD::EmpressNet into your own Perl environment. Then, you need the
following information.

If you have the Empress CDROM, you can find the DBD::EmpressNet package in:

    /CDROM/hypmedia/empperl/package/dbdemp.tgz

You can find the latest DBD::EmpressNet for your system in:
http://www.empress.com.

You can install both DBD::Empress and DBD::EmpressNet onto your Perl
installation.

------------------------------------------------------------------------

Prerequisites

To install this interface, there are the following prerequisite steps:

1. install perl 5.004

 * the source code for perl 5.004 is freely available from the CPAN sites
(some of which are listed above). Refer to its README file for installation
instructions.

 * NOTE: one area of difficulty which can cause problems in the later steps
is whether you want your version of perl to support dynamic loading of
modules.  Note that on some systems dynamic loading does not work.  If you
choose dynamic loading, and it is broken, then the tests will fail and you
will have to reinstall with this option turned off.

 * make sure you run the built-in tests, and that they pass before
proceeding.

2. install the perl module, DBI 0.89

 * the source code for DBI 0.89 is freely available from the CPAN sites
(some of which are listed above).  Refer to its README file for installation
instructions.

 * make sure you run the built-in tests, and that they pass before
proceeding.

 * some systems do not have dynamic module loading; in this case, you must
the follow the special instructions that come with the DBI module for this
case.

3. install the Interface Driver (libsse.a)

   If you have downloaded the DBD-EmpressNet package from an Internet Site,  
   you will need to add the libdse.a driver library to the lib directory 
   located in the DBD-EmpressNet directory itself. This library is included 
   in the Empress Perl distribution on the Empress CD. However, if you 
   want to use a driver for a different platform. These are available for 
   free from the Empress Web site:

        http://www/product/download.htm


You are now ready to install the DBD::EmpressNet module.

------------------------------------------------------------------------

Installation

The installation of the Empress perl interface proceeds as follows depends
on the type of module loading desired (or available) with your version of
perl. You may choose from either static or dynamic module loading; refer to
the perl documentation for further details.

1. static module loading:

        % perl Makefile.PL LINKTYPE=static
        % make
        % make perl
        % make -f Makefile.aperl inst_perl
        % make install

2. dynamic module loading:

        % perl Makefile.PL
        % make
        % make install

To run the tests:
        % perl test.pl


------------------------------------------------------------------------

How to Use the Empress Interface

Refer to the test program 'test.pl' in the main directory for examples of
the syntax and techniques for using the Empress interface for common types
of database access.
