OVERVIEW.............The dCLIP debugging system
DOT-PROMPT...........The Interactive dot-prompt as a debugger
ALT-D KEY............Using the ALT-D key to invoke the Interactive Debugger
CLD DEBUGGER.........Using dCLIP with the CLD Debugger
SOURCE-DEBUGGING.....The Source-Level debugging system
TRACE-DEBUGGING......Tracing or Profiling application code
SOURCE-WINDOW........The source-code window and menu options
STACK................Display the call stack
WATCH-WINDOW.........The Watch Window

OVERVIEW

The dCLIP debugging system

Description:

Both an INTERACTIVE debugging and SOURCE-LEVEL debugging
system is included in the dCLIP engine and in the dCLIP
libraries. This debugging system is unlike the Clipper
debugger in that it combines the ability to provide an
integration of "menu-driven" and "interactive" debugging
features. The Clipper debugger is not included as a
"standard" portion of the dCLIP engine because of its large
size however dCLIP is fully compatible with the Clipper
debugger and both debug systems can be on-line at the same
time. The dCLIP debugger program is more memory-efficient
than the Clipper debugger because it was designed to be
almost entirely "overlayable". The large footprint of
CLD.EXE (approximately 60k) makes debugging very large
applications quite difficult, whereas the dCLIP dot-prompt
can be added with as little as 5k memory overhead.

dCLIP's source-level debugging is also different than
that provided by CLD.EXE. It's overhead is so small that
it can actually be included in an end application and
controlled by calling functions from the dCLIP library.

DOT-PROMPT

The Interactive dot-prompt as a debugger

Description:

The "Dot-Prompt" of the interactive debugger is really a
"Double-Dot" or "Colon" prompt that prompts the user to
enter a command.

When you enter COMMANDS from the dot prompt they are passed
through the interactive pre-processor and converted to
expressions that are evaluated with the Clipper runtime
macro-compiler. All Clipper and third-party functions that are
linked into the engine will be "resident" in memory so they
will be executed when they are macro-compiled. The dCLIP dot
prompt is fully-interactive, meaning that you get an instant
response to the command at the moment you enter it from the
keyboard.

Any function that is not in the engine or has not been loaded
into memory (dynamically-linked) will generate an "undefined
function" error if it is called from dCLIP.

The Interactive dot-prompt is the starting place for just
about everything you need to do when debugging in dCLIP.
You can run any other executable program (regardless of size),
run any DOS command, run any Clipper or dCLIP command, run
any Clipper function or UDF, execute any batch file, edit
source files, even compile and run object code without ever
leaving the interactive environment of the dot prompt and
while the application program is suspended.

The dot-prompt is called by pressing the ALT-D key while
running an application that was compiled with debugging
information, or by calling the DC_DEBUG(.T.) function.

A 3-line status line will appear at the top of the display
with the following information:

Work Area | Database file | Database Filter |DEL|REL| Record No.
Alias | Index file | Index Key |EXC|UNI| Index No.
Rdd used | Current Tag | Index Filter |REA|DES|

To return back to the calling program, simply press (ENTER)
at the dot (colon) prompt when the command line is empty
or press (ESCAPE).

ALT-D KEY

Using the ALT-D key to invoke the Interactive Debugger

Description:

The Interactive Debugger (Double-Dot-Prompt) is activated at
any time while running an application program under the
dCLIP Engine by pressing the ALT and (D) keys simultaneously.
A COLON (:) prompt will appear at the bottom line of the
display to allow you to enter commands. All Clipper commands
and expressions can be used at the dot-prompt and any other
commands that have been pre-loaded with the INCLUDE command,
or DC_PREINCLUDE() function.

Your program will suspend execution immediately when the
ALT and (D) keys are pressed and you will find yourself at
the double-dot prompt.

Your runtime environment will remain intact so you may
examine your memory variables, databases, relations,
filters, set environment, etc. You are even allowed to
make modifications to PRIVATE and PUBLIC memory variables and
arrays, or data files to aid in debugging your application
program. You may close or open new data files, edit program
files, re-compile and reload new objects or even call the
DOS shell from the colon prompt.

You must use caution, of course, when making major changes
to your runtime conditions during a debugging session, as
you are likely to create error conditions when continuing
the execution of your program.

NOTE: The ALT-D key will function while in any wait state,
INKEY() state, or while executing code that has been
compiled with debugging information. The ALT-D key
is NOT active during execution of code that is not
Clipper-compiled, i.e. functions written in C/ASM.

When running dCLIP from CLD.EXE, pressing the ALT-D
key will invoke the Clipper debugger screen instead
of the colon prompt. To call the colon-prompt, use
the command ? DC_DEBUG() at the CLD prompt or the
command INPUT DOT to run the DOT.CLD program.

CLD DEBUGGER

Using dCLIP with the CLD Debugger

Description:

dCLIP is a Clipper application, therefore it can be used
with the CLD.EXE or CLD.LIB Clipper debugger for debugging
programs that are linked into the dCLIP.EXE engine or that
have been loaded into memory with the OBJ command, the
DC_OBJLOAD() function, or the / turbo-editor. You must
make sure that any .OBJ files loaded into memory have been
compiled WITH the /b (debug) option and WITHOUT the /l
(no line numbers) option for the debugger to work properly.

The CLD debug window will automatically be displayed as
soon as you DO a procedure or execute a function that has
been compiled with the /b switch or when you run a program
created by the turbo-editor.

To use the Clipper debugger with dCLIP, simply run the
CLD.EXE program as you would debug any other Clipper
program:

CLD [/S] [/50] DCLIP

If you have a VGA monitor it is recommended that you use
the /S option for SPLIT-SCREEN debugging.

The Clipper debugger (CLD.EXE) cam be used with dCLIP as
it would be used with any Clipper application, with the
exception that dCLIP's .DOT-PROMPT or :COLON-PROMPT
command set can now be used as an extension to the CLD
debugger command set by entering any of the following
commands at the CLD command line:

? DC_DOT() or INPUT DOT // Call dot-prompt
? DC_QDOT() or INPUT QDOT // Call Quick-Dot
? DC_DEBUG(.t.) or INPUT DEBUG // Call Colon-prompt

? DC_DOT() or INPUT DOT will call dCLIP's main dot prompt
and allow you to use any Clipper command or expression or
INCLUDEd command or manifest constant. INPUT DOT simply
calls a file named DOT.CLD which contains one command:
? DC_DOT(). To return back to the CLD debug screen type
RETURN or EXIT.

? DC_DEBUG(.T.) or INPUT DEBUG will call dCLIP's debugger
colon-prompt and allow you to use any Clipper command or
expression or INCLUDEd command or manifest constant.
INPUT DEBUG simply calls a file named DEBUG.CLD which
contains one command: ? DC_DEBUG(.T.). To return back to
the CLD debug screen simply press the (ENTER) key with an
empty command line or the (ESCAPE) key.

? DC_QDOT() or INPUT QDOT will call dCLIP's QUICK-DOT
function and allow you to use any Clipper command or
expression or INCLUDEd command or manifest constant.
INPUT QDOT simply calls a file named QDOT.CLD which
contains one command: ? DC_QDOT(). The difference between
DC_QDOT() and DC_DEBUG(.t.) is that DC_QDOT() does not
allow the values of LOCAL and STATIC memvars to be
displayed and DC_DEBUG(.t.) displays the dot-prompt in
RED (default) color rather than the BLUE (default) color
of DC_QDOT(). To return back to the CLD debug screen
simply press the (ENTER) key with an empty command line
or the (ESCAPE) key.

SOURCE-DEBUGGING

The Source-Level debugging system

Description:

A source-level debugger may be invoked at any time by using
the command SET STEP ON from the main dot prompt or the
debugger double-dot prompt or by pressing the (ALT) and (S)
key. Source-level debugging provides the ability to
single-step or animate a Clipper application while high-
lighting the current line of code in your actual source
code .PRG file.

There are several modes of operation for invoking the
SOURCE CODE WINDOW or "STEP" mode. STEP commands may be
entered from the main .dot prompt or the debug :dot prompt.

1. You can start the STEP mode when ANY expression
evaluates .TRUE. by entering the commands:

STEP OR
STEP (expression 1)
STEP (expression 2)
| | |
STEP (expression 9) // maximum of 9 allowed

2. You can start the STEP mode when ALL expressions
evaluate .TRUE. by entering the commands:

STEP AND
STEP (expression 1)
STEP (expression 2)
| | |
STEP (expression 9) // maximum of 9 allowed

3. You can start the STEP mode as soon as a
specified procedure is executed by entering the
command:

STEP PROC (procedure name)

4. You can start the STEP mode as soon as a
specified line number of a specified procedure is
executed by entering the command:

STEP PROC (procedure name) (line number)

5. You can start the STEP mode as soon as you
run or return to your application by using the
following command:

SET STEP ON

6. You can start the STEP mode by pressing the ALT-S
key at any time while running your application.

CAUTION: The ALT-S key will function only if your
application is currently in a WAIT state.

To insure that the STEP mode is enabled in
any state of operation, such as an INKEY(0),
it is best to press the ALT-D first then the
ALT-S key.

The source-level debugger HOT-KEY can be
refined by using the SET STEPKEY command.

7. You can BYPASS the source-level debugging of all
procedures EXCEPT specified procedure by using the
command:

STEP ONLY (procedure)

The source code window includes the name of the procedure
or function, the name of the source code .PRG program and
the line number of the code when program execution is
suspended. The current line of code will be highlighted
in the window. Use the UP/DOWN arrow keys or PGUP/PGDN
key to view the code before and after the current line.

NOTE: You must insure that your code is compiled WITH the
/b option and WITHOUT the /l option if you wish to
properly step through your code, otherwise the
function will be ignored completely by the source-
level debugger.

HINT: When you are debugging an application, it is best
to compile with line numbers only the modules which
need debugging. Modules which have already been
debugged should be compiled without line numbers to
reduce the object size for better memory management
and to prevent unnecessarily "stepping" through
these modules when they are call be modules you
are debugging.

You may still skip by procedures which have been
compiled with line numbers however, by including
the name(s) of the procedure(s) to skip in the
PROCedure table. See the PROCedure command for
more information about this feature.

TRACE-DEBUGGING

Tracing or Profiling application code

Description:

A background TRACE mode may be invoked at any time by
using the command TRACE ON from the main dot prompt or
the interactive debugger colon-prompt. TRACE debugging
provides the ability to output information to a file
during the running of an application.

TRACE mode will write the PROCEDURE name, LINE number, and
WATCH values into a file named DCTRACE for each line of
application code that executes. Only code which has been
compiled with debugging information (/b switch) will be
traced and only code which is actually "executed" during
the running of the program will be traced.

The information in the DCTRACE file will be stored as
follows:

Date: 11/01/89
Time: 12:15:33

Watch 1 = Lastkey()
Watch 2 = row
Watch 3 = col
Watch 4 = ALIAS()

Proc Line W1 W2 W3 W4

TTRAK 27 54 0 0 ""
TTRAK 28 54 0 0 ""
TTDAILY 1 44 0 0 ""
TTDAILY 2 44 1 0 ""
TTDAILY 3 44 1 1 "SALES"
TTDAILY 11 44 1 1 "SALES"

There are several modes of operation for invoking the
"TRACE" mode. TRACE commands may be entered from the main
.dot prompt or the debug :dot prompt.

1. You can start the TRACE mode when ANY expression
evaluates .TRUE. by entering the commands:

TRACE ON (expression)

2. You can start the TRACE mode as soon as a
specified procedure is executed by entering the
command:

TRACE ON PROCEDURE (procedure name)

3. You can start the TRACE mode as soon as a specified
line number of a specified procedure is executed by
entering the command:

TRACE ON PROCEDURE (procedure name) (line number)

4. You can start the TRACE mode as soon as you run or
return to your application by using the following
command:

TRACE ON

5. You can stop the TRACE mode when ANY expression
evaluates .TRUE. as by entering the commands:

TRACE OFF (expression)

6. You can stop the TRACE mode as soon as a specified
procedure is executed by entering the command:

TRACE OFF PROCEDURE (procedure name)

7. You can stop the TRACE mode as soon as a specified
line number of a specified procedure is executed by
entering the command:

TRACE OFF PROCEDURE (procedure name) (line number)

8. You can stop the TRACE mode as soon as you run or
return to your application by using the following
command:

TRACE OFF

9. You can skip the tracing of all procedures EXCEPT
specified procedure by using the command:

TRACE ONLY (procedure)

10. You can CONVERT the information in your DCTRACE file
to a new file which is a merging of the DCTRACE
information and your actual source code .PRG files by
using the following command:

TRACE CONVERT

NOTE: You must insure that your code is compiled WITHOUT
the /l option and WITH the /b option if you wish to
properly trace through your code. All other code
will be ignored completely.

HINT: When you are TRACE-debugging an application, it is
best to compile with the /b switch only the modules
that need debugging. Modules which have already been
debugged should be compiled without the /b switch to
reduce the object size for better memory management
and to prevent unnecessarily "tracing" through
these modules when they are call by modules you
are debugging.

You may still skip by procedures which have been
compiled with line numbers however, by including
the name(s) of the procedure(s) to skip in the
PROCedure table. See the PROCedure command for
more information about this feature.

CONVERTING YOUR DCTRACE FILE

Converting your DCTRACE file is a process which merges
the information that is stored in the DCTRACE file
with your actual source code in your .PRG files.

1. This is a sample input file (DCTRACE) :

Date: 11/01/89
Time: 12:15:33

Watch 1 = Lastkey()
Watch 2 = row
Watch 3 = col

Proc Line W1 W2 W3

TTRAK 27 54 0 0
TTRAK 28 54 0 0
TTDAILY 1 44 0 0
TTDAILY 2 44 3 0
TTDAILY 3 44 3 10
TTDAILY 11 44 3 10

2. This is a sample output file (file name) :

Watch 1 = Lastkey()
Watch 2 = row
Watch 3 = col

Proc: TTRAK Source: TTRAK.PRG W1 W2 W3

27 IF LASTKEY()=44 44 0 0
28 DO ttdaily 44 0 0

Proc: TTDAILY Source: TTDAILY.PRG W1 W2 W3

1 CLEAR 44 0 0
2 STORE 3 TO row 44 3 0
3 STORE 10 TO col 44 3 10
11 STORE 1 TO page 44 3 10

To convert your DCTRACE file to a new file use the command:

TRACE CONVERT [(file name)]

If you do not include a file name, then the output file
will be named DCTRACE.TXT.

NOTES:

TRACE CONVERT requires that your source code exist in
the current directory, the DOS APPEND path, or the
directory identified with the PDIR=(directory) command
in your DCLIP.SYS file.

For TRACE CONVERT to find your source code files you
may need to load a .LST map file or .DLB dynamic library.

SOURCE-WINDOW

The source-code window and menu options

Description:

SOURCE-LEVEL WINDOW commands

Each source-level window command is invoked with a
single keystroke to provide a CODE-VIEW style debug
enviroment.

(ENTER)/(SPACE) - Press the ENTER or SPACE BAR key to
step to the next line of code in your
application.

(G) GO - STOP at the next line of code which
evaluates .TRUE. for the STEP points
set. If NO STEP points are set, then
stop at the next line of code.

(R) RUN - The (R) key toggles between step rate .1
and step rate 0. Press key (R) once and
the program continues running while
displaying source code. Press key (R)
again and the program stops.

(X) EXECUTE - STOP at the next line of code which
evaluates .TRUE. for the STEP points
set only in the current procedure.
Use the (X) key to skip stepping on
any procedures or functions called by
the current procedure.

(J) JUMP - JUMP forward to a selected line of code
in your application. When your source
code is being displayed in the window,
use the up/down arrow keys or pgup/pgdn
keys to highlight the desired line of code.
The STEP mode of operation will be
suspended until the highlighted line of
code is executed.

CAUTION - JUMP will not work properly if
you move the highlight bar to a line of
code in a different procedure within the
same source module.

(P) PASS - PASS BY this procedure. The (P) key will
insert the name of the currently running
procedure into the PROCedure table. All
procedures which are in the PROC table are
skipped during source-level debugging.
See the PROC command for more information.

(T) TOGGLE - TOGGLE the display mode between normal
screen and split-screen mode. On a VGA/EGA
monitor, split-screen mode will use the top
25 lines of the screen for the application
and the bottom portion of the screen for the
source code.

(W) WATCH - Toggle the size of the WATCH window. This
is used to provide a wider watch window in
the event that a watch expression overflows
the width of the window. When the long
watch window is selected, the source code
window will display less lines of your
source code.

(H) HELP - Display a HELP screen.

(S) SCREEN - Turn off the SOURCE-CODE window and the
WATCH window so the operator can see the
entire application screen. Press any key
to reactivate the windows.

(F) FILE - Browse a different source file than the
currently executing procedure. You may
enter the name of any TEXT file and
scroll through it as a reference while
you are debugging.

(D) dBUGGER - Call the INTERACTIVE dBUGGER. You may
use all debug commands. Use the
dBUGGER to set or clear additional
STEP points or WATCH points.

(E) EDIT - EDIT the source .PRG file which
includes the current procedure or
function. This command will call your
editor with the name of the .PRG file
and the line number to place you at
the current line of code. You must
use the EDITOR=(program) command in
your DCLIP.SYS file for this feature
to be functional. See CONFIGURATION.

(C) COMPILE - COMPILE the source .PRG file which
includes the current procedure or
function. This command will call the
CLIPPER.EXE compiler and compile the
.PRG file with the -m option. You
must insure that CLIPPER.EXE can be
found in your DOS path.

(B) BREAK - BREAK to the next END SEQUENCE in
your application program. If there
are no BEGIN SEQUENCE/END SEQUENCE
commands in your application, then
this will operate the same as the
MAIN command.

(M) MAIN - This command will generate a series
of interrupt-driven BREAK commands
to return you to the main DOT prompt
when running DCLIP.EXE or to restart
your application program when running
DCLIPRUN.EXE. MAIN will also close
all files.

(ESC) ESCape - ESCAPE functions the same as SET STEP
OFF to allow continuous execution of
your program. STEP points and WATCH
points will remain in the STEP/WATCH
tables. To enter STEP mode again you
must use the SET STEP ON command from
the main dot prompt or press ALT-D and
ALT-S.

NOTES:

1. When running applications which include user-defined
functions or imbedded-procedures, you must use either
a dynamic library (.DLB) file or a map (.LST) file so
dCLIP can find the .OBJ and/or .PRG files which
contain the functions or procedures. See the chapter
titled DYNAMIC LINKING and also the following commands
in the chapter titled DOT PROMPT COMMANDS:

LIB (library file name)
MAP (map file name)

If your application "STEPS" into a procedure or UDF
that has not been properly mapped, an empty source
code window will be displayed with the following
error message:

Can't find SOURCE module for: (procedure)
Be sure to add (procedure) to a MAP file

2. Make sure that the object code you are running
"matches" the original source code module of the
same name or the source-level debugger will display
erroneous information. To insure that your object
modules and source modules always match make sure
that you compile your objects with the -m option
so no other source modules are compiled into the
object file. Object files which are compiled from
multiple source files will show the wrong
information in the source-code display or will
display the following error message:

Can't find Line Number in source code. Press any key..

3. Make sure that your source code exists in one of
the following locations while running your
application:

a. The currently selected DOS directory.

b. Any directory appended by the DOS APPEND command.

c. The directory established as the source directory
by the PDIR=(drive)/(directory) command in your
DCLIP.SYS file.

If dCLIP cannot find a source-code module the
following error message will be displayed:

Can't find SOURCE module for: (procedure)
Put PDIR=(drive)/(directory) in DCLIP.SYS

STACK

Display the call stack

Description:

STACK is used to display the command call-stack information
when debugging programs. Pressing the ALT-D key will interrupt
the program and invoke a Dot-Prompt. STACK will display the
call stack information.

Examples:

   . STACK
   

   
Called from DC_QDOT(0)
   
Called from NEXTKEY(0)
   
Called from DC_INKEY(0)
   
Called from DC_EDITDB(0)
   
Called from _DCBROW2_E(0)
   
Called from DC_BRWOSED(0)
   
Called from DCLIP(0)

WATCH-WINDOW

The Watch Window

Description:

You may set up to 9 WATCH points which will be displayed
whever the source-level debugger stops program
execution. WATCH points may be any memory variable,
database variable, array element or any valid
expression. If the WATCH value set is invalid, then the
WATCH window will display the value as UNUSED.

The "watch window" is an area of the screen that displays
the value of expressions. Watch expressions are invoked
by using the WATCH (expression) command at the dot-prompt
or by using the DC_WATCH((expression)) function in your
application code. The watch window is displayed at the
top of the screen and all expressions added to the watch
table will be evaluated after each command entered at the
dot prompt or each line of code invoked while source-
level debugging.

For more information about WATCH points see the following
commands and functions:

WATCH (expression)
WATCH CLEAR [(number)] | ALL
DC_WATCH()

Watch expressions are also evaluated and written to a
file named DCTRACE when TRACE DEBUGGING.

OVERVIEW

The dCLIP debugging system

Description:

DOT-PROMPT

The Interactive dot-prompt as a debugger

Description:

See Also:

ALT-D KEY

Using the ALT-D key to invoke the Interactive Debugger

Description:

See Also:

CLD DEBUGGER

Using dCLIP with the CLD Debugger

Description:

SOURCE-DEBUGGING

The Source-Level debugging system

Description:

See Also:

TRACE-DEBUGGING

Tracing or Profiling application code

Description:

See Also:

SOURCE-WINDOW

The source-code window and menu options

Description:

See Also:

STACK

Display the call stack

Description:

Examples:

WATCH-WINDOW

The Watch Window

Description:

See Also: