Alex Lane is a knowledge engineer for Technology Applications Inc. of Jacksonville, Fla. He can be reached as a lane on BIX and as ALANE on MCI Mail.
Sherlock; Edward K. Ream, 1617 Monroe St., Madison, WI 53711. IBM PC/XT/AT or compatible with 2 floppy disks or hard-disk MS-DOS. Microsoft C or Turbo C compiler. (Note: Microsoft MASM macro assembler required to change interrupt handler.) Price: $195.
It's funny how C programmers get caught in the rut of debugging programs by peppering them with printf( ) statements. Sure, some master the intricacies of source-level debuggers like CodeView, which offers both slick features and a formidable learning curve; others, influenced by books like Debugging C (Robert Ward, Que, 1986), try various ad hoc combinations of compile-time variables and macros. The rest, however, lacking time or budget, uneasily curse the darkness and continue to rely on printf( ) statements to flush bugs out into the open.
Rejoice, programmers! That darkness may be short-lived. Sherlock is a reasonably priced, well thought-out tool for debugging, tracing, and profiling programs written in C. The package was written by Edward K. Ream, who's developed a reputation for putting out quality software and whose name is no stranger to these pages. Sherlock runs on IBM PC/XT/AT machines under MS-DOS with either Microsoft C or Turbo C. (Because source code is provided for the macros and support routines, minor modifications should allow Sherlock to be used with other compilers as well.) The software comes on two 5 1/4-inch low-density floppies, and is accompanied by a 66-page spiral-bound manual.
I can appreciate the work that Ed Ream did on Sherlock because I did something similar (but nowhere near as polished) for a C project a while back. By enabling and disabling various trace-points, you can quickly see what's happening in the program without either being overrun with spurious debugging information or having to continually stop, edit, recompile, and relink the code. This is particularly important when trying to track down pointer bugs, which tend to behave differently as printf( ) statements are added to and removed from the code. Ream discusses such problems in the manual, and refers readers to Ward's Debugging C, mentioned earlier.
The typical statement executed from a Sherlock macro is a printf( ) statement, although any executable C statement (including blocks of statements) may be used in a macro. This lets you create really complicated debugging functions (display of data structures, for example) that are only called when you need them. I found Sherlock's tracing ability useful in selectively viewing the input from a serial port during program execution. This allowed me to quickly ell whether my program was misbehaving, or whether the serial input was corrupt.
Leaving the Sherlock object code in the application effectively embeds an extensive diagnostic capability that's easy to use and simple to document.
Sherlock is also a profiling tool, which means it can gather frequency and timing statistics and report them at any time. This feature can be of particular value when trying to track down the 20 percent of the code that uses 80 percent of the CPU's time, or when trying to track down a boundary-value bug. While I normally don't need this capability, I was pleasantly surprised to see how easy it was to implement.
Typically, Sherlock macros are enabled or disabled from the command line by including the macro name with a special prefix (like '+ +' or '--', respectively). These command-line arguments are removed by the SL_PARSE() macro, which passes the remaining arguments to the subsequent code. The scope of Sherlock tracepoints can also be controlled from other macros, particularly the SL_ON() and SL_OFF() macros.
Defining or not defining the compile-time variable SHERLOCK determines whether the macros in the code are expanded or whether they disappear without a trace. Because Sherlock macros are unobtrusive in source code, there's really no need to remove them before generating production versions of executable code. This capability is valuable for code that undergoes periodic revision or enhancement.
You can get a head start on mastering Sherlock by using the Sherlock preprocessor (SPP). This program automatically inserts macros to trace the entry and exit of all functions in a file and inserts initialization macros in the main() function. Studying such a "Sherlocked" file with the manual at hand speeds the learning process. Another Sherlock utility, SDEL reverses the process should you decide to remove macros.
A third utility, SDIF, is a file comparison program that is designed to compare an "un-Sherlocked" file with its "Sherlocked" cousin. The output of SDIF lets you immediately see which macros are in the file.
The C source code for SDEL and SDIF is included with the package. In addition, the source to CPP, a C preprocessor compatible with the draft ANSI standard of 1-11-88, is included as an extensive example of how Sherlock macros are used.
Despite the sophistication of the Sherlock package as a whole, there are some things to watch out for. Sherlock is intended for intermediate-to-advanced C programmers, and thus, doesn't go into the level of startup detail one might expect in a general-purpose package. For example, some things are dropped in the user's lap with no-nonsense explanations, such as the existence of two sets of macros (the second, in case your compiler does not allow multiple static variables to have the same name even if declared in separate blocks). Another such example is a warning to the effect that the timing interrupt handler (supplied in assembler source and in small- and large-model object file formats) may have to be twiddled for non-100 percent IBM compatibles.
Sherlock is not copy-protected and Ed Ream's no-nonsense license agreement asks the user to treat the software just like a book. Just as no-nonsense is the author's offer of a satisfaction-or-money-back guarantee.
Sherlock offers excellent value and utility for the price, and belongs in the toolkit of every serious C programmer.
Copyright © 1989, Dr. Dobb's Journal