DataBlade API Programmer's Manual

DataBlade API Programmer's Manual
Chapter 12: DataBlade API Function Descriptions

Home Contents Index Master Index New Book

mi_db_error_raise()

The mi_db_error_raise() function raises an error or warning.

Syntax

mi_integer mi_db_error_raise (conn, msg_type, msg, optional_parameter...)

		MI_CONNECTION *conn;

		mi_integer msg_type;

		char *msg;

		...; 


conn
is the connection descriptor established by a previous call to mi_open() or mi_server_connect(). The conn parameter should be set to NULL in a call to mi_db_error_raise() from a server function or to a valid connection opened by the current user-defined routine to raise an exception on that specific connection.

msg_type
is MI_MESSAGE, MI_EXCEPTION, or MI_SQL. 

msg
If msg_type is not MI_SQL, 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.


If msg_type is MI_SQL and the text of the error or warning message requires parameters, mi_db_error_raise() requires a pair of values for each parameter marker in the message. The first member of the pair is a null-terminated string that represents the name and format of the parameter in the following form:


name%format







 



Valid in Client Application?

Valid in Server Routine?

Yes
Yes

The following formats are supported.


Format	Meaning
`d`	integer
`f,g,G,e,E`	double (by reference)
`T`	text (lvarchar type, that is, a pointer to mi_lvarchar)
`t`	length followed by string (two separate parameters)
`s`	null-terminated C string

The second member of the pair is the value of the parameter.

Important: Terminate the parameter list arguments with a NULL pointer. If a NULL pointer does not terminate the list, the results are unpredictable.

Usage

The mi_db_error_raise() function can be invoked from either a client function or a server function. If it is invoked from a client function, the exception is passed to the database server for processing.

When mi_db_error_raise() is called, it signals an MI_Exception event. If the application has assigned a specific callback function to handle MI_Exception events, this callback is called. If no callback has been registered for MI_Exception conditions, DataBlade API uses the client default handler to handle the message.

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 syserrors table stores the text of error and warning messages along with their five-character SQLSTATE value.

If mi_db_error_raise() is used to return a literal message string, msg_type is MI_MESSAGE (a warning) or MI_EXCEPTION (an error), and msg contains the text of the message.

For example, both of the following lines return a message to the user:

mi_db_error_raise(conn,MI_MESSAGE,"Operation Successful");
mi_db_error_raise(conn,MI_EXCEPTION,"Out of Memory!!!");

For the first line, the database server sets the SQLSTATE value to 01U01 and the message text to Operation Successful. For the second line, the database server sets the SQLSTATE value to U0001 and the message text to Out of Memory!!! For more information about how Universal Server handles message text, see the Informix Guide to SQL: Syntax.

Important: In a server function, the MI_EXCEPTION flag directs the database server to abort current function processing and halt processing on the current SQL expression.The following example illustrates how the MI_EXCEPTION directive aborts a server function:

void MI_PROC_VACALLBACK
my_function()
{
	... Processing ... 
	if (error_cond) {
		... do any cleanup here ... 
		mi_db_error_raise ((MI_CONNECTION *)NULL,
			MI_EXCEPTION, "Fatal Error In my_function.");
	}
	... These lines never get reached ... 
}

If mi_db_error_raise() is used to return a predefined SQLSTATE value, defined in the syserrors system catalog table, the following actions occur:

The msg_type parameter is set to MI_SQL.
The msg parameter stores a five-character, predefined SQL return code.
Values specified in parameter pairs can replace markers in the SQL error or warning message.
The function passes in NULL to terminate the list of optional_parameter_pairs values.

The query select * from syserrors; retrieves the current list of available SQL message strings. The locale column is used for the internationalization of error and warning messages.

For example, a function call follows to return a predefined SQL message that has no markers:

mi_db_error_raise (conn, MI_SQL, "03I01", NULL);

This returns the message Operation Interrupted.

To return a predefined SQL message that has one or more markers (text of the form %NAME%), you can specify values in parameter pairs to replace the markers with custom text.

For example, assume that the following message is under 2AM10 in the syserrors table:

"Line %LINE%: Syntax error at '%TOKEN%':%CMD%"

The code to return the message follows:

mi_db_error_raise (conn, MI_SQL, "2AM10",
"TOKEN%s", "select",
		/* replace TOKEN marker with selecl */
"LINE%d", (mi_integer)500,
		/* replace LINE marker with 500 */
"CMD%s", "select * from tables;",
	/* replace CMD marker with query */
NULL);	/* terminate list */

This code returns the following message:

"Line 500: Syntax error at 'select':select * from tables;"

The code TOKEN%s indicates that the marker %TOKEN% should be replaced with the string "select" passed as the next argument. Parameter pairs do not have to be in the same order as the markers in the string.

Any supplied message text or message parameter strings are assumed to be in the database locale.

Parameter markers of the form %NAME% are assumed to be in single-byte ASCII characters only, to ensure that the markers will be independent of the locale used for the message.

Using the syserrors catalog table is recommended to maintain language independence.

Return Values

MI_OK
The function was successful.

MI_ERROR
The function was not successful. However, when this function is used in server functions to raise fatal errors that are not handled, the function does not return control to the calling function

DataBlade API Programmer's ManualChapter 12: DataBlade API Function Descriptions Home Contents Index Master Index New Book

mi_db_error_raise()

Syntax

Usage

Return Values MI_OK The function was successful. MI_ERROR The function was not successful. However, when this function is used in server functions to raise fatal errors that are not handled, the function does not return control to the calling function

Related Topics

DataBlade API Programmer's Manual
Chapter 12: DataBlade API Function Descriptions

Home Contents Index Master Index New Book

Return Values

MI_OK
The function was successful.

MI_ERROR
The function was not successful. However, when this function is used in server functions to raise fatal errors that are not handled, the function does not return control to the calling function