This milestone will guide you through the configuration of a new installation of Code Debug TSO andd Code Debug IMS17.02.

If you are performing an upgrade instead, go to Milestone 5: Configure Code Debug TSO and Code Debug IMS — Upgrade.

Roles Involved

Complete the following tasks to configure a new installation of Code Debug TSO and Code Debug IMS.

Task 4.1 Customize XTUPDATE Macro

The following person is required for this task:

XTUPDATE is an ISPF edit macro that can be used to automate the entry of site-specific JCL parameters. Using this macro saves you from having to repeatedly type in the same information and ensures your JCL parameters are always entered correctly.

Task 4.1.1 Copy SLXTINST(XTUPDATE) into a Library in Your SYSPROC Concatenation

This CLIST library must be allocated to your ISPF session.

Task 4.1.2 Edit the XTUPDATE Macro

Entering the XTUPDATE Command

The JCL is customized for you to submit, as shown in the following figure.

XTUPDATE Macro Results

Task 4.2 Configure XPLIBDEF and XPCGDSN

The following person is required for this task:

Task 4.2.1 Copy SLXTINST(XPLIBDEF) and (XPCGDSN)

Copy the two CLISTs into a data set that is either part of the SYSPROC concatenation or that is activated with an ALTLIB command.

Task 4.2.2 Edit the XPLIBDEF CLIST

By default, the XPLIBDEF CLIST will use the Simple Deploy method to allocate the data set names specified in the CSMC PARMLIB DDSNnnnn member (DDSN00 by default). If you are not using the default member, make sure to point to the DDSNnnnn member name by setting the DDSNSFX keyword to the one- to four-character PARMLIB member suffix.

For example, to point to PARMLIB member DDSNCPWR, use:

    DDSNSFX(CPWR)In addition, the primary CMSC will be used by default. If you are not using the default CMSC, specify the CMSC to use by setting the CMSC keyword to the one- to four-character CMSC ID.

For example, to point to CMSC subsystem TEST, use:

    CMSC(TEST)This CLIST can alternately use High-Level Qualifiers (HLQ) to allocate the various BMC AMI products it references. The following table identifies the product and its associated “node”.

Product Node Values

See the comments in the XPLIBDEF CLIST for further information.

Task 4.3 Configure the XOPTIONS File

Task 4.3.1 Create a New XOPTIONS File

1. Use the XTUPDATE macro to configure SLXTINST(JCL015).
2. Submit the JCL. It should end with return code 0.

Task 4.3.2 Code the XOPTIONS KEYWORD=Value Pair

In Implement the CMSC PARMLIB, the XOPTIONS data set name should be specified by coding the following pair:

Task 4.4 Implement the CMSC PARMLIB

The following person is required for this task:

Starting with release 17.02, BMC AMI mainframe products, including Code Debug TSO and Code Debug IMS, use parameter libraries (PARMLIBs) in conjunction with the BMC AMI Common Mainframe Services Controller(CMSC) to configure each product as well as common components. The CMSC was installed as part of the BMC AMI Enterprise Common Components installation.

In this task, you will implement the CMSC PARMLIB for Code Debug TSO and Code Debug IMS. This consists of creating default members and updating the CMSC with them. The default members are suffixed with 00 and should contain the values you want for all LPARs on which Code Debug TSO and Code Debug IMSand Code Coverage are installed.

Task 4.4.1 Create an Initial PARMLIB Member

In this task, you will implement the CMSC PARMLIB for Code Debug TSO and Code Debug IMS. This consists of creating a default member and updating the CMSC with it. The default member is suffixed with the value gathered from your ECC administrator and recorded in  Table Information Gathering Worksheetof the  Planning section. The member should contain the values you want for customizing the installation of  Code Debug IMS and Code Debug IMS.

Any KEYWORD=value parameter specification omitted from a PARMLIB member will cause Code Debug TSO to use the Code Debug TSO-delivered default value for that parameter.

• XTSO00: Provided as a typical PARMLIB member in which only the necessary overrides for a site would be included. The last two characters of “XTSO00” are zeros. Note that for an extremely basic, functional Code Debug TSO installation, only five required PARMLIB values need to be coded:
  • SYSOUT_DATASET_DEFAULT_SYSOUT_CLASS=a-non-held-sysout-class
    • SYSOUT_DATASET_HELD_SYSOUT_CLASS=a-held-sysout-class
  • BASE_PRODUCT_DATASETS_HELPLIB_1=HLVLNODE.XPEDITER.HELP
  • OPTIONS_DATA_SET=HLVLNODE.XPEDITER.XOPTIONS
  • TEST_SESSION_DDIO_FILE_1=HLVLNODE.XPEDITER.DDIO
• XTSOALL: Contains all the possible KEYWORD=value specifications and could be used as a starting point whereby unnecessary specifications are deleted for the sake of simplicity. Note that the XTSOALL member contains more than 600 parameters.

1. Begin with an empty PARMLIB member named XTSOxx, (the suffix being the value gathered from your ECC administrator and recorded in Table Information Gathering Worksheet), and copy in values from SLXTSAMP(XTSO00). Follow the instructions within the member to make all required changes.

2. Execute the CLIST XPLIBDEF with the INSTALL option (XPLIBDEF INSTALL). The screen shown in the following figure is displayed.
   Installation Defaults Screen

   COMPUWARE INSTALL ---------  INSTALLATION DEFAULTS  ---------------------------
   COMMAND ===>
   
   This process will commit the changes made to the CMSC PARMLIB member into
   member XPTDFLTS in the Code Debug TSO Table Library.  A CMSC "REFRESH" will be
   attempted before the COMMIT action is performed.  Member XPTBACK0 will be
   used to save the previous values.
   
   Enter the DSNAME of the Table Library to be updated:
             Output ===> 'ACMJET0.XT170.TENU'
   
   To copy existing installation defaults, enter the DSNAME of the old
   Table Library (optional):
              Input ===>
   
   
   Enter the suffix of PARMLIB member (XTSOssss) to be committed:
             Suffix ===>          (The default is used if no override is entered)
   
   
             Action ===> COMMIT   (Type COMMIT and press Enter to process)
   
                           Should Dataset Names in PARMLIB be validated? YES
3. Enter the dsname of your new SLXTTABL data set in the Output field.
4. Specify an ACTION of COMMIT.
5. If you want the data set names specified in the XTSO00 PARMLIB member validated, enter YES to that question.

6. Press Enter.

   Important

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

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

8. 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

   SDSF JOB DATA SET DISPLAY - JOB CMSCAC01 (S0935052)     DATA SET DISPLAYED
   COMMAND INPUT ===>                                            SCROLL ===> CSR
   PREFIX=CMSCAC01  DEST=(ALL)  OWNER=*  SYSNAME=*
   NP   DDNAME   StepName ProcStep DSID Owner    C Dest               Rec-Cnt Page-Cnt Byte-Cnt CC
        JESJCLIN                      1 CMSCCW01 A                          2               127  1
        JESMSGLG JES2                 2 CMSCCW01 A                          2        1      135  1
        JESJCL   JES2                 3 CMSCCW01 A                         34             1,760  1
        JESYSMSG JES2                 4 CMSCCW01 A                      3,133           156,941  1
       $INTTEXT JES2                 5 CMSCCW01 A                         14               821  1
        EVENTLOG JES2                 8 CMSCCW01 A                          0                    1
   S    FDBDLOG  CMSCCW01           101 CMSCCW01 A                      6,940           658,776  1
        LMCPRINT CMSCCW01           102 CMSCCW01 A                      6,464      108  649,659  1
        LMZPRINT CMSCCW01           103 CMSCCW01 A                     12,774      213       1M  1

9. 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

   ----------------------------------------------------------------------------------------------------------------------------
   BROWSE    SYS17158.T111305.RA000.ACMJET0.R0160298                                             Line 0000000654 Col 001 132
    Command ===>                                                                                              Scroll ===> CSR
   
              KEYWORD: DIRECT_JCL_PROC_EXPANSION_CLASS
                VALUE: (I,PROC02)
   
              KEYWORD: DIRECT_JCL_PROC_EXPANSION_CLASS
                VALUE: (M,PROC02)
   
              KEYWORD: DIRECT_JCL_PROC_EXPANSION_DSNAME
                VALUE: (IATPLBST,'SYS1.PROCLIB')
   
   ------------------------------------------------------------------------------------------------------------------------
   
   THE FOLLOWING DB2 PROC KEYWORDS WERE REPLACED
   
              KEYWORD: DB2SP_SEARCH_PROC_DSNAME
                VALUE: 'XT.SP.PROCLIB'
   
   ------------------------------------------------------------------------------------------------------------------------
   
   NUMBER OF ERRORS THAT WERE DETECTED: NONE
   INSTALLATION DEFAULTS CAN BE SAVED INTO 'ACMJET0.XT170.TENU'
   NUMBER OF NEW VALUES TO BE COMMITTED TO THE TABLE: 116
   ************************************************** Bottom of Data ********************************************************
10. Press End, then press Enter (or press PF3).
11. Press Enter to update the Installation Defaults. A message should be displayed saying that your Installation Defaults have been saved.

Task 4.5 Configure Multi-Batch Support

The following people are required for this task:

Configure the Code Debug TSO Multi-Batch Facility (MBF). MBF is required for Workbench for Eclipse.

Task 4.5.1 Create the Multi-Batch Staging File

The following person is required for this task:

1. Use the XTUPDATE macro to configure SLXTINST(JCLCREMB).
2. Submit the JCL. It should end with return code 0.

Task 4.5.2 Activate Multi-Batch

The following person is required for this task:

1. Use the XTUPDATE macro to configure SLXTINST(JCLACTMB).
2. Submit the JCL. It should end with return code 0.

Task 4.5.3 Configure z/OS to Start Multi-Batch After IPL

The following person is required for this task:

1. Copy SLXTINST(JCLACTMB) into the appropriate library in your system PROCLIB concatenation.
2. Modify JCLACTMB to meet your site’s standards for a z/OS startup procedure, replacing the JOB statement with a PROC statement.
3. Configure your z/OS system to start JCLACTMB at IPL time by either:
   • Updating your z/OS PARMLIB member COMMNDxx.
   • Configuring your automated operations application.

An example of the START command is provided in SLXTINST(COMMNDxx).

Restrictions

When Code Debug TSO converts Db2 Batch JCL for use in Batch Connect testing, it moves the data set specified by the LIBRARY(dataset_name) keyword to the STEPLIB concatenation. Since Multi-Batch does not alter the JCL, the LIBRARY keyword of the DSN command (used in Db2 Batch programs that use IKJEFT01 to establish a connection to Db2) is not supported. If your program is in the library indicated by the LIB keyword, that library must be specified in the JCL’s STEPLIB or in the Code Debug SETUP load library list. In addition, the Db2 SDSNLOAD library must be specified in the JCL’s STEPLIB or in the Code Debug SETUP load library list.

Task 4.5.4 Configure the Multi-Batch Communication Task

If your site does not require Cross-LPAR support, go to Perform Initial Verification.

Task 4.6 Perform Initial Verification

The following person is required for this task:

Task 4.6.1 Verify Libraries

1. Execute the following TSO command:
   EX 'dataset(XPLIBDEF)'
   where dataset is the fully qualified data set name chosen in Task 4.2.1 Copy SLXTINST(XPLIBDEF) and (XPCGDSN).
2. From the Code Debug TSO Primary Menu, type XENV LEVELS in the OPTION field and press Enter. A screen similar to figure XENV Screen is displayed. Library versions should be those just installed.

XENV Screen

Task 4.6.2 Verify Base Installation

Installation Verification Programs (IVPs)

The base product has four sets of IVP programs, one for each programming language supported by Code Debug TSO and Code Debug IMS:

Base Code Debug TSO and Code Debug IMS IVPs

• The SYSLMOD output from these compiles should not be directed to the Code Debug TSO LOADLIB library. Instead direct the SYSLMOD output from your linkedit step to a test data set available to your application programmers for training sessions. For example, you could create a data set named hlq.TRAINLIB or hlq.SLXTIVP.
• To verify that the compile was successful and that a source listing member was created, check the listing under the DDNAME CWPERRM for a message similar to the following:
  LISTINGS SUCCESSFULLY WRITTEN OUT TO DDIO

Run the IVPs to Initiate Verification Test Sessions

For each step, the program name or JCL referenced is specific to the language.

Verification Test Session IVPs

1. Select 2 (TSO) from the Code Debug TSO Primary Menu.

2. Select 1 (STANDARD) from the Environments Menu.

   Important

   The Environments Menu is automatically displayed if this is your first time to invoke a test session. Otherwise, you can access the Environments Menu by entering SETUP from the command line of the displayed test screen and selecting option 0 from the Test Setup Menu.

3. Enter SETUP from the Standard test screen.
4. Select 1 (LOADLIBS) from the Setup Menu.
5. On the Load Module Libraries screen, specify the application load library that contains the language-specific IVP load module. Also specify your Language Environment (LE) run-time library (usually CEE.SCEERUN). Press Enter.
6. Enter END (or press PF3) to return to the Standard screen.
7. Specify the language specific program from the table above on the Program ===> line.
8. The SLXTSAMP library contains sample JCL that can be used to run the IVP. On the File List/JCL Member ===> line, enter the language specific data set/member name from the table above (for example, 'hlq.SLXTSAMP(TRIJCL)' for COBOL).
9. Press Enter to begin the Code Debug TSO debugging session. The message area contains the lines Allocating User Datasets,  then  Allocating CODE DEBUG TSO Datasets. On a blank screen, the message Entering CODE DEBUG TSO Test Environment is displayed along with information about the test. Then the source for the applicable TRIMAIN program is displayed.
10. Type GO 1 on the COMMAND line and press Enter.
    The execution arrow will be on the next statement. The execution status message indicates that you are BEFORE program-name:line-number.
11. Press PF12 (GO). The Triangle Report is written to the screen.
12. Press Enter until you return to the Source screen with a TEST COMPLETED message, indicating that your program executed successfully.
13. Press PF4 (EXIT) to exit the test session.

Task 4.6.3 Verify Db2 Installation

The following people are required for this task:

Preparations for Testing the Db2 IVPs

1. Create and populate a sample Db2 table by issuing the Db2 commands shown in the following figure. Use your site’s standard method to execute the Db2 commands. These commands are also contained in member DB2TABLE of the SLXTSAMP data set.
   Db2 Commands to Create and Populate Sample Table

   CREATE TABLE hlvlnode.TRIDB2DATA (SSNR CHAR(11) NOT NULL,
         LASTNAME VARCHAR(15) NOT NULL,
         FIRSTNAME VARCHAR(15) NOT NULL,
         STREETADR VARCHAR(20),
         CITY VARCHAR(15),
         STATE CHAR(2),
         ZIPCODE CHAR(9),
         PHONENR CHAR(12),
         LICENSENO CHAR(8)) IN databasename.tablespacename; 
   INSERT INTO hlvlnode.TRIDB2DATA
         VALUES ('111-23-4567', 'DOE', 'JOHN', '100 CENTRAL AVENUE',
         'CHICAGO', 'IL', '60601', '312-445-1234', 'PIW-304');
   INSERT INTO hlvlnode.TRIDB2DATA
         VALUES ('444-33-7867', 'JOHNSON', 'BOB', '234 LAKE DR',
         'CLEVELAND', 'OH', '63641', '514-545-4674', 'AFW-323'); 
   INSERT INTO hlvlnode.TRIDB2DATA
         VALUES ('555-73-7157', 'THOMSON', 'PAUL',
         '34 PORTLAND AVE.',
         'SAN FRANCISCO', 'CA', '68291', '204-423-1462', 'PGF-321'); 
   INSERT INTO hlvlnode.TRIDB2DATA
         VALUES ('216-56-4537', 'ADAMS', 'MIKE', '23543 WEST STREET',
         'CHICAGO', 'IL', '64251', '917-655-1289', 'RYN-104'); 
   INSERT INTO hlvlnode.TRIDB2DATA
         VALUES ('217-33-4378', 'JOHNSON', 'LARRY',
         '160 EMERSON AVENUE',
         'BOSTON', 'MA', '73458', '712-435-3234', 'GFW-645'); 
   COMMIT; 
   GRANT SELECT ON TABLE hlvlnode.TRIDB2DATA TO PUBLIC; 
   CREATE SYNONYM VTRIDB2 FOR hlvlnode.TRIDB2DATA; 
   COMMIT;

2. Edit an in-house compile procedure with a Db2 precompile to create a member in the DDIO data set. There is no need to change the Db2 precompile step. Optionally, you can use the online Compile Facility provided by Code Debug TSO by selecting option 1 (PREPARE) from the Primary Menu. The base product has three sets of IVP programs (Table Code Debug Base IVP Programs), one for each programming language supported by Code Debug TSO and Code Debug IMS (except for Assembler).

   Code Debug Base IVP Programs

   Language	Program/SAMPLIB Member
   COBOL	TRIDB2
   PL/I	TRIDB2P
   C	TRIDB2C

   The programs are contained in the SLXTSAMP library. Use the specific Language Processor (LP) to compile or assemble the sample programs. See the BMC AMI Common Shared Services User/Reference Space for information on using the correct LP (COBOL, PL/I, or C).

   Important

   If you do not already have compile JCL which uses LP, you have two options for getting started:

   • Access the online BMC AMI Common Shared Services Compile Facility by selecting option 1 (PREPARE) from the Code Debug TSO Primary Menu.

   • Edit an in-house compile procedure with a Db2 precompile that has been converted to run with BMC AMI Common Shared Services (CSS) to create a member in the DDIO data set. There is no need to change the Db2 precompile step.

   • The SYSLMOD output from these compiles should not be directed to the Code Debug TSO LOADLIB library. Instead direct the SYSLMOD output from your linkedit step to a test data set available to your application programmers for training sessions. For example, you could create a data set named hlq.TRAINLIB or hlq.SLXTIVP.
   • To verify that the compile was successful and that a source listing member was created, check the listing under the DDNAME CWPERRM for a message similar to the following:
     LISTINGS SUCCESSFULLY WRITTEN OUT TO DDIO
3. If the BIND step is not included in your JCL, bind the successfully compiled program either by following your site standard or by using the online Bind Facility provided by Code Debug TSO.

Run the IVPs to Initiate Verification Test Sessions

For each step, the program name referenced is specific to the language.

1. Select 2 (TSO) from the Code Debug TSO Primary Menu.
2. Enter SETUP from the Standard test screen.
3. Select 1 (LOADLIBS) from the Setup Menu.
4. On the Load Module Libraries screen, specify the application load library that contains the language-specific IVP load module. Also specify your Language Environment (LE) run-time library (usually CEE.SCEERUN).
5. Press Enter.
6. Select 6 (DSNLOAD) from the Setup Menu.
7. Specify the Db2 subsystem names and the associated SDSNLOAD data set names.
8. Press Enter.
9. Enter END (or press PF3) to return to the Standard screen.
10. Specify the language-specific program from above table Code Debug Base IVP Programs on the Program ===> line.
11. Specify YES in the Is This a DB2 Test? ===> field.
12. Specify the Db2 PLAN name in the Plan ===> field.
13. Specify the Db2 subsystem name in the System ===> field.
14. The SLXTSAMP library contains sample JCL that can be used to run the IVP. Copy this JCL to a PDS or PDSE of your own. Customize it per the instructions in the JCL.
    1. Add a valid JOBCARD.
    2. Change 'YOUR.DB2.LOADLIB' on the STEPLIB to the data set name of the relevant Db2 SDSNLOAD library.
    3. Change 'YOUR.COBOL.LIB' on the STEPLIB to the data set name of the Language Environment (LE) run-time library (usually CEE.SCEERUN).
    4. Delete the SYSHELP DD.
    5. Change the 'SYSTEM(DSN)' to the relevant Db2 subsystem name.
    6. Change the PROGRAM(TRIDB2) keyword to the language specific program (from above table Code Debug Base IVP Programs).
    7. Change the PLAN(TRIDB2) keyword to the PLAN name used in the BIND step.
    8. Change 'YOUR.APPLICATION.LOADLIB' to the data set name of the loadlib containing the program specified in the PROGRAM keyword.
15. On the File List/JCL Member ===> line, enter the data set/member name of the JCL that was just customized.
16. Press Enter to begin the Code Debug TSO debugging session. The message area contains the lines Allocating User Datasets, then Allocating CODE DEBUG TSO Datasets. On a blank screen, the message Entering CODE DEBUG TSO Test Environment is displayed along with information about the test. Then the source for the program is displayed.
17. Type GO 1 on the COMMAND line and press Enter.
18. The execution arrow will be on the next statement. The execution status message indicates that you are BEFORE program-name:line-number.
19. Press PF12 (GO). The TRIDB2 SAMPLE DIRECTORY REPORT is written to the screen. (An SQL error message is written to the screen instead if the BIND was not done properly.)
20. Press Enter until you return to the Source screen with a TEST COMPLETED message, indicating that your program executed successfully.
21. Press PF4 (EXIT) to exit the test session.

Task 4.7 Additional New Installation Configuration

Because you are performing a new installation of Code Debug TSO and Code Debug IMS, you should examine a number of additional Milestones necessary to configure a new installation.

A new installation of Code Debug TSO and Code Debug IMS may not require all of these tasks. The conditions that could require you to perform a task are defined as follows:

To Support Workbench for Eclipse

To configure Code Debug TSO and Code Debug IMS to work with Workbench for Eclipse, you will need to perform the tasks in Milestone 6: Configuring Workbench Integration.

To Use Code Debug TSO’s Batch Connect Feature

If you will be using Code Debug TSO to debug batch jobs on the mainframe, you will need to perform the tasks in Milestone 7: Configure Batch Connect Support.

To Use IMS/DB Support

If you will be using IMS/DB support, you will need to perform the tasks in Milestone 8: Configure IMS/DB Support.

Licensed for Code Debug IMS (IMS/DC Support)

If you have purchased this license, to configure it, you will need to perform the tasks in Milestone 9: Configure IMS/DC Support.

Licensed for Code Debug Db2 Stored Procedure Support

If you have purchased this license, to configure it, you will need to perform the tasks in Milestone 10: Configure Db2 Stored Procedure Support.

To Use Code Debug TSO with IBM’s BTS (Batch Terminal Simulator)

If you will be using Code Debug TSO’s BTS support, you will need to perform the tasks in Milestone 11: Configure BTS Support.

To Use High-Performance Breakpoint Processing Methodology

If you have not previously configured this feature and want to use it, you will need to perform the tasks in Milestone 12: Enable High-Performance Breakpointing.

Licensed for the Code Debug for Db2 Extension

If you have purchased this license, see the Code Debug TSO and Code Debug IMS Advanced Configuration Guide for more information.

To Utilize Code Debug TSO with CA-ROSCOE

If you want to use this feature, see the Code Debug TSO and Code Debug IMS Advanced Configuration Guide for more information.