Callbacks
A callback is a user function within an application that is automatically invoked when the event associated with the callback occurs. The task of the callback is to perform the appropriate actions to handle the event.
An application must enable a callback before the application can invoke the callback in response to an event. To enable a callback, the application can register it with the mi_register_callback() function. The application can also explicitly enable or disable the callback with the mi_enable_callback() or mi_disable_callback() function.
A callback in a DataBlade API application takes four arguments:
Callback functions cannot execute SQL, raise exceptions, or register other callbacks.
When a registered callback is called, it should return one of the following values:
To register a callback, use mi_register_callback(). To remove the callback, use mi_unregister_callback().
If an application does not register any callbacks, the mi_default_callback() function, which Universal Server automatically registers to handle all events, returns an appropriate message when an event occurs.
On UNIX, this default callback displays an error or warning message on stderr in response to the event. 
On Windows 95 and Windows NT, this default callback displays an error or warning message in a Windows message box in response to the event.
An application can override the default callback by registering its own callback with mi_register_callback(). The function mi_default_callback() is also available for public use.
For a demonstration of callbacks, see "Callback Example".
All Events
A general-purpose dispatch callback can be registered for the special event type MI_All_Events. In this case, the callback is invoked for all event types. The type of the event is passed in the first argument to the callback, so the callback can dispatch the appropriate routine to handle the event. For an example that uses the MI_All_Events event type, see "Exception Handling".
Server Processing State Transitions
The following events cause a transition of the server processing state:
The transitions that can occur are begin, normal end, and abort end.
These events can cause a callback to be called. The callback can use mi_transition_type() on the client data to determine the transition type (begin, normal end, or abort end).
Callbacks are called for different events on the client computer and on the server computer, as the following table shows.
In a server program, callbacks are always called at the end of a transaction, not at the beginning.
In a client program, callbacks are called only for an explicit begin or end transition (BEGIN WORK, COMMIT WORK, or ROLLBACK WORK), or for an ANSI-standard implicit begin.
Callback Example
The example in this section implements a general-purpose callback named all_callback() and registers it to catch all events. The all_callback() function provides special handling for the events in which this application is interested: MI_Exception, MI_Client_Library_Error, and MI_Xact_State_Change.
The all_callback() function also calls other user functions that are special purpose handlers (not shown here) to handle messages (message_handler()) and server exceptions (exception_handler()). The message_handler() routine might simply display a message on standard error, while the other handlers could take some specific user-defined action based on the type of exception.
The MI_PROC_CALLBACK modifier on the definition of all_callback() is required for Windows NT applications. For all other systems, this modification is optional.
The all_callback() function is registered when the application is initialized by the following call to mi_register_callback():
|
