Informix DataBlade API Programmer's Manual Handling Exceptions and Events

When the database server or a user-defined routine raises a database server exception, the DataBlade API invokes any callbacks that are registered for the exception. This section provides information about exception handling in DataBlade API modules:

• An explanation of database server exceptions
• How to handle a database server exception in a user-defined routine and in a client LIBMI application
• How to return error information to the calling code
• How to handle errors that generate multiple exceptions
• How to explicitly raise a database server exception

A database server exception is an unexpected condition that occurs within the database server. A database server exception can occur in any of the following tasks:

• Within an SQL statement

The mi_exec() and mi_exec_prepared_statement() functions execute SQL statements. An exception can occur when the database server executes an SQL statement.

• Within a UDR

The mi_routine_exec() function executes UDRs through the Fastpath interface. An exception can occur when this UDR executes.

• By the DataBlade API function, mi_db_error_raise()

The mi_db_error_raise() function can explicitly raise a database server exception within a DataBlade API module. For more information, see Raising an Exception.

• Within the execution of some other DataBlade API function

Other functions in the DataBlade API might raise exceptions when they execute.

When the database server encounters a database server exception, it raises the MI_Exception event.

The MI_Exception event indicates which of the following status conditions has caused the database server exception:

• A warning is a condition that does not prevent successful execution of an SQL statement; however, the effect of the statement is limited and the statement might not produce the expected results.
• A runtime error (or failure) indicates that the SQL statement or DataBlade API function did not execute successfully and it made no change to the database.

Runtime errors can occur at the following levels:

• Hardware errors include controller failure, bad sector on disk, and so on.
• Kernel errors include file-table overflow, insufficient semaphores, and so on.
• Access-method errors include duplicated index keys, SQL null inserted into non-null columns, and so on.
• Parser errors include invalid syntax, unknown objects, invalid statements, and so on.
• DataBlade API library errors are usually caused by invalid arguments.

The following list describes the most common DataBlade API library errors:

• The DataBlade API might not have been initialized.
• One of the DataBlade API initialization functions must be the first DataBlade API call in the module. For more information, see Initializing the DataBlade API.
• A function that passes a connection descriptor (MI_CONNECTION) passes an invalid connection, one that was closed or dropped.
• A function that passes a row descriptor (MI_ROW_DESC) can pass an invalid row descriptor.
• A function that passes a row structure (MI_ROW) passes an invalid row.
• A function that passes a column name passes a column name that does not exist in the object or objects being accessed.
• A function that passes a column number passes a column number that is out of range (greater or less than the number of columns in the object).
• A function that passes an event type (MI_EVENT_TYPE) passes a nonexistent event type.
• A function that passes a save set (MI_SAVE_SET) passes an invalid save set.
• A function that passes a buffer passes a null buffer or a buffer that is too small.
• A function that passes a pointer passes an invalid pointer.
• If the pointer_checks_enabled field of the parameter information structure is set, a pointer might not be within the process heap space.

Potential exceptions other than these types of common invalid arguments are mentioned in the Return Values section of the individual function descriptions in Chapter 15, DataBlade API Function Descriptions.

An error descriptor for an MI_Exception event indicates the status condition of the event with one of the following exception levels.

The mi_error_level() function returns the exception level from an error descriptor for the MI_Exception event.

To identify the particular cause of an exception, the database server sets the following status variables:

• The SQLSTATE status variable holds a five-character code that is compliant with ANSI and X/Open standards.
• The SQLCODE status variable holds an integer value that is Informix specific.

SQLSTATE is a five-character string that the database server sets after it executes each DataBlade API function. The value of SQLSTATE indicates the status of the function execution.

The SQLSTATE status variable is compliant with ANSI and X/Open standards.

This five-character code consists of a two-character class code and a three-character subclass code. In Figure 10-6, "IX" is the class code and "000" is the subclass code. The SQLSTATE value "IX000" indicates that an Informix-specific error has occurred.

Figure 10-6 The Structure of the SQLSTATE Code with the Value "IX000"

SQLSTATE can contain only digits and capital letters. The class code is unique but the subclass code is not. The meaning of the subclass code depends on the associated class code. The initial character of the class code indicates the source of the exception, as Figure 10-7 summarizes.

After the database server executes a DataBlade API function, it sets SQLSTATE to indicate one of the status conditions, as Figure 10-8 shows.

"000" to "006"

"I01" to "I11"

For a list of reserved ANSI and X/Open values for SQLSTATE, see the description of the GET DIAGNOSTICS statement in the Informix Guide to SQL: Syntax. For more information on DataBlade API literal exceptions ("U0001" and "01U01"), see Passing Literal Messages. For more information on DataBlade API custom exceptions, see Raising Custom Messages.

When the database server executes a DataBlade API function successfully, but encounters a warning condition, it:

• Sets the class code of SQLSTATE to "01".
• Sets the subclass code of SQLSTATE to a unique value that indicates the cause of the warning (see Figure 10-8 on page 10-34).
• Throws an MI_Exception event with an MI_MESSAGE exception level.

When an SQL statement results in a runtime error, the database server:

• Sets the class code of SQLSTATE to a value greater than "02" (see Figure 10-8 on page 10-34).
• Sets the subclass code of SQLSTATE to a unique value that indicates the cause of the error.
• Raises an MI_Exception event with an MI_EXCEPTION exception level.

The actual class and subclass codes of SQLSTATE identify the particular error. For Informix-specific errors (SQLSTATE is "IX000"), you can also check the value of the SQLCODE variable to identify the an error.

Tip: The database server sets SQLSTATE to "02000" (class = "02") when a SELECT or FETCH statement encounters NOT FOUND (or END OF DATA). However, the NOT FOUND condition does not cause a database server exception. Therefore, you do not use SQLSTATE to detect this condition from within a callback of a DataBlade API module. Instead, your DataBlade API module can check for the MI_NO_MORE_RESULTS return code from the mi_get_result() function. For more information, see Retrieving Query Data. SQLCODE Status Value

Each SQLSTATE value also has an associated Informix-specific status code. The database server saves this Informix-specific status code in the SQLCODE status variable. The SQLCODE variable is an integer that indicates whether the SQL statement succeeded or failed.

When the database server executes an SQL statement, the database server automatically updates the SQLCODE variable. After an SQL statement executes, the SQLCODE variable can indicate one of the status conditions that Figure 10-9 shows.

Identifying Warnings With SQLCODE

When the database server executes an SQL statement successfully, but encounters a warning condition, it:

• Sets the SQLSTATE variable to a five-character warning value.
• Sets the SQLCODE variable to zero (success).
• Raises the MI_Exception event with the MI_MESSAGE exception level.

To identify warnings, examine the value of SQLSTATE. The SQLCODE value does not indicate the cause of a warning. For more information, see Identifying Warnings With SQLSTATE.

When an SQL statement results in a runtime error, the database server:

• Sets SQLCODE to a negative value.
• Raises an MI_Exception event with an MI_EXCEPTION exception level.

The actual number in SQLCODE identifies the particular Informix runtime error. The Informix Error Messages manual lists these Informix-specific error codes and their corrective actions. You can also use the command-line finderr utility to obtain information about an Informix error. For more information about finderr, see the Informix Error Messages manual.

Tip: The database server sets SQLCODE to 100 when a SELECT or FETCH statement encounters NOT FOUND (or END OF DATA). However, the NOT FOUND condition does not cause a database server exception. Therefore, you do not use SQLCODE to detect this condition from within a callback of a DataBlade API module. Instead, your DataBlade API module can check for the MI_NO_MORE_RESULTS return code from the mi_get_result() function. For more information, see Retrieving Query Data.

Providing Exception Handling

By default, the DataBlade API aborts the current statement when the statement generates a database runtime error and continues execution when the statement generates a database warning. (For more information, see Using Default Behavior.)

To override the default exception handling, you must:

• Write a callback function that handles the MI_Exception event.

To handle an MI_Exception event, you can write either of the following types of callback function:

• An exception callback executes only when the MI_Exception event occurs.
• An all-events callback executes when many events occur and can include handling for the MI_Exception event.

Within the callback, the DataBlade API function mi_error_level() returns the exception level for the database server exception. You can also use mi_error_sql_state(), mi_error_sqlcode(), and mi_errmsg() to get more details about the database server exception from its error descriptor. For more information, see Accessing an Error Descriptor.

• Register the callback that handles the MI_Exception event in the DataBlade API module that needs the exception handling.

Use the mi_register_callback() function to register callback functions. Once you have registered a callback that handles the MI_Exception event, the DataBlade API invokes this callback instead of performing its default exception handling.

Important: Exception callbacks are subject to some restrictions on what tasks they can perform. For more information, see Writing the Callback Function.

A database server exception only triggers an exception callback if the DataBlade API module has registered (and enabled) a callback that handles the MI_Exception event. The way that your DataBlade API module handles a database server exception depends on whether the DataBlade API module is a user-defined routine or a client LIBMI application.

If the C UDR has not registered an exception callback on the current connection, the DataBlade API takes a default action based on the exception level of the MI_Exception event. (For more information, see Default Behavior In a C UDR.)

For example, in Figure 10-10, the return statement never executes when a runtime error occurs in the SQL statement that mi_exec() executes.

Figure 10-10 A C UDR With Default Exception Handling

When an exception with an MI_EXCEPTION exception level occurs, the DataBlade API aborts the mi_exec() call and the no_exception_handling() routine. The database server returns control to the calling module. The calling module might have a registered callback (or some other method) to handle the exception.

To provide event handling for database server exceptions within a UDR, perform the following tasks:

• Determine if a callback can handle the runtime error.
• In the UDR, register a callback that handles the MI_Exception event.
• In the callback function, return a value that determines how to continue the exception handling once the callback completes.

The function descriptions in Chapter 15, DataBlade API Function Descriptions, contain a section entitled 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.

Most DataBlade API functions throw an MI_Exception event when they encounter a database server exception. Therefore, you can get control after a database server exception occurs in a DataBlade API function by registering a callback that handles MI_Exception. Whether the calling code receives a return value from the DataBlade API function depends on how the registered callback handles the MI_Exception event.

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_to_large_object(), mi_file_unlink(), and mi_file_write()
• Memory-allocation functions: mi_alloc(), mi_dalloc(), 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, if possible, correct the condition. Uncorrected error conditions might lead to worse failures later in processing. For conditions that cannot be corrected, the calling code might want to provide an informational message to notify the user 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

Tip: Even if you expect a DataBlade API function to throw an error, the exception handling might possibly ignore it. Therefore, Informix recommends that you always check the return value of a DataBlade API function for possible failure.

When the database server or a UDR raises a database server exception, the database server invokes any callbacks that handle the MI_Exception event and that the UDR has registered (and enabled) on the current connection. Use the mi_register_callback() function to register such a callback. For general information about mi_register_callback(), see Registering a Callback.

The code fragment in Figure 10-11 contains the same mi_exec() call as Figure 10-10 on page 10-38. However, this UDR, has_exception_handling(), registers the excpt_callback() function as an exception callback.

Figure 10-11 A C UDR with Exception Handling

When the database server exception occurs in the SQL statement that mi_exec() executes, mi_exec() returns MI_ERROR and the if statement handles the exception. For a sample implementation of the excpt_callback() callback function, see Figure 10-12 on page 10-44.

For the excpt_callback() function to be invoked on database exceptions that occur on the current connection, you must specify the connection descriptor of the current connection when you register excpt_callback(). Therefore, in Figure 10-11, mi_register_callback() passes the conn connection descriptor, which the mi_open() call has obtained, when it registers excpt_callback().

However, the mi_open() function can be resource intensive. If your UDR is likely to be executed many times in the context of a single SQL statement, you might want to cache the connection descriptor from the initial mi_open() call in an MI_FPARAM structure. Once you save this descriptor, you can reuse it in subsequent invocations of the UDR.

The following C UDR, has_exception_handling2(), saves the connection descriptor in its MI_FPARAM structure the first time it is called and obtains the saved connection descriptor on subsequent calls:

mi_integer

has_exception_handling2(flag, fparam)

	mi_integer flag;

	MI_FPARAM *fparam;

{

	MI_CONNECTION *conn = NULL;

	MI_CALLBACK_HANDLE *cback_hndl;

	DB_ERROR_BUF error;



	/* Obtain the connection descriptor from MI_FPARAM */

	conn = (MI_CONNECTION *)mi_fp_funcstate(fparam);

	if ( conn == NULL ) /* first time routine is called */

		{

		/* Obtain the connection descriptor */

		conn = mi_open(NULL, NULL, NULL);



		/* Register the 'excpt_callback2() function as an

		** exception callback on this connection */

		cback_hndl = mi_register_callback(conn, MI_Exception,

			excpt_callback2, (void *)&error, NULL);



		/* Save connection descriptor in MI_FPARAM */

		mi_fp_setfuncstate(fparam, (void *)conn);

		}
	

}

For more information on the MI_FPARAM structure and the user state, see Saving a User State.

In the preceding code fragment, the has_exception_handling2() routine registers the excpt_callback2() function as its exception callback. This callback uses a user-provided buffer to store event information. As its fourth argument, the mi_register_callback() call passes a user-defined buffer called error to the exception callback. For more information, see Returning Error Information to the Caller.

The return value of an exception callback tells the database server how to continue handling a database server exception once the callback completes. An exception callback for a UDR must return one of the MI_CALLBACK_STATUS values that Figure 10-3 on page 10-20 lists.

To indicate that the callback function executes instead of the default exception handling, an exception callback function returns the MI_CB_EXC_HANDLED status. This return status tells the DataBlade API that the actions of the callback have completely handled the exception.

An exception callback function returns the MI_CB_EXC_HANDLED status to indicate that the callback has completely handled the exception. That is, the actions of the callback have provided the exception handling. When the DataBlade API receives the MI_CB_EXC_HANDLED return status, it does not perform its default exception handling. It assumes that the callback has executed instead of the default exception handling. (For more information, see Default Behavior In a C UDR.)

When a callback returns MI_CB_EXC_HANDLED, the DataBlade API does not propagate the exception up the calling sequence. Therefore, a client application that has executed an SQL expression that contains a UDR does not receive an error from the execution of the UDR (unless the callback uses a user-provided error buffer). If the SQL expression contains no other exceptions, the client application would have an SQLSTATE value of 00000 (success).

Figure 10-12 shows the excpt_callback() exception callback, which is written to handle the MI_Exception event. It returns MI_CB_EXC_HANDLED to indicate that no further exception handling is required.

Figure 10-12 A Simple Exception Callback

The excpt_callback() function in Figure 10-12 returns MI_CB_EXC_HANDLED, which prevents the DataBlade API from taking any further exception-handling steps, such as invoking other callbacks that handle MI_Exception or aborting the current statement. This callback executes instead of the default exception handling.

For the has_exception_handling() routine (which Figure 10-11 on page 10-41 defines), the DataBlade API takes the following steps when the mi_exec() function executes:

1. Execute the excpt_callback() callback when mi_exec() throws an exception.
2. Return control to the first statement in has_exception_handling() after mi_exec().

As a result, execution of the has_exception_handling() routine returns from the mi_exec() call with a return value of MI_ERROR.

Important: Because excpt_callback() returns MI_CB_EXC_HANDLED, the database server assumes that the MI_Exception event does not require any further handling. However, excpt_callback() does not actually take any exception-handling steps; it contains only a return statement to return an MI_CB_EXC_HANDLED status. In an actual DataBlade API module, you would probably want to add code to excpt_callback() that provides exception handling. Continuing With Exception Handling

To indicate that the callback function executes in addition to the default exception handling, an exception callback function returns the MI_CB_CONTINUE return status. This return status tells the DataBlade API that the actions of the callback have not completely handled the exception and that the DataBlade API should continue with its default exception handling. (For more information, see Default Behavior In a C UDR.) The actions of the callback provide supplemental exception handling.

If the excpt_callback() function in Figure 10-12 had returned MI_CB_CONTINUE, instead of MI_CB_EXC_HANDLED, the database server would handle the exception in the has_exception_handling() routine as follows:

1. Execute the excpt_callback() function when the mi_exec() call throws an exception.
2. Abort the mi_exec() call in has_exception_handling().
3. Return control back to the calling module that called has_exception_handling().

If has_exception_handling() was a user-defined routine in an SQL statement, the database server would abort the SQL statement and return control to the client application. The client application would be expected to handle the runtime error for the end user.

However, if has_exception_handling() was called by another C UDR that had registered an exception callback, the database server would have executed this callback and continued with the exception handling as the return status of this callback indicated (MI_CB_CONTINUE or MI_CB_EXC_HANDLED). If this callback also returned MI_CB_CONTINUE, the database server would continue up the calling sequence, looking for a registered callback that handled the MI_Exception event. If the database server reached the top-most level in the calling sequence (the UDR within an SQL statement) without locating an exception callback that returned MI_CB_EXC_HANDLED, the database server would abort the UDR and return control to the client application.

For more information on how to write a callback function for a UDR, see Creating a Callback Function.

Tip: The MI_Exception event might overlap with the MI_EVENT_END_STMT and MI_EVENT_END_XACT events because an exception always causes either a statement or a transaction to abort. Design the corresponding callbacks with this relationship in mind.

Exceptions In a Client LIBMI Application

If the client LIBMI application has not registered a callback that handles the MI_Exception event on the current connection, the client LIBMI calls the system-default callback. (For more information, see Default Behavior In Client LIBMI Applications.)

To provide event handling for database server exceptions within a client LIBMI application, register a callback that handles the MI_Exception event in the client LIBMI application. The DataBlade API invokes any exception callback that the application has registered (and enabled) on the current connection when either of the following actions occurs:

• A client LIBMI application executes a DataBlade API function that throws an MI_Exception event.
• An exception occurs in a UDR that is invoked from a statement in the client LIBMI application and any exception callbacks that the UDR has registered return the MI_CB_CONTINUE return status.

The function descriptions in Chapter 15, DataBlade API Function Descriptions, contain a section entitled Return Values. This section lists the possible return values for the associated DataBlade API function. In a C UDR, DataBlade API function calls might or might not return a value, depending on whether the DataBlade API function throws an MI_Exception event when it encounters a runtime error. However, DataBlade API function calls in a client LIBMI application always indicate failure because client-side callbacks always return to the DataBlade API function that generated the error.

On failure, DataBlade API functions return one of the following values to a client LIBMI application:

• MI_ERROR if the return value is an integer
• NULL if the return value is a pointer.

The client LIBMI application can check for these error values and take any appropriate actions.

The client LIBMI application registers callbacks with the mi_register_callback() function. You must provide a valid connection descriptor to mi_register_callback() for all valid event types. For more information, see Registering a Callback.

For example, the following mi_register_callback() call registers the clntexcpt_callback() function to handle MI_Exception events:

int main (argc, arcv)
	int argc;
	char *argv;
{
	MI_CONNECTION *client_conn;
	MI_CALLBACK_HANDLE *client_cback;
	mi_integer ret;

/* Open a connection to the database server */
client_conn = mi_open(argv[1], NULL, NULL);

/* Register the exception callback */
client_cback = mi_register_callback(client_conn,
	MI_Exception, (MI_VOID *)clntexcpt_callback, NULL, NULL);
if ( client_cback == NULL )
	/* do something appropriate */


ret = mi_exec(client_conn, "bad SQL statement",
	MI_QUERY_NORMAL);
if ( ret == MI_ERROR )
	/* perform error recovery */


}

For more information about how to write a callback function for a client LIBMI application, see Creating a Callback Function.

The fourth argument of a callback function is a pointer to user data. The user data is a C variable or structure that contains application-specific information that a callback can use. You pass the user data to a callback when you register the callback with the mi_register_callback() function. The fourth argument of mi_register_callback() provides a pointer to the user data (see Figure 10-4 on page 10-22).

One of the most common uses of user data is a user-defined error structure. When a callback handles exceptions, DataBlade API functions return either MI_ERROR or NULL on failure. This information is often not specific enough for the calling code to determine the cause of the error. You can create a user-defined error structure to pass more specific error information back to the calling code, as follows:

1. The calling code defines and allocates a user-defined error structure.
2. The callback function populates the user-defined structure with error information.

The calling code can define a user-defined error structure to hold error information. This user-defined structure can be a single C variable or a structure with several pieces of error information. It can contain as much error information as the calling code requires.

Figure 10-13 shows a sample user-defined error structure called DB_ERROR_BUF.

Figure 10-13 A Sample User-Defined Error Structure

The DB_ERROR_BUF structure holds the following error information.

The calling code must allocate memory for the user-defined error structure. You can use the DataBlade API memory-allocation functions such as mi_alloc() and mi_dalloc(). When you allocate the user-defined error structure, you must associate a memory duration with this structure that you declare that is appropriate to its usage. For example, if the user-defined error structure is to be associated with a registered callback, you must allocate the structure with a memory duration of PER_STATEMENT, so that this memory is still allocated when the callback executes.

The following mi_dalloc() call allocates a DB_ERROR_BUF buffer with a PER_STATEMENT memory duration:

mi_dalloc(sizeof(DB_ERROR_BUF), PER_STATEMENT);

The calling code can use one of the following ways to make a user-defined error structure available to a callback:

• Associate the user-defined structure with the callback.
• Associate the user-defined structure with the database connection.

To associate a user-defined error structure with the registered callback, specify the address of the structure as the fourth argument of mi_register_callback() function. The call to mi_register_callback() initializes the fourth parameter of the exception callback with a pointer to the user-defined structure. For more information, see Figure 10-4 on page 10-22.

The following func1() UDR registers a callback called excpt_callback2(), which puts error information in the DB_ERROR_BUF user-defined structure (which Figure 10-13 on page 10-48 defines):

void func1(flag)
	mi_integer flag;
{
	MI_CONNECTION *conn;
	MI_CALLBACK_HANDLE *cback_hndl;
	DB_ERROR_BUF error;

	/* Initialize information in the error buffer */
	error.sqlstate[0] = '\0';
	strcpy(error.error_msg, 
		"func3: initialized error buffer.");

	/* Obtain connection descriptor */
	conn = mi_open(NULL, NULL, NULL);
	if ( conn == NULL )
		mi_db_error_raise(NULL, MI_EXCEPTION, 
			"func1: mi_open() call failed!");

	/* Register the exception callback */
	cback_hndl = mi_register_callback(conn, MI_Exception,
			excpt_callback2, (void *)&error), NULL):

	/* Execute SQL statement */
		mi_exec(conn, "bad SQL statement", MI_QUERY_NORMAL);

	/* Execution does not reach this point if the
	** excpt_callback2() callback returns MI_CB_CONTINUE
	*/

The call to mi_register_callback() specifies the address of the user-defined structure as its fourth argument. This structure is, in turn, passed in as the third argument of the excpt_callback2() callback (see Figure 10-4 on page 10-22). The following code implements the excpt_callback2() callback function:

MI_CALLBACK_STATUS
excpt_callback2(event_type, conn, event_info, user_data)
	MI_EVENT_TYPE event_type;
	MI_CONNECTION *conn;
	void *event_info;
	void *user_data; /* user-defined error buffer gets
					** passed here */
{
	DB_ERROR_BUF *user_info;
	mi_integer state_type;
	mi_string *msg;

	user_info = ((DB_ERROR_BUF *)user_data);
	user_info->error_type = event_type;

	if ( event_type != MI_Exception )
		{
		user_info->sqlstate[0] = '\0';
		sprintf(user_info->error_msg,
			"excpt_callback2 called with wrong event type ",
			 "%d", event_type);
		}
	else /* event_type is MI_Exception */
		{
		mi_error_sql_state((MI_ERROR_DESC *)event_info,
			user_info->sqlstate, 6);
		mi_errmsg((MI_ERROR_DESC *)event_info,
			user_info->error_msg, MSG_SIZE-1);
		}

	return MI_CB_EXC_HANDLED;
}

Important: Make sure that you allocate the user-defined error structure with a memory duration that is compatible with the callback that uses it. Memory durations longer than PER_COMMAND do exist for use with end-of-statement, end-of-transaction, and end-of-session callbacks. However, these longer memory durations should be used only in limited cases. For more information, contact your Informix representative.

The following code fragment from a client LIBMI application registers a callback called clntexcpt_callback2() that puts error information in the DB_ERROR_BUF user-defined structure (which Figure 10-13 on page 10-48 defines).

int main (argc, argv)
	int argc;
	char **argv;
{
	MI_CONNECTION *conn = NULL;
	char stmt[300];
	MI_CALLBACK_HANDLE callback_hdnl;
	DB_ERROR_BUF error_buff;
	mi_integer ret;

	/* Open a connection to the database server */
	conn = mi_open(argv[1], NULL, NULL);
	if ( conn == NULL )
		/* do something appropriate */

	/* Register the exception callback, with the user-defined
	** error structure as the fourth argument to
	** mi_register_callback() */
	callback_hndl = mi_register_callback(conn, MI_Exception,
		(MI_VOID *) clntexcpt_callback2;
		(MI_VOID *) &error_buff, NULL);
	if ( callback_hndl == NULL )
		/* do something appropriate */
	

	/* Execute the SQL statement that 'stmt' contains */
	ret = send_statement(conn, stmt);
	/* If an exception occurred during the execution of the
	** SQL statement, the exception callback initialized the
	** 'error_buff' structure. Obtain error information from
	** 'error_buff'. */
	if ( ret == MI_ERROR )
		{
		if ( error_buff.error_type == MI_Exception )
			{
			if ( error_buf.error_level == MI_EXCEPTION )
				{
				fprintf(stderr, "MI_Exception: level = %d",
					error_buff.error_level);
				fprintf(stderr, "SQLSTATE='%s'\n",
					error_buff.sqlstate);
				fprintf(stderr, "message = '%s'\n",
					error_buff.error_msg);
				/* discontinue processing */
				}
			else /* error_level is MI_WARNING */
				{

				sprintf(warn_msg, "WARNING: %s\n", 
					error_buf.error_msg);
				display_msg(warn_msg);
				}
			}
		/* do something appropriate */
	

}

The call to mi_register_callback() specifies the address of the user-defined structure as its fourth argument. This structure is, in turn, passed in as the fourth argument of the clntexcpt_callback2() callback. The following code implements the clntexcpt_callback2() callback function.

void clntexcpt_callback2(event_type, conn, event_info,
		error_info)
	MI_EVENT_TYPE event_type;
	MI_CONNECTION *conn;
	void *event_info;
	void *error_info; /* user-defined error buffer here */
{
	DB_ERROR_BUF *error_buf = (DB_ERROR_BUF *)error_info;

	/* Fill user-defined structure with error information */
	error_buf->error_type = event_type;
	if ( event_type == MI_Exception )
		{
		error_buf->error_level = mi_error_level(event_info);
		mi_error_sql_state(event_info, error_buf->sqlstate,
			6);
		mi_errmsg(event_info, error_buf->error_msg,
			MSG_SIZE-1);
		}
	else
		fprintf(stderr,
			"Warning! clntexcpt_callback() fired for event ",
			"%d", event_type);
	return;
}

The clntexcpt_callback() function is an example of an exception callback for a client LIBMI application. This callback returns void because the client LIBMI does not interpret the MI_CALLBACK_STATUS return value, as does the database server for UDRs.

To associate a user-defined error structure with the connection, you:

• Use the mi_set_connection_user_data() function in the calling function to bind the structure to a connection descriptor (an MI_CONNECTION structure).
• Use the mi_get_connection_user_data() function in the callback to obtain the structure that is bound to the connection descriptor.

Important: You can associate a user-defined error structure with a connection only if a valid connection exists and this connection does not change between the point at which the callback is registered and the point at which the exception event occurs. If you cannot guarantee that these two conditions exist, associate the user-defined error structure with the registered callback (page 10-50).

The following code fragment from a client LIBMI application binds the DB_ERROR_BUF user-defined structure (Figure 10-13 on page 10-48) to a connection:

int main (argc, argv)
	int argc;
	char **argv;
{
	MI_CONNECTION *conn = NULL;
	MI_CALLBACK_HANDLE *cback_hndl;
	char query[300];
	mi_integer ret;
	DB_ERROR_BUF error_buff;

	conn = mi_open(argv[1], NULL, NULL);
	if ( conn == NULL )
		/* do something appropriate */

	cback_hndl = mi_register_callback(conn, MI_Exception,
		(MI_VOID)clntexcpt_callback2, NULL, NULL);
	ret = mi_set_connection_user_data(conn,
		(MI_VOID)&error_buff);
	if ( ret == MI_ERROR )
		/* do something appropriate */
	ret = send_command(conn, query);
	if ( ret == MI_ERROR)
		{
		fprintf(stderr, "MI_Exception: level = %d",
			error_buff.error_level);
		fprintf(stderr, "SQLSTATE='%s'\n",
			error_buff.sqlstate);
		fprintf(stderr, "message = '%s'\n",
			error_buff.error_msg);
		}
	/* do something appropriate */
	

}

The call to mi_register_callback() does not specify the address of the user-defined structure as its fourth argument because this structure is associated with the connection. The following code implements the clntexcpt_callback() callback function, which uses the mi_get_connection_user_data() function to obtain the user-defined structure:

void clntexcpt_callback2(event_type, conn, event_info,
		user_data)
	MI_EVENT_TYPE event_type;
	MI_CONNECTION *conn; /* user-defined error buffer here */
	void *event_info;
	void *user_data;
{
	DB_ERROR_BUF *error_buf

	mi_get_connection_user_data(conn, (void **)&error_buf)
	error_buf->error_type = event_type;
	if ( event_type == MI_Exception )
		{
		error_buf->error_level = mi_error_level(event_info);
		mi_error_sql_state(event_info, error_buf->sqlstate,
			6);
		mi_errmsg(event_info, error_buf->error_msg,
			MSG_SIZE-1);
		}
	else
		fprintf(stderr,
			"Warning! clntexcpt_callback2() fired for event "
			"%d", event_type);
	return;
}

In the preceding code fragment, the italicized portion is the only difference between this client LIBMI application and the one that registers a user-defined variable with the callback (in Associating with a Callback).

The database server can generate multiple exceptions for a single SQL statement. A single statement might generate multiple exceptions when any of the following conditions have occurred:

• Multiple warnings occur.
• Multiple details are associated with a single error occurrence.

For example, a DROP TABLE statement might set both the SQLCODE value and the ISAM error value. Similarly, nested user-defined routines might generate errors at many levels.

The database server normally calls a registered exception callback once for each exception message. If a single error causes multiple exceptions, you must use the following DataBlade API functions in the callback to process multiple messages in a single invocation.

A callback is not called again for any messages have already been processed. The database server presents exceptions from highest message level to lowest message level. Therefore, a UDR or SQL message occurs first, followed by any ISAM message.

The smart-large-object functions (mi_lo_*) raise an MI_Exception event if they encounter a database server exception. However, the smart-large-object error is the second message that the database server returns. Therefore, an exception callback needs to include the following steps to obtain an exception from an mi_lo_* function:

1. Call mi_error_sqlcode() to get the high-level SQLCODE value.
2. Call mi_error_desc_next() to get the next error descriptor.
3. Call mi_error_sqlcode() again to get the detailed smart-large-object error (and ISAM error code).

The following callback function, excpt_callback3(), is a modified version of the excp_callback2() callback that handles multiple exceptions:

MI_CALLBACK_STATUS excpt_callback3(event_type, conn,
		event_info, user_data)
	MI_EVENT_TYPE event_type;
	MI_CONNECTION *conn;
	void *event_info;
	void *user_data; /* user-defined error buffer gets
					** passed here */
{
	DB_ERROR_BUF *user_info;
	mi_integer state_type;
	mi_string *msg;

	mi_integer i=0;
	/* Pointer to multiple error messages */
	MI_ERROR_DESC *err_desc=NULL;

	user_info = ((DB_ERROR_BUF *)user_data);

	user_info->error_type = event_type;
	if ( event_type != MI_Exception )
		{
		user_info->sqlstate[0] = '\0';
		sprintf(user_info->error_msg,
			"excpt_callback3 called with wrong event type ",
			 "%d", event_type);

		/* Send trace message for default trace class */
		DPRINTF("__myErrors__", 1, ("<<<<>>>> mesg=%s",
			user_info->error_msg));
		return MI_CB_CONTINUE;
		}

	err_desc = (MI_ERROR_DESC *)event_info;
	i++;
	mi_error_sql_state(err_desc, user_info->sqlcode, 6);
	mi_errmsg(err_desc, user_info->error_msg, MSG_SIZE-1);

	DPRINTF("__myErrors__", 1, 
		("<<<<>>>> mesg %d: sqlcode=%s, mesg=%s", i,
		user_info->sqlcode, user_info->error_msg));

/* Overwrites previous error. Another approach would be to
** allocate enough 'user_info' space to store all errors */
	if ( (err_desc=
			mi_error_desc_next((MI_ERROR_DESC *)event_info)) 
			!= NULL )
		{
		i++;
		mi_error_sql_state(err_desc, user_info->sqlcode, 6);
		mi_errmsg(err_desc, user_info->error_msg, 
			MSG_SIZE-1);

		DPRINTF("__myErrors__", 1, 
			("<<<<>>>> mesg %d: sqlcode=%s, mesg=%s", i,
			user_info->sqlcode, user_info->error_msg));
		}
	return MI_CB_CONTINUE;
}

This callback also uses the DPRINTF macro to send trace messages to an output file. For more information on tracing, see Using Tracing.

If a DataBlade API module detects an error, it can use the mi_db_error_raise() function to raise an exception.

In a C UDR, the mi_db_error_raise() function raises an exception to the database server.

In a client LIBMI application, the mi_db_error_raise() function sends the exception over to the database server.

When the mi_db_error_raise() function raises an exception, the database server handles this exception in the same way it would if a database server exception occurred in a DataBlade API function. If the DataBlade API module has registered an exception callback, this call to mi_db_error_raise() invokes the exception callback. If no exception callback has been registered, the DataBlade API uses the default behavior for the handling of exceptions.

The first argument to the mi_db_error_raise() function is a connection descriptor. This connection descriptor can be either a NULL-valued pointer or a pointer to a valid connection. Which values are valid depend on whether the calling module is a UDR or a client LIBMI application.

In a C UDR, you can specify the connection descriptor to mi_db_error_raise() as either of the following values:

• A NULL-valued pointer raises an exception on the parent connection.
• A pointer to the current connection descriptor raises an exception on the current connection.

When you specify a NULL-valued connection descriptor to the mi_db_error_raise() function, this function raises the exception against the parent connection, which is the connection on which the C UDR was invoked. This connection might be a client connection or a UDR-owned connection that was passed to mi_exec(), mi_exec_prepared_statement(), or mi_routine_exec().

If the raised exception has an MI_EXCEPTION exception level, the database server aborts both the UDR and the current SQL expression. For both exception levels (MI_EXCEPTION and MI_MESSAGE), the database server passes the event message to the module on the parent connection and returns control to this module. If the UDR needs control of the exception, it must call mi_db_error_raise() with a pointer to the current connection descriptor. For more information, see Raising an Exception on the Current Connection.

The following example shows how the MI_EXCEPTION exception level causes the my_function() UDR to abort when mi_db_error_raise() specifies a NULL-valued pointer as its connection descriptor:

void MI_PROC_VACALLBACK my_function()
{
	... Processing ... 
	if ( error condition ) 
		{
		... do any clean-up here ... 
		ret = mi_db_error_raise ((MI_CONNECTION *)NULL,
			MI_EXCEPTION, "FATAL ERROR in my_function()!");
		}
	... These lines never get reached ... 
}

Execution returns to the code that called my_function(). If this code has an exception callback, this callback determines how the exception handling continues.

When you specify a valid connection descriptor to the mi_db_error_raise() function, this function raises the exception against the specified connection. The DataBlade API invokes any callbacks that are registered for the MI_Exception event on this same connection. If a registered callback returns the MI_CB_EXC_HANDLED status, control returns to the UDR. (For more information, see Determining How To Handle the Exception.

When the my_function() routine registers a callback, the callback can catch the exception with an MI_EXCEPTION exception level, as the following example shows:

void MI_PROC_VACALLBACK
my_function()
{
	conn = mi_open(NULL, NULL, NULL);
	

	cback_hndl = mi_register_callback(conn, MI_Exception,
		excpt_callback, NULL, NULL);
	... Processing ... 
	if ( error condition ) 
		{
		... do any clean-up here ... 
		ret = mi_db_error_raise (conn, MI_EXCEPTION, 
			"The excpt_callback() function is invoked from \
			 my_function().");
		}
	... These lines do get reached if excpt_callback() 
		returns MI_CB_EXC_HANDLED... 
}

For a sample implementation of the excpt_callback() function, see Figure 10-12 on page 10-44.

In a client LIBMI application, you must specify a valid connection descriptor to the mi_db_error_raise() function. For an exception callback to be invoked when the mi_db_error_raise() function raises an exception, specify the same connection descriptor as the one on which the callback was registered.

For example, in the following code fragment, the call to mi_db_error_raise() causes the excpt_callback() function to be invoked when an MI_Exception event occurs:

conn1 = mi_open(argv[1], NULL, NULL);
cback_hndl = mi_register_callback(conn1, MI_Exception,
	clnt_callback, (void *)&error, NULL);


mi_db_error_raise(conn1, MI_EXCEPTION, 
	"The clnt_callback() callback is invoked.");

Both mi_register_callback(), which registers the callback for the MI_Exception event, and mi_db_error_raise(), which raises the MI_Exception event, specify conn1 as their connection descriptor.

The message that mi_db_error_raise() passes to an exception callback can be either of the following types:

• A literal message, which you provide as the third argument to mi_db_error_raise()
• A custom message that is associated with a value of SQLSTATE, which you provide as the third argument to mi_db_error_raise()

To raise an exception whose message text you provide, the mi_db_error_raise() function requires the following information:

• A message type of MI_MESSAGE or MI_EXCEPTION
• The associated message text

When you pass the MI_MESSAGE or MI_EXCEPTION message type to the mi_db_error_raise() function, the function raises an MI_Exception event whose error descriptor contains the following information.

If any exception callback is registered for the same connection, the DataBlade API sends this error descriptor to the callback when the MI_Exception event is raised.

If the C UDR (or any if its calling routines) has not registered an exception callback when the MI_Exception event is raised, the DataBlade API performs the default exception handling, which depends on the exception level of the exception:

• If the exception has an MI_EXCEPTION exception level, the database server aborts the UDR and returns control to the calling module.
• If the exception has an MI_MESSAGE exception level, the database server sends the warning message to the calling module and continues execution of the UDR.

If the client LIBMI application has not registered an exception callback when the MI_Exception event is raised, the client LIBMI calls the system-default callback, which provides the following information:

• The connection
• The exception type: MI_MESSAGE or MI_EXCEPTION
• The message text that is associated with the exception

For more information on the actions of the system-default callback, see Using Default Behavior.

The mi_db_error_raise() function can raise exceptions with custom messages, which DataBlade modules and user-defined routines can store in the syserrors system catalog table. The syserrors table maps these messages to five-character SQLSTATE values.

To raise an exception whose message text is stored in syserrors, you provide the following information to the mi_db_error_raise() function:

• A message type of MI_SQL
• The value of the SQLSTATE variable that identifies the custom exception
• Optionally, values specified in parameter pairs that replace markers in the custom exception message

When you pass the MI_SQL message type to the mi_db_error_raise() function, the function raises an MI_Exception event whose error descriptor contains the following information

If any exception callback is registered for the same connection, the DataBlade API sends this error descriptor to the callback when the MI_Exception event is raised.

For example, assume that the following predefined error message is under an SQLSTATE value of "03I01" in the syserrors table:

Operation Interrupted.

The following call to mi_db_error_raise() sends this predefined error message to a registered (and enabled) callback that handles the MI_Exception event:

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

The exception level for this exception would be MI_EXCEPTION, because any SQLSTATE value whose class code is greater than "02" is considered to represent a runtime error. If no such callback was registered (or enabled), the database server would take its default exception-handling behavior.

If the SQLSTATE value had a class code of "01", mi_db_error_raise() would raise a warning instead of an error. (For more information on SQLSTATE values, see SQLSTATE Status Value.) The following mi_db_error_raise() call raises an MI_Exception event whose exception level is MI_MESSAGE:

mi_db_error_raise(conn, MI_SQL, "01877", NULL);

When this exception is raised, execution continues at the next line after this call to mi_db_error_raise().

Tip: Both of the preceding mi_db_error_raise() examples specify NULL as the last argument because neither of their syserrors messages contains parameter markers. For more information on parameter markers, see Specifying Parameter Markers.

The following sections provide information on how to perform the following tasks:

• How mi_db_error_raise() searches for custom messages in the syserrors system catalog table
• How you specify values for parameter markers in custom messages
• How you add custom messages to the syserrors system catalog table

When the mi_db_error_raise() function initiates a search of the syserrors table, it requests the message in which all components of the locale (language, territory, code set, and optional modifier) are the same in the current processing locale and the locale column of syserrors.

Tip: For more information on the columns of the syserrors system catalog table, see the chapter on the system catalog tables in the "Informix Guide to SQL: Reference." For more information on SQLSTATE, see SQLSTATE Status Value.

For DataBlade API modules that use the default locale, the current processing locale is U.S. English (en_us). (The name of the default code set depends upon the platform you use. Refer to the Informix Guide to GLS Functionality for more information on default code sets.) When the current processing locale is U.S. English, mi_db_error_raise() looks only for messages that use the U.S. English locale.

For DataBlade API modules that use nondefault locales, the current processing locale is one of the following locales:

• For C UDRs, the current processing locale is the server-processing locale.
• For client LIBMI applications, the current processing locale is the client locale.

For more information on the client, database, server, and server-processing locale, see the Informix Guide to GLS Functionality.

A GLS locale name has the format ll_tt.codeset@modf, where ll is the name of the language, tt is the name of the territory, codeset is the name of the code set, and modf is the 4-character name of the optional locale modifier. (For more information on locale names, refer to the Informix Guide to GLS Functionality.) The ll_tt.codeset@modf format is the standard GLS locale name. Locale names can take other forms. However, mi_db_error_raise() first attempts to convert the names of the current processing locale and the syserrors locale into this standard GLS format.

The mi_db_error_raise() function then performs a string comparison on these two locale names. The function attempts to match a value in the locale column of syserrors with the GLS name of the current processing locale as follows:

1. Convert the current processing locale and syserrors locale names into standard GLS names, if possible.

If mi_db_error_raise() cannot map the current processing locale name to a standard name, it cannot perform the match.

2. Match the current processing locale name with an entire locale name, if possible.

Locate a row in syserrors whose locale column has a value that matches the full ll_tt.codeset@modf locale name.

3. Match the current processing locale name with only the language and territory part of a locale name, if possible.

Locate a row in syserrors whose locale column starts with the value ll_tt (only language and territory names match).

4. Match the current processing locale name with only the language part of a locale name, if possible.

Locate a row in syserrors whose locale column starts with the value ll (only language name matches).

5. Match the current processing locale name with the default locale (U.S. English), if it is available.

Locate a row in syserrors whose locale column matches the standard GLS name of the default locale.

When mi_db_error_raise() finds a matching locale name for the specified SQLSTATE value, it then verifies that the code set of the locale name from syserrors is compatible with the code set of the current processing locale. A compatible code set is one that is either the same as or can be converted to the current processing code set. If the two code sets are not compatible, mi_db_error_raise() continues to search the syserrors table for rows that match the specified SQLSTATE value. Once mi_db_error_raise() finds a matching row, it obtains the text from the corresponding message column of syserrors.

For example, suppose the current processing locale is the French Canadian locale, fr_ca.8859-1, and you issue the following call to mi_db_error_raise():

mi_db_error_raise(conn, MI_SQL, "08001", NULL);

The mi_db_error_raise() function performs the following search process to locate entries in syserrors:

1. Is there a row with the sqlstate column of "08001" and a locale value that matches "fr_ca.8859-1"?
2. Is there a row with the sqlstate column of "08001" and a locale value that starts with "fr_ca"?
3. Is there a row with the sqlstate column of "08001" and a locale value that starts with "fr"?
4. Is there a row with the sqlstate column of "08001" and a locale value that starts with "en_us"?

Suppose mi_db_error_raise() finds a row in syserrors with an sqlstate value of "08001" and a locale of "fr_ca.1250". The function obtains the associated text from the message column of this row if it can find valid code-set conversion files between the ISO8859-1 code set (8859-1) and the Microsoft 1250 code set (1250).

For C UDRs, these code-set conversion files must exist on the server computer.

For client LIBMI applications, these code-set conversion files must exist on the client computer.

The custom message in the syserrors system catalog table can contain parameter markers. These parameter markers are sequences of characters enclosed by a single percent sign on each end (for example, %TOKEN%). A parameter marker is treated as a variable for which the mi_db_error_raise() function can supply a value.

For messages with parameter markers, mi_db_error_raise() can handle a variable-length parameter list, as follows:

• Values specified in parameter pairs can replace parameter markers in the syserrors error or warning message.
• The function passes in NULL to terminate the list of parameter pairs.

The mi_db_error_raise() function requires a parameter pair for each parameter marker in the message. A parameter pair has the following values:

• The first member of the pair is a null-terminated string that represents the name and format of the parameter marker.
• The second member of the pair is the value to assign the parameter.

Parameter pairs do not have to be in the same order as the markers in the string.

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

The first member of the parameter pair has the following syntax:

parameter_name%format_character

The mi_db_error_raise() function supports following format_character values.

For example, suppose that the following message is under an SQLSTATE value of "2AM10" in the syserrors table:

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

This message contains the following parameter markers: LINE, TOKEN, and CMD. The following call to mi_db_error_raise() assigns the string "selecl" to the TOKEN parameter, 500 to the LINE parameter, and the text of the query to the CMD parameter in the message text:

mi_db_error_raise (conn, MI_SQL, "2AM10",
	"TOKEN%s", "selecl",
	"LINE%d", (mi_integer)500,
	"CMD%s", "selecl * from tables\;",
	NULL);

The string "TOKEN%s" indicates that the value that replaces the parameter marker %TOKEN% in the message string is to be formatted as a string (%s). The next member of the parameter pair, the string "selecl", is the value to format.

This mi_db_error_raise() call sends the following message to an exception callback:

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

The mi_db_error_raise() function assumes that any message text or message parameter strings that you supply are in the current processing locale.

You can store custom status codes and their associated messages in the syserrors system catalog table. To add custom messages, follow these steps:

1. Determine the SQLSTATE code for the message you want to add
2. Insert a row into the syserrors system catalog table for the new message

The syserrors system catalog table holds custom messages for DataBlade modules and user-defined routines. A unique SQLSTATE value identifies each row in the syserrors system catalog table. Therefore, to store a custom message in syserrors, you assign it an SQLSTATE value.

You must ensure that this SQLSTATE value is unique within syserrors. When you choose an SQLSTATE value, keep the following restrictions in mind:

• The database server has its own set of system messages.

Messages that the database server provides are not stored in the syserrors table. However, any special modules that are included with the database server (such as R-tree support) might have their own messages in syserrors.

• SQL reserves various SQLSTATE codes for its own use.

These messages are not stored in the syserrors table. For a list of the reserved values of SQLSTATE, see SQLSTATE Status Value.

• All SQLSTATE values for warnings begin with the "01" class code.

To define a custom warning message, you must define an SQLSTATE value that has a "01" class code and an unused subclass code.

• An installed DataBlade module might have stored its messages in syserrors.

When a DataBlade module is installed, associated messages might be added to syserrors. Avoid the use of any SQLSTATE values that an installed DataBlade module might use. You must also take care not to delete installed messages, or they must be recreated by a restore from backup or a reinstallation.

• If you are developing a DataBlade module, coordinate your SQLSTATE values with Informix.

You can group warnings and errors for your DataBlade modules into the same class code, each with a different subclass code.

Important: You must contact the Informix registry to obtain a unique error class code for the SQLSTATE values of your DataBlade module. This unique class code guarantees that your DataBlade module messages will not conflict with messages from other DataBlade modules.

You can use the following query to determine the current list of SQLSTATE message strings in syserrors:

SELECT sqlstate, locale, message FROM syserrors

ORDER BY sqlstate, locale

The locale column is used for the internationalization of error and warning messages. For more information, see Searching For Custom Messages.

To create a new message, insert a row into the syserrors system catalog table. By default, all users can view this table, but only users with the DBA privilege can modify it. For more information on columns of the syserrors system catalog table, see the Informix Guide to SQL: Reference.

For example, the following INSERT statement inserts a new message into syserrors whose SQLSTATE value is "03I01":

INSERT INTO syserrors 
VALUES ("03I01", "en_us.8859-1", 0, 1, 
	"Operation Interrupted.")

Enter message text in the language of the target locale, with the characters in the locale code set. By convention, do not include any newline characters in the message. Make sure you also update the locale column of syserrors with the name of the target locale of the message text. For information on locale names, see the Informix Guide to GLS Functionality.

Do not allow any code-set conversion to take place when you insert the message text. If the code sets of the client and database locales differ, temporarily set both the CLIENT_LOCALE and DB_LOCALE environment variables in the client environment to the name of the database locale. This workaround prevents the client application from performing code-set conversion.

If you specify any parameters in the message text, include only ASCII characters in the parameters names. Following this convention means that the parameter name can be the same for all locales. All code sets include the ASCII characters.