Base class for message handling. More...

#include <CoinMessageHandler.hpp>

Collaboration diagram for CoinMessageHandler:

Public Member Functions
Virtual methods that the derived classes may provide
virtual int	print ()
	Print message, return 0 normally. More...

virtual void	checkSeverity ()
	Check message severity - if too bad then abort. More...

Constructors etc
	CoinMessageHandler ()
	Constructor. More...

	CoinMessageHandler (FILE *fp)
	Constructor to put to file pointer (won't be closed) More...

virtual	~CoinMessageHandler ()
	Destructor. More...

	CoinMessageHandler (const CoinMessageHandler &)
	The copy constructor. More...

CoinMessageHandler &	operator= (const CoinMessageHandler &)
	Assignment operator. More...

virtual CoinMessageHandler *	clone () const
	Clone. More...

Get and set methods
int	detail (int messageNumber, const CoinMessages &normalMessage) const
	Get detail level of a message. More...

int	logLevel () const
	Get current log (detail) level. More...

void	setLogLevel (int value)
	Set current log (detail) level. More...

int	logLevel (int which) const
	Get alternative log level. More...

void	setLogLevel (int which, int value)
	Set alternative log level value. More...

void	setPrecision (unsigned int new_precision)
	Set the number of significant digits for printing floating point numbers. More...

int	precision ()
	Current number of significant digits for printing floating point numbers. More...

void	setPrefix (bool yesNo)
	Switch message prefix on or off. More...

bool	prefix () const
	Current setting for printing message prefix. More...

double	doubleValue (int position) const
	Values of double fields already processed. More...

int	numberDoubleFields () const
	Number of double fields already processed. More...

CoinBigIndex	intValue (int position) const
	Values of integer fields already processed. More...

int	numberIntFields () const
	Number of integer fields already processed. More...

char	charValue (int position) const
	Values of char fields already processed. More...

int	numberCharFields () const
	Number of char fields already processed. More...

std::string	stringValue (int position) const
	Values of string fields already processed. More...

int	numberStringFields () const
	Number of string fields already processed. More...

CoinOneMessage	currentMessage () const
	Current message. More...

std::string	currentSource () const
	Source of current message. More...

const char *	messageBuffer () const
	Output buffer. More...

int	highestNumber () const
	Highest message number (indicates any errors) More...

FILE *	filePointer () const
	Get current file pointer. More...

void	setFilePointer (FILE *fp)
	Set new file pointer. More...

Actions to create a message
CoinMessageHandler &	message (int messageNumber, const CoinMessages &messages)
	Start a message. More...

CoinMessageHandler &	message (int detail=-1)
	Start or continue a message. More...

CoinMessageHandler &	message (int externalNumber, const char source, const char msg, char severity, int detail=-1)
	Print a complete message. More...

CoinMessageHandler &	operator<< (int intvalue)
	Process an integer parameter value. More...

CoinMessageHandler &	operator<< (double doublevalue)
	Process a double parameter value. More...

CoinMessageHandler &	operator<< (const std::string &stringvalue)
	Process a STL string parameter value. More...

CoinMessageHandler &	operator<< (char charvalue)
	Process a char parameter value. More...

CoinMessageHandler &	operator<< (const char *stringvalue)
	Process a C-style string parameter value. More...

CoinMessageHandler &	operator<< (CoinMessageMarker)
	Process a marker. More...

int	finish ()
	Finish (and print) the message. More...

CoinMessageHandler &	printing (bool onOff)
	Enable or disable printing of an optional portion of a message. More...

Protected Attributes
Protected member data
std::vector< double >	doubleValue_
	values in message More...

std::vector< CoinBigIndex >	longValue_

std::vector< char >	charValue_

std::vector< std::string >	stringValue_

int	logLevel_
	Log level. More...

int	logLevels_ [COIN_NUM_LOG]
	Log levels. More...

int	prefix_
	Whether we want prefix (may get more subtle so is int) More...

CoinOneMessage	currentMessage_
	Current message. More...

int	internalNumber_
	Internal number for use with enums. More...

char *	format_
	Format string for message (remainder) More...

char	messageBuffer_ [COIN_MESSAGE_HANDLER_MAX_BUFFER_SIZE]
	Output buffer. More...

char *	messageOut_
	Position in output buffer. More...

std::string	source_
	Current source of message. More...

int	printStatus_
	0 - Normal. More...

int	highestNumber_
	Highest message number (indicates any errors) More...

FILE *	fp_
	File pointer. More...

char	g_format_ [8]
	Current format for floating point numbers. More...

int	g_precision_
	Current number of significant digits for floating point numbers. More...

Private Member Functions
void	gutsOfCopy (const CoinMessageHandler &rhs)
	The body of the copy constructor and the assignment operator. More...

char *	nextPerCent (char *start, const bool initial=false)
	Internal function to locate next format code. More...

int	internalPrint ()
	Internal printing function. More...

void	calcPrintStatus (int msglvl, int msgclass)
	Decide if this message should print. More...

Friends
bool	CoinMessageHandlerUnitTest ()
	A function that tests the methods in the CoinMessageHandler class. More...

Detailed Description

Base class for message handling.

The default behavior is described here: messages are printed, and (if the severity is sufficiently high) execution will be aborted. Inherit and redefine the methods print and checkSeverity to augment the behaviour.

Messages can be printed with or without a prefix; the prefix will consist of a source string, the external ID number, and a letter code, e.g., Clp6024W. A prefix makes the messages look less nimble but is very useful for "grep" etc.

Usage

The general approach to using the COIN messaging facility is as follows:

Define your messages. For each message, you must supply an external ID number, a log (detail) level, and a format string. Typically, you define a convenience structure for this, something that's easy to use to create an array of initialised message definitions at compile time.
Create a CoinMessages object, sized to accommodate the number of messages you've defined. (Incremental growth will happen if necessary as messages are loaded, but it's inefficient.)
Load the messages into the CoinMessages object. Typically this entails creating a CoinOneMessage object for each message and passing it as a parameter to CoinMessages::addMessage(). You specify the message's internal ID as the other parameter to addMessage.
Create and use a CoinMessageHandler object to print messages.

See, for example, CoinMessage.hpp and CoinMessage.cpp for an example of the first three steps. `Format codes' below has a simple example of printing a message.

External ID numbers and severity

CoinMessageHandler assumes the following relationship between the external ID number of a message and the severity of the message:

<3000 are informational ('I')
<6000 warnings ('W')
<9000 non-fatal errors ('E')
>=9000 aborts the program (after printing the message) ('S')

Log (detail) levels

The default behaviour is that a message will print if its detail level is less than or equal to the handler's log level. If all you want to do is set a single log level for the handler, use setLogLevel(int).

If you want to get fancy, here's how it really works: There's an array, logLevels_, which you can manipulate with setLogLevel(int,int). Each entry logLevels_[i] specifies the log level for messages of class i (see CoinMessages::class_). If logLevels_[0] is set to the magic number -1000 you get the simple behaviour described above, whatever the class of the messages. If logLevels_[0] is set to a valid log level (>= 0), then logLevels_[i] really is the log level for messages of class i.

Format codes

CoinMessageHandler can print integers (normal, long, and long long), doubles, characters, and strings. See the descriptions of the various << operators.

When processing a standard message with a format string, the formatting codes specified in the format string will be passed to the sprintf function, along with the argument. When generating a message with no format string, each << operator uses a simple format code appropriate for its argument. Consult the documentation for the standard printf facility for further information on format codes.

The special format code `%?' provides a hook to enable or disable printing. For each `%?' code, there must be a corresponding call to printing(bool). This provides a way to define optional parts in messages, delineated by the code `%?' in the format string. Printing can be suppressed for these optional parts, but any operands must still be supplied. For example, given the message string

"A message with%? an optional integer %d and%? a double %g."

installed in CoinMessages exampleMsgs with index 5, and CoinMessageHandler hdl, the code

hdl.message(5,exampleMsgs) ;
hdl.printing(true) << 42 ;
hdl.printing(true) << 53.5 << CoinMessageEol ;

will print

A message with an optional integer 42 and a double 53.5.

while

hdl.message(5,exampleMsgs) ;
hdl.printing(false) << 42 ;
hdl.printing(true) << 53.5 << CoinMessageEol ;

will print

A message with a double 53.5.

For additional examples of usage, see CoinMessageHandlerUnitTest in CoinMessageHandlerTest.cpp.

Definition at line 345 of file CoinMessageHandler.hpp.

Constructor & Destructor Documentation

CoinMessageHandler::CoinMessageHandler ( )

Constructor.

CoinMessageHandler::CoinMessageHandler ( FILE * fp )

Constructor to put to file pointer (won't be closed)

virtual CoinMessageHandler::~CoinMessageHandler ( )

virtual

Destructor.

CoinMessageHandler::CoinMessageHandler ( const CoinMessageHandler & )

The copy constructor.

Member Function Documentation

virtual int CoinMessageHandler::print ( )

virtual

Print message, return 0 normally.

virtual void CoinMessageHandler::checkSeverity ( )

virtual

Check message severity - if too bad then abort.

CoinMessageHandler& CoinMessageHandler::operator= ( const CoinMessageHandler & )

Assignment operator.

virtual CoinMessageHandler* CoinMessageHandler::clone ( ) const

virtual

Clone.

int CoinMessageHandler::detail	(	int	messageNumber,
		const CoinMessages &	normalMessage
	)		const

inline

Get detail level of a message.

Definition at line 378 of file CoinMessageHandler.hpp.

int CoinMessageHandler::logLevel ( ) const

inline

Get current log (detail) level.

Definition at line 383 of file CoinMessageHandler.hpp.

void CoinMessageHandler::setLogLevel ( int value )

Set current log (detail) level.

If the log level is equal or greater than the detail level of a message, the message will be printed. A rough convention for the amount of output expected is

0 - none
1 - minimal
2 - normal low
3 - normal high
4 - verbose

Please assign log levels to messages accordingly. Log levels of 8 and above (8,16,32, etc.) are intended for selective debugging. The logical AND of the log level specified in the message and the current log level is used to determine if the message is printed. (In other words, you're using individual bits to determine which messages are printed.)

int CoinMessageHandler::logLevel ( int which ) const

inline

Get alternative log level.

Definition at line 406 of file CoinMessageHandler.hpp.

void CoinMessageHandler::setLogLevel	(	int	which,
		int	value
	)

Set alternative log level value.

Can be used to store alternative log level information within the handler.

void CoinMessageHandler::setPrecision ( unsigned int new_precision )

Set the number of significant digits for printing floating point numbers.

int CoinMessageHandler::precision ( )

inline

Current number of significant digits for printing floating point numbers.

Definition at line 419 of file CoinMessageHandler.hpp.

void CoinMessageHandler::setPrefix ( bool yesNo )

Switch message prefix on or off.

bool CoinMessageHandler::prefix ( ) const

Current setting for printing message prefix.

double CoinMessageHandler::doubleValue ( int position ) const

inline

Values of double fields already processed.

As the parameter for a double field is processed, the value is saved and can be retrieved using this function.

Definition at line 430 of file CoinMessageHandler.hpp.

int CoinMessageHandler::numberDoubleFields ( ) const

inline

Number of double fields already processed.

Incremented each time a field of type double is processed.

Definition at line 438 of file CoinMessageHandler.hpp.

CoinBigIndex CoinMessageHandler::intValue ( int position ) const

inline

Values of integer fields already processed.

As the parameter for a integer field is processed, the value is saved and can be retrieved using this function.

Definition at line 447 of file CoinMessageHandler.hpp.

int CoinMessageHandler::numberIntFields ( ) const

inline

Number of integer fields already processed.

Incremented each time a field of type integer is processed.

Definition at line 455 of file CoinMessageHandler.hpp.

char CoinMessageHandler::charValue ( int position ) const

inline

Values of char fields already processed.

As the parameter for a char field is processed, the value is saved and can be retrieved using this function.

Definition at line 464 of file CoinMessageHandler.hpp.

int CoinMessageHandler::numberCharFields ( ) const

inline

Number of char fields already processed.

Incremented each time a field of type char is processed.

Definition at line 472 of file CoinMessageHandler.hpp.

std::string CoinMessageHandler::stringValue ( int position ) const

inline

Values of string fields already processed.

As the parameter for a string field is processed, the value is saved and can be retrieved using this function.

Definition at line 481 of file CoinMessageHandler.hpp.

int CoinMessageHandler::numberStringFields ( ) const

inline

Number of string fields already processed.

Incremented each time a field of type string is processed.

Definition at line 489 of file CoinMessageHandler.hpp.

CoinOneMessage CoinMessageHandler::currentMessage ( ) const

inline

Current message.

Definition at line 495 of file CoinMessageHandler.hpp.

std::string CoinMessageHandler::currentSource ( ) const

inline

Source of current message.

Definition at line 500 of file CoinMessageHandler.hpp.

const char* CoinMessageHandler::messageBuffer ( ) const

inline

Output buffer.

Definition at line 505 of file CoinMessageHandler.hpp.

int CoinMessageHandler::highestNumber ( ) const

inline

Highest message number (indicates any errors)

Definition at line 510 of file CoinMessageHandler.hpp.

FILE* CoinMessageHandler::filePointer ( ) const

inline

Get current file pointer.

Definition at line 515 of file CoinMessageHandler.hpp.

void CoinMessageHandler::setFilePointer ( FILE * fp )

inline

Set new file pointer.

Definition at line 520 of file CoinMessageHandler.hpp.

CoinMessageHandler& CoinMessageHandler::message	(	int	messageNumber,
		const CoinMessages &	messages
	)

Start a message.

Look up the specified message. A prefix will be generated if enabled. The message will be printed if the current log level is equal or greater than the log level of the message.

CoinMessageHandler& CoinMessageHandler::message ( int detail = -1 )

Start or continue a message.

With detail = -1 (default), does nothing except return a reference to the handler. (I.e., msghandler.message() << "foo" is precisely equivalent to msghandler << "foo".) If msgDetail is >= 0, is will be used as the detail level to determine whether the message should print (assuming class 0).

This can be used with any of the << operators. One use is to start a message which will be constructed entirely from scratch. Another use is continuation of a message after code that interrupts the usual sequence of << operators.

CoinMessageHandler& CoinMessageHandler::message	(	int	externalNumber,
		const char *	source,
		const char *	msg,
		char	severity,
		int	detail = `-1`
	)

Print a complete message.

Generate a standard prefix and append msg `as is'. This is intended as a transition mechanism. The standard prefix is generated (if enabled), and msg is appended. The message must be ended with a CoinMessageEol marker. Attempts to add content with << will have no effect.

The default value of detail will not change printing status. If detail is >= 0, it will be used as the detail level to determine whether the message should print (assuming class 0).

CoinMessageHandler& CoinMessageHandler::operator<< ( int intvalue )

Process an integer parameter value.

The default format code is `d'.

CoinMessageHandler& CoinMessageHandler::operator<< ( double doublevalue )

Process a double parameter value.

The default format code is `d'.

CoinMessageHandler& CoinMessageHandler::operator<< ( const std::string & stringvalue )

Process a STL string parameter value.

The default format code is `g'.

CoinMessageHandler& CoinMessageHandler::operator<< ( char charvalue )

Process a char parameter value.

The default format code is `s'.

CoinMessageHandler& CoinMessageHandler::operator<< ( const char * stringvalue )

Process a C-style string parameter value.

The default format code is `c'.

CoinMessageHandler& CoinMessageHandler::operator<< ( CoinMessageMarker )

Process a marker.

The default format code is `s'.

int CoinMessageHandler::finish ( )

Finish (and print) the message.

Equivalent to using the CoinMessageEol marker.

CoinMessageHandler& CoinMessageHandler::printing ( bool onOff )

Enable or disable printing of an optional portion of a message.

Optional portions of a message are delimited by `%?' markers, and printing processes one %? marker. If onOff is true, the subsequent portion of the message (to the next %? marker or the end of the format string) will be printed. If onOff is false, printing is suppressed. Parameters must still be supplied, whether printing is suppressed or not. See the class documentation for an example.

void CoinMessageHandler::gutsOfCopy ( const CoinMessageHandler & rhs )

private

The body of the copy constructor and the assignment operator.

char* CoinMessageHandler::nextPerCent	(	char *	start,
		const bool	initial = `false`
	)

private

Internal function to locate next format code.

Intended for internal use. Side effects modify the format string.

int CoinMessageHandler::internalPrint ( )

private

Internal printing function.

Makes it easier to split up print into clean, print and check severity

void CoinMessageHandler::calcPrintStatus	(	int	msglvl,
		int	msgclass
	)

private

Decide if this message should print.

Friends And Related Function Documentation

bool CoinMessageHandlerUnitTest ( )

friend

A function that tests the methods in the CoinMessageHandler class.

The only reason for it not to be a member method is that this way it doesn't have to be compiled into the library. And that's a gain, because the library should be compiled with optimization on, but this method should be compiled with debugging.

Member Data Documentation

std::vector< double > CoinMessageHandler::doubleValue_

protected

values in message

Definition at line 645 of file CoinMessageHandler.hpp.

std::vector< CoinBigIndex > CoinMessageHandler::longValue_

protected

Definition at line 646 of file CoinMessageHandler.hpp.

std::vector< char > CoinMessageHandler::charValue_

protected

Definition at line 647 of file CoinMessageHandler.hpp.

std::vector< std::string > CoinMessageHandler::stringValue_

protected

Definition at line 648 of file CoinMessageHandler.hpp.

int CoinMessageHandler::logLevel_

protected

Log level.

Definition at line 650 of file CoinMessageHandler.hpp.

int CoinMessageHandler::logLevels_[COIN_NUM_LOG]

protected

Log levels.

Definition at line 652 of file CoinMessageHandler.hpp.

int CoinMessageHandler::prefix_

protected

Whether we want prefix (may get more subtle so is int)

Definition at line 654 of file CoinMessageHandler.hpp.

CoinOneMessage CoinMessageHandler::currentMessage_

protected

Current message.

Definition at line 656 of file CoinMessageHandler.hpp.

int CoinMessageHandler::internalNumber_

protected

Internal number for use with enums.

Definition at line 658 of file CoinMessageHandler.hpp.

char* CoinMessageHandler::format_

protected

Format string for message (remainder)

Definition at line 660 of file CoinMessageHandler.hpp.

char CoinMessageHandler::messageBuffer_[COIN_MESSAGE_HANDLER_MAX_BUFFER_SIZE]

protected

Output buffer.

Definition at line 662 of file CoinMessageHandler.hpp.

char* CoinMessageHandler::messageOut_

protected

Position in output buffer.

Definition at line 664 of file CoinMessageHandler.hpp.

std::string CoinMessageHandler::source_

protected

Current source of message.

Definition at line 666 of file CoinMessageHandler.hpp.

int CoinMessageHandler::printStatus_

protected

0 - Normal.

1 - Put in values, move along format, but don't print. 2 - A complete message was provided; nothing more to do but print when CoinMessageEol is processed. Any << operators are treated as noops. 3 - do nothing except look for CoinMessageEol (i.e., the message detail level was not sufficient to cause it to print).

Definition at line 675 of file CoinMessageHandler.hpp.

int CoinMessageHandler::highestNumber_

protected

Highest message number (indicates any errors)

Definition at line 677 of file CoinMessageHandler.hpp.

FILE* CoinMessageHandler::fp_

protected

File pointer.

Definition at line 679 of file CoinMessageHandler.hpp.

char CoinMessageHandler::g_format_[8]

protected

Current format for floating point numbers.

Definition at line 681 of file CoinMessageHandler.hpp.

int CoinMessageHandler::g_precision_

protected

Current number of significant digits for floating point numbers.

Definition at line 683 of file CoinMessageHandler.hpp.

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

/tmp/DyLP-1.10.4/CoinUtils/src/CoinMessageHandler.hpp

Public Member Functions

Protected Attributes

Private Member Functions

Friends

Detailed Description

Usage

External ID numbers and severity

Log (detail) levels

Format codes

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation

Member Data Documentation