harbour-core/src/debug/en.txt

--About Help
 Up/Down        Select help topic.
 PageUp         Page help text down.
 PageDn         Page help text down.
 Esc            Returns to debugger.
--Keys
Special debugger keys fall into the following
categories:

    Function Keys
        Keys that execute debugger functions

    Window keys
        Keys that operate on the active window

    Others
        Keys for window navigation and sizing


Other keys (typeable characters) are sent to
the Command window and treated as input text.
--   Function
F1     Help
F2     Zoom active window

F3     Retype last command
F4     View Application (User) screen

F5     Go (Run application)
F6     View Workareas screen

F7     Run to cursor line
F8     Step

F9     Set breakpoint on cursor line
F10    Trace
--   Window
Enter        If input is pending in the Command window,
             <Enter> will execute the command, regardless
             of which window is active. Otherwise, if the
             Monitor or Watch window is active, ENTER will
             inspect the selected window item.

Up           In Code window, moves cursor line up.
             In Command window, recalls previous command.
             In other windows, moves selected item up.

Down         In Code window, moves cursor line down.
             In Command window, recalls previous command.
             In other windows, moves selected item down.

PageUp       In Code window, pages source up.
             In Command window, does nothing.
             In other windows, pages item list up.

PageDn       In Code window, pages source down.
             In Command window, does nothing.
             In other windows, pages item list down.

Ctrl PageUp  In Code window, moves cursor line to top.
             of source.
             In Command window, does nothing.
             In other windows, selects first item on list.

Ctrl PageDn  In Code window, moves cursor line to bottom.
             of source.
             In Command window, does nothing
             In other windows, selects last item on list.

Left         In Code window, scrolls left 1 column.
             In Command window, moves cursor left.
             In other windows, does nothing

Right        In Code window, scrolls right 1 column.
             In Command window, moves cursor right.
             In other windows, does nothing.

Home         In Code window, scrolls hard left.
             In Command window, moves cursor to beginning
             of line.
             In other windows, does nothing.

End          In Code window, scrolls hard right.
             In Command window, moves cursor to end
             of line.
             In other windows, does nothing.

Esc          In Command window, clears command line.
             In other windows, does nothing.
--   Other
TAB         Next window

SHIFT-TAB   Previous window

ALT-G       Grow active window

ALT-S       Shrink active window

ALT-U       Move the border between Command and Code
            windows Up

ALT-D       Move the border between Command and Code
            windows Down

ALT-X       Exit
--Windows
The Debugger display consists of the following five
windows:

    Command Window
        Accepts and displays debugger commands.
        Always open.

    Code Window
        Displays program source code.
        Always open.

    Watch Window
        Displays Watchpoints and Tracepoints, and inspects
        their values.
        Open when any Watchpoints or Tracepoints are
        defined. These are set and deleted via the
        Point menu.

    Monitor Window
        Displays monitored variables, and inspects their
        values.
        Open when any classes of variables are being
        monitored, via commands in the Monitor menu.

    CallStack Window
        Displays program call stack.
        Opened via the View:CallStack menu option.

        If this window is active, the Code, Watch and
        Monitor windows will display information pertaining
        to the selected call on the CallStack.


One debugger window is active at a time. The active window
is displayed with a hilighted border. TAB and SHIFT-TAB
navigate among open windows.

The Window menu contains options to Move, Size, Zoom and
Iconize the active window.

After a long session of moving and sizing, the Window:Tile
menu option will restore the windows to their original
size and location.
--   Command
The Command window accepts debugger commands as line
input, and displays the response from an executed
command, if any.

Commands are entered simply by typing in the command
text, then pressing ENTER.

Commands may be entered and executed while any
window is active. However, the entry cursor is
only visible within the Command window when it is
active.

When the Command window is active, the UP and DOWN
arrow keys can be used to recall previous commands.
--   Code
The Code window displays Clipper source code for
the program being debugged.


What file the Code window displays may be controlled
in the following ways:

    1.  By default, the Code window will contain the line
        of Clipper code currently being executed.

    2.  If the CallStack window is open, the code being
        viewed is that of the selected call in the CallStack
        window.

        NOTE: By default this will be the same code as 1,
        but code for the other calls may be viewed by
        making the CallStack window active and using UP
        and DOWN to traverse the call stack.

    3.  A specific file may be viewed by issuing a VIEW
        command, or selecting the File:View menu option.


If the Code window contains the line of Clipper code
currently being executed, that line will be hilighted.
Any lines which have Breakpoints set on them will also
be marked.


In addition to standard navigation keys, you can search
the viewed file for a specific string, or go to a particular
line within it, using options found in the Locate menu.
--   Watch
The Watch window displays Watchpoint and Tracepoint
expressions, and their current values.

Watchpoints and Tracepoints may be defined and deleted via
options on the Point menu. You can edit a Watchpoint or
Tracepoint expression by selecting it in the Watch window
and pressing CTRL-ENTER.

If the Watch window is active, pressing ENTER will inspect
the value of the selected expression. The navigation keys
described in 'Window Keys' may be used to change the
selected item.

If the CallStack window is active, the Watch window will
display the values for Watchpoints and Tracepoints at the
activation level represented by the selected call in the
CallStack window.
--   Monitor
The Monitor window displays monitored variables.

Classes of variables may be monitored via options in the
Monitor menu.

If the Monitor window is active, pressing ENTER will
inspect the value of the selected variable. The navigation
keys described in 'Window Keys' may be used to change the
selected item.

If the CallStack window is active, the Monitor window will
display the values of variables at the point of the
activation level represented by the selected call in the
CallStack window.
--   CallStack
The CallStack window displays the program's call stack.
It is opened and closed via the View:CallStack menu
option.

By default, the selected call within the CallStack window
is the top one -- i.e., the call currently being executed.
When the CallStack window is active, the other call levels
may be selected using the navigation keys described in
'Window Keys'.

All other windows except the Command window are synchronized
with the CallStack window. The code viewed in the Code
window, the values of Watchpoints and Tracepoints in the
Watch window, and the values of variables in the Monitor
window are all in the context of the activation level
selected in the CallStack window.
--Menus
The debugger menus contain various debugger functions.

Each menu may be accessed at any time by pressing the
ALT key, and the first letter in the menu's name.

Once in a menu, the UP and DOWN arrow keys navigate
the list of options. An option may be selected by
pressing ENTER, or by typing the first uppercase
letter within the name of the desired option.


Some menu options toggle a debugger setting. These
options will have a checkmark displayed to their left
if the setting they refer to is currently ON.


Each menu option is also available as a command,
made up of the Menu name, followed by the first
word of the option name. For instance, the
View:CallStack menu option may also be accessed via
the command:

    View Call

Words within these commands may be shortened in most
cases to one letter.

For more information on this class of commands, see
the 'Commands' section of this help.
--   File
Options:

    Open...
    Specify a file to be opened in the Code window

    OS Access
    Shell to the OS environment

    Exit    Alt-X
    Exit the debugger
--   Locate
Facilites for navigating the file in the Code window

Options:

    Find...
    Search for a specified string, from the beginning
    of the file onward.

    Next
    Search for the next occurence of the Find string,
    from the cursor line onward.

    Prev
    Search for the previous occurence of the Find string,
    from the cursor line backward.

    Goto Line...
    Go to a specific line in the file being viewed.

    Case Sensitivity
    Toggles case sensitivity in searches. Default is
    OFF.
--   View
Options:

    Sets
    View Set status information

    Work Areas   F6
    View Database status information

    App. screen  F4
    Displays application screen, until key is pressed

    CallStack
    Toggles the CallStack window. Default is OFF
--   Run
Options:

    Restart
    Terminate program and re-execute, leaving debugger
    settings in place

    Animate
    Execute program in Animate mode

    Step              F8
    Execute one line of program code

    Trace            F10
    Trace over function call in program code

    Go                F5
    Execute program

    to Cursor         F7
    Execute program, breaking at the current cursor
    line in Code window

    Next routine Ctrl-F5
    Execute program, breaking at line 1 of the next
    procedure or function call.,

    sPeed...
    Set step speed for Animate mode execution
--   Point
Options:

    Watchpoint...

    Add Watchpoint. A Watchpoint is an expression which
    the debugger tracks during program execution -- the
    current value of a Watchpoint is displayed in the
    Watch window during debugging.

    A Watchpoint may be any valid Clipper expression,
    i.e.:

        s                   // variable
        a[ n ]              // array element
        g:buffer            // object instance variable
        At( s, t )          // return value of function call
        ValType( s ) == 'C' // value of expression


    Tracepoint...

    Add Tracepoint. A Tracepoint is similar to a Watchpoint,
    with the additional property that if the value of a
    Tracepoint expression changes, the debugger will be
    invoked as if a Breakpoint had been hit.


    Breakpoint   F9

    Set Breakpoint on current cursor line in
    Code window


    Delete

    Delete Tracepoint or Watchpoint.
--   Monitor
Options:

    Public
    Monitor Public variables.

    Private
    Monitor Private variables.

    Local
    Monitor Local variables.

    Static
    Monitor Static variables.

    Global
    Monitor Global variables.

    All
    Monitor All variables.

    Sort
    Toggles whether monitored variables are sorted by
    name. Default is OFF.
--   Options
Options:

    Preprocessed code
    Toggles the display of preprocessed code (from
    PPO file) within the Code window. Default is OFF.

    Line numbers
    Toggles the display of line numbers in the Code
    window. Default is OFF.

    Exchange screens
    Toggles whether debugger screen is swapped with
    application screen during debugger execution.
    Default is ON.

    Swap on Input
    Toggles whether debugger screen is swapped with
    application screen when the program being debugged
    is waiting for input. Default is ON.
    This setting is only meaningful when the Exchange
    Screens setting is OFF.

    Codeblock Trace
    Toggles whether the debugger will trace into
    code blocks when tracing (i.e., when in Trace
    mode). Defaults to ON.

    Menu Bar
    Toggles display of the debugger menu bar.
    Default is ON.

    mono Display
    Toggles display between monochrome and color.
    Default is OFF.

    Colors...
    Inspects debugger colors.

    Tab width...
    Set tab width in Code window. Default is 4.

    pAth for Files...
    Specify search path for source files.
    The debugger will use this path to search for
    files, if not found in the current directory.
    NOTE: If not found in the debugger path, the
    directories specified in the environment's PATH
    will be searched.


    Save Settings
    Save debugger settings to a script file.

    Restore Settings
    Restore debugger settings from a previously
    saved script file.
--   Window
Options:

    Next       Tab
    Make next window active.

    Prev    Sh-Tab
    Make previous window active.

    Move
    Move active window. UP, DOWN, LEFT, RIGHT,
    PGUP, PGDN, HOME, END move ENTER finishes,
    While Moving, top left corner of window is marked.

    Size
    Size active window. UP, DOWN, LEFT, RIGHT,
    PGUP, PGDN, HOME, END size ENTER finishes,
    While Sizing, bottom right corner of window is marked.

    Zoom        F2
    Toggles whether active window is Zoomed. When
    Zoomed, window will fill entire display area.

    Iconize
    Toggles whether active window is Iconized. When
    Iconized, window will be one row high and a few
    columns wide.

    Tile
    Restore all windows to original size and position.
--Commands
There are two sets of debugger commands:

1. Menu option commands. These commands are formed
from the menu name, followed by the (first word of)
the option name. For instance, the Monitor:Public
menu option may be invoked via the command:

    Monitor Public

These commands may be abbreviated down to one letter
per word. However in some cases a second letter will
be required in the second word, as in the case of
Monitor Private:

    M P     // invokes Monitor Public
    M Pr    // invokes Monitor Private



2. Other commands. Listed below.


? <exp>
    Display the value of a variable or expression.

?? <exp>
    Inspect the value of a variable or expression.

ANIMATE
    Execute application in Animate Mode.

BP [<nLineNum> [ <cFileName> ]]|[<cFuncName>]

   BP
      Toggle breakpoint at current line in current
      source file.

   BP <nLineNum>
      Toggle breakpoint at <nLineNum> in current source
      file.

   BP <nLineNum> <cFileName>
      Toggle breakpoint at <nLineNum> in <cFileName>
      source file.
   BP <cFuncName>
     Toggle breakpoint on function.

CALLSTACK on|OFF
    Toggle display of CallStack window

DELETE ALL [WP|TP|BP]
DELETE WP|TP|BP <nNumber>
    Delete all or particular Watchpoint, Tracepoint
    or Breakpoint.

DOS
    Visit the operating system.

FIND <cSearchString>
    Search currently viewed file for specified
    character string.

GO
    Execute application in Run Mode.

GOTO <nLineNum>
    Move cursor to specified line in currently viewed
    file.

HELP
    Get advice in the form of the Help window.

INPUT <cFileName>
    Read commands from specified Script File.

LIST BP|WP|TP
    List Breakpoints, Watchpoints or Tracepoints in
    the Command Window.

NEXT
    Search for next occurence of FIND string.

NUM ON|off
    Toggle display of line numbers in Code window.

OUTPUT
    View application screen.


PREV
    Search for previous occurence of FIND string.

QUIT
    Quit.

RESTART
    Restart application

RESUME
    Resume viewing the currently executing program
    code in the Code Window, after VIEWing another
    file.

SPEED <nSpeed>
    Set Animate mode step speed. <nSpeed> designates
    the number of tenths of a second to delay.
    <nSpeed> must be greater than or equal to 0.

STEP
    Execute one line of program code.

TP <exp>
    Establish <exp> as a Tracepoint. <exp> may be a
    variable or expression.

VIEW <cFileName>
   View specified file in Code window.

WP <exp>
    Establish <exp> as a Watchpoint. <exp> may be a
    variable or expression.
--Script files
Script files contain debugger commands, in the same
form they would take as input in the Command window.
By default, script files use the extension CLD, as in
'myscript.cld'.


Creating a script file:

A script file containing all the debugger's current
settings may be created via the Options:Save menu
option. A script file may also be written by hand,
in a text editor.


Reading a script file:

A script file may be read into the debugger at any
time using the Options:Restore menu option.

The extension '.cld' will be assumed if no extension
is supplied.

When reading a script file, the debugger will look
for the file in the current directory first. If the
script is not found there, the debugger will search
all directories in the PATH environment variable.


init.cld:

On startup (or, if it is linked into a program, when
it is first invoked), the debugger will look for a
script file called init.cld, in the current directory
and then, if not found, in the directories specified
by the PATH environment variable.

If init.cld is found, the debugger will read it
automatically. It is useful to place general
preferences in init.cld -- specifying colors,
turning on the CallStack window, and so on.