Specify parameter markers

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.

d: Integer
f,g,G,e,E: Double (by reference)
T: Text (mi_lvarchar type, that is, a pointer to mi_lvarchar)
t: Length followed by string (two separate parameters)
s: Null-terminated C string

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.