INQUIRE ASSOCIATION LIST

The INQUIRE ASSOCIATION LIST command returns a list of user tasks that are in the local region.

INQUIRE ASSOCIATION LIST

Conditions: INVREQ, LENGERR, NOTAUTH

This command is threadsafe.

Description

User tasks are tasks that are associated with user-defined transactions or with transactions supplied by CICS®. You can restrict the list to tasks that match a number of filters.

You can use INQUIRE ASSOCIATION LIST to filter tasks on user correlation data that has been added to the associated data origin descriptors of the tasks by an XAPADMGR global user exit program. You can also search on certain fields in the origin data portion of the association data to find those tasks and transaction group IDs that share a set of common values. See Filtering options for information about the fields that can be filtered.

The command returns, in SET, the address of a list of tasks. Each entry in the list identifies a task that matches the DNAME and REALM, and USERCORRDATA filters. The number of items in the list is returned in LISTSIZE.

For more information about association data, see Association data.

Filtering options

The DNAME, REALM, and USERCORRDATA options are three separate filters. The following rules apply:

If you specify a filter, only the tasks which match the criteria of the filter are returned.
If you specify more than one filter, the tasks which match both filters are returned.
If you do not specify a filter, all tasks are returned.

Options

DNAME(data-value)

Specifies UTF-8 character field, up to a maximum of 246 characters, including 2 characters for opening and closing parentheses. You must specify parentheses in the DNAME option. DNAME is a filter to return a list of distinguished names for the realm specified in the REALM option. Distinguished names are represented in UTF-8 encoding, therefore null values are represented with ASCII blanks. An empty list is returned if you specify this option and you do not have the correct z/OS® release.

The following search forms are accepted:

(attr=value)
(attr=value*)

where:

attr is the first attribute in the distinguished name for the realm, specified in the REALM option. This attribute is case-sensitive.
value is the first value in the distinguished name, which can be a generic name if value* is specified. * represents zero or more characters. This attribute is case-sensitive.

For example, if a distinguished name is in the following format:

CN=John Smith

the search argument can be in this format:

(CN=John Smith)

or a generic form can be in this format:

(CN=John S*)

If a generic filter, for example, (CN=*), is specified, only the tasks that have distinguished names with the first attribute specified are included.

If you are filtering on a name that is greater than 244 characters in length, you must use a generic filter.

If value is not specified, or DNAME is not set, all distinguished names for the specified realm are included.

See Filtering options for information about how DNAME operates with REALM and USERCORRDATA.

DNAMELEN(data-value)

Specifies the length of the DNAME option. DNAMELEN is a numeric value, up to a maximum of 246.

LISTSIZE(data-area)

Returns, as a fullword binary number, the number of items in the list addressed by the SET option. Each entry in the list identifies a task that matches the DNAME and REALM, and USERCORRDATA filters. If one or more of the filters do not match any task, LISTSIZE returns zero.

REALM(data-value)

Specifies the realm name in UTF-8 encoding, therefore null values are represented with ASCII blanks. The realm is a component of a distributed identity and defines the region where a security ID applies. If you are using WebSphere® Application Server, the realm name can be the service that provides access to the registry where the user is defined. The LDAP server configuration listen statement provides the realm name in URL format.

An empty list is returned if you specify this option and you do not have the correct z/OS release.

If a value is not specified, or REALM is not set, all realms are included.

See Filtering options for information about how REALM operates with DNAME and USERCORRDATA.

REALMLEN(data-value)

Specifies the length of the REALM option. REALMLEN is a numeric value, up to a maximum of 255.

SET(ptr-ref)

Specifies the address of a list of 4-byte packed-decimal task numbers. Each entry in the list identifies a task that matches the DNAME and REALM, and USERCORRDATA filters. If one or more of the filters do not match any task, the SET pointer contains a null value.

CICS obtains the storage for this list and frees it when the inquiring task issues another INQUIRE ASSOCIATION LIST command or ends. The task cannot free the storage.

USERCORRDATA(data-value)

Specifies a subset (up to 64 bytes) of the user correlation data added to the associated data origin descriptor by an XAPADMGR global user exit program. This data is used as a filter to return a list of task numbers that match this request.

The filter can contain the following wildcard characters:

?: matches exactly one arbitrary character.
*: matches zero or more arbitrary characters.

See Filtering options for information about how USERCORRDATA operates with DNAME and REALM.

Conditions

INVREQ

RESP2 values:

1: Invalid distinguished name search filter.
3: Either DNAME or DNAMELEN is specified. You must specify both the DNAME and DNAMELEN options.
4: Either REALM or REALMLEN is specified. You must specify both the REALM and REALMLEN options.

LENGERR

RESP2 values:

3: DNAMELEN has a negative value or a value greater than 246.
4: REALMLEN has a negative value or a value greater than 255.

NOTAUTH

RESP2 values:

100: The user associated with the issuing task is not authorized to use this command.