LEHS - Log- and Exception-Handling System for ORACLE®

Definition of an Appender

An Appender Package is a Package with at least a Procedure named log with exactly one Parameter of the Datatype PKG_LEHS_APPENDER.pr_log_line.

The task of an Appender Package is to handle all Log-Entries and Log Transactions. You can register a Package as an Appender to an existing Log-Application by calling PKG_LEHS_SYSTEM.register_appender. After a successful Registration as an Appender, LEHS delegates the Handling of the Logs and the Log-Transactions to this Package by Procedures with the following Characteristics:

All Procedures must have a predefined Name for exactly one Task.
The Datatypes, the Order Sequence and the Count of the Parameters are fixed (but not the Names of these Parameters)

Appender Procedure API

Here' a List of the Procedure API and the appropriated Task:

Procedure Parameters (with Datatype) Task

register

1. Log-Application (PKG_LEHS_APPENDER.pst_application_name)

Tasks to be done while the Appender Package will be registered as an Appender to an existing Log-Application

deregister

1. Log-Application (PKG_LEHS_APPENDER.pst_application_name)

Tasks to be done while the Appender Package will be deregistered from a Log-Application as an Appender

check_param

1. Log-Application (PKG_LEHS_APPENDER.pst_application_name)

2. Name of the Parameter (PKG_LEHS_APPENDER.pst_parameter_name)

Value of the Parameter (	`PKG_LEHS_APPENDER.pst_param_value_clob`	)
	`PKG_LEHS_APPENDER.pst_param_value_number`
	`PKG_LEHS_APPENDER.pst_param_value_date`
	`PKG_LEHS_APPENDER.pst_param_value_timestamp`
	`PKG_LEHS_APPENDER.pst_param_value_interval_ds`
	`PKG_LEHS_APPENDER.pst_param_value_interval_ym`

Checks a Parameter Value for the following Characteristics:

Valid Parameter Name
Valid Datatype of the Parameter
Valid Parameter Value

initialize

1. Log-Application (PKG_LEHS_APPENDER.pst_application_name)

Initializes the internal Buffer of the Appender Package for the use by the given Log-Application (for Instance: predefine some Variables)

set_param

1. Log-Application (PKG_LEHS_APPENDER.pst_application_name)

2. Name of the Parameter (PKG_LEHS_APPENDER.pst_parameter_name)

Value of the Parameter (	`PKG_LEHS_APPENDER.pst_param_value_clob`	)
	`PKG_LEHS_APPENDER.pst_param_value_number`
	`PKG_LEHS_APPENDER.pst_param_value_date`
	`PKG_LEHS_APPENDER.pst_param_value_timestamp`
	`PKG_LEHS_APPENDER.pst_param_value_interval_ds`
	`PKG_LEHS_APPENDER.pst_param_value_interval_ym`

Save the Value of the given registered Parameter within an internal Buffer for the Usage of the given Log-Application. Speeds up the Usage duringe the Runtime of the Log-Application.

after_initialize_check

1. Log-Application (PKG_LEHS_APPENDER.pst_application_name)

Checks, if all prerequisites of the Appender Package has been fulfilled so that the given Log-Application can use the Appender Package as an Appender (for Instance: checks, if all mandatory Parameter have been set).

cleanup

1. Log-Application (PKG_LEHS_APPENDER.pst_application_name)

Empties the internal Buffer of the Appender Package for the given Log-Application.

log

1. Log Entry (PKG_LEHS_APPENDER.pr_log_line)

Logs a single Log-Entry

start_log_transaction

1.		Log Entry (`PKG_LEHS_APPENDER.pr_log_line`)
2.		Transaction ID (`BINARY_INTEGER`)

Tasks to be done, when a new Log-Transaction will be started

end_log_transaction

1.		Log Entry (`PKG_LEHS_APPENDER.pr_log_line`)
2.		Transaction ID (`BINARY_INTEGER`)

Tasks to be done, when the actual open Log-Transaction will be closed

add_transaction_keyword

1. Log-Application (PKG_LEHS_APPENDER.pst_application_name)

2. Transaction ID (BINARY_INTEGER)

3. Name of the Transaction Key (VARCHAR2)

Value of the Transaction Key (	`CLOB`	)
	`NUMBER`
	`DATE`
	`TIMESTAMP_UNCONSTRAINED`
	`DSINTERVAL_UNCONSTRAINED`
	`YMINTERVAL_UNCONSTRAINED`

Tasks to be done, when a Transaction Keyword will be added to the provided Transaction.

Remember, these Procedures (if provided by the Package) are called by LEHS automatically in accordance of the Phase (described later) of the Appender.

Phases of an Appender

An Appender can have 3 Phases:

Configuration Phase
associated Procedures:
- register
- deregister
- check_param
Initialization Phase
associated Procedures:
- cleanup
- initialize
- set_param
- after_initialize_check
Usage Phase
associated Procedures:
- log
- start_log_transaction
- end_log_transaction
- add_transaction_keyword

Configuration Phase

During the Configuration Phase of an Appender, the Package would be registered and configured for the Usage by the applied Log-Application.

Register a Package as an Appender

You can register an Appender Package by calling the Procedure PKG_LEHS_SYSTEM.register_appender.

BEGIN
  PKG_LEHS_SYSTEM.register_appender (
    pi_application   => 'TEST_APPLICATION'
   ,pi_appender_name => 'TABLE APPENDER'
   ,pi_max_log_level => 'TRACE'
   ,pi_package_owner => USER
   ,pi_package_name  => 'PKG_LEHS_TABLE_APPENDER'
  );
END;
/

When you register a Package as an Appender, the following Checks would be done:

Does there exist another Appender with the same Name within the Namespace of the Log-Application
Check, if another Appender within the Namespace of the Log-Application references the same Package.
The same Package have to be used by one Log-Application only once because the Procedure PKG_LEHS_APPENDER.get_appender_parameters provides the Appender Parameters as a List indexed by the Log-Application. If more than one Appender of the same Log-Application references this Package then this Assumption fails.
Check, if the Package provides at least one Method named log with exactly one Parameter of Datetype PKG_LEHS_APPENDER.pr_log_line.
Check, if the maximum Log-Level is a valid Log-Level of the Log-Application.
If the registered Package provides a Procedure named register, then this Procedure would be called just before the Appender will be registered. The Name of the Log-Application would be provided as a Parameter to this Procedure.
Any raised Exception during the Execution of the Procedure register would cause the Appender not to be registered as an Appender. Instead, this Exception will be looped through to the Caller of PKG_LEHS_SYSTEM.register_appender

The Logs would be handled by the registered Package only if the Log-Level of these Logs are lower or equal than the maximum Log-Level set to this Appender. Instead of the previous Versions of LEHS this Parameter now has been moved from the Application Level to the Appender Level.

Deregister an Appender

A registered Package can be deregistered to be used as an Appender.

BEGIN
  PKG_LEHS_SYSTEM.deregister_appender (
    pi_application => 'TEST_APPLICATION'
   ,pi_appender_name => 'TABLE APPENDER'
  );
END;
/

This stops LEHS to use the registered Package as an Appender for this Log-Application.

If the deregistered Package provides a Procedure named deregister then this Procedure will be called just before the Appender will be deregistered from the Log-Application. The Name of the Log-Application will be set as a Parameter to this Call.
If there will be any Exception raised during this Deregistration, the Message of the Exception will be logged as a warning but the Appender will still be deregistered.

Configure Appender Parameters

Normally Appender Packages will be developed to be used by many different Log-Applications. But maybe you wont have that every Log-Application would be served the same. Therefor you can register Appender Parameters which will be set to the Appender at the Initialization Phase (which, in fact, is the Reason why there exists an Initialization Phase).

You can define Parameters in accordance for the Usage of the Package. Appender Parameters are just a simple Form of a Name=Value Pair.

Be aware: Appender Parameter Names and its alphanumeric Values are, unless the Log-Application and the Appender Name, case sensitive!

Parameters will be set or changed by this Call:

BEGIN
  PKG_LEHS_SYSTEM.set_appender_parameter (
    pi_application     => 'TEST_APPLICATION'
   ,pi_appender_name   => 'TABLE APPENDER'
   ,pi_parameter_name  => 'RETENTION_TIME'
   ,pi_parameter_value => 500
  );
END;
/

This Procedure, PKG_LEHS_SYSTEM.set_appender_parameter, is overloaded with 7 different Datatypes for the Parameter pi_parameter_value. These Datatypes are:

VARCHAR2
Would internally be handled as CLOB
CLOB
NUMBER
DATE
TIMESTAMP
INTERVAL DAY TO SECOND
INTERVAL YEAR TO MONTH

The Task of LEHS is just to get these Parameters and save or change the Values. Neither more, neither less. So LEHS doesn't know anything about the Semantics of these Parameters.

If you wish, that LEHS checks also the Semantics of the Parameters (for Instance, if the provided Parameter Name is valid for the Appender Package) then you have to provide a Procedure named check_param for every Datatype you wish to check the Parameters of this Datatype. If such Procedure wouldn't be provided then LEHS saves (or changes) the Value without any Checks.

Just an Example: Imagine, your Package just needs 2 Parameters. A numeric Retention-Time and an alphanumeric Switch, which can only include the Values TRUE or FALSE. If you don't provide a Check-Method for any of these Values you can set any Value you like for these Parameters. An alphanumeric Retention-Time for Instance.

So, this is the Time, where you provide such "Checkers", how the Procedure check_param will be called.

CREATE OR REPLACE PACKAGE pkg_appender_example IS

  ...
  
  pc_param_retention_time CONSTANT PKG_LEHS_APPENDER.pst_parameter_name
    := 'RETENTION_TIME;
  pc_param_simple_switch  CONSTANT PKG_LEHS_APPENDER.pst_parameter_name
    := 'simpleSwitch';
  
  ...
  
  -- Checks a Parameter of Datatype VARCHAR2 or CLOB
  -- (called by PKG_LEHS_SYSTEM.set_appender_parameter)
  PROCEDURE check_param (
    pi_application IN PKG_LEHS_APPENDER.pst_appender_name
   ,pi_key         IN PKG_LEHS_APPENDER.pst_parameter_name
   ,pi_value       IN PKG_LEHS_APPENDER.pst_param_value_clob
  );
  
  -- Checks a Parameter of Datatype NUMBER
  -- (called by PKG_LEHS_SYSTEM.set_appender_parameter)
  PROCEDURE check_param (
    pi_application IN PKG_LEHS_APPENDER.pst_appender_name
   ,pi_key         IN PKG_LEHS_APPENDER.pst_parameter_name
   ,pi_value       IN PKG_LEHS_APPENDER.pst_param_value_number
  );
  
  ...
  
END pkg_appender_example;
/

CREATE OR REPLACE PACKAGE BODY pkg_appender_example IS

  ...

  pc_switch_value_true  CONSTANT PKG_LEHS_APPENDER.pst_param_value_clob
    := 'TRUE';
  pc_switch_value_false CONSTANT PKG_LEHS_APPENDER.pst_param_value_clob
    := 'FALSE';
  
  pc_retention_time_min_value CONSTANT PKG_LEHS_APPENDER.pst_param_value_number
    := 0;
  pc_retention_time_max_value CONSTANT PKG_LEHS_APPENDER.pst_param_value_number
    := 99999;

  ...
  
  PROCEDURE check_param (
    pi_application IN PKG_LEHS_APPENDER.pst_appender_name
   ,pi_key         IN PKG_LEHS_APPENDER.pst_parameter_name
   ,pi_value       IN PKG_LEHS_APPENDER.pst_param_value_clob
  ) IS
  BEGIN
    CASE pi_key
      WHEN pc_param_retention_time THEN
      	PKG_LEHS_APPENDER.assert_parameter_value (
      	  pi_assertion       => pi_value IS NOT NULL
      	 ,pi_parameter_name  => pi_key
      	 ,pi_parameter_value => pi_value
      	 ,pi_error_message   => pi_key || ' IS NULL'
      	);
      	PKG_LEHS_APPENDER.assert_parameter_value (
      	  pi_assertion       => pi_value IN (pc_switch_value_true
      	                                    ,pc_switch_value_false)
      	 ,pi_parameter_name  => pi_key
      	 ,pi_parameter_value => pi_value
      	 ,pi_error_message   => pi_key || ' NOT IN (''' ||
      	    pc_switch_value_true || ''', ''' || pc_switch_value_false || ''')'
      	);
      ELSE
        PKG_LEHS_APPENDER.raise_invalid_parameter_name (
          pi_parameter_name  => pi_key
         ,pi_parameter_value => pi_value
        );
    END CASE;
  END check_param;

  PROCEDURE check_param (
    pi_application IN PKG_LEHS_APPENDER.pst_appender_name
   ,pi_key         IN PKG_LEHS_APPENDER.pst_parameter_name
   ,pi_value       IN PKG_LEHS_APPENDER.pst_param_value_number
  ) IS
  BEGIN
    CASE pi_key
      WHEN pc_param_simple_switch THEN
      	PKG_LEHS_APPENDER.assert_parameter_value (
      	  pi_assertion       => pi_value IS NOT NULL
      	 ,pi_parameter_name  => pi_key
      	 ,pi_parameter_value => pi_value
      	 ,pi_error_message   => pi_key || ' IS NULL'
      	);
      	PKG_LEHS_APPENDER.assert_parameter_value (
      	  pi_assertion       => pi_value BETWEEN pi_retention_time_min_value
      	                                     AND pi_retention_time_max_value
      	 ,pi_parameter_name  => pi_key
      	 ,pi_parameter_value => pi_value
      	 ,pi_error_message   => pi_key || ' NOT BETWEEN ' ||
      	    TO_CHAR(pi_retention_time_min_value) || ' AND ' ||
      	    TO_CHAR(pi_retention_time_max_value)
      	);
      ELSE
        PKG_LEHS_APPENDER.raise_invalid_parameter_name (
          pi_parameter_name  => pi_key
         ,pi_parameter_value => pi_value
        );
    END CASE;
  END check_param;
  
  ...
  
END pkg_appender_example;
/

The Example above shows you the Usage of the Procedure check_param, also known as Checkers. Also you can see within the Implementation the Usage of 2 Utility Procedures of the Package PKG_LEHS_APPENDER: raise_invalid_parameter_name and assert_parameter_value.

These 2 Procedures can be used to raise standardized Exception Messages when one of these Checks will fail:

Invalid Parameter Name (raise_invalid_parameter_name)
Datatype of Parameter is invalid (raise_invalid_parameter_name)
invalid Value of the Parameter (assert_parameter_value)

As like the Procedure PKG_LEHS.assert, the Procedure PKG_LEHS_APPENDER.assert_parameter_value will raise the standardized Exception if the Assertion of Parameter pi_assertion fails. The raised Exception will also be journalized to the Log-Application LEHS.

Above you have read, that the Checker Procedure will be called (if provided by the Appender Package) when the Procedure PKG_LEHS_SYSTEM.set_appender_parameter have been executed. This Procedure has been overloaded 7 times (in accordance to the Parameter pi_parameter_value). It is vital that this Datatype is determinant for the Checker, which will be called. If you give a Parameter of Datatype VARCHAR2 or CLOB, the Checker with the Datatype PKG_LEHS_APPENDER.pc_param_value_clob will be executed to check the Value. If you give a Parameter of Datatype DATE the Checker with the Datatype PKG_LEHS_APPENDER.pc_param_value_date will be called through LEHS.

The following Table gives you an Overview, which Parameter Setter calls which Checker in the Appender Package. Also this Table gives you an Overview of the Setter Procedures of the Appender Package, which will be called during the Initialization of the Appender.

Setter of Package PKG_LEHS_SYSTEM Checker of the Appender Package Setter of the Appender Package

PKG_LEHS_SYSTEM.set_appender_parameter ( pi_application IN PKG_LEHS.pst_application_name ,pi_appender_name IN VARCHAR2 ,pi_parameter_name IN VARCHAR2 ,pi_parameter_value IN VARCHAR2 )

PKG_LEHS_SYSTEM.set_appender_parameter ( pi_application IN PKG_LEHS.pst_application_name ,pi_appender_name IN VARCHAR2 ,pi_parameter_name IN VARCHAR2 ,pi_parameter_value IN CLOB )

check_param ( pi_application IN PKG_LEHS_APPENDER.pst_appender_name ,pi_key IN PKG_LEHS_APPENDER.pst_parameter_name ,pi_value IN PKG_LEHS_APPENDER.pst_param_value_clob )

set_param ( pi_application IN PKG_LEHS_APPENDER.pst_appender_name ,pi_key IN PKG_LEHS_APPENDER.pst_parameter_name ,pi_value IN PKG_LEHS_APPENDER.pst_param_value_clob )

PKG_LEHS_SYSTEM.set_appender_parameter ( pi_application IN PKG_LEHS.pst_application_name ,pi_appender_name IN VARCHAR2 ,pi_parameter_name IN VARCHAR2 ,pi_parameter_value IN NUMBER )

check_param ( pi_application IN PKG_LEHS_APPENDER.pst_appender_name ,pi_key IN PKG_LEHS_APPENDER.pst_parameter_name ,pi_value IN PKG_LEHS_APPENDER.pst_param_value_number )

set_param ( pi_application IN PKG_LEHS_APPENDER.pst_appender_name ,pi_key IN PKG_LEHS_APPENDER.pst_parameter_name ,pi_value IN PKG_LEHS_APPENDER.pst_param_value_number )

PKG_LEHS_SYSTEM.set_appender_parameter ( pi_application IN PKG_LEHS.pst_application_name ,pi_appender_name IN VARCHAR2 ,pi_parameter_name IN VARCHAR2 ,pi_parameter_value IN DATE )

check_param ( pi_application IN PKG_LEHS_APPENDER.pst_appender_name ,pi_key IN PKG_LEHS_APPENDER.pst_parameter_name ,pi_value IN PKG_LEHS_APPENDER.pst_param_value_date )

set_param ( pi_application IN PKG_LEHS_APPENDER.pst_appender_name ,pi_key IN PKG_LEHS_APPENDER.pst_parameter_name ,pi_value IN PKG_LEHS_APPENDER.pst_param_value_date )

PKG_LEHS_SYSTEM.set_appender_parameter ( pi_application IN PKG_LEHS.pst_application_name ,pi_appender_name IN VARCHAR2 ,pi_parameter_name IN VARCHAR2 ,pi_parameter_value IN TIMESTAMP_UNCONSTRAINED )

check_param ( pi_application IN PKG_LEHS_APPENDER.pst_appender_name ,pi_key IN PKG_LEHS_APPENDER.pst_parameter_name ,pi_value IN PKG_LEHS_APPENDER.pst_param_value_timestamp )

set_param ( pi_application IN PKG_LEHS_APPENDER.pst_appender_name ,pi_key IN PKG_LEHS_APPENDER.pst_parameter_name ,pi_value IN PKG_LEHS_APPENDER.pst_param_value_timestamp )

PKG_LEHS_SYSTEM.set_appender_parameter ( pi_application IN PKG_LEHS.pst_application_name ,pi_appender_name IN VARCHAR2 ,pi_parameter_name IN VARCHAR2 ,pi_parameter_value IN DSINTERVAL_UNCONSTRAINED )

check_param ( pi_application IN PKG_LEHS_APPENDER.pst_appender_name ,pi_key IN PKG_LEHS_APPENDER.pst_parameter_name ,pi_value IN PKG_LEHS_APPENDER.pst_param_value_interval_ds )

set_param ( pi_application IN PKG_LEHS_APPENDER.pst_appender_name ,pi_key IN PKG_LEHS_APPENDER.pst_parameter_name ,pi_value IN PKG_LEHS_APPENDER.pst_param_value_interval_ds )

PKG_LEHS_SYSTEM.set_appender_parameter ( pi_application IN PKG_LEHS.pst_application_name ,pi_appender_name IN VARCHAR2 ,pi_parameter_name IN VARCHAR2 ,pi_parameter_value IN YMINTERVAL_UNCONSTRAINED )

check_param ( pi_application IN PKG_LEHS_APPENDER.pst_appender_name ,pi_key IN PKG_LEHS_APPENDER.pst_parameter_name ,pi_value IN PKG_LEHS_APPENDER.pst_param_value_interval_ym )

set_param ( pi_application IN PKG_LEHS_APPENDER.pst_appender_name ,pi_key IN PKG_LEHS_APPENDER.pst_parameter_name ,pi_value IN PKG_LEHS_APPENDER.pst_param_value_interval_ym )

Once an Appender Parameter has been set, it can be changed by recalling the Procedure PKG_LEHS_SYSTEM.set_appender_parameter.

You can unset an Appender Parameter by calling PKG_LEHS_SYSTEM.unset_appender_parameter:

BEGIN
  PKG_LEHS_SYSTEM.unset_appender_parameter (
    pi_application    => 'TEST_APPLICATION'
   ,pi_appender_name  => 'TABLE APPENDER'
   ,pi_parameter_name => 'RETENTION_TIME'
  );
END;
/

This removes the Appender Parameter RETENTION_TIME from the Appender TABLE APPENDER of the Log-Application TEST_APPLICATION.

Initialization Phase

During the Configuration Phase you can register a Package as an Appender and configure the Appender Parameters. These Parameters can be checked by optional Checker-Procedures (named check_param) and, after a successful Check, saved as Appender Parameters (Table: LEHS_APPENDER_PARAMETERS).

Because of the open Architecture of specially named Procedures LEHS has the ability to register any Package of the Database. Only the Execution Rights must be granted to the LEHS Installation User. This is also called the Open Appender Architecture (OAA).

Because of the open Appender Architecture the Package must not reside within the same Schema as LEHS itself. Several Developers can develop several Appenders on different Schemas. LEHS can delegate the Log-Calls to these Appenders. But there is a common denominator: The Registration and the Appender Parameters.

During the Initialization of an Appender these Appender Parameters will be set by LEHS by calling the Procedure set_param, which will be called the "Setter" Procedures.

There is a strict Order in which the Initialization of an Appender Package will be managed. First of all, all Procedures of the Initialization are optional. You can initialize an Appender Package. But this is not a must have.

The Initialization follows the following Order:

If the Package has already been initialized, the Cleanup Procedure cleanup will be called. The Name of the Log-Application, which will be initialized at the Moment, will be provided as a Parameter.
The Initialization Procedure initialize of the Package will be called. The Name of the Log-Application, which will be initialized at the Moment, will be provided as a Parameter.
For every registered Appender Parameter the corresponding Setter (Procedure: set_param) will be called. The correct Setter depends on the Datatype of the Appender Parameter. As the Checker the Setter can be overloaded.
The following Parameters will be provided by LEHS:
1. Name of the Log-Application (Datatype: PKG_LEHS_APPENDER.pst_application_name)
2. Name of the Appender Parameter (Datatype: PKG_LEHS_APPENDER.pst_parameter_name)
3. Value of the Appender Parameter (Datatype depends on the Datatype of the registered Appender Parameter)
The After Initialization Check (Procedure: after_initialize_check) will be executed. This gives the Package itself a Chance to check, if all mandatory Parameters for this Log-Application has been set.

Any raised Exception during any of the Procedures described above leads, that the Appender would not be initialized and can not be used during the Runtime of the Application. Instead a Warning would be warning journalized to the internal Log-Application LEHS.

When would the Initialization be started

The Initialization starts at the first Usage of the Log-Application. Any Procedure of the Package PKG_LEHS, which probably writes Log-Messages or handles any Log-Transaction (also the adding of a Log Topic or an Exception Message) leads, that this Log-Application will be initialized with all its registered Appenders. After the Initialization the initialized Appenders stay in Memory either until the Session ends or the Procedure PKG_LEHS.resync will be called.

This Method has 2 vital Impacts:

The first Call of any writable Procedure of the Package PKG_LEHS initializes the System. This leads, that the first Call of any of these Procedures takes more Times than any following Call because the following Calls get the Information from the Memory Structure of the PGA (or UGA on shared Server).
Exception of this Rule: If the Schema, where the Application runs that uses the Log-Application, has no Write Privileges to this Log-Application then only the Log-Levels, the programmable Log-Levels and the Privileges of this Log-Application will be read into Memory. Because any access violation would be journalized to the Log-Application LEHS. Expect if the logable Log Entry has a Log-Level higher than any maximum Log-Levels of all registered Appenders to this Log-Level. Than no Journal Entry will be added.
Only the Log-Applications which will be used uses Memory of the PGA. This impacts, that no Memory is wasted as LEHS needs it.

The Disadvantage of this Method: Changes during a Session Lifetime on an already initialized Log-Application would not lead to refresh the Memory Structure. You must explicitly call the Procedure PKG_LEHS.resync to clean the internal Memory Structure. After the resync Call all initialized Log-Applications will stay no longer in Memory so that the first Call of a writable Procedure leads to the Initialization as described above.

Usage Phase

After all Appenders have been initialized, these Appenders can be used by LEHS. LEHS delegates all Log-Calls and Transaction-Calls to these Appenders. The following Table gives an Overview, which Procedure of the Package PKG_LEHS leads to a Delegation of a Procedure within the Appender Package:

Procedure of Package PKG_LEHS Delegation Procedure within the Appender Package Description of the API Procedures

PKG_LEHS.log

PKG_LEHS.fatal

PKG_LEHS.error

PKG_LEHS.warn

PKG_LEHS.info

PKG_LEHS.debug

PKG_LEHS.trace

log

These Procedures will create a single Log-Entry

PKG_LEHS.handle_exception_and_log

PKG_LEHS.handle_exception_and_log_fatal

PKG_LEHS.handle_exception_and_log_error

PKG_LEHS.handle_exception_and_log_warn

PKG_LEHS.handle_exception_and_log_info

PKG_LEHS.handle_exception_and_log_debug

PKG_LEHS.handle_exception_and_log_trace

log

These Procedures will create a single Log-Entry because of a User defined Exception

PKG_LEHS.log_exception

PKG_LEHS.log_exception_fatal

PKG_LEHS.log_exception_error

PKG_LEHS.log_exception_warn

PKG_LEHS.log_exception_info

PKG_LEHS.log_exception_debug

PKG_LEHS.log_exception_trace

log

These Procedures will create a single Log-Entry because of a caught Exception (user defined or non user defined)

PKG_LEHS.assert

PKG_LEHS.assert_fatal

PKG_LEHS.assert_error

PKG_LEHS.assert_warn

PKG_LEHS.assert_info

PKG_LEHS.assert_debug

PKG_LEHS.assert_trace

log

These Procedures will create a single Log-Entry only if the Assertion fails

PKG_LEHS.start_log_transaction start_log_transaction Starts a new Log Transaction (ID will be created by LEHS and delegated to the Appender Package Procedure)

PKG_LEHS.end_log_transaction end_log_transaction Ends the actual Log Transaction (ID will be managed by LEHS and delegated to the Appender Package Procedure)

PKG_LEHS.add_transaction_key add_transaction_key Adds a Transaction Key to the actual Log Transaction

For more Usage Notes please refer to the Document Use LEHS.

Example of an Appender Package

Here's an Example of an Appender Package Specification with all available predefined Procedures:

CREATE OR REPLACE PACKAGE pkg_appender_example IS
  -- only mandatory Procedure of an Appender Package
  -- handles a single Log-Entry given by the LEHS System
  PROCEDURE log (
    pi_log_line IN PKG_LEHS_APPENDER.pr_log_line
  );
  
  -- Registers an Appender Package as an Appender
  -- (called by PKG_LEHS_SYSTEM.register_appender)
  PROCEDURE register (
    pi_application IN PKG_LEHS_APPENDER.pst_application_name
  );
  
  -- Deregisters an Appender Package
  -- (called by PKG_LEHS_SYSTEM.deregister_appender)
  PROCEDURE deregister (
    pi_application IN PKG_LEHS_APPENDER.pst_application_name
  );

  -- Checks a Parameter of Datatype CLOB
  -- (called by PKG_LEHS_SYSTEM.set_appender_parameter)  
  PROCEDURE check_param (
    pi_application IN PKG_LEHS_APPENDER.pst_application_name
   ,pi_key         IN PKG_LEHS_APPENDER.pst_parameter_name
   ,pi_value       IN PKG_LEHS_APPENDER.pst_param_value_clob
  );

  -- Checks a Parameter of Datatype NUMBER
  -- (called by PKG_LEHS_SYSTEM.set_appender_parameter)  
  PROCEDURE check_param (
    pi_application IN PKG_LEHS_APPENDER.pst_application_name
   ,pi_key         IN PKG_LEHS_APPENDER.pst_parameter_name
   ,pi_value       IN PKG_LEHS_APPENDER.pst_param_value_number
  );

  -- Checks a Parameter of Datatype DATE
  -- (called by PKG_LEHS_SYSTEM.set_appender_parameter)  
  PROCEDURE check_param (
    pi_application IN PKG_LEHS_APPENDER.pst_application_name
   ,pi_key         IN PKG_LEHS_APPENDER.pst_parameter_name
   ,pi_value       IN PKG_LEHS_APPENDER.pst_param_value_date
  );

  -- Checks a Parameter of Datatype TIMESTAMP
  -- (called by PKG_LEHS_SYSTEM.set_appender_parameter)  
  PROCEDURE check_param (
    pi_application IN PKG_LEHS_APPENDER.pst_application_name
   ,pi_key         IN PKG_LEHS_APPENDER.pst_parameter_name
   ,pi_value       IN PKG_LEHS_APPENDER.pst_param_value_timestamp
  );

  -- Checks a Parameter of Datatype INTERVAL DAY TO SECOND
  -- (called by PKG_LEHS_SYSTEM.set_appender_parameter)  
  PROCEDURE check_param (
    pi_application IN PKG_LEHS_APPENDER.pst_application_name
   ,pi_key         IN PKG_LEHS_APPENDER.pst_parameter_name
   ,pi_value       IN PKG_LEHS_APPENDER.pst_param_value_interval_ds
  );

  -- Checks a Parameter of Datatype INTERVAL YEAR TO MONTH
  -- (called by PKG_LEHS_SYSTEM.set_appender_parameter)  
  PROCEDURE check_param (
    pi_application IN PKG_LEHS_APPENDER.pst_application_name
   ,pi_key         IN PKG_LEHS_APPENDER.pst_parameter_name
   ,pi_value       IN PKG_LEHS_APPENDER.pst_param_value_interval_ym
  );
  
  -- initializes the Appender Package for the given
  -- Log-Application (called by PKG_LEHS_LOG_INTERNAL.resync)
  PROCEDURE initialize (
    pi_application IN PKG_LEHS_APPENDER.pst_application_name
  );
  
  -- Sets a registered Parameter of Datatype CLOB
  -- (called by PKG_LEHS_LOG_INTERNAL.resync)
  PROCEDURE set_param (
    pi_application IN PKG_LEHS_APPENDER.pst_application_name
   ,pi_key         IN PKG_LEHS_APPENDER.pst_parameter_name
   ,pi_value       IN PKG_LEHS_APPENDER.pst_param_value_clob
  );
  
  -- Sets a registered Parameter of Datatype NUMBER
  -- (called by PKG_LEHS_LOG_INTERNAL.resync)
  PROCEDURE set_param (
    pi_application IN PKG_LEHS_APPENDER.pst_application_name
   ,pi_key         IN PKG_LEHS_APPENDER.pst_parameter_name
   ,pi_value       IN PKG_LEHS_APPENDER.pst_param_value_number
  );
  
  -- Sets a registered Parameter of Datatype DATE
  -- (called by PKG_LEHS_LOG_INTERNAL.resync)
  PROCEDURE set_param (
    pi_application IN PKG_LEHS_APPENDER.pst_application_name
   ,pi_key         IN PKG_LEHS_APPENDER.pst_parameter_name
   ,pi_value       IN PKG_LEHS_APPENDER.pst_param_value_date
  );
  
  -- Sets a registered Parameter of Datatype TIMESTAMP
  -- (called by PKG_LEHS_LOG_INTERNAL.resync)
  PROCEDURE set_param (
    pi_application IN PKG_LEHS_APPENDER.pst_application_name
   ,pi_key         IN PKG_LEHS_APPENDER.pst_parameter_name
   ,pi_value       IN PKG_LEHS_APPENDER.pst_param_value_timestamp
  );
  
  -- Sets a registered Parameter of Datatype INTERVAL DAY TO SECOND
  -- (called by PKG_LEHS_LOG_INTERNAL.resync)
  PROCEDURE set_param (
    pi_application IN PKG_LEHS_APPENDER.pst_application_name
   ,pi_key         IN PKG_LEHS_APPENDER.pst_parameter_name
   ,pi_value       IN PKG_LEHS_APPENDER.pst_param_value_interval_ds
  );
  
  -- Sets a registered Parameter of Datatype INTERVAL YEAR TO MONTH
  -- (called by PKG_LEHS_LOG_INTERNAL.resync)
  PROCEDURE set_param (
    pi_application IN PKG_LEHS_APPENDER.pst_application_name
   ,pi_key         IN PKG_LEHS_APPENDER.pst_parameter_name
   ,pi_value       IN PKG_LEHS_APPENDER.pst_param_value_interval_ym
  );
  
  -- Checks if all mandatory Parameter have been set
  -- (called by PKG_LEHS_LOG_INTERNAL.resync)
  PROCEDURE after_initialize_check (
    pi_application IN PKG_LEHS_APPENDER.pst_application_name
  );
  
  -- Cleans up the internal Buffer to the Log-Application
  -- (called by PKG_LEHS_LOG_INTERNAL.resync if already initialized)
  PROCEDURE cleanup (
    pi_application IN PKG_LEHS_APPENDER.pst_application_name
  );
  
  -- Starts a new Log Transaction
  -- (called by PKG_LEHS.start_log_transaction)
  PROCEDURE start_log_transaction (
    pi_application IN PKG_LEHS_APPENDER.pst_application_name
   ,pi_transaction IN BINARY_INTEGER
  );
  
  -- Ends a Log Transaction
  -- (called by PKG_LEHS.end_log_transaction)
  PROCEDURE end_log_transaction (
    pi_application IN PKG_LEHS_APPENDER.pst_application_name
   ,pi_transaction IN BINARY_INTEGER
  );
  
  -- Adds a Transaction Key of Datatype CLOB
  -- (called by PKG_LEHS.add_transaction_key)
  PROCEDURE add_transaction_key (
    pi_application IN PKG_LEHS_APPENDER.pst_application_name
   ,pi_transaction IN BINARY_INTEGER
   ,pi_key         IN VARCHAR2
   ,pi_value       IN CLOB
  );
  
  -- Adds a Transaction Key of Datatype NUMBER
  -- (called by PKG_LEHS.add_transaction_key)
  PROCEDURE add_transaction_key (
    pi_application IN PKG_LEHS_APPENDER.pst_application_name
   ,pi_transaction IN BINARY_INTEGER
   ,pi_key         IN VARCHAR2
   ,pi_value       IN NUMBER
  );
  
  -- Adds a Transaction Key of Datatype DATE
  -- (called by PKG_LEHS.add_transaction_key)
  PROCEDURE add_transaction_key (
    pi_application IN PKG_LEHS_APPENDER.pst_application_name
   ,pi_transaction IN BINARY_INTEGER
   ,pi_key         IN VARCHAR2
   ,pi_value       IN DATE
  );
  
  -- Adds a Transaction Key of Datatype TIMESTAMP
  -- (called by PKG_LEHS.add_transaction_key)
  PROCEDURE add_transaction_key (
    pi_application IN PKG_LEHS_APPENDER.pst_application_name
   ,pi_transaction IN BINARY_INTEGER
   ,pi_key         IN VARCHAR2
   ,pi_value       IN TIMESTAMP_UNCONSTRAINED
  );
  
  -- Adds a Transaction Key of Datatype INTERVAL DAY TO SECOND
  -- (called by PKG_LEHS.add_transaction_key)
  PROCEDURE add_transaction_key (
    pi_application IN PKG_LEHS_APPENDER.pst_application_name
   ,pi_transaction IN BINARY_INTEGER
   ,pi_key         IN VARCHAR2
   ,pi_value       IN DSINTERVAL_UNCONSTRAINED
  );
  
  -- Adds a Transaction Key of Datatype INTERVAL YEAR TO MONTH
  -- (called by PKG_LEHS.add_transaction_key)
  PROCEDURE add_transaction_key (
    pi_application IN PKG_LEHS_APPENDER.pst_application_name
   ,pi_transaction IN BINARY_INTEGER
   ,pi_key         IN VARCHAR2
   ,pi_value       IN YMINTERVAL_UNCONSTRAINED
  );
END pkg_appender_example;
/