Milestone 5: Configure Code Debug CICS — Upgrade

This section will guide you through configuration of an upgrade to Code Debug CICS 17.02.

If you are performing a new installation instead, go to Milestone-6-Configure-Workbench-Integration.

Compare Code Debug CICS Transactions table and Code Coverage Transactions table in section Milestone 4: Configure Code Debug CICS — New Installation to your existing transaction security profile and set the appropriate security for any new transactions.

Task 5.2 Prepare the ISPF Edit Macro

This milestone requires the Code Debug CICS Installer.

If you have used the ISPF Edit Macro in the past, replace your existing edit macro rather than trying to update it. This will ensure that you are using an up-to-date edit macro.

To use the edit macro, first copy member XDUPDATE from the SMXDSAMP member (as described in the Note above) into your CLIST library. Then enter your site-specific information in the XDUPDATE macro. The macro includes instructions for entering the information (if you have used the ISPF Edit Macro in the past, it may be helpful to see to the prior version). 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.

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 5.3 Authorize the Code Debug SMXDAUTH Library

This milestone requires 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. PTFs XDQ021O–XDQ021U have replaced the z/OS services (dynamic allocation and file open/write/close) used to produce the BMC PARMLIB Reports with the use of CICS Extra partition Transient Data Queues and CICS services. As part of this refactoring, three new TDQ definitions have been included in the SMXDSAMP member CSDXDFIL. BMC PARMLIB Parameter Reports table lists the default TDQ names, the BMCPARMLIB Report associated with the TDQ, and the PARMLIB overrides used to change the TDQ names if required. For more information, see Task 4.1.4 BMC PARMLIB Reports. 

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.

Resource Members. 

Task 5.5 Update and Initialize the Code Debug Service Provider

This milestone requires z/OS System Programmer.

If you change the value of the SSID parameter value, make sure you change the PARMLIB parameter SERVICE_PROVIDER_SUBSYSTEM_NAME to match. For details on other Code Debug Service Provider parameters, see “Specifying-Code-Debug-Service-Provider-Parameters” in the Code Debug CICS Advanced Configuration Guide..

Task 5.6 Migrate Existing Parameters to BMC PARMLIB

• ECC Installer.

After ECC 17.02 has been upgraded, continue with the applicable migration process as follows, depending on which of the two scenarios describes your site. The following person is required for this task:

• Code Debug CICS Installer.

Upgrading Existing BMC PARMLIB Members:

Proceed directly to Migrate BMC PARMLIB Members to BMC PARMLIB Version 2.

Upgrading From a Release Prior to 17.02.

If you have been using the XDGBLINP and/or XDDBPINP DDs to specify parameters, you will instead need to specify these parameters within the BMC PARMLIB. Follow the steps in Migrate XDGBLINP Global Table Overrides through Migrate BMC PARMLIB Members to BMC PARMLIB Version 2 as follows.

Task 5.6.1 Migrate XDGBLINP Global Table Overrides

XDGBLINP may or may not vary across CICS regions:

• If your current XDGBLINP is common across all CICS regions, copy your current override member into BMC PARMLIB member XDGB00. In all cases, the XDGB00 member will be the first member read for input.
• If your current XDGBLINP varies across different CICS regions, copy your current override members from the data sets in the XDGBLINP DD into the BMC PARMLIB with member names of XDGBxxxx (where xxxx is 1 to 4 valid member name characters). Specify the XDGBxxxx members to be read for each CICS region in the BMC PARMLIB index member XD$$00. The members will be read during product initialization or when the XSIT transaction is used to refresh parameter changes.

Task 5.6.2 Migrate XDDBPINP DBPA Input

XDDBPINP may or may not vary across CICS regions:

• If your current XDDBPINP is common across all CICS regions, copy your current override member into BMC PARMLIB member XDDB00. In all cases, the XDDB00 member will be the first member read for input.
• If your current XDDBPINP varies across different CICS regions, copy your current override members from the data sets in the XDDBPINP DD into the BMC PARMLIB with member names of XDDBxxxx (where xxxx is 1 to 4 valid member name characters). Specify the XDDBxxxx members to be read for each CICS region in the BMC PARMLIB Index Member XD$$00. The members will be read during product initialization or when the XDBP transaction is used to refresh parameter changes. For more information on XD$$00, see the Code Debug CICS Advanced Configuration Guide.

Task 5.6.3 Migrate BMC PARMLIB Members to BMC PARMLIB Version 2

ECC 17.02 with all current maintenance supplies a Migration Utility (member MIGDRIVR in ECC SLCXCNTL) that will allow you to migrate your existing Version 1 BMC PARMLIB members to Version 2. Version 1 PARMLIB members were created when you first installed Code Debug CICS release 17.02 (or as described in Migrate XDGBLINP Global Table Overrides and Migrate XDDBPINP DBPA Input above).

The ECC Migration Utility includes a Code Debug CICS-specific module MXDMIGRT as part of this migration. Module MXDMIGRT will convert Version 1 keywords and values to the newly-implemented Version 2 keywords and values. You should run this utility for all your current BMC PARMLIB members for Code Debug CICS and for Code Coverage (if using Code Coverage with Code Debug CICS). These include members prefixed with XDGB, XDDB, and XVGB, as well as the index member XD$$00. See to the Enterprise Common Components Installation and Configuration guide “Migration Utility" for instructions on how to execute this utility.

Task 5.7 Update the CICS Startup JCL

1. Ensure that the most current CSS load library is in the DFHRPL concatenation. 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. Using the following table choose the appropriate Code Debug CICS load library and update 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. The XDGBLINP and XDDBPINP DD statements will no longer be used and should be removed from your CICS Startup JCL.

Task 5.8 Replace Previously Assembled Global Parameters Table

This milestone requires Code Debug CICS Installer

• the BMC PARMLIB and
• for sites requiring renaming of the DBPA, XPED, XPRT, XPON, or XPSP transactions, use of the CICS SIT parameter INITPARM for program DBUGTXNO.

See  Milestone 7: Specifying Additional Configuration Parameters for details about specifying parameters with the BMC PARMLIB and the section Overriding Session Initialization Transactions in the Code Debug CICS Advanced Configuration Guide for instructions on overriding transaction identifiers DBPA, XPED, XPRT, XPON, or XPSP.

Task 5.9 Verify the Basic Code Debug CICS Installation and Configuration

This milestone requires Code Debug CICS Installer.

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. See to "Abend-Codes" in the Code Debug CICS Messages and Codes space for information on the abend code. 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:

If 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 following messages shown will be directed to the terminal user. If the user responds NO to the CONTINUE INITIALIZATION prompt, Code Debug CICS abends with DBI0.

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 5.10 Update Support for the Db2 File Utility

This milestone requires DB2 DBA.

Perform the following steps to bind the plan:

1. Modify the JCL in member DBBIND10 as described in the comments within that member.
2. The JCL in DBBIND10 must be executed by an authorized Db2 user. Submit the JCL and ensure it completes successfully.
3. The plan bound above must be granted EXECUTION authority of PUBLIC by executing the following SQL statement using SPUFI (or whatever Db2 utility is used at your site):

If you changed the plan name in the JCL above, substitute that plan name in place of MXDPLAN before executing the SQL statement.

Task 5.11 Update Support for the IMS File Utility

This milestone requires IMS DBA.

Task 5.12 Update the File Utility Security Exit

This milestone requires Code Debug CICS Installer.

If you have implemented the File Utility Security Exit (DBUGUSEC), you will need to reassemble and relink the exit routine. For more information, see the section entitled “Implementing-the-File-Utility-Security-Exit” in the  Code Debug CICS Advanced Configuration Space.

Task 5.13 Update the Memory Update Security Exit

This milestone requires Code Debug CICS Installer.

Task 5.14 Update the Subsystem Security Exit

This milestone requires Code Debug CICS Installer.

Task 5.15 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.