Caché System Administration Guide
Using Multiple Instances of Caché
|
|
You can install and run multiple instances of Caché on a single host system. Each instance is a unique, independent Caché environment. This chapter addresses the following topics:
There are many ways to connect to a Caché instance. Two of the most common are through the Caché Launcher (only on Windows platforms) and from the command line of the console.
Each Caché instance installed on a Windows machine has its own launcher. All of the launcher utility functions operate within the context of the instance associated with that launcher.
As you install each instance of Caché, you give it an instance name. To perform command-line procedures on a particular instance of Caché, use this name. You can start, stop, and maintain each of these instances independently. The following table shows the most common commands to manipulate Caché instances.
Control Commands
Action desired |
Caché command |
Starting a Caché instance |
|
Connecting to a Caché instance |
|
Stopping a Caché instance |
|
From the Caché Launcher, you can also control multiple remote Caché environments. Caché allows you to create and edit all Caché data on remote systems. This includes, but is not limited to, running remote backups, editing remote instances, and creating and compiling remote objects and routines. See the chapter
Connecting to Remote Servers in this guide for more detailed information.
Note:
On UNIX® platforms, when a Caché instance is stopped, restarted, or forced down, the instance will wait for all processes to detach from shared memory for a maximum of 30 seconds. After 30 seconds, the instance will close. If there are still processes attached to the shared memory after the instance has closed, restarting the instance will fail.
Once you have started Caché, you can log into Caché on the command line using the
csession command, as follows:
csession <instname> [arguments]
where
instname is the name of the instance that you are managing, and
[arguments] indicates one or more of the optional arguments described in the following table. On a Windows system, you must execute the command from its location, the
install-dir\bin directory of a Caché instance, or include the full path in the command, for example:
C:\InterSystems\Cache27\bin\csession Cache33
Note:
As shown in the preceding example, the instance name you specify can be different from the instance of the
csession binary you are executing, but is always required, even if they are the same.
Caché csession Command and Arguments
Command |
Description |
csession instname -B |
Provides system administrator emergency login. |
csession instname -U namespace |
Specifies the login namespace. |
csession instname -b partition_size |
Specifies the maximum partition size (in KB) for the process. |
csession instname "[label[+offset]]^routine" |
Specifies the name of a COS program to run in user mode. In addition to the specified formats, you can pass parameter lists consisting of string and/or numeric literals, as well as omitted (void) parameters, as follows: Whitespace and shell meta characters must be quoted in an operating-system dependent form. |
You can control an instance of Caché using the
ccontrol command. The
ccontrol command supports a number of functions and has the following syntax:
ccontrol <function> <instname> [arguments]
where
instname is the instance name that you chose during the installation.
Note:
To display the most current help file for running the
ccontrol command, invoke
ccontrol help. On Windows, run the command from the
install-dir\Bin directory (or include the full path with the command):
C:\InterSystems\Cache27\bin>ccontrol help
The optional arguments (indicated by [
arguments]) are:
-
quietly non-interactive with minimal dialog
-
nostu do not run the startup routine (
^STU)
-
help print the help message and exit
-
restart start Caché after a successful shutdown (for
stop function only and not available on Microsoft Windows platforms)
The following table displays some common uses of the
ccontrol command.
Important:
The
ccontrol command has other platform-specific functions, which can be displayed with the
help function; functions that are internal to InterSystems do not appear in the help display.
Caché ccontrol Command and Functions
Command |
Description |
ccontrol start instname [args] |
Starts instance instname. |
ccontrol start instname [full pathname of .cpf file] |
Starts Caché instance instname, optionally using the specified name.cpf file. If a name.cpf file is not specified, the Caché instance uses the cache.cpf file. |
ccontrol start instname nostu |
On all platforms except Windows, starts the specified instance without running ^STU. |
ccontrol startnostu instname |
On Windows, starts the specified instance without running ^STU. |
ccontrol stop instname [args] |
Shuts down an instance. |
ccontrol stopnoshut instname 4 |
Shuts down the named instance using INTNOSHUT^SHUTDOWN. |
ccontrol stopstart instname |
Shuts down and restarts the named instance. |
ccontrol force instname |
Forces an instance down. |
ccontrol list |
Lists the following information for all installed instances: Instance name (and installation type) Installation directory Caché version Pathname of Caché parameter ( .cpf) file Superserver and webserver port numbers Instance status, as follows
|
ccontrol qlist |
Lists essentially the same information for each instance as ccontrol list, plus the JDBC Gateway port, but without labels and all on one line, separated by carets (^), in the following order. You can specify a single instance on the command line to display information for that instance only.Instance name (and installation type) Installation directory Caché version Instance status Pathname of Caché parameter ( .cpf) file Superserver, webserver, and JDBC Gateway port numbers Instance’s system health state, if running (not included on Windows) Mirror member type and status (if a mirror member)
|
ccontrol all 1 |
Lists the following information for all installed instances, one instance per line: |
ccontrol allw |
Lists the same information for each instance as ccontrol all, without wrapping long field values. Lines longer than 80 characters may result. |
ccontrol qall |
On platforms other than Windows, lists the same information for each instance as ccontrol all, except that long lines are truncated to 78 characters plus a terminating tilde (~); |
ccontrol stat instname [args] |
Retrieves system statistics. This is the same as the cstat utility (see the appendix Monitoring Caché Using the cstat Utility in the C Monitoring Guide). ccontrol stat is not available on Windows, but cstat is. |
ccontrol help |
Displays most recent information about the ccontrol command. |
ccontrol help [start | stop | force] |
Gives function-specific help for the start, stop, and force functions. |
ccontrol rename instname {newname} |
Renames the instance (not available on Windows systems). |
ccontrol [run | console | cterminal] instname |
Runs Caché in programmer mode with either no device, the console, or the terminal for $Principal (Windows only).5 |
ccontrol [run | console | cterminal] instname routine |
Runs the named Caché routine in application mode with either no device, the console, or the terminal for $Principal. (Windows only).5 |
ccontrol [run | console | cterminal] instname routine namespace3 |
Runs the named Caché routine in the indicated namespace in application mode with either no device, the console, or the terminal for $Principal. (Windows only).5 |
ccontrol runw instname routine [namespace3] |
Runs the named Caché routine in the specified namespace (if any) in application mode with no input/output device for $Principal (Windows only). When run from a batch script, ccontrol waits for the Caché process to terminate before returning. The exit code from the Caché process is returned by ccontrol.5 |
Table Notes
1 If you require complete information, such as for parsing or reporting purposes, use
ccontrol list.
4 Only owner and cacheusr can run SHUTDOWN without csession login.
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 instance a unique name, a unique installation directory, and a unique port number for the superserver, web server, and Telnet.
The special considerations for multiple instances are:
-
Each instance must be version 4.0 or later of Caché. For example, Caché 5.1 and 3.2.1 cannot run on the same machine at the same time.
-
Multiple instances can share the same multiserver key, but if they do, they must use the same license server or set of license servers. Each system running an instance of Caché under the auspices of one or more license servers must have a local copy of the authorizing license key file installed in every instance.
-
Multiple instances can be networked.
-
Protection is included against simultaneous database use (that is, each instance must have its own databases and cannot access or modify another instance’s databases).
-
Each instance must have unique port numbers. See the next section for information on how to
Set Port Numbers.
For a standard, single instance of Caché, the superserver port number is
1972 by default. For multiple instances of Caché 4.0 and later on a single machine, each must have a unique port number. During installation, subsequent instances are assigned the next available port if you choose to set it automatically, or you can manually enter port numbers during the installation. A standard installation sets the following port numbers for your Caché instance as follows:
-
Superserver port number
1972 or the first available subsequent number equal to or higher than
56773
-
-
Note:
If you frequently use and manage multiple instances of Caché on one machine, verify that each is assigned unique port numbers. The assignment of unique port numbers avoids confusion when using the Caché Launcher tools on multiple instances from one Windows client.