README for DBD::Informix -- an Informix interface for Perl 5 using DBI.

   Portions Copyright (c) 1994,1995,1996  Alligator Descartes
   Portions Copyright (c) 1996            Jonathan Leffler

   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!

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

BUILDING DBD::Informix

    If Perl 5.003 or later is NOT installed, then build, test and install it!

    If the DBI module (version 0.73 or later preferred; 0.69 or later is
    mandatory) is not installed, then build, test and install it.

    You must have a version of ESQL/C available to you.  At the moment,
    version 4.0x or 4.1x are not supported.  Versions 5.00 and 5.01 have a
    bug in them which makes them unsupported too.  If someone wants to code
    up the fix necessary to get versions 4 or 5.0[01] to work, then contact
    the DBD::Informix Maintenance Team.  ESQL/C Versions 5.02 upwards
    should be OK.  Please ensure that you have $INFORMIXDIR set, and that
    $INFORMIXDIR/bin is on your PATH.  The build may work without these
    environment variables being set, but it will be more reliable if they
    are.

    When Perl, DBI and ESQL/C are all installed do:

        perl Makefile.PL

    The script will attempt to work out what it needs to build the module.
    Then do:

        make

    This should complete without errors, and ideally without warnings
    either.  If you get warnings, I'm interested to know what they are and
    how they could be fixed generically.  If it fails horribly, see below.

    Do NOT hand edit the generated Makefile unless you are completely sure
    you understand the implications (and are willing to make those changes
    manually every time the Makefile is regenerated)!  Always try to make
    changes by editing Makefile.PL, which is extensively annotated.  You
    should also read the section on ExtUtils::MakeMaker in the 2nd Edition
    of 'Programming Perl'.

    You should never 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.

    You should then take a look at the documentation in InformixTest.pm,
    and set the DBD_INFORMIX_* environment variables as appropriate for
    your system.  Although the testing does as little damage as possible,
    it is not a good idea to use your prize database for this.  The stores
    database is a good bet (unless you are using an old version of Fourgen
    software and it is using the stores database for its data dictionary).
    Then run:

        make test

    On the reference system (Sun Sparc 10 running Solaris 2.4, compiling
    with GCC 2.7.0 or SUNWspro SC3.0.1), all the tests pass for ESQL/C
    versions 5.03.UC1, 5.07.UC1, 6.00.UC1, 7.13.UC1 and 7.21.UC1.
    Nevertheless, it is a good idea to run:

        make test TEST_VERBOSE=1

    You should inspect the results as not every test compares the actual
    data returned with the data that should be returned (though t/basic00.t
    does do this).  Note that the blob tests pass on SE, because the test
    scripts detect that the engine is SE and do not try to test blob
    handling.

KNOWN PROBLEMS:

    * DBD::Informix uses SQL DESCRIPTORS which are not part of ESQL/C
      Version 4.0x or 4.1x.  It also uses string-named cursors and
      statements, which are likewise not supported in 4.0x or 4.1x (or
      earlier) versions.

    * A bug in the 5.00 and 5.01 implementation of SQL DESCRIPTORS means
      that these versions are not suitable either.

    * Some desirable features are not implemented.  A number of these are
      listed in the POD file.
	  
    * Some Oracle-inspired functions which are listed as part of DBI are
      not implemented for lack of sufficient definition of what is actually
      required.

    * Some problems have been encountered on HP-UX 9.x when building shared
      libraries using 5.0x ESQL/C.  This seems to be because the HP-UX
      compilers and loader do not accept code not compiled for shared
      libraries inside a shared library.  Help (or reassurance) is needed
      on this.

    * Some problems have been encountered on SCO which seems to be related
      to the equivalent of LD_LIBRARY_PATH on System V Release 4 machines.
      Again, help or reassurance is needed on this.

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

Error: Undefined symbols __cg92_used at link time.
Environment:  Solaris, GCC

If you compile with the SparcWorks SPARCompiler, you need to add the
command line option on -xcg92 to resolve these symbol problems cleanly.

Alligator Descartes <descarte@hermetica.com>

JL notes: the detailed compiler versions are not known, but SC3.0.1 has not
shown any problems on Solaris 2.4.

This was originally reported for DBD::Oracle; may be relevant to some
versions of Informix-ESQLC on Solaris.  Versions 5.00 through 5.03 of
ESQL/C on Solaris 2.3 used libraries with names of the form libsql_cg92.a
and you may run into problems with these.  (Notably, Makefile.PL will warn
you that your ESQL/C may not be properly installed, even though it actually
is OK.)

Separately, for some reason, the STMT_START and STMT_END macros are not
being created using the 'if (1) ... else (void)0' version of the macros on
Solaris 2.4 with SPARCompiler version 3.0.1, even when -Dsun=1 or -D__sun__
is used on the command line.  I have not managed to figure out why.  This
leads to unwanted warnings about loop termination code not being reached.
JL 96-11-19

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

IF YOU HAVE PROBLEMS:

Firstly, check the Frequently Asked Questions, Known Bugs and any other
pertinent documents at:

    http://www.hermetica.com/technologia/DBI

If this does *not* resolve your problem, please post the details of your
problem to dbi-users@fugue.com and CC them to me at johnl@informix.com.
Please include:

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

    perl Makefile.PL           (do a make realclean first)
    make
    ./test.pl
    PERL_DBI_DEBUG=2 ./test.pl

2. A complete, sorted dump of your environment:

    env | sort

3. Full details of which version of Informix-ESQL/C and Perl you're using.

4. The output of:
    perl -e 'use Config; print Config::myconfig()'

5. If you get a core dump, try to include a stack trace from it.  If the
   stack trace mentions XS_DynaLoader_dl_load_file then rerun make test
   after setting the environment variable PERL_DL_DEBUG to 2.  Similarly,
   get the Devel::CoreStack module and use it.

6. Please don't post problems to comp.lang.perl.misc or perl5-porters.

7. If you are not currently subscribed to the mailing list please subscribe
   via http://www.fugue.com/dbi.  If you do not have WWW access, then send
   email to dbi-request@fugue.com.  There are 3 mailing lists:
   dbi-announce@fugue.com, dbi-users@fugue.com and dbi-dev@fugue.com.

Regards,
Tim & Al & Jonathan

@(#)$Id: README,v 25.3 1996/12/09 21:03:25 johnl Exp $ 

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

NOTE: This document is derived from the DBD::Oracle README.  Many of the
points made in that will apply to DBD::Informix too.

Original document: (c) Tim Bunce <Tim.Bunce@ig.co.uk>
Amendments 1:      (c) Alligator Descartes <descarte@hermetica.com>
Amendments 2:      (c) Jonathan Leffler <johnl@informix.com>
