DBD::Solid -- DBD module interfacing the SOLID database.

   $Id: README,v 1.2 1997/03/20 01:11:25 tom Exp $
   Copyright (c) 1997  Thomas K. Wenrich
   portions Copyright (c) 1994,1995,1996  Tim Bunce

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

   PLEASE READ THE ENTIRE README FILE CAREFULLY !

*  WARNING: THIS IS MOSTLY ALPHA SOFTWARE. Your mileage may vary.       *

*  Most of the code (and most parts of this README) were stolen from the 
*  DBD-Oracle distribution. 
*  However, any Bugs and errors herein are most likely my fault, not 
*  those of Tim Bunce.

*BEFORE* BUILDING, TESTING AND INSTALLING this you will need to:

    Build, test and install Perl 5 (at least 5.003).
    It is very important to TEST it and INSTALL it!

    Build, test and install the DBI module (at least DBI 0.73).
    It is very important to TEST it and INSTALL it!

    Remember to *read* the DBI README file!

    Install the SOLID RDBMS software.

    Install the SOLID SQL API files somewhere.
	Makefile.PL searches those files
	   1. below the directory pointed to by the SOLIDDIR environment
	      variable.
           2. below the home directory of the 'solid' user.
	   3. below /usr/local.

BUILDING:

	perl Makefile.PL
	make

This will build a static(!) perl binary. Unfortunately, the SOLID 
client library isn't compiled using '-fpic', so I suspect some 
troubles when loading this code dynamically.

However, there are already some people running dynamic loaded 
DBD::Solid. In the case you want to try this (but I *do not* 
recommend it), you you may
  a) comment the line "%opts{LINKTYPE}='static'" in Makefile.PL.
  b) create the symlink "libsolcli.a => solcli.a" (or however the
     name of your library is) in the directory where the Solid 
     lib resides.

If you have problems see the 'IF YOU HAVE PROBLEMS' section below.
If it builds without error you can then run the tests. For the
main test to work it must be able to connect to a SOLID database.

Don't worry about most warnings, specifically "end-of-loop code not
reached", "ANSI C forbids braced-groups within expressions", "cast
increases required alignment of target type".

TESTING
	
    The supplied test will connect to the database using the value of the
    SOLID_USER environment variable so you should set that to the correct
    value before starting the test. Don't forget to CREATE the user (see
    SOLID Server documentation) when you aren't using an existing 
    database user.

    When you want to use a remote SOLID server or have more than one
    SOLID Server running then you must set the SOLID_DSN environment
    variable to connect to the database.

    Example (assuming a UNIX machine):
	prompt> SOLID_USER="perltest perltest"
	prompt> SOLID_DSN="TCP/IP myhost.mydomain 1313"
	prompt> export SOLID_USER SOLID_DSN

    Test your settings by connecting to the database using the solsql
    tool supplied with SOLID:

	prompt> solsql $SOLID_DSN $SOLID_USER

    This should connect you to the SOLID server. Once you can do
    that then you can test DBD::Solid knowing that it should work.

	make test
	make test TEST_VERBOSE=1   (if any of the t/* tests fail)

	make install 		   (if the tests look okay)


IF YOU HAVE PROBLEMS:

Do not hand edit the generated Makefile unless you are completely sure
you understand the implications! Always try to make changes via the
Makefile.PL command line and/or editing the Makefile.PL.

You should not need to make any changes. If you do *please* let me
know so that I can try to make it automatic in a later release.

Please don't post problems to comp.lang.perl.misc or perl5-porters.
This software is supported via the dbi-users mailing list.  For more
information and to keep informed about progress you can join the a
mailing list via http://www.fugue.com/dbi (if you are unable to use the
web you can subscribe by sending a message to dbi-request@fugue.com, it
may take a few days to be processed).

Please post details of any problems (or changes you needed to make) to
dbi-users@fugue.com and CC them to me at wenrich@ping.at. But note...

** IT IS IMPORTANT TO INCLUDE THE FOLLOWING INFORMATION:

1. A complete log of a all steps of the build, e.g.:

	perl Makefile.PL           (do a make realclean first)
	make
	make test
	make test TEST_VERBOSE=1   (if any tests fail)

2. Full details of which software you are using:

	* Linux kernel version
	* libc version (!!) currently installed
	* Solid versions (of server and development system)
	* Perl version (the output of perl -V)

It is important to check that you are using the latest version before
posting. If you're not then I'm *very* likely to simply say "upgrade to
the latest". You would do yourself a favour by upgrading beforehand.

Please remember that I'm _very_ busy. Try to help yourself first,
then try to help me help you by following these guidelines carefully.

Regards,
Thomas.

===============================================================================
Examples and other info:

SOLID 'home page': http://www.solid.fi

DBI 'home page': http://www.hermetica.com/technologia/DBI

Master archive site for Perl DB information:
    ftp://ftp.demon.co.uk/pub/perl/db/

Mailing list archive:                /DBI/perldb-interest/

Searchable index of the dbi-users mailing list:
http://www.coe.missouri.edu/~faq/lists/dbiusers/

End.
