Search for custom messages

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.

For DataBlade API modules that use the default locale, the current processing locale is US English (en_us). (The name of the default code set depends upon the platform you use. For more information about default code sets, see the HCL Informix® GLS User's Guide.) When the current processing locale is US English, mi_db_error_raise() looks only for messages that use the US 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 about the client, database server, and server-processing locales, see the HCL Informix GLS User's Guide.

A GLS locale name has the format ll_tt.codeset@modf, in which 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 about locale names, see the HCL Informix GLS User's Guide.) 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:

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.
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.
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).
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).
Match the current processing locale name with the default locale (US 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. After 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:

Is there a row with the sqlstate column of "08001" and a locale value that matches "fr_ca.8859-1"?
Is there a row with the sqlstate column of "08001" and a locale value that starts with "fr_ca"?
Is there a row with the sqlstate column of "08001" and a locale value that starts with "fr"?
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.