Event Handler Callbacks
The callback information below, in combination with other event
handler guidelines, will help you develop event handlers that override or
extend standard model behavior.
An event handler performs a mix of custom logic and callbacks to Host Integrator
to get information about or modify the state of the model or terminal.
A callback invocation takes place any time an event handler invokes a method
on one of the callback interfaces. This may just be asking for information,
or it may be a request to modify the model or terminal state.
Note the following properties of callbacks:
- No specific timeout. The governing timeout is that of the event itself.
The time allowed per callback extends to the remaining time allotted to the
- The event can return the expected data, "normal errors" such as
a bad parameter name or a runtime failure in the model, or an event timeout
error if the event timeout expires during callback execution.
The callback interfaces, as documented in the Javadocs
for the Event Handler API, are:
Use this interface to get information about the host session and to manipulate
the terminal (whether at the terminal, model, or table level).
Use this interface to establish a session with a Host Integrator model other than the one containing this event handler.
- For events that rely on a specific terminal state, callbacks that could
change terminal state are disabled within that event. If you attempt this
sort of callback, you'll see an error message similar to the following:
Event handler callback not allowed in current state.
An event callback method was invoked at an inappropriate time.
Click Details in the error message dialog box to see the sequence that
preceded this error. The method immediately preceding the error can often
tell you the offending callback method. Many events within recordset
event handlers (for example, Apply Filter, Parse Screen) and recordset
field event handlers (Read Field) disable most callbacks:
- The ScriptHostSession interface cannot be used outside of the event from
which it was obtained. In the following events, this interface is not available:
- In addition to the limitations within the immediate event handler, callback
restrictions apply when event handlers are nested. If an event with callback
restrictions is currently open, this limitation will also be enforced for
a nested event.