Caché System Administration Guide
Configuring Caché
[Back] [Next]
Go to:

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 Tasks
Configure settings for this system from the System Configuration menu.
System Configuration Tasks
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
Connectivity Tasks
Configure network connections with other systems from the Connectivity menu.
Connectivity Tasks
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
Cluster Settings Configuring Cluster Settings section of this chapter.
Additional Tasks
Configure additional settings from the Additional Settings menu. For a summary of additional configuration settings, see the Caché Additional Configuration Settings Reference.
Additional Tasks
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 Caché 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:
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:
  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.
    Do not specify the following reserved system names: BIN, BROKER, DOCBOOK, 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 checkbox 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 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, Caché automatically performs additional configuration tasks for the new namespace, as follows:
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:
  1. On the Namespaces page, click Edit in the row of the namespace you wish to modify.
  2. Change or replace the existing name to rename the namespace.
    If you rename an Ensemble-enabled namespace without correspondingly renaming the required web application for the namespace, the namespace is no longer Ensemble-enabled (Ensemble does not work in the namespace).
  3. Choose the Default Database for Globals, the Default Database for Routines, and the Default Database for Temporary Storage from the list of defined databases.
    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.
  4. 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:
Sample Namespace Mapping
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:
  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 Global Mapping.
  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:
    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.
  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 Caché Parameter File Reference.
  7. Click OK.
    >> 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.
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:
  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 Routine Mapping.
  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. Select the Routine typeINC > INT > MAC > OBJ, or ALL for all types.
    Do not use a wildcard in the Routine name when selecting INC as the routine type, as such mappings are not indexed and therefore not visible in the Management Portal and Studio.
  6. Click OK.
    >> displayed in the first column of the new mappings row indicates that you opened the mapping for editing.
  7. 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:
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 Package Mapping.
  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.
    >> 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 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:
Mapping Data to All Namespaces
In addition to mapping globals, routines, and packages to specific namespaces, you can map them to all namespaces (except DOCBOOK and SAMPLES). To enable this form of mapping, you must first create a namespace named %ALL (see the Create/Modify a Namespace section of this guide). Then, use the procedures described in the Add Global, Routine, and Package Mapping to a Namespace section of this guide, choosing Global Mappings > Routine Mappings or Package Mappings in the %ALL namespace row.
%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).
To map data specifically to the DOCBOOK and SAMPLES namespaces, use the procedures in the Add Global, Routine, and Package Mapping to a Namespace section of this guide, choosing Global Mappings > Routine Mappings or Package Mappings in the DOCBOOK or SAMPLES namespace rows.
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 CSP 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 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:
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:
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:
To create a database that uses block sizes other than the supported blocks, do the following:
  1. Configure shared memory for the enabled block size on the the Startup Settings page (System Administration > Additional Settings > Startup), described in Configuring System Information.
  2. Restart Caché.
  3. 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:
Local Databases
The Local Databases page displays the following information about the databases on your system:
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. Enter a database name in the text box. A database name must
    Caché does not support logical names for database directories on OpenVMS systems.
  2. The first time you create a local database in a Caché instance using a particular browser, you must either
    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.
  3. 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
  4. In the Initial Size text box, type the number of megabytes for your database size (the default is 1 MB).
    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.
  5. 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.
    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.
  6. 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.
    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.
  7. If encryption is activated, you can encrypt this database by selecting Yes for Encrypt Database?.
  8. 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.
  9. From this panel onward, you can click Next. to continue configuring the database or Finish to accept the remaining defaults
  10. Choose the resource to control access to this database:
  11. Click Next to view a list of the database attributes.
  12. 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 Edit in the row 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.)
Edit Mirrored Local Database Properties
Click Edit in the row 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.
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:
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:
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:
  1. Click Add Remote Data Server and enter the following information for the ECP remote data server:
    1. Server Name — Enter a logical local name for the remote data server for convenience of the application system administrator.
    2. 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.
    3. IP Port — The port number defaults to 1972; change it as necessary to the superserver port of the Caché instance on the remote server.
  2. Click Save.
  3. 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:
  1. 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.
  2. 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.)
  3. 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.
  4. 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).
    InterSystems recommends that you use the default location.
  5. 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:
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. See 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.
  1. 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.
  2. 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.
    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.
  3. 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.
    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.
  4. If you select the Enable Long Strings check box, Caché allocates a large string stack to handle long strings for each process.
  5. 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.
  6. You can select a predefined label to displayed in the title bar from the System Mode drop-down list.
  7. 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, 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, 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”,, 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
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.
Support for the use of LDAP over IPv6 is not available on OpenVMS.
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.
You can also configure email settings programmatically through the %SYS.Task.Config class.
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 Data Collation Types in the “Caché SQL Basics” 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 a 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 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 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.
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 OK. 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 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:
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 (for example, OpenVMS). It 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):
For more information, see Configuring a Caché Cluster in the “Caché Cluster Management” chapter of the Caché System Administration Guide.