Xpediter Support for COPE DCCTL

This section describes the steps necessary to set up the optional Xpediter (Xpediter/TSO and Xpediter/IMS) support available in COPE. Xpediter is an interactive debugger. It allows developers to set break points and examine variables for a program running in an MPP or BMP test region. Refer to the Xpediter/TSO documentation for installation and configuration as well as usage information.

Task 9.1 Update ZDEFAULT Variables

Set the following parameters in the ZDEFAULT member of the PROCS library. Refer to the BMC-COPE-Installation-Guide for an explanation of ZDEFAULT parameters.

1. Set XCOPEEXP to YES.
2. Set XEXPUSER to the maximum number of simultaneous Xpediter users for a COPE Psys. Make this a reasonable value (extra transaction codes are generated later dependent on this value).
3. Set XCOPEACD to the dataset name of the dynamic ACB library (DOPT library). Make sure that this library is in your Control Region, and DLI region, ACBLIBA and ACBLIBB concatenations. The DSN should end in ACBLIBD (recommended). It must have the same blksize as other ACBLIBs.
4. Set XCOPEPSD to the dataset name of the dynamic PSB library (DOPT library). The DSN should end in PSBLIBD (recommended). It must have the same blksize as the non-DOPT PSBLIB.
5. Set XPLOAD to the Xpediter load library dataset name.
6. Set XPMENU to the Xpediter panels library dataset name.
7. Set XPSKEL to the Xpediter skeleton library dataset name.
8. IX_XPSKEL  8. Set XPMSG to the Xpediter messages library dataset name.

Task 9.2 Perform IMSGEN

1. Perform option 1.7 to allow definition of the Stage 1 statements that define the following excluded transactions:

   • COPEXPT1,
   • XPEDTX1
   • XPED0000 through XPED0200
   • excluded database XPIMSDB.

   Use the CTLCD member XPEDDEF to validate the Xpediter specific definition requirements for the excluded Stage 1 statements.

2. If you have RACF or ACF2 (etc.) IMS security exits, or rules, make sure that they allow COPEXPT1 (and all other COPE-prefixed transactions) to issue commands.
3. If you have RACF or ACF2 IMS security exits or rules, also make sure that your TSO users will be able to run all Cnnnnnnn transaction codes from their TSO regions.
4. Run option 4.1 (Modblks). This generates additional C-number DOPT PSBs and transaction codes, which are switched-to by COPE, for running the test transactions in the TSO regions.

Task 9.3 Generate Dummy ACBs

Run option 4.5(ACB).FIX for the following situations:

• This option generates dummy ACBs for the Xpediter transaction codes that are necessary so that these transaction codes will come up initialized to IMS. When the user runs an Xpediter test, their ACB will be copied over one of these (in the DOPT ACBLIB).
• After doing the PSB=ALL gen. for a new COPE Psys, or any time that an existing Psys has many transaction codes added to it. The latter case is necessary because in that situation additional Xpediter transactions might need to be available. The number of these is dependent on the total number of transactions.
• If a COPE release change requires an ACBGEN, for example, changing from release 4.4.14 to 4.4.15, the members in the Dynamic ACBLIB (ZDEFAULT parameter XACBLIBD) must be deleted, and the 4.5(ACB).FIX option run. This action is required because the FIX option will not replace any ACBLIB member that already exists.

Task 9.4 Customize Xpediter Exits

Customize Xpediter exits using the Xpediter/TSO PARMLIB.

Xpediter/TSO uses parameter libraries together with the Compuware Mainframe Services Controller (CMSC) for product configuration. The CMSC was installed as part of the Compuware Enterprise Common Components (ECC) installation.

Xpediter Execution Exit Routines keywords are used to specify special procedures that must be executed for every test session. The exits apply to Debug Sessions (Execution Test Sessions). They provide special handling before or after a debug session.

Task 9.4.1 First-time Xpediter Release 17.02 Installation Instructions

1. Create an initial PARMLIB member.

   	If you already have Xpediter Release 17.02 installed, skip this step and continue with Step 5.

2. Sample member XTSO00 is provided in the Xpediter/TSO installation sample library, SLXTSAMP.
3. Begin with an empty PARMLIB member named XTSOxx. Obtain the xx suffix value from your Compuware ECC Administrator.
4. Copy in the values from member XTSOALL in the SLXTSAMP dataset. Follow the instructions in the member to make required changes.

5. Modify the XTSOxx PARMLIB member with the Xpediter/TSO Execution Exit Routines keywords and their associated values for COPE provided in member XPEDPARM in the COPE CTLCD dataset as shown in the following figure.
   COPE XPEDPARM Values

   * USE ONE SET OF THE FOLLOWING PARAMETERS FOR COPE(CMSC VERSION 1 OR 2)
   *
   * THE FOLLOWING KEYWORD PARAMETERS AND THEIR ASSOCIATED
   * VALUES FOR COPE ARE VALID ONLY FOR CMSC VERSION 1
   *
   BEFORE_STANDARD_AND_DIALOG_TEST_SESSION_EXIT='PGM(COPEXPP1) PARM(01)'
   AFTER_STANDARD_AND_DIALOG_TEST_SESSION_EXIT='PGM(COPEXPP1) PARM(02)'
   BEFORE_IMS_TEST_SESSION_EXIT='PGM(COPEXPP1) PARM(03)'
   AFTER_IMS_TEST_SESSION_EXIT='PGM(COPEXPP1) PARM(04)'
   BEFORE_BTS_TEST_SESSION_EXIT='PGM(COPEXPP1) PARM(05)'
   AFTER_BTS_TEST_SESSION_EXIT='PGM(COPEXPP1) PARM(06)'
   BEFORE_MPP_TEST_SESSION_EXIT='PGM(COPEXPP1) PARM(07)'
   AFTER_MPP_TEST_SESSION_EXIT='PGM(COPEXPP1) PARM(08)'
   BEFORE_BMP/IFP_TEST_SESSION_EXIT='PGM(COPEXPP1) PARM(09)'
   AFTER_BMP/IFP_TEST_SESSION_EXIT='PGM(COPEXPP1) PARM(10)'
   BEFORE_HOGAN_TEST_SESSION_EXIT='PGM(COPEXPP1) PARM(11)'
   AFTER_HOGAN_TEST_SESSION_EXIT='PGM(COPEXPP1) PARM(12)'
   *
   * THE FOLLOWING KEYWORD PARAMETERS AND THEIR ASSOCIATED
   * VALUES FOR COPE ARE VALID ONLY FOR CMSC VERSION 2
   *
   BEFORE_STD_OR_DLG_TEST_SESSION_EXIT='PGM(COPEXPP1) PARM(01)'
   AFTER_STD_OR_DLG_TEST_SESSION_EXIT='PGM(COPEXPP1) PARM(02)'
   BEFORE_IMS_TEST_SESSION_EXIT='PGM(COPEXPP1) PARM(03)'
   AFTER_IMS_TEST_SESSION_EXIT='PGM(COPEXPP1) PARM(04)'
   BEFORE_BTS_TEST_SESSION_EXIT='PGM(COPEXPP1) PARM(05)'
   AFTER_BTS_TEST_SESSION_EXIT='PGM(COPEXPP1) PARM(06)'
   BEFORE_MPP_TEST_SESSION_EXIT='PGM(COPEXPP1) PARM(07)'
   AFTER_MPP_TEST_SESSION_EXIT='PGM(COPEXPP1) PARM(08)'
   BEFORE_BMP_IFP_TEST_SESSION_EXIT='PGM(COPEXPP1) PARM(09)'
   AFTER_BMP_IFP_TEST_SESSION_EXIT='PGM(COPEXPP1) PARM(10)'
   BEFORE_HOGAN_TEST_SESSION_EXIT='PGM(COPEXPP1) PARM(11)'
   AFTER_HOGAN_TEST_SESSION_EXIT='PGM(COPEXPP1) PARM(12)'

6. Execute the CLIST XPLIBDEF with the INSTALL option (XPLIBDEF INSTALL). The screen shown in following figure is displayed. The displayed screen, when completed, will commit the changes made to the CMSC PARMLIB member into the Xpediter/TSO Table Library.
   Installation Defaults Screen

   

7. Enter the name of your new Xpediter/TSO ISPF table SLXTTABL dataset in the Output field.
8. If you’re using a PARMLIB member other than the CMSC default for Xpediter, enter the suffix of your PARMLIB member (XTSOxx) to be committed.
9. Specify an ACTION of COMMIT.
10. To validate the dataset names specified in the XTSOxx PARMLIB member, enter YES to that question.

11.  Press Enter.

    Warning

    Note

    If you received an error message when you pressed Enter, the CMSC has experienced an error.

12. If you received no error message, a validation report will be displayed. Follow the instructions in the report.

13. Use SDSF, IOF, EJES, or whatever JES viewer is used by your site to check the CMSC address space’s FDBDLOG (as shown in the following figure) to determine whether anything went wrong.
    CMSC Address Space FDBDLOG

    

14. Return to the validation report and scroll to the bottom (as shown in the following figure) to determine whether there were any errors. If there were no errors, NONE is indicated. If there were errors, fix them and start over.
    Validation Report with No Errors 

    

15. Press End, then press Enter (or press PF3). The Save Installation Defaults screen is shown in the following figure.
    Save Installation Defaults Screen 

    

16. Press Enter to update the Installation Defaults. The following message should be displayed saying that your Installation Defaults have been saved:
    'Installation defaults have been saved into 'XT.XT170.SLXTTABL' and the installation report was copied to your ISPF List dataset TSOID01.ISP56596.SPF1.LIST'

Task 9.4.2 Upgrade Xpediter Installation Instructions

Follow this procedure when upgrading Xpediter to a new release (17.02):

1. Xpediter provides a utility is to extract ISPF Installation Parameter specifications from a prior release’s Xpediter/TSO ISPF table SLXTTABL.
2. SLXTINST(JCLCRPRM) contains sample JCL and instructions for executing the utility.
3. Use the XTUPDATE macro to configure SLXTINST(JCLCRPRM).
4. Follow the instructions in the JCL to complete customization.
5. Submit the JCL. The JCLCRPRM job should end with return code 0.
6. Copy the PARMOUT output from the JCLCRPRM job to CMSC PARMLIB member XTSOxx.
7. The XTSOxx member includes instructions to make all required changes.

8. Execute the CLIST XPLIBDEF with the INSTALL option (XPLIBDEF INSTALL). The screen shown in following figure is displayed.
   The displayed screen, when completed, will commit the changes made to the CMSC PARMLIB member into the Xpediter/TSO Table Library.
   Installation Defaults Screen

   

9. Enter the name of your new Xpediter/TSO ISPF table SLXTTABL dataset in the Output field.
10. Enter the name of your previous version’s Xpediter/TSO ISPF table SLXTTABL dataset in the Input field.
11.  If you’re using a PARMLIB member other than the CMSC default for Xpediter, enter the suffix of your PARMLIB member (XTSOxx) to be committed.
12. Specify an ACTION of COMMIT.
13. To validate the dataset names specified in the XTSOxx PARMLIB member, enter YES to that question.

14.  Press Enter. The Roll Forward screen as shown in following figure is displayed.
    ROLL FORWARD INSTALLATION DEFAULTS Screen 

    

15. Type Y in the Continue and roll forward? field and press Enter.
    
    

    Warning

    Note

    If you received an error message when you pressed Enter, the CMSC has experienced an error.

16.  If you received no error message, a validation report will be displayed. Follow the instructions in the report.

17. Use SDSF, IOF, EJES, or whatever JES viewer is used by your site to check the CMSC address space’s FDBDLOG (as shown in the following figure) to determine whether anything went wrong.
    CMSC Address Space FDBDLOG

    

18. Return to the validation report and scroll to the bottom as shown in the following figure to determine whether there were any errors. If there were no errors, NONE is indicated. If there were errors, fix them and start over.
    Validation Report with No Errors

    

19. Press End, then press Enter (or press PF3). The Save Installation Defaults screen displays as shown in the following figure.
    Save Installation Defaults Screen

    

20. Press Enter to update the Installation Defaults. The following message should be displayed saying that your Installation Defaults have been saved:
    'Installation defaults have been saved into 'XT.XT170.SLXTTABL' and the installation report was copied to your ISPF List dataset TSOID01.ISP56596.SPF1.LIST'

Task 9.4.3 Xpediter Release 16.05 and Earlier

1. Access the Xpediter Primary Menu.
2. Enter DEF to access the Exit Routine definition panels.
3. Enter 9 on the DEF COMMAND OPTIONS panel.
4. Enter 2 on the USER EXIT ROUTINES panel.
5. Fill in the EXECUTION EXIT ROUTINES screen (as shown in the following figure) during Installation of Xpediter as follows if the TSO and IMS Xpediter features are installed.

Xpediter Exit definition 

Fill in the EXECUTION EXIT ROUTINES screen (as shown in the following figure) during Installation of Xpediter as follows if only the TSO (BTS) feature is installed.

Xpediter BTS Exit Specification 

If the TSO feature only is installed, the IMS RESLIB name used by COPE must be included in the Xpediter JOBLIB definitions.

You can piggyback your own exit, panel or command onto the COPE exit, by putting its PGM, PANEL or CMD keyword, and its PARM keyword (or any other keywords), in the COPEXPP1 PARM, past the digit (01 to 12) and a blank, as in this example:

===> PGM(COPEXPP1) PARM(01 PGM(yourexit) PARM(yourparm))

If this Xpediter system can be invoked outside COPE, either copy COPEXPP1 from COPE.LOAD to Xpediter LOAD, or copy and rename IEFBR14 to Xpediter LOAD, as member COPEXPP1. This COPY is necessary because the COPE.LOAD library is not normally installed in your TSO or ISPF startup allocations.

Task 9.5 XPX Clist

Set up the invocation of Xpediter for your users, by editing COPE CLIST member XPX, modifying it to name your Xpediter CLIST, tables, xoptions and xmessages datasets. This CLIST is invoked from COPE option 6.4. XPX is the same as the Compuware-delivered CLIST except that we removed ISPLLIB, ISPPLIB, ISPSLIB and ISPMLIB allocations (these are done at COPE initialization, using the ZDEFAULT variables). The reason for this is that if these allocations were done in the CLIST, some maintenance levels of LIBDEF give bounce out and ISPF subtask abend behavior.

Task 9.6 Verify Install

1. Go into IMS:

2. Issue /DIS DB XPIMSDB command.
   Command output:

   DATABASE TYPE TOTAL UNUSED TOTAL UNUSED ACC CONDITIONS
   XPIMSDB DL/I                                EX ALLOCS
   *19220/130152*

   If the database is invalid, stopped, or condition is NOTOPEN NOTINIT, correct the Xpediter install of this DBD, its exit, or database dataset.

3. Issue /DIS PROG ADSIM001 command.

   Command output:

   PROGRAM    TRAN       TYPE
   ADSIM001   XPEDTX1 BMP
   *19220/131754*

   If the program is invalid, stopped, or NOTINIT, correct the Xpediter install of this PSB.

4. Go into TSO:

5. Access COPE ISPF. The COPE Primary Menu displays as shown in the following figure.

   COPE Primary Menu

   

6. Select Option 6 – View Trace (XPEDITER TSO) to display the COPE - IMS Online Menu as shown in the following figure.

   COPE - IMS Online Menu

   

7.  In the Lsys field, specify your COPE logical system (Lsys) name.
8.  In the Terminal field, specify your terminal name (sign-on ID or LTERM name).
9. Select COPE Option 4 – Xpediter - COPE.

10. Press Enter to access Xpediter (as shown in the following figure).
    Xpediter/TSO Primary Menu

    

11. From the Xpediter/TSO Primary Menu. select Option 2 TSO – Debug programs interactively under TSO.
    Xpediter/TSO Environments Menu

    

12.  Select option 8 (MPPS) and press Enter.

13.  Press Enter to access the Xpediter Debug Menu (as shown in the following figure) to set up testing conditions before beginning program execution.
    Xpediter/TSO Debug Menu

    

14.  Specify SE on the command line.
15.  Specify the ID of the IMS user issuing the IMS transaction you want to debug.

16.  Press Enter to access the Xpediter Setup Menu (as shown in the following figure).
    Xpediter/TSO SETUP Menu

    

17. Select Option 0 – Execution environments menu.

18. Press Enter to access the Xpediter Environments Menu (as shown in the following figure).
    Xpediter/TSO Environments Menu 

    

19.  Specify the appropriate environment, 8 (MPP) or 9 (BMP/IFP). The highlighted environment is the one currently selected.

20. Press Enter. Xpediter returns to the Setup Menu (as shown in the following figure).
    Xpediter/TSO SETUP Menu

    

21. Select Option 1 – Application load module libraries.

22. 2Press Enter to access the Xpediter Load Module Libraries screen (as shown in the following figure).
    Xpediter/TSO Load Module Libraries Screen 

    

23.  Under User Libraries, type XCOPEPGM (STUBX Library) as one of your load libraries.

24.  Press Enter. Xpediter returns to the Setup Menu (as shown in the following figure).
    Xpediter/TSO SETUP Menu

    

25.  Select Option 8 IMS – PSB and DBD libraries.

26. Press Enter to access the Xpediter PSB/DBD Libraries screen (as shown in the following figure).
    Xpediter/TSO PSB/DBD Libraries Screen 

    

27. Specify XCOPEPSD (DOPT PSBLIB) and XCOPEDBD (DBDLIB) as a PSBLIB/DBDLIB concatenation. This is used for BMP tests that use GSAM.

28. Press Enter. Xpediter returns to the Setup Menu (as shown in the following figure).
    Xpediter/TSO SETUP Menu 

    

29.  Select Option 11 PARMS – IMS region ID and parameter strings.

30. Press Enter to access the Xpediter IMSID and PARM Lists screen (as shown in the following figure).
    Xpediter/TSO IMSID and PARM Lists Screen

    

31. Specify the correct IMSID (subsystem identifier) in the IMS Region Id field.
32. Press Enter. Xpediter returns to the Setup Menu.

33. From the Setup Menu, press PF3 to display the MPP Program Test Screen (as shown in the following figure).
    Xpediter/TSO MPP Program Test Screen 

    

34. Specify the transaction to be debugged in the TRANCODE field.

35. When entries for the screen are complete and you press Enter, the screen clears. If the intercepts are set, the following messages appear on the screen:

    COP737 *** The COPE Intercepts are being set *** IECG.IEC1
    COP748 Invoking BMP prog COPEXPP1 tran COPEXPT1 to Set the COPE intercepts
    COP788 Doing BLDL for 1 Stubxs, lth 62, 1st 0025AA3E:C0009953
    COP788 BLDL got rc=0, reason code=0, from Tasklib
    COPYING FROM IMS141A.COPE.ACBLIBB
    COPYING TO IMS141A.COPE.DOPT.ACBLIB
    *** THE IMS INTERCEPTS ARE BEING SET ***
    *** INTERCEPTS SET - STARTING THE IECG IMS REGION ***
    *** THE TEST TRANSACTION CAN BE ENTERED ***

    The terminal is then locked. If the intercepts are set successfully, go to the IMS terminal and start the transaction you want to debug by entering the transaction code that invokes your program. When you press Enter, IMS schedules the transaction for execution and locks your terminal if it is in response mode. Return to the TSO terminal.

    If you have a source listing member for the high-level program, your source will be displayed. You are now ready to interactively debug a program with source. To enter or review data at any point in execution, go to the IMS terminal. At the TEST COMPLETED message, you can enter GO to retest this transaction, or enter EXIT to return to the MPP screen.

36. Access COPE ISPF. The COPE Primary Menu displays (as shown in the following figure).
    COPE Primary Menu

    

37. Specify Option 6;5 to access the Xpediter - Trace Display (as shown in the following figure).

Xpediter - Trace Display