SET IPCONN

Description

You can use the SET IPCONN command to change some of the attributes that define an IPCONN. Control returns to the issuing program when the required operation has been scheduled. To get the operation started, it is necessary to relinquish control to CICS.

Options

CONNSTATUS(cvda)

Specifies whether to acquire or release sessions with the system represented by the IPCONN name. An IPCONN cannot be both ACQUIRED and OUTSERVICE.

CVDA values are as follows:

ACQUIRED

Sessions are to be acquired.

RELEASED

Sessions are to be released.

For further information about managing IPCONNs, see the Getting started with intercommunication.

IPCONN(data-value)

Specifies, as an 8-character field, the name of the IPCONN to be modified. This is the name of the remote system or region specified on the IPCONN option of the IPCONN definition.

PENDSTATUS(cvda)

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

The CVDA value is:

NOTPENDING

Forces all indoubt units of work (that were created by the IPCONN before the initial start of the partner) to either commit or back out, as specified by the ACTION option of the TRANSACTION definition. It also forgets any resyncs (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: SET IPCONN NOTPENDING, SET IPCONN NORECOVDATA, and SET IPCONN UOWACTION are mutually exclusive. For advice on which command to use, see the notes following the description of the UOWACTION option.

The exchange lognames function and the resynchronization function are described in Troubleshooting intersystem problems.

PURGETYPE(cvda)

Specifies how associated transactions are to be purged. CVDA values are as follows:

CANCEL

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

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

Message DFHISnnnn is written to CSMT to indicate how many queued requests to use this IPCONN have been deleted 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.

FORCECANCEL

Specifies that all queued requests by transactions to use this IPCONN are to be 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 FORCECANCEL option of the CEMT SET IPCONN command.

FORCEPURGE

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

KILL

Specifies that the task is to be terminated. System and data integrity is not guaranteed. The KILL option extends the PURGE and FORCEPURGE options. You should use it only after an attempt has been made to PURGE or FORCEPURGE a task. The KILL option does not guarantee integrity of any kind but in some situations it allows you to free up a stalled region, enabling the region to continue processing. In some cases, for example if a task is killed during backout processing, CICS terminates abnormally.

PURGE

Specifies that transactions running on the connected system are to be 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.

RECOVSTATUS(cvda)

Specifies that the normal resynchronization process is to be overridden. The CVDA value is:

NORECOVDATA

Forces all indoubt units of work (according to the transaction definitions), targets any resyncs that were outstanding for the IPCONN, and erases the logname previously received from the partner system. The state of the connection is reset.

Attention: You should use SET IPCONN NORECOVDATA only in exceptional circumstances. It erases recovery information and may compromise data integrity for units of work that have updated resources on remote systems.

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

• You need to discard an IPCONN, and it is not possible for the quiesce protocols with the partner system to be 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: SET IPCONN NORECOVDATA, SET IPCONN NOTPENDING, and SET IPCONN UOWACTION are mutually exclusive.

SERVSTATUS(cvda)

Specifies whether the IPCONN is to be placed in service or out of service. CVDA values are as follows:

INSERVICE

The IPCONN is to be placed in service. This allows it to be acquired.

OUTSERVICE

The IPCONN is to be placed out of service; that is, not available for use.

The following occurs:

• If the connection is currently ACQUIRED and you specify OUTSERVICE, the command fails with INVREQ and a RESP2 of 2. You must RELEASE the connection before setting OUTSERVICE.
• If the connection is currently RELEASED, the status of the connection is set OUTSERVICE and it cannot be used until it is INSERVICE again.

UOWACTION(cvda)

Specifies that the normal resynchronization process is to be partially overridden: decisions are taken for any units of work that are indoubt because of a failure of the IPCONN; but the decisions are recorded and any data inconsistencies are reported when the connection is next acquired.

The operation is synchronous with setting the state of the UOW; that is, an INQUIRE UOW following a SET IPCONN UOWACTION returns the new UOW states. CVDA values are as follows:

BACKOUT

All UOWs shunted because of the failure of this IPCONN are to be backed out.

COMMIT

All UOWs shunted because of the failure of this IPCONN are to be committed.

FORCE

All UOWs shunted because of the failure of this IPCONN are to be forced to BACKOUT or COMMIT, as specified on the ACTION option of the TRANSACTION definition.

RESYNC

Any UOWs shunted because of the failure of this IPCONN 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.

Notes:

1. SET IPCONN UOWACTION unshunts all units of work that have failed indoubt because of a failure of the IPCONN. Before issuing SET IPCONN FORCE, you may want to use the SET UOW command to specify commit or backout for each indoubt unit of work explicitly, rather than letting it default. Local procedures will 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.
2. As far as shunted units of work are concerned, you may use only one of SET IPCONN UOWACTION, SET IPCONN NOTPENDING, and SET IPCONN NORECOVDATA. SET IPCONN NORECOVDATA should be used only in exceptional circumstances.
3. To force all indoubt units of work caused by a failure of the IPCONN in the same direction, use SET IPCONN COMMIT or SET IPCONN BACKOUT.
4. Neither SET IPCONN UOWACTION nor the SET UOW UOWACTION command clears resync information. If you want to do this, you must use SET IPCONN NOTPENDING or SET IPCONN NORECOVDATA.
5. You can issue SET UOW UOWACTION commands before issuing SET IPCONN NOTPENDING or SET IPCONN NORECOVDATA.

Conditions

INVREQ

RESP2 values:

2

ACQUIRED and OUTSERVICE are specified inconsistently in any of the following ways:

1. ACQUIRED specified with OUTSERVICE
2. ACQUIRED specified for OUTSERVICE IPCONN resource
3. RELEASED and OUTSERVICE specified in the same command for an ACQUIRED IPCONN resource.
4. OUTSERVICE specified for an IPCONN resource that is not RELEASED

3

CONNSTATUS has an invalid CVDA value.

4

SERVSTATUS has an invalid CVDA value.

7

PURGETYPE has an invalid CVDA value.

8

PENDSTATUS has an invalid CVDA value.

18

NOTPENDING cannot be set for an IPCONN that has successfully completed exchange lognames processing.

19

CONNSTATUS cannot be set to ACQUIRED when in the FREEING state.

20

An attempt was made to acquire a one-way IPCONN.

21

BACKOUT or FORCE was specified, but was unsuccessful. Some UOWs remain shunted for this IPCONN.

22

Other SET parameters were included with the CANCEL or FORCECANCEL option.

25

IPCONN is still in service.

26

RECOVSTATUS does not have a value of NORECOVDATA.

27

The CVDA value specified on the UOWACTION option is invalid.

45

NORECOVDATA cannot be set for an IPCONN that is in service.

IOERR

RESP2 values:

10

Unexpected error.

NORMAL

RESP2 values:

58

AIDs have been successfully canceled.

59

No AIDs have been canceled.

NOTAUTH

RESP2 values:

100

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

SYSIDERR

RESP2 values:

9

The named IPCONN could not be found.