Writing a Callback Function

Within the body of a callback function, you provide the code that handles a particular event or events. Only certain tasks are valid within a callback. When a callback function is invoked for an event, the DataBlade API passes information about the event to the callback.

Restrictions on Content

A callback can call a DataBlade API function to perform its task. Callbacks often clean up resources with such functions as mi_free( ), mi_close( ), and mi_lo_spec_free( ). The MI_EXCEPTION, MI_END_SESSION, and MI_EVENT_POST_XACT callbacks cannot perform the following tasks:

• Execute SQL statements
• Raise database server exceptions
• Register other callbacks

Event Information

When a callback function is invoked for a particular event, the DataBlade API passes an event-type structure as the third parameter of this function. This event-type structure contains information about the event that triggered the callback. The DataBlade API stores event information in one of the following structures based on the event type:

• Exceptions and errors are stored in error descriptors.
• State transitions are stored in transition descriptors.

The following table shows the event types and the corresponding event-type structures that describe them.

The milib.h header file defines the MI_ERROR_DESC and MI_TRANSITION_DESC structures.

Using an Error Descriptor

The DataBlade API stores information about exceptions and errors in an error descriptor. An error descriptor is an MI_ERROR_DESC structure. It holds information for the MI_Exception and MI_Client_Library_Error event types. The following table summarizes the memory operations for an error descriptor.

When an MI_Exception or MI_Client_Library_Error event occurs, the DataBlade API invokes the appropriate callback. To this callback, the DataBlade API passes an initialized error descriptor as the third callback argument. The error descriptor contains information about the MI_Exception or MI_Client_Library_Error event. Within the callback, use the accessor functions in Table 68 to obtain the error information from the error descriptor.

Accessing an Error Descriptor

The error descriptor is an opaque structure. You must use the DataBlade API functions in Table 68 to access information within it.

Each of the DataBlade API functions in Table 68 requires that you pass in a pointer to a valid error descriptor.

For a sample callback that obtains information from an error descriptor, see the excpt_callback2( ) function in Associating with a Callback.

Creating a Copy of an Error Descriptor

The DataBlade API passes the error descriptor as an argument to the callback. Therefore, the DataBlade API allocates memory for the error descriptor when it invokes the callback and deallocates this memory when the callback exits. To preserve the error information for the calling routine, you can create a user copy of the error descriptor within the callback.

The following DataBlade API functions facilitate an error-descriptor copy.

Using a Transition Descriptor

The transition descriptor, MI_TRANSITION_DESC, stores information about a transition in the processing state of the database server. It holds information for all 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
• MI_Xact_State_Change

The milib.h header file defines the MI_TRANSITION_DESC structure.

When a state transition event occurs, the DataBlade API invokes the appropriate callback. To this callback, the DataBlade API passes an initialized transition descriptor as the third callback argument. The transition descriptor contains the transition type that initiated the state-transition event. To obtain the transition type from the descriptor, use the mi_transition_type( ) function. This function returns a value of type MI_TRANSITION_TYPE to indicate the transition type of the event that occurred. For a list of valid MI_TRANSITION_TYPE values, see Understanding State-Transition Events.

The following code fragment uses the mi_transition_type( ) function to determine which action to take when it receives a state-transition event:

MI_TRANSITION_DESC *event_data;
MI_TRANSITION_TYPE trans_type;
mi_string s[30];
...
trans_type = mi_transition_type(event_data);
switch ( trans_type )
   {
   case MI_BEGIN: /* client LIBMI apps only */
      s = "Transaction started.";
      break;
   case MI_NORMAL_END:
      s = "Successful event";
      break;
   case MI_ABORT_END:
      s = "Event failed and rolled back,";
      break;
   default:
      s = "Unknown transition type";
      break;
   }
fprintf(stderr, "%s\n", s);