Klement_0902_v2F (complete article)

Viewpo

int industry watch strategic directio

ns solutio

ns

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 DebuggersLet’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-

Squash Bugs with IBM Debugging Tools

Fix your iBM i code with one of these debugging tools

Illus

tratio

n by

Mik

e Fr

ieha

uf

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 DebuggersThat 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.javasystem -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

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.

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 ChoiceAs 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:

• Ifit’sS/36RPGIIcode,useSTRISDB.• Ifyouonlyhavegreenscreenavailableormustdothe

debugging while away from your normal workstation (such as when troubleshooting a really tough bug in production), use the green-screen STRDBG tool.

• Ifyouareatyourusualworkstation,usetheRDi/WDScdebugger if you can afford it, and it’ll run well in your envi-ronment.

• Otherwise,usetheSystemi5Debugger.

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 PointsIn 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 ([email protected])

is the editor of the System iNetwork Programming Tips email newsletter, a System iNEWS technical

editor, and a Forum Pro on SystemiNetwork.com. He is

also a subject matter expert (SME) at COMMON and the

IT manager at Klement Sausage Co., Inc.

About the Author:

Documents

Klement_0902_v2F (complete article)