INQUIRE ASSOCIATION LIST

INQUIRE ASSOCIATION LIST 命令返回本地区域中的用户任务列表，这些用户任务在其关联数据中具有匹配的关联信息。

语法

警告系统命令功能强大，可提供有关系统状态的信息，并允许对系统进行更改。系统命令只能由授权应用程序和用户使用。

通过指定 XCMD 系统初始化参数并确保事务的命令安全检查处于激活状态（在 TRANSACTION 资源定义中指定 CMDSEC(YES) 或在 CMDSEC 系统初始化参数中指定 ALWAYS），激活命令安全检查。

INQUIRE ASSOCIATION LIST

条件: INVREQ ， LENGERR 和 NOTAUTH

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

此命令是线程安全的。

描述

用户任务是与用户定义的事务或与 CICS®提供的事务相关联的任务。您可以将列表限制为与多个过滤器匹配的任务。

您可以使用 INQUIRE ASSOCIATION LIST 来过滤已由 XAPADMGR 全局用户出口程序添加到任务的关联数据源描述符的用户关联数据上的任务。您还可以在关联数据的原始数据部分中搜索某些字段，以查找共享一组公共值的任务和事务组标识。有关可过滤的字段的信息，请参阅过滤选项。

该命令在 SET 中返回任务列表的地址。列表中的每个条目都标识与 DNAME 和 REALM 以及 USERCORRDATA 过滤器匹配的任务。列表中的项数在 LISTSIZE 中返回。

有关关联数据的更多信息，请参阅关联数据。

过滤选项

DNAME ， REALM 和 USERCORRDATA 选项是三个独立的过滤器。下列规则适用：

如果指定过滤器，那么将仅返回与过滤器条件匹配的任务。
如果指定多个过滤器，那么将返回与两个过滤器都匹配的任务。
如果未指定过滤器，那么将返回所有任务。

选项

DNAME (data-value)

指定 UTF-8 字符字段，最大长度为 246 个字符，包括用于打开和关闭括号的 2 个字符。必须在 DNAME 选项中指定括号。 DNAME 是一个过滤器，用于返回 REALM 选项中指定的领域的专有名称列表。专有名称以 UTF-8 编码表示，因此空值以 ASCII 空格表示。如果指定此选项并且没有正确的 z/OS® 发行版，那么将返回空列表。

接受以下搜索表单:

(attr=value)
(attr=value*)

其中：

attr 是域的专有名称中的第一个属性，在 REALM 选项中指定。此属性区分大小写。
value 是专有名称中的第一个值，如果指定了 value* ，那么可以是通用名称。 * 表示零个或多个字符。此属性区分大小写。

例如，如果专有名称采用以下格式:

CN=John Smith

搜索参数可以采用以下格式:

(CN=John Smith)

或者通用格式可以是以下格式:

(CN=John S*)

如果指定了通用过滤器 (例如， (CN=*)) ，那么仅包含具有指定的第一个属性的专有名称的任务。

如果要对长度超过 244 个字符的名称进行过滤，那么必须使用通用过滤器。

如果未指定 value ，或者未设置 DNAME ，那么将包括指定域的所有专有名称。

请参阅过滤选项，以获取有关 DNAME 如何使用 REALM 和 USERCORRDATA 运行的信息。

DNAMELEN (data-value)

指定 DNAME 选项的长度。 DNAMELEN 是一个数字值，最大值为 246。

LISTSIZE (data-area)

以全字二进制数的形式返回由 SET 选项寻址的列表中的项数。列表中的每个条目都标识与 DNAME 和 REALM 以及 USERCORRDATA 过滤器匹配的任务。如果一个或多个过滤器与任何任务都不匹配，那么 LISTSIZE 将返回零。

REALM (data-value)

以 UTF-8 编码指定域名，因此空值由 ASCII 空格表示。 realm 是分布式身份的组件，用于定义应用安全标识的区域。如果您正在使用 WebSphere® Application Server，那么域名可以是提供对定义用户的注册表的访问权的服务。 LDAP服务器配置的“侦听”语句以 URL提供领域名称。

如果指定此选项并且没有正确的 z/OS 发行版，那么将返回空列表。

如果未指定值，或者未设置 REALM ，那么将包括所有域。

请参阅过滤选项，以获取有关 REALM 如何使用 DNAME 和 USERCORRDATA 运行的信息。

REALMLEN (data-value)

指定 REALM 选项的长度。 REALMLEN 是一个数字值，最大为 255。

SET (ptr-ref)

指定 4 字节压缩十进制任务号列表的地址。列表中的每个条目都标识与 DNAME 和 REALM 以及 USERCORRDATA 过滤器匹配的任务。如果一个或多个过滤器与任何任务都不匹配，那么 SET 指针将包含空值。

CICS 获取此列表的存储器，并在查询任务发出另一个 INQUIRE ASSOCIATION LIST 命令或结束时释放该存储器。该任务无法释放存储器。

USERCORRDATA (data-value)

指定由 XAPADMGR 全局用户出口程序添加到关联数据源描述符的用户关联数据的子集 (最多 64 个字节)。此数据用作过滤器以返回与此请求匹配的任务号的列表。

过滤器可以包含以下通配符字符:

?: 正好与一个任意字符匹配。
*: 与零个或多个任意字符匹配。

请参阅过滤选项，以获取有关 USERCORRDATA 如何使用 DNAME 和 REALM 操作的信息。

条件

INVREQ

RESP2 值：

1: 专有名称搜索过滤器无效。
3: 指定了 DNAME 或 DNAMELEN。必须同时指定 DNAME 和 DNAMELEN 选项。
4: 指定了 REALM 或 REALMLEN。必须同时指定 REALM 和 REALMLEN 选项。

LENGERR

RESP2 值：

3: DNAMELEN 具有负值或大于 246 的值。
4: REALMLEN 具有负值或大于 255 的值。

NOTAUTH

RESP2 值：

100: 未授权与发出任务关联的用户使用此命令。