Skip to main content

This is documentation for Caché & Ensemble. See the InterSystems IRIS version of this content.

For information on migrating to InterSystems IRIS, see Why Migrate to InterSystems IRIS?

Controlling Caché Instances

Controlling Caché Instances

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 ccontrol help command displays the CcontrolHelp.html file in your browser; the file is in the install-dir\Help directory.

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)

To use the ccontrol command or the csession command (see Connecting to a Caché Instance) on a remote server, use a Telnet or ssh client or the Terminal.

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.
Note:
You may be prompted to start in “Emergency Mode;” if so, see Emergency Access in the “System Management and Security” chapter of the Caché Security Administration Guide for more information.
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
    • running
    • down
    • starting or stopping
    • incomplete start or stop, logins disabled
  • Instance’s system health state, if running (see System Monitor Health State in the “Using the Caché System Monitor” chapter of the Caché Monitoring Guide) (not included on Windows)
  • Mirror member type and status (if a mirror member) (see %SYSTEM.Mirror.GetMemberType() and %SYSTEM.Mirror.GetMemberStatus())
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:
  • Instance status, as follows
    • <blank> (status unavailable, logins disabled)
    • dn (down or has crashed)
    • up (running)
    • st (starting or stopping)
  • Instance name
  • Caché version
  • Superserver port number
  • Installation directory
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.

2 (removed)

3 The namespace argument has no effect if you are starting Caché with a user account whose namespace property contains a value. See the “Users” chapter of the Caché Security Administration Guide for details on maintaining user accounts.

4 Only owner and cacheusr can run SHUTDOWN without csession login.

5 On UNIX®/Linux systems, these tasks are executed using the csession command (see Connecting to a Caché Instance).

Feedback