Troubleshooting Error Patterns and Error Entities

The following topics explain the useful techniques associated with using error entities and error patterns when modeling a host application, specifically when dealing with character mode host applications. Using error conditions helps you to detect when an error has occurred while you're modeling and testing your host application model. Error patterns catch error messages displayed on the current entity, while error entities handle errors that result in a host error screen being displayed.

When creating both error patterns and error entities, it's possible to create a customized error message that enables you to detect what kind of error has occurred during an operation.

Note: In the Design Tool, if an error occurs and an operation completes before an error pattern is displayed or an error entity is reached, then error processing will not occur. For example, if an operation's destination entity is the same as its start entity and an error message is expected to display when the destination is reached, the action triggered by that error message may be bypassed. The operation needs to include a command, like a WaitForCursorAtLocation command, that ensures that the error pattern is displayed or the error entity is reached before the operation completes.

Error Patterns and Error Entities

When handling an error condition, you sometimes have the choice of setting up an error pattern or an error entity. When evaluating which to use, review the FAQ on this topic and remember that error patterns require less processing overhead and are therefore recommended. If you're dealing with a problem associated with a starting screen, you will need to use an error entity.

Trapping error messages that result from writing attribute data to the terminal screen is often helpful in identifying errors. This is usually applicable to character mode host applications that produce error messages while you are writing data to the terminal screen.

To create an error pattern to trap a host application error message:

The example below catches an error by creating an error pattern.

  1. Encapsulate the error message in a pattern and add it to the entity.
  2. On the Pattern tab, clear the Use in entity signature check box.
  3. Click the Operation tab in the Entity window.
  4. Click the Conditions button to open the Operation Conditions dialog box.
  5. Under Error patterns, move the pattern from the Available list to the Error patterns list.
  6. Under Error pattern, you can configure a text or an attribute value to be returned if an entity encounters an error pattern during an operation.
  7. Click Close to close the Operation Conditions dialog box and save any changes.


Error Entities

A user-defined error entity enables you to handle a host error screen by defining a custom error message or returning attribute data as your error message when the error entity is encountered. Make sure to define an operation on this error entity that enables you to navigate back to your original entity. Do not define an error entity as your home entity; if error handling is required, use error patterns instead.

To define an error entity:

  1. Select the entity from the Name box on the Entity window and click the Operation tab.
  2. Click the Destinations button to open the Operation Destinations dialog box.
  3. Select an entity from the Unassigned entities box and click the right arrow button to add it to the User-defined error entities box.
  4. You can also select one of the following options from the Operation Destinations dialog box to customize an error message to appear when your error entity is reached:


For more information, see the error pattern and error entities questions on the FAQ page.