Support for CICS Dynamic LIBRARY Capability

Code Debug CICS supports RDO-installed dynamic LIBRARY resources:

• Application program and Code Debug CICS demo program load libraries may be defined in any number of LIBRARY resources, in any sequence, or may be concatenated into DFHRPL.
• The Enterprise Common Components (ECC) load library may be defined in any LIBRARY resource, in any sequence, or may be concatenated into DFHRPL. BMC recommends that the ECC load library be defined in the same place (either LIBRARY resource or DFHRPL) as the Code Debug CICS product load library. The ECC load library may be positioned either before or after the Code Debug CICS product load library.
• The Code Debug CICS product load library may be defined in any LIBRARY resource, or may be concatenated into DFHRPL. If it is defined in a LIBRARY resource, that LIBRARY resource may be sequenced wherever the installer decides.
• Load libraries containing Code Debug CICS product user-replaceable modules (URMs) or user-customized exits must be defined in the same place (either LIBRARY resource or DFHRPL) as the Code Debug CICS product load library, and should be positioned before the Code Debug CICS product load library.
• Code Coverage (if licensed) and Xchange (if licensed) load libraries must be defined in the same place (either LIBRARY resource or DFHRPL) as the Code Debug CICS product load library. If either of those product load libraries are not defined in the same place as the Code Debug CICS product load library, the related product will not initialize properly.

 DASD Space Requirements

The following lists the estimated DASD space needed for Code Debug CICS target libraries.

 Code Debug Service Provider

The Code Debug Service Provider is a required component of Code Debug CICS.

A single Code Debug Service Provider can be used with multiple CICS regions and different CICS releases. Each release of the Code Debug Service Provider is downward compatible. For example, the Code Debug Service Provider included with Code Debug CICS Release 16.05 supports Code Debug CICS Releases 16.05 and 9.4, but does not support Code Debug CICS Release 17.02.

The Code Debug Service Provider supports the following features:

• Exploitation of the trap facility to improve performance of breakpoint handling
• Setting breakpoints in programs residing in protected E(RDSA)
• Code Debug CICS routing in a CICSPlex dynamic-routing environment
• Cross-LPAR communication between Code Debug Service Providers to facilitate CICSPlex dynamic routing
• Debugging in Open Transaction Environment (OTE).

Detailed descriptions of the various messages issued by the Code Debug Service Provider are provided in the section “Code-Debug-Service-Provider-Messages” the Code Debug CICS Messages and Codes space.

 Code Debug Service Provider Security

The default Subsystem Security Exit (DBUGSSX) is delivered with the load module name DBUGSSXX in SMXDAUTH. Therefore, a Subsystem Security Exit will be used only if you take action. If you need to use a Subsystem Security Exit, you can rename DBUGSSXX to DBUGSSX or create your own customized version. An example SMP/E USERMOD to rename the module is in member SSXXUMOD in SMXDSAMP.

If you are using an external security manager, such as RACF, at your site, you may need to customize the Subsystem Security Exit (DBUGSSX) and/or define access rules to allow a CICS address space to access the Code Debug Service Provider Subsystem. Use the sample JCL provided in SMXDSAMP member DBCSSX as displayed in the following figure to assemble and link-edit DBUGSSX.

Sample DBUGSSX Assembly JCL Member (DBCSSX)

During Code Debug Service Provider Subsystem initialization, the optional DBUGSSX exit is fetched from the Code Debug CICS APF authorized library. DBUGSSX is called during address space connect processing to determine whether the requester is authorized to connect to the Code Debug Service Provider Address Space. If DBUGSSX is not available, all CICS address space connections will be granted.

Without any customization, DBUGSSX performs a RACROUTE authorization check for READ access against a model profile data set resource class. The model profile data set is named XPEDITER.SUBSYS.ssid.cccccccc where ssid is the Code Debug Service Provider Subsystem Identifier and cccccccc is the requester address space job or started task name.

Resource Rules

Generic resource rules apply to the DBUGSSX-generated resource names. For the most complete protection, a site can define specific resource rules for each resource name that may be generated, then only grant the desired access to those resources to selected userIDs and groups (address spaces).

Another alternative is for a site to define a resource rule that denies all access by default and is always applied unless some other, more restrictive, rule is applied. The rule would be specified as XPEDITER.SUBSYS.** and defined as having no universal access (UACC=NONE). No userIDs or groups would have READ access to it.

More specific resource rules could then be defined, allowing access on an individual basis. In one possible scenario, a site that has CICS production processing regions with job names of PRODxxxx and test processing regions with job names of TESTxxxx might want to protect its production regions from use of the Code Debug Service Provider Subsystem, while retaining the capability of using it in their test regions. To accomplish this, first the site would define XPEDITER.SUBSYS.** with UACC=NONE and not grant READ access to any userIDs or groups. Then XPEDITER.SUBSYS.*.TEST* would be defined with UACC=NONE, and only selected userIDs and groups (address spaces) would be given the necessary READ access.

With these rules, site security retains complete control over which address spaces are able to use the Code Debug Service Provider Subsystem.

Minimizing CPU Consumption When Using Code Coverage

There are certain CICS, Code Debug CICS, and Code Coverageoptions you can set that may reduce CPU consumption when testing withCode Coverage.

CICS SIT Parameters Affecting CPU Consumption

You can alter the system initialization table (SIT) parameters STGPROT and SYSTR as follows either by modifying the SIT or by using SIT overrides.

STGPROT

When this option is set to YES and your application programs are defined as EXECKEY(USER), substantial CPU time will be spent changing execution key. Setting STGPROT to NO will save CPU.

SYSTR

When this option is set to ON, CICS will trace CICS API calls and internal CICS functions. Setting SYSTR to OFF will save CPU.

Code Debug CICS Global Parameter Affecting CPU Consumption

The UPDATE_INTERNAL_BRANCH_TRACE_TABLE global parameter can be set as described in Methods-of-Specifying-and-Updating-Parameters. This region-wide option can also be changed from any Code Debug CICS debugging session with the SET BTRACE primary command.

UPDATE_INTERNAL_BRANCH_TRACE_TABLE

When this option is set to YES or FULL, Code Debug CICS updates an internal branch trace table to help diagnose any Code Debug CICS issues. Unless Code Debug CICS Customer Solutions has requested that you run with this option set to YES or FULL, it should be set to NO to save CPU.

Code Coverage Global Parameter Affecting CPU Consumption

The setting of the INCREMENT_VERB_COUNTS global parameter can also affect CPU consumption while testing with Code Debug CICS. For more information on setting this option, see the Code Debug CICS Installation and Configuration space.

INCREMENT_VERB_COUNTS

When this option is set to YES, Code Debug CICS will monitor application programs and increment verb counts as each instruction is executed. This is a very CPU-intensive process. The default is YES.

Set this option to NO when it is not necessary to count each time a verb is executed. When INCREMENT_VERB_COUNTS=NO, Code Debug CICS will count each verb only the first time it is executed. To maximize the potential performance benefit of INCREMENT_VERB_COUNTS=NO, rules for Storage Protection and Program Trace are ignored when INCREMENT_VERB_COUNTS=NO and a Code Coverage test is active.

When INCREMENT_VERB_COUNTS is set to NO:

• Only one Code Coverage test at a time may be active in the CICS region.
• Each application program you execute is marked as RESIDENT until every verb within it has been executed or the Code Coverage test has been halted. If you encounter a Short on Storage (SOS) situation using INCREMENT_VERB_COUNTS=NO, reduce the number of programs referenced by your Code Coverage test.
• CPU consumption may actually increase, depending on the structure of your Code Coverage test. When the same code is executed multiple times, INCREMENT_VERB_COUNTS=NO will reduce CPU consumption by a factor related to how many times the code is executed. However, when different code is executed by each transaction and there is very little reuse of the same code, INCREMENT_VERB_COUNTS=NO can cause a noticeable increase in CPU consumption.

Workbench for Eclipse in a CPSM CICSPlex Environment

The following capabilities of BMC’s Workbench for Eclipse, when used with a CPSM CICSPlex environment, effectively support Dynamic Transaction Routing across LPARs:

• DBUGSOCK and XDPIMIRS use Channel/Containers to communicate. This modernizes the communication and allows cross-LPAR debugging sessions to be established. DBUGSOCK is the Code Debug CICS Socket Handler for the Workbench for Eclipse debugger, and XDPIMIRS is the Code Debug CICS Debugging Interface for the Workbench for Eclipse debugger.
• The CPSM Dynamic Transaction Routing exit DBUGWRAM supports cross-LPAR debugging sessions. If a workstation starts a Workbench for Eclipse debugging session by connecting to a TOR—and transaction XSOC is defined as dynamically routed—the debugging session (XDPIMIRS) will be started in the LPAR to which XSOC is to be routed. The XSOC transaction, however, will be routed to an existing Code Debug CICS-enabled region within the same LPAR as the TOR. This is due to a restriction of CICS Sockets for MVS that requires the socket to run in the same LPAR as the listener. This also means that for each TOR region, at least one Code Debug CICS AOR region must be defined in the same LPAR as the TOR.
• The trap routing logic within DBUGWRAM will route the application logic to the correct region where the Code Debug CICS trap is set when <HERE> is specified in the terminal field of the trap.
• The Code Debug CICS start-of-task exit uses the EXEC CICS INQUIRE ASSOCIATION call to obtain the client IP address associated with the task. This allows the terminal emulator IP address to be identified when a trap/breakpoint is taken. This most commonly occurs in cross-LPAR environments. However, the client IP address will only be filled in if the CICSPlex regions’ cross-LPAR connections utilize IPIC connections. If you use SESSION/CONNECTION definitions for cross-LPAR connections, the client IP address will not be available. BMC suggests you upgrade any cross-LPAR connections to use IPIC connections.

Restrictions

The following restrictions apply when using Workbench for Eclipse in a CPSM CICSPlex Environment:

• If the affinity of the transaction being routed prevents that transaction from running in the region where DBUGWRAM has determined it should be routed, that transaction will not be eligible for debugging. If you encounter this situation, you may need to end your Workbench for Eclipse debugging session and directly connect to an AOR where the transaction can be executed.
• If you have cross-LPAR regions that communicate using non-IPIC connections, consider upgrading your connections. Being able to correctly identify the IP Address of the transaction being executed is a key factor in determining when a transaction has been initiated by a terminal emulator running on the same workstation as your debugging session.

Examples of CPSM CICSPLEX Configurations Now Supported

The following examples utilize the simple CICSPlex configuration shown in following figure. In this configuration, the Service Providers XP40, XP01, and XP06 are all TCP/IP connected utilizing Code Debug CICS release 17.02.03 Service Providers. The AOR regions H40AC123, H40AC246, H01AC066, H01AC132, H06AC024, and H06AC093 all have Code Debug CICS release 17.02.03 installed and active. The TOR regions H40AC063, H01AC073, and H06AC053 all have Code Debug CICS release 17.02.03 exit DBUGWRAM installed and active. All regions, both TOR and AOR, are connected to their assigned Service Providers.

It is assumed that the user has set a trap in their debug launch configuration that has <HERE> in the Terminal field and all other fields set to asterisks. When the trap is set, the IP address of the workstation is used for the terminal field in the trap. This means that when the routing exit DBUGWRAM is performing a trap search to determine where to route a transaction, it will compare the IP address of the terminal entering the transaction against the IP address in the trap. Since the terminal emulator IP address matches that of the workstation, DBUGWRAM will route the transaction to the region where the trap was set.

Simple CICSPlex Configuration

Example 1. Workbench for Eclipse Connecting Directly to an AOR

In the following example, a Workbench for Eclipse user connects directly to AOR H06AC024. Because the connection is to an AOR, the routing exit DBUGWRAM is not involved. This means that XSOC (DBUGSOCK) will run in the AOR and do a local LINK to the Debugging Interface XDPIMIRS. Any breakpoints the user has requested will be set in H06AC024.

Workbench for Eclispe Connecting Directly to an AOR

If the user then logs into any TOR in the CICSPlex from their terminal emulator, the enhanced trap logic in routing exit DBUGWRAM will now route any transactions from that terminal emulator to AOR H06AC024 for execution. The user can now debug the programs in which they have set breakpoints using Workbench for Eclipse at their workstation.

Example 2. Workbench for Eclipse Connecting to a TOR

In this example, a Workbench for Eclipse user connects to TOR H01AC073. Because the connection is to a TOR, the routing exit DBUGWRAM is involved. When DBUGWRAM is invoked, transaction XSOC (used to initiate the debugging session) has already been slated for routing to H40AC246 on LPAR CW40 by the Work Load Manager. DBUGWRAM writes an entry to an internal table indicating that the Debugging Interface XDPIMIRS should run in region H40AC246 and then looks for a region with Code Debug CICS active on the same LPAR (CW01) on which the TOR runs. DBUGWRAM finds that region H01AC132 is available and changes the routing of the XSOC transaction to run in H01AC132 instead of H40AC246. This is necessary since XSOC invokes DBUGSOCK, the Sockets Listener Interface, which must run on the LPAR on which it was invoked. XSOC then starts on H01AC132 and links to XDPIMIRS on H40AC246 to start the debugging session. XDPIMIRS and DBUGSOCK communicate via Channel/Containers, and the actual socket connection is made between the workstation running Workbench for Eclipse and DBUGSOCK on H01AC132. Any breakpoints the user has requested will be set in H40AC246.

Workbench for Eclipse Connecting to a TOR

When the user logs on to any TOR in the CICSPlex from their terminal emulator, the enhanced trap logic in routing exit DBUGWRAM will now route any transactions from that terminal emulator to AOR H40AC246 to execute. The user can now debug the programs in which they have set breakpoints using Workbench for Eclipse at their workstation.