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.

Server only

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. The following table shows the valid values for the MI_CALLBACK_STATUS return type.

Table 1. MI_CALLBACK_STATUS return-status values
Return-status values	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 non-exception 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 from State transitions in a C UDR (Server) shows use of the MI_CB_CONTINUE status.

Client only

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 Return error information to the caller.