Caché Installation Guide
Installing Caché on OpenVMS
[Back] [Next]
   
Server:docs1
Instance:LATEST
User:UnknownUser
 
-
Go to:
Search:    

This chapter describes how to install Caché on an OpenVMS system. It assumes that you are familiar with OpenVMS 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 your parameter settings before you begin the installation, and use the online 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é.
Disk Space Requirements
A standard Caché installation needs approximately 340 MB (megabytes) of disk space depending on the type of installation you choose. This is the equivalent of 696320 blocks of disk space.
Supported Platforms and Web Servers
The latest version of Caché is supported on HP Alpha computers and HP Itanium processors.
Important:
For up-to-date information about platforms, versions, and features supported for each operating system, see InterSystems Supported Platforms.
If you are installing Caché on a Non-Uniform Memory Access (NUMA) machine, such as the GS160, contact the InterSystems Worldwide Response Center (WRC) for current configuration recommendations.
Supported Upgrade Paths and Procedures
If you are performing an upgrade, please first read and perform all necessary procedures described in the Upgrading Caché chapter.
When upgrading, back up your Caché installation after completing all the pre-installation upgrade tasks and before installing Caché.
Caché Installation
To install Caché, 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, the command procedure, CINSTALL, automatically changes your UIC to [1,4].
Note:
If the logical name CACHE$MGRUIC is defined during a new installation, the installation sets the owner UIC of the target directory to the value of that logical. Subdirectories and files inherit that UIC.
Once you are logged into OpenVMS:
Important:
Caché does not support lowercase characters in pathnames on OpenVMS.
Run the Installation Script
The installation script, CINSTALL, automatically does the following:
To perform the installation:
  1. The installation kit is downloaded to an OpenVMS system in the form of a .BCK file which, when restored, provides the Caché installation files. Locate the file, for example CACHE-2016_2_0_664_3-ALPHAVMS.BCK, in a suitable working directory, for example CACHEKIT, and issue the backup command, :
    $ CREATE/DIR [.CACHEKIT]
    $ BACKUP CACHE-2016_2_0_664_3-ALPHAVMS.BCK /SAVE [.CACHEKIT]
    where destination is the location in which you want to keep the restored installation files.
    Note:
    Depending on the way in which the .BCK file is conveyed to the OpenVMS system on which you restore it, the file’s attributes may be stripped in the process and not recognized by OpenVMS. If the BACKUP command results in an error, this may be the case. To restore the required attributes to the file once it is located on an OpenVMS system, the issue the following command in the working directory:
    $ SET file/attrib=(rfm:var,mrs:32256,lrl=32256,rat=none) CACHE-2015_2_0_664_3-ALPHAVMS.BCK
  2. Copy the installation files from the restored location to the OpenVMS system on which you want to install Caché, either to a work directory (recommended) or to the target installation directory.
  3. Start the 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:[CACHEKIT.2011-1-0-250-0]CINSTALL
    
    where, in this case, DKA0:[CACHEKIT.2011-1-0-250-0] specifies the directory path where you uncompressed and stored the installation kit distribution files.
  4. The installation script displays a list of any existing Caché instances on this machine. At the prompt, enter an instance name, using alphanumeric characters only. 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. If the directory you specify does not exist, it asks if you want to create it. The default answers are Yes; press Enter to continue with the installation.
  5. You next are asked whether you want to install Caché with 8-bit or Unicode character support.
  6. 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, which are used for building custom Callin and Callout modules. The default options, <YES>, are appropriate for these prompts in most cases.
  7. You next decide how restrictive you want the initial Caché security settings to be. Choose from Minimal (1), Normal (2), and Locked Down (3). The default is Minimal; if you choose this, the installation continues with the next step.
    If you enter 2 or 3, the script asks for additional information:
    1. Owner of the instance — Enter a username under which to run Caché. Caché creates an account for this user.
    2. Password for the instance owner — Enter the Caché password for the username twice to confirm it.
    3. Passwords for the _SYSTEM, Admin, and SuperUser predefined users and for the CSPSystem predefined user. For more details on these predefined users, see the Predefined User Accounts section of the “Users” chapter of the Caché Security Administration Guide.
    For a detailed explanation of these settings, see the Initial Caché Security Settings section of the “Preparing for Caché Security” appendix of this guide.
  8. Finally, for a new instance, or if the script does not detect a cache.key file in the mgr directory of an existing instance when upgrading, you are prompted for a license key file. If you specify a valid key, the license is automatically activated and the license key copied to the instance’s mgr directory during installation, and no further activation procedure is required.If you do not specify a license key, you can activate a license key following installation. See Activating a License Key in the “Managing Caché Licensing” chapter of the Caché System Administration Guide for information about licenses, license keys and activation.
  9. Review your installation options and press enter to proceed with the installation.
Edit the Startup File
For Caché to function properly, you may need to 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é instances, such as hardware-dependent definitions. This also includes defining logicals for magnetic tape devices and starting certain Caché instances automatically. To set up the file:
  1. Copy CACHE$STARTUP.COM from your installation subdirectory [.BIN] to SYS$LIBRARY.
  2. Make changes in that copy.
  3. 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.
Post-installation Tasks
Once you have completed running the installation procedure, perform the following tasks:
Install Caché on a Web Server
Caché does not install a private Web server on a OpenVMS instance; therefore to use the Management Portal to manage a Caché server on OpenVMS, you must install the CSP Gateway on a supported external web server and configure it to control the Caché instance on OpenVMS.
The version of Caché on the web server, in most cases, must be the same or a later version of the Caché system it manages.
See the Accessing the Management Portal section of the “Using Caché on OpenVMS” chapter of the Caché System Administration Guide for instructions on installing the CSP Gateway component of Caché on a separate web server to manage the OpenVMS Caché instance you just installed.
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 <instname>
where instname is the instance 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 <instname>
where instname is the instance name that you chose during the installation.
For more information, see the Using Caché on OpenVMS chapter of the Caché System Administration Guide.
Set OpenVMS 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 Runtime Library interface; they may otherwise obtain incorrect time values. This procedure is fully described in the OpenVMS documentation. In brief:
  1. Check if times in Caché and OpenVMS 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.
  2. Run the UTC$TIME_SETUP procedure to set the system time.
  3. 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 can configure OpenVMS to automatically adjust for Daylight Saving Time as described in the OpenVMS documentation.
Special Considerations
The following sections describe particular issues or tasks associated with licensing, specific platforms, or kinds of installations:
Multiple Caché Instances
You can install and simultaneously run multiple instances of Caché 4.0 and later on a single OpenVMS machine. Install Caché as for a single installation, giving each instance a unique name, a unique installation directory, and unique port numbers.
Please reference the Multiple Caché Instances section of the Caché System Administration Guide for further details.
Using SSL/TLS or Using X.509 Credentials for XML Security
To use SSL/TLS or to use X.509 credentials for XML security, OpenVMS versions prior to 8.3 require HP SSL for OpenVMS.
Patch for Client Access Using Kerberos on Itanium Platform
Applications attempting to access OpenVMS servers that use Kerberos authentication must install the patch, HP-I64VMS-TCPIP-V0505-11ECO1-1. The Engineering Change Order (ECO) is for TCP/IP, not the actual operating system. Without this patch, the server often transmits erroneous response packets back to clients using the C++ binding, ODBC, JDBC, or Studio.
Note:
This ECO applies only to OpenVMS on Itanium hardware. It is not needed for OpenVMS on Alpha.
SYSTEM-F-SECTBLFUL Error
Contact your system administrator or the InterSystems Worldwide Response Center (WRC) if you encounter an error similar to the following when installing Caché:
%INSTALL-E-FAIL, failed to CREATE entry for STRIPE1$:<CACHESYS.BIN>CACHE.EXE
-SYSTEM-F-SECTBLFUL, process or global section table is full
Also see the Calculating OpenVMS Parameters section of the “Calculating System Parameters for OpenVMS” appendix of this guide for setting values for the GBLSECTIONS parameter.
Uninstall Caché
The uninstall procedure removes all files installed and created during normal Caché processing, including journal and temporary database files.
Important:
Be aware that this procedure removes files you may wish to keep. For example: the license key (cache.key), the configuration file (cache.cpf), the user database file (cache.dat), and cluster files (cache.pij, cache.pijxxx).
To safely uninstall Caché, perform the following tasks:
  1. Find the name of the Caché instance you wish to uninstall using the ccontrol command to list all the instances on your machine:
    ccontrol list
  2. Stop the instance using the following command (if not already stopped):
    ccontrol stop <instname>
    where instname is the instance name that you chose during the installation.
  3. Unload the image from memory so that it can be deleted:
    ccontrol unload <instname>
    where instname is the instance name that you chose during the installation.
  4. Remove the instance using the following command:
    ccontrol delete <instname>
  5. Go to the instance directory:
    set def <device>:[<instancedir>]
    where instancedir is the directory where the instance is installed.
  6. Clean out the instance directory (make sure you are in the instance directory):
    Important:
    If you are performing this procedure on a system that is part of a Caché cluster configuration, do not delete any cluster files (cache.pij, cache.pijxxx) that reside in the instance directory.
    sh def 
    <device>:[<instancedir>]
    del [...]*.*;*
    Note:
    Repeat this command until there are no errors, which should be in the form:
    %DELETE-W-SEARCHFAIL, error searching for <device>:[<instancedir>]*.*;*
    -RMS-E-FNF, file not found
    
  7. Make sure everything was deleted:
    dir
    
    which should display the following message:
    %DIRECT-W-NOFILES, no files found