The events available for creating model event handlers are listed below. Review the API documentation for model events for more information.
The Client Connected event is fired after a client session has been created and the terminal has been positioned on the model's home entity.
Possible uses:
This event allows a new client session to have the terminal initialized in some customized manner. For example, based on an input parameter, the session could be automatically repositioned to another entity.
Notes:
This is the first event fired on behalf of a client session that has access to the terminal to fetch information or modify its state.
In the Design Tool, the Client Connected event is associated with a login.
It will not fire if a disconnect has been performed without executing a logout.
The Client Disconnected event is fired when a client disconnects, but before Host Integrator attempts to reset the session to the home entity.
Possible uses:
This event allows custom cleanup of the terminal session. For example, if you implement a pseudo-rollback of a failed procedure call, the event would use the state cache containing the audit trail of changes made by the client, visit the entities where the changes were made, and revert all attributes and fields to their prior values.
Notes:
This is the last event fired with access to the terminal and the client state cache. The subsequent Client Session Destroyed event does not have access to the terminal.
After the event completes, Host Integrator always attempts to reset the session to the model's home entity.
The Error Reported event fires whenever an initial error is reported in the Session Server and there is no event handler in progress. The parameters provide information about which error was reported.
Possible uses:
This event handler can obtain information about the terminal state. In combination with the client state cache, the event handler can save information for auditing or debugging purposes. In the Design Tool, this event is unnecessary since the terminal window provides this feedback.
Notes:
If another event handler is in progress, this event does not fire, allowing an error to be returned for processing to that event handler.
If another error is reported subsequent to the reported error but prior to returning results to the client, this event does not fire. In other words, for a given error stack, at most only the initial error report triggers this event.
The Execute Login event is invoked when a host session requires a host login process.
Possible uses:
Notes:
By default, the Session Server invokes the login sequence once per host session. Another event handler (Client Connected or Client Disconnected, for example) might call it again as part of recovering an otherwise dead session.
In a dedicated session, the login sequence is performed after the client session has been created. In a session pool, Host Integrator calls the login event handler in the absence of a client session. Only the host session is created. This is an extension of the session pool behavior used in previous versions of the product.
The default callback executes the login command list defined in the model, if any.
The Execute Logout event is invoked when a host session requires a host logout process.
Possible uses:
This event allows you to handle conditional logic during a logout process. For example, you can detect a session that is stalled on a particular terminal screen and then enter special key sequences to "recover" the session and log out normally.
Notes:
By default, the logout sequence is invoked once per host session. Another event handler (Client Connected or Client Disconnected, for example) might call it again as part of recovering an otherwise dead session.
On the Session Server, Host Integrator always calls the logout sequence after a client session has been destroyed, but before the host session is destroyed.
The default callback executes the logout command list defined in the model, if any.
The Format Error event is called after all other processing for a client request is complete and Host Integrator is about to report an error. This event can alter the contents of an error report to better meet the requirements of the client application.
Possible uses:
This event can alter the contents of the error stack reported. For example, this could be done by having a prior event handler stash a meaningful error in the client state hash table and then by using this event to remove the other errors and replace them with the more specific message.
Notes:
This event can add new user-defined messages and/or remove one or more messages from the existing stack. The event is not permitted to alter the contents of any given message. Such a case requires that the message be removed and then replaced with a new message.
Callbacks are restricted when using this event.
If the event removes all messages, Host Integrator restores the reported error to the original error stack that would have been returned to the client.
The alterations of the error stack are not recorded in the Host Integrator log by default. If the event handler requires that the new messages be in the log, you must invoke the event handler logging interface and directly place the message in the log.
Host Integrator runtime error numbers (error codes), can be referenced in this event.
Upon returning from this event, the connector used by the client to connect to Host Integrator will often append an additional error message onto the stack. This error message provides information about which API method was invoked.
The Move Cursor event is invoked if the cursor needs to be moved to a defined location and there is no move cursor override on the current entity.
Possible uses:
See the Move Cursor event for entities.
Notes:
See the Move Cursor event for entities.
This event is invoked if the cursor needs to be moved forward and there is no tab override on the current entity.
Possible uses:
This event can be used for special case logic in cursor movement. For example, in some cases a character mode host moves the cursor differently depending on the data transmitted. In these cases, the model-based method of a static set of tab stops may not be adequate to capture the logic of cursor movements.
Notes:
This event is applicable only to VT and HP models. It never fires for 3270 or 5250 models. This event is invoked by the model when there is a simple request to tab (usually via the internal tab/update algorithm used to write data to the terminal) or when there is a specific cursor location requested, but there is no move cursor override defined.
If the current terminal screen is an entity and there are tab stops defined, the list is available from the callback interface.
If the event returns with the cursor unchanged, Host Integrator assumes that the cursor cannot be moved any more in that direction. If the reverse direction is defined and has not been tried, Host Integrator tries to reverse direction. Otherwise, Host Integrator expects the event handler to move the cursor to the next position on the screen.
This event can be invoked iteratively on a single screen instance as a way to write data or move the cursor to a defined location.
The Move Cursor Backward event is invoked if the cursor needs to be moved backward and there is no tab override on the current entity.
Possible uses:
Uses for this event are parallel to those described for Move Cursor Forward.
Notes:
See Move Cursor Forward.
The Process String event is fired when a client invokes the processString API method.
Possible uses:
Notes:
You can test a process string event handler using Web Builder. On the Procedures and Model features panel of the project, select Process String Event Handler under Model Features. The resulting project will have an option to allow input for the event handler and return a result.
There is no restriction on the semantic meaning of the string passed to Host Integrator. The custom event handler is solely responsible for interpreting the input and deriving results.
If this event is not implemented, the processString API returns an error. There is no default processing in Host Integrator.
The Unrecognized Screen event is fired at specific times when an entity is expected but none is found.
Possible uses:
Notes:
This event fires only under the following circumstances:
| Case | Description | |
| 1. | An operation times out at an unknown location while Host Integrator is executing an operation that does not have an event handler attached, or is waiting for an entity arrival after an event handler has returned control. | |
| 2. | The login sequence times out at an unknown location. | |
| 3. | A remote command is issued (from a client or an event handler) that requires a current entity, but none is found. Example requests include setting the current entity, executing a procedure or operation, reading or writing data to or from attributes or recordset fields, or wait for cursor at attribute. | |
| 4. | A host session is trying to reset to the home entity and/or log out of the host after client disconnect and cannot begin navigation because the current location is undefined. | |
| 5. | The user selects a destination in the Navigator when the current location is undefined. |
Timeouts and Unrecognized Screen Events
If an operation times out at an unknown location while its event handler is in progress as described in case 1 above, the existing event handler receives the error notification and should take corrective action. The Unrecognized Screen event is not invoked: by definition, the event is still executing.
If a login event handler times out as described in case 2, this is a simple error. The Unrecognized Screen event is not invoked. Distinct from the login event handler, the login sequence consists of connecting to the host, executing the login script/event, and recognizing the current location. This sequence is governed by the host connection timeout in model properties. If, however, this timer expires and there is no intervening error (such as an event handler timeout), then the Unrecognized Screen event is invoked.
Once a handler timeout has been reported, the abort interval is already ticking (see timeout processing). Firing additional events during this interval is not permitted. The original event has already failed and Host Integrator is in the process of getting the original event to halt.
It is highly likely, that the next action from the client will result in the situation described in case 3 (a new request that requires an entity) or case 4 (client disconnect). Even if the operation or login event does not recover, the model will still attempt a recovery at some point in the future. If knowledge of the model state at the point of failure is important to recovery, this information should be stored by the operation or login event prior to returning.
In all cases, failure to recover to a known location results in an error. Even
if the session is restored to a known location, some requests still fail if
the location is not the one expected.
|