docs.intersystems.com
Home  /  System Administration  /  System Administration Guide  /  Using Multiple Instances of InterSystems IRIS


System Administration Guide
Using Multiple Instances of InterSystems IRIS
[Back]  [Next] 
InterSystems: The power behind what matters   
Search:  


You can install and run multiple instances of InterSystems IRIS™ on a single host system. Each instance is a unique, independent InterSystems IRIS environment. This chapter addresses the following topics:
InterSystems IRIS Instances
There are many ways to connect to an InterSystems IRIS instance. Two of the most common are through the InterSystems IRIS launcher (only on Windows platforms) and from the command line of the console.
Each InterSystems IRIS 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 InterSystems IRIS, you give it an instance name. To perform command-line procedures on a particular instance of InterSystems IRIS, use this name. You can start, stop, and maintain each of these instances independently. The following table shows the most common commands to manipulate InterSystems IRIS instances.
Control Commands
Action desired ObjectScript command
Starting an InterSystems IRIS instance
iris start instname
Connecting to an InterSystems IRIS instance
iris session instname
Stopping an InterSystems IRIS instance
iris stop instname
These commands are described in detail in Connecting to an InterSystems IRIS Instance (iris session) and Controlling InterSystems IRIS Instances (iris).
From the InterSystems IRIS launcher, you can also control multiple remote InterSystems IRIS environments. InterSystems IRIS allows you to create and edit all InterSystems IRIS 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 Windows platforms, you can also start, stop, and restart an InterSystems IRIS instance by using the Windows Services administrative tool to start, stop, and restart the Controller service for the instance. However, you cannot use this method to start an instance configured for startup with interactive encryption key activation (see Configuring Startup with Interactive Key Activation in the “Managed Key Encryption” chapter of the InterSystems Security Administration Guide) because it does not allow you to enter the required credentials.
Connecting to an InterSystems IRIS Instance
Once you have started InterSystems IRIS, you can log into InterSystems IRIS on the command line using the iris session command, as follows:
iris session <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 an InterSystems IRIS instance, or include the full path in the command, for example:
c:\InterSystems\IRIS27\bin\iris session IRIS4
Note:
As shown in the preceding example, the instance name you specify can be different from the instance of the iris session binary you are executing, but is always required, even if they are the same.
InterSystems IRIS iris session Command and Arguments
Command Description
iris session instname -B
Provides system administrator emergency login.
To execute an emergency startup on Windows, you must open the Command Prompt using the Run as Administrator option. See also Emergency Access in the “System Management and Security” chapter of the Security Administration Guide for information about starting and logging into InterSystems IRIS in emergency access mode.
iris session instname -U namespace Specifies the login namespace.
-U has no effect if you are starting InterSystems IRIS with a user account whose Startup Namespace is specified (see Properties of Users in the “Users” chapter of the Security Administration Guide).
iris session instname -b partition_size Specifies the maximum partition size (in KB) for the process.
iris session 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:
where, for example, parameter-list is specified in the form "string literal",,-+-000123.45600E+07, and omitted parameters are passed to the target as $Data(parameter)=0.
Whitespace and shell meta characters must be quoted in an operating-system dependent form.
To use the iris session command or the iris command (see Controlling InterSystems IRIS Instances) on a remote server, use iris session or Terminal, or a remote connection through Terminal or Telnet/ssh client.
Controlling InterSystems IRIS Instances
You can control an instance of InterSystems IRIS using the iris command. The iris command supports a number of functions and has the following syntax:
iris <function> <instname> [arguments]
where instname is the instance name that you chose during the installation and arguments depends on the platform and function.
Note:
To display the most current help file for running the iris command, invoke iris help. On Windows, run the command from the install-dir\Bin directory (or include the full path with the command):
c:\InterSystems\IRIS27\bin>iris help
The iris help command displays the IRISHelp.html file in your browser; the file is in the install-dir\Help directory.
The optional arguments (indicated by [arguments]) are:
To use the iris command or the iris session command (see Connecting to an InterSystems IRIS Instance) on a remote server, use a Telnet or ssh client or the Terminal.
The following table displays some common uses of the iris command.
Important:
The iris 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.
InterSystems IRIS iris Command and Functions
Command Description
iris start instname [args] Starts instance instname.
You may be prompted to start in “Emergency Mode;” if so, see Emergency Access in the “System Management and Security” chapter of the Security Administration Guide for more information.
iris start instname [full pathname of .cpf file] Starts InterSystems IRIS instance instname, optionally using the specified name.cpf file. If a name.cpf file is not specified, the InterSystems IRIS instance uses the iris.cpf file.
iris start instname nostu On all platforms except Windows, starts the specified instance without running ^STU.
iris startnostu instname On Windows, starts the specified instance without running ^STU.
iris stop instname Shuts down an instance.
iris stop instname restart On all platforms except Windows, shuts down and then starts the specified instance.
iris stopstart instname On Windows, shuts down and then starts the specified instance.
iris stopnoshut instname 4 Shuts down the named instance using INTNOSHUT^SHUTDOWN.
iris force instname Forces an instance down.
iris list
Lists the following information for all installed instances:
iris qlist Lists essentially the same information for each instance as iris 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
  • InterSystems IRIS version
  • Instance status
  • Pathname of InterSystems IRIS 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)
iris 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
  • InterSystems IRIS version
  • Superserver port number
  • Installation directory
iris allw Lists the same information for each instance as iris all, without wrapping long field values. Lines longer than 80 characters may result.
iris qall On platforms other than Windows, lists the same information for each instance as iris all, except that long lines are truncated to 78 characters plus a terminating tilde (~);
iris stat instname [args] Retrieves system statistics. This is the same as the irisstat utility (see the appendix Monitoring InterSystems IRIS Using the irisstat Utility in the C Monitoring Guide). iris stat is not available on Windows, but irisstat is.
iris help Displays most recent information about the iris command.
iris help [start | stop | force] Gives function-specific help for the start, stop, and force functions.
iris rename instname {newname} Renames the instance (not available on Windows systems).
iris [run | console | cterminal] instname Runs InterSystems IRIS in programmer mode with either no device, the console, or the terminal for $Principal (Windows only).5
iris [run | console | cterminal] instname routine Runs the named InterSystems IRIS routine in application mode with either no device, the console, or the terminal for $Principal. (Windows only).5
iris [run | console | cterminal] instname routine namespace3 Runs the named InterSystems IRIS routine in the indicated namespace in application mode with either no device, the console, or the terminal for $Principal. (Windows only).5
iris runw instname routine [namespace3] Runs the named InterSystems IRIS 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, iris waits for the InterSystems IRIS process to terminate before returning. The exit code from the InterSystems IRIS process is returned by iris.5
Table Notes
1 If you require complete information, such as for parsing or reporting purposes, use iris list.
2 (removed)
3 The namespace argument has no effect if you are starting InterSystems IRIS with a user account whose namespace property contains a value. See the Users chapter of the Security Administration Guide for details on maintaining user accounts.
4 Only owner and irisusr can run SHUTDOWN without iris session login.
5 On UNIX®/Linux systems, these tasks are executed using the iris session command (see Connecting to an InterSystems IRIS Instance).
Configuring Multiple InterSystems IRIS Instances
You can install and simultaneously run multiple instances of InterSystems IRIS on a single machine. Install InterSystems IRIS 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:
Note:
Please see the Multiple InterSystems IRIS Installation Issues section of the Installation Guide for important facts when installing multiple instances of InterSystems IRIS on the Windows platform.
Set Port Numbers
For a standard, single instance of InterSystems IRIS, the superserver port number is 51773 by default. For multiple instances of InterSystems IRIS 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 InterSystems IRIS instance as follows:
You most likely do not need to change the superserver or web server port numbers because of the way the InterSystems IRIS installation assigns them. However, you do need to assign each instance a unique Telnet port number. You can change the superserver port value after installation from the Memory and Startup page (System Administration > Configuration > System Configuration > Memory and Startup) of the Management Portal, and you can change the web server and Telnet port values after installation from the Startup Settings page (System Administration > Configuration > Additional Settings > Startup) and the Telnet Settings page (System Administration > Configuration > Device Settings > Telnet Settings), respectively, of the Management Portal.
Note:
If you frequently use and manage multiple instances of InterSystems IRIS on one machine, verify that each is assigned unique port numbers. The assignment of unique port numbers avoids confusion when using the InterSystems IRIS launcher tools on multiple instances from one Windows client.