Introduction to the Caché Parameter File
When Caché starts, it reads configuration values from the text file cache.cpf, the Caché parameter file, also called the CPF file. This file is a record of a particular Caché configuration. This chapter describes:
The syntax and purpose of each line of text in the CPF file.
How to choose values for parameters in the CPF file.
The system default for every parameter in a CPF file.
How to start Caché using a specific CPF file.
How to change the CPF file using the Management Portal, Config class APIs, or a text editor.Note:
Where mentioned, KB = 1024 bytes and MB = 1024 KB.
Filename and Location
A Caché parameter file name can be any valid file name with a .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.
|Windows||C:\install-dir\cache.cpf . By default C:\Intersystems\Cache\cache.cpf.|
|UNIX® and Linux||/bin/install-dir/cache.cpf|
You can keep as many parameter files as you like in the Caché installation directory. Each represents a different Caché configuration. You can start Caché with different configurations as needed for developing and testing new features, for troubleshooting problems, and for running a production system. For example, on Windows, if the Caché installation directory is C:\MyCache you might have the following CPF files:
C:\MyCache\cache_original.cpf C:\MyCache\production.cpf C:\MyCache\development.cpf C:\MyCache\testapps.cpf C:\MyCache\cache_customerbug.cpf
At shutdown, the system automatically saves the last known error-free configuration to a file called _LastGood_.cpf in the installation directory. You can use this file, if you need to, for recovery purposes.
Specifying a CPF File
Each installation of Caché is called an instance. Each instance has a name, which is the name you assigned to Caché when you installed it. The default instance name is CACHE.
You can start Caché using any CPF file contained in the installation directory. To start Caché with a CPF file other than cache.cpf, specify the name on the command line.
The following command starts Caché with a CPF file called mycache.cpf:
ccontrol start SPECIALCONFIG mycache.cpf
ccontrol start starts a Caché instance from the command line
SPECIALCONFIG is the Caché instance name
mycache.cpf is the parameter file (that is, the configuration) to use
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 the “Using Multiple Instances of Caché” chapter in the Caché System Administration Guide.
Editing the Active CPF File
When you edit and save configuration settings using the Management Portal, the settings are saved to the CPF file that was used when you started that Caché instance. Your changes in the portal overwrite existing values in the file.
You can also edit and save the CPF file using a text editor. We recommend that you save a backup copy of the CPF file before editing it.
If Caché startup detects that the Caché parameter file has been modified by a text editor 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:
Re-enter the username and password.
Start using the last known good configuration.
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 in theCaché Security Administration Guide.
Parameter File Format
A Caché parameter file is a line-oriented, UTF-8 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:
An empty line made up of zero or more spaces and tabs
The name of a file section enclosed in square brackets 
A Caché configuration parameter and its value(s)
You can add a comment by beginning a line with a semi-colon.
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:
All lines after the section name, up to the next section name (or the end of file), are in the current 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 a string:
When there is a set of similar items to configure, the keyword_# is the name of the item and the value is a string. Examples include namespaces, databases, devices, and anything else of which there is a group or set of similar items to configure, one per line. The syntax is usually:
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 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.
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:
Synopsis—The CPF file section in which this parameter is valid, followed by the name of the parameter and a synopsis of its syntax.
Description—A formal description of the parameter and its possible values.
Examples—Examples of the parameter line as it might be seen in various CPF files.
Range of Values—Minimum, maximum, and default values for the parameter.
Management Portal—How to change the value of this parameter using the browser-based Management Portal. If there is no portal equivalent, the section indicates this.
New or Obsolete Parameters
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.
Parameters are added or removed because:
New features require new configuration settings.
Obsolete features have had their settings removed.
List of Sections and Parameters
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, see the “Table of Contents” at the beginning of this book.