Handling errors
When creating custom applications, developers must often perform error handling that involves writing programming code to check for errors raised by the application or to create and raise custom errors. The Microsoft Office InfoPath 2003 object model supports error handling through the use of the Error object in association with the Errors collection.
In InfoPath, errors can occur when a form's XML Schema is validated, when a custom validation constraint fails, when an error is generated by the ReportError method of the DataDOMEvent object, or when an error is created using the Add method of the Errors collection.
Overview of the Errors collection
The Errors collection provides the following methods and properties that form developers can use to manage the Error objects that the collection contains.
| Name | Description |
|---|---|
| Add method | Creates an Error object and adds it to the collection |
| Delete method | Deletes all Error objects associated with the specified XML node and condition name |
| DeleteAll method | Deletes all Error objects contained in the collection |
| Count property | Returns a count of the number of Error objects contained in the collection |
| Item property | Returns a reference to an Error object based on the specified index number |
The Error object provides the following properties that form developers can use to access information about the error object.
| Name | Description |
|---|---|
| ConditionName property | Returns the name of the error condition, or returns null, depending on the type of Error object |
| DetailedErrorMessage property | Specifies or retrieves the detailed error message of the Error object |
| ErrorCode property | Specifies or retrieves the error code of the Error object |
| Node property | Returns a reference to the XML node associated with the Error object |
| ShortErrorMessage property | Specifies or retrieves the short error message of the Error object |
| Type property | Returns the type of the Error object |
Using the Errors collection and the Error object
The Errors collection is accessed through the Errors property of the XDocument object. The Errors collection is associated with a form's underlying XML document so that when an error occurs, it occurs within the XML document. The following example demonstrates how a Microsoft JScript for loop can be used to check the errors that may exist in a form's underlying XML document. The function first checks the Count property of the Errors collection to determine whether any errors are present. If there are errors, the function loops through each of them, and, using the ShortErrorMessage property of the Error object, displays a message box to the user.
function CheckErrors(xmlNode)
{
for (var i=0; i<XDocument.Errors.Count; i++)
{
var objError = XDocument.Errors(i);
if (xmlNode == objError.Node)
{
XDocument.UI.Alert("The following error has occured: " +
objError.ShortErrorMessage + ".");
}
}
}
The preceding function could be called from one of the form's data validation event handlers. For example, when used in the OnAfterChange event for a field in the form, the call to the function would pass the XML node argument using the Site property of the DataDOMEvent object as follows:
CheckErrors(eventObj.Site);
In addition to handling errors generated by InfoPath, form developers can also generate their own custom errors by using the ReportError method of the DataDOMEvent object, or by using the Add method of the Errors collection. For information about using the ReportError or Add methods, click the methods at the beginning of this topic.