Dr. Dobb's is part of the Informa Tech Division of Informa PLC

This site is operated by a business or businesses owned by Informa PLC and all copyright resides with them. Informa PLC's registered office is 5 Howick Place, London SW1P 1WG. Registered in England and Wales. Number 8860726.

Channels ▼

Examining Room



Kent Porter, and Randy Davis, coordinated by Ron Copeland

The Norton Guides

Target: PC or PS/2 and compatibles

Requires: DOS 2.0 or later. Hard disk recommended

Pricing: $50 for the program, $50 for each language guide

Vendor: Peter Norton Computing Inc. 2210 Wilshire Blvd, Santa Monica 90403 (213) 453-2361

Some years ago, after watching me work, my daughter announced to her playmates that a programmer is someone who sits in front of a computer looking things up in books. It seemed funny at the time, but the more I do it, the more I realize she was right. For the uninitiated, here's how to program: open to the index of manual A, turn to half a dozen references before you find what you need, make two keystrokes, then open manual B and repeat the process. While compilermakers toil mightily to shave milliseconds off compile time, we plod through weighty tomes checking error codes, parameter-passing conventions, syntax diagrams and all the rest. Simply put, the greatest obstacle to programmer productivity is the everlasting need to look things up.

Well, Peter Norton has done something about it with his Norton's Guides. The glib hype says it's a product for those who hate manual labor. A more specific description is that it's on-line, language-specific help for serious programmers. Yes, it's another memory-stealing 37K Termininate-and-Stay-Resident program, but think how much desk space it clears up.

Any time you're in text mode editing a program, using a debugger, whatever--Shift-F1 wakes up the Norton Guides by giving you a halfscreen pop-up containing a menu bar. Thoughtfully, the pop-up appears in the half away from the cursor, so that it doesn't obscure the code you're workIng on. You can toggle to full-screen with F9, and make the pop-up go away with Esc or F10.

And what do you get with the pop-up? Initially, a list of every instruction in the language on a scrollable panel. You can also do a key- word search that takes you straight to the instruction you want. Posi- tioning the highlight over an instruction, you press Enter and shazam! you get a detailed description of its purpose and syntax, often with a code example. There are also cross-references to related statements and topics, to which you can jump by pointing to a pick list entry and pressing Enter.

Additionally, the Guides furnish information about specific features of a given language implementation (the library functions of Turbo C and Microsoft C, for example, as well as data types, reserved words, etc.). Another menu selection called Tables leads to all those little details that consume so much look-up time in manuals: the ASCII values of linedrawing and graphics characters, color codes, etc. In short, the Norton Guides furnish, with a few keystrokes, access to most of the information programmers need while in a fever of creativity.

The foundation of the Guides is a $50 program that makes it work. Then you'll also need one or more of the language databases, each priced at $50. The entry price, then, is $100, plus $50 per language thereafter. If you have more than one database, the Options menu lets you switch among them with a couple of keystrokes.

As of this writing, Guides are available for BASICA, QuickBASIC, Turbo BASIC, Turbo Pascal, Turbo C, Microsoft C, and MASM. A spokeswoman for the company says more are in the works and should be out by the time you read this: the OS/2 kernel and Microsoft Windows are two that she'd 'fess up to.

For serious programmers, I recommend a set of two databases: MASM and the high-level language you normally use. That's because the Assembler Guide contains a wealth of DOS-related information not found in the others: error codes, interrupts, file attributes, and descriptions of the PSP and FCB structures, among others. If you want to reach deep into the machine from C or Pascal, you need this stuff.

There's a mistake in the Tables, which are common to all incarnations of the Guides. It says the screen attribute byte is given by 256 * background + foreground; replace 256 with 16. I reported it to the vendor, so it should be fixed in future releases. The Turbo C sample program for vprintf() closes a nonexistent stream. Other than that, my only complaint is that the tutorials are cloyingly cutesy. These minor points are enormously outweighed by the convenience of having a comprehensive language reference instantly available at one's fingertips.

In addition to the basic TSR, the program package includes tools for rolling your own guides. Norton calls them a compiler and linker, but don't be misled; they constitute a text formatter governed by a half-dozen commands embedded in the ASCII files. These "bang commands" associate text lines with menus, set up cross-references, establish linkages among text files, and so on. Once you've linked your files, they become a database available through the Guides' Options menu. It takes about 15 minutes to master the whole process.

This opens the way to tremendous possibilities for application developers. Instead of laboriously constructing help screens and all the code required to manage them, you can write a Guides database and bundle it with your software. Norton Computing says they're willing to license distribution rights to the underlying TSR program.

The Norton Guides don't completely eliminate the need for manuals and reference books, but they reduce clutter around the keyboard. They also let you write code a whole bunch faster, which is good news. This product represents a quantum jump in programmer productivity.

Figure 1: The Norton Guides add on-line help to a number of compilers, including Turbo C.

Soft-Scope Source-Level Debugger Target:

Target: PC/XT and compatibles

Required: DOS 2.0 or later, hard disk, 256K Compiler/linker generating Intel-type symbols

Price: (DOS version only, others available) Debugger is $500 One-year update/support is $100

Vendor: Concurrent Sciences Inc. P.O. Box 9666 Moscow, ID 83843; (208) 882-0445

Throw out the quiche, put the dog in the back of the pickup, and crack open a beer; Soft-Scope is a real man's debugger. No wimpy windows, no frilly function keys, no cuddly colors. No Sir, this is purely a command-driven program on a monochrome screen that keeps on scrollin'. It might be argued that real men don't use symbolic debuggers at all, but those who do will appreciate the full features and solid feel that underlie Soft-Scope's rugged exterior.

Soft-Scope reminds us of the forgotten fact that software doesn't have to be cute to be useful. What it lacks in sex appeal, this debugger makes up for in functionality. It monitors and reports program execution at the source level in any of Pascal, C, FORTRAN, Assembler, and even PLM and JOVIAL. You can set breakpoints on source lines and refer to variables by name when checking or assigning values. If you want to see what the compiler generated from a source line, you can view the resulting machine language as assembly code.

The point of reference when working with Soft-Scope is the source line number, which it gets from the requisite .LST file. Like a BASIC interpreter, it tracks its position in the source file via line numbers, and lists ranges of lines on command. It also associates a line number with a subroutine name, so that you can refer either by line or by name to entry points for setting breaks and the like. A command lets you find out the range of lines for a given routine. This is useful for setting a watchpoint within that range only, using the commands "RANGE 100 120" and "GO TIL .X = 5."

The single-step trace mode works by default at the source line level. You get into single-step with the S command, then keep punching the space bar to execute successive lines. Soft-Scope displays each line as it executes it. If you get tired of this, you can hit Enter instead of the space bar, then specify a speed from 0 (slowest) to 9 (fastest), and the debugger runs in continuous mode, displaying each line as it runs. The Q key (or alternatively Esc) stops it so that you can examine variables. You can also disassemble the source line and single-step at machinecode level, which is a nice feature for uncovering those bizarre glitches that sometimes crop up in programs that tickle the deep innards of the machine.

Soft-Scope has the particularly attractive ability to display the nesting of calls by name. A program crashes in some subroutine and you wonder how on earth it got there; this tells you who called whom, back up to the main program level. You can also list the stack itself to any level from the top down; e.g. "20 STACK" lists the top 20 words. Another command lists the stack size and the high-water mark, handy for diagnosing crashes due to stack overrun.

This debugger understands aggregate data structures. You can display a structure by name, listing its fields and data types, and fetch any of the fields' values. The same is true of arrays, which can be dumped as a whole, by row, or by individual element.

One of the best features of SoftScope is pointer dereferencing. This allows you to follow an indirection chain by dereferencing a series of pointers to an object, whose value appears on the screen. You can also view the resolved address to find out if you've got a screwy pointer. The pointer dereferencing notation is pure Pascal, which might confound those without a Pascal background. Still, it's not difficult to master. If INTPTR is a pointer to an integer, then the value of the integer is represented by INTPTR^. Similarly, STRUCT^.FLD^.OBJ is an indirection chain in which STRUCT points to FLD, which points to OBJ.

Another feature worth mentioning, is Soft-Scope's ability to route all of its prompts and displays to an external RS-232 terminal. This feature makes the program well suited for debugging programs which are highly interactive with the screen cursor position or are graphical in nature.

Soft-Scope's primitive user interface is usually not a problem. Indeed, elaborate displays such as CodeView's often dazzle the eye and thus get in the way. It would be nice, though, if you didn't have to halt the trace in Soft-Scope and type a command to examine registers and variables. Mso, the inability to switch display pages in Soft-Scope means that program and debugger output get mixed together, which can lead to a wild jumble.

Soft-Scope has 37 commands, most of which have several optional modifiers. The program acknowledges human frailty to the extent of furnishing a HELP command that accepts an angument. For example, "HELP SUBMIT" furnishes a synop sis of the command syntax for exercising a debugger script file.

But until you're a certified Soft-Scope guru, you can't effectively work this debugger without the manual at your elbow. The documentation is readable if a bit terse. There are 305 pages of tutorials using several programming languages, and the command reference is 98 pages. A major gripe with the manual is that it lacks an index.

Soft-Scope comes in several flavors. The one I reviewed is for MS-DOS. There are also incarnations for the likes of RTCS/UDI and iRMX. Prices range from $500 for the DOS version up to $2000 for the Intel 310 with iRMX 286 OS, and considerably higher than that for versions working with the Applied Microsystems ES 1800 emulator. Clearly, this is a debugger for serious developers.

Despite its no-frills, macho interface, Soft-Scope delivers for those who can afford it.


Target: PC or PS/2 and compatibles

Requires: DOS 2.0 or later

Pricing: $49

Vendor: Byte Corp. 701 Concord Ave, Cambridge, MA 02138; (617) 868-7704

Every once in a while you run across a smoothly crafted little program and you just hate the guys who dreamed it up: Why couldn't I have thought of that? The only consolation is that it's probably almost as much fun to use as it was to write it.

XO-Shell is such a program. I'm not sure what to call it. It's not really a debugger, nor is it exactly a DOS shell. The vendor refers to it as a programmer's productivity aid. Okay, but it could be a productivity tool for non-programmers, too. Agreement on one point is assured: XO-Shell is slick. It does a lot of stuff that you wish DOS and/or your editor would do.

I tend to have an allergic reaction to TSR's (Terminate-and-Stay-Resident programs). They can so overload memory with conveniences that you don't have enough left to do real work. And so I viewed XO-Shell with a certain wariness, especially in view of its 88K requirement. To exact that kind of price, I figured, it'd better be good.

Your jaundiced reviewer was pleasantly surprised. There's a whole host of goodies that make that 88K worth the cost. On the more prosaic side, XO-Shell stores up DOS commands for recall, edit, and re-execution, and it has a file viewer similar to Xtree and other DOS shells. What sets XO-Shell apart from other shells is that you can do this stuff from within an application such as an editor or the Thtbo/Qw.ck environments. But that's not all.

Say you're editing a program module and you've forgotten the exact spelling of a variable defined in a different module. With XO-Shell, you can pop up the other module and check it, or print out a portion of that code, without leaving your edit session. Whoops! You just noticed an error in the other module. No sweat, XO-Shell lets you correct it on the spot, then escape back to your main editing job. All it takes is the Alt-n hot key and a few keystrokes.

Last month you wrote a nifty little algorithm, and now you need to plug it into your latest masterpiece. Position the cursor where you want it to go, bring up that old file with XO-Shell, and mark the text with some Wordstar-like commands. When you leave XO-Shell, it copies the marked text into the new program, effecting a clipboard.

Maybe you remember the name of that algorithm, but not the name of the source file containing it. XO-Shell has a grep-like facility to search file groups for a specific string. Function keys direct the search results to the screen, the printer, or a file, and you can save the files list for future use in wide-ranging searches. XO-Shell also searches the file currentiy being worked on, in case your editor lacks this elementary capability.

Few things are as annoying as having to leave an edit session and list the directory simply because you forgot the name of an include file or data file. XO-Shell lets you list a directory while editing. It can also search directories to find a specific file if you can't remember which sub it's in. And if, while browsing among files, you decide it's time to clean up some directories, XO-Shell has the ability to copy and erase. When you're done, hit Esc and resume editing.

So now the program is done, but there's a variable name you want to change, or maybe one that's declared but possibly not used. Pop into XO-Shell and do a cross-reference listing among the program modules. It lists every line, identified by file, where the variable occurs.

There are other things as well. For example, XO-Shell can save output screens from your program in a disk file, and restore them later for double-checking. For another, there's a pop-up via Alt-m that shows all 256 characters; pick one from the display and plug it into your edit screen. Even if your editor can't generate graphics characters, you can incorporate them into the text this way. And XO-Shell lets you drag them around and replicate them, providing for text boxes and other visual effects in source listings, as well as direct encoding of special characters in string literals.

Aside from the hoggish 88K, my only criticism of XO-Shell is that the helpful hints on the prompt line (which appears only in response to the hot key) aren't very helpful. Such things as "F9:Chng__para" are far from intuitive, even for C cowboys.

XO-Shell has won its way into my programming toolkit, and I recommend it.

Microsoft Macro Assembler 5.0

Target: PC or PS/2 and compatibles

Requires: DOS 2.0 or later, hard disk recommended. Minimum 256K memory, 320K recommended

Price: $150

No licensing restrictions on generated code

Vendor: Microsoft 16011 NE 36th Wy, Box 97017, Redmond, WA 98073 (206) 882-8080

The latest release of Microsoft's venerable MASM brings a new level of productivity to this most tedious of all programming languages. It's loaded with new features, most importanfly a bundled copy of the CodeView symbolic debugger.

Microsoft claims that MASM 5.0 assembles 25 percent to 40 percent faster than 4.0. I didn't validate this with any test suites, but it is screamingly fast on an AT: under two seconds for a 150-line program and about five for an 800-liner, which is noticeably faster than earlier versions of the assembler.

With release 5.0, MASM now supports the instruction sets for all PC processors up through the 80386/387. The default mode of the assembler is the 8086 instruction set; pseudo-ops such as .386 and .387 tell the assembler to honor instructions for the indicated targets. If you forget to include the appropriate directive, the assembler scores a severe error for each non-8086 instruction and issues a complaint.

Speaking of pseudo-ops, one potential gotcha for those migrating upward to 5.0 has to do with the encoding of floating point numbers. Before, MASM encoded real numbers in Binary format. The default in 5.0 is the IEEE floating point standard, compatible with 80x87 math coprocessors. If you still want Microsoft binary format, you have to assert the new .MSFLOAT directive.

Yet another pseudo-op called MODEL implements memory models, new with MASM 5.0. Its operands are SMALL, MEDIUM, COMPACT, LARGE, and HUGE, which correspond to the models available in high-level Microsoft languages such as C and Pascal, as well as in Turbo C and, to a lesser extent, Turbo Pascal 4.0. This addition simplifies the assembler interface to other languages, since it generates pointers of the correct size for the high-level model being used. Clearly, the emphasis is shifting away from assembler as a primary language to assembler as a language for linked high-performance subroutines, and this addition to MASM recognizes the trend.

To that end, MASM 5.0 furnishes a macro library for mixed-language programming. This file, MIXED.INC, includes macros for passing and receiving anguments, allocating local variables on the stack, segment fixups, exit processing, and other high-level interfacing needs. The macro library is propped up by and excellent 1440-page guide covering a range of mixed-language programming issues.

The overall quality of the manuals is much better than any previous Microsoft documentation. In addition to the mixed-language guide, there are two soft-bound books, a 467-page Programmer's Guide and a 401-page volume covering CodeView and other utilities. Rounding out the documentation is a 148-page wire-bound reference divided into five tabbed sections. Intended to be kept at the programmer's elbow, this reference summarizes every instruction, pseudo-op, and command-line switch. There are several brochures and a function-key template for operating CodeView.

If you haven't worked with CodeView before, you're missing out on the finest thing Microsoft has done to date. This is how God intended a symbolic debugger to be. It's a wonderfully visual environment that lets you watch your code execute while keeping an eye on registers and selected memory locations. Codeview runs in a secondary video page, thus not interfering with programs that do graphics or fancy text screens, and you can easily toggle back and forth between the CodeView display and your program's output. Accommodating to all and sundry, CodeView lets you control it via pulldown menus, function keys, typed commands, or a mouse: your choice.

An example of the possibilities with this debugger is a thing called a watchpoint. You can tell CodeView to watch a memory location or even a register and, when it changes to a specified value (or changes at all), Codeview halts and reports the condition. If you've got several watchpoints and breakpoints set, the CodeView display twinkles like Times Square on Friday night, but without the chaos; you are actually watching your program run.

CodeView is not specific to MASM 5.0. It works with all of Microsoft's flagship languages: C, FORTRAN, Pascal, and QuickBASIC. All that's required is to compile and link with certain options, and then you can debug an entire application written in any combination of these languages. Alas, it doesn't work with Turbo languages, but that's hardly surprising.

MASM 5.0 doesn't reduce the notoriously finicky detail of programming in assembly language, but it makes for more productive tedium.

Figure 2: MASM 5.0 includes Microsoft's CodeView Debugger


Target: PC or PS/2 and compatibles

Requires: DOS 2.0 or later, hard disk recommended

Price: Annual fees for single-user, department, and site licenses start at $5,750; demo version available.

Vendor: Cinnabar Software 2704 Rio Grande, Ste. 1, Austin, TX 78705 (512) 477-3212

CheckMate is a quality assurance tool which runs on a PC or compatible allowing a tester to easily set up automatic scripts for testing communications. CheckMate is intended to test the host computer or communications service (hardware or software) to which the PC is attached.

At the highest level, CheckMate consists of a terminal program. Unfortunately, CheckMate does not emulate any of the popular intelligent terminals such as the VT100 (this feature is scheduled for inclusion in the summer of '88). It does, however, provide a lot more control than is normal with such programs. All communication parameters are accessible. In addition, a high level screen log and a detailed screen trace record all that is happening, both from the keyboard and from the communications ports. Turn your modem off or drop carrier and it's instantly recorded on the trace.

CheckMate also provides a capture mode. In this mode, the user goes through a normal communications sequence. CheckMate makes detailed notes on what was entered at the keyboard and what was received at the COM ports, writing this information into a "script" file. During replay, CheckMate makes the keyboard entries and compares the results with what it expects. CheckMate also notes changes in line status such as Carrier Detect or changes in baud rate. The executing sequence can be viewed in progress from the trace screen. Deviations from the expected are noted in the log file. Both the log and the trace can be recorded on disk for later perusal or as an testing audit trail.

CheckMate is designed to allow the user to set up scripts for testing every feature of his product. With such scripts, the user can build a test suite for acceptance testing of the program or service. This suite can be built upon as each new generation is developed. In this way, the tester is assured that no existing features have been "broken" by new additions. These scripts can also be used as a routine status check or to "attack" the system, running the same sequence over and over until a failure occurs.

Unlike most other communications software, however, CheckMate's script files are recorded in Microsoft 4.0 compatible C source code (an example script, created by CheckMate but with comments provided by Cinnabar, appears in Listing One). To play a script back, the user must exit CheckMate, compile and link the C program into an executable file that can then be played back from within the program. CheckMate is intended to handle large, carefully designed scripts which the user might run hundreds of times. The time to compile might be a nuisance during the actual development if it takes multiple iterations to get the script right.

For this, the user gets some pretty significant advantages. Compiled scripts run faster with better timing control than an interpretive script can. Roughly half of the user manual is devoted to a description of the system calls available to the CheckMate programmer. In addition, CheckMate's scripts can be edited by a C programmer to add any extra features desired. The complete C language is at the programmer's disposal.

While not for everyone, CheckMate should be an interesting product to those companies which provide communications services or which make heavy internal use of serial communications. CheckMate can also be used to test mainframe software by simulating multiple users logged into serial terminals. CheckMate comes on two floppies within a 8.5-by 11-inch 3-ring binder.

The single CPU license fee for CheckMate is $5,750 per year. A demo version can be ordered for $49.95. CheckMate requires 320k and DOS 3.1 or better to run.

by Randy Davis

Example 1: C source code generated by CheckMate

Related Reading

More Insights

Currently we allow the following HTML tags in comments:

Single tags

These tags can be used alone and don't need an ending tag.

<br> Defines a single line break

<hr> Defines a horizontal line

Matching tags

These require an ending tag - e.g. <i>italic text</i>

<a> Defines an anchor

<b> Defines bold text

<big> Defines big text

<blockquote> Defines a long quotation

<caption> Defines a table caption

<cite> Defines a citation

<code> Defines computer code text

<em> Defines emphasized text

<fieldset> Defines a border around elements in a form

<h1> This is heading 1

<h2> This is heading 2

<h3> This is heading 3

<h4> This is heading 4

<h5> This is heading 5

<h6> This is heading 6

<i> Defines italic text

<p> Defines a paragraph

<pre> Defines preformatted text

<q> Defines a short quotation

<samp> Defines sample computer code text

<small> Defines small text

<span> Defines a section in a document

<s> Defines strikethrough text

<strike> Defines strikethrough text

<strong> Defines strong text

<sub> Defines subscripted text

<sup> Defines superscripted text

<u> Defines underlined text

Dr. Dobb's encourages readers to engage in spirited, healthy debate, including taking us to task. However, Dr. Dobb's moderates all comments posted to our site, and reserves the right to modify or remove any content that it determines to be derogatory, offensive, inflammatory, vulgar, irrelevant/off-topic, racist or obvious marketing or spam. Dr. Dobb's further reserves the right to disable the profile of any commenter participating in said activities.

Disqus Tips To upload an avatar photo, first complete your Disqus profile. | View the list of supported HTML tags you can use to style comments. | Please read our commenting policy.