®
IBM Software Group
RDz Workbench – Debugging z/OS COBOL Applications
Jon Sayles, IBM Software Group, Rational EcoSystems Team
© 2008 IBM Corporation
IBM Trademarks and Copyrights
 © Copyright IBM Corporation 2007,2008, 2009. All rights reserved.
 The information contained in these materials is provided for informational purposes only, and is
provided AS IS without warranty of any kind, express or implied. IBM shall not be responsible for
any damages arising out of the use of, or otherwise related to, these materials. Nothing
contained in these materials is intended to, nor shall have the effect of, creating any warranties or
representations from IBM or its suppliers or licensors, or altering the terms and conditions of the
applicable license agreement governing the use of IBM software. References in these materials
to IBM products, programs, or services do not imply that they will be available in all countries in
which IBM operates.
 This information is based on current IBM product plans and strategy, which are subject to change
by IBM without notice. Product release dates and/or capabilities referenced in these materials
may change at any time at IBM’s sole discretion based on market opportunities or other factors,
and are not intended to be a commitment to future product or feature availability in any way.
 IBM, the IBM logo, the on-demand business logo, Rational, the Rational logo, and other IBM
Rational products and services are trademarks or registered trademarks of the International
Business Machines Corporation, in the United States, other countries or both. Other company,
product, or service names may be trademarks or service marks of others.
2
Course Contributing Authors
 Thanks to the following individuals, for assisting
with this course:
 Russ Courtney/IBM
 Reginaldo Barosa/IBM
 David Bean/IBM-Rational
3
Course Overview
 Audience
 This course is designed for application developers who have learned or
programmed in COBOL, and who need to do z/OS Traditional
Development and Maintenance as well as build leading-edge
applications using COBOL and Rational Developer for System z.
 Prerequisites
 This course assumes that the student has a basic understanding and
knowledge of software computing technologies, and general data
processing terms, concepts and vocabulary, as well as a working
knowledge of COBOL and z/OS.
 Knowledge of SQL (Structured Query Language) is assumed for
database access is assumed as well.
 Basic PC and mouse-driven development skills, terms and concepts are
also assumed.
4
Course Topics
 Course Name: Rational Developer for System z Foundation Training
 Course Description: Learn how to use Rational Developer for System z to do z/OS traditional
development, maintenance, support and for Enterprise Modernization of z/OS applications
 Pre-requisites: Some experience developing COBOL applications using z/OS is expected. A working
knowledge of SQL is also recommended.
 Course Length: ~5days – or if done in self-paced mode, at your own pace
 Topics (Agenda)









Getting Started - installing and configuring RDz - and the course materials, and using Eclipse
The RDz Workbench
– Code analysis tools
– Editing
– Compiling programs
– Debugging local COBOL programs
The Data Perspective:
– Working with relational data sources
– Modifying test data
– Editing and testing SQL statements
Working with remote system resources:
– Connecting to a mainframe
– Data management
– Accessing and editing files
z/OS Application Development
– Creating MVS Subprojects
– Creating and customizing project properties
Debugging z/OS Applications
– Debugging Batch Applications
– Setting Debug Tool for Online Applications
Working with File Manager
– Creating test data
– Editing complex file-types
Working with mainframe ABENDs using Fault Analyzer
– Creating Fault History views
– Analyzing and solving mainframe ABENDs
Creating and modifying BMS Maps using the BMS Map Editor
5
UNIT
The RDz Workbench
Topics:
 Debugging z/OS COBOL Batch Applications
 Debugging z/OS COBOL Online Applications
 Appendix
6
Topic Considerations
 Note: In this topic you will learn how to debug a COBOL program running
on a z/OS mainframe. The screen captures all describe connecting to a public
z/OS machine that IBM makes available – during classes.
If you are taking this course through standard IBM services delivery you should
be able to use the properties (I/P address, port#s, etc.), logon IDs and passwords
that your instructor provides you with.
But you may also be taking this course standalone – and in that case, you will
need to speak to your company's Systems Programming staff to learn how to
connect and logon.
It goes without saying that the actual file names in the screen captures of
mainframe libraries and datasets will vary. So you should focus on the process
and steps and "how to" – and don't be perplexed at differences in screen
captures.
You also may be using your company's own Source Control Management system
– to do things like builds, compiles, etc. In that case much of the remote
functionality in RDz will be customized and tailored to your company's unique and
idiosyncratic procedures and protocols.
7
Workshop Considerations
 Note: Unfortunately, due to the fact that you will need an I/P address that resolves to your
workstation in order to use IBM Debug Tool, there is no way that you can use the Sandbox for workshops that
reflect the content in this unit.
Your options for additional learning include:
Return to the RDz Workbench Introduction unit – and carefully go over all the Debug option materials in
the slides. Note that the workbench interface/perspective and > 95% of the functionality of Remote Debug is
also contained in Local Debug.
1.
2.
Download and watch the following Camtasias on RDz Debugging:
http://websphere.dfw.ibm.com/atdemo/atdemo_rdz_zosad_recorded.html
RDz and Debugging 
RDz and Remote Development
(including Debugging) 
8
Topic Objectives
After completing this unit, you should be able to:
Using the Problem Determination Tools, Debug Option and
RDz:
 Debug a mainframe batch job
 Compare and contrast mainframe debugging with local debugging
(see unit titled: RDz Workbench – Introduction)
 Discuss the Debug Option setup and configuration requirements
9
Debugging Overview
Face facts: No one gets
it right the first time.
 Not at the level of
production business
logic
That's why IBM invented source-level application
debuggers, so that you can:
 View program execution, line-by-line
 Verify the value of a variable – during program execution
 Stop and start program execution, and analyze results at
the speed that our procedural understanding of the
application's execution flow can handle
10
Enter "Source-Level Debuggers"
 In a previous unit (RDz Workbench – Introduction) you
learned about the RDz debugging capabilities:
Debug Perspective
Debug Views:
 Variables
 Monitors
 Breakpoints
Debugging functionality, steps, processes
 But what you did in that unit, applied to debugging
workstation-COBOL (Windows binary) executables
 Now it's time to see how to debug mainframeCOBOL applications
11
Enter Source-Level Debuggers
 Specifically: IBM Debug Tool
Green-screen (TSO-based) or RDz/Workstation-based interface to z/OSbased debugging engines
Debug:
 Online (CICS, or IMS TM)
 Batch
 Multiple languages (COBOL, PL/I, HLASM, Java, etc.)
Seamless debugging of mixed-language/cross-platform applications
Interactive, source-level debugging in RDz with program running on z/OS
Display, monitor and alter program variables
Set standard types of breakpoints
View data in Hex (EBCDIC) or string values
Multiple configurable views
Ability to make adjustments to the program while debugging

Product web-site: http://www-01.ibm.com/software/awdtools/debugtool/
12
RDz Interfacing with Debug Tool
TCP/IP
Your
Application
Debug Tool
Debug Tool
Engine
z/OS
Data
Source
 The RDz remote debugger
 Client software that is installed with RDz on your workstation
 Communicates with the Debug Tool engine on the mainframe
 Note that Debug Tool must be installed on z/OS in order for you to do
the labs in this unit
13
Debug Tool - Application Environments
One debugging engine, with support for many environments:
Batch
3270
or GUI
CICS
3270
or GUI
IMS/TM
3270
or GUI
DB2
stored
procedure
3270
or GUI
UNIX
systems
services
3270
or GUI
Debug Tool
Debug Tool
Debug Tool
Debug Tool
Debug Tool
Batch
Application
CICS
Application
IMS
Application
DB2 Stored
Procedure
Posix
Application
Transaction
Transaction
Batch
region
CICS
region
IMS/TM
region
14
WLM
region
z/OS
Steps for Batch Application Debug Session
 RDz is started on your workstation
1. Ensure that your compile proc has the necessary
TEST parameter, and Compile/Link options to
create a debug-able load module
2. Discover workstation TCP/IP parameters:
 TCP/IP Address
 Listener port#
3. Enter TCP/IP address of workstation in run JCL for
Debug Tool DD statement, and Submit the JCL
4. Debug the application
15
1. Compile JCL Requirements for Using Debug Tool
 Use the TEST compiler option to prepare your executable
COBOL program for use with the debugger.
The TEST option is required for remote debugging.
The TEST option produces symbol and statement
information that enables the debugger to perform symbolic
source-level debugging.
 The TEST option is set in the PROCs distributed with RDz
(see screen capture)

If you are not using the
IBM/RDz PROCs for building
your applications, be sure to
override the compiler option
and add TEST - as shown 
16
2. Discover TCP/IP address and RDz Port
 Open the Debug Perspective
Click the small downward pointing triangle
next to the debug-daemon icon
Note the Port#
Select: Get Workstation IP…
Copy the IP address
Note: Your RDz Port# will most likely be set
once, and will change infrequently.
However, depending on your installation's
setup, your workstation's TCP/IP address
could change - often
17
See Notes
3. Paste in the TCP/IP Address and Submit the JCL
 Configure your application to start Debug Tool by including a
specific DD card in the run JCL – that includes your
workstation's current Port# and TCP/IP address
 This is an example of JCL to run a batch job
 The CEEOPTS DD statement is the easiest way to start
the Debug Tool for batch applications
 Code as shown
//CEEOPTS DD *
TEST(,,,TCPIP&5.76.97.236%8001:)
18
Save your edits,
and submit the JCL
Debug Tool - Prompts

Debug Tool will
interface with
RDz and throw
the Confirm
Perspective
Switch prompt
 Click Yes
Additionally, if
your mainframe
source code is out
sync with the
Load Module
you'll get an
informational
prompt.
This typically means
you need to check
your compile
listings for syntax
errors that caused
the link edit step
not to execute
because of
condition codes
19
4. Debug Tool Connects to RDz


Debug Perspective is
launched in RDz
Same debugging features
as Local COBOL Debug
(from previous course
unit)

Your source is copied
down from z/OS to your
RDz workstation

Execution is on z/OS
20
The Debug Perspective and Views – Review
Variables
Breakpoints
Monitor
Views
The Debug Icons
Your code
Program
Outline
View
Notes:
- Same views, options and debugging features as Local COBOL Debugger
- However, application execution happening on z/OS
- Only interactive debug: view/browse activity occurs on the Workstation
21
Action Icons – Review
Resume: Run
the program to
the next
breakpoint or
to the end
Step Return:
run until return
from
subprogram
Terminate:
End the
program
Step: run one
statement
Disconnect:
from the
debug engine
Animated Step
Continuous source-level
debugging without user
interaction
22
Step Over:
run one
statement,
but step over
a CALL
Run Menu


Shows same + additional
debugging functionality as
icons on toolbar
 However, not all Run menu
functionality enabled for
COBOL/PL1
Also shows hot-keys


Your PC's function keys
Context-sensitive:

Options are grayed in current
debug session if not
applicable
23
Statement Breakpoints – Review
 A statement breakpoint will stop the program when it
reaches a statement:
 It stops before the statement runs
 A breakpoint can optionally be made conditional
 A simple condition may be specified such as:
 VariableX > 999
…or…

VariableY = 'Abc'
 A breakpoint can be based on a frequency:
 Stop the Nth time a statement runs
24
Set a Statement Breakpoint – Review
dbl
click
Set a statement breakpoint by
double-clicking in the gray area
next to a statement
25
Set/Edit Conditional Statement Breakpoints
Select the Breakpoint.
Right-click and select: Edit Breakpoint…
A breakpoint can trigger the
Nth time the statement runs…
Can set to different statement/line
Or click Next > to specify
conditional breakpoint logic
… and breakpoints
can be conditional.
26
Watch Monitor Breakpoints
 Can have breakpoints occur conditionally,
when:
 The value in a field changes
 Some portion (# of bytes) of a field
changes
 A simple condition tests true for the
value in the field
 Steps:
 Select a variable
 Right-click, and select: Add Watch
Breakpoint…
 Select Number of bytes to watch –
or add a simple condition

Specify Auto to test for all bytes
27
Run to a Statement Breakpoint
Resume
click
A breakpoint icon is shown…
and the breakpoint is also
shown in the Breakpoints view.
28
Breakpoint Options (from the Breakpoints View)
The program ran to the
breakpoint
You can remove the
breakpoint by double
clicking again here…
… or by deleting it from
the Breakpoints view
29
Variables View During Remote Debug – Additional Options
Many options for
working with variables
 Add to Monitor – for permanent viewing
 Monitor internal memory values
 Show value in hex – (EBCDIC internal) or string
value represntation
 Copy variable and value to Notepad
 Find specific variable in DATA DIVISION
 Show specific variables in the view
With large COBOL
programs can "filter" and
display only certain
categories of variables
30
Variables View – EBCDIC (Hex) Data Representation
Value – in string or numeric display
(depends on datatype) display
Value – in EBCDIC internal display 
very useful for debugging data
exceptions
31
Monitors View – Options
Monitored variable value – in EBCDIC
internal display  very useful for
debugging data exceptions
Add datatype prefix to variable data-name
displayed – still retail variable value)
32
Monitors – Detach the Eclipse View
Very useful Best Practice…
Can view any # of variable values
during debug, animated debug or
Resume to breakpoints
33
Monitor Memory
 Monitor Memory
 The memory content can be shown (or “rendered”) in several different formats:
 Raw HEX, EDBCDIC or ASCII
 Tree structure using customized XML mappings.
34
Debug Option – Jump to / Run To

Jump to Location - skip over sections of code to avoid executing certain
statements or move to a position where certain statements can be executed again.
Useful:


To avoid called programs or I/OS to a not available dataset

Or to iteratively execute some statements of interest
Run to Location - executes all statements between the current location and the
run-to location.
35
Outline View – Code Sync Options
While debugging through
PROCEDURE DIVISION Outline view
synchronizes with code in paragraphs
and sections
But if you scroll in the code while stepping, the Outline View syncs with
your browsing activity
36
Outline View – Other Icon-Function Options
For large programs, several
additional Outline view
features are available as
toggled icons:
• Click to Toggle function on
• Click again to Toggle function off

37
Sort all variables
Handling program abends
 Debug Tool can receive control back from the system after an
abend occurs
 The program will be stopped at the abending statement
 You can:
 Allow the application to abend and terminate
 Capture abend info with a product such as Fault Analyzer
 Terminate the application and prevent further processing
 Or continue running the program
 Usage note:
 The LE TRAP(ON) option must be active
38
Terminating the application
 There are several options for terminating your application:
 Remain in the debugger, and RESUME until the program
runs to completion
 The program will terminate normally or with an abend
 The return code is controlled by the program
 Disconnect the debugger, and allow the program to run
to completion
 The program will terminate normally or with an abend
 The return code is controlled by the program
39
Termination action buttons
You can immediately terminate the
application using action buttons
Disconnect: Disconnect
Debug Tool from the
application. The program
continues to run from the
current location without the
debugger. And subsequent
batch job steps can finish as
well.
Terminate: Immediate
termination of the application.
No more program statements
run. RC=0 is returned to the
environment.
40
Force an immediate termination with abend
1
Right click in the
Debug view
right
click
3
Options
2
click
click
41
Terminate
and abend
Restart Your Debugging Session
For batch debugging
If your submitted JCL is
still in the code
(Content) area
 No need to return to the z/OS
Projects perspective
Right-click
 Select: Submit
Note that F11 (or Debug from
the Run menu) does NOT work
– as it did with Local COBOL
debugging
42
Summary
Having completed this unit, you should now be
able to:
 Describe where the debug engines are located
 Show how to set the workbench preferences for running
and debugging
 Show how to invoke the debugger for local programs
 Describe the views of the Debug perspective
 Demonstrate how to set breakpoints in COBOL code
 Explain how to set up the COBOL compile options for
remote debugging
 Show how to debug a remote batch COBOL program
43
UNIT
The RDz Workbench
Topics:
 Debugging z/OS COBOL Batch Applications
 Debugging z/OS COBOL Online Applications
 Appendix
44
Topic Objectives
After completing this unit, you should be able to:
Using the Problem Determination Tools, Debug Option and
RDz:
 Debug a mainframe online transaction
Describe the online transaction features for configuring your
3270 sessions with Debug Option
Debug a CICS 3270 Application
45
Online Debugging Overview
 Guess what?
No one gets
it right the first time
coding online
programs either 
 Lucky for you:
 Debug tool handles:
 CICS 3270 online transactions
 IMS TM online transactions
 Without any different debugging techniques
 The only difference from batch is the debug setup procedure for the online
environment
46
Steps for Online (CICS) Application Debug Session
 RDz is started on your workstation
1.
Ensure that your compile proc has the necessary TEST parameter, and
Compile/Link to create load module – and that your CICS application is setup
for Debug Option testing
2.
Discover workstation TCP/IP parameters:

TCP/IP Address

Listener port#
3.
Access and login to your CICS region
4.
Execute the DTCN transaction and specify:

Terminal ID

Programs – to put under Debug control

User-ID

TCP/IP parameters:



5.
TCP/IP Address
Port#
Save the DTCN transaction specification
Debug your CICS application
47
1. Compile JCL Requirements for Using Debug Tool - Review
 Use the TEST compiler option to prepare your executable
COBOL program for use with the debugger.
The TEST option is required for remote debugging.
The TEST option produces symbol and statement
information that enables the debugger to perform symbolic
source-level debugging.
 The TEST option is set in the PROCs distributed with RDz
(see screen capture)

If you are not using the
IBM/RDz PROCs for building
your applications, be sure to
override the compiler option
and add TEST - as shown 
48
2. Discover TCP/IP address and RDz Port - Review
 Open the Debug Perspective
Click the small downward pointing triangle
next to the debug-daemon icon
Note the Port#
Select: Get Workstation IP…
Copy the IP address
Either paste the IP address into Notepad, or write it down
Note: Your RDz Port# will most likely be set
once, and will change infrequently.
However, depending on your installation's
setup, your workstation's TCP/IP address
could change - often
49
3. Login to your CICS Region
From Remote Systems Explorer:

Right-click

Select: Host Connection Emulator

Select your CICS application

Enter your Userid and Password and sign in
50
3. Setup the Debug Option Parameters using DTCN – 1 of 2
From CICS (after signing in):

Clear the screen

Enter: DTCN – and press  Enter
From the DTCN screen

Press F10 – this will fill in the Terminal Id for your workstation
Note that you can also
*
type an asterisk:
…as the Terminal Id
51
3. Setup the Debug Option Parameters using DTCN – 2 of 2
DTCN transaction data entry screen

Enter the Tran-code

Transaction ID

Enter up to eight
specific Program Id(s)
you wish to debug
through …or…

Enter wildcard text
for the Program Id(s)

Ex. CD*

Enter your User-ID

Session Type: TCP

Port Number:
from your Debugger look-up

Display ID:
Your TCP/IP address,
your Debugger look-up (note that you can not paste into this 3270, screen)

Press F4 to save your debug profile

Press F3 to clear the screen
52
from
4. Start Debugging
From the CICS region

Enter the Tran-code

Press  Enter

Click: Yes at the
Confirm Perspective Switch
53
4. Start Debugging
Debug as previously learned in the batch/remote and Local debug units.
54
What Happens for Calls and Screen-IO? – 1 of 2
You will be
prompted,
and
presented
with debugrun-time
options
55
What Happens for Calls and Screen-IO? – 2 of 2
If your current transaction ends, and a BMS or 3270 screen is sent:

You will be notified (prompted) by the debug engine

If a screen is sent, the 3270 will display in the content area
56
What About PF-Keys and Other Data Entry?
 You can resize the screen portion of the debugger
 And use the
PF-Key emulation
options in the
Host Connection
57
Same Debug Option Functionality!
All of the
debugging
features and
functions are
available
when
debugging
online CICS
or IMS TM
applications.
58
Topic Objectives
After having completed this unit, you now should be
able to:
Using the Problem Determination Tools, Debug Option and
RDz:
 Debug a mainframe online transaction
Describe the online transaction features for configuring your
3270 sessions with Debug Option
Debug a CICS 3270 Application
59
®
IBM Software Group
Appendices
 Local COBOL Workshop that does File I/O
 Additional (back-up) slides
© 2008 IBM Corporation
Steps in Debugging Local Workstation Projects
If you're looking for more extended code to practice your new RDz edit/debug skills with – the workshop slides in
this appendix will allow you to import and setup a small 5-program system for debugging, and use the more
sophisticated Debugging techniques, suitable for production-level work: Entry breakpoints, Watch monitors,
You will read and write files, do an inline sort, etc.
Recall from a previous course unit, that in order to Debug you will need the following:
1. A project – that compiles to an EXE (executable)
2. One or more COBOL programs to debug in the project
3. Data files
4. A Debug Configuration
We will provide you with explicit steps to accomplish that.
Debug
Configuration
Sequential
Input/Output
Files
RDz Debug
Perspective
COBOL.exe +
Called
modules
Output
Reports
The module and data flow is shown on the
next slide
61
Module and Data Flow Diagram (From Rational Asset Analyzer)
 This is the batch
job diagram, that
was produced by
Rational Asset
Analyzer from
the original
program and JCL
code
HOSPEDIT
QSAM Data Files
HOSPSRCH
HOSPDRVR
 In order to make
this report viewable on one slide
we have
annotated the
diagram
HOSPSORT
HOSPCALC
62
File Descriptions
Debugging Local Workstation Projects – 1 of 5
1. Download the zip file that's on: www.jsayles.com/ibm/cap - named: hospproject.zip
2. Import this project, and configure it for debug - as follows:
 From the File menu, select Import
 Select: Other > Project Interchange ( click Next > ) 
 From zip file: Browse to the downloaded zip file
- and select it. Check the box, and click Finish
63
Debugging Local Workstation Projects – 2 of 5
 Modify the FILE-CONTROL entries.
 In four of these programs there are ASSIGN statements that point to my Project's
Workspace. You will need to modify the bold text shown here, to point to your own project
Workspace... Drive:\folder\
64
Debugging Local Workstation Projects – 3 of 5
 Make sure that the Properties are configured for your Workspace
 Example - SYSLIB must point to your workspace (not mine) for COPY statements (and
there are COPY statements in all of the programs):
65
Debugging Local Workstation Projects – 4 of 5
 Delete the BuildOutput folder, then Rebuild the
HospProject Project
 By deleting the folder, and watching the Rebuild create it,
you ensure the proper executables
 G. Create a new Debug Configuration
 Again - point to the correct Workspace - and make HospDrvr.exe
the Program entry point
66
Debugging Local Workstation Projects – 5 of 5
 Step through the code – same skills/techniques as all the other Debug examples:
67
®
IBM Software Group
Appendices
 Additional (back-up) slides
© 2008 IBM Corporation
Breakpoints - Review
 Temporary markers you place in your program that tell the debugger to
suspend executing your program at a given point.
 Setting a breakpoint in a statement causes the execution to stop
 Source can then be stepped through and variables inspected
 Breakpoints are set until they are explicitly removed
 Breakpoints can be Removed, temporarily Disabled, Exported, Imported, etc.
69
Debug View: Stepping Through Code
Debug view
 Once execution has been
suspended at a breakpoint, the
source for the current stack frame
can be executed line-by-line using
the debugger’s navigation buttons

"Run" to next breakpoint

"Terminate" execution

“Animated Step Into” - the
debugger issues a step into
action repeatedly.
You can control the delay between each
step by selecting the Animated Step Into
icon down-arrow.

"Step into" next statement
(use for called programs)

"Step over" next statement
ƒ
“Step filters” - to filter out types that you do
not wish to see and or step through
while debugging.
ƒ
(use for local debugging when assembler
code is showing)
70
Run contained statements but don't
stop on them
"Run to return" to next higher
level statement in program
structure (return from a called
program)
Variables View
 Variables view
 View current record contents
 Update record/structure item contents

Double click on item name or right-click and select Change Variable Value
 Mouse (hover-over variable) also shows the contents
71
Monitor Variable Contents
 Monitors view
 View the contents of a Variable or Expression
 Variable/Expressions that you have selected and want to monitor at all times.
72