SET CONNECTION

Description

You can use the SET CONNECTION command to change some of the attributes that define an MRO or ISC over SNA connection. 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®.

The process of acquiring and releasing the APPC sessions associated with ISC over SNA connections involves starting the LU Services Manager transaction CLS1. To pass data to the CLS1 transaction, CICS uses a temporary storage queue with the default prefix DF. If temporary storage queues with the prefix DF are defined as recoverable in your installation, you must follow the SET CONNECTION command by a SYNCPOINT command to end the logical unit of work and allow the SET CONNECTION command to complete.

Options

ACQSTATUS(cvda) (APPC only)

This option is retained only for compatibility purposes. Use CONNSTATUS in new applications.

AFFINITY(cvda) (APPC and LU61 only)

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 LU6.1 connections. The connection must be out of service and, for APPC, in NORECOVDATA state.

The CVDA value is:

ENDAFFINITY

End the affinity.

Notes:

1. There is no facility in z/OS Communications Server for inquiring on affinities, so CICS has no certain knowledge that an affinity exists for a given connection. Whenever there is a possibility that an affinity has been created that must be ended explicitly, CICS issues message DFHZC0177. This message gives the NETNAME and NETID of the suspect connection.
2. If a request to end an affinity is rejected by z/OS Communications Server because no such affinity exists, CICS issues message DFHZC0181.
3. Generic resources and affinities are described in Workload balancing in a sysplex.

CONNECTION(data-value)

Specifies, as a 4-character field, the APPC, IRC, or LUTYPE6.1 connection. This is the name of the remote system or region specified in the CONNECTION option of the CEDA DEFINE CONNECTION command.

CONNSTATUS(cvda) (APPC only)

Specifies whether to acquire or release sessions with the logical unit represented by the CONNECTION name. To get more detailed information about the availability status of the connection elements, use the INQUIRE MODENAME START, NEXT, and END commands. A connection cannot be both ACQUIRED and OUTSERVICE.

CVDA values are:

ACQUIRED

Sessions are to be acquired.

RELEASED

Sessions are to be released.

For further information about managing APPC connections, see Managing APPC links.

Note: CONNSTATUS is applicable to IRC connections for the INQUIRE CONNECTION command but not for the SET CONNECTION command. The CONNSTATUS of an MRO connection is controlled by setting the connection INSERVICE or OUTSERVICE using the SERVSTATUS CVDA.

EXITTRACING(cvda) (z/OS Communications Server only)

Specifies whether to trace the activity associated with the terminal exit program for the sessions associated with this connection. CVDA values are:

EXITTRACE

The activity is to be traced.

NOEXITTRACE

The activity is not to be traced.

PENDSTATUS(cvda)(APPC and CICS-to-CICS MRO only)

Specifies, for either of the following kinds of connection, that the normal resynchronization process is to be overridden:

• A connection to a CICS Transaction Server for z/OS partner that has performed an initial start
• A connection to a pre-CICS Transaction Server for z/OS partner that has performed a cold start.

The CVDA value is:

NOTPENDING

Forces all indoubt units of work (according to the transaction definition) that were created by the connection before the initial (or cold) start of the partner. It also forgets any resyncs (waitforget UOW-links) that are outstanding for the connection, and created before the initial (or cold) 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. For a CICS Transaction Server for z/OS partner, a lognames mismatch indicates that the partner has performed an initial start. For a pre-CICS Transaction Server for z/OS partner, a lognames mismatch indicates that the partner has performed a cold start. In either case, 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 this system 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 CONNECTION NOTPENDING, SET CONNECTION NORECOVDATA, and SET CONNECTION 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 and SNA LU 6.2 Peer Protocols.

PURGETYPE(cvda)

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

CANCEL

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 are not canceled. In addition, the following CICS system AIDs are not purged unless FORCECANCEL is specified.

Table 1. System AIDs requiring FORCECANCEL to remove them

AIDS requiring FORCECANCEL	Name
Remote delete AIDs
Remote scheduler AIDs	CRSR
LU6.2 service manager 1 AIDs	CLS1
LU6.2 service manager 3 AIDs	CLS3
Remote schedule PURGE AIDs	CRSQ
Resource manager resync AIDs	CRSY
Autoinstall terminal delete AIDs	CATD
Restart terminal delete AIDs	CATR

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

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, this remote AID is canceled asynchronously.

FORCECANCEL

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 FORCECANCEL to remove them. This can lead to unpredictable results and should be used only in exceptional circumstances.

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

FORCEPURGE

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.

For indoubt and shunted UOWs, FORCEPURGE has no effect.

Note: To force shunted UOWs, the operator must issue SET CONNECTION COMMIT, BACKOUT, or FORCE following a FORCEPURGE. This can lead to unpredictable results and should be used only in exceptional circumstances.

KILL

The task is to be terminated. System and data integrity is not guaranteed. The KILL option extends the PURGE and FORCEPURGE options. It should be used 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

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, or if the UOW is shunted.

RECOVSTATUS(cvda) (APPC only)

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 connection, and erases the logname previously received from the partner system. The state of the connection is reset.

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

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

• You need to discard a connection, or issue a SET CONNECTION ENDAFFINITY command, and it is not possible for the quiesce protocols with the partner system to be completed. (Neither action is possible for an APPC connection if recovery data is outstanding.)
• 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 CONNECTION NORECOVDATA, SET CONNECTION NOTPENDING, and SET CONNECTION UOWACTION are mutually exclusive.

SERVSTATUS(cvda)

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

INSERVICE

The system is to be placed in service; that is, to be available for use.

For an MRO connection, all sessions are placed in service and the following occurs:

• If both the issuing system and the remote system have IRC open, and the remote system has INSERVICE connection definition for the issuing system, the connection is made ACQUIRED (see the note following the description of the CONNSTATUS option).
• Otherwise, the status of the connection is set INSERVICE so that the connection is acquired when the above conditions are met.
• The status of the underlying sessions for a connection is always the same as that for the connection itself.

For an EXCI connection, all receive sessions (or pipes) are placed in service and available for use by the client program.

For an ISC APPC connection, the LU Services Manager sessions are placed in service, thereby enabling the connection subsequently to be acquired.

For an ISC LU6.1 connection, all sessions are placed in service.

OUTSERVICE

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

For a connection, all sessions are placed out of service (immediately if PURGE is specified, or when tasks have terminated if it is not) and the following occurs:

• If an APPC 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 any other connection is currently ACQUIRED, the sessions are broken (quiesced). The connection cannot be used until it is once again placed INSERVICE.
• If the connection is currently RELEASED, the status of the connection is set OUTSERVICE and it cannot be used until it is INSERVICE again.
• The status of the underlying sessions for a connection is always the same as that for the connection itself.

For an EXCI connection, all receive sessions (or pipes) are placed out of service and are not available for use by the client program.

For an ISC APPC system, this option is valid only if the connection is RELEASED. The LU Services Manager sessions are placed out of service, and the connection cannot be ACQUIRED until it is placed INSERVICE again.

For an ISC LU6.1 connection, all sessions are released and placed out of service: immediately if PURGE or FORCEPURGE is specified; or when tasks have terminated if neither PURGE nor FORCEPURGE is specified. If the response to an INQUIRE CONNECTION command shows OUTSERVICE, it does not imply that the connection has been explicitly set as SET OUTSERVICE; in particular circumstances, you cannot reinstall this connection.

UOWACTION(cvda) (APPC parallel-session, CICS-to-CICS MRO, and LU61 only)

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 connection; 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 CONNECTION UOWACTION returns the new UOW states. CVDA values are:

BACKOUT

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

COMMIT

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

FORCEUOW

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

RESYNC (MRO-to-CICS Transaction Server for z/OS and later systems, and APPC only)

Any UOWs shunted because of 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.

Notes:

1. SET CONNECTION UOWACTION unshunts all units of work that have failed indoubt because of a failure of the connection. Before issuing SET CONNECTION 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 CONNECTION UOWACTION, SET CONNECTION NOTPENDING, and SET CONNECTION NORECOVDATA. SET CONNECTION NORECOVDATA should be used only in exceptional circumstances.
3. To force all indoubt units of work caused by a failure of the connection in the same direction, use SET CONNECTION COMMIT or SET CONNECTION BACKOUT.
4. Neither SET CONNECTION UOWACTION nor the SET UOW UOWACTION command clears resync information. If you want to do this, you must use SET CONNECTION NOTPENDING or SET CONNECTION NORECOVDATA.
5. You can issue SET UOW UOWACTION commands before issuing SET CONNECTION NOTPENDING or SET CONNECTION NORECOVDATA.

ZCPTRACING(cvda) (z/OS Communications Server only)

Specifies whether the z/OS Communications Server control component of CICS is to trace activity on the sessions associated with this connection. CVDA values are:

NOZCPTRACE

z/OS Communications Server ZCP tracing is not to be carried out.

ZCPTRACE

z/OS Communications Server ZCP tracing is to be carried out.

Conditions

INVREQ

RESP2 values:

1

ACQSTATUS|CONNSTATUS specified for a non-APPC connection.

2

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

1. ACQUIRED specified with OUTSERVICE
2. ACQUIRED specified for OUTSERVICE connection
3. OUTSERVICE specified for ACQUIRED APPC connection.
4. RELEASED and OUTSERVICE specified in the same command for an ACQUIRED connection.

3

ACQSTATUS|CONNSTATUS has an invalid CVDA value.

4

SERVSTATUS has an invalid CVDA value.

5

PENDSTATUS or NOTPENDING was specified for a connection that is not APPC or IRC.

6

PURGE was specified for a connection that is not z/OS Communications Server.

7

PURGETYPE has an invalid CVDA value.

8

PENDSTATUS has an invalid CVDA value.

11

SET command named a remote connection.

12

EXITTRACING has an invalid CVDA value.

13

ZCPTRACING has an invalid CVDA value.

14

EXITTRACING|ZCPTRACING specified for a non-z/OS Communications Server connection or z/OS Communications Server not initialized.

16

The resource whose name was specified by CONNECTION(data-value) is an indirect link.

17

ACQSTATUS|CONNSTATUS cannot be set when system initialized with ISC=NO.

18

NOTPENDING cannot be set for a connection which has successfully completed Exchange Lognames processing.

19

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

20

COMMIT, BACKOUT, FORCE, or RESYNC is not valid for this type of connection.

21

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

22

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

23

The resource whose name was specified by CONNECTION(name) is the local TCT system entry (TCTSE).

25

Connection is still in service.

26

RECOVSTATUS does not have a value of NORECOVDATA.

30

Wrong connection type for ENDAFFINITY. Affinities can exist only on LU6.1 and LU6.2 connections.

31

The NETID could not be obtained from the installed connection. Therefore, to end an affinity you must use the PERFORM ENDAFFINITY command.

32

See message DFHZC0178. z/OS Communications Server could not end the affinity for a reason other than 35 (NOTFOUND) or 36 (SESSIONS ACTIVE).

35

z/OS Communications Server could not find an affinity for this connection.

36

z/OS Communications Server could not end the affinity because the connection had some sessions active.

37

See message DFHZC0176. A z/OS Communications Server error prevented the CHANGE ENDAFFIN macro being carried out.

44

GRSTATUS is not set to REGISTERED or DEREGISTERED. (No generic resource name.)

45

NORECOVDATA cannot be set for a connection that is in service.

46

NORECOVDATA was specified for a non-APPC connection.

IOERR

RESP2 values:

10

Unexpected error.

NORMAL

RESP2 values:

58

AIDs are successfully canceled.

59

No AIDs are 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 connection could not be found.