The mi_db_error_raise() function

The mi_db_error_raise() function raises an error or warning and sends the message to the calling program.

Syntax

mi_integer mi_db_error_raise (conn, msg_type, msg, optional_parameters)
   MI_CONNECTION *conn;
   mi_integer msg_type;
   char *msg;
   optional_parameters;
conn
is either a NULL-valued pointer or a pointer to a connection descriptor established by a previous call to mi_open(), mi_server_connect(), or mi_server_reconnect().
msg_type
A message-type constant: MI_MESSAGE, MI_EXCEPTION, or MI_SQL.
msg
If msg_type is MI_MESSAGE or MI_EXCEPTION, the msg value is the text of the message to pass.

If msg_type is MI_SQL, the msg value is the five-character SQLSTATE value that represents the error or warning in the syserrors system catalog table, followed by a null terminator.

optional_parameters
If msg_type is MI_SQL and the text of the error or warning message requires parameters, mi_db_error_raise() accepts a value for each parameter marker in the message.
Valid in client LIBMI application? Valid in user-defined routine?
Yes Yes

Usage

The mi_db_error_raise() function raises an MI_Exception event to the database server. If the DataBlade® API program registers a callback function to handle MI_Exception events, the database server invokes this callback. By default, the client application receives any messages that mi_db_error_raise() raises, regardless of how the exception is raised on the database server.

Server only: The conn parameter can be either of the following values:
  • A NULL-valued pointer, which tells the database server to raise the exception against the parent connection
  • A pointer to a valid connection descriptor for the connection against which to raise the exception
Client only:

In a client LIBMI application, the conn parameter of mi_db_error_raise() must point to a valid connection descriptor. When a client LIBMI application invokes the mi_db_error_raise() function, the exception is passed to the database server for processing. If the client LIBMI application has not registered a callback for MI_Exception, the database server executes the system-default callback (which the mi_default_callback() function implements).

For more information, see the Informix® DataBlade® API Programmer's Guide.

The mi_db_error_raise() function can either pass a literal message or raise an SQL error or warning stored in the syserrors system catalog table. The msg_type parameter can contain one of the following values.
MI_MESSAGE
The mi_db_error_raise() function raises a warning (an MI_Exception event with an exception level of MI_MESSAGE) with the msg warning message.
MI_EXCEPTION
The mi_db_error_raise() function raises an error (an MI_Exception event with an exception level of MI_EXCEPTION) with the msg error message.
MI_SQL
The mi_db_error_raise() function raises an exception with a custom message from the syserrors system catalog table whose SQLSTATE value is in msg.

For more information about how to use custom messages, see the Informix® DataBlade® API Programmer's Guide.

For GLS, the locale column of the syserrors system catalog table is used for the internationalization of error and warning messages. It is recommended that you use the syserrors catalog table to maintain language independence of messages. For more information about internationalized exception messages, see the Informix® GLS User's Guide.

For the following line, mi_db_error_raise() raises an MI_Exception event with an exception level of MI_EXCEPTION, an SQLSTATE value of "U0001", and the "Out of Memory!!! " error message: 
mi_db_error_raise(conn, MI_EXCEPTION, "Out of Memory!!!");
The following call to mi_db_error_raise() returns the predefined SQL message that is associated with an SQLSTATE value of "03I01" and has no markers:
mi_db_error_raise (conn, MI_SQL, "03I01", NULL);

Custom messages can contain parameter markers, whose values the optional_parameters parameter specifies. The optional_parameters parameter list specifies a pair of values for each parameter marker in the message and is terminated with a NULL-valued pointer.

For more information about how to raise exceptions, see the Informix® DataBlade® API Programmer's Guide.

Return values

MI_OK
The function was successful.
MI_ERROR
The function was not successful, with the following exception: when used in UDRs to raise fatal errors that are not handled, it does not return control to the calling function.