Skip to main content

Configuring National Language Support (NLS)

A national language locale defines the character set in which all textual data is encoded by InterSystems IRIS. The character set is 16-bit Unicode UCS-16.

Each locale contains a number of character tables used by InterSystems IRIS when displaying text, collating data (see the “Collation” chapter of Using InterSystems SQL), converting between uppercase and lowercase letters, matching patterns, and so on. Each locale defines the table to be used for each of these purposes, as well as other details such as date, time, and number formats.

Each InterSystems IRIS instance uses a single current locale; this is determined when the instance is installed, but can be changed at any time. When you change the current locale, some or all of the locale tables used by InterSystems IRIS change.

Installing a new locale does not result in any data conversion, but rather changes how data is represented.

Installing a new locale should not be a frequent operation; it is intended mainly as an upgrade option or the means to correct an installation choice. Always remember that data conversion may be needed and that special attention should be given to global subscripts.

You cannot alter the system locales provided with InterSystems IRIS, which are overwritten when the instance is upgraded.

This section describes two methods to configure locales:

Using the NLS Pages of the Management Portal

The National Language Settings pages (System Administration > Configuration > National Language Settings) let you browse existing locales and tables as well as create custom locales. You can install a new current locale, load a new table into memory, and more the using the Management Portal. When you select System Administration > Configuration > National Language Settings, the following options are available in the right-hand column:

Configured Defaults

The Configured Defaults page (System Administration > Configuration > National Language Settings > Configured Defaults) displays the locale table currently used by default for each purpose within InterSystems IRIS. When writing ObjectScript code or using some utilities, it is possible to specify a particular table for a given purpose; the default table isused when no table is specified.

Each table name is color-coded to show whether the setting was inherited from the current locale at installation or specified using the NLS class packages, as described in Using System Classes for National Language Support.in the “Customizing the InterSystems IRIS System” chapter of Specialized System Tools and Utilities.

The configuration defaults are a property of the instance, not of the locale. Therefore, when the instance is upgraded, the default selections are preserved.

Locale Definitions

From the Locale Definitions page (System Administration > Configuration > National Language Settings > Locale Definitions), you can select a locale at the Select a locale drop-down and perform several actions. The drop-down is always set to the current locale when the page first displays.

  • Using the Use locale date/time/number formats for [current locale] drop-down, indicate whether or not you want to use the date, time, and number formats specified by the current locale. Note that this always applies to the current locale, not a locale you have selected in the Select a locale drop-down but not yet installed.

  • To view the details of a selected locale, click Properties. The next page displays the locale properties grouped into categories. For locales you have added, you can edit the fields and click Save to save these changes. You cannot edit the system locales provided with InterSystems IRIS. The properties are as follows:

    • Basic Properties

    • Date, Time, and Number Formats

    • Internal Tables — You have two options when editing the internal tables:

      • Edit Tables — You may select or delete a table from the list boxes by double clicking an item, or by selecting an item and then clicking > or < to move it from the appropriate list.

        Tables that require at least one entry are indicated by an asterisk (*); the other tables may be left empty.

      • Edit Defaults — You may choose the default from the values you enter in the Edit Tables function of the Internal Tables category.

    • Input/Output Tables — You can edit, add, or remove a table when choosing to edit this category.

      • To edit a table, click the table in the first list. The table name appears in the lower box. You can modify the values and click Save.

      • To remove a table, click the table in the first list. The table name appears in the lower box; click Remove. A confirmation box displays offering you the option to Cancel or OK the delete.

      • To add a table, click Add. The lower box has the Table field enabled and the Remove option disabled. You can enter a table name and enter the Output to and Input from fields.

      Click Save when you have made all your updates. If the save is successful, the updated list appears; otherwise, an appropriate error message displays.

    • Input/Output Defaults

    • Strings

  • To take further actions, click the following buttons:

    • Validate — Validates the selected locale, displaying an error message if the locale cannot be validated. This is useful when creating custom locales.

    • Copy — Creates a copy of the selected locale, which you can then customize. The name of the copy must contain four characters beginning with y and ending with 8 or w. The default description is Copy of%locale, where %locale is the selected locale name. When the copy is created, it is added to the Select a locale drop-down.

    • Export — Exports a locale to an .xml file. For example, you might export a custom locale you created and import it on another instance using the Import Locale page. The default name is loc_%locale.xml, where %locale is the selected locale. In addition, you can include the path of the export file; if you do not specify the path, the default location is install-dir\mgr.

    • Install — Installs the selected locale as the current locale for the instance. An initial validation occurs; if it fails, an error message displays, otherwise you can continue with installation.

    • Load Table — Lets you load a table from the selected locale (the current locale or another) into memory from disk. Select a table type and then a table name from the list populated after you select the type. Click OK to load the table or Cancel to close the dialog box and return to the Locale Definitions page.

    • Delete — Deletes a locale. You can delete only custom locales; the button is disabled when a system locale is selected. You cannot delete the current locale even if it is a custom locale. You must confirm deletion of the locale before proceeding.

Import Locale

From the Import Locale page (System Administration > Configuration > National Language Settings > Import Locales or Tables), you can import locales or tables. For example, you can import a custom locale exported (as described in the previous section) from another instance.

  1. Select the Import Type > Locale is the default.

  2. Enter a file name and click Import. The only valid file extensions are .xml and .goq.

  3. A message displays indicating how many locales, tables, and subtables have been imported.

Using the NLS Class Packages

System Classes for National Language Support contains details on using both the %SYS.NLS and Config.NLS class packages.

The %SYS.NLS Classes section contains details on using the following classes:

The Config.NLS Classes section contains details on using the following classes:

You can also find details on each of these classes in the InterSystems Class Reference.

Feedback