API

These are the procedures and functions (routines) that are part of the API of this utility. These modules are created under a schema specific to the log4db2 version. This means a database can have different log4db2 versions to allow compatibility with all of them. One version schema could be LOGGER_1RC.

Many of the routines are published as the public alias, which allows to call them without specifying the schema. When using multiple log4db2 versions, the public alias will point to the most recent installed version.

Tables are created in another schema, LOGDATA. This allows having a separate schema for the routines (code) from the data (tables).

Development (main routines)

These are the necessary procedures and functions to log a message from the code. All the following routines are part of the LOGGER module, under the version schema (for example LOGGER_1RC).

Signature	Type	Description
GET_LOGGER (NAME VARCHAR(256), LOG_ID SMALLINT)	Proc	Registers the name of a logger and returns the ID for that logger.
GET_LOGGER_NAME (LOG_ID SMALLINT) : VARCHAR(256)	Func	Retrieves the logger name for a given logger ID.
LOG (LOGGER_ID SMALLINT, LEVEL_ID SMALLINT, MESSAGE VARCHAR(512))	Proc	Writes the log message to the appenders. This function formats the message according to the layout.

Macros

All the following routines are part of the LOGGER module, under the version schema (for example LOGGER_1RC). They simplify the way to write a message at a specific log level.

Signature	Type	Description
DEBUG (LOGGER_ID SMALLINT, MESSAGE VARCHAR(512))	Proc	Macro to log messages in 'DEBUG'-5 level.
ERROR (LOGGER_ID SMALLINT, MESSAGE VARCHAR(512))	Proc	Macro to log messages in 'ERROR'-2 level.
FATAL (LOGGER_ID SMALLINT, MESSAGE VARCHAR(512))	Proc	Macro to log messages in 'FATAL'-1 level.
INFO (LOGGER_ID SMALLINT, MESSAGE VARCHAR(512))	Proc	Macro to log messages in 'INFO'-4 level.
WARN (LOGGER_ID SMALLINT, MESSAGE VARCHAR(512))	Proc	Macro to log messages in 'WARN'-3 level.

Administration

The following procedures and functions are used for utility administration. These routines are defined under two modules, both of them under the version schema (for example LOGGER_1RC).

Module	Routine name	Type	Description
LOGGER	ACTIVATE_CACHE ()	Proc	Activates the cache. The cache is a memory area where the loggers are kept for faster access.
LOGGER	DEACTIVATE_CACHE ()	Proc	Cleans the cache and deactivates it. This means that the logger should be retrieved standard SQL, which means that could be on bufferpool or not.
LOGGER	GET_DEFINED_PARENT_LOGGER (LOGGER_ID SMALLINT) : VARCHAR(256)	Func	For a given logger, returns the closer ascendancy that has a defined logger level. For example, if a given logger name is 'mydb.mytenant.myschema.myobject' it will return 'mydb.mytenant.myschema'.
LOGGER	GET_VALUE (KEY VARCHAR(32)) : VARCHAR(256)	Func	Retrieves a value from the configuration table by providing its key (name).
LOGGER	MODIFY_DESCENDANTS (LOGGER_ID SMALLINT, LEVEL_ID SMALLINT)	Proc	Modify the logger level of a logger and all its descendants.
LOGGER	REFRESH_CACHE ()	Proc	Refreshes the cache with the most recent values from the tables.
LOGGER	SHOW_CACHE ()	Proc	Shows the content of the logger cache, if it is currently used.
LOGGER	SHOW_CONF ()	Proc	Shows the current content of the configuration cache and information about its freshness.
LOGADMIN	LOGS (LENGTH SMALLINT DEFAULT 72, QTY SMALLINT DEFAULT 100, MIN_LEVEL SMALLINT)	Proc	Shows the last 100 log messages truncated to 72 characters with the hour (not the whole timestamp).
LOGADMIN	NEXT_LOGS (LENGTH SMALLINT DEFAULT 72, MIN_LEVEL SMALLINT)	Proc	Shows the log messages by pages, truncating the message to 72 characters with the hour (not the whole timestamp).
LOGADMIN	REGISTER_LOGGER_NAME (LOGGER_NAME VARCHAR(256), LEVEL_NAME CHAR(5))	Proc	Register a logger and specify a level name. This is the easiest way to change the level of a given logger.
LOGADMIN	REGISTER_LOGGER (NAME VARCHAR(256), LEVEL SMALLINT)	Proc	Register a logger and specify a level.
LOGADMIN	RESET_TABLES ()	Proc	Deletes all rows, and leave the basic tables as they were after the installation.
LOGADMIN	SHOW_LOGGERS ()	Proc	Returns a list of the loggers registered in the utility.

Testing purposes

The following routines are for testings purposes used when running with db2unit.

Module	Routine name	Type	Description
LOGGER	DELETE_LOGGER_CACHE (LOGGER_ID SMALLINT)	Proc	Deletes a given logger from the cache. Used for testing purposes.
LOGGER	DELETE_LOGGERS ()	Proc	Deletes all registered loggers, except root. This is used for testing purposes.
LOGGER	UNLOAD_CONF ()	Proc	Unloads the configuration from caches. This is used for testing purposes.