Oninit® ifxTAP — Install

Status: pre-release. ifxTAP is built from its source tree; there is no download yet. Ask us for the source.

Prerequisites

Installation prerequisites
Item	Requirement
Server	Informix 14.10.FC13W7 or later (tested on 14.10.FC13W7 and 15.0.1.0.3). Earlier releases should work too: see Tested versions below
Database	Logged: unbuffered, buffered or ANSI (all three tested). Unlogged databases are refused
Privilege	RESOURCE in the test database is enough to install the library and to run tests that create objects. CONNECT is enough for tests that need no DDL. DBA is needed to create objects under another owner (for example `CREATE TABLE other.t`) and to uninstall a library installed by another user; looking at, or calling, objects that already exist under another owner depends on the privileges granted on them
Java	11 or later (tested on 11, 17 and 25)
JDBC driver	IBM Informix JDBC 4.10.16 or later, supplied by you (tested with 4.10.16, 4.50.3, 4.50.10 and 15.0.1.3). Older drivers should work too
Locale	`en_US.819` and `en_US.utf8`; others best effort

Tested versions

What the test suite has been run against
Informix server	JDBC driver	Java	Result
15.0.1.0.3	4.10.16, 4.50.3, 4.50.10, 15.0.1.3	11, 17, 25	Passes (every combination)
14.10.FC13W7	15.0.1.3	11, 17, 25	Passes
14.10.FC13W7	4.10.16, 4.50.x	—	Not tested: the server we have refused those drivers’ login, which is a setup problem on our side, not ifxTAP

Databases with unbuffered, buffered and ANSI logging were all tested, with the locales en_US.819 and en_US.utf8, on Linux. Other 14.10 fix packs, other 15.0 releases, Windows and macOS have not been tested.

The minimum is what we have tested with: Informix 14.10.FC13W7, JDBC driver 4.10.16 and Java 11. It should work with earlier versions of the server and the driver too. We have not tried them, so we do not promise it. If it does not, please let us know at support@oninit.com with:

the Informix engine version (the full release, for example 14.10.FC13W7: the first line of onstat -, or the server line from ifxtap --check);
the JDBC driver version (the full release, for example 4.50.10 or 15.0.1.3: ifxtap --check shows only the first two numbers, so also give the name of the jar file);
the exact error: the message, and the SQLCODE or ISAM code if there is one.

The same goes for a failure on a version listed above.

Build the runner

From the source tree, with a JDK (11 or later: javac and jar) on the PATH:

./build.sh                       # compiles the runner and packs runner/ifxtap.jar
export PATH="$PWD/bin:$PATH"     # makes the ifxtap command available
ifxtap --version                 # prints: ifxtap 0.5.0

bin/ifxtap is a small launcher that runs runner/ifxtap.jar with the java on your PATH (or $JAVA_HOME/bin/java). Running the jar yourself works too: java -jar runner/ifxtap.jar --help. The commands below, and the other pages, are run from the source tree, where sql/install.sql is.

Get the JDBC driver

Download it from the IBM site, or take com.ibm.informix:jdbc from Maven Central. The runner finds it from --driver, then the IFXTAP_JDBC environment variable, then the classpath. If it finds none, it stops with a message saying so. Set it once for the whole session and every command below finds it:

export IFXTAP_JDBC=/path/to/jdbc.jar

Check the connection

export IFXTAP_URL='jdbc:informix-sqli://dbhost:9088/mydb:INFORMIXSERVER=myserver'
export IFXTAP_USER=...  IFXTAP_PASSWORD=...
ifxtap --check

Reports the server version, the driver version and whether the tap_* library is installed.

Install, upgrade and remove

Install the library into a logged test database with the runner:

ifxtap --install sql/install.sql

The whole install runs in one transaction. If a routine with the same name and signature already exists, whether ifxTAP itself or one of yours, the install is rolled back, the database is left exactly as it was, and the message says what clashed and, if ifxTAP is already installed, which version. A routine of yours that shares a name but has a different signature does not block the install; the runner warns that it was left alone. tap_version() reports the installed version.

dbaccess mydb sql/install.sql also works on a clean database, but dbaccess carries on after an error, so installing over existing routines that way can leave a half-installed library. Use --install.

To remove it, run dbaccess mydb sql/uninstall.sql as the user who installed it, or as a DBA. Use the uninstall.sql of the release that is installed (tap_version() tells you which): it names each routine by name and parameter types, so the list of a different release can leave routines behind. If you have upgraded, upgrade first and then use the new release's script. Any other user removes nothing: the number of routines the script reports removing is 0. The script drops each ifxTAP routine by name and parameter types, so a routine of your own is left alone, even one whose name starts with tap_. It prints the number of routines dropped and can safely be run twice. The results tables are temporary and disappear with each session, so there is nothing else to remove.

To move an installed library to a newer release, run:

ifxtap --upgrade sql

The runner reads the installed version from tap_version(), finds the chain of upgrade steps (sql/upgrade/<from>--<to>.sql) that leads to the version in sql/install.sql, and runs them in one transaction. Each step must leave tap_version() reporting its target; if a step fails, or the version is wrong, everything is rolled back and the library is left as it was. It stops with a message if ifxTAP is not installed (use --install), if it is already the latest version, or if there is no upgrade path from the installed version. Upgrades replace routines in place and keep no data, because ifxTAP has no permanent tables.