Event Reference for Supported Object Types

Click on an event handler object type to see information about the events that are defined for that type.

• Java: Review the API documentation for model events for more information.

• .NET: Review the ModelEventHandler documentation for more information.

Model

Life Cycle

Entity

Attribute

Operation

Recordset

Recordset Field

Procedure

Model Event Handlers

The events available for creating model event handlers are listed below.

• Client Connected/ Disconnected

• Error Reported

• Execute Login and Logout

• Format Error

• Move Cursor

• Process String

• Unrecognized Screen

Client Connected

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.

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.

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.

Client Disconnected

The Client Disconnected event is fired when a client disconnects, but before Host Integrator attempts to reset the session to the home entity.

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.

After the event completes, Host Integrator always attempts to reset the session to the model's home entity.

Error Reported

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.

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.

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.

Execute Login and Logout

The Execute Login event is invoked when a host session requires a host login process.

• Include conditional logic in login process—Under some circumstances, hosts can alter their login sequence (such as after a forcible disconnect).

• Recover from login errors—In some cases, the first time Host Integrator becomes aware of an expired account or password is during login. One branch of conditional logic could obtain newer credentials for the userid and password model variables automatically, and then update the model variable list configuration.

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.

Execute Logout

The Execute Logout event is invoked when a host session requires a host logout process.

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.

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.

Format Error

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.

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.

See the ScriptHostSession API topic regarding restrictions 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.

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.

Move Cursor

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.

See the Move Cursor event for entities.

• Move Cursor Forward

This event is invoked if the cursor needs to be moved forward and there is no tab override on the current entity.

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.

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.

• Move Cursor Backward

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.

Uses for this event are parallel to those described for Move Cursor Forward.

Process String

The Process String event is fired when a client invokes the processString API method.

• Process a custom XML document — Passing an XML document to an event handler enables complete encapsulation of processing an XML document inside the model. If the processing accesses entities directly (instead of through procedures), the local event handler callback interface is more efficient than a client application making the same calls.

• Process custom SQL statements — Host Integrator supports a subset of ANSI SQL-92. Keywords such as JOIN are recognized but not supported. You can extend this support by taking an SQL string, removing the portions not supported by Host Integrator, passing the remaining SQL to the model for processing, and then modifying the results based on the custom extensions from the original client string.

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.

Unrecognized Screen

The Unrecognized Screen event is fired at specific times when an entity is expected but none is found.

• Recovery — The event handler may restore the terminal to a known location by sending input directly to the terminal.
• Capture information for debugging — The event handler has the ability to read data from the terminal. For example, capturing a screen dump to a file may assist in diagnosing unexpected behavior by the model.

This event fires only under the following circumstances:

• 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.
• The login sequence times out at an unknown location.
• 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.
• 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.
• 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.

Life Cycle Event Handlers

• Model Loaded/Unloaded

• Host Session Created/Destroyed

• Authenticate User

• Client Session Created/Destroyed

Model Loaded

The Model Loaded event is fired whenever Host Integrator loads a new model, or an updated version of an existing model. There is one exception: when the Design Tool loads a model already loaded by another instance of the Design Tool, no events are fired for this model, including the Model Loaded event.

• Create shared resources — If interaction with an external system is required, a pool of shared connections can be created and stored in the state hash table for the model.
• Customize model environment - This could involve anything from altering Host Integrator's model variable list configuration to establishing a local output file for auditing or debugging purposes.

Any exception returned from this event causes the model to fail to load. In the Design Tool, these errors are reported and the model remains loaded. However, any model that fails to load on the Session Server is unavailable for client requests. If this is not a desired outcome, then the event handler should catch all "throwable" exceptions, log its own message, and then discard the exception.

Model Unloaded

The Model Unloaded event is fired when a model is unloaded by Host Integrator. This occurs for the existing model when the user exits the Design Tool or when the user loads a model. On the Session Server, this occurs when a new version of a model is activated or the server process shuts down.

This event can be used to clean up any shared resources created during the Model Loaded event.

Host Session Created

The Host Session Created event is fired each time a host session is created. In the Design Tool, this happens each time a model is loaded and when the user invokes certain tests in the Connection Events Test dialog box. On the Session Server, this occurs when a session pool is created or augmented and when a dedicated session is created in response to a client request.

This event can be used to initialize state or other resources that will live for the lifetime of the host session.

If this event returns any exception, the Host Integrator Session Server fails to create the host session and it is not made available for client access. In the Design Tool, errors are reported, but the host session creation succeeds.

Host Session Destroyed

The Host Session Destroyed event is fired each time a host session is destroyed. In the Design Tool, this happens each time a model is unloaded and when the user invokes certain tests in the Connection Events Test dialog box. On the Session Server, this occurs when a session pool is destroyed or decreased in size and after a dedicated session is released by its client.

This event can be used to clean up any resources that were intended to live for the duration of the host session.

Authenticate User

The Authenticate User event is fired when a client connects to a server host session to permit authentication or authorization beyond that provided by Host Integrator security. In the Design Tool, this event is fired when a model is loaded and when the user invokes certain tests in the Connection Events Test dialog box.

The normal Host Integrator security infrastructure is administered independently of this event.

• Extend authentication — Set up the extended authorization to access a proprietary security system, use connection parameters beyond user id and password, or both.
• Add authorization — For cases when user authentication to the larger Host Integrator system does not necessarily equate to authorization to access the model in question.
• Prepare host session — This event can modify the values of the model variables to match the connection parameters or otherwise meet application requirements.

Client Session Created

The Client Session Created event is fired after a client has been granted access to a host session, but before the client is allowed to make any requests.

• Initialize state cache — This is the first event for a client session that has access to the client hash map. Populating the cache with needed data is the primary use of this event.
• Define authorization tokens — After initializing the state cache, if you are implementing field-level security or other fine-grained authorization strategies, you can use this event to create the requisite tokens and store them in the cache.

As with other life cycle creation events, any exception returned from this event results in the Host Integrator Server failing to create the client session. The prospective client receives the error and is denied access to a host session. In the Design Tool, unhandled exceptions are reported but the client session is created anyway.

Client Session Destroyed

The Client Session Destroyed event is fired when the client has disconnected and all other client and terminal cleanup processing has been completed.

This event can be used to clean up any resources that were intended to live for the duration of the client session. The client cache will be made available for garbage collection after this event, so only orderly releases of external resources need be done with this event.

This event is guaranteed to be fired after all other client session cleanup has been completed.

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.

• 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.

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.

• 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.

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 Event

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.

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.

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.

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.

Attribute Events

The two events available for creating event handlers associated with attributes, Read Attribute and Write Attribute, are described below.

Read Attribute

This event is used to post-process data read from the terminal.

• Reformat data — Examples include changing the data from internal codes to human-readable form, changing the format of a date from one locale to another, adding or removing characters to modify the meaning (such as a negative sign for a number less than zero).
• Create composite data — Represent data from disparate regions of the screen as a single unit.
• Enforce field-level security — Authorization for access to the field data can be based on the user credentials.

This event is invoked whenever a request is received to read attribute data. This request might be from a client API, an event handler callback, an operation, or a procedure.

The default result is "scraped" from the terminal, passed to the model-defined post-processing for white-space and symbol removal, and then sent to the event handler.

The value returned from the event handler is treated as the value of the attribute for the current request. Changing the current entity during this event is not recommended, as there may be additional actions pending that depend on the current entity remaining the same. Otherwise, there are no predefined conditions that result in an error.

Write Attribute

This event is used to pre-process the data to be written to the terminal or to customize the process of writing the data.

• Reformat data — Examples include changing the data from human-readable form to internal codes, changing the format of a date from the external locale to the host format, adding or removing characters or sending special terminal keys to correctly indicate meaning (removing a negative sign for a number less than zero, sending the raw data to the terminal, and pressing a special terminal key to communicate the negative value).
• Split composite data — In contrast to the case of a Read Attribute event, a client may send data in a composite form, and the write processing requires special logic to split the data into constituent parts and transmit each to the terminal separately. For example, some calendar dates may need to be processed this way.
• Enforce field-level security — Authorization to update the field data can be based on the user credentials.
• Handle dynamic host applications — Some applications change the types of fields based on data inputs or user authorization. An event handler using Write Attribute can check for protected status and either omit the actual transmission of data or throw an informative exception.
• Create audit trails of changes — All changes to an attribute can be logged directly to an external system. Alternatively, the changes can be cached for later recording or for use in a pseudo-rollback of a failed procedure. See the Model event Client Disconnected.

This event is invoked whenever a request is received to write attribute data. This request might be from a client API call, event handler callback, an operation, or a procedure.

The input data is passed directly to the event handler with no pre-processing.

Examples of actions the event handler might take include:

• Modify the value and call the default
• Customize setting the terminal state with custom key sequences
• Make decisions about whether or not to attempt writing data

Host Integrator accepts whatever actions specified by the event handler, including omitting any terminal updates. Changing the current entity during this event is not recommended, as there may be additional actions pending that depend on the current entity remaining the same. Otherwise, there are no predefined conditions that result in an error.

The default callback performs the model-defined pre-processing for pre-pending, appending, and white-space padding, and then executes any pre-write operation, verifies the length of the data and state of the terminal, positions the cursor as needed, transmits the data to the terminal, and executes any post-write operation.

Operation Events

The event available for creating event handlers associated with operations is described below.

Execute Operation

The Execute Operation event is fired whenever an operation execution is requested.

• Conditional logic—Host Integrator can internally handle alternative outcomes of operations. In order to perform conditional navigation, entities must be defined at each conditional branch point. As an alternative, an event handler could perform midstream adjustments in the list of commands to issue. This could decrease the number of entities required to navigate a host application.

• Terminal validation — In some cases, data can be entered from different sources that may be difficult to validate as a whole. As the first step in an operation, an event handler can validate the state of the terminal to detect potential errors before the underlying data causes corruption in the host data source.

• Automated error recovery — For known error situations, an event handler can resolve the error cases in order to reach the desired destination. For example, some data combinations could cause a keyboard lock that can be resolved by simply pressing a terminal key.
• Custom error reporting — Given a set of possible error conditions, an event handler can generate a specific error message that may be more helpful to a client application than automatically generated error messages.
• Custom synchronization — Host Integrator provides a variety of means for deciding when a host has finished updating a terminal screen. However, there are occasions when the synchronization really involves branching logic based on inputs. The event handler is the only mechanism that supports this form of terminal-model validation.

The Execute Operation event is required to leave the terminal on a screen recognized as a valid outcome of the operation. Upon return, the operation iteratively checks for arrival at a valid destination a valid location is found, an invalid location is found, or the operation times out.

The default callback for an operation executes the command list, destination processing, and post-condition logic as defined by the model.

The Java WaitForArrival callback or the .NET WaitForArrival method (available in a Windows help file) processes primary, alternate, and error destinations, waiting for one of them to be found. This continues until the event times out, the callback-specified wait interval expires, or a destination is recognized.

Host Integrator does not process terminal input while the event handler is executing logic. The host data is processed into the terminal only during callbacks to Host Integrator. At the points where the operation needs to wait for the host to "catch up," inserting wait events or other callbacks is necessary.

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.

• Variable length records — A host application may vary the length of the records depending on content. This event allows for arbitrary record sizes as long as they are within the bounds of the recordset and rectangular in shape.

• Variable spaced records — A host application may group records together so that the records are not evenly spaced. This event allows for arbitrary record locations as long as they are within the bounds of the recordset.

• Partial records — The host may split records across columns or across screens. This event allows for these types of records to be identified and combined.

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.

• Variable field location and length — The location and length of fields may differ between records. This event allows for field locations and lengths to be specified on a record-by-record basis. The fields, however, must still be defined in linear fashion relative to the record.

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.

• Scroll termination — The host may indicate the first or last page of the recordset in a way that cannot be handled by the built-in scroll termination criteria.
• This event is fired once for scroll-up termination and once for scroll-down termination on a per screen basis. The event is fired after the records have been read from the screen. If this event returns True, the recordset is considered terminated in the direction queried.
• 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.
• Host Integrator will not fire isTerminated() if the fetch terminates with either of the following:
• Scroll operation results in the same recordset data.
• Scroll operation results in entity change.

In both cases, the corresponding option must be selected in the RecordSet Termination Options dialog box and the action must occur during the fetch.

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.

• Excluded records — Records marked as excluded are hidden from client applications. Typically, this is used for records that are repeated from a previous screen or do not contain data. Filtered records are assigned an index, but client applications cannot access them.
• Designate insertion locations — Records marked as blank can be used as insertion locations. Blank records are visible to client applications unless they are also marked as excluded.

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.

• Custom filter expressions — Many of the recordset API methods accept a filter expression. When this event is attached to a recordset, Host Integrator uses it to evaluate the filter expressions instead of using the built-in evaluation mechanism.

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.

• Customize current host record identification — A host application may identify the current record with an approach not supported by built-in Host Integrator mechanisms.

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.

• Specify the order in which fields are written — A host application may require the fields to be written in particular order.
• Customize the cursor movement between fields — A host application may require customized cursor movement in order to move between fields in a synchronized fashion.
• Customize before and after update actions — A host application may require special actions before or after updating a record.
• Validate field values — A set of fields may require validation as a whole, instead of individually validating at the field write event level. Alternatively, there may be a need to validate each field value before any data is actually written to the terminal screen.

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:

• If a tab definition exists for the current context, then the internal tab/update algorithm is used to input the data.

• Otherwise, each field object is invoked in an order determined by Host Integrator; each field ensures the cursor is in the first cell of its terminal location and then transmits the applicable data to the terminal.

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.

• Identify the correct insertion location — A host application may require special logic for identifying the correct insertion location.
• Specify the order in which fields are written — A host application may require the fields to be written in a particular order.
• Customize cursor movement between fields — A host application may require customized cursor movement in order to move between fields in a synchronized fashion.
• Customize before and after insert actions — A host application may require special actions before or after inserting a record.
• Validate the field values — A set of fields may require validation as a whole instead of individually at the field write event level. Alternatively, field value may need to be validated before any data is actually written to the terminal screen.

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:

• If a tab definition exists for the current context, then the internal tab/update algorithm is used to input the data.

• Otherwise, each field object is invoked in an order determined by Host Integrator; each field ensures the cursor is in the first cell of its terminal location and then transmits the applicable data to the terminal.

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.

Recordset Field Events

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

Read Field

The Read Field event is fired during the course of reading the current screen of the recordset. It reads the contents of a field.

• Reformat data — Examples include changing the data from internal codes to human-readable form, changing the format of a date from one locale to another, adding or removing characters to modify the meaning (such as a negative sign for a number less than zero).
• Create composite data — Represent data from disparate regions of the screen as a single unit.
• Enforce field-level security — Authorize access to the field data based on the user credentials.

This event is invoked for each instance of a field in a recordset. It is fired after the Parse Screen and Parse Record events.

The default result is "scraped" from the terminal, passed to the model-defined post-processing for white-space and symbol removal, and then sent to the event handler.

The value returned from the event handler is treated as the value of the field. 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. Otherwise, there are no pre-defined conditions that result in an error.

See the ScriptHostSession API topic regarding restrictions on changing terminal state using this event.

Write Field

The Write Field event is fired whenever a request is received to write data to a field.

• Reformat data — Examples include changing the data from human-readable form to internal codes, changing the format of a date from the external locale to the host format, adding or removing characters or sending special terminal keys to correctly indicate meaning (removing a negative sign for a number less than zero, sending the raw data to the terminal, or pressing a special terminal key to communicate the negative value).
• Split composite data — In contrast to the Read Field event, a client may send data in composite form, and the write processing requires special logic to split the data into constituent parts and transmit each to the terminal separately. Some calendar dates need to be processed this way.
• Enforce field-level security**—Authorization to update field data can be based on the user credentials.
• Handle dynamic host applications — Some applications change the types of fields based on data inputs or user authorization. An event handler using Write Field can check for protected status and either omit the actual transmission of data or throw an informative exception.
• Create audit trails of changes — All changes to an attribute can be logged directly to an external system. Alternatively, the changes can be cached for later recording or for use in pseudo-transactional semantics (see [Client Disconnected] (need link) model event).

This event is fired whenever data needs to be written to a field. Typically, this occurs inside an update or insert record request, but can also occur as result of a command such as TransmitToRecordsetField.

The input data is passed to the event handler with no pre-processing.

Examples of event handler actions include:

• Modify the value and call the default
• Customize setting the terminal state with custom key sequences
• Decide whether or not to attempt writing data

Host Integrator accepts whatever actions are taken by the event handler as intentional, including omitting any terminal updates. Changing the current entity during this event is not recommended, as there may be additional actions pending that depend on the current entity remaining the same. Otherwise, there are no predefined conditions that result in an error.

The default callback performs the model-defined pre-processing for pre-pending, appending, and white-space padding. It then executes any pre-write operation, verifies the length of the data and state of the terminal, positions the cursor as needed, transmits the data to the terminal, and executes any post-write operation.

Procedure Events

The event available for creating procedure event handlers is described below.

Execute Procedure

The Execute Procedure event fires whenever a procedure execution is requested. This request can be from processing SQL input, a direct invocation of a procedure by a client or script, or a portion of a compound procedure.

• Custom procedure — You can implement a procedure using other procedures, low-level navigation, recordset manipulation, or external data sources.

• Validate inputs or filters — Host Integrator has limited support for validation, but an event handler can extend this capability.

• Transform inputs or filters — The internal host codes may differ from the way data is passed in from a client or script.

• Alter the results — Edit the result set by adding or removing records, transforming from internal to external representations of data, or storing the results in an external system (database) in lieu of returning them to the client.

The default callback executes the entire model-defined procedure with provided filters or inputs, returning any results to the event handler for post-processing. For select, update and delete procedures there can be only one set of input parameters. For insert procedures, there may be one or more sets of input parameters.

Compound procedures cannot have events attached to them.