Guru: Three Little Words That Simplify Debugging
August 29, 2018 Susan Gantner
Author’s Note: The original version of this tip first appeared in March 2007. That was three renames ago for the toolset we now know as RDi. (It was WDSC then). Although RDi has seen many significant enhancements in the intervening years, not much about starting a debug session has changed. But the number of RPGers now using RDi for editing their code has grown dramatically, and many recent converts still struggle with getting a debug session started. So I think this tip bears repeating — with some name changes, updated images and relevant functional updates here and there.
I had struggled with using the debugger in RDi when I asked a friend that I knew to be an expert on the subject to help me understand how to use it. She told me that I only needed to know three little words — Service Entry Points — to make my debugging life easier. She was right!
If you have not yet learned the joys of debugging with Service Entry Points (SEPs), try it today. In the Remote Systems view (RSE), choose a program object. Right click on the object and select Debug or Code Coverage (Service Entry) –> Set Service Entry Point.
It can sometimes take several seconds for anything to happen, but eventually, you should see a confirmation message and the Service Entry Points view appears in the workbench. Your program name appears in the list of Service Entry Points. The default settings include *All modules in the program, *All procedures in the program and your User ID. (See Figure 1).
Setting that Service Entry Point says that when this program is invoked by your user profile, the IBM i debugger within RDi will ask you if you want to switch to the debug perspective. If you say yes (and/or if you have specified that there is no need to ask permission) the following will happen:
- The debug perspective in RDi will start (if necessary) and come into focus.
- This program will be put into debug mode on the host.
- The source for the program will be opened in the editor (if it’s not already open).
- The debugger will wait before the first executable statement for your interaction.
The first time you debug with RDi, you may get a message about the debug server on the host not being started. In this case, the message supplies instruction on how to start it.
After setting the Service Entry Point, go to another job (such as an emulation session) and call the program and see this for yourself. It may take a while for the debug session to start up but when it does, you are ready to add any breakpoints you may need, set up fields you want to monitor the values of as you are stepping through the program, issue a “Run to location” from a specific statement in the program or any of the other actions you may do within an RDi debug session normally.
I think that’s a pretty easy way to start a debug session. The best part is that it doesn’t matter whether I want to run the program from an interactive session or submit it to batch. Even better, if this program were invoked in some “non-traditional” way, such as in a web server job or a remote procedure call, I don’t need to be concerned about figuring out what job needs to be debugged (or “serviced”). I can simply wait for the program to be invoked by my user profile, however that is, and it will go into debug mode for me.
Of course, you are not limited to debugging only programs that you personally call. You can right click on the Service Entry Point in the list and select “Modify” to change the user profile and/or to specify which module(s) and procedure(s) you want to debug. Notice that from the right click menu, you can also remove a Service Entry Point or temporarily disable it. You may also do these actions from the tool bar icons at the top right corner of the view, as shown in Figure 2 below. Another important option you can use here is to refresh the Service Entry Point. You will need to refresh any time the program is recompiled.
Sadly, nice as they are, Service Entry Points are not a panacea. There are some limitations. For some shops the biggest limitation may be that you can only start an SEP debug session using an ILE language program, i.e., RPGLE, CBLLE, CLLE etc. However, once an SEP has been used to start a debug session, you can step into or add to debug any language programs you want, including older RPG or CLP types.
You also cannot start a debug session with SEP on a program that is already running — whether or not it is suspended due to an error. A limitation which seems counter-intuitive is that you cannot debug a program called from your current RSE server job using an SEP. And don’t forget that you must refresh the Service Entry Point from RSE after the program has been recompiled to debug the new version.
If you are in one of those situations where you can’t use SEP to start a debug session, you can still use the other method of creating a debug configuration. You can read more about that process in the tip I wrote here.
You should check out the debug preferences — search for IBM i Debug (under Run/Debug) in the RDi preferences dialog. There you will find the often important “Update production files” preference for all types of debugging and some specific preferences for Service Entry Points.
Hopefully these three little words will help to make your debugging life easier. I have also created a short video about starting a debug session. Happy debugging.
Susan Gantner, an IBM Champion and co-author of the popular Redbook Who Knew You Could Do That with RPG IV, is one of the top speakers/writers/trainers on IBM i development topics. She is a partner at Partner400 and System i Developer, and she hosts the RPG & DB2 Summit twice per year with partners Jon Paris and Paul Tuohy.