Translation Tables

Introduction

There are two general scenarios in which translation tables are used to convert characters:

• In many contexts (such as in URLs, in HTML, in JSON, and so on), specific characters are disallowed and must be represented by escape sequences. In this case, it is necessary to convert the characters to or from the allowed set of characters.

• If you are reading from a source outside the database or writing to a destination outside the database, that entity may expect a different character set than InterSystems IRIS uses. In this case, it is necessary to convert the character encoding.

The “translation table” for a given context is actually a pair of tables. One table specifies how to convert from the default character set to the foreign character set (or to the foreign context), and other specifies how to convert in the other direction. In InterSystems IRIS, the convention is to refer to this pair of tables as a single unit that has an input mode and an output mode. Thus, there is an HTML translation table for managing conversions to and from HTML, and there is an CP1250 translation table for managing conversions to and from the CP1250 character set.

List of Tables

The following is a list of the InterSystems IRIS translation tables:

Output Escaping

This section indicates how specific translation tables convert characters in output mode:

URL and URI Conversions

A URL or URI can only contain certain 8-bit ASCII characters. All other characters must be represented by an escape sequence beginning with %. If you wish to convert a string containing Unicode characters to a URL or URI, you must first convert your local representation to an 8-bit intermediate representation, using UTF-8 encoding. You then convert the UTF-8 results to URL encoding. To convert a URL back to its original Unicode string, you perform the reverse operation. This is shown in the following example:

  SET ustring="US$ to "_$CHAR(8364)_" échange"
  WRITE "initial string is: ",ustring,!
ConvertUnicodeToURL
  SET utfo = $ZCONVERT(ustring,"O","UTF8")
  SET urlo = $ZCONVERT(utfo,"O","URL")
  WRITE "Unicode to URL conversion: ",urlo,!
ConvertURLtoUnicode
  SET urli = $ZCONVERT(urlo,"I","URL")
  SET utfi = $ZCONVERT(urli,"I","UTF8")
  WRITE "URL to Unicode conversion: ",utfi

JS and JSML, JSON, and JSONML Conversions

The JS and JSON translations use UTF-8 encoding for Unicode characters. The JSML and JSONML translations render Unicode characters without encoding. For ASCII characters ($CHAR(0) through $CHAR(127)), JS and JSML encodings are identical. For ASCII characters ($CHAR(0) through $CHAR(127)), JSON and JSONML encodings are identical.

The following example compares the translation of JS and JSML characters:

  FOR i=1:1:256 {
      SET x=$ZCVT($C(i),"O","JS")
      SET y=$ZCVT($C(i),"O","JSML") 
      IF x=y {
        WRITE "."
      } ELSE {
        WRITE !!,$ZHEX(i),!,"JS: " ZZDUMP x WRITE !,"JSML: " ZZDUMP y 
      }
  }

Related APIs

For the currently available list of translation tables, refer to the XLTTablesOpens in a new tab property of %SYS.NLS.LocaleOpens in a new tab, as shown in the following example:

  SET nlsoref=##class(%SYS.NLS.Locale).%New()
  WRITE $LISTTOSTRING(nlsoref.XLTTables,", ")

Also, you can use %Net.CharsetOpens in a new tab to represent character sets within InterSystems IRIS. This class includes the following class methods:

• GetDefaultCharset() returns the default character set for the current InterSystems IRIS locale (see next heading).

• GetTranslateTable() returns the name of the InterSystems IRIS translation table for a given input character set.

• TranslateTableExists() indicates whether the translation table for the given character set has been loaded.

For method signatures, see the class documentation for %Net.CharsetOpens in a new tab.

Related Concepts

InterSystems IRIS locale is a set of metadata that specify the user language, currency symbols, formats, and other conventions for a specific country or geographic region. A locale includes translation tables. InterSystems IRIS uses the phrase National Language Support (NLS) to refer collectively to the locale definitions and to the tools that you use to view and extend them.

External to the definition of any locale, a given InterSystems IRIS instance is configured to use specific translation tables, by default, for input/output activity. These are the default translation tables or default I/O tables. To see the current defaults, use %SYS.NLS.TableOpens in a new tab; see the class reference for detail.

See Also

• $zconvert

• Using System Classes for National Language Support

• %SYS.NLS.LocaleOpens in a new tab

• %SYS.NLS.TableOpens in a new tab