P
*
*
ASSIGN
BREAK
CALLS
DISPLAY
ECHO
GO
HELP
KEY
LIST
OUTPUT
PROFILE
QUIT
ROUTE
STEP
TRACE
VIEW
WATCH
XECUTE
.
PROBE checks for breakpoints,  tracing,  watching, or striking of any key at
the  start of each line of the source program on which a  statement  starts. 
When  execution of the program is interrupted,  the following  commands  are
available:

A(ssign) new value to variable     O(utput) to alternate screen
B(reak) into program at event      P(rofile) on/off
C(alls) to reach current point     QUIT to operating system
D(isplay) value of variable(s)     R(oute) taken to current point
E(cho) screen output to file       S(tep) execution through source
G(o) on with execution             T(race) execution in object code
H(elp) explain command use         V(iew) alternate output screen
K(ey) interruption on/off          W(atch) variable or source lines
L(ist) source lines                X (eXecute) program

     Further help is available on each of these.
A syntax-description of each command is given. Alternatives are separated by
a vertical bar "|",  optional parts are shown in brackets "[]"  or where the
contents can be repeated,  by braces "{}".  Grouping is shown by parentheses
"<>"
Important parts of the syntax are:
    character-string    characters between apostrophes ('String')
    integer-constant    a constant with an integer value (123, -1, 'c')
    qualifier           naming a source file ('LOGFILE':), subroutine
                        or function (XSUB:, IFUNC:)
    variable            a variable of the program under test (i, ia(1, j))
    value               number, boolean, enumerated, char, set or string
                        constant, or variable value (12, 17.3E2, true, v)
    break-watch-specifier  source line or range, variable, variable with
                        condition, or nothing at all.

These are defined on the next screen.
Definitions of syntactic terms used in the commands:
    break-watch-specifier =
        [ qualifier ] < [lines] | variable [op value]>
    qualifier =  file-name : | routine-name :
    value = variable | constant
    lines = integer-constant [ .. integer-constant]
    line-count = integer-constant
    constant = integer-constant | real-constant | double-precision-constant |
               complex-constant | character-string
    variable = identifier | identifier ( value { , value } )
    op = = | <> | < | >= | > | <=
    routine-name = identifier
    file-name = character-string
    character-string = ' { character } '
The form of identifiers, and the various number constants is as in Fortran.

          ASSIGN [qualifier] variable = value

The  value  of  the given variable is changed as  specified.   The  variable
identified  is that which would be referred to by the name when used at  the
current (or given) point in the source program.  Array variables may only be
altered element by element.


examples

          A count=3
          A size(I, 3)=25.3

                                                      


          BREAK [break-watch-specifier] | - | ?
          break-watch-specifier = 
                     [qualifier] <[lines]|variable [op value]>

The  executing  program will be interrupted each time  the  specified  event
occurs.  The  qualifier  identifies a source  file  or  subroutine/function. 
Execution  is  interrupted at given source line(s),  on changes in  a  given
variable,  or on a variable being greater, equal or less than a given value. 
The  break  is  added  to existing breaks,  any  one  of  which  will  cause
interruption  of  execution.  "B -"  removes, and "B ?"  lists  all  current
breaks.   With "B"  alone,  a break occurs on all source lines.   Specifying
just  a  start  line  number gives a single line.   Where  a  subroutine  is
specified, execution of any source line in the subroutine causes a break.
examples
          B ReadItem:
          B size<=0
          CALLS

The  nest  of  active subroutine or function calls leading  to  the  current
execution point is displayed, starting with the currently active source line
and working outwards to the main program.   The names of the active routines
are  displayed.   Their variables can be inspected by using these  names  as
qualifiers to the display command.

example
          C






          DISPLAY [ qualifier ] [ variable ]

If  a  variable is named,  the current value of the variable  is  displayed. 
Whole arrays may be displayed in this way.  Where only a qualifier is given,
parameters and local variables of the routine are named and displayed. Where
only a source file is given,  variables of the main program in that file are
displayed.   Where no parameter is given,  parameters and variables  of  the
currently  active subroutine,  function or program are named and  displayed.
Pressing RETURN curtails display of an array;  any other key terminates  all
display and returns to the PROBE command prompt. 

examples
          DISPLAY ReadItem:
          D SORT:a(176)


          ECHO

The  subsequent console dialogue with PROBE will also be copied to the  disk
file PROBE.LOG.  If logging is already on, it will be switched off.
 
example:

         ECHO
         E







          GO [break-watch-specifier]
          break-watch-specifier = 
                     [qualifier] <[lines]|variable [op value]>

Execution  of the subject program is resumed,  with current Watch and  Break
conditions active.  A break-watch specifier may be given, in which case this
is added to the list of active break conditions,  but will not remain active 
when execution of the program is next suspended.

example
     
          GO
          g 20
          G ilim>0


          HELP [ Assign | Break   | Calls   | Display |
                 Echo   | Go      | Help    | Key     |
                 List   | Output  | Profile | Quit    |
                 Route  | Step    | Trace   | View    |
                 Watch  | X ]

Information  regarding the specified command is given,  or if no command  is
specified, a general description of Probe facilities is displayed.  Commands
about  which  information  is  requested may be  abbreviated  when  used  as
parameters to HELP, in the same way as when using the commands themselves. 
                                                                                                                                    
examples
          HELP
          H W
          HELP BREAK

          KEY

Probe's  facility  to  interrupt  a running program by  striking  a  key  is
switched on or off (reversing its current setting).   A message is displayed
confirming  its new setting.   The command is only useful when  the  program
under  test  itself  tests the keyboard.   Unless Probe's  use  of  keyboard
interrupts is disabled, it is not possible to exercise the keyboard checking
in the program under test.

example

          K




          LIST [ qualifier ] [ lines ]

The  specified source lines are displayed.  If no source file  is  specified
then  the  source file for the current execution point is  assumed.   If  no
source line is specified,  then lines in the vicinity of the current program
execution point are displayed.  Subsequent list commands without  parameters
will  display  lines following on from the preceding list command.   If  the
qualifier gives a subroutine name,  it must be currently in execution.   The
source file containing the subroutine will be listed.

example

          L
          L moveto:15..30


          OUTPUT (to alternate screens)

The  OUTPUT  command  has  no  parameters,  and is used to enable or disable
screen switching between Probe output  and  user  output.  If switching  was
disabled  (the  default  on  startup) then it will be enabled,  and the user
program's  display area will be cleared to a GEM type background.  If it was
enabled it will be turned off, and user and probe output will be interleaved
on the same  screen  area.  This option is particularly useful for debugging
GEM type applications, but also may be useful for debugging text output.

   example
         O




          PROFILE

The profiling option is switched on/off.  A message displays the new setting
(ON  or OFF).  A 'profile'  of a program shows how frequently each  line  is
executed.   When profiling is selected, execution counts of all source lines
are maintained.  When a LIST command is subsequently executed, the execution
counts  are displayed on screen in addition to the line numbers.   The  ECHO
command can be used to retain a copy of the counts for analysis or printing.
                                                                                                                                    
example
          PROFILE





          QUIT

Object  program and Probe execution are terminated.   This command  must  be
entered  in full in order to take effect;  abbreviations will  be  rejected.
Only the ECHO file (if any) will be closed.   Any files of the program under
test will not be closed.   Information still buffered in the runtime library
will not have been written to disc.

example
          QUIT






          ROUTE

The  most recently executed few source lines are displayed.   There  are  no
parameters.   The lines are displayed in the order in which their  execution
started.   Lines  containing a subroutine or function call may still  be  in
course of execution if the function has not yet returned.   These lines will
also appear in a CALLS command display.

example
          ROUTE






          STEP [ line-count ]
          
The object program's execution is resumed for the specified number of lines. 
If no line-count is specified,  a single line is executed.   Note that  only
lines on which an executable statement starts are counted.  These are marked
in the source listing by an asterisk following the line number.

          S 5








          TRACE
          
The object program's execution is resumed for the next  source  line.   If a 
debugging  program  such as SID is active,  it is first entered at the start
of the object code for the current source line.  The debugger's single  step
command can then be used to step through the object program instructions. If
the debugger's 'GO' command (or equivalent) is used,  Probe  will  interrupt
the program under test at the end of the current source line.  In  order  to
use this facility,  use a Probe command such as X SID TEST.PRG, then use the
G command to re-enter Probe immediately  prior  to  execution  of  the first
source line.  Note that if this command is used when no debugger is present,
it may cause a crash (9 Atari bombs).
 
   example
         T

          VIEW

If the screen switching to separate Probe output from  program  output is in
use  (see the OUTPUT  command),  the VIEW command will allow the contents of
the test program's screen to be inspected. Press any key to return to Probe.

   example

         V







          WATCH [break-watch-specifier] | - | ?
          break-watch-specifier = 
                     [qualifier] <[lines]|variable [op value])>

When the given condition holds during program execution,  source line,  (and
variable value) are displayed.  When the source text is not available,  only
the  source  file  name,  subroutine name and  line  number  are  displayed. 
Subroutine  and file name are suppressed if they have not changed since  the
previous displayed values.   Several watch and break requests can be  active
at  the  same time.   In this case,  the overall display  will  reflect  the
combination of all the current requests.

examples
          W     
          W dosort:120..150
          W a(I)<=34.2E9
          X

The  argument  of the X command is the name of a program to be executed.  If
this is a Prospero program compiled with the N option,  (or  itself executes
such a program) and no other program is being tested, then execution will be
halted and control passed to Probe immediately before execution of the first
source statement. However it is also possible (memory permitting) to execute
any other .PRG file, such as the Workbench or even another copy of Probe. It
is not possible for one copy of Probe to be used to debug two user  programs
at once. Any text supplied after the filename is passed to the  program as a
parameter suitable for use by the GETCOM subroutine.

   examples
         X F-BENCH
         X PROBE ANOTHER
         x sid myprog.prg






