Entity Events

The events available for creating event handlers associated with entities are described below.

Entity Arrival

The Entity Arrival event is used to pre-process a terminal screen or define state information.

Possible uses:

Notes:

This event fires whenever a transition is made from an unknown location or another defined location to the attached entity. The event fires after all signature patterns are recognized and the entity validation has been passed.

Entity Arrival events and Entity Departure events for a given entity are disallowed while the Entity Arrival event for that entity is in progress. If the current entity changes during an Entity Arrival event, the Entity Departure event will not fire.

Entity Departure

The Entity Departure event is used to delay actual departure from an entity or modify model state information to reflect the departure.
Possible use:

Notes:

This event fires any time an entity changes from being recognized to being unrecognized. The Entity Departure event fires just before the rest of Host Integrator is informed of the entity departure. If the next location is unknown, the event handler can engage an entity override that forces the entity to remain current even though its signature is not found.

Once the override is engaged, the event fires again each time there is a terminal screen update if the entity signature is still not recognized. Depending on how the host updates the terminal screen, this may produce many iterations of this event. As soon as a different entity is found, the departure event is fired without the entity override. This state can be discovered by asking for the next entity: if the result is non-null, then an invocation of the entity override is ignored.

See the ScriptHostSession API topic regarding restrictions when using this event.

Move Cursor

The Move Cursor event is invoked only when there is a predefined location requested. For example:

Possible use:

Notes:

This event can be invoked only by models built for VT or HP terminals. With 3270 and 5250 terminals, Host Integrator simply moves the cursor to the desired position in the local terminal, while VT and HP terminals often have the cursor position dictated by the host.

If this event fails to move the cursor to the expected location, Host Integrator sets a runtime error on return.

The default callback does one of the following:

For an entity, move the cursor using tab overrides by mapping operations for forward tab, backward tab, or both. This remains unchanged by the presence of the event handler. The mapped operations for tab overrides can themselves have event handlers attached. Host Integrator detects when a tab operation has an event handler and applies the same rules as for model object tab overrides.

Write Attributes

The Write Attributes event is invoked whenever a client API call, an event handler API callback, or a procedure writes attributes to the terminal. This event is also invoked by an operation issuing an UpdateAttributes command.

Possible uses:

Notes:

Typically, this event is used to handle the portions of terminal update that involve the entire set, such as validation, cursor movement, and ordering. Although the actual writing of the data can be done directly to the terminal, it may more often be done by calling upon each attribute in turn to perform the update.

As in the case of the Write Attribute event, Host Integrator accepts what is dictated by the event handler, even omitting some or all of the data if desired. Changing the current entity during this event is not recommended, as there may be additional actions that depend on the current entity remaining the same. Otherwise, there are no predefined conditions that result in an error.

The default callback behaves in one of two ways:

Related Topics
Bullet Event handler API overview
Bullet Event handler guidelines