NAME

OTC_Logger - Base class for additional message loggers.

SYNOPSIS


#include <OTC/debug/logger.hh>

class OTC_Logger
{
  public:
    virtual ~OTC_Logger();
    static void notify(OTC_LogLevel theLevel, char const* theMessage);
    inline static OTC_Boolean stderrOutputEnabled();
    inline static void enableStderrOutput();
    inline static void disableStderrOutput();
    inline static char const* logFile();
    inline static void setLogFile(char const* theFile);
  protected:
    OTC_Logger();
    virtual void log(
      OTC_LogLevel theLevel,
      char const* theMessage
    ) = 0;
};

CLASS TYPE

Abstract

DESCRIPTION

OTC_Logger is the base class for additional message loggers. The class is also the entry point for displaying a message using the logger. If you wish to log messages to destinations, in addition to those which may already be active, you should create a derived version of OTC_Logger which defines log() to send the message to the appropriate destination. When you create an instance of the derived class, it will automatically be linked in to the list of active loggers; when the instance is destroyed, it will automatically unlink itself from the list of active loggers. When the OTC_Logger class is compiled, if the symbol NDEBUG is not defined, in addition to broadcasting messages to user provided loggers, the logger will display messages on standard error using file descriptor 2. To turn off output to standard error, you can define the environment variable OTCLIB_NOLOGSTDERR. If the OSE C++ libraries have been installed in the standard manner, the symbol NDEBUG is not defined when the dbg, prf and std variants of the libraries are compiled. Therefore, if you link your programs with these variants of the library, messages by default will be displayed on standard error. If the OTC_Logger class is compiled with NDEBUG defined, the logger will NOT log messages to standard error. To turn on output to standard error, you can define the environment variable OTCLIB_LOGSTDERR. If the OSE C++ libraries are installed in the standard manner, the symbol NDEBUG is defined when the opt variant of the library is compiled. Regardless of whether NDEBUG was defined when the OTC_Logger class was compiled, you can enable saving of messages to a file, by defining the environment variable OTCLIB_LOGFILE to be the name of a file in which to save them. By default, this file will be truncated the first time it is opened. If you prefer messages to be appended to the file, you should define the environment variable OTCLIB_APPENDLOGFILE. If you need to change the number of the file descriptor used, to display messages to standard error, you can define the environment variable OTCLIB_LOGFD. This can be used to send messages through a secondary process which either filters or highlights messages as a debugging aid. There is no abilility to change the log file descriptor from within an application. An example of the messages displayed by the standard logger are: The text after the colon is the message. The text before the colon corresponds to the priority level at which the message was logged. Display of a long format message containing a time stamp and the process ID of the program can be enabled by setting the environment variable OTCLIB_LOGLONGFORMAT. If multiple programs are saving messages to the same log file you should enable this option.

DESTRUCTION

virtual ~OTC_Logger();

BROADCAST

static void notify(OTC_LogLevel theLevel, char const* theMessage);

STDERR OUTPUT

Note that enabling and disabling of log output has no effect when an alternate file descriptor is provided for log messages.
inline static OTC_Boolean stderrOutputEnabled();
inline static void enableStderrOutput();
inline static void disableStderrOutput();

LOG FILE

Note that log file names should always be absolute pathnames. This is because the file is opened each time a message needs to be written. If the file name was not absolute and the working directory of the program was changed, the file would be written to the new working directory. Two special tags may be embedded into the name of a file. These are %p and %h. The tag %p will be replaced with the process ID, and %h with the hostname of the machine. To embed a % character in the filename, you should use %%.
inline static char const* logFile();
inline static void setLogFile(char const* theFile);

CONSTRUCTION

OTC_Logger();

LOGGING

virtual void log(OTC_LogLevel theLevel, char const* theMessage) = 0;

NOTES

Any logger you write should avoid doing anything that would require memory to be allocated. This is necessary, as it could be that the message is to notify you that memory has been exhausted. Also, your logger should avoid using form() as the message could have been constructed originally using the function. Using form() again, without first copying the message, would result in the original message being lost.

LIBRARY

OTC

AUTHOR(S)

Graham Dumpleton

COPYRIGHT

Copyright 1992 OTC LIMITED
Copyright 1994 DUMPLETON SOFTWARE CONSULTING PTY LIMITED