LEHS - Log- and Exception Handling System for ORACLE

Overview

Deprecated

Index

Help

LEHS - Log- and Exception Handling System for ORACLE

FRAMES NO FRAMES

SUMMARY: FIELD | TYPE | METHOD

DETAIL: FIELD | TYPE | METHOD

Package pkg_lehs_appender

This Package is an Interface and a Utility Package for all Appenders.

In short Words: An Appender is a Package with at least a Procedure named log with only 1 Parameter of Datatype PKG_LEHS_APPENDER.pr_log_line. But such Package can have more than this one Procedure. Here's an Example of a possible Package Specification of an Appender Package:

 CREATE OR REPLACE PACKAGE a_appender_package IS
   -- This Procedure (with exactly this Signature) must be implemented
   -- to be recognized as a valid Appender Package
   PROCEDURE log (
     pi_log_line IN PKG_LEHS_APPENDER.pr_log_line
   );
 

   -- This Procedure will be called when the Appender-Package will be
   -- registered to a Log-Application by PKG_LEHS_SYSTEM.register_appender
   PROCEDURE register (
     pi_application IN PKG_LEHS_APPENDER.pst_application_name
   );
 

   -- This Procedure will be called when the Appender-Package will be
   -- deregistered from a Log-Application by PKG_LEHS_SYSTEM.deregister_appender
   PROCEDURE deregister (
     pi_application IN PKG_LEHS_APPENDER.pst_application_name
   );
 

   -- This Procedure will be called when a Log-Appender Parameter will be
   -- added or changed by PKG_LEHS_SYSTEM.set_appender_parameter for
   -- Values of type CLOB
   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
   );
 

   -- This Procedure will be called when a Log-Appender Parameter will be
   -- added or changed by PKG_LEHS_SYSTEM.set_appender_parameter for
   -- Values of type NUMBER
   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
   );
 

   -- This Procedure will be called when a Log-Appender Parameter will be
   -- added or changed by PKG_LEHS_SYSTEM.set_appender_parameter for
   -- Values of type DATE
   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
   );
 

   -- This Procedure will be called when a Log-Appender Parameter will be
   -- added or changed by PKG_LEHS_SYSTEM.set_appender_parameter for
   -- Values of type TIMESTAMP_UNCONSTRAINED
   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
   );
 

   -- This Procedure will be called when a Log-Appender Parameter will be
   -- added or changed by PKG_LEHS_SYSTEM.set_appender_parameter for
   -- Values of type DSINTERVAL_UNCONSTRAINED
   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
   );
 

   -- This Procedure will be called when a Log-Appender Parameter will be
   -- added or changed by PKG_LEHS_SYSTEM.set_appender_parameter for
   -- Values of type YMINTERVAL_UNCONSTRAINED
   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
   );
 

   -- This Procedure will be first called when the Appender-Package will
   -- be initialized to the given Log-Application
   PROCEDURE initialize (
     pi_application IN PKG_LEHS_APPENDER.pst_application_name
   );
 

   -- Sets the given Parameter at Runtime just before the first Usage
   -- of this Package for a Datatype CLOB
   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 the given Parameter at Runtime just before the first Usage
   -- of this Package for a Datatype NUMBER
   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 the given Parameter at Runtime just before the first Usage
   -- of this Package for a Datatype DATE
   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 the given Parameter at Runtime just before the first Usage
   -- of this Package for a Datatype TIMESTAMP
   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 the given Parameter at Runtime just before the first Usage
   -- of this Package for a Datatype INTERVAL DAY TO SECOND
   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 the given Parameter at Runtime just before the first Usage
   -- of this Package for a Datatype INTERVAL YEAR TO MONTH
   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
   );
 

   -- Will be called after all setter has been called
   PROCEDURE after_initialize_check (
     pi_application IN PKG_LEHS_APPENDER.pst_application_name
   );
 

   -- Will be called, when the Log-Application will be removed from memory
   PROCEDURE cleanup (
     pi_application IN PKG_LEHS_APPENDER.pst_application_name
   );
 

   -- When PKG_LEHS.start_log_transaction will be called this Procedure
   -- will be called for every registered Appender
   PROCEDURE start_log_transaction (
     pi_application IN PKG_LEHS_APPENDER.pst_application_name
    ,pi_transaction IN BINARY_INTEGER
   );
 

   -- When PKG_LEHS.end_log_transaction will be called this Procedure
   -- will be called for every registered Appender
   PROCEDURE end_log_transaction (
     pi_application IN PKG_LEHS_APPENDER.pst_application_name
    ,pi_transaction IN BINARY_INTEGER
   );
 

   -- Adds a Transaction Key with the Datatype CLOB
   -- Will be called by PKG_LEHS.add_transaction_key for every
   -- registered Appender
   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 with the Datatype NUMBER
   -- Will be called by PKG_LEHS.add_transaction_key for every
   -- registered Appender
   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 with the Datatype DATE
   -- Will be called by PKG_LEHS.add_transaction_key for every
   -- registered Appender
   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 with the Datatype TIMESTAMP
   -- Will be called by PKG_LEHS.add_transaction_key for every
   -- registered Appender
   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 with the Datatype INTERVAL DAY TO SECOND
   -- Will be called by PKG_LEHS.add_transaction_key for every
   -- registered Appender
   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 with the Datatype INTERVAL YEAR TO MONTH
   -- Will be called by PKG_LEHS.add_transaction_key for every
   -- registered Appender
   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 a_appender_package;

These Procedures can be divided into two Categories:

static Procedures
will be used to modify Appenders
- check_param
- deregister
- register
dynamic Procedures
will be called when the Appender is in use by LEHS
- add_transaction_key
- after_initialize_check
- cleanup
- end_log_transaction
- initialize
- log
- set_param
- start_log_transaction

static Procedures

Static Procedures will be called when an Appender will be changed. Either because the Appender will be registered or deregistered or one of its various Parameters will be changed.

Register an Appender

By calling PKG_LEHS_SYSTEM.register_appender you can register an Appender Package to an existing Log-Application. If you provide a Procedure named register with only a Parameter of Datatype PKG_LEHS_APPENDER.pst_application_name then this Procedure will be called just before this Appender will be registered to the Log-Application. The Log-Application, where the Appender will be registered to will be the Value of this Parameter.

Deregister an Appender

Whenever you no longer need an Log-Appender you can deregister it from an Log-Application. By doing this, this Appender will no longer be used for Log-Messages by the Log-Application the Appender has been deregistered from. If you provide a Procedure named deregister with only a Parameter of Datatype PKG_LEHS_APPENDER.pst_application_name then this Procedure will be called when deregistering this Appender from an existing Log-Application. The Log-Application, where the Appender will be deregistered from will be the Value of this Parameter.

Be aware that every Exception you deregister Procedure raises will be caught and logged to the Log-Application LEHS but this doesn't avoid your Appender to be deregistered from the given Log-Application.

Add, change or remove a Parameter of an Appender

Appenders are versatile. One Appender adds Rows to a Log-Table, the other just sends Mails to various Recipients. Because of this Diversity you can control the Behaviour of the Appenders by setting Parameters through the Procedure PKG_LEHS_SYSTEM.set_appender_parameter.

Because LEHS doesn't even know anything about the correct Parameters of a Log-Application it delegates the checking of the Parameters to the Appender itself. If the Appender doesn't provide a Checker Procedure to the Datatype of the Parameter to be set then LEHS expects, that this Parameter must be saved without any checkings.

A Parameter of an Appender is simply a Name=Value Pair. Following this Principle the Tasks of a Checker are the following:

Check the Name of the Parameter. Is the given Parameter a valid Parameter for this Appender. You can use the Procedure PKG_LEHS_APPENDER.raise_invalid_parameter_name to raise a standardized Exception if the Name of the Parameter is invalid
Check the Datatype of the Parameter. When the Datatype of the Value doesn't correspond the Parameter itself (i.E. a alphanumeric Value for a numeric Parameter) then an Exception should be raised. You can use the Procedure PKG_LEHS_APPENDER.raise_invalid_parameter_name to raise a standardized Exception if the Datatype of the Parameter is invalid.
Check the Value of the Parameter. Sometimes it is neccessary to check the Value of a Parameter (i.E. for specific Contents). You can do this by calling PKG_LEHS_APPENDER.assert_parameter_value. If the Assertion fails then a standardized Exception Message will be raised. The Value of the Parameter pi_error_message will be appended to this standardized Exception Message (to set a clearer Description why the checking has been failed).

Every raised Exception leads, that the Parameter would not be touched by the Procedure PKG_LEHS_SYSTEM.set_appender_parameter. The raised Exception will be logged and looped through the Caller of the Procedure PKG_LEHS_SYSTEM.set_appender_parameter.

dynamic Procedures

Dynamic Procedures will be called during the usage of the Log-Application by the API of LEHS. In accordance of its usage the Procedures will be called at 3 different timestamps:

Timestamp of Call	Procedures
First Call of any Procedure of Package `PKG_LEHS`	`cleanup` This Procedure will only be called, if the Appender has already been initialized once just before `initialize` This Procedure will be called once for every Appender. `set_param` For every Appender Parameter (which has been set by the Procedure `PKG_LEHS_SYSTEM.set_appender_parameter`) this Procedure will be called. `after_initialize_check` After all Appender Parameters has been set successfully this Procedure will be called to give the Appender a chance to check, if all neccessary Parameters has been set.
Every Call of any of these Procedures: `PKG_LEHS.log` `PKG_LEHS.fatal` `PKG_LEHS.error` `PKG_LEHS.warn` `PKG_LEHS.info` `PKG_LEHS.debug` `PKG_LEHS.trace` `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` `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` `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`
Every Call of the Procedures `PKG_LEHS.start_log_transaction`	`start_log_transaction`
Every Call of the Procedures `PKG_LEHS.add_transaction_key`	`add_transaction_key`
Every Call of the Procedures `PKG_LEHS.end_log_transaction`	`end_log_transaction`

Exceptions raised by the dynamic Procedures

In the opposite to the static Procedures, dynamic Procedures don't lead to a crash of the Application which uses the Log-Application. Instead, these Errors will be logged to the Log-Application LEHS and the Appender would either not be initialized (if the Exception has been raised by either the Procedure initialize, set_param or check_after_initialize) or the requested Action will not be executed correctly (either because the Procedure log has raised an Exception or one of the Procedures start_log_transaction, end_log_transaction or add_transaction_key raised an Exception).

Cleanup the Appender

When you call PKG_LEHS.resync, every initialized Appender will be removed from the internal Buffer. When an Appender will be removed from the internal Buffer, the Procedure cleanup will be called (if this Procedure is implemented).

The only allowed Parameter is of Datatype PKG_LEHS_APPENDER.pst_application_name. The Value of this Parameter is the Name of the Log-Application, the Package has been registered to and will be cleaned up.

The Procedure cleanup is used, to clean up the internal Memory Structures of the Appender, which has been set by the Initialization or during the Runtime.

This Procedure will also be called, if the Application will be resynced because any Setting of the Log-Application has been changed.

Initialize the Appender

Every Appender Package can be used by several Log-Applications. Any Database User can use several Log-Applications. The End: Any Database Session can use the same Appender Package by several Log-Applications at the same Time. This rules, that any Appender Package must handle several Log-Applications at the same Time within the same PGA (or UGA in the case of shared Server).
You as a Developer of an Appender Package must take care of this to handle all these Log-Applications in an internal Memory Structure. This is the Reason, why LEHS gives you ALWAYS the Log-Application as a Parameter (and why you have to provide all the optional Procedures with at least a Parameter of Datatype PKG_LEHS_APPENDER.pst_application_name or by the Record-Structure PKG_LEHS_APPENDER.pr_log_line for the Procedure log).

The best Way to do this is an internal PL/SQL associative Array (indexed by the Datatype PKG_LEHS_APPENDER.pst_application_name). This is the Reason for exactly the Procedure initialize, to initialize this internally used Memory-Structure.

Set the Appender Parameters

Every Appender Parameter, which has been registered to a Log-Appender (set by the Procedure PKG_LEHS_SYSTEM.set_appender_parameter) will be given to the Appender Package at the Initialization by the Procedure set_param. This Procedure must have at least 3 Parameters:

A Parameter of Datatype PKG_LEHS_APPENDER.pst_application_name, which sets the Name of the Log-Application as its Value
A Parameter of Datatype PKG_LEHS_APPENDER.pst_parameter_name, which sets the Name of the Appender Parameter as its Value
A Parameter of any of the following Datatypes, which sets the Value of the Appender Parameter:
- PKG_LEHS_APPENDER.pst_param_value_clob
  Parameters with a Value of Datatype CLOB
- PKG_LEHS_APPENDER.pst_param_value_number
  Parameters with a Value of Datatype NUMBER
- PKG_LEHS_APPENDER.pst_param_value_date
  Parameters with a Value of Datatype DATE
- PKG_LEHS_APPENDER.pst_param_value_timestamp
  Parameters with a Value of Datatype TIMESTAMP
- PKG_LEHS_APPENDER.pst_param_value_interval_ds
  Parameters with a Value of Datatype INTERVAL DAY TO SECOND
- PKG_LEHS_APPENDER.pst_param_value_interval_ym
  Parameters with a Value of Datatype INTERVAL YEAR TO MONTH
The Datatype of the Parameter has to correspond with the identic Checker-Procedure (check_param)

These Appender Parameters should be managed through the Appender Package by an internally used PL/SQL associative Array (indexed by Datatype PKG_LEHS_APPENDER.pst_application_name. Here's an Example, how this internal Structure can be used:

 CREATE OR REPLACE PACKAGE a_appender_package IS
   pc_param_retention_time CONSTANT PKG_LEHS_APPENDER.pst_parameter_name
     := 'RETENTION TIME';
   pc_param_trx_timeout CONSTANT PKG_LEHS_APPENDER.pst_parameter_name
     := 'TRANSACTION TIMEOUT';
   -- several other Procedures (incl. log) would follow here
 END a_appender_package;
 

 CREATE OR REPLACE PACKAGE BODY a_appender_package IS
   TYPE pr_values IS RECORD (
     retention_time PKG_LEHS_APPENDER.pst_param_value_number
    ,trx_timeout    PKG_LEHS_APPENDER.pst_param_value_number
   );
   TYPE pt_values IS TABLE OF pr_values
     INDEX BY PKG_LEHS_APPENDER.pst_application_name;
   pv_values PT_VALUES;
   -- several other Procedure Implementations (incl. log) would follow here
 END a_appender_package;

Check after the Appender Initialization

If a Package has some Parameters, which are really neccessary to be set because the Package doesn't work without these Parameters (for the specified Log-Application) you can check, if these Parameters has been set by implementing a Procedure after_initialize_check. When for some Reason, a mandatory Parameter has not been set (because it has been forgotten), then this Procedure has to check this and raises an Exception if mandatory Parameters are not set. This Exception would lead to an uninitialized Appender, which itself would cause a Log-Entry to the internal Log-Application LEHS and the Appender would not be recognized during the Runtime of the Application.

Create a Log Entry

The core of every Appender Package is the Procedure log. Every Log-Entry will be made by calling the Procedure log of every registered and successfully initialized Appender. Therefor, the Procedure log is of course the only real mandatory Procedure of an Appender Package.

The Procedure log has only one Parameter of the Datatype PKG_LEHS_APPENDER.pr_log_line, which in fact includes all Information to make the Log-Entry. If you look at the Table above, you can see, that several Procedures of the Package PKG_LEHS would lead to a Call of the Procedure log (including several Exception Handling Routines). So it is really vital, that this Procedure handles the Log-Entry very fast and doesn't really lead to expensive Exceptions.

If the Procedure log raises an Exception, this Exception would itself be logged to the Log-Application LEHS. If, for any Instance, there is also a misconfiguration at any Appender of the Log-Application LEHS, this would lead to a Log-Entry of the Session Trace File (this is the last sheet anchor for the Application itself, that this very fatal Exception has been logged anywhere).

Start a Log Transaction

A Log Transaction is a logical Compendium of Log-Entries. A Log Transaction will be started by PKG_LEHS.start_log_transaction. LEHS creates a unique Transaction ID which it will provide the optional Procedure start_log_transaction for every registered and successfully initialized Appender.

Add a Transaction Key

To find created Log-Transactions you can add Keywords in a name=value Form. These Keywords can be used to find Log-Transactions, which have been started by PKG_LEHS.start_log_transaction.

Like check_param or set_param the Keywords can be of several Datatypes (CLOB, NUMBER, DATE, TIMESTAMP, INTERVAL DAY TO SECOND or INTERVAL YEAR TO MONTH. Look at the Package PKG_LEHS to find the various Implementations of add_transaction_key (the Procedure add_transaction_key with the Value Datatype VARCHAR2 results in a Transaction Key with the Datatype CLOB).

End a Log Transaction

When you start a Log-Transaction by calling PKG_LEHS.start_log_transaction the generated Transaction ID will be provided for every Log-Entry until you end the Log-Transaction by calling PKG_LEHS.end_log_transaction.

For every registered and successfully initialized Appender the optional Procedure end_log_transaction will be called, if you end an active Log-Transaction by PKG_LEHS.end_log_transaction.

Sequence of the Parameters

If you look above at the Example Appender-Package, then you can see, that some Procedures have more than one Parameter. It really doesn't matter how you name these Parameters, but the Datatypes and the Sequence of these Parameters are relevant. They really must have these Datatypes and the Sequence. Instead, the Initialization and/or the Runtime would cause, that this Appender would not be recognized and leads to a Log-Entry to the Log-Application LEHS.

Field Summary
`VARCHAR2(30)`	`pc_default_log_format` Default Log-Format: `%d [%a:%T:%p] %M[TX=%t]: %m`
`VARCHAR2(250)`	`pc_default_log_time_format` Default Log-Time Format: `FMDD.MMFM.RRRR FMHH24FM:MI:SS:FF6`
`VARCHAR2(30)`	`pc_packname` Name of the Package
`VARCHAR2(30)`	`pc_type_app_name` Name of the Datatype for the Application Name: `PST_APPLICATION_NAME`
`VARCHAR2(30)`	`pc_type_log_line` Name of the Log Record: `PR_LOG_LINE`

Type Summary
`RECORD`	`pr_app_parameters(appender_name LEHS_APPENDER.appender_name%TYPE, max_log_level LEHS_APPENDER.max_log_level%TYPE, log_levels PT_LOG_LEVELS, parameters PT_PARAMETERS)` All neccessary Information to a specific Appender
`RECORD`	`pr_caller(owner VARCHAR2(30), method VARCHAR2(30), line# BINARY_INTEGER)` Where has the Call been made
`RECORD`	`pr_log_line(application PKG_LEHS.pst_application_name, log_time TIMESTAMP_UNCONSTRAINED, log_level LEHS_LOG_LEVELS.log_level%TYPE, log_topic LEHS_TOPICS.topic_name%TYPE, log_transaction PKG_LEHS.pst_log_transaction, log_caller pr_caller, log_message CLOB)` Representation of one Log-Entry
`RECORD`	`pr_parameter(datatype LEHS_APPENDER_PARAMETERS.datatype%TYPE, value_clob PST_PARAM_VALUE_CLOB, value_number PST_PARAM_VALUE_NUMBER, value_date PST_PARAM_VALUE_DATE, value_timestamp PST_PARAM_VALUE_TIMESTAMP, value_interval_day_to_second PST_PARAM_VALUE_INTERVAL_DS, value_interval_year_to_month PST_PARAM_VALUE_INTERVAL_YM)` Representation of the Value of one Appender Parameter
`PKG_LEHS.pst_application_name`	`pst_application_name()` Datatype of the Application Name
`LEHS_APPENDER_PARAMETERS.value_clob%TYPE`	`pst_param_value_clob()` Datatype of a `CLOB`-Parameter
`LEHS_APPENDER_PARAMETERS.value_date%TYPE`	`pst_param_value_date()` Datatype of a `DATE`-Parameter
`LEHS_APPENDER_PARAMETERS.value_interval_day_to_second%TYPE`	`pst_param_value_interval_ds()` Datatype of an `INTERVAL DAY TO SECOND`-Parameter
`LEHS_APPENDER_PARAMETERS.value_interval_year_to_month%TYPE`	`pst_param_value_interval_ym()` Datatype of an `INTERVAL YEAR TO MONTH`-Parameter
`LEHS_APPENDER_PARAMETERS.value_number%TYPE`	`pst_param_value_number()` Datatype of a `NUMBER`-Parameter
`LEHS_APPENDER_PARAMETERS.value_timestamp%TYPE`	`pst_param_value_timestamp()` Datatype of a `TIMESTAMP`-Parameter
`LEHS_APPENDER_PARAMETERS.parameter%TYPE`	`pst_parameter_name()` Datatype of the Parameter Name (Key)
`TABLE OF pr_app_parameters INDEX BY pst_application_name`	`pt_app_parameters()` List of neccessary Appender Information
`TABLE OF BINARY_INTEGER INDEX BY LEHS_LOG_LEVELS.log_level%TYPE`	`pt_log_levels()` List of valid Log-Levels
`TABLE OF pr_parameter INDEX BY pst_parameter_name`	`pt_parameters()` List of Appender Parameters

Method Summary
	`assert_parameter_value(pi_assertion BOOLEAN, pi_parameter_name pst_parameter_name, pi_parameter_value pst_param_value_clob, pi_error_message CLOB DEFAULT NULL)` If the Assertion fails then a standardized Exception will be thrown.
	`assert_parameter_value(pi_assertion BOOLEAN, pi_parameter_name pst_parameter_name, pi_parameter_value pst_param_value_number, pi_error_message CLOB DEFAULT NULL)` If the Assertion fails then a standardized Exception will be thrown.
	`assert_parameter_value(pi_assertion BOOLEAN, pi_parameter_name pst_parameter_name, pi_parameter_value pst_param_value_date, pi_error_message CLOB DEFAULT NULL)` If the Assertion fails then a standardized Exception will be thrown.
	`assert_parameter_value(pi_assertion BOOLEAN, pi_parameter_name pst_parameter_name, pi_parameter_value pst_param_value_timestamp, pi_error_message CLOB DEFAULT NULL)` If the Assertion fails then a standardized Exception will be thrown.
	`assert_parameter_value(pi_assertion BOOLEAN, pi_parameter_name pst_parameter_name, pi_parameter_value pst_param_value_interval_ds, pi_error_message CLOB DEFAULT NULL)` If the Assertion fails then a standardized Exception will be thrown.
	`assert_parameter_value(pi_assertion BOOLEAN, pi_parameter_name pst_parameter_name, pi_parameter_value pst_param_value_interval_ym, pi_error_message CLOB DEFAULT NULL)` If the Assertion fails then a standardized Exception will be thrown.
`CLOB`	`format_log_message(pi_log_line pr_log_line, pi_format pst_param_value_clob DEFAULT pc_default_log_format)` Formats a given Log-Line by the specified Format.
`pt_app_parameters`	`get_appender_parameters()` Get all neccessary Information for all registered Appenders, where the calling Package has been registered to.
	`raise_invalid_parameter_name(pi_parameter_name pst_parameter_name, pi_parameter_value pst_param_value_clob)` Raises the standardized Exception for any Parameter Error.
	`raise_invalid_parameter_name(pi_parameter_name pst_parameter_name, pi_parameter_value pst_param_value_number)` Raises the standardized Exception for any Parameter Error.
	`raise_invalid_parameter_name(pi_parameter_name pst_parameter_name, pi_parameter_value pst_param_value_date)` Raises the standardized Exception for any Parameter Error.
	`raise_invalid_parameter_name(pi_parameter_name pst_parameter_name, pi_parameter_value pst_param_value_timestamp)` Raises the standardized Exception for any Parameter Error.
	`raise_invalid_parameter_name(pi_parameter_name pst_parameter_name, pi_parameter_value pst_param_value_interval_ds)` Raises the standardized Exception for any Parameter Error.
	`raise_invalid_parameter_name(pi_parameter_name pst_parameter_name, pi_parameter_value pst_param_value_interval_ym)` Raises the standardized Exception for any Parameter Error.

Field Detail

pc_packname

  public VARCHAR2(30) pc_packname

Name of the Package

pc_default_log_format

  public VARCHAR2(30) pc_default_log_format

Default Log-Format: %d [%a:%T:%p] %M[TX=%t]: %m

pc_default_log_time_format

  public VARCHAR2(250) pc_default_log_time_format

Default Log-Time Format: FMDD.MMFM.RRRR FMHH24FM:MI:SS:FF6

pc_type_log_line

  public VARCHAR2(30) pc_type_log_line

Name of the Log Record: PR_LOG_LINE

pc_type_app_name

  public VARCHAR2(30) pc_type_app_name

Name of the Datatype for the Application Name: PST_APPLICATION_NAME

Type Detail

pst_application_name

  public PKG_LEHS.pst_application_name pst_application_name()

Datatype of the Application Name

pst_parameter_name

  public LEHS_APPENDER_PARAMETERS.parameter%TYPE pst_parameter_name()

Datatype of the Parameter Name (Key)

pst_param_value_clob

  public LEHS_APPENDER_PARAMETERS.value_clob%TYPE pst_param_value_clob()

Datatype of a CLOB-Parameter

pst_param_value_number

  public LEHS_APPENDER_PARAMETERS.value_number%TYPE pst_param_value_number()

Datatype of a NUMBER-Parameter

pst_param_value_date

  public LEHS_APPENDER_PARAMETERS.value_date%TYPE pst_param_value_date()

Datatype of a DATE-Parameter

pst_param_value_timestamp

  public LEHS_APPENDER_PARAMETERS.value_timestamp%TYPE pst_param_value_timestamp()

Datatype of a TIMESTAMP-Parameter

pst_param_value_interval_ds

  public LEHS_APPENDER_PARAMETERS.value_interval_day_to_second%TYPE pst_param_value_interval_ds()

Datatype of an INTERVAL DAY TO SECOND-Parameter

pst_param_value_interval_ym

  public LEHS_APPENDER_PARAMETERS.value_interval_year_to_month%TYPE pst_param_value_interval_ym()

Datatype of an INTERVAL YEAR TO MONTH-Parameter

pr_parameter

  public RECORD pr_parameter(datatype LEHS_APPENDER_PARAMETERS.datatype%TYPE, 
                             value_clob PST_PARAM_VALUE_CLOB, 
                             value_number PST_PARAM_VALUE_NUMBER, 
                             value_date PST_PARAM_VALUE_DATE, 
                             value_timestamp PST_PARAM_VALUE_TIMESTAMP, 
                             value_interval_day_to_second PST_PARAM_VALUE_INTERVAL_DS, 
                             value_interval_year_to_month PST_PARAM_VALUE_INTERVAL_YM)

Representation of the Value of one Appender Parameter

pt_parameters

  public TABLE OF pr_parameter INDEX BY pst_parameter_name pt_parameters()

List of Appender Parameters

pt_log_levels

  public TABLE OF BINARY_INTEGER INDEX BY LEHS_LOG_LEVELS.log_level%TYPE pt_log_levels()

List of valid Log-Levels

pr_app_parameters

  public RECORD pr_app_parameters(appender_name LEHS_APPENDER.appender_name%TYPE, 
                                  max_log_level LEHS_APPENDER.max_log_level%TYPE, 
                                  log_levels PT_LOG_LEVELS, 
                                  parameters PT_PARAMETERS)

All neccessary Information to a specific Appender

pt_app_parameters

  public TABLE OF pr_app_parameters INDEX BY pst_application_name pt_app_parameters()

List of neccessary Appender Information

pr_caller

  public RECORD pr_caller(owner VARCHAR2(30), 
                          method VARCHAR2(30), 
                          line# BINARY_INTEGER)

Where has the Call been made

pr_log_line

  public RECORD pr_log_line(application PKG_LEHS.pst_application_name, 
                            log_time TIMESTAMP_UNCONSTRAINED, 
                            log_level LEHS_LOG_LEVELS.log_level%TYPE, 
                            log_topic LEHS_TOPICS.topic_name%TYPE, 
                            log_transaction PKG_LEHS.pst_log_transaction, 
                            log_caller pr_caller, 
                            log_message CLOB)

Representation of one Log-Entry

Method Detail

format_log_message

  public CLOB format_log_message(pi_log_line pr_log_line, 
                                 pi_format pst_param_value_clob DEFAULT pc_default_log_format)

Formats a given Log-Line by the specified Format.

You can use the following Tokens for the Log Format. Every Literal will be printed as it is defined.

%a ... Name of the Log-Application
%d[opt. Format] ... Log-Time with an optional Format
If the Format is omitted the Default-Format FMDD.MMFM.RRRR FMHH24FM:MI:SS:FF6 will be taken
%M ... The producing Method
%p ... The used Log-Level
%T ... The Log-Topic
%t ... The Log-Transaction
%m ... The Log-Message
%% ... %-Sign

When omitting the Log-Format the Default-Format is: %d [%a:%T:%p] %M[TX=%t]: %m

Parameters:: pi_log_line - Log-Line to be formatted; pi_format - Format of the Log-Line

get_appender_parameters

  public pt_app_parameters get_appender_parameters()

Get all neccessary Information for all registered Appenders, where the calling Package has been registered to.

An Appender Package can be registered as an Appender for several Log-Applications. If an Appender Package needs Information about the Register Information outside the Runtime of an Applicaiton, then this Appender Package can call this Procedure. It provides the following Information:

The Name of the Appender, which the Package has been registered to
The maximum Log-Level of this Appender
the valid Log-Levels of the Log-Application, this Package has been registered to as an Appender
All registered Appender Parameters
The Name of the Log-Application the Appender Package has been registered to as the Key of the PL/SQL associative Array

This Procedure checks the Call Stacktrace so that it provides only the Information for the Package, it has been called from. If, for Example, you have a Package PKG_APPENDER_PACKAGE and you call this Procedure from within this Package, you would get the Information, where the Package PKG_APPENDER_PACKAGE has been used and which Parameter has been set to by LEHS.

This Information can be useful if you have an offline Procedure, which will be called asynchronous (within any other Session) and the Parameters for this asynchronous Procedure itself will be managed by the Appender Parameters. (Look at PKG_LEHS_TABLE_APPENDER.cleanup.

If the calling Package has not been registered as an Appender to any Log-Application then an empty PL/SQL associative Array will be returned.

Returns:: all Parameters neccessary for the Appender Package