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
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
You need the following 5 items to build DBD::Informix successfully:
1. Perl 5.004 or later.
2. DBI 1.08 or later.
3. A C compiler which accepts function prototypes (eg GCC or EGCS).
4. Informix ESQL/C 5.00 or later, or ClientSDK.
5. A 'stores' database to which you can connect without specifying
username or password, and in which you can create tables.
The default 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'.
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 (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.
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.08 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 EGCS C Compiler v1.1.2 or later.
This is the official successor to GCC as of 20th April 1999, and 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 an ANSI C compiler (or, at least, one 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.
*** 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' or a verbose message about an unrecognized data type
being treated as a null value) 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 work are:
BOOLEAN, INTEGER8, SERIAL8, LVARCHAR
The IUS-specific data types which probably do not work include:
BLOB, CLOB
Any user-defined type
ROW types
Collection types (SET, LIST, MULTISET)
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 (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.
*** 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 ***
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.
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), 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 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. 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 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! Yes,
I have been asked "How do I set the XYZ environment variable?"
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 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
your prize 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 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. If the test
fails, you do not get a Makefile so you cannot build DBD::Informix.
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 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 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 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.
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'. 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!
This README has grown huge and paranoid because there are lots of little
details which people don't necessarily think of, but which can make the
difference between working code and broken code.
Jonathan Leffler (j.leffler@acm.org)
@(#)$Id: README,v 62.4 1999/09/19 21:43:55 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>