INQUIRE ASSOCIATION

Retrieve association information for a specified task from its association data control block (ADCB).

INQUIRE ASSOCIATION

Conditions: INVREQ, NOTAUTH, TASKIDERR

This command is threadsafe.

Options

For more information about the use of CVDAs, see CICS-value data areas (CVDAs).

Description

The INQUIRE ASSOCIATION command retrieves information about the way a task was started, based on a task number.

Association records are identified by task numbers. Therefore, the input data, specified on the ASSOCIATION option of the INQUIRE command, is the task number. The association data is retrieved from the association data control block (ADCB) of the specified task.

The association data control block is built during task attach processing. It might contain information about another CICS® task that acted as the point of origin for this task.

Use the INQUIRE ASSOCIATION command to inquire about the association data of a single task in the local region. Browsing is not supported.

For more information about association data and origin data, see Association data.

Options

ACAPPLNAME(data-area)

Returns, in a 64-character area, the name of the application that is associated with the task. If no application context is associated with the task, this option is blank.

ACMAJORVER(data-area)

Returns, in fullword binary form, the major version number of the application associated with the task. If no application context is associated with the task, this option returns 0.

ACMICROVER(data-area)

Returns, in fullword binary form, the micro version number of the application associated with the task. If no application context is associated with the task, this option returns 0.

ACMINORVER(data-area)

Returns, in fullword binary form, the minor version number of the application associated with the task. If no application context is associated with the task, this option returns 0.

ACOPERNAME(data-area)

Returns, in a 64-character area, the name of the application operation that is associated with the task. If no application context is associated with the task, this option is blank.

ACPLATNAME(data-area)

Returns, in a 64-character area, the name of the platform that is associated with the task. If no application context is associated with the task, this option is blank.

APPLDATA(data-area)

Returns the 40-character value of the application data associated by CICS with the socket that received the request that started this task. If the task was not started through a TCPIPSERVICE socket, APPLDATA is blank.

The 40-character application data consists of these bytes:

A 24-byte prefix owned by the Sockets domain

Bytes 01-03

DFH

Byte 04

I: Inbound (listen and accept)
O: Outbound (connect)

Bytes 05-12

The APPLID of this region

Bytes 13-16

The ID of the transaction that is defined in the TCPIPSERVICE:

CIEP: ECI inbound
CISC: IPIC outbound
CISS: IPIC inbound
CWXN: HTTP inbound
CWXU: USER inbound
xxxx: HTTP outbound

Bytes 17-24

The network protocol: one of ECI, HTTP, IPIC, or USER

A 16-byte suffix owned by the using domain

The contents of the suffix depends on the state of the connection:

The TCPIPSERVICE is listening on the socket

Bytes 25-32: The TCPIPSERVICE name
Bytes 33-40: The first 8 bytes of the TCPIPSERVICE description

After the IPCONN has been acquired

Bytes 25-32: The IPCONN name
Bytes 33-40: The APPLID of the partner region

Default for outbound connections

Bytes 25-40: Blank

This data can be used to correlate CICS connection information with z/OS® Communication Server connection information.

APPLID(data-area)

Returns the 8-character APPLID of the CICS region in which this task is running.

ASSOCIATION(data-value)

Specifies the 4-byte number of the task for which you want to retrieve association data.

CLIENTIPADDR(data-area)

Returns, into a 39-character area, the IP address of the TCP/IP client that requested this task to start. When the CLNTIPFAMILY option returns IPV4, the returned address is a 15-character dotted decimal IPv4 address, padded with blanks. When CLNTIPFAMILY returns IPV6, the address returned is a 3- to 39-character colon hexadecimal IPv6 address, padded with blanks. If this task was not started from a TCP/IP client, CLIENTIPADDR returns 0.0.0.0 and CLNTIPFAMILY returns NOTAPPLIC.

You can specify IPv4 and IPv6 addresses in a number of acceptable formats. See IP addresses for more information about address formats.

CLIENTLOC(data-area)

Returns a 32-character area that represents the SO_CLUSTERCONNTYPE socket option returned by z/OS Communications Server for the facility in the FACILNAME option. The binary format of SO_CLUSTERCONNTYPE is converted to characters in CLIENTLOC and displayed as either zeros or ones. The CLIENTLOC option represents the current socket, unless the value in the FACILTYPE option is IPIC, in which case CLIENTLOC is taken from the CLIENTLOC value for the IPCONN. For details, see INQUIRE IPCONN. For a description of SO_CLUSTERCONNTYPE and an explanation of the bit settings, see z/OS Communications Server IP Sockets Application Programming Interface Guide and Reference.

CLIENTPORT(data-area)

Returns, in fullword binary form, the number of the port that the TCP/IP stack used to send the request that resulted in this task being attached. If the task was not started in this way, CLIENTPORT returns zero.

CLNTIPFAMILY(cvda)

Returns a value indicating the form of TCP/IP addressing used by this task. The CVDA values are as follows:

IPV4: The address is specified in IPv4 dotted decimal address format.
IPV6: The address is specified in IPv6 colon hexadecimal address format.
NOTAPPLIC: 0.0.0.0 is specified in the CLIENTIPADDR option and the task was not started from a TCP/IP client.

DNAME(data-area)

Returns the 1- to 246-character distinguished name padded with trailing ASCII blanks. Distinguished names are represented in UTF-8 encoding. If a distinguished name is not available for the task, DNAME returns ASCII blanks.

FACILNAME(data-area)

Returns the 8-character name of the facility associated with the initiation of this task. If the facility is a socket, FACILNAME returns the string "**STE**". If the facility is a web request without a URIMAP, FACILNAME returns the string "**WRB**".

FACILTYPE(cvda)

Returns a CVDA value identifying the type of facility that initiated this task. CVDA values are as follows:

APPC: LU 6.2 (APPC) connection
BRIDGE: 3270 bridge facility virtual terminal
EVENT: Event processing channel
IPECI: IP ECI Client Conversation session
IPIC: IP interconnectivity session (IPCONN)
JVMSERVER: JVM server
LU61: LU 6.1 session
MRO: MRO session
NONE: No facility is associated with this task
RRSUR: Recovery Manager Unit of Recovery
RZINSTOR: Request stream (RZ) instore transport client
SCHEDULER: Scheduler timer request entry
SOCKET: Socket domain session entry
START: Non terminal-related START element
STARTTERM: Terminal-related START element
TERMINAL: Terminal entry
TRANDATA: Transient data destination entry
UNKNOWN: The facility type is unknown
WEB: CICS web support session
XMRUNTRAN: CICS business transaction services (BTS) activity

INITUSERID(data-area)

This option is no longer supported.

IPCONN(data-area)

Returns the 8-character name of any IPIC connection that was used to receive a request that resulted in this task starting. If the task was not started in this way, IPCONN returns blanks. This field contains a nonblank value only when the FACILTYPE is IPIC.

IPFAMILY(cvda)

Replaced by the SRVRIPFAMILY option, which supports IPv6 addressing. IPFAMILY is maintained for existing programs only. Returns a CVDA value indicating the form of TCP/IP addressing used by this task. CVDA values are as follows:

IPV4: The request that caused CICS to initiate this task arrived at a TCPIPSERVICE resource that used an IPv4 address.
IPV6: The request that caused CICS to initiate this task arrived at a TCPIPSERVICE resource that used an IPv6 address.
NOTAPPLIC: No TCP/IP client is associated with this task.

LUNAME(data-area)

Returns the 8-character network name of the terminal from which this task was started. If the task was started from an IPIC (IPCONN), ISC over SNA (APPC), or MRO session, LUNAME returns the APPLID of the remote region. If the task was not started from a terminal, nor from an IPCONN, APPC, or MRO session, LUNAME returns blanks. For OTS transactions, LUNAME returns blanks.

MVSIMAGE(data-area)

Returns the 8-character name of the MVS™ image associated with the TCPIPSERVICE used to receive a request that resulted in this task starting. If the task was not started in this way, MVSIMAGE returns blanks.

This function depends on Communication Server TCP/IP Network Access Control support being activated and the CLIENTIPADDRESS being configured into a Network Security Zone.

NETID(data-area)

Returns the 8-character network ID of the terminal from which this task was started.

ODADPTRID(data-area)

Returns, in a 64-character area, the data that was added to the origin data by the adapter. This field is created when the originating task is started. If the task was not started by using an adapter, or if it was and the adapter did not set this value, ODADPTRID returns blanks.

ODADPTRDATA1(data-area)

ODADPTRDATA2(data-area)

ODADPTRDATA3(data-area)

ODAPPLID(data-area)

Returns the 8-character APPLID taken from the origin descriptor associated with this task.

ODCLNTIPADDR(data-area)

Returns, into a 39-character area, the IP address of the TCP/IP client that requested the originating task to start. When ODIPFAMILY returns IPV6, the address returned is a 3- to 39-character colon hexadecimal IPv6 address, padded with blanks. If the originating task was not started from a TCP/IP client, ODCLNTIPADDR returns 0.0.0.0 and ODIPFAMILY returns NOTAPPLIC.

ODCLNTPORT(data-area)

Returns, in fullword binary form, the number of the port that the TCP/IP stack used to send the request that resulted in the originating task being attached. If the originating task was not started in this way, ODCLNTPORT returns zero.

ODFACILNAME(data-area)

If the facility associated with the initiation of the originating task is a transient data queue, a terminal, or a system, ODFACILNAME returns the 8-character name of the facility.

If the facility associated with the initiation of the originating task is a socket, ODFACILNAME returns the string "**STE**".

ODFACILTYPE(cvda)

Returns a CVDA value identifying the type of facility that initiated the originating task that is associated with this task. CVDA values are as follows:

APPC: LU 6.2 (APPC) connection
BRIDGE: 3270 bridge facility virtual terminal
EVENT: Event processing channel
IPECI: IP ECI Client Conversation session
IPIC: IP interconnectivity session (IPCONN)
JVMSERVER: JVM server
LU61: LU 6.1 session
MRO: MRO session
NONE: No facility is associated with this task
RRSUR: Recovery Manager Unit of Recovery
RZINSTOR: Request stream (RZ) instore transport client
SCHEDULER: Scheduler timer request entry
SOCKET: Socket domain session entry
START: Non terminal-related START element
STARTTERM: Terminal-related START element
TERMINAL: Terminal entry
TRANDATA: Transient data destination entry
UNKNOWN: The facility type is unknown
WEB: CICS web support session
XMRUNTRAN: CICS business transaction services (BTS) activity

ODIPFAMILY(cvda)

Returns a value indicating the form of TCP/IP addressing used by the originating task. CVDA values are as follows:

IPV4: The address is specified in IPv4 dotted decimal address format.
IPV6: The address is specified in IPv6 colon hexadecimal address format.
NOTAPPLIC: 0.0.0.0 is specified in the ODCLNTIPADDR option and the task was not started from a TCP/IP client.

ODLUNAME(data-area)

Returns the 8-character network logical unit name of the terminal from which the originating task was started. If the originating task was started from an IPIC (IPCONN), ISC over SNA (APPC), or MRO session, ODLUNAME returns the network name of the remote region. If the originating task was not started from a terminal, nor from an IPCONN, APPC, or MRO session, ODLUNAME returns blanks. For OTS transactions, ODLUNAME returns blanks.

ODNETID(data-area)

Returns the 8-character network ID of the terminal (terminal, APPC peer, or similar device) from which the originating task was started.

ODNETWORKID(data-area)

Returns the 8-character network qualifier for the origin region APPLID on which the task ran.

ODSERVERPORT(data-area)

Returns, in fullword binary form, the listening IP port number that was used when the originating task received the request. If the originating task was not started in this way, ODSERVERPORT returns zero.

ODSTARTTIME(data-area)

Returns a 21-character representation of the time when the originating task was started. The time is in GMT and in the form yyyymmddhhmmss.ssssss.

ODTASKID(data-area)

Returns the 4-byte packed decimal identifier of the originating task that is associated with this task.

ODTCPIPS(data-area)

Returns the 8-character name of the TCPIPSERVICE resource associated with the connection that received the request that resulted in the originating task starting. If the originating task was not started in this way, ODTCPIPS returns blanks.

ODTRANSID(data-area)

Returns the 4-character name of the transaction under which the originating task ran.

ODUSERID(data-area)

Returns the 8-character user ID under which the originating task ran.

PHAPPLID(data-area)

Returns the 8-character APPLID from previous hop data. If the specified task was initiated by a task in another CICS region, PHAPPLID contains the APPLID of the other CICS region, or spaces if it was not initiated in this way. For more information about previous hop data, see Transaction tracking.

PHCOUNT(data-area)

Returns, in fullword binary form, the number of times there has been a request from one CICS region to another to initiate a task with which this task is associated, or zero if there have been no such requests.

PHNETWORKID(data-area)

Returns the 8-character network qualifier from previous hop data. If the specified task was initiated by a task in another CICS region, PHNETWORKID contains the network qualifier for the APPLID of the other CICS region or spaces if it was not initiated in this way.

PHSTARTTIME(data-area)

Returns a 21-character representation of the task start time from previous hop data. The time is in GMT and in the form yyyymmddhhmmss.ssssss. If the specified task was initiated by a task in another CICS region, PHSTARTTIME contains the start time of the task in the other CICS region, or spaces if it was not initiated in this way.

PHTASKID(data-area)

Returns the 4-byte packed decimal identifier from previous hop data. If the specified task was initiated by a task in another CICS region, PHTASKID contains the identifier of the task in the other CICS region, or packed decimal zero if it was not initiated in this way.

PHTRANSID(data-area)

Returns the 4-character name of a transaction from previous hop data. If the specified task was initiated by a task in another CICS region, PHTRANSID contains the transaction name of the task in the other CICS region, or spaces if it was not initiated in this way.

PROGRAM(data-area)

Returns the 8-character name of the first program called by a task running this transaction.

REALM(data-area)

Returns the 1- to 255-character realm name in UTF-8 encoding, padded with trailing ASCII blanks. The realm is a component of a distributed identity and defines the region where a security ID applies.

SERVERIPADDR(data-area)

Returns, into a 39-character area, the IP address of the IP service that scheduled this task. When the IPFAMILY option returns IPV4, the returned address is a 15-character dotted decimal IPv4 address, padded with blanks. When SRVRIPFAMILY returns IPV6, it is a 3- to 39-character colon hexadecimal IPv6 address, padded with blanks. If this task was not started by an IP service, SERVERIPADDR returns 0.0.0.0 and SRVRIPFAMILY returns NOTAPPLIC.

You can specify IPv4 and IPv6 addresses in a number of acceptable formats. See IP addresses for more information about address formats.

SERVERPORT(data-area)

Returns, in fullword binary form, the number of the port on which the IP service that received the request that resulted in this task being attached is listening. The service can be a TCPIPSERVICE resource or a Liberty JVM server. If the task was not started in this way, SERVERPORT returns zero.

SRVRIPFAMILY(cvda)

Replaces the IPFAMILY option. SRVRIPFAMILY returns a value indicating the form of IP addressing used by this task. CVDA values are as follows:

IPV4: The address is specified in IPv4 dotted decimal address format.
IPV6: The address is specified in IPv6 colon hexadecimal address format.
NOTAPPLIC: 0.0.0.0 is specified in the SERVERIPADDR option and the task was not started from a TCP/IP client.

STARTTIME(data-area)

Returns a 21-character representation of the time when this task was started. The time is in GMT and in the form yyyymmddhhmmss.ssssss.

TCPIPJOB(data-area)

Returns the 8-character name of the TCP/IP job associated with the connection that received the request that resulted in this task starting. If the task was not started in this way, TCPIPJOB returns blanks.

This function depends on Communication Server TCP/IP Network Access Control support being activated and the CLIENTIPADDRESS being configured into a Network Security Zone.

TCPIPSERVICE(data-area)

Returns the 8-character name of the TCPIPSERVICE resource associated with the connection that received the request that resulted in this task starting. If the task was not started in this way, TCPIPSERVICE returns blanks.

TCPIPZONE(data-area)

Returns the 8-character name of the TCP/IP network security zone, if any, associated with the connection that received the request that resulted in this task starting. If there is no TCP/IP network security zone, or the task was not started in this way, TCPIPZONE returns blanks.

TCPIPZONE depends on Communication Server TCP/IP Network Access Control support being activated and the CLIENTIPADDRESS being configured into a Network Security Zone.

TRNGRPID(data-area)

Returns, in a 28-byte area, a unique identifier that represents the transaction group ID of the originating transaction.

TRANSACTION(data-area)

Returns the 4-character name of the transaction that this task is running.

USERCORRDATA(data-area)

Returns, in a 64-byte area, the user correlator data that was added to the associated data origin descriptor by means of an XAPADMGR global user exit program. This field is created when the originating task is started. If the global user exit program is not driven at that point, USERCORRDATA returns blanks.

USERID(data-area)

Returns the 8-character user ID associated with this task.

Conditions

INVREQ

RESP2 values:

2: The command was specified with no arguments.

NOTAUTH

RESP2 values:

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

TASKIDERR

RESP2 values:

1: The task specified on the ASSOCIATION option was not found.