Class: FeiMsg

FeiMsg is used by FEI API classes to report messages. You can also use it from within an application. The command line utility fei uses it for example.

You don't create an FeiMsg object in your program. Just one such object exists in program space and its created automatically for you. Instead use the global friend function to feiMsg to reference FeiMsg member functions. The general syntax is:

    feiMsg().< member function >

For example:

    feiMsg().record ("Hello, world!", FEI_OK);

uses the record member function to record the message Hello, world!. (The second argument is the status, or serverity, value associated with the message.)

There is a good reason for using a single object for message reporting and that's because Fei is multi-threaded. With different threads - an your application portion of a program is one thread - it's likely that more than one of them will be writting a message at the same time. The FeiMsg class controlls the activity by only allowing the existance of a single object and by serializing message reporting within that object.

By default FeiMsg writes to stderr. It can also be configured to write a log file or to send email. You open and close a log file with the member functions openLog and closeLog. To have messages mailed, setMaiTo is used. Once configured with any or all of these options, there reporting state can be turned on or off with the member functions: setPrintMessage (stderr), setLogMessge (log file) and setMailMessage (email). These functions take a boolean argument {true, false} that sets the state.

The member function record is used to report a message. The message is sent each of the report facilities (stderr, log file, email) that's configured and has a state value of true.

record takes two arguments: a formatted message and an FEI status value. FEI status values are used by all FEI classes. The values and their general meaning are:

FEI_OK: This is the value returned when things go OK.
FEI_INFO: Everything went OK. This message just reports useful information.
FEI_WARN: Something went wrong, but it was not bad enough to cause an operation to fail.
FEI_ERROR: Something went wrong causing an operation to fail.
FEI_FATAL: Something went wrong that makes it impossible to carry out further Fei operations. For example, if you can't connect to an FEI server, FEI_FATAL is returned because no transactions can be processed.

The status values are positive integers with FEI_OK having a value of 0. The precedence order is FEI_OK < FEI_INFO < FEI_WARN < FEI_ERROR < FEI_FATAL. Note: FEI_OK will always be 0 so you can check the status of an operation as shown in the following example; but don't use numeric values for the other status values; they could change in the future, although their precedence will remain the same. Here's the example:

   if (status)              // take action if the status is
     takeAction (status);   // other than FEI_OK or 0.

When reporting messages you can turn on FeiMsg's header line if you like with the member function useHeader. (By default, it's turned off.) With the header turned on, each message send starts with a line that includes string value equivalent for the status value and the current system time. Use this method if you want to time stamp you messages.

FeiMsg does not return error messages; it's simply a reporting device to be used in multi-thread environments. You can get error messages directly from Fei objects using their member functions getErrno() and getMsg(). If you want to handle reporting messages yourself, turn off all of FeiMsg's reporting states, retrieve messages when you recieve an FEI status other than FEI_OK, and report them using your own mechanism.

For more information on the class, see the header file: FeiMsg.h

int FeiMsg::closeLog (void)

Close the log file if it's open. Before closing, write a message to the log file recording the time it was closed. This message is never printed.

FeiMsg& feiMsg (void)

A global friend function that calls the FeiMsg constructor. Use this function as the handle by which all FeiMsg member functions are referenced. Examples:

    feiMsg().record ("Hello, world!", FEI_INFO);
    feiMsg().openLog ("myLogFile.log");
    feiMsg().setMailMessage (true);

inline bool FeiMsg::isHeader (void)

Returns true if messages are have headers; false otherwise.

inline bool FeiMsg::isLogMessage (void)

Returns true if messages are sent to a log file; false otherwise.

inline bool FeiMsg::isLogOpen (void)

Returns true if the log file if open; false otherwise.

inline bool FeiMsg::isMailMessage (void)

Returns true if messages are emailed; false otherwise.

inline bool FeiMsg::isPrintMessage (void)

Returns true if messages are sent to stderr; false otherwise.

int FeiMsg::openLog (const char *fileName)

Open the log file. A log file is always opened for append. A message is written to the log file recording the time it was opened. Returns FEI_OK unless the log file can't be opened, then FEI_ERROR is returned and a message is recorded to stderr.

The logging state is set to true when the log file is opened. See setLogMessage, isLogMessage for further information.

void FeiMsg::record (const char *msg, int severity, int errorNumber)

Records the message string. Message are sent to stderr, a log file, and email depending on the definitions and reporting state values for those facilities. Two newline character is appended to the end of each message so message are separated by a blank line. If no message is supplied, the function returns immediately without attempting to record a message.

The second and third arguments are optional and only appear if a message header is included with the message, see useHeader. The second argument is an error number to be associated with the message. This is only included if the error number is not 0. The number appears within parentheses following any severity value and preceding the date and time value in the header string. The third argument is the message serverity. Valid values are: FEI_OK, FEI_INFO, FEI_WARN, FEI_ERROR, FEI_FATAL. See the class

bool FeiMsg::setLogMessage (bool flag)

If the flag is true and the log file is open, messages are printed to the log file; and if the flag is false they are not. The current setting of the flag is the return value. The state can't be set to true if the log file is not open.

bool FeiMsg::setMailMessage (bool flag)

If the flag is true and the mail address is defined, messages are mailed, otherwise they are not. The current setting of the flag is the return value. The state can't be set to true if a mail address is not defined.

int FeiMsg::setMailTo (const char *address, const char *subject)

Defined the email address to which messages are sent. Optionally, a subject for each message sent can be included as the second argument, for example:

   setMailTo ("jake@hardknocks.edu", "Re: file type - image");

The mail state is set to true by this memeber function. Change it with setMailMessage. Returns an FEI status value.