Skip to main content

Controlling an InterSystems IRIS Instance

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

Command and Description Arguments
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 InterSystems Terminal in an operating system command window rather than a Terminal window.
Same arguments as iris terminal.
iris force instname
Forces down the instance.
 
iris help [arguments]
Displays the most recent information about the iris command.
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.
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 Using Configuration Merge to Deploy and Reconfigure InterSystems IRIS).
merge-file [existing-CPF] — You may specify the location of the merge file to apply, optionally followed by location of the target CPF. For example, iris merge MyIRIS /tmp/merge.cpf applies the merge file /tmp/merge.cpf to the instance named MyIRIS.
If called without arguments, the following default values are used:
  • For merge-file, the default is the value of the ISC_CPF_MERGE_FILE environment variable.
  • For existing-CPF, the default is the iris.cpf file in the following location:
    • For installed instances, the installation directory.
    • For containers, the directory specified by the ISC_DATA_DIRECTORY environment variable; if durable %SYS and ISC_DATA_DIRECTORY are not in use, then the directory specified by the ISC_PACKAGE_INSTALLDIR environment variable.
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 (^).
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 start instname [arguments]
Starts the instance.
Note:
You may be prompted to start in “Emergency Mode;” if so, see Emergency Access for more information.
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 the appendix “Monitoring InterSystems IRIS Using the irisstat Utility” in the Monitoring Guide).
 
iris stop instname [arguments]
Shuts down the instance.
restart — Starts the instance after shutting it down.
nofailover — Specify this optional argument to prevent triggering a mirror failover.
iris stopnoshut instname [arguments]
Shuts down the named instance using INTNOSHUT^SHUTDOWN.
Note:
Only the instance owner and irisusr can run INTNOSHUT^SHUTDOWN without logging into the Terminal.
nofailover — Specify this optional argument to prevent triggering a mirror failover.
iris terminal instname [arguments]
Opens the InterSystems Terminal for the instance.
-B — Enables system administrator emergency login to the Terminal (see Administrator Terminal Session in the “Licensing” chapter).
-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 Terminal 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).

Command and Description Arguments
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 InterSystems Terminal in an operating system command window rather than a Terminal window.
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.
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 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 (^).
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 run instname [arguments]
Runs InterSystems IRIS in programmer mode with no input/output device for $Principal.
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.
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 Emergency Access in the “System Management and Security” chapter of the Security Administration Guide for more information.
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.
/nofailover — Specify this optional argument to prevent triggering a mirror failover.
iris stopnoshut instname [arguments]
Shuts down the named instance using INTNOSHUT^SHUTDOWN.
Note:
Only the instance owner and irisusr can run INTNOSHUT^SHUTDOWN without logging into the Terminal.
/nofailover — Specify this optional argument to prevent triggering a mirror failover.
iris stopstart instname [arguments]
Starts the instance after shutting it down.
/nofailover — Specify this optional argument to prevent triggering a mirror failover.
iris terminal instname [arguments]
Opens the InterSystems Terminal for the instance.
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

  • InterSystems IRIS version

  • Superserver port number

  • Installation directory

iris list

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

  • Instance name (and installation type)

  • Installation directory

  • InterSystems IRIS version

  • Pathname of InterSystems IRIS 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 System Monitor” chapter of the Monitoring Guide) (not included on Windows)

  • Mirror member type and status (if a mirror member) (see %SYSTEM.Mirror.GetMemberType() and %SYSTEM.Mirror.GetMemberStatus())

iris qlist

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

  1. Instance name (and installation type)

  2. Installation directory

  3. InterSystems IRIS 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. Webserver 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 (if applicable)

Feedback