CPSM Dynamic Transaction Routing Considerations

Code Debug CICS supports debugging of dynamically routed transactions within a CICSPlex managed by CICSPlex System Manager. This support is limited to a single MVS system image, unless the optional TPCONFIG file (and TCP) are used to connect the multiple Service Providers that deal with the same CICSPlex. For information about defining the TPCONFIG file, see “Enabling-Debugging-Across-Multiple-LPARs-in-a-CICSPlex” in the Code Debug CICS Advanced Configuration space. For information about creating Service Provider entries in a member of the TPCONFIG file, see Using the Code Debug TP Configuration File.

When the Service Providers involved in a given CICSPlex are connected to each other, all region, session, and routing mask information is shared among them. Because each Service Provider has complete and accurate information about Code Debug CICS debugging sessions within the entire CICSPlex, routing decisions that involve crossing LPAR boundaries can be made properly.

Make sure the following steps have been performed before trying to use Code Debug CICSPlex support:

• Install and activate the Code Debug Workload Manager exit in the CICS terminal owning regions (TORs).
• Install and activate Code Debug in the CICS application owning regions (AORs) with CICSPlex support enabled (DYNAMIC_TRANSACTION_ROUTING_SUPPORT=YES).

Code Debug Transaction Routing

The Code Debug CICSPlex Workload Manager exit routes Code Debug transactions only to CICS regions that have Code Debug activated with CICSPlex support enabled. These CICS regions are referred to as Code Debug debugging regions.

Code Debug may require additional information when a debugging session is established, depending on your CICSPlex configuration and application design. No additional information is required unless your application is dependent on affinities and/or executes in a CICSPlex composed of non-identical members (imperfect clones). The following sections show how to initiate Code Debug transactions with the optional routing information.

Code Debug uses four different methods for routing Code Debug transactions:

• Specific region routing (SYsid=region or Applid=region APPLID)
• Transaction scope routing (Tranid=trans)
• Most recently used routing
• Workload balancing routing.

In each case, the region to which Code Debug routes the transaction must have CICSPlex support active (DYNAMIC_TRANSACTION_ROUTING_SUPPORT=YES) and be registered with the Code Debug Service Provider.

For Code Debug transactions XPED, XPRT, and XPSP, Code Debug’s CICSPlex support will first look for the presence of specific region routing, then for transaction scope routing, and finally the most recently used routing. If no additional routing parameters were entered and no recent debugging session is active, the Code Debug transaction will use the workload balancing routing method. For all Code Debug transactions other than XPED, XPRT, and XPSP, the determination for routing is the same, but transaction scope is not available.

Specific Region Routing

With specific region routing of Code Debug transactions, the user specifies the CICS region where the Code Debug transaction is to be executed. Specific region routing would be used when a programmer wants the Code Debug transaction to routed to a specific CICS region.

In a DTR environment, the optional SYsid=sysidnt or Applid=applid parameter can be used with any Code Debug transaction except the demo transactions. The SYsid or Applid parameter is required for the transactions in the following Table because they make global changes to the environment.

Transactions Requiring SYsid or Applid Parameter in DTR Environment

For example, entering the transaction

will start a Code Debug CICS debugging session for program CWDEMCB2 in the CICS region with a SYSIDNT of AOR1. Entering the transaction

will load a new version of program CWDEMCB2 in the CICS region with SYSIDNT AOR2. To process Code Debug global parameters in a region whose APPLID is CICSAOR3, you would enter the transaction

Initialization of Code Debug in the CICS region with SYSIDNT AOR4 can be started by entering

Transaction Scope Routing

With transaction scope routing of XPED, XPRT, and XPSP transactions, the user specifies the user transaction that will be used in determining an eligible Code Debug debugging region. The Code Debug Workload Manager exit will determine which CICS regions are in scope for the specified transaction, then select one of those regions that also has Code Debug active. If there are no Code Debug debugging regions in the scope list, the Code Debug transaction routing will fail. Transaction scope routing could be used when a programmer wants to direct the Code Debug transaction to a CICS region that is in the target scope of a specific application transaction. It could also be useful when debugging a transaction that has affinities that limit the execution of the application to only certain CICS regions.

For example, entering the following Code Debug transaction:

will start a Code Debug CICS debugging session in a region that both has Code Debug initialized and is eligible to run transaction XCB2. Code Debug will then display the source for program CWDEMCB2.

Most Recently Used Routing

With most recently used routing of Code Debug transactions, the Code Debug Workload Manager exit will route the Code Debug transaction to the Code Debug debugging region that was used in the prior invocation. Most recently used routing would be used when the programmer wants to reestablish or terminate the most recent debugging session.

If a  Code Debug CICS debugging session had already been started in AOR1 by the transaction in the previous example, entering the following Code Debug transaction:

will result in most recently used routing also sending this transaction to AOR1. Source will then be displayed for program CWDEMCB2. Code Debug CICS will always return your debugging session to the most recently used region unless specifically routed with the SYsid, Applid, or Tranid parameters.

Workload Balancing Routing

With workload balancing routing of Code Debug transactions, the user allows CICSPlex Workload Manager and the Code Debug Workload Manager exit to select a Code Debug debugging region when the debugging session is established. Workload balancing routing would be used when a programmer knows that the transactions to be debugged do not have affinities and the CICSplex is composed of identical members.

For example, entering the following Code Debug transaction:

with no Code Debug CICS debugging session active for the terminal will result in workload balancing routing automatically selecting an eligible region and routing the transaction there. Code Debug will then display source for program CWDEMCB2.

User Transaction and Distributed Program Link Routing

The Code Debug Workload Manager exit routes user transactions and distributed program link requests based on Code Debug routing masks, established affinities, and transaction scope. When a route is processed, the Code Debug Workload Manager exit locates any matching Code Debug routing masks based on user ID, network name, terminal ID, transaction ID, client IP address, server IP address, and server port number. If the matching entry is within scope and the target CICS region is within the scope list and has not been marked ignore, the Code Debug Workload Manager exit routes the transaction or DPL request to the CICS region with the active debugging session. If the route fails, the Code Debug Workload Manager exit locates the next routing mask registered. If all routing masks are processed without a successful route, the request is routed to the CICS region selected by the CICSPlex Workload Manager. The Code Debug Workload Manager exit traces all successful routes and records the route information and the matching routing mask entry.

You should be as specific as possible when defining trap masks in Code Debug. Generic trap masks can cause transactions not intended for debugging to be routed to Code Debug debugging regions. Generic trap masks could also cause the debugging of other user’s transactions to be routed to the wrong Code Debug debugging region. Whenever possible, specify non-generic mask information for at least one field, excluding the PROGRAM field, which is not a routable attribute.

In the following example, the first trap mask shown was set in AOR1, the second in AOR2, and the third in AOR3.

Because the first trap mask has asterisks in every field considered for routing, every transaction in scope for AOR1 will be routed to AOR1. This may overload the region and cause debugging sessions to be missed for the second and third trap masks.

The second trap mask will cause all transactions with IDs starting with X that are in scope for AOR2 to be routed to AOR2. This will result in the missing of debugging sessions for the third trap mask.

Distributed program links, once routed into an AOR, no longer match the trap criteria because of the impact of routing. For example, IP input from TCPIPSERVICE connections have their DPL routing requests influenced correctly by client and/or server IP information. However, when the application program runs in the AOR, its facility is an MRO/ISC session and that program is no longer associated with the client IP address or TCPIPSERVICE. To correct this CICS DPL issue, Code Debug CICS recognizes DPL-routed work in the AOR and corrects the information used for trapping by obtaining it from Code Debug CICS Routing Trace records. This process is not foolproof; when multiple DPL requests with the same userID, transaction code, and program name are routed to the same AOR before Code Debug CICS in that AOR can access its Routing Trace records, the product may obtain incorrect information for some of those DPL requests.

XPON Transaction

The XPON transaction is used to manually initialize Code Debug CICS in specific AOR.

PLTPI processing is typically used to initialize Code Debug CICS in the AORs of a CICSPlex environment. (For more information, see “Configuring-Intercommunication-Facilities” in the Code Debug CICS Advanced Configuration space.) During this initialization, Code Debug CICS registers its presence in the region with the Code Debug Service Provider. When subsequent XPED, XPSP, or XPRT transactions are entered, the Code Debug CICS dynamic transaction router (DTR) exit EYU9WRAM is able to identify the regions available for Code Debug debugging sessions.

If, however, Code Debug CICS is shut down in an AOR, it cannot be reinitialized there by PLTPI processing unless you cycle the region. Because shutting down de-registers the AOR from the Code Debug Service Provider, and the DTR no longer knows of its existence, the XPED, XPSP, and XPRT transactions can also not be used to initialize Code Debug CICS in the region. Use the XPON transaction to initialize Code Debug CICS, and specify the desired AOR with Specific Region Routing. For example:

XPON,SYSID=AOR4 XPON,APPLID=CICSAOR4

Adding a Service Provider to an Active CICSPlex

When adding a new Service Provider to an active CICSPlex, no action is required for existing active Service Providers to immediately recognize the new one. The new Service Provider should have entries in the TPCONFIG member it references that identify all of the Service Providers involved in the CICSPlex. For eventual restart purposes, the TPCONFIG members referenced by all of the other Service Providers in the CICSPlex should be modified to include the new Service Provider.

When a Service Provider starts, it sends an “I am awake” message to all other Service Provider entries in its TPCONFIG member. If a receiving Service Provider does not recognize the new one, that new one is dynamically inserted into the receiver’s list of connected Service Providers and is sent all existing region, session, and routing mask information local to the receiving Service Provider.

When a Service Provider ends, it sends an “I am shutting down” message to all of its connected Service Providers. Receiving Service Providers immediately delete information pertaining to regions, sessions, and routing masks that were local to the Service Provider shutting down.

Every “I am awake” and “I am shutting down” message received by a Service Provider is logged in its JESLOG, as “connected” or “disconnected”.