Install

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

Prerequisites

To execute the installation, you must have a recent version of db2 installed (10.1 or newer). No other library or tool is necessary.

In addition, the user who executes 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'll need to get a release containing the installation files. These files are part of the sources but do not contain the tests or examples.

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

You should choose a release to download. The best option is to get the most recent version (latest version link). Once it is on your computer, remember where it was stored 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 - 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 storing the XML schemas and XML documents for the appenders.

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

Installing from release

Before you begin the installation, you'll need to connect to the database where the utility will be installed. If you do not do that, an error will be raised indicating no established connection.

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 based on the LOG4DB2_PATH variable.

To install the utility, you only need to execute the install file. In 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 must execute the SQL files directly.

cd log4db2
cd sql-pl
clpplus -nw username@localhost/log4db2
@00-AdminObjects.sql
@05-Tables.sql
@10-LogTable.sql
@15-UtilityHeader.sql
@20-UtilityBody.sql
@25-Appenders.sql
@30-Log.sql
@35-Get_Logger.sql
@40-Trigger.sql
@45-AdminHeader.sql
@50-AdminBody.sql

After executing the 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 us to execute the tests and 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 the Db2 version 10.1 or higher. The Beta and Alfa versions used just t.
• -A non-administrative installation (No bufferpools, tablespaces, or schemas are created). It requires some extra grant to perform the installation.
• -r returns an error message about the installation. This function is only available for the 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. Integrating db2unit in an installation chain could be helpful. 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, 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 unsure if everything is working properly.

Each release of this utility will have its own schema, which allows 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 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 can uninstall it.

NOTE: When reinstalling, ensure no dependent objects exist. If that is the case, the installation process could generate errors.

Uninstalling

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

Memory and storage distribution

This utility uses two tablespaces, one for the configuration and another 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 easily be filled with a configuration that generates many messages.

Each previously described tablespace has a different page size, and the installation script creates a dedicated bufferpool for each tablespace. However, you can change this configuration for your database according to your environment. The installation script creates bufferpools and tablespaces 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 rights to create these objects in the database, 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 different objects for you and give you the right 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 for the generated logs. Depending on the amount of information logged, this last could take up a lot of space.

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

install -A

This option will follow the ADMIN_INSTALL path in the scripts.

Error SQL20317N

If you hit the following error while installing:

SQL20317N The command or statement failed because the operation is only supported when there is at least one storage group defined for the database against which the command or statement was executed. SQLSTATE=55060

This is because a database does not have a default storage path (Old databases migrated from previous versions). Therefore, a tablespace cannot be created without specifying the containers.

The solution is to create the tablespaces and re-execute the installer.

CREATE TABLESPACE logger_space MANAGED BY DATABASE USING (FILE '/home/db2inst/mydb/log4db2/logger_space' 50 M);
CREATE TABLESPACE log_data_space MANAGED BY DATABASE USING (FILE '/home/db2inst/mydb/log4db2/log_data_space' 50 M);