Appendix C. Error Handling

Inventor provides a basic error handling mechanism for use with both the optimized and debugging versions of Inventor. As shown in Figure C-1, three classes are derived from the base class, SoError. Read errors occur during reading of an Inventor file. Memory errors occur when an application runs out of memory. Debugging errors occur as the result of a programming error. Most debugging errors are generated only in the debugging version of Inventor and are not checked in the optimized version. A correct application does not generate any debugging errors. In the beginning, it's a good idea to link with the debugging version of Inventor to ensure that your program is correct. Later, when no errors are generated, you can switch to the optimized version.

Figure C-1. SoError Class Tree

For example, suppose Inventor encounters an unrecognized field name when it is reading a file. The following steps occur:

  1. Inventor calls the static SoReadError::post() method and passes in the correct arguments.

  2. The SoReadError class creates an instance of itself. Within this instance, it stores the debug string, a character string that represents a detailed error message. (Use getDebugString() to obtain the debug string.)

  3. The SoReadError class passes the error instance to its error handler. The default error handler for all error classes simply prints the debug string to stderr. You can register your own error handler for specialized behavior. For example, in this case, you might want to bring up a window displaying a message saying that an error occurred during reading. Use the setHandlerCallback() method to register your own handler for an error class.

Runtime Type-Checking

Standard Inventor runtime type-checking for error classes is provided by the base class SoError. Each error class contains a runtime class type ID that can be used to determine the type of an instance.

Posting an Error

Each subclass of SoError has its own post() method. Posting is performed primarily by Inventor, but application writers can post their own errors as well.

Handling an Error

You can override the default error handler by specifying a callback function to be invoked when an error is posted. Each subclass of SoError supports a static setHandlerCallback() method. You can register the callback on SoError, so that it is called for all errors, or you can register it on one of the classes derived from SoError. The callback for the most derived class of a specific error instance is used to handle the error. Note that the error instance passed to a callback is deleted immediately after the callback is invoked. The application must copy this data ahead of time if it needs to use it later.


If you are using an interactive debugger, you may be able to set a breakpoint in SoError::handleError(), which is called whenever an error is handled. You can also create your own error handler, register it, and use the callback function to investigate the error condition.