Class RecordSetEventHandler

Abstract base class for a recordset event handler.

Inheritance

object

MarshalByRefObject

RecordSetEventHandler

Implements

IEventHandler

Inherited Members

MarshalByRefObject.MemberwiseClone(bool)

MarshalByRefObject.GetLifetimeService()

MarshalByRefObject.CreateObjRef(Type)

object.ToString()

object.Equals(object)

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

Namespace: Attachmate.Verastream.HostIntegrator.ScriptAPI

Assembly: Attachmate.Verastream.HostIntegrator.ScriptAPI.dll

Syntax

public abstract class RecordSetEventHandler : MarshalByRefObject, IEventHandler

Remarks

Abstract base class for a recordset event handler. All classes that extend this class appear as recordset handlers in the VHI design tool.
No recordset events will fire until a client makes a recordset request such as fetchRecords(). Once such a request is received, VHI will read the contents of the recordset on a screen by screen basis until enough data has been read to fulfill the client request.
The first step when reading a recordset screen is to determine its location and size. This step cannot be overridden by an event handler, but a recordset can be defined in the model to be the entire screen if need be.
The second step is to determine the location and size of each record. If the ParseScreen method is defined, VHI will defer to this method for determining the record locations and sizes.
The third step is to determine the location and size of each field within each record. If the ParseRecord method is defined, VHI will defer to this method for determining the field locations and sizes. The method will be called for each record found on the screen.
The fourth step is to read the contents of each field in each record. If a ReadField(IReadFieldEvent) method is defined, VHI will defer to this method for reading each field in the recordset. The method will be called for each field that needs to be read. This provides the opportunity to do any needed data translation.
The fifth step is to determine if the current screen is the first or last of the recordset. If an IsTerminated method is defined, VHI will defer to this method for making the first and last screen determination.
The sixth step is to designate which records should be visible to the client application and which records are eligible for record insertion. If a GetRecordType method is defined, VHI will defer to this method for categorizing the records. Typically blank and repeated records are excluded at this stage so that they will not be visible to client applications, regardless of any client provided filter expression.
As part of a recordset fetch or update API call, the client application can provide a filter expression that constrains the records retrieved or updated. The evaluation of this filter expression can be overridden by defining an ApplyFilter method. If this method is defined, VHI will defer evaluation of all client filter expressions to this method.

Methods

ApplyFilter(IApplyFilterEvent)

Called to apply a client provided filter expression to a record.

Declaration

public virtual bool ApplyFilter(IApplyFilterEvent vsEvent)

Parameters

Type	Name	Description
IApplyFilterEvent	vsEvent	The event instance.

Returns

Type	Description
bool	True if the record matches the filter, otherwise false.

Remarks

Called to apply a client provided filter expression to a record. This event will only be called if a client provides a non-empty filter expression in its recordset request.
When this event is defined, VHI will bypass its own filter expression processing and defer to this event.
See class summary for details about when this event is fired in relation to other recordset events.
NOTE: IScriptHostSession methods that change the terminal screen cannot be called within this event.

Exceptions

Type	Condition
ApptrieveException	Any exception will abort the recordset activity.

GetCurrentHostRecord(IGetCurrentHostRecordEvent)

Called to get the current host record index.

Declaration

public virtual int GetCurrentHostRecord(IGetCurrentHostRecordEvent vsEvent)

Parameters

Type	Name	Description
IGetCurrentHostRecordEvent	vsEvent	The event instance.

Returns

Type	Description
int	The one-based current host record index on the screen.

Remarks

Called to get the current host record index. The current host record is the record that the host identifies as current via some indicator on screen (cursor position, reverse video, etc). This is called before a record is selected or updated and in response to a client request to make the current recordset index the same as the current host record index.
NOTE: IScriptHostSession methods that change the terminal screen cannot be called within this event.

Exceptions

Type	Condition
ApptrieveException	Any exception will abort the recordset activity.

GetRecordType(IGetRecordTypeEvent)

Called to identify the type of record.

Declaration

public virtual RecordType GetRecordType(IGetRecordTypeEvent vsEvent)

Parameters

Type	Name	Description
IGetRecordTypeEvent	vsEvent	The event instance.

Returns

Type	Description
RecordType	A constant from RecordType.

Remarks

Called to identify the type of record. The record type affects which records are visible to the client application and which records are considered valid insertion locations. See class summary for details about when this event is fired in relation to other recordset events.
NOTE: IScriptHostSession methods that change the terminal screen cannot be called within this event.

Exceptions

Type	Condition
ApptrieveException	Any exception will abort the recordset activity.

InitializeLifetimeService()

Tell the .NET Framework remoting system that instances of this type have an infinite lifetime.

Declaration

public override object InitializeLifetimeService()

Returns

Type	Description
object	A null value.

Overrides

MarshalByRefObject.InitializeLifetimeService()

InsertRecord(IInsertRecordEvent)

Called to insert a record into the recordset.

Declaration

public virtual void InsertRecord(IInsertRecordEvent vsEvent)

Parameters

Type	Name	Description
IInsertRecordEvent	vsEvent	The event instance.

Remarks

Called to insert a record into the recordset. This event encompasses finding the insert location, executing the before insert operation writing the fields and executing the after insert operation.

Exceptions

Type	Condition
ApptrieveException	Any exception will abort the recordset activity.

IsTerminated(IIsTerminatedEvent)

Called to check if this is the last screen in a scroll direction.

Declaration

public virtual bool IsTerminated(IIsTerminatedEvent vsEvent)

Parameters

Type	Name	Description
IIsTerminatedEvent	vsEvent	The event instance.

Returns

Type	Description
bool	True if this is the last screen in the direction specified by ScrollDirection.

Remarks

This event will be fired twice per screen in the recordset: once for page up termination and once for page down termination.
See class summary for details about when this event is fired in relation to other recordset events.

NOTE: IScriptHostSession methods that change the terminal screen cannot be called within this event.

Exceptions

Type	Condition
ApptrieveException	Any exception will abort the recordset activity.

ParseRecord(IParseRecordEvent)

Called to obtain the field location and sizes for the specified record.

Declaration

public virtual IDictionary<string, IFieldLocation> ParseRecord(IParseRecordEvent vsEvent)

Parameters

Type	Name	Description
IParseRecordEvent	vsEvent	The event instance.

Returns

Type	Description
IDictionary<string, IFieldLocation>	A list of objects that implement IFieldLocation.

Remarks

Called to obtain the field location and sizes for the specified record. This event will fire for each whole and combined record. The default field location will be used for any fields not returned. See class summary for details about when this event is fired in relation to other recordset events.
NOTE: IScriptHostSession methods that change the terminal screen cannot be called within this event.

Exceptions

Type	Condition
ApptrieveException	Any exception will abort the recordset activity.

ParseScreen(IParseScreenEvent)

Called to obtain the location and size of records on the current screen.

Declaration

public virtual IList<IRecordLocation> ParseScreen(IParseScreenEvent vsEvent)

Parameters

Type	Name	Description
IParseScreenEvent	vsEvent	The event instance.

Returns

Type	Description
IList<IRecordLocation>	A list of objects that implement IRecordLocation.

Remarks

Called to obtain the location and size of records on the current screen. Records will only be created from the record locations returned by this method. Indicies will be assigned to the records in the order that the record locations are returned.
Any record marked as partial will be combined by VHI with adjacent partial records upon return from this event. If the last record is marked as partial it will be combined with the first record of the next screen if partial.
See class summary for details about when this event is fired in relation to other recordset events.
NOTE: IScriptHostSession methods that change the terminal screen cannot be called within this event.

Exceptions

Type	Condition
ApptrieveException	Any exception will abort the recordset activity.

UpdateRecord(IUpdateRecordEvent)

Called to update the contents of the current record.

Declaration

public virtual void UpdateRecord(IUpdateRecordEvent vsEvent)

Parameters

Type	Name	Description
IUpdateRecordEvent	vsEvent	The event instance.

Remarks

Called to update the contents of the current record. This event encompasses executing the before update operation, writing the fields and executing the after insert operation.

Exceptions

Type	Condition
ApptrieveException	Any exception will abort the recordset activity.

Implements

IEventHandler