This article describes how to debug a remote CICS®) compiled... using the IBM Rational® Developer for System z® (RDz) Debugger....

This article describes how to debug a remote CICS®) compiled... using the IBM Rational® Developer for System z® (RDz) Debugger....

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:
1.
2.
3.
4.
5.
6.
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:
D:\187945110.doc
Page 1 of 11
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:
D:\187945110.doc
Page 2 of 11
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:
1. Assemble your program using the Debug Tool Utilities or the High Level
Assembler (HLASM)
2. Create the EQALANGX file
example: PARM='IAPUT1 (ASM ERROR OFT IDILANGX FAULT'
3. 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).
D:\187945110.doc
Page 3 of 11
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:
D:\187945110.doc
Page 4 of 11
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:
1. 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.
2. User Id: The user ID associated with the transaction you want to debug.
3. Session Type: Specify the type of debug session you are about to run. You need
to set the session type to TCP.
4. 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.
D:\187945110.doc
Page 5 of 11
5. 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.
6. 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.
7. 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:
D:\187945110.doc
Page 6 of 11
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
D:\187945110.doc
Page 7 of 11
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:
D:\187945110.doc
Page 8 of 11
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.
D:\187945110.doc
Page 9 of 11
You can run the CICS transaction but the RDz debug session does
CICS transaction ends with the following error:
2. not start and the
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.
D:\187945110.doc
Page 10 of 11
D:\187945110.doc
Page 11 of 11