![]() |
Houdini Development Toolkit - Version 6.5Side Effects Software Inc. 2004 |
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");
myErrorManager->stealErrors(UTgetErrorMessage());
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. |
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:
24 L-system string "%s" was generated.
So that calling:
UTaddMessage("GU", 24, "FFFA");
Would result in the message:
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.
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.