Handling an exception in the callback

To indicate that the callback function executes instead of the default exception handling, an exception callback function returns the MI_CB_EXC_HANDLED status. This return status tells the DataBlade API that the actions of the callback have completely handled the exception.

An exception callback function returns the MI_CB_EXC_HANDLED status to indicate that the callback has completely handled the exception. That is, the actions of the callback have provided the exception handling. When the DataBlade API receives the MI_CB_EXC_HANDLED return status, it does not perform its default exception handling. It assumes that the callback has executed instead of the default exception handling.

When a callback returns MI_CB_EXC_HANDLED, the DataBlade API does not propagate the exception up the calling sequence. Therefore, a client application that has executed an SQL expression that contains a UDR does not receive an error from the execution of the UDR (unless the callback uses a user-provided error buffer). If the SQL expression contains no other exceptions, the client application would have an SQLSTATE value of 00000 (success).

The following code fragment shows the excpt_callback() exception callback, which is written to handle the MI_Exception event. It returns MI_CB_EXC_HANDLED to indicate that no further exception handling is required.

Figure 1. A simple exception callback

static MI_CALLBACK_STATUS MI_PROC_CALLBACK
excpt_callback(event_type, conn, event_data, user_data)
   MI_EVENT_TYPE event_type;
   MI_CONNECTION *conn;
   void *event_data;
   void *user_data;
{
   /* claim to have handled the exception */
   return MI_CB_EXC_HANDLED;
}

The excpt_callback() function in Figure 1 returns MI_CB_EXC_HANDLED, which prevents the DataBlade API from taking any further exception-handling steps, such as invoking other callbacks that handle MI_Exception or aborting the current statement. This callback executes instead of the default exception handling.

For the has_exception_handling() routine (which Figure 1 defines), the DataBlade API takes the following steps when the mi_exec() function executes:

Executes the excpt_callback() callback when mi_exec() throws an exception
Returns control to the first statement in has_exception_handling() after mi_exec(). As a result, execution of the has_exception_handling() routine returns from the mi_exec() call with a return value of MI_ERROR.

Important: Because excpt_callback() returns MI_CB_EXC_HANDLED, the database server assumes that the MI_Exception event does not require any further handling. However, excpt_callback() does not actually take any exception-handling steps; it contains only a return statement to return an MI_CB_EXC_HANDLED status. In an actual DataBlade API module, you would probably want to add code to excpt_callback() that provides exception handling.