Declaring a Callback Function

Figure 56 shows the declaration of a callback function named myhandler( ) for use in a UDR.

Return Value of a Callback Function

When a callback function completes execution, it returns any return value that it might have to the DataBlade API, which invoked it. The data type of the callback return value depends on whether a UDR or a client LIBMI application triggered the callback.

When a UDR causes a callback function to be invoked, the DataBlade API expects the callback-function return value to be one of the enumerated values of the MI_CALLBACK_STATUS data type. The MI_CALLBACK_STATUS values indicate how to continue handling the event once the callback completes. Table 67 shows the valid values for the MI_CALLBACK_STATUS return type.

Table 67. MI_CALLBACK_STATUS Return-Status Values
Return Status	Description
MI_CB_EXC_HANDLED	Only an exception callback can return this status value. When the callback completes, the DataBlade API returns control to the first statement after the statement that raised the exception event. This return status indicates that the callback has successfully handled the event and the DataBlade API does not need to continue with event handling. Therefore, the DataBlade API does not abort the statement that invoked the callback.
MI_CB_CONTINUE	This is the only status value that a callback other than an exception callback can return. If a nonexception callback returns this value, the database server continues processing after the callback completes. When an exception callback completes, the DataBlade API continues to look for registered callbacks that handle the event: Callbacks registered for the same event (on the same connection) and at the same level in the calling sequence Callbacks registered for the same event (on the same connection) in a higher level of the calling sequence When an exception callback returns this value to the highest-level function in a calling sequence and no other registered callback exists, the DataBlade API aborts the UDR and any current transaction.

The milib.h header file defines MI_CALLBACK_STATUS and its return-status values.

The end-of-transaction callback on page State Transitions in a C UDR (Server) shows use of the MI_CB_CONTINUE status. For information on the use of these return codes in exception callbacks, see Determining How to Handle the Exception.

When a client LIBMI application causes a callback to be invoked, the DataBlade API does not expect the callback to return a status value. The client LIBMI ignores any return value from a callback that a client LIBMI application registers. Therefore, any such callbacks can return void.

In effect, the client LIBMI always assumes a MI_CB_EXC_HANDLED return status from a callback. The client LIBMI returns control to the first statement after the one that threw the event. The client LIBMI application must include code that decides how to proceed based on the failure.

If a callback returns MI_CB_CONTINUE, the client LIBMI ignores the return code because this return value does not have a meaning within a client application. Within a C UDR, you can pass an exception up to a higher level in the calling sequence because the routine executes in the context of the database server. However, a client LIBMI application does not execute in the context of the database server. Therefore, it cannot assume this general exception-handling mechanism.

For an example of a callback that a client LIBMI application registers, see the clntexcpt_callback( ) function in Returning Error Information to the Caller.

MI_PROC_CALLBACK Modifier (Windows)

The MI_PROC_CALLBACK modifier on a callback definition is required for callbacks that execute with Windows applications. For all other operating systems, this modifier is optional. To make callbacks portable between operating systems, include the MI_PROC_CALLBACK modifier in your callback declaration.

The MI_PROC_CALLBACK modifier follows the callback return type and precedes the callback name. Figure 56 shows the location of the MI_PROC_CALLBACK modifier in the declaration of the myhandler( ) callback.1fs

Callback-Function Parameters

Argument Type	Description	Initialized by mi_register_callback( )?
MI_EVENT_TYPE	The event type that triggers the callback	Yes
MI_CONNECTION *	A pointer to the connection on which the event occurred If the connection is undefined, it might be NULL, as is the case with some client-library errors and state-transition events.	Yes
void *	A pointer to an event-type structure that holds event information For example, if the event is an MI_Exception event, the DataBlade API passes in an MI_ERROR_DESC structure, which holds the exception level and the message text.	No The DataBlade API sets this pointer to the associated event structure when it invokes the callback.
void *	A pointer to any user data, which you can use to pass any additional information to and from the callback	Yes

When you register a callback with the mi_register_callback( ) function, you provide arguments for most parameters of the callback. Figure 57 shows how a call to mi_register_callback( ) provides the arguments that initialize the parameters of the myhandler( ) callback.

The only callback parameter that the mi_register_callback( ) call does not initialize is the event-type structure (the event_data parameter in Figure 57). For more information about event-type structures, see Event Information.