Skip to main content

Manage InterSystems IRIS Instances: The iris Command

You can install and run multiple instances of InterSystems IRIS® data platform on a single host system. Each instance is a unique, independent InterSystems IRIS environment.

Options for Managing an Instance

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:

  • The Windows launcher

    Each InterSystems IRIS instance installed on a Windows system has its own launcher in the system tray, which among other options lets you:

    • Connect to the instance by opening the Management Portal or the Terminal.

    • Start, stop and restart the instance.

    • Display the documentation.

    From the launcher, you can also manage multiple remote InterSystems IRIS instances, including but not limited to, running remote backups, editing configuration settings, and creating and compiling remote objects and routines. See Connecting to Remote Servers for more detailed information.

  • The iris command

    Executing the iris command on the operating system command line gives you management access to an InterSystems IRIS instance, which among other options lets you:

    • Connect to the instance using the ObjectScript shell.

    • Start, stop, and restart the instance.

    • Display information about the instance, and about other instances installed on the system.

    The iris command is described in detail in Connecting to an InterSystems IRIS Instance and Controlling an InterSystems IRIS Instance.

    To use the iris command on a remote server, use a Telnet or SSH client; to use it with a containerized instance, use it inside the container, or use the docker exec command to run it from outside the container.

Connecting to an Instance

This section describes how to connect to an instance and have access to it via a shell, specifically the ObjectScript shell. You can use this shell in any namespace of an InterSystems IRIS instance. The ObjectScript shell is often called the Terminal, although the Terminal is actually a Windows application that provides this shell. To open this shell for a running instance, use the command iris terminal instname, where instname is the name you gave the instance at installation. A containerized instance is typically named IRIS.

Note:

See Using The TerminalOpens in a new tab (video) on the InterSystems online learning website.

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.

When using the docker exec command to open the Terminal for a containerized instance (as described in Interact Using the InterSystems Terminal), you are automatically logged in as irisowner and do not need to authenticate.

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 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 function.

Important:

The iris help command displays all the command functions and arguments; the file IRISHelp.html is in the install-dir\Help directory. Some functions of the iris command are not listed in this document, but are shown in the help display.

The iris command behaves differently depending on the platform, and is described in the following tables:

The iris Command on Unix®, Linux, and macOS

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 when you want to shut the instance down without having to confirm the command.

iris all

Lists summary information for all installed instances, one instance per line, as described below.

Note:

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 console instname [arguments]

Opens the ObjectScript shell command window.

Arguments: same arguments as iris terminal.

iris force instname

Forces down the instance.

iris help [arguments]

Displays the most recent information about the iris command.

Arguments: start, stop, force — Display function-specific help for the start, stop, and force functions.

iris list [arguments]

Displays information about the installed InterSystems IRIS instances, as described below.

Arguments: instname — Optionally specify an InterSystems IRIS instance name to display only information about that instance. For example, iris list MyIRIS displays only information about the MyIRIS instance.

iris mdx instname

Provides direct terminal access to the MDX shell by running ##class(%DeepSee.Shell).%Go().

iris merge instname [arguments]

Applies a configuration merge file to the instance, updating its CPF (see Automating Configuration of InterSystems IRIS with Configuration Merge).

Arguments: [merge-file], [target-CPF] — You can optionally specify the location of the merge file to apply, the location of the target CPF (the active CPF for the instance), or both. For example, iris merge MyIRIS /tmp/merge.cpf /net/home/MyIRIS applies the merge file /tmp/merge.cpf to the instance named MyIRIS, the active CPF of which is in /net/home/MyIRIS. If the merge file and/or target CPF are not specified, environment variables are used if they exist; for more information, see How do I reconfigure an existing instance using configuration merge?

iris python instname

Provides direct terminal access to the Python shell by running ##class(%SYS.Python).Shell().

Note:

For this command to work you must install Python as described in Using Embedded Python.

iris qall

Lists the same information for each instance as iris all, except that long lines are truncated to 78 characters plus a terminating tilde (~).

iris qlist [arguments]

Similar to iris list, but with additional information. The output for each instance (described below) is given on a single line, with fields separated by carets (^).

Arguments: instname — Optionally specify an InterSystems IRIS instance name to display only information about that instance. For example, iris qlist MyIRIS displays only information about the MyIRIS instance.

iris rename instname newname

Renames the instance.

iris restart instname [arguments]

Restarts the instance; equivalent of iris stop instname restart

Arguments: nofailover — Specify this optional argument to prevent triggering a mirror failover.

iris sql instname

Provides direct terminal access to the SQL shell by running ##class(%SQL.Shell).%Go()

iris start instname [arguments]

Starts the instance.

Note:

You may be prompted to start in Emergency Mode; if so, see Emergency Access for more information.

Arguments:

  • full CPF path — By default, InterSystems IRIS reads certain settings from the iris.cpf file located in the <install-dir>/mgr directory. You may provide the full path to a different .cpf file to use instead.

  • nostu — Starts the specified instance without running ^STU.

iris stat instname

Retrieves the same system statistics as the irisstat utility (see Monitoring InterSystems IRIS Using the irisstat Utility).

iris stop instname [arguments]

Shuts down the instance.

Arguments:

  • restart — Starts the instance after shutting it down.

  • nofailover — Specify this optional argument to prevent triggering a mirror failover.

  • quietly — As the final argument, shuts down the instance without requiring confirmation. (Can also be used to run other iris commands noninteractively.)

iris stopnoshut instname [arguments]

Shuts down the named instance without running user shutdown routines, by running INTNOSHUT^SHUTDOWN.

Note:

Only the instance owner and irisusr can run INTNOSHUT^SHUTDOWN without logging in to the Terminal.

Arguments: nofailover — Specify this optional argument to prevent triggering a mirror failover.

iris terminal instname [arguments]

Opens the ObjectScript shell for the instance.

Arguments:

  • -B — Enables system administrator emergency login (see Administrator Terminal Session).

  • -b partition_size — Specifies the maximum partition size (in KB) for the process.

  • "[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.

    Note:

    Whitespace and shell meta characters must be quoted in an operating-system dependent form.

  • -U namespace — Specifies the login namespace.

    Note:

    The -U argument has no effect if you are starting InterSystems IRIS with a user account whose Startup Namespace is specified (see User Account Properties).

The iris Command on Windows

On Windows, you must run the iris command from the install-dir\bin directory (or include the full path with the command).

iris all

Lists summary information for all installed instances, one instance per line, as described below.

Note:

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 console instname [arguments]

Opens the ObjectScript shell command window.

Arguments: Same arguments as iris terminal.

iris force instname

Forces down the instance.

iris help

Displays the most recent information about the iris command.

iris list [arguments]

Displays information about the installed InterSystems IRIS instances, as described below.

Arguments: instname — Optionally specify an InterSystems IRIS instance name to display only information about that instance. For example, iris list MyIRIS displays only information about the MyIRIS instance.

iris merge instname [arguments]

Applies a configuration merge file to the instance, updating its CPF (see Automating Configuration of InterSystems IRIS with Configuration Merge).

Arguments: [merge-file], [target-CPF] — You can optionally specify the location of the merge file to apply, the location of the target CPF (the active CPF for the instance), or both. If the merge file and/or target CPF are not specified, environment variables are used if they exist; for more information, see How do I reconfigure an existing instance using configuration merge?

iris qlist [arguments]

Similar to iris list, but with additional information. The output for each instance (described below) is given on a single line, with fields separated by carets (^).

Arguments: instname — Optionally specify an InterSystems IRIS instance name to display only information about that instance. For example, iris qlist MyIRIS displays only information about the MyIRIS instance.

iris restart instname [arguments]

Starts the instance after shutting it down.

Arguments: /nofailover — Specify this optional argument to prevent triggering a mirror failover.

iris run instname [arguments]

Runs InterSystems IRIS in programmer mode with no input/output device for $Principal.

Arguments: Same arguments as iris terminal.

iris runw instname routine [arguments]

Runs the named InterSystems IRIS routine in application mode with no input/output device for $Principal. When run from a batch script, the command waits for the InterSystems IRIS process to terminate before returning the exit code from the process.

Arguments: namespace — Runs the routine in the specified namespace.

Note:

The namespace argument has no effect if you are starting InterSystems IRIS with a user account whose Startup Namespace is specified (see User Account Properties).

iris start instname [arguments]

Starts the instance.

Note:

You may be prompted to start in “Emergency Mode;” if so, see Handling Emergency Situations in the Encryption Guide for more information.

Arguments: full CPF path — By default, InterSystems IRIS reads certain settings from the iris.cpf file located in the <install-dir>/mgr directory. You may provide the full path to a different .cpf file to use instead.

iris startnostu instname

Starts the specified instance without running ^STU.

iris stop instname [arguments]

Shuts down the instance.

Arguments: /nofailover — Specify this optional argument to prevent triggering a mirror failover.

iris stopnoshut instname [arguments]

Shuts down the named instance without running user shutdown routines, by running INTNOSHUT^SHUTDOWN.

Note:

Only the instance owner and irisusr can run INTNOSHUT^SHUTDOWN without logging in to the Terminal.

Arguments: /nofailover — Specify this optional argument to prevent triggering a mirror failover.

iris stopstart instname [arguments]

Starts the instance after shutting it down.

Arguments: /nofailover — Specify this optional argument to prevent triggering a mirror failover.

iris terminal instname [arguments]

Opens the InterSystems Terminal (formally the ObjectScript shell) for the instance.

Arguments:

  • routine — Runs the named InterSystems IRIS routine in application mode in the Terminal for $Principal.

  • "[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.

    Note:

    Whitespace and shell meta characters must be quoted in an operating-system dependent form.

  • namespace — Used with routine, runs the routine in the indicated namespace.

    Note:

    The namespace has no effect if you are starting InterSystems IRIS with a user account whose Startup Namespace is specified (see User Account Properties).

iris list, qlist, and all

This topic describes contains additional details about some of the iris functions.

iris all

Lists the following information about one or more InterSystems IRIS instance:

  • Instance status, as follows

    • <blank> (status unavailable, logins disabled)

    • dn (down or has crashed)

    • up (running)

    • st (starting or stopping)

  • Instance name

  • Product version

  • Superserver port number

  • Installation directory

iris list

Lists the following information about one or more InterSystems IRIS instances:

iris qlist

Outputs the following information on a single line, separated by carets (^), for one or more InterSystems IRIS instance:

  1. Instance name

  2. Installation directory

  3. Product version

  4. Instance status

  5. Pathname of the current Configuration Parameter File, relative to the installation directory. Windows systems instead show the full path.

  6. Superserver port number

  7. Web server port number

  8. JDBC Gateway port number

  9. Instance’s system health state, if running (always blank on Windows)

  10. Product name

  11. Mirror member type (if a mirror member)

  12. Mirror status (if a mirror member)

  13. Data directory—This phrase refers to the directory that stores the persistent data for the instance (specifically the mgr and other directories). For an instance installed from a kit, this is the same as the installation directory. For a container-based instance, see Durable %SYS for Persistent Instance Data.

  14. List of superserver port numbers

Configuring Multiple 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:

  • Installing multiple instances is limited by components where only one exists on a system. For example, typically there is only one web server on a system; and as such, the InterSystems IRIS installation configures the Web Gateway for the most recent installation. InterSystems IRIS client components stored in the registry encounter the same issue. InterSystems IRIS stores its ODBC driver in the registry using one name for each. Currently, the last installation updates these components to point to the last instance installed.

    InterSystems makes an effort to move common components to a common directory that can be shared across InterSystems IRIS instances.

  • 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 InterSystems IRIS 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).

  • Additional consideration should be given for routing requests to specific instances when multiple instances are configured. For details on this, see Target Applications on Multiple InterSystems IRIS Servers.

  • Each instance must have unique port numbers. See the next section for information on how to Set Port Numbers.

Set Port Numbers

For a standard, single instance of InterSystems IRIS, the superserver port number is 1972 by default. For multiple instances of InterSystems IRIS on a single machine, each must have a unique superserver port number. During installation, subsequent instances are assigned a port if you choose to set it automatically, or you can manually enter port numbers during the installation.

You most likely do not need to change the superserver port numbers because of the way the InterSystems IRIS installation assigns them. 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.

You do need to assign each instance a unique Telnet port number. You can change the 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.

FeedbackOpens in a new tab