进行 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]

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

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

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 (值)

mandin 代表一个选项，如果指定了 CALL，该选项将成为强制性选项。 value 可以用星号 (*) 表示，以表明之前使用宏时已经在参数列表中设置了该值（参见 CALL）。 有关如何完成 value 的更多详情，请参阅 XPI 语法中的具体函数调用。

输出

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

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

Mandout (值)

mandout 代表一个选项，如果指定了 CALL，该选项将成为强制性选项。 如果输入了星号 (*)，输出结果将被放置在参数列表中，或者您在 value 中指定的位置。 RESPONSE 是 MANDOUT 选项的一种特殊情况 (请参阅 RESPONSE)。 有关如何完成 "value "的更多详情，请参阅具体的函数调用（参见 XPI 语法 ）。

optin1,2…; optout1,2….

表示对所有形式的宏来说完全可有可无的项目；特别是，在指定 CALL 时不必指定这些项目。

响应

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

任何 XPI 调用的响应总是 OK, EXCEPTION, DISASTER, 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 会进行系统转储，发出错误信息，并设置 DISASTER 响应。 接收此消息时，您的用户出口程序应退出而不尝试任何进一步的处理。 此响应的 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（时间间隔），并且收到了 REASON 为 TIMED_OUT 的 RESPONSE，则表示您指定的 INTERVAL（时间间隔）已过。 由您决定下一步的工作。

如果 DFHDSSRX SUSPEND 或 WAIT_MVS 调用指定了一个 INTERVAL，但得到的 RESPONSE 的 REASON 为 TASK_CANCELLED ，这表明您指定的 INTERVAL 未过，但任务已被操作员或应用程序清除。 在这种情况下，必须设置 UERCPURG 的返回代码并返回。

如果 DFHDSSRX SUSPEND 或 WAIT_MVS 调用未指定 INTERVAL，且得到的 RESPONSE 的 REASON 为 TASK_CANCELLED 或 TIMED_OUT ，则表示任务已被操作员或应用程序或死锁超时设施清除。 在这种情况下，必须设置返回码 "UERCPURG" 并返回。

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

推理

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

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