Handling errors from DataBlade API functions
Function descriptions in the IBM®
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