第十七章 TCP 客户端 服务器通信 - 使用OPEN命令

使用OPEN命令

OPEN命令保留一个TCP绑定设备供使用。其语法为：

OPEN devicename:parameters:timeout:mnespace

• devicename - 一个|TCP|格式的字符串，后面跟着一些数字数字。设备名称的数字部分称为设备标识符。如果OPEN参数中没有指定端口号，则该设备标识符必须是唯一的5位TCP端口号。如果在OPEN参数中指定了端口号(这是首选的实践)，这个设备标识符可以是任何唯一的数字(最多2147483647)，只要单个作业使用的所有TCP设备名称是不同的。

• parameters - 可选-一系列一个或多个设备参数，用括号括起来，用冒号(：)分隔。如果省略了某个参数，请为缺少的参数指定冒号分隔符。(对于服务器端OPEN，始终省略第一个参数。)。具体参数说明如下。

  如果只指定第一个参数(hostname)，可以省略括号。例如客户端open: open "|TCP|7000":"127.0.0.1":10。如果不指定参数，则可以省略圆括号，但必须保留冒号作为分隔符。例如:服务器端open: open "|TCP|7000"::10。

• timeout - 可选- IRIS尝试打开TCP设备的最大秒数。如果在此间隔内没有成功，它会将$TEST设置为0，并将控制权返回给进程。如果成功，它会将$TEST设置为1。在来自客户端的OPEN命令中包含超时可防止客户端系统在服务器忙于处理另一个客户端时尝试打开连接时挂起。服务器一次只能打开一个连接。

• mnespace - 可选-支持所有的对象脚本OPEN命令。没有用于TCP绑定的预定义助记符空间。

如果省略开放参数，则可以通过指定冒号分隔符来指示其缺失。

尽管TIMEOUT参数是可选的，但强烈建议使用它，因为打开的成功或失败由$TEST特殊变量的值指示，并且只有在指定了TIMEOUT的情况下才会设置$TEST。如果在超时到期之前打开尝试成功，则$TEST设置为1；如果超时到期，则$TEST设置为0。

如果Windows系统上的tcp连接尝试失败，则tcp连接错误将被写入IRIS系统错误日志，例如，错误代码10061=WSAECONNREFUSED。

以下是客户端打开的示例，其中7000是端口号，"127.0.0.1"是parameters参数(主机名，指定为IPv4地址)：

  SET dev="|TCP|7000"
  OPEN dev:("127.0.0.1":7000)

hostname 参数

客户端OPEN需要HostName参数。客户端参数可以只是主机名，也可以是主机名后跟其他冒号分隔的参数。如果仅指定主机名参数，则可以省略参数圆括号。

服务器端参数省略了主机名。

主机名可以是IP主机的名称(来自本地系统的远程主机数据库)，也可以是IPv4或IPv6协议格式的IP地址。由于这些协议不兼容，服务器和客户端必须使用相同的Internet协议，否则传输将失败。

IPv4地址具有以下格式。N是介于0到255之间的十进制整数：

n.n.n.n

IPv6地址的完整格式如下。H是具有四个十六进制数字的十六进制数：

h:h:h:h:h:h:h:h

通常，IPv6地址的缩写方式是消除前导零并用双冒号(::)替换连续的零部分；IPv6地址中只能使用一个双冒号。通过使用IPv4缩写规则，可以将IPv6环回地址指定为"::1"(这意味着前七个连续的h部分都具有值0000，并且第八个部分中的前导零被删除)。

可以使用OPEN关键字/USEIPV6来指定要使用的协议。

第十六章 TCP 客户端/服务器通信

TCP 客户端/服务器通信

本章介绍如何使用 TCP/IP 在 IRIS 数据平台进程之间设置远程通信。

IRIS 支持两种互联网协议 (IP)：TCP 和 UDP。这些 Internet 协议允许 IRIS 进程与本地或远程系统上的进程通信，无论这些进程是否正在运行 IRIS。

• TCP IRIS 传输控制协议 (TCP) 绑定。在服务器和单个客户端之间建立双向连接。提供具有错误检查和纠正以及消息确认的可靠字节流数据传输。
• UDP IRIS 用户数据报协议 (UDP) 绑定。提供服务器和大量客户端之间的双向消息传输。 UDP 不是基于连接的；每次传输数据包都是一个独立的事件。为本地数据包广播和远程多播提供快速和轻量级的数据传输。本质上不如 TCP 可靠。不提供消息确认。

TCP 绑定将 IRIS 连接到广泛的网络标准，这样 IRIS 用户就可以通过 I/O 命令使用底层网络协议的基本功能。

TCP/IP 协议允许系统进行通信，即使它们使用不同类型的网络硬件。例如，TCP 通过 Internet 连接在使用以太网的系统和使用令牌环的另一个系统之间传输消息。 TCP 控制数据传输的准确性。 IP 或 Internet 协议在网络或 Internet 上的不同系统之间执行实际数据传输。

使用 TCP 绑定，可以创建客户端-服务器系统的客户端和服务器部分。在客户端-服务器类型的分布式数据库系统中，一个或多个客户端系统上的用户可以处理存储在另一个系统（称为服务器）上的数据库中的信息。

TCP 连接概述

要在系统之间创建客户端-服务器关系，必须遵循一组特定的约定：

• 系统必须与适当的网络硬件和软件连接，包括 TCP/IP 协议软件。
• 系统通过 TCP 端口相互通信。连接两端的进程必须使用相同的端口号。
• 指定 TCP 端口号或代表它的设备的设备名称，作为 IRISOPEN、USE 和 CLOSE 命令中的设备。

使用这些约定，建立 TCP 绑定连接的一般过程是：

1. 服务器进程向 TCP 设备发出 OPEN 命令。
2. 服务器进程发出一个 USE 命令，然后是一个 READ 命令，等待来自客户端进程的输入。在客户端可以建立连接之前，服务器必须处于监听状态。当客户端打开连接并发送一些数据时，初始 READ 命令完成。可以在 OPEN 命令中包含“A”模式参数，以便在服务器接受连接后立即完成初始读取。
3. 客户端进程发出一个 OPEN 命令，指定它要连接的 TCP 设备。
4. 客户端进程发出一个USE命令，然后是一个WRITE命令来完成连接。 IRIS将WRITE命令中的所有字符复制到缓冲区。它不会将它们写入网络，直到发出write !或WRITE #命令刷新缓冲区。
5. 服务器读取客户端在其第一个 WRITE 命令中发送的字符后，双方可以继续发出 READ 和 WRITE 命令。这些命令对同一端口的顺序没有进一步限制。
6. 任何一方都可以使用 CLOSE 或 HALT 命令启动连接的关闭。最好先关闭客户端。如果服务器需要断开连接以便它可以接受来自另一个客户端进程的连接，可以改为发出 WRITE *-2 命令。

注意：此过程假定客户端和服务器都是 IRIS 进程（尽管任一进程都可以是非 IRIS 进程）。

以下部分详细介绍了如何使用 IRIS I/O 命令在客户端和服务器进程之间创建 TCP 绑定。

TCP 设备的 OPEN 命令

服务器和客户端进程都使用 ObjectScript OPEN 命令来启动连接。服务器通过发出 READ 命令完成连接，该命令接收客户端 OPEN 命令和第一个数据传输。

注意：如果在已经打开的 TCP 设备上发出 OPEN 命令，则第二个 OPEN 命令将被视为 USE 命令。即，忽略主机名和端口参数（保留第一个 OPEN 命令值）并更新模式和终止符参数。

第十五章 IRIS 进程之间的通信

本页介绍如何在两个或多个 IRIS 数据平台进程之间建立通信。

介绍

作业间通信 (IJC) 设备是一组特殊设备编号，可让在两个或多个 IRIS 进程之间传输信息。这些流程可以是作业流程或交互式流程。

IJC 设备成对工作。最多可以有 256 个 IJC 设备对。使用称为接收器的偶数设备来读取数据。使用称为发送器的奇数设备来写入数据。尝试从发送器读取或写入接收器会导致 <NODEV> 错误。

可以向 IJC 设备发出 I/O 命令，就像向任何其他设备一样。向设备发出OPEN和USE命令后，进程可以发出：

• 向接收器设备读取命令
• 将命令写入发送器设备

一次只能有一个进程可以打开设备。

对基于 IRIS 设备表中映射的相对顺序，可以使用管理门户的配置选项查看和编辑该表。

每对设备都与一个 IJC 内存缓冲区关联。当进程向任何奇数 IJC 设备发出WRITE命令时 IRIS 会将数据写入该设备对的缓冲区中。当另一个进程向该对中的偶数设备发出READ命令时 IRIS 会从同一缓冲区读取数据。

写入的数据以先进先出的方式缓冲在内存中。如果在设备为空时发生READ ，则发出该信号的进程将挂起，直到另一个进程发出相应的WRITE 信号。缓冲区已满时发生的写入将挂起，直到另一个进程从该缓冲区读取数据。

将消息写入缓冲区后，即使关闭发送器，它也会保留在那里直到被读取。多个用户可以向发射器发出OPEN 、 USE 、 WRITE和CLOSE命令，一次一个。随后的READ命令将按照写入的顺序获取所有消息。

指定作业间通信设备的内存缓冲区

系统管理员可以使用管理门户配置 IJC 缓冲区。选择“系统管理” 、 “配置” 、 “附加设置” 、 “高级内存” 。可以设置的两个参数是：

• ijcnum ：IJC 设备的最大数量。范围为 0 到 256。默认值为 16。如果编辑此设置，则必须重新启动 IRIS 才能应用更改。
• ijcbuff ：每个 IJC 缓冲区的最大大小（以字节为单位）。范围为 512 到 8192。默认大小为 512 字节。如果编辑此设置，则必须重新启动 IRIS 才能应用更改。

每个 IJC 设备对应一个 IJC 缓冲区，其大小在ijcbuff中指定。可以写入长度为ijcbuff减 1 的消息。

禁用作业间通信缓冲区

如果不使用 IJC 设备，则可以将 IJC 设备的最大数量 ( ijcnum ) 设置为 0 以避免占用内存。

作业间通信设备编号

作业间通信设备由 IRIS 自动定义编号。它们的实际标识号取决于系统上配置的 IJC 缓冲区的最大数量

下表给出了系统上可用的 IJC 设备编号范围，具体取决于分配的 IJC 缓冲区的数量。

例如，如果分配 8 个 IJC 缓冲区，则系统上将定义从 224 到 239 的设备号（偶数用于READ设备，奇数用于WRITE设备）。

再举一个例子，如果分配 94 个 IJC 缓冲区，则定义以下设备编号范围：224 到 255、64 到 199、4 到 19 以及 2048 到 2051。可以将任何偶数/奇数对与OPEN一起使用，使用、读取、写入和关闭命令。

设备编号

IJC 设备的 I/O 命令

可以对 IJC 设备使用所有标准 I/O 命令： OPEN 、 USE 、 READ 、 WRITE和CLOSE 。

OPEN命令

OPEN命令保留作业间通信设备供使用。

OPEN device::timeout

device 设备

上表中的设备编号。打开偶数设备以发出READ命令。打开奇数设备以发出WRITE命令。为了两个进程进行通信，它们必须打开一组设备对。

timeout 暂停

可选— 一个正整数，其值（以秒为单位）是 IRIS 等待OPEN完成的最长时间。如果指定 0，则 OPEN立即将控制权返回给进程。

此示例显示两个进程如何通过打开单独的设备进行读取和写入来进行通信：

Process A                          Process B 
OPEN 227 USE 227 WRITE "MSG_1"
WRITE "MSG_2"                       OPEN 226 USE 226 READ X
CLOSE 227                           CLOSE 226
OPEN 224 USE 224 READ X             WRITE X
CLOSE 224                           MSG_1
WRITE X                             .
MSG_3                               .
                                    .
                                    OPEN 225 USE 225 WRITE "MSG_3" 
                                    CLOSE 225

过程A首先打开设备227并向其写入MSG_1。 IRIS 将此消息写入设备226 和227 共享的缓冲区中。然后进程A 将第二条消息写入同一缓冲区。现在，进程B打开伴随设备226并从缓冲器读取第一消息(MSG_1)。

现在，进程 A 想要读取消息，因此它必须打开另一个设备 224。由于该设备及其同伴设备 225 的缓冲区当前为空，因此进程 A 会等待，直到进程 B 打开设备 225 并将 MSG_3 写入其中。在IRIS将该消息放入由设备224和225共享的缓冲器中之后，对设备224的READ命令成功。

第十四章 本地进程间通信（管道） - 用于进程间通信的 CLOSE 命令

用于进程间通信的 CLOSE 命令

如果使用带Q (/QUEUE) 参数代码的OPEN创建子进程，则该子进程可能会在设备上的CLOSE操作中继续存在。排队的进程间通信管道的生存能力取决于平台。在 UNIX® 系统上，子进程始终在CLOSE后继续存在。在 Windows 系统上，进程的生存取决于进程的年龄。刚刚启动的子进程不会在CLOSE操作中幸存，但是一旦子进程完全建立，它就会在 CLOSE操作中幸存。

在 UNIX® 系统上，可以指定关闭管道命令设备时CLOSE命令应等待的时间。超时默认值为 30 秒。可以通过指定OPEN命令closetimeout位置参数来修改此默认值。可以通过指定可选的“I”位置参数来覆盖CLOSE命令的默认或指定超时。 “I”参数指定立即关闭（1 秒后关闭）。 CLOSE语法如下：

CLOSE cpipename:"I"

使用命名管道与 Visual Basic 进行通信

在 Windows 上，在 IRIS 中使用命名管道就像使用 TCP 设备一样，但使用设备名称|NPIPE|nnn而不是|TCP|nnn 。 OPEN参数如下：

OPEN "|NPIPE|3":(server:pipename)

其中server是计算机名称， pipename是要连接到的管道的名称。

要连接到本地管道名，请使用“.” （引用的期间）作为服务器。要创建管道（作为服务器），请使用“” （不含内容的引号）作为服务器名称。以下是所有有效的服务器名称：

   OPEN "|NPIPE|3":(".":"localpipe")
   OPEN "|NPIPE|3":("mother":"test")
   OPEN "|NPIPE|3":("":"info")

服务器可以打开命名管道并在客户端打开同一命名管道之前立即发出写入。写操作将挂起，直到客户端打开命名管道。用户可以通过发出 Control-C 来中断挂起。

一旦打开，管道就像普通设备一样。在服务器端，客户端可以像 TCP 中一样通过以下方式断开连接：

   USE "|NPIPE|3":"DISCONNECT"

或者：

   USE "|NPIPE|3" WRITE *-2

OPEN 命令关键字

以下列表描述了仅使用OPEN命令控制命名管道的关键字。

/HOSTNAME=str

默认值：默认值为“” （空字符串），它将管道作为服务器打开。

对应于服务器位置参数，指定 Windows 计算机。当打开管道作为服务器时，不需要指定该关键字。使用”。” （带引号的句点）连接到本地管道名。

/IBUFSIZE=n

默认值：2048

指定命名管道输入缓冲区的大小，该缓冲区保存从管道接收但尚未传递到应用程序的数据。

/INSTANCES=n

默认值：1

指定命名管道允许的最大实例数。大于 1 的值允许多个服务器打开命名管道的实例，以便一次可以为多个客户端提供服务。

/OBUFSIZE=n

默认值：2048

指定操作系统使用的输出缓冲区的大小。此缓冲区大小是建议性的，因为操作系统根据系统施加的约束来调整缓冲区的大小。

/PIPENAME=str

无默认值。

对应于指定管道名称的pipelinename位置参数。

第十三章 本地进程间通信（管道） - 用于进程间通信的 READ 命令

用于进程间通信的 READ 命令

语法

READ:pc readargument,...

READ 从管道读取数据。

其中reargument可以是：

formatting-mode
string
variable:timeout
*variable:timeout
variable#n:timeout

将 I格式化模式参数与管道一起使用。 I 参数允许对命名管道发出定时READ，而不会丢失跟随在一个部分记录中的任何数据。错误。当在READ上使用此参数时， READ会忽略消息。

默认情况下，I格式化模式的值处于关闭状态。如果在没有超时的情况下在READ命令中包含此参数，则进程将挂起，直到有数据要处理。

CPIPE 退出代码

可以检索命令管道 (|CPIPE|) 进程的退出代码。必须在 |CPIPE| 之前检索此退出代码设备已关闭。它是通过%SYSTEM.Process 类的PipeExitCode方法获得的。退出代码始终是整数值。如果退出代码不可用，该方法将返回空字符串并设置状态参数和解释，如以下示例所示：

  SET exitcode=$SYSTEM.Process.PipeExitCode(device, .status)
  IF exitcode="" {DO $SYSTEM.OBJ.DisplayError(status)}
  ELSE {WRITE "CPIPE exit code is ",exitcode } 

在 UNIX® 系统上，退出代码仅适用于非 shell 命令；即，使用 /COMMAND 或 /ARGS 打开的 CPIPE 设备。

用于进程间通信的 CLOSE 命令

如果使用带Q (/QUEUE) 参数代码的OPEN创建子进程，则该子进程可能会在设备上的CLOSE操作中继续存在。排队的进程间通信管道的生存能力取决于平台。在 UNIX® 系统上，子进程始终在CLOSE后继续存在。在 Windows 系统上，进程的生存取决于进程的年龄。刚刚启动的子进程不会在CLOSE操作中幸存，但是一旦子进程完全建立，它就会在 CLOSE操作中幸存。

在 UNIX® 系统上，可以指定关闭管道命令设备时CLOSE命令应等待的时间。超时默认值为 30 秒。可以通过指定OPEN命令closetimeout位置参数来修改此默认值。可以通过指定可选的“I”位置参数来覆盖CLOSE命令的默认或指定超时。 “I”参数指定立即关闭（1 秒后关闭）。 CLOSE语法如下：

CLOSE cpipename:"I"

第十二章 本地进程间通信（管道） - OPEN 和 USE 命令关键字

OPEN 和 USE 命令关键字

以下列表描述了用于使用OPEN和USE命令控制进程间通信管道的关键字。

/IOTABLE[=name]

默认值：如果未指定名称，则使用设备的默认 I/O 转换表。

对应K\name\参数代码，为设备建立I/O转换表。

/TRANSLATE[=n]

默认值：1

与K参数代码相关。 /TRANSLATE 或 /TRANSLATE= n （对于n的非零值）启用设备的 I/O 转换。 /TRANSLATE= n如果n值为零，则会禁用设备的 I/O 转换。

/XYTABLE[=name]

默认值：如果未指定名称，则使用设备的默认 $X/$Y 操作表。

对应Y\name\参数代码，为设备建立$X/$Y动作表。

仅限 OPEN 关键字

以下列表描述了仅使用OPEN命令控制进程间通信管道的关键字。

/ENV=environmentvars

指定要在新进程中设置的环境变量。有两种指定值的方法：

• 明确地说。例如：

/ENV=(name1:value1,name2:value2)

• 通过多维数组。例如：

 Set arr(name1)=value1
 Set arr(name2)=value2

// then later use the following in the OPEN command:
  /ENV=arr...

这些示例显示了两个环境变量，但可以有任意数量。显式列表必须括在括号中。

/IGNOREEOF[=n]

默认值：0

对应于 I 参数代码，它指定应无限期地重试READ操作（忽略任何 EOF 条件）或直到指定的超时到期。 /IGNOREEOF 或 /IGNOREEOF= n （对于n的非零值）启用参数代码，/IGNOREEOF= n （对于n的零值）禁用参数代码。

/PARAMS=str

无默认值。

对应于参数代码位置参数。 （它提供了一种以位置无关的方式指定参数代码字符串的方法。）

/QUEUE

默认值：设备不被识别为进程间通信管道。

对应于Q参数代码，它指定应打开进程间通信管道。请注意，使用此命令需要%System_Callout资源的使用权限。

/Read

默认值：如果未指定 /Read 或 /Write，则默认为读取。

对应于R参数代码，它指定应打开队列或管道以接受来自另一个进程的数据。

/Write

默认值：如果未指定 /Read 或 /Write，则默认为读取。

对应于W参数代码，它指定应打开队列或管道以将数据发送到另一个进程。

第十一章 本地进程间通信（管道） - OPEN 命令管道示例

OPEN 命令管道示例

以下是有效的命令管道OPEN语句。每个示例指定 10 秒的超时：

  OPEN "|CPIPE|1":"/nethome/myprog":10                                  // using shell, no args
  OPEN "|CPIPE|1":("/nethome/myprog":/WRITE):10                         // using shell, no args, WRITE
  OPEN "|CPIPE|2":/COMMAND="/nethome/myprog":10                         // no shell, no args
  OPEN "|CPIPE|3":("":/COMMAND="/nethome/myprog"):10                    // no shell, no args
  OPEN "|CPIPE|4":(/COMMAND="/nethome/myprog":/ARGS=arg1):10            // no shell, 1 arg
  OPEN "|CPIPE|5":("/nethome/myprog":/ARGS=arg1):10                     // no shell, 1 arg
  OPEN "|CPIPE|6":("/nethome/myprog":/ARGS=arg1:/WRITE):10              // no shell, 1 arg, WRITE
  OPEN "|CPIPE|7":(/COMMAND="/nethome/myprog":/ARGS=arg1,arg2):10       // no shell, 2 args
  OPEN "|CPIPE|8":(/COMMAND="/nethome/myprog":/ARGS=args...:/WRITE):10  // no shell, args array, WRITE

在 Windows 系统上，参数可以包含空格或双引号 (") 字符。在这些情况下，可以将参数加引号，并且可以通过加倍来转义文字双引号字符：

  OPEN "|CPIPE|9":("/nethome/myprog":/ARGS="string with blanks"):10
  OPEN "|CPIPE|10":("/nethome/myprog":/ARGS="string with literal "" character"):10

OPEN Errors

如果对非 IPC 设备发出带有QW参数的OPEN命令，当您尝试写入此设备时发生错误。

以下 UNIX® 示例打开一个到 lp 程序的输出管道，在本例中该程序的路径名为/usr/bin/lp 。然后它通过此管道将全局^TEXT的输出发送到打印机。

print ; Send the first layer of global ^TEXT to the printer. 
      SET IO="/usr/bin/lp"
      OPEN IO:"QW"   ; Open the pipe to lp 
      USE IO WRITE "The first layer of ^TEXT",!   ; Print the title 
      ;  . . .
      ;  Print each line, using $ORDER on the global ^TEXT
      USE IO WRITE !,"The End.",#
      CLOSE IO    ; close the pipe, spooling the file to lpsched 
      QUIT

可以更改此示例，以便OPEN命令将参数传递给 lp 程序。例如，要指定lp应将输出发送到名为 Laserjet 的打印机设备，可以将SET命令替换为以下内容：

   SET IO="/usr/bin/lp -dlaserjet"

以下示例展示了如何从外部程序读取数据。此处，该进程打开一个到 UNIX® 程序 who 的输入管道，以便它可以读取当前登录到 UNIX® 的所有用户的 ID。

getids ; read the login IDs of everybody currently on 
       SET IO="/usr/bin/who"
       SET $ZTRAP="EOT"
       KILL LOGINS 
       OPEN IO:"Q"
       ; note that "R" (the default) is understood 
       SET users=0
       FOR I=0:0 {
          USE IO
          READ USER
          SET users=users+1
          SET LOGINS(USER)=""
          }
       QUIT
EOT    SET $ZTRAP=""
       USE 0
       WRITE !,USERS," is/are currently logged on.",!
       CLOSE IO
       QUIT

在 Windows 系统上，当 CPIPE OPEN程序参数指定 /COMMAND 或 /ARGS 时，系统使用 CreateProcess() 来运行该命令。如果 CreateProcess() 失败，则 OPEN将失败并显示错误。 GetLastError() 值可通过$SYSTEM.Process.OSError()获得。

在 UNIX® 系统上，当 CPIPE OPEN程序参数指定 /COMMAND 或 /ARGS 时，系统会创建一个新进程，该进程发出 exec() 来运行该命令。如果 exec() 失败， OPEN将失败并显示错误。 exec() errno 可通过$SYSTEM.Process.OSError() 获得。

第十章 本地进程间通信（管道） - 用于进程间通信的 OPEN 命令

用于进程间通信的 OPEN 命令

OPEN命令允许程序与 IRIS 外部的进程进行通信。

OPEN Arguments

cpipename 管道名称

仅命令管道— “|CPIPE|”或"|CPIPE|xxxxxx" ，其中xxxxxx表示用户指定的唯一标识符。

program 程序

命令管道可以使用命令 shell 或不使用命令 shell（直接）执行程序。在大多数情况下，首选不使用命令 shell 执行。标准管道使用命令 shell 执行程序。

仅命令管道— 要在不使用命令 shell 的情况下执行，请指定 /COMMAND= program 。如果程序有参数，则必须使用 /ARGS 关键字指定它们。如果指定 /COMMAND 或 /ARGS 关键字，则无需命令 shell 即可执行程序： (/COMMAND=program) 、 (/COMMAND=program:/ARGS=arg1)和(program:/ARGS=arg1)都是有效的语法。 /ARGS 可以采用单个参数、以逗号分隔的参数列表或数组。例如， (/COMMAND=program:/ARGS=arg1,arg2) 。可以使用数组指定可变数量的参数：

  SET array(1)=arg1, array(2)=arg2, array=2
  OPEN device:(/COMMAND=cmd:/ARGS=array...)

要使用命令 shell 执行，请指定program ，并省略 /COMMAND 和 /ARGS 关键字。

程序字符串包含系统上安装的程序的完整路径名。它包含要在主机系统上执行的命令名称及其参数（如果有）。对于标准管道，限制为 <256 个字符。对于命令管道，最大长度取决于平台，但实质上超过 256 个字符。

parameters 参数

Read 对于标准管道，指定Q或QR以打开队列或管道以接受来自另一个进程的输入。对于命令管道：因为命令管道明确是管道，所以不需要Q字母代码；指定R 。

Write 对于标准管道，指定QW打开队列以将输入发送到另一个进程。对于命令管道：因为命令管道明确是管道，所以不需要Q字母代码；指定W 。

Read and Write 对于可以是读管道或写管道的标准管道，指定QRW以打开队列或管道以接受来自另一个进程的输入并将输入发送到另一个进程。对于命令管道：因为命令管道明确是管道，所以不需要Q字母代码；指定RW 。

可以使用 /关键字参数指定这些参数和其他参数，并用冒号分隔。例如， OPEN "|CPIPE|":(cmd:/READ:/IOTABLE="UTF8") 。以下可选关键字参数通常与管道一起使用：

• K/ name / （或K num ）以启用 I/O 转换（如果已在系统范围内启用转换）。可以通过指定表的名称来标识转换所基于的先前定义的表。用于打开和关闭协议的+和-选项不适用于K协议。
• Y/ name / （或Y num ）告诉系统使用命名的 $X/$Y 操作表。可以通过指定表名称来识别先前定义的 $X/$Y 操作表（转换所基于的操作表）。 $X/$Y 操作始终启用。如果未指定Y并且未定义系统默认 $X/$Y，则使用内置的 $X/$Y 操作表。用于打开和关闭协议的+和-选项不适用于Y协议。

可以通过上述参数指定S （流）、 F （固定长度）或U （未定义长度）模式参数。无法指定V （可变长度）模式参数。

closetimeout 关闭超时

可选— 仅限 UNIX®：可以指定关闭管道命令设备时CLOSE命令等待命令进程退出的秒数。默认值为 30 秒。可以通过在进程间通信的 CLOSE 命令上指定“I”（立即）参数来覆盖此关闭超时。

timeout 暂停

可选— 一个正整数，其值（以秒为单位）是 IRIS 等待OPEN成功完成的最长时间。如果 IRIS 能够在超时到期之前打开进程间通信，则会将$TEST设置为 1。如果 IRIS 在超时到期之前无法打开进程间通信，则会将$TEST设置为 0。如果忽略超时或指定0， OPEN立即将控制权返回给进程。

第九章 本地进程间通信（管道）

本页介绍如何通过管道与 IRIS® 数据平台外部的进程建立通信。

介绍

可以通过管道在 IRIS 进程和外部 UNIX® 或 Windows 进程之间进行通信，就像在 UNIX® 或 Windows 操作系统级别一样。可以将输出发送到管道或从管道接收输入。管道为单向；不能同时读取和写入同一个程序。

当打开另一个程序的管道进行输出时，可以像写入顺序文件一样对其进行写入。然后程序使用编写的内容作为其输入流。当希望 IRIS 进程与外部进程共享资源时，此功能特别有用。

打开 IRIS 实用程序的管道

可以打开通往 IRIS 实用程序以及 UNIX® 或 Windows 进程的管道。在将管道用于实用程序 I/O 之前，系统管理员必须在 IRIS 系统上定义管道设备。

系统管理员定义管道设备后，当运行实用程序（例如^%RD ）时，可以使用系统管理员定义的助记符回答Device:提示。输出会自动发送到该设备。

管道和命令管道

IRIS 支持标准管道和命令管道 (CPIPE)。标准管道用于相对较短的命令字符串，其中命令名称及其参数少于 256 个字符。当命令字符串长度为 256 个字符或更长时，使用命令管道。在这两种情况下，管道只能在 UNIX® 和 Windows 系统上使用。

标准管道 OPEN

以下是标准管道的OPEN命令语法：

OPEN program:(parameters):timeout

因为program是第一个参数（设备参数），所以它必须遵循OPEN命令设备名称的256个字符的限制。

如果对已打开的标准管道发出OPEN命令，则第二个OPEN将被忽略。没有发出错误。

OPEN 命令管道打开

以下是命令管道的OPEN命令语法：

OPEN cpipename:program:timeout
OPEN cpipename:(program:parameters:::closetimeout):timeout

cpipename参数可以采用值“|CPIPE|”如果只有命令管道同时打开。要打开多个并发管道，请指定"|CPIPE|xxxxxx" ，其中xxxxxx表示用户指定的唯一标识符。此cpipename参数是为后续USE和CLOSE命令指定的参数。

由于program是第二个参数，因此它不限于256个字符。程序的最大长度取决于平台。

如果对已打开的命令管道发出OPEN命令，则第二个OPEN将被忽略。没有发出错误。

第八章 在 I/O 命令中指定设备 - 通过 IRIS ID 指定设备

通过 IRIS ID 指定设备

为了与其他 产品兼容并方便起见，可以通过设备编号（存储在设备表中）来引用设备。系统管理员可以使用管理门户将这些号码链接到设备。选择“系统管理” 、 “配置” 、 “设备设置” 、 “设备”以创建新设备或编辑现有设备。

系统管理员还可以将一个数字转换为另一个数字。因此，可以发出OPEN 47 ， IRIS 会将其转换为OPEN 49 。

下表显示了设备编号。

IRIS 设备编号和设备

示例

要打开假脱机程序，请发出以下命令：

OPEN 2

指定磁盘上的文件

可以使用双引号括起来的操作系统文件规范来打开磁盘文件。

Windows 文件规范具有以下格式：

device:\directory\file.type

UNIX® 文件规范具有以下格式：

/directory/name

UNIX 示例

如果 UNIX® 或 Windows 系统上的当前默认目录是 /usr/user，则可以通过指定以下方式打开存储在当前默认目录中的名为pat_rec.dat的文件：

   OPEN "pat_rec.dat"

系统自动打开该文件。对于新文件，请包含参数字符串WN以避免挂起。

要打开存储在另一个目录中的同名文件pat_rec.dat ，还必须指定该目录，如下所示：

   OPEN "/usr/elsewhere/pat_rec.dat"

第七章 在 I/O 命令中指定设备

当使用 I/O 命令OPEN 、 USE和CLOSE在除正在使用的设备之外的任何设备上处理 I/O 时，必须指定一个 I/O 设备。可以根据设备类型以三种方式之一指定设备，如下表所示。

在 I/O 命令中指定设备

请注意，Windows 和 UNIX® 处理打印机I/O 的方式不同。有关详细信息，请参阅打印机。

按设备名称指定终端和打印机

如果的 I/O 操作是针对终端（或某些平台上的打印机），则可以使用操作系统（UNIX® 或 Windows）应用的设备名称来指定设备。形式如下：

OPEN "device"  
USE "device"  
CLOSE "device"

其中device是设备的操作系统名称，用引号引起来。设备的最大长度为 256 个字符。

在 Windows 系统上指定终端

要打开连接到串行通信端口的 I/O 设备，请使用以下语法指定OPEN命令：

OPEN "comn:"

其中n表示设备所连接的端口号。

   OPEN "com1:"

在 UNIX® 上指定终端和打印机

要在具有 UNIX® 设备名称 /dev/tty06 的终端上打开 I/O 设备，请输入以下命令

 OPEN "/dev/tty06"

在 UNIX® 系统上，打印机由OPEN命令上的名称来标识，并在 tty 设备上作为“字符特殊”文件进行处理。因此，支持的OPEN和USE命令参数与终端 I/O 的参数相同，而不是顺序文件 I/O。在 Windows 系统上，打印机 I/O 的处理方式与顺序文件 I/ 类似。

第六章 主设备、当前设备、空设备

明确使用主设备

USE 0或USE $principal向进程的主体设备隐式发出OPEN命令。如果另一个进程拥有该设备，则该进程会挂在隐式OPEN上，就像它遇到任何OPEN时一样。

为该进程不拥有的任何其他设备（由于先前的OPEN命令）发出USE命令会产生错误。

仅当进程获取设备时，没有超时的OPEN命令才将控制权返回给进程。可以通过键盘中断命令（如Ctrl-C ）中断打开命令。由于保护问题或无效设备名称而无法成功的OPEN将永远挂起。当在OPEN命令中指定超时时， OPEN将在超时到期时将控制权返回给进程。

使用主设备的选项

根据主要设备的性质，可以指定其他特定于设备的参数，这些参数对于管道（进程间通信） 、文件和终端 I/O是不同的。例如，可以使用 TLS 连接打开主设备：

USE $principal:(::/TLS=ConfigName)

其中ConfigName是同一实例中定义的 TLS 配置的名称。

空设备

如果应用程序生成不希望出现在屏幕上的无关输出，可以将该输出定向到空设备。可以通过发出带有适当参数的 IRIS OPEN命令来指定空设备（见表）。 IRIS 将其视为虚拟设备。

空设备参数

后续READ命令立即返回空字符串。随后的WRITE命令立即返回成功。没有读取或写入实际数据。 NULL 设备完全绕过 UNIX® 打开、写入和读取系统调用。

注：如果从 IRIS 内部以外的地方打开 NULL 设备（例如，通过将 IRIS 输出从 UNIX® shell 重定向到 /dev/null），则 UNIX® 系统调用确实会像对任何其他设备一样发生。

注：当一个进程使用JOB命令启动另一个进程时，Jobbed 进程的默认主要输入和输出设备是空设备。

第五章 主设备、当前设备、空设备

一个进程拥有一台设备

一次只有一个进程可以拥有一个设备，顺序文件除外。

换句话说，在进程成功向设备发出OPEN命令后，在第一个进程释放该设备之前，其他进程都无法打开该设备。进程通过以下任一方式释放设备：

• 通过显式发出CLOSE命令。

• 通过停下来。

每个进程都有一个主设备

每个 IRIS 进程都有一个主要输入设备和一个主要输出设备。默认情况下，这些是同一设备。当您登录终端并激活 IRIS 时，该终端将成为主要设备。由于 IRIS 隐式向该终端发出OPEN和USE命令，因此可以立即向它发出READ和WRITE命令。 IRIS 主设备是操作系统指定为主输入设备的设备。 $PRINCIPAL特殊变量包含主设备的设备 ID。

IRIS 将 I/O 命令定向到当前设备

IRIS 将输入和输出操作（包括READ 、 WRITE 、 PRINT和ZLOAD命令）定向到当前设备。 $I特殊变量包含当前设备的设备 ID。当在终端上登录 IRIS 时， $IO最初包含终端的设备名称。换句话说，登录后，主设备和当前设备是相同的。在发出USE命令后，当前的设备（ $IO中包含的设备）通常是执行的最后一次USE命令中指定的设备。

尽管可以在编程器模式下对主设备以外的设备发出OPEN和USE ，但每次 IRIS 返回到>提示符时，它都会隐式发出USE 0。要继续使用 0 以外的设备必须发出USE在>提示符下输入的每一行中输入命令。

当主要设备成为当前的设备时

当执行以下任一操作时，主要设备将自动成为当前设备：

• 首次登录。
• 发出USE 0或USE $principal命令。
• 发出对%Library.Device 类的 ChangePrincipal()方法的调用。
• 未设置错误陷阱时导致错误。
• 关闭当前设备。
• 返回程序员模式。
• 通过发出HALT命令退出 IRIS。

第四章 I O 输入输出简介 - Read 命令

Read 命令

该命令从当前设备读取数据。对于某些设备，以星号开头的参数返回 ASCII 数字信息；对于其他人来说，它们表示控制功能。

语法

READ variable:timeout

WRITE 命令

该命令将数据写入当前设备。对于某些设备，以星号开头的参数允许使用其 ASCII 数值写入 ASCII 字符；对于其他人来说，它们表示控制功能。对于某些设备，以 # 字符开头的参数指示写入该字符的次数。

语法

WRITE variable

WRITE /mnemonic

WRITE /mnemonic 语法允许使用在助记符空间中的 IRIS 代码中定义的助记符来控制设备。助记符空间是一个 IRIS 例程，必须在OPEN或USE命令中激活它，或者使用管理门户将其配置为设备的默认值。要了解如何定义和激活助记符空间，请参阅定义默认助记符空间。

要使用预定义的 ^%X364 助记符空间将光标移动到终端屏幕上的第 1 列第 2 行，请发出以下命令：

   WRITE /CUP(1,2)

CLOSE 命令

CLOSE命令释放指定设备的所有权。 CLOSE反转OPEN命令的效果。

语法

CLOSE device[:params] 

device

所需的设备名称、ID 号或助记符。

params

参数K在 IRIS 级别关闭设备，而不在操作系统级别关闭它。

K参数对 Windows 系统没有影响。该文件在操作系统级别关闭。

如果对主设备发出CLOSE命令，则主设备将保持分配给您的进程，直到注销为止。

其他几个条件可能会影响CLOSE的行为：

• 如果由于某种原因停止向设备的输出， IRIS 可能无法完成向该设备的输出，在这种情况下无法关闭它，并且可能无法停止。例如，如果终端向操作系统发送Ctrl-S以告知其停止向终端输出，则必须通过按Ctrl-Q恢复向终端的输出。
• 如果关闭当前设备， CLOSE会将系统变量 $IO 的值更改为主设备的值。仅当当前设备的所有输出完成后， CLOSE命令才会释放该设备的所有权。
• 当进程停止时，系统会自动关闭该进程在 IRIS 中打开的所有设备。

如果由于某种原因停止向设备的输出 IRIS 可能无法完成向该设备的输出，在这种情况下可能无法关闭它或无法停止。

第三章 I O 输入输出简介 - Use 命令

Use 命令

此命令使指定设备成为当前设备，并将特殊变量$IO设置为该设备。要使用主设备以外的设备，必须首先对其发出OPEN命令；否则，将收到错误。参数的含义与OPEN命令中的相同。

语法

USE device:(args):"mnespace"

device

所需的设备名称、ID 号或别名。设备的最大长度为 256 个字符。

args

可选— 某些设备所需的附加信息。管道（进程间通信） 、文件和终端 I/O的可用参数不同。

mnespace

可选— IRIS 例程的名称，包含控制助记符的定义，当将 I/O 定向到该设备时，可以与WRITE /mnemonic 命令一起使用。

Windows 上的使用示例

此 Windows 示例显示了用于通过 TCP 连接到远程主机larry上的时钟服务器的命令。它使用服务名称daytime ，本地系统将其解析为端口号。 USE命令用 PSTE 模式替换OPEN C 模式并关闭所有用户终止符：

   OPEN "|TCP|4":("larry":"daytime":"C")
   USE "|TCP|4":(::"PSTE")

在 UNIX® 上的使用示例

此 UNIX 示例显示了用于打开设备/dev/tty06的 I/O 通道并将其建立为当前设备的命令，并可以选择使用WRITE /mnemonic 和 X364 终端助记符。

   OPEN "/dev/tty06"
   USE "/dev/tty06"::"^%x364"

第二章 I O 输入输出简介 - Open 命令

Open 命令

OPEN建立指定设备的所有权并打开指定设备的 I/O 通道。此所有权将持续存在，直到发出CLOSE命令、进程终止或某些物理操作关闭设备。对于物理 I/O 设备或进程间通信（例如 TCP 连接），此所有权会阻止所有其他进程访问该设备。对于逻辑 I/O 设备（例如顺序文件），此所有权可能允许其他进程以某种形式共享访问该文件。打开同一顺序文件的多个进程的处理高度依赖于平台。强烈建议使用LOCK命令来限制对顺序文件的访问。

语法

OPEN device{:{(parameters)}{:{timeout}{:"mnespace"}}}

device

所需的设备名称、ID 号或助记符。设备的最大长度为 256 个字符。

parameters

可选— 一个或多个参数，指定某些设备所需的附加信息。该参数列表用括号括起来，列表中的参数之间用冒号分隔。管道（进程间通信） 、文件和终端 I/O的可用参数不同。

timeout

可选— 等待请求成功的秒数。前面的冒号是必需的。超时必须指定为整数值或表达式。如果超时设置为零 (0)， OPEN将尝试打开文件一次。如果尝试失败， OPEN会立即失败。如果尝试成功，则成功打开文件。如果未设置超时 IRIS 将继续尝试打开设备，直到打开成功或手动终止该过程。

mnespace

可选—助记符空间的名称，包含与该设备一起使用的控制助记符，指定为带引号的字符串。将 I/O 定向到该设备时，可以通过WRITE /mnemonic 命令使用这些控制助记符。

Windows 系统上 OPEN 的示例

此命令打开从 Windows 系统到终端服务器的出站 Telnet 连接：

  OPEN "|TNT|node:port"

其中， node是节点名称， port是服务器上的 IP 端口。

此命令打开现有 Windows 文件的 I/O 通道：

   OPEN "c:\abc\test.out":"WS"

UNIX® 系统上的 OPEN 示例

此命令打开到 UNIX® 终端设备 /dev/tty06 的 I/O 通道：

   OPEN "/dev/tty06/"

第一章 I/O 输入/输出简介

本页概括地描述了如何在 IRIS 数据平台应用程序中以及在 IRIS 提示符下使用 I/O 设备。

介绍

IRIS 数据平台为多种不同类型的逻辑和物理设备提供支持。支持的逻辑设备包括：

• 主要装置
• 文件
• 管道
• TCP连接
• 作业间通信 (IJC) 设备用于在 IRIS 进程之间进行通信
• 假脱机程序

支持的物理设备包括

• 终端
• 打印机

I/O 命令概述

I/O 命令允许拥有、使用、读取、写入和关闭设备。要将 I/O 操作定向到设备，请首先发出以下命令：

• 发出OPEN命令来建立所有权，除非该设备是主要设备。
• 发出USE命令使该设备成为当前设备。
• 随后的READ和WRITE命令将从该设备读取或写入该设备。
• CLOSE命令释放设备的所有权，以便其他进程可以使用该设备。

以下通用语法适用于支持 ObjectScript 中 I/O 命令关键字的 I/O 命令：

OPEN device:paramlist:timeout:"mnespace"
USE device:paramlist:"mnespace"
CLOSE device:paramlist

其中paramlist可以是单个参数，也可以是括在括号中并用冒号分隔的参数列表：

 parameter  (parameter:parameter[:...]) 
```

参数可以是位置参数或关键字参数。关键字参数具有以下语法：

````java
/keyword[=value] 
```

前导斜杠区分关键字参数和位置参数值。位置参数值的含义源自其在冒号分隔列表中的位置。关键字参数值的含义源自指定的关键字。

请注意，位置参数和关键字参数都可以在同一个`paramlist`中指定。例如，以下示例混合位置参数和关键字参数，以使用 `JIS I/O` 转换以写入/顺序模式打开名为test.dat的新文件：

````java
   OPEN "test.dat":("NWS":/IOTABLE="JIS")
```

InterSystems FAQ 

一个实例上的最大命名空间数量是 2047. 但是，要使用这么大量的命名空间，你需要相应地配置好内存。

一个实例里可以创建的数据库的最大数量（包括远程数据库） 15998. 根据授权的类型，可能会有所限制。具体细节请参考以下文档。
Database Configuration [IRIS]
Database Configuration
 

第五十五章 安全元素的详细信息 - <ReferenceList> 详情

本节讨论在消息头中用作 <Security>子元素的 <ReferenceList> 元素。当以这种方式使用 <ReferenceList> 时，可以在签名之前执行加密。以下显示了此元素的一个示例：

<ReferenceList xmlns="http://www.w3.org/2001/04/xmlenc#">
   <DataReference URI="#Enc-358FB189-81B3-465D-AFEC-BC28A92B179C"></DataReference>
   <DataReference URI="#Enc-9EF5CCE4-CF43-407F-921D-931B5159672D"></DataReference>
</ReferenceList>

详情

在每个 <DataReference> 元素中，URI 属性指向消息中其他位置的 <EncryptedData> 元素的 Id 属性。

使用顶级 <ReferenceList> 元素时，<EncryptedKey> and <EncryptedData> 的详细信息有所不同，如下所示：

消息中的位置

在 <Security> 中，应在关联的 <EncryptedKey> 之后包含一个 <ReferenceList> 元素。

第五十四章 安全元素的详细信息 - <DerivedKeyToken> 详情

<DerivedKeyToken> 的目的是携带发送者和接收者可以独立使用的信息来生成相同的对称密钥。这些方可以使用该对称密钥对 SOAP 消息的相关部分进行加密、解密、签名和签名验证。

以下显示了部分示例：

<DerivedKeyToken xmlns="[parts omitted]ws-secureconversation/200512" 
                 xmlns:wsc="[parts omitted]ws-secureconversation/200512" 
                 wsu:Id="Enc-943C6673-E3F3-48E4-AA24-A7F82CCF6511">
   <SecurityTokenReference xmlns="[parts omitted]oasis-200401-wss-wssecurity-secext-1.0.xsd">
      <Reference URI="#Id-658202BF-239A-4A8C-A100-BB25579F366B"></Reference>
   </SecurityTokenReference>
   <Nonce>GbjRvVNrPtHs0zo/w9Ne0w==</Nonce>
</DerivedKeyToken>

详情

该元素的各部分如下：

• Id 是元素的唯一标识符。IRIS 会自动生成此标识符。
• <EncryptionMethod>表示用于加密该数据的算法。

在 IRIS 中，可以指定此算法。请参阅指定块加密算法。

• <SecurityTokenReference> 表示在计算派生密钥时用作基础的对称密钥。这可以包含一个 <Reference> 元素，其 URI 属性指向同一消息中的 <EncryptedKey> 或另一个 <DerivedKeyToken>。

或者 <SecurityTokenReference>可以包含一个 <KeyIdentifier>，该 <KeyIdentifier> 引用所使用的 <EncryptedKey> 的 SHA1 哈希值。例如：

<SecurityTokenReference xmlns="[parts omitted]oasis-200401-wss-wssecurity-secext-1.0.xsd" 
                               s01:TokenType="[parts omitted]#EncryptedKey" 
                               xmlns:s01="h[parts omitted]oasis-wss-wssecurity-secext-1.1.xsd">
   <KeyIdentifier EncodingType="[parts omitted]#Base64Binary" 
                              [parts omitted]#EncryptedKeySHA1">
                     U8CEWXdUPsIk/r8JT+2KdwU/gSw=
   </KeyIdentifier>
</SecurityTokenReference>

• <Nonce> 是此派生密钥的密钥派生函数中的种子所使用的 base-64 编码值。

<DerivedKeyToken> 元素的计算使用 RFC 2246 中为 TLS 定义的机制的子集。

<DerivedKeyToken> 元素和关联的 <EncryptedData> 或 <Signature> 元素之间的连接处理如下：

• 每个 <DerivedKeyToken> 都包含一个具有唯一标识符的 Id 属性。
• 在每个已由给定 <DerivedKeyToken> 指示的对称密钥加密的 <EncryptedData>元素中，都有一个<SecurityTokenReference> 元素，其 URI 属性指向该 <DerivedKeyToken>。
• 在每个<Signature>元素中（其值由给定 <DerivedKeyToken> 指示的对称密钥计算），都有一个 <SecurityTokenReference> 元素，其 URI 属性指向该 <DerivedKeyToken>。
• 每个 <EncryptedData>和 <Signature> 元素还包括具有唯一标识符的 Id 属性。
• WS-Security 标头包含一个引用 <EncryptedData> 和 <Signature> 元素的 <ReferenceList>元素。

消息中的位置

<DerivedKeyToken> 应该包含在 <DerivedKeyToken> 中，位于引用它的任何 <EncryptedData> 和 <Signature> 元素之前。

第五十三章 安全元素的详细信息 - <Signature> 详情

<Signature>的目的是携带可由消息接收者验证的数字签名。可以使用数字签名来检测消息更改，或者只是验证消息的某个部分是否确实由列出的实体生成。与传统的手写签名一样，数字签名是对文档的附加，只能由文档的创建者创建，并且不易伪造。

以下显示了部分示例：

<Signature xmlns="http://www.w3.org/2000/09/xmldsig#">
   <SignedInfo>
      <CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#">
      </CanonicalizationMethod>
      <SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha256"></SignatureMethod>
      <Reference URI="#Timestamp-48CEE53E-E6C3-456C-9214-B7D533B2663F">
         <Transforms>
            <Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"></Transform>
         </Transforms>
         <DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"></DigestMethod>
         <DigestValue>waSMFeYMruQn9XHx85HqunhMGIA=</DigestValue>
      </Reference>
      <Reference URI="#Body-73F08A5C-0FFD-4FE9-AC15-254423DBA6A2">
         <Transforms>
            <Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"></Transform>
         </Transforms>
         <DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"></DigestMethod>
         <DigestValue>wDCqAzy5bLKKF+Rt0+YV/gxTQws=</DigestValue>
      </Reference>
   </SignedInfo>
   <SignatureValue>j6vtht/[parts omitted]trCQ==</SignatureValue>
   <KeyInfo>
      <SecurityTokenReference xmlns="[parts omitted]oasis-200401-wss-wssecurity-secext-1.0.xsd">
         <Reference URI="#SecurityToken-411A262D-990E-49F3-8D12-7D7E56E15081" 
                    ValueType="[parts omitted]oasis-200401-wss-x509-token-profile-1.0#X509v3">
         </Reference>
      </SecurityTokenReference>
   </KeyInfo>
</Signature>

详情

该元素的各部分如下：

• <SignedInfo> 指示消息中由此签名签名的部分，并指示这些部分在签名之前是如何处理的。

在 IRIS 中，可以指定摘要方法（由 <DigestMethod>的 Algorithm 属性显示）。请参阅指定摘要方法。

还可以指定用于计算签名的算法（由 <SignatureMethod> 的 Algorithm 属性显示）。请参阅指定签名方法。

• <SignatureValue 保存实际签名。在本例中，签名为 6vtht/[parts divided]trCQ==

该值是通过加密签名部分的连接摘要计算得出的。加密由发送者的私钥执行。

• <KeyInfo> 标识用于创建签名的密钥。在 IRIS 中，<KeyInfo> 包含 <SecurityTokenReference>，它具有以下几种形式之一：
  • 对 WS-Security 标头中前面的 <BinarySecurityToken> 的引用，如上例所示。在本例中，使用相应的私钥来创建签名。
  • 用于识别证书的信息，该证书可能是消息接收者先前收到并存储的。例如， <SecurityTokenReference> 可以包含证书的 SHA1 指纹，如下所示：

<SecurityTokenReference xmlns="[parts omitted]oasis-200401-wss-wssecurity-secext-1.0.xsd">
   <KeyIdentifier EncodingType="[parts omitted]#Base64Binary" 
                  ValueType="[parts omitted]#ThumbprintSHA1">
      maedm8CNoh4zH8SMoF+3xV1MYtc=
   </KeyIdentifier>
</SecurityTokenReference>

与前一种情况一样，使用相应的私钥来创建签名。

- 对 WS-Security 标头中先前的 <DerivedKeyToken>  的引用。例如：

<SecurityTokenReference xmlns="[parts omitted]oasis-200401-wss-wssecurity-secext-1.0.xsd">
   <Reference URI="#Enc-BACCE807-DB34-46AB-A9B8-42D05D0D1FFD"></Reference>
</SecurityTokenReference>

在这种情况下，签名是由该令牌指示的对称密钥创建的。

- 对隐含的 <DerivedKeyToken> 的引用。例如：

<SecurityTokenReference xmlns="[parts omitted]oasis-200401-wss-wssecurity-secext-1.0.xsd" 
              s01:Nonce="mMDk0zn8V7WTsFaIjUJ7zg==" 
              xmlns:s01="http://docs.oasis-open.org/ws-sx/ws-secureconversation/200512">
   <Reference URI="#Id-93F97220-568E-47FC-B3E1-A2CF3F70B29B"></Reference>
</SecurityTokenReference>

在这种情况下，<Reference> 中的 URI 属性指向用于生成 <DerivedKeyToken>,的 <EncryptedKey>元素，而 Nonce 属性指示所使用的 nonce 值。

与前一种情况一样，派生密钥用于加密数据。

消息中的位置

如果有的话，<Signature> 元素应包含在<Security> 中，位于其使用的 <BinarySecurityToken> or <DerivedKeyToken> 之后。

第五十二章 安全元素的详细信息 - <EncryptedData> 详情

<EncryptedData> 的作用是携带加密数据，部分示例如下：

<EncryptedData xmlns="http://www.w3.org/2001/04/xmlenc#" 
               Id="Enc-143BBBAA-B75D-49EB-86AC-B414D818109F" 
               Type="http://www.w3.org/2001/04/xmlenc#Content">
   <EncryptionMethod Algorithm="[parts omitted]#aes128-cbc"></EncryptionMethod>
   <CipherData>
      <CipherValue>MLwR6hvKE0gon[parts omitted]8njiQ==</CipherValue>
   </CipherData>
</EncryptedData>

详情

该元素的各部分如下：

• Id 是元素的唯一标识符。 IRIS 会自动生成此标识符。
• <EncryptionMethod> 表示用于加密该数据的算法。
• <CipherData>携带加密数据，作为 <CipherValue>元素中的值。在此示例中，值 MLwR6hvKE0gon[parts divided]8njiQ== 为加密数据。
• （未包含在示例中 <KeyInfo> 标识对称密钥。在本例中， <KeyInfo> 包含一个 <SecurityTokenReference> 元素，该元素包含对对称密钥的引用，其形式如下：
  • 对 WS-Security 标头中先前的 <DerivedKeyToken> 的引用。
  • 对隐含的 <DerivedKeyToken>的引用。例如：

<KeyInfo xmlns="http://www.w3.org/2000/09/xmldsig#">
   <SecurityTokenReference xmlns="[parts omitted]oasis-200401-wss-wssecurity-secext-1.0.xsd" 
                 s01:Nonce="mMDk0zn8V7WTsFaIjUJ7zg==" 
                 xmlns:s01="http://docs.oasis-open.org/ws-sx/ws-secureconversation/200512">
      <Reference URI="#Id-93F97220-568E-47FC-B3E1-A2CF3F70B29B"></Reference>
   </SecurityTokenReference>
</KeyInfo>

在这种情况下，<Reference> 中的 URI 属性指向用于生成 <DerivedKeyToken> 的 <EncryptedKey> 元素，而 Nonce 属性指示所使用的 nonce 值。

在这两种情况下，这个派生密钥都用于加密此 <EncryptedData> 元素中携带的数据。

如果加密使用顶级 <ReferenceList> 元素，则会包含 <KeyInfo> 元素；请参阅 <ReferenceList>。

消息中的位置

在 <Security> 中，应在关联的 <EncryptedKey> 之后包含一个 <EncryptedData> 元素。

<EncryptedData> 元素也可以是 SOAP 主体（<Body> 元素）的子元素。

第五十一章 安全元素的详细信息 - <EncryptedKey> 详情

详情

该元素的各部分如下：

• <EncryptionMethod> 表示用于加密对称密钥的算法。

在 IRIS 中，可以指定密钥传输算法（由 <EncryptionMethod> 的 Algorithm 属性显示）。请参阅指定密钥传输算法。

• <KeyInfo> 标识用于加密此对称密钥的密钥。在 IRIS 中，<KeyInfo> 包含 <SecurityTokenReference>，其具有以下形式之一：
  • 对 WS-Security 标头中较早位置的 <BinarySecurityToken> 的引用，如前面的示例所示。
  • 用于唯一标识证书的信息，该证书可能是邮件收件人所拥有的。例如，<SecurityTokenReference> 可以包含证书的 SHA1 指纹，如下所示：

<SecurityTokenReference xmlns="[parts omitted]oasis-200401-wss-wssecurity-secext-1.0.xsd">
   <KeyIdentifier EncodingType="[parts omitted]#Base64Binary" 
                  ValueType="[parts omitted]#ThumbprintSHA1">
      maedm8CNoh4zH8SMoF+3xV1MYtc=
   </KeyIdentifier>
</SecurityTokenReference>

在这两种情况下，相应的公钥都用于加密此 <EncryptedKey> 元素中携带的对称密钥。

如果加密使用顶级 <ReferenceList> 元素，则省略此元素；请参阅 <ReferenceList>。

• <CipherData>携带加密后的对称密钥，作<CipherValue>元素中的值。本例中的值 WtE[parts divided]bSyvg== 即为加密后的对称密钥。
• <ReferenceList> 表示此消息中使用此 <EncryptedKey> 元素中携带的对称密钥加密的部分或多个部分。具体而言，<DataReference> 的 URI 属性指向消息中其他地方的 <EncryptedData>元素的 Id 属性。

根据使用的技术，可能不包含此元素。可以通过顶级 <ReferenceList> 元素链接 <EncryptedData> 和相应的 <EncryptedKey> ；请参阅 <ReferenceList>。

消息中的位置

<EncryptedKey> 元素应包含在 <Security> 中，位于其使用的任何 <BinarySecurityToken> 之后，以及引用它的所有 <EncryptedData> 和 <DerivedKeyToken> 元素之前。

第五十章 安全元素的详细信息

本主题讨论 SOAP 消息中较常见的安全元素，特别是 IRIS Web 服务和客户端可以发送的变体。此信息旨在帮助那些不经常使用 SOAP 的人重温记忆。此处的详细信息也可能有助于故障排除。

<BinarySecurityToken>

<BinarySecurityToken> 的目的是携带消息中其他元素使用的安全凭证，供消息接收者使用。安全凭证以序列化、编码的形式携带。以下显示了部分示例：

<BinarySecurityToken wsu:Id="SecurityToken-4EC1997A-AD6B-48E3-9E91-8D50C8EA3B53" 
                     EncodingType="[parts omitted]#Base64Binary" 
                     ValueType="[parts omitted]#X509v3">
             MIICnDCCAYQ[parts omitted]ngHKNhh
</BinarySecurityToken>

详细

该元素的各部分如下：

• Id 是此令牌的唯一标识符，包含该标识符以便此消息中的其他元素可以引用此令牌。如有必要， IRIS 会自动生成此标识符。
• EncodingType 表示用于生成 <BinarySecurityToken> 中的值的编码类型。在 IRIS 中，<BinarySecurityToken> 中使用的唯一编码是 base-64 编码。
• ValueType 表示令牌中包含的值的类型。在 IRIS 中，唯一支持的值类型是 X.509 证书。
• <BinarySecurityToken> 元素中包含的值是序列化的编码证书。在此示例中，值 MIICnDCCAYQ[parts divided]ngHKNhh 是安全凭证。

如果此令牌与加密操作相关联，则所包含的证书是消息接收者的证书。如果此令牌与签名相关联，则所包含的证书是消息发送者的证书。

消息中的位置

<BinarySecurityToken> 应该包含在 <Security> 中，在任何引用它的元素之前。

<EncryptedKey>

<EncryptedKey> 的作用是携带供消息中其他元素使用的对称密钥。对称密钥以加密形式携带。以下显示了部分示例：

<EncryptedKey xmlns="http://www.w3.org/2001/04/xmlenc#">
   <EncryptionMethod Algorithm="[parts omitted]xmlenc#rsa-oaep-mgf1p">
      <DigestMethod xmlns="http://www.w3.org/2000/09/xmldsig#" 
                    Algorithm="http://www.w3.org/2000/09/xmldsig#sha1">
      </DigestMethod>
   </EncryptionMethod>
   <KeyInfo xmlns="http://www.w3.org/2000/09/xmldsig#">
      <SecurityTokenReference xmlns="[parts omitted]oasis-200401-wss-wssecurity-secext-1.0.xsd">
         <Reference URI="#SecurityToken-4EC1997A-AD6B-48E3-9E91-8D50C8EA3B53" 
                    ValueType="[parts omitted]#X509v3">
         </Reference>
      </SecurityTokenReference>
   </KeyInfo>
   <CipherData>
      <CipherValue>WtE[parts omitted]bSyvg==</CipherValue>
   </CipherData>
   <ReferenceList>
      <DataReference URI="#Enc-143BBBAA-B75D-49EB-86AC-B414D818109F"></DataReference>
   </ReferenceList>
</EncryptedKey>

第四十九章 解决安全问题 - 可能出现的错误

可能出现的错误

本节讨论 IRIS Web 服务和 Web 客户端中可能出现的与安全相关的错误：

• 如果刚刚生成了 IRIS Web 服务或客户端，则可能尚未配置为识别 WS-Security 标头。在这种情况下，当您尝试执行 Web 方法时，会收到如下一般错误：

<ZSOAP>zInvokeClient+269^%SOAP.WebClient.1

将以下内容添加到Web服务或客户端并重新编译：

Parameter SECURITYIN="REQUIRE";

这种一般错误也可能是由于错误地调用 Web 方法（例如，在 Web 方法没有返回值时引用返回值）造成的。

如果使用 WS-Policy，则此项不适用。

• 在其他情况下，当您尝试执行 Web 方法时，可能会收到以下安全错误：

ERROR #6454: No supported policy alternative in configuration 
Policy.Client.Demo1SoapConfig:service

• 入站消息可能未通过验证。如果是这样，SOAP 日志会指出这一点。例如：

08/05/2011 14:40:11 *********************
Input to Web client with SOAP action = http://www.myapp.org/XMLEncr.DivideWS.Divide
<?xml version='1.0' encoding='UTF-8' standalone='no' ?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV='http://schemas.xmlsoap.org/soap/envelope/' 
xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance' xmlns:s='http://www.w3.org/2001/XMLSchema' 
xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd" >
  <SOAP-ENV:Body>
    <SOAP-ENV:Fault>
      <faultcode>wsse:FailedAuthentication</faultcode>
      <faultstring>The security token could not be authenticated or authorized</faultstring>
      <detail></detail>
    </SOAP-ENV:Fault>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

第四十八章 解决安全问题

本主题提供信息来帮助识别 IRIS 中 SOAP 安全问题的原因。

有关与安全无关的问题的信息，请参阅 IRIS 中的 SOAP 问题故障排除。

故障排除所需的信息

要解决 SOAP 问题，通常需要以下信息：

• WSDL 及其引用的所有外部文档。
• （在出现与消息相关的问题的情况下）某种形式的消息记录或跟踪。有以下选择：

发生安全错误时要检查的项目

这 IRIS 中的 SOAP 问题故障排除中进行了讨论。

• 在极少数情况下， SOAP 客户端会使用 `HTTP 身份验证，请注意，可以启用身份验证的日志记录；请参阅提供登录凭据。

正确处理故障也非常有用，这样就可以收到最好的信息。请参阅 SOAP 故障处理。

如果入站消息验证失败或 IRIS 发出不支持的策略替代错误，则检查以下项目很有用：

• 当检索存储的 IRIS 凭证集时，请确保正确输入其名称。
• 检索 IRIS 凭证集后，检查对象的类型以确保它是 %SYS.X509Credentials。
• 确保使用的是适当的证书。

如果使用它进行加密，则使用要向其发送消息的实体的证书。加密使用此证书的公钥。

如果使用它进行签名，则使用自己的证书，并使用关联的私钥进行签名。在这种情况下，请确保已加载私钥，并且已正确指定私钥文件的密码。

• 确保证书由 IRIS 信任的证书颁发机构签名。
• 如果正在使用 WS-Policy，请务必编辑生成的配置类以指定要使用的 IRIS 凭证集。请参阅编辑生成的策略。
• 如果 Web 服务需要 <UsernameToken>，请确保 IRIS Web 客户端正在发送此令牌，并且其中包含正确的信息。 IRIS 无法自动指定要发送的 <UsernameToken> ；这必须在运行时完成。请参阅添加时间戳和用户名令牌。

确保 IRIS 支持 Web 服务或客户端所需的至少一种安全策略。请参阅 SOAP 安全标准。

• 如果身份验证失败，则在 <UsernameToken> 中识别用户，并检查该用户所属的角色。

第四十七章 创建和添加 SAML 令牌 - <SubjectConfirmation>与 <EncryptedKey>

<SubjectConfirmation>与 <EncryptedKey>

要添加带有 <SubjectConfirmationData>（其中包含 <EncryptedKey> 元素）的 <SubjectConfirmation>，请执行以下操作：

1. 按照以编程方式检索凭证集中所述，创建 %SYS.X509Credentials 的实例。

或者使用与签署断言时使用的相同凭证集。

2. 设置 SAML 断言对象的 Subject 属性的 NameID 属性。
3. 调用 SAML 断言对象的 Subject 属性的 AddEncryptedKeyConfirmation() 方法。

method AddEncryptedKeyConfirmation(credentials As %X509.Credentials) as %Status

对于参数，请使用之前创建的 %SYS.X509Credentials实例。

<SubjectConfirmation> 以 BinarySecret 作为密钥持有者

要添加以 BinarySecret 作为 Holder-of-key 的 <SubjectConfirmation>，请执行以下操作：

1. 签署 SAML 断言时，请按如下方式创建签名：

set sig=##class(%XML.Security.Signature).Create(assertion,$$$SOAPWSIncludeNone,$$$SOAPWSSAML)

其中断言是 SAML 断言。请注意，在此场景中使用 Create() 方法。$$$SOAPWSSAML 引用选项创建对 SAML 断言的引用。

2. 创建 BinarySecret。为此，请调用 %SOAP.WST.BinarySecret 的 Create() 方法：

set binsec=##class(%SOAP.WST.BinarySecret).Create()

3. 调用 SAML 断言对象的 Subject 属性的 AddBinarySecretConfirmation() 方法：

set status=assertion.Subject.AddBinarySecretConfirmation(binsec)

对于 binsec，请使用在上一步中创建的 BinarySecret。

这将添加一个 <SubjectConfirmation>，其中包含一个 <SubjectConfirmationData>，该 <SubjectConfirmationData> 包含一个 <KeyInfo>，该 <KeyInfo> 包含 <BinarySecret>。

添加 <Conditions> 元素

要将 <Conditions> 元素添加到 %SAML.Assertion 实例 执行以下操作：

1. 创建 %SAML.Conditions的实例。
2. 根据需要指定此实例的属性。
3. 将断言对象的“条件”属性设置为等于此实例。

添加 <Advice>元素

要将 <Advice> 元素添加到 %SAML.Assertion实例，请执行以下操作：

1. 创建下列一个或多个类的实例：

• %SAML.AssertionIDRef

• %SAML.AssertionURIRef

• %SAML.EncryptedAssertion

2. 根据需要指定这些实例的属性。
3. 创建一个包含这些建议实例的列表。
4. 将断言对象的 Advice 属性设置为等于此列表。

第四十六章 创建和添加 SAML 令牌 - <SubjectConfirmation> 使用方法 Holder-of-key

添加<Subject>元素

要将 <Subject> 元素添加到 %SAML.Assertion 实例，执行以下操作：

1. 创建 %SAML.Subject 的新实例。
2. 根据需要设置主题的属性。
3. 将断言对象的 Subject 属性设置为等于此实例。

添加 <SubjectConfirmation> 元素

要将 <SubjectConfirmation> 元素添加到的 %SAML.Assertion 实例，请使用以下某个小节中的步骤。

<SubjectConfirmation>使用方法 Holder-of-key

要使用 Holder-of-key 方法添加 <SubjectConfirmation>，请执行以下操作：

1. 按照以编程方式检索凭证集中所述，创建 %SYS.X509Credentials 的实例。

或者使用与签署断言时使用的相同凭证集。

2. 可以选择创建并添加包含与给定凭据集关联的证书的二进制安全令牌。

要创建令牌，调用 %SOAP.Security.BinarySecurityToken 的 CreateX509Token() 类方法。例如：

 set bst=##class(%SOAP.Security.BinarySecurityToken).CreateX509Token(credset)

其中 credset 是在上一步中创建的凭证集。

要将此令牌添加到 WS-Security 标头元素，请调用 Web 客户端或 Web 服务的 SecurityOut 属性的 AddSecurityElement() 方法。对于方法参数，请使用刚刚创建的令牌。

3. 调用 SAML 断言对象的 Subject 属性的 AddX509Confirmation() 方法。

method AddX509Confirmation(credentials As %SYS.X509Credentials, 
                           referenceOption As %Integer) as %Status

对于凭证，请使用二进制安全令牌或凭证集。在前一种情况下，请勿指定referenceOption。在后一种情况下，请指定 X.509 凭证的引用选项中所述的值。

<SubjectConfirmation>元素基于 X.509 KeyInfo 元素。

<SubjectConfirmation> 使用方法 Sender-vouches

要使用 Sender-vouches 方法添加 <SubjectConfirmation> ，请执行以下操作：

1. 设置 SAML 断言对象的 Subject 属性的 NameID 属性。
2. 调用 SAML 断言对象的 Subject 属性的 AddConfirmation() 方法。

method AddConfirmation(method As %String) as %Status

对于方法，指定 $$$SAMLSenderVouches、$$$SAMLHolderOfKey 或 $$$SAMLBearer。

在这种情况下，请务必签署 SAML 断言以保护它。

第四十五章 创建和添加 SAML 令牌 - 变体：不使用 <BinarySecurityToken>

变体：不使用 <BinarySecurityToken>

<BinarySecurityToken> 包含序列化、base-64 编码格式的证书。可以忽略此令牌，而改用标识证书的信息；接收方使用此信息从相应位置检索证书。为此，请使用上述步骤，并进行以下更改：

• 跳过步骤 2 和 3。也就是说，不要创建和添加 <BinarySecurityToken>.。
• 在步骤 4 中，使用凭证集（而不是二进制安全令牌）作为 CreateX509() 的第一个参数。例如：

 set assertion=##class(%SAML.Assertion).CreateX509(credset,referenceOption)

对于 referenceOption，可选择指定一个值，如 X.509 凭证的参考选项中所述。可以使用除 $$$SOAPWSReferenceDirect 之外的任意值。

如果指定凭证集作为第一个参数（正如我们在这个变体中所做的那样），则默认引用选项是证书的指纹。

变体：创建未签名的 SAML 断言

要创建未签名的 SAML 断言，请使用上述步骤，并进行以下更改：

• 跳过步骤 1、2 和 3。也就是说，不要创建和添加 <BinarySecurityToken>.。
• 对于步骤 4，请使用 Create() 方法而不是 CreateX509()。此方法不带参数。例如：

 set assertion=##class(%SAML.Assertion).Create()

此方法返回 %SAML.Assertion的一个实例。 IRIS 会自动设置此实例的 SAMLID 和 Version 属性。Signature 属性为空。

添加 SAML 语句

要将 SAML 语句添加到 %SAML.Assertion 实例，请执行以下操作：

1. 创建适当语句类的一个或多个实例：

• %SAML.AttributeStatement

• %SAML.AuthnStatement

• %SAML.AuthzDecisionStatement

2. 根据需要指定这些实例的属性。

对于 %SAML.AttributeStatement，Attribute 属性是 %SAML.Attribute 或 %SAML.EncryptedAttribute 的实例。

%SAML.Attribute 在其 AttributeValue 属性中带有属性值，该属性值是的 %SAML.AttributeValue实例的列表。

要在实例中向 %SAML.Attribute添加属性值：

a. 创建 %SAML.AttributeValue 的实例。

b. 使用 %SAML.AttributeValue的方法在中将属性指定为 XML、字符串或单个子元素。

c. 创建一个包含这些属性值实例的列表。

d. 将属性对象的 AttributeValue 属性设置为等于此列表。

或者直接指定 AttributeValueOverride 属性。对于值，使用值所需的精确字符串（XML 混合内容字符串）。

3. 创建一个包含这些语句实例的列表。
4. 将断言对象的 Statement 属性设置为等于此列表。

第四十四章 创建和添加 SAML 令牌

本主题描述如何将SAML 令牌添加到 WS-Security 标头元素。

另请参阅 %SAML.Assertion 的类参考和相关类。

未实现完整的 SAML 支持。 IRIS 中的 SAML 支持仅指 IRIS 中的 WS-Security 支持中列出的详细信息。

概述

借助 IRIS SOAP 支持，可以将 SAML 令牌添加到 WS-Security 标头元素。

可以选择将此 SAML 令牌用作签名或加密的密钥材料。如果这样做， IRIS 将遵循 WS-Security SAML 令牌配置文件规范。密钥材料来自 SAML 断言的 <SubjectConfirmation> 元素（带有 Holder-of-key (HOK) 方法）和 <SubjectConfirmationData> 或 <KeyInfoConfirmationData>（带有 <KeyInfo> 子元素）。

或者，可以使用 Sender-vouches (SV) 方法添加 <SubjectConfirmation>；在这种情况下，主题不包含密钥。为了保护这种情况下断言，建议您添加从消息签名到 SAML 令牌的安全令牌引用。

基本步骤

要创建 SAML 令牌并将其添加到出站 SOAP 消息，可以使用此处的基本过程或小节中描述的变体。

1. 可选择包含 %soap.inc 包含文件，它定义了可能需要使用的宏。
2. 创建 %SYS.X509Credentials 的实例，如以编程方式检索凭据集中所述。

此 IRIS 凭证集必须包含自己的证书。例如：

 Set x509alias = "servercred" 
 Set pwd = "mypassword" 
 Set credset = ##class(%SYS.X509Credentials).GetByAlias(x509alias,pwd)

3. 创建包含与给定凭证集关联的证书的二进制安全令牌。为此，调用 %SOAP.Security.BinarySecurityToken的 CreateX509Token() 类方法。例如：

 set bst=##class(%SOAP.Security.BinarySecurityToken).CreateX509Token(credset)

其中 credset 是在上一步中创建的 IRIS 凭证集。

4. 将此令牌添加到 WS-Security 标头元素。为此，请调用 Web客户端或 Web 服务的 SecurityOut 属性的 AddSecurityElement() 方法。对于方法参数，请使用刚刚创建的令牌。例如：

 do ..SecurityOut.AddSecurityElement(bst)

5. 根据二进制安全令牌创建签名的 SAML 断言。为此，中调用 %SAML.Assertion 的 CreateX509() 类方法。例如：

 set assertion=##class(%SAML.Assertion).CreateX509(bst)

此方法返回 %SAML.Assertion的实例。 IRIS 会自动设置此实例的 Signature、SAMLID 和 Version 属性。

该实例代表 <Assertion> 元素。

6. 指定 %SAML.Assertion 实例的以下基本属性：
7. 添加 SAML 语句，如添加 SAML 语句中所述。
8. 向 SAML 断言添加 <Subject> 元素，如添加 <Subject> 元素中所述。
9. 可选择向 <Subject>添加<SubjectConfirmation> 元素，如添加 <SubjectConfirmation> 元素中所述。

可以使用“钥匙持有人”方法或“发送方凭证”方法确认主题。

10. 指定 SAML &<Conditions>元素，如添加 <Conditions> 元素中所述。
11. 可选择添加 <Advice> <Advice>元素，如添加 <Advice> 元素中所述。
12. 调用 Web 客户端或 Web 服务的 SecurityOut 属性的 AddSecurityElement() 方法。对于方法参数，请使用您创建的 SAML 令牌。
13. （可选）通过将 SOAP 消息签名中的引用添加到 SAML 断言来签署 SAML 断言。

如果签名是对象中的 %XML.Security.Signature，那么将按如下方式签署 SAML 断言：

  Set str=##class(%SOAP.Security.SecurityTokenReference).GetSAMLKeyIdentifier(assertion) 
  Set ref=##class(%XML.Security.Reference).CreateSTR(str.GetId()) 
  Do signature.AddReference(ref)

特别是当使用 Sender Vouches 方法添加 <SubjectConfirmation> 时，建议执行此步骤。

14. 发送 SOAP 消息。请参阅添加安全标头元素中的一般注释。