home *** CD-ROM | disk | FTP | other *** search
/ Club Amiga de Montreal - CAM / CAM_CD_1.iso / files / 439.lha / Spy_v1.0 / Instructions < prev    next >
Encoding:
Text File  |  1990-11-13  |  9.6 KB  |  277 lines
  1. ==========================================================================
  2.  
  3.  
  4.                     *********    *********    *       *
  5.                     *            *       *    *       *
  6.                     *            *       *    *       *
  7.                     *********    *********    *********
  8.                             *    *                *
  9.                             *    *                *
  10.                     *********    *                *
  11.  
  12.  
  13.  
  14.                                 Version 1.0
  15.  
  16.  
  17.                            by Federico Giannici
  18.  
  19.  
  20. ==========================================================================
  21.  
  22.  
  23.  
  24. This program is a SPY of the main AmigaDOS and EXEC functions.
  25.  
  26.  
  27. SPY is a Public Domain program and you can copy and utilize it freely. You
  28. don't have to pay to me anything (every monetary contributions, however,
  29. will be well accepted) but you can't modify, sell or incorporate it in any
  30. commercial program without my written authorization. Again, I am not
  31. responsible for any damage, direct or indirect, derived by the utilization
  32. of SPY.
  33.  
  34.  
  35.  
  36.  
  37.  
  38.                                WHAT SPY DOES
  39.                               ---------------
  40.  
  41. You  can choose  which functions  (among those  implemented) to  keep under
  42. observation.  After  that,  every  single  call  to those functions will be
  43. reported on the screen.
  44.  
  45. Names, parameters and the results of the functions are displayed.
  46.  
  47. Names are shown in a different ink color.
  48.  
  49. Besides,  SPY often shows,  between parenthesis, the  name of the structure
  50. whose  address  had  been  passed  as  a  parameter,  for example: Devices,
  51. Library,  Resources, etc..  If the  structure is  a Lock,  SPY shows (again
  52. between parenthesis) the name of the file or of the directory (ending  with
  53. a "/" sign) completed with all the path corresponding to the lock.
  54.  
  55. When SPY has to show a FileHandle it will display the name of the file used
  56. in the "Open()" function corresponding to that FileHandle. I have not found
  57. a documented way to go back to the filename corresponding to a FileHandle.
  58. As  a partial solution,  every time SPY  intercepts a call  to the "Open()"
  59. function, it memorize the filename corresponding to that FileHandle.
  60. Then, when SPY intercepts a call  to the "Close()" function it deletes  the
  61. filename corresponding to that FileHandle.
  62. Therefore  SPY cannot show neither  the name of the  files opened before it
  63. was loaded, neither the name of the file opened when the "Open()"  function
  64. was not under observation.
  65. As  far  as  concern  the  FileHandles  obtained  with  the  "Input()"  and
  66. "Output()" functions, SPY  will show respectively  the names "<Input>"  and
  67. "<Output>".
  68. Obviously,  if the "Close()" function is not intercepted, the buffer of the
  69. filenames will grow  with no end,  and SPY could  show incorrect filenames.
  70. Therefore  you can clear the buffer with the command "Clear FileHandle mem"
  71. in the first menu.
  72. Obviously it  is a  makeshift solution.  I'll thank  everybody suggest me a
  73. better solution.
  74.  
  75. In  the "Read()" and  "Write()" functions, SPY  display also the content of
  76. the buffer (readed or written) as an ASCII string.
  77.  
  78.  
  79.  
  80.  
  81.  
  82.                                   LOADING
  83.                                  ---------
  84.  
  85.  
  86. SPY can be loaded either from CLI or Workbench.
  87. From CLI, you can  specify, as a parameter,  the name of the  configuration
  88. file,   otherwise   SPY   will   search   the   default  configuration file
  89. "spy.config".
  90. SPY searchs the configuration file,  first in the current directory,  then,
  91. if he didn't found it, in the "S:" directory.
  92. If  SPY  couldn't  find  the  configuration  file anywhere, it will use the
  93. default configuration:  interception activated,  printer de-activated,  all
  94. the  Preferences options activated and all the functions, but "FindName()",
  95. selected.
  96.  
  97.  
  98.  
  99.  
  100.  
  101.                                  THE MENUS
  102.                                 -----------
  103.  
  104.  
  105.                                   GENERAL
  106.  
  107.  
  108.  
  109. ACTIVATED
  110. When selected (selection symbol on the left), it  makes SPY active.
  111.  
  112.  
  113. PRINTER
  114. When selected, everything shown on the screen is sent to the printer too.
  115. IT IS VERY IMPORTANT  that the printer is  really ON! Otherwise, SPY  could
  116. stall  (stop  forever)  or,  if  the  "Printer Troubles - Check Printer and
  117. Cables" message appears,  all the system  could crash (if  SPY is currently
  118. trapping some particular functions).
  119.  
  120.  
  121. FUNCTIONS
  122. You  can also select this command, in an easier way, with a double click in
  123. the main window of SPY.
  124. It brings up the window for  the selection of the functions intercepted  by
  125. SPY. The active functions are those marked with the selection symbol on the
  126. left side.
  127. Five commands are selectable on the bottom side of this window:
  128.  
  129.                OK:  Accepts the  list of  the activated  functions actually
  130.                displayed on the screen.
  131.  
  132.                ALL: Selects all the functions. There is a single exception:
  133.                "FindName()", because it usually generates a large number of
  134.                calls (for example, every time a menu is used), so you  have
  135.                to select it expressly by clicking above it.
  136.  
  137.                NONE: De-selects the functions all them all.
  138.  
  139.                RESTORE: Restores the list of the selected functions as they
  140.                were the last time.
  141.  
  142.                CANCEL:  Closes the window without modifying the list of the
  143.                selected functions (the last one will be used).
  144.  
  145.  
  146. SAVE CONFIGURATION
  147. You will be asked for the name of the configuration file.
  148. The  configuration  includes  all  the  menu  options, the list of selected
  149. functions as well as the position and dimension of the window.
  150.  
  151.  
  152. LOAD CONFIGURATION
  153. You will be asked for the name of the configuration file to be used.
  154.  
  155.  
  156. CLEAR FILEHANDLE MEM
  157. It deletes the buffer of the FileHandles names (see "WHAT SPY DOES").
  158.  
  159.  
  160. INFORMATIONS
  161. It  shows  a  sub-menu  of  informations  about  both  the  program and the
  162. programmer (me!).
  163.  
  164.  
  165. QUIT
  166. It quits SPY.
  167. You can obtain it also with the close-window gadget on the main SPY window.
  168. Before quitting, SPY checks that no  other program is executing any of  his
  169. functions.
  170.  
  171.  
  172.  
  173.  
  174.                                 PREFERENCES
  175.  
  176. These  options define SPY's behaviour  when it intercepts a  call to any of
  177. the currently selected functions.
  178.  
  179.  
  180. DESCRIPTION
  181. If set on  "Verbose", SPY will  display all the  parameters and the  return
  182. value of the function.
  183. If  set on "Brief", SPY will display,  in a single line, only function name
  184. and the main parameter.
  185.  
  186.  
  187. ACTIVATION
  188. If set on "Failed only", SPY will display only the failed function calls.
  189. Otherwise, It will display all the intercepted function calls.
  190.  
  191.  
  192. GO ON
  193. If set on "Wait for GO", SPY will wait until you give your permission to go
  194. ahead with the next intercepted function.
  195. The gadget on  the bottom of  the main window  will start to  flash and you
  196. will  be able to give the OK either  by clicking on the gedget itself or by
  197. pressing any key  (in this case  the main SPY  window has to  be the active
  198. one).
  199. If  set on "Immediately", SPY will not wait any permission and will proceed
  200. in its work.
  201.  
  202.  
  203. SCREENFLASH
  204. If set on "Activated", and  if SPY is "waiting for  a GO" by the user  (see
  205. last   section),   all   the   screens   will   flash   every   two seconds
  206. (approximately), in order to remember to  the user that SPY is waiting  for
  207. him (meanwhile the calling program will be blocked).
  208.  
  209.  
  210.  
  211.  
  212.  
  213.                                 MISCELLANEA
  214.                                -------------
  215.  
  216.  
  217. The   "AllocMem()"  function  is   notified  only  when   an  error  occurr
  218. (insufficient memory). This is because this function is called too often by
  219. the system.
  220.  
  221.  
  222. In two cases SPY cannot wait for a GO (otherwise the system will crash):
  223.  
  224.                I) When a  MsgPort named "IDCMP"  is added to  the system by
  225.                the "AddPort()" function (a window is opened).
  226.  
  227.                II)  When the input.device makes  a call to the "FindName()"
  228.                function.
  229.  
  230.  
  231. In order to avoid stack overflow problems, SPY shows only the calls made by
  232. Tasks with a stack of 1600 bytes at least.
  233. This,  of  course,  does  not  eliminate  the overflow problems completely,
  234. because SPY don't know how much full is the stack.
  235. If a crash occurs, try to eliminate some function traps.
  236. The choise of 1600 bytes isn't a casual one. In fact, the initial CLI has a
  237. 1600  bytes stack (at least in the Operating System V1.2 and V1.3), even if
  238. when the CLI has to execute a command its stack became (!?) of 4000  bytes.
  239. Anyone of you can tell me why?
  240.  
  241. Some other strange behavior of the CLI (discovered with SPY):
  242.  
  243. When  the CLI has to execute a  command, it opens the dos.library (probably
  244. to get the DOSBase address), but it don't close it by the  "CloseLibrary()"
  245. function.  However the counter  of openings of  the library is decremented,
  246. probably by the CLI itself.
  247.  
  248. The  calls  made  by  the  CLI  commands  (Dir,  CD,  Delete,  etc.) aren't
  249. intercepted.  I think this is due to the fact that this commands use an own
  250. internal library that call  directly the system functions,  without passing
  251. through the jump-table of the libraries.
  252.  
  253.  
  254.  
  255.  
  256.  
  257.                                 FINAL NOTE
  258.                                ------------
  259.  
  260.  
  261. For  any suggestion,  criticism, bug  reporting, contribution  and, most of
  262. all, praises you can  contact me at the  address shown in the  Informations
  263. sub-menu  of  SPY  (and  at  the  end  of these instructions). You can also
  264. contact me on the Italian BBS Mc-Link (06-4180440), my code is MC4080.
  265.  
  266. Good investigations with SPY.
  267.  
  268.  
  269.  
  270.  
  271.                                                   Federico Giannici
  272.  
  273.                                                   Viale Francia 4
  274.                                                   90146 Palermo
  275.                                                   Italy
  276.  
  277.