Install

This page explains how to retrieve the necessary files to install the utility in a database.

Prerequisites

In order to execute the installation, you just need to have a recent version of db2 installed (10.1 or newer). No other library or tool is necessary.

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

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 or the examples.

The releases are published at: https://github.com/angoca/log4db2/releases

You should choose a release to download, the best is to get the most recent version (latest version link). Once it is on your computer, remember where it was stored in order to extract it.

The package contains the following files and directories:

README.txt - Description of this utility.
COPYING.txt - Licenses.
files.bat - Set of files for the Windows OS family terminal (CMD.exe).
files.ps1 - Set of files for the PowerShell in Windows OS.
files.sql - Set of files for CLPPlus.
files - Set of files for the UNIX-like OS family (AIX, HP-UX, Solaris, MAC OSX).
doc - A directory with documentation about the utility.
sql-pl - A directory with the DDL / DML to create the utility in the database (source code).
xml - A directory where the XML schemas and XML documents for the appenders are stored.

The Windows files have the same names of the UNIX files; the only difference is that Windows files have extensions.

Installing from release

Before beginning with the installation, you need to establish a connection to the database where the utility 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 (sources.) For this, there is a variable that is necessary to set:

LOG4DB2_SRC_MAIN_CODE_PATH

To ease this part, the init script will set the value of this variable, and it will be set based on the LOG4DB2_PATH variable.

In order to install the utility, you only need to execute the install file. For special cases, you could indicate some parameters. More about this later.

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

UNIX like

tar -zxvf log4db2.tar.gz
cd log4db2
. ./install

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

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

Set-ExecutionPolicy unrestricted

Windows terminal (CMD.exe - db2clp)

Unzip the file log4db2.zip

cd log4db2
install.bat

Windows PowerShell

Unzip the file log4db2.zip

cd log4db2
.\install.ps1

CLPPlus

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

cd log4db2
cd sql-pl
clpplus -nw username@localhost/log4db2
@00-AdminObjects.sql
@01-Tables.sql
@02-UtilityHeader.sql
@03-UtilityBody.sql
@04-Appenders.sql
@05-Log.sql
@06-Get_Logger.sql
@07-Trigger.sql
@08-AdminHeader.sql
@09-AdminBody.sql

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

If you are hitting installation errors, and you are using Linux/UNIX scripts, you can export the variable VERBOSE to true, and the installer will output the statement:

export VERBOSE=true

You can also install the utility from the sources, not from a release. This will allow to execute the tests, the example, or use an older or newer version.

The optional parameters are:

-t activates the option to install the temporal capabilities. This is only available for version 10.1 or higher Db2 version. The Beta and Alfa version used just t
-A non-administrative installation (No bufferpools, tablespaces, or schemas are created). It requires some extra grant to perform the installation.
-r return error message about the installation. Only for Bash/Korn shell script.

The possible command lines are (Not valid for CLPPlus scripts):

install                # Normal execution
install.bat -t         # Temporal capabilities (in Windows)
install -A -t          # Non Administrative with temporal capabilities
install.ps1 -t         # Temporal capabilities (in Windows PowerShell)
install.ps1 '-t'       # Normal execution (in Windows PowerShell)

NOTE: In PowerShell, the arguments with 'dots' should be passed surrounded by single or double quotes.

The installation process can generate several messages in the db2diag.log. They are normal. For more details, check the FAQs.

Error codes

Once the installation script finishes its execution, it returns an error code. This could be helpful if you integrate db2unit in an installation chain. The error codes are:

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

Reinstalling

If you want to reinstall the utility, you use the reinstall command (reinstall.bat, reinstall.ps1 or reinstall) with the same parameters for the installation.

This could be useful if your configuration tables have been drastically changed, and you are not sure if everything is working fine.

Each release of this utility will have its own schema, this allows to have multiple versions of this utility in a single database. This will ease the migration process of the other stored procedures or functions because they do not have to be modified in order to be adapted to a more recent version.

Once you are sure a given version of this utility is no longer used in your database, you could uninstall it.

NOTE: When reinstalling, make sure there are no dependent objects. If that is the case, the installation process could generate errors.

Uninstalling

If you want to uninstall the utility you just call the 'uninstall' command without any parameter.

Memory and storage distribution

This utility uses two tablespaces, one for the configuration and another one for the generated logs. It is recommended to have a dedicated tablespace for the generated logs because if only one tablespace is used, it could be filled easily with a configuration that generates many messages.

Each of the previously described tablespaces has a different page size, and the installation script creates a dedicated bufferpool for each tablespace. However, you can change this configuration for your own database according to your environment. The installation script creates both bufferpools and tablespaces for to fit the tables in your database.

All schemas, tablespaces and bufferpools are defined in the 00-AdminObjects.sql. If you do not have the necessary rights to create these objects in the database, then you should give this script to your DBA. This process is described in the next session.

Installation with restrictive rights

You can install this utility in a database where you do not have DBADM authority. However, the DBA should create for you different objects and give you the necessary rights to use them. The DBA should execute the file 00-AdminObjects.sql and give you the following rights:

 grant createtab on database to user USERNAME;
 grant use of tablespace LOGGER_SPACE to user USERNAME;
 grant use of tablespace LOG_DATA_SPACE to user USERNAME;
 grant createin on schema LOGDATA to user USERNAME;
 grant createin on schema LOGGER_1RC to user USERNAME;
 grant execute on function sysproc.MON_GET_CONNECTION to user USERNAME;

The utility creates two tablespaces, one for the configuration, and another one for the generated logs. This last could use a lot of space depending on how much information is logged.

Once you have these rights, you can install the utility with the -A option (Non-administrative objects.)