Internationalized Tracing Messages

The API supports trace messages that correspond to a particular locale. The current database locale determines which code set the trace message uses. Based on the current database locale, a given tracepoint can produce an internationalized trace message. Internationalized tracing enables you to develop and test the same code in many different locales.

To provide internationalized tracing support, the API provides the following capabilities:

• The systracemsgs system catalog table stores internationalized trace messages.
• Two internationalized trace functions, gl_dprintf( ) and gl_tprintf( ), format internationalized trace messages.

Inserting Messages in the systracemsgs System Catalog Table

The systracemsgs system catalog table stores internationalized trace messages that you can use to debug your C UDRs. To create an internationalized trace message, insert a row directly into the systracemsgs table.

The systracemsgs table describes each internationalized trace message.

The combination of message name and locale must be unique within the table. Once you insert a new trace class into systracemsgs, the database server assigns it a unique identifier, called a trace-message identifier. It stores the trace-class identifier in the msgid column of systracemsgs. Once a trace message exists in the systracemsgs table, you can specify the message either by name or by trace-message identifier to API tracing functions.

The trace-message text can be a string of text in the appropriate language and code set for the locale, and can contain tokens to indicate where to substitute a piece of text. Token names are delimited between percent (%) symbols. The following INSERT statement puts a new message called qp1_exit in the systracemsgs table:

INSERT INTO informix.systracemsgs(name, locale, message)
VALUES ('qp1_exit', 'en_us.8859-1',
   'Exiting msg number was %ident%; the input is still %i%')

This message text is in English and therefore the systracemsgs row specifies the default locale of U.S. English.

This second message is the French version of the qp1_exit message and therefore the systracemsgs row specifies a French locale on a UNIX system (fr_fr.8859-1):

INSERT INTO informix.systracemsgs(name, locale, message)
VALUES ('qp1_exit', 'fr_fr.8859-1',
   'Le numéro de message en sortie était %ident%; \
   l'entrée est toujours %i%')

Enter message text in the language of the server locale, with any characters available in the server code set. To insert a variable, enclose the variable name with a a single percent sign on each end (for example, %a%). When the database server prepares the trace message for output, it replaces each variable with its actual value.

Putting Internationalized Trace Messages into Code

The DataBlade API provides the following tracing functions to insert internationalized tracepoints into UDR code:

• The GL_DPRINTF macro formats an internationalized trace message and specifies the threshold for the tracepoint. The syntax for GL_DPRINTF is as follows:

  GL_DPRINTF(trace_class, threshold, 
     (message_name [,toktype, val]...,MI_LIST_END));

• The gl_tprintf( ) function formats an internationalized trace message but does not specify a tracepoint threshold.

  The gl_tprintf( ) function is for use within a trace block, which uses the tf( ) function to compare a specified threshold with the current trace level. The syntax for gl_tprintf( ) is as follows:

  gl_tprintf(message_name [,toktype ,val]...,
     MI_LIST_END);

Syntax elements for both GL_DPRINTF and gl_tprintf( ) have these values:

trace_class

is either a trace-class name or the trace-class identifier integer value expressed as a character string.

threshold

is a nonnegative integer that sets the tracepoint threshold for execution.

message_name

is the identifier for an internationalized message stored in the systracemsgs system catalog table of the database.

toktype

is a string made up of a token name followed by a single percent (%) symbol followed by a single character output specifier as used in printf formats.

val

is a value expression to be output that must match the type of the output specifier in the preceding token.

MI_LIST_END

is a macro constant that ends the variable-length list.

Important:

The MI_LIST_END constant marks the end of the variable-length list. If you do not include MI_LIST_END, the user-defined routine might fail.

This internationalized trace statement uses the GL_DPRINTF macro:

i = 6;
/* If the current trace level of the funcEntry class is greater
 * than or equal to 20, find the version of the qp1_entry 
 * message whose locale matches the current database locale
 */
GL_DPRINTF("funcEntry", 20, 
         ("qp1_entry",
         "ident%s", "one",
         "i%d", i,
         MI_LIST_END));

In the default locale, if the current trace level of the funcEntry class is greater than or equal to 20, this tracepoint generates the following trace message:

13:21:51  Exiting msg number was one; the input is still 6

The following internationalized trace block that uses the gl_tprinf() function:

i = 6;
/* Compare current trace level of "funcEnd" class and
 * with a tracepoint threshold of 25. Continue execution of
 * trace block if trace level >= 25 
 */
if ( tf("funcEnd", 25) )
   {
      i = doSomething();
   /* Generate an internationalized trace message (based 
    * on current database locale) */
      gl_tprintf("qp1_exit", "ident%s", "deux", "i%d", i,
      MI_LIST_END);
   }

If the locale is French and the current trace level of the funcEntry class is greater than or equal to 25, the tracepoint generates this trace message:

13:21:53 Le numéro de message en sortie était deux; l'entrée 
est toujours 6

The database server writes the trace messages in the trace-output file in the code set of the locale associated with the message. If the trace message originated from the systracemsgs system catalog table, its characters are in the code set of the locale specified in the locale column of its systracemsgs entry. The database server might have performed code-set conversion on these trace messages if the code set in the UDR source is different from (but compatible with) the code set of the server-processing locale.

Searching for Trace Messages

To write an internationalized trace message to your trace-output file, the database server must locate a row in the systracemsgs system catalog table whose locale column matches (or is compatible with) the server-processing locale for your UDR. Therefore, to see a particular trace message in the trace-output file, environment variables that specify the locale (CLIENT_LOCALE, DB_LOCALE, and SERVER_LOCALE) must be set so that the database server generates a server-processing locale that matches an entry in the systracemsgs system catalog table.

The database server searches the systracemsgs table for an entry with the same name as the tracepoint and a locale in which all components of the locale (language, territory, and code set) are the same in the current processing locale and the locale column of systracemsgs. If only the language and territory match, the database server converts the code set. If no message has 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.