Common Mistakes
Updated: Apr 9, 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 floatnum = integernum 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 floatnum = 10.0 THEN

  IF integernum = 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.  However, this is
unlikely since HotBasic has a list of over 500 reserved symbols and will
rename yours if there is overlap.  However, maybe we missed some!

In general, this occurs when

(1) you have "discovered" a symbol used in your code which is a ml.exe
reserved keyword (and therefore confuses it).

Solution: find the symbol and rename it and report it so I can add it
to the Rename List in the compiler.

(2) some other error in source code that the compiler failed to detect
and report *before* attempting to run ml.exe.

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

Summary, errlevel 3 should never 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. 

Some compilers use #IFDEF instead of $IFDEF, so a future release will
accept "#" as an alias for "$" in compiler directives.


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 some 9500 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
