IlsLogfile

Category

Utility class

Inheritance Path

IlsLogfile

Description

This class can be used to display messages to the user and should be used in a multithread environment as it is multithread-safe. Also, this class buffers messages, so that messages posted from different threads do not get mixed together in the output. A message is not sent until the IlsEOM function is encountered. A message that does not end with IlsEOM is never posted.

Libraries

Header File

#include <ilserver/logfile.h>

Synopsis

class IlsLogfile

{

public:

Type Definitions

typedef unsigned long CategoryId;

typedef unsigned long MessageId;

typedef IlsBoolean (*LogfileFilterFunc)(const MsgDescription&,

IlsAny);

typedef void (*LogfileMessageFunc)(const MsgDescription&,

IlsAny);

Creating a Message

friend IlsLogfile& IlsFatalError();

friend IlsLogfile& IlsInternalError();

friend IlsLogfile& IlsError();

friend IlsLogfile& IlsWarn();

friend IlsLogfile& IlsInfo();

friend IlsLogfile& IlsDebug();

friend IlsLogfile& IlsMsg();

Appending to a Message

IlsLogfile& operator<<(char value);

IlsLogfile& operator<<(unsigned char value);

IlsLogfile& operator<<(int value);

IlsLogfile& operator<<(unsigned int value);

IlsLogfile& operator<<(long value);

IlsLogfile& operator<<(unsigned long value);

IlsLogfile& operator<<(const char* value);

IlsLogfile& operator<<(float value);

IlsLogfile& operator<<(double value);

IlsLogfile& operator<<(short value);

IlsLogfile& operator<<(unsigned short value);

Appending a New Line to a Message

friend IlsLogfile& IlsEndl(IlsLogfile&);

Ending a Message

friend void IlsEOM(IlsLogfile&);

Changing the Printing Base for Integers

friend IlsLogfile& oct(IlsLogfile&);

friend IlsLogfile& hex(IlsLogfile&);

friend IlsLogfile& dec(IlsLogfile&);

friend IlsLogfile& restore(IlsLogfile&);

Setting All Output to a File

static IlsBoolean SetLogfile

(const IlsString& = IlsString::Null,

IlsBoolean logAndOutput = IlsFalse,

IlsBoolean appendToLog = IlsFalse);

Getting/Setting the Log Level

static IlsLogLevel GetLogLevel();

static IlsLogLevel SetLogLevel(IlsLogLevel);

Getting/Setting the Message Prefix

static void SetMsgPrefix(const char* p);

static const char* GetMsgPrefix();

static void SetPrintMessagesInFull (IlsBoolean inFull);

Redirecting Error Messages to the Application

static void SetRedirect(LogfileMessageFunc = 0, IlsAny = 0);

static void AddRedirect(LogfileMessageFunc, IlsAny = 0);

static IlsBoolean RemoveRedirect(LogfileMessageFunc,

IlsAny = 0);

typedef void (*IlsLogfileMsgFunc)(const char*, IlsLogLevel);

static void Redirect(IlsLogfileMsgFunc);

Throwing an Exception on Exit

static void ThrowExceptionOnExit(IlsBoolean);

Filtering Messages

static void SetFilter(LogfileFilterFunc = 0, IlsAny = 0);

static void AddFilter(LogfileFilterFunc, IlsAny = 0);

static IlsBoolean RemoveFilter(LogfileFilterFunc, IlsAny = 0);

Member Functions

Type Definitions

typedef unsigned long CategoryId;

This type defines the category of the message and can be used to identify which subsystem created the message.

typedef unsigned long MessageId;

This type defines the error number of the message.

typedef IlsBoolean (*LogfileFilterFunc)(const MsgDescription&, IlsAny);

This callback can be used to filter out messages that you want displayed to the user. If any filter returns IlsFalse for a message, this message is not displayed or logged. See the member functions under Filtering Messages.

typedef void (*LogfileMessageFunc)(const MsgDescription&,IlsAny);

This callback is used by the message-redirecting methods to trap all messages from the class IlsLogfile. See the member functions under Redirecting Error Messages to the Application.

Creating a Message

friend IlsLogfile& IlsFatalError();

This friend function can be used to create an instance of a fatal error. A fatal error will call exit after the message has been displayed. An example of its use is shown below:

IlsFatalError() << "cannot connect to display" << IlsEOM;

friend IlsLogfile& IlsInternalError();

This friend function can be used to create an instance of a internal error. An internal error will call abort after the message has been displayed. An example of its use is shown below:

IlsInternalError() << "process singleton not set" << IlsEOM;

friend IlsLogfile& IlsError();

This friend function can be used to create an instance of an error. An error will not exit after the message has been displayed. An example of its use is shown below:

IlsError() << "file net.ils does not exist" << IlsEOM;

friend IlsLogfile& IlsWarn();

This friend function can be used to create an instance of a warning. An example of its use is shown below:

IlsWarn() << "not able to read startup file" << IlsEOM;

friend IlsLogfile& IlsInfo();

This friend function can be used to create an instance of an information message.
An example of its use is shown below:

IlsInfo() << "file saved correctly" << IlsEOM;

friend IlsLogfile& IlsDebug();

This friend function can be used to create an instance of a debug message. Debug messages are not normally posted to the user. However, if you want to have them posted, set the log level (via a call to the static member function SetLogLevel) to ILS_LOG_DEBUG. An example of its use is shown below:

IlsDebug() << "internal checking passed ok" << IlsEOM;

friend IlsLogfile& IlsMsg();

This friend function can be used to create an instance of a plain message. An example of its use is shown below:

IlsMsg() << "server initialized..." << IlsEOM;

Appending to a Message

IlsLogfile& operator<<(char value);

IlsLogfile& operator<<(unsigned char value);

IlsLogfile& operator<<(int value);

IlsLogfile& operator<<(unsigned int value);

IlsLogfile& operator<<(long value);

IlsLogfile& operator<<(unsigned long value);

IlsLogfile& operator<<(const char* value);

IlsLogfile& operator<<(float value);

IlsLogfile& operator<<(double value);

IlsLogfile& operator<<(short value);

IlsLogfile& operator<<(unsigned short value);

Each of these operators appends value to the message.

Appending a New Line to a Message

friend IlsLogfile& IlsEndl(IlsLogfile&);

This member function appends a new line to the message.

Ending a Message

friend void IlsEOM(IlsLogfile&);

This member function appends a new line to the message and sends the message.
A message that does not end with IlsEOM is never posted.

Changing the Printing Base for Integers

friend IlsLogfile& oct(IlsLogfile&);

This friend function sets the printing base for integers to octal. An example of its use is shown below:

IlsError() << "invalid flag " << oct << flags << IlsEOM;

friend IlsLogfile& hex(IlsLogfile&);

This friend function sets the printing base for integers to hexadecimal. An example of its use is shown below:

IlsError() << "invalid flag " << hex << flags << IlsEOM;

friend IlsLogfile& dec(IlsLogfile&);

This friend function sets the printing base for integers to decimal. An example of its use is shown below:

IlsError() << "invalid count " << dec << flags << IlsEOM;

friend IlsLogfile& restore(IlsLogfile&);

This friend function restores the printing base to its old value. Only the last value is saved so calling the restore function twice will not work. An example of its use is shown below:

IlsError() << "invalid flag " << oct << flags << restore

<< " for count " << count << IlsEOM;

Setting All Output to a File

[static] IlsBoolean SetLogfile(const IlsString& = IlsString::Null,

IlsBoolean logAndOutput = IlsFalse,

IlsBoolean appendToLog = IlsFalse);

This static member function can be used to redirect all messages to a file. Depending on how the logAndOutput and appendToLog Boolean parameters are set, the messages can be redirected:

either uniquely to a file,

or to a file and to the normal output stream.

In addition, the output can be appended to the logfile if desired.

If the output is redirected to a file and the file already exists, the existing file is removed provided that the argument appendToLog is set to IlsFalse.

This function can also be set via the environment variables ILS_LOGFILE, ILS_LOGFILE_ONLY and ILS_LOGFILE_APPEND.

Setting the environment variable ILS_LOGFILE_ONLY causes the output to go only to the logfile specified.

Setting the environment variable ILS_LOGFILE causes the output to go to the logfile and to the normal output stream.

Setting the environment variable ILS_LOGFILE_APPEND causes the output to be appended to the logfile.

This function will expand the string found so as to substitute the current process identifier if requested. If the string contains the sequence %PID%,it will be replaced with the current process identifier. This mechanism allows several clients to write to different logfiles via the environment variable.

Getting/Setting the Log Level

[static] IlsLogLevel GetLogLevel();

This static member function can be used to get the current logging level that is used to control whether or not a message is reported to the user. The default logging level is ILS_LOG_WARNING, which means that all messages, except debug messages, are reported.

[static] IlsLogLevel SetLogLevel(IlsLogLevel level);

This static member function sets the current logging level to the value of the argument level for all new messages. This function returns the old logging level. It can be used to filter what level of messages are reported to the user. Refer to the type IlsLogLevel to know the relative order of messages.

Getting/Setting the Message Prefix

[static] void SetMsgPrefix(const char* p);

This static member function can be used to set a prefix to all messages.

[static] const char* GetMsgPrefix();

This static member function can be used to get the current message prefix, if any.

[static] void SetPrintMessagesInFull(IlsBoolean inFull);

Use this static member function when you want to print the complete message, including the prefix information. By default, the inFull parameter is set to IlsFalse.

Redirecting Error Messages to the Application

[static] void SetRedirect(LogfileMessageFunc func = 0, IlsAny any = 0);

This static member function sets, or unsets if the callback is zero, the callback to redirect error messages.

[static] void AddRedirect(LogfileMessageFunc func, IlsAny any = 0);

This static member function adds a callback to the list of callbacks to redirect error messages.

[static] IlsBoolean RemoveRedirect(LogfileMessageFunc func, IlsAny any = 0);

This static member function removes a callback from the list of callbacks to redirect error messages.

typedef void (*IlsLogfileMsgFunc)(const char*, IlsLogLevel);

This typedef defines the signature of the callback function used in the static function Redirect.

[static] void Redirect(IlsLogfileMsgFunc);

This static member function assigns a callback function that will be called with every complete error message or trace message to be displayed. See also the enumerated type IlsLogLevel. The second parameter to the callback is for information only. It indicates the error level of the message.

Throwing an Exception on Exit

[static] void ThrowExceptionOnExit(IlsBoolean);

This static member function can be used to have the library throw an exception of class IlsOnExitException (which derives from IlsException), rather than calling exit or abort. This function is useful when it is important to avoid a blunt application exit. In this case, call the function ThrowExceptionOnExit set to IlsTrue and catch any exceptions in the main thread (or secondary threads if any) as shown in the code samples below.

Examples:

IlsLogfile::ThrowExceptionOnExit(IlsTrue);

...

try {

run();

}

catch (IlsOnExitException e) {

// a fatal or internal error message occurred

}

catch (IlsException e) {

// some other exception was raised by the library

}

catch (...) {

// some other non Rogue Wave Views exception was raised

}

Filtering Messages

[static] void SetFilter(LogfileFilterFunc = 0, IlsAny = 0);

This static member function sets, or unsets if the callback is zero, the callback to filter error messages.

[static] void AddFilter(LogfileFilterFunc, IlsAny = 0);

This static member function adds a callback to the list of callbacks to filter error messages.

[static] IlsBoolean RemoveFilter(LogfileFilterFunc, IlsAny = 0);

This static member function removes a callback from the list of callbacks to filter error messages.