Debug Tool GUI v11 Basic Mentor Workshop-00

®

IBM Software Group

© 2009 IBM CorporationJanuary 5, 2011© 2010 IBM Corporation

IBM Debug Tool GUI for z/OS

Program number 5655-V50

Basic Mentor Workshop

Presenter

Presentation Notes

This is the tutorial for IBM Debug Tool for z/OS, one of the IBM zSeries problem determination tools.

IBM Debug Tool for z/OS V10 Basic Mentor Workshop2 © 2010 IBM CorporationW02

IBM trademarks

The following terms are trademarks of International Business Machines Corporation in the United States, other countries, or both:

AD/CycleCICSCICSDB2DFSORTIBMIMSIMS/ESALanguage EnvironmentMVS

RACFRedbooksS/390System/390VisualAgeVS COBOL IIVTAMWebSpherez/OSzSeries

Presenter

Presentation Notes

This is the tutorial for IBM Debug Tool for z/OS, one of the IBM zSeries problem determination tools.


Introduction 3

Starting the debugger for batch LE programs 15

Use a graphical user interface, and1. Debug in batch using an LE TEST option in JCL 182. Debug in batch using the 'User exit data set' facility in TSO 333. Debug in batch using the ‘User exit data set’ facility with the DTSP

plug-in 52

Using Debug Tool's graphical user interfaceDebug perspective views and navigation 64

Debug Tool training sections Page 1 of 3

Presenter

Presentation Notes

Take these tutorials to learn how to use Debug Tool to work with programs running on z/OS systems. Debug Tool is designed to address the needs of application developers working with complex programs and environments. Take a look at how the course is structured. It is broken down into sections. If you have not already used Debug Tool, take each section in order. But if you have already been using it and want to learn more about a particular topic, you can go directly to that section. This is the introduction, and it will describe how you can use Debug Tool and how to you can get the manuals from the IBM website. The next section, “Preparing programs for use with the debugger” provides an overview of how to compile programs so you can debug them, and shows where you can get detailed information about using the various compilers and assembler.


Using Debug Tool's graphical user interface (continued)Using the debugger

Stepping through statements and running the program 86Program statement breakpoints 100Monitoring variables 114Making breakpoints conditional 158Watch breakpoints 163Program entry and exit breakpoints 169Ending the debugging session 179

Loading program debug files 184Loading sysdebug, listings, dwarf, and source files 188Loading LANGX files 195

Debugging CICS Applications 202Creating and editing a DTCN profile using the GUI plug-in 205


Presenter

Presentation Notes

The next set of sections describe how to use the graphical user interface, showing buttons, commands, and features that you will use to debug programs.


Interface with Debug Tool using a graphical user interface

Remote graphical interfaces are available in Rational Developer for System z and CICS Explorer

It is software that can be installed on your workstationThe application running on the mainframe is controlled by the same debugging engine that is used by the 3270 interfaceDebug Tool displays on your workstation

z/OS

Debug ToolTCP/IP

ApplicationApplicationDebug ToolDebug Tool

Presenter

Presentation Notes

There are also remote graphical user interfaces for Debug Tool. The same debugging engine is used to control the application running on the mainframe, and it communicates with software installed on your workstation. You can install Rational Developer for System Z to provide a front end to Debug Tool. The GUI is also available as a plug-in to CICS explorer. You may prefer to use one of these interfaces instead of a 3270 terminal.


Download CICS Explorer and the plug-ins from the IBM web site

Download CICS Explorer at www.ibm.com/software/htp/cics/explorer

Then download the PD Tools plug-ins at www.ibm.com/software/awdtools/deployment/pdtplugin

Presenter

Presentation Notes

CICS Explorer can be downloaded at no charge from the IBM web site. Go to www.ibm.com/software/htp/cics/explorer, click the download button, and follow the instructions to install it. Then download and install the IBM PD Tools plug-ins, including the Debug Tool plug-in, at www.ibm.com/software/awdtools/deployment/pdtplugins.

http://www.ibm.com/software/htp/cics/explorer


Definition of terms for the Debug Tool GUI

WorkbenchThe desktop environment

PerspectiveA set of functions and capabilitiesThe Debug Tool GUI is a perspective

ViewA window within a perspective providing a specific capability

Presenter

Presentation Notes

Here are a few eclipse terms you will be hearing in this tutorial. First, the workbench is what you see when you start the eclipse platform. It consists of perspectives. A perspective provides a set of functions and capabilities. The debugging plug-in is an example of a perspective. It contains one or more views. A view is a window in a perspective that provides a particular capability, such as an editor or status window.


What features are provided by the interactive debugger?

Use the debugger to:

Determine why a program is producing incorrect results

Locate an abending statement

See program statements, and step through statements one at a time

Set breakpoints at statements, programs, and conditions

Run until a breakpoint is reached

View and change the values of variables and storage

And much more

Presenter

Presentation Notes

You can use the debugger to determine why a program is producing incorrect results, or to run a program that abends and have it stop automatically on the abending statement. As you are debugging, you can see program statements, and step through statements one at a time. You can set breakpoints at statements, at programs, and based on conditions, and then run the program until it reaches a breakpoint. You can view and change the values of variables in storage, trace the statement path of a program, and much more.


What kinds of applications can be debugged?

One debugging engine, with support for many environments

z/OS

3270 or GUI

3270or GUI

Debug Tool

BatchApplication

Batch region

Debug Tool

Transaction

CICSApplication

CICS region

Debug Tool

Transaction

IMSApplication

IMS/TM region

Debug Tool

DB2 Stored Procedure

WLM region

Batch

Debug Tool

PosixApplication

3270or GUI

3270or GUI

3270or GUI

CICS IMS/TMDB2

stored procedure

UNIX systems services

Presenter

Presentation Notes

Debug tool provides a single debugging engine that supports many different environments. You can use the same debugger for your batch, CICS, and online IMS applications. It is the same debugging engine when you work with DB2 stored procedures and programs running with UNIX systems services on z/OS. As a result, there is only a single debugger to learn. You do not need different debuggers in different application environments.


Debug batch LE applications

Debug batch programs while they run in batch jobsIncluding DB2 and IMS batch

This workshop module describes two simple methods to trigger thedebugger when an LE program runs in batch

Code an LE 'TEST' option in the run-time JCL, orUse the Debug Tool 'User exit data set' facility

The advanced training module describes how to trigger the debugger for non-LE batch programs

Debug Tool

BatchApplication

z/OS

Batch region C. When the batch

job step runs, the debugger starts because of the trigger

A. Set a trigger, thenB. Submit the batch job

D. The debugger displays on a Debug Tool terminal or GUI

Presenter

Presentation Notes

You can use Debug Tool to work with batch programs, including programs that access DB2 and IMS databases. To start the debugger for a batch application, you set a program trap so Debug Tool will start automatically when the program runs. There are several ways to set a trap. For example, if the system is set up for it, you can specify the name of the batch program on a special Debug Tool panel in TSO. Then just submit the job, and Debug Tool starts automatically. Another way to set a trap is to code a special test option in your JCL, and then when you run the job, the debugger starts. Remember that the debugger can be displayed either on a 3270 terminal or on GUI debugging software on your workstation. When you set your debugging trap, you specify which interface you want to use. This is the first, and generally best, method available to debug batch applications. Run them in their native environment, as a batch job. However, there is another way to debug batch applications.


Debug CICS applications

Use the Debug Tool DTCN or CADP transaction to set a triggerA plug-in is available for DTCN profiles Define the trigger attributes that identify your application using a combination of: program name, transaction ID, terminal ID, user ID, and othersSpecify where the debugger will be displayed

Single terminal mode: Debug Tool and the application share one terminalDual terminal mode: Debug Tool displays on a different CICS terminal (that you specify) than the applicationGUI: Debug Tool displays on GUI debugging software on your workstation

Debug Tool

CICStransaction

z/OS

CICS region

C. When the program runs, the debugger starts because of the trigger

A. Use DTCN or CADP to set a triggerB. Run the application

D. The debugger displays on a CICS terminal or GUI

CICS

Presenter

Presentation Notes

Use the same debugging engine to work with your CICS applications. To start the debugger for a CICS program, you will use a special Debug Tool transaction. Either DTCN or CADP. The Debug Tool transaction displays a screen where you specify information about the application that you want to debug. You can specify information such as the program name, the transaction ID, the CICS terminal ID, and the user ID. Then you save your debugging profile, and the trap is set. Then, just run your application normally in CICS. When it runs, Debug Tool is displayed on your CICS terminal or a remote GUI debugger. It is typical to debug CICS applications in something called single terminal mode. That means that Debug Tool is displayed on the same terminal where your transaction is running. The debugger and your application share the terminal. However, you can also in debug in dual terminal mode. That means your application is running on a CICS terminal, but the debugger is displayed on a different CICS terminal or on a remote GUI debugger. One of the benefits of dual terminal debugging is the ability for one person to run a CICS transaction, and another person to debug it. Also be aware that you can debug background CICS transactions, that is transactions that are not attached to a CICS terminal. For example, transactions that are initiated from web-based remote systems may run as background transactions.


Debug IMS/TM transaction applications

Set a program trap by specifying the program name on a Debug Tool panel in TSO or the DTSP plug-in

Dual Terminal mode: Run the application as it normally runs in an online IMS region. Debug Tool is displayed on a Debug Tool terminalor a GUI.

IMS Online Applications (IMS/TM)

Debug Tool IMSApplicationTransaction

z/OS

IMS/TM message processing region

Debug Tool

IMS

CICS

XXXX XXXXXXXXXXXXXXXXXXXXXXXX XXXXXXXX

---- ------------------------ --------

11 22222 333

111 222222222222 33333

11 22222222 333333

3270 or remote

GUI debugger

Presenter

Presentation Notes

And use the same debugging engine to work with your IMS transaction manager transactions. To start the debugger for an online IMS program, use a special Debug Tool panel in TSO to specify the program name. Then, you can run your transaction normally in a regular IMS message processing region. When your program runs, Debug Tool is displayed on a 3270 terminal or a remote GUI debugger. If you have IBM Batch Terminal Simulator software, you can debug an IMS transaction while it is running in your TSO region or in a batch job that you control.


Do lab exercise 1

Purpose: Make notes that will be needed inlater exercises

Estimated time:2 minutes

What to do:Turn to lab 1 in your workbook, and make these notes:

The Lab setup command:

EX '????.ADLAB.INSTALL(LABSETUP)'

The Debug Tool batch load library:

'????.ADLAB.DTXLOAD'

Presenter

Presentation Notes

Do lab exercise 1.


Do lab exercise 2

Purpose: Create your own copies of sample lab files that you will use in the remaining exercises


What you need:The command to enter in the TSO command shell:

EX '????.ADLAB.INSTALL(LABSETUP)'

Presenter

Presentation Notes

Do lab exercise 2.


Introduction

Starting the debugger for batch LE programs

Use a graphical user interface, and1. Debug in batch using an LE TEST option in JCL2. Debug in batch using the 'User exit data set' facility in TSO3. Debug in batch using the ‘User exit data set’ facility with the

DTSP plug-in

Using Debug Tool's graphical user interfaceDebug perspective views and navigation


Presenter

Presentation Notes



Plan your debugging session for batch programs – determine how you will run the application

You can debug your batch application as it runs as a batch job

Or you can use the 'Debug Tool setup file' online panels to run your program under TSO

A. Use the online panels to create a setup file and set a trigger

B. Run the setup file

Debug Tool

BatchApplication

z/OS

TSO region

C. When the setup file runs your program in TSO, the debugger starts because of the trigger

D. The debugger displays on your TSO terminal or a GUI

TSO

Debug Tool

BatchApplication

z/OS

Batch region C. When the batch

job step runs, the debugger starts because of the trigger

A. Set a trigger, thenB. Submit the batch job

D. The debugger displays on a Debug Tool terminal or GUI

Presenter

Presentation Notes

When you run a typical batch application, it runs as a batch job, but does not trigger the debugger. But you can configure your batch application so that when it runs, the debugger starts automatically. There are two ways you can run your application when you plan to debug it. First, you can run it normally as a batch job. Start with JCL that you already use to run the application, and make a minor change to the JCL that will cause the debugger to start. This change to the JCL is the debugging trigger. Examples of setting debugging triggers are shown in upcoming sections. Then submit the job. When it runs, the trigger causes the debugger to start, and it displays on either a dedicated Debug Tool terminal session, or on GUI debugging software on your workstation. This method, debugging your batch application while it runs natively in a batch job, is typically the best and simplest approach. Or, there is another method – run your batch application under TSO. Use the 'Debug Tool setup file' panels in TSO to create something called a 'setup file', which has all the information needed to run your batch program. You can copy JCL into your setup file to expedite the preparation. When it is ready, run the setup file, which runs your program under TSO and triggers the debugger. The debugger displays on your TSO terminal or on GUI debugging software on your workstation.


Plan your debugging session for batch programs – select a method to set a debugging trigger

Code a trigger that will cause the debugger start when you run your application

Set a debugging trigger when you want to debug

For debugging batch programs, two methods are commonly used:A. Code a Language Environment TEST option in your JCL, orB. Use the Debug Tool 'User exit data set' facility

Typically, coding a TEST option is the suggested methodIt can be somewhat simpler and easier for batch programs

However, consider using the Debug Tool 'User exit data set' facilityIf it is your personal preferenceIf you are using this method with other types of programs (non-batch), such as DB2 stored procedures or IMS transaction programs

It can be simpler to use the same method for all non-CICS programs

For z/OS version 1.7 and earlier, the TEST option is not be supported for IMS and certain other types of programs

Presenter

Presentation Notes

The last decision is which method you will use to set a trigger to start the debugger automatically when the application runs. Two methods are commonly used. Either code a Language Environment TEST option in your JCL, or use the Debug Tool 'User exit data set' facility. Either of these methods can be used whether you run in batch or in TSO, and regardless of the type of debugging interface used. A TEST option is typically the best method, because it is easy, and tends to be slightly quicker. However, consider the other method, using the Debug Tool 'User exit data set' facility if you prefer it. You may find that the 'User exit data set' method makes it easy to debug types of programs other than batch, such as DB2 stored procedures or programs that run in IMS message processing regions under the IMS transaction manager. If you get into a habit of using this method for those other programs, you may opt to use it for batch programs too. That way, you could use the same method for all of your non-CICS programs. In older versions of z/OS, at version 1.7 and earlier, the TEST option may not work with certain types of programs, which could be a reason to use the "user exit data set' method. You can see detailed examples of both of these methods in upcoming sections.


Introduction



DTSP plug-in



Presenter

Presentation Notes



Debug in batch using a TEST option in JCL and a graphical user interface

DescriptionA TEST(…) option is coded in the application's run-time JCL to trigger the debugger The debugger displays on GUI debugging software on your workstation

This method can be used:To debug Language Environment (LE) programs running in batch jobs

including programs that access IMS, DB2, or other types of databasesand non-LE programs that run in the call chain under an LE program

If compatible GUI debugging software is installed on your workstationSuch as Rational Developer for System z, or CICS Explorer with the Debug Tool plug-in

Presenter

Presentation Notes

This is a commonly used, simple method to start the debugger and display it on GUI debugging software on your workstation. You set a trigger, to start the debugger when the application runs, by coding a Language Environment (LE) TEST option in the program's run-time JCL. This method can be used to debug LE-conforming programs running in a batch job, including programs that access DB2, IMS, and other types of databases. Even non-LE subroutines can be debugged using this method, if there is at least one LE program higher in the call chain. Software such as Rational Developer for System z or CICS Explorer with the Debug Tool plug-in must be installed on your workstation. This is generally the best method when a GUI is used. However, you cannot use this method if compatible GUI debugging software is not installed. Also, if you are running on an older version of z/OS (1.7 or earlier), a TEST option may not trigger the debugger for IMS batch programs. In that case, the 'user exit data set' method could be used instead.


How to start Debug Tool for a batch job with an LE TEST option in JCL and a remote GUI

Start GUI debugging software on your workstation


You must have remote GUI debugging software installed, such as the Debug Tool plug-in for CICS Explorer, or Rational Developer for System z


dblclick

Presenter

Presentation Notes

The first step is to start the remote GUI debugging software on your workstation. This could be software such as Rational Developer for System z or CICS Explorer with the Debug Tool plug-in. Here, CICS Explorer is started.


To get the workstation TCP/IP address, click the down arrow next to the connection icon

= Listening= Listening

= Not Listening= Not Listening

click

Must be in "listening" mode to debug

Must be in "listening" mode to debug

Click the down arrow next to the connection icon


Open the Debug perspectiveOpen the Debug perspective

Presenter

Presentation Notes

That started CICS Explorer. If the "Debug" view is not displayed, switch to the Debug perspective. It must be in the “listening” mode. There is an icon on the toolbar that shows the listening status. If it is not listening, the listener icon is red, and you can click the icon to switch it on. The icon is green when the listener is on. You will need to determine your workstation's IP address. Click the small black down arrow next to the listening icon.


Click Get Workstation IP…

click

Click "Get Workstation IP"Click "Get Workstation IP"

This is the listener’s TCP/IP port number(8001 in this example)

This is the listener’s TCP/IP port number(8001 in this example)

Presenter

Presentation Notes

That displays a menu. Make a note of the listener’s IP port. In this example, it is 8001. Next, click “Get Workstation IP”.


The TCP/IP address of your workstation is shown

This is the TCP/IP address of the workstation. You will need this address and the port number to start the debugger. Copy by right clicking and selecting “Copy”. Click OK when finished

This is the TCP/IP address of the workstation. You will need this address and the port number to start the debugger. Copy by right clicking and selecting “Copy”. Click OK when finished

click

Presenter

Presentation Notes

That displays your workstation’s IP address. Make a note of it. At this point, you have prepared the remote GUI debugging software, and it ready to receive a debugging session. Click OK to close the pop-up window.


Switch to the z/OS perspective

Open the JCL that will run the application in batch

Open the JCL that will run the application in batch

In the “Open Perspective” dialog, select “System z/OS” and click “Ok”

In the “Open Perspective” dialog, select “System z/OS” and click “Ok”

11

Click the “Open Perspective” icon and select “Other”

Click the “Open Perspective” icon and select “Other”

click22

click33

Presenter

Presentation Notes

Next you will need to open the JCL that you use to run the application you want to debug. This example will show how to use the System z/OS perspective to open the JCL. Click open perspective, and select “Other”. Using the “Open Perspective” window, select “System z/OS” to open the z/OS Perspective.


Connect to the z/OS system

If not connected to your system, connect now. Instruction on how to set up a system connection is loacted in the “z/OS Perspective” training module

If not connected to your system, connect now. Instruction on how to set up a system connection is loacted in the “z/OS Perspective” training module

Presenter

Presentation Notes

Use the z/OS Perspective to connect to your z/OS system. The “z/OS Perspective” training module describes how to set up a connection if you have not already done so.


Open the JCL member for the application to be debugged

DBL click

Double click the JCL member to open in the editor

Double click the JCL member to open in the editor

Presenter

Presentation Notes

Using the Data Sets view, locate the JCL member for the application. Open the member in a edit session by double clicking the member name.


Code a TEST option in a CEEOPTS DD or as a PARM on the EXEC statement

Code a TEST option:- on the EXEC statement, or- in a CEEOPTS DD statement(But not both)

Code a TEST option:- on the EXEC statement, or- in a CEEOPTS DD statement(But not both)

TCPIP&address%port: denotes a GUI TCPIP&address%port: denotes a GUI

In the JCL, code a TEST option

In the JCL, code a TEST option

Presenter

Presentation Notes

To set a trigger for the debugger, code a Language Environment TEST option in the JCL. There are two ways to do it. Depending on how the JCL is coded, you may be able to code a TEST option directly on the EXEC statement that runs the program. Or you can add a special DD statement called CEEOPTS, and code a TEST option as input data in the CEEOPTS DD. Although both methods are shown in this example, only code one or the other. Notice how the TEST option is coded. After the third comma, it has "TCPIP&tcp address%listener port:". The keyword “TCPIP” specifies that a remote graphical user interface will be used. The IP address is coded after the ampersand. This is the IP address of your workstation, where the remote GUI debugging software is listening. The listener port number is coded after the percent sign and before a colon.


Submit the JCL to run the batch job

Update with the current IP address

Update with the current IP address

RT click

click

Right-click and select “Submit Job”

Right-click and select “Submit Job”

22

11

Presenter

Presentation Notes

The job is ready to run. Right click in the editor area and select “Submit Job”. The JCL is submitted to batch.


When the job step runs, the debugger is triggered

When the step runs, the TEST option is processed, and the Debug Tool GUI is activated.

When the step runs, the TEST option is processed, and the Debug Tool GUI is activated.

click

The “Confirm Perspective Switch” message appears, click “OK” to view the Debug Perspective

The “Confirm Perspective Switch” message appears, click “OK” to view the Debug Perspective

Presenter

Presentation Notes

When a step runs that has a TEST option specified, Language Environment receives the TEST option and starts Debug Tool. When the Debug Tool GUI receives notification of a debugging session it will request that the GUI software change to the Debug Tool perspective. Click “Yes” to change from the z/OS Perspective to the Debug Tool perspective.


The debugger automatically displays

The batch program can now be debugged

The batch program can now be debugged

Presenter

Presentation Notes

The batch job is running on the host z/OS system, and Debug Tool is communicating over the network with the GUI software.


Choosing between the CEEOPTS DD or EXEC parm

There are two ways to code a TEST option in JCL to start Debug Tool:in a CEEOPTS DD, oron the EXEC statement

Comparing the two methods:Both are easy, but CEEOPTS can be easier because:

it is simpler to cut and paste into JCL without making a syntax mistake It can be used with a JCL PROC without changing the PROCIt will trigger the debugger when the first LE program runs, even if it is a subprogram

• but a TEST option on the EXEC statement will only trigger if the main program is an LE program

Presenter

Presentation Notes

There are two ways to code a TEST option in JCL to start Debug Tool. On the EXEC statement, or with a CEEOPTS DD statement. For most people, the CEEOPTS DD method is a little easier. Here is why. When you use the CEEOPTS method, it can be easier to “cut and paste” a TEST option into JCL from other JCL where you have coded it before. Also, if a cataloged JCL PROC is used, you may not be able to code a parm on the EXEC statement, because it is embedded in the PROC. With a CEEOPTS DD, it is easy to code it in your JCL to make it take effect in any step you want in your PROC. You will see an example of that in a minute. Finally, when you use CEEOPTS, Debug Tool will trigger when the first LE program is called, even if it is a subprogram. That is an advantage over the other method, because when you code a TEST option on the EXEC statement, Debug Tool will only trigger if the main program is an LE program.


Coding the LE TEST option

The LE TEST option has five sub-options, separated by commas and a colon:

TEST( test-level , command-file , prompt , connection : preferences-file )

Test-level is not typically coded. It is used to control when the debugger will automatically stop as a program runs. (default = all conditions and abends)Command-file can be used to specify the DDname or file name of a script file containing debugger commands that will run automatically.Prompt is not typically coded. (default = display the debugger when triggered)Connection controls where the debugger displays:

• VTAM%user-id: = Connect to the TIM terminal where user-id logged on• MFI%terminal-id: = Connect to the non-TIM terminal named terminal-id• TCPIP%workstation_tcpip_address%port_id = Connect to GUI

debugging software such as Rational Developer for system zPreferences-file can be used to specify the DDname or file name of a script file containing debugger commands that will run automatically. The preferences file (if specified) runs before the command file (if specified).

Example: TEST(,,,VTAM%USER123:)


Introduction



DTSP plug-in



Presenter

Presentation Notes



Debug in batch using the 'user exit data set' facility and a graphical user interface

DescriptionThe 'User exit data set' online panels in TSO are used to set a trigger for the debugger.

A special library may be required in STEPLIB or JOBLIB to enable the Debug Tool LE user exit

The debugger displays on GUI debugging software on your workstation

This method can be used:To debug Language Environment (LE) programs running in batch jobs

including programs that access IMS, DB2, or other types of databasesand non-LE programs that run in the call chain under an LE program

If compatible GUI debugging software is installed on your workstationSuch as Rational Developer for System z, or CICS Explorer with the Debug Tool plug-in

When not to use this method:If GUI debugging workstation software is not available, use a terminal interface instead

Presenter

Presentation Notes

This is a commonly used, simple method to start the debugger and display it on GUI debugging software on your workstation. You set a trigger, to start the debugger when the application runs, using the 'Debug Tool user exit data set' utility panels in TSO. This method can be used to debug Language Environment (LE) conforming programs running in a batch job, including programs that access DB2, IMS, and other types of databases. Even non-LE subroutines can be debugged using this method, if there is at least one LE program higher in the call chain. Software such as Rational Developer for System z or CICS Explorer with the Debug Tool plug-in must be installed on your workstation. You cannot use this method if compatible GUI debugging software is not available.


How to start Debug Tool for a batch job with the 'User exit data set' facility and a remote GUI





In this example, the user is already logged on to TSO

In this example, the user is already logged on to TSOdbl

click

Presenter

Presentation Notes

In this example, the user is already logged on to TSO. The first step is to start the remote GUI debugging software on your workstation. This could be software such as Rational Developer for System z or CICS Explorer with the Debug Tool plug-in. Here, CICS Explorer is started.


To get the workstation TCP/IP address, click the down arrow next to the connection icon

= Listening= Listening

= Not Listening= Not Listening

click

Must be in "listening" modeMust be in "listening" mode



Open the Debug perspectiveOpen the Debug perspective

Presenter

Presentation Notes

That started CICS Explorer. If the "Debug" view is not displayed, switch to the Debug perspective. It must be in “listening” mode. There is an icon on the toolbar that shows the listening status. If it is not listening, the listener icon is red, and you can click the icon to switch it on. The icon is green when the listener is on. You will need to determine your workstation's IP address. Click the small black down arrow next to the listening icon.


Click Get Workstation IP…

click

Click "Get Workstation IP"Click "Get Workstation IP"

This is the listener’s TCP/IP port number.(8001 in this example)

This is the listener’s TCP/IP port number.(8001 in this example)

Presenter

Presentation Notes

That displays a menu. Make a note of the listener’s IP port. In this example, it is 8001. Next, click “Get Workstation IP”.


The TCP/IP address of your workstation is shown

This is the TCP/IP address of the workstation. You will need this address and the port number to start the debugger.

This is the TCP/IP address of the workstation. You will need this address and the port number to start the debugger.

click

click

Presenter

Presentation Notes

That displays your workstation’s IP address. Make a note of it. At this point, you have prepared the remote GUI debugging software, and it ready to receive a debugging session. Click OK to close the pop-up window. Now go back to TSO by clicking your TSO terminal session.


Navigate to the Debug Tool Utilities menu in TSO

Follow the menus on your system to navigate to the Debug Tool panels

Follow the menus on your system to navigate to the Debug Tool panels

Presenter

Presentation Notes

In TSO, navigate to the Debug Tool ISPF panels. The person who installed Debug Tool on your system may have defined a menu option for you to get there.


Select the Debug Tool user exit data set utility option from the menu

Enter

Presenter

Presentation Notes

The 'Debug Tool Utilities' menu is displayed. Select option 6 for the 'Debug Tool user exit data set' panels.


Specify the name of the Debug Tool user exit data set

Use the default file name unless instructed otherwise, or if a different user ID is needed

Use the default file name unless instructed otherwise, or if a different user ID is neededEnter

Specify the correct name of your user option data set

Specify the correct name of your user option data set

Presenter

Presentation Notes

In this utility, you store your debugging profile in a file. The file name must follow a specific convention. By default, it is yourID.DBGTOOL.EQAUOPTS. If you have not used this panel before, it will automatically fill in a file name in the 'data set name' field. Use the default name unless you have been instructed otherwise by your system programmer. The naming convention may have been customized for your system, and the convention must be followed for this feature to work. Later, when you run your batch job, a Debug Tool system exit will look for a file according to the convention. Press Enter. If the file does not already exist, it will be created automatically.


Use the default settings, unless required by your system

Use the default settings, unless required by your system

Enter

If the Debug Tool user exit data set does not already exist, this allocation panel is displayed

Presenter

Presentation Notes

In this example, the file did not exist, so the file allocation panel is displayed where you can specify attributes for the new file. On many systems, you do not need to change anything and you can take the defaults. Press Enter to continue.


Specify one or more program names

* = any program * = any program

Specify the names of main programs that should trigger the debugger when they run


Specify the debugging profile


Presenter

Presentation Notes

Now the Debug Tool user option data set has been created, and the panel titled: 'Edit test run-time option data set' is displayed. Here you specify the name or names of the main programs that should trigger the debugger when they run. Only the highest level LE program, typically the main program, will trigger the debugger. There is no reason to specify the names of lower level programs or subprograms. You do not need to specify all of the subprograms that you want to debug. In fact, entering subprogram names on this panel will have no effect at all. After the debugger has triggered, you will be able to use debugging commands to tell the debugger to stop at any subprogram you want to see. Notice that you can specify an asterisk in the program name, which specifies that the debugger will trigger for the first LE program that runs in the call chain, regardless of its name. This can be useful if you do not know the name of the highest level LE program, or if you want to use the same debugging profile with different programs.


Specify the name of one or more main programs that will trigger the debugger when they run

F8





Presenter

Presentation Notes

In this example, SAM1 is specified as the name of the main program that will trigger the debugger when it runs. You can specify up to eight program names. Notice that you can enter a partial program name using an asterisk as a wildcard. Scroll down with the F8 key.


Specify the debugging interface and connection information

Enter

Select the Remote debug mode option

Select the Remote debug mode option

When it triggers, the debugger will connect to the workstation at this address

When it triggers, the debugger will connect to the workstation at this address



Presenter

Presentation Notes

Since a graphical user interface is being used, select the option named “Remote debug mode" with a slash. Specify the IP address of your workstation in the "address" field. Also specify the "port" field. These are the TCP/IP address and port number where the GUI debugging software is listening. That is all that is needed. Press Enter.


The user exit data set was updated by pressing Enter

F3F3

F3

Presenter

Presentation Notes

At this point, the name of the program that will trigger Debug Tool, and the location of the debugging interface have been specified. Press F3 several times to save the options in the user exit data set and exit from the Debug Tool utilities.


Next, open the JCL that will run the program in batch

Depending on how your program was linked, you may need to add a special Debug Tool library to STEPLIB or JOBLIB. The name of the library will be provided by your system programmer.

Depending on how your program was linked, you may need to add a special Debug Tool library to STEPLIB or JOBLIB. The name of the library will be provided by your system programmer.

If needed, add a special library to STEPLIB or JOBLIB

If needed, add a special library to STEPLIB or JOBLIB

Presenter

Presentation Notes

Next, open the JCL that you will use to run your batch application in the editor. On some systems, you may need to add a special Debug Tool library to the STEPLIB or JOBLIB DD. This library enables the system exit that reads the 'User exit data set' to determine whether to start the debugger. If this library is needed, get its name from your system programmer or help desk.


Submit the JCL to run the batch job

Enter

Submit the jobSubmit the job

Presenter

Presentation Notes

Submit the JCL to run the batch job.


When the job step runs, the debugger is triggered

click

Select the GUISelect the GUI

When the step runs, the Debug Tool LE user exit is invoked. The exit opens your user exit data set. If the main program matches any of the program entries in the profile, the debugger is triggered and is displayed in the GUI

When the step runs, the Debug Tool LE user exit is invoked. The exit opens your user exit data set. If the main program matches any of the program entries in the profile, the debugger is triggered and is displayed in the GUI

Presenter

Presentation Notes

When the step that was modified in the batch job runs, the Debug Tool LE user exit runs automatically. The exit looks for your Debug Tool user exit data set. If the data set does not exist, no action is taken and the step runs normally. If the data set is found, it is read. If the highest level LE program does not match any of the program names in the profile, the step runs normally. But if there is a match on the program name, the exit automatically formats and passes a TEST option to Language Environment to trigger the debugger. The debugger is displayed by the GUI debugging software. The debugging software is selected by clicking it.


The debugger automatically displays

The batch program can be debugged from the GUI

The batch program can be debugged from the GUI

And you can click your TSO terminal to continue working in TSO

And you can click your TSO terminal to continue working in TSO

Presenter

Presentation Notes

The batch job is running on the host z/OS system, and Debug Tool is communicating over the network with the GUI software. Notice that you can control the program from the GUI debugger, but you can also click your TSO terminal window to continue working in TSO at the same time. Be aware that the TSO session is no longer needed. You could log off from TSO and continue to debug, because Debug Tool is controlling the application that is running in its own batch address space.


How the Debug Tool user exit data set facility works

How it works:

The user exit data set utility saves your debugging profile in a 'user exit data set'

By default, the naming convention is: user-ID.DBGTOOL.EQAUOPTSThe system programmer can customize the naming convention on your system. If that is the case:

• You need to learn the naming convention • Ensure that you name your user exit data set correctly

Debug Tool provides special LE exits. If an exit is enabled when the program runs:

It uses the user ID to determine the name of your data setThe exit reads your user option data setIf the main program name matches any of the programs in the profile, the exit passes a TEST option to LE to start the debugger

Presenter

Presentation Notes

That was an example of how to start Debug Tool for a batch application using the Debug Tool 'User Exit data set' utility and remote GUI debugging software. At this point, you may be comfortable with the process, and have all of the information you need to start the debugger. The rest of this section goes into technical details about how it works. You can opt to skip the rest of this section, if you are not interested in the details. Here is how it works. The 'User exit data set' utility saves your Debug Tool profile in a file. The test option file has to be named using a specific naming convention. By default, user ID.DBGTOOL.EQAUOPTS. However, your systems programmer can customize the naming convention. Use the default naming convention unless you have been instructed otherwise by your system programmer. Debug tool provides special exits for Language Environment. If one of these exits is enabled when your program runs, it uses the user ID of the job to determine the user ID portion of the file name. The exit program then reads your test option data set. If it finds a match on the program name in your profile, the exit passes a TEST option to Language Environment, which causes the debugger to start.


Introduction



DTSP plug-in



Presenter

Presentation Notes



In CICS Explorer, show the DTSP Profiles View

Once the DTSP plug-in is installed, access the view by opening the “Other” view menu

Once the DTSP plug-in is installed, access the view by opening the “Other” view menu

click

Presenter

Presentation Notes

Software is available as a plug-in to CICS Explorer that provides a graphical interface to the DTCN transaction. To use it, you must first install CICS Explorer on your workstation. It can be downloaded and installed from the IBM web site by following the instructions on the site. After it is installed, then follow the links and instructions on the same page to download and install the DTCN plug-in. To run the plug-in, first start CICS Explorer on your workstation. Select "window", then "show view", then "other".


Select the DTCN profiles view

dbl click Select the “DTSP

Profiles” view Select the “DTSP Profiles” view

Presenter

Presentation Notes

Select "DTCN profiles" from the show view window, and click OK.


Manage Test Runtime options datasets

“Right click” actions:Create – begin wizard driven profile creationRefresh – Reload the profiles listPreferences – set system connection information

The “DTSP Profiles” view is displayed near the “Debug Console” view

The “DTSP Profiles” view is displayed near the “Debug Console” view

Presenter

Presentation Notes

That displays the DTCN profiles view. One way to navigate is by right-clicking. When you right click in the view, you are given options to activate a profile, create, edit, or delete a profile, refresh the list, and change your preferences.


Create a new DTSP Profile

In the “DTSP Profiles” view, right click and select “Create” In the “DTSP Profiles” view, right click and select “Create”

RT click

click

11 22

Presenter

Presentation Notes

To create a new profile, right click anywhere in the profile view, then select "create".


Check the z/OS system connection settings

click

Presenter

Presentation Notes

A "Debug Tool profiles management" window is displayed. The hot-link “DTSP (non-CICS) preferences will open the system connection dialog for the DTSP profile builder.


The z/OS system connection settings

click

System connection settingsHost Name – TCP/IP address of the z/OS systemPort Number – Port number of the z/OS system set up for CICS TCP/IP serviceUser ID / Password – Used to sign on to the z/OS systemProfile Name Pattern – Naming pattern that matches the default naming pattern for the EQUAOPTS dataset contain a combination of “&userid” and “&pgmid”

click

Presenter

Presentation Notes

The DTSP preferences dialog is where the system connection settings are entered. Enter the host name, port number, user ID and password. The profile name pattern is used when the DTSP saves your debugging profile in a 'user exit data set. By default, the naming convention is: user-ID.DBGTOOL.EQAUOPTS but your system programmer can customize the naming convention on your system. If that is the case you will need to learn the naming convention, and customize the profile name pattern accordingly.


Build a DTSP profile

click

Choose the action, create or edit, and click “Next” Choose the action, create or edit, and click “Next”

Presenter

Presentation Notes

The “DTSP action choices" window is displayed again. Specify your CICS user id, the action you wish to perform, and click OK.


Enter the DTSP profile information

click

Add up to 8 load modules Add up to 8 load modules

Debugging profile information Debugging profile information

Presenter

Presentation Notes

Next is the “DTSP TEST run-time options“. Specify the load modules and run time options for the DTSP profile. Clicking finish will save your profile.


DTSP profile added to the list

The EQUAOPTS debugging profile is added to the list

The EQUAOPTS debugging profile is added to the list

Presenter

Presentation Notes

At this point, the name of the program that will trigger Debug Tool, and the location of the debugging interface have been specified, to view the profile switch to the system z/OS perspective.


Open the JCL that will run the program in batch

Opening the EQUAOPTS debugging profile shows the parameters that were added from the DTSP profile builder

Opening the EQUAOPTS debugging profile shows the parameters that were added from the DTSP profile builder

Presenter

Presentation Notes

Next, open the JCL that you will use to run your batch application in the editor. On some systems, you may need to add a special Debug Tool library to the STEPLIB or JOBLIB DD. This library enables the system exit that reads the 'User exit data set' to determine whether to start the debugger. If this library is needed, get its name from your system programmer or help desk.


Do lab exercise 3

Purpose: Run a program by submitting a batch jobStart the debugger on the Debug Tool GUI when the batch job runs


What you need:CICS Explorer or RDz installed on your workstation The Debug Tool GUI plugin installed

Presenter

Presentation Notes

Do exercise 3.


Introduction



DTSP plug-in



Presenter

Presentation Notes



Debug perspective

Debug consoleDebug console

Debug viewDebug view Monitors, breakpoints, listings… views

Monitors, breakpoints, listings… views

Source viewSource view

Presenter

Presentation Notes

Notice that the debug perspective has several panes. Each pane can have one or more “views” in it, and each view has a tab.


Display a view

You can display a view by clicking on it's tab

You can display a view by clicking on it's tab

click

Views• Support editors and provide ways to navigate your Workbench • Can appear by itself, or stacked with other views in a tabbed notebook

Views• Support editors and provide ways to navigate your Workbench• Can appear by itself, or stacked with other views in a tabbed notebook

Presenter

Presentation Notes

The pane in the upper right contains five views: variables, breakpoints, registers, monitors, and modules. Select a view by clicking it’s tab. Here, the breakpoints view is in the forefront, and the registers tab is clicked.


Result of clicking a view’s tab

Presenter

Presentation Notes

That action brought the registers view to the front.


Resizing views

dblclick

You can expand a view by double-clicking on it's tab

You can expand a view by double-clicking on it's tab

You can resize panes by dragging the borders

You can resize panes by dragging the borders

Presenter

Presentation Notes

It is easy to change the size of a pane, just drag-and-drop it's borders. You can expand a view by double-clicking it’s tab. The tab of the source view is double-clicked.


Full screen view window

dblclick

You can reduce an expanded view by double-clicking it's tab

You can reduce an expanded view by double-clicking it's tab

Presenter

Presentation Notes

That expanded it to fill the entire workbench. Sometimes it is helpful to expand a view so you can see more information. Reduce it to it’s original size by double-clicking it’s tab again.


Drag a view to another pane

You can move a view to another pane by dragging it's tab

You can move a view to another pane by dragging it's tab

drag

Presenter

Presentation Notes

You can move a view by dragging and dropping it's tab into a different pane. Here, the monitors view is moved.


Relocated tab

Presenter

Presentation Notes

Now the monitors view is located in the same pane as the debug view. This lets you control which views are visible at the same time.


Restore the default view configuration

You can reset the windows to their default position with Window -> Reset Perspective

You can reset the windows to their default position with Window -> Reset Perspective

click

Presenter

Presentation Notes

Do not be too concerned about moving, resizing, or closing views. It is easy to get them back to their original places. To reset the views click the “window” menu, and select “reset perspective”.


Reset perspective result

click

Presenter

Presentation Notes

Then click “Ok" in the “reset perspective” pop-up.


Reset perspective result

Presenter

Presentation Notes

The debug perspective was reset, with the default views shown and put back in their original positions.


The Source view

Source view Displays program source

The next statement that will run is highlightedSet and remove statement breakpoints Right click to display view action menu

Presenter

Presentation Notes

The source view displays the program. Notice that one of the statements is highlighted. That is the current statement, which is the next statement that will run. The grey area to the left of the program statements can be used to set or remove statement breakpoints. Right clicking in the source view displays an action menu, which can be used to add breakpoints, jump or run to a statement, and take other actions.


The Debug view

Debug view Controls running and terminating the program

Use step controls to step through the program line by lineRetrieve the workstation IP addressView the current program stack

The Debug view shows currently running programs

The Debug view shows currently running programs

Presenter

Presentation Notes

The debug view displays the current call chain, or program stack.


Debug view action bar buttons

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

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

Terminate: End the program

Terminate: End the program Step: run one

statement Step: run one statement

Step Over: run one statement, but step over a CALL

Step Over: run one statement, but step over a CALL

Step Return: run until return from subprogram

Step Return: run until return from subprogram

Disconnect: from the debug engine

Disconnect: from the debug engine

Animated Step: Steps into the program automatically at a rate you specify

Animated Step: Steps into the program automatically at a rate you specify

Presenter

Presentation Notes

Notice the icons in the debug view. Click them to make the program take certain actions. The green triangle is resume. It causes the program to run until it encounters a breakpoint. If no breakpoints are set, or if the program does not reach a breakpoints as it runs, it runs all the way to the termination of the application. The red box is terminate. It forces the immediate termination of the application with a zero return code. If you click it, no more statements will run. The disconnect icon disconnects the debugger from the application, but allows the application to continue running. The yellow down arrow is “step”, or “step into”, which runs a single program statement. You can watch a program run statement by statement by clicking the step icon repeatedly. If the current statement calls a sub-program, in many cases it will step directly into the subroutine or procedure. The step over icon allows you to step over a sub-program. Use this when you are on a statement that calls a sub-program, and you want the subroutine to run, but do want to see it in the debugger. The step return button is used to run until the next program return. Use it to easily run to the end of a program or sub-program and then stop.


The Breakpoints view

Breakpoints view Lists breakpoints

Set address, entry, statement, load, and watch breakpointsDelete breakpointsEnable and disable breakpoints

Right-click to open menu driven breakpoint builder

Right-click to open menu driven breakpoint builder

Presenter

Presentation Notes

The breakpoints view displays a list of breakpoints that have been set. With pop-up menu options, you can add, change, and remove breakpoints, and enable or disable breakpoints. You will see more about the different types of breakpoints, and how to set breakpoints in a minute.


The Variables view

Variables view Displays variables associated with the program selected in the debug view

Monitor local variables and memory Change representation (hex, decimal) Filter local variables (all, current, previous, language based criteria)

Presenter

Presentation Notes

The variables view is a place where you can see and change the values of variables in your program. You can display the auto monitor, which is a dynamic display that shows which ever variables are referenced by the current statement. Or you can display all local variables in the program, or optionally for COBOL programs, you can display all variables in the working-storage, linkage, or file section.


The Monitors view

Monitors view Shows variables and expressions that you have selected

Add or remove a variable or expression to the monitorChange representation (hex, decimal) Change a variable value

Presenter

Presentation Notes

The monitors view is another place where you can display and change variables. Having two views to display variables, the monitors and the variables view, gives you a lot of flexibility, and makes it easy to always see the variables you need. You can add as many individual variables as you need to the monitor, and remove them individually when you do not need to see them any more. You can optionally auto monitor variables in the monitor, so you always automatically see referenced variables as you step through a program.


The Registers view

Registers view Lists register values

Change a register valueAdd a register group

Presenter

Presentation Notes

The registers view lets you view and change the contents of machine registers. The different sets of registers can be seen, including the general purpose, 64-bit general purpose, floating point registers, and others.


The Memory view

Memory view

View and modify memoryAdd / remove memory monitorContains two panes -- the Memory Monitors pane and the Memory Renderings pane

Presenter

Presentation Notes

The memory view is used to display and change the contents of memory. You can see memory at the address of a variable, based on a register, or at an address you specify. There are several rendering formats available, including hexadecimal, EBCDIC, ASCII, signed integer, and unsigned integer.


The Modules view

Modules view Displays a list of modules loaded while running your application

Expand items to see compile units, files, and functionsDouble-click source file nodes to open source in the editor

Presenter

Presentation Notes

The modules view displays information about program modules. A module can be expanded to show compile units, related debug files, and functions. When debugging an application with multiple modules, you can double-click a debug file to have the program displayed in the source window. This gives you an easy way to see the source of a program other than the program currently running. For example, if currently running in a sub-program, you can refer to the source of the main program.


The Debug Console

Debug Console

Issue commands to the debug engine

View messages from the engine and commands

Presenter

Presentation Notes

The Debug Console allows you to issue commands to the debugging engine, which is controlling the program that is running on the host system. The commands available here are a subset of the commands available in the 3270 terminal debugging interface, and include commands to take actions such as turn the auto monitor on or off, load debugging source files, change settings, and many others. That is the end of this section. Please continue with the next section, using the GUI debugger.


The Debug Console

Debug Console commands

Review available commands

Retrieve a complete list of commands with CTRL + SHIFT

Retrieve a complete list of commands with CTRL + SHIFT

CTRL + SHIFT click

Presenter

Presentation Notes

Bring up a complete list of commands that can be entered into the Debug Console by placing the curser in the Debug Engine Command line and pressing “Control plus shift”. This will bring up a list of commands to choose from. Select a command by clicking.



Stepping through statements and running the programProgram statement breakpoints Monitoring variables Making breakpoints conditional Watch breakpoints Program entry and exit breakpoints Ending the debugging session

Loading program debug files Loading sysdebug, listings, dwarf, and source files Loading LANGX files

Debugging CICS ApplicationsCreating and editing a DTCN profile using the GUI plug-in


Presenter

Presentation Notes



The debugger starts at the top of the program

The program is not yet initializedThe program is not yet initialized

Presenter

Presentation Notes

When a debug session starts, it is paused before the program has initialized.


Use the “Step-into” button to run one statement at a time

click

Hint: F5 is the hotkey for “Step-into”

Hint: F5 is the hotkey for “Step-into”

The current positionThe current position

Click the “Step-into” button


Presenter

Presentation Notes

The current position is indicated by the highlighted source line. To begin the program, click the “resume” button to run the program or the “Step” button to run just one statement. In this example the step button is clicked to take one step.


“Step-into” again

The new current positionThe new current position

click



Presenter

Presentation Notes

The program initializes, and the current line indicator moves to the next statement. The "step" button is clicked again.


After stepping

The new current positionThe new current position

Presenter

Presentation Notes

You can continue to step through the program a statement at a time.


Search for text in the source code

To search for text, enter the text string and click OK

To search for text, enter the text string and click OK

RT click

click

22

11

33

click

Presenter

Presentation Notes

You can search for text in the source window, One way is to right-click anywhere in the source view, and then click “find text”.


Result of text search

If found, the text string is highlighted

If found, the text string is highlighted

Presenter

Presentation Notes

The find tool finds and selects a matching string in the program.


Scrolling in a window

SCROLLINGUse the scroll bar to navigate within a viewClick and drag, or click arrows

drag

Presenter

Presentation Notes

There are several ways to scroll. Use the Page up and down keys, or the scroll bar to change the position in a view.


Reset the active source line

dblclick

Reset the source view to the current line by clicking the program name

Reset the source view to the current line by clicking the program name

Presenter

Presentation Notes

If you scroll away from the current line, there is an easy way to get back to it. Click the program name in the debug view to position the source back to the current statement.


Set a breakpoint in the source view

Double click to set a breakpoint at statement 258

Double click to set a breakpoint at statement 258

dblclick

Scroll down to line 258Scroll down to line 258

Presenter

Presentation Notes

You can set breakpoints that make the program stop when it gets to specific statements. One way is to double click in the gray area to the left of a source statement. In this example the gray area next to line 258 is double-clicked.


Click the “Resume” button to run the program

A breakpoint was set at statement 258

A breakpoint was set at statement 258

click

The breakpoint is also displayed in the Breakpoints view

The breakpoint is also displayed in the Breakpoints view

Presenter

Presentation Notes

That set a breakpoint. Notice the breakpoint indicator icon next to line 258. With a breakpoint set, clicking the resume button will run the program until the breakpoint is reached. Or if the statement is never reached, it will continue to run to the end of the program.


Result of clicking the “Resume” button The program ran until it reached a breakpoint

Presenter

Presentation Notes

The program ran each statement until it reached the breakpoint. The program is suspended before running line 258. This statement will be the first to run the next time you click “Resume” or “Step”.


Right click on a line and select “Run To Location” to run the program until it reaches the statement

RT click

click

2211

“Run-to” line 275“Run-to” line 275

Presenter

Presentation Notes

That is one way to have the program run until it reaches a specific statement: set a breakpoint there and click resume. And there is another, even quicker way. Click once on a line to select it, in this example line 275, then right click the line and select “Run To Location”.


Result of the “Run To Location”

The program ran until it reached the RUNTO location

The program ran until it reached the RUNTO location

Presenter

Presentation Notes

The program ran until it reached statement 275.



Stepping through statements and running the program Program statement breakpointsMonitoring variables Making breakpoints conditional Watch breakpoints Program entry and exit breakpoints Ending the debugging session




Presenter

Presentation Notes



Add breakpoints by double clicking in the source view, or with the Breakpoints view menu

dblclick

RT clickclick

22

11

Presenter

Presentation Notes

There are several methods you can use to set statement breakpoints, and you can do it from either the source view or the breakpoints view.


The breakpoints view pop-up menu gives options for setting breakpoints

The breakpoint set at statement 258 is displayed

Right click and select additional breakpoints to create

The breakpoint set at statement 258 is displayed

Right click and select additional breakpoints to create

RT click click

2211

Presenter

Presentation Notes

You can also set a breakpoint from the breakpoints view. Right click in the white area of the breakpoints view and select “Add Breakpoint”. A menu is displayed with a list of available breakpoint types. Select “Statement”.


Specify line-number to set a statement breakpoint

Indicate the statement where you want to set a breakpoint

Indicate the statement where you want to set a breakpoint

click

clickExample expression: CUST-ID = '22004'

Example expression: CUST-ID = '22004'

Presenter

Presentation Notes

A dialog is displayed. On the first screen, the breakpoint information page, specify the statement number where you want the breakpoint to be set. The other fields give you additional control and options. The “Defer breakpoint until executable is loaded” check box lets you define a breakpoint in a program that has not been loaded, such as subroutines that have not been called yet. Indicate the Load Module or DLL in the first box, and the program or CSECT in the second, and optionally the debug file. By default, the current program is assumed, so the load module and program names are already filled in. Click Next to continue to the “Optional parameters” page. You can optionally set a frequency for the breakpoint. For example, if you enter "99" in the "from" field, the breakpoint will trigger the 99th time the statement runs, but not the first 98 times. This is useful to quickly run to a certain record in a file, prevent run-away situations, or debug loops. You can also add an expression that must be true before the breakpoint will trigger, which lets you continue to run through the statement until some variable is equal to or exceeds a specified value. Click “Finish”.


The breakpoint was set at the statement

Presenter

Presentation Notes

The new breakpoint is set at statement 312, and is shown in both the source and breakpoints views.


The Resume button or function key runs the program

F8

F8 from the keyboard has the same function as the Resume button

F8 from the keyboard has the same function as the Resume button

Presenter

Presentation Notes

Now that the breakpoint is set, run the program. Another way to resume, other than the "resume" button, is to press the F8 key.


The program ran until it reached a breakpoint

The highlighted line indicates the current statement. Statement 312 will be the next statement to run

The highlighted line indicates the current statement. Statement 312 will be the next statement to run

Presenter

Presentation Notes

The program ran until it triggered the next breakpoint, at statement 312.


Double click a breakpoint marker to clear a statement breakpoint

dblclick

Statement breakpoints have been set at lines 314 and 316

Statement breakpoints have been set at lines 314 and 316

Remove a statement breakpoint by double clicking the breakpoint indicator

Remove a statement breakpoint by double clicking the breakpoint indicator

Presenter

Presentation Notes

You have seen that there are different ways to set statement breakpoints. There are also several ways to remove them. Here is one method, double click a breakpoint icon in the gray area next to a statement.


Result of double clicking a breakpoint marker

The breakpoint at 316 was clearedThe breakpoint at 316 was cleared

Presenter

Presentation Notes

That removed the breakpoint from line 316.


Right click and select “remove” to clear a statement breakpoint

RT click

click22

11

Presenter

Presentation Notes

Another way to remove a breakpoint is to select the breakpoint to be removed in the breakpoints view, right click the breakpoint, and click "remove". Here that is done for the breakpoint at statement 312.


The statement breakpoint is cleared from the source and breakpoints views

The breakpoint at 312 was clearedThe breakpoint at 312 was cleared

Presenter

Presentation Notes

And the breakpoint is removed.


Select a breakpoint and click the “Remove” button

The breakpoint at 314 was clearedThe breakpoint at 314 was cleared click

The selected breakpoint will be removed when the “Remove” button is pressed

The selected breakpoint will be removed when the “Remove” button is pressed

Presenter

Presentation Notes

Another way is to select a breakpoint in the breakpoints view, and then click the "X"-shaped “Remove” button. In this example the breakpoint at line 314 is selected, and remove is clicked.


Result of clicking the “Remove” button

The breakpoint at 314 was removedThe breakpoint at 314 was removed

Presenter

Presentation Notes

Which removes the breakpoint.


Disable a breakpoint

clickDisable a breakpoint by un-checking the box

Disable a breakpoint by un-checking the box

Presenter

Presentation Notes

Instead of removing a breakpoint, you can turn it off temporarily. Notice the check box to the left of breakpoints in the breakpoints view. A check mark in the box indicates the breakpoint is enabled; no checkmark means the breakpoint is disabled. To enable or disable, click the box to toggle the setting.



Stepping through statements and running the program Program statement breakpoints Monitoring variablesMaking breakpoints conditional Watch breakpoints Program entry and exit breakpoints Ending the debugging session




Presenter

Presentation Notes



Hover over a variable to see it's value

The hover feature: hold the cursor (no click) over a variable in the source view, and the value is displayed!

The hover feature: hold the cursor (no click) over a variable in the source view, and the value is displayed!

Note: This option is can be activated in the user preferences

Note: This option is can be activated in the user preferences

Presenter

Presentation Notes

One way to see the value of a variable is by “hovering”. First select the source view by clicking anywhere in the source view. Then place your mouse cursor over a variable, but do not click. The variable value pops up automatically. That's an easy way to see a value.


The Variables view shows program variables, and optionally variables referenced by the current statement

Variables referenced by the current statement can be displayed in the variables view

Variables referenced by the current statement can be displayed in the variables view

StepStepclick

Presenter

Presentation Notes

The variables view provides another easy way to see variables. You can control the scope of the variables shown in this view by changing the "filter" setting. The filter can be set to show the current statement's variables, all variables, or COBOL working-storage, linkage, or file section. By default this view automatically monitors variables referenced by the current statement. Notice in this example, line 314 is the current statement, and it references two variables: cust-id and rpt-cust-id. Those variables are displayed in the variables view automatically. The step button is clicked.


After a Step. The variables view can display variables referenced by the current statement

Presenter

Presentation Notes

Now the next statement, line 315 is current, and it references different variables: cust-name and rpt-cust-name. Now these variables are shown instead. As you run or step through a program, the current variables are displayed.


Select “Automonitor Previous” to display variables from both the current and previous statements

RT click

click

22

11

Presenter

Presentation Notes

To change the scope of the variables view, right click in the view and select “Filter Locals”. A menu shows the filtering options. "Automonitor current" is the default setting, and you just saw what that setting displays. The filter is changed to “Automonitor Previous”.


Automonitor Previous displays variables from both the current and previous statements

CurrentCurrentPreviousPrevious

StepStep

click

Presenter

Presentation Notes

“Automonitor Previous” is similar to the "Automonitor current" setting, in that it automatically shows variables referenced by the current statement. But in addition, it shows variables referenced by the last statement shown. Notice that the current statement references two variables, and rpt-cust-name is one of them. It appears in the variables view, and it's value is blanks. The step button is clicked.


After a step. The Automonitor refreshes the display as you step and run

The Automonitor Previous option displays results automatically as you step through a program

The Automonitor Previous option displays results automatically as you step through a program

The yellow highlighting means the value has changed while in the variables window

The yellow highlighting means the value has changed while in the variables window

Presenter

Presentation Notes

One statement ran, and now the next line is the current statement. Notice that in the variables view, in addition to the variables referenced by the new statement, the rpt-cust-name variable is still displayed. You can see that it's value changed. "Automonitor previous" can be a very helpful setting, because it automatically shows the results of changes to variables as you step through a program. This can save you a lot of time as you monitor variable values while debugging.


Select the COBOL Working-Storage Section to view all of the Working-Storage variables

RT click

22

11

click

Presenter

Presentation Notes

There are other filtering options. Again, to see the options, right click in the variables view and select "filter locals". Notice that there are options to display all variables, and options to display variables in the COBOL file section, working-storage, linkage, and local storage sections. This time, COBOL working-storage is selected.


Result of adding the COBOL working-storage section to the variables view

The working storage starts here

The working storage starts here

DBL click

Double click the tab to expand the view

Double click the tab to expand the view

Presenter

Presentation Notes

All variables in the COBOL working-storage section are displayed. You can scroll the view using the scroll bar to locate variables. Here the variables view is expanded by double clicking its tab.


Showing all working-storage variables

Expand a section by clicking the “+”

Expand a section by clicking the “+”click

Presenter

Presentation Notes

Group variables are collapsed, and these are indicated by a “+” in front of the variable name. To expand an item to see it's subordinate variables, click the “+”.


Showing all working-storage variables

DBL click

Double click the tab to shrink the view

Double click the tab to shrink the view

Presenter

Presentation Notes

The group was expanded to show the lower level variables. To retract it again, you can click the “-”. To reduce the view back to it's normal size, the tab is double clicked.


Changing a variable value

RT click

click

22

11

Right click and select “Change Value”

Right click and select “Change Value”

Presenter

Presentation Notes

You can change the value of a variable. Select and right click the variable that you want to change, then select “Change Value” from the pop-up menu.


Change the value

click

22

11

Enter in the new value in the text box

Enter in the new value in the text box

Presenter

Presentation Notes

A “change variable” pop-up is displayed. Type in the new value, and click “OK”.


The value was changed

The value has now been changed for the session

The value has now been changed for the session

Presenter

Presentation Notes

And the value is changed.


Control + F searches for text in a window

Select the source view

Select the source view

CTRL + F The selected view is searched

The selected view is searched

click

Presenter

Presentation Notes

Sometimes you need to find a variable in the source view. You can right-click in the source view and select "find text", or you can use the “CTRL + F” hot key to bring up the “Find Text” pop-up. Enter part of the variable name and click OK.


After repeated CTRL + Finds

Presenter

Presentation Notes

The first occurrence of the string is highlighted. You can repeat the find to search forward in the program.


Display the monitors view

click

Presenter

Presentation Notes

Next, you will learn about another view you can use to display variables, the monitor view. Click the "monitors" tab to select it.


Add a variable to the monitors view

RT click click

Right click the variable after highlighting

Right click the variable after highlighting

Tip: Use the Find action to locate variables in the source

Tip: Use the Find action to locate variables in the source

2211

Presenter

Presentation Notes

You can add individual variables to the monitors view. One way to add a variable is to highlight it in the source, right click it, and then select “monitor expression”. This example shows variable “CUST-ID” added to the monitor.


Result of the "Monitor Expression"

Monitor was addedMonitor was added

Presenter

Presentation Notes

CUST-ID is shown in the monitors view. A variable added to the monitor will remain there until you remove it. As you run and step through the program, you can watch as the program changes it's value.


After adding more variables to the monitor

Monitors were addedMonitors were added

Presenter

Presentation Notes

Add as many variables to the monitors view as you need. Typically, you use the monitor to display important variables that you always want to see. In this example, several other variables were also added.


Clearing a variable from the monitor

RT click

click

22

11

Presenter

Presentation Notes

To remove a variable from the monitors view, highlight it and right click, and then select “Remove Monitored Expression”.


Result of “Remove” action – the monitored variable was cleared

Presenter

Presentation Notes

That removes the selected variable from the monitor.


Remove multiple items from the monitor

Select multiple items by clicking and holding down the Control key

Select multiple items by clicking and holding down the Control key

clickclick

2211 CTRL

+ click

33

Remove buttonRemove button

Presenter

Presentation Notes

Another way to remove one or more variables is to select them and then click the "remove" button. You can remove several at a time if you hold down the “control” key, and multi-select by clicking on each variable. Once the variables are selected, click the “X”-shaped remove button.


Result of a clearing multiple items from the monitor

Monitors remain active until you remove them

Monitors remain active until you remove them

Presenter

Presentation Notes

That removes the selected variables.


Select and double-click to add a variable to the monitor

DBL click

Presenter

Presentation Notes

An easy way to monitor a variable is to select and then double-click it.


Result of double-click a variable

Monitors remain active until you clear them


Double-click to monitor is an option setting in Window > Preferences > Run/Debug > Compiled Debug

Double-click to monitor is an option setting in Window > Preferences > Run/Debug > Compiled Debug

Presenter

Presentation Notes

That added the variable to the monitors view.


Add a variable to the monitor with the “Monitor Expression” button

Highlight the variable you want to monitor

Highlight the variable you want to monitor

clickMonitor Expression button

Monitor Expression button

click22

11

Presenter

Presentation Notes

One other way to add a variable to the monitors view is to use the “Monitor Expression” button. In the source view, highlight the variable. Then in the monitors view, click the “+”-shaped Monitor Expression button. A pop-up is displayed, with the variable name already filled in. Click “OK”. This method can also be used to add a variable that is not highlighted, by typing in the name of the variable.


Result of using the Monitor Expression button



Presenter

Presentation Notes

The variable was added to the monitors view.


Overtype the value of a monitored item to change it

DBL click

click

Change the value of the variable

Change the value of the variable

22

11

Presenter

Presentation Notes

To change the value of a monitored variable, double click it. Overtype with the new value in the pop-up, and click OK.


The value of a variable was changed

Presenter

Presentation Notes

That changed the value.


Monitoring group variables

Add CUST-REC as a Monitored Variable using one of the methods

Add CUST-REC as a Monitored Variable using one of the methods

Group variables are indicated by the “+” symbol. Click it to expand the variable.

Group variables are indicated by the “+” symbol. Click it to expand the variable.

click

Presenter

Presentation Notes

Group variables are indicated by a “+” symbol next to a variable. You can expand a group variable by clicking the “+”.


Expanded group variable

Presenter

Presentation Notes

That shows the subordinate variables in the group.


Collapse the group variable

Click the “-” to collapse the group variable.

Click the “-” to collapse the group variable.click

Presenter

Presentation Notes

Collapse a group variable by clicking the “-”.


Collapsed the group variable

The group variable can be expanded or collapsed any time

The group variable can be expanded or collapsed any time

Presenter

Presentation Notes

The group variable is collapsed again.


“Set auto on Both” command

Enter the “set auto on both” command in the Debug Console

Enter the “set auto on both” command in the Debug Console

Enter

Presenter

Presentation Notes

You have seen that you can auto monitor variables in the variables view. But you can optionally display the auto monitor in the monitors view instead. Enter a "set auto on" or "set auto on both" command in the debug console.


"Auto monitor" variables display in the monitors view

The “set auto on both” command turns on the auto monitor and displays it in the monitors view

The “set auto on both” command turns on the auto monitor and displays it in the monitors view

click

Click “Step”Click “Step”CurrentCurrent

PreviousPrevious

Presenter

Presentation Notes

That turns on the auto monitor in the monitors view. Other variables you have added to the monitor also continue to be displayed. Notice that the variables from the current and previous lines are shown. "Step" is clicked.


Result of step with “Set Auto On Both”

CurrentCurrent

PreviousPrevious

Presenter

Presentation Notes

After stepping, the variables in the auto monitor changed based on what are now the current and previous statements.


Move the monitors view

Click + drag

Drag and drop the Monitors view to move it

Drag and drop the Monitors view to move it

Presenter

Presentation Notes

The monitors and variables views can be used in tandem. If they are in different panes, you can see them both at the same time. The monitors view is moved by dragging it's tab to a different pane.


An example of using the variables and monitors views together

COBOL working storage section

COBOL working storage section

Auto monitorAuto monitor

Selected variablesSelected variables

Presenter

Presentation Notes

Here is an example of using both views together. In this case, the filter in the variables view is set to show COBOL working storage variables, and the monitors view is displaying selected variables and the auto monitor.


Another example of using the monitors and variables view in tandem

Auto monitorAuto monitor

Selected variablesSelected variables

Presenter

Presentation Notes

Another example of using both views together. This time, the filter in the variables view is set to show the auto monitor, and the monitors view is displaying only selected variables. Using these two views together gives you a lot of control over which variables display automatically as you debug your program.


Add a monitored variable to the memory monitor

Add a variable to the memory monitor by right clicking and selecting a format

Add a variable to the memory monitor by right clicking and selecting a format

RT click click

2211

Presenter

Presentation Notes

Now you have seen how to use the monitors and variables views to work with variables. You can also display memory in the memory view. In this example, the cust-rec variable in the monitor is right clicked, “monitor memory” is selected, and then the representation.


The variable is displayed in the selected format in the Memory view

Presenter

Presentation Notes

That added a rendering to the memory view. It displays storage beginning at the address of the selected variable. You can scroll up and down through memory and overtype data values. The representation can be changed to character or hexadecimal. In this example, a memory rendering was added based on a variable's location, but you can also add them based on addresses or register values. You can add as many memory renderings as you need.


Variables view

Displays information about the variables associated with the stack frame selected in the Debug view

Actions in the Variables viewFilter locals

AllAutomonitor currentAutomonitor previousCOBOL sections

Monitor local variablesMonitor memoryChange representation Change valueFind (selecting from a list of variables)

Presenter

Presentation Notes

To recap, the variables view displays variables in a program. The view has a filter that you use to change the scope of variables displayed.


Monitors view

The Monitors view shows variables and expressions that you have selected From the Source view

Highlight the variable Right Click Select MonitorFrom the Menu

Monitors Monitor Expression then type in the variable / expression

From the Source viewRight click a variable, then select Monitor Expression

From the Variables viewRight click a variable, then select Monitor Local Variable

From the Monitors viewRight click in the window, then select Monitor Expression, then type in the variable / expression

SET AUTO ON or SET AUTO ON BOTH debug console commandsDisplay the auto monitor in the monitors view

Actions in the Monitors viewAdd an expression to the monitorRemove an expression from the monitor Change a valueChange representation

Presenter

Presentation Notes

The monitors view shows variables and expressions. Add as many variables as you want. You can optionally enter SET AUTO ON or SET AUTO ON BOTH commands to show the auto monitor.



Stepping through statements and running the program Program statement breakpoints Monitoring variables Making breakpoints conditionalWatch breakpoints Program entry and exit breakpoints Ending the debugging session




Presenter

Presentation Notes



Begin by creating a breakpoint

RT click

22

11 click

Presenter

Presentation Notes

To define a conditional breakpoint, right-click in the white area of the breakpoints view. Then select "add breakpoint", and select the type of breakpoint that you want to add. In this example a statement breakpoint is created.


click

22

11

click

Specify an expression to set a conditional breakpoint

Breakpoint is set for statement 404, only when CUST-ID = ‘11004’

Breakpoint is set for statement 404, only when CUST-ID = ‘11004’

Presenter

Presentation Notes

Specify the statement where the breakpoint will be set, in this case "404", and click "next". In the second screen add a conditional expression. This expression specifies that CUST-ID must equal a specific value before the breakpoint can trigger. If CUST-ID does not match the value when statement 404 runs, the breakpoint will not trigger. Click Finish.


click

Run the program

Resume to run the program until the breakpoint is triggered

Resume to run the program until the breakpoint is triggered

Indicates that the breakpoint is conditional

Indicates that the breakpoint is conditional

Presenter

Presentation Notes

The breakpoint was added, and appears in the breakpoints view, and is shown to be conditional. Click “resume” to run the program.


The program stopped the next time it reached statement 404 and the condition was true

Adding CUST-ID to the monitor allows the value to be shown

Adding CUST-ID to the monitor allows the value to be shown

Presenter

Presentation Notes

The program ran until it the next time that it reached statement 404 and the condition was true. Notice that CUST-ID, shown in the monitors view, has the right value to trigger the conditional breakpoint. In this example statement 404 ran several times when the condition was false, but it did not stop there until it was true.



Stepping through statements and running the program Program statement breakpoints Monitoring variables Making breakpoints conditional Watch breakpointsProgram entry and exit breakpoints Ending the debugging session




Presenter

Presentation Notes



Create a “Watch” breakpoint

RT click

11

22click

Presenter

Presentation Notes

So far, you have seen how to set statement breakpoints. But there are other types of breakpoints. A "watch" breakpoint triggers when a variable's value changes. To add a watch breakpoint, right click in the breakpoints view, select “add breakpoint”, and then “watch”.


A Watch breakpoint triggers when a specified variable changes

click

22

11

click

Specify the variableSpecify the variable

Presenter

Presentation Notes

The “Add a Watch Breakpoint” dialog is displayed. At the top of the first screen enter the variable or expression that is to be watched, and click Next. The second screen has optional parameters that allow you to specify a frequency and optionally make the watch breakpoint conditional by entering an expression. In this example, the frequency is not changed and no expression is entered. Click "finish".


Watch breakpoint for variable NUM-CUSTFILE-RECS has been added

Click the Variables tab to view the variable value

Click the Variables tab to view the variable value

Presenter

Presentation Notes

The watch breakpoint was added, and is displayed in the breakpoints view.


Run the program

click

The current value of the variable is 1

The current value of the variable is 1

Click “Resume” to run until the breakpoint is triggered

Click “Resume” to run until the breakpoint is triggered

Presenter

Presentation Notes

Here, the variables view is selected, which is displaying the watched variable. The resume button is clicked.


The watch breakpoint triggered when the variable changed

The breakpoint triggered when the variable value changed

The breakpoint triggered when the variable value changed

Presenter

Presentation Notes

The watch breakpoint triggered. Notice that the value of the variable changed, and that the program is stopped at the next statement to run after the statement that changed the variable.



Stepping through statements and running the program Program statement breakpoints Monitoring variables Making breakpoints conditional Watch breakpoints Program entry and exit breakpointsEnding the debugging session




Presenter

Presentation Notes



You can step into a subprogram or function

click Step-intoStep-into

Presenter

Presentation Notes

But first, here is a simple example of how you can follow the logic of an application from one program to another. A program named SAM1 is running. You can tell because the program name is highlighted in the debug view, and it is also displayed in the tab of the source view. The next statement to run is line 312, which is a "CALL" statement that will pass control to another program named SAM2. It has not yet executed the CALL statement. To follow the logic into the subprogram, click “Step-into”.


After stepping into a subprogram

clickStep through the programStep through the program

SAM2 is added to the program stack

The location is at SAM2 initialization

SAM2 is added to the program stack

The location is at SAM2 initialization

Presenter

Presentation Notes

That stepped into the subprogram, SAM2. There are two cases when you are sitting on a "CALL" statement and step. Either the subprogram has been compiled for use with the debugger, or not. For example, in the case of an Enterprise COBOL subprogram, if it is compiled with the "TEST" compiler option, then it is compiled for the debugger. If it has been compiled with "NOTEST", then it is not. In this example, the subprogram is compiled for use with the debugger, so it steps in. If this program had not been compiled for the debugger, then "STEP" would run the subprogram, but the debugger would not display it. The debugger would pause at the next statement after the "CALL" statement in the higher level program. "Step-into" is clicked several times to step through the program.


You can STEP out of a subprogram or function

clickStep out of the programStep out of the program

Presenter

Presentation Notes

After stepping or running through the program, the last statement in the subprogram is reached. "Step-into" is clicked again.


Returned to the calling program

SAM2 returned, and you now back in SAM1

The Source view shows SAM1 code

SAM2 returned, and you now back in SAM1

The Source view shows SAM1 code

Presenter

Presentation Notes

After stepping, control is returned back to the higher level program. The debugger paused at the next logical statement, which is the statement after the CALL. Now you have seen one way to follow logic into a subprogram, step in and step out.


Create an entry breakpoint

RT click

11 click

22

Presenter

Presentation Notes

But it can be cumbersome to have to step into every subprogram that you want to debug. So there is a simpler way to pause when a specific subprogram in entered – an "entry" breakpoint. To set an entry breakpoint, right click in the Breakpoints view, and select “Add Breakpoint” and then “Entry”.



click11

click22Fill in the Function or Entry point nameFill in the Function or Entry point name

Presenter

Presentation Notes

The “Add an Entry Breakpoint” pop-up appears. If the sub program has not been called yet, then it may not be loaded in memory. If that is the case, click the check box labeled “Defer breakpoint until executable is loaded”. If you are not sure, check the box anyway. The breakpoint will still trigger if the module already happens to be loaded. Enter the full names of the load module, CSECT or program name, and entry point name, and click "next". On the next page, you can optionally specify a frequency or an expression to make the breakpoint conditional. Click "finish".



click

The entry breakpoint has been addedDeferred: The breakpoint is deferred until the source is loaded

The entry breakpoint has been addedDeferred: The breakpoint is deferred until the source is loaded

Click “Resume” to run the program until the breakpoint is triggered

Click “Resume” to run the program until the breakpoint is triggered

Presenter

Presentation Notes

The breakpoint is added, and appears in the breakpoints view. Click “resume” to" run the program.


After stopping at the entry breakpoint

The program stopped at the entry to SAM3

The program stopped at the entry to SAM3

Presenter

Presentation Notes

The breakpoint triggered when the program was entered. It is paused the at the entry, and you can follow the logic by stepping in.


Entry and exit breakpoints

Entry breakpointWill stop when a named subprogram is entered with a subsequent Resume or Run-to-LocationAnother option:

Stop at all function entries sets an entry breakpoint for all programsRight-click the program in the debug view to see this option

Considerations:With most compilers, the entered program must be compiled for debugging for the entry breakpoint to trigger

• Exceptions include debugging in disassembly modeDefer the breakpoint if the program is not already loaded

Presenter

Presentation Notes

An entry breakpoint gives you an easy way to run the application until it reaches a specific program. With most compilers, the subprogram must be compiled for debugging for the entry breakpoint to trigger. Don't forget to click the “Defer breakpoint until executable is loaded” checkbox when setting the breakpoint, if you are not sure that the module is already in memory.



Stepping through statements and running the program Program statement breakpoints Monitoring variables Making breakpoints conditional Watch breakpoints Program entry and exit breakpoints Ending the debugging session




Presenter

Presentation Notes



Termination action buttons

Immediately terminate the application using action buttons

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.

Tip: CTRL+F2 is the shortcut

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

Tip: CTRL+F2 is the shortcut

Disconnect: Disconnect Debug Tool from the application. The program continues to run from the current location without the debugger.

Disconnect: Disconnect Debug Tool from the application. The program continues to run from the current location without the debugger.

Presenter

Presentation Notes

When you click "resume", the application runs until the next breakpoint is triggered. However, if the program does not reach or trigger any breakpoints, it will run to termination. That is one way to end your debugging session, just run the program until it finishes. However, you can end a debugging session at any time with the terminate or disconnect buttons. "Terminate" stops the application immediately. No more statements run, and the application is given a zero return code. "Disconnect" ends the debugging session, but allows the application to run normally, continuing from the current statement.


Click the “Terminate” button


CTRL+F2 is the hotkey


CTRL+F2 is the hotkey

click

Presenter

Presentation Notes

The “terminate” button is clicked.


The debugging session ended

Presenter

Presentation Notes

The application was terminated immediately, and the debugging session ended. The debugger is now ready for the next debugging session to start, if needed.


Force an immediate termination with abend

right click11

Right click in the Debug view

Right click in the Debug view

Terminate and abend

Terminate and abend

click22

Terminate and abend Terminates the program and forces an abend.

Consider using this option to:• Capture the abend with IBM Fault Analyzer for z/OS (if installed) • Avoid running subsequent steps in a multi-step job • Roll back database updates

Terminate and abend Terminates the program and forces an abend.

Consider using this option to:• Capture the abend with IBM Fault Analyzer for z/OS (if installed)• Avoid running subsequent steps in a multi-step job• Roll back database updates

Presenter

Presentation Notes

Another way to end a session is to right click in the white space of the debug view, and select “Options” and then “Terminate and Abend”. This forces the program to terminate with an abend. Consider doing this if you want the system to collect a dump. If you have IBM’s Fault Analyzer product, perhaps you plan to use it to see a detailed analysis. In some cases, forcing an abend can prevent subsequent steps in a batch job from running. And in some applications an abend will force changes made to databases to be rolled back.




Loading program debug filesLoading sysdebug, listings, dwarf, and source files Loading LANGX files



Presenter

Presentation Notes



Providing program information for the debugger

Debug Tool reads a debug file for a program to display information about that program

The type of file needed depends on the compiler A SYSDEBUG file

Used with Enterprise COBOL and Enterprise PL/IThe compiler creates it when a TEST(…,SEP) compiler option is specified

A LANGX fileUsed with assembler, OS/VS COBOL, and COBOL II compiled with NOTESTIt is produced by a utility program (EQALANGX) that runs after a compile or assembly

A compiler listingUsed with older PL/I compilers, and COBOL II compiled with TEST

A dwarf or .mdbg fileUsed with XL C/C++ when certain compiler options are specified

The program source file Used with XL C/C++, and older versions of Enterprise PL/I

Presenter

Presentation Notes

The debugger reads a debug file for each program, and uses it to show you program source statements and variables. The type of file it uses depends on the compiler. Different compilers produce different kinds of debug files. Sysdebug files are used with programs compiled with the Enterprise COBOL and Enterprise PL/I compilers. LANGX files are used with assembler programs, and programs compiled with the OS/VS COBOL compiler, and can optionally be used with programs compiled with the VS COBOL II compiler. The debugger can read compiler listings with programs compiled with older PL/I compilers, and optionally with VS COBOL II programs. A dwarf or .mdbg file can be used with programs compiled with the XL C/C++ compiler, and the actual program source file itself can optionally be used with XL C/C++ programs and programs compiled with older versions of Enterprise PL/I. Compile processes should be updated so that the appropriate file is generated automatically when you compile or assemble a program.


The debugger can automatically locate the file for some compilers

Enterprise COBOL and Enterprise PL/I compilers embed the name ofthe SYSDEBUG file in the load module

The debugger can automatically load it if it exists

Load Library

Load Module SAM1‘library(SAM1)’

member SAM1

SYSDEBUG Library

Presenter

Presentation Notes

Enterprise COBOL and Enterprise PL/I compilers can embed the name of the sysdebug file directly in the load module. If you browse a load module generated with one of these compilers, you will be able to see the name of the sysdebug file in the module. This is a helpful feature, because the debugger can automatically find the file when the debugger starts or when a new program is entered. However, if the debug file has been moved or renamed, the debugger will not be able to find it automatically. There are several ways for you to specify the new name of the file.


How the debugger locates debug files

The debugger searches for debug files in this order:(For COBOL, PL/I, assembler, and C/C++ other than .mdbg files)

For Enterprise COBOL and Enterprise PL/I programs, it will attempt to load the sysdebug file name that is embedded in the load moduleThen, if these commands were entered, the files and libraries that they specify are searched:

SET SOURCE …SET DEFAULT LISTINGS …

Then, if an EQADEBUG DD statement was coded in the JCL, the libraries in it's concatenation are searchedFinally, using the “Debug Tool GUI Source Look Up Path” to indicate the location of debug files

If a matching file is not found automatically, you can enter a command or click the “change text file” button to specify the correct file or library

For LANGX files, also specify an LDD command to load the file

Presenter

Presentation Notes

When the debugger starts, or when it detects that a new program has been entered, it can attempt to automatically load the file containing the needed source information. For Enterprise COBOL and Enterprise PL/I programs, it attempts to load the sysdebug file based on the name embedded in the load module. If the file is found, the debugger performs a check to validate that the timestamp in the sysdebug file matches the timestamp of the module. If it matches, the file is used. If a match is not found, the debugger looks other places. The user can specify a "SET SOURCE …" debug engine setting to specify the name of the debug file for the program. If a "SET SOURCE" setting has been specified for the program, the debugger opens the specified file and validates the timestamp. If a match is still not found, the debugger checks for a "SET DEFAULT LISTINGS" setting. This setting provides a list of libraries to be searched. Each library in the list is searched for a member with a matching name and timestamp. Finally, the debugger checks to see if an EQADEBUG DD statement exists, which is another way to specify a list of libraries to be searched. These libraries are all checked for a matching member name and timestamp. Only after exhausting all of these possibilities will the debugger display a message indicating that source information could not be found. If that happens, you can then enter commands to specify a file or libraries to search for the correct file. In many cases, the debugger will then find and load the file automatically. For LANGX files, an "LDD" command must also be specified to load the file.




Loading program debug files Loading sysdebug, listings, dwarf, and source filesLoading LANGX files



Presenter

Presentation Notes



Example of loading sysdebug, listings, dwarf, and source files

Use these examples for programs compiled with:Enterprise COBOLEnterprise PL/ICOBOL II (compiled with a TEST compiler option)PL/I for MVS and VMOS PL/IXL C/C++ (when not using a .mdbg file)

Presenter

Presentation Notes

The following examples can be used for programs that load sysdebug files, listings, dwarf files, and source files. These include programs compiled with Enterprise COBOL, Enterprise PLI, XL C/C++, and others.


A program was entered, but no debug file was found

The source window is empty

The source window is empty

A message is displayed

A message is displayed

Presenter

Presentation Notes

In this example, the debugger started, but it did not find a debug file for the program. The source window is empty, and a message indicates that the source file was not found. Two buttons are displayed: “edit source lookup path” which can be selected to specify a list of libraries, and “Change Text File” which lets you specify the debug file name.


Change Text File (Method 1)

11

Click “Change text file"

Click “Change text file"

click

Enter the correct file. This mapping is not permanent

Enter the correct file. This mapping is not permanent

click22

Presenter

Presentation Notes

The “Change Text File” button is clicked. In the pop-up, enter the name of the correct debug file for the program, and click “OK”.


The debug file was loaded from the indicated location

The source code is now available


Presenter

Presentation Notes

The debugger loads and validates the time stamp of the debug file. If it is correct, the program source is displayed. You can use this method to load the debug file for each program you want to debug.


SET DEFAULT LISTING (Method 2)

Enter the “SET DEF LISTING” + location of the source information

Enter the “SET DEF LISTING” + location of the source information

Enter

Presenter

Presentation Notes

Another way to specify the locations of debug files is with a "SET DEFAULT LISTINGS …" command specifying one or more libraries. In this example, a sysdebug library is specified. Enter only the name of the library or PDS, not the member name. The debugger will automatically look for a matching member name.


The debug file was loaded from the indicated location



The source was loaded from the indicated location

The source was loaded from the indicated location

Presenter

Presentation Notes

When the SET DEFAULT LISTINGS command is entered, the debugger searches the library and loads a matching debug file. Notice that program source code is displayed in the source window now. "SET DEFAULT LISTINGS …" is a good way to specify the location of debug files. A single library, or list of libraries can be specified. The setting remains in effect, so when each subprogram is entered, the same libraries will be searched again to find the right file. So this setting automates the search.







Presenter

Presentation Notes



Example of loading LANGX debug files

Use this example to load LANGX debug files

LANGX files are used for programs compiled with:AssemblerVS COBOL II (compiled with the NOTEST compiler option)OS/VS COBOL

Presenter

Presentation Notes

LANGX files are used with programs compiled with Assembler, VS COBOL II, and OS/VS COBOL.


A program was entered, but no Langx file was found

The source view shows machine code

The source view shows machine code

Presenter

Presentation Notes

In this example an Assembler program is being debugged, the debug session launched, but the source view is not displaying program source code. Instead, it may display disassembled machine code.


Use a SET DEFAULT LISTINGS … command to specify LANGX file libraries

Enter one library, or a list of libraries in parentheses

Enter one library, or a list of libraries in parentheses

Enter

When entering library names, do not specify member names or use quotation marks

When entering library names, do not specify member names or use quotation marks

Presenter

Presentation Notes

A SET DEFAULT LISTINGS command is entered in the debug console. In this example, a library containing LANGX files is specified. Enter only the name of the PDS or library, not the member name.


Load the LANGX file with an LDD (load debug data) command

The LDD command loads a LANGX file into the debugger

The LDD command loads a LANGX file into the debugger

It will search the SET DEFAULT LISTINGS library or libraries for the specified member name

It will search the SET DEFAULT LISTINGS library or libraries for the specified member name

Enter

Presenter

Presentation Notes

Now the search path has been defined. To load the LANGX file into the debugger enter an LDD (load debug data) command with the member name.


The Langx file was loaded from the library

The SET DEFAULT LISTINGS setting remains in effect for other programs that are entered

The SET DEFAULT LISTINGS setting remains in effect for other programs that are entered



Presenter

Presentation Notes

The LDD command searched for the specified member in the library search concatenation, and loaded it. The program source code is now displayed.


Loading program debug files

SET DEFAULT LISTINGS library-name , orSET DEF LIST library-name , orSET DEF LIST ( library-1, library-2, library-3, … )

Defines a library or libraries whose members are searched for program debug filesYou can concatenate sysdebug files, langx files, compiler listings, and expanded source files all in the same list

LDD member-nameLoads the LANGX file in member-name from the library or libraries specified by the SET DEF LISTINGS … setting or an EQADEBUG DD

Presenter

Presentation Notes

A "SET DEFAULT LISTINGS …" command is used to specify a library, or a list of libraries that the debugger will search for debug files. Use an "LDD member-name" command to explicitly load the LANGX file. The libraries specified by the "SET DEFAULT LISTINGS …" command and the EQADEBUG DD statement are searched for the member.







Presenter

Presentation Notes



The same interfaces to the debugger are available in both batch and CICS environments:

Terminal full-screen interfaceRemote graphical user interface

Using the debugger is the same in CICS and batch

However, the method used to start the debugger is unique in CICS

Starting Debug Tool with CICS applications

Presenter

Presentation Notes

Debug Tool can be used to debug CICS programs. The same debugging interfaces that are available in other environments can be used in CICS, including the terminal interface and the graphical user interface. You use the same commands and features when you work with CICS programs as when you work in other environments. However, the way you start Debug Tool is unique in CICS.


Starting debug Tool with CICS Programs

The Debug Tool installer selects one of these methods to start the debugger in CICS

The DTCN transactionUsed to define a profile to start the debugger for one or more CICS programsThere is an optional graphical user interface for DTCN

DTCN profiles can be set from a workstation without using a terminal

DTCN is a feature of IBM Debug Tool for z/OS

The CADP transactionUsed to define one or more profiles to start the debugger for CICS programs CADP is a feature of CICS

Presenter

Presentation Notes

This tutorial describes two methods for starting the debugger, DTCN and CADP. In any given CICS region, you will use one method or the other, but not both. If DTCN is used on your system, use it to define a profile that will trigger the debugger when certain CICS programs or transactions run. After you define the profile, run the target transactions, and the debugger starts. In your profile, you can specify the names of several different programs that you want to debug. DTCN is a feature of Debug Tool. The CADP transaction provides a similar function, but it allows you to define more than one debugging profile. CADP is a feature of CICS, and is available in CICS version 2.3 and later. Generally, DTCN is the suggested method, since it provides additional capabilities to pinpoint the exact instance of a program that you want to debug. For example, a debugging trigger can optionally be set in DTCN that will trigger only if certain data values are found in a commarea or container. Another advantage of DTCN is that debugging profiles can be defined from an optional graphical interface, so you can create a profile from a workstation without logging on to a CICS terminal. The person or group that installs Debug Tool decides which method is implemented in your CICS regions. Determine which method is available on your system, DTCN or CADP, and view the sections of the tutorial that pertain to your system.







Presenter

Presentation Notes



In CICS Explorer, show the DTCN Profiles View

Once the DTCN plug-in is installed, access the view by opening the “Other” view menu

Once the DTCN plug-in is installed, access the view by opening the “Other” view menu

click

Presenter

Presentation Notes

Software is available as a plug-in to CICS Explorer that provides a graphical interface to the DTCN transaction. To use it, you must first install CICS Explorer on your workstation. It can be downloaded and installed from the IBM web site by following the instructions on the site. After it is installed, then follow the links and instructions on the same page to download and install the DTCN plug-in. To run the plug-in, first start CICS Explorer on your workstation. Select "window", then "show view", then "other".


Select the DTCN profiles view

Select the “DTCN Profiles” view Select the “DTCN Profiles” view

dbl click

Presenter

Presentation Notes

Select "DTCN profiles" from the show view window, and click OK.


The DTCN profiles view is displayed

“Right click” actions:Activate – activate a profileCreate – begin wizard driven profile creationEdit – wizard driven profile editingDelete – remove a profileRefresh – refresh viewPreferences – edit the DTCN connection information defined at installation

The “DTCN Profiles” view is displayed near the “Debug Console” view

The “DTCN Profiles” view is displayed near the “Debug Console” view

Presenter

Presentation Notes

That displays the DTCN profiles view. One way to navigate is by right-clicking. When you right click in the view, you are given options to activate a profile, create, edit, or delete a profile, refresh the list, and change your preferences.


Create a new DTCN Profile

In the “DTCN Profiles” view, right click and select “Create” In the “DTCN Profiles” view, right click and select “Create”

RT click

click

11 22

Presenter

Presentation Notes

To create a new profile, right click anywhere in the profile view, then select "create".


Specify your CICS user ID and "create"

click

Presenter

Presentation Notes

A "Debug Tool profiles management" window is displayed. Specify your CICS user id, and click OK. That displays a window where you can specify settings for the new profile.


Specify the settings for your DTCN profile

Enter the transaction or terminal ID

Enter the transaction or terminal ID

click

Select active or inactive for profile status

Select active or inactive for profile status

“*” is a wild card“*” is a wild card

click

Optionally enter Load Module or Compile unit pairs

Optionally enter Load Module or Compile unit pairs

Click next to continueClick next to continue

Presenter

Presentation Notes

Specify information about the application you want to debug. You can specify the name of the CICS terminal where the transaction will run, the transaction ID, program names, CICS user ID, and other identifiers. By default, your user id is filled in automatically. You can use an asterisk as a wildcard for all or part of a name in these fields. The profile determines when the debugger will start. When a program runs in CICS, and all of the resource names match, then the debugger will trigger. For example. If you specify a terminal id, a user id, and a program name, all three must match. To add a program, click the add button. A window will be displayed where you can enter a combination of a load module and compile unit. The load module is the name known to CICS. It is the name of a load module, which could be the first program that runs in a transaction, or a program called with a an EXEC CICS XCTL or LINK. The compile unit is the name known to the compiler, such as the COBOL "program id" or the PL/I main procedure. You can specify up to eight pairs of load modules and compile units. You can use asterisks and question marks as wildcards in the names. For example, you can code the load module name and specify an asterisk in the compile unit field. Then the profile will trigger if there is a match on the load module name, regardless of the compile unit name. You can also specify a data value that must be present in the commarea at a specific offset, or you can specify a data value that must be present at a specific offset in a named container. Typically, these are only needed in cases where a combination of terminal, transaction, program, and user id are not specific enough, and the profile might trigger for the wrong instance of a transaction. This can happen with background transactions that are started from other systems or web-based applications. Applications and interfaces often communicate through the commarea or a container. If you want the profile to be active immediately, ensure that the "profile status" box is set to "active". Click next to continue.


Selecting “TCP” updates the TCPIP address

Selecting “TCP” updates the TCPIP address

You can change the Test run-time options

Ensure that the session type is set to TCP. The option for mainframe interface, MFI is available

Ensure that the session type is set to TCP. The option for mainframe interface, MFI is available

Ensure that port number corresponds to the port number RDz is listening to

Ensure that port number corresponds to the port number RDz is listening to

click

Presenter

Presentation Notes

A window is displayed where you can make changes to the sub-options of the TEST option that will be used to start the debugger. Notice that by default, the session type is set to TCP, and the address of your workstation has been filled in automatically. With these settings, the debugger will use GUI debugging software that must be installed on your workstation, such as the debugger in Rational Developer for System z, or the Debug Tool plug-in for CICS Explorer. Click "finish".


A new DTCN profile was created

Presenter

Presentation Notes

That added the new DTCN profile, and it is displayed in the list. At this point, you are ready. The profile is defined and active in CICS. Now, do whatever you need to do to run your application to create the conditions specified in the profile that will start the debugger. When the profile is matched, the debugger will be started. It will be displayed on the device that you specified in the profile, which could be the GUI debugger on your workstation, or a CICS terminal.


Editing a DTCN profile

In the “DTCN Profiles” view, right click the profile and and select “Edit”

In the “DTCN Profiles” view, right click the profile and and select “Edit”

RT click

click

11 22

Presenter

Presentation Notes

Once a profile is created, you can delete it or make changes to it. Right click the profile. Click "delete" to remove it, or click "edit", as in this example.


DTCN profile editor

Enter changes to the DTCN Profile

Enter changes to the DTCN Profile

Presenter

Presentation Notes

You can work through the same windows that you used to create the profile, and make changes as needed. Your changes are saved when you click "finish". That is the end of this section, which described how to start the debugger for CICS programs by using the graphical user interface for the DTCN transaction.


Starting the Debug Tool using a DTCN profile

The profile is added to the DTCN profiles list, and ready to trap the indicated transaction

The profile is added to the DTCN profiles list, and ready to trap the indicated transaction

Open a CICS terminalOpen a CICS terminal

Presenter

Presentation Notes



Run the transaction

The The

Presenter

Presentation Notes



The DTCN profile triggered the debugger when the application ran

Open a CICS terminalOpen a CICS terminal

Presenter

Presentation Notes



Manage compiled language exception breakpoints

click22

11

Presenter

Presentation Notes

Exception breakpoints are triggered when the debugger recognizes an exception thrown by the application. The debugger recognizes the following types of exceptions: TEST(ALL), TEST(ERROR), and TEST(NONE). Select the type of exceptions that you want to trap with a breakpoint.


Reference

Visit the IBM Problem determination tools website at www.ibm.com/software/awdtools/deployment/

Get the latest news about IBM problem determination tools productsDownload product manuals

Recommended Redbook: "Introduction to the IBM Application Development Tools on z/OS and OS/390"

Go to www.redbooks.ibm.com and search for “PD Tools”It describes the IBM Application Development Tools for z/OS and OS/390 and includes scenarios that show how to use the tools to recognize, locate, and fix errors in application programs using:

IBM Fault AnalyzerIBM File ManagerIBM Debug ToolIBM Application Performance AnalyzerIBM Workload Simulator

http://www.ibm.com/software/awdtools/deployment/

http://www.redbooks.ibm.com/


Take the Debug Tool online tutorial

Missed a class? Need a refresher course?Debug Tool training is available on the IBM websiteGo to: http://publib.boulder.ibm.com/infocenter/ieduasst/stgv1r0/index.jsp/then click Debug Tool for z/OS (on the left side of the screen)

then click web-based training (on the left side of the screen)

Debug Tool GUI v11 Basic Mentor Workshop-00

Documents

Transcript of Debug Tool GUI v11 Basic Mentor Workshop-00