docs.intersystems.com
InterSystems IRIS Data Platform 2019.2  /  System Administration Guide

System Administration Guide
Using Multiple Instances of InterSystems IRIS
Previous section           Next section
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:
Managing InterSystems IRIS Instances
There are many ways to connect to and manage an InterSystems IRIS instance, which may be one of several installed on a given system. Two of the most common methods are as follows:
Connecting to an InterSystems IRIS Instance
The InterSystems IRIS Terminal is a command line you can use in any namespace of an InterSystems IRIS instance. Open the Terminal for a running instance using the command iris terminal instname, where instname is the name you gave the instance at installation. A containerized instance is typically named IRIS.
Log in using one of the predefined user accounts, with the password you provided during installation, or an account you created. The prompt that displays indicates the login namespace, for example:
# iris terminal IRIS

Node: intersystems2588, Instance: IRIS27

Username: admin
Password: ********
USER>
To exit the Terminal and close the window, enter the command halt.
On a containerized instance, log in for the first time using one of the predefined accounts and the default password SYS; you are immediately prompted to change the password.
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 terminal IRIS4. You can execute the binary of a given instance to connect to that instance or another; the instance name is required either way.
Controlling an InterSystems IRIS Instance
The iris command supports a number of functions beyond terminal, and is invoked in the format iris function instname arguments, where instname is the instance name that you chose during the installation and arguments depends on the platform and function. As previously noted, on Windows, run the command from the install-dir\bin directory (or include the full path with the command).
Typical uses of the iris command are shown in the following table.
Important:
The iris help command displays all the command functions and arguments; the file IRISHelp.html is in the install-dir\Help directory. Some platform-specific functions of the iris command are not listed in this table, but are shown in the help display; functions that are internal to InterSystems do not appear there.
Note:
The iris command often displays error information in a message box. You can suppress this message box by adding quietly as the final argument to the iris command, which runs the command non-interactively with minimal dialog. This argument is also useful with other commands, such as iris stop and iris stopstart when you want shut the instance down without having to confirm the command.
InterSystems IRIS iris Command Functions and Arguments
Command and Description Arguments
iris start instname [arguments] — Starts the instance.
[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.
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 [arguments] — Shuts down the instance.
restart — On all platforms except Windows, starts the instance after shutting it down.
iris stopstart instname — On Windows, starts the instance after shutting it down.  
iris stopnoshut instname — Shuts down the instance using INTNOSHUT^SHUTDOWN.
Only the instance owner and irisusr can run INTNOSHUT^SHUTDOWN without logging into the Terminal.
 
iris force instname — Forces down the instance .  
iris list instname — Lists the following information for the specified instance, or fall all installed instances if none is specified:
 
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
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
If you need complete information, such as for parsing or reporting purposes, use iris list.
 
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 — Retrieves system statistics, except on Windows systems. The same as the irisstat utility (see the appendix Monitoring InterSystems IRIS Using the irisstat Utility in the C Monitoring Guide), which is available on Windows.  
iris rename instname newname — Renames the instance (not available on Windows systems).  
iris terminal instname — Opens the InterSystems IRIS Terminal for the instance.
-B — Enables system administrator emergency access to the Terminal.
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.
-b partition_size — Specifies the maximum partition size (in KB) for the process.
routine — Runs the named InterSystems IRIS routine in application mode in the Terminal for $Principal. (Windows only).
"[label[+offset]]^routine" — Specifies the name of an ObjectScript 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:
  • "routine[([parameter-list])]"
  • "[label]^routine[([parameter-list])]"
  • "##CLASS(package.class).method[([parameter-list])]"
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.
-U namespace — Specifies the Terminal login namespace.
namespace — Used with routine, runs the routine in the indicated namespace (Windows only).
The namespace and -U arguments have 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 console instname — Opens the InterSystems IRIS Terminal in an operating system command window rather than a Terminal window. Same arguments as iris terminal.
iris run instname — Runs InterSystems IRIS in programmer mode with no input/output device for $Principal (Windows only). Same arguments as iris terminal.
iris runw instname routine — Runs the named InterSystems IRIS routine in application mode with no input/output device for $Principal (Windows only). When run from a batch script, the command waits for the InterSystems IRIS process to terminate before returning the exit code from the process. namespace — Runs the routine in the specified namespace.
The namespace argument 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 help — Displays the most recent information about the iris command. start, stop, force — Display function-specific help for the start, stop, and force functions.
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.


Previous section           Next section
Send us comments on this page
View this book as PDF   |  Download all PDFs
Copyright © 1997-2019 InterSystems Corporation, Cambridge, MA
Content Date/Time: 2019-09-20 05:47:55