INQUIRE ASSOCIATION
Retrieve association information for a specified task from its association data control block (ADCB).
Conditions: INVREQ, NOTAUTH, TASKIDERR
This command is threadsafe.
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
- 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.
- 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)
- 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, ODADPTRDATA1 returns blanks. ODADPTRDATA1 also returns blanks if the adapter set a value for this field, but did not set an adapter identifier.
- ODADPTRDATA2(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, ODADPTRDATA2 returns blanks. ODADPTRDATA2 also returns blanks if the adapter set a value for this field, but did not set an adapter identifier.
- ODADPTRDATA3(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, ODADPTRDATA3 returns blanks. ODADPTRDATA3 also returns blanks if the adapter set a value for this field, but did not set an adapter identifier.
- 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.
- 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.
- 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.