Format Error Example

Purpose

This example shows how to respond to a formatError event delivered to a model event handler. A format error event is generated after the Verastream server has decided that an error must be reported, but before the error is returned to the client application. A formatError event handler has the opportunity to examine the error stack and to add, remove, or change entries in the stack. This permits an event handler to provide more descriptive error message than Verastream can provide itself.

This example illustrates three different ways in which a format error event handler can deal with errors:

  1. Do nothing. In this case the original error is returned to the client.
  2. Replace the error messages with a different error message (or messages).
  3. Add more information to the existing errors.

In this example the model used is a variant of the CICSAccts model supplied with the Verastream software development kit. The model has been modified slightly so that it can be used to drive an event handler to display the alternative behaviors.

Model Design

The model is a slightly modified form of CICSAccts. The changes made were:

Implementation

The event handler retrieves a List of the errors which the Verastream server intends to return to the client application, and determines the number of errors it contains. Then the event handler begins a simple case analysis to decide whether or not the error list should remain as-is or be modified.

If only one error is in the list and its error code means that a user-defined operation error entity has already supplied an error message, the errors being reported by the server are not changed. Notice that in this case the newErrorList variable remains set to null. Returning null from this event means "report the existing errors, as-is".

If two errors are to be returned, and the error to be reported is that a name search failed, the event handler returns a new error list containing only a single error message.

In all other cases the error reported by the server is considered to be "unexpected". In this case a new user-defined error with the text "Unexpected error" is returned as the first error. Then the existing error list entries are copied to the new error list.

Finally, the new error list is returned to the server.

Unrecognized Screen Example

Purpose

When the host application displays a screen which is not defined as an entity in the Verastream model, the Verastream server will usually abort the session and report a dead session exception to the client. This will not occur if either (a) the client is using an ApptrieveRejuvenationSession (for which undefined screens are a normal part of processing), or if (b) the model has provided an unrecognizedScreen event handler.

Unrecognized screens are also a normal part of using the Design Tool: when defining a new model all host application screens are unrecognized. For this reason, unrecognized screen events are sometimes difficult to generate in the Design Tool environment.

An unrecognizedScreen event handler can respond to the event in three different ways:

  1. Issue terminal-level commands (for example, keystroke entries, or disconnecting from and reconnecting to the host) to cause the host application to reach a known screen.
  2. Temporarily "delay" the departure from the last known screen (entity). This is useful when the event handler has reason to believe that the screen, while not recognized by the Verastream server, still has attributes or recordsets or operations which can be used. (This sleight of hand works only until Verastream does recognize another entity.)
  3. Throw an error to be returned to the client application.

This example illustrates two ways to issue terminal-level commands to recover from an unrecognized screen event. Depending upon the recovery option chosen it will either send a Clear key to the host application or disconnect from and reconnect to the host application.

Model Design

The UnrecognizedScreenmodel is adapted from the CICSAccts model supplied with the Verastream software development kit. It has been modified by removing the tables and procedures, removing some operations related to procedures, and by removing the NoAccount entity.

Execution using the Design Tool

Start by running the Design Tool, loading the UnrecognizedScreen model, connecting to the Host Emulator, and navigating to the Main entity. To see the screen dump generated by the event handler, open the Event Handler Console window.

On the entity Main, tab to the LastName attribute (labeled SURNAME on the screen) and enter any letter except "W". Then execute the SearchByName operation. An Operation in Progress dialog will appear for ten seconds or so (the operation timeout). Nothing appears to happen because the operation is waiting for an operation destination, alternate, or error entity to appear.

Once the operation times out the server notices that it is sitting at an unrecognized screen. The server calls the unrecognized screen event handler to recover from the problem. The event handler reads the model variable EventRecoveryType to decide how to recover. Even though the event handler moves the host application to the Main entity, the Design Tool reports an operation timeout.

The default setting for EventRecoveryType is "clear". That tells the event handler to send a Clear key to the host application, which returns to the entity Main. Setting the variable value to "reconnect" tells the event handler to disconnect and reconnect to the host application. Use the Model:Variables... menu command, which displays the Variables dialog, to change the variable value.

Implementation

The event handler itself is simple. It determines how it should recover from the unrecognized screen problem, dumps a screen image to the Java output stream, and then executes the recovery action.