Common Mistakes
Updated: Sep 24, 2005


Yuk!  My Program Won't Compile
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
When your program will not compile, obviously the compiler sucks.  Or, if you
are like me, you want it to guess what you mean and not only that, it better
guess right.

Seriously, let's talk about debugging -- more than just reading the help files
-- and highlight some factors that may cause suffering and travail.


HotBasic is case-sensitive by default for user symbols
======================================================
  ThisLineLabel:
  'is not equal to
  THISLINELABEL:
  'and is not equal to
  Thislinelabel:

The same is true for dimensioned variables.  If you want to avoid editing your
source code (as you know you should), try $UPPERCASE ON -- that is, if you are
not doing API calls.


Suck it in and have $TYPECHECK ON or use the -t switch
======================================================
Do not rely on automatic variable typing, which applies only to destination
variables, anyway.  Also, the old method of using suffixes to indicate variable
type, which have to be typed throughout your source code, is tiring,
troublesome and error-prone.

HotBasic provides for specific dimension by type throughout to *save your time*
because mistakes are avoided.  HotBasic is oriented toward getting the job done
as fast as possible.

Automatic dimensioning with $TYPECHECK OFF is only for beginners -- and I mean,
just day one or day two for 
  
  x=1: PRINT x 'and gee, whiz, it prints "1"

Once you have seen that works, forget it and dimension all variables.


Common mistake: write a function as a subroutine or visa versa
==============================================================

  sqlret = sql.Close 'causes ERROR; sql.Close is not a function

  sql.Finalize  'causes ERROR; sql.Finalize is not a subroutine

Note: my hotsql.bas test program did not work and it took me about an hour to
realize that my own creation -- sql.Finalize -- was not a subroutine as I first
wrote the source code.  So "strange" ERROR messages often are due to the above
kind of mixup.  And I wrote the manual!


Common mistake: mixing numeric types in IF THEN statements
==========================================================
Evaluation of boolean expressions with mixed numeric types will compile but
expected results may not be obtained.  Therefore, avoid mixing floating and
non-floating values, such as
 
  IF float_num = integer_num THEN

Also, avoid mixing floating numbers of different precision, such as

  IF MySingle = MyDouble THEN

You might assign the same value to both but the representation of the numbers
may be different in mixed precision boolean expressions and evaluate as *not*
equal (please see hottypes.bas).

For immediate values, you can force float or integer by using a decimal point:

  IF float_num = 10.0 THEN

  IF integer_num = 10 THEN


ERROR producing object module
=============================
Holy smoke!  What could this be?  Often one of your symbols is the same as an
internal symbol used in HotBasic compilation and each symbol must be unique.
If not, ERROR producing object module.  HotBasic reserves symbols with
lower-case prefix "hb" -- e.g., "hb0".  Thus, it is a good idea to avoid
dimension using such symbols or other HotBasic internal variables, such as
"hWnd", "uMsg", "wParam", etc.  There would be no conflict if you dimension
"hW", "uM" and "wP" for similar items.

Solution: Send shortest possible source code proof-of-concept so a new error
message can be added to the compiler.

Summary:  Generally, Errlevel 3 should not occur.  Always the solution is to
improve the compiler as described above.  So please report.


Every RapidQ, QuickBasic or Visual Basic program will not compile
=================================================================
Why should they?  Other compilers will not compile every HotBasic program
either.  And there is nothing wrong with any of the compilers.

It is a valid desire to work with two different compilers.  Try this:

(1) At command-line or in your hb.bat file, use the $DEFINE switch

  hot MyProg -DHOT 

(2) In source code,

  $IFDEF HOT
  {statements that only work in HotBasic}
  $ELSE
  {statements that only work in another compiler}
  $ENDIF
  '
  {statements that work in both compilers}
  '
  $IFNDEF HOT
  {statements that only work in another compiler}
  $ENDIF
  '
  {statements that work in both compilers}
  '
  $IFDEF HOT
  {statements that only work in HotBasic}
  $ENDIF

Then, one set of source code files will compile and run under two different
compilers.  Example,

  $IFDEF HOT
  IF x <> 0 THEN y = sum/x ELSE y=0
  $ELSE
  ON ERROR RESUME NEXT
  y = sum/x
  $END IF

This shows why HotBasic does not bother with ON ERROR ...  What error?  For
example, HotBasic does not slow your programs down with a "math nanny" to stop
your work if divide by zero or numeric overflow or whatever.  It is assumed
that you will not allow those errors to occur in your tasks, or at least, you
do not want the whole job stopped if one does occur.

Imagine you are calculating thousands of values over many hours and the
HotBasic executable says, "We did it all, but sorry, in one case a number was
out of range."  Now imagine you find a VB "math nanny" message like "overflow"
and possibly loose all of your work.  

In modern programs, one tries to avoid errors BEFORE they occur, so there are
no errors to trap.  Another example,

  file$ = "MyFile.dat"
  $IFDEF HOT
  DIM F As FILE
  IF FILEEXITS(file$) THEN F.Open(file$,2) ELSE F.Open(file$,65535)
  $ELSE
  ON ERROR RESUME NEXT
  {your file open syntax in another language which may be error-prone)
  $END IF

NEW! The App.OnFPUerror event allows you to trap 7-bits worth of FPU exceptions
and you can turn it on and off, also.  .OnFPUerror applies to all math
operators (e.g., * / - + etc) and math functions performed by the FPU, such as
SIN, SQR, LOG, etc.  Also, FPU.error can be tested at any time.  Please see
hotapp in the help files and OnFPUerr.bas for details.

Use App.OnExit = ExitProcedure (see Application Object) to trap certain fatal
errors.  But really, HotBasic programs should run 24 hours a day for as long as
your computer is turned on if they are written properly.  There is no need at
all for ON ERROR. 


PRINT, BEEP, FPU.error, GETLASTERROR, FILEEXISTS and PAUSE
==========================================================
All of the above and more can be used to avoid errors or trouble-shoot.  E.g.,
PRINT of keyvalues with PAUSE may let you step through a procedure to see
exactly what is happening.


Can I trust the results of HotBasic-compiled executables?
========================================================
In short, one does not trust the results of a program compiled with any
compiler.  Users of your program may not even know what a compiler is.  They do
know and will say, "You goofed".  Thus, your professional reputation is on the
line, not the reputation of any particular compiler.  So results should always
be checked for accuracy.  If inaccurate results are due to a defect in the
compiler, please let us know.  That is a bug that should be fixed.  If
inaccurate results are due to your source code or failure to check for errors,
then you can address that issue.

hot.exe is compiled by a previous version of itself and correctly creates a
new hot.exe based on over 10,000 statements (at this point) using a quite ample
spectrum of HotBasic statement types.  If hot.exe can do that, it can do a lot
in a completely reliable manner.


xyz compiler is better than HotBasic
====================================
This is fine if the reason is that you are accustomed to xyz compiler or it has
features you need.  However, if it is better in your view for some other
reason, please let us know why.  After all, how could it be better?  [smile]
Let us know. Thanks!


Copyright 2003-2005 James J Keene PhD
Original Publication: Nov 1, 2003