Configuring Caché
A Caché configuration is composed of system configuration information, namespaces, databases, operator task configurations, network connections, and other advanced settings.
Use the Management Portal to set up a Caché system and view its configuration parameters. You can use the portal to adjust system settings as well as to create and modify namespaces, databases, and network connections, and to connect to the CSP Gateway to configure CSP applications.
The major configuration tasks are subdivided into categories, which are divided into subcategories. This chapter describes some of the topics; other topics have separate chapters or documents as references. The configuration tasks are:
System Configuration — See the System Configuration Tasks table in this chapter.
Connectivity — See the Connectivity Tasks table in this chapter.
Mirror Settings — See the Configuring Mirroring section in the “Mirroring” chapter of the Caché High Availability Guide.
Database Backup — See the Configuring Caché Backup Settings section in the “Backup and Restore” chapter of the Caché Data Integrity Guide.
CSP Gateway Management — See the “CSP Configuration” chapter of Using Caché Server Pages.
SQL and Object Settings — See the SQL and Object Settings section in the “Caché Additional Configuration Settings” chapter of Caché Additional Configuration Settings Reference.
Device Settings — See the Device Settings section in the “Caché Additional Configuration Settings” chapter of Caché Additional Configuration Settings Reference.
National Language Settings — See the Configuring National Language Support (NLS) section in this chapter.
Zen Reports — See the “Zen Reports” section of the Caché Additional Configuration Settings Reference, and the Configuring Zen Reports for PDF Output section of the “Running Zen Reports” chapter of Using Zen Reports.
Additional Settings — See the Additional Tasks table in this chapter.
Configure settings for this system from the System Configuration menu.
| Menu Item | Documentation Source |
|---|---|
| Memory and Startup | Configuring System Information section of this chapter |
| Namespaces | Configuring Namespaces section of this chapter |
| Local Databases | Configuring Databases section of this chapter |
| Remote Databases | Remote Databases section of this chapter |
| Journal Settings | Configuring Journal Settings section of the “Journaling” chapter of the Caché Data Integrity Guide |
Configure network connections with other systems from the Connectivity menu.
| Menu Item | Documentation Source |
|---|---|
| ECP Settings | “Configuring Distributed Systems” chapter of the Caché Distributed Data Management Guide. |
| Shadow Server Settings | Configuring Shadowing section of the “Shadowing” chapter of the Caché Data Integrity Guide. |
| SQL Gateway Settings | Creating Gateway Connections for External Sources in the “Using the Caché SQL Gateway” chapter of Using Caché SQL. |
| JDBC Gateway Settings | “Using the Caché SQL Gateway with JDBC” chapter of Using Caché with JDBC. |
| Object Gateway Settings |
“Setting Gateway Server Properties” chapter of Using the Caché Gateway for .NET. |
| XSLT 2.0 Gateway Server | Configuring, Starting, and Stopping the XSLT 2.0 Gateway in the “Performing XSLT Transformations” chapter of Using Caché XML Tools. |
| Cluster Settings | Configuring Cluster Settings section of this chapter. |
Configure additional settings from the Additional Settings menu. For a summary of additional configuration settings, see the Caché Additional Configuration Settings Reference.
| Menu Item | Documentation Source |
|---|---|
| Compatibility | Miscellaneous Settings of Caché Additional Configuration Settings Reference. |
| Advanced Memory | Advanced Memory Settings of Caché Additional Configuration Settings Reference. |
| Monitor | “Monitoring Caché Using BMC PATROL”, “Monitoring Caché Using SNMP”, and “Monitoring Caché Using WMI” appendixes of the Caché Monitoring Guide. |
| Source Control | “Using Studio Source Control Hooks” appendix of Using Studio. |
| Startup | Startup Settings in the Caché Additional Configuration Settings Reference. |
| Task Manager Email Settings | Configuring Task Manager Email Settings in this chapter. |
Most configuration changes can be done dynamically and do not require you to restart Caché. When the update does require a restart, the portal notifies you.
This chapter covers the following topics:
Configuring Data
Caché 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. A Caché system may (and usually does) have multiple databases.
Each Caché 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 Caché. (For information about allocating the database cache, see Memory and Startup Settings.)
Caché 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. A Caché system may (and usually does) have multiple namespaces. Caché 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 entries 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.
Caché comes with the following predefined namespaces:
%SYS — System management information and utilities.
DOCBOOK — Documentation.
SAMPLES — Sample code and applications.
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 size of the namespaces table is automatic and not configurable. For more information about namespaces, see the “Namespaces and Databases” chapter of the Caché Programming Orientation Guide.
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:
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, DOCBOOK, DOCUMATIC, %SYS.
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 checkbox described in step 6 below.
Choose whether the default database for globals is local or remote.
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.
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.
Select the Create a default Web application for this namespace check box if you are creating a web application that accesses this namespace.
After entering the required information, click Save to add your namespace to the configuration.
Create a Namespace on an Ensemble Instance
When you create a namespace on an Ensemble instance, the Make this an Ensemble namespace check box is displayed at the bottom of the New Namespace page and is automatically selected. To create a namespace that is not Ensemble-enabled, clear this check box before clicking Save.
If you do not clear the check box and create an Ensemble-enabled namespace, the system automatically performs additional configuration tasks for the new namespace, as follows:
If the default global 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 Ensemble 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 Ensemble 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 Ensemble: /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 Caché, using the following procedure:
Go to the Namespaces page (System Administration > Configuration > System Configuration > Namespaces).
On the Namespaces page, click the name of namespace you wish to modify.
Change or replace the existing name to rename the namespace.
Important:If you are renaming an Ensemble-enabled namespace, you must take additional steps to complete the process.
Open the InterSystems Terminal from the System Tray.
Enter:
do ##class(%Library.EnsembleMgr).EnableNamespace("<NewNamespace>",1)
Where <NewNamespace> is the new name of the existing namespace.
Go to the Web Applications page (System Administration > Security > Applications > Web Applications).
Find the name of the application that corresponds to the old name of the namespace, and click Delete.
Click the name of the application that corresponds to the new name of the namespace.
Select Namespace Default Application and click Save.
In the Terminal, enter:
do ##class(%EnsembleMgr).DisableNamespace("<OldName>",1)
Where <OldName> is the original name of the namespace that you are renaming.
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 CACHETEMP; for more information, see Using Temporary Globals and CACHETEMP in the “Journaling” chapter of the Caché Data Integrity Guide.
Click Save.
Users directly accessing the database at the time of the change may need to log out of and then back into Caché to update their namespace mapping.
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. For more information about mapping globals, routines, and packages, see the “Useful Skills to Learn” chapter of the Caché Programming Orientation Guide.
Mappings are sorted alphabetically; if subscripts are specified, they are sorted by name and subscript. See the “Global Structure” chapter of the Using Caché 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:
Data and programs are stored in Caché databases, the physical storage locations, and referred to by namespaces, the logical references.
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:
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.
From the Global Mappings page click New Global Mapping.
Select the Global database location database where the global is located.
Enter the Global name. You can use the * character as part of the global name to specify multiple globals, for example ABC*.
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 Caché Globals.
Click Advanced to display the following:
Select the Collation. Collation applies only to new subscript-level mapping globals.
Select the Lock Database Location. For more information see Global in the “[Map]” section of the Caché Parameter File Reference.
Click OK.
Note:>> displayed in the first column of the new mappings row indicates that you opened the mapping for editing.
To save the mappings in the cpf file, click Save Changes.
While it is possible to add a mapping changing 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 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:
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.
From the Routine Mappings page, click New Routine Mapping.
Select the Routine database location database where the routine is located.
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).
Click OK.
Note:>> displayed in the first column of the new mappings row indicates that you opened the mapping for editing.
To save the mappings in the cpf file, click Save Changes.
For example, using the preceding Sample 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:
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:
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.
From the Package Mappings page, click New.
Select the Package database location database where the package is located.
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:
Click New Package.
In the New package name text box, enter a name.
Click OK.
Note:>> displayed in the first column of the new mappings row indicates that you opened the mapping for editing.
To save the mappings in the cpf file, click Save Changes.
See the Package Mapping section in the “Packages” chapter of Using Caché Objects for a description of packages and the procedure for mapping them.
For example, to make the class definitions in the Cinema package of the SAMPLES database available in the TESTSAMPLES namespace, navigate to the Package Mappings page and click New Package Mapping. Enter the information as shown in the following Package Mapping dialog box:
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:
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 (except DOCBOOK and SAMPLES).
Then, make the desired mappings in the %ALL namespace, as described in the Add Global, Routine, and Package Mapping to a Namespace section.
Note:For mappings in the DOCKBOOK and SAMPLES namespaces, you must create the mappings separately.
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:
Navigate to the Namespaces page (System Administration > Configuration > System Configuration > Namespaces) and click Delete in the row of the namespace you want to delete.
On the Delete Namespaces page, if you want to delete the CSP pages from the physical path, select the check box.
To delete the namespace and associated mappings, click Perform Action Now.
Configuring Databases
A database is a CACHE.DAT file you create using the Database Wizard. A Caché 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 (CSP and HTML), SQL, BASIC, and JavaScript files.
On Windows systems, do not use file compression on Caché CACHE.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 CACHE.DAT file, the instance to which it belongs will fail to start, with misleading errors.
Caché 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 Caché wizards for local and remote database creation are described in the following sections:
Database Considerations
This section discusses the following topics:
Database Configuration Limits
The absolute limit on the number of databases that can be configured within a single Caché instance (given sufficient storage space) is 15,998. However, because database directory information for all databases in an instance is limited to 64KB, the practical maximum depends on the number of bytes used in their database directory paths, and is likely to be much lower. Because mirrored databases (see the Mirroring chapter of the Caché High Availability Guide) require additional database directory information, the precise minimum depends on the number of mirrored databases involved, if any. The different calculations for non-mirrored and mirrored databases are described in the following sections.
The number of databases that can be in use simultaneously is further limited by the operating system’s limit on the number of open files (either per process or system-wide), minus what Caché reserves for its own use and devices, which is approximately half.
Calculating the Maximum Non-mirrored Databases per Instance
For non-mirrored databases, the maximum databases per instance can be calculated using the following formula:
maximum_DBs = 65512 / (avg_DB_path_length + 3)
For example, if all database directory paths are of the form c:\InterSystems\Cache\mgr\DBNNNN\, the average length is 33 bytes, and the maximum number of databases is therefore 65512 / 36, or 1,819.
Calculating the Maximum Mirrored Databases per Instance
A mirrored databases has both a local database name and a mirror database name, which is its name within the mirror (see Adding Databases to a Mirror in the “Mirroring” chapter of the Caché High Availability Guide), and is referenced within ECP by its mirror database name in the format :mirror:mirror_name:mirror_DB_name (see Configuring ECP Connections to a Mirror in the “Mirroring” chapter). Because its mirror database name and mirror name are therefore stored along with its database directory path, the average length of the information for a mirrored database is greater. In addition, each mirrored database counts twice against the absolute maximum of 15,998. The maximum number of configurable databases on a mirror member is therefore lower and requires a more complex calculation.
The formula for the practical maximum on a mirror member depends not only on the average database directory path length but also on the mirror name length, the average mirror database name length, and the proportion of the total databases that are mirrored, as follows:
maximum_DBs = 65512 / ((avg_DB_path_length + 3) + ((mirror_name + avg_mirror_DB_name + 49) * mirrored_DB_%))
For example, taking the database directory path of 33 bytes from the preceding example and adding a mirror name of MYMIR, a standard mirror database name of DBNNNN, and a mirrored database proportion of 80%, the maximum would be 65512 / (36 + ((5 + 6 + 49) * .8)) = 65512 / 84, or 779.
Database Configuration Considerations
The following are tips to consider to consider when configuring databases:
Caché provides a seamless option to spread data across multiple physical database (CACHE.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 CACHE.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 Caché (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:
Enable the block sizes using the DBSizesAllowed setting on the Startup Settings page (System Administration > Additional Settings > Startup), described in Startup Settings in the Caché Additional Configuration Settings Reference.
Configure the database cache for the enabled block size on the the Startup Settings page (System Administration > Additional Settings > Startup), as described in Memory and Startup Settings.
Restart Caché.
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 a Caché database to an instance other than the one in which it was created by copying or moving its CACHE.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 Caché 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 Caché Character Width in the Caché Installation Guide) and the same locale (see Using the NLS Pages of the Management Portal in this chapter) as the source instance (the one in which the database was created).
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 (see “Platform Endianness” in the “Supported Technologies” chapter of the online InterSystems Supported Platforms document for this release), 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 CACHE.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 Caché 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 Caché 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 Caché High Availability Guide.
Directory — Location of the CACHE.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 Caché ” 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 Caché System Security Guide.
Encrypted — Specifies whether or not the database is encrypted; for more information, see the “Managed Key Encryption” chapter in the Caché System Security Guide.
Journal Specifies whether or not the database is journaled; for more information, see the “Journaling” chapter of the Caché 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).
Click Create New Database to open the Database Wizard.
Enter a database name in the text box. A database name must
not already be in use within the Caché 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
The first time you create a local database in a Caché instance using a particular browser, you must either
enter the name of the database directory, in which case this directory, containing the CACHE.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 CACHE.DAT file is created in that directory
Thereafter, by default a directory of the same name as the database name you provide, containing the CACHE.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.
Note:InterSystems does not support the use of symbolic links when configuring database directories.
Click Next to continue configuring the database. If a CACHE.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 CACHE.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.
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.
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.
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 Caché 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 CACHETEMP; for more information, see Using Temporary Globals and CACHETEMP in the “Journaling” chapter of the Caché Data Integrity Guide.
If encryption is activated, you can encrypt this database by selecting Yes for Encrypt Database?.
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 Caché High Availability Guide for information about creating mirrored databases.
From this panel onward, you can click Next. to continue configuring the database or Finish to accept the remaining defaults
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)
Click Next to view a list of the database attributes.
Click Finish to add your database.
You are now ready to configure and manage your new database.
To protect you from accidentally corrupting a database, you cannot open or write to an operating system file called CACHE.DAT or cache.ext, 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 Non-Mirrored Local Database Properties
Click the name of a non-mirrored 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 CACHE.DAT database file)
Encrypted (cannot be changed)
Mirrored — Click the Add to Mirror mirror_name link to add the database to the mirror in which the Caché 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 Caché 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.
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 Caché 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 Caché starts up; if the database cannot be mounted, Caché 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 Caché start without first mounting the database.
Note:By default, this setting is selected for required Caché databases (for example, CACHESYS, CACHELIB, CACHETEMP, and CACHE) and cannot be changed. The default is cleared for but can be selected for databases that you create, as well as some Caché databases (for example, USER and SAMPLES). 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 Caché” 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.
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 CACHE.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 Caché starts up or, if a mirror member, becomes primary; if the database cannot be mounted, Caché 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 Caché 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 Caché” 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 Caché High Availability 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 CACHE.DAT file, if and only if:
No other databases use this CACHE.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 CACHE.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 CACHE.DAT file, the database is still removed from the Databases section of the Caché 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:
Edit a remote database’s properties
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 an ECP remote data server. To configure a remote data server:
Navigate to the ECP Settings page (System Administration > Configuration > Connectivity > ECP Settings).
Click Add Remote Data Server and enter the following information for the ECP remote data server:
Server Name — Enter a logical local name for the remote data server for convenience of the application system administrator.
Host DNS Name or IP Address — Specify the host name either as a raw IP address (in dotted-decimal format or, if IPv6 is enabled, in colon-separated format) or as the Domain Name System (DNS) name of the remote host. If you use the DNS name, it resolves to an actual IP address each time the application server initiates a connection to that ECP data server host. For more information about IPv6 addressing, see the IPv6 Support section in this chapter.
IP Port — The port number defaults to 1972; change it as necessary to the superserver port of the Caché instance on the remote server.
Click Save.
In the list of remote servers, verify the status is Normal. If it is not, click Change Status and change the status to Normal.
To add a remote database, follow these steps:
Navigate to the Remote Databases page (System Administration > Configuration > System Configuration > Remote Databases) and click Add Remote Database to launch the wizard.
Select Select databases from a list to let the portal provide you with a drop-down list of remote data servers and then a drop-down list of database directories on the server you select. If a remote data server cannot currently be reached, its database directories are not available for selection.
Select Enter your own database specification to enter the remote data server name and database directory directly. (Note that the portal does not validate your entries.)
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.
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 Caché Temp directory (install-dir\Mgr\Temp).
Note:InterSystems recommends that you use the default location.
Click Save to configure the remote database.
You can click the Edit link for a remote database at any time to view and change the database described in the preceding procedure.
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 System Information
Caché stores system-wide configuration information in one or more configuration files in the installation directory with filenames ending in the .cpf extension. In most cases, the default configuration file created during installation, cache.cpf, is the only one you need to use Caché, but you can maintain different versions and specify a particular version when you start Caché. All but a few of the settings in the current configuration file can be modified using the Management Portal, but you can also modify the settings in a configuration file using a text editor. See the Caché Parameter File Reference for more information on the .cpf file.
There are some startup settings that you must change following installation, and others you should review. There are also a variety of advanced options available; however, these topics are not critical to running most Caché systems. These advanced options are described in various Caché topic-specific guides and reference books that you can access from the documentation home page.
Memory and Startup Settings
When you first install Caché, you may change some default system information. The Memory and Startup page (System Administration > Configuration > System Configuration > Memory and Startup) lets you allocate memory to routine and databases caches and change a few startup settings.
Allocating memory for these caches is one of two primary actions you must take in determining the way a Caché instance uses memory. The other important component of Caché memory configuration and allocation is the generic memory heap (also known as the shared memory heap), which determines the memory available to Caché for purposes other than the routine and database caches. For more information, see Managing Caché Memory in the “Preparing to Install Caché” chapter of the Caché Installation Guide, gmheap in the “Advanced Memory Settings” section of the Caché Additional Configuration Settings Reference, and Generic (Shared) Memory Heap Usage in the “Monitoring Caché Using the Management Portal” chapter of the Caché Monitoring Guide for more information about the gmheap setting.
For an in-depth look at Caché memory planning by an InterSystems senior technology architect, see InterSystems Data Platforms and Performance Part 4 - Looking at Memory on InterSystems Developer Community.
When Caché is first installed, routine and database cache memory allocation is set to Automatically, under which Caché 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.
Before deploying the system for production use or performing any tests or benchmarking intended to simulate production use, you must manually create an appropriate memory allocation for database cache (typically as much memory as possible after taking into account the needs of application and operating system processes) by selecting Manually and specifying allocations as follows. For guidelines for your initial allocation of memory to the routine and database caches, see Calculating Initial Memory Requirements in the “Preparing to Install Caché” chapter of the Caché Installation Guide
Memory Allocated for Routine Cache (MB) — Specifies the system memory allocated for caching server code. Caché assigns half the total space allocated for routines to a pool of 64 KB buffers, three-eighths of the space for a pool of 16 KB buffers, and one-eighth of the space for a pool of 4 KB buffers.
The maximum number of buffers allocated to any pool is limited to 65,529. Caché also never allocates fewer than 205 buffers to any sized pool. This means the actual memory used for routine buffers can be larger than specified in the configuration file. The format for Caché routines does not allow more than 32,768 characters for literal strings regardless of the setting for the maximum routine size.
See routines in the “[Config]” section of the Caché Parameter File Reference for information about allocating memory for routine buffers using the Caché parameter file (cache.cpf).
Memory Allocated for [blocksize] Database Cache (MB) — Specifies the system memory allocated for buffering data, that is, for creating global buffers. You must enter a separate allocation for each database block size enabled by the DBSizesAllowed setting on the Startup Settings page (System Administration > Additional Settings > Startup); see DBSizesAllowed in the Caché Additional Configuration Settings Reference for more information.For important information about selecting the appropriate block sizes for your applications, see Large Block Size Considerations.
The number of global buffers created by this allocation for each allowed database block size is determined by dividing the allocation by the database block size; the smaller the block size, the larger the number of global buffers for databases with that block size. (This is why the database cache and the memory allocated to it are sometimes referred to as the global buffer pool.)
Important:If you are configuring an ECP data server, see Memory Use on Large ECP Systems in the “Developing Distributed Applications” chapter of the Caché Distributed Data Management Guide for important information about adjustments to database cache sizes that may be necessary.
You can change the Maximum per Process Memory (KB) allocation (that is, the maximum memory allocation for a process) for this Caché 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, you should increase the size.
This amount of 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 maximum is reached. The initial allocation is 128 KB. Once this memory is allocated to the process, it is not deallocated until the process exits.
On Windows platforms, you can set your Caché instance to start automatically when the system starts by selecting the Auto-start on System Boot check box.
Note:The Auto-start on System Boot check box is selected by default. If you do not want the instance of Caché to start automatically on system boot, clear the check box.
If you select the Enable Long Strings check box, Caché allocates a large string stack to handle long strings for each process.
You can change the Superserver Port Number (TCP port used to accept incoming client requests) for this Caché instance. When you change it, a restart required message will be displayed, indicating that the change will not take effect until you restart this Caché instance.
You can select a predefined label to displayed in the title bar from the System Mode drop-down list.
Click Save to save your modifications; restart Caché to activate them.
Some changes on this page require a Caché restart and some do not. If you modify a field that requires a restart, no changes — even those that normally do not require a restart — to your configuration take effect until you restart Caché.
If you have made changes system-wide to the configuration settings that require a Caché restart, you receive the following:
Modification saved. You must restart system for the new values to take effect.
After you close the page, the warning message does not appear again to remind you that a restart is required.
IPv6 Support
You can enable or disable the use of IPv6 addresses in Caché by navigating to the Startup Settings page (System Administration > Additional Settings > Startup) page; in the IPv6 row, click Edit, then enter 1 to enable or 0 to disable.
This option is visible only if the network to which this Caché instance is connected permits IPv6 addressing.
When IPv6 is enabled, Caché accepts IPv6 addresses, IPv4 addresses, or DNS forms of addressing (host names, with or without domain qualifiers); when IPv6 is disabled, Caché 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.
If Caché is running in an IPv6 or mixed network, the license server must be configured on a host running Caché 2009.1 or later; license servers running in Caché 5.1 through Caché 2008.2 do not accept IPv6 connections. See the Configure License Servers section in the “Managing Caché Licensing” chapter of the Caché System Administration Guide.
Caché 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 a Caché 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 Caché 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 a Caché service earlier, Caché 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.
Caché does not support the use of wildcard characters or ranges in IPv6 addresses.
Configuring Task Manager Email Settings
On the Task Manager Email Settings page (System Administration > Configuration > Additional Settings > Task Manager Email), you can configure the settings the Task Manager uses for the email notifications described in the Using the Task Manager section of the “Managing Caché” chapter of this guide. For information about the settings, see “Task Manager Email Settings” in the Caché Additional Configuration Settings Reference.
Configuring National Language Support (NLS)
A national language locale defines the character set in which all textual data is encoded by Caché. The character set can be the 16-bit Unicode UCS-16 or one of a number of 8-bit character sets in common use worldwide, such as ISO 8859-1 (also known as Latin-1) or Windows Code Page 1252. A given national language may have several locales associated with it, at the least to provide both an 8–bit (ending in 8) and a Unicode (ending in w) version of the language; the appropriate locales are installed with Caché depending on whether it is an 8-bit or a Unicode instance. For example, Danish-language locales installed with 8-bit Caché include dai8 (Latin-9), dan8 (Latin-1), and daw8 (Windows-1252), while a Unicode instance has danw.
Each locale contains a number of character tables used by Caché when displaying text, collating data (see the “Collation” chapter of Using Caché 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 Caché 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 Caché change. While you can you import a locale of the wrong character width, you cannot install it as the current locale; for example, you can import dan8 into a Unicode instance, but cannot install it as the current locale.
Installing a new locale does not result in any data conversion, but rather changes how data is respresented. Because Unicode data can be accessed from any Unicode locale, changing one Unicode locale to another does not cause any data incompatibility. However, moving from one 8-bit locale to another may cause data incompatibility, depending on the character sets involved and the data stored in the system. For example, data encoded in ISO 8859-2 (Latin–2) will be interpreted differently by a locale based on CP1251 (Windows Cyrillic). The only guarantee is that the lower part of all 8-bit character sets (characters 0-127) is equal to the ASCII character set.
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 Caché, 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 Caché. When writing ObjectScript code or using some utilities, it is possible to specify a particular table for a given purpose; the default table is used 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 Caché System” chapter of Caché 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 Caché. 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.
Select the Import Type > Locale is the default.
Enter a file name and click OK. The only valid file extensions are .xml and .goq.
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 Caché System” chapter of Caché 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:
%SYS.NLS.Device — Properties of the current device.
%SYS.NLS.Format — Date, time, and number formats.
%SYS.NLS.Locale — Basic properties of current locale (read-only).
%SYS.NLS.Table — System and process tables (I/O and internal).
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.
Configuring Cluster Settings
These settings apply only to platforms that support clusters. Configuring them does not automatically force a system to join a cluster. A system joins a cluster automatically the first time it mounts a database for clustered access.
The connection is automatically configured and the cluster members do not need to be listed as clients of each other. The only requirement is that if the machine has multiple IP addresses (generally because there are multiple network interface cards) you must set the CommIPAddress to force Caché to use a specific IP address for the cluster ECP traffic.
The following settings appear in the Cluster Settings category on the Cluster Settings page (System Administration > Configuration > Connectivity > Cluster Settings):
JoinCluster — True or false. When true, this configuration is part of a cluster and the appropriate cluster definition settings can be configured; in addition, the directory must exist. The default is false.
CommIPAddress — This setting is required only for systems with multiple interfaces to specify the default IP Address for other cluster members to use for inter-cluster communication; it is advertised in the PIJ. The string, which may be up to 128 characters long (a cluster feature), is a resolvable DNS name or IP address.
pijdir — The pre-image journal (PIJ ) file to support cluster failover, recovery, and write image journaling in a cluster. This setting must be the same on each cluster node and is required when JoinCluster is set to true. The directory must exist.
If you edit this setting, you must restart Caché to apply the change.