Handling Errors

  • Article

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 2007 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

Overview of the Error object

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.