Adding support for debugging under CICS

To debug applications that run in CICS®, z/OS® Debugger requires the following:

• Language Environment®. Refer to the Language Environment installation and customization information for more information.
• Do the steps described in this chapter.

To add z/OS Debugger support for CICS applications:

1. Verify that the current z/OS Debugger resources are defined in the CICS CSD and installed in the CICS region. The CICS definitions are in the EQACCSD and EQACDCT members of the hlq.SEQASAMP data set.
   1. If your site policy is to define the Transient Data queues by using DCT macro definitions, add the definitions in the EQACDCT member to your DCT and reassemble it.

      If your site uses COBOL or PL/I separate debug files, follow the instructions in EQACDCT to define the appropriate queues to CICS.

   2. Add the z/OS Debugger definitions to the CICS CSD. The following two members are provided in the hlq.SEQASAMP data set:
      • EQACCSD, which contains the resource definitions for the group EQA.
      • EQAWCCSD, which contains JCL to apply the definitions which are in EQACCSD.
      Review the instructions in both members and run the batch job to add the definitions to your CICS CSD.
2. Update the JCL that starts CICS:
   1. Update the DFHRPL concatenation in the CICS region startup JCL to include the following libraries:

      Table 1. Libraries to be included in DFHRPL

      Library	Description
      hlq.SEQAMOD	z/OS Debugger library In the DFHRPL concatenation, hlq.SEQAMOD must be placed before any other library that also contains CEEEVDBG for z/OS Debugger to get control of a debug session. Defining the hlq.SEQAMOD data set as a CICS LIBRARY resource is not supported. It must be included in the DFHRPL concatenation.
      SCEECICS	z/OS Language Environment runtime library
      SCEERUN	z/OS Language Environment runtime library
      SCEERUN2	z/OS Language Environment runtime library Specify this library if it is required by your application.
      MIGLIB SIEAMIGE	z/OS system libraries These libraries are needed to debug routines compiled with Enterprise COBOL V5 and V6.1 TEST and Enterprise COBOL V6.2 (and later) TEST or TEST(NOSEPARATE).

   2. Remove any data sets from the concatenation that refer to old releases of z/OS Debugger.
   3. Include EQA00DYN and EQA00HFS from the debugger's hlq.SEQAMOD data set in the STEPLIB concatenation by either of the following ways:
      • Use the Authorized Program Facility (APF) to authorize¹ the hlq.SEQAMOD data set and add the data set to the STEPLIB concatenation.
      • Copy² the EQA00DYN and EQA00HFS modules from the hlq.SEQAMOD data set to a library that is already in the STEPLIB concatenation.
      • Place hlq.SEQAMOD in the system link list and use the Authorized Program Facility (APF) to authorize it¹. For more information, see Setting up the link list data set (SEQAMOD).
   4. Ensure that the JCL does not include DD statements for CINSPIN, CINSPLS, CINSPOT, IBMDBGIN, or IGZDBGIN.
   5. See Storing DTCN debug profiles in a VSAM file to determine if you want to store DTCN debugging profiles in a VSAM data set. If you do, follow the instructions in that topic to add the EQADPFMB DD statement that refers to the VSAM data set.
3. For any terminal that z/OS Debugger uses to display a debugging session, do the following tasks:
   • Verify that the CICS TYPETERM definition specifies a minimum value of 4096 for the RECEIVESIZE attribute and sets the BUILDCHAIN attribute to YES.
   • Enable either color or highlighting. For best usability, enable both and the ability to query the screen size. To enable these three functions, verify that the CICS TYPETERM definition specifies EXTENDEDDS. For more information, refer to the CICS Transaction Server for z/OS Resource Definition Guide.
   • Under CICS, z/OS Debugger can use a screen as large as 10922 characters (for example, 68x160 can be used, but not 69x160), and provides automatic switching from the application's screen size to the physical screen size. Larger screens can enhance user productivity. CICS selects the TYPETERM to use from the BIND information given to it from VTAM®. Ask your systems programmer to ensure that VTAM passes the screen sizes through to CICS.
4. Verify that users can run the CDT# transaction without receiving any errors.

   If the CDT# transaction runs successfully, no messages are displayed. You might see X-SYSTEM after you press Enter. This disappears when the transaction finishes and the keyboard unlocks.

5. If you are running your CICS programs in a multi-region CICS environment:
   1. Define the DTCN transaction name the same across all local and remote systems. If the DTCN transaction name is changed, or if a DTCN transaction is duplicated and given a different name, change the name on all systems.
   2. If a debugging session might run in a region that is different from the one where DTCN or CADP was used to save the debugging profile, use the PLTPI program EQA0CPLT with the CICS start up parameter INITPARM=(EQA0CPLT='NWP').
   3. If you are using DTCN, ensure that the region shares the debug profile repository. See Sharing DTCN debug profile repository among CICS systems for more information about defining the region that owns the debug profile repository. The most common multi-region debugging scenario is where the debug profile repository is shared and DTCN runs in the TOR while the application to be debugged is transaction routed to an AOR.

      One of two methods must be used in this case to start the debugger's new program support in the AOR. Either use EQA0CPLT to enable this support when the region starts (see step 9 for information about EQA0CPLT), or use the z/OS Debugger DTCP transaction to start or stop this support as needed. In the AOR, enter DTCPO on a clear CICS screen to activate this support and enter DTCPF to deactivate it. You can activate and deactivate this support multiple times.

   4. If you are using CADP for debugging profiles, set the startup parameter DEBUGTOOL=YES for any region where a z/OS Debugger session might start. This parameter activates the z/OS Debugger new program support.
6. If users need to debug Enterprise PL/I for z/OS, Version 3 Release 4 (or later), applications under CICS:
   1. Install the following corequisite:
      • If you are running z/OS Version 1 Release 6, you need to apply the PTF for Language Environment APAR PK03093.
      • If you are compiling with Enterprise PL/I for z/OS, Version 3 Release 4, apply the PTF for APAR PK03264.
      Users can begin a debug session by using DTCN or CADP at either of the following points:
      • The entry to programs invoked by EXEC CICS LINK or XCTL.
      • The entry to any program, even if it is a nested program within a composite load module, invoked as a static or dynamic CALL.
   2. To enable users to start debug sessions with CADP, use PLTPI program EQA0CPLT with the CICS start up parameter INITPARM=(EQA0CPLT='NWP'). See step 9 for information about EQA0CPLT.
7. If you are planning to debug command-level assembler application programs that do not run under or use Language Environment services, activate the CICS non-Language Environment exits as described in Activating CICS non-Language Environment exits.
8. If your CICS region is started with the SEC parameter set to YES and the XCMD parameter is set to YES to activate command security, review the access settings for the following resources:

   EXITPROGRAM

   Do one of the following options:

   • Verify that z/OS Debugger users have UPDATE authority to the EXITPROGRAM resource so that they can run EXEC CICS ENABLE PROGRAM EXIT, DISABLE PROGRAM EXIT, and EXTRACT EXIT.
   • Activate the debugger's single-terminal mode screen stacking user exits during CICS start up by doing the following:
     1. Verify that the user ID that runs the CICS region has UPDATE access to the EXITPROGRAM resource.
     2. Add the program EQA0CPLT to your Program List Table (PLTPI).
     3. Add INITPARM=(EQA0CPLT='STK') to your CICS startup parameters.
     See step 9 for instructions on using EQA0CPLT.

   TDQUEUE

   Verify that all users have UPDATE authority to the TDQUEUE resource, so that they can run EXEC CICS INQUIRE and EXEC CICS SET TDQUEUE.

   PROGRAM

   Verify that all users have READ authority to the PROGRAM resource, so that they can run EXEC CICS INQUIRE PROGRAM.

   For more information about the CICS security features, see CICS RACF® Security Guide.

9. (Optional) Set up the CICS PLTPI program called EQA0CPLT:
   1. Add the program EQA0CPLT to your Program List Table (PLTPI). EQA0CPLT initializes parts of z/OS Debugger during CICS startup as indicated by a CICS INITPARM system initialization parameter. Run EQA0CPLT as a Stage 2 or Stage 3 PLTPI program. IBM® recommends that you place EQA0CPLT after other PLT programs. The following sample PLT includes EQA0CPLT:

         TITLE 'DFHPLTXX - IBM
      z/OS Debugger CICS Sample PLT'
         DFHPLT TYPE=INITIAL,SUFFIX=XX
         *
         DFHPLT TYPE=ENTRY,PROGRAM=DFHDELIM
         DFHPLT TYPE=ENTRY,PROGRAM=EQA0CPLT
         *
         DFHPLT TYPE=FINAL  END DFHPLTBA

   2. Add the INITPARM keyword to the CICS startup parameters. Multiple parameters can be passed to EQA0CPLT in the same INITPARM. The following common parameters can be used:

      NLE

      Non-Language Environment support. See Activating CICS non-Language Environment exits.

      STK

      Screen stack exits. This parameter is required if you are using command security.

      NWP

      New program support. This parameter is required if you are using multi-regions or Enterprise PL/I Version 3 Release 4 (or later) with CADP.

      STG

      This parameter enables the protection of storage that was GETMAINed in the current task by a program that is not the active program. This protection is only provided when the user is using the remote debugger.

      DNT

      This parameter disables the generation of z/OS Debugger trace entries. By default, these trace entries are generated for IBM Software Support to diagnose problems with z/OS Debugger. You can specify this parameter to disable generation if z/OS Debugger trace entries are not needed.

      For example, to activate the non-Language Environment support, screen stack exits, and new program support (multi-region and Enterprise PL/I Version 3 Release 4 with CADP) in a single INITPARM, add the following to your CICS startup parameters:

      INITPARM=(EQA0CPLT='NLE,STK,NWP')

      Any combination of these four can be coded on the same INITPARM.

10. If the users use COBOL or PL/I separate debug files, verify that the users specify the following attributes for the PDS or PDSE that contains the separate debug files:
    • RECFM=FB
    • LRECL=1024
    • BLKSIZE set so that the system determines the optimal size
    Important: Users must allocate files with the correct attributes to optimize the performance of z/OS Debugger.
11. (Optional) Increase the DSALIM and EDSALIM sizes in your CICS region so that z/OS Debugger functions properly with multiple concurrent users. The amount of increase is based on the current workload in the CICS region.
    Recommendation: Increase the sizes of DSALIM and EDSALIM in increments of 5% or 10%. Monitor the storage in the region as z/OS Debugger users are debugging for the highest amount of storage that is used at any one point.
12. To enable users to start debug sessions for Enterprise COBOL or Enterprise PL/I application with DTCN, use one of the following methods:
    • Use PLTPI program EQA0CPLT with the CICS start up parameter INITPARM=(EQA0CPLT='NWP'). For more information about EQA0PLT, see Step 9.
    • Save a DTCN profile.
    • Run DTCPO transaction after the region starts up.

See the IBM z/OS Debugger User's Guide for information about how to debug CICS programs.