OPUS API Class: Msg

Msg - The API message reporting class

Availability:

This class is available for the OPUS Blackboard API. The initial OPUS 2.0 release is described here

Constructors:

Msg( )
~Msg( )

Methods:

new_logfile( ) create new log file
append_logfile( ) append to an existing log file
close_logfile( ) close log file
set_trl_rpt_level( ) set the trailer report level
set_rpt_level( ) set the default message report level
get_rpt_level( ) get the default message report level
get_trl_rpt_level( ) get the default message report level
set_default_out( ) set the default message output device
set_time_format( ) set the time stamp format
operator<<( ) output operators
err( ) Msg stream manipulators: to stderr
log( ) Msg stream manipulators: to trailer file
day( ) Msg stream manipulators: to day file
dft( ) Msg stream manipulators: to default
endm( ) Msg stream manipulators: end of message
sev( ) set the severity
type( ) set the message type set the message type
sev_func( ) set the severity
ttype_func( ) set the message type
stype_func( ) set the message type

Data Members:


 static const std::string EOM;	   // end of message mark
 // control constants

 enum SEVERITY {D = 01, I = 010, W = 0100, E = 01000, F = 010000};

 enum RPT_LEVEL {NONE = 0, DIAG = 011111, INFO = 011110, 
      WARN = 011100, ERROR = 011000, FATAL = 010000, ALL = 011111};

 enum TARGET {ERR = 01, LOG = 010, DAY = 0100};

 enum TYPE {MESG = 0, BADVAL, BADTYPE, MISSING, CORRUPT, FIO, LOCK,
            DUPL, EXEC, AMBIG, SEVERE, MISUSE, FACTERR, USE_STRING};

Description

The Msg class provides support for message reporting in OPUS applications. Messages consist of a time stamp, severity code, category and descriptive text. The time stamp format is programmer configurable, and arbitrary strings can be used for the message category in addition to the labels provided by the API. Messages automatically go to standard error, and can be routed to a log file.

The Msg class is modelled after the standard cerr class which is derived from the ostream class. Thus OPUS messages are formatted in the same fashion as the standard C++ output strings using the concatenation operator. In addition to overloading the concatenation operator for the Msg class, there are a number of manipulators provided to modify the behavior of the message stream.

Each message is formatted with a timestamp, followed by a severity level, followed by the message type, followed finally by the message itself. In addition to being able to modify the default message type by using the set_msgtype( ) method, a more convenient manipulator (type) is provided. The message type can either be one of the built-in Msg::TYPE constants, or you may provide your own string to make these message easier to find in the log files. Similarly the severity of individual messages can be modified either using the sev( ) manipulator, or by setting a default severity for subsequent messages with set_severity().

The severity of the messages reported to any of the log files can be selected, allowing the user to specify that only messages of a certain type should be reported. Ordinarily the number of 'Debug' message can be quite large, and during normal operations 'Informational' messages (and those more severe) will be sufficient.

In case users don't like the default time string of "%Y%j%H%M%S" they can select thier own strftime format.

Example

  
  #include <iostream>
  #include <string>
  
  using namespace std;
  
  #include "msg.h"
  
  int main(int argc, char* argv[]) {
  
    Msg msgout;
  
    msgout.new_logfile("temp.txt");
    msgout.set_default_out (Msg::ERR | Msg::LOG);
    msgout.set_rpt_level(Msg::ALL);
    msgout.set_time_format("%m-%d-%Y");
    msgout << sev(Msg::D) << type("TEST") << "I am a message" << endm;
    msgout << "another message using defaults" << endm;
    msgout << sev(Msg::F) << type(Msg::BADARG) << "Using built-in type BADARG"
           << endm;
  
    msgout.set_rpt_level(Msg::DIAG);
    msgout << sev(Msg::E) << "Better not see this one" << endm;
    msgout << sev(Msg::D) << "will see ";
    msgout << "this one" << endm;
  
    return(0);
  }

Msg::Msg - The Message object constructor.

Synopsis


Msg::Msg()

Description

Exceptions Thrown

none

Example

  
	Msg msgout;
	msgout << "This is a message" << endm;

Msg::~Msg - The Node object destructor.

Synopsis


Msg::~Msg()

Description

Destroys the object.

Exceptions Thrown

none

Msg::new_logfile - Open a new log file.

Synopsis


void Msg::new_logfile(
                      const string& fname) // I - log file name

void Msg::new_logfile(
                      const Ofile& of) // I - log file name

Description

Create a new logfile and set default output to include LOG. If a log file is already open, it will be closed first.

Exceptions Thrown

Io_error - if failed to open log file
Bad_val - if stretch cannot be resolved

Example

  
	Msg msgout;
	msgout.new_logfile("/my/absolute/path/logfile.name");
  
	// or we could use a stretchable path name
  
	Ofile fname("OPUS_DEFINITIONS_DIR:exceptions.log");
	msgout.new_logfile(fname);

Msg::append_logfile - Open the log file for append.

Synopsis


void Msg::append_logfile(
                         const string& fname) // I - log file to append

void Msg::append_logfile(
                         const Ofile& of) // I - log file to append

Description

Open existing log file for append. If a log file is already open for writing, it will be closed prior to attempting the append. If no such file exists, then a new one will be opened.

Exceptions Thrown

Io_error - if open fails
Bad_val - if stretch fails to resolve

Example

  
	Msg msgout;
	msgout.append_logfile("/my/absolute/path/logfile.name");
  
	// or we could use a stretchable path name
  
	Ofile fname("OPUS_DEFINITIONS_DIR:exceptions.log");
	msgout.append_logfile(fname);

Msg::close_logfile - Close the logfile

Synopsis


void Msg::close_logfile()

Description

Closes the log file and removes it from the current and default output destinations.

Exceptions Thrown

Not_ready - if no log file is open

Msg::set_rpt_level - Sets the current report level.

Synopsis


int Msg::set_rpt_level(
                       const int newrl) // I - new report level

int Msg::set_trl_rpt_level(
                       const int newrl) // I - new report level

Description

Sets the current report level. The report level is defined in the Msg.h file and can take one of the following values: ALL, DIAG, INFO, WARN, ERROR, FATAL, NONE. The report levels are cumulative which implies, for example, that the WARN level will receive WARN, ERROR and FATAL messages.

Returns

The old report level.

Exceptions Thrown

none

Msg::get_rpt_level - Returns the current report level.

Synopsis


int Msg::get_rpt_level() const

int Msg::get_trl_rpt_level() const

Description

Returns the current report level. This level should be one of ALL, DIAG, INFO, WARN, ERROR, FATAL, NONE, as defined for the Msg class.

Returns

The current report level.

Exceptions Thrown

none

Example

  
	#include "msg.h"
  
	Msg msg;
	int report_level;
	report_level = msg.get_report_level();
	int report_trl_level;
	report_trl_level = msg.get_trl_report_level();

Msg::set_default_out - Sets the default output destination(s).

Synopsis


int Msg::set_default_out(
                         const int flag) // I - new output destination

Description

Sets the default output destination. The destinations are defined in the Msg.h file and currently can take to value Msg::ERR (stderr), or Msg::LOG (which is the alternate log file). The destinations can be 'or'd.

Returns

The old default.

Exceptions Thrown

Bad_val<int> - if the report level is not defined in the Msg.h header. Exammple: #include "msg.h" Msg msgout; msgout.set_default_out(Msg::ERR|Msg::LOG);

Msg::set_time_format - Set the strftime() formatting string.

Synopsis


string Msg::set_time_format(
                            const string& fmt) // I - new time format

Description

Sets the time format to be used in the message header. The format is the same as for the strftime() library function. No checks are made whether the formatting string is reasonable.

Returns

The old time format.

Exceptions Thrown

none

Example

  
	#include "msg.h"
  
	Msg msg;
	string fmt("%y%m%d");	//use non-FITS compliant date
	string old_fmt = msg.set_time_format(fmt);
  
	// set the old format back
	msg.set_time_format(old_fmt);

sev - Set the severity of the current message.

Synopsis


                  const Msg::SEVERITY s) // I - severity code

Description

Severity manipulator. Changes the current message severity to the argument; the default severity is not affected.

The severity levels are defined in the msg.h file and are limited to:

Msg:D
Msg:I
Msg:W
Msg:E
Msg:F

for DIAG, INFO, WARN, ERROR, FATAL. These levels determine whether the message gets reported or not, depending on the setting of the Message Report Level.

If the severity level cannot be interpreted it will automatically be set to Msg:F so that it will always be reported.

Returns

Msg_sev_manip object.

Exceptions Thrown

none

Example

  
	#include "msg.h"
  
	Msg msgout;
  
	msgout << sev(Msg::W) << "This is a warning message!" << endm;

type - Set the type of the current message.

Synopsis


                    const Msg::TYPE t) // I - type

Description

Changes the current message type to the argument; the default type is not affected. The possible types are listed in the msg.h file and are limited to:

Msg::MESG
Msg::BADVAL
Msg::BADTYPE
Msg::MISSING
Msg::CORRUPT
Msg::FIO
Msg::LOCK
Msg::DUPL
Msg::EXEC
Msg::AMBIG
Msg::SEVERE
Msg::MISUSE
Msg::FACTERR
Msg::USE_STRING

If you wish to define a new type, this is easily done by passing a string with the name of the new type, rather than a TYPE.

Returns

Msg_type_manip object.

Exceptions Thrown

none

Example

	#include "msg.h"
  
	Msg msgout;
  
	msgout << type(Msg::BADVAL) << sev(Msg::W) 
	       << "Some bad value was found" << endm;
  
	// define a new type of error message
      msgout << type("ERROR") << sev(Msg::E) 
	       << "An ERROR happened" << endm;

Msg::operator<< - Append something to the message stream

Synopsis


Msg& Msg::operator<<(
                     const string& s) // I - string message

Msg& Msg::operator<<(
                     const char* cs) // I - string message

Msg& Msg::operator<<(
                     const int i) // I - int message

Msg& Msg::operator<<(
                     const unsigned int i) // I - int message

Msg& Msg::operator<<(
                     const long i) // I - int message

Msg& Msg::operator<<(
                     const unsigned long i) // I - int message

Msg& Msg::operator<<(
                     const double& d) // I - double message

Msg& Msg::operator<<(
                     Msg_sev_manip s) // I - severity manipulator

Msg& Msg::operator<<(
                     Msg_type_manip t) // I - type manipulator

Msg& Msg::operator<<(
                     Msg& (*pf)(Msg&)) // I - manipulator w/o args

Msg& Msg::operator<<(
                     ostream& (*pf)(ostream&)) // I - ostream manipulator
                                               //     w/o args

Description

Message output operators place their arguments in the stream, or in the case of manipulators, affect the output in some way.

This method is defined for the following objects:

C++ strings
C strings
ints
unsigned ints
longs
unsigned longs
doubles
severity levels
message types

Returns

A reference to the Msg object.

Exceptions Thrown

none

Example

  
	#include "msg.h"
  
	Msg msgout;
	int i=12;
	double d=1.2;
  
	msgout << "This integer = " << i << endl;
	msgout << "This double  = " << d << endl;
	msgout << sev(Msg::W) << type(Msg::MISSING) 
	       << "Seems that something is missing" << endm;

OPUS API index · STScI Home Page · Search · Topics · Index

For more information, contact opushelp@stsci.edu

Last modified: 25 April 2000

new_logfile( )	create new log file
append_logfile( )	append to an existing log file
close_logfile( )	close log file
set_trl_rpt_level( )	set the trailer report level
set_rpt_level( )	set the default message report level
get_rpt_level( )	get the default message report level
get_trl_rpt_level( )	get the default message report level
set_default_out( )	set the default message output device
set_time_format( )	set the time stamp format
operator<<( )	output operators
err( )	Msg stream manipulators: to stderr
log( )	Msg stream manipulators: to trailer file
day( )	Msg stream manipulators: to day file
dft( )	Msg stream manipulators: to default
endm( )	Msg stream manipulators: end of message
sev( )	set the severity
type( )	set the message type set the message type
sev_func( )	set the severity
ttype_func( )	set the message type
stype_func( )	set the message type

Io_error	- if failed to open log file
Bad_val	- if stretch cannot be resolved