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:
Installation Requirements
This section describes the hardware and software requirements for new
and upgrade installations of Caché 5.0.
A standard Caché installation that includes support for Caché
Server Pages (CSP), needs 140151 MB (megabytes) of disk space depending
on the type of installation you choose. This is the equivalent of 286720309248
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.
Supported Upgrade Paths and Procedures
When upgrading, you may want to back up your Caché installation
after completing all the pre-installation upgrade tasks and before installing
Caché.
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:
-
-
-
-
-
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.
-
$ MOUNT/OVERRIDE=IDENTIFICATION cd_dev:
$ backup cd_dev:[CACHEDIST]C50B544.BCK/SAVE/SELECT=[REL.ALPHAVMS.DIST...]
dest_dev:[CACHEKIT...]
$ DISMOUNT cd_dev:
Where
cd_dev is the device name of your CD-ROM
drive,
[CACHEDIST]C50B544.BCK is the name of the compressed
backup file on the CD,
dest_dev is the device name for
your local hard disk, and
[CACHEKIT] is a directory that
you create on your local disk to temporarily uncompress and store the installation
kit distribution files. Two levels down in the uncompressed kit is
CINSTALL.COM.
-
For magnetic tape distribution:
$ MOUNT/FOREIGN magtape_dev:
$ backup magtape_dev:C50B544.BCK/REWIND/SAVE/SELECT=[REL.ALPHAVMS.DIST...]
dest_dev:[CACHEKIT...]
$ DISMOUNT magtape_dev:
Where
magtape_dev is the device name of your magnetic
tape drive,
C50B544.BCK is the name of the compressed
backup file on the tape,
dest_dev is the device name
for your local hard disk, and
[CACHEKIT] is a directory
that you create on your local disk to temporarily uncompress and store the
installation kit distribution files. Two levels down in the uncompressed kit
is
CINSTALL.COM.
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:
-
-
Copy the
CPRECONV script from the distribution
media into the current manager's directory.
-
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é.
-
Use the
%G utility to check the
^SYS("UCI") global.
Make sure it properly represents all current application databases.
-
Start the preconversion routine using the following operating
system command:
-
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.
-
Run the Installation Script
The installation script,
CINSTALL, automatically
does the following:
-
Installs the Caché system manager databases.
-
Starts Caché in installation mode.
-
Installs Caché system manager globals and routines.
-
Shuts down Caché and restarts using the default configuration.
Upgrade installations restart using their original configuration files, updated
as necessary.
To perform the installation:
-
Start the installation procedure by running the
CINSTALL script,
located at the top level of the installation files:
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.
-
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.
-
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 88591. 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.
-
-
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.
-
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.
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:
-
-
Make changes in that copy.
-
Install Caché on Windows for Use as a Console
Once you have completed running the installation procedure, perform
the following tasks:
-
-
-
-
If appropriate for your installation, perform any additional
tasks described in the
Special Considerations section.
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.
Once Caché is started, initiate a Caché session using
the
csession command:
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:
-
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.
-
Run the UTC$TIME_SETUP procedure to set the system time.
-
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.
The following sections describe particular issues or tasks associated
with licensing, specific platforms, or kinds of installations:
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 choose to enter the license key information during
installation, follow the procedure described in the
Enter
License Key Information section.
-
Otherwise, Caché continues the installation without
configuring licensing; you can set up licensing after completing the installation
as described in the
Enter License After
Installation 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:
-
Enter the license capacity exactly as it appears on the key.
-
Enter the customer name, whether that is a person or an organization,
exactly as it appears on the key.
-
Enter the order number exactly as it appears on the key.
-
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).
-
Enter the authorization key exactly as it appears on the key.
-
Enter the machine ID exactly as it appears on the key.
-
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:
-
$ CCONTROL stop <configname>
-
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.
-
Enter the license key information exactly as it appears on
the key following the procedure described in the preceding section,
Enter License Key Information.
-
$ 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:
-
Point to
and click
to
add a remote server connection to the Caché instance just installed.
Make sure you specify the appropriate port number for this connection.
-
Point to
, point
to
, and then click the appropriate
connection server name you entered in the previous step.
-
-
-
When the configuration starts, your new license information takes effect.
If Caché starts with only a single-user license or you receive
the error
<LICENSE LIMIT EXCEEDED>:
-
Check that the license key was entered properly in the
cache.key file.
It must be entered exactly as on the paper key, including the keywords using
uppercase and lowercase.
-
If you have entered the key by hand and are still having problems,
use the Configuration Manager from a Windows client to connect to the OpenVMS
Caché server and enter the key using the license wizard.
-
Check to see that the license key is properly installed:
-
Log into Caché using
csession with
the -B option:
$ CSESSION <configname> -"B"
The quotes are required to indicate an uppercase B.
-
Do $System.License.CKEY()
-
If the key is not valid, the customer name field displayed
in the default diagnostic key explains why.
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.