Affinity considerations

When you define an affinity, you must specify its lifetime. The affinity normally persists until its specified lifetime expires.

You can define one of the following types of lifetime:
Activity
Expires when the CICS BTS activity ends
Delimit
Expires when the PCONV mode of the transaction is END
Logon
Expires when the terminal user logs off.
Pconv
Expires when a transaction uses EXEC CICS RETURN specifying no NEXTTRANSID or the PCONV mode of the transaction is END.

CICS does not support pseudoconversations for APPC (LUTYPE6.2) devices.

Permanent
Expires when the workload of which the target region is a part terminates
Process
Expires when the CICS BTS process ends
Signon
Expires when the terminal user signs off.
System
Expires when the target region terminates
UOW
Expires when the unit of work associated with the transaction ends. The unit of work ends either when a CICS SYNCPOINT or ROLLBACK request is run, or when the originating task terminates.
There are circumstances when SM_SCOPE generates a scope list containing a single affinity target region, but the target region is not available for routing. This happens when:
  • The target region is down.
  • The CICS link to the target region is down.
  • The target region is currently active but it was shutdown and restarted after the affinity was created.

In these cases, the EYU9WRAM default processing issues a terminal message indicating that the affinity target region is not available and causes the transaction to terminate. If the affinity lifetime is PCONV (pseudoconversation), CICSPlex® SM automatically deletes the affinity because it has expired (there is no NEXTTRANSID). However, the default EYU9WRAM processing does not delete any other affinities because the characteristics of the actual affinity to the target region are unknown. For example, a LOGON affinity may involve the use of the TCTUA to pass information to the target region. If the affinity is deleted when the target region is not available, the next transaction for the transaction group would cause a new target region to be selected. The transaction might fail upon using the TCTUA contents when routed to the new target region.

The sample EYU9WRAM program, which implements the default processing, contains a subroutine that checks on affinity status after a call to SM_SCOPE. When an affinity is active to an target region, but not committed, and the affinity target region status is not OK, the subroutine sends a message to the terminal user and then exits so that the EYU9WRAM program terminates. The subroutine contains an unexecuted code fragment that can be used to delete the affinity using the SM_DELAFF call. Before the unexecuted code fragment is a series of tests for the affinity lifetime of the active affinity. One or more of the branches can be changed to jump to the code fragment. The code fragment itself deletes the affinity, issues a message, and then returns so that the EYU9WRAM program exits, thereby causing the transaction to terminate. This processing can be modified so that the affinity is deleted, no message is issued, and the subroutine exits causing the mainline process to reexecute the SM_SCOPE call. In that case, a new set of target regions is received for use by SM_BALANCE.

The same subroutine also contains an unexecuted code fragment that can be enabled to create an affinity. In this case, the subroutine has determined that an affinity is defined but not active. It then checks the WCOM_AFF_AUTO indicator to determine whether CICSPlex SM should automatically create affinities during SM_BALANCE. The subroutine exits normally no matter what the answer is. You can enable the SM_CREAFF fragment in order to cause an affinity to be created. The SM_CREAFF call may be used regardless of whether WCOM_AFF_AUTO does or does not indicate the automatic creation of affinities during SM_BALANCE. The SM_CREAFF call can therefore be used to:
  • Create an affinity when CICSPlex SM will not.
  • Create an affinity to a target region that CICSPlex SM would ordinarily not select.
The SM_CREAFF code fragment creates an affinity to the target region that appears first in the scope list returned by SM_SCOPE.
The following fields in the EYURWCOM communication area provide information regarding CICSPlex SM affinity processing.
  • WCOM_AFF_STAT
  • WCOM_AFFAOR_STAT
  • WCOM_AFF_TYPE
  • WCOM_AFF_LIFE
  • WCOM_AFF_AUTO
  • WCOM_WORK_NAME
  • WCOM_TGRP_NAME