---------------------------------------------------------
The Liberty Basic Newsletter - Issue #34 - MAY 99
"Knowledge is a gift we receive from others."
		- Michael T. Rankin
---------------------------------------------------------
In This Issue:
1)  Editorial
2)  The Mechanics of Debugging.
------------
In Future Issues:

- Parts 3, 4 and 5 of Dean's series on Disk File Functions.

- Theory of Debugging.

- More great articles by guest authors!
---------------------------------------------------------
1)      EDITORIAL:
An observation:  We have more than 150 subscribers to this
group.....GREAT!  In the last 2 months (approximately) SIXTY
of these great folks have posted here.  Their contributions
include questions, comments, answers, suggestions,sample
code (very helpful!) and sample tkns (not as helpful!)  It is 
gratifying to have 60 of 150 people who actively participate,
so Brosco and Alyce want to say to you all THANKS ! ! ! !
(This includes a special thanks to Guest Authors !! )
To the 90 people who receive all of the benefits of this 
newsletter group, but who do not participate, we'd like to say
PLEASE PARTICIPATE!  Each person has something of value to
contribute.  You can put an FAQ in the FAQ area of the database
on our eGrous website.  You can answer a poll there, also, or even
upload a helpful program or article to the Vault.  You can comment
on the content of newsletters - tell us which ones are helpful - 
suggest topics for future newsletters.  Ask a question!  This group
is famous for treating questions kindly, so you can be assured that
you won't be flamed for asking a dumb question...there is no such 
thing!  How about suggesting someone to be next in the Programmer's
Spotlight?  We'll be watching for some new names to be posting here
really soon!  Thanks in advance, from the old fogies.
---------------------------------------------------------
2)     MECHANICS OF DEBUGGING:

There is not a single way that is best for debugging all programs!  
If there were such a magic solution, it would surely make things 
easier!  If you can isolate the problem to one spot, you might 
find it easiest to debug with a notice message.  If you have a 
number of variables to track, you might find it best to write 
their values into the main window.  If you cannot isolate the 
problem to the value of a single variable, or the performance 
of a single routine, then you have a good friend in LBs debugger.


DEBUGGING WITH THE NOTICE MESSAGE
If you have just one or two sticky places in your code, it will 
be easy to debug it by using LBs NOTICE message.  One example 
would be an API call problem.  If the call doesnt seem to be 
working, try giving yourself a NOTICE of the result.  We often 
make the call to GetDC:

open "user" for dll as #user
   calldll #user, "GetDC",_
   Wnd as word,_
   hDC as short
close #user

The return from the call is the handle of the Device Context.  
To check if the call worked properly, give a NOTICE of the 
returned hDC:

NOTICE str$(hDC)
or 
NOTICE "hDC is:  " + str$(hDC)

If the NOTICE tells us that the hDC is 0, then we have found 
our problem.

We can also give ourselves a NOTICE for the values of variables:

pets = cats + dogs
NOTICE "Number of pets is:  ";pets
or
NOTICE "Number of pets is:  " + str$(pets)





DEBUGGING WITH THE MAIN WINDOW
The notice message can get pretty annoying if you have a number 
of variables to track.  Lets say that you have an array of 100 
numbers and you want to track the value of each.  It wouldnt 
take you long to get tired of clicking on the NOTICE OK button!  
Here is a way to write the values into the main window, so that 
you can check them out at your leisure!

dim array1(100)

for i = 100 to 0 step -1
    array1(j)=i
    j=j+1

    print "index "+str$(j)+" value "+str$(i)
next i

The printout in the mainwindow would be:

index 1 value 100
index 2 value 99
index 3 value 98
index 4 value 97
index 5 value 96
index 6 value 95
index 7 value 94
index 8 value 93
index 9 value 92
index 10 value 91
etc.......

If you choose this method, be sure to include text that tells 
you what you are tracking!  It might be confusing to look at the 
printout, if it were, instead:

print j;i

This would give a printout like the following:

1100
299
398
497
596
695
794
893
992
1091
etc...



DEBUGGING WITH THE LIBERTY BASIC DEBUGGER

The debugging window is called the TRACE WINDOW.  Open one of the
sample programs that comes packed with Liberty BASIC, then choose
DEBUG from the RUN menu.  This will activate the Trace Window. 
Look first at the top texteditor displayed in the Trace  Window.  
The first thing you see is something like the following:

WindowWidth=150

The top section records the values of all variables as they are 
used in the code.  The first variable used in many programs
is WindowWidth.

Look at the middle section of the Trace Window, which contains 
a larger texteditor.  That part holds the code that is currently 
being executed by the program.  The current line is highlighted 
in black, so you can see which part of the source code is being
executed.

At the bottom of the window, there are three buttons and a checkbox.  
The checkbox says ON TOP.  If it is checked, the Trace Window will 
remain on top of any other windows while the debugging process is 
running.  This is a really handy feature to use.


THREE SPEEDS:  Run, Walk, Step
The three buttons represent the speed at which you will run the 
program for debug.  The button marked RUN will cause the program 
to run as normal, and no variables will be logged, no code 
highlighted.  Hey!  Thats no help!  -  or is it?  Well discuss 
this option a little later when we talk about the TRACE command.

The WALK button will scroll though the code, highlighting the 
line that is being executed and logging the variables.  The program 
will stop when it needs input from the user, so you must interact 
with the program to see the results of button pushes, etc.  This 
is the method to use if you need to check the values of a lot of 
variables.  You can scroll through the logged variables in the top 
texteditor of the Trace Window.  That area is small, so you might 
want to select the entire contents of that texteditor and copy and 
paste into Notepad for ease of reading.

The STEP button allows the program to execute ONE LINE AT A TIME!  
You must click the button to advance to the next line each time.  
This gives you absolute control over debugging.  Each line is 
highlighted as it is being executed and you can check the value 
of each variable as it is used.  You will know exactly which line 
of code generates an error and you will know which sections of code 
are implemented and which are skipped.  This procedure tells you 
everything but WHY!  But with all of this help, the problem should 
be easier to figure out.

WARNING
If you are filling an array of 100 items, or doing a FOR/NEXT loop 
of 1000, you will NOT want to click that STEP button each time!  
Too bad there isnt a way to run quickly through the parts of the 
code that we know are fine, and stop for a line-by-line walk-through 
of the tricky parts.  THERE IS!  This is where the RUN button and 
the TRACE command take center stage.


USING THE TRACE COMMAND

WARNING!!!!!  The helpfile has contained an error, so be sure to 
use these values for n in the TRACE command!!!!

TRACE n
Place the TRACE command into your code at the spot that is likely
to be causing problems.  When you RUN this code for DEBUG by
clicking the RUN button at the bottom of the Trace Window, the
program will execute normally until it reaches the TRACE
command, at which time it will change the type of execution to
the type secified by n in TRACE n.

Values  for n can be any of the following:

  2 = single step mode - or STEP
  1 = animated trace - or WALK
  0 = full speed no trace - or RUN


Usage:

  'Here is the trouble spot
  trace 2  ' kick down to single step mode
  for index = 1 to int(100*sin(index))
    print #graph, "go "; index ; " "; int(100*cos(index))
  next index

You can click the WALK or RUN button again to recover from the 
single-step trace mode when you have discovered your error.

Problems?
It sometimes happens that a program halts or crashes when run 
from the Liberty BASIC editor, but runs fine using the debugger.  
It can also happen that a program runs fine when run as a BAS file 
from the Liberty BASIC editor, but halts or crashes when tokenized.  
When these kinds of problems happen, it is most likely due to 
sloppy coding technics, such as nested loops with too many levels 
of recursion, or spagetti code.  Spaghetti code has many jumps 
using the GOTO command and can be quite confusing to read and 
understand.  Watch for an article on the Theory of Debugging, 
which deals with these and other issues in more detail.
---------------------------------------------------------
 Newsletter compiled and edited by: Brosco and Alyce.
 Comments, requests or corrections: Hit 'REPLY' now!
---------------------------------------------------------