Notes on Submitting Bug Reports for DBD::Informix
=================================================
EMAIL ADDRESS FOR REPORTING PROBLEMS WITH DBD::INFORMIX
dbd.informix@gmail.com
IF YOU HAVE PROBLEMS BUILDING DBD::INFORMIX
First, read the README file and other documentation in the DBD::Informix
distribution area. This includes the Notes sub-directory and the various
documentation files in there, such as the FAQ file and the various specific
platform files and even the Working.Versions file. You are apt to get curt
responses to your questions if the information you need is available in the
documentation. Since you're reading this file, there is a good chance you
either are doing this or already have done this. Thank you!
Next, check the Frequently Asked Questions, Known Bugs and any other
pertinent documents at:
http://dbi.perl.org/
At one time, the version numbers recorded at this site were out of date
at times, but they are now (since September 1999) usually correct. 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@perl.org and CC them to the maintainer(s) at
dbd.informix@gmail.com, using one of the two methods outlined below.
For information on how to subscribe to (and unsubscribe from) the
dbi-users mailing list, send a message to dbi-users-help@perl.org.
Please ensure that any email message has DBD::Informix in the subject line.
Thanks!
FAILURE CLASSES
There are 4 classes 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).
You need to classify your failure into one of these four classes, and then
follow either the STANDARD FAILURE REPORT METHOD or the MANUAL FAILURE
REPORTING METHOD.
STANDARD FAILURE REPORTING METHOD
You need to classify your failure report as class A, B, C, or D -- see
the description of FAILURE CLASSES above. Let's suppose you've got a
problem with the test t/t75blob.t (only), so it is a Class D failure.
If you use a civilized (Bourne, Korn, Born-Again) shell, then you use:
perl BugReport D t/t75blob.t 2>&1 | tee bugreport.out
If you're a C shell die-hard, then you use:
perl BugReport D t/t75blob.t |& tee bugreport.out
You can then submit the output file bugreport.out as the supporting
material for your bug report.
Note that if you specify a failure class, the BugReport script assumes
it is OK to redo the complete configuration, build and test of
DBD::Informix. If this is not a valid assumption, then you need to
follow the manual failure reporting method. If you do not specify a
failure class, it simply reports the environment and version numbers.
Also note that the script deliberately hides the passwords in the
environment. The actual values are not of any interest in bug
reporting, though their presence or absence can be important. This
saves you having to edit the environment (see step 2 of the manual
failure reporting method).
Also note that the BugReport script does not attempt to create a stack
trace from a core dump. If you have a core dump, please do that
manually.
MANUAL FAILURE REPORTING METHOD
This section describes the information that is generated automatically by
the BugReport Perl script. This clarifies what the BugReport script does.
Please include:
1. 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.
New requirement (v0.62): please include the line or lines from the
sqlhosts file which applies to the database(s) you are using.
2. A complete, sorted dump of your environment:
env | sort
Before sending the output, replace the value of DBD_INFORMIX_PASSWORD or
DBD_INFORMIX_PASSWORD2 with a string of 8 X's.
3. 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 t00basic.t) send
# the output from:
test.one.sh t/t00basic.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.sh t/t05dbase.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:
DBI_TRACE=9 test.one t/t00basic.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.
4. 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.
WHERE TO SEND FAILURE REPORTS
For information on Informix Technical Support, please run:
perldoc DBD::Informix::TechSupport
If you are not currently subscribed to the DBI users' mailing list, then
please subscribe via http://dbi.perl.org/, or for information on how to
subscribe via email, send email to dbi-users-help@perl.org.
There are 3 mailing lists:
dbi-announce@perl.org
dbi-users@perl.org
dbi-dev@perl.org
You should probably subscribe to dbi-users and probably do not need to
subscribe to dbi-dev unless you are planning to write your own DBD driver.
(If you want to take over the maintenance of DBD::Informix, let me know!)
Please don't post problems with DBD::Informix to comp.lang.perl.misc or
perl5-porters because they probably will not be seen by anyone able to
answer them (but comp.lang.perl.modules might provide an answer).
Questions asked in the comp.databases.informix news group will usually
be answered.
Please don't try to email Tim Bunce directly, either. He's an expert in
many fields, but Informix is not one of those fields.
Go through the proper channels, which means the dbi-users@perl.org
mailing list or the dbd.informix@gmail.com mail alias.
---------------------------------------------------------------------------
Copyright 1999 Jonathan Leffler
Copyright 2000 Informix Software Inc
Copyright 2002 IBM
Copyright 2005 Jonathan Leffler
Jonathan Leffler (jleffler@us.ibm.com)
@(#)$Id: bug.reports,v 100.7 2005/07/06 20:13:27 jleffler Exp $