A Caché parameter file can use any valid filename plus the .cpf extension. A default parameter file called cache.cpf is provided with every new installation of Caché.

A Caché parameter file must reside in the  Caché installation directory . This is the directory into which you installed Caché. The exact pathname varies by platform and by choice of directory name during Caché installation. The following table provides some examples.

You can keep as many parameter files as you like in the Caché installation directory. Each represents a different  Caché configuration . You can invoke different configurations as needed for developing and testing new features, for troubleshooting problems, and for running the normal system day by day. Thus, on Windows, if the Caché installation directory is C:\CacheSys you might have:

C:\CacheSys\cache_original.cpf
C:\CacheSys\production.cpf
C:\CacheSys\development.cpf
C:\CacheSys\testapps.cpf
C:\CacheSys\cache_customerbug.cpf

At shutdown, Caché automatically saves the last known error-free configuration to a file called _LastGood_.cpf in the installation directory. This file is available should you need it for recovery purposes.

An installed Caché engine is called a  Caché instance . The instance has a name, which is the name you assigned to Caché when you installed it. Usually this name is:

CACHE

You can start a Caché instance using any configuration that you have recorded in a parameter file. Only one configuration can be active for the currently-running Caché instance. You specify this configuration on the command line, when you start Caché, by providing the name of the corresponding .cpf file. This must be a valid .cpf file that resides in the Caché installation directory. If no parameter file is specified on the command line, the Caché instance uses the same parameter file that was used last time it was started up. If none of these conventions identifies a parameter file, Caché uses the default parameter file. Its name is:

cache.cpf

The following command starts a Caché instance with a specific parameter file:

ccontrol start SPECIALCONFIG mycache.cpf 

Where:

To use a different configuration for the Caché instance, you must stop Caché and start it again with a different parameter file.

For further details about the Caché command line, including many additional ccontrol command line options, see “Using Multiple Instances of Caché” in the Caché System Administration Guide.

When you edit configuration settings using the Caché System Management Portal, by clicking the Save button you automatically export the current configuration to the parameter file that was active when you started that Caché instance. Your changes in the portal automatically overwrite any previous values in that parameter file.

In addition to automatic export, you can export the current configuration to a parameter file that is not currently active, by calling the CPFExport method from ObjectScript code or the Terminal command line, as follows:

do ##class(Config.Configuration).CPFExport(cfgname,file)

Where cfgname and file are parameter file names. If you omit the second argument, the configuration is exported to cfgname. Otherwise the configuration is exported to file.

It is also possible for you to edit and save parameter files using a text editor. InterSystems recommends that you do not pursue this option, as it can introduce errors more readily than exporting from a running Caché instance.

InterSystems recommends that if you do edit a Caché parameter file, make sure it is not the active configuration for a currently-running Caché instance. If it is, then InterSystems recommends that you shut down the Caché instance and save a backup copy of the Caché parameter file before editing it.

If Caché startup detects that the Caché parameter file has been modified outside the control of the System Management Portal since the last time Caché was started, and if Configuration Security is enabled, Caché startup requests a username and password to validate the changes. The username supplied must have %Admin_Manage:Use privileges. If the appropriate username and password cannot be provided, Caché allows the operator to choose as follows:

If the operator chooses option 2, Caché renames the parameter file that was invoked at startup (file.cpf) with the suffix _rejected (file.cpf_rejected). Caché then overwrites the file.cpf with the last known good configuration (_LastGood_.cpf) and starts up using this configuration.

For more information on other systemwide security parameters, see the “System Management and Security” chapter of the Using Caché Advanced Security book.

A Caché parameter file is a line-oriented, case-sensitive, ASCII text file. Each line ends with a carriage return and line feed. Long items cannot be continued on a following line. A line in the file may be any of the following:

There is no syntax for including comments in a Caché parameter file.

In general, spaces at the beginning and end of lines are without effect. Spaces within the line are usually considered significant. The best practice is to use no spaces in the line except where they are meaningful components of strings.

Related settings are collected into sections. The beginning of a section is marked by a line consisting of the name of the section enclosed in square brackets. For example:

[Devices]

All lines after the section name, up to the next section name (or the end of file), are considered as belonging to that section.

Each line that is not a section name is the definition of a parameter. Each parameter line uses the following syntax, where keyword is a parameter name and value is any string:

keyword=value

When there is a group or set of similar items to configure, the keyword string is repeated with a sequential number. Examples include output devices, COM ports, Ethernet connections, SQL data types, and anything else of which there is a group or set of similar items to configure, one per line. The syntax is generally along the lines of:

keyword_1=value
keyword_2=value
keyword_3=value
.
.
.

The syntax for the value string varies widely from parameter to parameter. The string may indicate true or false using a word, YES or NO, or a number, 1 or 0. It may be a number of bytes, or a number of megabytes. It may be a single value, or it may contain multiple values separated by a delimiter character on the same line. If there is a delimiter within the string, it may be a comma, semicolon, tilde (~), slash (/), colon, or some combination of these, depending on the parameter. Many other possibilities exist.

Whatever the required syntax in each individual case, this document describes it. The organization of this document follows the order in which sections and parameters typically appear in the file.

Each parameter description in this book includes the following information:

With each Caché release, a small number of parameters are removed or added to the .cpf file. This document only describes parameters for the current release. If you are an experienced Caché user, you might not recognize every parameter in this document and you might be familiar with .cpf file parameters that are now removed.

The general reasons for changes in .cpf file parameters are as follows:

To see a list of all parameters and sections in the Caché parameter file, in the order in which they usually appear in the file, return to the Table of Contents at the beginning of this book.