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 IBMs 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.

Course Contributing Authors

Thanks to the following individuals, for assisting with this course:
Russ Courtney/IBM Reginaldo Barosa/IBM David Bean/IBM-Rational

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.

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

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

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

Debug Tool Debug Tool Engine

Your Application

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 CICS IMS/TM
DB2 stored procedure
3270 or GUI

UNIX systems services

3270 or GUI

3270 or GUI

3270 or GUI

3270 or GUI

Debug Tool Batch Application Batch region

Debug Tool CICS Application

Transaction

Debug Tool IMS Application

Transaction

Debug Tool DB2 Stored Procedure WLM region

Debug Tool Posix Application

CICS region

IMS/TM region

z/OS

14

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 debugdaemon 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

The Debug Icons Variables Breakpoints Monitor Views

Your code

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

Program Outline View

Action Icons Review

Resume: Run the program to the next breakpoint or to the end

Step Return: run until return from subprogram Step Over: run one statement, but step over a CALL

Terminate: End the program

Disconnect: from the debug engine

Step: run one statement

Animated Step Continuous source-level debugging without user interaction

22

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

Sort all variables

37

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

Terminate: Immediate termination of the application. No more program statements run. RC=0 is returned to the environment.

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.

40

Force an immediate termination with abend

1
right click
Right click in the Debug view

Options

3 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.
3. 4.

Discover workstation TCP/IP parameters:

TCP/IP Address Listener port# Access and login to your CICS region Execute the DTCN transaction and specify:
Terminal ID Programs to put under Debug control User-ID

TCP/IP parameters:
TCP/IP Address Port#

Save the DTCN transaction specification

5.

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 Press F10 this will fill in the Terminal Id for your workstation

From the DTCN screen

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, from 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

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

HOSPSRCH

QSAM Data Files

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 debuggers 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

Run contained statements but don't stop on them

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)

"Run to return" to next higher level statement in program structure (return from a called program)

70

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