Informix DataBlade API Programmer's Manual Handling Exceptions and Events

The event-handling mechanism provides a way for one DataBlade API module to inform another module (or another part of the same module) that an event has occurred during execution of a function. The two parts of the event-handling mechanism are as follows:

• A function that throws an event

A function in a DataBlade API module might encounter a condition that it cannot handle. Many common conditions are represented by events (see Figure 10-1 on page 10-4). When a module encounters one of these conditions, it can throw the associated event to indicate that some event handling needs to be performed.

• A function that catches an event

A special function, called a callback function, is invoked when its associated event occurs. It can perform the appropriate actions to handle or recover from this event.

This division of event-handling responsibility allows you to put common event-handling code for a particular condition in a single location, in a callback function. Any DataBlade API module that requires the associated event handling can then register this callback function.

When an event occurs, the DataBlade API performs the event handling based on whether it finds a registered callback that can catch (or handle) the event, as follows:

• If a registered callback exists, the DataBlade API invokes this callback.
• If no registered callback exists, the DataBlade API takes the appropriate default behavior.

A callback function (sometimes called just a callback) is a function that you write to handle a particular event. The DataBlade API provides the following functions to handle invocation of a callback function.

For the DataBlade API to invoke a callback when the associated event occurs, the following conditions must be met in the DataBlade API module:

• The module must register the callback for the event on the current connection.

The mi_register_callback() function registers a callback for a particular event. The DataBlade API module that requires the event handling must register the callback.

• The registered callback must be enabled.

It is possible to disable a registered callback to suspend its invocation. The mi_enable_callback() function enables a previously disabled callback.

In addition, a module can save a registered callback and restore it at a later time. The following sections describe each of these topics.

For a callback to execute when its associated event occurs, you must register it with the mi_register_callback() function. When you register a callback, you:

• Associate the callback function with the event it is to catch.
• Provide arguments for the callback parameters.

The call to the mi_register_callback() function must occur before the statement for which you want the exception handling. If you register more than one callback to handle a particular event, all registered callbacks execute when the event occurs. The order in which these callbacks execute is not predetermined.

Tip: You do not need to register a callback function in the database with the CREATE FUNCTION statement. You only need to register the callback with the mi_register_callback() function.

The mi_register_callback() function requires the following arguments.

These arguments initialize many of the parameters of the callback function. For more information, see Figure 10-4 on page 10-22.

When mi_register_callback() registers the callback, the function returns a callback handle for the callback. For more information, see Callback Handle.

If a callback is not registered when its event occurs, the DataBlade API takes the default behavior. For more information, see Using Default Behavior.

The second argument to the mi_register_callback() function is the event type. The DataBlade API supports a callback on each event type. The following table lists the types of callbacks that the DataBlade API supports and the events the invoke them.

For a general introduction to how to write a callback function, see Creating a Callback Function.

The first argument to 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 UDRor a client LIBMI application.

For a UDR, the connection descriptor must be a NULL-valued pointer when you register callbacks for the following state-transition events:

• MI_EVENT_END_STMT
• MI_EVENT_END_XACT
• MI_EVENT_END_SESSION

Tip: In releases before 9.12, the single event code MI_Xact_State_Change occurred for both the MI_Xact_State_Change and MI_EVENT_END_XACT events. For backward compatibility, the DataBlade API still allows you to register a callback for the MI_Xact_State_Change event in a C UDR. In this case, the connection descriptor must be NULL. However, in UDRs, the mi_register_callback() function translates MI_Xact_State_Change to the MI_EVENT_END_XACT event type. Therefore, when the DataBlade API invokes a registered callback from a UDR, it passes the event type as MI_EVENT_END_XACT.

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 State Transitions In a C UDR 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 all other UDR event types (MI_Exception and MI_All_Events). For example, the following code fragment registers the all_callback() all-events callback (which Creating an All-Events Callback defines):

conn = mi_open(NULL, NULL, NULL);



if ( mi_register_callback(conn, MI_All_Events, all_callback,

		NULL, NULL) == NULL )

	/* handle error */

In the preceding fragment, the mi_register_callback() function specifies a valid connection descriptor, which the mi_open() function has initialized.

For the MI_Exception and MI_All_Events events, 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 user-defined routine. If no callbacks exist 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.

For information on how to register an exception callback, see Exceptions In a C UDR.

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 throws an exception.

The third argument to the mi_register_callback() function is a callback-function pointer. The DataBlade API stores a pointer to the location of a callback function in the MI_CALLBACK_FUNC data type. In the mi_register_callback() function, you can specify the callback function in either of the following ways:

• The name of the function

When you specify the function name as the third argument, mi_register_callback() creates a callback-function pointer from the function name.

The sample callback registrations in Connection Descriptor pass the name of the callback as the third argument to mi_register_callback(). Both of these registrations are the first time that the callback is registered within the module.

• A pointer to an MI_CALLBACK_FUNC variable

If mi_register_callback() has already initialized a callback-function pointer, you can specify this pointer as the third argument to mi_register_callback().

In the code fragment in Retrieving the Callback Function, the second registration of the initial_cback() function passes a pointer to an MI_CALLBACK_FUNC variable (&initial_cbptr) as the third argument to mi_register_callback().

The mi_register_callback() function returns a callback handle, which accesses a registered callback within a DataBlade API module. The DataBlade API stores a callback handle in the MI_CALLBACK_HANDLE data type. Use this callback handle to identify the callback for the following tasks.

Tip: The last argument of the mi_register_callback() function is also a callback handle. However, this argument is reserved for future use and must currently be a NULL-valued pointer. Registration Duration

The registration of a callback survives until one of the following conditions is met:

• The connection on which the callback is registered is closed (either the UDR exits or the mi_close() function executes).
• For state-transition callbacks, when one of the following state transitions occurs, the DataBlade API unregisters the callback:
• MI_EVENT_END_STMT
• MI_EVENT_END_XACT
• MI_EVENT_END_SESSION
• MI_Xact_State_Change
• You can explicitly unregister the callback with the mi_unregister_callback() function.

A callback must be enabled for the database server to invoke it. The mi_register_callback() function automatically enables the callback that it registers. You can explicitly disable a registered callback with the mi_disable_callback() function. When you disable a callback, you suspend its invocation. You can later explicitly reenable it with the mi_enable_callback() function.

Tip: If you want to reuse a callback, it is usually less resource intensive to disable and reenable the callback then to unregister and reregister it.

Both the mi_enable_callback() and mi_disable_callback() functions take the following arguments:

• A connection descriptor

The connection descriptor must have the same value that the mi_register_callback() statement used when it registered the callback. For more information, see Connection Descriptor.

• An MI_EVENT_TYPE value

This argument identifies the event type that the callback handles. For more information, see Figure 10-1 on page 10-4.

• A callback handle for a registered callback

The mi_register_callback() function returns a callback handle when it successfully registers a callback. This handle identifies the callback to the mi_enable_callback() or mi_disable_callback() function. For more information, see Callback Handle.

The mi_retrieve_callback() function returns a callback-function pointer (MI_CALLBACK_FUNC) when you pass in a callback handle (MI_CALLBACK_HANDLE). This function is useful when a DataBlade API module needs to temporarily change the callback that is registered for a particular event.

To temporarily change a registered callback, follow these steps:

1. Register the initial callback with mi_register_callback().

The mi_register_callback() function returns a callback handle for the callback that it receives as its third argument.

2. Perform tasks that require the event handling of the initial callback.
3. Obtain the callback-function pointer for the initial callback with mi_retrieve_callback().

Pass the callback handle for the initial callback as an argument to the mi_retrieve_callback() function. The function returns a callback-function pointer, which saves the location of the registered initial callback.

4. Register the temporary callback with mi_register_callback().

This call to mi_register_callback() overwrites the previous callback that was registered for the event. It returns a callback handle for the temporary callback.

5. Perform the tasks that require the event handling of the temporary callback.
6. Restore the initial callback with mi_register_callback().

Pass the saved callback-function pointer (step 3) of the initial callback as the third argument to mi_register_callback(). The function returns a new callback handle for the initial callback.

For example, suppose the UDR func1() specifies the initial_cback() function to handle the MI_All_Events event type but it requires the tmp_cback() callback for MI_All_Events events during a portion of its execution. The following code fragment shows the use of mi_retrieve_callback() and mi_register_callback() to save the initial_cback() callback, temporarily use the tmp_cback() callback, then restore the initial_cback() callback:

func1()

{

	MI_CONNECTION *conn;

	MI_CALLBACK_HANDLE *initial_hndl, *tmp_hndl;

	MI_CALLBACK_FUNC initial_cbptr;



	conn = mi_open(NULL, NULL, NULL);



	/* Register the initial callback (register #1). */

	initial_hndl = mi_register(conn, MI_All_Events, 

		initial_cback, NULL, NULL);



	/* Do tasks that require initial_cback() as callback. */
	

	/* Retrieve the current callback-function pointer on

	** this connection into initial_cbptr. Pass in the

	** callback handle of initial_cback(). */

	mi_retrieve_callback(conn, MI_All_Events, initial_hndl,

		&initial_cbptr, NULL);


	/* Register the temporary callback (register #2).

	** Callback handle for initial callback is overwritten. */

	tmp_hndl = mi_register_callback(conn, MI_All_Events,

		tmp_cback, NULL, NULL);



	/* Do tasks that require tmp_cback() as callback. */
	

	/* Restore initial callback (register #3) */

	initial_hndl = mi_register(conn, MI_All_Events,

		&initial_cbptr, NULL, NULL);



	/* Continue with tasks that require initial_cback() as

	** callback. */
	

}

If a callback is not registered for a particular event, the DataBlade API uses its default behavior when this event occurs. The default event handling depends on whether the event occurs in a C UDR or a client LIBMI application.

If an event occurs during the execution of the UDR and the UDR does not register any callback to handle this event, the DataBlade API takes one of the following default actions, based on the event type.

If a UDR does not register a callback for the MI_Exception event whose exception level is MI_EXCEPTION (a runtime error), the DataBlade API aborts the UDR and returns control to the calling module, which might have been either of the following cases:

• A client application, which called the UDR in an SQL statement
• Another user-defined routine, which called the UDR that encountered the runtime error

The calling module might have a registered callback (or some other method) to handle the exception. To prevent database runtime errors from aborting a UDR, use the mi_register_callback() function to register callbacks in the UDR. For more information, see Exceptions In a C UDR.

Important: Programming errors do not cause execution of callbacks. If a user-defined routine contains a serious programming error (such as a segmentation fault), execution jumps out of the routine and back to the routine manager. The routine manager attempts to make an entry in the database server message log file (online.log by default).

Default Behavior In Client LIBMI Applications

If an event occurs during the execution of a client LIBMI application and the application does not register any callback to handle the event, the client LIBMI takes one of the following default actions, based on the event type.

On UNIX, the system-default callback causes the client LIBMI application to send the error or warning message to stderr in response to an unhandled event.

On Windows 95 and Windows NT, the system-default callback causes the client LIBMI to display the error or warning message in a Windows message box in response to an unhandled event.

To prevent the execution of the system-default callback, use the mi_register_callback() function to register callbacks in the client LIBMI application. For more information, see Exceptions In a Client LIBMI Application and Handling Client LIBMI Errors.