• Remote System Explorer (RSE), which gives you access to all your iSeries objects
• iSeries Projects to keep your work organized
• The Remote Systems LPEX editor
• Verify and compile interfaces
• The Integrated iSeries Debugger

Solid, easy-to-use debugging tools are an integral part of any modern development environment. Because Development Studio Client 5.0 gives you the ability to develop native iSeries applications as well as Web and Java applications that may or may not run on the iSeries, it also provides debugging facilities for various runtime models.

Those of you who trust the modern programming tools to help find bugs will find the new Integrated iSeries Debugger quite convenient for your daily RPG, COBOL, CL, Java, C, and C++ debugging needs. You can set breakpoints while you work with the source of your program in the iSeries editor. When you start the debugger, those breakpoints will be in effect. Step through your code, monitor variables and storage, display source for various entries on the call stack, get easy access to debugging Toolbox program and service program calls, debug client/server applications, and much more, using a single debug perspective!

Development Studio Client 4.0 did not have an Integrated iSeries Debugger. Instead, users had to launch the well-known IBM Distributed Debugger, which ran as a separate process and did not look anything like an Eclipse component. Development Studio Client 5.0 users still can access the Distributed Debugger, but it is included in the product mainly to support older releases of WebSphere Application Server on the iSeries and VisualAge for RPG.

Debug Perspective

You will find that all debuggers share the same debug "perspective"--a collection of various resizable views within the same window. This way, you can leverage your development skills from one runtime model to another. Figure 1 shows a typical layout of the debug perspective. The "Debug" view in the top left corner presents all of the debug-specific actions--step, run, suspend, etc. At the same time, all the jobs/processes under debug and their respective threads and call stacks are listed within this same view. Your source code is shown in the source editor/browser view, which typically takes up most of the real estate of the debug perspective. While Java source will have an associated outline view of your class, Development Studio Client 5.0 provides this feature in the RSE perspective for languages like RPG and COBOL.

Figure 1: A typical debug perspective layout shows actions, jobs, code, and more. (Click images to enlarge.)

The top right corner of the debug perspective contains a number of views that overlay each other. Switching between different tabs will give you a way to look at the breakpoints, variables, and storage and will list programs that are currently under debugger control. Different features are available for different languages and host platforms. We will give more details on this when we discuss iSeries-specific features.

Since Development Studio Client 5.0 is built on top of Eclipse technology, views can be easily added, removed, or rearranged within the Debug or any other perspective. For example, we recommend that iSeries users remove Registers and Expressions views, since these don't apply to iSeries. Likewise, it may be useful to add a Properties view that gives detailed descriptions of various debug elements, like breakpoints or call stack frames. To remove a view, just press the x in its top right corner. To add the Properties view, select Window -> Show View and select Properties if it is listed or Other -> Basic and then Properties. To restore the original Debug perspective, select Window -> Reset Perspective.

Typically, the Debug perspective comes up every time you invoke a debugger. However, you can also bring up the Debug perspective manually using Window -> Open Perspective.

If the Debug perspective has already been opened before, yet you are currently working in some other perspective (for example J2EE, RSE, or iSeries Projects), you can switch back by simply selecting the little bug icon in the left margin of the workbench window.

Setting Up the Environment

Before you can debug your application or access any object on the iSeries using Development Studio Client 5.0, you need a connection to your iSeries system. Start the workbench by selecting Start -> Programs -> IBM WebSphere Studio -> Development Studio Client for iSeries. This will display a dialog asking you for the directory for the workspace, where everything you are working on locally is stored. Once you specify the directory and click OK, the Development Studio Client workbench comes up.
To access your iSeries objects, you want to be in the RSE perspective, which allows you to invoke the actions for your host development. To open any perspective, select Open Perspective from the Window menu and select the desired perspective. If it is not listed, click on Other... to get a list of all available perspectives and select it from there. See Figure 2.

Figure 2: Use the drop-down menu lists to open different perspectives.

The RSE, like any other perspective, consists of a combination of views: the Remote Systems view on the left, which lists all iSeries systems that the workbench knows about; the Edit view in the middle, where you work with your source; the Outline view for easy navigation of the source; a Properties sheet; and a tabbed notebook for host-specific information.

To define a connection between a workstation and the iSeries, simply expand the New Connection node in the Remote Systems view and select iSeries by double-clicking it or clicking on the plus sign (+) in front of it. This displays the New iSeries System Connection wizard (Figure 3). The profile name defaults to the workstation name, so you can just press Next. The communication between the workstation and the iSeries uses TCP/IP. You only have to specify the host name of your iSeries. The default connection name will match the host name. Notice that this is the name that will be listed in the Remote Systems view.

Press Finish to create your new connection.

Figure 3: Use the New iSeries System Connection wizard to establish your connection between the workstation and the iSeries.

To access iSeries objects, expand the connection. This will list four iSeries subsystems: iSeries Objects, iSeries Commands, iSeries Jobs, and IFS Files, each with its own set of predefined filters to which you can add your own. Expanding iSeries Objects lists a number of filters, including the library list as it is initially set by your user profile. The popup menu of the objects (right-click the object) lists all default actions that are available for the selected type of object.

Before you can run or debug your application, you have to set your library list. You can do that by dynamically changing your library list from the popup menu, but a better and persistent way to do this is by adding the required libraries to the Properties of the iSeries Objects. Select Properties from the popup menu of the iSeries Objects, select Initial Library List in the properties tree (see Figure 4), and enter the library names either to the top or bottom of your library list. Here, you can also set a current library. Don't forget to press the Add button. In this window, you can also reorder the entries you made already. Every time you start this connection, the libraries will be added to the libraries from your user profile.


Figure 4: Set your library list by adding the required libraries to the Properties of the iSeries Objects.

Note: The properties are set when you log on to the connection. Changes to the properties that are added afterward will come into effect when you disconnect and then reconnect. Use the popup menu of the connection or iSeries Objects to disconnect.

Tip: You can create multiple connections to the same iSeries host and specify a different library list for each one.

Now, everything is set up so that you can work with your iSeries objects. Expand the Library List in the iSeries Objects subsystem. The first time you do this, you are prompted to log on. You can choose to save the user ID and password information to avoid being prompted again, even after rebooting your workstation.

Preparing Your Program for Debugging

Editing

To open a source member in the LPEX editor, expand the source file and double-click on the member you want to edit. The source is displayed, and a tab at the top of the source view allows you to switch easily between different sources that you want to work with at the same time. These could be different modules of the same program or a calling and called program, for example. See Figure 5.

Figure 5: The RSE editor allows you to work on more than one source member at a time.

If you are a CODE user, you will find the editor's user interface and functionality familiar. Notice that the source in the editor gets tokenized the same way as in the CODE editor, which means that the different language elements get displayed in different colors to enhance readability. This helps you find errors in your source faster. If you, for example, accidentally marked a line as a comment, it will be displayed in just one color, and you will notice your error right away.

For those of you who are just starting to work with a workstation editor, it may be easier to start with functions that are the same as in SEU. You can use most of the SEU line commands--such as I, D, M, and MM--in the sequence number column. As you would expect, pressing F4 will prompt you for the selected command, and pressing F1 will display the command description from the online Language Reference.

A significant portion of working with an editor involves finding a specific place in the source. What you want to avoid, especially in large programs, is scrolling until you find the line you are looking for. There are, of course, the different Find options available from the Edit menu. Like in CODE editor, there is also the option to filter source. You can filter by date, comments, SQL statements, or other categories, depending on the programming language. Filtering by comments will give you a view of all the comments in your source, suppressing all other lines. This allows you to read through the text much faster. A plus sign (+) in front of the number column indicates wherever source lines are not currently shown. Clicking on the plus sign will show all lines up to the next comment.

To get all of the source to display again, select Show All from the Edit menu or the popup menu in the source view.

The Outline view gives you an overview of the structure of your program. For RPG, it lists global definitions like the files used in the program, indicators and fields, and subroutines and procedures and their parameters and local definitions. Double-clicking on any entry in the Outline view takes you directly into the source at the position of the first occurrence of the selected entry.

By default, every line of code you enter or change is syntax checked as soon as you move the cursor off that line.

Make all your changes and save the source either locally or back to the iSeries.

Verify your source locally to ensure a clean compile on the iSeries. The Verify action is available from the popup menu of the source member in the RSE.

Compiling

Once you have verified your source, you use a compile command in the RSE. Select your source and pick the appropriate compile command from the popup menu. The default debug option for compile from the workstation is different from the compile commands on the host. For ILE, Debugging Views is set to *SOURCE; for non-ILE, *SRCDBG is the default. Click the Advanced button to get all the options for the compile command listed in the dialog. See Figure 6.

Figure 6: The CRTRPGMOD screen provides your RPG compile options.

Once you've created the module, scroll up to it in the RSE view. Then, from the module's popup menu, select CRTPGM or CRTSRVPGM. See Figure 7.

Figure 7: Now, it's time to create your program.
You may have to press the Refresh button in the Remote Systems toolbar to see a newly created object.

Debugging iSeries Programs

Starting the Integrated iSeries Debugger

The RSE perspective is where you typically initiate your development actions. You just made changes to your code using Remote Systems LPEX Editor, and you verified and compiled your source, but your application is not behaving as intended. If you have a good idea as to which program or service program is at fault, just select it in the RSE, right-click, and pick one of the actions from the Debug As menu. For example, if your application does not have any screen I/O, you can select Debug As -> Batch (see Figure 8). Be sure that your library list for the RSE connection you are using is set up correctly, as described earlier.

Figure 8: Select the program that's not behaving properly and then use the debug options offered in the Debug As menu.

The Debug perspective will come up, and the iSeries debug session will start (see Figure 9). Your program source will be displayed in the debugger source browser in the middle of the perspective. The current line of execution is highlighted in the view and marked with an arrow in the prefix area (the left margin in the source browser). For visual convenience, all executable lines are in blue, while comments and other non-executable statements are in dark cyan (these colors are not customizable).

Figure 9: The iSeries debug session highlights each line of code as you work on it.

Most languages support *SOURCE, *LISTING, and *STATEMENT debug views if the program or module was compiled with one of these debug options. Right-click anywhere in the source browser, and use the Switch View menu option to switch between available views (see Figure 10). The majority of debug actions can be performed from the source browser (e.g., stepping, running to a specific line, setting various kinds of breakpoints, displaying variables and storage). There is usually a very intuitive (point-and-click) way of performing these operations.

Figure 10: The Switch View menu option allows you to switch between available debug views, such as *SOURCE, *LISTING, and *STATEMENT.

Tip: If you would like to get an editable version of your source while in the Debug perspective, select Edit... from the popup menu in your source browser. The source will open in the iSeries editor.

Specifying Debug Session Preferences

If you would like to debug an application that accesses production libraries on your iSeries, you must specify the Update Production Files setting. If you use one of the prompt options to start up the Integrated iSeries Debugger, you can specify this value in the dialog box. However, if you invoke the debugger via a popup menu from the RSE, you will need to use the Preferences dialog to set the value. The Windows->Preferences menu will bring up the dialog. Select Debug->iSeries Debug to display the required page.

Integrated iSeries Debugger needs to know the IP address of your workstation. Typically, that setting can be figured out programmatically. However, IBM has discovered that, in certain network configurations, the IP address returned by the socket APIs does not yield the actual IP address that your workstation is known as. IBM plans to fix this bug in the next release, but meanwhile, you can manually specify the IP address of your workstation via the Integrated iSeries Debugger preference page under the Workstation Host Name Address control.

Controlling Program Execution Flow

Integrated iSeries Debugger, just like a green-screen debugger, supports two stepping modes: step over and step into. Both actions are available from the toolbar and popup menu of the Debug view (top left corner of the debug perspective) as well as from the Run menu of the main window. The step into action should be used when execution is stopped at the call to some routine that you would like to debug. In any other situation, step over and step into both go to the next statement. The corresponding shortcut keys are F5 for step into and F6 for step over.

Note: If the routine you are about to call and any routines that it calls are compiled without debug data, the step into action has the same effect as step over.

The Resume (or Run) action is also available from the toolbar and popup menu of the Debug view and from the Run menu. F8 is the corresponding shortcut key. The Run To Location command (available via the popup menu in the source browser and the prefix area) is very useful when you want to stop at a specific location but do not feel like setting a line breakpoint for future use. Run To Location is context (line)-sensitive and hence has neither toolbar button nor shortcut key.

Line breakpoints can be set by double-clicking in the prefix area of any executable line or by using the popup menu in the source browser and the prefix area. Alternatively, you can use the Add Line Breakpoint wizard, which is invoked from the popup menu in the Breakpoints view (see Figure 11).

Figure 11: Bring up the Add Line Breakpoint wizard.

In particular, to set a conditional breakpoint, you will need to enter a valid Boolean expression in the Expression field on the second page of the wizard (see Figure 12). Once a line breakpoint has been set, it will show up as a blue dot with a checkmark in the prefix area of the corresponding line.

Tip: If you are setting a line breakpoint inside a loop but would like your program to stop, for example, only every third time through the loop execution, enter 3 in the Every field within the Frequency group on the second page of the Add Line Breakpoint wizard (Figure 12). Similarly, you can use From and To fields to control how often your program will stop.


Figure 12: These screens in the Add Line Breakpoint wizard walk you through the steps.

Similarly, watches are set through the Add Watch Breakpoint wizard. In the source browser, double-click on a variable that you would like to set a watch on, and it will get selected. Bring up the popup menu (using a right-click), which will contain an Add Watch Breakpoint option (see Figure 10). In this case, the Address Or Expression entry field will already be populated with the selected variable. Alternatively, you can use a popup menu in the Breakpoints view (see Figure 11) to bring up the same wizard. Leave the Number Of Bytes To Watch set to zero if you want to watch a variable in its defined length.

Using watches can be handy when you want to monitor changes of a variable or variables as you run or step through the code. Watches can be set for any valid variable. If the content of a watched variable changes during the execution of your program, execution stops, and the user is notified about the variable being changed and given control. The program execution stops at the next statement after the one that caused the change.

Note: If the variable gets changed in a non-debuggable module, the watch notification message will also be displayed. The program execution will then stop at the next debuggable statement after the call.

All line breakpoints and watches that are set successfully are listed in the Breakpoints view (see Figure 11). From that view, you can modify breakpoint properties and enablement. Currently, the Integrated iSeries Debugger supports line breakpoints and watches. However, IBM plans to add advanced breakpoint features.

Displaying Variables

One of the major advantages of the Integrated iSeries Debugger is its capability to display many program variables at the same time in one monitor view. If you want to quickly examine a variable, simply position the cursor over that variable in the source browser, and a little popup window will show its value. This works well for scalars, but complicated structures and arrays require more-structured viewing space.

For languages like C, C++, and Java, you can take advantage of the Variables view that displays the list of all local variables in scope. Unfortunately, the current version of the Integrated iSeries Debugger does not support the Variables view for languages like RPG, COBOL, and CL. But not to worry; you can add your variables to the more permanent Monitors view.

Double-clicking on a variable in the source browser will select that variable. A right-click will bring up a popup menu from which you can select the Monitor Expression option (see Figure 13). The top right part of the workbench window will switch focus to the Monitors view (if it's not already in focus), and your variable will show up in that view along with other variables that you may have added thus far.

Alternatively, you can use the Monitor Expression dialog that is accessible via the plus sign-like toolbar button in the Monitors view (see Figure 13).

As you step through your program, variables in the Monitors view get updated to reflect their up-to-date values. Variables that have changed their value as a result of the last step or run are colored in red. Therefore, if you end up with a large number of variables in that view--say over 50--you might notice that debugger performance degrades slightly. At this point, consider removing some of the variables from the Monitors view.

Tip: If you select a variable in the Monitors view and then select another one while holding the Shift key, all variables between those two will get selected. You can remove them all in one shot either by using the toolbar button that looks like a minus sign (-) or by simply pressing the Delete key.

Figure 13: Use the Monitor Expressions windows to view your variables.

Data structures and arrays are displayed in the tree format. You can expand the entire tree to see all the fields or array elements. The Debugger also gives you the ability to expand only parts of the data structure or to see only part of the array. This is handy if you would like to see multiple variables at the same time.

Double-clicking on a variable in the Monitors view makes its value editable. At this point, you can type in any valid value and press Enter. The value of the variable will be changed. Alternatively, you can use the Monitor Expression dialog to enter a new value. Anything that is valid on the EVAL command will work here as well, but no need to type EVAL! Right-clicking on a variable in the Monitors view brings up a popup menu that includes an option to change the variable's representation.

Documentation for the Integrated iSeries Debugger is always at your fingertips. Just press F1. To get more help, simply follow the corresponding iSeries links. Keep in mind that the same debug perspective is used for Java debugging as well, so some of the information will not apply to RPG, COBOL, or CL.

Debugging Interactive Applications

Thus far, we have covered all the major features of the Integrated iSeries Debugger and its tight integration with the RSE. Let's look at a more-sophisticated iSeries application, which consists of a program (PGM_A) that calls a service program (SRVPGM_B). Suppose PGM_A puts up a 5250 screen and, depending on user input, calls either procedure PROC1 or PROC2 in SRVPGM_B. In addition, you suspect that a problem you are chasing occurs inside PROC1; therefore, you are interested in debugging only that procedure.

In this scenario, simply select SRVPGM_B in the RSE and use the Debug As -> Interactive option from the popup menu. A Debug Launch Configuration dialog will come up. The What To Debug page (where you indicate the name of the program or service program you wish to debug) will be pre-filled with the name of the service program you selected in RSE. At the same time, the How To Start page (where you specify how your application should be invoked) in that same dialog will initially show a little error icon. You need to switch to that page and fill in the program name (and parameters, if any) for the CALL command (see Figure 14). If you use a command to start your application, you need to enter your command name in the Command To Start Application area. Optionally, you can use the Prompt... button to fill in all required parameters.

Note: The Command Prompt dialog is currently implemented using Swing Java components and therefore is not modal to the workbench. This sometimes causes confusion, as the dialog can be easily hidden behind the workbench and other windows on your desktop.

Figure 14: Some fields in What To Debug are automatically filled in. Others must be filled in manually.

In addition, it's a good idea to name this launch configuration so that in the future it can be identified and invoked from the history of all debug launches. Specify any unique name (for example, SRVPGM_B) in the Name field at the top of the dialog. Once all required fields are filled in, the Debug button at the bottom of the Launch Configuration dialog will become enabled and you can fire up your debug session.

One scenario in which Development Studio Client requires a 5250 emulation session is when you run or debug an interactive application. If you don't have an active RSE emulation session already, you will be prompted to start a 5250 session and to run the STRRSESVR command, which will associate that emulator session with the Development Studio Client communications job (see Figure 15).

Tip: You can simply cut and paste the complete STRRSESVR command from the prompt window. See item 3 in Figure 15.

Figure 15: For some debug operations, you'll need a 5250 emulation session.

Once the RSE server is invoked in the 5250 session, the prompt dialog will dissapear and the debug session will start. Your application will be executing in that 5250 emulator window, and that's where all your screens will be displayed.

Debugging an iSeries Job

If setting up your application's environment is laborious or you would like to start debugging an application while it is already running, the debugger allows you to specify the name of the job of interest. In such scenarios, you might want to set your breakpoints before even starting the debugger. If you are aware of the problem areas in your program and you have the source code handy, you can set line breakpoints before starting a debug session. Depending on your development model, you may either use the RSE to open your source or create a local copy in an iSeries project.

To set a line breakpoint, simply double-click in the prefix area of your source. A Breakpoint dialog will come up asking you to specify the Library, Program/Service Program, and Module name that the source file corresponds to. Since the debugger is not started yet, you must provide this information for the first line breakpoint you are setting in the source. You will not be prompted for subsequent breakpoints.

Tip: By default, Program/Service Program and Module names are filled in with the name of the source in the editor. Make sure you change these values if this assumption is incorrect. If incorrect information is specified, the breakpoint will not be honored during the debug session.

Once you fill out all entry fields and press OK, the breakpoint will show up in the prefix area of your source as a blue dot. At this point, it is not active because there is no debug session around. The next debug session that you start will activate all source file breakpoints, and they will show up as blue dots with the checkmark to the left in the prefix area as well as in Breakpoints view.

To start the debugger, you need to bring up a Launch Configurations dialog and create an iSeries: Debug Job launch configuration. Select the down arrow to the right of the bug icon on the toolbar and pick the Debug... menu option (see Figure 16) to bring up the Launch Configurations dialog. Then, select iSeries: Debug Job from the list of configurations on the left. From the popup menu (right-click) select New (alternatively, you can use the New button at the bottom of the configurations list). You will need to supply the name of your connection, the iSeries job and, optionally, the Program/Service Program name to debug. Finally, press the Debug button to start the debug session.

Tip: If you use the Browse button to get a list of jobs, you can use wild card characters to provide job name filters. Only jobs that match that filter will be displayed. If your iSeries has a large number of jobs, such a technique can save you time.

Figure 16: To start the debugger, you need to bring up the Launch Configurations dialog.

Once the debugger is ready, you will be prompted to resume or invoke your application on the iSeries host. Make sure that your application is executing in the iSeries job that you specified in the Launch Configurations dialog, and then press the OK button on the message. At this point, your program source will display and you will have control of your debug session.

Tip: If you specify the name of the program to debug, Terminate Debug Session On Program Completion will be selected by default. In this case, your debug session will complete once the program completes. Note that this option is not available for service programs.

Tip: If you specify the name of the program/service program to debug and leave the Step Into checkbox selected, program execution will stop at the first debuggable line in that program/service program. If the program/service program name is omitted, program execution will stop at the next debuggable line in your application. If you would like to run till the next breakpoint is hit, simply deselect the Step Into checkbox.

Give It a Try!

Development Studio Client 5.0 offers a rich development environment not only for Java programmers, but also for RPG and COBOL programmers. All tasks--from editing to debugging--are integrated into the same work environment, thus shortening the learning curve for the new tools.

So go ahead. Give Development Studio Client and Integrated iSeries Debugger a try, and nobody will know that those bugs ever existed in your code!

Inge Weiss is a software engineer in the iSeries Application Development Tools Center at the IBM Canada Toronto Laboratory. She has a degree in Computer Science from the University in Hamburg, Germany. Inge worked as a systems engineer for midrange systems at IBM Germany and joined the IBM Canada Toronto Laboratory in 1985. She has worked on different projects but spent most of the time in the iSeries tools area. Currently, she is a member of the iSeries Debugger development team. Inge is a frequent speaker at COMMON conferences.

Vadim Berestetsky is a software engineer at the IBM Canada Toronto Laboratory. He has a Computer Science degree from the University of Toronto and is currently finishing up his Master’s thesis. Vadim joined the IBM Canada Toronto Laboratory in 1993 and has worked on various projects within the iSeries tools area. Currently, he is a technical team lead of the iSeries Debugger development team. Vadim has previously published technical articles, and he has been a speaker at COMMON and ITSO conferences.