PROGRAM ERRORS & DEBUGGING.
                        ßßßßßßßßßßßßßßßßßßßßßßßßßßß

Programming errors inevitably occur and it is fortunate that a debugger
is built into the Turbo Pascal Integrated Development Environment (IDE).

There are three basic types of program bugs:

 1.   Syntax errors, which are found at compile time, such as the
      omission of an end-of-statement semi-colon or assigning a real
      value to an integer variable.

 2.   Semantic errors are found at run-time, and include dividing by
      zero or opening a non-existant file for input.

 3.   Logical errors, which are difficult to find. Perhaps a variable
      has not been initialized and hence assumes an unexpected value,
      or the algorithm for the solution of the problem is incorrectly
      chosen.


1. Syntax errors.
ÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍ
Pascal has strict rules, compared with many other programming languages
and Turbo Pascal will not compile the program until all the syntax errors
are removed. Instead it stops compiling, searches the source code and
finds the error, positions the cursor there and displays an error message
in the EDIT window. When corrected, compiling can be restarted and the
next error found, until all errors are removed and compilation is completed.
If the command-line version (TPC.EXE) of Turbo Pascal is used instead of
the IDE version (TURBO.EXE), then the offending line is printed with a line
number and error message so that any alternative editor can be used to
correct the program.

2. Semantic errors.
ÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍ
When a compiled program is run under the IDE, any errors which then occur
are automatically located by referring to the source file and an appropriate
error message is displayed at the top of the Edit window, for example:

	Error 200: Division by zero.

and the program halts, with the cursor at the offending line.
Further details of each numerical error message (###) can be found in the
list of error codes and messages in Appendix A of the Programmer's Guide.

If the command-line compiler is used to create an executable file, with the
extension name .EXE and the program is run by typing the filename,
then the message   'Run-time error ### at seg:ofs'  is displayed. The
address should be noted and then the command-line compiler re-used with the
/F option and the address after the filename, for example:
         C:\>TPC TEST /F0000:001C
This then recompiles and finds the offending line in the source code.
See pages 232-3 of the User's Guide for details.


3. Logical errors.
ÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍ
These are the most difficult to find, and would normally require a manual
calculation through the algorithm or the insertion of additional lines in
the program (temporarily) to show values as the program is executed.
Fortunately the Turbo Pascal integrated debugger is included in the IDE,
with two main menus (Run and Debug) with suitable hot keys for some of the
options.
Pages 189-192 of the User's Guide give details of the Run menu's commands,
whilst pages 194-8 give details of the Debug menu's commands.

Debug Options.
ÍÍÍÍÍÍÍÍÍÍÍÍÍÍ
The debugger of the Integrated Development Environment (IDE) has the
following options:

1. Tracing through the program as it is executed, one line at a time, is
   achieved by selecting the Run Menu (Alt-R) and then T for Trace into
                        ÜÜÜÜÜÜ
   or using the hot key Ý F7 Þ
                        ßßßßßß
   By entering variable names in the Watch Window, the user can see how any
   selected variables change as the program is executed and thus quickly
   indicate any logical errors.
   Variable names are entered in the Watch Window by the key-presses:
   Alt-D for Debug Menu, W for Watches and then A for Add watch or by the
                       ÜÜÜÜÜÜÜÜÜÜÜÜ
   hot key combination Ý CTRL-F7) Þ
                       ßßßßßßßßßßßß
   After these alternative key-presses, a dialog box appears on the screen,
   with a default entry taken as the word currently indicated by the cursor.
   This can be accepted directly or overwritten as desired.

   Borland suggest that 'Tracing' is a good way to learn about programming.

2. The option 'Go to Cursor' (Alt-R for Run Menu and then G) causes the
   program to run up to a preselected line in the program where the cursor
   has been located.
                                  ÜÜÜÜÜÜ
   The hot key for this option is Ý F4 Þ
                                  ßßßßßß

3. Lines in the program can be set as 'breakpoints' so that the program
   will stop at each breakpoint, displaying the source code and allowing
   examination of the variables selected in the Watch Window.
   A breakpoint is set or cleared by moving the cursor to the required
   line and then selecting the Debug Menu (Alt-D) followed by T to toggle
   the breakpoint on or off.
                                                     ÜÜÜÜÜÜÜÜÜÜÜ
   The hot key combination for toggle breakpoints is Ý Ctrl-F8 Þ
                                                     ßßßßßßßßßßß

There are other features of the debugger as listed in the Chapter 5 of the
User's Guide (version 6.0), but for most initial usage the above options
should be sufficient.

Selection of the Integrated Debugger.
ÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍ
In order to use the debugger it is necessary to instruct the compiler to
generate the necessary symbol table and line number information for that
program. The symbol table is a database of all the identifiers used.
This requires the use of the compiler directives {$D+} and {$L+}.

{$D+} generates the general debug information for global identifiers.
This can also be preset by selecting Options/Compiler/Debugging from the
IDE and then toggling the Debug information box by pressing the spacebar.

{$L+} generates local debug information. (i.e. it creates a list of the
identifiers local to each procedure or function). This can also be preset
by the Options/Compiler/Debugging/Local Symbols selection in the IDE.

These compiler directives must also be declared in any Unit used by the
program.

It is also necessary to ensure that the IDE's debugging switch is on
(Options/Debugger/Debugging/Integrated).

It should be noted that the Trace execution is for a single line, which
might include more than one statement. However, if a single statement is
spread over more than one line then the complete statement is executed.

Finally it should be noted that the debug procedure does not increase the
size of the .EXE file and there is no need to recompile once debugging is
finished.


DEBUG.TXT
Revised 18.1.93