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.
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.
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
1 Please read the HP-UX topic of the Special Considerations section for required patches.
2 Please read the IBM AIX topic of the Special Considerations section for system requirements and environment considerations.
3 Please read the Red Hat Linux topic of the Special Considerations section for information regarding shared memory size and the MQ Series interface.
4 Please read the Sun Solaris topic of the Special Considerations section for environment considerations.
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 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:
  1. If upgrading an ISM 5.10 or 6.4 system, run the preconversion routine; otherwise bypass this step.
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:
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
Operating System Sample Mount Command
Tru64UNIX mount /dev/disk/cdrom0a /cdrom
HP-UX mount /dev/dsk/c1t2d0 /cdrom
IBM AIX* mount /dev/cd0
Red Hat Linux mount /dev/cdrom /mnt/cdrom -o map=o
Sun Solaris Mounted automatically (no command needed)
SuSE Linux mount /dev/cdrom /mnt/cdrom -o map=o
* 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:
  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 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.
  7. Shut down ISM:
    ./mstop
    
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:
To perform the installation:
  1. Start the installation procedure by running the cinstall script, located at the top level of the installation files:
    # /pathname/cinstall
    
    where pathname is the CD mount point or the directory where the downloaded tar or rpm file is unpacked.
  2. 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.
  3. 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.
  4. 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.
  5. 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.
  6. 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.
  7. 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:
    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.
  8. The installation begins copying files and displays various messages as it progresses.
  9. 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.
  10. If you chose to install the CSP Gateway, the installation begins. See Installing and Configuring the CSP Gateway appendix of Using Caché Server Pages for more information.
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 UNIX-based 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> [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.
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 2005 is 7/10/2005).
  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:
    # cd /<cache-dir>/mgr
    # ../bin/licentry
    
    where cache-dir is the directory where Caché is installed, and mgr is the manager's subdirectory.
  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 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.
HP-UX
The following patches for the HP-UX operating system (OS) may be required:
For more information and to download the applicable patches, refer to the support section of the HP Web site.
IBM AIX
There are several issues with AIX:
AIX Default Parameters
The default settings of several AIX parameters can adversely affect performance. For detailed information on the settings and recommendations, see the AIX Default Parameters section of the Calculating System Parameters for UNIX and Linux appendix.
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:
# bootinfo -y
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:
# lslpp -l bos.64bit
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:
# bootinfo -K
Alternatively, confirm that /unix points to unix_64, rather than unix_up or unix_mp:
# 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:
  1. Log in as root.
  2. In the PSE drivers section of the /etc/pse.conf file, uncomment the four lines that refer to the DLPI drivers.
  3. Save the file.
  4. Restart the computer.
If the DLPI devices are not installed, the Caché ObjectScript $ZU(114) function returns a null string rather than information about the Ethernet device.
Red Hat Linux
The default shared memory limit (shmmax) on Linux platforms is 32 MB. This value is too small for Caché, but it can be changed in the proc file system without a restart. See the Linux Platform Notes section of Calculating System Parameters for UNIX and Linux for more information.
Sun Solaris
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.