Because my programs never have any bugs, I've never needed to debug them. << SMACK! >> Oh, sorry, I was dreaming there for a moment. It was such a nice dream, too.

Every programmer has to debug programs, but debugging programs that aren't run in an interactive job can be tricky. Batch jobs, trigger programs, never-ending programs, server programs, exit programs, CGI programs . . . all these types of jobs are run in the background by some sort of automatic process. Finding the background job and running the debugger on it can be a challenge.

Traditionally, programmers have debugged batch jobs by holding the job queue, running the Start Service Job (STRSRVJOB) command to specify the job to debug, and then running the Start Debug (STRDBG) command. Finally, they release the job queue. What a pain! And when you're not issuing the SBMJOB command yourself, how do you even know which job queue to hold?

In V5R2, the folks at IBM provided an easier way called Service Entry Points (SEP). This article discusses how you can use SEP to debug your programs, both in WDSc and in the green-screen debugger.

Using SEP from the Green Screen

With the standard STRDBG tool, you can use SEP from a green-screen terminal. Unfortunately it's rather awkward. But it works, and sometimes, especially when you're out in the trenches, you have no access to the more advanced debugger in WDSc.

Here's how you set a SEP breakpoint:

1. Start debugging the program in your current job by typing the following command:

     STRDBG PGM(my-library/my-program)

2. Review the source code on the screen. In the leftmost column of the screen, you see the line numbers that the debugger uses to refer to each line of code in your program. Find the line number of the statement in which you want to place the SEP breakpoint.

3. At the command line in the debugger, use the sbreak command, followed by the line number at which the program should stop. If you want a different user aside from the current one, you should also specify the user when you run the sbreak command. For example, if the line number is 145 and the user is QUSER, you type the following:

     sbreak 145 user QUSER

4. When the break point has been set, press F12 to let the debugger run.

5. As soon as the specified user runs your program and reaches the breakpoint on any job anywhere in the system, the user's program stops, and a notification message is sent to the terminal on which STRDBG was run.

   If you press the F1 key to get extra information about the message, you get a display like the following:

   Additional Message Information Message ID . . . . . . : CPI1903 Date sent . . . . . . : 01/09/07 Time sent . . . . . . : 23:40:07 Message . . . . : Service Entry Point has stopped at line 2 in program LIBSCK/TESTCALL in job 584077/KLEMSCOT/QPADEV000R. Cause . . . . . : Service Entry Point has stopped at line 2 in program LIBSCK/TESTCALL in job 584077/KLEMSCOT/QPADEV000R. Recovery . . . : This program must be debugged from a servicing job. Do a Start Service Job (STRSRVJOB JOB(584077/KLEMSCOT/QPADEV000R)). Then do Start Debug (STRDBG) on the spawned job from where the STRSRVJOB was done. Set a local breakpoint at or after the Service Entry Point. Return to the original job and press enter to release the spawned job. Bottom Press Enter to continue. F1=Help F3=Exit F6=Print F9=Display message details F10=Display messages in job log F12=Cancel F21=Select assistance level

   
   

6. Here's the part that makes the green-screen tool awkward: To use this information, you have to run STRSRVJOB and STRDBG on the job number and program reported in the preceding notification message. But you can't run it in the same job! You can't issue STRSRVJOB in the same job, because that job is already in debug. You can't end the debug session in that job, or you'll release the SEP breakpoint.

   You have to go to a separate 5250 window and key the following commands:

   STRSRVJOB JOB(584077/KLEMSCOT/QPADEV000R)
   
   STRDBG PGM(my-library/my-program)

   The first line can be copied and pasted from the notification message. Make sure that you use the same job information that appeared in the notification message! The second command, the STRDBG command, is needed to start debugging on the new job.

7. Set a new breakpoint (it can be in the same place) so that the program stops in the servicing job, and debug it as you typically would. After this breakpoint has been set, the SEP breakpoint gets removed, so you can feel free to end the debugger on the first 5250 screen.

Like I said, some parts of this process are awkward. In particular, the fact that you need to use two jobs, and you have to manually start a service job and set a breakpoint in the second one! You'll have none of that awkwardness if you use WDSc's debugger.

As far as I can tell, the reason that you use a separate job is because you're already in debug (for the SEP) in the first one. Because you can't start a service job while you're in debug, you have to do it in a separate window. I hope that IBM fixes that in a future release. However, if you want something without that inelegance, it's available today in WDSc.

The Graphical Debugger in WDSc

Using SEP from WDSc is a breeze. I'm using the Rational version (6.0.1.1), and all I have to do is follow these steps:

1. At an i5/OS command prompt, start the RSE debug server if it's not already running. To do that, type the following command:
   

     STRDBGSVR

2. Start WDSc and connect to the system that you want to work with.

3. In the Remote Systems pane, open iSeries Objects.

4. Find the program object (not the source code) that you want to debug.

   Tip: An easy way to find an object is to click the Work with objects option, which lets you create a new filter, where you can specify the object's name, library, and type, as shown in the following picture:

   

   For anyone unfamiliar with filters, let me explain a bit about them. They're little "subtrees" that appear in the remote systems pane, and they show a subset of the objects (or libraries or members) that match a certain criteria. For example, I could use wildcards to list all programs in a library or all programs that begin with OEL in a library or whatever criteria make sense for what I'm working on. In this case, I didn't use any wildcards but simply selected one program name to make that program easy to find.

   Now that I've entered the criteria for my filter, I click Next and am prompted for a name to give the filter. For the sake of this demonstration, I use the name My Filter.

   The new filter, and the object that it includes, are now listed in my Remote Systems pane, and I can now proceed with the next step.

5. Right-click the program object, and select Debug(Service Entry)|Set Service Entry Point. This is shown in the following screen shot:

   
   
   

6. If all is well, after a second or two, you should get a message telling you that the service entry point was set up correctly. The program should now be listed as a service entry point in a table in the iSeries Service Entry Points pane near the bottom of your screen.

That's it! As soon as this program is executed, in any job on the system, the WDSc debugger opens automatically, lets you set breakpoints, and steps through the code as it runs. No need to find the job or run STRSRVJOB.