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 200204 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.
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:
-
Obtain the Caché disk image file (with a
.dmg extension)
from InterSystems.
-
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.
-
-
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.
-
The Caché Software License Agreement displays. You must click
Agree to
accept the license agreement before you can
Continue.
-
-
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.
-
For a custom install, choose any or all of the three components:
-
CSP Gateway (required to view Caché online documentation)
-
-
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.
-
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.
-
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.
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
kern.sysv.shmmax: 67108864
kern.sysv.shmmni: 128
kern.sysv.shmall: 2097152
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
file. 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 file is uncompressed.
-
The installation script identifies your system type and validates
it against the installation type on the distribution media.
-
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.
-
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 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
Information section provides details about entering InterSystems Caché
licensing 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é.
The following tasks help you get started using 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.
Once Caché is started, initiate a Caché session using the
csession command:
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.
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.
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 instance 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 Mac-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.