CEMT SET IPCONN

Change the attributes of an IPCONN resource or cancel outstanding automatic initiate descriptors (AIDs).

In the CICS Explorer, the IPIC connections operations view provides a functional equivalent to this command.

Description

You can use the SET IPCONN command to change some attributes of an IPCONN resource.

To install a new IPCONN definition when one is already installed, you must set the connection to OUTSERVICE before you use the CEDA INSTALL commands for your new definition.

For information about the different kinds of intercommunication connections, see Intercommunication methods.

Syntax

Press the Clear key to clear the screen. You can start this transaction in two ways:

Type CEMT SET IPCONN (or suitable abbreviations for the keywords), followed by one or more connection identifiers, or ALL. The resulting display lists the current status, similar to that obtained by using the CEMT INQUIRE IPCONN command. You can tab to the highlighted or blank fields and overtype them with the required values.
Type CEMT SET IPCONN (or suitable abbreviations for the keywords), followed by one or more connection identifiers or ALL, then followed by one or more attribute settings that you want to change. For example, cemt s ip al i resets the values for all connections to make them available for use (inservice).

Typing ? at the beginning of either the first or second line gives a syntax prompt. Resetting the values takes effect immediately.

CEMT SET IPCONN

Options

(value)

Specifies the name (1 - 8 characters) of the connection to modify. This is the name of the remote system or region specified on the IPCONN option of the IPCONN definition. You can specify more than one name.

ACQUIRED

Specifies that CICS® acquires a session with the system represented by the IPCONN name. A connection cannot be both ACQUIRED and OUTSERVICE.

ALL

Specifies that any changes you request are made to all resources of the specified type that you are authorized to access.

BACKOUT

Specifies that all units of work (UOWs) shunted because of the failure of this connection are backed out. The normal resynchronization process is partially overridden: decisions are taken for any UOWs that are indoubt because of a failure of the connection, but the decisions are recorded and any data inconsistencies are reported when the connection is next acquired.

CANCEL

Specifies that queued requests by transactions to use this IPCONN are canceled.

Queued requests to use this IPCONN by CICS system transactions that manage communications across the IPCONN are not purged unless FCANCEL is specified.

Message DFHISnnnn is written to CSMT to indicate how many queued requests to use this IPCONN have been deleted for the IPCONN and how many remain.

A QUEUED REQUESTS CANCELED message appears on the CEMT panel whenever queued requests to use this IPCONN are deleted using the CANCEL option of the CEMT SET IPCONN command.

COMMIT

Specifies that all UOWs shunted because of the failure of this connection are committed. The normal resynchronization process is partially overridden: decisions are taken for any units of work that are indoubt because of a failure of the connection, but the decisions are recorded and any data inconsistencies are reported when the connection is next acquired.

FCANCEL

Specifies that all queued requests by transactions to use this IPCONN are canceled, including requests by CICS system transactions that manage communications across this IPCONN. This can lead to unpredictable results and should be used only in exceptional circumstances.

A QUEUED REQUESTS CANCELED message appears on the CEMT panel whenever queued requests to use this IPCONN are deleted using the FCANCEL option of the CEMT SET IPCONN command.

FORCEPURGE

Specifies that all transactions running on sessions to the connected system are abnormally terminated immediately. 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.

FORCEUOW

Specifies that all UOWs shunted because of the failure of this connection are forced to back out or commit, as specified in the ACTION option of the TRANSACTION definition. The normal resynchronization process is partially overridden: decisions are taken for any units of work that are indoubt because of a failure of the connection, but the decisions are recorded and any data inconsistencies are reported when the connection is next acquired.

INSERVICE

Specifies that the system is placed in service; that is, available for use.

KILL

Specifies that the task is terminated. System and data integrity is not guaranteed. The KILL option extends the PURGE and FORCEPURGE options. Use this option only after first attempting a purge or forced purge. The KILL option does not guarantee integrity of any kind, but in some situations you can use it to free up a stalled region, thus enabling the region to continue processing. In some cases, for example, if a task is killed during backout processing, CICS terminates abnormally.

NORECOVDATA

Specifies that the normal resynchronization process is overridden. NORECOVDATA forces indoubt units of work (according to the transaction definitions), targets any resynchronization tasks that are outstanding for the connection, and erases the logname previously received from the partner system. The state of the connection is reset.

Note: Use SET IPCONN NORECOVDATA only in exceptional circumstances. this option erases recovery information and might compromise data integrity for units of work that have updated resources on remote systems.

Examples of circumstances in which you might need to use this option are as follows:

You need to discard a connection and it is not possible for the quiesce protocols with the partner system completed.
An operational or logic error results in a logname mismatch for the connection. The connection state must be reset to allow the exchange lognames process to complete.

Note: If you specify NORECOVDATA, you cannot specify COMMIT, BACKOUT, FORCEUOW, RESYNC, or NOTPENDING.

NOTPENDING

For a connection to a CICS Transaction Server for z/OS® partner that has performed an initial start, specifies that the normal resynchronization process is overridden.

NOTPENDING forces all indoubt units of work (according to the transaction definition) that were created by the connection before the initial start of the partner. It also forgets any resynchronization tasks (waitforget UOW-links) that are outstanding for the connection, and created before the initial start of the partner.

The PENDING condition indicates the existence of recovery information (either shunted UOWs or decisions remembered for the partner) on a connection that has experienced a lognames mismatch with its partner. This indicates that the partner has performed an initial start and that the recovery protocol has been corrupted by a loss of log data at the partner.

It is not possible to set a connection to NOTPENDING state (forcing indoubt and erasing NOFORGET UOWs) until CICS has made contact with the partner and received a new logname from it.

Decisions for a whole connection can be forgotten, but that does not affect the memory of a decision for any other connection involved in the UOW.

Note: If you specify NOTPENDING you cannot specify COMMIT, BACKOUT, FORCEUOW, RESYNC, or NORECOVDATA. For advice on which option to use, see the notes following the description of the RESYNC option.

The exchange lognames function and the resynchronization function are described in Troubleshooting intersystem problems and SNA LU 6.2 Peer Protocols.

OUTSERVICE

Place the system out of service; that is, unavailable for use.

PURGE

Specifies that 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.

RELEASED

Specifies that CICS releases a session with the system represented by the IPCONN name.

RESYNC

Specifies that any UOWs shunted because of the failure of this connection are retried. That is, exchange lognames resynchronization for this connection is attempted. This process should normally start automatically when a connection is acquired or when a UOW is unshunted. The normal resynchronization process is partially overridden: decisions are taken for any units of work that are indoubt because of a failure of the connection, but the decisions are recorded and any data inconsistencies are reported when the connection is next acquired.

Note:

The COMMIT, BACKOUT, FORCEUOW and RESYNC operations are synchronous with setting the state of the UOW; that is, an INQUIRE UOW following SET IPCONN BACKOUT, COMMIT, FORCEUOW, or RESYNC returns the new UOW states.
Specifying one of these options unshunts all units of work that have failed because of a failure of the connection. Before you issue a SET IPCONN FORCEUOW command, you can use the SET UOW command to specify commit or back out for each indoubt unit of work explicitly, rather than allowing the default action. Local procedures determine the importance of the data and the method of using the INQUIRE UOW, INQUIRE UOWENQ, and INQUIRE UOWLINK commands to establish the correct actions.
You can specify only one of the BACKOUT, COMMIT, FORCEUOW, RESYNC, NOTPENDING, and NORECOVDATA options. Use the SET IPCONN NORECOVDATA command only in exceptional circumstances.
To force all indoubt units of work caused by a failure of the connection in the same direction, use SET IPCONN COMMIT or SET IPCONN BACKOUT.
The BACKOUT, COMMIT, FORCEUOW, or RESYNC options of SET IPCONN and SET UOW do not clear resync information. If you want to do this, you must use SET IPCONN NOTPENDING or SET IPCONN NORECOVDATA.
You can issue BACKOUT, COMMIT, FORCEUOW, or RESYNC commands before issuing SET IPCONN NOTPENDING or SET IPCONN NORECOVDATA commands.