This chapter describes how to install Caché 5.0 on a UNIX or Linux system.
It assumes that you are familiar with UNIX and Linux 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 and adjust your parameter settings before you
begin the installation.
Installation Requirements
The following sections describe 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 140 151 MB (megabytes) of disk space depending on
the type of installation you choose.
Supported Platforms and Web Servers
The latest version of Caché is supported on the following operating systems
and hardware platforms. For each operating system and platform that supports Caché
Server Pages (CSP) technology, the table lists the supported Web servers. For the
particular versions supported for each operating system, see the
Supported
Operating Systems table of the
Caché Supported Platforms guide.
Caché 5.0 Supported Platforms and Web Servers
Operating System |
Platform |
Unicode Support Available |
Apache Web Server
Support |
iPlanet Web Server Support |
Tru64 UNIX |
Alpha |
Yes |
Yes |
Yes |
HP-UX1 |
Hewlett-Packard |
Yes |
Yes |
Yes |
AIX2 |
IBM
PowerPC |
Yes |
Yes |
Yes |
Red Hat Enterprise Linux AS3 |
Intel |
Yes |
Yes |
Yes |
Sun Solaris4 (64-bit only) |
SPARC |
Yes |
Yes |
Yes |
SuSE Linux |
Intel |
Yes |
Yes |
No |
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 in as userid
root. It is
not sufficient to su (super user) to
root while logged in from
another account. Once you are logged into your operating system:
-
-
-
-
Important:
Do not use symbolic links for any Caché directory; unexpected results
can occur.
Transfer Files from the Distribution Media
Caché for UNIX-based platforms is distributed either on CD-ROM or acquired
from InterSystems in a compressed file with a
tar.Z extension.
There is also a single-user RPM (Redhat Package Manager) Linux kit available for download
from the
InterSystems
Web site. The
# represents the UNIX prompt in the following
examples.
Transfer the Caché installation files by choosing the one appropriate
method from the following:
-
-
Uncompress and untar the downloaded
tar.Z file:
# uncompress -c cache-x.x.x.xxx-platform.tar.Z | tar xvf -
-
Unpack the RPM package file:
# rpm -ivh cache-x.x.x-x.i386.rpm
Mount the Distribution CD
For the CD distribution, install directly from the CD, using the
mount command.
The device name and options for a CD
mount command vary between
systems. Typically, the
mount command is:
# mount <device> <mountpoint>
Where
<device> specifies the name of the CD-ROM device
and
<mountpoint> specifies the pathname of the directory to
which the CD is mounted.
CD Mount Commands
* The IBM-AIX mount command accepts only the device or the mount point, not
both.
For some operating systems, you must set up devices and mount points in the
file system table (preferably through the system management utility). Note that devices
and mount points vary by machine; those listed above are merely samples. Consult your
operating system documentation for more information.
After running the installation script, unmount the CD with the
umount command.
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 the current directory.
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
To run the installation script, you must be logged in as userid root. It is
not sufficient to su (super user) to root while logged in from another account.
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:
where
pathname is the CD mount point or the directory where
the downloaded tar or rpm file is unpacked.
-
The installation script identifies your system type and validates
it against the installation type on the distribution media.
If your system
supports more than one type, for example, nonclustered and clustered, or if the install
script cannot identify your system type, you are asked additional questions. If your
desired system type does not match that on the distribution media, the installation
stops. Contact the
InterSystems
Worldwide Response Center (WRC) for help in obtaining the correct distribution.
-
Next the script displays a list of Caché instances on this
machine, if there are any.
At the configuration 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.
-
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 after the Caché installation completes.
-
The script asks if you wish to install ODBC and the SQL Gateway, 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.
-
At this point in the installation, you are asked which group should
be allowed to start and stop Caché. Only one group can have these privileges
and must be listed in the
/etc/group file. The options are:
-
Enter the name or userid number of an existing group; Caché
verifies that the group exists before proceeding.
-
Enter
0 (zero) if you want the group to which
the
root user belongs to be the only group to start and stop Caché.
-
Press
Enter without entering anything. In this case,
only the
root user has this privilege. It is best to enter a value
here rather than relying on the default.
Note:
The permissions on the
<cache-install-dir>/bin directory
are modified at installation/upgrade time to remove write access by group and other.
Since the owner is root, only the system administrator is able to modify files in
this directory.
-
The installation begins copying files and displays various messages
as it progresses.
-
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.
-
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:
csession <configname> [parameters]
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
login for single-user version of Caché and, for multiuser versions, emergency
login in case logins are disabled. |
csession <configname> -U "namespace" |
Specifies
login namespace. |
csession <configname> -b <partition> |
Specifies maximum
partition size for process (in KB) |
csession <configname> "[label[+offset]]^routine" |
Runs a routine in user mode. |
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 2005 is 7/10/2005).
-
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:
# cd /<cache-dir>/mgr
# ../bin/licentry
where
cache-dir is the directory where Caché is
installed, and
mgr is the manager's subdirectory.
-
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 UNIX-based 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
-
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 machine. Install Caché as for a single installation,
giving each configuration a unique name, a unique installation directory, and a unique
port number.
The following patches for the HP-UX operating system (OS) may be required:
-
PHSS_16587 To use the CDL compiler, HP-UX
11.00 systems without the C++ development environment require the HP runtime patch
PHSS_16587 or
a newer patch that includes it.
-
PHSS_26559 To prevent processes from
hanging when compiling Caché Basic routines, install the s700_800 11.00 ld(1)
and linker tools cumulative patch,
PHSS_26559, for the HP 11.00
OS. This applies to the 32-bit kit of Caché 5.0 on HP-UX 11.
This
may also affect other applications that dynamically load a shared object, such as
customers that compile their own applications for use with the Caché callin
and callout interfaces.
The issue is only with dynamic loading of 32-bit executables. If running on
HP-UX 11i, but with the 32-bit version of Caché for HP-UX 11, you also require
this patch.
For more information and to download the applicable patches, refer to the support
section of the
HP Web site.
There are several issues with AIX:
PowerPC System Requirements
Current versions of Caché are only supported on PowerPC. PowerPC AIX
4.3 and later support a 64-bit runtime environment on 64-bit hardware. AIX 5.1 and
later support a 64-bit kernel on POWER4, or equivalent, hardware.
The following table lists the allowable combinations of runtime, kernel, and
hardware configurations:
AIX PowerPC Configuration Combinations
Combination |
Runtime |
Kernel |
Hardware |
1 |
32-bit |
32-bit |
32-bit |
2 |
32-bit |
32-bit |
64-bit |
3 |
64-bit |
32-bit |
64-bit |
4 |
32-bit |
64-bit |
64-bit |
5 |
64-bit |
64-bit |
64-bit |
Note:
Combinations 4 and 5 require AIX 5.1 or later.
64-bit Caché requires combination 5.
To determine whether the CPU is 64-bit, issue the following command:
This returns
64 for POWER3 or POWER4 and returns
32 on
older PowerPC systems.
To determine whether the 64-bit runtime environment is installed, issue the
following command:
To determine whether the 64-bit runtime environment is loaded at boot, issue
the following command:
# grep load64bit /etc/inittab
To determine whether the system is running the 64-bit kernel, issue the following
command:
# ls -l /unix
... /unix -> /usr/lib/boot/unix_64
# file unix
unix: symbolic link to /usr/lib/boot/unix_64
To summarize, 64-bit Caché for PowerPC AIX requires that the 64-bit runtime
environment be loaded on the 64-bit kernel; this requires AIX 5.1, or later, on POWER4,
or equivalent, hardware.
Shared Library Environment Variable for Caché Engine Link Libraries
The Caché Engine link libraries contain a batch file that references
any installed C linker.
If you have either the standard UNIX C libraries or any proprietary C libraries
defined in the
LIBPATH environment variable, then your environment
is ready.
If not, append the paths for the standard UNIX C libraries to
LIBPATH;
these paths are
/usr/lib and
/lib.
Use of DDP and Raw Ethernet
On IBM AIX machines, in order to use DDP and raw Ethernet, the machine must
have the DLPI (Data Link Provider Interface) packages installed. If the machine does
not have the DLPI packages, then obtain them from your IBM provider and create DLPI
devices through the following procedure:
-
-
In the PSE drivers section of the
/etc/pse.conf file,
uncomment the four lines that refer to the DLPI drivers.
-
-
If the DLPI devices are not installed, the Caché ObjectScript
$ZU(114) function returns a null string rather than information
about the Ethernet device.
If the Ethernet adapters are protected against access by non-root users, the
Caché ObjectScript
$ZU(114) function invoked
by a non-root user returns a null string rather than information about the Ethernet
device.