Recordset Events

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

Parse Screen

Parse Record

Is Terminated

Get Record Type

Apply Filter

Get Current Host Record

Update Record

Insert Record

Parse Screen

The Parse Screen event is fired during the reading of the current screen of the attached recordset. It determines the location and size of records within the recordset.

Possible uses:

Notes:

This is event fired on a screen by screen basis when the host session reads or rereads the contents of the current screen. Record locations must be rectangular and relative to the recordset.

Along with a location, each record can be designated as whole or partial. Upon returning from the event, Host Integrator automatically combines adjacent partial records into whole records. If the last record on the screen is marked as partial, Host Integrator retains it until the next screen is parsed.

The order in which the record locations are returned from this event dictates the order in which indices are assigned to the records. This is also the order that a client application sees the records when fetched.

Parse Record

The Parse Record event is fired during the reading of the current screen of the attached recordset. It determines the location and size of fields within a record.

Possible uses:

Notes:

This event is fired for each whole record resulting from the Parse Screen event. It is not fired for partial records until they are recombined. Field locations must be linear and relative to the record.

Changing the current entity during this event is not supported and causes the event to fail. Also, attempting any action on the recordset from which the event fired results in an error.

Callbacks that change terminal state are restricted when using this event.

Is Terminated

The Is Terminated event is fired during the reading of the current screen of the attached recordset. It determines if the current screen is the first or last screen of the recordset.

Possible use:

Notes:

Get Record Type

The Get Record Type event is fired during the reading of the current screen of the attached recordset. The results of this event affect which records are visible to client applications and which records are eligible for insert. Records are categorized as normal, blank, or excluded and blank. This event fires after a record and all of its fields have been read from the screen.

Possible uses:

Notes:

This event is fired after the records have been read from the screen. Host Integrator provides a default categorization based on the model definition.

Changing the current entity during this event is not supported and causes the event to fail. Also, attempting any action on the recordset from which the event fired results in an error.

Callbacks that change terminal state are restricted when using this event.

Apply Filter

The Apply Filter event is fired to apply a custom filter expression to a record.

Possible uses:

Notes:

When this event is attached to a recordset, it replaces the built-in evaluation mechanism. Host Integrator does not attempt to parse or evaluate filter expressions from the client. Instead, any client filter expressions are handed to this event for evaluation against a record. This allows the event to define its own filter expression syntax for clients to use. This event only fires when the client uses non-empty filter expressions.

Callbacks that change terminal state are restricted when using this event.

Get Current Host Record

The Get Current Host Record event is fired when the host session needs to know the host's current record.

Possible uses:

Notes:

The host's current record is based on the host application current record status, while the recordset's current record is based on the client application's current record status. For performance reasons, these are not kept in sync unless the client application makes a request to update, insert or select a record. When one of these requests is made, the Get Current Host Record event is called to determine the current host record. If it does not match the recordset's current record, Host Integrator uses line up and line down operations to change the host's current record to match. The client request fails if they cannot be successfully synchronized.

The client application can also explicitly ask to set the recordset's current record to the host's current record. In this circumstance, the event fires to obtain the host's current record.

When this event is not attached to a recordset, the built-in evaluation mechanism is used.

Changing the current entity during this event is not supported and causes the event to fail. Also, attempting any action on the recordset from which the event fired results in an error.

Callbacks that change terminal state are restricted when using this event.

Update Record

The Update Record event is fired whenever a client application or a procedure requests to update a record.

Possible uses:

Notes:

The Update Record event encompasses executing the before update operation, writing the fields, and executing the after update operation. Before the event fires, the record to be updated is made the recordset's current record and the host's current record.

Upon invocation, this event is responsible for orchestrating the record update. This may include performing before and after update actions, writing the fields, and moving the cursor between fields. The actual writing of the data can be done directly to the terminal, but each field should be called in turn to perform its write. Writing to the terminal directly would bypass the Write Field event for the fields.

The default callback executes the before update operation, writes the fields, and executes the after update operation. The fields are written in one of two ways:

Host Integrator accepts whatever decisions are made by the event handler. This includes 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 pending that require that the current entity remain the same. Otherwise, there are no predefined conditions that result in an error.

Insert Record

The Insert Record event is fired whenever a client application or procedure issues an insert record request.

Possible uses:

Notes:

The Insert Record event encompasses searching for an insertion location, executing the before insert operation, writing the fields, and executing the after insert operation. When the event is fired, the event must first find the correct insertion location and make it the current record. This can either be done via a callback to find the default location, or done by simply making the correct location the current record. Either way, the insertion location must be the current record before any fields are written.

Once the insertion location is made the current record, the event is responsible for writing the fields to the record. This may include performing before and after insert actions, writing the fields, and moving the cursor between fields. The actual writing of the data can be done directly to the terminal, but each field should be called in turn to perform its write. Writing to the terminal directly would bypass the Write Field event for the fields.

The default callback locates the insertion location, executes the before insert operation, writes the fields, and executes the after insert operation. The fields are written in one of two ways:

As in the Write Field event case, Host Integrator accepts whatever decisions are made by the event handler. This includes 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 pending that require that the current entity remain the same. Otherwise, there are no predefined conditions that result in an error.

Related Topics
Bullet ScriptHostSession limitations
Bullet Event handler guidelines
Bullet Event handler API overview