A callback function (or just callback) is a function that you write to handle a particular event. The DataBlade API provides the following functions to handle invocation of a callback function.
For the DataBlade API to invoke a callback when the associated event occurs, the following conditions must be met in the DataBlade API module:
The mi_register_callback( ) function registers a callback for a particular event. The DataBlade API module that requires the event handling must register the callback.
It is possible to disable a registered callback to suspend its invocation. The mi_enable_callback( ) function enables a previously disabled callback.
In addition, a module can save a registered callback and restore it at a later time.
For a callback to execute when its associated event occurs, you must register it with the mi_register_callback( ) function. When you register a callback, you take the following actions:
The call to the mi_register_callback( ) function must occur before the statement for which you want the exception handling. If you register more than one callback to handle a particular event, all registered callbacks execute when the event occurs. The order in which these callbacks execute is not predetermined.
The mi_register_callback( ) function requires the following arguments.
| Argument Type | Description | More Information |
|---|---|---|
| MI_CONNECTION * | A pointer to the connection on which the callback is to be registered. It might be NULL if the connection is undefined, as is the case with some client LIBMI errors and state-transition events. | Connection Descriptor |
| MI_EVENT_TYPE | The event type that the callback handles | Types of Callbacks |
| MI_CALLBACK_FUNC | A pointer to the callback function to invoke when the specified event occurs | Callback-Function Pointer |
| void * | A pointer to the user data, which is passed to the callback function when the specified event occurs. It can be used to pass additional information to and from the callback. | Returning Error Information to the Caller |
| MI_CALLBACK_HANDLE * | Must be NULL | Callback Handle |
These arguments initialize many of the parameters of the callback function. For more information, see Figure 57.
When mi_register_callback( ) registers the callback, the function returns a callback handle for the callback. For more information, see Callback Handle.
If a callback is not registered when its event occurs, the DataBlade API takes the default behavior. For more information, see Using Default Behavior.
By default, a callback remains registered until the end of the connection. For more information, see Registration Duration.
The second argument of the mi_register_callback( ) function is the event type. The DataBlade API supports a type of callback for each event type. The following table lists the types of callbacks that the DataBlade API supports and the events that invoke them.
| Callback Type | Event Type | More Information | |
|---|---|---|---|
| Exception callback | MI_Exception | Database Server Exceptions | |
| State-transition callbacks: | State-Transition Events | ||
| Savepoint callback
Commit-abort callback Post-transaction callback |
MI_EVENT_SAVEPOINT | ||
| Client LIBMI callback | MI_Client_Library_Error | Client LIBMI Errors | |
For a general introduction on how to write a callback function, see Callback Functions.
The first argument of the mi_register_callback( ) function is a connection descriptor. This connection descriptor can be either a NULL-valued pointer or a pointer to a valid connection. The valid value depends on whether the calling module is a C user-defined routine (UDR) or a client LIBMI application.
For a UDR, the connection descriptor must be a NULL-valued pointer when you register callbacks for the following state-transition events:
For example, the following call to mi_register_callback( ) specifies a connection descriptor of NULL to register the endxact_callback( ) end-of-transaction callback, (which State Transitions in a C UDR (Server) defines):
cback_hndl = mi_register_callback(NULL, MI_EVENT_END_XACT, endxact_callback, NULL, NULL);
The mi_register_callback( ) function requires a valid connection descriptor for the MI_Exception event type. For example, the following code fragment registers the handle_errs( ) callback:
conn = mi_open(NULL, NULL, NULL);
if ( mi_register_callback(conn, MI_Exception, handle_errs,
NULL, NULL) == NULL )
/* handle error */
In the preceding code fragment, the mi_register_callback( ) function specifies a valid connection descriptor, which the mi_open( ) function has initialized.
For the MI_Exception event, you can also provide a NULL-valued pointer as a connection descriptor. In this case, the DataBlade API looks for callbacks registered by the function that called the C UDR. If no callback exists for this calling function, the DataBlade API continues up the calling hierarchy looking for registered callbacks until it reaches the client application (which initially invoked the UDR). This hierarchy of callbacks takes advantage of the calling hierarchy.
For further information on how to register an exception callback, see Exceptions in a C UDR (Server).
For a client LIBMI application, you must provide a valid connection descriptor to mi_register_callback( ) to register callbacks for the following event types:
If the connection descriptor is not valid, the mi_register_callback( ) function raises an exception.
The third argument of the mi_register_callback( ) function is a callback-function pointer. The DataBlade API stores a pointer to the location of a callback function in the MI_CALLBACK_FUNC data type. In the mi_register_callback( ) function, you can specify the callback function in either of the following ways:
When you specify the function name as the third argument, mi_register_callback( ) creates a callback-function pointer from the function name.
The sample callback registrations in Connection Descriptor pass the name of the callback as the third argument of mi_register_callback( ). Both of these registrations are the first time that the callback is registered within the module.
If mi_register_callback( ) has already initialized a callback-function pointer, you can specify this pointer as the third argument of mi_register_callback( ).
In the code fragment in Retrieving a Callback Function, the second registration of the initial_cback( ) function passes a pointer to an MI_CALLBACK_FUNC variable (&initial_cbptr) as the third argument of mi_register_callback( ).
The mi_register_callback( ) function returns a callback handle, which accesses a registered callback within a DataBlade API module. A callback handle has the MI_CALLBACK_HANDLE data type. Use a callback handle to identify a callback for the following tasks.
The registration of a callback survives until one of the following conditions is met:
A callback must be enabled for the database server to invoke it. The mi_register_callback( ) function automatically enables the callback that it registers. You can explicitly disable a registered callback with the mi_disable_callback( ) function. When you disable a callback, you suspend its invocation. You can later explicitly reenable it with the mi_enable_callback( ) function.
Both the mi_enable_callback( ) and mi_disable_callback( ) functions take the following arguments:
The connection descriptor must have the same value that the mi_register_callback( ) statement used when it registered the callback. For more information, see Connection Descriptor.
This argument identifies the event type that the callback handles. For more information, see Table 66.
The mi_register_callback( ) function returns a callback handle when it successfully registers a callback. This handle identifies the callback to the mi_enable_callback( ) or mi_disable_callback( ) function. For more information, see Callback Handle.
The mi_retrieve_callback( ) function returns a callback-function pointer (MI_CALLBACK_FUNC) when you pass in a callback handle (MI_CALLBACK_HANDLE). This function is useful when a DataBlade API module needs to change temporarily the callback that is registered for a particular event.
The mi_register_callback( ) function returns a callback handle for the callback that it receives as its third argument.
Pass the callback handle for the initial callback as an argument to the mi_retrieve_callback( ) function. The function returns a callback-function pointer, which saves the location of the registered initial callback.
The initial callback should be unregistered.
This call to mi_register_callback( ) overwrites the previous callback that was registered for the event and returns a callback handle for the temporary callback.
Pass the saved callback-function pointer (step 3) of the initial callback as the third argument of mi_register_callback( ). The function returns a new callback handle for the initial callback.
A temporary callback is useful when C UDRs are nested and some inner function wants to trap an event type in its own way instead of in the way that the outer function provides.
For example, suppose the func1( ) function specifies the func1_callback( ) function to handle event_type events and then calls the func2( ) function, as follows:
func1(...)
{
MI_CALLBACK_HANDLE *cback_hndl;
...
/* Set callback for event_type event type in func1( ) */
cback_hndl = mi_register_callback(conn, event_type,
func1_callback, ...)
/* do some stuff */
...
/* call func2( ), which "inherits" func1( ) callback */
func2( )
...
}
func2( )
{
MI_CALLBACK_HANDLE *cback_hndl;
MI_CALLBACK_FUNC *old_callback;
/* Save func1( ) callback in 'old_callback' */
if ( mi_retrieve_callback(conn, event_type, cback_hndl,
old_callback, NULL) == MI_ERROR )
/* handle error */
/* Set up func2( ) callback */
mi_unregister_callback(conn, event_type, cback_hndl);
mi_register_callback(conn, event_type, func2_callback, ...);
/* do some other stuff */
...
/* restore func1( ) callback */
cback_hndl = mi_register_callback(conn, event_type,
old_callback, ...)
...
}
By default, the database server uses the func1_callback( ) callback to handle any event_type events that occur during execution of func2( ). For the func2( ) routine to trap an event_type event in its own way, the routine must save the func1_callback( ) callback and then register its own callback for the event_type event type.
In the preceding code, the func2( ) function performs the following tasks:
The func2( ) function passes in the func1_callback( ) callback handle (cback_hndl) to the mi_retrieve_callback( ) function, which puts the MI_CALLBACK_FUNC handle for func1_callback( ) into the old_callback argument.
The mi_register_callback( ) function registers the func2_callback( ) function for the event_type event type.
Any event_type event that occurs during this work causes the database server to invoke the func2_callback( ) function.
The func2( ) function uses mi_register_callback( ) again, this time to restore the func1_callback( ) as the callback for the event_type event type.
For example, suppose the UDR func1( ) specifies the initial_cback( ) function to handle the MI_Exception event type, but the UDR requires the tmp_cback( ) callback for MI_Exception events during a portion of its execution. The following code fragment shows the use of mi_retrieve_callback( ) and mi_register_callback( ) to save the initial_cback( ) callback, to use the tmp_cback( ) callback temporarily, and then to restore initial_cback( ):
func1( )
{
MI_CONNECTION *conn;
MI_CALLBACK_HANDLE *initial_hndl, *tmp_hndl;
MI_CALLBACK_FUNC initial_cbptr;
conn = mi_open(NULL, NULL, NULL);
/* Register the initial callback (register #1). */
initial_hndl = mi_register(conn, MI_Exception,
initial_cback, NULL, NULL);
/* Do tasks that require initial_cback( ) as callback. */
...
/* Retrieve the current callback-function pointer on
* this connection into initial_cbptr. Pass in the
* callback handle of initial_cback( ).
*/
mi_retrieve_callback(conn, MI_Exception, initial_hndl,
&initial_cbptr, NULL);
/* Register the temporary callback (register #2).
* Callback handle for initial callback is overwritten.
*/
tmp_hndl = mi_register_callback(conn, MI_Exception,
tmp_cback, NULL, NULL);
/* Do tasks that require tmp_cback( ) as callback. */
...
/* Restore initial callback (register #3) */
initial_hndl = mi_register(conn, MI_Exception,
&initial_cbptr, NULL, NULL);
/* Continue with tasks that require initial_cback( ) as
* callback.
*/
...
}