|
Caché System Administration Guide
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 Tasks
System Configuration Tasks
Connectivity Tasks
Configure network connections with other systems from the
Connectivity menu.
Connectivity Tasks
Additional Tasks
Additional Tasks
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:
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:
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.
-
-
SAMPLES — Sample code and applications.
-
USER — Empty at installation. Typically used for application development.
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.
-
-
-
-
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:
-
On the
Namespaces page, click
Edit in the row of the namespace you wish to modify.
-
Change or replace the existing name to rename the namespace.
Important:
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).
-
-
Note:
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.
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.
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:
-
-
-
-
Enter the
Global name. You can use the
* character as part of the global name to specify multiple globals, for example
ABC*.
-
(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.
-
Click
Advanced to display the following:
-
Select the
Collation. Collation applies only to new subscript-level mapping globals.
-
-
Note:
>> displayed in the first column of the new mappings row indicates that you opened the mapping for editing.
-
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.
You can add mappings to your namespace at the routine level that overrides the default database mapping for routines of the namespace:
-
-
-
-
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).
-
Note:
>> displayed in the first column of the new mappings row indicates that you opened the mapping for editing.
-
Important:
When you map one or more routines, be sure to identify all the code and data needed by those routines, and ensure that all that code and data is available in all the target namespaces. The mapped routines could depend on the following items:
Use additional routine, package, and global mappings as needed to ensure that these items are available in the target namespaces.
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:
-
-
-
-
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:
-
-
-
Note:
>> displayed in the first column of the new mappings row indicates that you opened the mapping for editing.
-
Important:
When you map a package, be sure to identify all the code and data needed by the classes in that package, and ensure that all that code and data is available in all the target namespaces. The mapped classes could depend on the following items:
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
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).
You can delete a namespace, including all mappings associated with it:
-
-
On the
Delete Namespaces page, if you want to delete the CSP pages from the physical path, select the check box.
-
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.
Caution:
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:
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:
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:
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:
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:
-
-
-
-
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 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.
The
Local Databases page displays the following information about the databases on your system:
-
-
-
-
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.
-
-
-
You can use this page to:
-
-
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
-
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.
-
-
-
-
-
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:
-
-
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.
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
-
-
-
-
-
-
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.
-
-
-
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é will not start. 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 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.
-
Note:
This prompt displays only if this is a clustered system.
-
Note:
InterSystems recommends that you use the default location.
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.
-
-
Mirror Name — Name by which the database is identified within the mirror; cannot be changed,
-
-
-
Note:
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.
-
-
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; if the database cannot be mounted, Caché will not start. Clear to let Caché start without first mounting the database.
-
-
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.
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 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.
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.
-
-
Edit a remote database’s properties
-
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:
-
-
-
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.
-
-
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:
-
-
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.
-
-
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.
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
-
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.
-
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.
-
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.)
-
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é.
Important:
If you have made changes system-wide to the configuration settings that require a Caché restart, you receive the following:
After you close the page, the warning message does not appear again to remind you that a restart is required.
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.
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:
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
-
-
-
::FFFF:127.0.0.1 (IPv4 mapped IPv6 format)
-
0:0:0:0:0:0:0:1 (full 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.
Note:
Caché does not support the use of wildcard characters or ranges in IPv6 addresses.
Configuring Task Manager Email Settings
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 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 configuration defaults are a property of the instance, not of the locale. Therefore, when the instance is upgraded, the default selections are preserved.
-
-
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:
-
-
-
-
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.
-
-
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.
-
-
-
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.
-
-
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
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.
-
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.
