DataBlade API Programmer's Manual Chapter 10: Tracing

Home

Contents

Index

Master Index

New Book

GLS Performing Internationalized Tracing The DataBlade API supports tracing for multiple languages and code sets. A given trace statement can produce a different message for each locale. The current database server locale determines which version of the message is output. This internationalized tracing enables you to develop and test the same code in many different locales. For more information on locales, see the Guide to GLS Functionality. The DataBlade API provides a new system catalog table for storing internationalized messages. The DataBlade API also provides two internationalized trace functions. The systracemsgs System Catalog Table The systracemsgs system catalog table stores internationalized trace messages that you can use to debug your routines. DataBlade developers create a trace message by inserting a row directly into the systracemsgs table. Once a message exists in the table, you can specify the message either by name or by ID, using DataBlade API functions. Each row in the table has a message name, a locale, and message text, and must be unique in message name plus locale. The message text can be a string of text in the appropriate code set for the locale, or it might contain tokens to indicate where to substitute a piece of text. Token names are set off by a single % symbol on each end. To create a trace message, you specify its name, locale, and text. The database server assigns it a sequential message identifier. Use the INSERT statement to put new entries in the systracemsgs table, as the following example shows: insert into informix.systracemsgs(name,locale,message) values (`qp1_exit', `en_us.8859-1', `Exiting msg number was %ident% the input is still %i%'); By default, all users can view the systracemsgs table, but only users with the DBA privilege can modify it. Internationalized Trace Messages Enter message text in the language of the server locale, using any characters available in the code set. Characters enclosed by a single percent sign on each end (for example, %a%) are treated as variables. 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. Internationalized Trace Functions The two internationalized trace statements are gl_dprintf() and gl_tprintf(). Their syntax is as follows: gl_dprintf(trace_class, threshhold, (message_name [,toktype, val]...,MI_LIST_END)); gl_tprintf(message_name [,toktype ,val]...,MI_LIST_END); Syntax elements have the following values: trace_class is either a class name or the class ID integer value expressed as a character string. threshold is a non-negative integer setting the statement threshold for execution. message_name is the identifier for a message stored in the database. toktype is a string made up of a token name followed by a single % 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: MI_LIST_END is required to mark the end of the variable-length list. Failure to include MI_LIST_END might cause the user-defined routine to crash. The following two examples show internationalized trace statements: GL_DPRINTF ("funcEntry", 20, ("qp1_entry", "ident%s", "one", "i%d", i, MI_LIST_END)); if(tf ("funcEnd", 25)) { i = doSomething(); gl_tprintf("qp1_exit", "ident%s", "two", "i%d", i, MI_LIST_END); }