Filter error processing

The server reacts to error conditions in various ways, depending on what operation you are running. In general, errors are handled according to where you are within filter processing with regard to the database transaction:

If an error is encountered during filter processing and the filter has no error handler, all processing immediately stops, no further filters or actions run, and an error is returned back to the caller.
If the error occurs during a Phase 1 or 2 action but before the database transaction is completed, the operation is cancelled, the database transaction is rolled back, and no change is made to the database.
If an error occurs during Phase 3 actions, processing continues, and changes are not rolled back. However, if you override filter processing so that your Phase 3 actions are processed before the database transaction, errors are handled according to the "before-transaction-commit" rules. The error handling itself does not change, but using the override causes actions that are normally deferred to take place before the database transaction; therefore, any errors encountered are handled as an error before the transaction is complete and terminate the transaction and roll back.

To summarize, overriding phasing for a filter moves Phase 3 actions into Phase 1 actions. Such actions take on the behavior of other Phase 1 actions (that is, if an error occurs while processing the action, all filter processing is halted, and any database changes are rolled back).

Error handling filters

You can specify an error handling filter that the server executes before it performs the default error handling described in the preceding section. Using an error handler, workflow can recover from an error or change the handling of Message Actions of type Error produced by third-party AR System applications when called from your custom applications.

The procedure for creating an error handling filter is much the same as creating any filter. To specify and enable an error handler filter, use the Error Handler in the filter editor. See Creating filters. For an example of an error handling filter, see the Sample application distributed with AR System . The Sample:GetMoreInfo filter has an error handler, Sample:GetMoreInfoError.

The error handler filter and the filter whose errors it handles must be associated to the same form in the Associated Forms list for the filter. This ensures the error handler has access to the fields the other filter references. If no error handler is specified or if the error handler is not enabled, AR System handles errors.

Error handler execution

When a filter is executed as an error handler, the execution differs from the usual filter execution in the following ways:

The Execution Order value and Execute On selections on the Basic tab of the Filter properties window are ignored. The Enable check box is not ignored. The filter must be enabled to be executed.
Three keywords that give information about the error that caused the error handler to be called are defined:
- $ERRNO$ — The number of the first error on the stack.
- $ERRMSG$ — The error message for the first error on the error stack.
- $ERRAPPENDMSG$ — The appended message for the first error on the error stack, if any.
  Some error conditions place more than one error number, message, and appended message on the error stack. The error handler has access to the first one only.
Filter processing phasing is overridden. Phase 3 actions are not deferred; they are run immediately. The error handling filter executes in-line like a filter whose name ends with a back quote and an exclamation point (`! ). Although this naming convention is not required, use this convention for error handling filters to indicate that they execute in-line.
When all the If actions of the error handling filter complete successfully, the error is considered handled, the error information and keyword is cleared, and the filter in which the error occurred continues execution with the next action. If another error occurs during the execution of the filter, the error handler is executed again.
If the Else actions of the error handler filter are executed or if the If actions terminate in error as described in the next section, the error information is not cleared, the remaining actions in the filter where the error occurred are not run, and the server continues to process the error. If the filter was called from another filter, the server might call another error handler as described in Error handling for nested filter calls. Otherwise, the server processes the error.

Errors in error handling filters

An error can occur while an error handler is running its If actions. If the error handler has its own error handler, that error handler is called (unless calling that inner error handler would exceed the Maximum Stack of Filters value). If that error handler handles the error, the If actions of the outer error handler continue to run.

If the outer error handler does not have its own error handler or if its error handler does not handle the error, the remaining If actions of the outer error handler are not run, the error information for the error in the If actions is added to the error stack below the original error, the outer error handler does not handle the original error, and the error is treated as described in the next section on nested filter calls.

An error can occur while an error handler is running its Else actions. If the error handler has its own error handler, that error handler is called (unless calling that inner error handler would exceed the Maximum Stack of Filters value). If that error handler handles the error, the Else actions of the first error handler continue to run.

If the outer error handler does not have it own error handler or if its error handler does not handle the error, the remaining Else actions of the outer error handler are not run and the error information for the error in the Else actions is added to the error stack below the original error.

Because the outer error handler was running its Else actions when the error occurred whether or not the error is handled, the outer error handler does not handle the original error and it is treated as describe in the next section on nested filter calls.

Error handling for nested filter calls

A filter can be executed from another filter, so a filter can execute some number of levels down in a stack of executing filters. If an error occurs in such a filter and the error is not handled, either because the filter has no error handler or because the error handler does not handle the error, the remaining actions in the filter where the error occurred are not run and the error is passed one level up the stack.

AR System server treats the error as it had occurred in the filter that executed the filter where the error actually occurred. That filter can, in turn, handle the error or not. Thus, the error can pass up though the stack of running filters, terminating each until an error handler handles it. If no error handler handles the error, AR System server performs default error handling.

If an outer error handler handles an error that occurs in a nested filter call, the remaining actions in the nested call, if any, are not run. In this case, the server does not report an error, but some actions are skipped. The following figure illustrates how an action can be skipped. Filter F4 has error handler HF4. When F4 runs a Push Fields action to another form, it executes filter F5. Filter F5 has error handler HF5. An error occurs in F5, but HF5 does not handle it. Filter HF4 is called and handles the error in F5. But the actions in F5 that were pending when the error occurred are not run because HF4, the error handler for F4, handled the error.

Error in Nested Filter Execution, Error Handler for Outer Filter Handles Error

Using filter guides with error handling filters

To write a filter that handles several errors, write the qualification to select exactly the errors the filter must handle, store the values of the filter error keywords in fields in the form, and call a filter guide. The qualifications of the filters in the guide select the filter to process each error. If the last filter in the guide has no qualification, it must process the error or errors the other guide filters do not process. The guide filters are not error handlers. They get the error keywords values from the fields in the form, not from the keywords. The actual error handling filter that called the guide succeeds because its If actions are run and do not fail. The guide filters must process all the errors that pass the qualification of the error handler.

To handle errors from separate actions differently, put the actions in separate filters with different error handlers and put those filters in a filter guide.