Using Callback Functions

Database server events include the following types.

Event Type

Description

MI_Exception

Exceptions with the following severity:

• Warnings
• Runtime errors

MI_EVENT_END_XACT

End-of-transaction state transition

MI_EVENT_END_STMT

End-of-statement state transition

MI_EVENT_END_SESSION

End-of-session state transition

To have the access method handle an error or a transaction rollback, use the DataBlade API mechanism of callback functions. A callback function automatically executes when the database server indicates that the event of a particular type has occurred.

To register an access-method callback function, pass the function name and the type of event that invokes the function to mi_register_callback(), as the example in Figure 5 shows.

typedef struct statement_data
{
...
...
   MI_CALLBACK_HANDLE *error_cback;
} statement_data_t;

/*Allocate memory*/
my_data = (statement_data_t *) 
   mi_dalloc(sizeof(statement_data_t),PER_STMT_EXEC);


my_data.error_cback=
   mi_register_callback(connection,
      MI_Exception, error_callback, NULL, NULL)

The example in Figure 5 accomplishes the following actions:

• Registers the error_callback() function as a callback function to handle the MI_Exception event
• Stores the callback handle that mi_register_callback() returns in the error_cback field of the my_data memory

For more information about detecting whether a transaction commits or rolls back, refer to Checking Isolation Levels.

By default, the database server aborts the execution of the access-method UDR if any of the following actions by the access method fails:

• Allocating memory
• Using the FastPath feature to execute a UDR
• Obtaining a handle for a file or smart large object
• Obtaining a connection
• Reading or writing to storage media, such as a disk

If you want to avoid an unexpected exit from the access method, register a callback function for any exception that you can anticipate. The callback function can roll back transactions and free memory before it returns control to the database server, or it can tell the database server to resume access-method processing.

For a complete discussion of callback processing and the DataBlade API mi_register_callback() function, refer to the IBM Informix: DataBlade API Programmer's Guide. For code samples, choose the DataBlade Corner from the list box on the IBM Informix Developer Zone at www.ibm.com/software/data/developer/informix.