Class ModelEventHandler

Abstract base class for a model event handler.

Inheritance

object

MarshalByRefObject

ModelEventHandler

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 ModelEventHandler : MarshalByRefObject, IEventHandler

Remarks

Abstract base class for a model event handler. All classes that extend this class appear as model event handlers in the VHI design tool.

Methods

ClientConnected(IClientConnectedEvent)

Called when a client connects to the host session.

Declaration

public virtual void ClientConnected(IClientConnectedEvent vsEvent)

Parameters

Type	Name	Description
IClientConnectedEvent	vsEvent	The event instance.

Remarks

Called when a client connects to the host session. This event fires after the client session has been created but before the client can make any requests. The host application will be at the model's home entity at the time the event fires.

Exceptions

Type	Condition
ApptrieveException	If an exception is thrown from this event the VHI server will log the error and fail the client connection. The design tool will simply report the exception and move on.

ClientDisconnected(IClientDisconnectedEvent)

Called when a client disconnects from the host session.

Declaration

public virtual void ClientDisconnected(IClientDisconnectedEvent vsEvent)

Parameters

Type	Name	Description
IClientDisconnectedEvent	vsEvent	The event instance.

Remarks

Called when a client disconnects from the host session. This event fires before the client session is destroyed. The host application will be at whatever entity the client was at when the client disconnected. Upon returning from the event, VHI will navigate to the home entity if not already there.

Exceptions

Type	Condition
ApptrieveException	Any exception thrown from this event will be logged but otherwise ignored.

ErrorReported(IErrorReportedEvent)

Called the moment a top level error outside the context of an event handler.

Declaration

public virtual void ErrorReported(IErrorReportedEvent vsEvent)

Parameters

Type	Name	Description
IErrorReportedEvent	vsEvent	The event instance.

Remarks

This event will not fire in the VHI design tool, nor will the event fire if there is already an event in progress in the VHI server. This event provides the opportunity to capture screen state.

Any exception thrown from this event will be logged but otherwise ignored.

Exceptions

Type	Condition
ApptrieveException	Any exception thrown will be logged.

ExecuteLogin(IExecuteLoginEvent)

Called immediately after a network connection has been established with the host system.

Declaration

public virtual void ExecuteLogin(IExecuteLoginEvent vsEvent)

Parameters

Type	Name	Description
IExecuteLoginEvent	vsEvent	The event instance.

Remarks

The host system may or may not be displaying a login prompt when this event is fired. Regardless, it is the responsibility of this method to position the host application at a recognized screen. Upon returning from the event, VHI will attempt to navigate to the model's home entity if not already there.

Exceptions

Type	Condition
ApptrieveException	Any exception thrown from this event will result in the host login process failing.

ExecuteLogout(IExecuteLogoutEvent)

Called before a network connection with the host system is dropped.

Declaration

public virtual void ExecuteLogout(IExecuteLogoutEvent vsEvent)

Parameters

Type	Name	Description
IExecuteLogoutEvent	vsEvent	The event instance.

Remarks

The application will be positioned at the model's home entity. This method should do whatever is needed in order to logout from the host in an orderly fashion. Upon returning from the event, the host connection will be immediately dropped.

Exceptions

Type	Condition
ApptrieveException	Any exception thrown from this event will result in the host logout process failing.

FormatError(IFormatErrorEvent)

Called before an error is returned to a client.

Declaration

public virtual IList<ErrorMessage> FormatError(IFormatErrorEvent vsEvent)

Parameters

Type	Name	Description
IFormatErrorEvent	vsEvent	The event instance.

Returns

Type	Description
IList<ErrorMessage>	A list of ErrorMessage objects.

Remarks

Called before an error is returned to a client. In the VHI design tool this event is fired before reporting the error to the user. The list of error messages returned from this event will be returned to the client or reported to the user.
Error messages can be created using one of the vsEvent.CreateErrorMessage methods.
Note that upon returning from this event, the connector used by the client to connect to VHI will often append an additional error message onto the stack. This error message provides information about which API method was invoked.
Any exception thrown from this event will be logged but otherwise ignored.

Exceptions

Type	Condition
ApptrieveException	Any exception thrown will be logged.

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()

MoveCursor(IModelMoveCursorEvent)

Called when the cursor needs to move to a specific location on the terminal screen and the current entity, if any, has not defined how to move the cursor.

Declaration

public virtual void MoveCursor(IModelMoveCursorEvent vsEvent)

Parameters

Type	Name	Description
IModelMoveCursorEvent	vsEvent	The event instance.

Remarks

This event will fire in response to the following commands if the cursor is not already at the requested location:

• DefaultValue
• DefaultValueEncrypted
• MoveCursor
• ShiftCursor
• TransmitToAttr
• TransmitToAttrEncrypted
• TransmitToField
• TransmitToFieldEncrypted
• TransmitToLocation
• TransmitToLocationEncrypted
• TransmitToOffset
• TransmitToOffsetEncrypted
• UpdateAttribute
• UpdateRecordSetField

If no method to move the cursor forward or backward is defined for a character mode model, this event will fire to position the cursor at each attribute and field before writing.

If the cursor is not positioned at the specified location upon returning from the event, VHI will fail the current client request.

Any exception thrown from this event will cause the current attribute write or command to fail.

Exceptions

Type	Condition
ApptrieveException	Any exception thrown from this event will result in the move cursor process failing.

MoveCursorBackward(IModelMoveCursorBackwardEvent)

Called when VHI wants to move the cursor to the previous rest position on the screen and the current entity, if any, has not defined a move cursor backward operation.

Declaration

public virtual void MoveCursorBackward(IModelMoveCursorBackwardEvent vsEvent)

Parameters

Type	Name	Description
IModelMoveCursorBackwardEvent	vsEvent	The event instance.

Remarks

If the move cursor forward event or command list ever leaves the cursor position unchanged this event will begin to iteratively fire. See MoveCursorForward method for details.

Any exception thrown from this event will cause the current attribute write or command to fail.

Exceptions

Type	Condition
ApptrieveException	Any exception thrown from this event will result in the host logout process failing.

MoveCursorForward(IModelMoveCursorForwardEvent)

Called when VHI wants to move the cursor to the next at rest position on the screen and the current entity, if any, has not defined a move cursor forward operation.

Declaration

public virtual void MoveCursorForward(IModelMoveCursorForwardEvent vsEvent)

Parameters

Type	Name	Description
IModelMoveCursorForwardEvent	vsEvent	The event instance.

Remarks

VHI will iteratively fire this event while writing attributes on a character mode host. Upon returning from the event, VHI will check if the new cursor position corresponds to an attribute that needs writing and write to it.

This event will fire in the situation where the move cursor event is not defined on either the current entity or the model. Calling defaultMoveCursor in either of these events would also cause this event to fire. See MoveCursor(IModelMoveCursorEvent) for the list of commands.

If this event leaves the cursor position unchanged, VHI will begin iteratively calling the move cursor backwards event or command list, if defined, in lieu of this event.

Any exception thrown from this event will cause the current attribute write or command to fail.

Exceptions

Type	Condition
ApptrieveException	Any exception thrown from this event will result in the cursor move process failing.

ProcessString(IProcessStringEvent)

Called to process a string from the client.

Declaration

public virtual string ProcessString(IProcessStringEvent vsEvent)

Parameters

Type	Name	Description
IProcessStringEvent	vsEvent	The event instance.

Returns

Type	Description
string	The result string.

Remarks

Called to process a string from the client. The client provided string in the processString() method will be passed unmodified to this event. The results from this event will likewise be passed unmodified back to the client.

Exceptions

Type	Condition
ApptrieveException	Any exception thrown from this event will be propagated back to the client.

UnrecognizedScreen(IUnrecognizedScreenEvent)

Called to handle the arrival at an unrecognized screen.

Declaration

public virtual void UnrecognizedScreen(IUnrecognizedScreenEvent vsEvent)

Parameters

Type	Name	Description
IUnrecognizedScreenEvent	vsEvent	The event instance.

Remarks

The event handler should do whatever is needed in order to recover the host session or to return an intelligible error message:

• Send one or more keystrokes that will return the application to a recognized screen.
• Throw an exception describing a problem that cannot be handled.

If the host application is still at an unrecognized screen upon returning from the event, the current client request will fail with a dead session error.

Exceptions

Type	Condition
ApptrieveException	Any exception thrown from this event will be logged but otherwise ignored.

Implements

IEventHandler