Caché Installation Guide for OpenVMS

This document describes how to install Caché 4.1 on an OpenVMS system. This document assumes that you are familiar with OpenVMS directory structures, utilities, and commands. It contains the following major sections:

You may wish to consult the appendix on Calculating System Parameters to verify your parameter settings before you begin the installation, or use the OpenVMS Parameter Calculator to obtain parameter values that InterSystems recommends.

Installation Requirements

This section describes the hardware and software requirements for new and upgrade installations of Caché 4.1.

Disk Space Requirements

For a standard Caché installation that includes support for Caché Server Pages (CSP), you need about 75 Mb (153600 blocks) of disk space.

Supported Platforms and Web Servers

The current version of Caché can be installed 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 Support Center for current configuration recommendations.

For OpenVMS v7.2, the Caché Server Pages (CSP) technology is supported on the Apache 1.3.12 Web server. For OpenVMS v7.3, CSP is supported on the Compaq Secure Web server 1.0. You must install the Web server before installing Caché.

Supported Upgrade Paths and Procedures

If you are performing an upgrade, please first read the Caché Upgrade and Compatibility Guide. If you are upgrading from a supported direct upgrade path, perform the necessary tasks in the Pre-installation Tasks for Upgrades section of this document, and then continue with the Caché Installation.

Pre-installation Tasks for Upgrades

If this is a new installation, you may bypass this section and proceed to the Caché Installation; otherwise, perform the applicable upgrade tasks described in this section.

Save Custom Routines and Globals

The installation procedure updates all InterSystems Caché routines and globals in the manager's directory. Therefore, if you have altered these routines and globals, the installation will overwrite your changes. To prevent your own routines and globals in the manager's directory from being affected by the installation, ensure that they have names that begin with “Z”, “z”, “%z”, or “%Z”.

Upgrade Tasks Unique to Clusters

If you are upgrading an OpenVMS cluster system, perform the following tasks:

Prepare Each Cluster Member

Before upgrading a member of a Caché for OpenVMS cluster system from 3.x (or earlier) to 4.1, cleanly shut down all members of the Caché cluster and remove the CACHE.PIJ file. If you do not remove this file, the installation will not be upgraded and will produce error messages in the cconsole.log for startup:

Cache (2100036c) Tue Aug 1 14:28:59 2000
Activating Namespaces
Cache (21000404) Tue Aug 1 14:28:59 2000 Cluster image journal 
is incompatible with this version 
Cache (21000404) Tue Aug 1 14:28:59 2000 Unable to join the cluster 
Cache (21000404) Tue Aug 1 14:29:00 2000
ENQdaemon exited due to VMS error code (decimal) 0

Note:

Caché 3.x (or earlier) and 4.0 (or later) systems cannot coexist in a single Caché cluster due to PIJ file version upgrade incompatibilities.

Upgrade Tasks Unique to ISM

If you are upgrading an ISM system, perform the following tasks:

Check Routine Labels and References

Prior to an upgrade to Caché 4.1 from ISM 6.4, you must:

Use %LBLRDEF to check all application routines for duplicate labels. If there are routines with duplicate label names, they will generate a <LABELREDEF> error, the routines will not recompile, and they will not be executable with Caché 4.1.
Check all application routines for routine references over 8 characters (including function calls, DO routine calls, $ZT calls, and so on). Caché recognizes up to 31 significant characters in routine names, and this could possibly cause <NOROUTINE> errors at compile and/or run time.

Run the Integrity Check Utility

Run the system integrity check utility on existing directories:

> Do ^INTEGRIT

Run the Pre-Conversion Routine

After backing up the current system, run the pre-conversion routine. The pre-conversion routine examines the current ISM configuration and builds a Caché configuration file that is used for the upgrade. To run the pre-conversion script:

Start the ISM system:
```
@MSTART
```
Copy the CPRECONV.COM script into the current manager's directory from the distribution media.
Copy the CVTCFG.EXE 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 CPRECONV using the following operating system command:
```
@CRunSysConv
```
The script prompts for the Caché installation directory (which is where CPRECONV stores the Caché configuration file that it creates); if the directory does not exist, CPRECONV creates it. You can install into any directory. The CPRECONV script creates one cache.cpf file for each system configuration and the default network and namespace configurations associated with that system configuration.
Shut down ISM:
```
@MSTOP
```

Back Up the System

Before proceeding with the rest of the installation, InterSystems recommends that you run a complete backup of your system. Use your usual backup utility. After backing up your current system, you are now ready to proceed with the Caché Installation.

Caché Installation

The following are the steps for all installations of Caché 4.1:

Log Into OpenVMS

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, CINSTALL, the command procedure automatically changes your UIC to [1,4].

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. For illustration, the examples below use a work directory named DKA0:[CACHEDIST]. Use the VMS backup command to copy the distribution files to the work directory:

For CD distribution:

$ MOUNT/OVERRIDE=IDENTIFICATION cd_device:
$ backup cd_device:[CACHE]CACHE.BCK/SAVE/SELECT=[REL.ALPHAVMS.DIST...]
		DKA0:[CACHEDIST...]
$ DISMOUNT cd_device:

For magnetic tape distribution:

$ MOUNT/FOREIGN magtape_device:
$ backup magtape_device:CACHE.BCK/REWIND/SAVE - 
		/SELECT=[REL.ALPHAVMS.DIST...] DKA0:[CACHEDIST...]
$ DISMOUNT magtape_device:

Run the Installation Script

The installation script, CINSTALL, automatically does the following:

Loads the system manager's database and other system databases.
For ISM upgrades, renames the .DAT and .EXT files to CACHE.DAT and CACHE.EXT.
Starts Caché in installation mode.
Installs system globals and routines (if required).
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 automatic installation procedure by running the CINSTALL script, located at the top level of the installation files:
```
@CINSTALL
```
Or, if you are not in the installation directory, use a full path to invoke the script, such as:
```
@DKA0:[CACHEDIST.Q4-0-BUILD134]CINSTALL
```
Where, in this case, DKA0 specifies the disk on which Caché is installed and CACHEDIST.Q4-0-BUILD134 specifies the directory tree of the installation.
The installation script displays a list of Caché configurations on this system, if there are any. At the installation prompt, enter a configuration name. If a configuration with this name already exists, the program assumes that you wish to upgrade it; if no such configuration exists, it assumes that 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. Use Unicode only if your applications need to handle 16-bit languages, such as Japanese. It is best to enter the appropriate choice here rather than relying on the default.

Caution:
If you choose a Unicode installation, you cannot revert to an 8-bit version without potential data loss. This is because 16-bit characters cannot be stored in a database that stores those characters in 8 bits.
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. 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.

The License Key Information section provides details about InterSystems Caché licensing.
Database journaling is enabled by default for new installations; upgrades retain their prior journaling settings.

Edit the Startup File

For Caché to function properly, you must 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:

Copy CACHE$STARTUP.COM from your configuration's subdirectory [.BIN] to SYS$LIBRARY.
Make changes in that copy.
Edit the OpenVMS system startup command file, SYS$MANAGER:SYSTARTUP_VMS.COM, to invoke the CACHE$STARTUP.COM file.

For further details, read the comments contained within the CACHE$STARTUP.COM file.

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.

Post-installation Tasks

If you are upgrading you may now perform the Post-installation Tasks for Upgrades before running Caché. Otherwise proceed to the Prepare to Run Caché section.

Post-installation Tasks for Upgrades

Run the System Conversion Utility for ISM Upgrades

Once the installation is complete on an ISM upgrade, run the system conversion utility, %SYSCONV, from the system manager's directory. This automatically runs all required conversions and re-collates routine and object code globals. A converted database may use slightly more disk storage after conversion. Before running the %SYSCONV utility:

Make sure that the current manager's directory contains a valid license key file. The %SYSCONV utility starts several processes to speed conversion of the databases, if permitted by your license type.
If you use National Language Support (NLS), configure your locale properly on Caché before running the ISM conversion utility. To do this, use the Windows Caché console.

To run the system conversion utility:

Start Caché, ensuring that no other users have access to Caché during the conversion.

To disable other logins from Windows:
1. Start the Caché Control Panel (by right clicking on the Caché cube and selecting it from the menu).
2. Right-click on the Caché installation and click Properties. This displays the System Properties dialog box.
3. On the System Access tab, check the Inhibit All sign-ons check box and click Apply.
At the Caché prompt (indicated below by ">"), run the %SYSCONV routine. To convert all databases, change to the manager's namespace, %SYS, and run:
```
> Do ALL^%SYSCONV
```
To convert a single database, run:
```
> Do START^%SYSCONV(<directory-name>)
```
The ALL^%SYSCONV procedure upgrades only databases recorded in the UCI list. To convert a database that is not in the UCI list, use the START^%SYSCONV procedure.
To check the status of the conversion, run:
```
> Do STATUS^%SYSCONV
```

Convert Caché Object and SQL Applications

If you have databases containing Caché Object or Caché SQL applications from an earlier version, convert them for use with Caché 4.1:

Upgrade the Object Data Dictionary to the v4.1 structure (Caché 4.1 supports packages) by running the object upgrade utility from the command line:
```
Do $system.OBJ.Upgrade() 
```
Run this utility for every namespace in which there are any preexisting Caché Object applications.
Recompile all classes (again for each namespace):
```
Do $system.OBJ.CompileAll()
```

Convert Caché ObjectScript Routines

Recompile any Caché ObjectScript routines that were developed on a version of Caché before 4.1; this ensures that they are compatible with the Caché 4.1 runtime engine.

You can now Prepare to Run Caché.

Prepare to Run Caché

Start Caché, log into the system, and set up the configuration using the following commands:

Start Caché

If it is not already running, 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 offers the following options:

The ccontrol Command and Its Functions

Command	Description
ccontrol start <configname> [args] {configfile}	Brings up a configuration
ccontrol stop <configname> [args]	Shuts down a configuration
ccontrol force <configname>	Forces a configuration down
ccontrol list	Lists all installed configurations
ccontrol help [start \| stop \| force]	Gives function-specific help for the start, stop, and force functions.

In the table above, configname is the name of the configuration that you are managing and configfile is an optional alternate configuration file (with a .cpf extension) that is located in the same directory as the configuration being started.

The optional args available are:

quietly — non-interactive with minimal dialog
nostu — do not run the startup routine (^STU)
help — print the help message and exit
Any other value will be taken as a .cpf configuration file name

Log Into Caché

Once Caché is started, log into it using the csession command:

csession <configname>

Where configname is the configuration name that you chose during the installation.

Use the csession command to log into and run Caché:

The csession Command and Its Arguments

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 Run-time Library interface; they may otherwise obtain incorrect time values. This procedure is fully described in the OpenVMS documentation from Compaq. In brief:

Check if times in Caché and VMS 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 have now installed and are ready to use Caché 4.1.

Special Considerations

The following sections describe particular issues or tasks associated with licensing, various 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 choose to enter the license key information at this time, follow the procedure described in the Enter License Key Information section.
Otherwise, Caché continues the installation at step 6 without configuring licensing; you can set up licensing after completing the installation as described in the Enter License After Installation section.

Enter License Key Information

The key information includes the Customer Name, Order Number, Product Authorization Key, Expiration Date, Machine Type, and Machine ID. Be sure to enter the information exactly as specified in the license.

If you choose yes, Caché installs a key and starts the license server as part of the installation process:

The script asks if you wish to start the license server. For a standard installation, answer yes.
If you answer yes, the script prompts for a license server name or IP address and then for a port on that machine. To run the license server on the same machine where you have installed Caché, choose the default (127.0.0.1, the local host, and port 4001).
Next, enter your customer name, whether that is a person or an organization.
For the next two prompts, order number and product authorization key, enter the values exactly as they appear on the key.
Next, 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).
For the next two prompts, machine type and machine ID, enter the values exactly as they appear on the key.
For the rest of the prompts, enter the values that appear 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. You can now return to step 6 in running the installation script procedure.

Enter License After Installation

You can enter your license key information after the installation is complete either on the local machine or from Caché configuration utilities on a Windows machine.

Enter License on the Local Machine

To set up licensing after installation on the local machine:

Shut down Caché
```
$ CCONTROL stop <configname>
```
From the Caché manager's directory, run the licentry program:
```
$ SET DEFAULT [.MGR]
$ RUN [-.BIN]licentry 
```
The program asks if you want to use a license server. Enter yes. If you answer yes, licentry then prompts for a license server name or IP address and then for a port on that machine; to run the license server on the standard port on the local machine, choose the defaults.
Next, enter your customer name, whether that is a person or an organization.
For the next two prompts, order number and product authorization key, enter the values exactly as they appear on the key.
Next, 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).
For the next two prompts, machine type and machine ID, enter the values exactly as they appear on the key.
For the rest of the prompts, enter the values that appear on the key.
When prompted to save the key, type yes (the default), and the script then states that it has saved the cache.key file.
Restart Caché:
```
$ CCONTROL start <configname>
```

Enter License From Windows

If you do not enter a license key during the installation procedure, you can do so from a Windows machine with the Caché configuration utilities on it:

From the Windows Start menu, choose Programs and go into the Caché menu; run the Caché Configuration Manager.
From the Caché Configuration Manager dialog box, click Wizards..., select Create a License, and click OK.
Click Next in the Introduction dialog box.
A dialog box appears asking if you wish to obtain a license from an existing server. When entering a license key do not select the Use License Server check box. Click Next.

If, however, you require a license server that varies from the standard setup, follow the procedure in the Use a License Server section to enter this information.
In the Set License Information dialog box, enter the identifying information from the license that you obtained from InterSystems. The information includes the Customer Name, Order Number, Product Authorization Key, Expiration Date, Machine Type, and Machine ID. Be sure that you enter the information exactly as specified in your license.
In the Set License Capacity Info dialog box, enter the specific information from your license.
Click Finish. When Caché starts, your new license information takes effect and Caché will obtain licenses from the license server if warranted.

If you have any problems entering your license information, see the License Troubleshooting section.

License Troubleshooting

If Caché displays 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 a Windows client to connect to the OpenVMS Caché server using the Caché Configuration Manager.
Check that the license server is running. This process shows up in the %SS display as LMFSERV; to view the %SS display:
1. Log into Caché using csession with the -B option:
```
$ CSESSION <configname> -"B"
```
2. Then, at the Caché prompt, invoke the following commands (the ZN command changes namespaces and the DO command invokes the %SS display):
```
%USER> zn "%SYS"
%SYS> Do ^%SS
```
3. In the Routine column, look for an entry with the name LMFSERV. If this entry exists, then the license server is running; otherwise, it is not.
```
[Startup]
RunLicenseServer=YES
LicenseServer=<ip_address>,<port>
```
Where ip_address is the IP address of the server machine and port is the TCP port of the server machine.
Check that the IP address for the license server is correct.

Multiple Configurations

You can install and simultaneously run multiple configurations of Caché 4.0 and later on a single OpenVMS machine. Install Caché as for a single configuration, giving each configuration a unique name, a unique installation directory, and a unique port number.

The special considerations for multiple configurations are:

Each configuration must be Version 4.0 or later of Caché. For example, Caché 4.1 and 3.2.1 cannot run on the same machine at the same time.
Multiple configurations can share the same key (using the license server mechanism), but the multiple configurations cannot run concurrently if they have their own local copies of the same key.
Multiple configurations can be networked.
Protection is included against simultaneous database use (that is, each configuration must have its own database and cannot access or modify another configuration's database).
Only one configuration can use DDP (the Distributed Data Protocol). DDP is an older distributed data protocol that is supported for interoperation with legacy applications.
Each configuration must have a unique port number. See the next section for information on how to Set Port Numbers.

Set Port Numbers

For a standard, single configuration of Caché, the port number is 1972 by default and is set automatically during installation. For multiple configurations of Caché 4.0 and later on a single machine, each must have a unique port number. To specify this value:

Start the Caché Configuration Manager (by right clicking on the Caché cube and selecting it from the menu).
On the Advanced tab, expand the section for General settings.
Set the value for Default Port Number.

The assignment of unique port numbers ensures that the Caché default port number is always available for use by another installation. Since the installation process does not involve setting the port number, change it afterwards.