Loadstar 128 #29/q29.d81/t.st demo

Text File | 1992-01-01 | 16.1 KB | 353 lines

                            S T E P T R A C E R

                       Program and Text by e. g. bell


FENDER'S PREMUMBLE: StepTracer is a programmer's utility and is not
designed to be something you can access from LOADSTAR 128's menu.  However,
ed has provided a revised version of CONTROL80's demo, which shows you that
StepTracer works with CONTROL80 programs -- at least on a C-128D.  I
couldn't get it to work right on a flat C-128, so I don't recommend looking
at the demo on a flat C-128 unless you like a blank screen half way through
the demo.  My theory is that CONTROL80's VLOAD command is a little too
weird for StepTracer.  It's also hardcoded for drive 8.  I don't consider
VSAVE and VLOAD to be among CONTROL80's more useful commands so you should
still be able to use StepTracer with your CONTROL80 programs.  Even on a
C-128D there is a spot at the end of the demo where it asks you to press a
key while the screen scrolls horizontally.  Press RESTORE instead and you
get back to the demo's title screen where you can return to LOADSTAR 128.


*** StepTracer

    When debugging a BASIC program, it is often necessary to follow the
flow of logic.  When you get unexpected results, is the program doing what
you want it to do or is it just doing what you told it to do?  There are
several utilities of varying degrees of usefulness in determining this.

*** Dump

    There are 'dump' utilities which dump the names and current values of
all variables.  Using such a utility usually requires frequent STOPs to
check these values at various points in the program operation.

    This can be useful in determining why or where something is happening
in a program, but a computer executes a program at an extremely high rate
of speed.  Couple that with the many twists and turns the program can take
while getting from here to there and it can be a long, time-consuming
process to isolate and fix some problems using only a dump utility.

*** Follow Me

    More useful are the 'trace' utilities.  Most of these trace program
flow by printing the line number, to the screen inside brackets, of the
BASIC statement currently being executed.  For example, consider the
following code:

      10 print chr$(147):na$="":cnt=0:input "Enter Name  ";na$

If you used the BASIC 7.0 TRON command, it would produce the following
screen display:

      [10][10][10][10]Enter Name  ?

If you have never tried this with your Commodore 128 BASIC programs, type
TRON then run any BASIC program.  [TROFF toggles this function off.]

    There have been many such utilities published for the C64 over the
years also.  Most, if not all of these, function exactly the same.  As
helpful as this type of utility is, as you may have noticed from the
example, there are some serious limitations.

*** Drawbacks

    First, using this type of trace, screen display is hopelessly disrupted
as rows and rows of line numbers are dutifully displayed onscreen starting
wherever the cursor happened to be resting at the time.  There is much
information presented, but it is confusing if you can use it at all.  This
is particularly true in the case of deeply nested loops or GOSUB/GOTO
procedures.  The information can be simply overwhelming.

    Second, often you know where something is happening, but cannot locate
where the offending code is being called.  This can be particularly
troublesome to find if the code is called from several places.  Which call
is causing the problem?  StepTracer will help you isolate such calls
quickly.  This capability of StepTracer will help you find and correct the
problem areas instead of wasting a lot of time looking at the wrong place
in your code.

    Third, the trace, like the program being traced, is operating at
extreme speeds.  It is virtually impossible to visually follow the
execution unless frequently stopped by user input or STOP statements.  This
can be irritating and confusing.  If sections of the code being traced
clear the screen, it can be quite impossible.  If you STOP the program, you
must start it again with a GOTO, CONT, or RUN.  If you merely request user
input, the screen display problem mentioned above presents itself,
particularly if you are trying to find out why something is being displayed
WHERE it is being displayed.

    Finally, you learn little from only a line number unless you are
working with a program listing in front of you, especially when a problem
involves several lines or routines.  Since you are usually the person who
wrote the program, it is your logic.  If the logic in the listing was
working as expected, you wouldn't need to trace the flow.  In addition, if
the program flow jumps around a lot, with GOSUBs for example, it can become
difficult to follow the logical flow from a listing alone.  So a listing by
itself is often of limited help in battling some bugs.

*** A Solution

    There is a solution.  StepTracer is a short single-step trace routine
for the Commodore 128 in 80 column mode.  It will not work in 40 column
mode.   StepTracer will lead you along the precise route your program is
taking.  But it does more!

    More than just the line numbers, the complete segment of BASIC code TO
BE EXECUTED is displayed for you prior to its execution.  You know what
will take place and in which line it was commanded to do so just BEFORE it
actually happens.

    If that is not enough, there is virtually no disruption of screen
display.  Using some interesting capabilities of the VDC chip in your
Commodore 128, StepTracer gives you some extra lines at the bottom of your
screen IN ADDITION TO the normal 25 lines.  But it does still more.

*** Single Step

    Even displaying a segment of code would be of minimal value if it
happened at extreme speed, so StepTracer is an adjustable speed trace
utility AND a single-stepper.  You may slog through your code at various
speeds OR step through your program one segment at a time if you like.

    In single-step mode, after the program segment is displayed, you must
press a SHIFT Key to continue.  (In single-step mode, a '*' is displayed
after the line number and before the program text to flag that user input
is expected before the program can continue)  When you do, the segment of
code you are looking at is executed and the next segment is displayed.  If,
for example, the current segment says GOTO 50 the next thing you will see
in the trace window is the first code segment of line 50.  This feature
could also be helpful to novice computer programmers wondering what
different segments of someone else's code do.

    In single-step mode, if you want to stop the program for editing, you
must press the STOP key and then press the SHIFT key to resume execution.
The program will then stop normally.

    Note that I refer to code 'segments' above rather than just 'lines'.
This is because BASIC evaluates lines of code in this manner when there are
multiple commands on a single line.  In cases like this, StepTracer lists
each such command individually, just as BASIC will execute it.  The line
number remains onscreen though, so regardless of which segment is being
displayed, the appropriate line number is always evident.

*** Tron

    Using StepTracer is very simple and will interfere with no BASIC
programs.  First, you must install it using the BLOAD command:

    bload "StepTracer"

Next, you simply activate it:

    sys 2816,a,b

    a =    0-Trace Disabled    1-Trace Enabled

    b =    0-6 Speed of trace display   0-fastest  6-slowest
or  b =    128 Requires pressing SHIFT after each segment displayed

So, to turn the trace on with a speed factor of 3, the command would be:

    sys 2816,1,3

To turn the trace on with a speed factor of 0, the fastest possible, the
command would be:

    sys 2816,1,0

To turn the trace on and specify that you must press the SHIFT key after
each segment is displayed, the command would be:

    sys 2816,1,128

If you just want to toggle trace mode on with the current speed setting
unchanged, you may use the BASIC 7.0 'TRON' command in your BASIC program.
StepTracer recognizes this command as its own and resumes the trace.  For
this reason, the normal function of TRON is disabled if used in program
mode.  If you use TRON in immediate mode, simply typing it and pressing
RETURN, it will function normally until StepTracer is activated.

*** Troff

    To turn the trace off, disabling StepTracer, the command would be:

    sys 2816,0
 or sys 2819

If you just want to toggle trace mode off with the current speed setting
unchanged and StepTracer enabled, you may use the BASIC 7.0 'TROFF' command
in your BASIC program.  StepTracer recognizes this command as its own and
stops tracing.  The last command executed before the TROFF command will
remain on display on the trace line, but line by line tracing will stop.
For this reason, the normal function of TROFF is disabled if used in
program mode.

*** Tweaking

    You can adjust StepTracer trace speed from within your program without
using the SYS command if you like.  To do this, POKE the appropriate value,
from 0 through 6 (or 128 for prompted mode), into address 2822.  This POKE
does the same thing as the 'sys 2816,1,#' command.  This is useful when you
want a loop to proceed at full speed and then slow the trace down again
afterward.  For example:

    100 poke 2822,.
    110 for x=1 to 1000:read a:poke b+z,a:z=z+1:next
    120 poke 2822,1

This example is the same as the one above using the SYS call with the speed
factor set to zero.  The two methods may be used interchangeably.

    You can also do some dynamic temporary tweaking to the trace speed.
This technique is primarily for programmers who write structured code using
subroutines.  You may want to zip through a section of code that you are
tracing.  You can do this in one of several ways.

  o As mentioned above,  you can POKE a zero into 2822, and a 1 or
    other value after the routine is complete.

  o You can use the TROFF and TRON commands before and after the
    routine.

  o You can also tap the RESTORE key.

The RESTORE key will drop the speed setting of the trace to zero until the
next RETURN statement is encountered in the BASIC code.  At that point, the
original speed setting is restored.  Using this feature, if your programs
are very structured, you can set the trace speed once and interactively
'hurry' through areas that are repetitive and unnecessarily slow down
StepTracer.  An example of this situation would be a READ/POKE routine that
installs sprite data or machine language routines.

*** Caveat

    There are some situations that StepTracer cannot handle, or which will
cause StepTracer to fail.  One of them is to try to bload StepTracer while
it is already active.  This will cause a lockup.  The recommended procedure
is to bload StepTracer prior to running the program you want to trace.

    You may activate StepTracer with the SYS 2816,1,# command in immediate
mode before running the program or from within the program itself.  You may
even use this to change the speed of the trace during the program
execution.  It is only reloading of StepTracer over itself that causes the
problem.

*** REU and RAMDOS

    StepTracer will work with any BASIC program that does not use the 4
memory pages $0b00 through $0eff.  If you are using a Ram Expansion Unit
and RAMDOS, you should not use any of these for the interface page.  Select
page 15 ($0f00) instead and you will have no problems.  A good workaround
for this is to simply disable those parts of your program that use RAMDOS
until the other parts are debugged if you absolutely must have RAMDOS
installed in this area.

    Also note that if you are using RAMDOS, you should install StepTracer
BEFORE you install RAMDOS.  The first time StepTracer is loaded and
installed, a help screen is displayed.  This screen is disabled after the
first display, but most of it lives in page $0f00, where RAMDOS must be
installed.  Therefore, StepTracer MUST be BLOADed and installed before
RAMDOS.

*** VDC Considerations

    It is the VDC chip that gives the Commodore 128 its 80 column
capabilities.  One of these is the ability to display more than 25 lines on
the screen.  StepTracer mines this treasure, and this is the reason it only
works in 80 column mode.

    StepTracer makes some adjustments to the VDC attribute settings in
order to tweak several extra lines onto your screen.  It is here that the
trace display appears.  Some programs that use other buffers in the VDC for
storage, etc. may have some problems with StepTracer enabled.  These
problems are not fatal to StepTracer.  They might affect, for example,
programs that use RAM in the VDC chip to store and recall program screens.
They also may affect the status line display of StepTracer.  Some of the
effects in the Control80 demo cause the display of StepTracer to be
momentarily off the screen or unreadable.  Again, simply use StepTracer to
debug the other parts of your program first, disabling these spots in your
code.  When the other problems are removed, complete your debugging without
StepTracer.  I suspect that most BASIC programmers will never find this to
be a problem.

*** The Getaway

    When you are finished debugging your program, you should make sure that
StepTracer is disabled using one of the two methods described above.
(Either 'sys 2819' or 'sys 2816,0')  This will assure that your VDC is
properly reset.  You can't hurt anything if you don't reset the VDC, but it
may cause display problems for subsequent programs.

    More important than the VDC is the BASIC execution vector which MUST be
restored to its default state.  This is very important and can cause some
very weird things if you don't reset the vector.

*** Harmony

    StepTracer can exist quite peacefully with Control80 and programs that
use it.  There are no memory contentions and I added the code to recognize
and trace the Control80 commands.  (The lone exception to this MIGHT be the
'MINE' command.  Control80 is flexible in that add-on routines can be
written to execute anywhere in memory, requiring only a POKE to the main
code to direct Control80 to the new code.  Any such add-ons that were
written to load and execute where StepTracer lives are obviously going to
cause a serious burp if used with StepTracer.)

    mEGaBasic is another matter.  If you are using my mEGaBasic utility,
make sure you disable StepTracer (sys 2816,0  or  sys 2819) before enabling
mEGaBasic.  All of mEGaBasic's command functions use the same memory as
StepTracer.  The problem this will cause relates back to the restoration of
the BASIC execution vector.  This vector under StepTracer points to a new
section of code.  mEGaBasic is going to change the code. The problem will
show up immediately when you try to press RESTORE, RUN/STOP RESTORE, or run
your program.  The simple solution is to make sure StepTracer is disabled
before you enable mEGaBasic.  This also means, obviously, that StepTracer
will have to be reloaded and reinstalled the next time it is needed.

    If you make a mistake and activate something that causes a problem,
there is something you may be able to do to make a spot correction to at
least allow you to save your work and do a RESET.  If you are using
mEGaBasic, you can do a reset then use the OLD command  (or the '@o'
command if you have JiffyDos).  If you don't have either of these at your
disposal, try this:

    First, type 'MONITOR' and press RETURN to enter the machine language
monitor of your Commodore 128.

    Next, type the command 'm 0308'.  This will bring up a dump of memory
starting at address $0308.

    Now, move your cursor up to the start of the hex code after address
$0308.  Replace the first two values with the values 'a2 4a'.  This will
repair the BASIC execution vector.

    Next, move your cursor to the line starting with address $0318.

    Replace the first two values in that line with the values '40 fa'.
This will restore the NMI vector to normal.

    From here you should be back in business.  Save whatever you were
working on (using a new name so as to protect your disk backup) and reset
the computer.  Now reload the new version and start again.

*** A Perfect World

    In a perfect world, there would be no need for trace utilities.  We
would write things that worked perfectly the first time out.  That is not
yet the case.  In the meantime, though, there is StepTracer.

                \\\\\ RETURN - Menu   R - Run \\\\\