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 ) |
3. |
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 ) |
3. |
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 ) |
4. |
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
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
.
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:
- Name of the Log-Application (Datatype:
PKG_LEHS_APPENDER.pst_application_name
)
- Name of the Appender Parameter (Datatype:
PKG_LEHS_APPENDER.pst_parameter_name
)
- 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;
/