Problem solve Get help with specific problems with your technologies, process and projects.

Understand all your trace options, including the latest one -- STRTRC

Find out the advantages and the disadvantages of the new trace facility, STRTRC.

Ron Turull

V5 provides yet another way to trace jobs and programs: The new STRTRC command and its related command set. This new trace facility is similar to -- and some IBM documentation implies that it is meant to replace -- the old TRCJOB command. The new trace facility definitely has its advantages, but it also carries some drawbacks that might burden it too much to replace the old TRCJOB facility.

We'll discuss both the advantages and the disadvantages of the new trace facility. But first, let's take a quick look at the other trace facilities currently on the 400 (there are several). Since job and program tracing are debug functions, we'll also touch on debug facilities as well.

The old stand by
The original debug/trace command set of STRDBG, STRSRVJOB, and TRCJOB (and others) is still around and can still be used to debug just about any job or program on your iSeries. They are old, relatively slow and at times can be difficult to work with. But they work, and with a little patience you can usually get the job done.

However, this original debug/trace facility has one big drawback: No multiple job tracing. That is, you cannot trace/debug multiple jobs at the same time from a single workstation. In this ever-evolving world of client/server computing, multithreaded execution, and e-ready solutions, this can pose a big obstacle.

Trace APIs
Before things on the AS/400 evolved too far, it became quite apparent that debugging jobs early in their existence was somewhat problematic. Trying to catch a job as it starts with the STRSRVJOB/TRCJOB command duo is like trying to hit a Randy Johnson fastball with your eyes closed.

To correct this "problem" IBM introduce a couple of APIs that let you "pre-register" jobs for servicing. For example, you use the Control Trace API (QWTCTLTR) to turn on (and off) this "early" trace facility. Next, you can use the Set Trace API (QWTSETTR) to "pre-register" a job name and a user name. Then, the next time a job starts with that job name and user name, the job starts tracing immediately with the first instruction.

The tracing is done in the background, so you can call the QWTSETTR API multiple times to set up traces for multiple jobs. When the tracing is finished, the QWTCTLTR API should be called using the value *RESET for the Control value parameter to clear out all the job names.

There are also a group of Unix-type APIs that can be used for tracing and debugging jobs and programs. They are as follows:

  • Qp0zDump. Dump Formatted Storage Trace Data
  • Qp0zDumpStack. Dump Formatted Stack Trace Data
  • Qp0zDumpTargetStack. Dump Formatted Stack Trace Data of the Target Thread
  • Qp0zLprintf. Print Formatted Job Log Data
  • Qp0zUprintf. Print Formatted User Trace Data

Those APIs can be used in conjunction with the CL commands CHGUSRTRC, DMPUSRTRC, and DLTUSRTRC.

Flight recorders
Flight recorders, the infamous black boxes of the multithreaded programming world, provide you with an easier way to trace and debug multithreaded programs. Multithreaded programs are notoriously complex and hard to follow when they are running (even though the code may look fairly simple and straightforward).

Used mostly in C, flight recorders are accessed using built-in macros. For example, in your multithreaded program, you turn on the flight record and perform trace/debug tasks (such as printing out trace data) using these built-in macros. Then, when you compile the program, you specify that you want the flight recorder macros activated.

Once the program is satisfactorily debugged, you can recompile the program to turn the macros off and essentially remove the trace-related code from the compiled program.

The latest trace facility
The latest trace facility to come out of Rochester is headlined by the aforementioned STRTRC (Start Trace) command. The other related CL commands are ENDTRC, PRTTRC, and DLTTRC.

This new trace facility allows you to trace multiple jobs at once from a single workstation. It also runs much more efficiently, which makes it virtually undetectable in the job(s) being traced. The internal buffers are also very larger, which is a good thing because this trace facility tracks much more data than the old TRCJOB facility.

The one big setback I have been able to find with this new trace facility is the inability to register an exit program for it. The old TRCJOB facility has a great exit program that, among other things, allows interaction -- albeit limited interaction -- with the trace facility. This allows you to customized the trace facility somewhat. Unfortunately, this feature is not included in the newest trace facility. Oh well, maybe next time.

About the author: Ron Turull is editor of Inside Version 5. He has more than 20 years experience programming for and managing AS/400-iSeries systems.


  • Using STRDBG to analyze OPNQRYF member Guy Roberto Pacheco says, when you use the STRDBG command, the operation system generates additional information on joblog that can be valuable in analyzing the performance of OPNQRYF commands.
  • 5,00.html>Options for debugging Java applications
    Debugging applications isn't usually an important consideration when you're deciding on application architectures or requirements. It's one of those items that becomes critical during development if you haven't planned ahead. With Java, iSeries developers usually have a good choice of debugging options. You can select the one that best fits your debug requirements. Web development expert Jim Mason points out your options and some considerations for getting started.
  • How to debug a batch job
    How can you debug a batch job ? How can you debug a job that has been running for a long time? "Raju400" needed to know, and "vlui00" had the answers.

Dig Deeper on Performance