STRDBG Command Reference

Who this is for: RPG and CL developers who already compile ILE programs and now need to step through one at a 5250 command line. It gives the exact STRDBG syntax and parameter defaults, and the usual reasons a debug session does not show source, will not update a file, or will not start.

Prerequisites: you can compile a program with CRTBNDRPG or CRTRPGMOD and call it from a command line.

STRDBG (Start Debug) puts your job into debug mode and, for ILE programs, opens the ILE source debugger on the program you name. It is the command most people type first when they want to stop a program at a line and look at a variable. This page is the lookup for its parameters and defaults, the compile-time prerequisite, and the mistakes that make a session fail.

It is a reference, not a debugging method. For how to approach a problem before you open a debugger (symptom first, job log, messages, one change at a time) read Debugging on IBM i: A Beginner’s Guide. That guide talks about breakpoints in general. This page covers the command that sets them up.

At a glance

Syntax

STRDBG PGM(library/program) SRVPGM(library/service-program) UPDPROD(*NO) OPMSRC(*NO)

PGM is the first positional parameter, so STRDBG MYLIB/MYPGM is the same as STRDBG PGM(MYLIB/MYPGM).

Parameters

Defaults are those on the IBM i 7.5 command page. The IBM i 7.1 page lists the same twelve parameters with the same defaults.

Four of the twelve matter in ILE RPG work: PGM, SRVPGM, UPDPROD and, for older OPM code, OPMSRC. The trace and default-program parameters belong to the OPM system debugger.

Before you start: debug data

STRDBG can only show source that the compiler kept. On CRTBNDRPG and CRTRPGMOD the DBGVIEW parameter decides what is kept.

Two consequences follow from IBM’s documentation:

• The default *STMT gives no source view. If you want to read your code in the debugger, compile with *SOURCE, *LIST or *ALL. IBM’s own batch-debug note uses DBGVIEW(*ALL).
• A source view points back at the source member. For the root source or copy view, IBM says the source must be on the same system as the program and in a library, file and member with the same names it had at compile time. Move or rename the member and the view is lost. The listing view does not have this dependency: IBM’s ILE Concepts (7.5, “Module Views”) says “the list view is produced and stored with the module”, which “allows the source debugger to display source even if the source files used to create the module are not present on the system.”

For an OPM program, IBM says it must be compiled with OPTION(*SRCDBG) or OPTION(*LSTDBG) to be debugged in the ILE source debugger, and an OPM CL program must use *SRCDBG. You then start debug with OPMSRC(*YES). Without those, the OPM program is debugged with the OPM system debugger (ADDBKP, DSPPGMVAR and related commands).

What happens when you run it

For an ILE program, STRDBG shows the Display Module Source display. IBM documents which module appears first:

• the module that contains the program entry procedure, if it has debug data,
• otherwise the first bound module that has debug data.

If you name an ILE program and a service program, the program is shown. If you name an OPM program and a service program, the service program is shown when it has debug data.

From that display you work with debug commands, typed on the debug command line at the bottom of the screen. IBM’s note is explicit: “The debug commands entered on the debug command line are not CL commands.” The ones you use most:

Leaving the display (F12) does not end debug mode. Your job stays in debug mode until you run ENDDBG. Call the program and it stops at the first breakpoint. To get back to the source display later, run DSPMODSRC.

To add more programs after the session has started, IBM documents option 1 (Add program) on the Work with Module List display of DSPMODSRC, and option 4 to remove one. IBM says there is no limit on the number of ILE programs added this way, and that removing a program removes its breakpoints.

Examples

Verification status: documentation-backed, not execution-verified. None of these commands were run on a live IBM i or PUB400 system for this article. The behaviour described comes from the IBM pages listed under Sources Consulted. No screen output is shown because none was captured.

Debug one ILE RPG program

CRTBNDRPG PGM(MYLIB/PAYCALC) SRCFILE(MYLIB/QRPGLESRC) DBGVIEW(*SOURCE)
STRDBG PGM(MYLIB/PAYCALC)

On the source display, type BREAK 42 (use a line number from your source), press F12, then:

CALL PGM(MYLIB/PAYCALC)

The program stops at line 42. Type EVAL fieldName on the debug command line to see a value, or STEP to run the next statement. You can also press F10 (Step) or F12 (Resume). IBM’s “STRDBG Example” screen for the ILE source debugger (7.2 documentation, shown with a COBOL program) lists F3=End program, F6=Add/Clear breakpoint, F10=Step, F11=Display variable and F12=Resume. The key legend at the bottom of your screen is the final word for your release. End with:

ENDDBG

A program plus the service program it calls

STRDBG PGM(MYLIB/ORDENTRY) SRVPGM(MYLIB/PRICING)

ORDENTRY is shown first. Use DISPLAY or the Work with Module List display to move to a module in PRICING and set breakpoints there. How service programs are built is in the CRTSRVPGM Command Reference.

Allow updates to production-library files

STRDBG PGM(TESTLIB/PAYROLL) UPDPROD(*YES)

This is IBM’s first example with UPDPROD(*YES) in place of *NO. Read the next section before using it.

An OPM program in the ILE source debugger

STRDBG PGM(MYLIB/OLDRPG) OPMSRC(*YES)

OLDRPG must have been compiled with OPTION(*SRCDBG) or OPTION(*LSTDBG).

A batch job

STRDBG debugs the job you run it in. To debug a batch job, IBM’s support note gives this order:

SBMJOB CMD(CALL PGM(MYLIB/NIGHTLY)) HOLD(*YES)
STRSRVJOB JOB(123456/MYUSER/QDFTJOBD)
STRDBG PGM(MYLIB/NIGHTLY)

Release the job with WRKSBMJOB option 6, press F10 for a command line, run DSPMODSRC and set breakpoints, then press Enter on the Start Serviced Job display. When finished:

ENDDBG
ENDSRVJOB

The job number comes from the message SBMJOB sends. IBM’s note also names the RDi Service Entry Point as an alternative. For the job commands themselves see the IBM i Job Commands Reference.

UPDPROD and production libraries

This parameter surprises people more than any other.

• CRTLIB TYPE defaults to *PROD. Unless someone created a library with TYPE(*TEST), it is a production library to the debugger, including most “test” libraries.
• With UPDPROD(*NO), the default, database files in production libraries can be opened only for reading while the job is in debug mode. IBM warns that some commands, function keys or menu options may then not work correctly.
• IBM notes one exception: a production library file that was already open when you started debug.
• The protection is narrow. The CRTLIB page says it does not stop a program from deleting database files or changing other objects, such as data areas.

If an update program fails only when you debug it, check UPDPROD before you check the code. You can change it in the session with the SET debug command, or end debug and restart with UPDPROD(*YES). Prefer debugging against copies of the data in a *TEST library.

How STRDBG relates to the other debug commands

The line to remember: ADDBKP and DSPPGMVAR are for OPM programs. In ILE RPG you use BREAK and EVAL inside the source debugger.

Common mistakes

• Compiling with the default DBGVIEW(*STMT) or with *NONE. With *STMT there is no source to read. With *NONE there is no debug data at all. Recompile with *SOURCE, *LIST or *ALL, and rebind if the program is made of modules. DSPPGM and DSPSRVPGM show whether each module has debug data.
• Debugging one module of a multi-module program and wondering why another shows nothing. Debug data is per module. Each module needs its own DBGVIEW.
• Running STRDBG when the job is already in debug mode. IBM says the command cannot be used in debug mode. Run ENDDBG first.
• Forgetting ENDDBG. The job stays in debug mode with UPDPROD(*NO) in force, so later update programs in the same job can fail on production files. If debug is never ended, IBM says trace data is printed when the job ends.
• Moving or renaming the source member after the compile. The *SOURCE and *COPY views look for the member under its compile-time name. Recompile from the member’s new location, or use *LIST (or *ALL), whose listing view is stored in the module.
• Using ADDBKP or DSPPGMVAR on an ILE program. Both reject bound programs. Use BREAK and EVAL.
• Expecting a recompiled program to be the one you are debugging. UNVERIFIED_SOURCE: this is common practitioner advice, not stated on the STRDBG page. If the program runs in a named activation group that is still active in your job, the job may keep using the copy it already activated, and the source view and the running code no longer match. Reclaim the activation group (RCLACTGRP) or sign off and on, then start debug again. For how activation groups live inside a job, see the RPGLE Activation Groups Reference and IBM i Activation Groups and the Call Stack Explained.
• Debugging the job you are sitting in when the problem is in batch. Use STRSRVJOB first.

Troubleshooting

UNVERIFIED_SOURCE: the exact message ID and text you see when a module has no debug data were not confirmed against an IBM page for this article. Read the message on your own system with F1 or DSPMSGD.

Release notes

The IBM i 7.1 and 7.5 command pages list the same twelve parameters and the same defaults for UPDPROD, OPMSRC, DSPMODSRC and SRCDBGPGM. No release-specific change to STRDBG was found between them. DBGENCKEY is therefore present from at least 7.1. UNVERIFIED_SOURCE: the release in which it was first added was not confirmed. IBM’s RPG documentation recommends the debugger in Rational Developer for i as the preferred method, and STRDBG remains the 5250 route. See RPGLE Development Tools and Workflow Basics for where RDi fits.

Related commands

FAQ

What does STRDBG do?

It puts your job into debug mode and adds the programs you name to the session. For ILE programs it opens the ILE source debugger, where you set breakpoints with BREAK and look at variables with EVAL.

Why can I not see my source in the debugger?

Most often the program was compiled with the default DBGVIEW(*STMT) or with *NONE. Recompile with DBGVIEW(*SOURCE) or *ALL.

What does UPDPROD(*NO) mean?

While the job is in debug mode, database files in production libraries open for read only. Libraries are *PROD unless created with TYPE(*TEST), so this affects most libraries.

How do I end a debug session?

Run ENDDBG. Leaving the source display with F12 does not end it.

Can I debug a batch job with STRDBG?

Yes, through STRSRVJOB. Submit the job held, start the service job, run STRDBG, set breakpoints, release the job, and end with ENDDBG and ENDSRVJOB.

Do ADDBKP and DSPPGMVAR work on ILE programs?

No. IBM says both cannot be used with bound programs. They belong to the OPM system debugger.

Summary

• STRDBG starts debug mode and, for ILE programs, opens the ILE source debugger.
• It needs debug data. The compiler default DBGVIEW(*STMT) gives no source view.
• UPDPROD(*NO) is the default, and libraries are *PROD by default, so updates are blocked in debug mode.
• ENDDBG ends the session. ADDBKP and DSPPGMVAR are OPM tools. Use BREAK and EVAL for ILE.
• For the wider debugging approach, read Debugging on IBM i: A Beginner’s Guide.

Sources Consulted

• WebFetch: IBM i 7.5 STRDBG command. Confirms the twelve parameters, their defaults and OPM/ILE scope, the UPDPROD read-only behaviour and exception, the OPMSRC and DSPMODSRC rules, the restrictions (not in debug mode, public *EXCLUDE, *CHANGE or *USE plus *SERVICE), the PAYROLL and CLASS examples, and CPF1999.
• WebFetch: IBM i 7.1 STRDBG command. Confirms the same twelve parameters and the same defaults for UPDPROD, OPMSRC, DSPMODSRC and SRCDBGPGM.
• WebFetch: IBM i 7.5 ENDDBG command. Confirms no parameters, what it removes, the breakpoint and ENDSRVJOB restrictions, trace data printed at job end, and CPF1931 / CPF1999.
• WebFetch: IBM i 7.5 ADDBKP command and IBM i 7.5 DSPPGMVAR command. Confirm both require debug mode and cannot be used with bound programs.
• WebFetch: IBM i 7.5 CRTBNDRPG command. Confirms the DBGVIEW values and *STMT default.
• WebFetch: IBM i 7.5 CRTLIB command. Confirms TYPE defaults to *PROD, the debug-mode update protection, and that it does not stop deletes or data area changes.
• WebFetch: IBM i 7.4 ILE RPG Programmer’s Guide pages Debugging Programs, Starting the ILE Source Debugger, Adding/Removing Programs from a Debug Session, Preparing a Program for Debugging and Debug Commands. Confirm the 20/20 limits, which module is shown first, the source-location restriction, *SRCDBG / *LSTDBG for OPM, the Work with Module List options, the debug command list, “not CL commands”, and RDi as the recommended method. These are 7.4 pages. A 7.5 edition was not fetched.
• WebFetch: IBM i 7.5 ILE Concepts, Module Views. Confirms the listing view is stored with the module and can be displayed when the source files are not on the system.
• WebFetch: IBM i 7.2 STRDBG Example (ILE source debugger). Confirms the Display Module Source function keys, including F10=Step and F12=Resume. The example uses a COBOL program and is a 7.2 page.
• WebFetch: IBM Support: Debugging ILE programs submitted to a batch job queue. Confirms the SBMJOB HOLD(*YES), STRSRVJOB, STRDBG, ENDDBG, ENDSRVJOB order.
• WebSearch: community threads (midrange.com archives). Corroborate DBGVIEW(*NONE) as the usual cause of “no debug data”. Not IBM documentation. Used only for the troubleshooting row, and the exact message text is marked UNVERIFIED_SOURCE.

Not run on a live system. Every example on this page is documentation-backed and not execution-verified.