CEMT INQUIRE CONNECTION

Retrieve information about an MRO or ISC over SNA connection to a remote system.

In the CICS Explorer, the ISC/MRO operations view provides a functional equivalent to this command.

Function

Description

CEMT INQUIRE CONNECTION returns information about a connection from your local CICS® region to another CICS region or another system. The connection is either MRO or ISC over SNA. To inquire on connections that use TCP/IP, use the CEMT INQUIRE IPCONN command.

You can reset the options either by typing the SET command or by overtyping at the appropriate place on the INQUIRE screen.

See CONNECTION definition attributes for further information about connections.

The resource signature

You can use this command to display the resource signature fields. You can use these fields to manage resources by capturing details of when the resource was defined, installed, and last changed. For more information, see Auditing resources. The resource signature fields are CHANGEAGENT, CHANGEAGREL, CHANGETIME, CHANGEUSRID, DEFINESOURCE, DEFINETIME, INSTALLAGENT, INSTALLTIME, and INSTALLUSRID. See Summary of the resource signature field values for detailed information about the content of the resource signature fields.

Input

Press the Clear key to clear the screen. There are two ways of starting this transaction:

Type CEMT INQUIRE CONNECTION. You get a display that lists the current status.
Type CEMT INQUIRE CONNECTION followed by as many of the other attributes as are necessary to limit the range of information that you require. So, for example, if you enter cemt i c ins acq, the resulting display will show you the details of only those connections that are in service and acquired.

You can then tab to the highlighted or blank fields and overtype them with the required values.

(value): specifies one or more names (1–4 characters) defined for an interregion communication (IRC) or an intersystem communication (ISC) connection.
ALL: is the default.

Sample screen

Figure 1. CEMT INQUIRE CONNECTION screen

  IN CONN
  STATUS:  RESULTS - OVERTYPE TO MODIFY
    Con(G1GA)                   Ins     Irc Exci
    Con(ISC1) Net(AUHZCIC1)     Ins Acq Vta Appc     Xok Unk
                                               Nqn(GBIBMIYA.AUHZCIC1)
    Con(MRO2) Net(CICSHAA1)     Ins Acq Irc              Unk
    Con(MRO4) Net(CICSHAA2)     Ins Acq Irc              Unk
    Con(MRO5) Net(CICSHAA3)     Ins Acq Irc              Unk
    Con(MRO6) Net(CICSHAB1)     Ins Acq Xcf
    Con(VTA1) Net(IYCQTC03)     Ins Acq Vta Appc
                                               Nqn(GBIBMIYA.IYCQTC03)

Note: There are blank fields on the screen where a value does not apply or is ‘negative'; that is, the value begins with ‘No'. To modify these fields, locate them by tabbing (they appear in the same sequence as in the expanded format), and overtype with input valid for that field. You may find it more convenient to use the expanded format when setting one of these values, (negating is easier because you are overtyping a displayed field with its negative causing the result to become non-displayed).

If you place the cursor against a specific entry in the list and press ENTER, CICS displays an expanded format as shown in Figure 2.

Figure 2. The expanded display of an individual entry

  IN CONN
  RESULT - OVERTYPE TO MODIFY
    Connection(MRO5)
    Netname(CICSHAA3)
    Pendstatus( Notpending )
    Servstatus( Inservice )
    Connstatus( Acquired )
    Accessmethod(Irc)
    Purgetype(            )
    Protocol()
    Xlnstatus()
    Recovstatus( Norecovdata )
    Uowaction(              )
    Cqp( Notsupported )
    Grname()
    Membername()
    Affinity(              )
    Nqname()
    Remotesystem()
    Rname()
    Rnetname()

CEMT INQUIRE CONNECTION

Displayed fields

ACCESSMETHOD

displays the access method in use for this connection. The values are:

VTAM®: VTAM is now z/OS® Communications Server. The connection is used for intersystem communication (ISC).
IRC: The connection is used for multiregion operation (MRO), and has been defined to use the interregion communication (IRC) program for communication. If the CONNECTION is ACQUIRED, the MRO partner is running on the same MVS™ image. If the CONNECTION is RELEASED, the MRO partner may not be on the same MVS image; if it is not, the XCF access method will be used when the connection becomes ACQUIRED.
XM: The connection is used for multiregion operation (MRO) and has been defined to use MVS cross-memory (XM) services for communication. If the CONNECTION is ACQUIRED, the MRO partner is running on the same MVS image. If the CONNECTION is RELEASED, the MRO partner may not be on the same MVS image; if it is not, the XCF access method will be used when the connection becomes ACQUIRED.
INDIRECT: Communication between the local CICS system and the system defined by this connection is through the system named in the INDSYS operand of the connection definition.
XCF: The connection is used for multiregion operation (MRO), and communication uses the cross-system coupling facility (XCF) of MVS. XCF is used for MRO links between CICS regions on different MVS images within an z/OS sysplex. It is selected dynamically by CICS for such links when the access method is defined as IRC or XM in the connection definition.
RCONNECTION: The connection is remote—that is, it is owned by another CICS system.

AFFINITY (input only field)

specifies, where CICS is a member of a z/OS Communications Server generic resource group, that z/OS Communications Server is to end an affinity owned by CICS. This option is valid only for APPC and LU61 connections. The connection must be out of service and in NORECOVDATA state. The value is:

ENDAFFINITY: z/OS Communications Server is to end an affinity owned by CICS.

CHANGEAGENT(value)

Displays a value that identifies the agent that made the last change to the resource definition. You cannot use CEMT to filter on some of these values because they are duplicated. The possible values are as follows:

AUTOINSTALL: The resource was autoinstalled.
CREATESPI: The resource definition was last changed by an EXEC CICS CREATE command.
CSDAPI: The resource definition was last changed by a CEDA transaction or the programmable interface to DFHEDAP.
CSDBATCH: The resource definition was last changed by a DFHCSDUP job.
DREPAPI: The resource definition was last changed by a CICSPlex SM BAS API command.

CHANGEAGREL(value)

Displays the 4-digit number of the CICS release that was running when the resource definition was last changed.

CHANGETIME(date time)

Displays the date and time when the resource definition was last changed. The format of the date depends on the value that you selected for the DATFORM system initialization parameter for your CICS region. The format of the time is hh:mm:ss.

CHANGEUSRID(value)

Displays the 8-character user ID that ran the change agent.

CONNECTION(value)

identifies this panel as relating to system connections, and displays the 4-character name by which the connection is known.

CONNSTATUS

displays the state of the connection between CICS and a remote system. The remote system can be an APPC or an MRO partner identified by (value) on the CEMT INQUIRE CONNECTION command. The ACQUIRED and RELEASED values are common to both APPC and MRO; the others are unique to APPC. The values are:

ACQUIRED (APPC and MRO)

The CONNECTION is acquired. The criteria for ACQUIRED for z/OS Communications Server links are:

The partner LU has been contacted.
Initial CNOS exchange has been done.

The criteria for ACQUIRED for MRO links are:

Both sides of the link are in service.
Both sides of the link are successfully logged on to the CICS interregion communication program (DFHIRP).
A connection request by each side has been successful for at least one session, and therefore each side can send and receive data.

RELEASED (APPC and MRO)

The connection is released. Although the connection might be in service, it is not usable.

In the case of an MRO link, the released status can be caused by any one of a number of conditions. For example, it could be because the CICS region on the other side has not yet initialized, or not yet signed on to the CICS interregion communication program (DFHIRP); or it could be because CICS interregion communication may have been closed on the other side, or the connection on the other side may have been set out of service.

OBTAINING (APPC only)

The connection is being acquired. The connection remains in the OBTAINING state until all the criteria for ACQUIRED have been met.

FREEING (APPC only)

The connection is being released.

AVAILABLE (APPC only)

The connection is acquired but there are currently no bound sessions because they were unbound for limited resource reasons.

Connstatus can be reset with Acquired or Released.

CQP(value)

displays the status of the connection quiesce protocol for the connection. The values are:

NOTSUPPORTED: The connection quiesce protocol is not supported for this connection.
UNATTEMPTED: CICS has not attempted to use the connection quiesce protocol (because the connection has not been released).
COMPLETE: The connection quiesce protocol completed succesfully when the connection was release. The status reverts to UNATTEMPTED when the connection is re-acquired.
FAILED: The connection quiesce protocol failed (for instance, becasue a session failed while the protocol was executing). The status reverts to UNATTEMPTED when the connection is re-acquired.

DEFINESOURCE(value)

Displays the source of the resource definition. The DEFINESOURCE value depends on the CHANGEAGENT option. For details, see Summary of the resource signature field values.

DEFINETIME(date time)

Displays the date and time when the resource was created. The format of the date depends on the value that you selected for the DATFORM system initialization parameter for your CICS region. The format of the time is hh:mm:ss.

GRNAME(value) (APPC only)

displays (for an APPC connection to a generic resource when this system is also a generic resource) the 8-character generic resource name of the connected system. Otherwise this field is blank. CICS assumes that the partner is a generic resource if the two NETNAMEs sent with a BIND are different. Thus, information may be displayed for a partner that is not a generic resource but which uses XRF.

INSTALLAGENT(value)

Displays a value that identifies the agent that installed the resource. You cannot use CEMT to filter on some of these values because they are duplicated. The possible values are as follows:

AUTOINSTALL: The resource was autoinstalled.
CREATESPI: The resource was installed by an EXEC CICS CREATE command.
CSDAPI: The resource was installed by a CEDA transaction or the programmable interface to DFHEDAP.
GRPLIST: The resource was installed by GRPLIST INSTALL.

INSTALLTIME(date time)

Displays the date and time when the resource was installed. The format of the date depends on the value that you selected for the DATFORM system initialization parameter for your CICS region. The format of the time is hh:mm:ss.

INSTALLUSRID(value)

Displays the 8-character user ID that installed the resource.

MEMBERNAME(value)

displays (for an APPC connection to a generic resource when this system is also a generic resource) the 8-character member name (applid) of the connected LU. Otherwise this field is blank. CICS assumes that the partner is a generic resource if the two NETNAMEs sent with a BIND are different. Thus, information may be displayed for a partner that is not a generic resource but which uses XRF.

NETNAME (value)

displays the 8-character name by which the remote system is known to the network.

Note: If the netname is a z/OS Communications Server LU alias, it is different from the netname component of the NQNAME, which always contains the real netname.

NQNAME(value)

displays the 17-character network-qualified name by which the remote system is known to the network.

PENDSTATUS (APPC and MRO only)

displays whether there are any pending units of work for this connection. The values are:

NOTPENDING

There has been no mismatch of lognames with the partner.

Note: MRO connections to pre-displays systems do not use lognames. Therefore, for these connections, PENDSTATUS is always NOTPENDING.

PENDING

There is resynchronization work outstanding for the connection but the partner system has performed an initial start, preventing completion of the resynchronization process. (If the partner system is a CICS version earlier than CICS Transaction Server, a cold start performed on the partner system has the same effect.) You can use the SET CONNECTION NOTPENDING command to unilaterally commit or back out the units of work associated with the connection, according to their associated transaction definitions. You can also investigate the units of work individually and force them to commit or back out, in which case you must also complete the recovery activity by using a SET CONNECTION NOTPENDING command to clear the PENDING condition.

If this is an APPC connection, no new syncpoint work (that is, work involving synclevel 2 protocols) can be transmitted across it until a SET CONNECTION NOTPENDING command has been issued. This restriction does not apply to MRO connections.

If you are not concerned by the loss of synchronization caused by the initial (or cold) start of the partner, you can cause the SET CONNECTION NOTPENDING command to be issued automatically by specifying XLNACTION(FORCE) on the CONNECTION definition.

Pendstatus can be reset with Notpending.

For further information about pending units of work, see Intercommunication concepts and facilities.

PROTOCOL

displays the protocol in use if this is a z/OS Communications Server or external CICS interface connection. The values are:

APPC: The connection uses the z/OS Communications Server LUTYPE6.2 protocol for intersystem communication, or is remote.
EXCI: The connection uses the external CICS interface for communication between CICS and a non-CICS client program.
LU61: The connection uses the z/OS Communications Server LUTYPE6.1 protocol for CICS-to-CICS or CICS-to-IMS intersystem communication.

PURGETYPE (input only field)

specifies how associated transactions are to be purged. The values are:

PURGE (z/OS Communications Server only and IRC only)

Transactions running on the connected system are abnormally terminated. Transactions are terminated only if system and data integrity can be maintained. A transaction is not purged if its definition specifies SPURGE=NO.

FORCEPURGE (z/OS Communications Server only)

All transactions running on sessions on the connected system are immediately terminated abnormally. This can lead to unpredictable results and should be used only in exceptional circumstances.

In some extreme cases (for example, if an error occurs during backout processing), CICS might terminate abnormally.

CANCEL

Automatic initiate descriptors (AIDs) queuing for the specified connection are to be canceled.

AIDs representing scheduled and allocated requests waiting in the local CICS system for the specified connection are canceled. However, TD AIDs with an associated triggered task already started will not be canceled. In addition, the following CICS system AIDs are not purged unless FCANCEL is specified.

Table 1. System AIDs requiring FCANCEL to remove them
Description	Tranid
Remote delete AIDs
Remote scheduler AIDs	CRSR
LU6.2 service manager 1 AIDs	CLS1
LU6.2 service manager 3 AIDs	CLS3
Remote scheduler PURGE AIDs	CRSQ
Resource manager resync AIDs	CRSY
Autoinstalled terminal delete AIDs	CATD
Autoinstalled terminal restart AIDs	CATR

When a canceled SCHEDULE request is found to have a precursor in a remote CICS system, that is, the AID was originally scheduled in a remote system, the remote AID is canceled asynchronously.

Message DFHTF0100 is written to CSMT to indicate how many AIDs have been deleted for the connection and how many remain.

An ‘AIDS CANCELED' message appears on the CEMT panel whenever AIDs are deleted using the CANCEL option of the CEMT SET CONNECTION command.

FCANCEL

All AIDs, including system AIDs, queuing for the specified connection are to be canceled. See Table 1 for a list of those system AIDS that require FCANCEL to remove them. This can lead to unpredictable results and should be used only in exceptional circumstances.

Note: FCANCEL does not remove transient data AIDs with an associated triggered task. These aids may be removed by purging the associated task.

An ‘AIDS CANCELED' message appears on the CEMT panel whenever AIDs are deleted using the FCANCEL option of the CEMT SET CONNECTION command.

RECOVSTATUS (APPC and MRO only)

displays whether there is resynchronization work outstanding for this connection. The connection may never have been connected, or may have been quiesced and all resynchronization work completed, or disrupted without quiesce—in which case resynchronization may be necessary. The values are:

NORECOVDATA: Neither side has recovery information outstanding.
NRS: CICS does not have recovery outstanding for the connection, but the partner may have.
RECOVDATA: There are indoubt units of work associated with the connection, or there are outstanding resyncs awaiting FORGET on the connection. Resynchronization takes place when the connection next becomes active, or when the UOW is unshunted.

If there is recovery outstanding, on completion of exchange of lognames either resynchronization takes place or, in the case of a cold exchange, the PENDING condition is created.

Recovstatus can be reset with Norecovdata.

REMOTESYSTEM (value)

displays the 4-character name of a connection, if the subject of the inquiry is a remote or an indirect connection. In either case, the named connection can be either a connection entry that links towards the TOR, or an indirect connection that provides the netname of the TOR.

If the subject of the inquiry is an indirect connection, the value of REMOTESYSTEM is taken from the INDSYS option of the CONNECTION definition.

Otherwise this field is blank.

RNAME (value)

displays the 4-character name by which this connection is known in a remote system, if the subject of the inquiry is a remote connection.

RNETNAME (value)

displays the 8-character netname of the owning TOR, if the subject of this inquiry is a remote connection. If it is blank, but the connection is remote, the system named in the REMOTESYSTEM field has not been installed, and no value was specified for the REMOTESYSNET option when the connection was defined.

SERVSTATUS

displays whether the system can receive and send data. The values are:

INSERVICE: The system is in service; that is, it is available for use.
OUTSERVICE: The system is out of service; that is, it is not available for use.

Note: You can reset this value by overtyping it with a different value.

UOWACTION (input-only field)

specifies that the normal resynchronization process is to be partially overridden. The value specifies the type of decision to be taken for any units of work that become indoubt due to a failure of the connection; the decisions are recorded and any data inconsistencies are reported when the connection is next acquired. The values are:

BACKOUT: All UOWs shunted due to the failure of this connection are to be backed out.
COMMIT: All UOWs shunted due to the failure of this connection are to be committed.
FORCEUOW: All UOWs shunted due to the failure of this connection are to be forced to BACKOUT or COMMIT, as specified on the INDOUBT option of the TRANSACTION definition.
RESYNC: Any UOWs shunted due to the failure of this connection are to be retried (that is, exchange lognames resynchronization for this connection is to be attempted). This process should normally be started automatically when a connection is acquired or when a UOW is unshunted.

XLNSTATUS

displays the status of the exchange lognames (XLN) process. The values are:

XOK (APPC only): The exchange log names (XLN) process for the APPC connection has completed successfully.
XNOTDONE (APPC only): The exchange log names (XLN) flow for the APPC connection has not completed successfully. The CSMT log can contain information relating to this state. Synchronization level 2 conversations are not allowed on the connection, but synchronization levels 0 and 1 are still allowed.

No status is displayed if exchange log names is not applicable. This can be because the link:

Is released
Is MRO, LU6.1, or single-session APPC
Does not support synchronization level 2 conversations.

For information about the APPC exchange log names process, see Defining links for multiregion operation.