This article describes how to debug a remote CICS®) compiled language applications by using the IBM Rational® Developer for System z® (RDz) Debugger. Examples of compiled languages include C, C++, COBOL, and PL/I. You can also debug Assembler applications using the RDz debugger. In this article you will learn how to:
- Configure the CICS environment for the Debug Tool
- Configure RDz prior to debugging
- Preparing your CICS application for debugging
- Debug your CICS application
- Troubleshoot debug problems
- Explore the many features of the RDz debugger
The user interface screen captures in this article were taken while using RDz Version 7.5.1 and Debug Tool Version 9.1. CJIS currently RD/z V7.6 and Debug Tool V9.1 (10.1 should be implemented with z/OS V1.10). Throughout this article, references are made to the RDz user assistance. To open the RDz user assistance, select Help from the main menu bar and then select Help Contents. This help contains a series of books at the top level. In some cases, the referenced help locations are nested beneath topics within these books.
Configure the CICS environment for the Debug Tool
Before you can debug a CICS application, your system administrator must complete a series of steps that enable Debug Tool support for debugging under CICS. These steps can vary depending on the version of Debug Tool you are using.
For the description of the steps involved, see the following information:
· Adding support for debugging under CICS chapter of the Debug Tool for z/OS Customization Guide (PDF, 614.2KB) for Debug Tool Version 9.1. Debug Tool for z/OS Customization Guide of other Debug Tool versions can be found in Debug Tool For z/OS Library.
Configure RDz prior to debugging
Start RDz and open the Debug Perspective by selecting Windows > Open Perspective > Debug:
To enable the environment for debugging, the following information must be verified and changed, if needed:
· Daemon port number
The daemon listens on a port for a connection from the debugger user interface. You can hover over the daemon icon in the Debug view to see if the daemon is listening on a port and what the port number is. The default daemon port number is 8001 as shown below:
If the daemon is listening on a port, the daemon icon will be . Otherwise the daemon icon will be . In either case, you can change the port number by clicking the down arrow to the right of the daemon icon and selecting Change Port:
· TCP/IP address of the client computer
You will need the IP address of the computer that is running RDz. To get the IP address, go to the Debug view and click the down arrow to the right of the daemon icon and then select Get Workstation IP:
Record both the daemon port number and the IP address. You will need to record this information in the DTCN panel fields Port Number and Display Id respectively in the Preparing your CICS application for debugging section.
Prepare your CICS application for debugging
To enable your CICS application for debugging by the RDz debugger, complete these steps:
Build your application for debugging
Before you can debug your application, you need to compile the application with the correct set of debug options. These options control the generation and placement of hooks and symbol tables as well as placement of the debug information into the object file or a separate debug file. Here is a list of different languages, each with an example of the compile time debug option:
· COBOL : TEST compiler option
example: PARM(..., TEST(ALL, SEPARATE))
· PL/I : TEST compiler option
example: PARM(..., TEST)
· C : DEBUG or TEST compiler options
example: PARM(DEBUG) or PARM(TEST)
· C++ : DEBUG or TEST compiler option
DEBUG(FORMAT(DWARF),HOOK(ALL),NOSYMBOL) or TEST(HOOK)
· Assembler: For assembler programs, you need to:
- Assemble your program using the Debug Tool Utilities or the High Level Assembler (HLASM)
- Create the EQALANGX file
example: PARM='IAPUT1 (ASM ERROR OFT IDILANGX FAULT' - Link-edit your program
example: LKED EXEC PGM=HEWL,PARM='RMODE=24,AMODE=31,RENT,LIST,LET'
For information about COBOL, PL/I, C, and C++ compiler options, see the Preparing a CICS program chapter of the Debug Tool for z/OS User's Guide (PDF, 1.84MB).
For information about preparing an assembler program, see the Preparing an assembler program chapter of the Debug Tool for z/OS User's Guide (PDF, 1.84MB).
Create a debug profile
To debug your CICS application with the RDz debugger, start the Debug Tool in the Remote Debug mode, which you can do by using a debug profile. There are a number of ways to create a debug profile for the application. This example shows you how to create the debug profile through the DTCN transaction:
· In the z/OS projects perspective, open the Remote Systems view. Expand the New Connection tree. Right-click the z/OS tree item and then select New Connection:
· In the Remote System Connection dialog box, enter the connection details and click Finish (if you do not want to use the default connection information, you need to click Next and update the port number and connection type):
· In the Remote Systems view, you can now see the new host name. Right-click it and select Host Connection Emulator:
Enter the CICS region name as your TSO application ID. Sign on to the CICS transaction server by entering your user ID and password.
· In the host emulator session, enter DTCN. The DTCN panel and fields are described in the following screen capture:
- Terminal Id: This is the CICS terminal identifier that is associated with the transaction you want to debug. This field defaults to the terminal that is currently running DTCN. You can also place the cursor on this field and press F10 to set the Terminal Id.
- User Id: The user ID associated with the transaction you want to debug.
- Session Type: Specify the type of debug session you are about to run. You need to set the session type to TCP.
- Port Number: This is the TCP/IP port number that is used to listen for debug sessions on your workstation. This port number must match the daemon port number that you specified in the Configure RDz prior to debugging section. If the port number is left blank, the default daemon port number (8001) is used.
- Display Id: This is the IP address of the client computer that is running the RDz program. You learned how to gather this information in the Configure RDz prior to debugging section.
- Generated String: This is the run-time debug option that is used for debugging the CICS application. If you do not save your debug profile information, this string represents the default run-time option.
- Repository String: This string represents the run-time debug option of your saved profile. This string is your run-time debug option until the next time the debug profile is changed. If you do not save the debug profile, this string indicates that no string is saved in the repository.
Press F4 to save the settings and then press F3 to exit the DTCN panel. The debug profile is now ready and the CICS application can be debugged.
For more information about creating debug profiles, see the RDz help:
· Creating and storing a DTCN profile in the Preparing a CICS program section.
· Choosing a debug mode section.
Debug your CICS application
Now you are ready to debug! Start the CICS transaction from the host emulator. When the CICS transaction starts, it connects to the RDz debugger and the source of the application is displayed in the Debug Perspective editor:
Here are brief descriptions of some of the views in the Debug Perspective:
Debug view 1.
From this view, you can control the debugging of your program. This view shows where you are in your application. You can perform all the basic debug actions (such as step over, step into, and resume), from this view:
Editor 2.
In the RDz debugger, the editor is language-sensitive. Therefore, certain features such as language coloring, hover text, and automatic indentation vary depending on the language of the compiled unit. If source is not available for your application (or parts of it), or part of the application is not compiled with the debug option, the debugger attempts to display a disassembly view of the source. Debugger actions such as adding a breakpoint, monitoring an expression, running to a location, or jumping to a location can be set from the editor.
Breakpoints view 3.
This view lists all breakpoints you have already set in your application. For example, if you set a statement breakpoint in the editor:
then the Breakpoints view display this:
You can also add, enable, disable, edit, and remove breakpoints from this view.
Variables view 4.
This view allows you to display and change the value of variables. Variables in the view can be filtered. As you debug, if the value of a variable changes, the changed variable is denoted with a delta symbol:
Debug Console view 5.
With this view, you can issue Debug Tool commands. These commands interact with the debugger user interface. The result of the commands is shown in the output area of the view on the left. This area also displays other logging information from the Debug Tool, such as when a breakpoint is hit. In this example, the describe loadmods command has been issued and the results are displayed:
A subset of Debug Tool commands are supported from this view, which you can see by placing the cursor in the Debug Engine Command field and pressing CTRL + SPACE.
Memory view 6.
With this view, you can look at the contents of memory at a specific address. This view can be the address of a variable or a register. This example shows the address of the EIBTRIND variable in Hex and EBCDIC data format:
For information about all of the views in the Debug Perspective, see the Compiled Language Debugger section in the Developing book of the RDz help.
For the list of supported Debug Tool commands in the Debug Console view, see the Appendix B: Debug Tool commands supported in remote debug mode section in the Debug Tool for z/OS User's Guide (PDF, 1.84MB). This list can vary depending on the version of Debug Tool you are using.
Troubleshoot debug problems
Here is the list of some of the problems you can encounter while attempting to debug your CICS application using the RDz debugger:
You have logged on to the host session but you cannot run DTCN or the CICS transaction you want to debug: 1.
· The Debug Tool has not been started correctly under CICS. Verify that your system administrator has completed all required steps as specified in the Configure the CICS environment for Debug Tool section.
You can run the CICS transaction but the RDz debug session does 2. not start and the CICS transaction ends with the following error:
The following problems can cause this condition:
· The Debug Tool has not been set up correctly to work under CICS. Verify that your system administrator has completed all required steps as specified in the Configure the CICS environment for Debug Tool section.
· You have not set the debug profile correctly to interact with the RDz debugger. If you have used DTCN to set the debug profile, verify that the Session Type, Port Number, and Display Id fields are set correctly as specified in the Preparing your CICS application for debugging section.
· The debug daemon port number is incorrect. Verify that the Port Number you have set in the debug profile is the same as the one you have enabled in the RDz debugger as explained in the Preparing your CICS application for debugging section.
· The debug daemon is not listening on the desired port. Verify that the debug daemon is enabled and is listening on the desired port number.
You can debug the CICS application but the source of the application displayed in the editor is in disassembly: 3.
· You have compiled the application without the debug option. Verify that the debug option was specified when building the application.
Explore the many features of the RDz debugger
Now that you have set up your RDz and CICS environments for debugging, you can experiment with the many debug features that are available for helping you find problems in your code. You are encouraged to explore the views in the Debug Perspective and to see how the information about your application is represented.
\\omninet-file-01\home$\krevans2\Documents\Manuals\CICS\Debug_CICS_Apps_Using_RDz.doc Page 1 of 11