This chapter describes how to install Caché 5.0 on an OpenVMS system. It assumes that you are familiar with OpenVMS directory structures, utilities, and commands. This chapter contains the following major sections:
You may wish to consult the appendix on Calculating System Parameters to verify your parameter settings before you begin the installation, and use the OpenVMS Parameter Calculator to obtain parameter values that InterSystems recommends.
Installation Requirements
This section describes the hardware and software requirements for new and upgrade installations of Caché 5.0.
Disk Space Requirements
A standard Caché installation that includes support for Caché Server Pages (CSP), needs 140–151 MB (megabytes) of disk space depending on the type of installation you choose. This is the equivalent of 286720–309248 blocks of disk space.
Supported Platforms and Web Servers
The latest version of Caché is supported on Compaq Alpha computers running OpenVMS v7.2 and v7.3. If you are installing Caché on a Non-Uniform Memory Access (NUMA) machine, such as the GS160, contact the InterSystems Worldwide Response Center (WRC) for current configuration recommendations.
For OpenVMS v7.2, the Caché Server Pages (CSP) technology is supported on the Apache 1.3 and 2.0 Web server. For OpenVMS v7.3, CSP is supported on the Compaq Secure Web server 1.0 and 1.3.
You must install the Web server before installing Caché. Its support on each operating system is dependent on the operating system vendor and is subject to change. See the Web Server Configuration section of the “CSP Configuration” chapter of the Using Caché Server Pages guide for more information.
Supported Upgrade Paths and Procedures
If you are performing an upgrade, please first read and perform all necessary procedures described in the Upgrade and Compatibility chapter of the Caché Release Notes.
The chapter contains a list of Supported Upgrade Paths and a detailed description of Upgrade Tasks necessary to upgrade to this version of Caché.
When upgrading, you may want to back up your Caché installation after completing all the pre-installation upgrade tasks and before installing Caché.
Caché Installation
To install Caché 5.0, log into OpenVMS as the system manager or with CMKRNL, WORLD, BYPASS, SYSLCK, ALTPRI, and OPER privileges. If your UIC is not [1,4] when you run the installation script, the command procedure, CINSTALL, automatically changes your UIC to [1,4].
Note:
If the logical name CACHE$MGRUIC is defined during a new configuration installation, the installation sets the owner UIC of the target directory to the value of that logical. Subdirectories and files inherit that UIC.
Once you are logged into OpenVMS:
  1. If upgrading an ISM 5.10 or 6.4 system, run the preconversion routine; otherwise bypass this step.
Transfer Files from the Distribution Media
Transfer the Caché installation files from the distribution media either to a work directory (recommended) or to the target directory. Use the OpenVMS backup command to copy the distribution files to the work directory.
Run the Preconversion Routine (ISM Upgrades Only)
If upgrading an ISM 5.10 or 6.4 system, perform the following procedures; otherwise bypass this section.
After running your backup and transferring the Caché files from the distribution media, run the preconversion routine. The preconversion routine examines the current ISM configuration and builds a Caché configuration file that is used for the upgrade. To run the preconversion script:
  1. Start ISM:
    @MSTART
  2. Copy the CPRECONV script from the distribution media into the current manager's directory.
  3. Copy the CVTCFG program from the distribution media either into the current manager's directory or into the directory where you plan to install Caché.
  4. Use the %G utility to check the ^SYS("UCI") global. Make sure it properly represents all current application databases.
  5. Start the preconversion routine using the following operating system command:
    @CPRECONV
  6. The script prompts for the Caché installation directory, which is where the routine stores the Caché configuration file that it creates. If the directory does not exist, the routine creates it. You can install into any directory, the default is /USR/CACHESYS.
    The routine creates one cache.cpf file for each system configuration and the default network and namespace configurations associated with that system configuration.
  7. Shut down ISM:
    @MSTOP
Run the Installation Script
The installation script, CINSTALL, automatically does the following:
To perform the installation:
  1. Start the installation procedure by running the CINSTALL script, located at the top level of the installation files:
    @CINSTALL
    
    Or, if you are not in the installation directory, use a full path to invoke the script, such as:
    @DKA0:[CACHEKIT.Q5-0-BUILD544]CINSTALL
    
    Where, in this case, DKA0:[CACHEKIT.Q5-0-BUILD544] specifies the directory path where you uncompressed and stored the installation kit distribution files.
  2. The installation script displays a list of Caché instances on this machine, if there are any. At the prompt, enter a configuration name. If an instance with this name already exists, the program asks if you wish to upgrade it; if no such configuration exists, it asks if you wish to create it and asks you to specify its location on disk.
  3. You next are asked if you want to install Caché with 8-bit or Unicode character support.
    InterSystems recommends 8-bit character support for locales based upon the Latin-1 character set, ISO 8859–1. Use Unicode if the base character set for your locale is not Latin-1, or if you plan to have data from locales based upon a different character set. If you use an 8-bit version of Caché, your data is not portable to 8-bit locales based on a different character set.
    Caution:
    If you choose a Unicode installation, you cannot revert to an 8-bit version without potential data loss. This is because an 8-bit version of Caché cannot retrieve 16-bit character data from a database.
    For client installations, choose the format that matches that of the server with which this client communicates. Install an 8-bit client to access 8-bit servers, and a Unicode client to access Unicode servers.
  4. If you have a supported Web server installed, you are asked if you want to configure it for CSP. Answer Yes to install the CSP Gateway. See Installing and Configuring the CSP Gateway appendix of Using Caché Server Pages for more information.
  5. The script then asks if you wish to load the source code for the various system management utilities and load the Caché engine link libraries, which are used for building custom callin and callout modules. The default options are appropriate for these prompts in most cases.
  6. If the installation does not detect a cache.key file in the MGR subdirectory, it asks if you want to enter the license key information; the default is No.
    If you choose Yes, Caché installs a key as part of the installation process. The License Key Information section provides details about entering InterSystems Caché licensing information.
Edit the Startup File
For Caché to function properly, you may need to edit the CACHE$STARTUP.COM file to add commands that set up Caché when you restart your machine. The CACHE$STARTUP.COM script should only contain commands that affect all Caché configurations, such as hardware-dependent definitions. This also includes defining logicals for magnetic tape devices and starting certain Caché configurations automatically. To set up the file:
  1. Copy CACHE$STARTUP.COM from your installation's subdirectory [.BIN] to SYS$LIBRARY.
  2. Make changes in that copy.
  3. Edit the OpenVMS system startup command file, SYS$MANAGER:SYSTARTUP_VMS.COM, to invoke the CACHE$STARTUP.COM file.
For further details, read the comments contained within the CACHE$STARTUP.COM file.
Install Caché on Windows for Use as a Console
Install Caché on a Windows machine for use as a system management console. The procedure is described in the Caché Installation Guide for Windows. You can install the client-only option to manage your OpenVMS system.
The version of Caché on the client PC in most cases, must be the same or a later version of the Caché system it manages. See the Supported Caché Version Interoperability section of the Caché Supported Platforms document for specific information.
Post-Installation Tasks
Once you have completed running the installation procedure, perform the following tasks:
Start Caché
When Caché is installed it is left running. However, if you need to start Caché, first log into your operating system, then start Caché using the ccontrol command:
ccontrol start <configname>
Where configname is the configuration name that you chose during the installation.
Use the ccontrol command to start and stop Caché. It is described in greater detail in the Controlling Caché Instances section of the Caché System Administration Guide.
Once Caché is started, initiate a Caché session using the csession command:
csession <configname>
Where configname is the configuration name that you chose during the installation.
Additional command options are outlined in the following table:
Caché csession Command and Options
Command Description
csession <configname> -"B" Provides emergency system administrator login to perform system tasks such as setting up licensing.
csession <configname> -"U" "namespace" Specifies login namespace.
csession <configname> "[label[+offset]]^routine" Runs a routine in user mode.
Set OpenVMS v7.x Time for Use with Caché
Beginning with OpenVMS version 7.0, C programs that use UTC time functions (including Caché) require the proper setup for the DEC C Runtime Library interface; they may otherwise obtain incorrect time values. This procedure is fully described in the OpenVMS documentation. In brief:
  1. Check if times in Caché and OpenVMS are synchronized, using the following commands at the Caché prompt:
    > Write $ZTIME($P($H,",",2))
    > !SHOW TIME 
    
    The first displays the Caché time and the second displays the OpenVMS system time. The two values should be approximately the same.
  2. Run the UTC$TIME_SETUP procedure to set the system time.
  3. If this procedure exits prematurely, enter the following command at the OpenVMS prompt:
    $ @SYS$MANAGER:UTC$TIME_SETUP.COM "" BOTH 
    
    This command forces an update of both the time zone and Time Differential Factor (TDF) data. Make sure these values are consistent. For example, if the selected main time zone is US (33), Eastern zone (6) or EST, the appropriate TDF is -5:00 (or -4:00, if Daylight Saving Time is in effect).
    You can configure OpenVMS to automatically adjust for Daylight Saving Time as described in the OpenVMS documentation.
You are now ready to use Caché 5.0.
Special Considerations
The following sections describe particular issues or tasks associated with licensing, specific platforms, or kinds of installations:
License Key Information
Caché uses license keys to ensure proper operation of its registered sites. Caché requires a product activation key that defines the Caché features and capacity available. You may receive identifying information from InterSystems for the license key file on paper, by phone, by fax, or by computer connection. You may chose one of two options for entering license key information:
If you have any problems entering your license information, see the License Troubleshooting section.
License keys are not required for single-user installations. If you are setting up such a site, bypass these sections.
Important:
Licenses from versions prior to Caché 4.1 or other InterSystems products do not work with Caché 5.0. Please contact the InterSystems Worldwide Response Center (WRC) for an appropriate key if you are upgrading.
Enter License Key Information
The key information includes the License Capacity, Customer Name, Order Number, Authorization Key, Expiration Date, and Machine ID. Be sure to enter the information exactly as specified in the license:
  1. Enter the license capacity exactly as it appears on the key.
  2. Enter the customer name, whether that is a person or an organization, exactly as it appears on the key.
  3. Enter the order number exactly as it appears on the key.
  4. Enter the key's expiration date in the form mm/dd/yyyy, leaving out any leading zeroes (so that 10 July 2002 is 7/10/2002).
  5. Enter the authorization key exactly as it appears on the key.
  6. Enter the machine ID exactly as it appears on the key.
  7. When prompted to save the key, type Y or Yes (the default), and the script then states that it has saved the cache.key file.
Enter License After Installation
You can enter your license key information after the installation is complete either on the local machine or from the Caché Configuration Manager of a Windows client.
Enter License on the Local Machine
To set up licensing after installation on the local machine:
  1. Shut down Caché
    $ CCONTROL stop <configname>
    
  2. From the Caché manager's directory, run the licentry program:
    $ SET DEFAULT DKA0:[CACHESYS.MGR]
    $ RUN [-.BIN]licentry 
    
    Where, in this case, DKA0 specifies the disk on which Caché is installed, and CACHESYS.MGR specifies the manager's directory.
  3. Enter the license key information exactly as it appears on the key following the procedure described in the preceding section, Enter License Key Information.
  4. Restart Caché:
    $ CCONTROL start <configname>
    
Enter License From a Windows Client
If you do not enter a license key during the installation procedure, you can do so from the Caché Cube of a Windows client:
  1. Point to Preferred Server and click Add/Edit to add a remote server connection to the Caché instance just installed. Make sure you specify the appropriate port number for this connection.
  2. Point to Remote System Access, point to Configuration Manager, and then click the appropriate connection server name you entered in the previous step.
  3. In the Configuration Manager dialog box, click Wizards, select Create a License, and click OK.
  4. In the Set License Information dialog box, enter the identifying information from the license that you obtained from InterSystems. The information includes the License Capacity, Customer Name, Order Number, Expiration Date, Authorization Key, and Machine ID. Be sure to enter the information exactly as specified in the license key.
  5. Click OK.
When the configuration starts, your new license information takes effect.
License Troubleshooting
If Caché starts with only a single-user license or you receive the error <LICENSE LIMIT EXCEEDED>:
Multiple Caché Instances
You can install and simultaneously run multiple instances of Caché 4.0 and later on a single OpenVMS machine. Install Caché as for a single installation, giving each configuration a unique name, a unique installation directory, and a unique port number.
Please reference the Multiple Caché Instances section of the Caché System Administration Guide.