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

   Portions Copyright (c) 1994-96 Alligator Descartes
   Portions Copyright (c) 1996-99 Jonathan Leffler
   Portions Copyright (c) 1999-2000 Informix Software
   You may distribute under the terms of either the GNU General Public
   License or the Artistic License, as specified in the Perl README file.

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

PREREQUISITES

    You need the following 5 items to build DBD::Informix:

    1.  Perl 5.004 or later.
    2.  DBI 1.13 or later.
    3.  A C compiler which accepts function prototypes (eg GCC 2.95.2).
    4.  Informix ESQL/C 5.00 or later, or ClientSDK 2.00 or later.
    5.  A 'stores' database to which you can connect without specifying
        username or password, and in which you can create tables.  Ideally,
        the connection should not use shared memory (not olipcshm nor
        onipcshm), and you should have DBA privileges in the database.

    The basic build steps are:

        perl Makefile.PL
        make
        make test
        make install

    If you aren't sure about any of these items, or if one of the build
    steps above fails when you run it, you need to read the information
    below.  The section 'BUILD AND TEST ENVIRONMENT' will help you set your
    environment variables.  If you run into problems during the build or
    test phases, read the section 'IF YOU HAVE PROBLEMS BUILDING
    DBD::INFORMIX'.

    When you have DBD::Informix working *and* installed, please use 'sh
    ItWorks' to report your successful installation.  Please check the
    output file It-Worked (especially the email address it deduces), and
    send it to the maintainers in an email with the subject "DBD::Informix
    - It Works":

            j.leffler@acm.org
            myk@informix.com

PERL

    If you do not have Perl version 5.004 or later, then build, test and
    install it before doing anything else.  You should be using at least
    Perl version 5.004_04 and really should be using Perl 5.005_03.  Please
    ensure that you compile it with whatever options are necessary to make
    the C compiler accept prototypes; the DBD::Informix code uses
    prototypes.  You are also strongly encouraged to
    use the C compiler to create shared libraries, even if the Perl
    configuration script suggests that you use the 'ld' program directly.
    There have been endless problems for people who do not use the C
    compiler to create the shared libraries, and very few for those who do.

    Also note that to install DBD::Informix, you must be able to put files
    under the Perl lib directory.  See the file Notes/nonroot.install for
    alternative options.

DBI

    If you do not have DBI version 1.13 or later installed, then build,
    test and install it.  Although some old versions of DBD::Informix
    allowed you to use older versions of DBI than the version it was built
    with, the current versions do not.

    Note that if the 'perl Makefile.PL' process requires a later version of
    DBI, it means that there's a minor bug in these notes -- use the
    version it says.  Also note that "perl -MCPAN -e 'install Bundle::DBI'"
    will get the latest version.  Similarly, if it rejects your version of
    Perl, it means you should upgrade your Perl.

C COMPILER

    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 bundled compiler does not accept prototypes at
    all, and the ANSI compiler does not accept them unless told to do so).
    If you have problems, get hold of the GNU C Compiler v2.95.2 or later.
    It is available from http://egcs.cygnus.com.  You should use the same
    compiler to build Perl and DBI and DBD::Informix.  Note that Perl 5.005
    requires a C compiler which handles prototypes.

ESQL/C OR CLIENTSDK

    You must have a version of Informix ESQL/C or Informix ClientSDK
    installed on the machine where you wish to compile DBD::Informix.
    Informix Connect is not sufficient.  The Notes/Informix.Licence file
    contains more information about what you need.  ESQL/C Versions 4.1x
    and earlier are not (and will not be) supported by DBD::Informix.
    ESQL/C Versions 5.00 upwards should be OK.  If you do not have ESQL/C
    and are not prepared to buy it, then please don't try to use
    DBD::Informix; it won't work.  You can probably get Informix ClientSDK
    at a reasonable cost.  If you have Informix ODBC drivers available to
    you, consider using DBD::ODBC instead.  If you are on Linux, you should
    investigate the software available from the main Informix web site:

                         http://www.informix.com/
                       http://www.informix.com/idn

    You must also be able to compile, link and run ESQL/C programs with
    your setup.  The Makefile.PL will test that you can do this, but it
    will save you time if you ensure this before hand.  If you cannot
    compile and link free-standing ESQL/C programs, you certainly won't be
    able to hook DBD::Informix into Perl.  If you need help with
    environment variable settings, then consult the information below, and
    also the file Notes/environment.variables.

    DBD::Informix version 1.00 provides limited support for UDTs, treating
    them as CHAR(255). If you need to handle BLOBs and CLOBs, use
    LOTOFILE() when you fetch the data and FILETOBLOB() or FILETOCLOB() 
    when you insert it. If you need to handle non-blob UDTs that exceed 255 
    characters in length, use server-side cast to lvarchar, as in

        select mycol::lvarchar from mytab;

    DBD::Informix will compile under ClientSDK 2.01.UC1 (ESQL/C 9.14.UC1),
    but some tests will fail.  This appears to be a bug in this version of
    ClientSDK.  Working with the same code under ClientSDK 2.02.UC2 (ESQL/C
    9.15.UC2) and 2.10.UC1 (ESQL/C 9.16.UC1), the failures in t/t31nulls.t
    and t/t32nulls.t now pass.

    Most versions of ESQL/C which support shared libraries have shared
    linking as the default behaviour, which is correct.  Other versions
    reportedly have static linking as the default behaviour, which is a
    pain in the posterior.  The Makefile.PL will add the '-shared' flag to
    the ESQL/C command line to try to force shared libraries for ESQL/C
    versions 7.20 and upwards.  If this does not work for you, or if you
    are building a static Perl, you will need to set the environment
    variable DBD_INFORMIX_ESQLC_LINKAGE either to nothing if your version
    of ESQL/C does not support the '-shared' option at all, or to '-static'
    to force static linkage.  You could also use this environment variable
    to bootstrap any special ESQL/C compiler options into the build process
    (eg '-thread' if you are experimenting with threaded Perl and threaded
    ESQL/C); you are advised to set '-static' or '-shared' as well.

STORES DATABASE

    Unless you have a 'stores' database that you can connect to without
    specifying a username or password (and in which you can create tables),
    you will need to set various environment variables to tell the build
    and test code for DBD::Informix which database to use for testing and
    exactly how to connect to it.  For more details on the environment
    variables which can be set, see the section BUILD AND TEST ENVIRONMENT.

    You *must* have a fully working Informix environment before you try to
    build and test DBD::Informix.  This means you need to have access to at
    least one database where you have at least RESOURCE level privileges.
    If you don't understand what this means, read the "Informix Guide to
    SQL: Syntax" manual, and especially the GRANT section.  You can obtain
    a PDF version of any Informix documentation from:

                     http://www.informix.com/answers

    If you don't have RESOURCE (preferably DBA) privileges on a database,
    you should consider creating a database called 'stores' for testing.
    If you do not have DBA privileges, the test t/t55mdata.t will fail.
    Unless you have other problems, you can disregard this failure.

    Note that DBD::Informix testing creates and drops its own tables.  Most
    of the tests use temporary tables.  It doesn't matter whether the test
    database has a database logging or not, though a logged database allows
    more features to be tested than an unlogged database.  You can use a
    brand new, empty database for testing.  When DBD::Informix creates any
    database object, the name begins with "dbd_ix_".  If the test t99clean
    runs, there should be nothing left over from the testing (please report
    any such debris).  DBD::Informix has one test which creates a database
    and then drops it.

SHARED MEMORY CONNECTIONS

    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).  As of version 0.95, the esqltest program will
    report that both connections use shared memory and will allow you to
    proceed after writing a message.  The actual test scripts attempt to
    detect that the two connections both use shared memory connections and
    skip the tests.  However, if you run into problems with shared memory
    connections (for example, error -27000 from the esqltest program), then
    read Notes/olipcshm.  If your databases are not on the machine where
    you are building DBD::Informix, you will need to ensure that you have
    the necessary privileges to connect to the machine where the databases
    are.  This may be as simple as setting DBD_INFORMIX_USERNAME and
    DBD_INFORMIX_PASSWORD (see below); it may be require you to get your
    systems administrators to set you up with a login account on the
    machine.

BUILD AND TEST ENVIRONMENT

    Please ensure that you have $INFORMIXDIR set even if the software is
    installed in /usr/informix, 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.  Starting with version 0.95, you will have the
    absolute pathnames of the Informix shared libraries built into your
    DBD::Informix library by default.  This means that you do not need to
    worry about LD_LIBRARY_PATH, LD_RUN_PATH, SHLIB_PATH or LIBPATH at
    runtime, at least for the Informix shared libraries.  The downside of
    this is that if you change the location of your software, you will need
    to rebuild and reinstall DBD::Informix (or you can mess about with
    symlinks to simulate the original INFORMIXDIR).

    If this is unacceptable, you need to set the environment variable
    DBD_INFORMIX_RELOCATABLE_INFORMIXDIR to some value such as "yes".  This
    will use relative names to identify the Informix shared libraries.  You
    will be warned that this is happening.  At both test time and at run
    time, you need to ensure that the Informix shared libraries will be
    found when you run Perl with DBD::Informix.  On SVR4 and Linux
    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 unless you
    are using version 5.x ESQL/C.  You may need to set other
    Informix-specific environment variables too.  Consult the Informix
    manuals for more information.  And, if you are not yet familiar with
    how to set environment variables, then please get yourself a Unix
    primer (eg "Learning the Unix System, 4th Edition" from O'Reilly,
    http://www.oreilly.com/) and read it.

    You should take a look at the documentation in perlsubs/InformixTest.pl, 
    and set the DBD_INFORMIX_DATABASE, DBD_INFORMIX_USERNAME, 
    DBD_INFORMIX_PASSWORD environment variables as appropriate for your system.
    There is also a parallel set of environment variables with the suffix 2 
    (DBD_INFORMIX_DATABASE2, DBD_INFORMIX_USERNAME2, DBD_INFORMIX_PASSWORD2),
    which can be set to specify the second test database completely 
    independently of the first. You do not have to set any of these 6 
    environment variables if the defaults are OK.  The default database is 
    'stores'; no username and password are supplied if none is specified.  
    If you set the username, you must also set the password to have any effect.
    Although the testing does as little damage as possible, it is not a good 
    idea to use the production database for this.  The stores database is a 
    good bet.  Note that these variables only have significance when running 
    the DBD::Informix tests.  They are not used by DBD::Informix itself, only
    by the InformixTest code.  However, the variables should be set before you
    start the build and not changed until after you complete the testing.
    If you do change them, you should check that the esqltest program run
    by 'perl Makefile.PL' still gives your new environment a clean bill of
    health.

    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.  If the test
    fails, you do not get a Makefile so you cannot build DBD::Informix.

    Note that some tests, notably t/t56tabinfo.t and t57tables.t, will fail
    if you have the DELIMIDENT environment variable set.

BUILDING DBD::Informix WITH BUNDLES

    Assuming that you have pre-configured the Perl CPAN module and
    that your Informix environment is set up correctly, you can install
    DBD::Informix by simply typing:

        perl -MCPAN -e 'install Bundle::DBD::Informix'

    This will go and fetch the latest version of DBI (and its pre-requisite
    modules), and the latest version of DBD::Informix, and compile, test
    and install them all completely automatically.  Before doing this, you
    need to be confident that things will work correctly (or that you've
    got good backups of your Perl installation).  On the other hand, for
    sheer convenience, it takes a lot of beating.  You could even arrange
    to do this once a week via cron, if you wanted to.

    When you first use the CPAN module, it will ask you many questions,
    including the name of the CPAN site that you wish to download the
    material from, but it remembers this information for the next time (and
    it offers you a choice of sites based on continent and country).

    You should consider installing the latest CPAN bundle first:

        perl -MCPAN -e 'install Bundle::CPAN'

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, we are 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 us know so that we can try
    to make it automatic in a later release.

    Then run:

        make test

    Note that testing DBD::Informix does create some tables and databases.
    The database is normally called 'dbd_ix_db', and the table names start
    with 'dbd_ix_'.  Some of the tables are permanent; most are temporary.
    The tests are designed to work whether the tables and database are
    present when the tests start or not; that means they get dropped.  Do
    not run the tests if you have precious tables or databases that begin
    'dbd_ix_'!  As of version 0.61, the cleanup script t/t99clean.t is run
    at the end of the testing.  It removes the tables, views, synonyms, etc
    which might have been created by DBD::Informix.

    On the reference system (Sun Sparc 20 running Solaris 2.6, compiling
    with GCC 2.8.1 or SUNWspro SC4.0.1, using either Perl 5.00404 or 5.00502),
    all the tests pass when DBD::Informix is built with ESQL/C versions
    5.08.UD1, 6.00.UE1, 7.24.UC1 and 9.14.UC1.

    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 many of
    them do check the data which is returned).  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

    Different tests will be skipped depending on the version of ESQL/C, the
    version of the database, and the logging modes of the databases you are
    connecting to.

    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.  You can also test with different
    server versions (eg using 7.2x ESQL/C to connect to a 5.0x OnLine) if
    you have the software available.
	
    Note that the tests should be 100% clean if you run t/t99clean.t, but
    if you don't run that, the tests can leave the odd table or stored
    procedure (or user defined types, etc) in the database.  All permanent
    objects created in any of the databases by any of the DBD::Informix
    tests have names that begin with 'dbd_ix_'.

    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

    Please consult the Notes/Working.Versions file for information about known
    working versions of the software (and specific problem versions).  If
    you are using a combination of versions which is different from any
    previously recorded, please send me (j.leffler@acm.org) the details for
    your new, successful port.

    If you run into major problems even getting the esqltest program to
    compile, you can try compiling the esqlbasic.ec program using a plain
    ESQL/C command:

        esql -o esqlbasic esqlbasic.ec

    If even this will not compile, you need to concentrate on fixing your
    ESQL/C environment before doing anything else with DBD::Informix.  If
    it compiles but does not run, then you need to ensure that you fix the
    Informix environment so that you can access databases.  Once this test
    both compiles and runs, you will probably be able to compile and test
    DBD::Informix.

    You can suppress the esqltest code in Makefile.PL by setting
    DBD_INFORMIX_NO_ESQLTEST=yes in your environment before you run 'perl
    Makefile.PL'.  However, no problem reports will be accepted if you do that;
    the esqltest code is critical to ensuring that DBD::Informix has some 
    chance of compiling successfully.

    You can see how the esqltest code is compiled if you set
    DBD_INFORMIX_DEBUG_ESQLTEST=yes in your environment before you run
    'perl Makefile.PL'.

    For more information on environment variables for both DBD:Informix and
    Informix, see the file Notes/environment.variables.

KNOWN PROBLEMS:

    * DBD::Informix does not work, and never will work, with ESQL/C Version
      4.0x or 4.1x.  There is a package DBD::Informix4 available from Goran
      Thyni <goran@bildbasen.kiruna.se> (version 0.23 is current at
      1999-12-31 and is available from CPAN).

    * Problems have been encountered on HP-UX (both 9.x and 10.x) when
      building DBD::Informix using 5.x and 6.x ESQL/C.  This seems to be
      because the Informix products either do not have shared libraries at
      all or have shared libraries which the HP-UX compilers and loader do
      not accept.  It seems that the only way to build DBD::Informix on
      HP-UX with 5.x or 6.x ESQL/C is to build a statically linked version
      of Perl with the Informix libraries included.  This is a defect in
      ESQL/C rather than Perl, DBI or DBD::Informix.  If you know how to
      build DBD::Informix on HP-UX with version 5.x (or 6.x) ESQL/C without
      doing it statically, please tell everyone.

    * Compiling on HP-UX 10.20 has been problematic.  Please see the
      guidelines in Notes/hpux-10.20 which were supplied by Reed White
      (REED_WHITE@HP-Corvallis-om1.om.hp.com).  Note that the non-ANSI C
      compiler distributed with HP-UX base package is not usable for
      DBD::Informix because it does not accept prototypes.

    * 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 and HP-UX
      10.20 in particular, but probably on other platforms too), 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.  Please read the
      file Notes/eprintf (contributed by Bernd Gill <bernd@dsi.co.nz>).
      You can work around it by setting DBD_INFORMIX_USE_EPRINTF_CODE in
      the environment before running 'perl Makefile.PL'.  You could also
      consider adding DBD_INFORMIX_DISABLE_ASSERT (which also gets rid of
      the __eprintf() problem by disabling any assertions; __eprintf() is
      used by the GNU assert macro).

    * Do not use the GNU assembler or loader with GCC on Solaris; they
      don't work properly with shared libraries.  Remove them and rebuild
      and reinstall GCC immediately.

IF YOU HAVE PROBLEMS BUILDING DBD::INFORMIX

Read the file Notes/bug.reports which describes what to do and where to
send the failure report.  Please ensure that any email message has
DBD::Informix in the subject line -- thanks!

IF YOU HAVE PROBLEMS USING DBD::INFORMIX

If your problem is with your own code and the DBD::Informix tests all pass,
then the initial message should give the version information (see the
Notes/bug.reports file), a description of the problem, a minimal test
script, and the results of running the test script on your machine (along
with an explanation of why the result is wrong -- it may not be obvious to
me -- and what the correct result should be).  Please ensure that any email
message has DBD::Informix in the subject line -- thanks!

The minimal test script should preferably:

(1) Use the stores database, with empty username and password fields.  If
    the test needs a particular type of database (eg with transactions) to
    demonstrate the problem, alternative convenient names are 'logged',
    'unlogged' and 'mode_ansi'.  If you are using SE, please mention that.
(2) Use temporary tables rather than permanent ones.
(3) Load just enough data to show the problem.
(4) Test every statement that uses a DBI function for success.
(5) Clearly indicate when it fails.
(6) Clearly indicate when it passes.
(7) It had better not use DBI->install_driver() without an extremely good
    reason, and I can't immediately think of a reason which would be good
    enough.  It should use the DBI->connect("dbi:Informix:...", ...) form
    for connecting.

If your test is failing with a core dump, the stack trace for it is useful
if it lists function names -- it is not useful if it does not.

SAMPLE CODE

The tests which come with DBD::Informix show a variety of ways of using
DBD::Informix.  Do not use the connection method shown in the code for test
t/t83oconn.t; it is officially obsolete.  DBD::Informix needs to test it, but
you should not.

There are some simple examples of DBI scripts for Informix databases in the
examples sub-directory.  Read the examples/README file for more details.

Remember -- it is supposed to be fun!

Jonathan Leffler (j.leffler@acm.org)
Michael Kopchenov (myk@informix.com)

@(#)$Id: README version /main/57 2000-01-19 11:51:49 $

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

Original document: (c) Tim Bunce <Tim.Bunce@ig.co.uk>
Amendments 1:      (c) Alligator Descartes <descarte@arcana.co.uk>
Amendments 2:      (c) Jonathan Leffler <johnl@informix.com>
Amendments 3:      (c) Jonathan Leffler <j.leffler@acm.org>
Amendments 4:      (c) Jonathan Leffler <jleffler@informix.com>
Amendments 5:      (c) Informix Software
