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

   Portions Copyright (c) 1994,1995,1996  Alligator Descartes
   Portions Copyright (c) 1996,1997       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!

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

PREREQUISITES

    If you do not have Perl version 5.003 or later, then build, test and
    install it before doing anything else!  And please ensure that you
    compile it with whatever options are necessary to get __STDC__ defined.

    If you do not have DBI version 0.81 or later installed, then build,
    test and install it.  Note that previous versions of DBD::Informix
    allowed you to use older versions of DBI than the version it was built
    with.  This policy changed with DBD::Informix v0.54.  In addition,
    the code uses ChopBlanks introduced in DBI 0.81.

    To build DBD::Informix, the C compiler must accept function prototypes.
    This is not a problem on any machine to which Informix is currently
    ported (though the HP-UX compiler does not accept prototypes unless
    told to do so).

    You must have a version of Informix-ESQL/C available to you.  You
    should read the Informix.Licence file for information about what you
    need.  At the moment, ESQL/C Versions 4.0x or 4.1x are not supported,
    nor are any earlier versions.  ESQL/C Versions 5.00 upwards should be
    OK.

    *** BEWARE ***

    DBD::Informix version 0.54 has been tested on Informix-Universal Server
    version 9.10.UC2 (on a Sparc 20 running Solaris 2.5.1).  Where the IUS
    database uses the same types as were available in earlier versions of
    Informix products, there doesn't seem to be any problem.  However, it is
    known to fail badly (usually with an assert firing and a core dump) if it
    encounters one of the IUS-specific data types.

    The IUS SysProcedures table in the system catalog has a ParamTypes column
    which is of the type RtnParamTypes, and therefore DBD::Informix will not
    work if you try to select all the columns from this table.  There are
    probably other columns in the system catalog for which this is true.  And
    there may be other tables which won't work for the same reason.

    *** YOU WERE WARNED ***

    DBD::Informix has never been tested with a version 8.x (OnLine XPS)
    version of ESQL/C and database.

    *** YOU WERE WARNED ABOUT THIS TOO ***

    You need to have a fully working Informix environment before you try to
    build and test DBD::Informix.  This means that you will need to have
    access to at least one database where you have at least RESOURCE level
    privileges.  You should consider creating the 'stores' database using
    the dbaccessdemoN program (where N is a version number, such a 7) which
    comes with your server if you don't have DBA privileges on any
    databases.  The multiple connection tests use two databases for
    preference (though the tests will use the same database twice if you do
    not specify two separate databases) and the test will fail if you try
    using olipcshm (shared memory) connections to both databases.  If your
    databases are not on the machine where you are building DBD::Informix,
    you need to ensure that you have the necessary privileges to connect to
    the machine where the databases are.

    Please ensure that you have $INFORMIXDIR set, and that $INFORMIXDIR/bin
    is on your PATH.  The build no longer works unless these environment
    variables are set.  Also, if you are using ESQL/C version 6.x or later,
    you may be using ESQL/C shared libraries which are found in
    $INFORMIXDIR/lib and $INFORMIXDIR/lib/esql.  You need to ensure that
    these will be found when you run Perl with DBD::Informix.  On SVR4
    machines, this means adding these directories to LD_LIBRARY_PATH; on
    HP-UX, the variable is SHLIB_PATH; other systems may have other
    variable names.  You need to set INFORMIXSERVER correctly if you are
    using version 6.0x or later.  You may need to set other environment
    variables too -- consult the Informix manuals for more information.

    You should take a look at the documentation in InformixTest.pm, and set
    the DBD_INFORMIX_DATABASE, DBD_INFORMIX_USERNAME, DBD_INFORMIX_PASSWORD
    and DBD_INFORMIX_SERVER 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).
    Note that these variables only have significance when running the
    DBD::Informix tests.  They are not used by DBD::Informix itself, only
    by DBD::InformixTest.

    One step in the setup process tests that you have permissions on the
    databases which will be used by the testing.  It does this by compiling
    and running a relatively simple ESQL/C program which simply opens a few
    databases, creates and drops some tables, and exits.

BUILDING DBD::Informix

    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 to the generated Makefile,
    nor to Makefile.PL.  If you do *please* let me know so that I can try
    to make it automatic in a later release.

    Then run:

        make test

    On the reference system (Sun Sparc 10 running Solaris 2.5.1, 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.

    Additionally, for a really thorough scrutiny of DBD::Informix, you need
    to test with at least 3 different databases: one created MODE ANSI, one
    created with a transaction log but not MODE ANSI, and one created
    without any transaction logs at all.

        DBD_INFORMIX_DATABASE=mode_ansi make test
        DBD_INFORMIX_DATABASE=logged    make test
        DBD_INFORMIX_DATABASE=unlogged  make test

    If you are concerned about both OnLine and SE, then you need these
    databases for both environments.  Also note that the multiple
    connection tests will use two different databases if you set the
    environment variable DBD_INFORMIX_DATABASE2, but the tests assume that
    you don't need to specify the user and password.  This could be fixed,
    but hasn't happened yet.  You can use one SE and one OnLine database
    for the multiple connection testing.

    Once you are satisfied that DBD::Informix is working correctly, you
    should install it:

        make install

    If you ever need to remove it, possibly as a preamble to installing a
    new version, you should use the old version's makefile and run:

        make uninstall

    You can then install using the new version's makefile.  It is important
    to use the correct (old or new) makefiles because the installed files
    may be different, and if some file is made obsolete by the new version
    (is not used by the new version), its makefile will not uninstall the
    obsolete file; over time and multiple versions, this could, eventually,
    lead to 'coronary thrombosis' on your disk drive -- or disk full.

    If you run into problems which suggest that the ESQL/C you have won't
    work as dynamically loaded libraries (eg on HP-UX or SCO), then you
    should create a statically linked version of Perl with DBD::Informix
    linked to it.  Use:

        make perl
        make test_static

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.

    * 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 and 6.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.

    * If you are using GCC to compile the software on Solaris, ensure that
      you also use GCC to build the shared libraries, rather than trying to
      use 'ld'.  If you use ld instead, you are likely to run into problems
      with an undefined symbol __eprintf.  If you have this problem, the
      fix is usually to reconfigure (and therefore rebuild) Perl to use GCC
      to create the shared libraries.  It is not clear why using GCC gives
      this problem.

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

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:

    perl Makefile.PL           (do a make realclean first)
    make
    make test
    make test TEST_VERBOSE=1

    You can also use (with Bourne/Korn Shells) to get a lot more debug
    information, but don't send this unless asked to do so:

    PERL_DBI_DEBUG=2 make test TEST_VERBOSE=1

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.
   The output of "perl -V" gives the Perl information.

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,
Jonathan Leffler (johnl@informix.com)

@(#)README	54.3 97/05/14 17:19:54

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

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>
