-
Notifications
You must be signed in to change notification settings - Fork 2
Install
This page explains retrieving the necessary files to install the utility in a database.
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.
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.
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
).
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
Unzip the file log4db2.zip
cd log4db2
install.bat
Unzip the file log4db2.zip
cd log4db2
.\install.ps1
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 justt
. -
-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.
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.
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.
If you want to uninstall the utility, call the 'uninstall' command without any parameter.
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.
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.
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);