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