Exceptions in a client LIBMI application (Client)

If the client LIBMI application has not registered a callback that handles the MI_Exception event on the current connection, the client LIBMI calls the system-default callback.

To provide event handling for database server exceptions within a client LIBMI application, register a callback that handles the MI_Exception event in the client LIBMI application. The DataBlade® API invokes any exception callback that the application has registered (and enabled) on the current connection when either of the following actions occurs:
  • A client LIBMI application executes a DataBlade® API function that throws an MI_Exception event.
  • An exception occurs in a UDR that is invoked from a statement in the client LIBMI application and any exception callbacks that the UDR has registered return the MI_CB_CONTINUE return status.

Function descriptions in the Informix® DataBlade® API Function Reference contain a section titled Return Values. This section lists the possible return values for the DataBlade® API function. In a C UDR, DataBlade® API function calls might or might not return a value, depending on whether the DataBlade® API function throws an MI_Exception event when it encounters a runtime error. However, DataBlade® API function calls in a client LIBMI application always indicate failure because client-side callbacks always return to the DataBlade® API function that generated the error.

On failure, DataBlade® API functions return one of the following values to a client LIBMI application:
  • MI_ERROR if the return value is an integer.
  • NULL if the return value is a pointer.

The client LIBMI application can check for these error values and take any appropriate actions.

The client LIBMI application registers callbacks with the mi_register_callback() function. You must provide a valid connection descriptor to mi_register_callback() for all valid event types.

For example, the following mi_register_callback() call registers the clntexcpt_callback() function to handle MI_Exception events: 
int main (argc, arcv)
   int argc;
   char *argv;
{
   MI_CONNECTION *client_conn;
   MI_CALLBACK_HANDLE *client_cback;
   mi_integer ret;

/* Open a connection to the database server */
client_conn = mi_open(argv[1], NULL, NULL);

/* Register the exception callback */
client_cback = mi_register_callback(client_conn,
   MI_Exception, (MI_VOID *)clntexcpt_callback, NULL, NULL);
if ( client_cback == NULL )
   /* do something appropriate */
...
ret = mi_exec(client_conn, "bad SQL statement",
   MI_QUERY_NORMAL);
if ( ret == MI_ERROR )
   /* perform error recovery */
...
}