Category : Dbase (Clipper, FoxBase, etc) Languages Source Code
Archive   : BUG11.ZIP
Filename : BUGGR.DOC

ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿
³ ³
³ Little Bugg'r (tm) ³
³ ³
³ Interactive Source Code Utility v1.1.0 ³
³ Copyright (C) Dirk R. Bliss, 1989 ³
³ ³
³ ³
³ For use with Clipper (Summer '87) ³
³ Interactive Debugger ³
³ ³
ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ


-2-





It does WHAT...?
ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ


Little Bugg'r is linked into your application along with
Nantucket's debug utility (debug.obj) and the extend library
(extend.lib). It can then be used to display each line of source
code that corresponds to a statement in your compiled program. The
net effect is a source level trace function that allows you to
watch your program execute. This is much more meaningful that
watching line number flash by, and it can be a great help in
locating those difficult to find programming bugs.

Any number of source modules can be traced in a given application
so long as no single module is larger than 64K in size. If any
.PRG file is larger than 64K, it will need to be split into
multiple files to be traced. Don't specify the name of one of
these large .PRG files in a TRACE() statement unless it has been
broken into smaller files first.


-3-





How to use Little Bugg'r...
ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ


Make sure that when you compile your application, you compile WITH
line numbers. That is, don't use the " -l" parameter in the
Clipper command line. You will also need to add a few lines of
code to the program you want to debug.

TRACE(.T., "" ) && Enable TRACE, and select .PRG

You will need this at the top of your program, or possibly at the
beginning of each module you want to debug if you use multiple
.PRG files.

The first operand is a logical expression that enables tracing and
allows the TRON() function (more on TRON later...) to open the
source window. The second expression is simply the name of the
source code file in quotes. If you're debugging a system composed
of several different .PRG files, you may want this line to appear
in several different modules. If the trace utility can't find the
file you've indicated in your TRACE() statement, the window will
continue to display line numbers, but will cease displaying code
until re-initialized by a TRACE() statement that contains a valid
file name, eg; TRACE(.T., "").

After the name of the source code file has been specified, you can
optionally disable the display window by putting TRACE(.F.) in
your code or enable it again by inserting TRACE(.T.).

ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿
³ The window hasn't appeared yet, but the next section ³
³ gives the final detail on that... ³
ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ

Link your application with Little Bugg'r object file (bugr.obj)
and Nantucket's interactive debugger (debug.obj). You must also
include the Extend library (extend.lib) in your compilation.


-4-





Opening the View Window...
ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ


To actually begin viewing the source code, you need to activate
the Clipper debugger by inserting an ALTD() in your code, or by
pressing the ALT-D key sequence. Then toggle over to WATCH,
select the SET and then the ADD option and enter:

TRON(PROCLINE())

This stands for "TRace ON", and the PROCLINE() parameter feeds the
current line number to the TRACE() utility. Once you've entered
the TRON(PROCLINE()) statement at the WATCH option, you won't need
to do it again unless you re-start your application from the DOS
prompt.

If you have previously specified TRACE(.T., "program name") in
your application, a window will open on the screen displaying a
five line section of your source code with the current line
highlighted (if you haven't, your program will abend!). If you
have specified TRACE(.F., ""), the window won't open
until it encounters a TRACE(.T.) in your code.

From here, you can select whatever additional Clipper debugger
options you need. When you are satisfied with your choices, you
may toggle over to the CONTROL menu and select SINGLE STEP, or GO
(AUTOMATION) and watch as your source code appears in the viewing
window. The other debugger options are also available.

NOTE:
Larger source code (.PRG) files can cause much slower execution
speed on "XT" class machines. Source files under 15K will provide
optimum speed of execution while files from 30 - 64K in size may
slow execution depending on the processing power of the CPU. The
difference becomes negligible on 386 and fast 286 machines. If
speed is a problem in your application, consider limiting the
extent of the trace by inserting TRACE(.T.) and TRACE(.F.) at
strategic places in your code. In this way, you can exclude any
unnecessary tracing.


-5-





Enough already...what do I put in my code...?
ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ


TRACE(.T., "program.prg") && This line points to source code and
&& turns trace function on. Could be
&& .F., and may be used with different
&& program names in other modules.
&& Specify .F. if you like and turn the
&& trace function on later in the code
&& with TRACE(.T.).
Your program continues
here...
.
.
.

TRACE(.T.) && (Optional) Can be used to turn trace on
. && at a specific locations.
.
.

TRACE(.F.) && (Optional) Turn it off again where you
&& like.


ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿
³ To open the trace window, call the debugger (ALT-D), ³
³ and enter TRON(PROCLINE()) at the WATCH option. Then ³
³ select the GO option of your choice. SINGLE STEP and ³
³ GO (ANIMATION) will allow you to view your source code ³
³ during program execution. ³
ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ


-6-





And one other utility, DELAY()...
ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ

There may be occasions during the debugging process that you will
want to step through a section of code without waiting for Bugg'r
to display each line. If the "GO (animation)" selection speeds
through too quickly to watch, and "GO SINGLESTEP" is too tedious
to endure, link Bugg'r into your application (w/ Extend.lib) and
use Buggr's DELAY() function.

Activate the Clipper debugger by inserting an ALTD() in your code,
or by pressing the ALT-D key sequence. Then toggle over to WATCH,
select the SET and then the ADD option and enter:

DELAY() && You may enter an optional delay factor

This will cause a .2 second delay for each line executed in your
program. This is a clock dependent function so the speed of your
CPU is not a factor in the delay. This should give you an
opportunity to follow the program flow without slowing execution
unbearably.

You may also enter a delay factor of your own. If you wanted a
slightly longer delay, you might enter "DELAY(.5)". This would
provide a one half second delay between lines. Entering a factor
of 1 would allow 1 second between lines and allow you the luxury
of following along with a numbered copy of the source code (use
Nantucket's LINE.EXE to number your program).

You won't need to change anything in your source code to use the
DELAY() function. Just enter "DELAY()" at the WATCH option in the
interactive debugger.

Also, DELAY() uses the INKEY() function and so is not a true wait
state. Once you add DELAY() to your WATCH list, and restart your
application, you won't be able to return to the debugger (ALT-D)
until you hit a true wait state (READ, etc.) within your code. You
CAN hold the SPACEBAR down during a DELAY() to speed things up.
Holding the SPACEBAR will eliminate most of the time delay and
allow you to "speed" to the desired location.


-7-





OK, so how much...?
ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ


AGREEMENT:
You may use this code for 30 days, free of charge. If you decide
to continue using it after the 30 day evaluation period, you must
register your copy by sending a $15.00 check or money order to:

Dirk Bliss
7615 N.E. 54th Avenue
Altoona, IA 50009
Tel: (515) 967-4103
CIS: 72137, 3245


I, in turn, will send you a copy of the latest version of Little
Bugg'r, embedded with your own personal serial number on 5.25 inch
diskette (or 3.5 inch if you so request).

If you would like to purchase a SITE LICENSE so that you may use
Little Bugg'r on any number of your PCs in one company at a single
address, send $30.00 as instructed above and I will send you a
copy of the latest version, embedded with your own site-license
serial number on 5.25 inch diskette (or 3.5 inch if you so
request), which you may copy to your hearts content as well as the
source code which you may modify for your own use.


-8-





How did this thing come about...?
ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ


I was scanning the Nantucket area of Compuserve the other day and
came across a likely looking Clipper utility that was supposed to
display Clipper source code as the program executed. Not being
familiar with Microsoft's Codeview debugger (I'm not a "C" or
assembler programmer), I was stunned by the possibilities. What
an aid to debugging! I anxiously downloaded the file and attempted
to link it into a fairly large application that I had been
struggling with.

I found more wrong ways to use that utility over the next two days
than you'll ever imagine. I was plagued by software explosions,
untraceable (to me, anyway...) abends, and "out of memory" errors.
When I did experience some limited success (I had to settle on
tracing the entire program instead of just the section I wanted to
see), the source window ran so slowly, I found it useless for my
purposes (I later found that speed was directly tied to .PRG file
size).

Extremely disappointed, I was convinced there had to be some way
to make it work, but I didn't have any more time to spend on it.
Assuming the author had written it in "C", and with no comparable
experience, I reluctantly abandoned the utility.

Over the weekend, I mulled it over, examining the possibility of
creating something similar. Since the only PC language I'm any
good with is Clipper, I tried to come up with some way to
implement a code view utility in Clipper.

Sometime between Saturday night and Sunday morning, a solution hit
me. I grabbed the keyboard to try it and sure enough, it didn't
work at all. I was on the right track, however, and I soon found
a solution that did work.

What you have before you is the result of my Saturday night
inspiration and my Sunday afternoon labor + 40 hours of re-writing
it 20 different ways to get it exactly right. I hope you like it.
Half the fun of being a programmer (in my case, anyway) is having
people tell you that they like something you wrote. Enjoy...


Dirk Bliss


-9-




Anomalies
ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ


The very nature of this software may cause a problem on occasion.
During a trace, the TRON() function is called every time a line is
executed so the code window can be updated. Since a function has
to return some value (no way around it), TRON() returns the status
of TRACE(); .T. if TRACE() is currently on and .F. if it is off. I
suspect that the logical value returned from TRON() may interfere
in a few cases with the passing of parameters between program
modules. TRON() does interfere with the PCOUNT() function, used
to determine the number of parameters passed between functions /
procedures. IF you have unknown abends, or a certain function
returns a peculiar value or produces an error that you've never
seen before, try it again without Bugg'r and see if the
peculiarity persists.


Problems have been noted in some of these situations:

(1) User Defined Functions w/optional parameters -
Functions that pass nothing and then test a parameter.

(2) undefined identifier (related to #1)

(3) Printing routines -
Since I-O is usually directed out one of the printer ports,
there is little hope of using Bugg'r while printing. If you
have registered a site license, you will receive a copy of the
source code which you could modify for your particular
situation. You will also need Clipper, Summer '87 to
re-compile Bugg'r.


If someone can tell me how to "pull out" the return value from a
function, I will attempt to correct this situation.

I hope you find Bugg'r helpful. If you have suggestions for
improving Bugg'r, I would be very glad to hear from you. As a
small token of my appreciation for any suggestion that is
implemented, I would be pleased to send you a licensed copy of the
program with your corrections / modifications at no cost,
regardless of whether you are a registered user, or just
evaluating the program.


-10-





Acknowledgements
ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ


I'd like to thank the author of the original "Codeview" type
utility, Darren J. Forcier. I loved his idea of adapting the
"Codeview" technique to Clipper. My thanks to Darren for his
vision.

My thanks to Bruce Ireland, who never seems to run out of
excellent programming suggestions and to Dave Antila for his
helpful comments and ideas.


***


Clipper and Clipper (Summer '87) are a registered trademarks of
Nantucket Corp. Codeview is a registered trademark of Microsoft
Corp. PC/XT is a registered trademark of International Business
Machines.