Open up ‘IBM i Client Access’, make sure you have entered the correct system, then choose ‘Database – Run SQL Scripts’.
Now select ‘Run – System Debugger’. If on start-up, you get an error ‘Unknown system ‘xxxxx’ was specified – OK’, go to ‘File – Change System’. Enter the system IP address instead. Now enter the user and password.
Sometimes when you open the Debug start-up screen, and you also have a 5250 session (Green screen), the 5250 won’t respond until you fill in the details and OK or Cancel. The way to get around this is to open a NEW ‘IBM i Client Access’ window. Then signon and open SQL then Debug. I enter ‘– – Debug’ or ‘/* Debug */’ in the SQL. This is just a comment. If I have another SQL session, I can tell which is which. If you don’t it’s OK, the screen will unhang when you actually start debugging.
You have a number of choices, but first enter one of the programs you want to debug. This can be CL, CLLE, RPG, RPGLE, SQLRPGLE, C and probably others. I did get into a C program once by mistake. Obviously for debug to work the program needs to be compiled with DBGVIEW(*SOURCE).
If you have debugged a program before, you can use the ‘Recent’ button on the right. It remembers the details.
Using Existing JOB
If you have an interactive program, or a program called from a command, you will want to use the default ‘Debug existing job on system’. Change the ‘Existing job to debug’ at the bottom of the screen, with the 5250 details and click OK (use WRKJOB from 5250). All the job details such as library list etc. will come from the job you entered.
Note the bug in the top right. If there is a white hand it means that you are at a breakpoint. If the bug is moving, it means the program is executing or waiting. See below.
First you need to at least put in a ‘Breakpoint’, just in case. Find a convenient line in your program. It is advisable NOT to put it on the top **FREE line. This is done by pressing F6 or ‘Breakpoint – Add Breakpoint’ with your cursor on the required line. If your cursor is in the variable area, it will find the top executable line.
Make sure you change focus from the debugger to the 5250 at the right point of time. If you stay in the Debugger and press Shift-F11 (Step Into)or F12 (Resume to Breakpoint) in the Debugger, the bug top right will start moving, but nothing will happen. You need to call your program from the 5250 and return to the Debugger. If you go to the 5250 before starting to debug with F12 or any other, then your 5250 will appear to hang, you need to start the debugging first. Similarly when the bug is on the move, it is probably waiting for input (or it could be waiting on an error message or doing heavy processing or looping).
If all goes well, a yellow highlight should appear on the current line of your program in the debugger. This will be the first line of the first program if you used Shift-F11 or the first Breakpoint line if you used F12.
It may be a good idea to put your first breakpoint after the first screen input. This means your screen will ask for input after you execute it and after entering data you can return to the debugger.
Submit and debug program in batch job
In this case it uses the SQL job QZDASSINIT or QZDASOINIT to submit a job. This job doesn’t use your library list or any other settings. So you use the ‘Initialization comma…’ to setup what you need. You can only have one command. You can, as I have, use CHGCURLIB, or ADDLIBLE or write a CL program and call it. In the CL you could setup multiple libraries in the library list, add objects to QTEMP etc. Obviously this program has to be able to run in Batch mode. You can also enter ‘Parameters’ above the command. When you press OK the source code appears and you carry on with debug.
Debugging in general
F11 ‘Step Into’ will stop at every line and move to another module / program, but not external procedures unless they have a breakpoint. F12 ‘Resume to Breakpoint’ will jump to the next Breakpoint, in the current or the next module / program / procedure. You can also use the symbols in the top ribbon. Hover over them to get the descriptions. Have a play.
If you need to add other modules or programs use F2 or ‘Debug – Add Program Object’ or within the Programs tree list ‘Right Click – Add Program Object’. It is a good idea at this point to add Breakpoints to the other modules and programs too. If you have used BNDDIR (Binding Directories), the other modules / programs will be added by the System Debugger. If you have external procedures included then you should put a breakpoint in each procedure you want to debug.
Below is a program I have been working on.
The top left window has been changed to the Breakpoints tab.
In the code window, the Red Arrows show the Breakpoint lines. The Yellow Highlighted line is where the program is at the moment. In this case, I pressed F12 after executing the program on the 5250 screen. It didn’t stop at the first Breakpoint because the if statement above it is false. The program has stopped at line 65 when the first log file line starts with “error”.
In the Locals tab (bottom left), I have clicked the + sign next to LOGFILE to expand the Data Structure. The symbols to the left of the variable names show the variable type., although I’m not sure why the character strings are shown as 12.
The Monitors tab, can be used to track Global Variables, if you have any. It can also be used to cause a breakpoint when the value of a variable changes. See below
The bottom left, of the screen, shows the current Status. If you point to any variable in the code, the status bar will show the value, as well as the hover text.
Right click gives Menus of options in each window and each tab which are relevant to that area.
The good bits
To add Monitors, the program has to have started. ‘Right Click – New Monitor’ in the blank area under the Monitors column headings. Type in the Variable you want to monitor. In my case ‘x’. I also tick the Watch option. I added another field as well. When I press F12, the status line shows the breakpoint line 63 and the variable that changed X. For some reason the monitor breakpoint doesn’t work for character strings, but it does work for ‘length’. Maybe it only works for numeric fields.
On the right, above, I Right Click on the variable Line and pick ‘Go To Memory’. I then changed the drop down options. The Expression list remembers what I have already looked at. This is very useful. Not only can you change the amount of data that you see, in both HEX and character, but you can also change it to ASCII, Unicode or UTF32. Of course it will only make sense in one of them.
In addition, you can change any of the variables mid-flow by Double Click on the variable Value. This works in both Locals and Monitors tabs. Of course, it doesn’t like it when I try to change an INT to ‘xxxx’.
Here are some of the Bug symbols.
I hope you have fun with this, before Liam Allan manages to write something better still.
i-UG is back with a meeting in person!
We will be at the Victory Club in London on Thursday 10th March 2022. We hope to see you there. For more details go to www.i-ug.co.uk