Client LIBMI Errors

Home | Previous Page | Next Page Database Access > Handling Exceptions and Events >

Client LIBMI Errors

The DataBlade API throws the MI_Client_Library_Error event to indicate an error in the client LIBMI library. The MI_Client_Library_Error event indicates the type of error that has occurred with one of the error levels that Table 72 shows.

Table 72. Client LIBMI Error Levels
Error Level	Description
MI_LIB_BADARG	Raised when a DataBlade API function receives an incorrect argument, such as a bad connection descriptor or a NULL value where a pointer is required
MI_LIB_BADSERV	Raised when the DataBlade API client library is unable to connect to a database server
MI_LIB_DROPCONN	Raised when the DataBlade API client library has lost the connection to the database server
MI_LIB_INTERR	Raised when an internal DataBlade API error occurs
MI_LIB_NOIMP	Raised when the called function or feature has not yet been implemented
MI_LIB_USAGE	Raised when a DataBlade API function is called out of sequence; for example, a call to mi_next_row( ) occurs when the statement did not return row data

To handle a client LIBMI error

Write a callback that handles the MI_Client_Library_Error event.
To handle an MI_Client_Library_Error event, you can write either of the following types of callback function:
- A client LIBMI callback executes only when the MI_Client_Library_Error event occurs.
- An all-events callback executes when many events occur and can include handling for the MI_Client_Library_Error event.
Register the callback function that handles the MI_Client_Library_Error event in the client LIBMI application that requires the error handling.
Use the mi_register_callback( ) function to register callback functions. After you register a callback that handles the MI_Client_Library_Error event, the client LIBMI invokes this callback instead of performing its default error handling.

Write a callback that handles MI_Client_Library_Error when you need to provide special handling for one or more client LIBMI errors, which Table 72 shows. Within the callback, the mi_error_level( ) function returns the error level for the client LIBMI error. You can also use the following DataBlade API functions to get more details about the client LIBMI error from its error descriptor:

The mi_error_sql_state( ) function returns an SQLSTATE value of "IX000" to indicate an Informix-specific error.
The mi_error_sqlcode( ) function returns the Informix-specific error.
The mi_errmsg( ) function returns the error message text.

For more information, see Accessing an Error Descriptor.

Important:

Client LIBMI callbacks are subject to some restrictions on what tasks they can perform. For more information, see Writing a Callback Function.

The following sample code uses special-purpose handlers (not shown) to handle messages (message_handler( )) and database server exceptions (exception_handler( )). The message_handler( ) routine might simply display a message on standard error, while the other handlers could take some specific user-defined action based on the type of exception.

/* This routine dispatches callback events for the following
 * events:
 *     MI_Exception (client-side & server-side),
 *     MI_Client_Library_Error (client-side only)
 *     MI_Xact_State_Change (client-side only)
 */
#include "mi.h"
 
MI_CALLBACK_STATUS MI_PROC_CALLBACK
all_callback(event_type, conn, event_data, user_data)
   MI_EVENT_TYPE event_type;
   MI_CONNECTION *conn;
   void *event_data;
   void *user_data;
{
   mi_integer elevel;
   char err_msg[200];
   char *msg;

   switch ( event_type )
      {
      /* A database server exception calls a special-purpose
      ** handler to handle a message (warning) or an
      ** exception. */

      case MI_Exception:
         /* Obtain exception level from event */
         elevel = mi_error_level(event_data);

         switch ( elevel )
            {
            case MI_MESSAGE:
               message_handler(event_data, user_data);
               break;
            case MI_EXCEPTION:
               exception_handler(event_data,
                  user_data);
               break;
            }
         break;

      /* A client LIBMI error is any type of internal
      ** client-library error, library-usage problem, or
      ** a dropped connection. */
      case MI_Client_Library_Error:
         /* Obtain error level from event */
         elevel = mi_error_level(event_data);

         switch ( elevel )
            {
            case MI_LIB_BADARG:
               msg = "MI_LIB_BADARG";
               break;

            case MI_LIB_USAGE:
               msg = "MI_LIB_USAGE";
               break;

            case MI_LIB_INTERR:
               msg = "MI_LIB_INTERR";
               break;

            case MI_LIB_NOIMP:
               msg = "MI_LIB_NOIMP";
               break;

            case MI_LIB_DROPCONN:
               msg = "MI_LIB_DROPCONN";
               break;

            default:
               msg = "UNKNOWN";
               break;
            }
         mi_errmsg(event_data, err_msg, 200);
         fprintf(stderr, "%s: %s\n", msg, err_msg);
         break;

      /* A transaction-state-change event occurs whenever
      ** the client LIBMI module begins or ends a
      ** transaction block. */
      case MI_Xact_State_Change:
         {
         mi_integer  change_type;

         /* Obtain transition type from event */
         change_type = mi_transition_type(event_data);

         switch ( change_type )
            {
            case MI_BEGIN:
               msg = "Transaction started.";
               break;

            case MI_NORMAL_END:
               msg = "Transaction committed.";
               break;

            case MI_ABORT_END:
               msg = "Transaction aborted!";
               break;

            default:
               msg = "Unknown transaction type!";
               break;
            }
         fprintf(stderr, "%s\n", msg);
         break;
         }

      /* No other types of events are expected here,
       * although they could happen. Let the user know
       * what happened and continue.
       */
      default:
         fprintf(stderr, 
            "Caught an unexpected event type.\n");
         break;
      }
   return MI_CB_CONTINUE;
}

Server Only

The all_callback( ) callback returns a status of MI_CB_CONTINUE when it is invoked from a C UDR. Therefore, the database server would check for additional callbacks that are registered for the event once it completed execution of all_callback( ). If no additional callbacks existed, the database server would abort the UDR.

End of Server Only