Setting up the CICS DB2 environment

Because the CLIP agent uses CICS® interactive debugger technology, a CICS Application Debugging Profile (CADP) profile must exist in the CICS DB2 environment. The profile is needed to determine which transactions to monitor for DB2® events. Rational® Integration Tester can create the profile for you if the application debugging profile manager Web interface is available on your CICS system.

For information related to the setup of the web interface, see Using the application debugging profile manager Web interface.

After you have verified that the web interface is available, ensure that the names of the test application's DBRM datasets are specified in the DBRM Locations tab under the z/OS section of the physical database definition. The name of your DBRM dataset can be determined by examining the JCL that is used to compile your test programs. Specify the URL of the profile manager web interface under the CADP URLs tab and the criteria for selecting transactions or programs to be tested under the Recording/Stubbing Filters tab of the physical database definition. These values and the host name of the system where the CLIP front end is running will be used to automatically build the CADP profile. For more information, see Configuring the physical database resource.
Note: The host name of your CLIP front-end machine must be resolvable from your z/OS system. For example, if the CLIP front-end is running on a computer named myhost.mydomain, the automatically generated CADP profile will direct the CLIP back-end to connect to myhost.mydomain. If the computer running the CLIP back-end cannot resolve myhost.mydomain into an IP address, it will not be able to connect to the CLIP front-end.

Creating a CADP profile manually

In certain circumstances, you may want to manually create a CADP profile rather than having Rational Integration Tester create it automatically. For example, you may want to enable tracing using the AQE_DBG_TRACE variable. To manually create a CADP profile, do these steps:

  1. Determine the name of the host where the CLIP agent front-end is running and the port number that it uses. Both of these can be obtained from the messages displayed on the console when the CLIP agent front-end is started. The following is an example: 
    CRRDG7028I The Compiled Language Interception Processor Agent Daemon has started listening on port 8003
CRRDG7030I The Compiled Language Interception Processor Agent Daemon address is myhost

    For more information about setting up the CLIP agent front-end and specifying the port number to be used, see Installing the CLIP agent front-end and CLIP command line options.

  2. Log in to the CICS region where the application will run.
  3. Clear the screen, enter CADP on the command line and press Enter. The profile list is displayed.
  4. Press F5 to create a new profile for a compiled program.
  5. In the Create Compiled Debugging Profile field, enter a unique name for your profile.
  6. Specify the CICS Resource conditions that must be met for a debugging session to start. By default, the current CICS region, your user ID, the terminal ID, and the terminal network ID are pre-populated. You can modify these and specify the following values:
    • Transaction ID
    • Program name (the name known to CICS. For example, the load module name, the initial program in a transaction, etc.)
    • The compile unit (the name known to the compiler; for example, the COBOL PROGRAM-ID)
    Populating all of the fields with each resource spelled out in full, ensures that you debug a specific transaction. However, you can optionally also specify more generic conditions. In the following example, the only condition specified is the program name and the debugger will start anytime a program starting with “X” runs.

    Under the conditions specified in this example, you might inadvertently trap someone else’s transaction, because the user ID has not been specified. This combination of resources will also start a debugging session regardless of the terminal or transaction. Before refinement, use of the wildcard * is recommended for the fields Compile Unit, Termid, and Netname, because at runtime, unmatched values in those fields will prevent the debug session from starting.

  7. Enter ENVAR('AQE_DBG_DBRM=//USER.DBRMLIB') in the Other Language Environment Options field so that the CLIP back-end can access the DBRMs associated with the program you are testing. For diagnostic purposes, you can also specify a value for the AQE_DBG_TRACE variable. For example, ENVAR('AQE_DBG_DBRM=//IBMUSER.CB12.DBRMLIB','AQE_DBG_TRACE=3').
    Attention: Use caution when using this variable to enable tracing because it will cause large amounts of output to be written to CEEMSG.

  8. Press enter and then F12 to save and create the CICS Application Debugging Profile. The newly created profile will appear in the profile list, but with a status of inactive.
  9. To activate the profile, type A on the command line next to it, and press Enter.
  10. In the Set Compiled Debugging Display Device panel, change the session type to TCP.
  11. In the TCPIP Name or Address field, enter RIT& followed by the hostname or address of the host running the CLIP front end.
  12. Change the port number to the port used by the CLIP agent front-end. See Step 1 for details about how to determine the port number. The following screen shot shows an example:
When you set up the CADP profile, remember the following points:
  • CICS provides the CADP transaction, with which you define a set of filters. If a transaction starts on the region that matches the specified filters, CICS invokes the appropriate debugger or tool on the transaction. The CADP profile must specify the hostname/IP and port number of the listening CLIP agent front-end.
  • Prefix the hostname or IP with RIT& so that the CLIP agent back-end (probe) can co-exist with other debuggers and tools that might be configured on the CICS region. For information about coexistence with other debuggers, see the Supported Environments section of Testing with DB2 on z/OS systems.
  • To specify which transactions, program, compile unit, userid or terminal will trigger the tool, use the filters on the CADP profile. Because you might not know which transaction calls other transactions or programs, using a wildcard on all the fields is a way to ensure that everything on the region is monitored for DB2 events.
    Note: The filters can be narrower, but recording and virtualization will not capture events that do not match the filter. Multiple profiles with different filters can be active at the same time.
  • Specify the AQE_DBG_DBRM environment variable for each profile. This variable must specify the location of the relevant DBRM files for the transactions or programs being recorded or virtualized. The DBRM files are DB2 artifacts that are produced by the user's application build.
  • If the CLIP front-end is connected to more than one instance of Rational Integration Tester, specify the AQE_DBG_RIT_ID environment variable to determine which Rational Integration Tester instance will receive the events.
  • If an application is run that matches the conditions of multiple profiles, the debugger will be launched using the oldest profile and all other profiles will be ignored.
Feedback