Skip to main content
Previous sectionNext section

Configuring InterSystems IRIS

An InterSystems IRIS® data platform configuration determines all the connections, settings, and roles for an instance of InterSystems IRIS. You can use the Management Portal to adjust system settings; create and modify namespaces, databases, and network connections; and perform various other tasks.

Configuring System Information

InterSystems IRIS stores system-wide configuration information in a file called the configuration parameter file (CPF). This file is an important tool, as it contains most of the configurable settings for an InterSystems IRIS instance. A default CPF is deployed with every instance and is located in the installation directory. You can modify the CPF directly in a text editor, or indirectly from the Management Portal or the Terminal. On UNIX® and Linux, you can also customize the CPF during deployment by specifying a merge file, which InterSystems IRIS uses to update the default CPF before the instance starts for the first time. For more information about the CPF and its parameters, see the “Introduction to the Configuration Parameter File” chapter in Configuration Parameter File Reference.

There are several startup settings that you must change for any newly installed instance, and others you should review. This section discusses these settings to consider initially:

Memory and Startup Settings

When you first install InterSystems IRIS, you should review and adjust the memory allocations, among other configuration settings. There are three primary actions you must take in determining the way an InterSystems IRIS instance uses memory, as follows:

Important:

When InterSystems IRIS is first installed, database and routine cache memory allocation is set to Automatically, under which InterSystems IRIS allocates a conservative fraction of the available physical memory for the database cache (global buffers), not to exceed 1 GB. This setting is not appropriate for production use.

For guidelines for allocating memory to an InterSystems IRIS instance’s routine and database caches and the generic memory heap, see Memory Management and Scaling for InterSystems IRIS in the “Vertical Scaling” chapter of the Scalability Guide.

Other than the memory settings, the Memory and Startup page includes the following:

  • Auto-start on System Boot — On Windows systems, an InterSystems IRIS instance is configured by default to start automatically when the host system starts. You can change this behavior, so that the instance does not start automatically on system startup, by clearing this check box.

  • Superserver Port Number — The superserver port is the TCP port used by an InterSystems IRIS instance to accept incoming client requests. When you change this setting (which should be done with caution, as many clients may be configured to connect to the instance using this port), the change will not take effect until you restart the instance.

  • System Mode — You can enter a label to be displayed in the Management Portal header, or select one from the drop-down list.

Click Save to save your modifications to these settings.

Important:

Some changes on this page require an InterSystems IRIS restart and some do not. If you modify a setting that requires a restart and save your changes, none of the changes take effect until you restart InterSystems IRIS, even those that by themselves do not require a restart. If a restart is required, the message Modification saved. You must restart system for the new values to take effect. displays. After you close the page, the warning message does not appear again to remind you that a restart is required, and it is therefore best to restart the instance immediately.

Allocating Memory to the Database and Routine Caches

When InterSystems IRIS is first installed, memory for the routine and database caches is set, by default, to be Automatically allocated. With this default, InterSystems IRIS allocates a conservative fraction of the available physical memory for the database cache, not to exceed 1 GB. This setting is not appropriate for production use. Before deploying the system for production use or before performing any tests or benchmarking intended to simulate production use, you must manually create an appropriate memory allocation for the database and routine caches by selecting Manually and using the following procedures. To allocate memory for the routine and database caches,

  1. On the Management Portal, navigate to the Memory and Startup page (System Administration > Configuration > System Configuration > Memory and Startup).

  2. Select Manually.

Allocating Memory to the Database Cache

Memory Allocated for [blocksize] Database Cache (MB) — The database cache specifies the system memory allocated for buffering data; this is also called creating global buffers. The database cache and the memory allocated to it are sometimes referred to as the global buffer pool.

Enter a separate allocation for each enabled database block size listed. The 8K block size is required and is listed by default. To enable more database block sizes (16K, 32K, 64K), use the DBSizesAllowed setting on the Startup Settings page (System Administration > Additional Settings > Startup). See DBSizesAllowed in the Configuration Parameter File Reference for more information.

Both block size and the maximum number of buffers available have implications for performance. To determine how many global buffers InterSystems IRIS will create for databases with a particular block size, divide the allocation for a block size by the block size; the smaller the block size, the larger the number of global buffers that will be created for databases with that block size. For guidelines for selecting the appropriate block sizes for your applications, see Large Block Size Considerations.

Important:

If you are configuring a large ECP system, allocate at least 50 MB of 8 KB buffers for ECP control structures in addition to the 8 KB buffers required to serve your 8 KB blocks over ECP. See Increase Data Server Database Caches for ECP Control Structures in the “Horizontally Scaling Systems for User Volume with InterSystems Distributed Caching” chapter of the Scalability Guide for details.

Note:

You can also allocate memory to the database cache using the globals setting in the iris.cpf file; for more information, see globals in the Configuration Parameter File Reference.

Allocating Memory to the Routine Cache

Memory Allocated for Routine Cache (MB) — The routine cache specifies the system memory allocated for caching server code.

InterSystems IRIS takes the total amount of memory you allocate for the routine cache and creates buffers of different sizes according to this formula: half the total memory in 64 KB buffers, three-eighths in 16 KB buffers, and one-eighth in 4 KB buffers. For example, if you allocate 500 MB, InterSystems IRIS creates 4000 64 KB buffers (250 MB * 1024 KB/MB / 64KB), 12000 16 KB buffers (187.5 MB), and 16,000 4 KB buffers (62.5 MB). These groups of buffers are sometimes called pools, as in “the 16 K buffer pool”.

Bear in mind the following points regarding the routine cache memory allocation:

  • For typical production instances, a good starting allocation is 350-400 MB. However, the ideal allocation for a given application depends on may factors, and adjustment may be necessary to optimize performance.

  • The maximum number of total buffers that InterSystems IRIS allocates is 65,529. The format for InterSystems IRIS routines does not allow more than 32,768 characters for literal strings regardless of the setting for the maximum routine size.

  • The minimum allocation is 35 MB; the instance will allocate this much even if you specify less. The minimum number of buffers in a pool is 430.

Note:

You can also allocate memory to the routine cache using the routines setting in the iris.cpf file; for more information, see routines in the Configuration Parameter File Reference.

Setting the Maximum per Process Memory

The Maximum Per-Process Memory (KB) setting on the Memory and Startup page specifies the maximum memory that can be allocated to a process running on this InterSystems IRIS instance. The default is 262144 KB. The allowed range is 128 KB to 2147483647 KB.

Note:

It is not necessary to reset this value unless you have set it lower than its default (262144 KB). If you receive <STORE> errors, increase the size and start a new process.

Process private memory, which is used for symbol table allocation and various other memory requirements (for example I/O device access structures and buffers), is allocated in increasing extents as required by the application until the specified maximum is reached. The initial allocation is 128 KB. Once private memory is allocated to a process, it is not deallocated until the process exits.

For a detailed discussion of process memory in InterSystems IRIS, see Process Memory in InterSystems Products.

Configuring Generic Memory Heap (gmheap)

The generic memory heap (also known as the shared memory heap) is the memory used by InterSystems IRIS for purposes other than the routine and database caches. This setting is not on the Memory and Startup page. You can configure gmheap on the Advanced Memory page (System Administration > Configuration > Additional Settings > Advanced Memory); for more information, see gmheap in Configuration Parameter FileReference.

To see details of used and available memory for gmheap, navigate to the Shared Memory Heap Usage page (System Operation > System Usage) and click the Shared Memory Heap Usage link; for more information, see Generic (Shared) Memory Heap Usage in the “Monitoring InterSystems IRIS Using the Management Portal” chapter of the Monitoring Guide.

IPv6 Support

You can enable or disable the use of IPv6 addresses in InterSystems IRIS by navigating to the Startup Settings page (System Administration > Configuration > Additional Settings > Startup) page; in the IPv6 row, click Edit. Select IPv6 to enable this option.

Note:

This option is visible only if the network to which this InterSystems IRIS instance is connected permits IPv6 addressing.

When IPv6 is enabled, InterSystems IRIS accepts IPv6 addresses, IPv4 addresses, or DNS forms of addressing (host names, with or without domain qualifiers); when IPv6 is disabled, InterSystems IRIS accepts only IPv4 addresses or DNS forms of addressing.

When dotted-decimal IPv4 addresses (for example, 192.29.233.19) are specified, an IPv4 connection is attempted; when colon-separated IPv6 addresses (for example, 2001:fecd:ba23:cd1f:dcb1:1010:9234:4085) are specified, an IPv6 connection is attempted. When a DNS name (for example, mycomputer.myorg.com) is specified, it resolves to an actual IP address: first, it attempts to make an IPv4 connection; then, if an IPv4 connection cannot be made, it attempts an IPv6 connection.

InterSystems IRIS allows Internet addresses to be supplied in DNS, IPv4 and IPv6 formats. For example, “localhost”, 127.0.0.1, and ::1 are representations of the loopback address in each format, respectively. Detailed information about IPv6 addressing can be found in the following Internet Engineering Task Force documents:

IPv6 addressing can also be checked and controlled using the IPv6Format method of the %SYSTEM.Process class (for the current process) or the IPv6 method of the Config.Startup class (for the system generally).

Even though an InterSystems IRIS instance may be using an IPv4 network, IPv6 addresses can still be used as input to the various services provided that the IPv6 address supplied has a valid IPv4 equivalent. The loopback address used earlier in this section is such an example; RFC 4291 describes several more formats. Thus, the various InterSystems services will accept either IPv4 or IPv6 addresses without error as long as the address form given can be validly converted for use on the connected network. So all of these forms (and several more) are acceptable

  • localhost (DNS)

  • 127.0.0.1 (IPv4)

  • ::FFFF:127.0.0.1 (IPv4 mapped IPv6 format)

  • 0:0:0:0:0:0:0:1 (full IPV6)

  • ::1 (compressed IPv6)

as valid representations of the loopback address.

Generally, when asked for an Internet address that has been supplied to an InterSystems service earlier, InterSystems IRIS does not alter the address format. Addresses supplied in IPv4, or IPv6 format are returned as IPv4 or IPv6, respectively. The only exception is that addresses supplied as host names and translated by the Domain Name Server (DNS) may be returned in whatever form the DNS returns.

Note:

InterSystems IRIS does not support the use of wildcard characters or ranges in IPv6 addresses.

Configuring Data

InterSystems IRIS stores data — persistent multidimensional arrays (globals) as well as executable code (routines) — in one or more physical structures called databases. A database consists of one or more physical files stored in the local operating system. An InterSystems IRIS system may (and usually does) have multiple databases.

Each InterSystems IRIS system maintains a database cache — a local, shared memory buffer used to cache data retrieved from the physical databases. This cache greatly reduces the amount of costly I/O operations required to access data and provides much of the performance benefits of InterSystems IRIS. (For information about allocating the database cache, see Memory and Startup Settings.)

InterSystems IRIS applications access data by means of a namespace. A namespace provides a logical view of data (globals and routines) stored in one or more physical databases. An InterSystems IRIS system may (and usually does) have multiple namespaces. InterSystems IRIS maps the data visible in a logical namespace to one or more physical databases. This mapping provides applications with a powerful mechanism for changing an application’s physical deployment without changing application logic.

In the simplest case, there is a one-to-one correspondence between a namespace and a database, but many systems take advantage of the ability to define a namespace that provides access to data in multiple databases. For example, a system could have multiple namespaces, each of which provides a different logical view of the data stored within one or more physical databases.

For more details, see the following sections:

See the Config package in the InterSystems Class Reference for information about updating namespaces, databases, and mappings programmatically.

Configuring Namespaces

A namespace is a collection of data and programs in a virtual work space. In a namespace, you can define the globals that various groups or people need. For example, if your accounting department needs to use certain globals that exist on different systems or in different directories, you can set up a single namespace that references all the accounting globals and databases on your network.

InterSystems IRIS comes with the following predefined namespaces:

  • %SYS — System management information and utilities.

  • USER — Empty at installation. Typically used for application development.

You can perform the following procedures for configuring namespaces on the Namespace page of the Management Portal, which you can navigate to by selecting System Administration on the home page, then Configuration, then System Configuration, then Namespaces:

The absolute limit to the number of namespaces within a single InterSystems IRIS instance is 2048. The size of the namespaces table is automatic and not configurable. For more information about namespaces, see the “Namespaces and Databases” chapter of the Orientation Guide for Server-Side Programming.

Create/Modify a Namespace

You can create a new namespace at any time, but when you are first setting up the system, create the basic ones that your users need. To create a namespace, click Create New Namespace to display the New Namespace page, then do the following:

  1. Enter a Name for the namespace.

    Namespace names must be at least one character (but not more than 255 characters) long, starting with an alphabetic character or a percent sign (%) followed by an arbitrary number of alphanumeric characters, dashes, or underscores.

    Important:

    Do not specify the following reserved system names: BIN, BROKER, DOCUMATIC, %SYS.

  2. You can Copy from an existing namespace, creating a duplicate of the selected namespace. In this case, all other options will be made unavailable except for the Web application check box described in step 6 below.

  3. Choose whether the default database for globals is local or remote.

  4. Select an existing database for Globals for the default Global mapping of this namespace or click Create New Database, which launches either the database wizard or the remote database wizard.

  5. Optionally, you can choose whether the default database for routines is local or remote, then either use the Select an existing database for Routines drop-down to choose a database for the default Routine mapping of this namespace, or click Create New Database, which launches either the database wizard or the remote database wizard.

  6. Select the Create a default Web application for this namespace check box if you are creating a web application that accesses this namespace.

  7. After entering the required information, click Save to add your namespace to the configuration.

Create a Namespace on an InterSystems IRIS Instance

When you create a namespace on an InterSystems IRIS instance, the Enable namespace for interoperability productions check box is displayed at the bottom of the New Namespace page and is automatically selected. To create a namespace that is not interoperability-enabled, clear this check box before clicking Save.

If you do not clear the check box and create an interoperability-enabled namespace, the system automatically performs additional configuration tasks for the new namespace, as follows:

  • If the default globals database for this namespace is an existing database, it upgrades and recompiles some classes in that database.

    Caution:

    If you are also using this database in other namespaces, you might consider this change undesirable. When you create a new namespace in an InterSystems IRIS instance, carefully consider whether it is appropriate for this namespace to reuse an existing database.

  • It defines global mappings, routine mappings, and package mappings that make the InterSystems IRIS system classes and data available to the namespace.

  • It adds nodes to the ^%SYS global.

  • It creates a web application for the namespace, using the application name required by InterSystems IRIS: /csp/namespace

Rename a Namespace or Modify Default Mappings

You can rename a namespace, or change the databases to which your namespace is mapped without restarting InterSystems IRIS, using the following procedure:

  1. Go to the Namespaces page (System Administration > Configuration > System Configuration > Namespaces).

  2. On the Namespaces page, click the name of namespace you wish to modify.

  3. Change or replace the existing name to rename the namespace.

    Important:

    If you are renaming an interoperability-enabled namespace, you must take additional steps to complete the process.

    1. Open the InterSystems Terminal from the System Tray.

    2. Enter:

      do ##class(%Library.EnsembleMgr).EnableNamespace("<NewNamespace>",1)

      Where <NewNamespace> is the new name of the existing namespace.

    3. Go to the Web Applications page (System Administration > Security > Applications > Web Applications).

    4. Find the name of the application that corresponds to the old name of the namespace, and click Delete.

    5. Click the name of the application that corresponds to the new name of the namespace.

    6. Select Namespace Default Application and click Save.

    7. In the Terminal, enter:

      do ##class(%EnsembleMgr).DisableNamespace("<OldName>",1)

      Where <OldName> is the original name of the namespace that you are renaming.

  4. Choose the Default Database for Globals, the Default Database for Routines, and the Default Database for Temporary Storage from the list of defined databases.

    Note:

    Selecting a database that is configured not to journal globals (that is, the Journal globals property is set to No) from the Default Database for Temporary Storage drop-down list is not the same as selecting IRISTEMP; for more information, see Using Temporary Globals and IRISTEMP in the “Journaling” chapter of the Data Integrity Guide.

  5. Click Save.

Note:

Users directly accessing the database at the time of the change may need to log out of and then back into InterSystems IRIS to update their namespace mappings.

Add Global, Routine, and Package Mapping to a Namespace

In addition to having access to the globals and routines in the mapped database, you can also map globals, routines, and class packages from other databases on the same or different systems. This allows simple references to data which can exist anywhere and is the primary feature of a namespace. You can map whole globals or pieces of globals; this feature allows data to easily span disks.

Note:

Mappings are sorted alphabetically; if subscripts are specified, they are sorted by name and subscript. For more information, see the “Global Structure” chapter of the Using Globals guide.

Click the appropriate choice to begin mapping:

The following is a schematic diagram of how mapping works in a sample airline reservation application:

Test Namespace Mapping
Namespaces for Travel Agent and Flight Schedule have unique mappings, and are both mapped to the Airline Routes database.

Data and programs are stored in the database databases, the physical storage locations, and referred to by namespaces, the logical references.

Important:

If there is mapped content with the same identifier as local content (such as a package, class, global, or routine name), the mapped content will be visible, rather than the local content.

Global Mappings

You can add a mapping for a new global to your namespace at the global and global subscript level that overrides the default database mapping for globals of the namespace:

  1. Navigate to the Namespaces page (System Administration > Configuration > System Configuration > Namespaces) and click Global Mappings in the row of the namespace where you want to map the global.

  2. From the Global Mappings page click New.

  3. Select the Global database location database where the global is located.

  4. Enter the Global name. You can use the * character as part of the global name to specify multiple globals, for example ABC*.

  5. Enter the Global subscripts to be mapped. The subscript reference must begin with an open parenthesis. Some examples follow:

    (1)
    ("A")
    (1):(5)
    ("A"):("Z")
    ("B",23,"m"):("E",5)
    (BEGIN):("X")
    ("Y"):(END)
    
    Note:

    When specifying a range (for example, ("A"):("Z"), the range is “from-to” (not “from-through”) the specified subscripts; that is, the lower end of a defined subscript range is inclusive, while the upper end of the defined subscript range is exclusive. For example, Name (1):(10) includes Name (1) but does not include Name (10); the exclusive upper range allows you to have a defined upper boundary when working with subscripted ranges, such as Name ("a"):("b"), where Name ("aa") and Name ("aaaaa") are equally valid ranges to precede Name ("b").

    You can use the reserved words BEGIN and END to refer to the first and last possible subscripts; however, you cannot use the asterisk (*) wildcard with subscripted globals because global subscripts must be mapped individually.

    For more information about subscript-level mapping (SLM) ranges, see Setting Global Mappings in the “Global Structure” chapter of Using Globals.

  6. Click Advanced to display the following:

    1. Select the Collation. Collation applies only to new subscript-level mapping globals.

    2. Select the Lock Database Location. For more information see Global in the “[Map]” section of the Configuration Parameter File Reference.

  7. Click OK.

    Note:

    >> displayed in the first column of the new mappings row indicates that you opened the mapping for editing.

  8. To save the mappings in the cpf file, click Save Changes.

Important:

While it is possible to add a mapping that changes the database location of an existing global, this does not actually move the global. As a consequence, the global becomes inaccessible, as it remains in the original database while the namespace expects to find it in the newly mapped database. For a new mapping for an existing global to be successful, you must relocate the global manually, for example using the Terminal or Studio, by creating it on the new database and removing it from the original database.

Routine Mappings

You can add mappings to your namespace at the routine level that overrides the default database mapping for routines of the namespace:

  1. Navigate to the Namespaces page (System Administration > Configuration > System Configuration > Namespaces) and click Routine Mappings in the row of the namespace where you want to map the global.

  2. From the Routine Mappings page, click New.

  3. Select the Routine database location database where the routine is located.

  4. Enter the Routine name. The routine does not have to exist when you map it (that is, it can be the name of a routine you plan to create).

  5. Click OK.

    Note:

    >> displayed in the first column of the new mappings row indicates that you opened the mapping for editing.

  6. To save the mappings in the cpf file, click Save Changes.

For example, using the preceding Test Namespace Mapping example, if you plan to create a schedule routine (for example, BOSZZairline) in the airports database (in the FlightSchedule namespace) and you want it to be available to users in the TravelAgent namespace, navigate to the Routine Mappings page (in the TravelAgent namespace row), then click New Routine Mapping. Enter the information as shown in the following Routine Mapping dialog box:

Important:

When you map one or more routines, be sure to identify all the code and data needed by those routines, and ensure that all that code and data is available in all the target namespaces. The mapped routines could depend on the following items:

  • Include files

  • Other routines

  • Classes

  • Tables

  • Globals

Use additional routine, package, and global mappings as needed to ensure that these items are available in the target namespaces.

Package Mappings

You can add a class package mappings which makes all the classes within a package (and all the generated routines for those classes) in a specific database visible to another namespace:

  1. Navigate to the Namespaces page (System Administration > Configuration > System Configuration > Namespaces) and click Package Mappings in the row of the namespace where you want to map the package.

  2. From the Package Mappings page, click New.

  3. Select the Package database location database where the package is located.

  4. Select the Package name. The package does not have to exist when you map it (that is, it can be the name of a package you plan to create); you can specify a new package name, as follows:

    1. Click New Package.

    2. In the New package name text box, enter a name.

  5. Click OK.

    Note:

    >> displayed in the first column of the new mappings row indicates that you opened the mapping for editing.

  6. To save the mappings in the cpf file, click Save Changes.

See the Package Mapping section in the “Packages” chapter of Defining and Using Classes for a description of packages and the procedure for mapping them.

Important:

When you map a package, be sure to identify all the code and data needed by the classes in that package, and ensure that all that code and data is available in all the target namespaces. The mapped classes could depend on the following items:

  • Include files

  • Routines

  • Other classes

  • Tables

  • Globals

Use additional routine, package, and global mappings as needed to ensure that these items are available in the target namespaces.

Mapping Data to All Namespaces

In addition to mapping globals, routines, and packages to specific namespaces, you can map them to all namespaces. To enable this form of mapping:

  1. First, create a namespace named %ALL, as described in the Create/Modify a Namespace section.

    Note:

    %ALL is not visible except for the purposes of mapping data; that is, it is not a real namespace, but a mechanism for mapping data to all namespaces.

  2. Then, make the desired mappings in the %ALL namespace, as described in the Add Global, Routine, and Package Mapping to a Namespace section.

These %ALL mappings apply in all namespaces. You cannot create namespace-specific mappings to resources that are mapped in the %ALL namespace, as %ALL mappings override any namespace-specific mappings to the same resource.

When you create a subscript-level mapping in the %ALL namespace, a mapping for the root global is automatically created to %DEFAULTDB. The %DEFAULTDB variable represents the default database for any given namespace.

Delete a Namespace

You can delete a namespace, including all mappings associated with it:

  1. Navigate to the Namespaces page (System Administration > Configuration > System Configuration > Namespaces) and click Delete in the row of the namespace you want to delete.

  2. On the Delete Namespaces page, if you want to delete the Web Gateway pages from the physical path, select the check box.

  3. To delete the namespace and associated mappings, click Perform Action Now.

Configuring Databases

A database is a IRIS.DAT file you create using the Database Wizard. An InterSystems IRIS database holds data in multidimensional arrays called globals and executable content called routines, as well as class and table definitions. Globals and routines encompass such things as methods, classes, web pages, SQL, BASIC, and JavaScript files.

Caution:

On Windows systems, do not use file compression on IRIS.DAT database files. (Files are compressed by right-clicking a file or folder in Windows Explorer and selecting Properties, then Advanced, then Compress contents to save disk space; once compressed, a folder name or filename is rendered in blue in Windows Explorer.) If you compress a IRIS.DAT file, the instance to which it belongs will fail to start, with misleading errors.

InterSystems IRIS databases dynamically expand as needed (assuming free space is available), though you can specify a maximum size. A database can grow until it is 32 terabytes if you are using the default 8KB block size.

You can make most database configuration changes dynamically; you can create and delete databases and modify database attributes while the system is running.

Before configuring databases on your instance, review the database considerations discussed in the next section.

Issues to consider before configuring databases in your instance and the wizards for local and remote database creation are described in the following sections:

Database Considerations

This section discusses the following topics:

Database Total Limit

The absolute limit on the number of databases that can be configured within a single InterSystems IRIS instance (given sufficient storage space) is 15,998. There are other limitations as follows:

  • The directory information for databases cannot exceed 256 KB. This means that if the average length of a database directory name is longer, an instance can have fewer total databases. The following formula describes this relation:

    maximum_DBs = 258048/ (avg_DB_path_length + 3)

    For example, if all database directory paths are of the form c:\InterSystems\IRIS\mgr\DBNNNN\, the average length is 33 bytes. Thus, the maximum number of databases is 7,168, calculated as follows: 258048/ (33 + 3) = 7168.

  • Mirrored databases count twice toward the absolute limit of 15,998. If all databases on the instance are mirrored, the effective limit is 7,499 databases. This is because InterSystems IRIS creates two database definitions for mirrored databases; one for the directory path (c:\InterSystems\IRIS\mgr\DBNNNN\), and one for the mirror definition (:mirror:MIRRORNAME:MirrorDBName).

  • The number of databases that can be in use simultaneously is limited by the operating system’s restriction on the number of open files (either per process or system-wide). InterSystems IRIS reserves approximately half of the operating system’s open file allocation for its own use and devices.

Database Configuration Considerations

The following are tips to consider to consider when configuring databases:

  • InterSystems IRIS provides a seamless option to spread data across multiple physical database (IRIS.DAT) files. Therefore, you can build applications with multiple databases or splitting data by global or subscript-level mappings, as appropriate.

  • Keep database sizes within a manageable value based on the infrastructure available for administration tasks such as backup, restore, integrity checks, etc.

  • It is recommended that stream globals (if storing streams within IRIS.DAT database files) be global mapped to a separate database, and that the stream database(s) be configured with a large (64 KB) block size.

  • Depending on your workload, it may be beneficial to consider alternate (larger) block sizes than the default 8 KB database block size. For general guidelines, see Large Block Size Considerations below.

Large Block Size Considerations

In addition to the 8 KB (default) block size supported by InterSystems IRIS (which is always enabled), you can also enable the following block sizes:

  • 16 KB (16384)

  • 32 KB (32768)

  • 64 KB (65536)

However, you should exercise caution when creating your database to use large block size because using them can impact the performance of the system. Consider the following before enabling and using large block sizes:

  • If your application workload consists primarily of sequential inserts or sequential reads/queries, large block sizes may improve performance.

  • If your application workload consists primarily of random inserts or random reads/queries, large block sizes may degrade performance. Since larger block sizes result in fewer blocks being cached for a given total size of database cache, to reduce the impact on random database access, you should also consider making more total memory available as database cache.

  • For index-type databases, the default block size (8 KB) ensures optimum performance; larger block sizes potentially degrade performance. If you are considering larger block sizes for your data, you should consider mapping index globals to a separate 8 KB block size database.

To create a database that uses block sizes other than the supported blocks, do the following:

  1. Enable the block sizes using the setting on the Startup Settings page (System Administration > Additional Settings > Startup), described in the DBSizesAllowed entry in Configuration Parameter File Reference.

  2. Configure the database cache for the enabled block size on the Startup Settings page (System Administration > Additional Settings > Startup), as described in Memory and Startup Settings.

  3. Restart InterSystems IRIS.

  4. Create the database as described in Create Local Databases in this chapter.

Database Compatibility Considerations

As described in the Create a Local Database procedure, you can copy or move an InterSystems IRIS database to an instance other than the one in which it was created by copying or moving its IRIS.DAT file, or temporarily mount a database created in another instance on the same system. You can also restore a backup of a database (see the “Backup and Restore” chapter of the Data Integrity Guide) to an instance other than its original instance. To avoid data incompatibility, however, the following requirements must be met:

  • The target (new) instance must use the same character width (8-bit or Unicode; see Character Width Setting in the Installation Guide) and the same locale (see Using the NLS Settings Page of the Management Portal in the “Configuring InterSystems IRIS” chapter of the System Administration Guide) as the instance that created the database.

    The one exception to this requirement is that an 8-bit instance using a locale based on the ISO 8859 Latin-1 character set is compatible with a Unicode instance using the corresponding wide character locale. For example, a database created in an 8-bit instance using the enu8 locale can be used in a Unicode instance using the enuw locale.

  • If the source and target instances are on systems of different endianness, the database must be converted to the endianness of the target instance before being used.

    Depending on the platform, multibyte data is stored with either the most significant byte or the least significant byte in the lowest memory address (that is, first): when the most significant byte is stored first, it is referred to as “Big-endian;” when the least significant byte is stored first, it is referred to as “Little-endian.”

    When defining a database using an existing IRIS.DAT created on a system of different endianness, use the cvendian utility (see the Using cvendian to Convert Between Big-endian and Little-endian Systems section of the “Migration and Conversion Utilities” chapter of Specialized System Tools and Utilities) to convert the database before you use it. When restoring a backup of a database to a system of different endianness than the source system, see Considering Endianness in the “Backup and Restore” chapter of the Data Integrity Guide.

Local Databases

The Local Databases page displays the following information about the databases on your system:

  • Name — Database name.

  • Mirror — If the database is mirrored, the name of the mirror; for more information see Add Databases to the Mirror in the “Mirroring” chapter of the High Availability Guide.

  • Directory — Location of the IRIS.DAT file.

  • Size (MB) — Size of the database in megabytes.

  • Status — Specifies whether or not the database is mounted, unmounted, or dismounted; if it is mounted, specifies whether it has read-only or read-write permission. For more information, see The Local Databases List Information table in Maintaining Local Databases in the “Managing InterSystems IRIS” chapter of this guide.

  • Resource Name — The name of the database resource that governs access to the database; for more information, see the “Assets and Resources” chapter in the Security Administration Guide.

  • Encrypted — Specifies whether or not the database is encrypted; for more information, see the “Managed Key Encryption” chapter in the Security Administration Guide.

  • Journal Specifies whether or not the database is journaled; for more information, see the “Journaling” chapter of the Data Integrity Guide.

You can use this page to:

Create a Local Database

To create a local database, navigate to the Local Databases page (System Administration > Configuration > System Configuration > Local Databases).

  1. Click Create New Database to open the Database Wizard.

  2. Enter a database name in the text box. A database name must

    • not already be in use within the InterSystems IRIS instance

    • be between one and 30 characters long

    • start with an alphabetic character or an underscore; the remainder can include alphanumeric characters, dashes, or underscores

  3. The first time you create a local database in an InterSystems IRIS instance using a particular browser, you must either

    • enter the name of the database directory, in which case this directory, containing the IRIS.DAT file, is created in c:\InterSystems\mgr once you confirm it

    • click the folder icon to browse to an existing directory, in which case the IRIS.DAT file is created in that directory

    Thereafter, by default a directory of the same name as the database name you provide, containing the IRIS.DAT file, will be created in the same location as the previous database directory. For example, if you first create database db22 in any directory under c:\InterSystems\mgr, when you click Create New Database again and enter db33 in the Enter the name of your database box, c:\InterSystems\mgr\db33 is automatically filled into the Database directory text box. If you change this to c:\InterSystems\db33 and create db33, the base directory c:\InterSystems will be filled in the next time.

  4. Click Next to continue configuring the database. If a IRIS.DAT file already exists in the directory you specified, you are warned of this and can either

    • Click Finish to use the existing file, in which case all of the databases characteristics are determined by the IRIS.DAT file. You would typically do this when copying or moving a database from another instance, or temporarily mounting a database created in another instance on the same system.

    • Click Back to specify another directory, then click Next again to continue specifying the characteristics of the new database in the next step.

  5. In the Initial Size text box, type the number of megabytes for your database size (the default is 1 MB).

    Note:

    You cannot create or edit a database so that its size is larger than the total available disk space. If the size you specify is within 90% of the disk's free space, you are warned and must confirm the action.

  6. Select the desired block size from the Block size for this database will be drop-down list. By default, all new databases are created with a Block Size of 8 KB.

    Caution:

    Do not select block sizes other than 8 KB from the drop-down list unless you have read and understand the guidelines described in “Large Block Size Considerations” in the Configuring Databases section of this chapter.

  7. Select whether or not you want to journal globals in this database from the Journal globals? drop-down list. See the “Journaling” chapter of the Data Integrity Guide.

    Note:

    If you are configuring the database to store temporary globals, setting the Journal globals property to No is not the same as storing the temporary globals in IRISTEMP; for more information, see Using Temporary Globals and IRISTEMP in the “Journaling” chapter of the Data Integrity Guide.

  8. If encryption is activated, you can encrypt this database by selecting Yes for Encrypt Database?.

  9. If the instance is part of a mirror, you can add this database to the mirror by selecting Yes for Mirrored Database?. See Add Databases to the Mirror in the “Mirroring” chapter of the High Availability Guide for information about creating mirrored databases.

  10. From this panel onward, you can click Next. to continue configuring the database or Finish to accept the remaining defaults

  11. Choose the resource to control access to this database:

    • Default — %DB_%DEFAULT

    • Existing — Choose from a list of existing database resources

    • New — Create a new database resource (the new name defaults to %DB_% database name)

  12. Click Next to view a list of the database attributes.

  13. Click Finish to add your database.

You are now ready to configure and manage your new database.

Note:

To protect you from accidentally corrupting a database, you cannot open or write to an operating system file called IRIS.DAT, even if it is not a mounted database.

Edit a Local Database’s Properties

The information displayed varies depending on whether or not the database is mirrored. This section identifies the fields for:

Edit Nonmirrored Local Database Properties

Click the name of a nonmirrored database to view the following database properties and change some of them. (The “Create a Local Database” section describes many of these fields.)

  • Name

  • Directory (this setting must always reflect the location of the IRIS.DAT database file)

  • Encrypted (cannot be changed)

  • Mirrored — Click the Add to Mirrormirror_name link to add the database to the mirror in which the InterSystems IRIS instance is the primary failover member. (This option is available only when the instance is the primary in a mirror.) See Add an Existing Database to the Mirror in the “Mirroring” chapter of the High Availability Guide for more information.

  • Block Size (Bytes) (cannot be changed)

  • Size (MB) — There are three size settings, as follows:

    • Change Current to modify the current size of the database.

      Note:

      You cannot create or edit a database so that its size is larger than the total available disk space. If the size you specify is within 90% of the disk's free space, you are warned and must confirm the action.

    • Expansion sets the amount by which to expand the database when required; the default (and recommended) setting of zero (0) indicates 12% of current size or 10 MB, whichever is larger. When using 12% of the current size, the expansion size will not be greater than 1GB.

    • Maximum specifies the maximum size to which the database can grow, in megabytes; the default setting of zero (0) indicates no maximum. To modify this setting, you can enter a new number of MB, or you can precede a number by + or -, for example +10 or -20, to enlarge or reduce the maximum by the specified amount. When you reduce the maximum size of a database, you are warned and must confirm the action.

  • Resource Name — Select the resource with which to associate the database. Click the resource icon next to the drop-down to display the Resources page so you can create a resource.

  • New Global — Specify attributes for new globals.

  • Global Journal State — Select to enable journaling, clear to disable. See the “Journaling” chapter of the Data Integrity Guide.

  • Preserve global attributes on delete — Specify whether a global’s directory entry and attributes should be preserved when it is deleted; attributes include collation, journaling status, and growth pointer. Select to preserve a global’s directory entry and attributes when the global is entirely deleted; clear to remove the directory entry and attributes.

  • Mount Read-Only — Select to specify that the database be mounted as read-only; clear to specify that it be mounted as read-write.

  • Mount Required at Startup — Select to indicate that the database must be mounted when InterSystems IRIS starts up; if the database cannot be mounted, InterSystems IRIS does not start. This lets you ensure that journal recovery and transaction rollback can be performed on the database before startup following a crash (as described in the “Journaling” chapter of the Data Integrity Guide). Clear to let InterSystems IRIS start without first mounting the database.

    Note:

    By default, this setting is selected for required InterSystems IRIS databases (for example, IRISLIB and IRISAUDIT) and cannot be changed. The default is cleared but can be selected for databases that you create, as well as the USER and ENSLIB databases). For additional information about database status and explicitly dismounting and mounting databases, see The Local Databases List Information table in Maintaining Local Databases in the “Managing InterSystems IRIS” chapter of this guide.

  • Stream Location — Click the Browse button to select the directory in which streams associated with this database are stored. By default, the stream location for a local database is a subdirectory named stream in the database Directory, which is one of the above fields (for example, install-dir\mgr\DB1\stream).

    Note:

    InterSystems recommends that you use the default location.

Edit Mirrored Local Database Properties

Click the name of a mirrored database to view and change some of the following database properties; see definitions in the previous section.

Note:

Journaling is required for a mirrored database, therefore the Global Journal State setting does not appear.

  • Name

  • Mirror Name — Name by which the database is identified within the mirror; cannot be changed.

  • Directory (this setting must always reflect the location of the IRIS.DAT database file)

  • Encrypted (cannot be changed)

  • Stream Location — Click the Browse button to select the directory in which streams associated with this database are stored. By default, the stream location for a local database is a subdirectory named stream in the database Directory, which is one of the above fields (for example, install-dir\mgr\DB1\stream).

    Note:

    Like other database-related data that is not contained in the database itself (see Mirror Configuration Guidelines in the “Mirroring” chapter of the High Availability Guide), a mirrored database’s file streams are not mirrored. (For information about file streams, see the “Working with Streams” chapter of Defining and Using Classes.)

    InterSystems recommends that you use the default location.

  • Resource Name — Select the resource with which to associate the database. Click the resource icon next to the drop-down to display the Resources page so you can create a resource.

  • Block Size (Bytes) (cannot be changed)

  • Collation — Among global attributes, only the collation attribute can be changed, for new globals only.

  • Preserve global attributes on delete — Specify whether a global’s directory entry and attributes should be preserved when it is deleted; attributes include collation, journaling status, and growth pointer. Select to preserve a global’s directory entry and attributes when the global is entirely deleted; clear to remove the directory entry and attributes.

  • Mount Read-Only — Select to specify that the database be mounted as read-only; clear to specify that it be mounted as read-write.

  • Mount Required at Startup — Select to indicate that the database must be mounted when InterSystems IRIS starts up or becomes a mirror primary; if the database cannot be mounted, InterSystems IRIS does not start or become primary. This lets you ensure that journal recovery and transaction rollback can be performed on the database before startup following a crash (as described in the “Journaling” chapter of the Data Integrity Guide) and that open transactions on the former primary have been rolled back as part of failover. Clear to let InterSystems IRIS start without first mounting the database. For additional information about the Mount Required at Startup setting, see The Local Databases List Information table in Maintaining Local Databases in the “Managing InterSystems IRIS” chapter of this guide.

  • Local Properties — This area contains three size settings, as follows:

    • Change Size to modify the current size of the database.

      Note:

      You cannot create or edit a database so that its size is larger than the total available disk space. If the size you specify is within 90% of the disk's free space, you are warned and must confirm the action.

    • Expansion sets the amount by which to expand the database when required (and assuming free space is available); the default (and recommended) setting of zero (0) indicates 12% of current size or 10 MB, whichever is larger.

    • Maximum specifies the maximum size to which the database can grow, in megabytes; the default setting of zero (0) indicates no maximum. To modify this setting, you can enter a new number of MB, or you can precede a number by + or -, for example +10 or -20, to enlarge or reduce the maximum by the specified amount. When you reduce the maximum size of a database, you are warned and must confirm the action.

    This area also contains the current, expansion, and maximum size settings for Other System — if the current instance is a failover member, this is the other failover member; if the current instance is an async member, this is the first failover member that the async could obtain the information from. For important information about how the properties of a mirrored database on the backup and async mirror members are synchronized with those on the primary, see Mirrored Database Considerations in the “Mirroring” chapter of the High Availability Guide.

Relocate a Local Database

To move a local database’s IRIS.DAT file to a different directory, you must do the following:

  1. Make note of the current database directory. You can view this information from the Local Databases page (System Administration > Configuration > System Configuration > Local Databases).

  2. Perform a clean shut down of the instance, such as by using the iris stop command.

  3. Copy the IRIS.DAT file and the stream directory from the current database directory to the desired location.

    Important:

    If there is an iris.lck file in the database directory, do not attempt to move the database. This means the database is still in use, and attempting to move it could lead to unforeseen problems. Contact the InterSystems Worldwide Response Center (WRC) for assistance.

  4. Open the iris.cpf file for the instance in a text editor. This file is usually located in the installation directory.

  5. Locate the name of the database beneath the [Databases] section. Replace the old directory path with the new path, then save iris.cpf.

  6. Start the InterSystems IRIS instance, and view the Local Database page to confirm that the directory is set to the new location. If the database is mirrored, it needs to be activated and caught up.

  7. Delete the old database directory.

Important:

After you relocate a local database directory, you must also update any systems that access the database remotely (such as ECP application servers). On each remote system, update the remote database directory to the new location, as described in the Remote Database section of the “Configuring InterSystems IRIS” chapter in System Administration Guide.

Delete a Local Database

To delete a local database, click the Delete link in the appropriate row. The Delete Database page displays information about the database you are deleting, and lets you:

  • Select the namespaces mapped to this database for deletion. You cannot delete a database if a namespace is mapped to it, so unless you select all of the listed namespaces you cannot delete the database.

    You cannot delete namespaces that are also mapped to other databases. When this is the case, a link is provided to take you to the Namespaces page, where you can modify the database mappings of the namespaces involved. After you delete all mappings to another database, that database will be removed from the list of databases you have to delete.

  • You can choose to delete the database’s IRIS.DAT file, if and only if:

    • No other databases use this IRIS.DAT file.

    • You have marked all namespaces mapped to the database for deletion.

    If these conditions are not met, you can still delete the database from the current configuration, but the IRIS.DAT file cannot be deleted.

  • Confirm that you want to delete the database after reviewing information about it by clicking Delete Database Now.

If you cannot or chose not to delete the IRIS.DAT file, the database is still removed from the Databases section of the InterSystems IRIS parameters file and therefore from the list of local databases displayed by the Management Portal.

Remote Databases

A remote database is a database that is physically located on another server system, as opposed to a local database which is physically located on the local server system.

From the Remote Databases page you can perform the following tasks:

Add a Remote Database

You can define a remote database on the local server if the database’s host is configured on that server as a distributed cache data server. For instructions for adding a data server, see Configuring an Application Server in the “Horizontally Scaling Systems for User Volume with InterSystems Distributed Caching” chapter of the Scalability Guide.

To add a remote database, follow these steps:

  1. Navigate to the Remote Databases page (System Administration > Configuration > System Configuration > Remote Databases) and click Create Remote Database to launch the wizard.

  2. Select the data server that hosts the database from the Remote Server drop down.

  3. Choose how you want to specify the remote database directory from the Remote Directory radio buttons:

    • Select databases from a list lets you choose from a drop-down list of database directories on the remote server. If the remote data server cannot currently be reached, the drop-down list is empty.

    • Enter your own database specification lets you enter the database directory directly, but the Portal does not validate your entry.

  4. Enter a database name (its name on the local server; it does not need to match its name on the remote server). You have defined a remote database.

    Database names are between 1 and 30 characters long, can start with an alphabetic character or an underscore. The remaining characters can be alphanumeric, a dash, or an underscore.

  5. You can optionally specify the directory in which streams associated with this database are stored. By default, the stream location for a remote database is the InterSystems IRIS Temp directory (install-dir\mgr\Temp).

    Note:

    InterSystems recommends that you use the default location.

  6. Click Save to configure the remote database.

You can click the Edit link for a remote database at any time to modify the remote database fields.

Delete a Remote Database

To delete a remote database, click the Delete link in the appropriate row. The Delete Database page displays information about the database you are deleting, and lets you:

  • Select the namespaces mapped to this database for deletion. You cannot delete a database if a namespace is mapped to it, so unless you select all of the listed namespaces you cannot delete the database.

    You cannot delete namespaces that are also mapped to other databases. When this is the case, a link is provided to take you to the Namespaces page, where you can modify the database mappings of the namespaces involved. After you delete all mappings to another database, that database will be removed from the list of databases you have to delete.

  • Confirm that you want to delete the database after reviewing information about it by clicking Delete Database Now.

This action simply removes the database from the local instance’s remote database configuration; the actual database and its local configuration on its host are not affected.

Configuring Task Manager Email Settings

You can set the Task Manager to send email notification when a task completes, as described in the Using the Task Manager section of the “Managing InterSystems IRIS” chapter of this guide. On the Task Manager Email Settings page (System Administration > Configuration > Additional Settings > Task Manager Email), you can configure the notification settings:

SMTP Server and Port

Address and port of your outgoing SMTP (Simple Mail Transfer Protocol) mail server

SSL Config

The SSL configuration to use if you want to encrypt the email using SSL/TLS. If there are no SSL configurations on the instance, or you want to create a new one, see Creating or Editing an SSL/TLS Configuration in the “Using SSL/TLS with InterSystems IRIS” chapter of the Security Administration Guide. If you do not select an SSL configuration, SSL/TLS will not be used.

SMTP Auth User and Password

Required only for SMTP authentication to the SMTP server. See RFC 2554 for details. If you do not provide entries, SMTP username and password are set to NULL.

Sender

Required only for SMTP authentication to the SMTP server. See RFC 2554 for details.

Reply To

Email address to which the recipient should reply

Success Subject

The formatted subject line of a successful task message. See the section “Parameters for Subjects and Messages” below.

Success Message

The formatted message sent after a successful task runs

Failure Subject

The formatted subject line of a failed task message

Failure Message

The formatted message sent after a task fails

Note:

You can also configure email settings programmatically through the %SYS.Task.Config class.

Parameters for Subjects and Messages

Format the information in the subject and message text boxes using the task parameters listed at the bottom of the web page and defined in the following table. The web page includes examples.

Task Parameter Description
ID Task ID
DESCRIPTION Task description
NAME Task name
LASTSTARTED Last time the task started
LASTFINISHED Last time the task finished
SCHEDULED Last scheduled starting time
CURRENTDATE Date the email sent
CURRENTTIME Time the email sent
STATUS Return value of the task
TASKCLASS Task class used for this task; for example, %SYS.Task.IntegrityCheck for a database integrity check task,
ERROR Error code if task failed
SUCCESS Completed message if task ran successfully

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.

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

The System Classes for National Language Support section of the “Customizing the InterSystems IRIS System” chapter of Specialized System Tools and Utilities 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.