Skip to Content
Information
Space announcement This documentation space provides the same content as before, but the organization of the content has changed. The content is now organized based on logical branches instead of legacy book titles. We hope that the new structure will help you quickly find the content that you need.

Installing in a CPSM Dynamic Routing Environment

Related topic

Customizing-after-installation

The dynamic MRO support provided by Code Debug CICS requires IBM’s CICSPlex SM (CPSM). For information on supported release, see Installation-and-Configuration-Guide space.

To effect dynamic routing of transactions in a CICSPlex, Code Debug CICS utilizes a CPSM routing exit, DBUGWRAM, which is typically run in a terminal owning region (TOR). This is distinct from the Code Debug CICS debugger, which normally runs in an application owning region (AOR). The DBUGWRAM exit gains controls via the Global User Exit (GLUE) point XPCFTCH and XPCREQC. After a link is made to CPSM module EYU9WRAM from EYU9XLOP, the Code Debug module DBUGWRAM gains control and determines if the transaction being routed is an Code Debug transaction (XPED, XPSP, etc.) or an application transaction that matches a trap set in Code Debug CICS. In either of these cases, module DBUGWRAM will route the transaction to an applicable CICS region containing Code Debug CICS.

DBUGWRAM now supports CICSPlex environments that cross LPAR boundaries when using Workbench for Eclipse (Code Debug Eclipse). For more details and illustrated examples, see Workbench for Eclipse in a CPSM CICSPlex Environment. When using Code Debug Eclipse and starting a debugging session to a TOR, if the XSOC transaction is to be routed to a different LPAR, the code in DBUGWRAM will save the region where XSOC was intended to be routed. Due to the limitations of TCP/IP, the XSOC transaction will remain in a region in the CICSPlex that is running in the same LPAR as the TOR and is also running Code Debug CICS. The actual debugging session will actually start in the original AOR in which XSOC was originally slated to run. DBUGSOCK, the program associated with XSOC, contains the socket communication code and communicates with the actual Code Debug CICS debugging code using CICS containers. The debugging code (XDPIMIRS) will run in the AOR in which XSOC was originally slated to run. In the event that Workbench for Eclipse visualization is being used, or when events such as breakpoints or abends occur, these events are communicated back to the DBUGSOCK LPAR using a new program, DBUGREMS (transaction XSRE).

The Code Debug Service Provider keeps track of all active traps within all AORs of each CICSPlex. User-ID, Transaction Code, Terminal-ID, Netname, Client IP Address, Server IP Address, and Server Port trap fields are provided by the service provider to DBUGWRAM in the TOR to influence routing. Once routed to an appropriate AOR, all trap fields, including those that did not participate in the routing decision (Program Name, Enhanced Trapping Criteria), determine if the trap is actually matched when an abend and/or breakpoint is hit.

Code Debug CICS module DBUGWRAM also influences CPSM dynamic routing of distributed program links (DPL). 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.

One of the features of Workbench for Eclipse is that it allows debugging of transactions initiated from terminal emulators on the same workstation as the Workbench for Eclipse debugging session. The user specifies <HERE> in the Terminal field of traps specified in the Traps tab of the Workbench for Eclipse launch configuration. In order to support this feature when debugging across LPAR boundaries in a CICSPlex, the cross-LPAR connections between CICS regions on different LPARs must use IP-based connections using IPCONN and TCPIPSERVICE definitions. Regions running on the same LPAR may use CONNECTION and SESSIONS definitions. Failure to use the correct type of connection for cross-LPAR communication may cause unexpected results during debugging sessions.

Installing Resource Definitions

The procedure you choose for installing Code Debug CICS resource definitions in a dynamic MRO environment will depend on whether you want to use Code Debug to trap transactions in both TORs and AORs, or only in AORs. The remote names of the Code Debug transactions in the TOR used for dynamic transaction routing must match the names in the Code Debug global table. Therefore, if you will be using Code Debug to debug applications in both TORs and AORs, you must have two sets of transaction definitions:

  • One to run locally with transaction IDs matching those in the Code Debug CICS global table.
  • One set to run remotely with remote names matching the Code Debug global table.

In the following example of transactions defined in the TOR, transaction XPED would run locally in the TOR. Transaction XPER would run remotely in an AOR with a local name of XPED.

DEFINE TRANSACTION(XPED) DYNAMIC(NO)
DEFINE TRANSACTION(XPER) REMOTENAME(XPED) DYNAMIC(YES)

If you do not have a need to run Code Debug CICS in both the TOR and AOR then the definition

DEFINE TRANSACTION(XPED) DYNAMIC(YES)

would run the remote transaction XPED in the AOR. For complete examples, see members provided in SMXDSAMP as described as follows .

Task 17.3 Install Code Debug CICS in TORs and AORs

After completing the tasks in “Milestone 4: Configure Code Debug CICS — New Installation” in the Installation and Configuration space, install Code Debug CICS in your site’s TORs and install and start Code Debug in the AORs. The startup global parameter DYNAMIC_TRANSACTION_ROUTING_SUPPORT should be set to NO in each TOR and YES in each AOR.

BMC recommends using PLTPI to start Code Debug CICS in the AORs. Code Debug’s dynamic routing support will not allow you to enter the XPED, XPRT, or XPSP transactions in the TOR to start Code Debug in an AOR. Transaction XPON, which can be separately secured, is provided for this purpose. For more information, see “XPON Transaction” in the section entitled “Intercommunication-Considerations” in the Code Debug CICS Reference space.

Warning

Important

Do not use function shipping to define Code Debug CICS listing files as remote resources. However, the same files can be defined in each region to allow access to each source listing at all times.

Task 17.4 Replace the Default EYU9WRAM

The default EYU9WRAM delivered in the CPSM load library cannot be used with Code Debug’s Dynamic Transaction Routing support. Replace it as follows:

  1. Create your own EYU9WRAM or assemble and link the sample distributed with CPSM in the sample library SEYUSAMP. The command level translate of the program requires a parameter of NOPROLOG NOEPILOG. Make sure it is linked AMODE31 and that EYU9WAPI from the CPSM library SEYULOAD is included. Sample JCL (EYU9WRAM) is provided in an SMXDSAMP member.
  2. Stop and restart CPSM or recycle CICS. If you do not, TOR support will be unable to route transactions, and the only indication will be a lack of routing messages on Code Debug’s Routing Trace Summary screen (P.4).

Task 17.5 Establish TOR Dynamic Transaction Routing Support

The Code Debug CICS CPSM router exit (DBUGWRAM) that provides dynamic transaction routing (DTR) and distributed program link (DPL) support can be started and stopped either by using transactions or with PLTPI and PLTSD entries.

Start DTR support in a TOR by doing one of the following:

  • Add program DBUGWRMI to the PLTPI of the desired CICS regions.
  • Type XPWI on a blank CICS screen and press Enter.

Stop DTR support in a TOR by doing one of the following:

  • Add program DBUGWRMD to the PLTSD of the desired CICS regions.
  • Type XPWD on a blank CICS screen and press Enter.

Task 17.6 Add Resource Definitions to the TOR for Dynamic Transaction Routing Support

If you do not plan to use Code Debug for debugging in the TOR, use SMXDSAMP member CSDXDDYN to add required transaction and program definitions to the TOR. See applicable task “Using RDO to Update Resource Definitions” in the Code Debug CICS Installation and Configuration space. The definitions in member CSDXDDYN must override any previously created Code Debug definitions.

If you do plan to use Code Debug for debugging in the TOR, use SMXDSAMP member CSDXDDYT to add required transaction and program definitions to the TOR. See applicable task "Using RDO to Update Resource Definitions" in the Code Debug CICS Installation and Configuration space.

To support dynamic routing of EXEC CICS START commands and Dynamic Program Link (DPL), install the Code Debug CICS CPSM router exit in all AOR regions. Copy the definitions from your TOR for transaction codes XPWI and XPWD and programs DBUGWRAM, DBUGWRMI, DBUGWRMD, DBUGWRMM, and DBUGWRSI.

DPL requests cannot be routed in a CICSplex environment by program name. An alternative is to create a trap mask by userID and/or transaction code.

 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*

BMC AMI DevX Code Debug for CICS 17.02