ROSE Library Reference
RoseErrorContext

Overview

The RoseErrorContext class is for libraries or applications that have defined their own codes. This class stores predefined errors as well as severity and logging information. The thresholds are normally handled by the RoseErrorReporter, but you can set local thresholds for each context. Report errors to the context and it will find or create the appropriate RoseError structure and pass it on to the error reporter.

The RoseError structure is used to create a static array of predefined errors. These are used with the RoseErrorContext class to define messages for a particular library or application. Note that error codes may be duplicated between contexts, but it is not advisable to do so.

// ERROR CONTEXT -- Provides RoseError lookup by numeric code and also // local thresholds for passing on to the reporter for printing. // class ROSE_DLLSPEC RoseErrorContext { protected: RoseError * f_msgs; unsigned f_msgcnt; unsigned f_rptmax; RoseStatus f_rptlev; RoseStatus f_quitlev; public: RoseErrorContext(); RoseErrorContext( RoseError * msgs, /* message array */ unsigned msgcnt /* message array size */ ); // look up the message for a given code. RoseError * find_error (RoseErrorCode code); // ISSUE REPORTING - Direct reporting with a RoseError or lookup // with a predefined code. Also a convenience versions that make // a general unspecified issue with a detail string. // // No minor() convenience function because of conflicts with a // macro in sys/types.h on linux. // void report (const RoseError *, ...); void report (RoseErrorCode, ...); void fatal (const char* fmat, ...); void error (const char* fmat, ...); void warning (const char* fmat, ...); void message (const char* fmat, ...); // Show report if the issue has a severity at or above the // threshold. Set to ROSE_STATUS_DEFAULT to fall back to the // value in rose_ec(), which is normally ROSE_OK to show all // informational messages as well as more severe issues. // void report_threshold (RoseStatus s); RoseStatus report_threshold() { return f_rptlev; } // Stop reporting an issue after a certain number of times. Set // to zero for no limit, or set to ROSE_MAXCOUNT_DEFAULT to fall // back to the default in rose_ec(). A RoseErrorStats object must // be present for this to work. // void report_maxcount (unsigned s) { f_rptmax = s; } unsigned report_maxcount() { return f_rptmax; } // Exits if the issue has a severity at or above the threshold. // Set this to ROSE_STATUS_DEFAULT to fall back to the value in // rose_ec(), which is normally ROSE_STATUS_FATAL. // void exit_threshold (RoseStatus s); RoseStatus exit_threshold() { return f_quitlev; } // table of all errors, mostly for internal use RoseError * get_error_by_index (unsigned idx); unsigned size(); };

RoseErrorContext Constructor

RoseErrorContext(
	RoseError * msgs,  /* message array */
	unsigned msgcnt    /* message array size */
	);

struct RoseError {
	RoseErrorCode f_errcode;
	RoseSeverity  f_severity; 
	char *        f_message; 
	};

The RoseErrorContext constructor creates an new error context and expects an array of pre-defined RoseError messages to be supplied.

Example

    #define BAD_KEYWORD  100
    #define NO_FILE      200
     
    RoseError application_errors[] = {
    { BAD_KEYWORD, ROSE_SEV_WARNING, "Unknown keyword %s" },
    { NO_FILE,     ROSE_SEV_WARNING, "Could not find %s" }
    };
     
     
    RoseErrorContext * application_ec() {
        static RoseErrorContext * ec = 0;
     
        /* Create the context on the first call.  Do this rather than
         * have a global with a static ctor so that we can report
         * errors during static ctor calls if necessary.
         */
        if (!ec) {
        	ec = new RoseErrorContext 
        		(application_errors, 
        		 ROSE_COUNT (application_errors));
        }
        return ec;
    }

See Also

RoseSeverity;

<action>_threshold()

RoseSeverity exit_threshold();

RoseSeverity report_threshold();

void exit_threshold(
	RoseSeverity s
	);

void report_threshold(
	RoseSeverity s
	);

The error context keeps track of severity thresholds for reporting errors, and exiting the application. The error reporter only takes action if the severity of a message exceeds the threshold. Setting the thresholds to ROSE_SEV_FATAL turns off the action. The error reporter also has thresholds, but the thresholds in the error context will override these if they are set to something other than ROSE_SEV_NULL.

Example

The following example sets the reporting threshold so that informational messages are not printed.

    RoseErrorContext * ec;
    ec-> report_threshold (ROSE_SEV_WARNING);

See Also

RoseSeverity; RoseErrorReporter::<action>_threshold()

<error_severity>()

virtual void fatal(
	char * fmat, ...
	);

virtual void error(
	char * fmat, ...
	);

virtual void warning(
	char * fmat, ...
	);

virtual void message(
	char * fmat, ...
	);

These functions are used report general error conditions that do not have a pre-defined code for the report() function. The functions take variable arguments and use the printf() conventions, but no trailing newline is required.

Example

    RoseErrorContext * ec;
    RoseDesign * design;
     
    ec-> message ("Design %s is happy", design-> name())
    ec-> warning ("Design %s is not happy", design-> name())
    ec-> error ("Design %s is extremely unhappy", design-> name())
    ec-> fatal ("Design %s is so unhappy that we stop here", design-> name())

report() / va_report()

virtual void report(
	RoseErrorCode code, ...
	);

virtual void va_report(
	RoseErrorCode code, 
	va_list ap
	);

The report() and va_report() functions are used to signal one of the pre-defined conditions. The RoseErrorCode corresponds to a predefined RoseError structure, which contains message text and a severity. The severity determines whether the message will be printed and/or logged, and whether the application will quit or continues as appropriate. The set of pre-defined conditions are specified when the error context is created.

The report() function takes variable arguments for printf() parameters within the pre-defined error message. The va_report() function is for reporting a condition from within a function that already takes variable arguments. The function uses the same convention as the vprintf() function.

Example

The following example uses the messages defined by the RoseErrorContext constructor example:

    RoseErrorContext * ec;
     
    ec-> report (BAD_KEYWORD, "OPEN");
    ec-> report (NO_FILE, "/usr/local/widget");