Module to supply the functions necessary to create a logfile and an
associated event describing the action which took place.
The Module has to stay independent. Thus no reference to
SYSMOD routines or fields might be taken.

The purpose of this module is to enable the easy and error-free creation of process logs in transactions which are used in technical areas like reorganizations, cleanup processes or manager running in background.

The module provides the following functionality:

• Integration of LOGDSP to display logs
• Supply routines to create a log
• Automated creation of a Event of type System
• Optional usable without SYSMOD
• Optional usable without access to database table (for installation routines)
• All Logged texts are automatically prefixed with date and time
• Text lines of more than 80 characters are automatically wrapped to multiple text lines
• Multiline texts are automatically indented
• Support of empty lines to separate different parts of a log
• Automatic setting of Error-Returncode Events in case of error exits and application exists
• In private logs the automatic creation of unique log file names is based on the transaction name and the current date and time. The format of the filename is <trn>.<yyyymmdd>.<hhmmssdd>.log.
• Support for shared logs used by more than one process
• Support for switching of logs (closing the old log file an continue the log in a new log file)
• Switch on configurable file size
• Switch on configurable times per day
• Assignment of different severities to mark log entries
• Automatically create a summary with the number of the different logged severity levels
• Performance optimized switch checking with configurable maximum frequency

To display a log within other transactions, the following steps need to be taken:

• Integrate LOGDSP into an appropriate module or into the transaction
• The file name of the selected log might be extracted out of an event text via a call to GetLogFilepath
• The file name of the log to be shown has to be made available to LOGDSP in the field LOGFIL
• A more descriptive name of the log used as heading to the popup panel might be put into the field LOGNAM. LOGDSP itself defaults LOGNAM to the filename of the log.

Should be called in the Init to generate the default header with

• displaying the names of transaction and user, who started the transaction
• identifying the servers
• a note, stating whether the transaction has been called in the foreground or background
• optionally displaying the work environment in the batch mode of the command line
• displaying the database used. 

The following has to be considered when implementing a processing log:

1. The processing context must be identifiable in the log, i.e. which settings have been used in which environment for the processing. These data (as far as they are not modifiable) can be displayed at the beginning of the log once.
   
2. If there exist multiple processing steps, the intermediate results should be displayed in order to show the progress of the procedure.
   
3. A processing cycle or a longer-term closed action should be stated should be specified at the end and at the beginning of each log.
   
4. In case large numbers of elements are processed, the numbers of the processed elements should be displayed.
   
5. All error or warning messages have to be displayed.
   
6. The log entries have to be that clear, that they could be understood by people, who do not know the implemented logic.
   Specifying an INR, for example, is technically unambiguous, but has absolutely no meaning for a 'common' user. If  the EXTKEY or the  OWNREF or the like are specified besides the INR provides much more understandable information in order to identify the object that causes an error.
   
7. A log may not be too text-laden.
   The important information may not be hidden by a host of unimportant details or texts. In particular, recurring data/texts should not be displayed.
   A switch that is used to set the level of detail of a log can be helpful. For example, if always the same path has to be displayed with varying file names , this path should be displayed once, followed by the file names.
   
8. A log must have a begin and end message.
   Thereby canceled logs can be identified and the total running time can be determined easily.

An additional type can be passed when calling. This type describes the meaning of the line or it marks the log line with a flag.

The originally passed textual description of the event. This Text concatenated with the filename of the Logfile will be stored in the Event.

This field holds the maximum size of a logfile in bytes. If a log grows beyond this size an automatic switch to a new log will take place. The default value preset in init of LOGMOD is 3096000 which stands for a size of 3 MB.

Name of the logfile where the logentries are written to. The field holds the complete filepath. The filename is generated by LOGMOD. If the file could not be created or opened two blanks are stored in the field.

This field holds the name of the shared logfile the module is currently writing to.

This field defines the default maximum frequency of checking the filesize. The default value of 0.01, which stands for once per minute, is set in the init of LOGMOD.

String to mark all hours with a nonspace character where a switch of the log should take place. The first character represents midnight or 0:00, the second 1:00 and so on.

Rule to automatically set the currently created log as log to be displayed

Function to build the lineprefix used to begin each line of a log.

Function to temporarily suspend an open log.
Filename of the currently used logfile is returned.
This returned filename should be used as argument to the corresponding call to ResumeLog.
The intended usage is to suspend an open log to be able to write an entry to a shared log.
In this case the sequence should be
$LogFil = LOGMOD.SuspendLog
LOGMOD.StartSharedLog( “xxx” )
LOGMOD.WriteLine( “xyz was processed” )
LOGMOD.CloseLog( “” )
LOGMOD.ResumeLog( $LogFil )

Corresponding function: ResumeLog

Function to write the summary of the currently written log.
The function returns the most severe level. The internal used sequence is:
blank → `O`ther → `I`nfo → `W`arning → `E`rror

ArgHea may be used to set the heading of the Summary. If a blank heading
is passed a default heading is used.
ArgFlg Passing a nonblank value clears the counter after output of the summary.

Corresponding functions: StartLog, StartSharedLog, WriteLine, CloseLog

Routine to check for automatic switching of the log due to size overrun or timer.
This routine might be called externally. It is internally called when writing loglines.
The following externally set fields control the switching to a new logfile:
MAXSIZ describes the maximum allowed size of a logfile. (Default: 3 MB)
SWTLST holds a list of hourmarkers for time controlled switching (Default: No time)
NXTADD describes the maximum frequency of the automatically executed checks (Default: 0.01, thus check not more often than every minute)

Corresponding functions: SwitchLog

Routine to finally update and close a log. If the counter of marked lines are set, the
Summary is automatically created with the default heading.
ArgRtn might optionally hold a returncode used to update the event created on entry.
After having used this function a DBCommit has to be issued by the calling transaction.

Corresponding functions: StartLog, StartSharedLog, WriteLine, WriteSummary

Routine to flag the current transaction as idle.
The intended usage is to call CommitLog after having complete a task when returning control to the user.
When using CommitLog at least one WriteLine should be executed before any data is amended.
After having completed the amendment and if necessary commited the amendments to the database
a call to CommitLog would flag the log as complete (up to now). Any further WriteLine would
restore the incomplete status.

On execution of an Interrupt check and optionally close a log

Routine to clear the counter per flag

Internal routine to initially clear all log fields

Internal routine to create the EVT entry.

Internal routine to create the filename of the processing log or the filename of an archive of
a shared logfile
Output is the created logfil with the filename stored in LOGFIL.

Internal routine to save the fields of the EVT into the local EVT module
Has internally to be used after creation of the logfile.
Database related fields like INR and Session-INR should be set separately.

Routine to finally update the evt entry of a log.
ArgRtn might optionally hold a returncode used to update the event created on entry.
After having used this function a DBCommit has to be issued by the calling transaction.

Corresponding functions: CloseLog

Part of the WriteLine routine to output the text into the logfile without switch checking.

Routine to finally update and close a log.
ArgRtn might optionally hold a returncode used to update the event created on entry.
After having used this function a DBCommit has to be issued by the calling transaction.

This routine is obsolete and the new routine CloseLog should be used.

Procedure to initially create a Log.
If possible an event is created holding a textual reference to the created logfile.
ArgTxt holds the text used in the event to describe the action, that will take place.

This routine is obsolete and the new routine StartLog should be used.

Inserts a Logentry / Logline into the open Log. The Log has to be started with the StartLog procedure in advance.
If the passed Text hold more than one line only the first line is prefixed by the current date and time.
The other lines are indented with space characters.

This routine is obsolete and the new routine WriteLine should be used.

Function to resume a temporarily suspended open log.
The filename returned by the preceding SuspendLog should be used as argument.

Corresponding function: SuspendLog

Open a new log and write a default header for standard transactions

Procedure to initially create a Log.
If possible an event is created holding a textual reference to the created logfile.
ArgTxt holds the text used in the event to describe the action, that will take place.

Corresponding functions: WriteLine, WriteSummary, CloseLog

Procedure to initially create a Log. The Event will be created upon closing of the
log. This is intended for routines like SYSDBA which initially create the necessary
database table.
The event is created holding a textual reference to the created logfile.
ArgTxt holds the text used in the event to describe the action, that will take place.

Corresponding functions: WriteLine, CloseLog

Procedure to initially create or extend a shared Log.
ArgLog holds the Basename of the shared log to be filled. (Default value is the Transactionname)
Corresponding functions: WriteLine, WriteSummary, CloseLog

Open a new log and write a header for standard transactions

Routine to close the current log and continue in a new logfile
ArgTxt holds an optional text describing the reason for the switch of the log, which
if set is inserted at the end of the old log.

Inserts a Logentry / Logline into the open Log. The Log has to be started with the StartLog or StartSharedLog procedure in advance.
ArgLin holds the Text to stored in the log.
If the passed Text hold more than one line only the first line is prefixed by the current date and time.
The other lines are indented with space characters.
ArgFlg holds an optional Flag to mark the severity of the entry

Corresponding functions: StartLog, StartSharedLog, WriteLineAndStatus, WriteSummary, CloseLog

Inserts a Logentry / Logline into the open log and shows the line in the statusline
The arguments are identical to the routine WriteLine.
ArgLin holds a line of text to be stored in the log.
ArgFlg holds an optional flag to mark the severity of the entry

Corresponding functions: WriteLine