========================================================================== ********* ********* * * * * * * * * * * * * ********* ********* ********* * * * * * * ********* * * Version 1.0 by Federico Giannici ========================================================================== This program is a SPY of the main AmigaDOS and EXEC functions. SPY is a Public Domain program and you can copy and utilize it freely. You don't have to pay to me anything (every monetary contributions, however, will be well accepted) but you can't modify, sell or incorporate it in any commercial program without my written authorization. Again, I am not responsible for any damage, direct or indirect, derived by the utilization of SPY. WHAT SPY DOES --------------- You can choose which functions (among those implemented) to keep under observation. After that, every single call to those functions will be reported on the screen. Names, parameters and the results of the functions are displayed. Names are shown in a different ink color. Besides, SPY often shows, between parenthesis, the name of the structure whose address had been passed as a parameter, for example: Devices, Library, Resources, etc.. If the structure is a Lock, SPY shows (again between parenthesis) the name of the file or of the directory (ending with a "/" sign) completed with all the path corresponding to the lock. When SPY has to show a FileHandle it will display the name of the file used in the "Open()" function corresponding to that FileHandle. I have not found a documented way to go back to the filename corresponding to a FileHandle. As a partial solution, every time SPY intercepts a call to the "Open()" function, it memorize the filename corresponding to that FileHandle. Then, when SPY intercepts a call to the "Close()" function it deletes the filename corresponding to that FileHandle. Therefore SPY cannot show neither the name of the files opened before it was loaded, neither the name of the file opened when the "Open()" function was not under observation. As far as concern the FileHandles obtained with the "Input()" and "Output()" functions, SPY will show respectively the names "" and "". Obviously, if the "Close()" function is not intercepted, the buffer of the filenames will grow with no end, and SPY could show incorrect filenames. Therefore you can clear the buffer with the command "Clear FileHandle mem" in the first menu. Obviously it is a makeshift solution. I'll thank everybody suggest me a better solution. In the "Read()" and "Write()" functions, SPY display also the content of the buffer (readed or written) as an ASCII string. LOADING --------- SPY can be loaded either from CLI or Workbench. From CLI, you can specify, as a parameter, the name of the configuration file, otherwise SPY will search the default configuration file "spy.config". SPY searchs the configuration file, first in the current directory, then, if he didn't found it, in the "S:" directory. If SPY couldn't find the configuration file anywhere, it will use the default configuration: interception activated, printer de-activated, all the Preferences options activated and all the functions, but "FindName()", selected. THE MENUS ----------- GENERAL ACTIVATED When selected (selection symbol on the left), it makes SPY active. PRINTER When selected, everything shown on the screen is sent to the printer too. IT IS VERY IMPORTANT that the printer is really ON! Otherwise, SPY could stall (stop forever) or, if the "Printer Troubles - Check Printer and Cables" message appears, all the system could crash (if SPY is currently trapping some particular functions). FUNCTIONS You can also select this command, in an easier way, with a double click in the main window of SPY. It brings up the window for the selection of the functions intercepted by SPY. The active functions are those marked with the selection symbol on the left side. Five commands are selectable on the bottom side of this window: OK: Accepts the list of the activated functions actually displayed on the screen. ALL: Selects all the functions. There is a single exception: "FindName()", because it usually generates a large number of calls (for example, every time a menu is used), so you have to select it expressly by clicking above it. NONE: De-selects the functions all them all. RESTORE: Restores the list of the selected functions as they were the last time. CANCEL: Closes the window without modifying the list of the selected functions (the last one will be used). SAVE CONFIGURATION You will be asked for the name of the configuration file. The configuration includes all the menu options, the list of selected functions as well as the position and dimension of the window. LOAD CONFIGURATION You will be asked for the name of the configuration file to be used. CLEAR FILEHANDLE MEM It deletes the buffer of the FileHandles names (see "WHAT SPY DOES"). INFORMATIONS It shows a sub-menu of informations about both the program and the programmer (me!). QUIT It quits SPY. You can obtain it also with the close-window gadget on the main SPY window. Before quitting, SPY checks that no other program is executing any of his functions. PREFERENCES These options define SPY's behaviour when it intercepts a call to any of the currently selected functions. DESCRIPTION If set on "Verbose", SPY will display all the parameters and the return value of the function. If set on "Brief", SPY will display, in a single line, only function name and the main parameter. ACTIVATION If set on "Failed only", SPY will display only the failed function calls. Otherwise, It will display all the intercepted function calls. GO ON If set on "Wait for GO", SPY will wait until you give your permission to go ahead with the next intercepted function. The gadget on the bottom of the main window will start to flash and you will be able to give the OK either by clicking on the gedget itself or by pressing any key (in this case the main SPY window has to be the active one). If set on "Immediately", SPY will not wait any permission and will proceed in its work. SCREENFLASH If set on "Activated", and if SPY is "waiting for a GO" by the user (see last section), all the screens will flash every two seconds (approximately), in order to remember to the user that SPY is waiting for him (meanwhile the calling program will be blocked). MISCELLANEA ------------- The "AllocMem()" function is notified only when an error occurr (insufficient memory). This is because this function is called too often by the system. In two cases SPY cannot wait for a GO (otherwise the system will crash): I) When a MsgPort named "IDCMP" is added to the system by the "AddPort()" function (a window is opened). II) When the input.device makes a call to the "FindName()" function. In order to avoid stack overflow problems, SPY shows only the calls made by Tasks with a stack of 1600 bytes at least. This, of course, does not eliminate the overflow problems completely, because SPY don't know how much full is the stack. If a crash occurs, try to eliminate some function traps. The choise of 1600 bytes isn't a casual one. In fact, the initial CLI has a 1600 bytes stack (at least in the Operating System V1.2 and V1.3), even if when the CLI has to execute a command its stack became (!?) of 4000 bytes. Anyone of you can tell me why? Some other strange behavior of the CLI (discovered with SPY): When the CLI has to execute a command, it opens the dos.library (probably to get the DOSBase address), but it don't close it by the "CloseLibrary()" function. However the counter of openings of the library is decremented, probably by the CLI itself. The calls made by the CLI commands (Dir, CD, Delete, etc.) aren't intercepted. I think this is due to the fact that this commands use an own internal library that call directly the system functions, without passing through the jump-table of the libraries. FINAL NOTE ------------ For any suggestion, criticism, bug reporting, contribution and, most of all, praises you can contact me at the address shown in the Informations sub-menu of SPY (and at the end of these instructions). You can also contact me on the Italian BBS Mc-Link (06-4180440), my code is MC4080. Good investigations with SPY. Federico Giannici Viale Francia 4 90146 Palermo Italy