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.
When upgrading Caché on a Windows system, the USER namespace and database will not be created if the original USER database was deleted in the original instance.
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é.)
-
The Welcome to the Caché Installation dialog box displays the following buttons to let you control the upgrade:
-
Optionally, click Customize to add or remove components during the installation upgrade. For more information, see Caché Custom Installation.
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 InstallShield Wizard Complete dialog box indicates the installation has completed successfully. Click Finish.
Caché 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.
Installing Caché
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
For a description of all Caché Windows installer properties, see Unattended Custom 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.)
-
If you are installing a new instance of Caché on this computer, setup displays the License Agreement dialog box. Click I accept the terms in the license agreement to confirm that you accept the license agreement.
-
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 characters only. Subsequent updates to this instance maintain the instance name you enter here.
-
The Destination Folder dialog box lets you select a destination directory for the Caché software for the new instance; the default location is C:\InterSystems\Cache (or Cachen when multiple instances exist).
You can select or create a directory by clicking Change. If the specified directory does not exist, setup lets you create it.
Important:Be sure to see Installation Directory in the “Preparing to Install” chapter for important information about choosing an installation directory.
-
The Setup Type dialog box lets you specify how you intend to use Caché. Review the Setup Type section in Preparing to Install Caché to decide which components of Caché you need.
The next steps of the installation procedure differ based on the Setup Type you choose. To finish installing Caché, follow the steps in the section that corresponds to your chosen Setup Type:
-
Development — Installing Caché Development or Server Components Only
-
Server — Installing Caché Development or Server Components Only
-
Web Server — Installing the Web Server (CSP) Gateway Only
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:
-
Select Development or Server in the Setup Type dialog box, described in the Installing Caché procedure, and click Next.
-
The Install Unicode Support dialog box lets you select either 8-bit or Unicode character support for your installation (the default depends on your operating system locale).
-
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.
If you select Normal or Locked Down, the installation includes the following steps:
-
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é.
Important:If you are using Kerberos, you must configure a service account before installing Caché; see Preparing the Security Environment for Kerberos in the “Preparing to Install Caché” chapter for more information.
Note:See Shared Memory Allocation on Windows for information about granting the Windows “Lock Pages in Memory” (SELockMemory) privilege when running Caché under credentials other than the local system account.
-
The first panel of the Caché Users configuration dialog let you enter the initial password for the following predefined Caché user accounts _SYSTEM, Admin, and SuperUser, as well as the username you specified if you selected a defined Windows account as the service account on the previous panel. The second panel of the Caché Users configuration dialog lets you enter the initial password for the CSPSystem predefined account. For more details on these predefined users, see the Predefined User Accounts section of the “Users” chapter of the Caché Security Administration Guide.
For a detailed explanation of these security settings, see Managing Windows User Access to the Caché Instance below, and the Initial Caché Security Settings section of the “Preparing to Install Caché” chapter of this guide.
-
-
The Ready to Install dialog box lets you review the installation name, type, and directory, as well as the license key status.
Click the License button to select a Caché license key. If the key is valid, the license is automatically activated, the License Key field on the Ready to Install dialog is updated to Valid, and the license key is copied to the instance’s manager directory (install-dir/mgr) as cache.key during installation; 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.
-
The InstallShield Wizard Complete dialog box indicates the installation has completed successfully. Choose whether you want to see the Getting Started page and click Finish.
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 Programs 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:
-
Select Client in the Setup Type dialog box, described in the Installing Caché procedure, and click Next.
-
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.
-
The InstallShield Wizard Complete dialog box indicates the installation has completed successfully. Click Finish.
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.
Before you can use the client, you must specify the preferred server for this client; this procedure is described in the Define a Remote Server Connection section of the “Connecting to Remote Servers” chapter of the Caché System Administration Guide.
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:
-
Select Web Server in the Setup Type dialog box, described in the Installing Caché procedure, and click Next.
-
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.
-
The InstallShield Wizard Complete dialog box indicates the installation has completed successfully. Click Finish.
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:
-
/
-
/csp
-
/Cache (instance name)
You can change the configurations manually after installation from the CSP Gateway application; for information, see the CSP Gateway Configuration Guide.
The installer cannot automatically configure an Apache web server for use with Caché and CSP; for information on the required manual configuration procedures, see the CSP Gateway Configuration Guide.
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:
-
Select Custom in the Setup Type dialog box, described in the Installing Caché procedure, and click Next.
-
In the Custom Setup dialog box, select the components you want to install as described in the Components Installed by Setup Type table.
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 X 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.
-
The Install Unicode Support dialog box lets you select either 8-bit or Unicode character support for your installation (the default depends on your operating system locale).
Important:If you are installing Ensemble, you must select Unicode.
-
The Enter Port Numbers lets you change the port numbers assigned by Caché.
Note:You cannot enter a port number greater than 65535 or less than 1. For information about setting port numbers, see Set Port Numbers in the “Using Multiple Instances of Caché” chapter of the Caché System Administration Guide.
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 Memory and Startup page (System > Configuration > Memory and Startup).
-
WebServerPort number — 57772 or the first available subsequent number; you can change the WebServerPort values after installation from the Startup Settings page (System Administration > Configuration > Startup Settings).
-
-
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.
If you select Normal or Locked Down, it displays Enter Credentials for Caché Service, where you can choose to run Caché service under:
-
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.
For a detailed explanation of these settings, see the Initial Caché Security Settings section of the “Preparing for Caché Security” section of this book.
-
-
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.
-
The InstallShield Wizard Complete dialog box indicates the installation has completed successfully. Choose whether you want to see the Getting Started page and click Finish.
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.
This section discusses the following topics:
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>
where:
-
<path> is the path to the Caché installation file.
-
<installer>.exe is the name of 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.)
-
<properties> are the properties you are passing to the installer (see the Command-Line Properties table).
For example, to install an instance of Caché with the default instance name in an installation directory named C:\InterSystems\MyCache on a 64–bit 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 64–bit Windows system, specify the following:
C:\downloads\cache-2015.1.0.320.0-win_x64.exe /qn ADDLOCAL=cube,documentation,documentation_pdf
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
Special Consideration
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>
where <product_guid> is the ProductCode property value of the version you installed.
You can obtain the ProductCode property value from the Registry:
-
On 32-bit machines, go to the following Registry location: HKEY_LOCAL_MACHINE\SOFTWARE\InterSystems\Cache\Configurations\<instance>
-
On 64-bit machines, go to the following Registry location: HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\InterSystems\Cache\Configurations\<instance>
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}
You can also use any of the properties in the Command-Line Properties table with msiexec. For information about msiexec, see the Microsoft msiexec (command-line options)Opens in a new tab TechNet article (http://technet.microsoft.com/en-us/library/cc759262.aspx).
Command-Line Reference
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
In the following table, only the REINSTALL and REMOVE properties are used with installed instances, as described in Running an Unattended Upgrade or Reinstall and Running an Unattend Uninstall, respectively. All of the other properties are used only when installing new instances.
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.
Note:
In the absence of the ADDLOCAL property, or if ADDLOCAL=ALL is specified, all features are installed. 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.
Note:
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.
Note:
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.
Note:
If the service credentials are specified as LocalSystem, do not use this property. |
CACHEUSERPASSWORD |
Required if the security level is Normalor Locked Down; see the INITIALSECURITY property in this table. Use this property to specify the password for the predefined Caché accounts _SYSTEM, Admin, and SuperUser, as well as the account with the username specified by CACHESERVICEUSER if SERVICECREDENTIALS is specified as UserDefined.
Note:
If the initial security level is None, do not use this property. |
CSPSKIPIISCONFIG |
Optionally use this property to install IIS CSP binary files. With a value of 1, the files will be installed without any changes to the IIS web server configuration. With a value of 0, the installer will update the IIS web server configuration regardless of the existence of the /csp virtual directory. |
CSPSKIPAPACHE20CONFIG |
Optionally use this property to install Apache 2.0 CSP binary files. With a value of 1, the files will be installed without any changes to the IIS web server configuration. With a value of 0, the installer will update the IIS web server configuration regardless of the existence of the /csp virtual directory. |
CSPSKIPAPACHE22CONFIG |
Optionally use this property to install Apache 2.2 CSP binary files. With a value of 1, the files will be installed without any changes to the IIS web server configuration. With a value of 0, the installer will update the IIS web server configuration regardless of the existence of the /csp virtual directory. |
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.
Note:
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\" (the escaped quote characters are needed due to the space character).
Note:
Omit this property to accept the default of None. See also the CACHEUSERPASSWORD, CSPSYSTEMUSERPASSWORD, and SERVICECREDENTIALS properties in this table. |
INSTALLDIR |
Optionally use this property to specify the directory in which the instance is to be installed.
Note:
If the property is omitted, the default installation directory is C:\InterSystems\CACHEn, where n is {empty}, 1, 2, ... 127. |
INSTALLERMANIFEST |
If installing with an installation manifest, as described in Using the Manifest in the chapter “Creating and Using an Installation Manifest”, you must use this property to specify the location of the installation manifest (that is, your exported manifest class) . |
INSTALLERMANIFESTLOGLEVEL |
If installing with an installation manifest, as described in Using the Manifest in the chapter “Creating and Using an Installation Manifest”, optionally use this property to specify the log level of the setup() method of your installation manifest class. The default log level is 1. |
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é:
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é:
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.
Note:
If the initial security level is None, do not use this property. See Managing Windows User Access to the Caché Instance for important information about the Caché service account. If you specify UserDefined for this property, you must also specify the CACHESERVICEDOMAIN, CACHESERVICEPASSWORD, and CACHESERVICEUSER properties. |
SUPERSERVERPORT |
Optionally use this property to specify the Superserver port to be used by the instance being installed.
Note:
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 8–bit or 16–bit Unicode characters are to be supported by the instance being installed. For 8–bit characters, specify 0; for 16–bit characters, specify 1.
Note:
This setting applies to Caché instances only; Ensemble instances are always Unicode. If you omit this property, is 8–bit specified by default for all languages except Chinese, Korean and Japanese; 16–bit 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.
Note:
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.)
You can choose not to install any of the three optional databases, ISC_PACKAGE_DOCBOOK_DATABASE, ISC_PACKAGE_SAMPLES_DATABASE, and ISC_PACKAGE_USER_DATABASE, by changing the value to N (Y by default). Doing so will ensure these database/namespace definitions are not installed and will not be created in cache.rpf.
Component Group (featurename) | Components (featurename) |
---|---|
Server (server) |
Samples database (server_samples) User database (server_user) SQL Gateway (sqlgateway) Apache Formatting Objects Processor (fop) Server monitoring tools (server_monitoring) HotJVM RenderServer/QueuingRenderServer for Zen Reports (renderserver) Agent Service (agent_service)
Note:
For Ensemble and HealthShare only: ENSDemo database (server_ensdemo) |
Launcher (cube) |
|
Studio (studio) |
|
xDBC (sqltools) |
ODBC (odbc) JDBC (jdbc) |
Development (development) |
C++ Binding (cppbind) Light C++ Binding (lcbind) C++ SDK (cppsdk) Callin (callin) Callin, Threaded (callin_threaded) Perl Binding (perlbind) Python Binding (pythonbind) Java (javabind) Threaded Server Libraries (server_threaded) ActiveX Connectivity (activex) Other Samples (other_samples) |
Documentation (documentation) |
PDF Documentation (documentation_pdf) Online Documentation (documentation_online) |
CSP Gateway (cspgateway) |
IIS (cspiis) Apache 2.0 (cspapache20) Apache 2.2 (cspapache22) |
Post-Installation Tasks
Review the following important post-installation tasks:
-
You can manage your Caché instance using the Management Portal, which is accessible from the Caché Cube. For more information on this management tool, see the “Using the Management Portal” chapter of the Caché System Administration Guide.
-
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).
You can configure the instance not to autostart by changing the Start Caché on System Boot setting on the Memory and Startup page of the Management Portal (from the home page, select System Administration > Configuration > System Configuration > Memory and Startup). If this instance is part of a Windows cluster, you must clear this check box to prevent automatic startup, allowing the cluster manager to start Caché.
Note:You may occasionally need to prevent IRIS from starting with the host system starts while the host system is down (for example during restores). This can only be done at the OS level and is dependent on your configuration.
-
If you plan to connect remotely to other instances of Caché, follow the procedure described in the Define a Remote Server Connection section of the “Connecting to Remote Servers” chapter of the Caché System Administration Guide.
-
If you are upgrading from a previous version of Caché, see Post-installation Upgrade Tasks in the “Upgrading Caché” chapter of this book.
-
If you are using the Windows IIS Web server, file types must be mapped manually; for information, see the Web Servers for Microsoft Windows chapter of the CSP Gateway Configuration Guide.
-
If appropriate for your installation, perform any additional tasks described in the Special Considerations section.
Special Considerations
The following topics describe particular issues or tasks associated with licensing, specific platforms, or kinds of installations:
Managing Windows User Access to the Caché Instance
For Normal and Locked Down installations, two local user groups control access to the Caché instance. These groups are:
-
CacheServices, which grants the privileges to start, stop, and control the Caché instance.
-
Cache_Instance_<instancename>, which grants access to the installation tree—the directory in which Caché is installed and all its subdirectories.
Regarding these groups and their privileges:
-
When the CacheServices group is created, it is granted the Replace a process level token and Adjust memory quotas for a process privileges. Do not remove these privileges.
-
The CacheServices and Cache_Instance_instancename groups may not grant all the permissions that Caché requires to perform certain actions. To ensure Caché has the needed access to all instance, journal, and log files that are outside the installation tree, grant the Cache_Instance_instancename group full access to these files and the directories containing them. You may also grant this group additional permissions if necessary.
When you specify a service account other than the default local system account, Caché creates these two groups and adds the service account to each. See the Changing the Caché Service Account section below for details.
By default, any authenticated Windows users can access the installation tree, which may be undesirable. The following command removes the Windows access control entry (ACE) for authenticated users:
icacls <install-dir> /remove "NT AUTHORITY\Authenticated Users"
After running this command, only users that are administrators or in the Cache_Instance_<instancename> group have access to the installation tree.
If you do not do this, any user who can log in to the host Windows system can easily modify files, change settings, or disable the Caché instance entirely.
In some cases, you may want to give a Windows account other than the service account access to the installation tree. This could, for example, include accounts running automated tasks, or accounts that log in to 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.
Changing the Caché Service Account
Enter the following in the command line to change the InterSystems service account:
<install-dir>\bin\cinstall.exe setserviceusername <instance-name> <username> <password>
This command changes the service account to the user you provide. It also adds the user to the CacheServices and Cache_Instance_<instancename> groups, creating these groups if necessary. After running this command and restarting a Caché instance, the instance runs under the new service account.
Using an Installation Manifest
You can define an installation manifest that describes a specific Caché configuration and invoke it when executing the installation file. For more information on installation manifests, see the chapter “Creating and 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.
Please refer to the Multiple Caché Instances section of the Caché System Administration Guide for more detailed information.
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
For more information on .local files, see the MSDN library article Dynamic-Link Library RedirectionOpens in a new tab.
Registering Files
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.
For example:
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\
.
.
Running RegFiles.bat ALL when it is not necessary will prevent the uninstall procedure from removing some registry keys under HKLM\Software\InterSystems when you uninstall the last Caché instance.
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:
Code | Language |
---|---|
CHS | Chinese (Simplified) |
DEU | German (Standard) |
ENU | English (United States) |
ESP | Spanish (Spain) |
FRA | French |
ITA | Italian (Standard) |
JPN | Japanese |
KOR | Korean |
NLD | Dutch (Standard) |
PTB | Portuguese (Brazilian) |
RUS | Russian |
For information about changing the locale of a Caché installation, see Using the NLS Settings Page of the Management Portal in the “Configuring Caché” chapter of the Caché System Administration Guide.
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.
When you run setup as described in Caché Installation and select a Caché instance of the same version as the installer in the Select Instance box, or select an instance in Programs and Features and use the Change or Repair buttons, the Updating Instance instancename dialog box displays.
When you select the Uninstall button in Programs and Features, the uninstall operation begins immediately.
Click Next to display the Modify, repair or remove the program dialog box, then select the appropriate option on this dialog to change, repair, or uninstall the instance.
-
Select Modify to display the Custom Setup dialog box described in Performing a Caché Custom Installation. Using this dialog box, you can select the component groups or components you want to add or remove. Components are described in the Components Installed by Setup Type table.
-
Select Repair to repair problems with the instance such as missing or corrupt files or registry entries.
-
Select Remove to uninstall the instance.
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
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 Properties.
You can also click Start, point to Settings and click Network and Dial-up Connections.
-
Right-click Local Area Connection and click Properties.
-
Click Install.
-
Click Protocol in the Select Network Component Type dialog box and then click Add.
-
Click Have Disk in the Select Network Protocol dialog box.
-
Enter the path to the packet driver kit and click OK.
You can also enter the appropriate drive letter and click Browse to search for the correct path, \drivers\win2k, that contains the file ispkt2k.inf. Click Open and then click OK.
-
Select the appropriate driver for your operating system, InterSystems Packet Driver for Windows 2000, XP and 2003 Server, for example, 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.
If Caché is running under the default SYSTEM account, it has the “Lock Pages in Memory” privilege by default.
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.
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,
-
Request large pages.
-
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.
-
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 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.
The Write-cache Buffer
Certain Caché features utilize Windows write-cache buffer flushing, which is enabled by default. To verify this option is correctly enabled and Caché receives the full benefit of these features:
-
Open the Device Manager from the Control Panel.
-
Select the storage device from the Disk Drives section.
-
Click on the Policies tab.
-
Ensure that Turn off Windows write-cache buffer flushing on this device is not selected.