DPL_Request

参数

版本数

一个全字二进制输入区域，指示正在使用的外部 CICS 接口参数列表的版本。 可以在客户机程序中设置为 1 ， 2 或 3。

CICS提供的副本 DFHXCPL x (其中 x 指示语言) 中此参数的等同值为 VERSION_1， VERSION_2或 VERSION_3。 请参阅 返回区域和函数调用 EQUATE 副本 以获取副本详细信息。

返回区域

用于接收响应和原因码的 5 字输出区域以及消息指针字段。 有关更多详细信息，请参阅 EXCI CALL 接口的返回区域。

用户令牌

1 字输入区域，用于指定在 Initialize_User 命令上返回到客户机程序的用户令牌。

call_type

指示命令功能的 1 字输入区域。 这必须在客户机程序中设置为 6 ，以指示管道现在正用于 DPL_Request 调用。

CICS提供的副本 DFHXCPL x (其中 x 指示语言) 中此调用的等同值为 DPL_REQUEST。 请参阅 返回区域和函数调用 EQUATE 副本 以获取副本详细信息。

管道令牌

1 字输入区域，用于指定 EXCI 在 Allocate_Pipe 命令上返回的令牌。 它表示用于 DPL_Request 调用的管道。

PGMNAME

要作为服务器程序调用的 CICS 应用程序的 8 字符名称。

这是在安装在 CICS 服务器区域中的预定义 PROGRAM 资源定义上指定的名称，如果要自动安装该程序，那么这是用户编写的自动安装程序已知的名称。 该程序可以在 CICS 服务器区域中定义为本地程序，也可以定义为远程程序。 定义为远程启用 daisy-chining 的程序，其中 EXCI-CICS DPL 调用变为 EXCI-CICS-CICS DPL 调用。

COMMAREA (或 null_ptr)

客户机和服务器程序之间的通信区 (COMMAREA) 的可变长度输入区。 长度由 COMMAREA_len定义。

这是包含要发送到 CICS 应用程序的数据的存储区域。 此区域还用于从 CICS 应用程序 (服务器程序) 接收更新的 COMMAREA。

该参数是可选的。 如果不需要此参数，那么必须确保 CALL 参数列表包含此参数的空地址。 执行此操作的方式取决于您用于非CICS 客户机程序的语言。 有关省略可选参数的调用的示例，请参阅 带有空参数的 EXCI CALL 示例。

COMMAREA_长度

全字二进制输入区域。 此参数指定 COMMAREA 的长度。 它也是服务器程序的 COMMAREA (EIBCALEN) 的长度。

如果指定 COMMAREA ，那么还必须指定此参数以定义长度。

如果要在任何两个 CICS 服务器之间传递 COMMAREA (对于产品/版本/发行版的任何组合) ，那么此值不应超过 24 KB。 否则，如果您确信将不会在另一 LINK 请求上传递 COMMAREA ，那么可以使用最大长度为 32 KB 的 COMMAREA。

如果未指定 COMMAREA ，那么将忽略此参数。

数据长度

全字二进制输入区域。 此参数指定从 COMMAREA 开始要发送到服务器程序的连续存储器的长度。

此参数限制发送到服务器程序的数据量，并且应该用于优化性能 (例如，如果 COMMAREA 较大但传递的数据量较小)。

从服务器程序返回时， EXCI 数据变换器程序确保非CICS 客户机程序中的 COMMAREA 与服务器程序的 COMMAREA 相同。 这将满足以下条件:

• 返回的数据超过在原始 COMMAREA 中传递的数据。
• 返回的数据小于在原始 COMMAREA 中传递的数据。
• 由于未更改，因此未返回任何数据。
• 服务器正在返回空数据。

data_len 的值不得大于 COMMAREA_len 的值。 值为零是有效的，因此不会将任何数据发送到服务器程序。

如果未指定 COMMAREA ，那么将忽略此参数。

CHANNEL

16 个字符的输入区域，其中包含要提供给被调用程序的通道的名称。 允许使用的字符为 A - Z、a - z、0 - 9、$、@、#、/、%、&、?、!、:、|、"、=、¬、,、;、<、>、.、- 和 _。不允许出现开头和嵌套的空格字符。 如果提供的名称少于 16 个字符，那么将使用最多 16 个字符的尾部空格来填充该名称。 如果该通道不存在，那么将创建该通道。 由于 EXCI 客户机只有一个 LINK 级别，因此此通道仍在作用域内。 有关通道作用域的更多信息，请参阅 通道作用域。

通道名称始终采用 EBCDIC。 前面列出的通道名称所允许的字符集包含在所有 EBCDIC 代码页中不具有相同表示法的一些字符。 因此，若需在不同区域间传输频道，建议将频道命名所用字符限制为 A-Z、a-z、0-9 及 & : =,; < >. - 和 _。

可以指定通道名称 DFHTRANSACTION 以使用事务通道。 在 CICS中，当链路级别发生更改时，事务通道不会超出作用域: 它在事务中始终可访问。 有关更多信息，请参阅 通道和容器。

发出 DPL_REQUEST 命令的程序可以在命令上指定通道的名称。 指定的通道可能已存在，由程序使用一个或多个 PUT CONTAINER 命令创建。 或者，程序可以指定当前不存在的通道的名称，在这种情况下将创建新的空通道。

注: CHANNEL 后面的两个参数必须为空。 此外， ccsid 和 endian 参数必须为空。

transid (或 null_ptr)

4 字符输入区域，其中包含要运行服务器程序的 CICS 镜像事务的标识。 必须将此事务定义到 CICS 服务器区域，并且其定义必须指定:

程序 (DFHMIRS)

初始程序必须是 CICS 提供的镜像程序 DFHMIRS。

未能将 DFHMIRS 指定为初始程序意味着不会将从客户机应用程序传递的 COMMAREA 传递到 CICS 服务器程序。 此外， DPL 请求失败，并且客户机应用程序接收到响应 SYSTEM_ERROR 和 reason SERVER_PROTOCOL_ERROR。

概要文件 (DFHCICSA)

DFHCICSA 概要文件指定 INBFMH 参数的正确值，对于镜像事务，该参数必须指定为 INBFMH (ALL)。

当 CICS 服务器区域接收到 DPL 请求时，它将连接镜像事务并调用 DFHMIRS。 然后，镜像程序将控制权传递给请求的服务器程序，并传递客户机程序提供的 COMMAREA。 传递到服务器程序的 COMMAREA 仅准备了数据， COMMAREA 的其余部分设置为空。

Transid 参数的目的是区分服务器程序的不同调用。 这使您能够在指定不同属性的事务下运行服务器程序的不同调用。 例如，您可以更改事务优先级或安全性需求。

转换是可选的。 缺省情况下， CICS 服务器区域使用 CICS提供的镜像事务 CSMI。 如果不想指定 transid ，那么必须确保 CALL 参数列表包含此参数的空地址。 执行此操作的方式取决于您用于非CICS 客户机程序的语言。 有关省略可选参数的调用的示例，请参阅 带有空参数的 EXCI CALL 示例。

如果在同一 z/OS® 恢复单元中发出多个请求，那么必须在所有这些请求中使用相同的 transid。

uowid (或 null_ptr)

包含工作单元标识 (使用 APPC 体系结构格式) 的输入区域，在 DPL_Request 上传递此标识以用于相关目的。

对于在 CICS 程序将控制权返回给 z/OS 应用程序时落实的 DPL 请求，此参数是可选的。

对于属于 RRMS 恢复单元的 DPL 请求，必须指定 null_ptr。 如果存在与 RRMS 恢复单元相关联的工作单元标识，那么将使用该标识; 如果没有此标识，那么 CICS (或另一个 RRMS 资源管理器) 将生成唯一的工作单元标识，并将其与 RRMS 恢复单元相关联。

如果不想指定 uowid 参数，那么必须确保 CALL 参数列表包含此参数的空地址。 执行此操作的方式取决于您用于非CICS 客户机程序的语言。 有关省略可选参数的调用的示例，请参阅 带有空参数的 EXCI CALL 示例。

uowid 参数传递到 CICS 服务器区域，该区域将其用作 CICS 服务器程序执行的第一个工作单元的 UOWID。 如果服务器程序在返回到客户机程序之前发出中间同步点，那么 CICS 会将提供的 uowid 用于后续工作单元，但每个新的逻辑工作单元的双字节序号递增。 如果 CICS 服务器程序更新远程资源，那么客户机提供的 UOWID 将分发给拥有这些资源的远程系统。

在 EXCI CALL 接口上提供 uowid 参数仅用于关联目的，以允许在 CICS 中标识源自特定客户机程序的工作单元。 uowid 不是为了在 CICS 和客户机程序之间进行恢复而提供的。

uowid 的最大长度可以为 27 个字节，并且具有以下格式:

• 1 字节长度字段，包含 UOWID 的整体长度 (不包括此字段)。
• 包含逻辑单元名称长度 (不包括此字段) 的 1 字节长度字段。
• 最大长度为 17 个字节的可变长度逻辑单元名称字段。
  要符合 APPC 体系结构规则， LUNAME 的格式必须为 AAAAAAAA.BBBBBBBB ，其中 AAAAAAAA 是可选的，并且:

  • AAAAAAAA 和 BBBBBBBBBB 是由句点分隔的 8 字节名称
  • 如果省略了 AAAAAAAA ，那么还必须省略该句点
  • AAAAAAAA 和 BBBBBBBB 必须是 type-1134 符号字符串 (即，由一个或多个 EBCDIC 大写字母 A-Z 和 0-9 组成的字符串，其第一个字符必须是大写字母)。
• 时钟值; 8 字节存储时钟 (STCK) 值的中间 6 字节。
• 2 字节的序号。

如果省略工作单元标识 (通过指定空指针) ，并且 DPL 请求不是 RRMS 恢复单元的一部分，那么外部 CICS 接口将为您生成一个由以下内容组成的接口:

• 一个长度为1字节的字段被设置为 X'1A'。
• 1 字节 LU 长度字段设置为 X'11 '。
• 由下列各项组成的 17 字节 LU 名:
  • 8 字节的 eyecatcher 设置为 DFHEXCIU。
  • 包含句点 (.) 的 1 字节字段
  • 4 字节字段，其中包含运行客户机的 z/OS 系统标识 (SYSID) (以字符计)。
  • 包含正在其中运行 z/OS 客户机程序的地址空间标识 (ASID) 的 4 字节字段。 该字段包含 2 字节十六进制地址空间标识的四字符 EBCDIC 表示。
• 时钟值; 8 字节存储时钟 (STCK) 值的中间 6 字节
• 设置为 X'0001 '的 2 字节序号。

userid (或 null_ptr)

一个 8 字符输入区域，其中包含用于在 CICS 区域中进行用户安全性检查的 RACF® 用户标识。 外部 CICS 接口将此用户标识传递到 CICS 服务器区域，以便在服务器应用程序中进行用户资源和命令安全性检查。

仅当 MRO 连接指定 ATTACHSEC (IDENTIFY) 属性时，才需要用户标识。 如果连接指定 ATTACHSEC (LOCAL) ，那么 CICS 服务器区域将应用链路安全性检查。 有关 MRO 连接上的链路安全性的信息，请参阅 Intercommunication security 。

另请参阅 EXCI 安全性 ，以获取有关外部 CICS 接口安全性注意事项的信息。

该参数是可选的。 但是，如果未指定用户标识，那么外部 CICS 接口将传递正在运行客户机程序的安全用户标识。 例如，如果客户机程序作为 z/OS 批处理作业运行，那么外部 CICS 接口将获取并传递在 JOB 语句的 USER 参数上指定的用户标识。

如果指定用户标识，那么用于运行 EXCI 作业的用户标识将接受代理用户检查。 此检查由外部 CICS 接口执行，以确保客户机作业用户标识有权使用在 DPL 调用上指定的用户标识。 有关代理用户安全性检查的更多信息，请参阅 EXCI 安全性。

如果要将 userid 设置为缺省值，那么必须确保 CALL 参数列表包含此参数的空地址。 执行此操作的方式取决于您用于非CICS 客户机程序的语言。 有关省略可选参数的调用的示例，请参阅 带有空参数的 EXCI CALL 示例。

如果在同一 z/OS 恢复单元中发出多个请求，那么必须在所有这些请求中使用相同的用户标识。 如果恢复单元还包含 EXEC CICS 调用，那么应允许所有 DPL_requests 上的用户标识缺省为正在运行客户机程序的安全用户标识。

dpl_rerea

DPL_Request 处理器将响应放入 DPL 请求的 12 字节输出区域。 通常，这些响应来自 CICS ，但在某些情况下，错误检测发生在外部 CICS 接口中，这将返回与 EXEC CICS LINK 命令返回的异常条件等效的异常条件。

仅在以下情况下，此字段才有意义:

• EXCI 返回区域的响应字段具有零值
• EXCI 返回区域指示服务器程序已异常结束 (响应 = USER_ERROR ，原因 = SERVER_AB已结束)。

12 个字节组成三个字段，提供以下信息:

字段 1 ( 全字值 )

此字段是包含来自 DPL_Request 调用的 RESP 值的全字。 有关可在 DPL_Request 调用上返回的 RESP 值，请参阅 错误代码 。

如果 DPL_Request 调用到达 CICS ，那么此字段包含 EIBRESP 值，否则包含外部 CICS 接口设置的等效响应。 如果此字段由外部 CICS 接口设置，那么 RESP 将由第二个字段中的 RESP2 值进一步限定。

零值是正常响应，在返回码副本中等同于 EXEC_NORMAL。

字段 2 ( 全字值 )

此字段是一个全字，可以包含链接请求中的 RESP2 值，从而进一步限定字段 1 中的 RESP 值。

如果 DPL_Request 调用到达 CICS ，那么 RESP2 字段通常为空 ( CICS 不会返回跨 MRO 链接的 RESP2 值)。 但是，如果 RESP 字段指示 SYSIDERR (值 53) ，那么此字段将提供原因码。 请参阅 Dpl_rerea 返回码 以获取更多信息。

如果 RESP 字段由外部 CICS 接口设置，那么该字段将由第二个字段中的 RESP2 值进一步限定。 例如，如果 data_len 参数指定的值大于 COMMAREA_len 参数，那么外部 CICS 接口将返回 RESP 值 22 (在返回码副本中等于 EXEC_LENGERR) 和 RESP2 值 13。

请参阅 LINK 中的 LINK 条件，以获取可能的 RESP 和 RESP2 值的完整详细信息。

注: 数据变换器程序特别使用 RESP2 字段。 如果在变换器中发生任何错误，那么将在 RESP2中返回该错误。

字段 3 ( 全字值 )

第三个字段 (4 字符字段) 包含以下信息:

• 服务器程序异常终止时的异常终止代码
• 如果服务器程序未异常终止，那么为 4 个空白。

如果服务器程序异常终止，那么它将回退到其最后一个同步点 (可以是任务的开始) 或中间同步点。 由于强制 SYNCONRETURN ，因此服务器程序可以发出中间同步点。

DPL_opts (或 null_ptr)

1 字节输入区域，指示要在 DPL_Request 调用上使用的选项。

如果省略此参数，那么它将缺省为值 X'00 '。 如果要省略 DPL_opts 并将其设置为缺省值，请确保 CALL 参数列表包含此参数的空地址。 如何执行此操作取决于您用于非CICS 程序的语言。 有关省略可选参数的调用的示例，请参阅 带有空参数的 EXCI CALL 示例。

当前， DPL_opts 参数仅适用于资源恢复，使用以下值:

X'00 '

指示您指定了 NOSYNCONRETURN ，因为您希望客户机批处理程序使用 z/OS RRS 支持的 2 阶段落实协议来控制资源恢复。 使用此选项，当服务器程序将控制权返回给 CICS 时， CICS 服务器区域不会执行同步点。 此外， CICS 服务器应用程序不得采用任何显式同步点，否则会被 CICS 异常终止。 有关更多信息，请参阅 资源恢复。

X'80 '

指示在 CICS 服务器区域中需要 SYNCONRETURN。

SYNCONRETURN 指定服务器区域将在成功完成服务器程序时采用同步点，而与客户机程序无关。 此选项不会阻止服务器程序获取其自己的显式同步点。

CICS提供的副本 DFHXCPL x (其中 x 指示语言) 中此参数的等同值为 SYNCONRETURN。 请参阅 返回区域和函数调用 EQUATE 副本 以获取副本详细信息。

transid2 (或 null_ptr) 适用于 VERSION_2 或更高版本

包含 CICS 事务标识的 4 字符输入区域。

服务器程序在 CICS 提供的镜像事务 CSMI 或 CPMI 下运行。 但是，通过 Exec 接口块中的 EIBTRNID 字段提供给服务器程序的事务标识是由 transid2 参数指定的标识。 如果指定了 transid 参数，那么将忽略 transid2 参数。 下表提供了 transid 和 transid2 的不同组合的示例:

表 1. 使用 transid2

事务ID	transid2	程序执行依据	程序看到的 EIBTRNID
UTRN	省略	UTRN	UTRN
UTRN	欧洲投资银行	UTRN	UTRN
省略	省略	CSMI	CSMI
省略	欧洲投资银行	CSMI	欧洲投资银行

transid2 参数对于访问 Db2®的服务器程序很有用，因为 EIBTRNID 用于确定要使用的 DB2ENTRY 定义。 先前，只能使用 transid 来设置 EIBTRNID ，这要求您定义到 CICS 的镜像事务。 通过使用 transid2 ，设置了 EIBTRNID ，但镜像程序在 CICS 提供的定义 CSMI 下执行。

ccsid (或 null_ptr) VERSION_2 仅

一个全字二进制输入区域，指示 COMMAREA 中包含的字符数据的编码字符集标识 (CCSID)。 如果在将 COMMAREA 传递至服务器程序或从服务器程序返回时必须转换字符数据，那么必须指定 ccsid 参数。 该参数可以采用以下值:

- -1 ')

指示需要转换字符数据，并且在服务器中安装的转换模板中定义了源 CCSID。

1 ≤ ccsid ≤ 65535

指示需要转换字符数据，并且指定的值将覆盖在服务器中安装的转换模板中定义的源 CCSID。

endian (或 null_ptr) VERSION_2 仅

全字二进制输入区域，用于指示 COMMAREA 中包含的二进制数据的格式 (大尾数法或小尾数法)。 大尾数法指示最左边的字节包含最有效的数字，例如，在 System 390 体系结构中使用。 小尾数法指示最右边的字节包含最重要的数字，例如在 Intel 体系结构中使用的数字。 如果在将 COMMAREA 传递到服务器程序或从服务器程序返回时必须转换二进制数据，那么应指定 endian 参数。 如果 ccsid 参数指示需要转换，但未指定 endian (缺省为 null) ，那么二进制数据的转换取决于在服务器中安装的 DFHCNV 转换模板中指定的内容。 该参数可以采用以下值:

16909060 (X'01020304 ')

二进制数据以大尾数法格式保存。

67305985 (X'04030201 ')

二进制数据以小尾数法格式保存。

响应和原因码

对于所有非零响应代码，唯一原因码值标识响应的原因。