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:
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.
The model is a slightly modified form of CICSAccts. The changes made were:
TestFormatErrorevent handler to the model event source.
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 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.
Load the model in the Design Tool, connect to the Host Emulator, and navigate to the Main entity.
To cause the event handler to leave the error stack alone, execute the Delete operation first. Since there is no record to delete, the Delete operation ends up at an entity called NoAccount. The Delete operation defines this as an error entity with its own message, and the event handler leaves that alone.
To cause the event handler to replace the error messages on the stack with its own message, navigate back to the Main entity, enter the value "Q" in the attribute labeled SurName, and execute the SearchByName operation. The error returned by the event handler will explain that only name searches for the letter "W" are allowed.
To exercise the final case, adding another error to the error list, return to the Main entity and execute the Add operation. Then execute the FillWithValidData and SaveChanges operations. This will return to the Main entity. Now execute the Add operation again. An error dialog containing the text Unexpected error will be displayed. If the error details are not already displayed, click the button marked "Details >>" to see the errors that were originally reported by the Verastream server.
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
(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.
unrecognizedScreen event handler can respond to the event in three
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.
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.
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.
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.