Connection descriptor

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.

Server only

For a UDR, the connection descriptor must be a NULL-valued pointer when you register callbacks for the following state-transition events:
  • MI_EVENT_SAVEPOINT
  • MI_EVENT_COMMIT_ABORT
  • MI_EVENT_POST_XACT
  • MI_EVENT_END_STMT
  • MI_EVENT_END_XACT
  • MI_EVENT_END_SESSION
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 the code fragment in 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.

Client only

For a client LIBMI application, you must provide a valid connection descriptor to mi_register_callback() to register callbacks for the following event types:
  • MI_Exception
  • MI_Xact_State_Change
  • MI_Client_Library_Error

If the connection descriptor is not valid, the mi_register_callback() function raises an exception.