Skip to main content

Using System Classes for National Language Support

Modern applications can adapt to various languages and regions without engineering changes. This process is called internationalization. The process of adapting an application to a specific region or language by adding specific components for that purpose is localization.

The set of parameters that defines the user language, country, and any other, special variant preferences is a locale. Locales specify the conventions for the input, output and processing of data. These are such things as

  • Number formats

  • Date and time formats

  • Currency symbols

  • The sort order of words

  • Automatic translation of strings to another character set

A locale often is identified by noting the language in use and its geographic region (or other variation). These are usually given by the International Standards Organization (ISO) abbreviations for languageOpens in a new tab and locationOpens in a new tab. For example, en-us can represent the conventions of the English language as it is used in the United States, and en-gb as English is used in Great Britain.

Note:

The InterSystems IRIS instances on all members of a mirror must have the same locale and collation. See the “Mirroring” chapter of the High Availability Guide for more information.

The %SYS.NLS Classes

InterSystems IRIS supports localization via classes in the package %SYS.NLS (NLS refers to National Language Support). These classes contain the information InterSystems IRIS needs to adapt an internationalized program to its runtime circumstances. This section summarizes your options; for additional detail, see the class documentation for each class.

Note:

Using any of these classes, an application can obtain the values currently set for the system or the process. Changing the values associated with the process takes effect immediately. To change the system settings, your application must define a new locale with the appropriate values and direct InterSystems IRIS to start using the new locale.

%SYS.NLS.Locale

The properties in %SYS.NLS.LocaleOpens in a new tab contain information about the current locale that you might need to consult. Changing any of them will not affect any behavior of the system.

%SYS.NLS.Device

The class %SYS.NLS.DeviceOpens in a new tab contains some properties for the current device, not necessarily the device that was current when the object was instantiated.

Usually, the properties for a specific device are set when the device is opened. This guarantees that the correct translations will be used. It is possible to change the translation table once the device is open by changing the XLTTable property in the process instance of this class, but this is not recommended without a solid reason for doing so.

Other properties in %SYS.NLS.DeviceOpens in a new tab enable you to handle errors that occur during translations. By default, when a character cannot be handled by the current table, no error is triggered and the offending character is translated as a question mark (?). This character, called the replacement value or replacement string can be changed to any other string. Furthermore, instead of silently translating undefined characters, it is possible to issue an error. This behavior is called the default action, and the possible choices are:

  • 0 — Generate error

  • 1 — Replace the untranslatable character with the replacement value

  • 2 — Ignore the error and pass the untranslatable character through

There are separate properties for the input and output operations in the properties of this class:

  • InpDefaultAction

  • InpReplacementValue

  • OutDefaultAction

  • OutReplacementValue

%SYS.NLS.Format

The class %SYS.NLS.FormatOpens in a new tab contains properties that affect the behavior of $ZDATE() and related functions. These properties are inherited from the values defined for the current locale but can be altered at the process level without affecting other users. The properties DateSeparator and TimeSeparator, for example, hold the characters that separate date and time items respectively.

The documentation for $ZDATE, $ZDATEH, and $FNUMBER describes the effect of changing these values.

Locale Property

The Locale property in the class %SYS.NLS.FormatOpens in a new tab allows control of the “look” of values in the current process. For example:

  • If Locale is a empty string, the system default formats (usually US English) are in effect.

  • If Locale is a locale name such as rusw or csy8, the formats come from that locale.

  • If Locale is Current, the formats come from the system.

The property can be changed after the object is instantiated or by passing the desired locale to the %New() method as in the following:

 Set fmt = ##class(%SYS.NLS.Format).%New("jpnw")

These changes affect only the current process.

%SYS.NLS.Table

The class %SYS.NLS.TableOpens in a new tab can instantiate objects that reflect either the system default or the current process settings for the various categories of tables. A table is the basic NLS mechanism that allows application data to be accepted as input, ordered, and displayed in the format appropriate to the specified locale. As with %SYS.NLS.LocaleOpens in a new tab, changing any property of a system object will not affect the system. However, changing a property from a process object will cause the associated behavior to change immediately.

NLS tables can be classified into I/O and Internal tables. Each table type has its own set of related data:

I/O Tables

The I/O tables (also called translation tables) translate between the basic underlying character set supported by the current locale in which the systems is operating and a foreign character set supported by some entity outside InterSystems IRIS. The locale character set might be, for example, Latin2 (more properly known as ISO 8859-2) and the foreign character set might be UTF-8, generally used to communicate with the Terminal. Thus, on output, a table like Latin2–to-UTF8 would be used and, on input, a reverse mapping table would be needed, UTF8–to-Latin2.

Although there are two tables involved here (one for input and another for output), these tables usually complement one another. For simplicity, when speaking of locale definitions and system defaults, InterSystems IRIS uses a single name for a pair of I/O tables. This name is usually the name of the foreign character set, with the tacit assumption that the other half is the locale character set. However, when creating custom tables, any name that conveys the meaning of the exchange can be chosen.

I/O tables are used in devices; in this case, the word device refers to any interface where InterSystems IRIS meets the external world and where translation is needed, including the process and system call interfaces.

  • Terminal

  • Other terminal connections

  • External files

  • TCP/IP connections

  • Printer

  • InterSystems IRIS processes

  • System call

For more information, see the Translation Tables reference page.

Internal Tables

The internal tables also map strings of characters from the current local character set to some other value, but they are not intended to be used in communication with the external world. The internal tables identify characters that are part of:

  • Pattern matching

    Identify the characters that match certain pattern codes such as letters, numbers, punctuation, and so on.

  • Identifiers

    Identifier tables indicate which characters can be used in identifiers.

  • Uppercase, lowercase alphabets, and uppercase when used in titles.

    These similar in structure to the I/O tables; they map from one character set to another which just happens to be the same set. However, they are used in the context of $ZCONVERT(), not with some I/O operation.

  • Collation ordering

    These tables map a string of characters into an internal representation of that string suitable for use in global subscripts. Different languages have differing rules about how words should collate in dictionary order; these rules are encapsulated in a collation table.

  • $X/$Y action

    These tables map characters into values that indicate how they interact with the $X and $Y special variables. Should $X and/or $Y be incremented after this character is output? Is the character printable? These are questions that a $X/$Y table answers.

Note:

The list of available collations in any version of InterSystems IRIS is fixed. If your needs are not met by an existing collation, please contact the InterSystems Worldwide Support CenterOpens in a new tab for assistance.

Examples Using %SYS.NLS

Important:

These examples are all executable but none have a RunIt button, because they manipulate process-default values for the current locale. Also, many require administrative privileges and/or write access to the %SYS namespace. If you wish to execute them, please run them in a separate process, such as the InterSystems Terminal facility (Windows), or via a TCP/IP connection, and with the appropriate privileges.

Display Current Locale Information

This example displays information about the current system locale:

  Set Info = ##class(%SYS.NLS.Locale).%New()
  Set Items = "Name" _
              "/Description" _
              "/Country" _
              "/CountryAbbr" _
              "/Language" _
              "/LanguageAbbr" _
              "/Currency" _
              "/CharacterSet"

  Write !
  For i = 1 : 1 : $LENGTH(Items, "/")
  {
    Set Item = $PIECE(Items, "/", i)
    Write $JUSTIFY(Item, 15),": ", $PROPERTY(Info, Item), !
  }

Display System and Process Table Data

This should display the same values for the system and process tables unless some properties have been externally altered before running this example.

  Set IOTables = "Process" _
                 "/IRISTerminal" _
                 "/OtherTerminal" _
                 "/File" _
                 "/TCPIP" _
                 "/SystemCall" _
                 "/Printer"
  Set IntTables = "PatternMatch" _
                  "/Identifier" _
                  "/Uppercase" _
                  "/Lowercase" _
                  "/Titlecase" _
                  "/Collation" _
                  "/XYAction"

  // iterate over the systems, and then the process data
  For Type = "System", "Process"
  {
    Write !
    Set Table = ##class(%SYS.NLS.Table).%New(Type)
    Write "Type: ", Type, !

    Write "I/O Tables", !
    For i = 1 : 1 : $LENGTH(IOTables, "/")
    {
      Set PropName = $PIECE(IOTables, "/", i)
      Write $JUSTIFY(PropName, 15), ": ", $PROPERTY(Table, PropName), !
    }

    Write "Internal Tables", !
    For i = 1 : 1 : $LENGTH(IntTables, "/")
    {
      Set PropName = $PIECE(IntTables, "/", i)
      Write $JUSTIFY(PropName, 15), ": ", $PROPERTY(Table, PropName), !
    }
  }

Changing Date and Time Displays

The %SYS.NLS.FormatOpens in a new tab class contains the properties DateSeparator and TimeSeparator, for example, hold the characters used to separate the components of date and time items respectively. In the United States default locale, enu8 (or enuw for Unicode systems), these are the slash character (/) and the colon (:), respectively. The following example shows how these may be altered:

  // display the current defaults
  // date is 10 April 2005
  // time is 6 minutes 40 seconds after 11 in the morning
  Write $ZDATE("60000,40000"), !

  // now change the separators and display it again
  Set fmt = ##class(%SYS.NLS.Format).%New()
  Set fmt.DateSeparator = "_"
  Set fmt.TimeSeparator = "^"
  Write !, $ZDATE("60000,40000")

This following example changes the month names to successive letters of the alphabet (for demonstration purposes). To do this, it sets the property MonthName to a space-separated list of the month names. Note that the list starts with a space:

  // get the format class instance
  Set fmt = ##class(%SYS.NLS.Format).%New()

  // define the month names
  Set Names = " AAA BBB CCC DDD EEE FFF GGG HHH III JJJ KKK LLL"
  Set fmt.MonthAbbr = Names
  Set rtn = ##class(%SYS.NLS.Format).SetFormatItem("DATEFORMAT", 2)

  // show the result
  Write $ZDATE(60000, 2)

Changing the Way Numbers Are Displayed

Some properties in %SYS.NLS.FormatOpens in a new tab control how numbers are interpreted by $Number(). In English locales, the decimal point is used to separate the integer from the fractional part of a number, and a comma is used to separate groups of 3 digits. This too can be altered:

  // give the baseline display
  Write $Number("123,456.78"), !

  Set fmt = ##class(%SYS.NLS.Format).%New()
  // use "/" for groups of digits
  Set fmt.NumericGroupSeparator = "."

  // group digits in blocks of 4
  Set fmt.NumericGroupSize = 4

  // use ":" for separating integer and fractional parts
  Set fmt.DecimalSeparator = ","

  // try interpreting again
  Write $Number("12.3456,78"), !

Setting the Translation for a File

The following shows that an application can control the representation of data written to a file.

  // show the process default translation (RAW, no translation performed)
  Set Tbl = ##class(%SYS.NLS.Table).%New("Process")
  Write "Process default translation: ", Tbl.File, !

  // create and open a temporary file
  // use XML for the translation
  Set TempName = ##class(%Library.File).TempFilename("log")
  Set TempFile = ##class(%Library.File).%New(TempName)
  Do TempFile.Open("WSNK\XML\")
  Write "Temp file: ", TempFile.CanonicalNameGet(), !

  // write a few characters to show the translation
  // then close it
  Do TempFile.WriteLine(("--" _ $CHAR(38) _ "--"))
  Do TempFile.Close()

  // now re-open it in raw mode and show content
  Do TempFile.Open("RSK\RAW\")
  Do TempFile.Rewind()
  Set MaxChars = 50
  Set Line = TempFile.Read(.MaxChars)
  Write "Contents: """, Line, """", !

  // finish
  Do TempFile.Close()
  Do ##class(%Library.File).Delete(TempName)
  Set TempFile = "" 

For more information on translation tables, see the section on “Three-Parameter Form: Encoding Translation” in the documentation for the $ZCONVERT function.

The Config.NLS Classes

Unlike %SYS.NLS, which is available everywhere and is intended for general use, the classes in Config.NLS can be used only in the %SYS namespace and only by a user with administrative privileges. Normally, administrators who need to create custom locales and tables would use the NLS pages in the Management Portal. Only users with very special requirements should need to use Config.NLS.

There are three classes in package Config.NLS:

  • Locales – Contain all the definitions and defaults for a country or geographical region.

  • Tables – Contain a high level description of tables, but not the mapping itself.

  • SubTables – Contain the character mappings proper and may be shared by more than one Table.

The main reason for having separate Tables and SubTables classes is to avoid duplication of data. It is possible to have Tables for different character sets that happen to share the same mappings and thus the same SubTable. Also, the classes in Tables define a default action and a replacement value (see description of these properties in %SYS.NLS above). Therefore, it is possible to have separate Tables in which these attributes are different even though they share the same SubTable. This flexibility adds some complexity in managing the correct relationships between Tables and SubTables, but the gains make it worthwhile. The separation of Tables from SubTables is kept hidden from users in the Management Portal and the %SYS.NLS classes, where all the housekeeping is done. However, when working with Config.NLS this needs to be done explicitly.

Conventions for Naming User-Defined Locales and Tables

To differentiate your custom items from the system items, and to simplify upgrades, use a y at the start of the name of your items; for example: XLT-yEBCDIC-Latin1 and XLT-Latin1-yEBCDIC.

Caution:

User-defined tables, sub-tables and locales that do not follow this convention may be deleted during a system upgrade. The way to avoid this is to export user-defined tables and locales to XML files and re-import them after the upgrade.

When a custom SubTable is created from a copy of some InterSystems SubTable, the utilities that perform this task automatically use the same name and append a numeric suffix. Thus, copies of the Latin2-to-Unicode SubTable would be named XLT-Latin2-Unicode.0001 and XLT-Unicode-Latin2.0001, and so on.

Examples Using Config.NLS

This section presents the following examples:

Listing the Available Locales

This example uses the List() class query in Config.NLS.LocalesOpens in a new tab and displays a list of the available locale identifiers and descriptions.

  new $namespace
  set $namespace="%SYS"

  set stmt=##class(%SQL.Statement).%New()
  set status=stmt.%PrepareClassQuery("Config.NLS.Locales","List")
  if $$$ISERR(status) {write "%Prepare failed:" do $SYSTEM.Status.DisplayError(status) quit}

  set locales=stmt.%Execute("*")
  if (locales.%SQLCODE '= 0) {write "%Execute failed:", !, "SQLCODE ", locales.%SQLCODE, ": ", locales.%Message quit}

  while locales.%Next()
  {
    write locales.%Get("Name"), " - ", locales.%Get("Description"), !
  }
  if (locales.%SQLCODE < 0) {write "%Next failed:", !, "SQLCODE ", locales.%SQLCODE, ": ", locales.%Message quit}

Listing the Tables in a Specific Locale

The following example shows the tables that make up the Unicode locale for United States English (if it is available).

  new $namespace
  set $namespace="%SYS"

  // establish the locale identifier, try
  // United States - English - Unicode
  // United States - English - 8-bit
  Set Loc = "enuw"
  Do ##class(Config.NLS.Locales).Exists(Loc, .Ref, .Code)
  If (##class(%SYSTEM.Status).IsError(Code))
  {
    Set Loc = "enu8"
    Do ##class(Config.NLS.Locales).Exists(Loc, .Ref, .Code)
    If (##class(%SYSTEM.Status).IsError(Code))
    {
      Do ##class(%SYSTEM.Status).DisplayError(Code)
      Quit
    }
  }

  // get the local array of table names
  Write "Tables for locale: ", Loc, !
  Do Ref.GetTables(.Tables)
  Set Type = $ORDER(Tables(""))
  While (Type '= "")
  {
    Set Name = $ORDER(Tables(Type, ""))
    While (Name '= "")
    {
      Set Mod = $ORDER(Tables(Type, Name, ""))
      While (Mod '= "")
      {
        Write Type, " - ", Name, " - ", Mod, !
        Set Mod = $ORDER(Tables(Type, Name, Mod))
      }
      Set Name = $ORDER(Tables(Type, Name))
    }
    Set Type = $ORDER(Tables(Type))
  }

Creating a Custom Locale

This example will provide a template for creating a custom locale with a custom table. The custom table will translate between EBCDIC (the common form used in the US) and Latin-1 (ISO-8859–1). For more details, see the documentation for the respective classes.

As for any other table, first we need to get the definition for the character mappings. For this example we are using the data file from the web site http://source.icu-project.orgOpens in a new tab (International Components for Unicode). The relevant data fileOpens in a new tab is a text file with comment lines starting with a pound sign (#) and then a series of translation definition lines of the form:

<Uuuuu>  \xee |0

A small excerpt of the file looks like:

#
#UNICODE EBCDIC_US
#_______ _________
<U0000>  \x00 |0
<U0001>  \x01 |0
<U0002>  \x02 |0
<U0003>  \x03 |0
<U0004>  \x37 |0
<U0005>  \x2D |0
...

The lines indicate that Unicode character Uaaaa maps to EBCDIC character \xbb (where aaaa and bb are expressed in hexadecimal). We assume that the table is reversible and that EBCDIC character \xbb maps back to Unicode character Uaaaa. This allows us to create both sides (that is, EBCDIC-to-Latin1 and Latin1-to-EBCDIC) from the same data file in a single scan. Because the Unicode range is just from 0 to 255, this is actually a Latin-1 table.

The process first creates the SubTable object, then the Table, and finally the Locale. For the first step, the process creates two SubTables objects, initializes their Name and Type properties, and then fills in the FromTo mapping array with data read from the definition file.

SubTable names take the form, Type–FromEncoding–ToEncoding. The Type for regular I/O translations is “XLT” and so the SubTable names will be XLT-yEBCDIC-Latin1 and XLT-yLatin1-EBCDIC.

The following code creates the SubTables objects. In a real world program, the code would perform a number of consistency checks that omitted here for the sake of clarity. This example deletes an existing previous versions of the same objects (SubTables, Tables and Locales) so that you can run the example multiple times. More properly, you should check for the existence of previous objects using the class method Exists() and take a different action if they are already present.

  // Names for the new SubTables (save for later)
  Set nam1 = "XLT-Latin1-yEBCDIC"
  Set nam2 = "XLT-yEBCDIC-Latin1"

  // Delete existing SubTables instances with same ids
  Do ##class(Config.NLS.SubTables).Delete(nam1)
  Do ##class(Config.NLS.SubTables).Delete(nam2)

  // Create two SubTable objects
  Set sub1 = ##class(Config.NLS.SubTables).%New()
  Set sub2 = ##class(Config.NLS.SubTables).%New()

  // Set Name and Description
  Set sub1.Name = nam1
  Set sub1.Description = "ICU Latin-1->EBCDIC sub-table"
  Set sub2.Name = nam2
  Set sub2.Description = "ICU EBCDIC ->Latin-1 sub-table"

The SubTables object contains a property, type, that is a small integer indicating whether we are dealing with a multibyte translation or not. This example sets type to zero indicating a single-byte mapping. The mapping is initialized so that code points (characters) not defined in the data file are mapped to themselves.

  // Set Type (single-to-single)
  Set sub1.Type = 0
  Set sub2.Type = 0

  // Initialize FromTo arrays
  For i = 0 : 1 : 255
  {
    Do sub1.FromTo.SetAt(i, i)
    Do sub2.FromTo.SetAt(i, i)
  }

Next the application reads the file. Definitions in the file override those set as the default mapping. The function $ZHEX() converts the codes from hexadecimal to decimal.

  // Assume file is in the mgr directory
  Set file = "glibc-EBCDIC_US-2.1.2.ucm"

  // Set EOF exit trap
  Set $ZTRAP = "EOF"

  // Make that file the default device
  Open file
  Use file
  For
  {
    Read x
    If x?1"<U"4AN1">".E
    {
      Set uni = $ZHEX($E(x,3,6)),ebcdic = $ZHEX($E(x,12,13))
      Do sub1.FromTo.SetAt(ebcdic,uni)
      Do sub2.FromTo.SetAt(uni,ebcdic)
     }
  }

EOF  // No further data
  Set $ZT = ""
  Close file

  // Save SubTable objects
  Do sub1.%Save()
  Do sub2.%Save()

The character mappings are now complete. The next step is to create the Table objects that reference the SubTables objects just defined. Table objects are really descriptors for the SubTables and have only a few properties. The following code makes the connection between the two:

  // Delete existing Tables instances with same ids
  Do ##class(Config.NLS.SubTables).Delete("XLT", "Latin1", "yEBCDIC")
  Do ##class(Config.NLS.SubTables).Delete("XLT", "yEBCDIC", "Latin1")

  // Create two Table objects
  Set tab1 = ##class(Config.NLS.Tables).%New()
  Set tab2 = ##class(Config.NLS.Tables).%New()

  // Set description
  Set tab1.Description = "ICU loaded Latin-1 -> EBCDIC table"
  Set tab2.Description = "ICU generated EBCDIC -> Latin-1 table"

  // Set From/To encodings
  Set tab1.NameFrom = "Latin1"
  Set tab1.NameTo = "yEBCDIC"
  Set tab2.NameFrom = "yEBCDIC"
  Set tab2.NameTo = "Latin1"

  // Set SubTable
  Set tab1.SubTableName = nam1
  Set tab2.SubTableName = nam2

  // Set Type
  Set tab1.Type = "XLT"
  Set tab2.Type = "XLT"

  // Set Default Action
  // 1 = Replace with replacement value
  Set tab1.XLTDefaultAction = 1
  Set tab2.XLTDefaultAction = 1

  // Set Replacement value of "?"
  Set tab1.XLTReplacementValue = $ASCII("?")
  Set tab2.XLTReplacementValue = $ASCII("?")

  // Set Reversibility
  // 1 = Reversible
  // 2 = Generated
  Set tab1.XLTReversibility = 1
  Set tab2.XLTReversibility = 2

  // Set Translation Type
  // 0 = non-modal to non-modal
  Set tab1.XLTType = 0
  Set tab2.XLTType = 0

  // Save Table objects
  Do tab1.%Save()
  Do tab2.%Save()

With the Tables defined, the last step of the construction is to define a locale object that will incorporate the new tables. The application creates an empty Locale object and fills in each of the properties as was done for the Tables and SubTables. A Locale, however, is bigger and more complex. The easiest way to make a simple change like this is to copy an existing locale and change only what we need. This process uses enu8 as the source locale and names the new one, yen8. The initial y makes it clear this is a custom locale and should not be deleted on upgrades.

  // Delete existing Locales instance with the same id
  Do ##class(Config.NLS.Locales).Delete("yen8")

  // Open source locale
  Set oldloc = ##class(Config.NLS.Locales).%OpenId("enu8")

  // Create clone
  Set newloc = oldloc.%ConstructClone()

  // Set new Name and Description
  Set newloc.Name = "yen8"
  Set newloc.Description = "New locale with EBCDIC table"

With the locale in place, the process now adds the EBCDIC table to the list of I/O tables that are loaded at startup. This is done by inserting a node in the array property XLTTables, as follows:

XLTTables(<TableName>) = <components>
  • tablename identifies the pair of input and output tables for this locale.

    Because the name does not need to start with y, we use EBCDIC.

  • components is a four-item list as follows:

    1. The input “From” encoding

    2. The input “To” encoding

    3. The output “From” encoding

    4. The output “To” encoding

The following code adds the table to the list of available locales:

  // Add new table to locale
  Set component = $LISTBUILD("yEBCDIC", "Latin1", "Latin1", "yEBCDIC")
  Do newloc.XLTTables.SetAt(component, "EBCDIC")

Before the locale is usable by InterSystems IRIS, it must be compiled into its internal form. This is also sometimes called validating the locale. The IsValid() class method does a detailed analysis and returns two arrays, one for errors and one for warnings, with human-readable messages if the locale is not properly defined.

  // Check locale consistency
  If '##class(Config.NLS.Locales).IsValid("yen8", .Errors, .Warns)
  {
    Write !,"Errors: "
    ZWrite Errors
    Write !,"Warnings: "
    ZWrite Warns
    Quit
  }

  // Compile new locale
  Set status = ##class(Config.NLS.Locales).Compile("yen8")
  If (##class(%SYSTEM.Status).IsError(status))
  {
    Do $System.OBJ.DisplayError(status)
  }
  Else
  {
    Write !,"Locale yen8 successfully created."
  }

Using %Library.GlobalEdit to Set the Collation for a Global

The collation of newly created InterSystems IRIS globals is automatically set to the default collation of the database in which the global is created. The databases created by InterSystems IRIS installation are all set to the InterSystems IRIS standard collation, except USER, which is set to the default collation for the locale with which InterSystems IRIS is installed.

After you create a database, you can edit its properties to change its default collation. You can select InterSystems IRIS standard, the default collation for the locale, or any other collation loaded in the instance. Once the default collation of the database is set, any globals created in this database are created with this default collation.

InterSystems IRIS also supports the ability to override this behavior and specify a custom collation for a global. To do this, use the Create() method in the class %Library.GlobalEditOpens in a new tab supplying the collation desired:

  Set sc = ##class(%Library.GlobalEdit).Create(ns,
                                               global,
                                               collation,
                                               growthblk,
                                               ptrblock,
                                               keep,
                                               journal,
                                               .exists)

where:

  • ns — Specifies the namespace, where "" indicates the current namespace, or ^^directoryname references a specific directory.

  • global — Specifies the global name, including leading ^, such as ^cz2.

  • collation — Specifies the collation, where collation is one of the supported collations.

  • growthblk — Specifies the starting block for data.

  • ptrblk — Specifies the starting block for pointers.

  • keep — Specifies whether or not to keep the global’s directory entry when the global is killed. Setting this to 1 preserves the collation, protection, and journal attributes if the global is killed.

  • journal — This argument is no longer relevant and is ignored.

  • exists — Specifies, by reference, a variable that indicates whether the global already exists.

In environments in which some globals require different collations from other globals, InterSystems recommends that you set up a database for each different collation, and that you add a global mapping within the namespace to map each global to the database with its required collation. This method allows mixed collations to be used without changing application code to specially use the Create() method call.

Supported Collations

The following are supported in InterSystems IRIS, for use in the collation argument of the CreateGlobal^%DM subroutine:

  • 5 — InterSystems IRIS standard

  • 10 — German1

  • 11 — Portuguese1

  • 12 — Polish1

  • 13 — German2

  • 14 — Spanish1

  • 15 — Danish1

  • 16 — Cyrillic1

  • 17 — Greek1

  • 18 — Czech1

  • 19 — Czech2

  • 20 — Portuguese2

  • 21 — Finnish1

  • 23 — Cyrillic2

  • 24 — Polish2

  • 27 — French1

  • 28 — Finnish2

  • 29 — Hungarian1

  • 30 — German3

  • 31 — Polish3

  • 32 — Spanish2

  • 33 — Danish2

  • 34 — Greek2

  • 35 — Finnish3

  • 36 — Lithuanian1

  • 41 — Danish3

  • 44 — Czech3

  • 45 — Hungarian2

  • 47 — Spanish3

  • 49 — Spanish4

  • 51 — Spanish5

  • 52 — Finnish4

Note:

To see a similar list, including which collations have been loaded into the instance, open a Terminal window, change to the %SYS% namespace, and enter the command DO ^COLLATE.

Default Collation for the Installed Locale

The default collation for the locale of a new installation of InterSystems IRIS is always the most recent version of the collation, that is, the one with the highest numeric suffix (as shown in the list in the previous section). For example, when installing with a Spanish locale, the default collation is Spanish5. Older versions of the collation are supported for compatibility with existing databases.

When an InterSystems IRIS instance is upgraded, the default collation is preserved when the updated locale uses a new default. For example, if the existing instance’s locale uses Finnish3 as the default collation and the updated instance would use Finnish4, the upgrade preserves Finnish3 as the default, but makes Finnish4 available for new globals and databases.

FeedbackOpens in a new tab