Recordset Field Events

The events available for creating event handlers associated with recordset fields are described below. Review the API documentation for recordset field events for more information.

Read Field

Write Field

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.

Possible uses:

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.

Notes:

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.

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

Write Field

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

Possible uses:

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 model event) .

Notes:

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.