Most library errors are caused by invalid arguments. The following list describes the most common errors:

• The DataBlade API might not have been initialized. "Initialization" lists the functions that initialize DataBlade API. In general, one of these functions must be the program's first call to DataBlade API.
• Any function that passes a connection (MI_CONNECTION) can pass an invalid connection, one that has been closed or dropped.
• Any function that passes a row descriptor (MI_ROW_DESC) can pass an invalid row descriptor.
• Any function that passes a row (MI_ROW) can pass an invalid row.
• Any function that passes a column name can pass a column name that does not exist in the object or objects being accessed.
• Any function that passes a column number can pass a column number that is out of range (greater or less than the number of columns in the object).
• Any function that passes an event type (MI_EVENT_TYPE) can pass a nonexistent event type.
• Any function that passes a save set (MI_SAVE_SET) can pass an invalid save set.
• Any function that passes a buffer can pass a null buffer or a buffer that is too small.
• Any function that passes a pointer can pass an invalid pointer. If the pointer_checks_enabled field of the parameter information structure is set, pointers are checked to ensure that they are within the process heap space.

Client Errors

• MI_LIB_BADARG: This error is raised when a DataBlade API function is passed an incorrect argument, such as a bad connection descriptor or a NULL value where a pointer is required.
• MI_LIB_BADSERV: This error is raised when the DataBlade API is unable to connect to a database server.
• MI_LIB_DROPCONN: This error is raised when the database server drops the connection.
• MI_LIB_INTERR: This error is raised when an internal DataBlade API error occurs. The user should call Informix Technical Support if this error occurs.
• MI_LIB_NOIMP: This error is raised when the called function has not yet been implemented.
• MI_LIB_USAGE: This error is raised when a function is called out of sequence; for example, a call to mi_next_row() when the statement did not return row data.

Exception Raising

• The connection
• A message type (MI_MESSAGE or MI_EXCEPTION)
• A message string to associate with the exception

A standard SQLSTATE value consists of five characters. Legal characters are 0 to 1 and A to Z. A code is divided into a two-character class code followed by a three-character subclass code. The class code denotes a general class of condition and the subclass code a more narrowly defined condition within the class code classification.

User-created status codes and their associated messages are stored in the syserrors system catalog table. Users can add their own status codes and messages to this table. However, SQL reserves various codes for its use.

To create a new message, insert a row directly into the syserrors system catalog table. By default, all users can view this table, but only users with the DBA privilege can modify it.

GLS

Enter message text in the language of the target locale, using any characters available in the code set, though by convention, the message does not include any newline character.

Sequences of characters enclosed by a single percent sign on each end (for example, %TOKEN%) are treated as variables when supplied with matching values. When preparing the message for output, the database server replaces each variable with its actual value.

The database server searches for the message in which all components of the locale (language, territory, and code set) match its own. If only the language and territory match, it converts the code set. If there is no message with matching language and territory, it uses the first available message with the correct language. If there is no message in the appropriate language, it uses the message for the default language, en_us.

Messages are converted to the appropriate code set and formatting styles before being sent to the client.

For more information on the syserrors system catalog table, see the Informix Guide to SQL: Syntax.

For more information about mi_db_error_raise(), see the description of this function in Chapter 12.