INVOKE SERVICE

从 CICS® 应用程序调用服务。 该命令指定服务或 CICS 资源（如 WEBSERVICE 资源）的名称，该 CICS 资源包含有关要调用的服务的信息。

语法

INVOKE SERVICE

读取语法图跳过可视语法图INVOKE SERVICE( data-value) CHANNEL( data-value)OPERATION( data-value)URI( data-value)URIMAP( data-value)SCOPE( data-value)SCOPELEN( data-value)

条件: INVREQ ， LENGERR ， NOTFND 和 TIMEDOUT

此命令是线程安全的。

NOHANDLE、RESP 和 RESP2是常用选项，可添加到所有 EXEC CICS 命令中以处理错误条件。 命令语法图和选项说明中没有明确包含这些选项。 有关这些常用选项和 EXEC CICS 命令语法的信息，请参阅 EXEC CICS 命令格式和编程注意事项.

描述

在 CICS 应用程序中使用 INVOKE SERVICE 命令来调用服务; 例如，应用程序可以充当 Web Service 请求者并调用基于 XML 的服务，或者应用程序可以调用另一个充当基于通道的服务的 CICS 应用程序。 有关这两种服务类型的更多信息，请参阅 从 CICS 应用程序创建业务服务。

将此命令用于所有新的 Web Service 应用程序，而不是 INVOKE WEBSERVICE 命令 (这是同义词)。 如果将此命令用于 Web Service ，那么必须将特定容器作为输入提供给 CICS 。 有关编写 Web Service 应用程序的更多信息，请参阅 开发 SOAP Web Service。

调用服务时，可以指定包含有关服务 URI 的信息的 URIMAP 资源。 您可以直接在 INVOKE SERVICE 命令上指定此信息，而不是使用 URIMAP 资源。 但是，使用 URIMAP 资源具有以下优势：
  • 系统管理员可以管理对连接端点的任何更改，因此如果服务提供者的 URI 发生更改，那么您无需重新编译应用程序。
  • 您可以选择使 CICS 使使用 URIMAP 资源打开的连接在使用后保持打开状态，并将它们放在池中以供应用程序用于后续请求或由调用同一服务的其他应用程序复用。 只有在指定设置了 SOCKETCLOSE 属性的 URIMAP 资源时，连接池才可用。 有关连接池性能优势的更多信息，请参阅 HTTP性能的连接池》。

如果未在 INVOKE SERVICE 命令中指定 URIMAP ，那么 CICS 会尝试查找与 USAGE (CLIENT) 匹配的 URIMAP。 CICS 根据当前请求的主机，端口和路径搜索匹配的 URIMAP。 如果找到一个，那么将使用此 URIMAP。 如果找到多个与主机，端口和路径匹配的 URIMAP ，那么将使用最早安装的 URIMAP。 因此，作为最佳实践，始终按名称使用 URIMAP ，尤其是在系统中启用了多个指向同一端点的 URIMAP 时。

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

INVOKE 服务和 INVOKE 服务

INVOKE WEBSERVICE 是 INVOKE SERVICE 命令的同义词，与现有网络服务请求程序兼容。 在任何新的网络服务应用程序中使用 INVOKE SERVICE

选项

CHANNEL（ 数据值 ）
指定用于传递容器的通道的名称，这些容器保存由应用程序数据结构映射的数据。 返回时，同一通道保存来自 Web Service 的响应，该响应再次由应用程序数据结构映射。 通道的名称最多可包含 16 个字符。 如果 name 是变量，并且它包含少于 16 个字符的名称，那么必须使用尾部空格来填充该变量。 您可以指定通道名称 DFHTRANSACTION 以使用事务通道。
OPERATION（ 数据值 ）
指定包含要调用的操作的名称的数据区。 操作的名称包含在目标 Web Service 的 WSDL 中。 数据区的长度必须为 255 个字符; 如果操作名称小于 255 个字符，那么必须使用尾部空格来填充数据区。
SERVICE（ 数据值 ）
指定服务的名称:
  • 如果要调用 Web Service ，请指定用于定义该 Web Service 的 WEBSERVICE 资源的名称。 WEBSERVICE 资源指定 CICS 在与 Web Service 通信时使用的 Web Service 描述和 Web Service 绑定文件的位置。 WEBSERVICE 资源的名称最多可包含 32 个字符。 如果少于 32 个字符，那么必须使用尾部空格填充该值。
  • 如果要调用基于通道的服务，请指定服务的名称。 服务的格式为 URI。 该名称最多可包含 32 个字符。 如果少于 32 个字符，那么必须使用尾部空格填充该值。
SCOPE（ 数据值 ）
充当服务名称的限定前缀。 如果您正在使用基于服务组件体系结构 (SCA) 通道的服务，并且需要额外的前缀来标识该服务，请使用 SCOPE 。
注: SCOPE 仅适用于基于通道的服务。
如果您编写的 COBOL 程序是用 COBOL3 翻译器选项翻译的，则数据值的长度不能超过 160 字节。 如果使用 COBOL2 翻译器选项，则必须使用数据区而不是数据值。
SCOPELEN（ 数据值 ）
一个全字二进制值，用于指定以服务名称为前缀的作用域的长度。
URI（ 数据值 ）
指定包含要调用的服务的 URI 的数据区。 如果指定了此选项，那么它将取代 WEBSERVICE 资源定义中指定的任何 URI。 如果同时省略此选项和 URIMAP 选项，那么与资源定义相关联的 WEBSERVICE 绑定文件必须包含提供程序 URI 或提供程序应用程序名称。 数据区的长度必须为 255 个字符; 如果 URI 小于 255 个字符，那么必须使用尾部空格来填充数据区。 有关URI格式的信息，请参阅 URL组成部分。
请勿对使用 WS-Addressing 的 Web Service 指定此选项。
如果使用连接池，请勿指定此选项; 而是使用 URIMAP 选项来指定相应的 URIMAP 资源以启用连接池。
URIMAP（ 数据值 ）
指定 CICS 用于派生 URI 值的 URIMAP 资源的名称。 如果您想启用连接池，请使用URIMAP资源， CICS 将保持客户端 HTTP打开，以便此应用程序或其他应用程序重复使用。 如果指定了此选项，那么它将取代 WEBSERVICE 资源定义中指定的任何 URI。 如果同时省略此选项和 URI 选项，那么与资源定义相关联的 WEBSERVICE 绑定文件必须包含提供程序 URI 或提供程序应用程序名称。
您必须为 HTTP创建URIMAP资源，并指定属性USAGE(CLIENT)。 对于连接池，还必须设置 SOCKETCLOSE 属性。 CICS Web 服务助手不会创建 URIMAP 资源，因此您必须自行定义它。 有关为客户端请求创建URIMAP资源的信息，请参阅 CICS 创建URIMAP资源作为 HTTP。
请勿对使用 WS-Addressing 的 Web Service 指定此选项。

条件

16 INVREQ
RESP2 值：
1
为 CHANNEL 选项指定的名称包含非法字符或字符组合。
2
为 OPERATION 选项指定的名称包含非法字符或字符组合。
3
与 WEBSERVICE 关联的 Web Service 绑定文件无效。
4
为 URI 指定的值包含非法字符或字符组合，或者无法解析指定的主机名。
5
WEBSERVICE 所使用的 PIPELINE 定义为服务请求者管道，但在服务提供者中调用， 反之亦然。
6
调用的 WEBSERVICE 返回了 SOAP 故障。 在容器 DFHWS-BODY 中提供了故障的 XML 格式描述。
注: 对于 XML-ONLY Web Service 调用，不会提出此条件。
7
未在命令上指定 URI 选项，并且 WEBSERVICE 定义未指定 URI 或程序名。
8
WEBSERVICE 未在服务中
9
容器没有正确的 DATATYPE。 这可能是 DFHWS-DATA 容器，也可能是应用程序数据中引用的另一个容器。 必须以 BIT 方式填充 DFHWS-DATA 容器和大多数其他应用程序数据容器。 必须以 CHAR 方式填充任何包含 XML 标记的容器。
10
未启用 WEBSERVICE 所使用的 PIPELINE。
11
CICS 无法链接到 WEBSERVICE 定义中指定的程序。
12
命令期望的容器不在正确的通道上。
13
检测到输入错误，正在生成 SOAP 请求消息或处理 SOAP 响应消息。 将 DFHPIxxxx 消息写入 MSGUSR 以更详细地记录问题。 应用程序数据结构可能包含无法转换为 SOAP 请求消息的无效数据。 有关更多信息，请参阅 DFH-XML-ERRORMSG 容器中的错误消息。
14
CICS 尝试在应用程序数据结构与 SOAP 消息之间进行转换时发生转换错误。 应用程序数据结构包含无法转换为 SOAP 请求的无效数据，或者 SOAP 响应消息中的数据无法转换为应用程序的数据结构。 此情况的一些可能的原因是:
  • SOAP 响应消息中的值大于应用程序数据结构中的相应字段。
  • 构建 SOAP 请求时， Web Service 绑定文件指示数据字段包含压缩十进制或分区十进制数据，并且该字段的内容对此数据类型无效。

将 DFHPIxxxx 消息写入 MSGUSR 以更详细地记录问题。 有关更多信息，请参阅 DFH-XML-ERRORMSG 容器中的错误消息。

15
管道中发生了未处理的错误。 有关错误的信息在容器 DFHERROR 中。
16
本地优化的 Web Service 已异常结束。 已回退底层工作单元。
17 日
远程 Web Service 请求未返回响应消息。
18
容器 DFHWS-BODY 尚未由 XML-ONLY WEBSERVICE 的应用程序填充。
19
已指定 URI 或 URIMAP ，但当 WEBSERVICE 资源具有缺省 WS-Addressing 端点引用或已使用 WSACONTEXT BUILD API 命令构建 WS-Addressing 上下文时，不允许使用此选项。
20
指定的 URIMAP 没有有效的方案。
21
指定的 URIMAP 不是客户机方式。
22
未启用指定的 URIMAP。
23
尝试使用管道时发生未指定的传输或链路故障。 CICS 发出一条消息来记录特定问题。
24
已使用 z/OS® Connect 管道。
41
连接已关闭。
101
容器 DFHWS-BODY 没有正确的 DATATYPE。 对于此容器，必须指定 CHAR 的 DATATYPE。
103
容器 DFHWS-BODY 不包含任何数据。
104
缺少容器 DFHREQUEST 或容器 DFHWS-BODY 。
105
在 WEBSERVICE 使用的服务请求者 PIPELINE 中构建了故障 (在发送请求时或在处理响应时)。 此情况可能指示头处理程序已发出故障。
106
生成的 SOAP 请求消息的格式不正确，或者 SOAP 响应消息的格式不正确。 此情况可能指示 XML 解析器返回了致命错误代码。
107
生成的 SOAP 请求消息不是有效的 SOAP 消息，或者 SOAP 响应消息不是有效的 SOAP 消息。
108
发生 HTTP 错误。 使用DFHRESPONSE容器中的 HTTP来诊断 HTTP的原因。
109
109 HTTP 重定向 （301、 302、303或307）响应已返回。 位置头在 DFHWS-LOCATION 容器中可用。
可以将 HTTP 的响应自动重定向到 DFHWS-LOCATION 中包含的信息。 为此，请在管道配置文件的 default_http_transport_handler_list 元素中添加 follow_redirects="true" ，如下例所示：
<default_http_transport_handler_list follow_redirects="true" />
CICS 将跟进最多三次重定向。
22 LENGERR
RESP 2 值:
1
未指定 SCOPELEN 选项或它不是有效值。
13 NOTFND
RESP2 值：
1
与 WEBSERVICE 关联的 Web Service 绑定文件指定由另一产品提供的 SOAP 消息解析程序的名称，但找不到解析程序。
2
找不到指定的 CHANNEL。
3
指定的 OPERATION 不在 Web Service 绑定文件中。
4
找不到指定的 WEBSERVICE。
5
找不到在 Web Service 绑定文件中指定的 CONTAINER。
6
找不到指定的 URIMAP。
124 TIMEDOUT
RESP2 值：
1
发生了预期的超时。 当消息交换模式指定可选错误响应，并且未从远程 Web Service 返回错误响应时，可接受超时。
2
发生意外超时。 期望来自远程 Web Service 的响应，但未收到任何响应。
62
套接字接收时发生意外超时。