The Java-Based iSeries System Debugger

by Kevin Vandever

For so long we iSeries programmers have used the green-screen debuggers STRDBG (Start Debug) and STRISDB (Start Interactive Source Debugger) to solve our debugging needs. Although they're not the best or the most robust in the industry, these debugging tools have, for the most part, done the job quite satisfactorily. However, in the last few years it seems as if system debuggers have been falling out of the sky and now we iSeries programmers have many options from which to choose. In this article, I am going to talk about one of those options.

Java to the Rescue

Available as a base product on V5R2 and via a PTF on V5R1 (Server PTF is SI05799 and client PTF is SI06301), the iSeries System Debugger is a Java-based software solution, and as such it can be installed and run on any platform where the Java language is allowed. This means you can now debug iSeries programs in a GUI environment, from the comfort of your own desktop. The purpose of this article is to explain some of the requirements and capabilities of the iSeries System Debugger and to allow you to start debugging programs--if you should ever have the need, that is.

Installing the iSeries System Debugger

The iSeries System Debugger is packaged as part of the IBM Toolbox for Java. If you do not have the Toolbox for Java jt400.jar file already installed on your client, you will need to install it when you install the iSeries System Debugger. To install the debugger, complete the following steps:

• Install at least Version 1.3 of the Java Runtime Environment (JRE) on your client. You can also install the Java 2 Software Development Kit (J2SDK), but it is not required to run the debugger.
• Install JavaHelp. The jhall.jar file contains the classes necessary to allow you to use the help function in the debugger. This is the same help software I installed to use the help function when prompting iSeries commands in Java. For more information, check out the article "Prompting iSeries Commands: A Closer Look."
• Install the IBM Toolbox for Java. You can follow the link to IBM's Toolbox site and follow the instructions there, or you can simply copy the jt400.jar file from your iSeries to your client, since that is the only JAR file you will need. The jt400.jar file can be found on your iSeries at /QIBM/ProdData/HTTP/public/jt400/lib/jt400.jar.
• Copy the iSeries System Debugger tes.jar file to your client. This JAR file can be found on your iSeries at /QIBM/ProdData/HTTP/public/jt400/lib/tes.jar.
• Modify the CLASSPATH on your workstation client to include the pertinent JAR files that you just installed: jt400.jar, tes.jar, and jhall.jar. You can set the CLASSPATH on Microsoft Windows 2000 or XP by clicking Start, Settings, Control Panel, System, Advanced, Environment Variables, and editing the CLASSPATH environment variable at either the system or user level, whichever is appropriate for you. When editing the CLASSPATH, you type in the path where the JAR files can be found. Another way to modify the CLASSPATH is by using the command line by clicking Start, Run, and typing CMD at the command line prompt. This will bring you to a DOS prompt screen, where you can then set the CLASSPATH as follows:

      SET CLASSPATH=c:\your folder hierarchy\tes.jar;c:\
      your folder hierarchy\jt400.jar;c:\your folder hierarchy\
      jhall.jar

System Requirements

Now that you know how to install the debugger, I should probably let you in on the client requirements:

• CPU: A minimum of 400 to 500 MHz processing power.
• Memory: A minimum 128 MB (256 MB recommended).
• Software: Follow the installation instructions above to ensure that the proper JAR files are installed and that the CLASSPATH environment variable is set correctly.

Running the iSeries System Debugger

Now that you have your system set up, you probably want to run the debugger, right? There are a couple ways to run the debugger, and you can pick whichever one suits your style. First, you can run the debug manager from the command line (or from DOS prompt, for you old school folks) by entering the command java utilities.DebugMgr. Case counts with the name, so make sure you enter it as I have shown. The debug manager allows you to manage a list of iSeries systems. From this applet, you can add or remove iSeries systems and users of those systems, you can start the debugger on any of your current systems, and you can register a user profile and system so that when that user on that registered system starts the STRDBG CL command from a 5250 emulator, the GUI Debug applet will be displayed, instead of the green-screen version.

If you are not into the management of the users and systems and just want to jump to the debugging, you can go right into the debugger by entering java.utilities.Debug on the your workstation command line. After you provide the system, user ID, and password, and optionally a program to debug, you'll be presented with the main panel of the debug applet. This panel is broken up into multiple windows for your convenience. On the top left, you will see a list of programs, modules, and class files that you want to debug, as well as any breakpoints you've set. On the top right, the source code is displayed, and from this display you can set breakpoints and accomplish all sorts of other debugging tasks. On the bottom left is a panel displaying the variables (local and global), as well as a system console to show any output and allow you to enter commands. The bottom right window displays the call stack entries, as well as threading and memory information. You can resize or remove any of the windows to help you set up the display to fit your needs. And remember, we installed the JavaHelp JAR file, so don't be afraid to press F1 and find out all the cool things you can do with this debugger. If you don't want to pop the applet to accept the system, job, and user information, you can send those arguments as parameters when you call the debugger, as follows:

 java utilities.Debug <args>
where <args> represents any of the following command arguments:
-u = User 
-s = System name or system IP address 
-j = Job description, in the form of: job number/job user/job name 
-p = Program to run, in the form of: program library/program name 

As I mentioned before, if you register your client using the debug manager, you can use the GUI debugger by entering the Start Debug (STRDBG) CL command from an emulation session. You can also launch System Debugger directly from the System Debug Manager.

The What's and When's

You can use the debugger on almost any high-level language that can run on the iSeries (I think REXX is the only language not included, but I may be wrong). The following is a list of languages you can debug, so why don't we look at it from that angle. I hope that your language is listed. If not, it may be time to learn a new one!

• ILE C and C++
• ILE RPG
• ILE COBOL
• ILE CL
• Java
• OPM RPG
• OPM COBOL
• OPM CL

With the debugger, you can easily debug interactive jobs, but you can also just as easily debug batch jobs, as well as jobs that are already running and jobs that are on hold. The debugger even comes with a browse option for locating a job. It also comes with the ability to view local and global variables, call stack entries, memory, and threads. There are advance stepping functions not available with the green-screen version, including running the code to the cursor location even if that means skipping breakpoints. You also are able to use Windows pull-down functions to navigate to different source views, as well as manipulate breakpoints by clicking directly on the line number. Larger source members (and we all still have some of those around) can be displayed in pieces and easily navigated by using the Goto and Find menu options.

Who Thought Debugging Could Be So Fun?

I have introduced you to the Java-based iSeries System Debugger and touched on some of the features available to you. I only scratched the surface. Install the necessary components and give it a whirl. I think you'll be impressed. In fact, don't be surprised if you start adding bugs to your programs on purpose or wander around your shop volunteering to debug everyone else's code. Don't worry, these are natural reactions to the awesome capabilities of the iSeries System Debugger, and they will eventually subside. The important thing is to use the functions and features available to you to debug complex iSeries programs more effectively and efficiently.

Editor's Note: In order to start Java, the degug hub has to be started on the iSeries. On V5R1 use the command CALL QSYS/QTESSTRSVR, and on V5R2 use the command STRTCPSVR *DBG.

Sponsored By PROFOUND LOGIC SOFTWARE

Announcing RPGsp! RPG Smart Pages (RPGsp) is an Integrated Development Environment for creating dynamic web applications. If you are a shop with strong RPG skills, you can start developing e-Business / e-Commerce or Intranet Applications IMMEDIATELY! It's easier than traditional RPG/DDS development! RPG Smart Pages (RPGsp) integrates an RPG aware WYSIWYG HTML Designer with RPG-Alive enabled Code Editing Capabilities, allowing you to create and compile dynamic Web applications as well as traditional RPGLE programs from one sophisticated GUI development environment! For a Free Trial or more information, contact Profound Logic Software at www.ProfoundLogic.com