第四十二章 使用多个 IRIS 实例（二）

控制 IRIS 实例

iris 命令支持终端以外的许多功能，并以 iris function instname arguments 格式调用，其中 instname 是在安装期间选择的实例名称，参数取决于函数。

重要提示： iris help 命令显示所有命令函数和参数； IRISHelp.html 文件位于 install-dir\Help 目录中。 iris 命令的某些功能在本文档中没有列出，但在帮助显示中显示。

C:\InterSystems\IRISHealth\bin>iris help
usage:
       iris start <instance> [<cpf_file>]
           to start instance <instance>, optionally using the specified .cpf file.

           An optional /EmergencyId=Username,Password can be used to start
           InterSystems IRIS in emergency mode.  When the EmergencyId argument
           is supplied, the system starts up in emergency mode in which only the
           baseline databases are mounted and access to InterSystems IRIS is
           governed by InterSystems IRIS login using that username and password.
           Emergency mode is supplied to give access in the event that privileged
           users are not available or their password is forgotten.  Emergency
           startup is only available from an administrator account.

           When InterSystems IRIS is started in emergency mode, the IRIS control
           service is not used. This means that if you log out of Windows, all
           the InterSystems IRIS processes will immediately exit.

   or: iris startnostu <instance>
           to start instance <instance> without running ^STU.

   or: iris stop <instance>
           to shut down instance <instance>.

   or: iris stopnoshut <instance>
           to shut down instance <instance> without running user shutdown routines.

   or: iris stopstart <instance>
           to shut down and restart instance <instance>.

Note:  An optional /nofailover argument can be specified for stop,
       stopnoshut, or stopstart to not trigger a mirror failover.

   or: iris force <instance>
           to force down instance <instance>.

   or: iris [ run OR console OR terminal ] <instance>
           to run InterSystems IRIS in programmer mode with
           [ no-device OR console OR terminal ] for $Principal.

   or: iris [ run OR console OR terminal ] <instance> <Rou>
           to run InterSystems IRIS routine <Rou> in application mode with
           [ no-device OR console OR terminal ] for $Principal.

   or: iris [ run OR console OR terminal ] <instance> <Rou> <namespace>
           to run InterSystems IRIS routine <Rou> in <namespace> in application
           mode with [ no-device OR console OR terminal ] for $Principal.

   or: iris runw <instance> <Rou> [<namespace>]
           to run InterSystems IRIS routine <Rou> in application mode with
           no input/output device for $Principal using the optional namespace.
       When run from a batch script, iris will wait for the InterSystems IRIS
       process to terminate before returning. The exit code from the InterSystems
       IRIS process will be returned by iris.

Note:  An optional /Title="Title string" can specify the console
       or terminal title bar text.

   or: iris iristraystart <instance>
           to start IRISTray for instance <instance>.

   or: iris iristraystop <instance>
           to stop IRISTray for instance <instance>.

   or: iris licmanagerstop <instance>
           to stop licmanager running in instance <instance>.

   or: iris all [> outputfile]
           to list all installed instances.

   or: iris allw [> outputfile]
           to list (wide format) all installed instances.

   or: iris list [<instance>] [> outputfile]
           to list information about all installed instances or the
           specified instance.

   or: iris qlist [<instance>] [> outputfile]
           to display a quick list of information about all installed
           instances or the specified instance, in a format suitable
           for parsing in command scripts.
   The record for an instance contains fields separated by "^" (carats):
           Field 1: instance name
           Field 2: instance directory
           Field 3: version identifier
           Field 4: current status for the instance
           Field 5: configuration file name last used
           Field 6: SuperServer port number
           Field 7: WebServer port number
           Field 8: JDBC Gateway port number
           Field 9: Instance status (e.g., ok, warn, alert)
           Field 10: Product name of the instance
           Field 11: Mirror Member Type (e.g., Failover, Disaster Recovery)
           Field 12: Mirror Status (e.g., Primary, Backup, Connected)

   or: iris serverlist [> outputfile]
           to list information about all defined servers.

Note:  When  [> outputfile] is present, output is redirected
       to the file instead of being displayed on the terminal.

   or: iris telnetstop <instance>
           to stop the InterSystems IRIS TELNET daemon.

   or: iris telnettrace <instance>
           to toggle the TELNET trace state.

   or: iris iristrmdstop <instance>
           to stop the InterSystems IRIS terminal daemon.

Note:  iris often displays error information in a message box.
       You can suppress the message box containing error information
       by adding "quietly" (without the quotation marks) as the
       final argument to the iris command.

   or: iris help [display]
           to show this help. If display is specified the help
           is displayed in a browser window.

IRISHelp.html

IRIS.EXE USAGE:



            iris start <instance name> [<full path and file name of .cpf file>]

                        Starts InterSystems IRIS instance <instance name>, optionally using the specified .cpf file.



            Note:   An optional /EmergencyId=Username,Password can be used

                        to start InterSystems IRIS in emergency mode.  When the EmergencyId

argument is supplied, the system starts up in emergency mode in which

only the baseline databases are mounted and access to InterSystems IRIS is governed

by InterSystems IRIS login using that username and password.  Emergency mode is supplied

to give access in the event that privileged users are not available or their password

is forgotten.  Emergency startup is only available from an administrator account.


When InterSystems IRIS is started in emergency mode, the IRIS control service is not used.  

This means that if you log out of Windows, all the InterSystems IRIS processes will immediately exit.



            iris startnostu <instance name>

                        Starts instance <instance name> without running ^STU.



            iris stop <instance name>

                        Shuts down instance <instance name>.



            iris stopnoshut <instance name>.

            Shuts down instance <instance name> without running user shutdown routines.



            iris stopstart <instance name>

                        Shuts down and restarts instance <instance name>.



            Note:  An optional /nofailover argument can be specified for stop, stopnoshut,

                        or stopstart.  Specifying this option prevents triggering a mirror failover.



            iris force <instance name>

                        Forces down instance <instance name>.



            iris [ run OR console OR terminal ] <instance name>

                        Runs InterSystems IRIS in programmer mode with

                        [ no-device OR console OR terminal ] for $Principal.



            iris [ run OR console OR terminal ] <instance name> <Rou>

                        Runs InterSystems IRIS routine <Rou> in application mode with

                        [ no-device OR console OR terminal ] for $Principal.



            iris [ run OR console OR terminal ] <instance name> <Rou> <namespace>

                        Runs InterSystems IRIS routine <Rou> in <namespace> in application mode with

                        [ no-device OR console OR terminal ] for $Principal.



      iris runw <instance> <Rou> [<namespace>]

                        Runs InterSystems IRIS routine <Rou> in application mode with

                        no input/output device for $Principal using the optional namespace.

                        When run from a batch script, iris will wait for the InterSystems IRIS process to

                        terminate before returning.  The exit code from the InterSystems IRIS process will be

                        returned by iris.



            Note:  An optional /Title=”Title string” can specify the console

                        or terminal title bar text.



            Examples:



                        Run ^%SS in a console in the i181u instance:



                        iris console i181u ^^%SS



                        Run ^%SS in an InterSystems IRIS terminal in the i181u instance:



iris terminal i181u ^^%SS



Start ^%SS running in an InterSystems IRIS terminal in the i181u instance from a batch file (extra % required):



iris terminal i181u ^^%%SS



Run sub^test(“hello”) in an InterSystems IRIS terminal in the USER namespace of the IRIS instance i181u:



iris terminal i181u sub^^test(\"hello\")  USER



Note:  The namespace parameter only works if the login record for the user does not specify a namespace. If the user security record specifies a namespace, then it will override the namespace parameter.



            iris iristraystart <instance name>

                       Starts IRISTray for instance <instance name>.



            iris iristraystop <instance name>

                        Stops IRISTray for instance <instance name>.



            iris licmanagerstop <instance name>

                        Stops the licmanager process running in instance <instance name>.



            iris all [> outputfile]

                        Lists all installed instances.



The status for each instance is indicated by:

                "dn" - InterSystems IRIS instance is not running

                "st" -  InterSystems IRIS instance is starting or stopping.

                "up" - InterSystems IRIS instance is running on this machine

                "  " - (blank) status unavailable.  Instance is probably partly up without ^STU completing.  Logins are disabled.



            iris allw [> outputfile]

                        Lists all installed instances in wide format.



            iris list [<instance>] [> outputfile]

                        Lists brief information about all installed instances, or the specified instance.



The status for each instance is indicated by:

                "down" - InterSystems IRIS instance is not running

                "starting or stopping" -  InterSystems IRIS instance is starting or stopping.

                "running" - InterSystems IRIS instance is running on this machine

                "Incomplete start or stop, logins disabled"  " - Instance is probably partly up without ^STU completing.  Logins are disabled.



            iris qlist [<instance>] [> outputfile]

                        Display a quick list of information about all installed instances, or the specified instance, in a format suitable for parsing in command scripts.

                        The record for an instance contains fields separated by "^" (carats):

                               Field 1: instance name

                               Field 2: instance directory

                               Field 3: version identifier

                               Field 4: current status for the instance

                               Field 5: configuration file name last used

                               Field 6: SuperServer port number

                               Field 7: WebServer port number

                               Field 8: JDBC Gateway port number

                               Field 9: Instance status (e.g., ok, warn, alert)

                               Field 10: Product name of the instance

                               Field 11: Mirror Member Type (e.g., Failover, Disaster Recovery)

                               Field 12: Mirror Status (e.g., Primary, Backup, Connected)



            iris serverlist [> outputfile]

                        Lists information about all defined servers.



            Note:   When [> outputfile] is present, output is redirected to the file

                        instead of being displayed on the terminal.



iris telnetstop <instance name>

                        Stops the InterSystems IRIS TELNET daemon.



iris iristrmdstop <instance name>

                        Stops the InterSystems IRIS terminal daemon.



            iris help [display]

                        Writes the help text to the terminal or, if display is specified,

                        displays the help in a browser window.



            Error reporting:



            Return value:  If the control command succeeds, it returns 0.  Otherwise it usually returns 1 or some other

non-zero value to indicate an error.  You can check the return value by inspecting the ErrorLevel environment

variable.



Message box:  iris often displays error information in a message box.

You can suppress the message box containing error information by adding “quietly”

(without the quotation marks) as the final argument to the iris command.

This may be useful when running an unattended .bat script.  For example:



        iris stop xxxx quietly
        if not errorlevel 0 …

iris 命令的行为因平台而异，如下表所述：

Unix®、Linux 和 macOS 上的 iris 命令

注意： iris 命令通常会在消息框中显示错误信息。可以通过安静地添加作为 iris 命令的最后一个参数来抑制此消息框，该命令以非交互方式运行该命令，并带有最少的对话框。此参数对其他命令也很有用，例如当想要关闭实例而无需确认命令时。

• iris all 列出所有已安装实例的摘要信息，每行一个实例，如下所述。

C:\InterSystems\IRISHealth\bin>iris all
    Instance          Version ID        Port   Directory
    -------------     ----------        ----   ---------
up  irishealth        2022.1.0.114.0    51773  c:\intersystems\irishealth

注意：如果需要完整的信息，例如用于解析或报告目的，请使用 iris list。

C:\InterSystems\IRISHealth\bin>iris list
Instance 'IRISHealth'   (Custom installation)
        directory: 'C:\InterSystems\IRISHealth'
        versionid: '2022.1.0.114.0'
        conf file: 'c:\intersystems\irishealth\iris.cpf'  (SuperServer port = 51773, WebServer port = 52773)
        status   : 'running, since Sun Sep  4 16:16:54 2022'
        Product  : InterSystems IRISHealth

• iris allw 为每个实例列出与 iris all 相同的信息，而不包含长字段值。可能会产生超过 80 个字符的行。

C:\InterSystems\IRISHealth\bin>iris allw
    Instance Name                   Version ID                   Port   Directory
    ------------------------------- ---------------------------- -----  --------------------------------
up  irishealth                      2022.1.0.114.0               51773  c:\intersystems\irishealth

• iris console instname [arguments] 在操作系统命令窗口而不是Terminal 窗口中打开 Terminal 。同 iris terminal

• iris force instname 强制关闭实例。

C:\InterSystems\IRISHealth\bin>iris force irishealth

• iris help [参数] 显示有关 iris 命令的最新信息。start, stop, force — 显示启动、停止和强制功能的特定功能帮助。

C:\InterSystems\IRISHealth\bin>iris help force
C:\InterSystems\IRISHealth\bin>iris help start
C:\InterSystems\IRISHealth\bin>iris help stop

• iris list [arguments] 显示有关已安装 IRIS 实例的信息，如下所述。

instname — 可以选择指定 IRIS 实例名称以仅显示有关该实例的信息。例如，iris list MyIRIS 仅显示有关 MyIRIS 实例的信息。

C:\InterSystems\IRISHealth\bin>iris list irishealth
Instance 'irishealth'   (Custom installation)
        directory: 'C:\InterSystems\IRISHealth'
        versionid: '2022.1.0.114.0'
        conf file: 'c:\intersystems\irishealth\iris.cpf'  (SuperServer port = 51773, WebServer port = 52773)
        status   : 'running, since Sun Sep  4 16:16:54 2022'
        Product  : InterSystems IRISHealth

• iris merge instname [arguments] 将配置合并文件应用于实例，更新其 CPF（请参阅使用配置合并自动配置 IRIS）。

merge-file [existing-CPF] — 可以指定要应用的合并文件的位置，可以选择后跟目标 CPF 的位置。例如，iris merge MyIRIS /tmp/merge.cpf 将合并文件 /tmp/merge.cpf 应用于名为 MyIRIS 的实例。如果不带参数调用，则使用以下默认值：

• 对于合并文件，默认值是 ISC_CPF_MERGE_FILE 环境变量的值。

• 对于现有的 CPF，默认是位于以下位置的 iris.cpf 文件:

  • 对于已安装的实例，安装目录。
  • 对于容器，由 ISC_DATA_DIRECTORY 环境变量指定的目录；如果未使用持久 %SYS 和 ISC_DATA_DIRECTORY，则使用 ISC_PACKAGE_INSTALLDIR 环境变量指定的目录。

• iris qall 为每个实例列出与 iris all 相同的信息，除了长行被截断为 78 个字符外加一个终止波浪号 (~)。

C:\InterSystems\IRISHealth\bin>iris qall

• iris qlist [参数] 与 iris list 类似，但有附加信息。每个实例的输出（如下所述）在一行中给出，字段由插入符号 (^) 分隔。

instname — 可以选择指定 IRIS 实例名称以仅显示有关该实例的信息。例如，iris qlist MyIRIS 仅显示有关 MyIRIS 实例的信息。

C:\InterSystems\IRISHealth\bin>iris qlist irishealth
irishealth^C:\InterSystems\IRISHealth^2022.1.0.114.0^running, since Sun Sep  4 16:16:54 2022^c:\intersystems\irishealth\iris.cpf^51773^52773^^^IRISHealth^^

• iris rename instname newname 重命名实例。
• iris restart instname [参数] 重启实例；相当于 iris stop instname restart

nofailover — 指定此可选参数以防止触发镜像故障转移。

• iris start instname [参数] 启动实例。

注意：系统可能会提示以“紧急模式”启动；如果是这样，请参阅紧急访问了解更多信息。

完整的CPF 路径 — 默认情况下， IRIS 从位于 <install-dir>/mgr 目录中的 iris.cpf 文件中读取某些设置。可以提供另一个 .cpf 文件的完整路径以供使用。 nostu — 启动指定的实例而不运行 ^STU。

• iris stat instname 检索与 irisstat 实用程序相同的系统统计信息。
• iris stop instname [参数] 关闭实例。

restart — 关闭实例后启动实例。 nofailover — 指定此可选参数以防止触发镜像故障转移。

• iris stopnoshut instname [参数] 使用 INTNOSHUT^SHUTDOWN 关闭命名实例。

注意：只有实例所有者和 irisusr 可以在不登录终端的情况下运行 INTNOSHUT^SHUTDOWN。

nofailover — 指定此可选参数以防止触发镜像故障转移。

• iris terminal instname [参数] 打开实例的 Terminal 。

B — 允许系统管理员紧急登录终端。 -b partition_size — 指定进程的最大分区大小（以 KB 为单位）。 "[label[+offset]]^routine" — 指定要在用户模式下运行的 ObjectScript 程序的名称。除了指定的格式之外，还可以传递由字符串和/或数字文字组成的参数列表，以及省略的 (void) 参数，如下所示：
- "routine[([parameter-list])]"
- "[label]^routine[([parameter-list])]"
- "##CLASS(package.class).method[([parameter-list])]"

其中，例如，参数列表以“字符串文字”的形式指定，-+-000123.45600E+07，省略的参数作为 $Data(parameter)=0 传递给目标。

注意：空格和 shell 元字符必须以依赖于操作系统的形式引用。

U 命名空间 — 指定终端登录命名空间。

注意：如果使用指定了启动命名空间的用户帐户启动 IRIS，则 -U 参数无效（请参阅用户帐户属性）。