Debugging

The following macros are used to conditionally generate output for debugging. All output generated by these macros is written using the replaceable character-output procedure pointed to by the global variable SOMOutCharRoutine. The default procedure simply writes the character to stdout, but it can be replaced to change the output destination of the methods and functions below. (See Chapter 5 for more information on customizing SOM.)

Debugging output is produced or suppressed based on the settings of three global variables, SOM_TraceLevel, SOM_WarnLevel, and SOM_AssertLevel:

• SOM_TraceLevel controls the behavior of the <className>MethodDebug macro;

• SOM_WarnLevel controls the behavior of the macros SOM_WarnMsg, SOM_TestC, and SOM_Expect; and

• SOM_AssertLevel controls the behavior of the SOM_Assert macro.

Available macros for generating debugging output are as follows:

<className>MethodDebug

(macro for C and C++ programmers using the SOM language bindings for <className>) The arguments to this macro are a class name and a method name. If the SOM_TraceLevel global variable has a nonzero value, the <className>MethodDebug macro produces a message each time the specified method (as defined by the specified class) is executed. This macro is typically used within the procedure that implements the specified method. (The SOM Compiler automatically generates calls to the <className>MethodDebug macro within the implementation template files it produces.) u To suppress method tracing for all methods of a class, put the following statement in the implementation file after including the header file for the class:

#define <className>MethodDebug(c,m) \
                   SOM_NoTrace(c,m)

This can yield a slight performance improvement. The SOMMTraced metaclass, discussed below, provides a more extensive tracing facility that includes method parameters and returned values.

The SOM_TestC macro takes as an argument a boolean expression. If the boolean expression is TRUE (nonzero) and SOM_AssertLevel is greater than zero, then an informational message is output. If the expression is FALSE (zero) and SOM_WarnLevel is greater than zero, a warning message is produced.

The SOM_WarnMsg macro takes as an argument a character string. If the value of SOM_WarnLevel is greater than zero, the specified message is output.

The SOM_Assert macro takes as arguments a boolean expression and an error code (an integer). If the boolean expression is TRUE (nonzero) and SOM_AssertLevel is greater than zero, then an informational message is output. If the expression is FALSE (zero), and the error code indicates a warning-level error and SOM_WarnLevel is greater than zero, then a warning message is output. If the expression is FALSE and the error code indicates a fatal error, then an error message is produced and the process is terminated.

The SOM_Expect macro takes as an argument a boolean expression. If the boolean expression is FALSE (zero) and SOM_WarnLevel is set to be greater than zero, then a warning message is output. If condition is TRUE and SOM_AssertLevel is set to be greater than zero, then an informational message is output.

See the System Object Model Programming Reference for more information on a specific macro.

The somDumpSelf and somPrintSelf methods can be useful in testing and debugging. The somPrintSelf method produces a brief description of an object, and the somDumpSelf method produces a more detailed description. See the System Object Model Programming Reference for more information.