These are the steps to retrieve the necessary files to install the framework in a database.

Prerequisites

These are the prerequisites to install db2unit in an existing Db2 database:

  • The framework could be installed in recent versions of Db2 (9.7 or higher). For more information, check this section.

  • log4db2 should be installed in your database before installing this framework.

  • In addition, the user used to execute the installation has to have elevated privileges. If the user has not DBADM authority, you should review the section Installation with restrictive rights.

log4db2 prerequisite

As said before, log4db2 is a prerequisite to install this framework. You can download the sources it from https://github.com/angoca/log4db2/releases/latest and then install them.

This is the compatibility table between db2unit version and log4db2 versions.

db2unit Min log4db2 version log4db2 version tested
Version 1 (2014-10-13) Version 1B (>= 2014-04-21) 1RC
Version 1B (2014-07-26) Version 1B (>= 2014-04-21) 1B, 1RC
Version 1A (2014-05-11) Version 1B (>= 2014-04-21) 1B, 1RC
Version 2 - v2 ToDo ToDo

Retrieve installation files (release)

First, you need to retrieve a release that contains the files for the installation. These files are part of the sources, but they do not contain the tests, nor the examples.

For the most recent release, it is published at: https://github.com/angoca/db2unit/releases/latest

You could choose the latest release or a previous version to download. Once it is on your computer, remember where it was downloaded in order to extract it or to copy to a server.

You can also get db2unit in any of these ways:

  • Main branch for the current stable development.
  • Develop branch for the more recent integration of the development. It could be unstable.
  • Clone the repository with https://github.com/angoca/db2unit.git

The installer package contains the following files and directories:

  • README.txt - Description of this framework.
  • LICENSE.txt - Licenses.
  • files - Without extension - Set of files for the UNIX-like OS family (Linux, AIX) (Bash required).
  • files.bat - Set of files for the Windows OS family to be run in terminal (CMD.exe).
  • files.ksh - (v2) Set of files mainly for AIX with only Korn.
  • files.ps1 - Set of files for PowerShell in Windows OS.
  • doc - A directory with documentation about the framework.
  • sql-pl - A directory with the DDL / DML to create the framework in the database (source code).

For ease in the documentation, we will use the installer without extension. However, depending on the platform you use, you will need the files with the appropriate extension.

Installing from release

Before beginning with the installation, you need to establish a connection to the database where the framework is going to be installed. If you do not do that, an error will be raised indicating that there is not an established connection.

In order to run the installation, it is necessary to indicate where the installation code is (source code.) For this, there is a variable that is necessary to set:

  • DB2UNIT_SRC_MAIN_CODE_PATH

To ease this part, the init script will set the value of this variable, and the value is based on the DB2UNIT_PATH variable. When executing the installation from the scripts, this value will be set automatically.

NOTE: The installation process changes the Db2's internal CURRENT PATH special register (SYSTEM PATH, CURRENT USER).

NOTE: (v2) As part of the installation, in order to identify the environment, the SQL_CCFLAGS for conditional compilation are changed. If you have set them, they will have extra values after executing the installation.

UNIX like systems

In the UNIX like systems, the scripts are written to use Bourne Shell or Bash.

tar -zxf db2unit.tar.gz
cd db2unit
. ./install

Make sure to put the dot before the command. This will 'source' the values and use the current connection.

If Bash is not present, then each SQL file can be executed independently. (v2) Also, if you have AIX with only Korn shell, you can use the scripts with .ksh extension.

Windows terminal (CMD.exe - db2clp)

Unzip the file db2unit.zip with an appropriate tool.

cd db2unit
install.bat

Windows PowerShell

Unzip the file db2unit.zip with an appropriate tool.

cd db2unit
.\install.ps1

If an error about signing (PSSecurityException) appears, you need to deactivate the Execution strategy:

Set-ExecutionPolicy unrestricted

CLPPlus

You do not need to use scripts, you just need to execute the SQL files directly.

cd db2unit
cd sql-pl
clpplus -nw username@localhost/db2unit
@01-ObjectsAdmin.sql
@02-Objects.sql
@03-Headers.sql
@04-Body.sql
@05-Asserts.sql
@06-AssertNoMessage.sql
@07-Version.sql

(v2) Since version 2, the 07-Version.sql is replaced by the following two ones: 07-XMLReport.sql and 08-Version.sql. Thus, the complete instruction is:

cd db2unit
cd sql-pl
clpplus -nw username@localhost/db2unit
@01-ObjectsAdmin.sql
@02-Objects.sql
@03-Headers.sql
@04-Body.sql
@05-Asserts.sql
@06-AssertNoMessage.sql
@07-XMLReport.sql
@08-Version.sql

After the execution of the install scripts, all statements should have been successful.

If you have any problem, please visit the FAQs section or put an issue.

You can also install the framework from the sources, not from a published release. This method will allow to execute the tests, the examples, and to try the framework with older or more recent Db2 versions.

Error codes

Once the installation script has finished its execution, it returns an error code. This could be helpful if you need to integrate db2unit with an installation chain. The error codes are:

  • 0: Installation success.
  • 1: There were errors during the installation.
  • 2: There is not an established connection to any database.

Reinstalling

If you want to reinstall the framework, you use the reinstall command in the same way you did the installation. For example for Linux / UNIX:

. ./reinstall

Uninstalling

If you want to uninstall the framework you just call the uninstall command in the same way you did the installation. For example for Linux / UNIX:

. ./uninstall

If you have special requirements about the db2unit installation, please check the Special tricks to install db2unit page.