进行 XPI 调用

XPI 调用有两组参数: 输入参数 (包括 XPI 函数调用和传递给调用的参数) 和输出参数 (通过这些参数， CICS ® 可以向您返回值，包括用于指示调用是否成功的响应和原因码)。

要使用 XPI 宏调用，必须包含用于定义输入和输出参数的副本。宏的名称始终采用格式 DFHxxyyX ，并且关联的副本具有名称 DFHxxyyY。例如， GETMAIN 调用是存储控制 XPI 的一部分。您将使用的宏是 DFHSMMCX ，关联的副本是 DFHSMMCY。

所有 XPI 调用的常规格式 (省略汇编语言连续字符) 为:

        macro-name [CALL],
                   [CLEAR],
                   [IN,
                   FUNCTION(call_name),
                   mandin1(value),
                   mandin2(value),
                   …
                   [optin1(value),]
                   [optin2(value),]
                   …]
                   [OUT,
                   mandout1(value),
                   mandout2(value),
                   …
                   [optout1(value),]
                   [optout2(value),]
                   …
                   RESPONSE,
                   REASON]

XPI 调用遵循汇编语言编码约定:

"macro-name" 必须在第 16 列之前开始。
连续行必须以第 16 列开始。
除了宏名称和第一个关键字 (通常为 CALL) 之间的空格之外，不能有任何嵌入的空格。
除最后一行以外的行上的条目必须以逗号结尾。
除最后一行以外的行必须在第 72 列中具有连续字符。
需要将输入和输出值括在括号内-如果使用寄存器引用作为输入或输出值，那么必须将其括在一对内部括号中，因此: ((R6))。
有关如何设置 XPI 选项的值的详细信息，请参阅 XPI 语法。

这些 XPI 函数有三种用途。您可以：

清除 XPI 调用所使用的参数列表
设置输入参数
对 CICS 函数进行调用。

您可以单独对所有这些内容进行编码 (请参阅显示如何以递增方式构建参数列表的示例) ，或者将它们包含在单个语句中。

某些选项是所有 XPI 用途的公共选项。它们包含在所有语法描述中，但它们的解释在此处给出。选项包括 CALL ， CLEAR ， IN ， FUNCTION ， OUT ， RESPONSE 和 REASON。

CALL

导致对 XPI 函数发出调用的代码生成。如果指定 CALL ， IN ， FUNCTION 和 OUT ，那么将生成代码以执行构建参数列表，调用函数以及接收结果的整个操作。您可以省略 CALL ，但指定 IN 以递增方式构建参数列表; 稍后可以将 CALL 与该列表一起使用，编码 CALL ， IN ， FUNCTION ， OUT 和所有必需选项。然后，您可以使用星号 (*) 来表示预设选项的值，以显示该值已存在于列表中。

注: 如果以递增方式构建参数列表，请不要在最后发出调用时指定 CLEAR ，因为 CLEAR 选项会将参数列表设置为零，这将导致您丢失预设值。

CLEAR

将参数列表中的存在位 (必需参数和可选参数) 设置为二进制零。每个宏都有一个 COPY 代码，它通过一个由头部分组成的 DSECT 定义参数列表，后跟一组存在位，以及参数本身。出于性能原因，仅清除头部分和存在位。参数列表的其余部分保持不变。

注: 未能清除参数列表可能会导致不可预测的结果，例如程序检查或存储器违例。如果要以递增方式构建参数列表，请在指定任何参数之前指定 CLEAR。如果未以递增方式构建参数，请在发出 CALL 时指定 CLEAR。

之中

告知 CICS ，在 IN 选项之后且在 OUT 选项之前的任何参数都是输入值。当指定了 CALL 时，必须指定它。如果使用不带 CALL 的函数来构建参数列表，那么可以指定 IN 和一些参数值以将值存储到列表中。

函数

指定您需要的宏的函数; 例如， GETMAIN 或 FREEMAIN。在指定 CALL 时必须指定它，并且与其他选项不同，它必须始终是显式的-您不能编码 "FUNCTION (*)"。

Mandin (值)

如果指定了 CALL ，那么 "mandin" 表示必需的选项。 "value" 可以用星号 (*) 表示，以显示先前使用的宏已在参数列表中设置值 (请参阅 "CALL")。有关如何完成 "value" 的更多详细信息，请参阅 XPI 语法中的特定函数调用。

OUT

告知 CICS OUT 选项后的任何参数都是接收方字段。当指定了 CALL 时，必须指定它。

注: 如果未指定 CALL ，那么将以下输出参数与星号 (*) 以外的值配合使用无效。

Mandout (值)

"mandout" 表示在指定了 CALL 的情况下变为必需的选项。如果对星号 (*) 进行了编码，那么输出将放在参数列表中，或者放在您在 "value" 中指定的位置中。 RESPONSE 是 MANDOUT 选项的一种特殊情况 (请参阅 RESPONSE)。有关如何完成 "value" 的更多详细信息，请参阅特定函数调用 (请参阅 XPI 语法)。

optin1,2…; optout1,2….

表示对于宏的所有形式完全可选的项; 尤其是，指定 CALL 时不必指定这些项。

RESPONSE

是您定义的必需数据区，用于接收来自 XPI 调用的响应。可以使用星号 (*) 向 CICS 指示要将 RESPONSE 值放在参数列表中，也可以指定要将 RESPONSE 值放在其中的字段的名称。如果要在不使用 CALL 的情况下使用宏来构建参数列表，那么无需对 RESPONSE 选项进行编码。

来自任何 XPI 调用的响应始终为 "OK" ， "EXCEPTION" ， "灾难" ， "INVALID" ， "KERNERROR" 和 "PURGED" 之一。 CICS 提供的响应代码值有标准化名称 (EQU 符号):

xxyy_OK, xxyy_EXCEPTION, xxyy_DISASTER, xxyy_INVALID,
xxyy_KERNERROR, and xxyy_PURGED,

其中 "xxyy" 是从字符串 "DFH" 后面的相关宏名称的四个字母派生的前缀。因此，对于 DFHSMMCX ，前缀为 SMMC; 对于 DFHLDLDX ，前缀为 LDLD。当您包含宏 DFHxxyyX的副本 DFHxxyyY 时，将生成与这些名称等同的值。您不能假定对应 RESPONSE 代码的算术值对于所有宏调用都是相同的。 RESPONSE 代码的含义如下:

确定

XPI 请求已成功完成。

EXCEPTION

该函数未成功完成，原因可能是预期会发生，并且可能由程序进行编码 (例如， TRANSACTION_DUMP ， EXCEPTION = SUPPRESSED_BY_DUMPTABLE)。任何 REASON 值都可能提供更多信息。

DISASTER

请求已完全失败。您无法在用户出口程序中从此故障恢复。发生此故障时， CICS 将执行系统转储，发出错误消息并设置 "灾难" 响应。接收此消息时，您的用户出口程序应退出而不尝试任何进一步的处理。此响应的 REASON 值 (仅显示在跟踪中) 可能提供更多信息。没有返回到调用程序的 REASON 值。

INVALID

您省略了必需值，或者为选项提供了无效值。您无法在用户出口程序中从此故障恢复。发生此故障时， CICS 将执行系统转储，发出错误消息并设置 "INVALID" 响应。在接收此响应时，用户出口程序应返回到调用者，而不尝试任何进一步的处理。此响应的 REASON 值 (仅显示在跟踪中) 可能提供更多信息。这可能帮助您更正出口程序中的任何错误。没有返回到调用程序的 REASON 值。

KERNERROR

内核检测到您尝试调用的 CICS 函数存在错误。您请求的功能不可用或无效，或者 CICS 中存在错误。

PURGED

任务已清除，或者在 XPI 调用上指定的时间间隔已到期。检查 REASON 代码。

请注意，如果除 DFHDSSRX SUSPEND 或 WAIT_MVS 以外的 XPI 调用获取此 RESPONSE ，那么出口程序应将返回码设置为 "UERCPURG" 并返回到调用者。

如果 DFHDSSRX SUSPEND 或 WAIT_MVS 调用指定了 INTERVAL ，并且获取此响应的原因为 "TIMED_OUT" ，那么表明您指定的 INTERVAL 已通过。由您决定下一步的工作。

如果 DFHDSSRX SUSPEND 或 WAIT_MVS 调用指定了 INTERVAL ，并获取此响应 (原因为 "TASK_COMPLETED") ，那么这指示您指定的 INTERVAL 尚未传递，但该任务已被操作员或应用程序清除。在这种情况下，必须设置返回码 "UERCPURG" 并返回。

如果 DFHDSSRX 暂挂或 WAIT_MVS 调用不指定了 INTERVAL ，并且获取此响应的原因为 "TASK_COMPLETED" 或 "TIMED_OUT" ，那么表明该任务已由操作员或应用程序或死锁超时工具清除。在这种情况下，必须设置返回码 "UERCPURG" 并返回。

出于任何其他原因，不得将响应代码 "UERCPURG" 返回给 CICS。如果您尝试这样做，那么您的程序将产生不可预测的结果。

推理

这是为了接收有关 RESPONSE 值的更多信息而定义的必需数据区。您可以使用 (*) 向 CICS 指示要将 REASON 值放在参数列表中。在大多数 XPI 调用上，仅针对 "EXCEPTION" 和 "PURGED" 的响应值提供标准化原因名称 (EQU 符号)。响应随附的 REASON 值因 XPI 函数而异，因此详细信息随 XPI 调用的描述一起提供。

当 RESPONSE 为 "OK" 时，原因不适用。在这些情况下，您不应测试 REASON 字段。

注: 有关如何初始化参数列表，设置参数，进行调用和接收输出参数的示例，请参阅显示使用存储器的全局用户出口 XPI 示例。该部分既包含完整的示例，也包含单独执行每个步骤的示例。