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 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_STATEMENT);


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 mi_register_callback() function, see the HCL® Informix® DataBlade® API Programmer's Guide.