The DataBlade API function mi_db_error_raise( ) sends an exception message to an exception callback. This message can be either of the following:
The mi_db_error_raise( ) function can raise exceptions with customized messages, which DataBlade modules and UDRs can store in the syserrors system catalog table. The syserrors table maps these messages to five-character SQLSTATE values. In the syserrors table, you can associate a locale with the text of a customized message.
For general information on how to specify a literal message in mi_db_error_raise( ) and how to specify a customized message for mi_db_error_raise( ), see the chapter on how to handle exceptions and events in the IBM Informix: DataBlade API Programmer's Guide.
This section discusses the following tasks about how to raise locale-specific exception messages:
You can store customized status codes and their associated messages in the syserrors system catalog table. To create a customized exception message, insert a row directly in the syserrors table. The syserrors table provides the following columns for an internationalized exception message.
| Column Name | Description |
|---|---|
| sqlstate | The SQLSTATE value that
is associated with the exception 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, localeFor more information on how to determine SQLSTATE values, see the IBM Informix: DataBlade API Programmer's Guide. |
| message | The text of the exception message, with characters in the code set of the target locale By convention, do not include any newline characters in the message. |
| locale | The locale with which the exception message is to be used The locale column identifies the language and code set used for the internationalization of error and warning messages. This name is the name of the target locale of the message text. |
For more information on the syserrors system catalog table, see the chapter that describes the system catalog in the IBM Informix: Guide to SQL Reference. Do not allow any code-set conversion when you insert the text in syserrors.
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 parameter names, so s that the parameter name can be the same for all locales. Most code sets include the ASCII characters. For example, the following INSERT statements insert new messages in syserrors whose SQLSTATE value is "03I01":
INSERT INTO syserrors VALUES ("03I01", "en_us.8859-1", 0, 1,
"Operation Interrupted.")
INSERT INTO syserrors VALUES ("03I01", "fr_ca.8859-1", 0, 1,
"Traitement Interrompu.")
The '03I01' SQLSTATE value now has two locale-specific messages. The database server chooses the appropriate message based on the server-processing locale of the UDR when it executes. For more information on how mi_db_error_raise( ) locates an exception message, see Searching for Customized Messages.
As noted in the previous section, when you create messages for exceptions raised within user-defined routines (UDRs) by mi_db_error_raise( ), the locale of the message text must match the server-processing locale. If these locales are different, use of an SQL script or of a C UDR that calls the mi_exec( ) function to insert the message is not reliable, because the SQL parser issues an exception when it encounters characters that it does not recognize. To avoid this restriction, you can use a UDR that prepares the INSERT statement (with mi_prepare( )) to load the error messages:
For example, the following line prepares an INSERT statement for messages in the default locale (en_us) on a UNIX system:
stmt = mi_prepare(conn, "insert into syserrors (?, 'en_us.8859-1', 0, 1, ?)", NULL);
When executing this statement, you must provide values for the placeholders (sqlstate and message) and then use the mi_exec_prepared_statement( ) function to send the prepared INSERT statement to the database server.
The following UDR code uses a message array (enus_msg) to hold the SQLSTATE values and their associated message text. It puts information about each element of this message array in the appropriate placeholder arrays (args, lens, nulls, and types) of the mi_exec_prepared_statement( ) function.
#include <stdio.h>
#include <string.h>
#include "mi.h"
#define MAX_MSG 3
char *enus_msg[MAX_MSG][2] = {
"XT010", "First error message for insertion",
"XT020", "Second error message for insertion",
"XT030", "Third error message for insertion"
};
/*
* Title: gls_insert_enus
* Purpose: Add localized messages to 'syserrors' system error table
* for given locale, independent of session locale setting.
*/
mi_integer
gls_insert_enus()
{
MI_DATUM args[2]; /* pointers to column values */
mi_integer lens[2]; /* lengths of column values */
mi_integer nulls[2]; /* null capability of columns */
mi_string *types[2]; /* types of columns */
mi_integer i;
MI_STATEMENT *stmt;
MI_CONNECTION *conn = mi_open(NULL, NULL, NULL);
/*
* Prepare statement using placeholder values for sqlstate and message
* columns and fixed values for locale, level, and seqno columns.
*/
stmt = mi_prepare(conn,
"insert into syserrors values(?,'en_us.8859-1',0,1,?)", NULL);
for (i=0; i<MAX_MSG; i++) /* Loop through message array */
{
args[0] = (MI_DATUM)enus_msg[i][0];
/* Set pointer to sqlstate string */
lens[0] = strlen(args[0]); /* Set length of sqlstate string */
nulls[0] = MI_FALSE; /* Set null handling capability */
types[0] = "char(5)"; /* Set sqlstate column type */
args[1] = (MI_DATUM)enus_msg[i][1];
/* Set pointer to message string */
lens[1] = strlen(args[1]); /* Set length of message string */
nulls[1] = MI_FALSE; /* Set null handling capability */
types[1] = "varchar(255)"; /* Set message column type */
mi_exec_prepared_statement(stmt,0,0,2,args,lens,nulls,types,
NULL,NULL);
}
mi_close(conn);
return 0;
}
For descriptions of executing prepared statements and of how to add customized messages to the syserrors system catalog table, see the IBM Informix: DataBlade API Programmer's Guide.
When the mi_db_error_raise( ) function initiates a search of the syserrors system catalog 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 C UDRs that use the default locale, the current processing locale is U.S. English (en_us). 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 C UDRs that use nondefault locales, however, the current processing locale is the server-processing locale.
For a description of how mi_db_error_raise( ) searches for messages in the syserrors system catalog table, see the chapter on exceptions in the IBM Informix: DataBlade API Programmer's Guide.
The customized message in the syserrors system catalog table can contain parameter markers. These parameter markers are strings of characters enclosed by a single percent ( % ) symbol 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. The mi_db_error_raise( ) function assumes that any message text or message parameter strings that you supply are in the server-processing locale. For a complete description of how to specify parameter markers for a customized message, see the IBM Informix: DataBlade API Programmer's Guide.
Home | [ Top of Page | Previous Page | Next Page | Contents | Index ]