Milestone 6: Configure Workbench Integration

This section will guide you through the tasks necessary to integrate Code Debug CICS with Workbench for Eclipse.

If your site

• Is not using—and does not plan to use—Workbench for Eclipse, or
• Has already configured your CICS environment for Workbench for Eclipse integration during a previous installation or upgrade, go to Milestone-7-Specifying-Additional-Configuration-Parameters.

Code Debug CICS makes use of IP CICS Sockets for integrating with Workbench for Eclipse. If you do not currently have IP CICS Sockets defined in your CICS regions, follow the installations steps outlined in the IP CICS Sockets Guide supplied with IBM’s z/OS Communication Server.

Task 6.2 Verify IP CICS Sockets Listener Program and Transaction Definitions

The CICS System Programmer role is involved in this task.

XSKL is the default transaction code for the IP CICS sockets listener. If XSKL is not already defined, a sample is in SMXDSAMP member CSDXDTRN. Code Debug CICS requires use of the default CICS sockets listener, EZACIC02, delivered with the z/OS Communications Server. If you have customized this program, see to the Code Debug CICS Advanced Configuration Guide for considerations.

Transaction XSKL will run under the following security (If you choose another transaction code, make note of it for later use in Task 6.5 - Define Listener to IP CICS Sockets):

• If invoked from the PLTPI, it will run under the CICS PLT user ID (if the listener is started in the CICS PLT) or the ID of the user that invoked the EZAO transaction (if the listener is started using the EZAO transaction).
• If invoked from a terminal, it will run under the terminal user.
• Or in all cases, it can run under the default user ID specified in the USERID parameter in the IP CICS EZACICD definition.

• As previously mentioned in External Security Considerations, 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).

  Warning

  Important

  If you wish to limit access to Code Debug CICS by use of Workbench for Eclipse, you should instead secure transaction code XPGD as described in the following Task 6.3 - Define Transaction Code for Limiting Access to Code Debug CICS Using Workbench for Eclipse.

• If your site has CICS SIT parameter XPCT=YES:
  • If you do not want to limit access, make sure you do not secure this transaction.
  • If your site wants to limit access to Code Debug CICS debugging facilities through the use of Code Debug Eclipse, you may do so by limiting access to transaction XPGD as follows:
    • Define any users you want to allow access by adding user profiles in the ACICSPCT class. Any users added should have READ access.
    • A QUERY SECURITY RESTYPE(TRANSACTION) will be performed for this transaction, and any user with READ access will be allowed to continue. If a user does not have READ access, they will not be allowed to continue, and message MXDSK0026E Access Denied, uuuuuuuu Is Not Authorized To Use
      
      {{display reference="Mainframe.DevX.BMC-AMI-DevX-Code-Debug-for-CICS.bcxcics1702._SvIncludeLibrary._SvIncludePlusContent-_XpediterCICS_short-1.WebHome"/}} API (where uuuuuuuu is the user ID) will be displayed in the message log.
  • If your site has CICS SIT parameter XPCT=NO:
    • If you do not want to limit access, make sure transaction XPGD is not secured. This can be done by setting parameter RESSEC(NO) on the XPGD transaction definition (the default shipped with the product).
    • If your site wants to limit access to Code Debug CICS debugging facilities through the use of Code Debug Eclipse, you may do so by limiting access to transaction XPGD as follows:
      • Set parameter RESSEC(YES) on the XPGD transaction definition.
      • Define any users you want to allow access by adding user profiles in the ACICSPCT class. Any users added should have READ access.
      • A QUERY SECURITY RESTYPE(TRANSACTION) will be performed for this transaction, and any user with READ access will be allowed to continue. If a user does not have READ access, they will not be allowed to continue, and message MXDSK0026E Access Denied, uuuuuuuu Is Not Authorized To Use
        
        {{display reference="Mainframe.DevX.BMC-AMI-DevX-Code-Debug-for-CICS.bcxcics1702._SvIncludeLibrary._SvIncludePlusContent-_XpediterCICS_short-1.WebHome"/}} API (where uuuuuuuu is the user ID) will be displayed in the message log.

Task 6.4 Define Code Debug CICS Sockets Security Exit

The CICS System Programmer role is involved in this task.

If you wish to ensure user ID/password authentication and logon, you must specify the parameter SECEXIT=XDPCICSE in the IP CICS Sockets Listener definition in the next section. If you do not require a user to log on to CICS, leave this parameter blank. This will cause the default CICS user ID to be assigned to the task under which the Workbench for Eclipse session runs.

If program XDPCICSE is not already defined, a sample is in SMXDSAMP member CSDXDPRG.

Task 6.5 Define Listener to IP CICS Sockets

The roles involved in these milestones are the following:

• CICS System Programmer
• Network Administrator.

Execute the EZAC transaction and define the listener using the EZAC DEFine and ALTer commands.

XSOC is the default transaction code for the Code Debug CICS sockets interface. If XSOC is not already defined, a sample is in SMXDSAMP member CSDXDTRN.

Transaction XSOC will run under the following security:

• If the listener is started from the PLTPI, XSOC will run under the CICS PLT user ID. If the listener is started using the EZAO transaction, XSOC will run under the ID of the user that invoked the EZAO transaction.
• If the XSKL IP CICS socket definition (EZACICD) specifies a default user ID, that user ID will be used.

The USEREXIT parameter can be used if you want to ensure that the user attempting to use Code Debug Eclipse can be authenticated. If you want to require authentication, the program XDPCICSE must be specified. If a user cannot be authenticated, access to Code Debug CICS debugging facilities through Code Debug Eclipse will be prohibited.

The HELP LISTENER command can be used to display and validate the listener definition.

Definitions for Enabling Listener to IP CICS Sockets - Upper 

Definitions for Enabling Listener to IP CICS Sockets - Lower

Task 6.6 Update the HCI Parameter File for CICS Debugging

Specifically:

• CSTRAN in EZAC must match CICS_ENV SOCK in the HCI Parameter File
• PORT in EZAC must match CICS_ENV PORT in the HCI Parameter File.

Task 6.7 Enable Code Debug CICS Sockets-Based Debugging

• Activate the new listeners using the EZAO transaction. This is not necessary, however, if you have stopped and started IP CICS Sockets.
• Refresh the HCI parameter member you updated in Task 6.6 Update the HCI Parameter File for CICS Debugging.
• To implement the changes in the HCI, stop and restart the HCI.

Task 6.8 Validate the Workbench for Eclipse Integration

The Workbench for Eclipse Installer role is involved in this task.

The HELP LISTENER and HELP HCI commands can be used to assist in validating and troubleshooting the connection between Code Debug CICS and Workbench for Eclipse.