[SESI logo]

Houdini Development Toolkit - Version 6.5

Side Effects Software Inc. 2004

Utility Classes

UT_ErrorManager Class

This class was designed to manage an ordered list of UT_Error objects. Each UT_Error object has a severity (message, warning, abort, or fatal) associated with it, and can be used to generate a message string. Typically, the UT_Error objects are created through the add* methods of UT_ErrorManager.

In houdini, there are many error managers, one of which is the global error manager. Functions that are not operating within the context of a specific error manager will add their errors to the global error manager (using the UTadd* global functions). When program control returns to a function which is aware that it is being executed within the context of a specific error manager, it transfers the errors from the global error manager to the specific one.

For example, the LSystem SOP uses a class far down in the GU library which is responsible for generating the geometry for the L-system. After generating the string that describes the L-system, the GU class adds a message containing the string to the global error manager.

 UTaddMessage("GU", CODE, "FFFA"); 

The particulars of this function call are described in the Methods section below. When program control returns to the SOP_LSystem object that initiated the action, the message is transfered from the global error manager to the SOP's local error manager.
 myErrorManager->stealErrors(UTgetErrorMessage()); 

The messages and errors that are stored in the SOP's error manager are used to generate the messages that are seen in the SOP's info button in houdini.

Each error manager also has an error severity associated with it. This severity is defined as the maximum severity of all the contained UT_Error objects. The severity is an enumerated type defined by UT_ErrorSeverity. It can be one of:

UT_ERROR_NONE The error manager is empty.
UT_ERROR_MESSAGE Used for informational messages.
UT_ERROR_WARNING Something unusual happened, but there was a graceful recovery.
UT_ERROR_ABORT There was an errror from which recovery wasn't really possible, and code execution was aborted.


Methods

constructor

The constructor initializes the list to be empty and clears the error status of the manager.

void clearAndDestroyErrors();

This method deletes all UT_Error objects that are contained in the UT_ErrorManager and resets the UT_ErrorManager.

int stealErrors(UT_ErrorManager &victim, int rangestart = 0, int rangeend = -1, UT_ErrorSeverity severity = UT_ERROR_NONE);

This method steals all UT_Error objects from the UT_ErrorManager that is specified as victim, unless the rangestart, rangeend, or severity arguments are changed from their defaults. These extra parameters can be used to restrict the errors being taken. (a severity of UT_ERROR_NONE means "ignore the severity of the errors"; any other value means take only those errors with exactly the specified severity)

void getErrorMessages(UT_String &messages, UT_ErrorSeverity severity = UT_ERROR_NONE);

This is the call that is used to generate a long string containing the concatenation of all the messages generated from the UT_Errors contained in the UT_ErrorManager. (The severity parameter works as the one above.

UT_ErrorSeverity addMessage(const char *type, int code, const char *msg=0)
UT_ErrorSeverity addWarning(const char *type, int code, const char *msg=0)
UT_ErrorSeverity addError (const char *type, int code, const char *msg=0)
UT_ErrorSeverity addFatal (const char *type, int code, const char *msg=0)

Each of these four functions will instantiate a standard UT_Error object with a severity type correspond to the ones described above. The parameters determine what message should be generated from the UT_Error object.

By convention, type is the prefix that is used for the library that generated the error. For example, all errors that are added from any function in the SOP library will add an error with type set to "SOP".

Actually, the type string is used to find the file containing the string used to generate the UT_Error's message. The files are located in $HFS/houdini/error. So, for example, all the SOP messages are stored in the file $HFS/houdini/error/SOP. The format of the file is very simple:

<code number> <tab> <message>

For the purposes of writing custom code, it is best to create your own message file to avoid conflicts with existing or future changes to the standard houdini files.

<code number> is the code that is passed into the functions above. Every line in the error file that starts with that code number will be used to generate the message for the error.

You can also insert your own substrings in the message text by using the msg parameter. UT_ErrorManager uses sprintf to insert the substring into the string that was found in the error file. ie:

sprintf(message, string_from_error_file, msg);

The placement of the substring is determined be the placement of a %s in the text found in the message file. In the L-system example above, the message file might contain:

So that calling:

Would result in the message:


Global Functions

UT_ErrorManager UTgetErrorManager()

This function returns a pointer to the global UT_ErrorManager.

UT_ErrorSeverity UTaddMessage(...)
UT_ErrorSeverity UTaddWarning(...)
UT_ErrorSeverity UTaddError (...)
UT_ErrorSeverity UTaddFatal (...)

These four global functions correspond to the four similarly named member functions above. They are provided for convenient access to the global UT_ErrorManager. In other words, they are equivalent to calling:

UTgetErrorManager()->addMessage(...); etc.


Other Information

Within the context of writing custom OPs, you generally don't have to worry about calling stealErrors() because the OP_Node base class steals the errors from the global UT_ErrorManager after your cook code.

However there are some circumstances where you should call stealErrors directly yourself. For instance, if you are about to ask another OP to cook, you should make sure you steal any existing global errors for yourself. Otherwise they will be aquired by the other OP, and you'll get confusing error messages. There is a function called stealGlobalErrors provided in OP_Parameters (the superclass of OP_Node) that steals the errors from the global UT_ErrorManager.


Table of Contents
Operators | Surface Operations | Particle Operations | Composite Operators | Channel Operators
Material & Texture | Objects | Command and Expression | Render Output |
Mantra Shaders | Utility Classes | Geometry Library | Image Library | Clip Library
Customizing UI | Questions & Answers

Copyright © 2004 Side Effects Software Inc.
477 Richmond Street West, Toronto, Ontario, Canada M5V 3E7