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

   Portions Copyright (c) 1994-96 Alligator Descartes
   Portions Copyright (c) 1996-98 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.

---------------------------------------------------------------------------
        ***  Note that DBI 1.00 and above is not alpha code!  ***
---------------------------------------------------------------------------

PREREQUISITES

    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.  Please ensure that you compile it with whatever
    options are necessary to make the C compiler accept prototypes; the
    DBD::Informix code uses prototypes (almost) everywhere.  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.

    If you do not have DBI version 1.00 or later (preferably at least 1.02)
    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.

    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 standard 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, GCC.  You
    should use the same compiler to build Perl and DBI and DBD::Informix.
    Note that Perl 5.005 requires an ANSI C compiler (or, at least, one
    which handles prototypes).

    You must have a version of Informix ESQL/C or Informix ClientSDK
    available to you.  You should read the Informix.Licence file for
    information about what you need.  At the moment, ESQL/C Versions 4.0x
    and 4.1x are not supported by DBD::Informix; nor are any earlier
    versions.  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 and link 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.

                              *** BEWARE ***

    DBD::Informix version 0.61 has been tested on Informix Universal Server
    version 9.14.UC4 (on a Sparc 20 running Solaris 2.6).  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 (sometimes with an assert firing and a core
    dump, but sometimes with an error such as -402 'Address of a host
    variable is NULL') if it encounters one of the IUS-specific data types.
    IUS is also now known as Informix Dynamic Server Universal Data Option,
    or IDS-UDO.

    The pre-IUS data types which are known to work are the following, plus
    their various synonyms:
        SMALLINT, INTEGER, SERIAL
        DATE, DATETIME, INTERVAL
        SMALLFLOAT, FLOAT, DECIMAL, MONEY
        CHAR, VARCHAR (NCHAR, NVARCHAR)
        BYTE, TEXT

    The IUS-specific data types which probably do not work include:
        BOOLEAN, INTEGER8, SERIAL8, LVARCHAR, BLOB, CLOB
        Any user-defined type
        ROW types
        Collection types (SET, LIST, MULTISET)

    Adding support for BOOLEAN, INTEGER8, SERIAL8 and LVARCHAR is high on
    the list of desirable enhancements.  Handling the other types is more
    complex; they represent the antithesis of Perl's untyped variables.

    As an example of the problems, the IUS SysProcedures table in the
    system catalog has a ParamTypes column 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, now
    known as Informix Dynamic Server Extended Parallel Option or IDS-XPO)
    version of ESQL/C and database.  There will probably be few problems,
    but...

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

    DBD::Informix will compile under ClientSDK 2.01.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 and 2.10.UC1, the
    failures in t/t31nulls.t and t/t32nulls.t now pass.

                 *** YOU WERE ALSO WARNED ABOUT THIS ***

    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.

                 *** YOU WERE ALSO WARNED ABOUT THIS ***

    You need to 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 DBA privileges on any databases, you should consider
    creating the 'stores' database using the dbaccessdemoN program (where N
    is a version number, such as 7) which comes with your server.  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 use olipcshm or
    onipcshm (shared memory) connections to both databases.  If you run
    into problems with shared memory connections (for example, error -27000
    from the esqltest program), then read hints/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_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.  You need to ensure that these 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 if you are using version 6.0x
    or later.  You may need to set other environment variables too, such as
    DBPATH to locate your database, especially with SE (eg on Linux).
    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 -- believe it or not,
    I've been bothered by people asking "How do I set the XYZ environment
    variable?", and that irritates me a lot!

    You should take a look at the documentation in InformixTest.pm, and set
    the DBD_INFORMIX_DATABASE, DBD_INFORMIX_USERNAME, DBD_INFORMIX_PASSWORD
    environment variables as appropriate for your system.  Note that
    DBD_INFORMIX_SERVER is no longer used at all.  There is now also a
    parallel set of environment variables (DBD_INFORMIX_DATABASE2,
    DBD_INFORMIX_USERNAME2, DBD_INFORMIX_PASSWORD2), which can be set to
    specify the second test database completely independently of the first.
    Note that 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 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.
    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.

BUILDING DBD::Informix WITH BUNDLES

    If your environment is set up correctly, you can simply type:

        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 run this, the CPAN module will ask you a number of
    questions, including the name of a CPAN site that you wish to download
    the material from, but it remembers this information for the next time.

    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, 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

    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

    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 are not 100%
    clean and can leave the odd table or stored procedure in the database.

    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 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 in your environment -- but you may not report
    any problems whatsoever to anybody if you have this set.

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.  There is a package DBD::Informix4 available from
      Goran Thyni <goran@bildbasen.kiruna.se> (version 0.22 was current in
      August 1997).  I don't have a working URL for this software.

    * 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 hints/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 hints/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

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

    http://www.arcana.co.uk/technologia/perl/DBI

Note that (as of 1998-08-12), the version numbers recorded at this site are
mostly up to date, but they might be a little out of date.  The other
information there is valuable, though.  In case of doubt, go to CPAN
(http://www.perl.com/CPAN/modules/by-module) for the latest versions of any
of the DBI or DBD files.

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 j.leffler@acm.org.

There are 4 types of failures which you might encounter:
    A.  A configuration failure (perl Makefile.PL does not work)
    B.  A build failure (the Makefile was generated but there were problems
        during the build proper so that no test worked at all)
    C.  A general test failure (although the build appeared OK, every
        single test fails, or almost all of them fail).
    D.  A selective test failure (the build appeared OK and most of the
        tests pass, but a few (say 1 to 5) of them fail).
Please classify your problem and follow the relevant steps below.

Please include:

1. A log of a complete build:

    # Before doing anything, please either re-extract the source from the
    # compressed tar file you retrieved from CPAN into an empty directory
    # or make sure that the build area is really clean:
    [ -f Makefile ] && make realclean
    rm -f esql esqlvrsn.h

    # Send this output for all failure types (A, B, C, D)
    perl Makefile.PL

    # Send this output for failure types B, C, D.
    make

    # Send this output for failure types C, D
    # If the output is more than about 30 lines, then just send the first
    # 30 lines or so of the output -- anything more is unlikely to give any
    # extra information.
    make test

    # Send this output for failure types C, D
    # Then, taking the first test which fails (typically basic00.t) send
    # the output from:
    test.one t/basic00.t

    # Send this output for failure type D
    # If the failing tests are failing in distinctly different ways
    # (different error messages, or one is a core dump, or ...) then send
    # the test output for each of the different outputs, but do not send
    # more than 5 sets of test results unless requested to do so.
    test.one t/dbase.t

    If you use a Bourne or Korn Shell (or any work-alikes), you can also
    use the following command to get a lot more debug information, but
    don't send this unless asked to do so:

    PERL_DBI_DEBUG=2 test.one t/basic00.t

    Use this to verify that the problems you are reporting as different for
    failure type D really are different, but still don't send the output
    unless asked to do so.

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; running "esql -V"
   gives the Informix ESQL/C information.  Also, please give the version of
   the Informix database engine which you are using.  This is usually most
   easily done using "dbaccess -V".  More authoritative answers are got by
   running "$INFORMIXDIR/lib/sqlexec -V" for SE, "tbstat -V" for OnLine
   5.0x, or "onstat -V" for other versions of OnLine or for IUS.  The
   software serial number is of little or no use for debugging problems.

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.  Do not send a stack trace
   if it does not contain function names.

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
       dbi-dev@fugue.com

   You should probably subscribe to dbi-users and probably do not need to
   subscribe to dbi-dev.

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 point 3
above, plus the version of the Informix database engine you are using), 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).

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'.
(2) Use temporary tables rather than permanent ones.
(3) Load just enough data to show the problem.
(4) Test every statement using DBI functions 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.

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/basic00.t; it is officially obsolete.  DBD::Informix needs to use 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)

@(#)$Id: README,v 61.6 1998/11/24 03:53:48 jleffler Exp $

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

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>
