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
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.
Exceptions Thrown
Example
Msg msgout; msgout << "This is a message" << endm;
Msg::~Msg - The Node object destructor.
Synopsis
Msg::~Msg()
Description
Destroys the object.
Exceptions Thrown
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
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
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
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:
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
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:
Returns
Msg_type_manip object.
Exceptions Thrown
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:
Returns
A reference to the Msg object.
Exceptions Thrown
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;
Copyright © 1997-2000 The Association of Universities for
Research in Astronomy, Inc. All Rights Reserved.
For more information, contact opushelp@stsci.edu
Last modified: 25 April 2000