home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 3 / PDCD_3.iso / utilities / utilst / tracker / !Tracker / ReadMe < prev   
Text File  |  1995-05-21  |  6KB  |  185 lines
  1. Tracker
  2. =======
  3.  
  4. Tracker is a simple little utility which I wrote ages ago. At the time it
  5. was hard to justify the effort in terms of the project I was working on, but
  6. it's paid back many times over now.
  7.  
  8. It allows applications, modules and any other code which can either write to
  9. a file or issue an SWI to write textual information to a trace window which
  10. appears, and updates, on the desktop at the next null event.
  11.  
  12. Shortcomings
  13. ============
  14.  
  15. A lot if it looks rather naive to me now. There is at least one known bug
  16. which means it can't save output directly to an editor. I had a quick look
  17. at it prior to posting it here, but it wasn't immediately obvious. Perhaps
  18. if anyone fixes it they'd let me know. Also it currently uses SWI chunk
  19. CF000 which is not allocated by Acorn. Feel free to change it. I know I
  20. should register it but I've never got around to it.
  21.  
  22. Interface
  23. =========
  24.          
  25. SWI Tracker_Open -- open a new tracker window
  26.  
  27. R0  ==> Title for this window (ASCIIZ)
  28. R1  ==> Width of window in characters
  29. R2  ==> Height of window in characters
  30. R3  ==> Flags: bit 0 means treat LF as CRLF which is useful for C
  31.  
  32. On exit
  33.  
  34. R0  ==> Handle of new window
  35.  
  36. SWI Tracker_Close -- close a tracker window
  37.  
  38. R0  ==> Handle to close
  39.  
  40. NOTE: When a Tracker window is closed it doesn't disappear from the screen.
  41. What this call does is mark the window 'OK to close' which means that if you
  42. click on it's close icon it won't complain. To reflect this change of state
  43. the text in it goes grey.
  44.  
  45. SWI Tracker_SetPos -- set cursor position
  46.  
  47. R0  ==> Handle of window
  48. R1  ==> New cursor X position
  49. R2  ==> New cursor Y position
  50.  
  51. Allow the cursor to be repositioned in a Tracker window. 
  52.  
  53. SWI Tracker_WriteS -- write a string to a Tracker window
  54.  
  55. R0  ==> Handle of window
  56. R1  ==> String
  57.  
  58. The following control codes are handled 08, 09, 0A, 0B, 0C, 0D, 7F. All
  59. others are ignored.  Top bit set characters are processed normally.
  60.  
  61. SWI Tracker_CLS -- clear a tracker window
  62.  
  63. R0  ==> Handle of window
  64.  
  65. SWI Tracker_Simple -- simple output
  66.  
  67. R0  ==> String to output
  68.  
  69. A simpler interface to the Tracker module for code which can't be bothered
  70. to keep track of window handles. The first time this call is made a new
  71. Tracker window measuring 80x1000 characters is opened and the given string
  72. is written to it. Subsequent calls write the string at R0 to the same
  73. window. If you close it, the next call to Tracker_Simple opens a new one.
  74.  
  75. Filing system
  76. =============
  77.  
  78. A file can be opened on TrackFS: like this
  79.  
  80. track% = OPENOUT "TrackFS:Spog"
  81.  
  82. Any data written to this file will appear in the window. Optionally the file
  83. name can be suffixed with the size of the window, as in
  84.  
  85. track% = OPENOUT "TrackFS:Spog_80_100"
  86.  
  87. The file name is the bit up to the first '_' for the purposes of name
  88. matching.
  89.  
  90. Assembler
  91. =========
  92.  
  93. I write quite a lot of modules, so I produced a debugging library which I
  94. can link modules with which gives them the benefit of easy access to
  95. Tracker. The code is included in AsmLib.
  96.  
  97. To use it you need to
  98.  
  99.           GBLL  Debug
  100. Debug     SETL  {TRUE}      ; or {FALSE}
  101.  
  102.           GET   Somepath:s.DebugHdr
  103.  
  104. and in your module initialisation you can do something like
  105.  
  106.           DBSET           DebugOn :OR: UseTracker  ; UseVDU, UseBeeb and UseRam are
  107.                                                    ; also allowed
  108.           DBF             "\fStarting\n\n"
  109.  
  110. and link with
  111.  
  112.           Somepath:o.debuglib
  113.  
  114. If Debug is {FALSE} no extra code will be generated or linked.
  115.  
  116. Within your code you can now do things like
  117.  
  118.           DBF   "r0 is %0w and r9 is %9w\n"
  119.  
  120. which would display in the Tracker window
  121.  
  122.           r0 is 12345678 and r9 is 87654321
  123.  
  124. DBSET Macro
  125.  
  126. The argument to DBSET is a bitfield which indicates whether debugging is
  127. enabled, and if it is enabled, where the output should go to. UseTracker
  128. specifies that output should be sent to Tracker. UseVDU states that output
  129. should go to the screen. You shouldn't use this option for interrupt code.
  130. UseBeeb sends output to a user port if you have one fitted. The reason why
  131. it's called UseBeeb is because when I wrote it I accessed the debug output
  132. by plugging an old BBC Micro into the other end. UseRam stores debug output
  133. in a RAM board I wirewrapped ages ago. The advantage is that debug output
  134. stored on the RAM board will survive over a hard reset. Unless you happen to
  135. have an identical board (unlikely) you can't use this option I'm afraid.
  136.  
  137. DBF Macro
  138.  
  139. DBF outputs a formatted string to the current debug destinations. Within the
  140. string, a '%' specifies a conversion and '\' introduces and escape.
  141.  
  142. The general format of conversions is
  143.  
  144.   %<register>[<radixspecifier>]<conversion>
  145.  
  146. where register can be '0' - 'F' or 'R0' - 'R15' or SP, LR or PC. Case is
  147. insignificant.
  148.  
  149. The radix specifier is
  150.  
  151.   % for binary,
  152.   # for decimal
  153.  
  154. The default is hex.
  155.  
  156. The conversion character specifies how the data is to be output as follows
  157.  
  158.   s -- string (null terminated I think; check the source)
  159.   w -- word (i.e. 32 bits)
  160.   h -- half word
  161.   b -- byte
  162.   c -- character
  163.  
  164. In addition,
  165.  
  166.   %z and %t
  167.  
  168. insert the value of a centisecond clock into the output. %z also zeros the
  169. clock so that successive %zs output the time difference since the last %z,
  170. and successive %ts output the total time since the last %z.
  171.  
  172. A DBF can be made conditional as in
  173.  
  174.    DBF "It's not equal\n", NE
  175.  
  176. Conclusion
  177. ==========
  178.  
  179. As I said, it's a little bit crude but it's performed well for me over the
  180. years.
  181.  
  182. If you run into any problems or you improve it at all let me know.
  183.  
  184. Andy Armstrong, andy@armswalk.demon.co.uk
  185.