The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
DBD-Informix-0.25
River stage one • 2 direct dependents • 2 total dependents
/ DBD::InformixTest

NAME

DBD::InformixTest - Test Harness for DBD::Informix

SYNOPSIS

  use DBD::InformixTest;

DESCRIPTION

This document describes DBD::InformixTest for DBD::Informix version 0.25 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 DBD::InformixTest

To use the DBD::InformixTest software, you need to load the DBI software and then install the Informix driver:

        use DBD::InformixTest;

Connecting to test database

        $dbh = &connect_to_test_database;

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 4 environment variables:

        DBD_INFORMIX_DATABASE
        DBD_INFORMIX_SERVER
        DBD_INFORMIX_USERNAME
        DBD_INFORMIX_PASSWORD

The 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 the database name does not contain either slashes or at-signs, then the value in the server variable, which defaults to $INFORMIXSERVER (which must be set for 6.00 and later Informix database systems) is appended to the database name after an at-sign. If INFORMIXSERVER is not set, then you had better be on a 5.0x system as it 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 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 test_sqlca

The &test_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.

        &test_sqlca($dbh);
        &test_sqlca($sth);

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 '!! FAIL !! 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.

        &stmt_fail();

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");

AUTHOR

  • Jonathan Leffler (johnl@informix.com)

SEE ALSO

perl(1), DBD::Informix