The mi_register_callback() function

The mi_register_callback() function registers a callback function for a single event type or for all event types.

Syntax

MI_CALLBACK_HANDLE *mi_register_callback(conn, event_type, 
   cback_func,user_data, parent)
   MI_CONNECTION *conn;
   MI_EVENT_TYPE event_type;
   MI_CALLBACK_FUNC cback_func;
   void  *user_data;
   MI_CALLBACK_HANDLE *parent;
conn
This value is either a NULL-valued pointer or a connection descriptor established by a previous call to mi_open(), mi_server_connect(), or mi_server_reconnect().
event_type
The type of event that the cback_func callback handles. For a list of valid event types, see the HCL OneDB™ DataBlade® API Programmer's Guide.
cback_func
A pointer to the callback function.
user_data
A pointer to a user-provided structure that is passed to the callback function when the event specified by event_type occurs. It can be used to pass additional information to the callback.
parent
This value must be a NULL-valued pointer.
Valid in client LIBMI application? Valid in user-defined routine?
Yes Yes

Usage

The mi_register_callback() function registers the callback that cback_func identifies for the event that event_type specifies.

Server only: For a C UDR, conn must be a NULL-valued pointer for the following event types:
  • MI_EVENT_SAVEPOINT
  • MI_EVENT_COMMIT_ABORT
  • MI_EVENT_POST_XACT
  • MI_EVENT_END_STMT
  • MI_EVENT_END_XACT
  • MI_EVENT_END_SESSION

For the MI_Exception event, conn can be either a valid connection descriptor or a NULL-valued pointer. For more information, see the HCL OneDB DataBlade API Programmer's Guide.

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

The callback is enabled when it is registered. You can explicitly disable the callback with the mi_register_callback() function and re-enable it with the mi_register_callback() function.

The mi_register_callback() function initializes the DataBlade API when it is the first DataBlade API function in a client LIBMI application or a C UDR. For more information, see the HCL OneDB DataBlade API Programmer's Guide.

You can use the user_data parameter to specify the address of a user-defined error structure, which the callback can use to hold additional error information.

Return values

An MI_CALLBACK_HANDLE pointer
A pointer to the newly registered callback function.
NULL
The function was not successful.