Distributed Dynamic VIPA

With Dynamic Virtual IP Addressing (DVIPA), you can concurrently run identical setups on different systems in your sysplex, and have TCP/IP, optionally with the help of WLM, distribute the client connections among these systems.

As Debug Manager works together with IBM Explorer for z/OS to allow remote debugging from Eclipse clients, the distributed DVIPA supported by z/OS Explorer is also available with Debug Manager, but with the following considerations:

Debug Manager only communicates with z/OS Explorer’s Remote System Explorer daemon (RSED) started task that is active on the same system. This implies that a Debug Manager started task (DBGMGR) must be active on each system of your sysplex where RSED is active.
Unlike in z/OS Explorer where TCP/IP can choose which system a user will connect to, the client connection to Debug Manager must be sent to the system that the debug session has started. To achieve this, each Debug Manager must use a unique external port (the CLIENT variable in the started task).
Each of the unique Debug Manager ports must be defined to TCP/IP in the VIPADISTRIBUTE PORT statement.

Unique external ports

When a remote debug session is started, Debug Manager informs the Eclipse client about the port that it is listening at. In a distributed DVIPA scenario, this port must be unique in the sysplex so that the Sysplex Distributor can use this to send the client connection to the correct system.

You can use a started task JCL per system, and use a unique port number in each JCL to ensure that each Debug Manager has a unique external port. A system symbol that holds the unique port number for that system can be used if you want to share the started task JCL across the systems.

If you already have a system symbol with a numeric value that is unique per system, for example, &SYSCLONE, you can make it part of the CLIENT port number definition in the started task JCL like in the following example:
```
//DBGMGR   PROC PRM=, 
//            LEPRM='RPTOPTS(ON)', 
//            TZ='EST5EDT', 
//            CLIENT=53&SYSCLONE, 
//            HOST=5336, 
//            HLQ=EQAW
```
Or you can use sample JCL SEQASAMP(EQADVIPA) to create system symbol EQADBM that holds the unique port number, and then reference EQADBM in the started task JCL:
```
//DBGMGR   PROC PRM=, 
//            LEPRM='RPTOPTS(ON)', 
//            TZ='EST5EDT', 
//            CLIENT=&EQADBM, 
//            HOST=5336, 
//            HLQ=EQAW
```
Note: The EQADBM system symbol must exist before the Debug Manager started task (DBGMGR) is started. For example, you can define EQADVIPA as started task to start it early in your IPL sequence.

Sample setup

In this example, the TCP/IP definitions for an existing z/OS Explorer distributed DVIPA setup are extended with Debug Manager ports 5331 and 5332 added to the definition. For more information about the original setup, see the “Distributed Dynamic VIPA” section in the “TCP/IP considerations” chapter of the IBM Explorer for z/OS Host Configuration Reference Guide.

Figure 1. Distributed Dynamic VIPA sample

Figure 2. System SYS1 – TCP/IP profile

IPCONFIG
; SYSPLEXROUTING is required as this stack needs sysplex communication
  SYSPLEXRouting
; DYNAMICXCF defines device/link with home address 9.9.9.1 as needed
  DYNAMICXCF 9.9.9.1   255.255.255.0   1
  IGNORERedirect

VIPADYNAMIC
; VIPADEFINE defines 9.9.10.1 as DVIPA, with this system as main controller
  VIPADEFINE 255.255.255.0   9.9.10.1 
; VIPADISTRIBUTE makes 9.9.10.1 a distributed DVIPA, must match SYS2
  VIPADISTRIBUTE DEFINE
    SYSPLEXPORTS               ; prereq, must be in first VIPADISTRIBUTE
    DISTMETHOD BASEWLM         ; BASEWLM
    9.9.10.1                   ; DVIPA address used by z/OS Explorer clients
    PORT 4035   5331   5332    ; zExpl & DBM ports used by zExpl clients
    DESTIP 9.9.9.1   9.9.9.2   ; z/OS Explorer active on SYS1 and SYS2
ENDVIPADYNAMIC

Figure 3. System SYS2 – TCP/IP profile

IPCONFIG
; SYSPLEXROUTING is required as this stack needs sysplex communication
  SYSPLEXRouting
; DYNAMICXCF defines device/link with home address 9.9.9.2 as needed
  DYNAMICXCF 9.9.9.2   255.255.255.0   1
  IGNORERedirect

VIPADYNAMIC
; VIPABACKUP defines 9.9.10.1 as DVIPA, with this system as backup controller
  VIPABACKUP 255.255.255.0   9.9.10.1 
; VIPADISTRIBUTE makes 9.9.10.1 a distributed DVIPA, must match SYS1
  VIPADISTRIBUTE DEFINE
    SYSPLEXPORTS               ; prereq, must be in first VIPADISTRIBUTE
    DISTMETHOD BASEWLM         ; BASEWLM
    9.9.10.1                   ; DVIPA address used by z/OS Explorer clients
    PORT 4035   5331   5332    ; zExpl & DBM ports used by zExpl clients
    DESTIP 9.9.9.1   9.9.9.2   ; z/OS Explorer active on SYS1 and SYS2
ENDVIPADYNAMIC

Communication example

Figure 4 shows an overview of how an Eclipse client connects and communicates to the host in a DVIPA environment with two LPARs. Debug Manager instances on those LPARs are listening to external ports 5334 and 5335 respectively.

When a user tries to log in to the host from an Eclipse client, Remote System Explorer (RSE) on the client connects to the RSE daemon on the host by using the virtual IP address and RSED port.
DVIPA picks an LPAR to connect to. In this example, LPAR1 is selected.
Debug Miner, a component of the RSE daemon finds out the DBM name-token pair in the system, reads the DBM internal port, connects to DBM, and notifies it that the user username is logged on to the system.
The user starts a job with TEST runtime option DBMDT%username. In this example, the job goes to LPAR2. The debugger finds out the host port of DBM in LPAR2 by reading its name-token pair and notifies DBM that a debug session for user username is waiting for a workstation to connect.
As the DBM on LPAR2 does not have username logged on, it contacts other DBM instances in the sysplex, notifying that a debug session is waiting and adding its external port number 5335 to the request. For more information, see Enabling sysplex support.
The DBM on LPAR1 has username logged on, so it picks up the request and notifies Debug Miner that there is a debug session for user username on port 5335.
The RSE daemon notifies the Eclipse client about the debug session and passes the port to connect to.
The remote debugger in the Eclipse client uses port 5335 to connect to DBM. As the connection IP address is a DVIPA address, a unique port is available, which only allows DVIPA to forward the request to the correct DBM instance in the sysplex.
DBM links the workstation connection to the debugger.
The debugger and the Eclipse client can now communicate directly to each other by using the established connection.