You are currently on IBM Systems Media’s archival website. Click here to view our new website.


Tracing Our Steps

This month, we thought we’d return to the land of IBM-supplied and open-source utilities and talk about tools that fill a gap in the development tooling we’ve had for some time. In one case, the potential goes way beyond just filling the gap.

The gap we’re talking about is the lack of a program trace tool for ILE programs. Back when we were writing OPM programs, the STRTRC command and its companions were part of our daily programming life. For reasons that we never fully understood, STRTRC was never enabled for ILE programs, and we missed it. After a while, we became aware that we could probably write our own tool using the debugger APIs—but by that time we were doing less programming, and the advanced features of the debugger in the Rational tools meant that debugging was so much easier that we rarely missed the trace capabilities.

Recently, however, we faced several situations where a trace tool would have been really useful and as a result went “shopping” to see what we could find. We came upon several tools during our search, but only two appear to be actively supported; the others didn’t seem to have been updated in some time and/or Web pages were missing, etc.

TSX from vLegaci

The first tool we came upon is an open-source offering from vLegaci, known as TSX. One of the nice things about TSX is that rather than produce a simple printer report as the old IBM trace did, it outputs results to an SQL table. The data included is quite comprehensive and includes (joy of joys) the actual source code line itself, as well as additional columns containing the op-code and the name of any variable changed by the operation. More on this aspect to follow**. The data lets you write SQL queries to analyze it in various ways. For example, you may want to show which variables may have been changed by a particular subroutine or subprocedure.

Another interesting aspect of the way the results are recorded is that each trace run is given a unique identifier. This makes it possible to compare the data from different program executions and identify the differences in the code paths.

You can find all you need to know about TSX at There you’ll find a basic explanation of the benefits of using the tool and a download link for the package. The package itself consists of a short PDF that covers the installation and running of the tool. More importantly, it provides some use-case examples that will give you some excellent ideas on ways you may be able to exploit the tool. For example, you could run a query to simply list I/O operations either on all files or a specific file—very useful in cases where the logic governing I/O operations is complex and files are not being updated as expected. Even if you don’t want all the extra features, the basic trace data is very usable and, in our opinion, this tool is a great addition to your toolbox.

** One word of caution. The method the software uses to determine which variables have been modified by an operation appears to be based on a simple analysis of the source statement in question and is therefore incomplete. For example, variables modified as a result of a READ, CHAIN or EXFMT would not appear in the data. But remember what we said about it being open source ... you can always change the code!

IBM’s ZTRCPGM from the QUSRTOOL Library

After TAA tools “went private” some years ago, we stopped paying as much attention to the contents of QUSRTOOL. From time to time, we’ve come upon some useful proof-of-concept type tools in the library but nothing that really grabbed our attention. As a result, we were somewhat surprised when our search for trace tools led us to ZTRCPGM.

This utility is designed to provide a unified tracing facility for applications comprised of both OPM and ILE components. That aspect is of very little interest to us, but it might interest some of our readers.

The big feature that ZTRCPGM brings to the table (that’s not offered by TSX) is the capability to specify variables to be monitored. This is achieved by placing debugger EVAL statements into a source physical file, which is then specified on the ZTRCPGM command. You can restrict the execution of the EVAL to within a specific procedure, and you can determine whether the value is output on every step or only when it changes. Not sure why we’d ever want to see it on every step, but it’s there. You can also control whether called programs and procedures are stepped “over” (F10 in STRDBG) or “into” (F22). At first glance, we thought this would be a useful feature but in practice the lack of granularity (e.g., step into this procedure but not others) somewhat limits its utility.

Unlike TSX, ZTRCPGM outputs results of the trace to a source physical file. We’re not sure why this approach was used instead of simply using a printer file, particularly since the output is 132 characters long, but we assume there was a good reason.

The biggest problem we encountered with this utility was having to build it. To save space, the source files for tools in QUSRTOOL are now packaged as savefiles and you must run the utility UNPACKAGE to restore the ones you require. Once that’s done, you run the specified build script to create the programs. According to the documentation in the text member AAAMAP (in QUSRTOOL/QATTINFO), the text file for the individual utility lists the components that must be unpacked. That didn’t appear to be the case with ZTRCPGM. The TTEINFO text member explains how to build and use the tool but it took us three tries because each attempt revealed another package that needed to be restored. Perhaps we just missed some additional instructions somewhere, but it was a frustrating experience. In the end, it was worth the effort, but it could have been so much easier.

Choices, Choices

So which of the two do we prefer? In the long haul, we think we’ll find ourselves using TSX far more often than ZTRCPGM because of its flexibility. The use of a database to store the results is a great idea and takes it well beyond the capabilities of a simple tracing tool. We’re also more likely to recommend TSX to clients because of the significantly better documentation and ease of installation.

ZTRCPGM’s capability to monitor variables, on the other hand, makes it a compelling choice in some circumstances. No doubt, we’ll end up finding a space for both in our toolbox.

Of course, the other advantage of TSX is that it’s written in RPG and can therefore readily be modified to your own requirements. It should even be possible to add the missing variable monitoring if you choose. Indeed, perhaps someone has already done just that. For most of us, the same is not true of ZTRCPGM. While IBM does supply the source, sadly it’s written in C and therefore even the relatively simple task of changing the output to a database, for example, requires skills that few of us have.

Talk to Us!

If you’ve found any other trace tools, or any tools you find invaluable in your daily work, please let us know via the comments below.

Jon Paris is a technical editor with IBM Systems Magazine and co-owner of Partner400.

Susan Gantner is a technical editor with IBM Systems Magazine and co-owner of Partner400.

Like what you just read? To receive technical tips and articles directly in your inbox twice per month, sign up for the EXTRA e-newsletter here.



2019 Solutions Edition

A Comprehensive Online Buyer's Guide to Solutions, Services and Education.

New and Improved XML-INTO

Namespace support makes the opcode a viable option

Authenticating on the Web

The finer points of OpenRPGUI, Part 1

The Microphone is Open

Add your voice: Should IBM i include open-source RPG tools?

IBM Systems Magazine Subscribe Box Read Now Link Subscribe Now Link iPad App Google Play Store
IBMi News Sign Up Today! Past News Letters