This chapter describes how to install Caché 5.0 on a Apple Mac OS X system. It assumes that you are familiar with Mac directory structures, utilities, and commands. It contains the following major sections:
Installation Requirements
This section describes the hardware and software requirements for installations of Caché 5.1:
Disk Space Requirements
A standard Caché installation that includes support for Caché Server Pages (CSP), needs 200–204 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 version 10.3 and 10.4 of the Apple Mac OS X operating system. For Mac OS X, the Caché Server Pages (CSP) technology is supported on the Apache 1.3 and 2.0 Web servers.
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.
Caché Installation
In most cases, the Caché installation is much like installing other software products on the Macintosh OS, and does not require an archive file. For cases where you are installing multiple instances of Caché on one machine, see the Caché UNIX-based Installation section for detailed instructions. Otherwise, the procedure is straightforward:
  1. Obtain the Caché disk image file (with a .dmg extension) from InterSystems.
  2. If the source is on a CD, it automatically mounts and displays a window containing the file, Cache_5.0.13.5603.0.2117.dmg, for example. Double-click the file to open a Finder window.
  3. The new window displays two files: Cache.mpkg and a Packages directory. Double-click Cache.mpkg to start the installation.
  4. The Welcome to Caché Installer window displays. The six steps involved in a Caché installation appear on the left-hand side of the window:
    Click Continue to begin the Caché installation.
  5. The Caché Software License Agreement displays. You must click Agree to accept the license agreement before you can Continue.
  6. Select the Macintosh HD volume as the destination and click Continue.
  7. Next, choose the installation type. If there are no instances of Caché on this machine, this is a new install, otherwise it is an upgrade. You may choose an Easy Install or a Custom Install.
  8. For a custom install, choose any or all of the three components:
    Clicking Easy Install installs all three components. If you plan to use this node only as a client, you may not need to install the Caché database engine.
  9. After choosing the installation type, click New or Upgrade. The install begins after asking you to authenticate that you have the correct privileges to install Caché. Enter your name and password and click OK.
  10. As the installation completes, you see various messages with a progress bar and finally the “Software installed successfully” message. The installer places Caché in the /Applications/Cache folder and runs from port 1972 or the first available port number after that. It names the instance CACHE. To finish the installation, click Restart.
When the machine restarts, Caché is left running. See the Post-Installation Tasks section for descriptions of tasks you may need to perform to begin using Caché.
Uninstall Caché
To uninstall a Caché instance that was installed with the Mac OS X installer, perform the following from the terminal as root:
cd /Applications/Cache      ; ./cstop
rm -rf /Applications/Cache
rm -rf /Library/Receipts/Engine.pkg
rm -rf /Library/Receipts/ODBC.pkg
rm -rf /Library/Receipts/CSPGateway.pkg.
Caché UNIX-based Installation
The alternative installation of Caché on the Mac OS X is much like the installation on any UNIX-based platform. 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, obtain the installation kit either on a CD-ROM which mounts automatically or from InterSystems in a compressed archive file. The Mac OS X tool, StuffIt Expander, automatically uncompresses the archive file and leaves the install files on the desktop.
Now you are ready to start the installation:
Important:
Do not use symbolic links for any Caché directory; unexpected results can occur.
You can install and simultaneously run multiple instances of Caché 5.0 on a single machine. Install Caché as for a single installation, giving each instance a unique name, a unique installation directory, and a unique port number. See the Configuring Multiple Caché Instances section of the Caché System Administration Guide for details.
Adjust Kernel Parameters
When using the UNIX-type installation, it may be necessary to adjust the shared memory kernel parameters of the operating system before installing Caché to avoid a shared memory problem illustrated by the following example:
Configuring minimum system...
Unable to allocate 1 MB global buffer space...
 
Unable to allocate shared memory
Cache: Invalid argument
Cache failed to start.
Check if shared memory requirements exceed system resources.
Call InterSystems Technical Support if you need assistance.
 
** Installation aborted **
 
Increase the shared memory on the Mac OS X system from the default values:
kern.sysv.shmmax: 4194304
kern.sysv.shmmni: 32
kern.sysv.shmall: 1024
To these new ones:
kern.sysv.shmmax: 67108864
kern.sysv.shmmni: 128
kern.sysv.shmall: 2097152
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:
    # /pathname/cinstall
    
    where pathname is the CD mount point or the directory where the downloaded tar file is uncompressed.
  2. The installation script identifies your system type and validates it against the installation type on the distribution media.
  3. Next the script displays a list of Caché instances on this machine, if there are any.
    At the configuration prompt, enter an instance name. If an instance with this name already exists, the program asks if you wish to upgrade it; if no such instance 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 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 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.
After the installation completes, Caché is left running. See the Post-Installation Tasks section for descriptions of tasks you may need to perform to begin using Caché.
Post-Installation Tasks
The following tasks help you get started using Caché:
Install Caché on Windows
Install Caché on a Windows client for use as a system management console or to use the Caché development tools. The procedure is described in the Caché Installation Guide for Windows. Install the client-only option to manage your Mac system. You can use telnet as well as SSH from a command prompt on a Windows client to connect to your OS X machine.
Reference the Connecting to Remote Servers chapter of the Caché System Administration Guide for details.
Start Caché
When Caché is installed it is left running. However, if you need to start Caché, first log into the operating system, then start Caché using the ccontrol command:
ccontrol start <configname>
Where configname is the instance name that you chose during the installation. If you installed using the Mac installer, the configname is most likely CACHE.
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 instance 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.
You can also use the csession command remotely from a Windows client described in the previous section.
License 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.
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 instance 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>: