Klement_0902_v2F (complete article)

ViewpointIndustryWatchStrategicDirectionsSolutions
by Scott Klement
SystemiNetwork.com february 2009 System iNEWS 25
Still using the green-screen tools to debug your programs? There are lots
of really nice debugging tools available, both green screen and GUI. To
compare the two types, let me slip into my native Milwaukee dialect:
Are ya still usin’ da green-screen debuggin’ tools? Dat’s pert-near
drinkin’ from da bubbler while tailgatin’ instead-a havin’ a brewski.
Nothin’ goes better at a brat-fry than a nice cold one, aina hey?
If you haven’t looked over the menu of available debugging tools lately,
you might be surprised to see the number of tools IBM has provided us
with. You might even find it useful to rethink your choice of day-to-day
debugging tools, because there are some really nice features in the tools
available today. This article discusses the various debugging tools and gives
you my thoughts on each.
Green-Screen Debuggers
Let’s begin by taking a look at some of the available green-screen
debugging tools.
Start Interactive Source Debugger (STRISDB). Interactive
Source Debugger (ISDB) is a full-screen source debugger for
Original Program Model (OPM) RPG, Cobol, and CL pro-
grams. The debugger is provided as part of the Application
Development ToolSet (ADTS) that is ubiquitous in IBM i
shops. At the time of ISDB’s release, STRDBG didn’t show
the program source on the screen as you were debugging it;
it showed only the statement number! You had to follow
along by comparing the statement number against your
compile listing. ISDB is a big improvement because
it shows the source code as the lines of code are
run. It lets you interactively place breakpoints in
the code, view variable values, and so forth.
However, ISDB can’t debug across programs.
For example, if one program calls another pro-
SquashBugs
withIBM
DebuggingTools
Fix your IBM i code with one of these debugging tools
IllustrationbyMikeFriehauf

debugging tools
26 System iNEWS february 2009 SystemiNetwork.com
gram, you can’t step from the first program into the sec-
ond. Furthermore, it doesn’t support any ILE languages
or Java, making it useful only for legacy development.
ISDB is the only debugger that supports debugging
RPG II programs in the S/36 environment, and in my
opinion, that’s the only place that ISDB should still be
used today.
Start Debug (STRDBG). Today, you can use
STRDBG to invoke three different debuggers: the origi-
nal statement debugger, a green-screen source debugger,
and a GUI debugger called the System i5 Debugger. I
describe the System i5 Debugger in the next section and
use this section to describe the green-screen tools.
STRDBG provides a green-screen source debugger similar
to ISDB, except that STRDBG supports all of the ILE lan-
guages and Java in addition to OPM RPG, CL, and Cobol.
To use the source debugger, you must compile a “debug view”
into your program (see “Compiling Debug Views into Your
Programs,” below).
In today’s world of modular, reusable code, your application is
likely to consist of many routines written in multiple modules,
programs, and service programs. Don’t sweat it! STRDBG is
happy to help you debug these programs. As long as all of the
modules in the programs have debug views compiled into them,
you can step from one to the other in the debugger. Here’s how
it works: When your program reaches a statement that calls a
program, procedure, or Java method, simply press F22 to “step
into” the routine. If necessary, the debugger loads the source
code for that routine into memory and then steps to the first
statement in the called routine. That’s a feature I use quite fre-
quently, and it saves me a ton of time!
Although STRDBG has, at times, been referred to as
the “ILE debugger,” it works just fine with OPM pro-
grams as well. Like ILE programs, OPM programs must
be compiled with a debug view as described in “Compiling
Debug Views into Your Programs.” Furthermore, to start
debugging an OPM program, you need to specify the
OPMSRC(*YES) parameter to the STRDBG command.
This parameter tells STRDBG to use the source debugger
FIgure 1
Start Debug (STRDBG) in 132-column mode
A
compiler’s job is to convert your source code to machine
instructions. The actual code executed by the CPU looks
nothing like the source code you started with, so how
can a debugger display your source code as the program is
executed? That’s what a debug view is for! A debug view is an
extra bit of code that’s added to your program and is executed
only when your program is run through a debugger. It tells
the system which group of machine instructions corresponds
to which line of source code, and which areas of memory cor-
respond to the variables defined in your source code. That way,
you get all the advantages of running compiled code and can
still debug using the source code from which it was compiled.
Although the debug view does make your program object
larger because it takes up extra bytes on a disk, the debug
view is used only if the program is run through a debugger.
Rest assured that your program doesn’t require more memory
or run slower when run outside of the debugger.
With the sole exception of ISDB, all of the debuggers pre-
sented in the main article require you to create your program
with a debug view.
In an ILE language, you select a debug view for your pro-
gram when you compile it. This is done with the DBGVIEW
parameter on the CRTxxxMOD, CRTBNDxxx, or CRTSQLxxxI
command when you compile your source code. Here are the
basic debug views you can choose from:
*NONE—No debugging information is included.
You can’t use your code with a debugger.
*STMT—Only statement numbers are included in the
debug view.This option lets you debug your program
using the legacy tools that print your source statement
number on the screen, and it expects you to follow
along on a compile listing.This view is the default, but
it isn’t useful if you want to use a source debugger.
*SOURCE—Instructions are given that correlate lines of
machine instructions with the lines of your source code.
When your program is run, your original source mem-
ber (or stream file) is read by the debugger, and the
contents of that member are used to display the lines
of source code as they are executed.This debug view
works properly only if the source code in the source
member still exists and hasn’t changed since the last
time you compiled the program.
*LIST—This option is the same as *SOURCE, except
that a copy of the compile listing for your program is
included in the program (or service program) object.
That way, you can still debug it even if the source
code has changed or is no longer available. The dis-
advantage, of course, is that this view makes your
Compiling Debug Views into Your Programs

on OPM programs.
By default, STRDBG displays your source code in 80-column
mode on your green screen. To enable 132-column mode, set
the following environment variable:
ADDENVVAR ENVVAR(ILE_DEBUGGER_1) +
VALUE(ALLOW_WIDE_SCREEN) +
LEVEL(*JOB) REPLACE(*YES)
After you’ve set that variable, STRDBG starts in 132-column
mode in that job. Figure 1 shows what the debugger looks like
in 132-column mode.
Despite all its features, STRDBG has some limits—most nota-
bly, service entry points (SEPs). SEPs make it much easier to debug
noninteractive jobs such as batch jobs, server jobs, web applications,
stored procedures, triggers, and so forth.Although STRDBG sup-
ports SEPs, they are too awkward to be useful. If you’d like to try
them, check out “An Easier Way to Debug Batch Jobs” (January
2007, article ID 53910 at SystemiNetwork.com). However, it’s
much easier to use a GUI debugger.
GUI Debuggers
That said, let’s examine a few GUI debugging tools, as well as
how to set up and use them.
IBM Distributed Debugger (CODE/400). With WDSc
or RDi, you get a copy of CODE/400, which contains the
IBM Distributed Debugger. I’ve included it in this list only for
completeness. Although the distributed debugger still works,
it’s deprecated. As with CODE/400, IBM is phasing it out. My
guess is it will be around for only another two—maybe three—
releases. There’s no point in learning it today; instead, learn the
System i5 or WDSc debugger.
IBM System i5 Debugger. The System i5 Debugger is a
GUI debugging solution that’s included with the IBM i oper-
ating system. Unlike the Distributed Debugger or the RDi/
WDSc debugger, it doesn’t require you to have an entitlement
FIgure 2
Debug Manager window
programs significantly larger because entire copies of
the source code are embedded in the program.
*ALL—Both the listing and source debug views are
included in the program. You can switch between
them in the debugger.
I prefer to use the *LIST option. In today’s world, disk space
is cheap and plentiful. The convenience of the *LIST option
is more important to me than the cost of adding a few extra
kilobytes to my program’s size. The only exception to this rule
is when I use the SQL precompiler. Under that circumstance,
the compiled code in the *LIST view is significantly different
from what my original code looked like when I compiled it, so I
prefer to use the *SOURCE view.
To specify a debug view, simply include the DBGVIEW in the
ILE environment and specify the DBGVIEW parameter when
your program or module is compiled. For example:
CRTBNDRPG PGM(MYPROGRAM) DBGVIEW(*SOURCE)
In PDM, you can specify a debug view by typing option 14 (or
15 for a module) and then pressing F4 to prompt the compile
command. Hit F10 and scroll down to the debug view parameter.
In WDSc or RDi, you can similarly prompt your compile command
to specify a debug view. If you use a different debug view most
of the time, you might consider changing the command default
so that you don’t have to remember to specify the debug view
each time. RDi/WDSc has a Work with Compile Commands option
that you can use to change the parameters that are automatically
specified when the compile commands are run.
OPM programs work similarly to ILE. By default, OPM pro-
grams are compiled with the equivalent of *STMT. For an
OPM program to have a debug view that’s compatible with
the source debuggers, you have to specify OPTION(*SRCDBG)
or OPTION(*LSTDBG) when you compile your program. These
options are equivalent to the ILE *SOURCE and *LIST debug
views, respectively. For example:
CRTRPGPGM PGM(MYPGM) OPTION(*SRCDBG)
In Java, you specify a debug view by specifying the -g
option on the javac command, then run the CRTJVAPGM com-
mand over your class file. This results in the equivalent to ILE’s
DBGVIEW(*SOURCE).With this in effect, you can begin to debug
your Java class file, but the system still needs to be able to locate the
source code. I suggest putting the source code (the .java file) in the
same directory with your .class file to make it easy for the debugger
to find. For example, if you compile your class from QShell:
javac -g HelloWorld.java
system -q "CRTJVAPGM CLSF('HelloWorld.java')"
— S.K.

debugging tools
to ADTS or RDi. Instead, it’s bundled with the IBM Toolbox
for Java, which is included with the IBM i operating system.
The System i5 Debugger runs as a distributed application
with a client component that runs on your PC and a server
component that runs under IBM i. The server component uses
the same underlying debugging support that the STRDBG
tool uses and therefore requires a debug view to be compiled
into your program. Like STRDBG, the System i5 Debugger
supports all ILE languages plus OPM RPG, Cobol, and CL.
Additionally, it has a debugger for PASE.
The PC side is written in Java and consists of three JAR files.
These are pure Java, so they run on any operating system. That
means a lot to me because I often use FreeBSD (Unix) as my
desktop. I’ve tried the System i5 Debugger on FreeBSD, Linux,
and Windows, and it works great on all of them. It also works
on older, slower PCs. A 400 MHz PC with 128 MB of RAM
is adequate to run the System i5 Debugger. (But don’t try the
RDi/WDSc debugger on such an older, slower system!)
Setting up the System i5 Debugger. To install this debug-
ger, you need to download the appropriate JAR files from the
IFS on IBM i to your PC, then invoke the Java code. IBM
provides detailed instructions in the Information Center under
Programming|Development Tools|System i5 Debugger.
Here’s how I did it:
1. I created a new folder on my PC named C:i5debug.
2. I opened the /QIBM/ProdData/HTTP/Public/JT400/Lib
directory in my IFS.
3. I downloaded the jt400.jar and tes.jar files onto the
C:i5debug directory on my PC.
4. I went to http://java.sun.com/products/javahelp and down-
loaded a .zip file of the JavaHelp package.
5. In that .zip file, I found a directory named jh2.0/javahelp/
lib. I copied the jhall.jar file from that directory into my C:
i5debug folder on my PC.
6. I right-clicked my desktop and chose New|Shortcut.
7. I typed javaw -cp jhall.jar;jt400.jar;tes.jar utilities.DebugMgr
for the location of the item.
8. I typed IBM System i5 Debugger for the name of the shortcut.
9. I right-clicked the new icon on my desktop and chose
Properties.
10. On the Shortcut tab, I changed the “start in” folder to C:
i5debug.
Now when I double-click the icon on my desktop, it starts the
System i5 Debugger’s Debug Manager.
The Debug Manager is a great tool for managing connec-
tions to the IBM i systems on which you need to debug pro-
grams. Figure 2 shows a picture of the Debug Manager window.
You can click the Add System button to add as many systems as
you like. When you set up a new system, you tell it which user
ID you use on that system. If you want to have more than one
user ID, you can click the Add User button.
I also recently discovered, quite by accident, that you can
invoke the System i5 Debugger from Navigator for i. If you
start the Run SQL Scripts tool (a great tool, by the way) and
click Run|Debugger, it invokes the System i5 Debugger.
However, this invokes the start debug window, which provides
fewer options, instead of the Debug Manager window, so I pre-
fer the method previously outlined.
Running the System i5 Debugger. To start debugging from
the Debug Manager, click Debug|Start Debug. You choose
whether to submit a new job and run the program you want
to debug, or whether to debug an existing job. There’s even a
“browse” option that shows all the existing jobs for your user
ID (or any user ID you designate), and you can click one of the
jobs to select it for debugging.
If you prefer to start your debugging sessions from the com-
mand line rather than the GUI, you can associate the System
i5 Debugger with the STRDBG CL command. To do this,
make sure the debug server is running by typing STRTCPSVR
*DBG, then invoke the System i5 Debug Manager. After
you’ve done that, running the STRDBG command invokes the
System i5 Debugger GUI instead of the green screen.
The System i5 Debugger (Figure 3) provides an intuitive
GUI interface where you can simply click the spot in your
source code to set/unset a breakpoint. Hover the mouse over a
variable, and the debugger shows its value. It also has features
like “run to cursor location” that let you run the code to a
particular line and then examine the variables. To learn more
about these features, simply look at the options on the menus
or use the Help menu, which explains them.
The one feature that’s more cumbersome in the System i5
Debugger than it is in the RDi/WDSc debugger is SEPs. If it
weren’t for SEPs, I’d use the System i5 Debugger for all my
debugging needs! Alas, SEPs are far more elegant in the RDi/
WDSc debugger, but if you’d like to try the System i5 version for
yourself, see “The System i5 Debugger and Service Entry Points”
(System iNetwork Programming Tips, December 11, 2008, article
ID 57548).
RDi/WDSc debugger. Without any doubt, the debugger
available in RDi is the most powerful debugging tool available
FIgure 3
System i5 Debugger

for IBM i developers today. It doesn’t support PASE, but it does
support everything that the System i5 Debugger supports, plus
the RDi debugger does a nice job of coloring your source code
to make it easier to read.
Like the System i5 Debugger, the RDi/WDSc debugger
has both server and PC components. The server components
use the same underlying
support in the operating
system as STRDBG and
the System i5 Debugger
do. Therefore, you need to
compile your program with
a debug view as explained
in “Compiling Debug Views
into Your Programs.”
In IBM i versions 5.1 to
5.4, entitlement to WDSc
was included with the
Websphere Development
Studio (5722-WDS) licensed
program. That’s the same
licensed program that
included the RPG, C, and Cobol compilers, as well as the
ADTS tools such as SEU and PDM. So if you had any of those
tools, you were entitled to WDSc and could use its debugger.
That changed with the release of IBM i 6.1. In this release,
IBM discontinued WDSc and replaced it with a new licensed
program called RDi. If
you’re already familiar with
WDSc, don’t fear; RDi has
the same look and feel as
WDSc, and it provides the same
debugger—the only caveat being that
RDi is no longer included with the com-
pilers. You have to pay for RDi separately. I rec-
ommend giving RDi a try because it has a ton of other
features, chief among them a nice source code editor with lots
of functionality that SEU and PDM lack.
However, if you develop only in CL and/or Java, it might
not make sense to pay for WDSc or RDi, especially if it’s only
for the debugger! In that case, the System i5 Debugger might
be a better choice.
Another disadvantage of the RDi/WDSc debugger is its per-
formance. It requires a lot more resources than the alternatives,
so unless you have a fast PC with a lot of memory, you’ll find
the performance of the RDi/WDSc debugger to be noticeably
slower than the System i5 Debugger or the green-screen tools.
Another disadvantage is that RDi/WDSc is supported only in
Windows.You can’t use it with another desktop operating system
such as Linux or Mac. I often use a FreeBSD desktop, and the fact
that I couldn’t use WDSc in that environment was a big problem
for me and made the System i5 Debugger a better choice.
WDSc is designed to provide every tool that a programmer
would need to do development on any platform. The result? It
has a lot of options. When you click the debug button, a win-
dow pops up that shows about 20 different debuggers, and each
of them has a plethora of options. I know several programmers
who use WDSc to write their code but don’t use it for debug-
ging because of the complexity.
Still, there’s one killer feature in the RDi/WDSc debug-
ger that raises it above all
the problems. This feature
makes the debugger easy
to use, makes it worth the
higher system require-
ments for the PC, makes it
worth the higher cost, and
even makes it worth using
Windows as your desktop.
That feature is SEPs.
Using the RDi/WDSc
debugger. I won’t discuss the
installation of RDi or WDSc
in this article. Suffice it to say
that you insert the DVD into
your PC and run the setup
wizard, just as you would for any Windows software.
You need to start the server component of the debugger by
typing the command STRDBGSVR (but if you forget to do
this, RDi/WDSc offers to do it for you).
The traditional way to invoke the PC side of the debug-
FIgure 4
Setting a Service Entry Point (SEP) in the RDi/WDSc debugger
FIgure 5
An example of available programs listed in SEP
Ifyouhaven’tlookedoverthemenuof
availabledebuggingtoolslately,you
mightbesurprisedtoseethenumber
oftoolsIBMhasprovideduswith.You
mightevenfinditusefultorethink
yourchoiceofday-to-daydebugging
tools,becausetherearesomereallynice
featuresinthetoolsavailabletoday.

debugging tools
Now that you’ve set up the SEP, the next time the desig-
nated user runs that program, WDSc automatically opens
the debugger and shows you your program code. As with the
System i5 Debugger, you can click the source code to add
breakpoints, hover over variables to show their values, and so
forth. Figure 6 shows what the WDSc debugger looks like.
It’s Your Choice
As I said at the beginning of this article, there are quite a few
tools available for debugging a program. If you’re a bit confused
about which one to use, here’s my rule of thumb:
• If it’s S/36 RPG II code, use STRISDB.
• If you only have green screen available or must do the
debugging while away from your normal workstation (such
as when troubleshooting a really tough bug in production),
use the green-screen STRDBG tool.
• If you are at your usual workstation, use the RDi/WDSc
debugger if you can afford it, and it’ll run well in your envi-
ronment.
• Otherwise, use the System i5 Debugger.
In the end, it’s your choice which tool you use.This article has
taught you about a few new ones and introduced the pros and cons
of each. Don’t be afraid to give some of them a try; one of them
might help boost your productivity.
Good luck, and happy debugging. ■
ger is by clicking Run|Debug from within the Remote
Systems perspective. As I mentioned, there are a ton of
options, but you can focus on the ones that say “iSeries:
Debug Interactive Application” and “iSeries: Debug Batch
Application.” However, since I learned about SEPs, I have
not used the traditional method, so I won’t discuss it fur-
ther. Instead, I explain how to use SEPs.
Service Entry Points
In today’s world of web applications, stored procedures, func-
tions, triggers, and exit programs, it can be hard to predict
which job a program will run under. Therefore, the traditional
method of running Start Service Job (STRSRVJOB) followed
by STRDBG can be tricky because the STRSRVJOB command
requires you to specify the job number. You can’t start a service
job if you don’t know what the job name, user ID, and number
will be. The traditional solution is to add code to your program
to help debug it. Maybe you’ll have it write the job number
to the screen or insert a delay for 60 seconds to give you time
to locate the job number with the Work with Active Jobs
(WRKACTJOB) command. After you know the job number,
you can run STRSRVJOB to service the job, then STRDBG to
start debug. That works, but it’s cumbersome.
With SEPs, you need not know the job number. Instead,
you tell the system which program to debug, and any job that
invokes that program under your user ID (or another user ID
that you designate) automatically displays the program in your
debugger. No need to locate the job that it runs in! No need
to tell the debugger how to invoke your program or find an
existing job or anything like that. Just tell it which program and
which user ID—and presto—the system takes care of the rest.
SEPs are supported in the green-screen source debugger
(STRDBG), the System i5 Debugger, and the RDi/WDSc
debugger. However, I find the latter to be the most elegant way
to use SEPs, so that’s what I’ll focus on here.
In RDi/WDSc, it’s easy to use SEPs. Just locate the program
object in the Remote Systems pane. If you use RDi/WDSc
for coding, you already use this pane to browse for the source
members that you want to edit; however, in this case you’re
looking for the compiled *PGM object instead of a member.
You can either browse the library list for the program object or,
if you know the name, use iSeries Objects|Work With Objects
to create a filter that points directly to your program.
Once you’ve found your object, you can right-click it and
choose Debug As (Service Entry)|Set Service Entry Point,
as in Figure 4. If you’ve already started the debug server, that
should be all you need to do. When you click that option,
it shows you a list of all the programs you have SEPs on, as
Figure 5 shows.
By default, it runs only the SEPs for the user ID that RDi/
WDSc is connecting under. To debug programs under a dif-
ferent user profile, highlight the program in the SEPs list
and click the pencil icon to open a dialog box where you can
change the user ID.
FIgure 6
The WDSc debugger
Scott Klement(iSN@scottklement.com)
istheeditoroftheSystem iNetwork Programming
Tipsemailnewsletter,aSystem iNEWStechnical
editor,andaForumProonSystemiNetwork.com.Heis
alsoasubjectmatterexpert(SME)atCOMMONandthe
ITmanageratKlementSausageCo.,Inc.
About the Author:

Klement_0902_v2F (complete article)

More Related Content

What's hot

Viewers also liked

Similar to Klement_0902_v2F (complete article)

Klement_0902_v2F (complete article)