STRart the source DeBuG utility (STRDBG).

You might need it someday (maybe not today, maybe not tomorrow, but soon and for the rest of your programming life). For more information, see the textbook, page 368, or the ILE RPG for AS/400 Programmer's Guide.

For your convenience, a DEBUG cmd has been created in RPG544LIB library. Just run DEBUG from a command line and it will complete the following steps for you. But keep reading anyway.

First compile your program (or create your modules) with "Debugging views" ...

PDM option 14 (or 15) + F4 (not Enter!),
then F10 for Additional Parameters,
change the Debugging Views default from *STMT to *list or *source, e.g.

Debugging views . . . . . . . . *LIST *STMT, *SOURCE, *LIST...

Press Enter to compile the program with debugging information.

If you include the following in your Control form (H spec):
debug will show your source line numbers and not bother you by stepping through the Input or Output specs.

If you want to see the I/O specs during debug, specify

Interactive programs using a display file:
Debug utilities are difficult to use with screens using ERRMSG unless you specify RSTDSP(*YES) on the CRTDSPF or CHGDSPF command.

After compiling your program (and adjusting your display file) ...

Prompt the STRDBG command with F4,

Call the program and the Display Module Source screen is shown again when the system reaches your breakpoint. If you don't see that screen, you did not previously specify a breakpoint where you needed it. Exit the program, run the DSPMODSRC cmd to specify a breakpoint, then call your program again.

Press F10 to step through each line of code or
enter the STEP nnnn lines command to run through many of lines code until the next breakpoint. I often enter "S 9999" to get debug to move along to my next breakpoint.

Have a current compile listing of your program beside you when you are debugging. You can make notes if what you "said" in your code is different from what you "meant" in your comments. Don't you wish you had a DOWIM compiler? (see first lecture notes)

When you are done debugging, you must run ENDDBG.

CL program to run these steps

/* Parameter:  program name to be compiled and debugged      +    
/* chgcurlib so compiler, etc. can find needed objects       +    
 * Compile program with debug option   +                            
 * Start debugger, call pgm, end debug. +                          
            PGM        PARM(&PROGRAM)                            
            DCL        VAR(&PROGRAM) TYPE(*CHAR) LEN(10)         
            ENDDBG     /* cancel leftover debugging session */        
            MONMSG     MSGID(CPF0001) /* ignore if not in debug mode*/

            ?CHGLIBL   /* confirm current library and the list */ 
                         SRCFILE(*CURLIB/QRPGSRC) SRCMBR(*PGM)                                                   
            STRDBG     PGM(&PROGRAM) UPDPROD(*YES)               
            CALL       &PROGRAM                                  


How often do you find yourself debugging a program and typing the same debug command over and over again? Or maybe you press function key F9 repeatedly to retrieve previously typed debug commands until you find the one you need. Here's a way to create debug shortcuts for faster, easier debugging sessions.

You can use the Equate debug command to associate a user-supplied name with a field, expression, or debug command. You can then use the name alone or within an expression.

The syntax of the Equate command is
Equate Name Definition
where Name is the name you want to associate with a field, expression, or debug command
and Definition is the field, expression, or debug command you are associating with the name.
You can use up to 144 characters in an Equate command.

For example, here's how to create a shortcut command called DCN to display field CustomerName:

Equate DCN Eval CustomerName

When you want to display CustomerName, simply type DCN on the debug command line, and the debugger executes the command Eval CustomerName.

To see a list of active Equate definitions, type Display Equate on the debug command line.

************ Club Tech iSeries Programming Tips Newsletter ***********
An iSeries Network Publication
Home of iSeries NEWS Magazine
Editor: Scott Klement
Issue 194 January 27, 2005

Starting in V3 of OS/400, IBM upgraded the STRDBG command to also be an interfactive debugger. Unlike ISDB, it works with all of the languages that run on the iSeries, including all of the ILE languages, OPM (the original program model that came before ILE) languages, and even Java. Not only that, but it's able to handle them all at once.

For example, let's say that you have an OPM CL program that calls an ILE program. The main procedure of the ILE program is written in RPG IV, but it calls additional modules written in C and COBOL. Using the "step into" function key, F22, you can step right into each of the programs and modules as they are called, effectively switching between all of these different languages as the code executes. That's a very useful feature!

In order to enable interactive debugging of your programs, you have to specify a debugging view when you compile it. You specify the debugging view using the DBGVIEW parameter on any of the ILE compilers. The following list explains the values available:

DBGVIEW(*STMT) = This is the default, and it only includes the statement numbers in the view. If you use this option, you won't be able to debug your program interactively.

DBGVIEW(*SOURCE) = This allows the debugger to view the source member of your program when you debug it. This gives you a result that's similar to what ISDB provides. The problem with this option is that if the source code gets changed, you might be seeing incorrect results. Also, when your program object gets moved to a production system, you may not have the source member available, which could be a problem.

DBGVIEW(*LIST) = A copy of the compile listing gets embedded into your program object. When the debugger views your program, it uses that compile list instead of viewing the source member. That way, if the source gets changed, or is unavailable, you can still debug the program. This is the option that I use and recommend.

Once you've compiled your program with the appropriate debugging view, you can start the debugger by typing the following command:
===> STRDBG PGM(myProgram)

The debugger will then set up the debugging environment and show the source code for your program on the screen. The following is a screenshot of the screen that I get when I do this:

= = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
                         Display Module Source
Program:   XLCRTDEMO      Library:   TIPSNL         Module: XLCRTDEMO
    16     001500
    17     001600 FDIVSALES  IF   E           K DISK
    18     001700
    19     001800  /copy qrpglesrc,hssf_h
    20     001900
    21     002000 D CreateCellStyles...
    22     002100 D                 PR
    23     002200
    24     002300 D AddMonth        PR
    25     002400 D   book                              like(HSSFWorkbook)
    26     002500 D   month                        2P 0 value
    27     002600 D   monthname                   20A   varying const
    28     002700
    29     002800 D FormatColumns   PR
    30     002900 D   sheet                             like(HSSFSheet)
 Debug . . .
 F3=End program  F6=Add/Clear breakpoint  F10=Step  F11=Display variable
 F12=Resume      F17=Watch variable  F18=Work with watch  F24=More keys    
= = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =

You can page through the source and insert breakpoints where you want the program to stop. You can press the F10=Step or F22=Step Into keys to tell it to stop on the next statement that gets executed. The difference between these keys becomes apparent when a program or subprocedure gets executed. If you use the Step function, it will not show the code of the subprocedure or program as it's executed, but it will continue stepping with the next line of the routine that you're in. If you choose Step Into, it will step line by line through the called routine as well.

The F14 key can be pressed to switch between modules in the program or to add additional modules or programs to the debugger so that you can set breakpoints in them as well.

Once you've set the breakpoints, you press the F12 key to continue. This will exit the interactive source display, and put you back at the command line. Unlike ISDB, it will not run your program for you. You have to run your program from the command line using the CALL command.

When you're done with the debugger, use the ENDDBG command to take yourself out of debug mode. Also, if you need to recompile your program, you should end the debugger with ENDDBG and restart it with STRDBG. This will ensure that the new copy of the program is loaded into the debugger.

You can enable wide screen debugging in STRDBG by setting the ILE_DEBUGGER_1 environment variable to a value of ALLOW_WIDE_SCREEN. Do this with the following command:


Once this has been set, the debugger will use 132-column mode if your terminal allows it to. It will continue to use 80-column mode if your terminal is not configured to use 132 columns.

To tell the debugger that you no longer wish to use 132-column mode, you can remove the environment variable with the RMVENVVAR command.