index previous next 

File name: error.hpp, error.cpp
contents: error report macros, global error functions
use: provide a common interface for all error outputs of the simulation
 
Note: this description does not include error.h, which belongs to the network driver and has nothing to do with SimUTC error handling.

 
global items used by the functions:

 
local items used by the functions:

const int MessageLen: the maximum length of the complete error message.

#define ABORTFUNC: the name of the function that is called to stop the program if an assert fails. The function depends on the operating system: if PSOS_SIM is defined, then the macro is set to k_fatal. Otherwise, it is set to abort.

#define ABORTPARAMS: the parameters of the abort function. Again, the value of the macro depends on the operating system: if PSOS_SIM is defined, then the macro is set to 0x10000, K_LOCAL. The first parameter is the error code that is set by k_fatal(), the second parameter specifies that only the local node should be shut down. If PSOS_SIM is not defined, the macro is void.
 

macros:

All macros operate on the same principle: if NDEBUG is defined, the macro expands to void (i.e., it behaves as if it were not there). Else, it calls the global function ReportError (EReportType, char *, int, char *) (see below) and then does something specific to the macro used. Since the macro is expanded, if you use it in a class that has a function with the same prototype as the above-mentioned global ReportError(), the function of the class is called instead. You can use this trick to add additional information like the identifier(s) and type of the module that is reporting the error. Even if you are overloading the global function and adding own information, always call one of the additional global functions declared in error.hpp and return their return values. In the following description of the macros, it is assumed that NDEBUG has not been defined.

Assert (expr): If expr evaluates to zero, the macro calls ReportError() with type Asserting, which causes ReportError() to stop the program. If expr evaluates to non-zero, nothing happens. The macro has no value.

Check(expr): If expr evaluates to zero, the macro calls ReportError() with type Checking and has the value of ReportError(), which should be 0. If expr evaluates to non-zero, nothing happens, and the macro has the value 1.

Report(expr): expr is *not* evaluated. The macro calls ReportError() with type Reporting and has no value.
 

global error report functions:

enum EReportType: Asserting, Checking, Reporting

int ReportError (EReportType type, char *file, int line, char *expression): Report the error of type type in expression expression, which has occurred in file file at line line. If type==Asserting, then abort() is called and the function does not return. The other types do not stop program execution and should always return 0. The error message itself is assembled into a string and give to an error handler object, which must be installed to see any error outputs.

int ReportError (EReportType type, char *file, int line, char *expression, EModule module): Adds the module type to the basic error output.

int ReportError (EReportType type, char *file, int line, char *expression, EModule module, SINT32 moduleID);
Adds the module type and a module identifier to the basic error output.

int ReportError (EReportType type, char *file, int line, char *expression, EModule module, SINT32 nodeID, int area);
Adds the module type and two module identifiers to the basic error output.
 
void ReportMessage (const char *msg): Just passes on the message to the error handler (if installed). The function does not append any additional information.
 

(de-)installing an error handler:

void InstallErrorHandler (CErrorHandler *handler): Installs an error handler (cf. errbase.hpp); error.cpp keeps a pointer to that handler and passes all error messages to it. As long as no handler is installed, the pointer is NULL and error messages are discarded, so you must install a handler if you want to see the error messages of your code.

void DeinstallErrorHandler (): Sets the internal pointer to the error handler to NULL.
 

local variables defined in the implementation file:

CErrorHandler *errorHandler: the currently used error handler. If the variable is NULL, the error messages are discarded.
default: NULL
 

local functions defined in the implementation file:

int GetReturnValue (EReportType type): returns the value that the calling ReportError() function should return, which is 0. If type is Asserting, then if an error handler exists it is deleted (causing all messages that are still kept to be flushed), and at last the function calls ABORTFUNC (ABORTPARAMS) to stop program execution. Thus, the function does not return.

char *ModuleToString (EModule module): converts the module enumeration into a string constant, which is returned.

void PrintFileSpecs (EReportType type, char *expression, char *file, int line, char *msg): Assembles the basic error report message that is printed as the first line by all ReportError() functions.
 
 


last modified: Fri Feb 5 18:56:13 1999