NAME
Test Harness for DBD::Informix
SYNOPSIS
require "perlsubs/InformixTest.pl";DESCRIPTION
This document describes the InformixTest.pl collection of subroutines for testing DBD::Informix version 0.62 and later. This is pure Perl code which exploits DBI and DBD::Informix to make it easier to write tests. Most notably, it provides a simple mechanism to connect to the user's chosen test database and a uniform set of reporting mechanisms.
Loading the InformixTest Subroutines
To use the InformixTest software, you need to load the DBI software and then install the Informix driver:
require "perlsubs/InformixTest.pl";Connecting to test database
$dbh = &connect_to_test_database({ AutoCommit => 0 });This gives you a reference to the database connection handle, aka the database handle. If the load fails, your program stops immediately. The functionality available from this handle is documented in the DBD::Informix manual page. This function does not report success when it succeeds because the test scripts for blobs, for example, need to know whether they are working with an OnLine system before reporting how many tests will be run.
This code exploits 3 environment variables:
DBD_INFORMIX_DATABASE
DBD_INFORMIX_USERNAME
DBD_INFORMIX_PASSWORDThe database variable can be simply the name of the database, or it can be 'database@server', or it can be one of the SE notations such as '/opt/dbase' or '//hostname/dbase'. If INFORMIXSERVER is not set, then you had better be on a 5.0x system as otherwise the connection will fail. With 6.00 and above, you can optionally specify a user name and password in the environment. This is horribly insecure -- do not use it for production work. The test scripts do not print the password.
Using cleanup_database
If the test needs a clean database to work with, the cleanup_database method removes any tables, views, synonyms (or IUS types) created by the DBD::Informix test suite. These are all identified by the 'dbd_ix_' prefix.
&cleanup_database($dbh);This is not used in all tests by any stretch of the imagination. Whereever possible, tests should use temporary tables.
Using test_for_ius
If the test explicitly requires Informix Universal Server (IUS) or IDS/UDO (Informix Dynamic Server with Universal Data Option -- essentially the product as IUS, but with a longer, more recent, name), then the mechanism to use is:
my ($dbh) = &test_for_ius();If this returns, then the ESQL/C is capable of handling IUS data types, the database connection worked, and the database server is capable of handling IUS data types.
Using stmt_test
Once you have a database connection, you can execute simple statements (those which do not return any data) using &stmt_test():
&stmt_test($dbh, $stmt, $flag, $tag);The first argument is the database handle. The second is a string containing the statement to be executed. The third is optional and is a boolean. If it is 0, then the statement must execute without causing an error or the test will terminate. If it is set to 1, then the statement may fail and the error will be reported but the test will continue. The fourth argument is an optional string which will be used as a tag before the statement when it is printed. If omitted, it defaults to "Test".
Using stmt_retest
The &stmt_retest() function takes three arguments, which have the same meaning as the first three arguments of &stmt_test():
&stmt_retest($dbh, $stmt, $flag);It calls:
&stmt_test($dbh, $stmt, 0, "Retest");Using print_sqlca
The &print_sqlca() function takes a single argument which can be either a statement handle or a database handle and prints out the current values of the SQLCA record.
&print_sqlca($dbh);
&print_sqlca($sth);Using print_dbinfo
The &print_dbinfo() function takes a single argument which should be a database handle and prints out salient information about the database.
&print_dbinfo($dbh);Using all_ok
The &all_ok() function can be used at the end of a test script to report that everything was OK. It exits with status 0.
&all_ok();Using stmt_ok
This routine adds 'ok N' to the end of a line. The N increments automatically each time &stmt_ok() or &stmt_fail() is called. If called with a non-false argument, it prints the contents of DBI::errstr as a warning message too. This routine is used internally by stmt_test() but is also available for your use.
&stmt_ok(0);Using stmt_fail
This routine adds 'not ok N' to the end of a line, then reports the error message in DBI::errstr, and then dies. The N is incremented automatically, as with &stmt_ok(). This routine is used internally by stmt_test() but is also available for your use. It takes an optional string as an argument, which is printed as well.
&stmt_fail();
&stmt_fail("Reason why test failed");Using stmt_err
This routines prints a caption (defaulting to 'Error Message') and the contents of DBI::errstr, ensuring that each line is prefixed by "# ". This routine is used internally by the InformixTest module, but is also available for your use.
&stmt_err('Warning Message');Using stmt_note
This routine writes a string (without any newline unless you include it). This routine is used internally by stmt_test() but is also available for your use.
&stmt_note("Some string or other");Using select_some_data
This routine takes three arguments:
&select_some_data($dbh, $nrows, $stmt);The first argument is the database handle. The second is the number of rows that should be returned. The third is a string containing the SELECT statement to be executed. It prints all the data returned with a '#' preceding the first field and two colons separating the fields. It reports OK if the select succeeds and the correct number of rows are returned; it fails otherwise.
Using select_zero_data
This routine takes a database handle and a SELECT statement and invokes &select_some_data with 0 rows expected.
&select_zero_data($dbh, $stmt);Note
All these routines can also be used without parentheses or the &, so that the following is also valid:
select_zero_data $dbh, $stmt;AUTHOR
At various times:
Jonathan Leffler (johnl@informix.com)
Jonathan Leffler (j.leffler@acm.org)
SEE ALSO
perl(1), DBD::Informix