Milestone 4 Configure Code Debug CICS — New Installation

This section will guide you through configuration of a new installation of Code Debug CICS 17.02.

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

The following roles are involved in this milestone:

• z/OS Security Administrator
• Code Debug CICS Installer
• z/OS System Programmer
• CICS System Programmer.

To help you to set up security groups for external security, the following tables list the Code Debug CICS (and Code Coverage) transactions and their uses. The tables also identify started transactions and provide recommended external security settings.

The terms used in the “Security Recommended” column are defined as follows:

• NO - All users of Code Debug, including the user ID associated with PLTPI programs, should be permitted to execute these transactions.
• YES - These transactions provide capabilities beyond the needs of a typical end user of Code Debug. Access may be limited to those responsible for installation, configuration, etc.
• EITHER - No recommendation.

Code Debug CICS Transactions

Code Coverage Transactions 

Started Transaction User Security

User Security for Code Debug CICS Started Transactions.

User Security for Code Coverage Started Transactions

If you need to control activity in the Code Debug CICS File Utility, see to the section entitled “Implementing-the-File-Utility-Security-Exit” in the Code Debug CICS Advanced Configuration Guide.

Task 4.1.3 INQUIRE ASSOCIATION Considerations

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. The ASSOCIATION command is subject to CICS command security checking using the resource identifier (ASSOCIATION). Code Debug CICS will need a profile created that allows all CICS users to have READ access for resource identifier ASSOCIATION.

Task 4.1.4 BMC PARMLIB Reports

Code Debug CICS has replaced the z/OS services (dynamic allocation and file open/write/close) used to produce the BMC PARMLIB Reports with the use of CICS Extrapartition Transient Data Queues and CICS services. As part of this refactoring, three new TDQ definitions have been included in the SMXDSAMP member CSDXDFIL. PARMLIB Parameter Reports table lists the default TDQ names, the BMC PARMLIB Report associated with the TDQ, and the PARMLIB overrides used to change the TDQ names if required.

Whether you are performing a new install or upgrading to a new release, these queues should be defined to produce the BMC PARMLIB reports during PARMLIB processing. Review member CSDXDFIL and add these queues to your RDO definitions. If you decide to modify the queue names, be aware that you must also add the appropriate parameter changes to your BMC PARMLIB members. If you decide not to install these TDQ definitions, be aware that:

• Additional messages may be written to the CSMT queue indicating that the TDQ definitions are not present.
• The report produced by the Installation Verification Program (transaction XIVP) will display warning messages for any missing queues.

The global tables supplied with the product have also had their default values for the report ddnames changed to reflect the new TDQ queues. If you install the new TDQ definitions and do not change the default names, you should not encounter any errors.

BMC PARMLIB parameters that are being deprecated by this change are:

• CODE_COVERAGE_PARMLIB_REPORT_ALLOCATION
• CODE_COVERAGE_PARMLIB_REPORT_SYSOUT_CLS
• DBPA_REPORT_ALLOCATION
• DBPA_REPORT_SYSOUT_CLASS
• PARMLIB_REPORT_ALLOCATION
• PARMLIB_REPORT_SYSOUT_CLASS

The following BMC PARMLIB parameters are being repurposed from supplying a one- to eight-character ddname to providing a one- to four-character TDQ name (if it is necessary to override the new TDQ names):

• CODE_COVERAGE_PARMLIB_REPORT_DDNAME
• DBPA_REPORT_DDNAME
• PARMLIB_REPORT_DDNAME

The reports produced have had minor cosmetic changes made to better describe what the reports represent and the names of the TDQ that they are written to.

BMC PARMLIB Parameter Reports 

Task 4.1.5 Additional Considerations

The following security considerations are covered in more detail in Milestone 6: Configure Workbench Integration.

Enabling CICS Transaction for XSKL User ID

The user ID associated with transaction XSKL must be permitted to start a CICS transaction as a surrogate for the Workbench for Eclipse user (for example: read access to *.DFHSTART in CLASS SURROGAT).

Verifying Transaction Definition for Controlling Access from Workbench for Eclipse

XPGD is the default transaction code for controlling access to Code Debug CICS from Workbench for Eclipse. If XPGD is not already defined, a sample is in SMXDSAMP member CSDXDTRN.

Task 4.2 Prepare the ISPF Edit Macro

This milestone requires the Code Debug CICS Installer.

To use the edit macro, first copy member XDUPDATE from the SMXDSAMP member into your CLIST library. Then enter your site-specific information in the XDUPDATE macro. The macro includes instructions for entering the information. Your CLIST library must be allocated to your ISPF session. You can verify that your CLIST library is accessible to ISPF by entering the command TSO LISTA or TSO ISRDDN.

The edit macro can be used during Code Debug installation each time you are instructed to edit JCL. To run it, first open the JCL member for editing. You can then look at the JCL before any changes are made. Type XDUPDATE in the COMMAND field of the ISPF EDIT screen and press Enter.

Task 4.3 Integrate Code Debug CICS with MVS

This milestone requires the Code Debug CICS z/OS System Programmer

Ensure the Code Debug CICS 17.02 SMXDAUTH library is APF authorized. The Code Debug CICS APF authorized library is backward compatible. BMC suggests you add the data set to your IEAAPFxx or PROGxx list, as appropriate, so it will be APF authorized at each system IPL.

1. Add program DBUGSTC to the MVS program properties table (PPT) member in SYS1.PARMLIB using either of the following methods:
   • Copy SMXDSAMP member SCHEDXD to SYS1.PARMLIB, then add XD to the SCH=(xx) directive of IEASYSxx in SYS1.PARMLIB. For example, change SCH=00 to SCH=(00,XD).
   • Append SMXDSAMP member SCHEDXD to your SCHEDxx member in SYS1.PARMLIB.
2. Update the MVS PPT by issuing one of the following MVS operator commands:

Task 4.3.3 Define the Code Debug Service Provider as an MVS Subsystem

• • Copy SMXDSAMP member IEFSSNXD to SYS1.PARMLIB, then add XD to the SSN=(xx) directive of IEASYSxx in SYS1.PARMLIB. For example, change SSN=00 to SSN=(00,XD).
  • Append SMXDSAMP member IEFSSNXD to your IEFSSNxx member in SYS1.PARMLIB.

You are not required to perform an IPL to use the Code Debug Service Provider. If an MVS subsystem entry has not already been defined, Code Debug CICS will build one dynamically during initialization.

Task 4.4 Update the CICS Resource Definitions

This milestone requires the CICS System Programmer

• Some Code Debug CICS control blocks are GETMAINed in accordance with the TASKDATALOC specified for the transaction being tested. Code Debug’s use of below the line storage can be reduced by specifying TASKDATALOC=ANY for your eligible transactions.
• Code Debug CICS does not support programs with RELOAD:YES in the program resource definition. Remove this option for programs that you plan to debug with Code Debug.
• Do not define temporary storage queues with an XP prefix as remote.
• In DFHSITxx, do not specify SRT=NO.
• If your site will be initializing Code Debug CICS using PLT startup, observe the following conditions:
  • Add the Code Debug CICS program DBUGPPM2 to the PLT program initialization (PLTPI) table.
  • Shutdown of Code Debug CICS via the PLT is supported. To enable this support, add program DBUGPLTS to the PLTSD table. In your CICS shutdown PLT, before the line reading DFHPLT TYPE=ENTRY,PROGRAM=DFHDELIM, add the following entry:

Do not put DBUGPPM2 in the PLTSD table.

Task 4.4.1 Using RDO to Update Resource Definitions 

1. The previous method of using z/OS dynamic allocation and file open/close/write services to produce BMC PARMLIB reports has been removed from the product and replaced with the use of transient data queues. PARMLIB Parameter Reports table describes the queues, the report written to each queue, and the PARMLIB member prefix and parameter needed to override the queue name (if necessary). The definitions of these queues are in SMXDSAMP member CSDXDFIL. The only modifications you may need to make are to the TDQUEUE name and the ddname. The other definition values should not be changed. Changing the TDQUEUE name will require you to use the appropriate PARMLIB parameter so that the correct queue is used to produce the report during parameter processing. The ddname parameters must not conflict with existing ddnames in your region’s JCL or other TDQUEUE definitions.
   While BMC suggests defining all three queues, you can decide to define only one and use the appropriate PARMLIB parameters to point the reports to that single queue—or use INDirect queues to point to a single queue. The report queues cannot be defined as INTra or Remote.

2. Review the supplied JCL member DBCRDO. See to the following table and use the SYSIN in resource members CSDXDFIL, CSDXDPRG, and CSDXDTRN. If Code Debug’s program autoinstall is implemented during customization, CSDXDPRG can be omitted
    

   Warning

   Important

   • If your site is not using Code Coverage, edit the CSDXDFIL, CSDXDTRN, and CSDXDPRG members and comment out the definitions for Code Coverage data sets, transactions, and programs (prefixed with XV).

   • If your site is using BAS, you may use the furnished JCL member CSD2BAS to create an input file for the BATCHREP view in the CICSPlex SM End User Interface.

   • LSRPOOLNUM or LSRPOOLID may be specified as appropriate. Be aware that for file control update requests, CICS does not support the use of LSRPOOLNUM(NONE) or LSRPOOLID(NONE) while Transaction Isolation is active. This restriction is enforced with an AFDK abend.

3. The Code Debug CICS resource group created in this step must be added to a CICS group list, which in turn is specified in the system initialization parameter GRPLIST
4. CSDXDFIL contains an ENQMODEL. Ensure that this ENQMODEL definition is added to all CICS regions that share the same Code Debug CICS Profile Data set.

5. Submit JCL member DBCRDO to batch the required CEDA transactions.

   Warning

   Important

   • If you changed any of the Code Debug transaction IDs before submitting the JCL, the corresponding configuration parameters must also be changed. For details, see the Code Debug CICS Advanced Configuration Guide.

   • The section entitled Configuring-Intercommunication-Facilities in the Code Debug CICS Advanced Configuration Guide contains additional transaction definitions that may be necessary for your environment.

• • To run the subsystem as a batch job:

1. If you change the value of the SSID parameter value in member XDSSJCL, make sure you change the global parameter SERVICE_PROVIDER_SUBSYSTEM_NAME to match.

2. Submit XDSSJCL.

• • To run the subsystem as a started task, issue the following operator command:

    S XDSSPROC{,SSID=xxxx}

    where {,SSID=xxxx} is an optional parameter used to override the default subsystem identifier, XDSS, with the identifier used at your site.

    If you would like the Code Debug Service Provider to be initialized automatically during MVS startup, add the following start command to SYS1.PARMLIB member COMMNDxx:

    S XDSSPROC,SSID=xxxx

    where xxxx is the subsystem identifier. XDSS is the default. Place the start command for the Code Debug Service Provider after your start of TCPIP.

    Warning

    Important

    The MVS Performance Group for the Code Debug Service Provider must be higher than CICS and less than VTAM to prevent runtime abends.

Submit SMXDSAMP member DBCDEFPF to define the VSAM KSDS profile file.

The resource definition for DBUGPRF was installed as part of Update the CICS Resource Definitions.

Task 4.7 Set Up Test Assets

Task 4.7.1 Assemble/Compile and Link-Edit the Test Programs

The following table show the program name for each test program found in the SMXDSAMP library and the language that it is used for. The tables also include the name of the Assembler subroutine that is called by each of these programs.

Test Programs.

Additional Test Programs Using Channels and Containers

Setting Up CSS Language Processor JCL

For specific information on compiling your programs using the BMC Language Processors (LPs), see to the BMC AMI Common Shared Services User/Reference Guide. This guide will provide information on using the correct LP (COBOL, PL/I, Assembler, or C). If you do not already have compile JCL which uses LP, use the appropriate sample JCL provided in the Enterprise Common Components (ECC) sample library SLCXCNTL to modify your existing compile JCL. For example, member CXCOBPRE provides JCL that uses the LP COBOL preprocessor to compile a COBOL program, and member CXCOB1 provides JCL that uses the LP COBOL postprocessor when compiling a COBOL program.

Verify Test Programs Function

Complete the following steps to ensure that the test programs function properly:

1. Assemble program CWCDSUBA. If you have the Assembler option, process it using the BMC Assembler language processor. For detailed information, see “Assembler Language Processor” in theBMC AMI Common Shared Services User/Reference Guide. The CWCDSUBA routine does not contain any CICS commands and, therefore, does not need to be translated. CWCDSUBA must be included when CWDEMCB2, CWDEMCCH, CWDEMPE, or CWDEMPCH are link-edited.

   Warning

   Important

   For the following steps, only the step for your site’s primary language needs to be performed. You can perform the steps for any other languages your site has support for as well.

2. If you have the COBOL option, compile the CWDEMCB2 program with the modified compile/link-edit JCL that includes the BMC COBOL language processor. Use the NODYNAM parameter in the COBOL compile step and make sure that the library for CWCDSUBA is in the SYSLIB data set. For detailed information, see “COBOL https://docs.compuware.com/cy/CY1702/html/CSS_UserRef/Responsive%20HTML5/index.html#t=CSS_UserRef%2Fcobol_lp%2Fcobol_lp.htmLanguage Processor” in the BMC AMI Common Shared Services User/Reference Guide. (You may also compile CWDEMCCH.)

3. If you have the PL/I option, compile the CWDEMPE program with the modified compile/link-edit JCL that includes the BMC PL/I language processor. Make sure that the library for CWCDSUBA is in the SYSLIB data set. For detailed information, see “PL/I confluencePage:id:995987012Language Processor” in the BMC AMI Common Shared Services User/Reference Guide. (You may also compile CWDEMPCH.)

4. If you have the Assembler option, assemble CWDEMASM using the modified assembly/link-edit JCL that includes the BMC Assembler language processor. For detailed information, see “Assembler Assembler-Language-ProcessorLanguage Processor” in the BMC AMI Common Shared Services User/Reference Guide. (You may also assemble CWCEEASM and CWDEMACH.)

5. If you have the C option, compile the CWDEMC program with the modified compile/link-edit JCL that includes the BMC C language processor. (You may also compile CWDEMZCH.) For detailed information, see “Compiling-and-Binding-C-Test-Programs” in the  Code Debug CICS Advanced Configuration Guide.

Task 4.7.2 Allocate and Initialize the Employee File (DBCDEFEM)

The employee data set (keyed sequential) is required to run the test (demonstration) programs.

Define a VSAM KSDS file using the JCL in SMXDSAMP member DBCDEFEM. The JCL loads the file with five records. The test programs require that these records be present.

The resource definition for DBUGEMP was installed as part of Update the CICS Resource Definitions.

Task 4.8 Update the CICS Startup JCL

Change your site’s CICS startup JCL as follows:

1. Make the CSS load library accessible to Code Debug CICS by adding it to the DFHRPL concatenation in the CICS startup JCL. The CSS load library is named CPWR.LCXnnn.SLCXLOAD (nnn is the release of CSS) and is included in the installation of Enterprise Common Components.

2. Add the appropriate Code Debug CICS load library listed in the following table to the DFHRPL concatenation:
   Load Libraries for CICS Release Support. 

   CICS Release	Data set Name
   CICS TS 5.6	CPWR.VMXD170.SMXDO73L
   CICS TS 6.1	CPWR.WMXD170.SMXDO74L
   CICS TS 6.2	CPWR.XMXD170.SMXDO75L
   CICS TS 6.3	CPWR.YMXD170.SMXDO76L

3. Define one or more SLS data sets to CICS using one or any combination of the following methods. (The maximum number of ddnames is specified by PARMLIB parameter MAXIMUM_SLS_FILES_TO_SEARCH. For more information, see the section entitled “Configuration-Parameters” in the Code Debug CICS Advanced Configuration Guide.
   • Enable dynamic allocation by using PARMLIB parameter ENABLE_DYNAMIC_FILE_DEF_FOR_SLS_FILES and naming the SLS data sets as required for that feature. For more information, see the description of ENABLE_DYNAMIC_FILE_DEF_FOR_SLS_FILES in the section entitled “Configuration-Parameters” in the Code Debug CICS Advanced Configuration Guide.

   • Add a DD statement and/or RDO definition for each SLS standard DDIO data set or shared directory to the CICS startup JCL.

     Warning

     Important

     • If you use a non-IBM dynamic allocation product, ensure that the source listing data sets are excluded from automatic opens performed by these products when the data set is allocated. If you fail to do so, you may be unable to access source listings through Code Debug CICS.

     • The optional data sets described in the remainder of this step have not yet been created.

4. If you are not dynamically allocating CICS data sets, add a DD statement for the profile file created in Allocate a Profile File(DBCDEFPF).
5. If you are not dynamically allocating CICS data sets, add a DD statement for the employee file created in Allocate and Initialize the Employee File (DBCDEFEM).

Task 4.9 Verify the Basic Code Debug CICS Installation and Configuration

All discrepancies detected by XIVP are assigned a severity level of SEVERE, ERROR, WARNING, or INFORMATIONAL.

If severe errors are detected during initialization, they are placed in the temporary storage queue XPEDXIVP, and Code Debug CICS abends with a code of DBI0. For information on the abend code, see to the section entitled “Abend-Codes” in the Code Debug CICS Messages and Codes section. If the product is being initialized at a terminal where errors are detected, the following messages are directed to the terminal user before the abend is issued:

ERRORS WERE DETECTED DURING INITIALIZATION

USE CEBR TO BROWSE TEMPSTG QUEUE XPEDXIVP, OR
EXAMINE TRANSDATA DESTINATION CSMT FOR MESSAGES, OR
EXECUTE TRANSACTION XIVP DEST=TERMINAL TO SEE ERRORSIf ERROR level discrepancies are detected during initialization, they are placed in the temporary storage queue XPEDXIVP, and Code Debug CICS initialization will continue. If the product is being initialized at a terminal, the messages shown as follows will be directed to the terminal user. If the user responds NO to the CONTINUE INITIALIZATION prompt, Code Debug CICS abends with DBI0.

ERRORS DETECTED THE PRODUCT MAY BE USED, BUT UNPREDICTABLE RESULTS

MAY OCCUR, UP TO AND INCLUDING POSSIBLE REGION
OUTAGES. CORRECT THESE ERRORS AS SOON AS POSSIBLE.CONTINUE INITIALIZATION? ==> (YES/NO)If product is initialized with ERROR level discrepancies, a message “Code Debug initialization error, execute XIVP” will be issued to the terminal when a new Code Debug CICS session is started. This will alert each user to the fact that there may be problems with the product's configuration. These errors should be corrected as soon as possible.

Task 4.10 Review Automatic Session Termination

The following tasks will be sufficient for most sites where terminal autoinstall is used. For other methods, see to the section entitled “Configuring-Automatic-Session-Termination” in the  Code Debug CICS Advanced Configuration Guide.

Task 4.10.1 Modify the Terminal Autoinstall Exit DFHZATDX

If your site uses a different autoinstall exit, its name can be found in the SIT parameter AIEXIT.

1. Add the following line of code to DFHZATDX in the “Delete Processing Section” after the IBM Put Delete Code Here comment:
   EXEC CICS START INTERVAL (0) TRANSID (’XPN0’) FROM (DELETE_TERM_ID)

   Warning

   Important

   • Add the above line in the section labeled DELETE_TERMINAL. Do not add the line to the section labeled DELETE_SHIPPED_TERMINAL.

   • Consider adding “NOHANDLE”—or other appropriate condition handling—for exception conditions such as TRANSIDERR.

2. Reassemble and link edit DFHZATDX (or whatever VTAM terminal autoinstall exit is used at your site).