home *** CD-ROM | disk | FTP | other *** search
/ Vectronix 2 / VECTRONIX2.iso / FILES_01 / P_FOTRAN.LZH / PROBE.HLP < prev    next >
Text File  |  1987-12-31  |  13KB  |  365 lines
  1. P
  2. *
  3. *
  4. ASSIGN
  5. BREAK
  6. CALLS
  7. DISPLAY
  8. ECHO
  9. GO
  10. HELP
  11. KEY
  12. LIST
  13. OUTPUT
  14. PROFILE
  15. QUIT
  16. ROUTE
  17. STEP
  18. TRACE
  19. VIEW
  20. WATCH
  21. XECUTE
  22. .
  23. PROBE checks for breakpoints,  tracing,  watching, or striking of any key at
  24. the  start of each line of the source program on which a  statement  starts. 
  25. When  execution of the program is interrupted,  the following  commands  are
  26. available:
  27.  
  28. A(ssign) new value to variable     O(utput) to alternate screen
  29. B(reak) into program at event      P(rofile) on/off
  30. C(alls) to reach current point     QUIT to operating system
  31. D(isplay) value of variable(s)     R(oute) taken to current point
  32. E(cho) screen output to file       S(tep) execution through source
  33. G(o) on with execution             T(race) execution in object code
  34. H(elp) explain command use         V(iew) alternate output screen
  35. K(ey) interruption on/off          W(atch) variable or source lines
  36. L(ist) source lines                X (eXecute) program
  37.  
  38.      Further help is available on each of these.
  39. A syntax-description of each command is given. Alternatives are separated by
  40. a vertical bar "|",  optional parts are shown in brackets "[]"  or where the
  41. contents can be repeated,  by braces "{}".  Grouping is shown by parentheses
  42. "<>"
  43. Important parts of the syntax are:
  44.     character-string    characters between apostrophes ('String')
  45.     integer-constant    a constant with an integer value (123, -1, 'c')
  46.     qualifier           naming a source file ('LOGFILE':), subroutine
  47.                         or function (XSUB:, IFUNC:)
  48.     variable            a variable of the program under test (i, ia(1, j))
  49.     value               number, boolean, enumerated, char, set or string
  50.                         constant, or variable value (12, 17.3E2, true, v)
  51.     break-watch-specifier  source line or range, variable, variable with
  52.                         condition, or nothing at all.
  53.  
  54. These are defined on the next screen.
  55. Definitions of syntactic terms used in the commands:
  56.     break-watch-specifier =
  57.         [ qualifier ] < [lines] | variable [op value]>
  58.     qualifier =  file-name : | routine-name :
  59.     value = variable | constant
  60.     lines = integer-constant [ .. integer-constant]
  61.     line-count = integer-constant
  62.     constant = integer-constant | real-constant | double-precision-constant |
  63.                complex-constant | character-string
  64.     variable = identifier | identifier ( value { , value } )
  65.     op = = | <> | < | >= | > | <=
  66.     routine-name = identifier
  67.     file-name = character-string
  68.     character-string = ' { character } '
  69. The form of identifiers, and the various number constants is as in Fortran.
  70.  
  71.           ASSIGN [qualifier] variable = value
  72.  
  73. The  value  of  the given variable is changed as  specified.   The  variable
  74. identified  is that which would be referred to by the name when used at  the
  75. current (or given) point in the source program.  Array variables may only be
  76. altered element by element.
  77.  
  78.  
  79. examples
  80.  
  81.           A count=3
  82.           A size(I, 3)=25.3
  83.  
  84.                                                       
  85.  
  86.  
  87.           BREAK [break-watch-specifier] | - | ?
  88.           break-watch-specifier = 
  89.                      [qualifier] <[lines]|variable [op value]>
  90.  
  91. The  executing  program will be interrupted each time  the  specified  event
  92. occurs.  The  qualifier  identifies a source  file  or  subroutine/function. 
  93. Execution  is  interrupted at given source line(s),  on changes in  a  given
  94. variable,  or on a variable being greater, equal or less than a given value. 
  95. The  break  is  added  to existing breaks,  any  one  of  which  will  cause
  96. interruption  of  execution.  "B -"  removes, and "B ?"  lists  all  current
  97. breaks.   With "B"  alone,  a break occurs on all source lines.   Specifying
  98. just  a  start  line  number gives a single line.   Where  a  subroutine  is
  99. specified, execution of any source line in the subroutine causes a break.
  100. examples
  101.           B ReadItem:
  102.           B size<=0
  103.           CALLS
  104.  
  105. The  nest  of  active subroutine or function calls leading  to  the  current
  106. execution point is displayed, starting with the currently active source line
  107. and working outwards to the main program.   The names of the active routines
  108. are  displayed.   Their variables can be inspected by using these  names  as
  109. qualifiers to the display command.
  110.  
  111. example
  112.           C
  113.  
  114.  
  115.  
  116.  
  117.  
  118.  
  119.           DISPLAY [ qualifier ] [ variable ]
  120.  
  121. If  a  variable is named,  the current value of the variable  is  displayed. 
  122. Whole arrays may be displayed in this way.  Where only a qualifier is given,
  123. parameters and local variables of the routine are named and displayed. Where
  124. only a source file is given,  variables of the main program in that file are
  125. displayed.   Where no parameter is given,  parameters and variables  of  the
  126. currently  active subroutine,  function or program are named and  displayed.
  127. Pressing RETURN curtails display of an array;  any other key terminates  all
  128. display and returns to the PROBE command prompt. 
  129.  
  130. examples
  131.           DISPLAY ReadItem:
  132.           D SORT:a(176)
  133.  
  134.  
  135.           ECHO
  136.  
  137. The  subsequent console dialogue with PROBE will also be copied to the  disk
  138. file PROBE.LOG.  If logging is already on, it will be switched off.
  139.  
  140. example:
  141.  
  142.          ECHO
  143.          E
  144.  
  145.  
  146.  
  147.  
  148.  
  149.  
  150.  
  151.           GO [break-watch-specifier]
  152.           break-watch-specifier = 
  153.                      [qualifier] <[lines]|variable [op value]>
  154.  
  155. Execution  of the subject program is resumed,  with current Watch and  Break
  156. conditions active.  A break-watch specifier may be given, in which case this
  157. is added to the list of active break conditions,  but will not remain active 
  158. when execution of the program is next suspended.
  159.  
  160. example
  161.      
  162.           GO
  163.           g 20
  164.           G ilim>0
  165.  
  166.  
  167.           HELP [ Assign | Break   | Calls   | Display |
  168.                  Echo   | Go      | Help    | Key     |
  169.                  List   | Output  | Profile | Quit    |
  170.                  Route  | Step    | Trace   | View    |
  171.                  Watch  | X ]
  172.  
  173. Information  regarding the specified command is given,  or if no command  is
  174. specified, a general description of Probe facilities is displayed.  Commands
  175. about  which  information  is  requested may be  abbreviated  when  used  as
  176. parameters to HELP, in the same way as when using the commands themselves. 
  177.                                                                                                                                     
  178. examples
  179.           HELP
  180.           H W
  181.           HELP BREAK
  182.  
  183.           KEY
  184.  
  185. Probe's  facility  to  interrupt  a running program by  striking  a  key  is
  186. switched on or off (reversing its current setting).   A message is displayed
  187. confirming  its new setting.   The command is only useful when  the  program
  188. under  test  itself  tests the keyboard.   Unless Probe's  use  of  keyboard
  189. interrupts is disabled, it is not possible to exercise the keyboard checking
  190. in the program under test.
  191.  
  192. example
  193.  
  194.           K
  195.  
  196.  
  197.  
  198.  
  199.           LIST [ qualifier ] [ lines ]
  200.  
  201. The  specified source lines are displayed.  If no source file  is  specified
  202. then  the  source file for the current execution point is  assumed.   If  no
  203. source line is specified,  then lines in the vicinity of the current program
  204. execution point are displayed.  Subsequent list commands without  parameters
  205. will  display  lines following on from the preceding list command.   If  the
  206. qualifier gives a subroutine name,  it must be currently in execution.   The
  207. source file containing the subroutine will be listed.
  208.  
  209. example
  210.  
  211.           L
  212.           L moveto:15..30
  213.  
  214.  
  215.           OUTPUT (to alternate screens)
  216.  
  217. The  OUTPUT  command  has  no  parameters,  and is used to enable or disable
  218. screen switching between Probe output  and  user  output.  If switching  was
  219. disabled  (the  default  on  startup) then it will be enabled,  and the user
  220. program's  display area will be cleared to a GEM type background.  If it was
  221. enabled it will be turned off, and user and probe output will be interleaved
  222. on the same  screen  area.  This option is particularly useful for debugging
  223. GEM type applications, but also may be useful for debugging text output.
  224.  
  225.    example
  226.          O
  227.  
  228.  
  229.  
  230.  
  231.           PROFILE
  232.  
  233. The profiling option is switched on/off.  A message displays the new setting
  234. (ON  or OFF).  A 'profile'  of a program shows how frequently each  line  is
  235. executed.   When profiling is selected, execution counts of all source lines
  236. are maintained.  When a LIST command is subsequently executed, the execution
  237. counts  are displayed on screen in addition to the line numbers.   The  ECHO
  238. command can be used to retain a copy of the counts for analysis or printing.
  239.                                                                                                                                     
  240. example
  241.           PROFILE
  242.  
  243.  
  244.  
  245.  
  246.  
  247.           QUIT
  248.  
  249. Object  program and Probe execution are terminated.   This command  must  be
  250. entered  in full in order to take effect;  abbreviations will  be  rejected.
  251. Only the ECHO file (if any) will be closed.   Any files of the program under
  252. test will not be closed.   Information still buffered in the runtime library
  253. will not have been written to disc.
  254.  
  255. example
  256.           QUIT
  257.  
  258.  
  259.  
  260.  
  261.  
  262.  
  263.           ROUTE
  264.  
  265. The  most recently executed few source lines are displayed.   There  are  no
  266. parameters.   The lines are displayed in the order in which their  execution
  267. started.   Lines  containing a subroutine or function call may still  be  in
  268. course of execution if the function has not yet returned.   These lines will
  269. also appear in a CALLS command display.
  270.  
  271. example
  272.           ROUTE
  273.  
  274.  
  275.  
  276.  
  277.  
  278.  
  279.           STEP [ line-count ]
  280.           
  281. The object program's execution is resumed for the specified number of lines. 
  282. If no line-count is specified,  a single line is executed.   Note that  only
  283. lines on which an executable statement starts are counted.  These are marked
  284. in the source listing by an asterisk following the line number.
  285.  
  286.           S 5
  287.  
  288.  
  289.  
  290.  
  291.  
  292.  
  293.  
  294.  
  295.           TRACE
  296.           
  297. The object program's execution is resumed for the next  source  line.   If a 
  298. debugging  program  such as SID is active,  it is first entered at the start
  299. of the object code for the current source line.  The debugger's single  step
  300. command can then be used to step through the object program instructions. If
  301. the debugger's 'GO' command (or equivalent) is used,  Probe  will  interrupt
  302. the program under test at the end of the current source line.  In  order  to
  303. use this facility,  use a Probe command such as X SID TEST.PRG, then use the
  304. G command to re-enter Probe immediately  prior  to  execution  of  the first
  305. source line.  Note that if this command is used when no debugger is present,
  306. it may cause a crash (9 Atari bombs).
  307.  
  308.    example
  309.          T
  310.  
  311.           VIEW
  312.  
  313. If the screen switching to separate Probe output from  program  output is in
  314. use  (see the OUTPUT  command),  the VIEW command will allow the contents of
  315. the test program's screen to be inspected. Press any key to return to Probe.
  316.  
  317.    example
  318.  
  319.          V
  320.  
  321.  
  322.  
  323.  
  324.  
  325.  
  326.  
  327.           WATCH [break-watch-specifier] | - | ?
  328.           break-watch-specifier = 
  329.                      [qualifier] <[lines]|variable [op value])>
  330.  
  331. When the given condition holds during program execution,  source line,  (and
  332. variable value) are displayed.  When the source text is not available,  only
  333. the  source  file  name,  subroutine name and  line  number  are  displayed. 
  334. Subroutine  and file name are suppressed if they have not changed since  the
  335. previous displayed values.   Several watch and break requests can be  active
  336. at  the  same time.   In this case,  the overall display  will  reflect  the
  337. combination of all the current requests.
  338.  
  339. examples
  340.           W     
  341.           W dosort:120..150
  342.           W a(I)<=34.2E9
  343.           X
  344.  
  345. The  argument  of the X command is the name of a program to be executed.  If
  346. this is a Prospero program compiled with the N option,  (or  itself executes
  347. such a program) and no other program is being tested, then execution will be
  348. halted and control passed to Probe immediately before execution of the first
  349. source statement. However it is also possible (memory permitting) to execute
  350. any other .PRG file, such as the Workbench or even another copy of Probe. It
  351. is not possible for one copy of Probe to be used to debug two user  programs
  352. at once. Any text supplied after the filename is passed to the  program as a
  353. parameter suitable for use by the GETCOM subroutine.
  354.  
  355.    examples
  356.          X F-BENCH
  357.          X PROBE ANOTHER
  358.          x sid myprog.prg
  359.  
  360.  
  361.  
  362.  
  363.  
  364.  
  365.