WEB OPEN

打开与作为 HTTP 客户机的 CICS® 服务器的连接。

WEB OPEN

主机

条件: IOERR ， INVREQ ， LENGERR ， NOTFND ， NOTAUTH 和 TIMEDOUT

此命令是线程安全的。

描述

WEB OPEN 允许应用程序通过 CICS Web Support 打开与因特网上 HTTP 服务器上的指定主机的连接。打开连接后，应用程序可以向服务器发送 HTTP 客户机请求并接收来自服务器的响应。

在打开连接时，您可以指定包含有关该连接 URL 的信息的 URIMAP 资源。您可以直接在 WEB OPEN 命令上指定此信息，而不是使用 URIMAP 资源。但是，使用 URIMAP 资源具有以下优势：

系统管理员可以管理对连接端点的任何更改，这样当您请求的 URL 发生更改时，您无需重新编译自己的应用程序。
如果您正在使用 SSL，那么您可以在 URIMAP 资源中指定一个 SSL 客户机证书或密码套件代码，以便于系统管理员可以管理对这些证书和代码的任何更改。
您可以选择使 CICS 在使用后保持使用 URIMAP 资源打开的连接处于打开状态，并将这些连接放在池中以供另一个应用程序或同一应用程序的另一个实例复用。只有在指定设置了 SOCKETCLOSE 属性的 URIMAP 资源时，连接池才可用。有关连接池的性能优势的更多信息，请参阅用于 HTTP 客户机性能的连接池。

有关为客户机请求创建 URIMAP 资源的信息，请参阅为 CICS 创建 URIMAP 资源作为 HTTP 客户机。

WEB OPEN 命令驱动 XWBOPEN 用户出口，如果需要，该用户出口可使与服务器的连接通过代理服务器。

注: 如果连接请求未在死锁超时时间间隔内完成 (在启动用户应用程序的事务的 TRANSACTION 定义的 DTIMOUT 属性中指定) ，那么 CICS 会向应用程序返回 TIMEDOUT 响应。如果将 DTIMOUT 设置为 NO，或者允许其使用缺省值 NO，表示应用程序准备无限期等待。

选项

CERTIFICATE(数据值)

指定要在 SSL 握手期间用作 SSL 客户机证书的 X.509 证书的标签。证书标签最多可以由 32 个字母数字字符组成。仅当指定 HTTPS 选项时，才与该选项相关。如果指定了 HTTPS ，但省略了 CERTIFICATE 选项，那么将使用在 CICS 区域用户标识的密钥环中定义的缺省证书。证书必须存储在外部安全性管理器的数据库的密钥环中。有关更多信息，请参阅手动构建密钥环。

CIPHERS(数据值) -不建议

指定最多包含 56 个十六进制数字的字符串，此字符串将被解释为一个最多 28 个双位密码套件代码的列表。当 SSL 对连接处于活动状态时，将使用密码套件代码，因此仅当指定了 HTTPS 选项时，此选项才相关。它们指示用于该连接的加密方法。

使用 NUMCIPHERS 选项来指定列表中的密码套件代码数。可用的代码取决于 ENCRYPTION 系统初始化参数指定的加密级别。如果您指定任何不属于活动加密级别的缺省列表的密码代码，那么将忽略这些代码。有关密码套件的更多信息，请参阅密码套件和密码套件规范文件。

注: 对于新编译，建议您在 URIMAP 定义中指定 SSL 密码套件规范文件，并使用 URIMAP 选项来引用 URIMAP 定义。在这种情况下，不需要 CIPHERS 选项。

避免同时使用 CIPHERS 选项和 URIMAP 选项。

当同时指定了 CIPHERS 选项和 URIMAP 选项时，将按如下所示确定要用于连接的密码套件:

如果 URIMAP 定义指定了 SSL 密码套件规范文件，那么将始终使用此密码套件规范文件。
如果 URIMAP 定义将十六进制值指定为密码套件代码列表，那么 URIMAP 定义中的设置将被 EXEC CICS WEB OPEN的 CIPHERS 选项覆盖。

如果您省略 CIPHERS 选项和 URIMAP 选项，但是为连接激活了 SSL，那么将使用正在运行的系统的加密级别的缺省密码列表。

CODEPAGE(数据值)

指定适用于应用程序的代码页。代码页名称可最多包含 8 个字母数字字符。缺省值是本地 CICS 区域的缺省代码页，如 LOCALCCSID 系统初始化参数中所指定。在此连接的持续时间内，该代码页适用。当服务器返回对 HTTP 请求的响应时，如果请求了转换 (这是缺省值) ，那么 CICS 会将请求主体转换为此代码页，然后再将其传递到应用程序。

此代码页名称的标准 CICS 格式由使用 3 编写的代码页号 (或更一般的 CCSID) 组成，必要时使用十进制数字 5 ，然后使用尾部空格填充到 8 个字符。对于少于 3 位数字的代码页 37，标准格式是 037。 CICS 还接受范围为 1 到 65535 的最多 8 位 (以尾随空格填充) 的任何十进制数作为代码页名称，即使它不是标准格式也是如此。

HOST(数据值)

指定您要连接到的服务器上的主机名。您可以使用 WEB PARSE URL 命令从已知 URL 中抽取此信息，也可以使用 INQUIRE URIMAP 命令从现有 URIMAP 定义中抽取此信息。您可以指定 URIMAP 选项以从现有的 URIMAP 定义中直接使用该信息，在这种情况下不需要 HOST 选项。仅当指定 URIMAP 选项时，才能合用客户机 HTTP 连接以供复用; 使用 HOST 选项不会启用连接池，即使从 URIMAP 定义中抽取信息也是如此。

如果在与 HTTP 服务器的连接中使用传输层安全性 (TLS) ，那么在 TLS 握手期间， CICS 会在服务器名称指示 (SNI) 扩展中传递主机名。这允许 CICS 使用与虚拟主机的 TLS 通信，其中服务器支持使用单个 IP 地址的多个虚拟主机。另请参阅 CICS Web Support 基本面: 虚拟托管。

字符主机名、IPv4 地址或 IPv6 地址可以表示主机名。如果指定 IPv6 地址（或可解析为 IPv6 地址的主机名），请确保您在双方式（IPv4 和 IPv6）环境中运行，并确保正与之通信的客户机或服务器也在双方式（IPv4 和 IPv6）环境中运行。

有关 IPv6的更多信息，请参阅了解 IPv6 和 CICS。

您可以多种格式指定 IPv4 和 IPv6 地址。有关 IP 地址的信息，请参阅 IP 地址。

如果您需要端口号，那么不能在 HOST 选项中包含该端口号。请改为使用 PORTNUMBER 选项。

可接受的字符：

字母数字字符，连字符 (-) ，冒号 (:) 或句点 (.)

不能在字符主机名中使用冒号 (:)。

HOSTLENGTH(数据值)

以全字二进制值的形式指定主机名的长度。如果使用 WEB PARSE URL 命令来解析 URL ，那么将返回此信息。您可以指定 URIMAP 选项以从现有的 URIMAP 定义中直接使用该信息，在这种情况下不需要 HOSTLENGTH 选项。

HTTPRNUM(数据区)

返回服务器的 HTTP 版本的发行版号（以半字二进制值的形式）。（HTTPVNUM 返回版本号。）例如，如果服务器处于 HTTP/1.0 级别，那么 HTTPRNUM 将返回 0。

HTTPVNUM(数据区)

返回服务器的 HTTP 版本的版本号（以半字二进制值的形式）。（HTTPRNUM 返回发行版号。）例如，如果服务器处于 HTTP/1.0 级别，那么 HTTPVNUM 将返回 1。

如果指定 HTTPVNUM 和 HTTPRNUM 选项，那么 CICS 将在打开与服务器的连接时获取 HTTP 版本信息。如果服务器未提供 HTTP 版本信息来响应此请求，或者版本低于 1.0，那么 CICS 假定它处于 HTTP/1.0 级别。

如果您必须检查 HTTP 版本信息以确认您应用程序的计划操作在其首个请求之前或期间是否将会成功，请指定这些选项。依赖于 HTTP 版本的操作包括：

编写请求某个操作（HTTP/1.1 级别以下的服务器可能无法正确执行此操作）的 HTTP 头
使用可能不适用于 HTTP/1.1 级别以下的服务器的 HTTP 方法
使用分块的传输编码
发送由管道传送的序列的请求

CICS 为获取 HTTP 版本信息而发出的其他 HTTP 请求会影响性能，因此，如果在此阶段不需要这些选项，请不要指定这些选项。从服务器收到第一个响应时，您可以使用 WEB EXTRACT 命令获取该信息。

NUMCIPHERS(数据值)

以半字二进制值的形式指定您为 CIPHERS 选项指定的密码套件代码的数目。

PORTNUMBER(数据值)

以全字二进制值的形式指定端口号。指定不是指定方案的缺省值的端口号。对于 HTTP，缺省端口号为 80；对于 HTTPS，缺省端口号为 443。可以使用 WEB PARSE URL 命令从已知 URL 中抽取端口号信息，也可以使用 INQUIRE URIMAP 命令从现有 URIMAP 定义中抽取端口号信息。您可以指定 URIMAP 选项以从现有的 URIMAP 定义中直接使用该信息，在这种情况下不需要 PORTNUMBER 选项。仅当指定 URIMAP 选项时，才能将客户机 HTTP 连接放入池中以供复用；使用 PORTNUMBER 选项并不会启用连接池，即使您从 URIMAP 定义中抽取该信息。

SCHEME(cvda)

指定要用于连接服务器的方案（可带有 SSL，也可不带 SSL）。 CVDA 值如下：

HTTP: HTTP 协议，不带 SSL。
HTTPS: HTTPS 协议，即带有 SSL 的 HTTP。如果使用 HTTPS ，那么必须对 CICS 地址空间启用 SSL。

可以使用 WEB PARSE URL 命令从已知 URL 中抽取此信息，也可以使用 INQUIRE URIMAP 命令从现有 URIMAP 定义中抽取此信息。您可以指定 URIMAP 选项以从现有的 URIMAP 定义中直接使用该信息，在这种情况下不需要 SCHEME 选项。仅当您指定 URIMAP 选项时，才能合用客户机 HTTP 连接; 使用 SCHEME 选项不会启用连接池，即使您从 URIMAP 定义中抽取信息也是如此。

SESSTOKEN(数据区)

返回会话令牌，这是一个 8 字节的二进制值，用于唯一地标识此应用程序对 CICS 与服务器之间的连接的使用。必须在与此连接相关的所有 CICS WEB 命令上使用会话令牌。有关使用会话令牌的信息，请参阅会话令牌。

URIMAP(数据值)

指定用于提供以下信息的 URIMAP 定义的名称（最多包含 8 个字符，混合大小写）：

要用于连接服务器的方案。
要连接到的服务器上的主机名。
端口号（如果需要）。
URI 的路径部分，表示您要访问的服务器上的资源。该路径将成为与该连接相关的 WEB SEND 或 WEB CONVERSE 命令的缺省路径，但是可以通过在 WEB SEND 或 WEB CONVERSE 命令上指定其他路径来覆盖。
使用 URIMAP 资源打开的合用连接的到期期限。当您使用 SOCKETCLOSE 属性在 URIMAP 定义中指定到期期限，并且在 WEB OPEN 命令上指定 URIMAP 资源时，将启用连接池。
要用作 SSL 客户机证书的 X.509 证书的标签（如果需要）。
可用于该连接的密码套件代码。
如果要使用 SSL 密码套件规范文件，那么必须对连接使用 URIMAP 定义。 EXEC CICS WEB OPEN 不支持在 CIPHERS 选项中使用密码套件规范文件。

如果指定了 URIMAP 选项，请不要指定 CERTIFICATE、HOST、HOSTLENGTH、PORTNUMBER、PORTLENGTH 或 SCHEME 选项。

如果指定了 URIMAP 选项，请避免指定 CIPHERS 选项。

当同时指定了 CIPHERS 选项和 URIMAP 选项时，将按如下所示确定要用于连接的密码套件:

如果 URIMAP 定义指定了 SSL 密码套件规范文件，那么将始终使用此密码套件规范文件。
如果 URIMAP 定义将十六进制值指定为密码套件代码列表，那么 URIMAP 定义中的设置将被 EXEC CICS WEB OPEN的 CIPHERS 选项覆盖。

URIMAP 定义必须用于指定了 USAGE (CLIENT) 的作为 HTTP 客户机的 CICS 。

条件

17 IOERR

RESP2 值：

38: 代理错误。
42: 套接字错误。存在连接问题。

16 INVREQ

RESP2 值：

14: 代码页不正确。
22: 在使用 OPTIONS 方法的初始 HTTP 请求期间收到错误的分块。
23: 不正确的客户机证书。
40: 方案不正确。
41: 在使用 OPTIONS 方法的初始 HTTP 请求期间服务器关闭了连接。
48: 主机选项的格式不正确。
63: URIMAP 对象不可用。
66: 处理 XWBOPEN 出口时发生错误。
67: 响应的内容不符合 HTTP 格式。生成此错误是因为存在语法问题。
96: 不支持 SSL。
137: 所有请求的密码代码都已被拒绝。
138: 端口号大于 65535。
144: 一个或多个 Web 命令参数不正确。

22 LENGERR

RESP2 值：

21: 主机长度不正确。

13 NOTFND

RESP2 值：

20: 名称服务器未解析主机名，或者主机选项的格式不正确。
39: 未知代理。
61: 未找到指定的 URIMAP 对象。

70 NOTAUTH

RESP2 值：

100: 安全性出口禁止的主机名。

124 TIMEDOUT

RESP2 值：

62: 接收套接字时出现超时。