Callback functions

Database server events include the following types.

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 the following figure shows.

Figure 1. Register a callback function

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 the preceding figure 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

By default, the database server stops 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, see the HCL Informix® DataBlade API Programmer's Guide.