Hard mode help
--------------
12345678901234567890123456789012345678901234567890

{100}  The windows help system can
  not be activated  when the
  debugger  has  suspended  a
  program in  hard mode.

{101}  The windows help system can
  not be  activated  when the
  debugger  has  suspended  a
  program in  hard mode.

{1}  GENERAL_CONTEXT

The Clarion for Windows Debugger
This page describes the commands
available in the Debugger. Help for
dialog boxes is also available; a help
topic jump appears next to each command
that leads to a dialog box. You'll also
find a list of "how to" topics following
the command list:

Menu Commands:

 .   File Menu

File to Debug  Allows  you to choose  an
               executable file  to  load
               and  debug. Choose a file
               from    the   Open   File
               dialog.  When  you  start
               the   Debugger  from  the
               IDE,   it   automatically
               loads   the   executable.
               This  command allows  you
               to   start  the  Debugger
               first,  then load a  file
               into  a (see also) source
               code window.
Load Redirection    Allows you to change
               the Redirection file used
               for  the current Debugger
               session.  The Redirection
               file  provides a list  of
               directories to search for
               libraries,  source  code,
               and   debug   information
               files.
Debug Active DLL      Adds   a   related
               dynamic    link   library
               (*.DLL)   to  the   debug
               session.  Choose  a  file
               from   the   (see   also)
               Active   Module   dialog.
               This  option is available
               for  hard  mode debugging
               only.
Sleeper Mode   Sets  the  Debugger  into
               sleep  mode, in which  it
               waits  for  a  protection
               violation          (GPF),
               ctrl+alt+sys req,  or  an
               INT3.   This  option   is
               available  for hard  mode
               debugging only.
               You    can   start    the
               Debugger  in  sleep  mode
               from the command line  by
               adding  /s to the command
               line.
Add Sources    Allows   you   to    open
               additional  source  files
               for   the  current  debug
               session.
Exit           Closes the Debugger,  and
               terminates the Debuggee.
Restart        Continues   a  previously
               terminated Debug session.
               The Debugger will restart
               with    previous    watch
               expressions   and   break
               points, provided that the
               source   code   has   not
               changed.

 .   Edit Menu

Find Text      Opens the (see also) Find
               Text dialog, allowing you
               to  search for text in  a
               source code window.
Find Next      Repeats  the  last   text
               search.
Find Procedure Opens the (see also) Find
               Procedure  dialog,  which
               allows  you to  choose  a
               procedure from the  list,
               then  locate  the  source
               code for the procedure in
               a source code window.
Goto Line      Opens the (see also) Goto
               Line dialog, which allows
               you to move the selection
               bar  to  the line  number
               you specify.
Current Line   Moves  the selection  bar
               to      the     currently
               executing  line  in   the
               source code window.
Find Last Error      Moves the selection
               bar  to  the source  code
               line  where the  Debugger
               last  detected an  error.
               See also Setup dialog.
Breakpoints    Opens   the  (see   also)
               Breakpoints dialog, which
               allows    you   to    set
               conditional            or
               unconditional
               breakpoints.  Breakpoints
               allow       you        to
               automatically        halt
               execution at the line  of
               code  at  which (or  near
               which)   you  think   the
               problem   occurs.    Your
               program  runs up  to  the
               breakpoint,  then   halts
               and turns control back to
               the   Debugger.  You  can
               then  check the  contents
               of      variables     and
               expressions  to  identify
               the cause of the problem
Edit           Opens the (see also) Edit
               Variable  dialog,   which
               allows you to change  the
               value of a variable while
               the      Debuggee      is
               suspended. You  can  then
               resume execution to  test
               the  program with the new
               value.
               You  must first select  a
               variable  in  either  the
               Global  Variables  window
               or  the Active Procedures
               window.

 .   ! Menus

The Go!, GoCursor!, Step!, and ProcStep!
commands execute your application  while
the   Debugger  monitors   it   in   the
background. They allow you to test  your
application  in a controlled environment
which helps you identify bugs faster.

Tip: These  commands are all  top  level
     menu  commands.  No pulldown  menus
     appear  below them; just place  the
     cursor  on  the  menu  command  and
     click,   or  press  alt  plus   the
     underlined letter to execute.

Go!            Runs  the  Debuggee  from
               its  current state to the
               next  breakpoint. When  a
               source   or   disassembly
               window is active,  the  g
               key executes the command.
GoCursor!      Runs  the  Debuggee  from
               its  current state to the
               currently selected source
               or  assembler line in the
               source      code       or
               disassembly window.  When
               a  source  or disassembly
               window is active,  the  c
               key executes the command.
Step!          Runs  the  Debuggee  from
               the   currently  selected
               source or assembler line,
               one  line  of code  at  a
               time.  When a  source  or
               disassembly   window   is
               active,   the    s    key
               executes the command.
ProcStep!      Runs  the  Debuggee  from
               the   currently  selected
               source or assembler  line
               to  the  next, but  skips
               through  procedure  calls
               without stopping. When  a
               source   or   disassembly
               window is active,  the  p
               key executes the command.

 .   Options Menu

Soft Mode      Toggles  hard  and   soft
               mode debugging.
               In  soft  mode, when  the
               Debuggee is suspended  in
               the Debugger, part of the
               Debugger will attempt  to
               simulate the behavior  of
               the Debuggee.
               In  hard  mode, when  the
               Debuggee is suspended  in
               the  Debugger,  the  only
               window to operate is  the
               Debugger.    All    other
               activity   is  suspended.
               One  consequence of  this
               is  that  the desktop  is
               not redrawn.
Clarion Soft Mode    The  Debugger  will
               use  part of the  runtime
               library  to simulate  the
               behavior of the Debuggee.
               This  is  the recommended
               mode for most projects.
Extended Stack Trace      Debugger shows
               information         about
               procedures when no  debug
               information is available.
               A    disassembly   window
               opens,   containing   the
               relevant segment.
Disassembly On The       (see      also)
               Disassembly        window
               "shadows"   the    active
               source  window. When  you
               select  a line of source,
               the    cursor   in    the
               disassembly window  moves
               to the line corresponding
               to it.
               This  menu  is  a  toggle
               option.      If       the
               disassembly   window   is
               closed  when you turn  on
               the  option, you can open
               it  by double clicking on
               a   source   line,   then
               pressing  Cancel  in  the
               Break Point dialog.
Assembly Single  Step      Toggles  step
               mode     for    assembler
               breakpoints.         When
               execution   reaches    an
               assembler     breakpoint,
               step mode is set on. When
               execution    reaches    a
               source   breakpoint,   it
               turns off.
Control Panel  Displays a toolbox window
               with              buttons
               corresponding to the four
               Go!  commands.  The  next
               time   the  Debuggee   is
               suspended,  the   control
               panel receives focus.
               When  debugging  in  hard
               mode, when you switch the
               active window to the main
               Debugger   window,    you
               cannot access the control
               panel.
Setup          Opens   the  (see   also)
               Setup dialog
Custom Groups  Opens   the  (see   also)
               Selective  Break   Points
               dialog, which allows  you
               to  customize the windows
               message groups for  which
               you  can  set conditional
               break points.
Custom Colors  Opens   the  (see   also)
               Colors   dialog,    which
               allows  you  to  set  the
               Debugger selection colors
               for   the   source   code
               windows.

 .   Window Menu

Cascade        Resizes    the     active
               windows, and places  them
               in     an     overlapping
               arrangement.
Tile           Resizes    the     active
               windows, and places  them
               in an end to end vertical
               arrangement.
Tile Horizontal      Resizes the  active
               windows, and places  them
               in    an   end   to   end
               horizontal arrangement.
Arrange Icons  Arranges   the   iconized
               windows and arranges them
               at  them at the bottom of
               the  Debugger application
               frame.
Registers      Opens   the  (see   also)
               Registers  window,  which
               shows     the     current
               registers values.
Library State  Opens   the  (see   also)
               Library   window,   which
               shows  the return  values
               for    Clarion    library
               functions.
Windows Messages    Opens the (see also)
               Windows  Messages window,
               which displays up to  200
               Windows          messages
               generated by and sent  to
               the Debuggee.
Position Debuggee    Sizes  the Debuggee
               to  the  maximum  desktop
               area not taken up by  the
               Debugger.  This  has   no
               effect  when the Debugger
               is maximized.
Global Variables    Opens the (see also)
               Global  Variables window,
               which  shows the  current
               value  of  each component
               of each variable.
Watch Expressions   Opens the (see also)
               Watch Expressions window,
               which  shows the  current
               value  of  variables  and
               expressions.
Active Procedures   Opens the (see also)
               Active Procedures window,
               which lists the procedure
               currently executing,  and
               allows   you  to  monitor
               nested procedure calls.

 {2} COLOR_CONTEXT

  The Colors Dialog

The Debugger displays the lines within a
(see also) source code window in
different colors, which you can
customize. Select a radio button for the
line type you wish, then choose a color
from the list box.

You can specify colors for the Current
Line, General Cursor, Inactive Code and
Break Points.

You can also specify a Monochrome
"color" scheme, by checking the box.

 {3} GROUP_CONTEXT

  The Selective Break Point Groups
  Dialog

This allows you to set up your own
custom message groups to watch. Type a
name for the group, and choose the
Windows messages from the listbox.
When setting conditional breakpoints in
the (see also) Break Point dialog, you
can specify your custom group.
Volume 3 of the Microsoft Windows 3.1
Programmers Reference, published by
Microsoft Press, devotes over 200 pages
to lists and descriptions of all Windows
messages.

{4} BREAKPOINT_CONTEXT

  The Break Point Dialog

This dialog is where you set
breakpoints.

Normally, when debugging an application,
you'll identify a small part of the
program which produces incorrect output,
or crashes. The Debugging process for
this situation will probably require
running just that part of the program,
and stopping it at one or more points to
check its status.

Breakpoints allow you to automatically
halt execution at the line of code at
which (or near which) you think the
problem occurs. Your program runs up to
the breakpoint, then halts and turns
control back to the Debugger. You can
then check the contents of variables and
expressions to identify the cause of the
problem, and step through from that
point on. When in Step mode, the
Debugger executes one source code
statement, then returns control to the
Debugger until you issue the next (see
also the Step! command).

You can also set conditions on the
breakpoint, telling the program to
continue executing if the condition is
false, or turning control over to the
Debugger if true. After you set a
breakpoint, the source code line where
the breakpoint occurs appears in magenta
in the source window. For "How To
information, see also Setting
a Conditional Breakpoint and
Setting Conditional Breakpoints.

Break Kind     Choose the type of break.
               Always  -  Specifies   an
               unconditional break.  The
               Debugger   will    always
               suspend execution at this
               point.
               Watch  Expression  #0   -
               Specifies  a break  based
               on  the  contents  of   a
               variable   in  the   (see
               also)  Watch  Expressions
               window.  Type the  number
               of   the  variable   (its
               place  in the Watch list)
               in the Watch Number box.
               Windows Message - Type in
               a message name, or select
               a  message from the combo
               box.
               Message Group - Choose  a
               message  group.  A  group
               can  indicate a  category
               of   messages,  such   as
               mouse  or  key  messages.
               You  can  also set  up  a
               custom  message group  in
               the  (see also) Selective
               Break     Point    Groups
               dialog.    to    remember
               several          specific
               messages,  so  that   the
               breakpoint   will   occur
               only   on  one  of  these
               messages.  For   example,
               you    could   place    a
               breakpoint  which  checks
               for    a   WM_RBUTTONDOWN
               message,  which  is   the
               message   Windows   sends
               when the user clicks  the
               right  mouse  button   in
               your window. When you run
               the  program, you  right-
               click   inside  it,   and
               Windows      sends      a
               WM_RBUTTONDOWN message to
               your   application.   The
               breakpoint      condition
               would be true.
               Message  Not In  Group  -
               Choose a message group to
               exclude.
Remove         Removes    the   selected
               break point.
Custom Groups  Allows  you to  define  a
               message  group  comprised
               only   of   the   Windows
               messages you want. Define
               them  in  the (see  also)
               Selective   Break   Point
               Groups dialog.

{5} LOCATE_BREAK_CONTEXT

  The Break Points Dialog

This dialog presents active break points
in a list. Its main function is to allow
you to select a break point, then
quickly highlight the source code line
containing the break.

Locate         Activates the source code
               window   and  moves   the
               selection  bar   to   the
               source  code  line  where
               the   break   point    is
               located.
Delete         Deletes  the break  point
               from the list.
Edit           Opens   the  (see   also)
               Break Point dialog.

{6} SELECT_SOURCE_CONTEXT

  The Sources to Include in Session
  Dialog

This dialog allows you to add source
code files to the Debug session.
Only files for which you specified that
the Project System includes debug
information appears in the list. See
also Preparing Your Projects for
Debugging.

The buttons in the dialog allow you to
select or de-select more than one file
at a time. When you expand the dialog,
two additional lists display the names
of source code files selected or already
in the session.

{7} INTERNAL_ERROR_CONTEXT

  Internal Error Dialog

This dialog indicates an error has
occurred in the Debug session. The
Debugger provides as much of a
description as possible. In some cases,
it may be necessary to exit Windows and
reboot the machine before trying again.

{8} UNKNOWN_CONTEXT

  Unknown Error Dialog

This dialog indicates an error has
occurred in the Debug session. Exit
Windows and reboot the machine before
trying again.

{10} LOAD_MODULE_DLL_CONTEXT  1

  Select Active Module Dialog

This dialog allows you to add a dynamic
link library, if opened by the Debuggee,
to the Debug session. If the .DLL
contains debug information, you can view
the source code.

You can specify in the (see also) Setup
dialog whether to ignore the information
in the .DLL file. Debugging the .DLL may
increase the startup time for the Debug
session.

{11} WATCH_CONTEXT            1

  The Watch Expression Dialog

The Watch Expression dialog allows you
to add or edit a variable or expression
in the (see also) Watch Expressions
window.

Type an expression in the Expression to
Evaluate field, then press the OK
button. When the Debugger runs the
program, it will test the expression
upon reaching the breakpoint, and halt
if the expression evaluates true.

The Watch Expression dialog also
contains a Browse button, to help create
your expression faster. Press the Browse
button to see a list of the variables
local to the procedure you're currently
debugging.

You can prefix the variable name with a
procedure name and/or a module name.
This allows you to name a variable not
currently in scope, for example, a
variable in another procedure that would
not be visible for the current
procedure.

 .  To    specify   a   procedure    and
     variable, prefix the variable  with
     the  procedure name plus  a  period
     (".").

    For    example,    "RoyalFlush.King"
     refers to a variable called King in
     the procedure called RoyalFlush.

 .  To   specify  a  module  and  global
     variable, prefix the variable  with
     the module name plus a dot (".").
    For    example,   "NewDeal.Shuffled"
     refers  to a global variable called
     Shuffled   in  the  module   called
     NewDeal.

 .  To  specify  a local variable  in  a
     procedure   in   another    module,
     combine the prefixes.

    For example,
     "Poker.RoyalFlush:King"  refers  to
     the  variable called  King  in  the
     procedure called RoyalFlush in  the
     module called Poker.

 .  You  may specify register names (for
     example, ax) in a watch expression.

 .  You  may use the unary operator (  @
     ) to denote the address of a memory
     object.

Tip: The  Debugger will guess the  right
     prefix if the variable is unique.

The following list presents the
operators and expression syntax for the
Watch Expression dialog. The operators
are language independent, derived from
C/C++, and Modula 2/Pascal operators.

     Key       Function
     +         add
     -         subtract
     *         multiply
     / or DIV  divide
     % or MOD  modulus (remainder)
     |          bitwise OR
     &         bitwise AND
     <         less than
     <=        less than or equal to
     >         greater than
     >=        greater than or equal to
     =         equal
     != or <>  not equal
     ! or NOT  logical NOT
     & or AND  logical AND
     | or OR    logical OR
     *         indirection (when prefix)
     ^         indirection (when post-
     fix)
     ->        point at member
     .         select member (record
     field)
     ::={e,d}  display expression e as
               if it was the same type d

{13} SETUP

  The Setup Dialog

This dialog allows you to select various
options which carry over from Debugger
session to session.

Ignore .DLL Files       Instructs    the
               Debugger to ignore  debug
               information    in    .DLL
               files.  This reduces  the
               startup   time  for   the
               Debugger. See also Select
               Active Module dialog.
Disable Kernel Msgs  If  you are running
               the   Debug  version   of
               Windows (available in the
               Microsoft   Windows   3.1
               SDK),  the Debugger  will
               automatically trap  error
               messages  posted  by  the
               kernel (one of the  three
               main     dynamic     link
               libraries   utilized   by
               Windows). You can  locate
               such errors with the Find
               Last Error command.
               If  you are not using the
               AUX   device  to   report
               messages,  add  the  line
               OutputTo=NUL    in    the
               [DEBUG]  section of  your
               SYSTEM.INI file.
Report Missing Source      The  Debugger
               automatically prompts for
               source   code  files   it
               cannot locate.
Iconize When Inactive      Automatically
               iconizes   the   Debugger
               when   the  Debuggee   is
               active.
Debugger On Top     The Debugger appears
               on  top an any other open
               windows    when   active;
               relevant  for  hard  mode
               debugging only.

Tip: When  working in Hard mode, type  d
     to bring the Debugger to the top.

Disassembly Opcodes    The   disassembly
               window  contains only  op
               codes,  eliminating   the
               space  taken up by binary
               codes.
Smart Single Stepping     When  enabled,
               single stepping on a line
               with   a  procedure  call
               will   load   the   debug
               information    for    the
               target   procedure,    if
               available.  This   option
               extends  to  .DLL's  with
               debug information.
No Horizontal Scroll        Hides    the
               horizontal       Debugger
               scroll bars.
Global Find Text     When disabled, each
               source window "remembers"
               its   own   search   text
               string. When enabled, the
               default search text  will
               be  the same as the  last
               search, regardless of the
               window.
Order Record Fields  When  enabled,   it
               orders     the     RECORD
               variables    by    memory
               address.
Auto Tile      Tiles  the open  Debugger
               windows.
Clean Desktop  When     enabled,      it
               minimizes    all    other
               running      applications
               (other than the debuggee)
               when     the     debugger
               activates.
Max Source Windows  Self explanatory.
Max Disassembly     Self explanatory.

{14} FIND_TEXT

  The Find Text Dialog

This dialog allows you to search for
text within the source code document(s).
Type the text to search for in the edit
box, then press the Find button.

{15} ABOUT_CONTEXT            1

  The About Dialog

This dialog provides a copyright screen
for the Debugger.

{16} EDIT_VAR_CONTEXT         1

  The Edit Variable Dialog

This dialog allows you to change the
value of a variable at run time.
Type in a new value and press the OK
button.
See also Editing Variables at Runtime

{17} GOTO_LINE_CONTEXT        1

  The GoTo Line Dialog

This dialog allows you to move the
selection bar to the source code line
number you specify.

Type the number of the line in the edit
box, then press the OK button.

{18} FIND_PROCEDURE_CONTEXT   1

  The Find Procedure Dialog

This dialog allows you to move the
selection bar to the source code line at
which the procedure you select begins.
Select a procedure name from the list,
then press the Locate button.

{21} SOURCE_WINDOW            2

  The Source Window

The source windows display the source
code documents. The title bar shows the
document file name. By default, the
current line cursor is green. When you
select a line other than the current,
the cursor is light cyan.

Tip: If   the   Debugger  opens  without
     listing  any source code  documents
     in   the  (see  also)  Sources   to
     include in this session dialog, the
     most probable cause is that none of
     the source code files listed in the
     Project   Tree   contained    debug
     information. Check for .DAD  files,
     which     contain     the     debug
     information.

ins inserts an unconditional break point
at the cursor. del removes one. Pressing
the space bar displays the Break Point
dialog.

{22} DISASSEMBLY_WINDOW       2

  The Disassembly Window

The Disassembly window display the
machine instructions for the active
module.

If you run the Debugger on a program
with no debug information, the
Disassembly window automatically
displays the assembly language
instructions. The current instruction is
selected.

double-clicking (or pressing enter) on a
line in the Disassembly window which
contains a jump or call instruction
moves the cursor to the target location.
esc returns the cursor to the original
location.

ins inserts an unconditional break point
at the cursor. del removes one. Pressing
the space bar displays the (see also)
Break Point dialog.

{23} GLOBAL_WINDOW            2

  The Global Variables Window

The Global Variables window shows you
the current value of each component of
each variable. For example, for a string
variable of eighteen characters,
eighteen separate lines show the
contents of the each position of the
string. The variables window contains
tree controls, so that you can expand
only the variables you want to examine.
Each variable has a tree control to
expand its listing. The top level is the
source code module which contains the
variable. The next is the variable name.

{24} ACTIVE_PROCEDURE_WINDOW  2

  The Active Procedures Window

The Active Procedures window lists the
procedure currently executing, which
allows you to monitor nested procedure
calls. The window appears in tree
format. The upper levels represent the
names of procedures and the lower levels
represent the variables. double-clicking
on an active procedure displays the
source or disassembly. double-clicking
on a variable copies it to the (see
also) Watch Expressions dialog.
When working with more than one (see
also) THREAD, the Active Procedures
window displays information for the
current thread only.

{25} WATCH_WINDOW             2

  The Watch Expressions Window

The Watch Expressions window shows the
current value of variables and
expressions. Set a watch expression to
see how a variable or expression changes
as your program executes.

See also the Watch Expression dialog to
learn the syntax for watch expressions,
and how to edit an expression in the
list. To add a variable to the watch
list:

1.   double-click  on an empty  line  in
     the Watch window.
2.   When  the Watch Expressions  dialog
     appears,  type a variable name  (as
     it  appears in the global variables
     list) and press OK.
3.   Alternatively,  press  the   Browse
     button, select a variable from  the
     list, then press OK twice.

The  expression or variable  appears  in
the   watch  window,  and  its   current
contents appear next to it.

You can also add a variable to the watch
window by double-clicking or pressing
enter on a variable in either the global
variables or the active procedures
windows.

You can add a watch expression by double-
clicking on an empty line in the Watch
Expressions window, then specify an
expression in the Watch Expression
dialog.

Tip: To   quickly   add   a   structured
     variable (such as a record,  string
     or array) to the watch list, double-
     click on it in the Global Variables
     or  Active Procedures windows, then
     press  the Copy Variable  to  Watch
     button.

{26} MESSAGE_WINDOW           2

  The Message Window

The Messages window displays up to the
most recent 200 message events generated
by or directed to your application. The
Debugger adds a separator line ("-----")
to indicate a breakpoint occurred.
Every action the user takes_from mouse
movement to menu commands_is first
processed by Windows. If Windows
determines the action is for your
application, it passes the information
to your application via a message. For
example, if the user types the letter
"A," it sends a WM_KEYDOWN message to
your application, with the key code for
"A" as the first message parameter.
See the Break Point dialog for
information on selecting Windows
messages to break on.

Tip: If you include DDE services in your
     application,  we recommend  testing
     your  application with another  DDE
     application and monitoring the  DDE
     messages.  For further information,
     see   the  Microsoft  Windows   3.1
     Programmers  Reference,  Volume  3,
     available from Microsoft Press.

{27} CLARION_LIBRARY_WINDOW

  The Library Window

The Library window displays return
values for Clarion library functions.
These functions represent all the field
and other events. Functions include (see
also) ACCEPTED, (see also) SELECTED,
(see also) FIELD, (see also) FOCUS, (see
also) FIRST-FIELD, (see also) LASTFIELD,
(see also) ERRORCODE, AND (see also)
ERRORFILE.

The names listed in EQUATES.CLW and
KEYCODES.CLW appear next to the return
values.

{28} REGISTER_WINDOW

  The Registers Window

The Registers window shows the current
register values; the register appears in
the left column, and its value to the
right.

{29} SETTING_UNCONDITIONAL_BREAKPOINTS

  Setting Unconditional Breakpoints
Normally, when debugging an application,
you'll identify a small part of the
program which produces incorrect output,
or crashes. The Debugging process for
this situation will probably require
running just that part of the program,
and stopping it at one or more points to
check its status.

Breakpoints allow you to automatically
halt execution at the line of code at
which (or near which) you think the
problem occurs. Your program runs up to
the breakpoint, then halts and turns
control back to the Debugger. You can
then check the contents of variables and
expressions to identify the cause of the
problem, and step through from that
point on. When in Step mode, the
Debugger executes one source code
statement, then returns control to the
Debugger until you issue the next Step!
command.

When you set a breakpoint, the source
code line where the breakpoint occurs
appears in magenta in the source window.
An unconditional or "sticky" breakpoint
is placed on a source code line, and
stops execution whenever the program
encounters that statement. To add an
unconditional breakpoint:

1.   Open the (see also) source code  or
     disassembly window.
2.   Locate the line of code to break on
     and double-click on it.
3.   When  the  (see also)  Break  point
     dialog  appears, select Always  and
     press the OK button.

When you execute the Go! command, the
Debuggee runs until it reaches the
breakpoint, then stop.

{30} SETTING_CONDITIONAL_BREAKPOINTS

  Setting Conditional Breakpoints

To narrow the search for bugs, you can
tell the Debugger to break only when a
certain condition exists. The condition
takes the form of an expression which
can include program variables, operators
and constants. You can also tell the
Debugger to break when it detects a
particular message or messages from
Windows to the application.

 .  To  set a conditional breakpoint  on
     a  change  in  a watch expression's
     value:

1.   Establish  a  watch  expression  as
     described  in the (see also)  Watch
     Expression dialog, below.
2.   Locate the line of code to break on
     and double-click on it.
3.   When  the  (see also)  Break  point
     dialog   appears,   select    Watch
     Expression #0.
4.   Type   the  number  of  the   watch
     expression    (from    the    watch
     expressions window) in the  Watch#0
     field.
5.   Press the OK button.

When  you  execute the Go! command,  the
program   runs  until  it  reaches   the
breakpoint,    evaluates    the    watch
expression, then stops if the expression
is  true,  i.e., evaluates to a non-zero
value.

For example, if variable X should have a
maximum value of 999, but increments  to
1000 anyway, causing havoc, you can tell
the  Debugger to break at 999, then step
through the program to see when and  how
it reaches 1000.

 .  To  set a breakpoint conditional  on
     a specific Windows message:

1.   Locate  a line of code to break  on
     and double-click on it.
2.   When   the   Break   point   dialog
     appears, select Windows Message.
3.   Select  a Windows message from  the
     Windows Message combo box.
4.   Press the OK button.

For   example,   you   could   place   a
breakpoint in a loop which checks for  a
WM_RBUTTONDOWN  message,  which  is  the
message  Windows  sends  when  the  user
clicks  the right mouse button  in  your
window.  When  you run the program,  you
right-click inside it, and Windows sends
a   WM_RBUTTONDOWN   message   to   your
application.  The  breakpoint  condition
would be true.

 .  To  set a breakpoint conditional (or
     not)  on  receipt of one of several
     Windows messages:
1.   Locate the line of code to break at
     and double-click on it.
2.   When   the   Break   point   dialog
     appears,  select Message Group;  or
     Message Not in Group.
3.   Select  a  message group  from  the
     list.  This can indicate a category
     of  messages, such as mouse or  key
     messages.  You can also  set  up  a
     custom  message group (by  pressing
     the   Custom   Groups  button)   to
     remember several specific messages,
     so  that the breakpoint will  occur
     only on one of these messages.
4.   Press the OK button.

For   example,   you   could   place   a
breakpoint in a loop which checks for  a
Key  message. When you run the  program,
when  you press a key, Windows  sends  a
message  to  your application,  and  the
breakpoint condition would be true.

 .  To  set  a  breakpoint which  breaks
     when   you  receive  an  unexpected
     message, that is, one that  doesn't
     belong to a group you specify:
1.   Locate  the line of code  at  which
     you    want   to   establish    the
     breakpoint and double-click it.
2.   When   the   Break   point   dialog
     appears, select Message Group.
3.   Select  a  message group  from  the
     combo  box.  The  breakpoint   then
     occurs  only  when the  application
     receives  a  message  not  in  this
     group.
4.   Press the OK button.

{31} EDITING_VARS_AT_RUNTIME

  Editing Variables at Runtime

Using  the Debugger, you can change  the
value  contained  in a  memory  variable
while the program is suspended. You  can
then   resume   the  program   to   test
execution  with the variable  containing
the new value.

To change the contents of the variable:

1.   Select  the variable in either  the
     (see also) Global Variables or  the
     (see    also)   Active   Procedures
     windows.
2.   Press f2, or choose Edit „ Edit.
The  (see  also)  Edit  Variable  dialog
appears.
3.   Type  a  new value for the variable
     and press the OK button.
     When  you  choose  Go!,  GoCursor!,
     Step!,  or  ProcStep!, the  program
     resumes  execution with the  memory
     variable   changed   to   the   new
     variable.

{32} PREPARING_FOR_DEBUGGING

  Preparing Your Projects for Debugging

The Project System allows you to set the
debug global options in the Global
Options dialog, in the IDE. To create an
.EXE file to debug, do the following in
the IDE, before launching the Debugger:

1.   Create your project file, and  make
     it the current project.
2.   Choose   Project  „  Edit   Current
     Project  to  view the Project  Tree
     dialog.
3.   Select  the top level of the  tree,
     which   holds  the  name   of   the
     project,  and press the  Properties
     button.
4.   When   the  Global  Options  dialog
     appears, mark the Full checkbox  in
     the Debug Information group box.
5.   Optionally  check the Line  Numbers
     box.
6.   Press  the  OK button to close  the
     dialog.
7.   Press   the  Make  button  on   the
     toolbar  to  compile and  link  the
     application.

The application now includes the
information the Debugger needs.
You can also turn on debugging
information for a single module in the
project. The advantage of this is that
it reduces the overhead for the
debugger. To do so, do the following in
the IDE, before launching the Debugger:

1.   Create your project file, and  make
     it  the current project (the  Using
     the Project System chapter explains
     how).
2.   Choose   Project  „  Edit   Current
     Project  to  view the Project  Tree
     dialog.
3.   Select  only the source module  you
     need   to  debug,  and  press   the
     Properties button.
4.   When  the  Compile  Options  dialog
     appears, mark the Full checkbox  in
     the Debug Information group box.
5.   Check the Line Numbers box.
6.   Press  the  OK button to close  the
     dialog.
7.   Press   the  Make  button  on   the
     toolbar  to  compile and  link  the
     application.

This includes debug information for that
module only.

The Debugger runs as a separate
application, but you can start it either
inside the IDE, or directly from
Windows.

 .  To  start  the Debugger  inside  the
     IDE, either:

1.   Either  choose Project „  Debug  or
     compile  and  link your application
     by pressing the Make button.
2.   With  the  Compile  results  dialog
     still open, press the Debug button.

 .  To  start  the Debugger as a  normal
     application.

1.   Switch to Program Manager and  open
     the Clarion group.
2.   double-click the Debugger icon.
If  you wish to start the Debugger  from
another program launcher the application
file name is CLWDB.EXE.
3.   With  the Debugger launched, choose
     File  „  File to Debug, then choose
     an  .EXE  file  in  the  Open  File
     dialog.

You can load the debugger, then debug  a
program  which was launched even  before
you  loaded the debugger. This is useful
for  situations where the program  under
development  unexpectedly  "misbehaves,"
but hasn't yet produced a fatal error.
To do so, start the debugger and execute
the  File  to Debug command. Choose  the
.EXE  file for the running program  from
the  Open File dialog. The debugger will
ask  you  to  confirm that you  wish  to
debug a running program.

When  you  launch the Debugger from  the
Compile Results dialog, you must confirm
the name of the source code files.

 .  To  load  the source files when  the
     Debugger appears:

1.   Select the source code files in the
     (see  also)  Sources to include  in
     session dialog.
The  debug  information file stores  the
files you select between debug sessions.
2.   Press the OK button.
The Debugger windows appear.
If  the  application  does  not  include
debug  information, the  Debugger  skips
this   step  and  opens  a  (see   also)
disassembly window.

asdfasdasd

