Informix DataBlade API Programmer's Manual DataBlade API Function Descriptions

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

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 the connection descriptor of a previous call to mi_open(), mi_server_connect(), or mi_server_reconnect() has established.
msg_type	is 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 values for each parameter marker in the message.

Valid in Client LIBMI Application?	Valid in User-Defined Routine?
Yes	Yes

The mi_db_error_raise() 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.

In a client LIBMI application, the conn parameter of mi_db_error_raise() must be 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).

The conn parameter can be either of the following values:

• A NULL-valued pointer indicates to raise the exception against the parent connection
• A valid connection descriptor for the connection against which to raise the exception

For more information, see Specifying the Connection.

You can use the mi_db_error_raise() function either to pass a literal message or to raise an SQL error or warning stored in the syserrors system catalog table. The msg_type parameter can contain one of the following values.

For example, the following call to mi_db_error_raise() raises an MI_Exception event with an exception level of MI_MESSAGE, an SQLSTATE value of "01U01", and the "Operation Successful " warning message:

mi_db_error_raise(conn, MI_MESSAGE, "Operation Successful");

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 syserrors system catalog table stores the text of custom error and warning messages along with their five-character SQLSTATE value. A DataBlade module can store module-specific error and warning messages in syserrors.

The locale column of the syserrors system catalog table is used for the internationalization of error and warning messages. Using the syserrors catalog table is recommended to maintain language independence of messages. For more information on internationalized exception messages, see the Informix Guide to GLS Functionality.

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.

See the descriptions of the following functions: mi_default_callback(), mi_errmsg(), mi_error_desc_copy(), mi_error_desc_destroy(), mi_error_desc_is_copy(), mi_error_level(), mi_error_sql_state(), and mi_register_callback().

For more information on how to raise exceptions, see Raising an Exception.