Implementation of a Class supporting Logging with a DRAMA GIT Task. More...

#include <gitlogger.h>

Public Member Functions
	GitLogger (const char system, StatusType status, const char *dir=0, bool compress=false)
	Construct a GitLogger object.

void	CheckDayChange (int newDay, StatusType *status)
	Internal use only.

void	Log (const IMP_AbsTime time, unsigned level, bool nofmt, const char prefix, StatusType status, const char fmt,...)
	Log a message with a specified event time.

void	Log (unsigned level, bool nofmt, const char prefix, StatusType status, const char *fmt,...)
	Log a message.

void	Set (unsigned newFileLevels, unsigned newScreenLevels, StatusType *status)
	Enable new logging levels.

void	Unset (unsigned newFileLevels, unsigned newScreenLevels, StatusType *status)
	Clear existing logging levels.

Static Public Member Functions
static GitLogger *	GetLogger (StatusType *const status)
	Get the logger object.

static void	SetTimeOffset (long int t)
	Change the time offset.

Friends
FILE *	GitLoggerFile (StatusType *status)
	C interface to fetching the log file pointer.

void	GitLoggerFlushAlways (int flag, StatusType *status)
	C interface to setting the GitLogger flush flag.

void	GitLoggerTune (unsigned NewSettings, unsigned OldSettings, StatusType status)

Detailed Description

Implementation of a Class supporting Logging with a DRAMA GIT Task.

Simplified Usage:: An AAO style GIT task (using GitActivate() should invoke GitLoggerInit() as the first thing in its INITIALISE action and when re-initialising as part of its RESET action. Application code then can then DitsLogMsg() to log messages. DRAMA will also log various details via the logging system. Logging levels can be set using the {system}LOG_LEVEL environment variable or the LOG_LEVEL action, and default to logging of MsgOut messages and error messages/action completion in error. For use in non-GIT tasks, see below.

This class implements the GIT LOG_LEVEL action and routines which allow a DRAMA task to log. It also implements a DITS Logging system (see DitsSetLogSys()) which allows logging of internal DRAMA details.

Note: GitLogger must be on the heap so that it is cleaned up correctly when the task shutdowns. This is enforced by protecting the destructor.; It is assumed the machine time is set correctly. For VxWorks, this is not the case by default. Also, VxWorks does not support locales so the UT date may be used instead of the local date.

Discussions about the constructor  also refer to invoking of
the constructor by the C linkage routine GitLoggerInit().  See below.

The constructor may be invoked from a DRAMA action (normally 
INITIALISE/RESET
in an AAO task obeying the GIT specification (see @htmlonly <a href="../routines/GitActivate.html">GitActivate()</a>@endhtmlonly).  
It may also be invoked in the tasks @verbatim main() @endverbatim
function after @htmlonly <a href="../routines/DitsAppInit.html">DitsAppInit()</a>@endhtmlonly but
before @htmlonly <a href="../routines/DitsMainLoop.html">DitsMainLoop()</a>@endhtmlonly (or an equivalent) is invoked.

If you invoke the constructor from action code, then the LOG_LEVEL
action must already exist as must the LOG_LEVEL parameter.  
The handler for that action will be changed, as will the action code.

If the action is invoked from outside a DRAMA action, then the LOG_LEVEL
action will be created if needed.  The LOG_LEVEL parameter will be
created if it does not exist and the parameter system being used
is Sdp (indicated by using @htmlonly <a href="../routines/DitsAppParamSys.html">DitsAppParamSys()</a>@endhtmlonly to get the current
parameter system details and finding @htmlonly <a href="../routines/SdpGet.html">SdpGet()</a>@endhtmlonly is the getRoutine).  If
the parameter system has not been created, then it is created by
calling @htmlonly <a href="../routines/SdpInit.html">SdpInit()</a>@endhtmlonly.  (Hence always call @htmlonly <a href="../routines/SdpInit.html">SdpInit()</a>@endhtmlonly before invoking
this routine if calling it yourself, otherwise there will be a memory
leak and existing parameters will be lost). 

Use must create objects of this class using "new" or invoke.
GitLoggerInit().  When the new logging system is created, any old
DITS logging system is deleted automaticaly by DITS, which invokes
its logShutdown routine, which is also done when task shutdowns.  
The logShutdown routine of GitLogger will invoke
"delete" on the object.  Hence - you need not worry about deleting 
the object.

The GitLogger class constructor examines the LOG_LEVEL parameter and
the {system_name}_LOG_LEVEL environment variable to determine the
default logging levels.  The parameter LOG_LEVEL must have the
value NONE for the environment variable value to be used.  The parameter
will contain the actual value on return from the constructor.

If {system_name}_LOG_LEVEL does not exist, then DRAMA_LOG_LEVEL will
be used and if that does nto exist then a default level of
INST,ERROR,MSG is used.

The log file is then opened. The name is {taskname}-{date}.<ver>.log[.gz] with
date in the format "DDMMMYYYY".  This file is appended to if it
already exists.  The directory is specified as the third argument
to the constructor, but if this is specified as 0 (the default) or
a zero length string, the value of the DRAMA_LOGDIR environment 
variable is examined.  If this is not defined, then the default 
directory is chosen.  On the first message on a new day, the log file
will be closed and a new log file opened.   <ver> is the log file version
number - this number starts are 00 and increased by 1 each time the
log system is re-initialised or if the log file (when uncompressed) exceedes
1/2 a Giga-Byte in size.  If compress mode is enabled, then the log file
name has ".gz" appended after ".log"

If compress mode is enabled (See the contructor), the log file is compressed as it is 
written using "gzip" run under "nice".  Normally a very high compression ratio is
achivied.  Note that running this way results in considerable buffering, as 
data is buffered by the gzip input and output streams to a very large extent.  It is
suggested that this mode only be used when the amount of data suggest  it is 
appropiate.  When compress mode is enabled, SIGPIPE may be generated by a failure
of the logger output commands (e.g. disk full).  As a result, GitLogger will catch
that signal and ignore it (through a message it output to stderr).  If the user
application is using SIGPIPE is must set up its handler after calling the GitLogger
constructor (but I don't know how it can tell the difference between the GitLogger
pipe failing or its own pipes failing).

The GitLogger tells DITS to use this class as its logging system, by calling
@htmlonly <a href="../routines/DitsSetLogSys.html">DitsSetLogSys()</a>@endhtmlonly - this will also result in the object being deleted
when DitsStop() is invoked or if another logging system is enabled.
As a result of this feature, this object cannot be allocated globally,
statically or on the stack.  It must be created on the heap (using 
@verbatim new() @endverbatim).
To help enforce this, the destructor is made protected.  Inheriting
objects should have the same restriction.

Much logging is done internally by DRAMA.  User code can call
@htmlonly <a href="../routines/DitsLogMsg.html">DitsLogMsg()</a>@endhtmlonly or us the GitLoggers Log() method to log messages from
application code.

The following logging levels are supported.

   \arg STARTUP  Log startup messages.  Equivalent to @htmlonly <a href="../routines/DitsLogMsg.html">DitsLogMsg()</a>@endhtmlonly
                 \c DITS_LOG_STARTUP.

   \arg ERRORS   Log errors - messages output by ERS and details
                 of actions completing with bad status.

   \arg ACTENT   Log action and uface entry.  Used by DRAMA logging

   \arg ACTEXIT  Log action and uface return.  Used by DRAMA logging.

   \arg INST      Log instrument specific functions. Equivalent to 
                   @htmlonly <a href="../routines/DitsLogMsg.html">DitsLogMsg()</a>@endhtmlonly \c DITS_LOG_INST.

   \arg COMMS    Log DRAMA communications (sendings of messages etc).

   \arg ARG      If logging action entry and/or action exit/comms, also 
                 log a string giving the details of any argument.  For 
                 comms logs, this is only arguments to a send (obey etc).

   \arg DEBUG    Log debugging messages

   \arg USER1    User defined level 1.  Equivalent to 
                 @htmlonly <a href="../routines/DitsLogMsg.html">DitsLogMsg()</a>@endhtmlonly \c DITS_LOG_USER1.

   \arg  USER2    User defined level 2.  Equivalent to 
                 @htmlonly <a href="../routines/DitsLogMsg.html">DitsLogMsg()</a>@endhtmlonly \c DITS_LOG_USER2.

   \arg  USER3    User defined level 3.

   \arg  USER4    User defined level 4.

   \arg  ALL      All levels are defined.

GitLogger maintains an internal mask of the above levels.  It or's this
if the level passed to it by the Log() routine and if the result
is non-zero the message is logged.

A second internal mask is kept which identifies logging messages
which are echoed to the screen. MsgOut messages always goto the
screen and you can change this effect for Ers message, which only
goto the screen if flushed.

The argument to the LOG_LEVEL action and the contents of the 
environment variable/LOG_LEVEL parameter on startup should be a 
comma or space separated list of the above names.  If prefixed with
NO, the level is truned off, otherwise the level is turned on.

If the suffix -S is added to the name, we are indicating that screen
logging for this level should be turned on/off.

The LOG_LEVEL action without any arguments just returns (using MsgOut)
the current values.  With or without an argument, the LOG_LEVEL
action causes the log file to be flushed to disk.

If you must use this from a C program, rather then a C++ program,
use the GitLoggerInit() routine to initialise the logger.  Then
always use the @htmlonly <a href="../routines/DitsLogMsg.html">DitsLogMsg()</a>@endhtmlonly routine to log messages.

When possible (On VxWorks and on Unix machines with posix threads available) 
GitLogger uses a low priority background thread to sync the log file to 
disk every five seconds.

The documentation for this class was generated from the following file:

gitlogger.h

Public Member Functions

Static Public Member Functions

Friends

Detailed Description