Handling errors from DataBlade API functions

Function descriptions in the Informix® DataBlade® API Function Reference contain a section titled Return Values. This section lists the possible return values for the associated DataBlade API function. However, whether the calling code actually receives a return value depends on whether the DataBlade API function throws an MI_Exception event when it encounters a runtime error. The DataBlade API functions can be divided into the following subsets based on their response to a database server exception:
  • Functions that throw an MI_Exception event
  • Functions that do not throw an MI_Exception event but provide either MI_ERROR or a NULL-valued pointer when a database server exception occurs
  • Functions that can raise an error when a database server exception occurs

Functions that throw MI_Exception event

Most DataBlade API functions throw an MI_Exception event when they encounter a database server exception. For these functions, you can register an exception callback to gain control after a database server exception occurs. Whether the calling code receives a return value from the DataBlade API function depends on how the registered callback handles the MI_Exception event.
Tip: Even if you expect a DataBlade API function to throw an error, the exception handling might possibly ignore it. Therefore, it is recommended that you always check the return value of each DataBlade API function for possible failure.

Functions that return MI_ERROR or NULL-valued pointer

The DataBlade API functions that do not throw an MI_Exception event when they encounter a database server exception include the following functions:
  • DataBlade API file-access functions: mi_file_allocate(), mi_file_close(), mi_file_errno(), mi_file_open(), mi_file_read(), mi_file_seek(), mi_file_sync(), mi_file_tell(), mi_file_to_file(), mi_file_unlink(), and mi_file_write()
  • Memory-allocation functions: mi_alloc(), mi_dalloc(), mi_realloc(), and mi_zalloc()
When one of the preceding DataBlade API functions encounters an exception, the function does not cause any callbacks registered for the MI_Exception event to be invoked. Instead, these functions return one of the following values to the calling code to indicate failure:
  • MI_ERROR, if the function returns an integer value
  • NULL-valued pointer, if the function returns a pointer
The calling code must check the return value of the DataBlade API function and take the appropriate actions. Uncorrected error conditions might lead to worse failures later in processing. For conditions that cannot be corrected, the calling code can provide an informational message to notify the user about what has occurred. The calling code can use the mi_db_error_raise() function to perform the following tasks:
  • Explicitly raise an MI_Exception event
  • Send a message to the client application