Ending affinities

When a session is established with a member of a generic resource, VTAM® creates an association called an affinity between the generic resource member and the partner LU, so that it knows where to route subsequent flows. In most cases, VTAM ends the affinity when all activity on the session has ceased. However, for some types of session, VTAM assumes that resynchronization data may be present, and therefore relies on CICS® to end the affinity. The sessions affected are:

In VTAM terms, the CICS generic resource member "owns" the affinity and is responsible for ending it. The affinity persists even after a connection has been deleted or CICS has performed an initial or cold start. For a connection between two generic resources, both partners own an affinity, and each must be ended. For APPC connections between CICS TS OS/390®, Version 1 Release 3 or later regions, the APPC connection quiesce protocol does this automatically--see APPC connection quiesce processing. For other connections, the affinities must be ended explicitly.

CICS provides commands that can be used to end affinities explicitly:

These commands are valid only for LU6.1 and APPC connections. The connection, if present, must be out of service and its recovery status (as shown by the RECOVSTATUS option of the INQUIRE CONNECTION command) must be NORECOVDATA. Note that only those affinities that are owned by CICS can be ended by CICS.

CICS has no certain knowledge that an affinity exists for a given connection. To help you, message DFHZC0177 is issued whenever there is a possibility that an affinity has been created that you may have to end explicitly. This message gives the NETNAME and NETID to be used on the PERFORM ENDAFFINITY command.

Having received message DFHZC0177, to check whether an affinity that must be ended explicitly does indeed exist, you can use the SNA D NET,GRAFFIN command. This command produces messages IST1706 and IST1707, which should contain the information you need. Alternatively, the MVS/ESA Version 5 Interactive Problem Control System (IPCS) Commands manual, GC28-1491, tells you how to produce a dump of the VTAM ISTGENERIC data area. This contains SPTE records that show which affinities exist. For example, start the dump with:

DUMP COMM=(title)

Reply with:

r xx ,STRLIST=(STRNAME=ISTGENERIC,
                  ACC=NOLIMIT,(LNUM=ALL,ADJ=CAP,EDATA=SER))

Look at the dump with:

STRDATA DETAIL ALLSTRS ALLDATA

If a request to end an affinity is rejected by VTAM because no such affinity exists, message DFHZC0181 is issued. This may mean either that you supplied an incorrect NETNAME or NETID, or that you (or CICS) were wrong in supposing that an affinity existed.

When should you end affinities?

You need to end affinities if you reconfigure your sysplex. For example, you must end any relevant affinities before you do any of the following:

Note:
For connections between generic resources, you must end the affinities owned by both generic resources.

Writing a batch program to end affinities

If a generic resource member that owns affinities fails and cannot be recovered, the affinities must be ended. In a case like this, you cannot use the SET CONNECTION ENDAFFINITY or PERFORM ENDAFFINITY commands. Instead, you can use a batch program to clear the affinities owned by the failed member. This section demonstrates how to write such a batch program. The program must be written in assembler language.

Note:
You can use the dump technique described in the MVS/ESA Version 5 Interactive Problem Control System (IPCS) Commands manual to discover what affinities the failed generic resource member owns.
Important

You should use this technique only if it is impossible to restart the failed CICS system.

Program input

The following input parameters are needed:

Program output

The program uses the VTAM CHANGE OPTCD=ENDAFFIN macro to end the affinities. You will probably need to produce a report on the success or failure of this and the other VTAM macro calls that the program uses. Consult the OS/390 eNetwork Communications Server: SNA Programming manual for the meaning of RTNCD/FDB2 values.

Processing

  1. Reserve storage for the following:
  2. Issue a VTAM OPEN command for the ACB of the member which owns the affinity, passing the input APPLID for this member.
  3. If any sessions persist, use the VTAM SENDCMD macro to terminate them. (If you are not using persistent sessions this will not be necessary.)
    1. Move the following command to an area in storage. In this example, applid1 is the member name of the failed member and applid2 is the APPLID of the partner system.
      'VARY NET,TERM,LU1=applid1,LU2=applid2,TYPE=FORCE,SCOPE=ALL'
    2. Issue the SENDCMD macro, as in the example below. In this example:
      • rpl-name is the name of an RPL.
      • acb-name is the ACB of the failed sysplex member.
      • output-area is the name an area in storage where the VARY command is held.
      • command-length is the length of the command.
               SENDCMD  RPL=rpl-name,
                     ACB=acb-name,
                     AREA=output-area,
                     RECLEN=command-length,
                     OPTCD=(SYN)
  4. Use the VTAM RCVCMD macro to receive messages from VTAM. Note that RCVCMD must be issued three times after the SENDCMD to be sure that the VARY command worked correctly. In the following example:
             RCVCMD  RPL=rpl-name,
                   ACB=acb-name,
                   AREA=input-area,
                   AREALEN=receive-length,
                   OPTCD=(SYN,TRUNC)
  5. Issue this command twice more to make sure of receiving all the output from VTAM.
  6. Issue the VTAM CHANGE OPTCD=ENDAFFIN macro to end the affinity. Before issuing the macro the following fields must be initialized in the NIB:
             CHANGE  RPL=rpl-name,
                   ACB=acb-name,
                   NIB=nib-name,
                   OPTCD=(SYN,ENDAFFIN)
  7. Issue VTAM CLOSE command for the ACB.
Programming notes:
  1. The VTAM commands should be synchronous, to avoid the use of exits (OPTCD=SYN).
  2. Care must be taken not to run the program for an APPLID of a running CICS. If you do, and you are using VTAM persistent sessions, a predatory takeover will occur--that is, your program will assume control of the sessions belonging to the APPLID.

JCL for submitting the ENDAFFINITY program

Figure 36. Example JCL for submitting the ENDAFFINITY program
//JOBNAME   JOB 1,userid,
// NOTIFY=userid,CLASS=n,MSGLEVEL=(n,n),MSGCLASS=n,REGION=1024K
//*
//JOBLIB    DD DSN=loadlib-name,DISP=SHR
//*
//*******************************************************************
//* PARM='FAILED_APPLID,FAILED_GENERIC,PARTNER_NETID,PARTNER_APPLID'
//*******************************************************************
//*
//RUN    EXEC PGM=ENDAFFIN,PARM='parm1,parm2,parm3,parm4'
//*
//REPORT    DD SYSOUT=*
//SYSPRINT  DD SYSOUT=*
//

Related tasks
Planning your CICSplex to use VTAM generic resources
Defining connections in a generic resource environment
Generating VTAM generic resource support
Migrating a TOR to a generic resource
Removing a TOR from a generic resource
Moving a TOR to a different generic resource
Setting up inter-sysplex communications between generic resources
Using ATI with generic resources
Using the ISSUE PASS command
Dealing with special cases
Related reference
Prerequisites for VTAM generic resources
Rules checklist
[[ Contents Previous Page | Next Page Index ]]