Entity Events

The events available for creating event handlers associated with entities are described below. Review the API documentation for entity events for more information.

Entity Arrival

Entity Departure

Move Cursor

Write Attributes

Entity Arrival

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

Possible uses:

Validate terminal state—The event handler can verify that the expected data is on the terminal screen, and can confirm that the host has not placed any error messages or locked the keyboard.
Preprocess the terminal screen—Fields hidden from the client application may require static data entry or conditional logic to cause the screen to initialize properly.
Automatic recovery—In the case that the entity represents an error condition, the event handler may automatically alter the terminal state to bypass the screen.

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:

Define an unknown screen—The screen can be defined as an extension of the last known entity for data processing purposes. For example, a recordset scroll may lead to a screen with no static content for use in identification.

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.

Callbacks are restricted when using this event.

Move Cursor

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

The MoveCursor or ShiftCursor command is issued by a command list.
The MoveCursor or ShiftCursor API method is invoked by a client or event handler.
Model commands that write data to attributes, such as TransmitToAttr, DefaultValue, WriteVarToAttr, and UpdateAttribute invoke this event if the cursor is not in the first terminal cell of its location. The same is true for corresponding commands that act on recordset fields.
The exception to the commands listed above is UpdateAttributes and UpdateRecordsetFields. These two commands have different behavior depending on the structure of the model:
- If tab forward and/or backward definitions exist on the entity or the model, an internal algorithm that iteratively checks the current location for applicable input data, writes any data that is found, and then tabs to the next tab stop used to write the cached inputs to the terminal screen in order.
- If there is no tab definition on the entity or the model, the iterative internal algorithm is bypassed (see information on the cursor tab for more details) in favor of issuing a TransmitToAttr command for each attribute with the input data as the argument. In this case, each attribute or field object that does not find the cursor in the correct location issues a MoveCursor command to move the cursor to the first terminal cell of its location.
Procedures in combination with client and event handler API invocations to write data to attributes or fields follow the same rules as UpdateAttributes and UpdateRecordsetFields commands.

Possible use:

The Move Cursor event would typically be defined when clients or operations are expected to request moving of the cursor to one or more absolute positions on the terminal screen represented by this entity.

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:

Invokes the internal algorithm built on model tab definitions to move to the desired tabstop
Uses the arrow keys to try to position the cursor

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:

Customize the order of update and/or terminal preparation—When one or more attributes need to be written to an entity in a character mode host, the cursor often must be moved in a particular manner. Additionally, terminal updates may be required in a specific order.
Validate inputs—In some cases, a set of attribute inputs requires validation as a whole instead of the more usual one-by-one basis. Alternatively, you may want to validate each entry before any data is actually written.

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:

If a tab definition exists for the current context, then the internal tab/update algorithm is used to input the data.
Otherwise, each attribute object is invoked in an order determined by Host Integrator; each attribute ensures the cursor is in the first cell of its terminal location and then transmits the applicable data to the terminal.