Overview

The RoseErrorReporter class handles the display of all messages from the ROSE libraries. Only one error reporting object exists and is kept by the ROSE interface object. All messages go through this object, and you can provide hook functions if you want to customize how they are handled.

The default behavior is to print messages to the console. Using the report_fn() hook, you can format messages differently, display them in a dialog box, or display them using some other mechanism. The other fine-grained controls are available for setting reporting thresholds and keeping statistics.

The reporter decides to display a message using preferences held by a RoseErrorContext that give thresholds for minimum severity or maximum number of duplicate messages. There are also mechanisms for adding trace information to messages and for keeping summary statistics while turning off all message display.

error_file() 

void error_file (FILE* f);
FILE * error_file();

The error_file() functions hold the output file handle used by the default printf-style reporting function to display messages. If this value is null, messages are printed to stdout. An application may provide a different reporting function that uses or ignores this value.

exit_threshold() 

void exit_threshold (RoseStatus s);
RoseStatus exit_threshold();

These functions are a wrapper around the RoseErrorContext exit_threshold() value on the rose_ec() context. When reporting a message, the threshold value is checked against the severity of the RoseError struct, and if it is met or exceeded, the fatal_fn() hook function is called. The rose_ec() value is normally ROSE_STATUS_FATAL.

fatal_fn() 

typedef void (*RoseErrorFatalFn) (
	RoseErrorReporter *, 
	RoseErrorContext *,
	const RoseError *
	);

RoseErrorFatalFn fatal_fn()
void fatal_fn (RoseErrorFatalFn f)

The fatal_fn() is a user-supplied hook function called when the severity of a message meets the exit_threshold(). If null, the rose_error_dflt_fatal() function is used. The hook function is passed the reporter and error and can use the userfn_data() variable for additional data if required.

log() 

void log(
	RoseBoolean yn = ROSE_TRUE
	);

The ROSE error reporter can log error messages to a file. This is useful for debugging applications that has turned off message printing or on systems that do not have a console. The log() function starts or stops logging from within the application using the filename given by log_filename()

ROSE.error_reporter()-> log_filename (logfile);
ROSE.error_reporter()-> log();         /* turn it on */

. . .

ROSE.error_reporter()-> log (FALSE);   /* turn it off */

Alternatively, you can capture an entire application run by setting the $ROSE_LOG environment variable to the name of a log file. If the variable does not contain a filename, the log will be written to the file rose_log.

% setenv ROSE_LOG  logfile     -- Turns on logging
% unsetenv ROSE_LOG            -- Turns off logging

log_filename() 

void log_filename(
	const char * filename
	);

The log_filename() function allows an application to set the file that logging messages will be written to. This file is normally taken from the ROSE_LOG environment variable. If log_filename() is used, then the log() function must be used to turn on logging.

push_stats() / pop_stats() / stats() 

void push_stats (RoseErrorStats * l);
RoseErrorStats * pop_stats();
RoseErrorStats * stats();

The push_stats() and pop_stats() functions manage a stack of RoseErrorStats objects. The stats() function returns the object at the top of the stack. If you want more information about errors, you can push an instance of RoseErrorStats onto the stack. It will then keep counts, codes, and summary messages for all errors seen. Later, you can search for specific errors, or print summaries with counts.

The following code uses a stats object to capture summary information about the issues seen when reading a STEP file.

RoseErrorStats es;
RoseDesign * d;

ROSE.error_reporter()-> push_stats (&es);
d = ROSE.findDesign ("airplane.stp");
ROSE.error_reporter()-> pop_stats();

... analyze summary information from file read ...

push_trace() / pop_trace() / trace() 

void push_trace (RoseErrorTrace * l);
RoseErrorTrace * pop_trace();
RoseErrorTrace * trace();

The push_trace() and pop_trace() functions manage a stack of RoseErrorTrace objects. The trace() function returns the object at the top of the stack. The top element of this stack is used when reporting a message to give some additional context information like filename, line number, etc.

The following code fragment briefly adds a trace object for use with a warning message.

RoseErrorTrace t1("MY PROGRAM");

ROSE.error_reporter()-> push_trace(&t1);
ROSE.warning ("Something went wrong");
ROSE.error_reporter()-> pop_trace();


This prints the following - 

MY PROGRAM: warning: Something went wrong

report() / va_report() 

void report(
	RoseErrorContext * context,
	const RoseError * message_spec, ...
	);

void va_report(
	RoseErrorContext * context,
	const RoseError * message_spec,
	va_list ap
	);

The report() and va_report() functions are used to signal a message of some sort. The RoseError structure contains message text and a severity, while the context provides thresholds for deciding whether to report a message. The report() function takes printf-style variable arguments for the detail message, while the va_report() function has those arguments as a va_list block as per vprintf().

report_debug() 

void report_debug (int yn);
int report_debug();

The report_debug() functions get and set a flag that forces everything to be shown for debugging, regardless of any other thresholds or settings. This can also be done by setting the ROSE_DEBUG environment variable before running you application.

report_detail() 

void report_detail (int yn);
int report_detail();

The report_detail() functions get and set a flag that controls whether individual messages are printed as they happen. This detailed reporting is on by default, but may be turned off by calling if you are collecting summary data using RoseErrorStats.

report_fn() 

typedef void (*RoseErrorReportFn) (
	RoseErrorReporter *, 
	RoseErrorContext *,
	const RoseError *, 
	va_list
	);

RoseErrorReportFn report_fn()
void report_fn (RoseErrorReportFn f)

The report_fn() functions manage a user-supplied hook function is will be called when the severity of a message meets the report_threshold(). If no hook function is provided, the rose_error_dflt_report() function will be used.

The hook function is passed the reporter, error, and printf varargs. The userfn_data()() variable can hold additional data if required.

report_maxcount() 

void report_maxcount (unsigned i);
unsigned report_maxcount();

These functions are a wrapper around the RoseErrorContext report_maxcount() value on the rose_ec() context, which stops the error reporter from displaying a message after it has occurred a certain number of times. The limit is checked against the count in the current RoseErrorStats object held by the reporter. The limit has no effect if the reporter is not keeping statistics. The rose_ec() value is normally zero, indicating no limit.

report_threshold() 

void report_threshold (RoseStatus s);
RoseStatus report_threshold();

These functions are a wrapper around the RoseErrorContext report_threshold() value on the rose_ec() context. When reporting a message, the threshold value is checked against the severity of the RoseError struct, and if it is met or exceeded, the report_fn() hook function is called. The rose_ec() value is normally ROSE_OK, but may be set to warning by the RoseInterface::quiet() function

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

ROSE.error_reporter()-> report_threshold (ROSE_STATUS_WARNING);

reset() 

void reset();

The reset() function and sets the cumulative status() value kept by the reporter to zero (ROSE_OK).

status() 

RoseStatus status()

The status() function returns the maximum severity of all issues reported since the last reset()

userfn_data() 

void * userfn_data();
void userfn_data (void * d);

The userfn_data() is a pointer variable where an application can keep a reference to additional information for use by report_fn() and fatal_fn() hook functions.

Copyright © 1991-2024 STEP Tools Inc. All Rights Reserved.