Caché Installation Guide
Installing Caché on Microsoft Windows
|
|
This chapter describes how to install Caché on a Microsoft Windows system. It assumes you are familiar with Windows directory structures, utilities, and commands. Before beginning this installation, be sure you have read all the information that applies to this platform in the chapter
Preparing to Install Caché.
This chapter contains the following major sections:
Caché Upgrade Installation
The steps for upgrading each type of a Caché installation are the same. The upgrade installation procedure installs the required components for the selected setup type on the computer.
To upgrade an installation follow this procedure:
-
Stop any running Caché server on the computer. Also, close all other Windows applications and shut down the web server if it is installed on the same computer. Ensure that you have access to the installation kit.
-
Execute the installation file, for instance by double-clicking it in Windows Explorer or executing it on the command line as follows:
C:\Users\Public\Downloads\cache-2016.2.0.626.0-win_x64.exe
-
The
Select Instance dialog box lists the existing installation directories of all Caché instances installed on the machine. Select the instance you want to upgrade. (You can always select
New Instance to install a new Caché instance, as described in
Installing Caché.)
-
-
Note:
When you upgrade a previously-installed instance of Caché, the installer retains all configuration settings unless you customize them.
-
Click
Update to continue to the next dialog box whether or not you have customized the installation.
-
The steps for installing each type of Caché configuration are fundamentally the same, but diverge slightly depending on the type of installation. The differences are detailed in subsections after the standard installation description.
The installation procedure installs the required components for the selected setup type on the computer. To perform an installation follow this procedure:
-
Ensure that the installation kit is available on your computer or on a network.
-
Execute the installation file, for instance by double-clicking it in Windows Explorer or executing it on the command line as follows:
C:\Users\Public\Downloads\cache-2016.2.0.626.0-win_x64.exe
Note:
By default, a newly installed Caché instance starts immediately after installation and the Caché launcher (cube) is placed in the system tray. To prevent Caché from starting, set the Windows Installer property
ISCSTARTCACHE to
0; to prevent the launcher from being placed in the system tray, set
ISCSTARTLAUNCHER to
0. You can do this using the
setup.exe from the multifile installation kit on the command line, for example:
C:\Users\Public\Downloads\setup.exe ISCSTARTCACHE=0 ISCSTARTLAUNCHER=0
-
The Caché setup begins. Within setup, the following buttons are activated to let you control the installation:
-
Click
Next to continue to the next dialog box.
-
Click
Back to go back to a previous dialog box and change what you have entered.
-
Click
Cancel to stop the installation.
-
If there are existing Caché instances installed on the system, the
Select Instance dialog box lists their installation directories. Select
New Instance to install a new Caché instance. (You can also select an existing instance to
upgrade that instance.)
-
-
The
Caché Instance Name dialog box lets you assign a name to the new instance you are installing. The default name is
CACHE (or if other instances, exist
CACHEn, where
n is the number of Caché instances including this new one). Accept the default or enter another name, using alphanumeric chacaters only. Subsequent updates to this instance maintain the instance name you enter here.
-
You can select or create a directory by clicking
Change. If the specified directory does not exist, setup lets you create it.
-
The
Setup Type dialog box lets you specify how you intend to use Caché:
-
Development Installs the Caché Database Engine (Samples Database, User Database, SQL Gateway, Server Monitoring Tools), Studio, all supported language bindings, and xDBC (ODBC and JDBC) drivers. Select this option if you plan to use this instance to perform both client and server tasks. See the
Installing Caché Development or Server Components Only section for details.
Note:
For Ensemble and HealthShare only, the
Development Setup Type also installs the EnsDemo Database.
-
Server Installs Caché Database Engine (Samples database, User database, SQL Gateway, Server monitoring tools) and CSP Gateway. Select this option if you plan to use this instance as a Caché database server which can be accessed by Caché clients. See the
Installing Caché Development or Server Components Only section for details.
Note:
For Ensemble and HealthShare only, the
Server Setup Type also installs the EnsDemo Database.
-
Client Installs Studio, and the xDBC (ODBC and JDBC) drivers. Select this option if you plan to use this instance as a client to a Caché database server on this or another computer. See the
Performing a Caché Client Installation section for details.
-
Web Server Installs CSP Gateway (IIS, Apache 2.0, Apache 2.2). Select this option if you want to install only those parts of Caché that are required on a CSP gateway machine. See the
Installing the Web Server (CSP) Gateway Only section for information about installing the CSP Gateway.
-
The following table identifies which component groups are installed for each setup type. The
Custom setup type lets you select specific component groups/components to install or remove; see the
Performing a Caché Custom Installation section of this book:
Components Installed by Setup Type
Component Group |
Components |
Development |
Server |
Client |
Web |
Caché Database Engine (Caché Server) |
Server Monitoring Tools Samples database User database SQL Gateway Agent Service (ISCAgent) Apache FOP (Formatting Objects Processor) |
X |
X |
|
|
Caché Launcher (cube) |
|
X |
X |
X |
|
Studio |
|
X |
|
X |
|
xDBC |
ODBC Driver Java Database Connectivity |
X |
|
X |
|
Caché Application Development |
ActiveX Connectivity C++ Binding for Caché Light C++ Binding Java Binding for Caché C++ SDK for Caché Caché Engine Link Libraries Python Binding for Caché 1.NET Binding for Caché Threaded Server Libraries Other Samples) |
X |
|
|
|
Documentation |
PDF Documentation Online Documentation |
X |
X |
|
|
Web Server Gateway (CSP) |
CSP for IIS CSP for Apache 2.0.x CSP for Apache 2.2.x |
|
X |
|
X |
1 This component is supported only on the x86-32 bit platform.
Installing Caché Development or Server Components Only
If you wish, you can install only the components of Caché that are required on a development system or on a server system.
To perform a Development or Server installation:
-
-
-
The
Initial Security Settings dialog box lets you decide how restrictive you want the initial Caché security settings to be. If you choose
Minimal, the installation continues with the next step.
Important:
If you select
Minimal for your initial security setting, but Caché requires network access to shared drives and printers, you must manually change the Windows user account under which to run the Caché service, choosing an existing account or creating a new account that has local administrator privileges on the server machine.
-
The
Enter Credentials for Caché Service dialog lets you choose the credentials under which the Windows Caché service will run. The default is the local default SYSTEM account. You can also specify a defined (existing) Windows user account and password; when you do so, the installer verifies these credentials before proceeding. The installer also creates a Caché account with the same username, with the %All role for unrestricted access to the instance (the password for this account is provided on the next panel).
Running the Windows Caché service under the default SYSTEM account is appropriate for many installations, but in some cases can cause issues relating to file permissions and network security access. If you anticipate potential problems in these areas for a Caché instance, for example due to your network configuration or security arrangements, specify an account for the Windows Caché service that has the needed privileges and/or access, for example that of a domain administrator.
To change the service account (in Windows 10): Navigate to
Control Panel >
Administrative Tools >
Services. Next, locate the correct Caché service. Then, right-click to open the properties dialog of the correct instance. Finally, change the credentials on the
Log On Tab and restart Caché.
-
-
The
Ready to Install dialog box lets you review the installation name, type, and directory, as well as the license key status.
Click
Install to continue. Setup installs Caché in the selected directory.
-
The system starts automatically after installation is complete. The
Caché Cube icon appears in the system tray area of the Windows tool bar. Click the cube to bring up the Caché menu. In addition, there is a
Caché item on the Windows
menu.
Installing Caché Client Components Only
If you wish, you can install only those parts of Caché that are required on a client machine.
To perform a client installation:
-
-
The
Ready to Install dialog box lets you review the installation name, type, and destination directory for the software files.
Click
Install to continue. Setup installs Caché in the selected directory.
-
After Caché is installed on a client, the
Caché Cube icon appears in the system tray area of the Windows tool bar; it appears dimmed because there is no Caché server running.
Installing the Web Server (CSP) Gateway Only
If you wish, you can install only those parts of Caché that are required on a CSP Gateway machine.
To perform a CSP Gateway installation:
-
-
The
Ready to Install dialog box lets you review the installation name, type, and destination directory for the software files.
Click
Install to continue. Setup installs Caché in the selected directory.
-
If a web server is running, a dialog box asks if you want to restart the web server. If you click
Yes, the installation procedure restarts the web server. If you click
No, the procedure does not restart the web server, in which case it does not start until you restart it manually or restart the system.
If the installer detects an Internet Information Services (IIS) web server installed on the system, it configures the web server for the CSP gateway. The installer also displays a checkbox for IIS; if you select this, CSP gateway IIS modules are installed in
C:\InetPub\CSPGateway.
The CSP Gateway configures the following application paths pointing to the server configured for the instance:
Performing a Custom Caché Installation
The Caché installation program allows you to select certain Caché components to install on the computer. For example, you may want to install only the Web Server (CSP) Gateway. Keep in mind that some selections require that you also install other components.
To perform a custom Caché installation:
-
-
Important:
If you are custom-installing the Caché Database Engine (Caché Server) component group or any of its components, ActiveX Connectivity (included in the Caché Application Development component group) is a prerequisite.
If you are custom-installing the Documentation component group or any of its components, the Caché Database Engine (Caché Server) component group is a prerequisite.
Note:
You can remove previously-installed components by selecting the
menu item for any component group or component.
-
Optionally, click
Space to ensure that there is enough space on the disk for the selected components.
-
Important:
If you are installing Ensemble, you must select
Unicode.
-
The following port numbers are valid for your Caché instance:
-
SuperServer Port Number
1972 or the first available subsequent number equal to or higher than
56773; you can change the superserver port value after installation from the
[Home] > [Configuration] > [Memory and Startup] page of the Management Portal.
-
WebServerPort number
57772 or the first available subsequent number; you can change the WebServerPort values after installation from the
[Home] > [Configuration] > [Startup Settings] page of the Management Portal.
-
The
Initial Security Settings dialog box lets you decide how restrictive you want the initial Caché security settings to be. If you choose
Minimal, the installation continues with the next step.
Important:
If you select
Minimal for your initial security setting, but Caché requires network access to shared drives and printers, you must manually change the Windows user account under which to run the Caché service, choosing an existing account or creating a new account that has local administrator privileges on the server machine.
-
The default SYSTEM account, which runs Caché as the Windows Local System account.
-
Defined Windows user account. The installation creates a Caché account with the %All role for the user who is installing Caché to grant that user access to services necessary to administer Caché. Enter and confirm the password for this account. The password must meet the criteria corresponding to the security setting.
Important:
If you are using Kerberos, you must enter a defined account that you have set up to run the Caché service. InterSystems recommends that you use a separate account specifically set up for this purpose.
When you click
Next, the installation verifies the following if you enter a defined user account:
-
The account exists on the domain.
-
You have supplied the correct password.
-
The account has local administrator privileges on the server machine.
Caution:
If you are installing on Windows Vista, before entering the account verify that it has local administrator privileges. Currently, the installation procedure cannot check this on the Vista platform.
-
The
Ready to Install dialog box lets you review the installation name, type, and destination directory for the software files.
You can also click the
License button to select a Caché license key. If the key is valid, the license is automatically activated and the license key is copied to the instance’s manager directory (
install-dir/mgr) as
cache.key during installation, and no further activation procedure is required. If you do not select a key, you can activate your InterSystems Caché license key following installation. See
Activating a License Key in the
Managing Caché Licensing chapter of the
Caché System Administration Guide for information about licenses, license keys and activation.
Click
Install to continue. Setup installs Caché in the selected directory.
-
Unattended Custom Installation
The Caché for Windows installer provides a way to perform
unattended custom installation, upgrade, reinstallation (repair), and removal (uninstall) of instances of Caché on your computer. A typical install operation obtains necessary input from the user in the form of responses to dialog boxes. An unattended operation, however, does not prompt the user for input; instead, it gets input from properties passed to the Caché installation file on the command line. These properties are described in the
Command-Line Reference section.
Important:
Before using the Caché unattended installation utility, you must unzip and install the Visual C++ Redistributable included in your installation kit. If you are installing on a 64-bit system, you must install both the
vcredist_x86.exe file and the
vcredist_x64.exe file.
This section discusses the following topics:
Note:
No messages are displayed during unattended installation, upgrade, reinstallation, or uninstallation.
Running an Unattended Installation
To launch unattended installation of a new instance of Caché, use the following command:
<path>\<installer>.exe /instance <instancename> /q{b|n} <properties>
-
<path> is the path to the Caché installation file.
-
-
/qb displays a progress bar during unattended installation, while
/qn specifies a completely silent installation (one or the other must be included).
-
<instancename> is the name of the installed Caché instance. (A new instance is installed with the default instance name
Cache if the
/instance parameter is omitted, however the
/instance parameter must be used when there are one or more instances already installed.)
-
For example, to install an instance of Caché with the default instance name in an installation directory named
C:\InterSystems\MyCache on a 64bit Windows system, specify the following:
C:\downloads\cache-2015.1.0.320.0-win_x64.exe /qn INSTALLDIR=C:\InterSystems\MyCache
To install an instance of Caché with the instance name
CacheA, specify the following:
C:\downloads\cache-2015.1.0.320.0-win_x64.exe /instance CacheA /qn
Alternatively, you can custom install a subset of features using the
ADDLOCAL property; see the
Command-Line Properties table, as well as the
Custom-Installable Features table for a list of features that can be specified. For example, to install only the Launcher and the PDF version of documentation in an installation that uses the default instance name and default installation directory on a 64bit Windows system, specify the following:
C:\downloads\cache-2015.1.0.320.0-win_x64.exe /qn ADDLOCAL=cube,documentation,documentation_pdf
Note:
An unattended installation does not install the CSP Gateway by default; this must be specified using the
ADDLOCAL property (see the
Command-Line Properties table).
Running an Unattended Upgrade or Reinstall
The target of the Caché installer can be an existing installed instance as well as a new instance. When there are no installed Caché instances, the target is always a new instance. When one or more instances of Caché are already installed, you must use the
/instance flag to specify either the name of one of the existing instances or a new name, which installs a new instance.
When an installed instance is the installer target, the action the installer takes depends on the versions of the installation file specified in the command line and the target instance, as follows:
-
If the installation file is the same version as the target installed instance, the installer reinstalls (repairs) the instance.
-
If the installation file is a later version than the target installed instance, the installer upgrades the instance to the new version.
For example, to run an unattended upgrade of an installed instance
CacheB that is an earlier version than the installation file, use the following:
C:\downloads\cache-2015.1.0.320.0-win_x64.exe /instance CacheB /qn
You can reinstall one or more specific features, as listed in the
Custom-Installable Features table, by specifying the target instance and using the
REINSTALL property (see the
Command-Line Properties table). For example, to reinstall Studio for the installed instance
CacheB, you can use the following command (assuming the installation file and
CacheB are the same version):
C:\downloads\cache-2015.1.0.320.0-win_x64.exe /instance CacheB /qn REINSTALL=studio
Running an Unattended Uninstallation
To launch an unattended uninstall, specify the instance to be uninstalled and the
REMOVE=ALL property, as follows:
C:\downloads\cache-2015.1.0.320.0-win_x64.exe /instance CacheC /qn REMOVE=ALL
You can also use the
REMOVE property to remove specific features, as described in the
Custom-Installable Features table. For example, to remove the Apache 2.0 CSP Gateway from instance
CacheC, use the following command:
C:\downloads\cache-2015.1.0.320.0-win_x64.exe /instance CacheC REMOVE=cspgateway,cspapache20
If you do not have access to the original installation package, you can run uninstall in unattended mode by using the
Windows® Installer command-line application (
msiexec) and information in the Registry, as follows:
msiexec /x {<product_guid>} /qn /l <logfile>
You can obtain the
ProductCode property value from the Registry:
where
<instance> is the name of the Caché instance you want to uninstall in unattended mode. The
ProductCode property value is displayed in a row similar to the following:
ProductCode REG_SZ {80E3F658-2D74-4A81-92AD-FD16CD226154}
The
Command-Line Properties table describes the Caché-specific unattended install properties that you can modify via the command-line interface. The property name must be uppercase, but the arguments are not case sensitive; each property must be separated by one or more spaces, and properties can be specified in any order as
PROPERTYNAME=argument. For example:
... ISCSTARTCACHE=0 UNICODE=0 WEBSERVERPORT=57779 INITIALSECURITY=Normal
Command-Line Properties
Property Name |
Description |
ADDLOCAL |
Use this property to custom install a new instance of Caché with a subset of features or to omit optional databases (see the Custom-installable Features table) by specifying a comma-separated list of featurenames together with their group names, as described in the example following this table. See also the REINSTALL property, for use with installed instances. |
CACHESERVICEDOMAIN |
Required if the service credentials are defined as UserDefined; see the SERVICECREDENTIALS property in this table. Use this property to specify the domain of the Windows Caché service login account specified by CACHESERVICEUSER. If the service credentials are specified as LocalSystem, do not use this property. |
CACHESERVICEPASSWORD |
Required if the service credentials are defined as UserDefined; see the SERVICECREDENTIALS property in this table. Use this property to specify the password for the Windows Caché service account specified by CACHESERVICEUSER. If the service credentials are specified as LocalSystem, do not use this property. |
CACHESERVICEUSER |
Required if the service credentials are defined as UserDefined; see the SERVICECREDENTIALS property in this table. Use this property to specify the username of the account under which to run the Windows Caché service. If the service credentials are specified as LocalSystem, do not use this property. |
CACHEUSERPASSWORD |
If the initial security level is None, do not use this property. |
CSPSYSTEMUSERPASSWORD |
If the security level is Normalor Locked Down (see the INITIALSECURITY property in this table), optionally use this property to specify a password for the CSPSystem predefined user. If this property is omitted, the value of CACHEUSERPASSWORD is used. If the initial security level is None, do not use this property. |
INITIALSECURITY |
Optionally use this property to specify the level of security to be used by the instance being installed. Specify None, Normal, or Locked Down. Omit this property to accept the default of None. |
INSTALLDIR |
Optionally use this property to specify the directory in which the instance is to be installed. |
INSTALLERMANIFEST |
|
INSTALLERMANIFESTLOGLEVEL |
|
INSTALLERMANIFESTPARAMS |
If installing with an installation manifest, as described in Using the Manifest in the chapter Creating and Using an Installation Manifest, use this property to specify the name/value pairs ( name=value) to be passed to the first argument of the setup() method of your installation manifest clas. This property can be used to modify the Caché parameter file ( cache.cpf) and activate the changes before your manifest runs. The following parameters can be specified: For example: INSTALLERMANIFESTPARAMS="bbsiz=512000,globals4kb=20,
globals8kb=30,globals16kb=40,globals32kb=50,
globals64kb=100,routines=40,gmheap=10000,
LibPath=c:\libpath\,locksiz=2179648,MaxServerConn=5,
Path=c:\lib\,ZFSize=2000,ZFString=3000" The following would be useful in installing and activating 100 MB of 64KB buffers before running a manifest that creates a 64kb block size database: INSTALLERMANIFESTPARAMS="globals64kb=100" |
ISCSTARTCACHE |
Optionally set this property to 0 to prevent Caché from starting after installation. The default is 1, to start Caché. |
ISCSTARTLAUNCHER |
Optionally set this property to 0 to prevent the Caché launcher (cube) from being added to the system tray. The default is 1, to add the launcher. |
REINSTALL |
Use this property to reinstall (repair) an installed instance of Caché or to change the custom-installed features (see the Custom-installable Features table) for an installed instance of Caché: To reinstall whatever features are currently installed for the instancewhether that is a custom-installed subset of features or all featuresspecify ALL. To reinstall a subset of Caché features that is different from the subset of features currently installed, specify a comma-separated list of featurenames together with their group names (as described in the example following this table).
See also the ADDLOCAL property (for use with new instances) and REMOVE property (for uninstalling installed instances). |
REMOVE |
Use this property to uninstall (remove) an instance of Caché or a subset of custom-installed features (see the Custom-installable Features table) installed for an installed instance of Caché: To remove an instance of Caché, specify ALL. To remove a subset of Caché features (see the Custom-installable Features table), specify a comma-separated list of featurename together with their group names (as described in the example following this table).
See also the ADDLOCAL (for new instances) and REMOVE properties in this table properties in this table. |
SERVICECREDENTIALS |
If the security level is Normalor Locked Down (see the INITIALSECURITY property in this table), optionally use this property to specify the credentials under which the Windows Caché service will run: LocalSystem for the default local system account or UserDefined (an existing Windows user account). If you do not specify the property, the default of LocalSystem is used. If the initial security level is None, do not use this property. |
SUPERSERVERPORT |
Optionally use this property to specify the Superserver port to be used by the instance being installed. By default, this port is auto-determined, beginning with 1972 (if available), then 56773, and increasing by 1 for each installed instance of Caché. |
UNICODE |
Optionally use this property to specify whether 8bit or 16bit Unicode characters are to be supported by the instance being installed. For 8bit characters, specify 0; for 16bit characters, specify 1. This setting applies to Caché instances only; Ensemble instances are always Unicode. If you omit this property, is 8bit specified by default for all languages except Chinese, Korean and Japanese; 16bit is specified by default for Chinese, Korean, and Japanese systems. |
WEBSERVERPORT |
Optionally use this property to specify the Webserver port to be used by the instance being installed. By default, this port is auto-determined, beginning with 57772 and increasing by 1 for each installed instance of Caché. |
The
Custom-Installable Features table lists component group/component names and the associated
featurename for each. You can specify
ALL (to specify all available features) or a comma-separated list (with no spaces) of feature names (to specify individual features).
To specify components in
ADDLOCAL,
REINSTALL, and
REMOVE properties (see the
Command-Line Properties table), specify the
featurename of a component group, followed by the
featurename of each specific component from that group that you want installed. For example, to install only the SAMPLES and USER databases and the PDF documentation, include the following in the command line:
ADDLOCAL=server,server_samples,server_user,documentation,documentation_pdf
When specifying a component group, you must also specify at least one associated component; if no components are listed with a component group, the component group is ignored and no components are installed. For example, if you specify the following:
ADDLOCAL=documentation,documentation_pdf,server,development,perlbind,pythonbind
the
server component group is ignored and no server components are installed. (This requirement does not apply to the
studio and
cube groups as they have no components.)
Custom-Installable Features
Component Group (featurename) |
Components (featurename) |
|
Apache Formatting Objects Processor ( fop) HotJVM RenderServer/QueuingRenderServer for Zen Reports ( renderserver) |
|
|
|
|
|
|
|
|
|
|
|
|
Review the following important post-installation tasks:
-
-
Caché installation on Windows names the Windows Caché service with the instance name, using the name from the
Define Caché Instance Name dialog box, and configures the service to start automatically when you start your server; this means the Caché instance is automatically configured to autostart (start when the system starts).
-
-
-
-
If appropriate for your installation, perform any additional tasks described in the
Special Considerations section.
The following topics describe particular issues or tasks associated with licensing, specific platforms, or kinds of installations:
Managing Access to the Caché Instance and Installation Tree
When Caché is installed with Normal or Locked-Down security, the account under which the Windows Caché service runs must have both of the following:
-
The privileges needed to start, stop, and control the Caché instance.
This is automatic when the service runs under the default local system account or when the service account specified during installation is a member of the Windows Administrators group, but not for other specified service accounts.
-
Full access to the installation treethe directory in which Caché is installed and all of its subdirectories.
This is automatic for all accounts by default because, as installed, all authenticated Windows users have access to the installation tree. For security reasons, however, you may want to restrict access to the installation tree, as described in the following.
When you specify a service account that is not a member of Administrators, to address these needs, the installer creates the following two user groups and adds the service account to each:
-
The CacheServices group, which grants the required instance control privileges.
-
Please note the following points about these groups:
-
To restrict access to the Caché installation tree to members of the Administrators and Cache_Instance_
instancename groups (including the service account), remove the Windows access control entry (ACE) granting access to all authenticated users with the following command:
icacls <install-dir> /remove "NT AUTHORITY\Authenticated Users"
Important:
If you do not restrict access to the installation tree, any user who can log into the system hosting the Caché instance can easily modify its files and settings or disable it entirely.
-
To ensure Caché the needed access to all instance database, journal and log files that are outside the Caché installation tree, grant the Cache_Instance_
instancename group full access to these files and the directories containing them.
-
In some cases you may want a Windows account that is not in Administrators and is not the service account to have access to the installation tree and other instance files. This could, for example, include service accounts running automated tasks and accounts that will log into the Windows server directly and then access Caché through a local Terminal session, or by invoking a custom callin executable. You can give any such account the needed access by adding it to the Cache_Instance_
instancename group.
Important:
If you want to change the Windows Caché service account to one that is not in Administrators, do not use the Windows Control Panel for this purpose. Instead use the following command, which adds the specified account to the CacheServices and the Cache_Instance_
instancename groups:
<install-dir>\bin\Cinstall.exe setserviceusername <instance-name> <username> <password>
Using an Installation Manifest
Multiple Caché Installation Issues
You can install and simultaneously run multiple instances (Caché 4.0 and later) on a single Windows machine. Install Caché as for a single installation, giving each instance a unique name, a unique installation directory, and a unique port number.
Installing multiple Caché instances is limited by components where only one exists on a system. For example, typically there is only one web server on a system; and as such, the Caché installation configures CSP for the most recent installation. Caché client components stored in the registry encounter the same issue. Caché stores its ODBC driver and ActiveX components in the registry using one name for each. Currently, the last installation updates these components to point to the last instance installed. If you are adding this release of Caché to your machine and keeping older (Caché 4.1 and earlier) versions running, you need to register the latest components. See
Registering Files for details.
InterSystems makes an effort to move common components to a common directory that can be shared across Caché instances. Unfortunately, because of backward compatibility issues, not all current Caché components support Caché 5.0 and 4.1 instances and are even less likely to support Caché 4.0 instances on the same machine.
As a work-around, you can take advantage of a feature Microsoft introduced with Windows 2000 and later. You can force your executable to ignore the registry paths to an executable by creating an empty file of the same name with
.local appended to the executable name.
For example:
CStudio.exe would need an empty file called
CStudio.exe.local to force the Studio program to look in the current directory, before using the registry path. By creating these empty
.local files, you enable a previous Caché instance to use the compatible local files, rather than a newly installed current Caché set of registered executables.
To create
.local files for all the executables in a directory type the following at a DOS prompt:
for %c in (*.exe) do set tempvariable= >%c.local
The Caché installation contains a
Regfiles.bat script file in the
install-dir/Bin directory that reregisters object tool files in a common Caché directory. You require Administrator privileges to run
RegFiles.bat.
You need to run this script only if you install or uninstall any instance of Caché 4.1 or earlier; if you are running only instances of Caché 5.0 or later, the object tools function properly with multiple instances.
Here is an example of running the script:
C:\MyCache\Bin>regfiles.bat
C:\MyCache\Bin>rem Register Cache Self-Registering executables in
common directory
.
.
If after running
RegFiles.bat, you still receive errors similar to the following when you start Studio:
Cannot create class factory for COM_SLSID_TNodes
Run the script with the
ALL argument; this reregisters all
JCOM DLLs in addition to the other files.
C:\MyCache\Bin>RegFiles.bat ALL
C:\MyCache\Bin>rem Register Cache Self-Registering executables in
common directory
.
.
C:\MyCache\Bin>rem Register JCOM dlls
C:\MyCache\Bin>set CacheDir=C:\MyCache\bin\
.
.
Changing the Caché Language
When you install Caché, all supported language-specific utility DLLs are installed in the
install-dir\Bin directory. Each DLL contains localized strings and messages.
The format of the name of the DLL is
UTILaaa.DLL, where
aaa is a 3-letter code that signifies the following languages:
Note:
You can change only among 8-bit locales or Unicode locales, not from 8-bit to Unicode or vice versa. See the
%SYS.NLS entry in the
InterSystems Class Reference for more information.
Reinstalling or Uninstalling Caché
By running setup and selecting a Caché instance of the same version as the installer, or by selecting
Programs and Features from Windows Control Panel and selecting a Caché instance, you can make changes to or uninstall the instance.
-
-
Select
Repair to repair problems with the instance such as missing or corrupt files or registry entries.
-
Select
Remove to uninstall the instance.
Important:
Use only the Caché installer or Windows Control Panel
Programs and Features to uninstall Caché. Other uninstall programs are not supported and using them may cause unexpected results.
InterSystems Caché Packet Drivers
Install Caché Packet Driver for Windows 2000, XP, and 2003 Server
To use Raw Ethernet with Caché on Windows systems, you must install the appropriate packet driver as described below. First ensure that the appropriate driver file is available on your computer or on a network.
For Windows 2000, XP, and 2003 Server systems, install the InterSystems Packet Protocol Driver as follows:
-
Right-click
My Network Places on the desktop and click
.
You can also click
Start, point to
and click
.
-
Right-click
Local Area Connection and click
.
-
-
-
-
Enter the path to the packet driver kit and click
OK.
-
-
After the driver is installed, click
Close.
After you restart Windows, Caché is fully available to you.
Shared Memory Allocation on Windows
InterSystems recommends enabling Caché to allocate its memory as large pages on Windows systems, which provides more efficient use of memory and paging space. To do so, grant the Windows
Lock Pages in Memory (SELockMemory) privilege to the user account used to run Caché, which allows Caché to request its memory as large pages. For finer grain control over the memlock parameters, see
memlock in the
Caché Parameter File Reference.
When you restart Caché while using large pages, you typically also need to restart Windows, to guarantee that all configured memory is allocated. If startup is unable to allocate the full amount of configured memory, it attempts to start up with less memory, and may or may not use large pages. You can check the actual memory allocated by reviewing the most recent Caché/Ensemble startup in the console log.
Specifically, Caché allocates shared memory at Windows startup as follows:
-
Request large pages, if allowed.
-
If unable to allocate the full amount of configured memory in large pages, or if large pages are not allowed, request small pages.
-
If unable to allocate the full amount of configured memory in small pages, reduce the allocation by one eighth (1/8) and begin again with step 1.
Note:
On Windows versions prior to Windows Server 2008 and Windows Vista, which are not supported by this version Caché, allocation of small pages bigger than 2 GB is not allowed. The Caché memory allocation algorithm was therefore different, as follows:
-
If large pages are allowed,
-
-
If unable to allocate the full amount of configured memory in large pages, allocate small pages if amount of configured memory is smaller than 2 GB.
-
If configured memory is larger than 2 GB, or if unable to allocate the full amount of configured memory in small pages, reduce the allocation by one eighth (1/8) and begin again with step 1a.
-
If large pages are not allowed,
-
Reduce memory request size to 2 GB.
-
-
If unable to allocate the full amount of configured memory in small pages, reduce the allocation by one eighth (1/8) and begin again with step 2b.
If the total amount of shared memory configured for Caché exceeds 2 GB on one of these Windows versions and is not allocated as Windows large pages, Caché or Ensemble can become slow or unresponsive. In these circumstances, key Caché/Ensemble processes, such as the Write daemon, spend more and more time in the Windows kernel, visible as percentage of Privileged time in Windows Performance Monitor,
perfmon.exe.