This class can be used to display messages to the user. More...

#include <ilserver/logfile.h>

Inherits IlsIndenter.

Classes
class	MsgDescription
	Gives access to the characteristics of the messages handled by the class `IlsLogfile`. More...

Public Types
typedef unsigned long	CategoryId
	Defines the category of the message and can be used to identify which subsystem created the message.

typedef IlsBoolean(*	LogfileFilterFunc) (const MsgDescription &, IlsAny)
	This callback can be used to filter out messages that you want displayed to the user. More...

typedef void(*	LogfileMessageFunc) (const MsgDescription &, IlsAny)
	This callback is used by the message-redirecting methods to trap all messages from the class `IlsLogfile`. More...

typedef unsigned long	MessageId
	Defines the error number of the message.

Static Public Member Functions
static void	AddFilter (LogfileFilterFunc, IlsAny=0)
	Adds a callback to the list of callbacks to filter error messages.

static void	AddRedirect (LogfileMessageFunc, IlsAny=0)
	Adds a callback to the list of callbacks to redirect error messages.

static IlsLogLevel	GetLogLevel ()
	Gets the current logging level that is used to control whether or not a message is reported to the user. More...

static IlsString	GetMsgPrefix ()
	Gets the current message prefix, if any. More...

static IlsBoolean	RemoveFilter (LogfileFilterFunc, IlsAny=0)
	Removes a callback from the list of callbacks to filter error messages.

static IlsBoolean	RemoveRedirect (LogfileMessageFunc, IlsAny=0)
	Removes a callback from the list of callbacks to redirect error messages.

static void	SetFilter (LogfileFilterFunc=0, IlsAny=0)
	Sets, or unsets if the callback is zero, the callback to filter error messages.

static IlsBoolean	SetLogfile (const IlsString &fileName=IlsString::Null, IlsBoolean logAndOutput=IlsFalse, IlsBoolean appendToLog=IlsFalse)
	Redirects all messages to a file. More...

static IlsLogLevel	SetLogLevel (IlsLogLevel level)
	Sets the current logging level to the value of the argument level for all new messages. More...

static void	SetMsgPrefix (const IlsString &prefix)
	Sets a prefix to all messages. More...

static void	SetPrintMessagesInFull (IlsBoolean inFull)
	Chooses to print the complete message, including the prefix information. More...

static void	SetRedirect (LogfileMessageFunc=0, IlsAny=0)
	Sets, or unsets if the callback is zero, the callback to redirect error messages.

static void	ThrowExceptionOnExit (IlsBoolean=IlsTrue)
	Makes library throw an exception of class `IlsOnExitException` which derives from `IlsException`), rather than calling `exit()` or `abort()`. More...

Friends
ILSIMPORT IlsLogfile &	dec (IlsLogfile &)
	Sets the printing base for integers to decimal. More...

ILSIMPORT IlsLogfile &	hex (IlsLogfile &)
	Sets the printing base for integers to hexadecimal. More...

ILSIMPORT IlsLogfile &	IlsDebug (IlsLogfile::CategoryId, IlsLogfile::MessageId, const IlsString &, const IlsString &)
	Creates an instance of a debug message. More...

ILSIMPORT void	IlsEOM (IlsLogfile &)
	Appends a new line to the message and sends the message. More...

ILSIMPORT IlsLogfile &	IlsError (IlsLogfile::CategoryId, IlsLogfile::MessageId, const IlsString &, const IlsString &)
	Creates an instance of an error. More...

ILSIMPORT IlsLogfile &	IlsFatalError (IlsLogfile::CategoryId, IlsLogfile::MessageId, const IlsString &, const IlsString &)
	Creates an instance of a fatal error. More...

ILSIMPORT IlsLogfile &	IlsInfo (IlsLogfile::CategoryId, IlsLogfile::MessageId, const IlsString &, const IlsString &)
	Creates an instance of an information message. More...

ILSIMPORT IlsLogfile &	IlsInternalError (IlsLogfile::CategoryId, IlsLogfile::MessageId, const IlsString &, const IlsString &)
	Creates an instance of a internal error. More...

ILSIMPORT IlsLogfile &	IlsMsg (IlsLogfile::CategoryId, IlsLogfile::MessageId, const IlsString &, const IlsString &)
	Creates an instance of a plain message. More...

ILSIMPORT IlsLogfile &	IlsWarn (IlsLogfile::CategoryId, IlsLogfile::MessageId, const IlsString &, const IlsString &)
	Creates an instance of a warning. More...

ILSIMPORT IlsLogfile &	oct (IlsLogfile &)
	Sets the printing base for integers to octal. More...

ILSIMPORT IlsLogfile &	restore (IlsLogfile &)
	Restores the printing base to its old value. More...

Appending to a Message
ILSIMPORT IlsLogfile &	IlsEndl (IlsLogfile &)
	Appends a new line to the message.

IlsLogfile &	operator<< (char)
	Appends its parameter to the message.

IlsLogfile &	operator<< (unsigned char)
	Appends its parameter to the message.

IlsLogfile &	operator<< (int)
	Appends its parameter to the message.

IlsLogfile &	operator<< (unsigned int)
	Appends its parameter to the message.

IlsLogfile &	operator<< (long)
	Appends its parameter to the message.

IlsLogfile &	operator<< (unsigned long)
	Appends its parameter to the message.

IlsLogfile &	operator<< (long long)
	Appends its parameter to the message.

IlsLogfile &	operator<< (unsigned long long)
	Appends its parameter to the message.

IlsLogfile &	operator<< (const char *)
	Appends its parameter to the message.

IlsLogfile &	operator<< (float)
	Appends its parameter to the message.

IlsLogfile &	operator<< (double)
	Appends its parameter to the message.

IlsLogfile &	operator<< (short)
	Appends its parameter to the message.

IlsLogfile &	operator<< (unsigned short)
	Appends its parameter to the message.

Detailed Description

This class can be used to display messages to the user.

Library: server
and mvcomp

It can 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.

See also: IlsException, IlsInit(), IlsLogfile::MsgDescription.

Member Typedef Documentation

§ LogfileFilterFunc

typedef IlsBoolean(* IlsLogfile::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.

§ LogfileMessageFunc

typedef void(* IlsLogfile::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.

Member Function Documentation

§ GetLogLevel()

static IlsLogLevel IlsLogfile::GetLogLevel ( )

static

Gets 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.

Returns: the log level

§ GetMsgPrefix()

static IlsString IlsLogfile::GetMsgPrefix ( )

static

Gets the current message prefix, if any.

Returns: current message prefix

§ SetLogfile()

static IlsBoolean IlsLogfile::SetLogfile	(	const IlsString &	fileName = `IlsString::Null`,
		IlsBoolean	logAndOutput = `IlsFalse`,
		IlsBoolean	appendToLog = `IlsFalse`
	)

static

Redirects 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 ILS_LOGFILE_ONLY causes the output to go only to the logfile specified.
Setting ILS_LOGFILE causes the output to go to the logfile and to the normal output stream.
Setting 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.

Parameters

fileName	log file name
logAndOutput	if equal to `IlsTrue:` log to file and to output `IlsFalse:` log only to file.
appendToLog	`IlsTrue` to append to or `IlsFalse` to erase the log file when it exists

§ SetLogLevel()

static IlsLogLevel IlsLogfile::SetLogLevel ( IlsLogLevel level )

static

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.

Parameters

level new log level

Returns: old log level

§ SetMsgPrefix()

static void IlsLogfile::SetMsgPrefix ( const IlsString & prefix )

static

Sets a prefix to all messages.

Parameters

prefix message prefix

§ SetPrintMessagesInFull()

static void IlsLogfile::SetPrintMessagesInFull ( IlsBoolean inFull )

static

Chooses to print the complete message, including the prefix information.

By default, the inFull parameter is set to IlsFalse.

§ ThrowExceptionOnExit()

static void IlsLogfile::ThrowExceptionOnExit ( IlsBoolean = IlsTrue )

static

Makes 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(IlsTrue) and catch any exceptions in the main thread (or secondary threads if any) as shown in the code samples below.

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 Server exception was raised
}

Friends And Related Function Documentation

§ dec

ILSIMPORT IlsLogfile& dec ( IlsLogfile & )

friend

Sets the printing base for integers to decimal.

An example of its use is shown below:

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

§ hex

ILSIMPORT IlsLogfile& hex ( IlsLogfile & )

friend

Sets the printing base for integers to hexadecimal.

An example of its use is shown below:

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

§ IlsDebug

ILSIMPORT IlsLogfile& IlsDebug	(	IlsLogfile::CategoryId	,
		IlsLogfile::MessageId	,
		const IlsString &	,
		const IlsString &
	)

friend

Creates 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;

§ IlsEOM

ILSIMPORT void IlsEOM ( IlsLogfile & )

friend

Appends a new line to the message and sends the message.

A message that does not end with IlsEOM is never posted.

§ IlsError

ILSIMPORT IlsLogfile& IlsError	(	IlsLogfile::CategoryId	,
		IlsLogfile::MessageId	,
		const IlsString &	,
		const IlsString &
	)

friend

Creates 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;

§ IlsFatalError

ILSIMPORT IlsLogfile& IlsFatalError	(	IlsLogfile::CategoryId	,
		IlsLogfile::MessageId	,
		const IlsString &	,
		const IlsString &
	)

friend

Creates 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;

§ IlsInfo

ILSIMPORT IlsLogfile& IlsInfo	(	IlsLogfile::CategoryId	,
		IlsLogfile::MessageId	,
		const IlsString &	,
		const IlsString &
	)

friend

Creates an instance of an information message.

An example of its use is shown below:

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

§ IlsInternalError

ILSIMPORT IlsLogfile& IlsInternalError	(	IlsLogfile::CategoryId	,
		IlsLogfile::MessageId	,
		const IlsString &	,
		const IlsString &
	)

friend

Creates 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;

§ IlsMsg

ILSIMPORT IlsLogfile& IlsMsg	(	IlsLogfile::CategoryId	,
		IlsLogfile::MessageId	,
		const IlsString &	,
		const IlsString &
	)

friend

Creates an instance of a plain message.

An example of its use is shown below:

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

§ IlsWarn

ILSIMPORT IlsLogfile& IlsWarn	(	IlsLogfile::CategoryId	,
		IlsLogfile::MessageId	,
		const IlsString &	,
		const IlsString &
	)

friend

Creates an instance of a warning.

An example of its use is shown below:

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

§ oct

ILSIMPORT IlsLogfile& oct ( IlsLogfile & )

friend

Sets the printing base for integers to octal.

An example of its use is shown below:

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

§ restore

ILSIMPORT IlsLogfile& restore ( IlsLogfile & )

friend

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;

Classes

Public Types

Static Public Member Functions

Friends

Appending to a Message

Detailed Description

Member Typedef Documentation

§ LogfileFilterFunc

§ LogfileMessageFunc

Member Function Documentation

§ GetLogLevel()

§ GetMsgPrefix()

§ SetLogfile()

§ SetLogLevel()

§ SetMsgPrefix()

§ SetPrintMessagesInFull()

§ ThrowExceptionOnExit()

Friends And Related Function Documentation

§ dec

§ hex

§ IlsDebug

§ IlsEOM

§ IlsError

§ IlsFatalError

§ IlsInfo

§ IlsInternalError

§ IlsMsg

§ IlsWarn

§ oct

§ restore