Caché System Administration Guide
Configuring Caché
[Back] [Next]
   
Server:docs2
Instance:LATEST
User:UnknownUser
 
-
Go to:
Search:    

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 Local 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é.
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:
Perform the following procedures for configuring namespaces from the [Home] > [Configuration] > [Namespaces] page of the Management Portal:
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, then do the following:
  1. 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.
  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.
Creating a Namespace in an Ensemble Instance
When you create a namespace within an Ensemble instance, the system automatically performs additional configuration tasks for the new namespace:
Modify Default Database Mapping
You can change the database to which your namespace is mapped without restarting Caché:
  1. Navigate to the [Home] > [Configuration] > [Namespaces] page to see a list of defined namespaces.
  2. Click Edit in the row of the namespace you wish to modify.
  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.
    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.
  4. Click Save.
Note:
Users directly accessing the database at the time of the change may need to log off and then log on to 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.
Note:
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.
Important:
If there is mapped content with the same identifier as local content (such as a package, class, global, or routine name), the mapped content will be visible, rather than the local content.
Global Mappings
You can add a mapping for a new global to your namespace at the global and global subscript level that overrides the default database mapping for globals of the namespace:
  1. Navigate to the [Home] > [Configuration] > [Namespaces] page, 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:
    (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.
  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.
    Note:
    >> displayed in the first column of the new mappings row indicates that you opened the mapping for editing.
  8. To save the mappings in the cpf file, click Save Changes.
Important:
While it is possible to add a mapping 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 [Home] > [Configuration] > [Namespaces] page, 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.
    Important:
    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.
    Note:
    >> 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 [Home] > [Configuration] > [Namespaces] page, and click Package Mappings in the row of the namespace where you want to map the package.
  2. From the [Home] > [Configuration] > [Namespaces] > [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.
    Note:
    >> displayed in the first column of the new mappings row indicates that you opened the mapping for editing.
  6. To save the mappings in the cpf file, click Save Changes.
See the Package Mapping section in the “Packages” chapter of 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.
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).
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 [Home] > [Configuration] > [Namespaces] page, 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.
Caché databases dynamically expand as needed, 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.
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. This maximum 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.
Note:
Because more information is stored for mirrored databases, the maximum number of configurable directories on a mirror member is lower and requires a more complex calculation. Each mirrored database counts twice against the absolute maximum of 15,998. 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.
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.
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
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. Enable the block sizes using the DBSizesAllowed setting on the [Home] > [Configuration] > [Startup Settings] page (see Startup Settings in the Caché Additional Configuration Settings Reference).
  2. Configure shared memory for the enabled block size on the [Home] > [Configuration] > [Memory and Startup] page (see Configuring System Information).
  3. Restart Caché.
  4. Create the database as described in Create Local Databases in this chapter.
Database Compatibility Considerations
As described in the Create a Local Database procedure, you can copy or move 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 [Home] > [Configuration] > [Local Databases] page of the Management Portal.
  1. Enter a database name in the text box. A database name must
    Important:
    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).
    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.
  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.
    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.
  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.
    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.
  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.
Note:
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.
Note:
Journaling is required for a mirrored database, therefore the Global Journal State setting does not appear.
The mirror automatically synchronizes fThe mirror automatically and continually synchronizes the following properties of a mirrored database on a backup or async with the properties of the database on the primary: Maximum Size, Expansion Size, Resource Name, and Collation. For example, if a database’s Maximum Size is increased on the primary, the property is automatically increased on the backup and asyncs to match the primary (if needed). There are some exceptions, however, as noted in the following:
For more information on automatic synchronization of database properties in a mirror, see Mirrored Database Considerations in the “Mirroring” chapter of the Caché System Administration Guide.
Delete a Local Database
To delete a local database, click the Delete link in the appropriate row. The Delete Database page displays information about the database you are deleting, and lets you:
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. Navigate to the [Home] > [Configuration] > [ECP Settings] page of the Management Portal.
  2. 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.
  3. Click Save.
  4. 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. Navigate to the [Home] > [Configuration] > [Remote Databases] page of the Management Portal and click Add Remote Database to launch the wizard.
  2. 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.
  3. 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.)
  4. Enter a database name (its name on the local server; it does not need to match its name on the remote server). You have defined a remote database.
    Database names are between 1 and 30 characters long, can start with an alphabetic character or an underscore. The remaining characters can be alphanumeric, a dash, or an underscore.
  5. You can optionally specify the directory in which streams associated with this database are stored. By default, the stream location for a remote database is the Caché Temp directory (install-dir\Mgr\Temp).
    Note:
    InterSystems recommends that you use the default location.
  6. Click Save to configure the remote database.
You can click the Edit link for a remote database at any time to 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 a configuration file. By default, the file is stored in the Caché root directory with the .cpf file extension. Caché initially starts with the provided configuration file called cache.cpf. In most cases, this configuration file is the only one you need to use Caché.
There are a few Memory and Startup Settings you may want to review on a new installation.
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. See the Caché Parameter File Reference for more information on the .cpf file.
Memory and Startup Settings
When you first install Caché, you may change some default system information. The [Home] > [Configuration] > [Memory and Startup] page of the Management Portal provides an interface to the database allocation features, as well as a few startup settings:
  1. When Caché is first installed, memory configuration is set to Automatically. Under this setting, Caché selects a conservative fraction of the available physical memory to allocate for database cache (global buffers), not to exceed 1GB. 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 should manually create an appropriate memory configuration 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.
    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.
  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.
    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.
  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é.
Important:
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.
Routine Buffer Pool Allocation
Caché allocates 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.
Important:
If you are configuring a large ECP system, allocate at least 50 MB of 8-KB buffers for ECP control structures in addition to the 8-KB buffers required to serve your 8-KB blocks over ECP. See the Memory Use on Large ECP Systems section of the “Developing Distributed Applications” chapter of the Caché Distributed Data Management Guide for details.
IPv6 Support
You can enable or disable the use of IPv6 addresses in Caché by on the [Home] > [Configuration] > [Startup Settings] page; in the IPv6 row, click Edit, then enter 1 to enable or 0 to disable.
Note:
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.
Important:
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
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.
Note:
Caché does not support the use of wildcard characters or ranges in IPv6 addresses.
Note:
Support for the use of LDAP over IPv6 is not available on OpenVMS.
Configuring Task Manager Email Settings
On the [Home] > [Configuration] > [Task Manager Email Settings] page of the Management Portal, 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.
Note:
You can also configure email settings programmatically through the %SYS.Task.Config class.
Configuring NLS Settings
Caché contains mechanisms for maintaining National Language Support (NLS) settings. The following sections describe the three ways to manage these settings:
Caution:
InterSystems provides the [Home] > [Configuration] > [National Language Settings] page of the Management Portal for you to browse existing locales and tables and for you to create custom locales. Do not edit the system locales and tables (those in the InterSystems product distribution kit), as the next product update will overwrite any changes you make.
For more information, see National Language Support Settings in the of Caché Additional Configuration Settings Reference.
Using the NLS Settings Page of the Management Portal
You can configure many NLS settings using the Management Portal.
From the [Home] > [Configuration] > [National Language Settings] page, you have the following menu options under the Locale Definitions column:
Locale Definitions
From the [Home] > [Configuration] > [National Language Settings] > [Locale Definitions] page, you can select a locale and perform several actions (the default of the locale field is always the current locale):
Note:
On Unicode systems, 8-bit locales are no longer permitted; only Unicode locales can be installed.
To view and edit details of a selected locale, click Properties. The next page displays the locale properties grouped into categories. For each category you can edit the fields and click Save, or click Return at the top of the page to cancel any of your edits and return to the Locale Properties page. The properties are grouped into the following tables:
Import Locale
From the [Home] > [Configuration] > [National Language Settings] > [Import Locale] page, you can import locales or tables:
  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 [Home] > [Configuration] > [Cluster Settings] page:
For more information, see Configuring a Caché Cluster in the “Caché Cluster Management” chapter of the Caché System Administration Guide.