@DATABASE SnoopDos.guide @remark : @remark : $VER: SnoopDos.guide 3.0 (15.9.94) @remark : vi:ts=8 @remark : If you don't have AmigaGuide handy, you should find it fairly easy @remark : to read this file using a normal text reader. All the contents @remark : have been arranged in logical order, and the "heavy" AmigaGuide @remark : stuff is at the end, to avoid it being too distracting. @remark : @remark : I recommend using the utility AG2TXT by Jason R. Hulance to @remark : convert this file into plain ascii, suitable for printing out. @remark : You can find it on Aminet as /pub/aminet/text/hyper/ag2txt.lzh. @remark : @remark :01234567890123456789012345678901234567890123456789012345678901234567 @INDEX Index @MASTER SnoopDos.Guide @NODE MAIN @TITLE "SnoopDos 3.0 Copyright © Eddy Carroll 1994" SnoopDos 3.0 -- System and application monitor Copyright © Eddy Carroll, September 1994. Freely distributable. SnoopDos is a utility that allows you to monitor a variety of system operations carried out by programs on your Amiga. This includes what files a program is trying to open, what fonts, libraries, devices and environment variables it is looking for, and so on. Click on one of the following topics for more detailed information: @{" Quick start " link QuickStart } For people who hate reading documentation @{" Introduction " link Introduction } An overview of how to use SnoopDos @{" What's new in 3.0 " link WhatsNew } For users upgrading from SnoopDos 1.7 @{" Main window " link MainWindow } A guide to the main SnoopDos window @{" Settings window " link SettingsWindow } How to alter SnoopDos's global settings @{" Function window " link FunctionWindow } How to select what functions SnoopDos will monitor @{" Format editor " link FormatEditor } How to customise the layout of the event output @{" Menu options " link Menu_Index } A guide to the main window's menu options @{" Command index " link CommandIndex } A comprehensive guide to all supported commands @{" Workbench startup " link Workbench } How to start SnoopDos from Workbench @{" CLI startup " link CLI } How to start SnoopDos from the CLI @{" ARexx support " link ARexx } How to control SnoopDos using ARexx @{" Settings files " link SettingsFiles } How to make best use of settings files @{" Distribution " link Distribution } Conditions for redistribution of SnoopDos @{" History " link History } Information about past and present versions @{" Credits " link Credits } Bouquets to everyone who helped @{" Author " link Author } How to get in touch with the author Click on the CONTENTS button at the top to return here at any time. @ENDNODE @NODE QuickStart @TITLE "A quick guide to using SnoopDos" A QUICK GUIDE TO USING SNOOPDOS To start SnoopDos, just double-click on the SnoopDos icon from Workbench or type "Run SnoopDos" from the CLI. The default options have been chosen to suit most configurations. You can click on the Functions button to choose what functions are being monitored, or the Setup button to change most other settings. Also check out the menus associated with the main window. Here are the main things you need to know: · Press HELP from inside SnoopDos to access this help file. · The headings displayed in the main window can be dragged left and right using the mouse. Holding down shift moves all items to the right of the current item as well. · Double-click on the header line in the main window to quickly call up the format editor. Use this editor to change the display layout by picking up a field with the left mouse button, dragging it to a new position, and releasing it. · Changes made in the Function, Setup and Format Editor windows always take effect immediately. Click Use to make the change permament, or Undo or Cancel to restore the previous settings. You can have all three configuration windows open simultaneously. · When you select Save Settings, SnoopDos saves the current configuration to ENVARC:SnoopDos.prefs (the SETTINGS tooltype and CLI option allows you to choose a different name). Type this file to see a partial list of supported ARexx commands, tooltypes, and CLI options. If you move this file to S:, SnoopDos will automatically use that copy instead (this saves memory in ENV:). · If you want to monitor file operations performed by programs compiled using Gnu C (i.e those using ixemul.library) then ensure that the Monitor Packets option is turned on in the function window. This may slow down your system a little, however. · The "Buffer->Copy Window to Clip" menu option lets you quickly copy SnoopDos output into your favourite editor using the clipboard. · You can exclude any tasks you don't want to monitor by entering an AmigaDOS pattern like "~(task1|task2|task3)" into the Match Name gadget in the function window. · The Pause button in the main window lets you see what an application is trying to do before it actually does it. Any task that tries to execute a monitored function will be listed with a result of WAIT. Click on the down-arrow scroll gadget or press Space to allow the task to execute the function call. · For DOS device writers, the Packet Debugger option in the function window lets you view all packets sent to a device. You'll probably want to also turn on Monitor ROM Calls to view packets sent internally by dos.library. You should also make the Action and Res. fields wider to ensure you can see all pertinent information. · If you want SnoopDos to run automatically when you boot your system, simply drag the icon to your WBStartup drawer. Ensure the icon contains the tooltype HIDE=YES if you want SnoopDos to start up hidden in the background. · If you want to access online help from within SnoopDos, make sure the file SnoopDos.guide is in the same directory as SnoopDos itself, or else copy it to the directory HELP:English. See also: @{" Contents " link Main} @{" Introduction " link Introduction} @{" What's New " link WhatsNew} @{" Main window " link MainWindow} @ENDNODE @NODE Introduction @TITLE "Introduction to SnoopDos" INTRODUCTION TO SNOOPDOS How many times have you tried to install some big application program, only to find out when you run it that it doesn't seem to work properly? Often, it's looking for some configuration file, library, environment variable, or font which you've forgotten to install. Version 1 of SnoopDos provided a simple no-frills approach to spying on a program's activities. Since its release, other programs have appeared which perform a similar task, including DosTrace by Peter Stuer, Snoopy by Gerson Kurz, and Woodward by Tomas Rokiki. However, good as these programs are, I felt that they made it unnecessarily difficult for the user to view the information of interest. SnoopDos 3.0 aims to bring the original SnoopDos into the 90's by adding a full style guide compliant GUI and a host of powerful new features, whilst retaining the simplicity of its ancestor. To get going with SnoopDos, simply double-click on the SnoopDos icon or type "Run SnoopDos" in a Shell window. The first thing you'll see is the main SnoopDos window, which features a variety of buttons. At this point, SnoopDos is active, and monitoring a range of system operations. If you now run another application, you should see some lines of output displayed in the SnoopDos window. When there are too many lines to fit in the window, some will scroll off the top; you can use the scroll bar to bring them back into view. In most cases, this is all you need to do to identify a problem. The SnoopDos window will list any files that can't be opened, fonts that can't be found, and so on, as well as all those operations that were successful. However, you can customise SnoopDos to better suit your Amiga environment. By clicking on the Setup and Function gadgets in the main window, you can open two additional windows. The @{" Settings " link SettingsWindow} window lets you change various preferences settings, such as the fonts used for the SnoopDos window, while the @{" Function " link FunctionWindow} window lets you choose which events you want SnoopDos to display in the main window. If you're unsure of the meaning of any of the buttons, check out the Function window help for more details. An important feature of SnoopDos is that you can choose exactly how much or how little information about events you want to see. Select "Show Format" from the Windows menu to open up the format editor. This contains the current event format which controls how the information in the main window is displayed. To change this, simply pick up fields using the left mouse button and drag them to a new position. For example, if you want to see what time each event occurred at, simply drag the Time field from the "Available" box into the "Current Format" box. As soon as you release it, the main window updates to show the time associated with each event in the window. SnoopDos always records all possible information about an event, even if it isn't all being displayed at the moment. You can also modify the format directly in the main window, by clicking on a column title with the mouse and dragging it to a new position. Usually, dragging a title repositions it independently of those on either side; if you hold down shift as you drag, then all the columns to the right will move as well. If you make any changes to the default SnoopDos configuration, you may wish to save the changes so that they will take effect the next time you run it. Simply click on the Save Settings button in the main window, and they will be saved to a text file called ENVARC:SnoopDos.prefs. You can view this file with any text reader. Now go and play with SnoopDos a bit. At any time within SnoopDos, you can press the HELP key to call up context-sensitive help from this document. After this, you might like to return and read the help pages dealing with the main window, function window, and settings window. See also: @{" Contents " link Main} @{" Quick Start " link QuickStart} @{" What's New " link WhatsNew} @{" Main Window " link MainWindow} @ENDNODE @NODE WhatsNew @TITLE "What's New In SnoopDos 3.0" WHAT'S NEW IN SNOOPDOS 3.0 If you are one of the many users of SnoopDos 1.7, you will be pleased to see that SnoopDos 3.0 has a host of new features designed to make it more useful. Alas, nothing is for free in this world. SnoopDos has grown from a lean and mean CLI-only utility into a rather large GUI-based application. Since most serious Amiga users these days have an accelerated system with plenty of memory and hard drive space, this seems like a reasonable trade off. If your Amiga has more modest capabilities, you may find one of the other SnoopDos-like utilities more suited to your system. Now, without further ado, here's a list of the major new features in this version of SnoopDos: · A fully font-sensitive GUI lets you control all options using the mouse or keyboard. The main window gadgets can be selectively disabled to allow as many lines of text as possible to be displayed. · A memory buffer stores details of all function calls that scroll off the top of the window. These can then be reviewed using the scroll bar. · Many new functions can be monitored, including Workbench tooltypes, ARexx messages sent by any ARexx script, and a variety of new 2.04 DOS functions. · Programs compiled with GNU C, which bypass dos.library and talk directly to DOS devices using packet i/o, can now be monitored. · Additional information is available for each function monitored, including the time the function was called, what program module made the call (if @{" SegTracker " link SegTracker} is loaded), the process ID, and much more. · You can choose exactly which programs to monitor or ignore, using a standard AmigaDOS pattern string. · For DOS device programmers, a packet debugger allows you to monitor every packet sent to any currently mounted filesystem device. · A convenient "drag & drop" format editor allows you to easily select exactly how much or little information you wish to see about each event. For even greater control, you can directly adjust the width of each column of output in the main window using the mouse. · All of the sub windows used to control various settings are modeless. You can leave them open all the time if you like, and any changes you make take effect immediately. · SnoopDos can now run as a commodity, continuing to monitor activity while hidden in the background. · A new Pause option allows you to freeze any tasks being monitored by SnoopDos, or single step through the calls they make, one at a time. · A comprehensive command language with over 100 commands lets you control SnoopDos from the CLI, Workbench, ARexx, or script files. · SnoopDos can read an external language catalog file to allow it to be localised for any country. · Context-sensitive AmigaGuide help is available from within the program, both for windows and menu options. · The clipboard is fully supported, allowing you to quickly copy SnoopDos output into your favourite editor or wordprocessor. · Function calls can now be simultaneously written to a disk file while being displayed in the SnoopDos window. So what are you waiting for? Go and give it a try! See also: @{" Contents " link Main} @{" Quick Start " link QuickStart} @{" Introduction " link Introduction} @{" Main Window " link MainWindow} @ENDNODE @NODE Workbench @TITLE "Starting SnoopDos from Workbench" STARTING SNOOPDOS FROM WORKBENCH SnoopDos can be easily started from Workbench by double-clicking on its icon, or on the icon of any settings file saved earlier. You can store any SnoopDos command as a tooltype in the icon and each command will be executed by SnoopDos when it loads. For example, this allows you to automatically open a log file on disk each time you run SnoopDos (using the @{" OpenLog " link OpenLog} or @{" AppendLog " link AppendLog} commands). You could also automatically open the function window using the @{" OpenFunction " link OpenFunction} command, or arrange that the main window always opens in a particular position using the @{" MainWindowPos " link MainWindowPos} command. SnoopDos carries out the following actions when started from Workbench: · Checks icon tooltypes for @{" Language " link Language}, @{" PatchRamLib " link PatchRamLib} and @{" Settings " link Settings} commands · Loads the default settings file, as defined by the Settings command. If no name has been set, then checks PROGDIR:, ENVARC: and S: for a file called SnoopDos.prefs and reads that instead if it exists. · Reads any settings files that were passed in as project icons when SnoopDos was loaded. These files can contain any SnoopDos command, not just settings commands. · Scans the tooltypes of all selected icons, starting with the program icon, and executes any recognised commands contained therein. After all of this, the main window is automatically opened, unless a @{" Hide " link Hide} or @{" CX_Popup=No " link CX_Popup} command was encountered. If SnoopDos was already running when the icon is loaded, then the commands in the settings files and tooltypes will be executed by the running version instead. In this case, the Hide and CX_Popup keywords will be ignored, and the SnoopDos window will be automatically re-opened if it was hidden. This allows you to always show the SnoopDos window by clicking on a SnoopDos icon, even if that icon contains a Hide command in its tooltypes. See also: @{" Command Index " link CommandIndex} @{" Command syntax " link CommandSyntax} @{" Settings files " link SettingsFiles} @{" CLI usage " link CLI} @{" ARexx support " link ARexx} @ENDNODE @NODE CLI @TITLE "Starting SnoopDos from the CLI" STARTING SNOOPDOS FROM THE CLI When you run SnoopDos from the CLI, it carries out the following actions: · Checks the command line for @{" Language " link Language}, @{" PatchRamLib " link PatchRamLib} and @{" Settings " link Settings} options · Loads the default settings file, as defined by the Settings command. If no name has been set, then checks PROGDIR:, ENVARC: and S: for a file called SnoopDos.prefs and reads that instead if it exists. · Executes all other SnoopDos commands on the command line. If SnoopDos was already running, then any commands on the command line will be executed by that version instead. For example, you could use the command SNOOPDOS OPENLOG "ram:SnoopDos.log" to make the current copy of SnoopDos open a new log file. Typing SNOOPDOS HELP will display a summary of all the commands recognised by SnoopDos. Commands that need a parameter will be marked with an '*'. If you intend to control SnoopDos from the CLI like this, you may want to investigate its @{" ARexx " link ARexx} capabilities. Using the RX command to send a command to SnoopDos will usually be much quicker than waiting for the SnoopDos executable to load a second time. An alias such as the following can be useful: ALIAS SNOOPTELL "RX *"ADDRESS SNOOPDOS '[]'*"" This allows you to issue SnoopDos commands by simply typing SnoopTell . If you do this, you'll need to double-up any quotes that might appear on the command line, so that SnoopTell OpenLog "ram:test file" would become SnoopTell OpenLog ""ram:testfile"". If you accidentally forget to type "RUN SNOOPDOS" the first time you load the program, that CLI will be unavailable until SnoopDos exits. If this happens, you can tell SnoopDos to quit by typing CTRL-C inside the CLI window. This is particularly useful if you are running SnoopDos remotely via modem or over a network. See also: @{" Command Index " link CommandIndex} @{" Command syntax " link CommandSyntax} @{" Settings files " link SettingsFiles} @{" Workbench usage " link Workbench} @{" ARexx support " link ARexx} @ENDNODE @NODE ARexx @TITLE "SnoopDos ARexx support" SNOOPDOS AREXX SUPPORT When SnoopDos is running, it creates an ARexx port called (predictably) SNOOPDOS. This allows you to control almost every aspect of the program from within ARexx scripts. Here's an example of a simple ARexx script that configures SnoopDos to monitor one particular function, and then captures all calls to that function in a log file. /* Sample ARexx script to log all calls to LoadSeg */ /* Check if SnoopDos is running; if not, then start it */ if ~show('P', 'SNOOPDOS') then do address command "run >nil: SnoopDos" address command "waitforport SNOOPDOS" end address SNOOPDOS /* Commands now go to SnoopDos */ logformat "%t %15p %6a %37n %6o %r" /* Install a custom log format */ functions none /* Disable all functions */ loadseg on /* Re-enable LoadSeg function */ appendlog "ram:SnoopDos.txt" /* Open log file */ addlog "(Monitoring only LoadSeg)" /* Add info message to log file */ logformat none /* Remove our custom format */ (Even though we remove the custom log format at the end of the script, it will remain in use until the log file is closed. The next time a log file is opened, it will use the main window format instead.) If this code is stored in a file called LoadSeg.Rexx, you can execute it by typing RX LOADSEG. You can tell if a particular SnoopDos command succeeded or not by checking the RC variable afterwards. This will be set as follows: RC = 0 Command completed successfully RC = 10 Command requires a parameter RC = 20 Command could not be completed (parameter may be invalid) RC = 30 Command was not recognised by SnoopDos You can use the ARexx command SIGNAL ON ERROR to cause ARexx to stop if it encounters a SnoopDos error (usually, it will quietly ignore all errors). If you want to get a feel for using SnoopDos commands, you can use the @{" LoadSettings " link LoadSettings} command with a filename of "CON:////SnoopDos/CLOSE" to open a command window that lets you interactively enter commands and see their effect. See also: @{" Command Index " link CommandIndex} @{" Command syntax " link CommandSyntax} @{" Settings files " link SettingsFiles} @{" Workbench usage " link Workbench} @{" CLI usage " link CLI} @ENDNODE @NODE SettingsFiles @TITLE "SnoopDos Settings Files" SNOOPDOS SETTINGS FILES A SnoopDos settings file is any text file which begins with the line "" and contains SnoopDos commands. While settings files are usually generated automatically using the @{" SaveDefSettings " link SaveDefSettings} command, they can also be created using any standard text editor. In fact, the term "settings file" is slightly misleading, since such a file can contain any SnoopDos command, not just those that control program settings. For example, a settings file can carry out actions like opening a new log file, opening a particular arrangement of windows, or adding custom output to an existing log file. The format of the file is fairly free form. There should be one command per line, and anything following a semicolon is treated as a comment. See the section on @{" Command syntax " link CommandSyntax} for more details. When you run SnoopDos, it looks for a default settings file and executes all the commands it contains. You can specify the name of this file explicitly using the @{" Settings " link Settings} command. If you don't specify a default filename, then SnoopDos will look in the PROGDIR:, ENVARC: and S: directories for a file called SnoopDos.prefs. If it can't find a file in any of those three directories, then it will use the name ENVARC:SnoopDos.prefs when you ask it to save default settings. Note that this gives you some flexibility as to where you store your default settings. If you don't like the idea of the SnoopDos settings file wasting RAM by being stored in ENVARC: (and thus ENV:) then you can simply move the file to S: or the program directory instead, and SnoopDos will always use the new directory with no additional work needed on your part. Since SnoopDos erases the old defaults file whenever you save default settings, it's not a good idea to include commands other than those written by SnoopDos itself in the defaults file -- they would get overwritten the next time you saved your settings. Instead, you could consider adding such commands as tooltypes in the SnoopDos icon. However, there is another slightly more convoluted way to execute additional commands while SnoopDos is initialising. You can create a default settings file (e.g. ENVARC:SnoopDos.prefs) which contains something like the following: ; Settings "S:SnoopDos.set" ; This is where the defaults will be stored LoadDefSettings ; Now load in the defaults ; ; Additional commands go below here ; OpenLog "ram:SnoopDos.log" ; Let's start a new log file FormatWindowPos=400,300 ; Ensure window position is always the same OpenFormat ; Open the format window for easy access ; etc. As you can see, the first thing this command file does is to change the name of the default settings file. This ensures that if you click on Save Settings from within SnoopDos, the new file will be overwritten rather than this file. Next, those settings are loaded in. (SnoopDos won't automatically load the settings unless you tell it to.) After this, any additional commands can appear. For example, you could make SnoopDos always start up Paused or Disabled. If there are certain settings that you always want set to a particular value, overriding any changes made via Save Settings, then this is a good place to put them. Note that while it is perfectly valid for one settings file to execute another (using the @{" LoadSettings " link LoadSettings} or @{" LoadDefSettings " link LoadDefSettings} commands) this oly works up to three levels of nesting. This prevents an infinite loop from occurring if you accidentally try and load a file from within itself. There is one final trick you can do with settings files. If you load a settings file with a filename that corresponds to a valid console window, such as "CON:////SnoopDos/CLOSE", then SnoopDos will allow you to type in commands interactively and see their effect. See the @{" LoadSettings " link LoadSettings} command for more information. See also: @{" Command Index " link CommandIndex} @{" Command syntax " link CommandSyntax} @{" ARexx support " link ARexx} @{" Workbench usage " link Workbench} @{" CLI usage " link CLI} @ENDNODE @NODE Distribution @TITLE "SnoopDos Distribution" SNOOPDOS DISTRIBUTION My distribution policy for SnoopDos is simple: it may be freely distributed for non-commercial purposes, as long as all the files in the original archive are present and have not been modified in any way. No charge for SnoopDos may be made, other than a reasonable cost to cover the media and copying time. If you wish to include SnoopDos on a magazine cover disk, you may do so as long as you send a complimentary copy of the magazine issue in which it appears to my home address. The entire package must be included on the disk, not just the executable. Please @{" contact " link Author} me in advance to ensure you have the latest version. If you wish to supply SnoopDos as part of a commercial product, please contact me to discuss it -- I'm easy to please. If you wish to supply SnoopDos as part of a CD-ROM compilation of freeware, you may do so as long as the disc contains at least 20 Mb of other freeware. Otherwise, contact me first please. Explicit permission is granted to distribute SnoopDos on any CD-ROM produced by Fred Fish / Amiga Library Services, and on any officially supported Aminet compilation CD-ROM. I reserve the right to publically poke fun at anyone who fails to abide by these distribution rules, along with more severe action if appropriate. Note: The source code for SnoopDos is available in a separate archive. You should be able to find it on Aminet in the util/moni directory, along with the main SnoopDos archive. See also: @{" Contents " link Main} @{" History " link History} @{" Credits " link Credits} @{" Author " link Author} @ENDNODE @NODE History @TITLE "SnoopDos History" SNOOPDOS HISTORY The very first version of SnoopDos was written back in May 1990 at the suggestion of a friend. It proved popular, and was officially released to the world as Version 1.0 in September 1990. Over the next few years, SnoopDos received a number of minor upgrades, with the final public release being V1.7 in December 1992. A further upgrade, V1.7a in May 1993, had limited circulation. In Autumn of 1993, work began on a complete rewrite of SnoopDos. A closed user group was set up on the UK conferencing system, Cix, and an initial prototype of the GUI was constructed using Commodore's ToolMaker. This was used to obtain early feedback on the interface from my testers, and acted as the basis for the first real version. In January 1994, I found myself unexpectedly transferred to St Paul, Minnesota as part of my job. After acquiring a second-hand A3000 (thanks Scott!), I was able to resume work on the project. During these three months, SnoopDos gained most of its functionality, along with a few neat features like the drag & drop format editor. I returned to Ireland at the end of April, and work continued throughout the summer. Many bugs were squashed, the command language was fleshed out, refinements were made, and documentation was written. In July, the feature set was locked down, and August was spent finetuning. After almost a year, SnoopDos 3.0 was ready for release. When you consider that the very first version of SnoopDos took less than a week to write, you have to wonder why it took so long to produce this new version. Either I've slowed down a lot, or it's a much more sophisticated program -- you'll have to decide for yourself. A NOTE ABOUT PIRATE VERSIONS OF SNOOPDOS You may have noticed the jump in version numbering from SnoopDos 1.7 to 3.0. This is partly to co-incide with the current version of Kickstart and partly to avoid confusion with pirate copies of SnoopDos. For reasons best known to themselves, various individuals have seen fit to take the source code for SnoopDos (always freely available) and use it to generate new, unauthorised versions which are then released as official upgrades. At least one of these versions has been found to contain a trojan horse. Two particularly widespread hacks were numbered 1.6 and 2.0; if you have either version on your system, you should delete it immediately. One way for me to reduce the chance of this happening in future is to stop distributing source code for SnoopDos. I have no particular wish to do this; I learnt many of my programming skills from studying other people's code, on Fish disks and elsewhere, and it's nice to be able to contribute something back to the programming community. Instead, I would ask anyone out there considering such an action to put their creative talents to better use by writing their own software. In the meantime, I recommend that you try and ensure you obtain your copy of SnoopDos from a reputable source such as Aminet or Fred Fish's regular CD-ROM. If you run a BBS, please feel free to check with me first before putting a new version online, if you have reason to suspect it may be an unauthorised copy. All versions of SnoopDos 3.0 and above are signed using my PGP public key (see @{" Author " link Author} for information on how to obtain this.) If you have PGP, you can use this digital signature to ensure that your copy has not been tampered with. Even if you don't have PGP, a missing signature is a good sign that something is wrong. See also: @{" Contents " link Main} @{" Distribution " link Distribution} @{" Credits " link Credits} @{" Author " link Author} @ENDNODE @NODE Credits @TITLE "SnoopDos Credits" SNOOPDOS CREDITS A project like SnoopDos 3.0 would not be possible without the input of many people. A big thank you to all the users of SnoopDos 1.x who sent in helpful suggestions -- these were a big incentive to write Version 3.0. Writing this version of SnoopDos provided a good opportunity for me to learn about the new Kickstart 2.0 and 3.0 features. Along the way, I ran into many problems, and I'd like to thank the following programmers for their useful coding advice and suggestions: Ralph Babel, Christopher Feck, Mike Froggett, Ed Mackey, Udo K Schuermann and Mike Sinz. While any project of this size is unlikely to be completely bug free, there would be a great many more bugs without the help of my army of beta testers. Not only did they suffer through every variety of crash, they also made many useful suggestions for improvements: Dean Ashton Derek Holdon Charles O'Reilly Timothy Aston Leon Hurst Jolyon Ralph Dan Barrett Paul Kelly (Ireland) Geoffrey Reeves Fred Botton Paul Kelly (England) Tommy Rolfs Charlie Chuck David Malone Toby Simpson Rick Costas Barry McConnell Paul Wakeford Jonathan Evans Markus Moenig Richard Waspe Tommy Gibbons Ian Moran Ian Wellock Jim Hawkins Niall Murphy Michael Witbrock Sincere thanks to one and all. See also: @{" Contents " link Main} @{" History " link History} @{" Distribution " link Distribution} @{" Author " link Author} @ENDNODE @NODE Author @TITLE "SnoopDos Author" HOW TO CONTACT THE AUTHOR I can be contacted via Internet at: ecarroll@maths.tcd.ie ecarroll@cix.compulink.co.uk If you have any bug reports, suggestions or just general comments about SnoopDos, I would like to hear from you. If you think you could do a better job designing an icon for SnoopDos than I did (which wouldn't be hard!) then I would also like to hear from you. You can obtain my PGP public key by sending mail to ecarroll@maths.tcd.ie with the subject line "PGPKEY". If you have an account on Bix or Cix, you can check my online resume instead (user name ecarroll). I can also be reached by snail mail at this address: Eddy Carroll The Old Rectory Delgany Co. Wicklow Ireland I regret that due to the volume of mail received, I cannot always reply to every letter. This is further compounded by the fact that I travel quite frequently. Please use email if possible. See also: @{" Contents " link Main} @{" History " link History} @{" Distribution " link Distribution} @{" Credits " link Credits} @ENDNODE @remark -------------------------------------------------------------- @remark @remark Start of window reference @remark @remark -------------------------------------------------------------- @NODE MainWindow @TITLE "SnoopDos Main Window" The main window looks like this. Click on any item for a more detailed description of its purpose. +-+-----------------------------------------------------------+ |X| SnoopDos 3.0 © Eddy Carroll, August 1994. @{" Hotkey= " link HotKey} | +-+-----------------------------------------------------------+ | @{" Event headings " link EventHeadings} # |-------------------------------------------------------------# | # | @{" Event output " link EventOutput } # | # |-------------------------------------------------------------# | @{" Status " link StatusLine } [ Monitoring system activity.................] # | @{" Pause " link Pause} @{" Disable " link Disable} @{" Open Log... " link MainOpenLog } @{" Setup " link SettingsWindow} A | @{" Hide " link Hide } @{" Quit " link Quit } @{" Save Settings " link SaveDefSettings} @{" Functions " link FunctionWindow} V +===========================================================<>+ The gadgets shown need not be displayed in the window -- you can turn them off via the Windows menu, or by using the @{" HideGadgets " link HideGadgets} and @{" HideStatus " link HideStatus} commands. Even when hidden, the gadgets can still be accessed via keyboard shortcuts. All gadgets also have menu equivalents for convenience. In addition to the underlined characters in the gadget labels, a range of other keystrokes are also recognised. See the @{" Keyboard Shortcuts " link MainKeys} section for more details. See also: @{" Function window " link FunctionWindow} @{" Settings window " link SettingsWindow} @{" Format editor " link FormatEditor} @{" Menu options " link Menu_Index} @{" Show " link Show} @{" Hide " link Hide} @ENDNODE @NODE EventHeadings @TITLE "SnoopDos Event Headings" EVENT HEADINGS This line at the top of the main window displays the headings for each of the current output fields. While the @{" Format editor " link FormatEditor} and @{" Format " link Format} command allow you to change the current headings, you can also use the mouse to make small adjustments directly in the main window. This is useful if you want to see a bit more of a particular field, such as the @{" Target name " link Format_TargetName} field. If you click on any heading, it is highlighted in white, and two vertical markers show the current boundaries of the output field. In addition, a short vertical line indicates the rightmost position in the current format (this is useful if you are trying to adjust the total width to fit neatly inside the current window). While the mouse button is held down, you can move the heading left or right to adjust the position and width of the column. As you drag, you will see the other headings adjust accordingly. When you release the mouse button, the rest of the event output will be updated to reflect the new format. If you click to the blank area at the right of a heading, then you can adjust the width of that heading, while leaving its position unchanged. If the heading title fills the whole width of the column, then you can click on the rightmost character of the title instead to achieve the same effect. Usually, as you adjust a column, the headings to the right of the selected column remain in the same position. This keeps the overall width of the format the same, and is achieved by making one of the other columns narrower or wider, to compensate for the changes made in the selected column. Sometimes it's convenient to be able to increase the overall width of a format -- for example, if you've just resized the main window to be wider. You can do this by holding down the SHIFT key while moving a heading. All the headings to the right of the selected heading will then move in synchronisation with it. At any time while dragging a column, you can press the SPACE key to update the event text to match the new format. This is a little quicker than releasing the column and then clicking on it again, since it allows you to make fine adjustments while still keeping the mouse button pressed. If you change your mind while dragging a column, you can restore the previous setting by pressing the ESC key or clicking the right mouse button. Once you release the left mouse button, the change becomes permanent. (You may find the @{" Last Saved " link Menu_Last_Saved} option on the settings menu useful in this case.) See also: @{" Main window " link MainWindow} @{" Event output " link EventOutput} @{" Format editor " link FormatEditor} @{" Format " link Format} @ENDNODE @NODE EventOutput @TITLE "SnoopDos Event Output" EVENT OUTPUT A large part of the main window is given over to event output. This is where the information about each function being monitored is displayed. The exact details displayed for each function depend on the current event @{" Format " link Format}, but will usually include at least the target name, action, option and result output fields. Because of the way SnoopDos works, it is possible for several programs to start executing monitored functions simultaneously. When this occurs, you may see several events listed without any text in the @{" Result " link Format_Result} field. This is perfectly normal. As each call completes, its result field will be filled in accordingly. Some functions which are expected to take a long time display "----" in the result field instead, to indicate that they are currently executing. These include the @{" Execute " link Execute}, @{" RunCommand " link RunCommand} and @{" System " link System} functions. You can use the cursor keys to move around the event output. Cursor up and down will move backwards and forwards through the event buffer, while cursor left and right will scroll the window horizontally. You can only scroll horizontally if the current event format is too wide to fit completely inside the window. To move in jumps greater than one character, hold down SHIFT or ALT while pressing the cursor key. You can highlight any line in the event buffer by clicking on it with the mouse. The line will remain highlighted until you release the mouse button. This provides an easy way to match text in the Options and Result columns with the corresponding text in the Process Name and Target Name columns. While the highlight is displayed, you can move the mouse up and down to select different lines. If you try and move off the top or bottom of the window, the buffer will scroll in the appropriate direction. Note that no new output will be displayed while a line is highlighted. If you keep a line highlighted for a long time, you may find that the event information currently displayed has vanished from the buffer, and new events will start to be printed instead -- if this happens, the entire window will be automatically refreshed when you release the button. If you use a click-to-front window utility, you may find the brief flash of a row being highlighted when you click the SnoopDos window to the front distracting. You can avoid this by configuring SnoopDos to only allow highlighting of rows when a qualifier key like SHIFT, ALT or CTRL is held down. See the @{" RowQualifier " link RowQualifier} command for more details. See also: @{" Main window " link MainWindow} @{" Event headings " link EventHeadings} @{" Format editor " link FormatEditor} @{" Format " link Format} @{" RowQualifier " link RowQualifier} @{" ShowGadgets " link ShowGadgets} @{" ShowStatus " link ShowStatus} @{" TextSpacing " link TextSpacing} @ENDNODE @NODE StatusLine @TITLE "SnoopDos status line" MAIN WINDOW / STATUS LINE The SnoopDos status line can display a variety of messages, depending on what SnoopDos is currently doing. Here's a summary of the information that will appear on the status line: · when disabled, the time that Disable was selected · when paused, the time that Pause was selected · when logging to a disk file, the name of the file · when logging to a device, the name of the device · when loading a settings file, the name of the file · when saving a settings file, the name of the file If none of these is currently in progress, then SnoopDos will simply say it is monitoring system activity. The information displayed in the status line is sufficient to allow you to remove the gadgets in the main window if you choose. This provides more room for event text to be displayed. See also: @{" HideGadgets " link HideGadgets} @{" HideStatus " link HideStatus} @{" Main window " link MainWindow} @{" ShowGadgets " link ShowGadgets} @{" ShowStatus " link SHowStatus} @ENDNODE @NODE MainOpenLog @TITLE "SnoopDos Open Log Gadget" MAIN WINDOW / OPEN LOG The "Open Log..." gadget in the main window is used to start a new log file. The actual gadget label will vary depending on the current @{" LogMode " link LogMode} setting. You can change this in the @{" Setup " link SettingsWindow} window. The four possible settings are: @{" Open Log... " link OpenLog } Prompt for the new log file using the ASL file requester @{" Start Log " link OpenLog } Open a new log file using the current @{" LogName " link LogName} @{" Append Log " link AppendLog } Add to an existing log file as defined by @{" LogName " link LogName} @{" Serial Log " link OpenSerialLog} Send log file output to a terminal on the serial port When a log file is open, the gadget label is changed to @{" Close Log " link CloseLog}. You can always open a new log file via the ASL file requester by choosing the @{" Open log " link Menu_Open_log} option on the Project menu, regardless of the current label on the gadget. See also: @{" Main window " link MainWindow} @{" AppendLog " link AppendLog} @{" OpenLog " link OpenLog} @{" OpenSerialLog " link OpenSerialLog} @ENDNODE @NODE MainKeys @TITLE "SnoopDos Keyboard commands" MAIN WINDOW / KEYBOARD COMMANDS The following keyboard shortcuts are recognised in the main window: Cursor Left Scrolls left one or more columns in the window Cursor Right Scrolls right one or more columns in the window Cursor Up Scrolls back one or more lines in the event buffer Cursor Down Scrolls forward one or more lines in the event buffer RETURN Scrolls forward one line in the event buffer TAB Performs a @{" Pause " link Pause} (if necessary) and a @{" SingleStep " link SingleStep} SPACE Performs a @{" SingleStep " link SingleStep} while paused SHIFT-TAB Unconditionally cancels @{" Pause " link Pause} or @{" Disable " link Disable} M Opens the @{" Format editor " link FormatEditor} (like the menu shortcut) SPACE Redraws event text while adjusting @{" Event headings " link EventHeadings} ESC Cancels any column drag currently in progress CTRL-C Selects the @{" Quit " link Quit} gadget CTRL-D Activates the @{" Disable " link Disable} gadget CTRL-E De-activates the @{" Disable " link Enable} gadget CTRL-F Brings the main window to the front Most gadgets also have a keyboard shortcut, indicated by an underlined letter in the gadget title. If you press the keyboard shortcut for a button gadget, it will not take effect until you release the key. If you change your mind after pressing it, you can press ESC (with the original key still held down) and the gadget selection will then be ignored. For many gadgets, holding down SHIFT while you type the shortcut key will produce slightly different behaviour. For example, holding down SHIFT while you type the shortcut key for the Setup gadget in the main window will close the Setup window instead of opening it. See also: @{" Main window " link MainWindow} @ENDNODE @NODE SettingsWindow @TITLE "Settings Window" The settings window lets you control overall settings which govern how SnoopDos operates. Click on any item for a more detailed description. +-------------------------------------+ | SnoopDos Settings...................| +-------------------------------------+ | @{" Hide method " link HideMethod} @{" Hotkey " link HotKey } | | @{" Screen type " link ScreenType} @{" Screen name " link ScreenName} | | @{" Log mode " link LogMode } @{" Log file " link LogName } | | @{" File I/O " link FileIOType} @{" Window font " link WindowFont} | | @{" Buffer size " link BufferSize} @{" Buffer font " link BufferFont} | | | | @{" Buffer format " link Format } @{" Edit " link FormatEditor} | | @{" Logfile format " link LogFormat } @{" Copy " link SettingsCopy} | | | | @{" Use " link SettingsButtons} @{" Undo " link SettingsButtons} @{" Cancel " link SettingsButtons} | +-------------------------------------+ See also: @{" Main window " link MainWindow} @{" Function window " link FunctionWindow} @{" Format editor " link FormatEditor} @{" OpenSetup " link OpenSetup} @{" SetupWindowPos " link SetupWindowPos} @ENDNODE @NODE SettingsCopy @TITLE "Setup Window Copy Gadget" SETUP WINDOW / COPY GADGET This gadget copies the current @{" Format " link Format} string into the @{" LogFormat " link LogFormat}. Usually, the format used when sending event information to a log file is the same as that used to display the information in the main window. However, you can choose a separate format if you wish. This allows you to design your log file format using the format editor and the main window. Once you are happy with it, you can Copy it into the LogFormat gadget, and then restore the original window format by clicking Undo in the format editor. If you hold down the shift key while selecting the gadget, then instead of copying the current buffer format, it will clear the log format. When the log format is clear, it indicates that the current buffer format should be used when logging to a file. See also: @{" Setup window " link SettingsWindow} @{" Format editor " link FormatEditor} @{" Format " link Format} @{" LogFormat " link LogFormat} @{" WindowWidth " link WindowWidth} @ENDNODE @NODE SettingsButtons @TITLE "Setup Window Gadgets" SETUP WINDOW / GADGETS The USE, UNDO and CANCEL gadgets in the @{" Setup " link SettingsWindow} window are used to control whether or not the current window settings are made permanent. When you change a gadget in the Setup window, the change takes effect immediately. For example, if you choose a new @{" HotKey " link HotKey}, you will see the main window titlebar updating to reflect the change. Selecting Use will close the Setup window and make all such changes permanent. If you want to close the window while maintaining the current settings, then choose this option. Selecting Undo will restore all the settings in use when you first opened the Setup window. This allows you to recover from any accidental changes you might have made. Selecting Cancel will restore the original settings, and then close the Setup window. This will cause any changes that have been made to the settings since the window was opened to be discarded. There are two exceptions to the earlier statement that all changes made in the Setup window take effect immediately. The first is the @{" BufferSize " link BufferSize} gadget, which controls the size of the event buffer. Since changing the buffer size causes the current buffer contents to be lost, the change doesn't take effect until you select Use. This allows you to change your mind if you alter it by mistake. The second exception is the @{" LogFormat " link LogFormat} gadget. If a log file is currently open when you alter it, the change will not take effect until after the log file is closed. This avoids producing a confusing log file with a variety of different formats. See also: @{" Setup window " link SettingsWindow} @ENDNODE @NODE FunctionWindow @TITLE "Function Window" The SnoopDos function window allows you to choose which events are monitored. Click on any item for a more detailed description. +--------------------------------------------------------------+ | SnoopDos Functions...........................................| +--------------------------------------------------------------+ | System Functions DOS Functions | | | | @{" System Select " link SelectGadgets } @{" FindPort " link FindPort } @{" ChangeDir " link ChangeDir } | | @{" AmigaDOS Select " link SelectGadgets } @{" FindResident " link FindResident } @{" Delete " link Delete } | | @{" FindSemaphore" link FindSemaphore} @{" Execute " link Execute } | | @{" Only show fails " link OnlyShowFails } @{" FindTask " link FindTask } @{" GetVar " link GetVar } | | @{" Show CLI number " link ShowCLI } @{" LockScreen " link LockScreen } @{" LoadSeg " link LoadSeg } | | @{" Show full paths " link ShowFullPaths } @{" OpenDevice " link OpenDevice } @{" Lock " link Lock } | | @{" Use device names " link UseDeviceNames } @{" OpenFont " link OpenFont } @{" MakeDir " link MakeDir } | | @{" Monitor packets " link MonitorPackets } @{" OpenLibrary " link OpenLibrary } @{" MakeLink " link MakeLink } | | @{" Packet debugger " link PacketDebugger } @{" OpenResource " link OpenResource } @{" Open " link Open } | | @{" Monitor ROM calls " link MonitorROMCalls} @{" ReadToolTypes" link ReadToolTypes} @{" Rename " link Rename } | | @{" Ignore WBench/Shell " link IgnoreShell } @{" SendRexx " link SendRexx } @{" RunCommand " link RunCommand} | | @{" SetVar " link SetVar } | | @{" Match name " link MatchName} [......................] @{" System " link System } | | | | @{" Use " link FunctionButtons} @{" Undo " link FunctionButtons} @{" Cancel " link FunctionButtons} | +--------------------------------------------------------------+ See also: @{" Main window " link MainWindow} @{" Settings window " link SettingsWindow} @{" Format editor " link FormatEditor} @{" OpenFunction " link OpenFunction} @{" FunctionWindowPos " link FunctionWindowPos} @ENDNODE @NODE SelectGadgets @TITLE "SnoopDos Function Selection gadgets" FUNCTION WINDOW / SYSTEM AND DOS SELECTORS These gadgets allows you to quickly select or deselect all the functions listed in the System or AmigaDOS column of the @{" Function " link FunctionWindow} window. There are three possible settings. SELECTED is the usual setting, and indicates that a mixture of functions are currently being monitored. ALL and NONE indicate respectively that all or none of the functions in each column are currently being monitored. The function checkbox gadgets will reflect this. As long as you don't click on any of the function checkboxes, SnoopDos will remember the last SELECTED configuration, and you can then restore that configuration by changing the selection back to SELECTED again. However, if you change any checkbox gadget while in the ALL or NONE state, then the state changes back to SELECTED, and SnoopDos will no longer be able to restore the original settings. This is more difficult to explain than to understand. Play with all the gadgets and everything should become clear. You can use the @{" Functions " link Functions} command to enable or disable groups of functions from within a script. See also: @{" Function window " link FunctionWindow} @{" Functions " link Functions} @ENDNODE @NODE FunctionButtons @TITLE "Function Window Gadgets" FUNCTION WINDOW / GADGETS The USE, UNDO and CANCEL gadgets in the @{" Function " link FunctionWindow} window are used to control whether or not the current function settings are made permanent. When you change a function gadget in the window, the change takes effect immediately. Selecting Use will close the window and make all such changes permanent. If you want to close the Function window while maintaining the current function settings, then choose this option. Selecting Undo will restore all the function settings in use when you first opened the window. This allows you to recover from any accidental changes you might have made. Selecting Cancel will restore the original function settings, and then close the window. This will cause any changes that have been made to the settings since the window was opened to be discarded. See also: @{" Function window " link FunctionWindow} @ENDNODE @NODE FormatEditor @TITLE "Format Editor" The format editor lets you choose what information is displayed in the main window for each monitored event. Click on any item for a more detailed description. +------------------------------------------------+ | SnoopDos Format Editor.........................| +------------------------------------------------+ | Available fields Current format | | +--------------------+ +---------------------+ | | | @{" CallAddr %c " link Format_CallAddr } | | @{" Count %05u " link Format_Count } | | | | @{" Date %d " link Format_Date } | | @{" Proc Name %18p " link Format_ProcessName} | | | | @{" Hunk:Offset %h " link Format_HunkOffset } | | @{" Action %10a " link Format_Action } | | | | @{" Task ID %i " link Format_TaskID } | | @{" Target Name %27n " link Format_TargetName } | | | | @{" Segment Name %s " link Format_SegmentName} | | @{" Options %07o " link Format_Options } | | | | @{" Time %t " link Format_Time } | | @{" Res. %04r " link Format_Result } | | | | | | | | | +--------------------+ +---------------------+ | | | | @{" Field width " link Format_FieldWidth} [====[]===================] 7 | | | | @{" Use " link FormatButtons} @{" Undo " link FormatButtons} @{" Cancel " link FormatButtons} | +------------------------------------------------+ The current format is listed in the righthand box while other fields not currently in use are listed in the lefthand box. You can use the mouse to drag fields from their current position to a new position. As you do this, you will see the main window updating to reflect your change. You can also use the cursor keys to edit the format. Cursor Up and Down select a field to edit in the current format, and Cursor Left and Right adjust the field width. See also: @{" Main window " link MainWindow} @{" Settings window " link SettingsWindow} @{" Function window " link FunctionWindow} @{" Format " link Format} @{" OpenFormat " link OpenFormat} @{" FormatWindowPos " link FormatWindowPos} @ENDNODE @NODE Format_FieldWidth "Format width gadget" FORMAT EDITOR / FIELD WIDTH SLIDER The format width slider gadget allows you to adjust the width of the currently selected format output field. As soon as you release the slider, the main window will be updated to reflect the new width of the selected field. The width of each event in the current format is displayed to the right of the event name (between the '%' and the format identifying letter). Only fields in the current format can have their widths adjusted. If there is no currently selected field, then the slider is disabled. See also: @{" Format editor " link FormatEditor} @{" Main window " link MainWindow} @{" Format " link Format} @ENDNODE @NODE FormatButtons @TITLE "Format Editor Gadgets" FORMAT EDITOR / GADGETS The USE, UNDO and CANCEL gadgets in the @{" Format " link FormatEditor} editor are used to control whether or not the current format is installed permanently. When you make changes in the format editor, you can immediately see the effect of those changes in the main window. Selecting Use will close the format editor and make those changes permanent. If you want to close the format editor while maintaining the current settings, this is the option to choose. Selecting Undo will restore the format in use when you first opened the format editor. This allows you to recover from any accidental changes you might have made. Selecting Cancel will restore the original format, and then close the format editor. This will cause any changes that have been made to the format since the editor was opened (including any changes made in the main window) to be discarded. See also: @{" Format editor " link FormatEditor} @{" Format " link Format} @{" Event heading " link EventHeadings} @ENDNODE @NODE Format_Action "Action output field" %A -- ACTION The action output field is one of the most important parts of any event. It shows what action a program is trying to carry out. The possible actions correspond roughly to the functions listed in the @{" Function " link FunctionWindow} window, but you may also see other actions listed occasionally. In particular, if you have the @{" PacketDebugger " link PacketDebugger} turned on, you will see many actions of the form #XXXXXX (such as #FINDOUTPUT and #COPY_DIR). These are raw AmigaDOS packets, and of interest only to programmers. Any actions prefixed with an asterisk correspond to operations carried out using direct packet i/o, rather than dos.library function calls. You will only see these if you have enabled the @{" MonitorPackets " link MonitorPackets} option. Typically, such calls are only made by programs compiled using GNU C. See also: @{" Format editor " link FormatEditor} @{" Main window " link MainWindow} @{" Format " link Format} @ENDNODE @NODE Format_CallAddr "Call Address output field" %C -- CALL ADDRESS This output field displays the memory address from which a monitored function was called. On its own, this is fairly meaningless. However, if you are a programmer, you can use this information to locate the piece of code that made the call, and see what it tries to do next. The address is displayed as a 7 digit hex number since very few, if any, Amigas have memory above $0FFFFFFF. If your Amiga happens to be the exception, then ensure that you make this field at least 8 characters wide to catch any wider addresses. Also note that the value actually represents the address of the first instruction after the call to the monitored function. If you want to see the instruction that made the call, subtract 6 from this value. If another program has patched a function after SnoopDos, then SnoopDos will usually be unable to determine the correct return address -- instead, the address of the second program's patch code will be displayed. If this causes a problem, then you should not enable SnoopDos's monitoring of the function in question until after the second program has been loaded. See also: @{" Format editor " link FormatEditor} @{" Main window " link MainWindow} @{" Format " link Format} @ENDNODE @NODE Format_Date "Date output field" %D -- DATE This output field displays the date an event took place on, in the standard AmigaDOS format DD-MMM-YY. You are unlikely to find this useful unless you intend running SnoopDos for several days at a time. See also: @{" Format editor " link FormatEditor} @{" Main window " link MainWindow} @{" Format " link Format} @{" Time field " link Format_Time} @ENDNODE @NODE Format_HunkOffset "Hunk:Offset output field" %H -- HUNK:OFFSET This output field is only of use to programmers, and then only when @{" SegTracker " link SegTracker} is loaded. It displays the hunk and offset from where the current function was called, in the format HH:OOOOOO. (Both the hunk and the offset are given in hex). You can use this information in conjunction with the @{" Segment Name " link Format_SegmentName} output field and the @{" FindHit " link SegTracker} utility to identify which line in a program's source code was responsible for making the function call. This can be invaluable when you are debugging your code. If SegTracker is not loaded, or if it cannot identify which module the function was called from, then this field will usually be blank. However, if the function was called from ROM, then the offset from the beginning of the ROM module will be displayed instead. The same caveat discussed for the @{" Call Address " link Format_CallAddr} field regarding programs that patch functions after SnoopDos has been installed also applies here. See also: @{" Format editor " link FormatEditor} @{" Main window " link MainWindow} @{" Format " link Format} @ENDNODE @NODE Format_TaskID "TaskID output field" %I -- TASK ID This output field displays the task address of the program that called the current function. The address is displayed as a 7 digit hex number. If your Amiga happens to have memory above $0FFFFFFF, you will need to widen this field to allow all 8 digits to be displayed. This field can be useful in identifying the process that called a function if there are several processes running on your system with the same name. You can use a tool such as ARTM or XOper to find out more information about the process based on its address. See also: @{" Format editor " link FormatEditor} @{" Main window " link MainWindow} @{" Format " link Format} @ENDNODE @NODE Format_TargetName "TargetName output field" %N -- TARGET NAME This output field displays the most vital piece of information associated with the monitored function. This will vary from function to function, but is typically the name of the requested system resource or disk file. This field is unusual in that it can be displayed aligned on the left or the right -- all the other fields are always displayed left aligned. See the @{" LeftAligned " link LeftAligned} and @{" RightAligned " link RightAligned} commands for more details. See also: @{" Format editor " link FormatEditor} @{" Main window " link MainWindow} @{" Format " link Format} @ENDNODE @NODE Format_Options "Options output field" %O -- OPTIONS This output field displays any secondary options associated with the item displayed in the @{" TargetName " link Format_TargetName} output field. This will vary from function to function. For example, with the Open() function, this will show whether the file is being opened for reading or writing. With the RunCommand() function, it will show the stack size of the command being run. If a particular function has no secondary options, then this field will remain blank. See also: @{" Format editor " link FormatEditor} @{" Main window " link MainWindow} @{" Format " link Format} @ENDNODE @NODE Format_ProcessName "ProcessName output field" %P -- PROCESS NAME This output field displays the name of the process that called the function being monitored. Note that while this indicates the program that was responsible for the call, the program displayed may not have made the call directly. For example, it may have called a function in an external library, and that library may be making the call on the program's behalf. If this distinction is important, you can use the @{" Segment Name " link Format_SegmentName} output field to get more precise information. Sometimes you may find you have several processes running which all have the same name. In this case, you can use the @{" Task ID " link Format_TaskID} output field to distinguish between them. Alternatively, if they were all run from the CLI instead of Workbench, you can use the @{" ShowCLI " link ShowCLI} command to display the CLI number of each process in brackets at the start of the name. See also: @{" Format editor " link FormatEditor} @{" Main window " link MainWindow} @{" Format " link Format} @ENDNODE @NODE Format_Result "Result output field" %R -- RESULT This output field displays the result of each function call. This will usually be either OK or Fail, depending on the outcome. Some functions behave slightly differently. In the case of the @{" Execute " link Execute}, @{" RunCommand " link RunCommand} and @{" System " link System} functions, this field will still display Fail if the function failed, but will return the numeric program return code if the function succeeded. Since these functions typically take some time to execute, the result will be shown as "----" while the command is executing. If you @{" Pause " link Pause} SnoopDos, then each task that calls a monitored function will be put to sleep. When this occurs, the result field displays "WAIT" to indicate the task is no longer active. This will be replaced by the appropriate return code when execution is resumed. If you have enabled the @{" PacketDebugger " link PacketDebugger}, then this field will not only contain OK or Fail, it will also contain the value or values returned by the DOS device being monitored. To see this additional information, you will need to make the field wider than its normal 4 character width. If you have been using the Packet debugger or the @{" MonitorPackets " link MonitorPackets} option, you may occasionally see a result code of "Missed". This simply indicates that SnoopDos couldn't determine the result code of a particular packet operation, most likely because you disabled packet monitoring while the operation was still in progress. See also: @{" Format editor " link FormatEditor} @{" Main window " link MainWindow} @{" Format " link Format} @ENDNODE @NODE Format_SegmentName "Segment Name output field" %S -- SEGMENT NAME This output field is only of use when @{" SegTracker " link SegTracker} is loaded. It displays the name of the module that called the current function. It is usually used in conjunction with the @{" Hunk:Offset " link Format_HunkOffset} field. The Segment Name will often, but not always, be the same as the process name. They can differ if a program calls a module outside its own code, such as a ROM function or a function in an external disk library. If that function then calls any functions monitored by SnoopDos, it will be identified independently of the original process. This is useful if you are trying to find out what part of the system is responsible for a particular operation. If SegTracker is not loaded, SnoopDos can still identify calls made from within resident ROM modules. In this case, the ROM module name will be displayed. Since calculating the calling module is a relatively time consuming process, SnoopDos only actually performs the calculation when it needs to display the segment name on the screen or output it to the log file. This means that if you don't have any interest in the segment name, then SnoopDos isn't slowed down unnecessarily. However, this has a side effect which can trip up the unwary. If the module that made a function call is unloaded from memory before SnoopDos has a chance to print the details about the functions it called, then the module name and hunk:offset can't be calculated; a "Module not found" message will be displayed instead. This is most likely to happen if SnoopDos is hidden (since it won't display anything until the window is re-opened) but it can also happen if a program exits quickly while it is being monitored. To guard against this, you can take a few simple precautions. Make sure you add the Segment Name field to your output format before you start monitoring. Raise the priority of SnoopDos using the @{" Task priority " link Menu_Task_priority} menu option so that it's higher than the priority of the processes you will be monitoring. This lets SnoopDos call SegTracker before the module has a chance to unload itself. Finally, if you plan on running SnoopDos hidden in the background, keep a log file open, even if it's only to NIL:. This will make sure that SnoopDos always resolves segment names as soon as possible. If you have the main window open, then this won't be necessary. See also: @{" Format editor " link FormatEditor} @{" Main window " link MainWindow} @{" Format " link Format} @ENDNODE @NODE Format_Time "Time output field" %T -- TIME This output field provides a simple way to timestamp each function that SnoopDos monitors. It is particularly useful if you will be running SnoopDos unattended for long periods of time. The time is displayed in the format HH:MM:SS. If you are only interested in the hours and minutes, you can narrow the field width from 8 to 5 characters wide. If SnoopDos will be running for several days, you may also want to consider using the @{" Date " link Format_Date} output field. See also: @{" Format editor " link FormatEditor} @{" Main window " link MainWindow} @{" Format " link Format} @ENDNODE @NODE Format_Count "Count output field" %U -- COUNT This output field simply provides a unique sequence number that identifies the position of an event in the buffer. Events are numbered starting from one and each new event increments the count accordingly. If you are logging events to a file, this field is particularly useful because it provides an easy way of matching up partially completed events with the completed version which appears later on in the file. See the @{" OpenLog " link OpenLog} command for more information. See also: @{" Format editor " link FormatEditor} @{" Main window " link MainWindow} @{" Format " link Format} @ENDNODE @NODE SegTracker "SegTracker and FindHit" SEGTRACKER AND FINDHIT SegTracker and FindHit are two useful utilities by Mike Sinz that form part of the Enforcer package. SegTracker keeps track of the memory occupied by any module loaded from disk, while FindHit allows a hunk and offset within a module to be mapped back to a line number in source code. For best results, SegTracker should be run immediately after SetPatch in your startup-sequence. This lets it keep track of as many programs as possible. Running SegTracker after SnoopDos has loaded will still work, but it will not be able to identify programs which were already running at that time. You can usually find the latest version of Enforcer on Aminet in the /pub/aminet/dev/debug directory. See also: @{" Hunk:Offset " link Format_HunkOffset} @{" Segment name " link Format_SegmentName} @ENDNODE @remark -------------------------------------------------------------- @remark @remark Start of command reference @remark @remark -------------------------------------------------------------- @NODE CommandIndex @TITLE "SnoopDos Command Index" SnoopDos supports over 100 commands which can be accessed via command line arguments, Workbench tooltypes, settings files, or ARexx. See the @{" Command syntax " link CommandSyntax} section for general information, or click on any command in the list below for detailed information about that command. @{" AddLog " link AddLog } @{" HideGadgets " link HideGadgets } @{" Pause " link Pause} @{" AppendLog " link AppendLog } @{" HideMethod " link HideMethod } @{" Quit " link Quit} @{" AutoOpen " link AutoOpen } @{" HideStatus " link HideStatus } @{" ReadToolTypes " link ReadToolTypes} @{" BufferFont " link BufferFont } @{" HotKey " link HotKey } @{" Rename " link Rename} @{" BufferSize " link BufferSize } @{" IconPos " link IconPos } @{" RightAligned " link RightAligned} @{" ChangeDir " link ChangeDir } @{" IgnoreShell " link IgnoreShell } @{" RowQualifier " link RowQualifier} @{" ClearBuffer " link ClearBuffer } @{" Language " link Language } @{" RunCommand " link RunCommand} @{" CloseFormat " link CloseFormat } @{" LeftAligned " link LeftAligned } @{" SaveBuffer " link SaveBuffer} @{" CloseFunction " link CloseFunction } @{" LoadDefSettings " link LoadDefSettings } @{" SaveDefSettings " link SaveDefSettings} @{" CloseLog " link CloseLog } @{" LoadSeg " link LoadSeg } @{" SaveSettings " link SaveSettings} @{" CloseSetup " link CloseSetup } @{" LoadSettings " link LoadSettings } @{" SaveWindow " link SaveWindow} @{" CopyBuffer " link CopyBuffer } @{" Lock " link Lock } @{" ScreenName " link ScreenName} @{" CopyWindow " link CopyWindow } @{" LockScreen " link LockScreen } @{" ScreenType " link ScreenType} @{" CreateIcons " link CreateIcons } @{" LogFormat " link LogFormat } @{" ScrollDown " link ScrollDown} @{" CX_PopKey " link HotKey } @{" LogMode " link LogMode } @{" ScrollUp " link ScrollUp} @{" CX_Popup " link CX_Popup } @{" LogName " link LogName } @{" SendRexx " link SendRexx} @{" CX_Priority " link CX_Priority } @{" MainWindowPos " link MainWindowPos } @{" Settings " link Settings} @{" Delete " link Delete } @{" MainWindowSize " link MainWindowSize } @{" SetupWindowPos " link SetupWindowPos} @{" Disable " link Disable } @{" MakeDir " link MakeDir } @{" SetVar " link SetVar} @{" DisableWhenHidden " link DisableWhenHidden } @{" MakeLink " link MakeLink } @{" Show " link Show} @{" Enable " link Enable } @{" MatchName " link MatchName } @{" ShowCLI " link ShowCLI} @{" Execute " link Execute } @{" MonitorPackets " link MonitorPackets } @{" ShowFullPaths " link ShowFullPaths} @{" FlushLog " link FlushLog } @{" MonitorROMCalls " link MonitorROMCalls } @{" ShowGadgets " link ShowGadgets} @{" FileIOType " link FileIOType } @{" OnlyShowFails " link OnlyShowFails } @{" ShowStatus " link ShowStatus} @{" FindPort " link FindPort } @{" Open " link Open } @{" SingleStep " link SingleStep} @{" FindResident " link FindResident } @{" OpenDevice " link OpenDevice } @{" SimpleRefresh " link SimpleRefresh} @{" FindSemaphore " link FindSemaphore } @{" OpenFont " link OpenFont } @{" SmartRefresh " link SmartRefresh} @{" FindTask " link FindTask } @{" OpenFormat " link OpenFormat } @{" StackLimit " link StackLimit} @{" Format " link Format } @{" OpenFunction " link OpenFunction } @{" System " link System} @{" FormatWindowPos " link FormatWindowPos } @{" OpenLibrary " link OpenLibrary } @{" TaskPri " link TaskPri} @{" Functions " link Functions } @{" OpenLog " link OpenLog } @{" TextSpacing " link TextSpacing} @{" FunctionWindowPos " link FunctionWindowPos } @{" OpenResource " link OpenResource } @{" Unpause " link Unpause} @{" GetVar " link GetVar } @{" OpenSerialLog " link OpenSerialLog } @{" UseDeviceNames " link UseDeviceNames} @{" GotoLine " link GotoLine } @{" OpenSetup " link OpenSetup } @{" WindowFont " link WindowFont} @{" Help " link Help } @{" PacketDebugger " link PacketDebugger } @{" WindowWidth " link WindowWidth} @{" Hide " link Hide } @{" PatchRamLib " link PatchRamLib } @ENDNODE @NODE CommandSyntax @TITLE "SnoopDos Command Syntax" SNOOPDOS COMMAND SYNTAX SnoopDos understands over 100 individual commands. These commands can be executed from the CLI, as Workbench icon tooltypes, as ARexx commands, or in SnoopDos settings files. In each case, the syntax is the same. There are two broad categories of commands: those that take a parameter and those that don't. You can get a quick summary of commands by typing SNOOPDOS HELP in a CLI window -- this will list all the supported commands, and those that require a parameter will be marked with an '*'. If a command takes a parameter, you can specify the parameter in the following ways. Let's use the HideMethod command as an example (note that all commands and parameters are case insensitive): HideMethod=Iconify HideMethod="Iconify" HideMethod Iconify HideMethod "Iconify" Which of these four variants you use will depend on personal preference, and on whether you are executing the command from ARexx, the CLI or an icon tooltype. However, if a command parameter contains spaces, it must be enclosed in quotation marks. Most of the commands that don't need a parameter are used to control various program settings, such as what functions to monitor. There are several ways to select whether you want each setting on or off. For example, let's look at the Lock command, which controls whether or not SnoopDos monitors the Lock() function in dos.library. All of the following will turn on Lock monitoring: Lock Lock=Yes Lock=On Lock=1 To turn off lock monitoring, you can say: NoLock Lock=No Lock=Off Lock=0 The '=' is optional in most cases, but is required if you are executing the command from the CLI. If you are executing the command via ARexx, it's a good idea to leave out the '=' to prevent it confusing the ARexx command interpreter. In general, most commands have both a positive and negative version. For example, Disable=No, NoDisable, and Enable are all equivalent. Similarly, you can say HideGadgets=Yes or ShowGadgets=No -- they both have the same effect. If SnoopDos doesn't understand a particular command, it will usually inform you -- exactly how depends on the method used to invoke the command. Commands executed from the CLI produce an error message in the CLI window, while those executed from ARexx return a result code in the RC variable. Unrecognised commands in icon tooltypes and settings files are silently ignored. If you want to experiment with SnoopDos commands, you can use the @{" LoadSettings " link LoadSettings} command with a filename of "CON:////SnoopDos/CLOSE" to create a window where you can type commands interactively. See also: @{" Command Index " link CommandIndex} @{" CLI usage " link CLI} @{" Workbench usage " link Workbench} @{" ARexx usage " link ARexx} @ENDNODE @NODE AddLog @TITLE "AddLog command" Command: ADDLOG "text" Example: ADDLOG "Loading BBS..." This command lets you output a custom message to the current SnoopDos log file. It can be useful if SnoopDos is monitoring a DOS or ARexx script which generates large amounts of output, and you want to indicate when certain parts of the script were executed in relation to the SnoopDos output. See also: @{" Command Index " link CommandIndex} @{" AppendLog " link AppendLog} @{" CloseLog " link CloseLog} @{" FlushLog " link FlushLog} @{" LogFormat " link LogFormat} @{" OpenLog " link OpenLog} @ENDNODE @NODE AppendLog @TITLE "AppendLog command" Command: APPENDLOG "filename" Example: APPENDLOG "ram:SnoopDos.log" This command opens a log file. Any output displayed in the SnoopDos window will also be written to this file. If the file already exists, SnoopDos will append its output to the existing contents of the file; otherwise, a new file is created. Files opened using AppendLog have an advantage over those opened with OpenLog, in that it is possible to access the contents of the file from another program while SnoopDos is still writing to it. This is useful if you want to quickly review the events that have been logged so far -- you can simply TYPE the file in a CLI window. If you are doing this, you can ensure that the file contents are up to date by selecting then unselecting the @{" Pause " link Pause} gadget. This will write any information that might still be in the file buffer to the file. See the @{" OpenLog " link OpenLog} documentation for more information about how SnoopDos outputs information to a log file. See also: @{" Command Index " link CommandIndex} @{" AddLog " link AddLog} @{" CloseLog " link CloseLog} @{" FlushLog " link FlushLog} @{" LogFormat " link LogFormat} @{" OpenLog " link OpenLog} @{" OpenSerialLog " link OpenSerialLog} @ENDNODE @NODE AutoOpen @TITLE "AutoOpen command" Command: AUTOOPEN NOAUTOOPEN This command enables or disables SnoopDos's AutoOpen setting. This setting can also be controlled via an option on the Windows menu. When AutoOpen is enabled, SnoopDos will automatically open its window whenever something happens which proces output in the window. This is useful if you have configured SnoopDos to only show one or two event types, since it lets you run SnoopDos in the background and have it pop up as soon as those events happen. This command is automatically written to the settings file when you save settings. See also: @{" Command Index " link CommandIndex} @{" MatchName " link MatchName} @ENDNODE @NODE BufferFont @TITLE "BufferFont command" Command: BUFFERFONT "fontname.size" Example: BUFFERFONT "courier.13" This command selects the font used by SnoopDos when displaying events in the main window. You can also change the font by using the font requester accessible through the @{" Settings " link SettingsWindow} window. The font selected must be a non-proportional font, and you must give a size. This command is automatically written to the settings file when you save settings. See also: @{" Command Index " link CommandIndex} @{" WindowFont " link WindowFont} @ENDNODE @NODE BufferSize @TITLE "BufferSize command" Command: BUFFERSIZE Example: BUFFERSIZE 32 This command changes the size of the buffer SnoopDos uses to record information about events. You can also change the buffer size using the Buffer Size gadget in the @{" Settings " link SettingsWindow} window. The buffer size is given in kilobytes. As a very rough guide, each event occupies about 100 bytes of memory, so you can store about 10 events per kilobyte. The actual size of each event varies depending on the length of the file and process names, and several other factors. Note that changing this setting in the @{" Settings " link SettingsWindow} window only takes effect when you select Use; this is in contrast to most of the other gadgets which take effect as soon as you change them. This is because the SnoopDos buffer is cleared when you change its size, and so the action is left until the last possible moment. If there is not enough memory available for the buffer size you request, SnoopDos will allocate as large a buffer as possible using the available memory. Note that SnoopDos requires contiguous memory for its buffer, so if you have been running many applications before loading SnoopDos, you may find less memory is available then expected. This command is automatically written to the settings file when you save settings. See also: @{" Command Index " link CommandIndex} @{" ClearBuffer " link ClearBuffer} @ENDNODE @NODE ChangeDir @TITLE "ChangeDir command" Command: CHANGEDIR NOCHANGEDIR This command enables or disables monitoring of the CurrentDir() dos.library function. It is also available as a gadget in the @{" Function " link FunctionWindow} window. Programs call the CurrentDir() function when they want to change their working directory to somewhere else. Files opened by the program are then assumed to be in this directory if a pathname isn't explicitly specified. This can sometimes show you where a program expects to find certain files. This command is automatically written to the settings file when you save settings. See also: @{" Command Index " link CommandIndex} @ENDNODE @NODE ClearBuffer @TITLE "ClearBuffer command" Command: CLEARBUFFER This command erases the contents of SnoopDos's event buffer. All events which occur from this point on are numbered starting from one again. If you are about to start monitoring a new program, this is a convenient way to ensure that you don't get the new output mixed up with output from earlier programs. This option is also available as an item on the @{" Buffer " link Menu_Clear_buffer} menu. See also: @{" Command Index " link CommandIndex} @{" BufferSize " link BufferSize} @ENDNODE @NODE CloseFormat @TITLE "CloseFormat command" Command: CLOSEFORMAT This command closes the @{" Format editor " link FormatEditor} if it happened to be open. The current position of the window on the screen is remembered so that it can re-open in the same position next time. You can also close the format window by holding down the shift key while selecting the @{" Show format " link Menu_Show_Format} item on the Windows menu, or while double- clicking on the header line in the main window. Yet another way to close the format window is to hold down the shift key while selecting the "Edit..." gadget in the @{" Setup " link SettingsWindow} window. See also: @{" Command Index " link CommandIndex} @{" OpenFormat " link OpenFormat} @{" FormatWindowPos " link FormatWindowPos} @ENDNODE @NODE CloseFunction @TITLE "CloseFunction command" Command: CLOSEFUNCTION This command closes the @{" Function window " link FunctionWindow} if it happened to be open. The current position of the window on the screen is remembered so that it can re-open in the same position next time. You can also close the function window by holding down the shift key while selecting the @{" Show functions " link Menu_Show_functions} item on the Windows menu, or while clicking on the Function gadget in the main window. See also: @{" Command Index " link CommandIndex} @{" OpenFunction " link OpenFunction} @{" FunctionWindowPos " link FunctionWindowPos} @ENDNODE @NODE CloseLog @TITLE "CloseLog command" Command: CLOSELOG This command closes any currently open log file. It is available as an option on the Project menu, and also as a gadget in the main window (it replaces the @{" Open Log " link MainOpenLog} button while a log file is open). See also: @{" Command Index " link CommandIndex} @{" AddLog " link AddLog} @{" AppendLog " link AppendLog} @{" FlushLog " link FlushLog} @{" LogFormat " link LogFormat} @{" OpenLog " link OpenLog} @ENDNODE @NODE CloseSetup @TITLE "CloseSetup command" Command: CLOSESETUP This command closes the @{" Setup window " link SettingsWindow} if it happened to be open. The current position of the window on the screen is remembered so that it can re-open in the same position next time. You can also close the setup window by holding down the shift key while selecting the @{" Show setup. " link Menu_Show_setup} item on the Windows menu, or while clicking on the Setup gadget in the main window. See also: @{" Command Index " link CommandIndex} @{" OpenSetup " link OpenSetup} @{" SetupWindowPos " link SetupWindowPos} @ENDNODE @NODE CopyBuffer @TITLE "CopyBuffer command" Command: COPYBUFFER This command copies the entire contents of the SnoopDos event buffer to the system clipboard, allowing you to easily paste it into another application such as a word processor or text editor. It can also be accessed as an item on the Buffer menu. The data will be formatted according to the current buffer format. Since this can potentially generate a large amount of text, you may prefer to use the CopyWindow command instead, which only copies that data currently displayed in the main window. See also: @{" Command Index " link CommandIndex} @{" CopyWindow " link CopyWindow} @{" SaveBuffer " link SaveBuffer} @{" SaveWindow " link SaveWindow} @ENDNODE @NODE CopyWindow @TITLE "CopyWindow command" Command: COPYWINDOW This command copies the contents of the main window to the system clipboard, allowing you to easily paste it into another application such as a text editor or word processor. It is also available as an item on tbe Buffer menu. If the current buffer format is too wide to fit completely in the main window, only that portion which is currently displayed will be copied. If this doesn't include enough information, you can use the CopyBuffer command instead and then delete any extra lines that you don't need. See also: @{" Command Index " link CommandIndex} @{" CopyBuffer " link CopyBuffer} @{" SaveBuffer " link SaveBuffer} @{" SaveWindow " link SaveWindow} @ENDNODE @NODE CreateIcons @TITLE "CreateIcons command" Command: CREATEICONS NOCREATEICONS This command controls whether or not SnoopDos should create an icon when it saves a settings file. You can find a corresponding menu option to control this on the Settings menu. Note that no icon is saved for default settings files, only for settings files that are saved using the @{" SaveSettings " link SaveSettings} command. If an icon is created for a settings file, then the settings in that file can be loaded at any time by double-clicking the icon. When SnoopDos writes out icons, it tries to use the same image as that used by the SnoopDos program icon. If it couldn't locate a program icon, it uses a simple built-in icon instead. This command is automatically written to the settings file when you save settings. See also: @{" Command Index " link CommandIndex} @{" SaveDefSettings " link SaveDefSettings} @{" SaveSettings " link SaveSettings} @ENDNODE @NODE CX_PopKey @TITLE "CX_PopKey command" Command: CX_POPKEY "key description" Example: CX_POPKEY "ctrl alt d" This command allows you to select what key sequence is used to open the SnoopDos main window when it is hidden. This corresponds to the Hotkey gadget in the @{" Settings " link SettingsWindow} window. It is a synonym for the @{" HotKey " link HotKey} command. Any standard commodities key description can be given. You can always tell which key sequence is currently in use by looking at the titlebar of the main window. If you enter an incorrect description, then the titlebar will display "". When you have defined a hotkey, SnoopDos can be called up at any time by pressing that key sequence. If the main window was already open, it will be brought to the front and activated. If it was open, but on a different screen, it will be re-opened on the current screen (as selected using the @{" ScreenType " link ScreenType} command). See also: @{" Command Index " link CommandIndex} @{" CX_Popup " link CX_Popup} @{" CX_Priority " link CX_Priority} @{" HotKey " link HotKey} @ENDNODE @NODE CX_Popup @TITLE "CX_Popup command" Command: CX_POPUP=YES CX_POPUP=NO This command controls whether or not SnoopDos should open its window when you run it. If you give the command while SnoopDos is already running, then the window will be opened or closed accordingly. As a special case, if you run SnoopDos from an icon which contains the tooltype CX_POPUP=NO, it will only have an effect the first time SnoopDos is run. If you run it again while SnoopDos is hidden the background, then the main window will be automatically opened, overriding this tooltype. This ensures that a hidden SnoopDos window can always be re-opened by double-clicking on an icon, even if the icon contains a tooltype of CX_POPUP=NO. This command is identical to the @{" Show " link Show} and @{" Hide " link Hide} commands. It is included for compatibility with other commodities. See also: @{" Command Index " link CommandIndex} @{" CX_PopKey " link CX_PopKey} @{" CX_Priority " link CX_Priority} @ENDNODE @NODE CX_Priority @TITLE "CX_Priority command" Command: CX_PRIORITY=n Example: CX_PRIORITY=5 This command is used to control the priority of the hotkey used to call up the SnoopDos window when SnoopDos is running as a commodity. Most people will never need to change this from its default value of zero. However, occasionally you may find that another commodity is intercepting several keystrokes, one of which is the SnoopDos key. By increasing the value of CX_Priority, you can ensure that SnoopDos gets precedence. Alternatively, by setting CX_Priority to a negative value, you could ensure that the other application gets priority. See also: @{" Command Index " link CommandIndex} @{" CX_PopKey " link CX_PopKey} @{" CX_Popup " link CX_Popup} @ENDNODE @NODE Delete @TITLE "Delete command" Command: DELETE NODELETE This command enables or disables monitoring of the DeleteFile() dos.library function. It is also available as a gadget in the @{" Function " link FunctionWindow} window. The DeleteFile() function is used to delete a file from disk. Programs often delete temporary files when they no longer need them. If a file seems to constantly vanish, and you can't figure out why, monitoring DeleteFile() may show you which program is responsible. SnoopDos automatically writes this command to the settings file when you save settings. See also: @{" Command Index " link CommandIndex} @ENDNODE @NODE Disable @TITLE "Disable command" Command: DISABLE This command provides a simple way to completely disable SnoopDos while still leaving it ready for action in the future. It corresponds to the Disable gadget in the main window and the Disable option on the Project menu. In addition, CTRL-D is recognised as a keyboard shortcut for Disable, for SnoopDos 1.x compatibility. This works even when sent via an external log device such as CON: or AUX:. When SnoopDos is disabled, it removes all its system patches and enters a dormant state where it has no effect on system performance. If a log file is open, then any outstanding buffered output is written to the file, along with a message indicating what time SnoopDos was disabled at. (If flushing the output file is all you want to do, the @{" FlushLog " link FlushLog} command is an easier way to achieve this.) See also: @{" Command Index " link CommandIndex} @{" DisableWhenHidden " link DisableWhenHidden} @{" Enable " link Enable} @{" Pause " link Pause} @ENDNODE @NODE DisableWhenHidden @TITLE "DisableWhenHidden command" Command: DISABLEWHENHIDDEN NODISABLEWHENHIDDEN This command controls whether or not SnoopDos continues to monitor system activity when it is running in the background as a commodity. There is a corresponding menu option in the Windows menu. If DisableWhenHidden is set, then SnoopDos automatically disables monitoring when it is hidden (using the @{" Hide " link Hide} command). When the SnoopDos window is re-opened, the previous monitoring state is restored, unless monitoring was re-enabled using the @{" Enable " link Enable} command while SnoopDos was hidden -- in that case, no change is made. SnoopDos automatically writes this command to the settings file when you save settings. See also: @{" Command Index " link CommandIndex} @{" Disable " link Disable} @{" Enable " link Enable} @{" Pause " link Pause} @ENDNODE @NODE Enable @TITLE "Enable command" Command: ENABLE This command is the counterpart to the @{" Disable " link Disable} command. It undoes the effect of an earlier Disable and allows SnoopDos to resume monitoring functions. This corresponds to the Disable gadget in the main window, and the Disable menu option in the Project menu. For compatibility with SnoopDos 1.x, CTRL-E will also select Enable. This works even when sent via an external log device such as AUX: or CON:. Yet another keyboard shortcut is SHIFT-TAB, which will also perform an unconditional @{" Unpause " link Unpause}. If a log file is open, the time at which monitoring was enabled is written to the file. See also: @{" Command Index " link CommandIndex} @{" Disable " link Disable} @{" DisableWhenHidden " link DisableWhenHidden} @{" Pause " link Pause} @ENDNODE @NODE Execute @TITLE "Execute command" Command: EXECUTE NOEXECUTE This command enables or disables monitoring of the Execute() dos.library function. It is also available as a gadget in the @{" Function " link FunctionWindow} window. Older applications call Execute() to run an external command from inside the main program. For example, a program might try to run Commodore's Colors utility to provide a simple way of editing the screen colours. Most modern software will call @{" RunCommand " link RunCommand} or @{" System " link System} instead. The @{" Target name " link Format_TargetName} output field shows the command line being executed by the application. Usually, only a single command is being executed; in this case, the @{" Options " link Format_Options} output field will show "Single". If the application has provided additional commands to execute afterwards, then "Batch" will be displayed instead. Batch mode is most commonly used to create a new CLI or Shell; the additional commands are then read from a console window rather than passed directly by the application. The @{" Result " link Format_Result} output field will show whether or not the command line was loaded successfully. Note that this doesn't indicate that the command itself completed successfully, only that AmigaDOS was able to locate the command on disk and load it into memory. SnoopDos automatically writes this command to the settings file when you save settings. See also: @{" Command Index " link CommandIndex} @{" RunCommand " link RunCommand} @{" System " link System} @ENDNODE @NODE FileIOType @TITLE "FileIOType command" Command: FILEIOTYPE=AUTOMATIC | IMMEDIATE | BUFFERED Example: FILEIOTYPE=IMMEDIATE This command determines what method of buffering SnoopDos uses when capturing information to a log file. It is also available as a gadget in the @{" Settings " link SettingsWindow} window SnoopDos distinguishes between logging to a disk file, and logging to a device such as PRT:, AUX:, or CON:. If you select AUTOMATIC then SnoopDos will automatically use buffered output for disk files and disable buffering when logging to devices. If you select IMMEDIATE, then SnoopDos will never use buffered output. This ensures that the information written to the log file (whether it's on disk or on a physical device such as a printer) will always be completely up to date. However, this can slow things down a little since one file operation needs to be carried out for every single event that SnoopDos monitors. If you select BUFFERED, then SnoopDos will always buffer output, even if logging to a device. The buffering works by waiting until up to 8K of event data has been collected, and then outputting all the data in one operation. This is quicker than IMMEDIATE, but has the disadvantage that the log output may not always be up to date. In the case of a printer, for example, you would see no output for a while, and then suddenly 100 lines would all be printed at once. SnoopDos automatically writes this command to the settings file when you save settings. See also: @{" Command Index " link CommandIndex} @{" FlushLog " link FlushLog} @ENDNODE @NODE FindPort @TITLE "FindPort command" Command: FINDPORT NOFINDPORT This command enables or disables monitoring of the FindPort() exec.library function. It is also available as a gadget in the @{" Function " link FunctionWindow} window. Programs call FindPort to rendezvous with other applications on the system. It is most commonly called to locate another application's ARexx port, but can also be used to allow several products from the same company to work together. SnoopDos automatically writes this command to the settings file when you save settings. See also: @{" Command Index " link CommandIndex} @{" SendRexx " link SendRexx} @ENDNODE @NODE FindResident @TITLE "FindResident command" Command: FINDRESIDENT NOFINDRESIDENT This command enables or disables monitoring of the FindResident() exec.library function. It is also available as a gadget in the @{" Function " link FunctionWindow} window. The Kickstart ROM on all Amigas contains a number of resident modules -- libraries, devices, resources, and so on. The FindResident() function searches the list of all ROM modules for a particular name. Most programs have no need to call FindResident() directly, but you will sometimes see ROM libraries calling it if your current format string includes the @{" Segment name " link Format_SegmentName} field. In normal use, you probably won't find it a useful function to monitor. SnoopDos automatically writes this command to the settings file when you save settings. Note for OS experts: The background ramlib process calls FindResident frequently when searching for libraries and devices. SnoopDos deliberately ignores these calls to keep the amount of information displayed down to a reasonable level. See also: @{" Command Index " link CommandIndex} @{" PatchRamLib " link PatchRamLib} @ENDNODE @NODE FindSemaphore @TITLE "FindSemaphore command" Command: FINDSEMAPHORE NOFINDSEMAPHORE This command enables or disables monitoring of the FindSemaphore() exec.library function. It is also available as a gadget in the @{" Function " link FunctionWindow} window. This is similar to @{" FindPort " link FindPort} but not as commonly used. It allows access to a piece of data to be arbitrated so that only one task at a time can access it. It is often used to allow several copies of a single program to run at once, with all copies sharing access to a single set of data. The main reason you might want to monitor it is if you are writing a program yourself that makes use of it. SnoopDos automatically writes this command to the settings file when you save settings. See also: @{" Command Index " link CommandIndex} @ENDNODE @NODE FindTask @TITLE "FindTask command" Command: FINDTASK NOFINDTASK This command enables or disables monitoring of the FindTask() exec.library function. It is also available as a gadget in the @{" Function " link FunctionWindow} window. The FindTask() function allows a program to locate another task on the system by name. Having located the task, the program can then proceed to signal that task or communicate with it in some other way, or even try and kill it off. Generally, this function is used by utilities to locate system tasks, rather than by applications. SnoopDos automatically writes this command to the settings file when you save settings. See also: @{" Command Index " link CommandIndex} @ENDNODE @NODE FlushLog @TITLE "FlushLog command" Command: FLUSHLOG When SnoopDos is logging output to a disk file, it usually buffers up output in memory and only writes it to disk when the buffer is full (about every 100 lines or so). This is much more efficient than writing every line of output to disk separately, but it has the disadvantage that if the system crashes, you may lose the most recent lines of output. This command instructs SnoopDos to flush any outstanding output in the buffer to the log file, thus bringing it up to date. It has no effect if no log file is open. A quick way to do this interactively is to @{" Pause " link Pause} and then @{" Unpause " link Unpause} SnoopDos using the Pause gadget. Note that you can use the @{" FileIOType " link FileIOType} command to control whether or not SnoopDos uses buffering when writing to the log file. See also: @{" Command Index " link CommandIndex} @{" AddLog " link AddLog} @{" AppendLog " link AppendLog} @{" CloseLog " link CloseLog} @{" LogFormat " link LogFormat} @{" OpenLog " link OpenLog} @ENDNODE @NODE Format @TITLE "Format command" Command: FORMAT "formatstring" Example: FORMAT "%u %p %a %n %o %r" This command defines how SnoopDos should format the output detailing each event it monitors. It is also available as a gadget in the @{" Settings " link SettingsWindow} window. You can edit the format string using the @{" Format " link FormatEditor} editor, or by manipulating columns in the main window using the mouse. The format string is similar to that used by printf in the C programming language. It contains a list of format fields, with each field corresponding to one piece of information about a monitored event. The fields are as follows: @{" Action %a " link Format_Action } The name of the function being called @{" CallAddr %c " link Format_CallAddr } The address the function was called from @{" Date %d " link Format_Date } The date the function was called @{" Hunk:Offset %h " link Format_HunkOffset } The module hunk and offset the call was made from @{" Task ID %i " link Format_TaskID } The address of the task making the call @{" Target Name %n " link Format_TargetName } The name of the item the function call is accessing @{" Options %o " link Format_Options } Any additional options required by the function @{" Proc Name %p " link Format_ProcessName} The name of the process making the call @{" Res. %r " link Format_Result } The result returned by the function @{" Segment Name %s " link Format_SegmentName} The name of the module making the call @{" Time %t " link Format_Time } The time the function was called at @{" Count %u " link Format_Count } The sequence number of this event Each field may appear only once in a format string, but need not appear at all. Several of the fields are really only of use to programmers and can be ignored by most people. The % characters listed are used in the format string to represent each field. Between the % and the field identifier, a number may appear; this defines the number of characters available to display that field. If no number is given, then a sensible default is used instead. Here are some example formats: "%21p %5a %39n %4o %r" -- Classic SnoopDos 1.7 format "%16p %r %6a %6o %80n" -- Maximizes space for target name "%u %7i %p %h %s %7a %39n %o %r" -- For programmers with big screens Normally, SnoopDos will use the currently defined format string when logging information to disk. However, you can change this by supplying a special @{" LogFormat " link LogFormat} string instead. If your format string includes some unrecognised or duplicate fields, SnoopDos will silently remove them and simply use what remains. See also: @{" Command Index " link CommandIndex} @{" Format editor " link FormatEditor} @{" LogFormat " link LogFormat} @ENDNODE @NODE FormatWindowPos @TITLE "FormatWindowPos command" Command: FORMATWINDOWPOS=, Example: FORMATWINDOWPOS=0,20 This command is used to change the position of the format editor window on the current screen. If the format window is open, then it is moved immediately, else it will appear in the new position the next time it is opened. and are the pixel co-ordinates of the upper left corner of the window. SnoopDos automatically writes this command to the settings file when you save settings. See also: @{" Command Index " link CommandIndex} @{" Format editor " link FormatEditor} @ENDNODE @NODE Functions @TITLE "Functions command" Command: FUNCTIONS=ALL | NONE | ALLDOS | NODOS | ALLSYSTEM | NOSYSTEM Example: FUNCTIONS=ALLDOS This command provides a convenient way for an ARexx script to quickly enable or disable monitoring of a group of functions. The ALL and NONE option apply to the entire group of functions that SnoopDos can monitor. ALLDOS and NODOS affect only those functions listed under "DOS Functions" in the function window. ALLSYSTEM and NOSYSTEM affect only those functions listed under "System Functions" in the function window. See also: @{" Command Index " link CommandIndex} @{" Function window " link FunctionWindow} @ENDNODE @NODE FunctionWindowPos @TITLE "FunctionWindowPos command" Command: FUNCTIONWINDOWPOS=, Example: FUNCTIONWINDOWPOS=0,20 This command is used to change the position of the function window on the current screen. If the function window is open, then it is moved immediately, else it will appear in the new position the next time it is opened. and are the pixel co-ordinates of the upper left corner of the window. SnoopDos automatically writes this command to the settings file when you save settings. See also: @{" Command Index " link CommandIndex} @{" Function window " link FunctionWindow} @ENDNODE @NODE GetVar @TITLE "GetVar command" Command: GETVAR NOGETVAR This command enables or disables monitoring of the GetVar() and FindVar() dos.library functions. It is also available as a gadget in the @{" Function " link FunctionWindow} window. AmigaDOS has three types of environment variables: Local, Global and Alias. These functions allow access to all three types. Local variables are associated directly with a single CLI or Shell, and can't be accessed by any other part of the system. Global variables reside in the ENV: directory and can be accessed by all programs. Alias variables are manipulated using the AmigaDOS Alias command, and aren't usually accessed by application programs. The @{" Options " link Format_Options} output field displays which of the three types of variable a program is asking for. If the variable type is followed by an * (for example, "Local*") then this indicates that the program is expecting a binary variable which may contain non-printable characters and which was probably created by the program itself, rather than the AmigaDOS SetEnv command. GetVar() and FindVar() are very similar in operation. GetVar() is typically used by application programs that are only interested in the current value of a variable, while FindVar() is used by Commodore commands that want to directly alter a variable's current value. SnoopDos automatically writes this command to the settings file when you save settings. See also: @{" Command Index " link CommandIndex} @{" SetVar " link SetVar} @ENDNODE @NODE GotoLine @TITLE "GotoLine command" Command: GOTOLINE Example: GOTOLINE 100 This command is used to reposition the buffer display in the main window at a particular line. The line numbers correspond to those displayed in the @{" Count " link Format_Count} output field. A quick way to move to the top or bottom of the buffer is to give the command GOTOLINE 0 or GOTOLINE 99999. See also: @{" Command Index " link CommandIndex} @{" ScrollDown " link ScrollDown} @{" ScrollUp " link ScrollUp} @ENDNODE @NODE Help @TITLE "Help command" Command: HELP Example: HELP MainWindow You can call up help from within SnoopDos itself via the Help menu option on the Project menu, by pressing the Help key while any menu option is highlighted, or by pressing the Help key inside any SnoopDos window. The HELP command is mainly of use from the CLI. If you give it with no parameters, then it will display a list of all the currently recognised SnoopDos commands. If you give a topic, then help on that topic will be loaded into AmigaGuide for you to read. If in doubt, HELP MAIN will always bring you to the main @{" Contents " link Main} page, from where you can find any information you require. See also: @{" Command Index " link CommandIndex} @ENDNODE @NODE Hide @TITLE "Hide command" Command: HIDE This command closes all the SnoopDos windows, but leaves SnoopDos monitoring system activity in the background. It is available as a gadget in the @{" Main " link MainWindow} window, and as a menu option on the Project menu. You can also hide SnoopDos by clicking on the Close gadget in the main window. If the current @{" HideMethod " link HideMethod} is set to None, then this option is not available. When SnoopDos is hidden, the main window can be re-opened by pressing the currently defined @{" HotKey " link HotKey}. Depending on the hide method, you may also be able to open the SnoopDos AppIcon, or select the Show SnoopDos menu item on the Workbench Tools menu. See also: @{" Command Index " link CommandIndex} @{" CX_Popup " link CX_Popup} @{" HideMethod " link HideMethod} @{" Show " link Show} @ENDNODE @NODE HideGadgets @TITLE "HideGadgets command" Command: HIDEGADGETS This command disables the display of the panel of button gadgets in the @{" Main " link MainWindow} window. It is also available as a menu option on the Windows menu. Removing the gadgets allows more information about events to be displayed in the SnoopDos window. Even though the gadgets are no longer visible, you can still use the gadget keyboard shortcuts to activate the various functions. To maximise the amount of room available for displaying event output, you might also like to turn off the @{" Status line " link StatusLine} gadget. SnoopDos automatically writes this command to the settings file when you save settings. See also: @{" Command Index " link CommandIndex} @{" HideStatus " link HideStatus} @{" ShowGadgets " link ShowGadgets} @{" ShowStatus " link ShowStatus} @{" TextSpacing " link TextSpacing} @ENDNODE @NODE HideMethod @TITLE "HideMethod command" Command: HIDEMETHOD=NONE | INVISIBLE | ICONIFY | TOOLSMENU Example: HIDEMETHOD=ICONIFY This command controls the mechanism SnoopDos uses to run in the background when you select the @{" Hide " link Hide} command. It is also available as a gadget in the @{" Settings " link SettingsWindow} window. Setting the hide method to NONE stops SnoopDos from running in the background at all. The Hide menu and gadget options will be disabled, and when you click on the main window's Close gadget, SnoopDos will exit completely, rather than just hiding itself. The INVISIBLE hide method completely removes all traces of SnoopDos from the screen. The only way to re-activate it is to use the currently defined commodity @{" HotKey " link HotKey}, use the Show Interface option in the commodities exchange, or send a @{" Show " link Show} command to SnoopDos (double-clicking on the SnoopDos program icon will do this). The ICONIFY hide method is similar to INVISIBLE, but creates an AppIcon on the Workbench desktop whenever SnoopDos is hidden. SnoopDos can then be re-activated by double-clicking on the AppIcon. The image used for the AppIcon will be the same as the SnoopDos program icon if possible; if no icon was found, a simple built-in image is used instead. The icon position will be automatically selected by Workbench; if you prefer, you can select a fixed position using the @{" IconPos " link IconPos} command. The TOOLSMENU hide method creates an entry on the Workbench Tools menu entitled "Show SnoopDos". Selecting this menu item will automatically re-open the SnoopDos window. Note that the SnoopDos hot key can be used to re-activate the main window at all times, even if SnoopDos is not currently hidden. See also: @{" Command Index " link CommandIndex} @{" Hide " link Hide} @{" HotKey " link HotKey} @{" Show " link Show} @ENDNODE @NODE HideStatus @TITLE "HideStatus command" Command: HIDESTATUS This command tells SnoopDos to disable the display of the @{" Status line " link StatusLine} gadget in the @{" Main " link MainWindow} window. It is also available as a menu option on the Windows menu. The status line is not strictly necessary, but it provides a useful "at-a-glance" summary of whether or not a log file is currently open, and whether SnoopDos is currently @{" paused " link Pause} or @{" disabled " link Disable}. Some people prefer to sacrifice the status line to allow more lines of event output to be displayed in the main window. If you are doing this, you may like to also hide the @{" button " link HideGadgets} gadgets, which will allow the maximum number of lines of text to be displayed. SnoopDos automatically writes this command to the settings file when you save settings. See also: @{" Command Index " link CommandIndex} @{" HideGadgets " link HideGadgets} @{" ShowGadgets " link ShowGadgets} @{" ShowStatus " link ShowStatus} @{" TextSpacing " link TextSpacing} @ENDNODE @NODE HOTKEY @TITLE "HotKey command" Command: HOTKEY "key description" Example: HOTKEY "ctrl alt d" This command allows you to select what key sequence is used to open the SnoopDos main window when it is hidden. This corresponds to the Hotkey gadget in the @{" Settings " link SettingsWindow} window. It is a synonym for the @{" CX_PopKey " link CX_PopKey} command. Any standard commodities key description can be given. You can always tell which key sequence is currently in use by looking at the titlebar of the @{" Main " link MainWindow} window. If you enter an incorrect description, then the titlebar will display "". When you have defined a hotkey, SnoopDos can be called up at any time by pressing that key sequence. If the main window was already open, it will be brought to the front and activated. If it was open, but on a different screen, it will be re-opened on the current screen (as selected using the @{" ScreenType " link ScreenType} command). SnoopDos automatically writes this command to the settings file when you save settings. See also: @{" Command Index " link CommandIndex} @{" CX_PopKey " link CX_PopKey} @{" CX_Popup " link CX_Popup} @{" CX_Priority " link CX_Priority} @ENDNODE @NODE IconPos @TITLE "IconPos command" Command: ICONPOS=, Example: ICONPOS=500,300 This command defines the position of the AppIcon created by SnoopDos when it is running in an Iconified state. Normally, the AppIcon will be automatically positioned in an appropriate position on the screen, but you may sometimes want to override this with your own preferred co-ordinates. Setting the position to -1,-1 allows Workbench to choose the best position once again. Note that there is no way to set this option from within SnoopDos; you must change it by editing the SnoopDos @{" default settings " link SettingsFiles} file directly, or by adding it as a tooltype to the SnoopDos icon. SnoopDos automatically writes this command to the settings file when you save settings. See also: @{" Command Index " link CommandIndex} @{" HideMethod " link HideMethod} @ENDNODE @NODE IgnoreShell @TITLE "IgnoreShell command" Command: IGNORESHELL NOIGNORESHELL This command enables or disables SnoopDos's Ignore Workbench/Shell setting. This setting can also be controlled via a gadget in the @{" Function " link FunctionWindow} window. When this is enabled, SnoopDos will ignore all system calls made by Workbench, or by any shell processes or background CLI's that don't currently have a command loaded. This can reduce the amount of output substantially. If you have the @{" MonitorROMCalls " link MonitorROMCalls} option enabled, then most Workbench and Shell activity will be automatically ignored anyway. In that case, you mays prefer to leave this option disabled, since it will speed up SnoopDos's monitoring a little. Note: if you enable MonitorROMCalls and disable IgnoreShell, then you can see which tooltypes Workbench looks for by default whenever it starts a program from an icon. SnoopDos automatically writes this command to the settings file when you save settings. See also: @{" Command Index " link CommandIndex} @{" MatchName " link MatchName} @{" MonitorROMCalls " link MonitorROMCalls} @ENDNODE @NODE Language @TITLE "Language command" Command: LANGUAGE "languagename" Example: LANGUAGE "english" This command is used to define the language used by SnoopDos to display all menus, windows, and requesters. SnoopDos has built-in support for English, but can also support other languages via external language catalog files. At this time, SnoopDos only supports English. However, I expect to release localised versions over the next few months. If you track down the SnoopDos source code archive on AmiNet, you will find it contains a catalog description file that will enable you to create your own language catalog. If you would like to create a catalog for your native language, please @{" email " link Author} me first in case someone has already performed the translation. Unlike most other commands, the LANGUAGE command only makes sense when specified as either an icon ToolType or a CLI command line option. This is because SnoopDos needs to read the language file very early on during its startup initialisation, in order to allow it to display error messages in the correct language. Normally, you should never need to use this command -- SnoopDos will automatically try and use one of the languages defined in the system Locale preferences, only falling back to English if an appropriate catalog file can't be located. However, if you are developing a new catalog file for SnoopDos, then this command can be useful since it allows you to tell SnoopDos to use your new catalog file during testing. SnoopDos will look for the language you specify in two separate places. The first is "PROGDIR:Catalogs//SnoopDos.catalog" and the second is "LOCALE:Catalogs//SnoopDos.catalog". You can override these defaults by including a full path name to the directory containing the SnoopDos.catalog file. For example, setting LANGUAGE="ram:" will look for the catalog file "ram:SnoopDos.catalog". If you do this, you will need to temporarily alter the name given in the ##language line of your translation (.CT) file to read "##language ram:" as well, or locale.library will not recognise the generated catalog as valid. Also remember to AVAIL FLUSH after quitting SnoopDos, since otherwise locale.library will keep a copy of the first catalog file loaded into memory and ignore the new version on disk. See also: @{" Command Index " link CommandIndex} @ENDNODE @NODE LeftAligned @TITLE "LeftAligned command" Command: LEFTALIGNED This command controls how the @{" Target name " link Format_TargetName} output field is displayed in the main window. It is also available as a sub option to the Target Name menu option on the Windows menu. Left aligned is the normal state of the Target Name field; in this mode, it behaves just like all the other output event columns. See the discussion under @{" RightAligned " link RightAligned} for more information. SnoopDos automatically writes this command to the settings file when you save settings. See also: @{" Command Index " link CommandIndex} @{" RightAligned " link RightAligned} @{" ShowFullPaths " link ShowFullPaths} @ENDNODE @NODE LoadDefSettings @TITLE "LoadDefSettings command" Command: LOADDEFSETTINGS This command reads in the default settings file, as defined by the @{" Settings " link Settings} command. The @{" Last Saved " link Menu_Last_saved} option on the Settings menu will usually do the same thing. If no file has been explicitly defined, then the file that was loaded during startup will be reloaded. If no such file could be found, then it will attempt to load ENVARC:SnoopDos.prefs. See also: @{" Command Index " link CommandIndex} @{" LoadSettings " link LoadSettings} @{" SaveDefSettings " link SaveDefSettings} @{" SaveSettings " link SaveSettings} @{" Settings " link Settings} @ENDNODE @NODE LoadSeg @TITLE "LoadSeg command" Command: LOADSEG NOLOADSEG This command enables or disables monitoring of the LoadSeg() and NewLoadSeg() dos.library functions. It is also available as a gadget in the @{" Function " link FunctionWindow} window. These functions are called to load an executable module from disk into memory, where it can be executed. You are mostly likely to see these functions being called by the @{" ramlib " link PatchRamLib} process, which is responsible for loading in libraries and devices from disk. You may also see these being used to load in fonts and keymaps. Sometimes, an application will call LoadSeg() directly to load a sub-component of the program which has not yet been needed. If you see LoadSeg() being called with no apparent name, this indicates that an application is loading an overlay -- a part of the application which has remained on disk until it was needed, to help conserve memory. Functionally, both LoadSeg() and NewLoadSeg() are identical. The main difference is that NewLoadSeg() was not introduced until Kickstart 2.04, and may in the future gain some additional options that are not available with LoadSeg(). SnoopDos automatically writes this command to the settings file when you save settings. See also: @{" Command Index " link CommandIndex} @ENDNODE @NODE LoadSettings @TITLE "LoadSettings command" Command: LOADSETTINGS "settingsfile" LOADSETTINGS "con:////SnoopDos Command Window/CLOSE" Example: LOADSETTINGS "ram:SnoopDos.prefs" This command reads in a SnoopDos settings file. It is also available as a menu item on the Settings menu. A settings file is any ascii text file which contains valid SnoopDos commands, one per line. The file must contain the following text on the first line to be recognised as a settings file: Anything between a semicolon and the end of a line will be treated as a comment and ignored. Settings files are usually used to store a particular combination of SnoopDos settings that define what functions will be monitored etc. However, they can also contain other commands which perform actions like opening or closing windows or log files. If the filename you specify is an interactive file (i.e. a CON: window) then LoadSettings behaves slightly differently. It prints a command prompt in the window, and allows you to type in commands directly at the keyboard. This lets you try out any SnoopDos command interactively and see the effect it has. Note however that as long as the console window is open, other SnoopDos operations will be suspended. See also: @{" Command Index " link CommandIndex} @{" LoadDefSettings " link LoadDefSettings} @{" SaveDefSettings " link SaveDefSettings} @{" SaveSettings " link SaveSettings} @{" Settings " link Settings} @ENDNODE @NODE Lock @TITLE "Lock command" Command: LOCK NOLOCK This command enables or disables monitoring of the Lock() dos.library function. It is also available as a gadget in the @{" Function " link FunctionWindow} window. A program usually calls Lock() to check whether or not a file actually exists. It can also use Lock() to locate a directory so that it can access the files within that directory. A file or directory can be locked for Read access, where several programs are free to access it at the same time, or Write access, where the program requires exclusive control with no interruptions. The @{" Options " link Format_Options} output field displays which access mode a program asked for. You may occasionally see an access mode of "Read???" -- this indicates that a program has forgotten to specify which access mode was required. Most AmigaDOS disk devices will assume that Read was intended, but some may be confused, causing the program to work incorrectly on those devices. SnoopDos automatically writes this command to the settings file when you save settings. See also: @{" Command Index " link CommandIndex} @{" ChangeDir " link ChangeDir} @{" Open " link Open} @ENDNODE @NODE LockScreen @TITLE "LockScreen command" Command: LOCKSCREEN NOLOCKSCREEN This command enables or disables monitoring of the LockPubScreen() intuition.library function. It is also available as a gadget in the @{" Function " link FunctionWindow} window. Many modern programs support Intuition public screens -- screens similar to the Workbench screen, but possibly with a different resolution and number of colours. Monitoring this function allows you to see if a program expects to find a public screen with a particular name. If it finds such a screen, it may choose to open there rather than on the Workbench. You can use one of the many public screen manager utilities to create a screen with a particular name. In fact, SnoopDos itself has the ability to open on a named public screen -- for more information, see the @{" ScreenType " link ScreenType} command. SnoopDos automatically writes this command to the settings file when you save settings. See also: @{" Command Index " link CommandIndex} @ENDNODE @NODE LogFormat @TITLE "LogFormat command" Command: LOGFORMAT "formatstring" LOGFORMAT NONE Example: LOGFORMAT "%t %p %a %n %o %r" This command is similar to the @{" Format " link Format} command, but instead of controlling the format of the events displayed in the @{" Main " link MainWindow} window, it controls the format of events written to the log file. It is also available as a gadget in the @{" Settings " link SettingsWindow} window. Normally, you won't need to use this. If no log format has been defined, then SnoopDos will use the current main window format instead. However, occasionally you may prefer to use a custom format. For example, you may have a large Workbench screen which can display 130 columns of text in the main window, but you would like your log files to fit on an 80 column display. The format string specified is identical to that used for the Format command. Usually, the quickest way to design a new log format is to set the main window to 79 columns using the @{" Change window width " link Menu_Change_window_width} menu option and then use the @{" Format editor " link FormatEditor} to choose what items you want displayed. Once you are happy with the format in the main window, you can quickly copy it to the log format by using the @{" Copy " link SettingsCopy} gadget in the Settings window. The special keyword NONE is used to tell SnoopDos to stop using a custom log format and just use whatever format is installed in the main window instead. This is equivalent to just giving an empty format string, but is often more convenient to use from within an ARexx script. Note that when SnoopDos is writing to a log file, it automatically leaves the first character on each line blank (see @{" OpenLog " link OpenLog} for more details). As a result, a log format that's 79 characters wide produces lines of 80 characters in the log file. SnoopDos automatically writes this command to the settings file when you save settings. See also: @{" Command Index " link CommandIndex} @{" Format " link Format} @{" Format editor " link FormatEditor} @{" OpenLog " link OpenLog} @ENDNODE @NODE LogMode @TITLE "LogMode command" Command: LOGMODE=PROMPT | APPEND | OVERWRITE | SERIALPORT Example: LOGMODE=PROMPT This command determines the precise operation of the @{" Open Log " link MainOpenLog} gadget in the main window. It is also available as a gadget in the @{" Settings " link SettingsWindow} window. When the log mode is set to PROMPT (the most common choice), then the main window gadget will be titled "Open Log...", and selecting it will produce an ASL file requester allowing a log file to be chosen. If the chosen file already exists, SnoopDos will display a requester allowing you to overwrite or append to it. When a file requester is displayed, you are not limited to entering only filenames -- you can also enter device names such as PRT:, CON:////, or AUX:. When the log mode is set to APPEND, the main window gadget will be titled "Append Log" and selecting it will automatically open the log file defined using the @{" LogName " link LogName} command in append mode. This is convenient if you like all logging information to be captured into a single file, and prefer not to have to deal with the ASL file requester. The OVERWRITE log mode is similar to APPEND, but the main window gadget now reads "Start Log". When that gadget is selected, the filename defined with the @{" LogName " link LogName} command is overwritten with the new log information. This is most appropriate if you frequently log to a device, such as the printer (PRT:) or perhaps a console window -- you can set the log name accordingly and then easily turn on or off logging to that device with a single click of the mouse. If you are logging to a console window, note that the old SnoopDos 1.x control keys still operate. CTRL-D and CTRL-E can be used to disable and enable logging, and in addition, CTRL-F will bring the main SnoopDos window back to the foreground again. CTRL-C will quit SnoopDos entirely, so be careful not to press it by mistake. The SERIAL PORT log mode will send the log output directly to a serial debugging terminal connected to the internal serial port. This is mainly intended for programmers. It is particularly useful if you use Carolyn Scheppner's useful Sushi utility to redirect debugging output to a window or file, since it allows SnoopDos output to be interleaved with output from other tools like @{" Enforcer " link SegTracker} and Mungwall. When this option is chosen, the main window gadget is titled "Serial Log". Note that even when the log mode is APPEND, OVERWRITE or SERIAL PORT, you can still open a log file via the ASL file requester by choosing the @{" Open Log " link Menu_Open_log} menu item on the Project menu. SnoopDos automatically writes this command to the settings file when you save settings. See also: @{" Command Index " link CommandIndex} @{" AppendLog " link AppendLog} @{" OpenLog " link OpenLog} @{" OpenSerialLog " link OpenSerialLog} @ENDNODE @NODE LogName @TITLE "LogName command" Command: LOGNAME "logfile" Example: LOGNAME "PRT:" This command defines the default log filename to be used when the current @{" LogMode " link LogMode} is set to either APPEND or OVERWRITE. It is also available as a gadget in the @{" Settings " link SettingsWindow} window. The APPEND and OVERWRITE log modes allow the ASL file requester to be bypassed when opening a log file; this is convenient if you frequently log output to a single file or device. If you are using a log mode of PROMPT, where an ASL file requester is displayed to let you choose a log file, then the first default filename supplied to the ASL requester will match the currently defined LogName. This is useful if you usually log to the same file, but prefer to be able to easily change to a different filename if you want to. SnoopDos automatically writes this command to the settings file when you save settings. See also: @{" Command Index " link CommandIndex} @{" LogMode " link LogMode} @ENDNODE @NODE MainWindowPos @TITLE "MainWindowPos command" Command: MAINWINDOWPOS=, Example: MAINWINDOWPOS=0,20 This command is used to change the position of the main window on the current screen. If the function window is open, then it is moved immediately, else it will appear in the new position the next time it is opened. and are the pixel co-ordinates of the upper left corner of the window. SnoopDos automatically writes this command to the settings file when you save settings. See also: @{" Command Index " link CommandIndex} @{" Main window " link MainWindow} @ENDNODE @NODE MainWindowSize @TITLE "MainWindowSize command" Command: MAINWINDOWSIZE=, Example: MAINWINDOWSIZE=640,150 This command is used to change the current dimensions of the main window. If the main window is open, then it is resized immediately, else it will appear with the new size the next time it is opened. and are the new dimensions of the window in pixels. In addition to using this command, or manually resizing the window with the mouse, you can also use the @{" WindowWidth " link WindowWidth} command to define the width of the window in text columns rather than pixels. SnoopDos automatically writes this command to the settings file when you save settings. See also: @{" Command Index " link CommandIndex} @{" Main window " link MainWindow} @ENDNODE @NODE MakeDir @TITLE "MakeDir command" Command: MAKEDIR NOMAKEDIR This command enables or disables monitoring of the CreateDir() dos.library function. It is also available as a gadget in the @{" Function " link FunctionWindow} window. (The command name has been chosen to match the CLI command of the same name, which is more familiar to most users than CreateDir). Programs call this function to create a new directory on disk. This is most commonly done during installation, where an application creates a special directory to hold data or project files. SnoopDos automatically writes this command to the settings file when you save settings. See also: @{" Command Index " link CommandIndex} @ENDNODE @NODE MakeLink @TITLE "MakeLink command" Command: MAKELINK NOMAKELINK This command enables or disables monitoring of the MakeLink() dos.library function. It is also available as a gadget in the @{" Function " link FunctionWindow} window. This function is called to create a file link on disk, which provides a new name for an existing file, while retaining the original name as well. Unlike the Copy command, this approach does not require a second copy of the file to be stored, which saves disk space. There are two types of Link: Hard and Soft. Hard links can only reside on the same partition as the original file. Once created, they become indistinguishable from the original; if the original file is deleted, then the hard link automatically takes its place. Soft links can be created on any disk or partition, not just that which contained the original file. However, if the original file is deleted, then the soft link becomes useless. The @{" Target name " link Format_TargetName} output field will show the link information in the form "Newlink --> original_file". The @{" Options " link Format_Options} output field will show "Soft" or "Hard" according to the link type. SnoopDos automatically writes this command to the settings file when you save settings. See also: @{" Command Index " link CommandIndex} @ENDNODE @NODE MatchName @TITLE "MatchName command" Command: MATCHNAME "pattern" Example: MATCHNAME "~(Yak|TurboText)" This command lets you define what programs SnoopDos should or should not monitor. It is also available as a gadget in the @{" Function " link FunctionWindow} window. The pattern you give is a standard case-insensitive AmigaDOS pattern. This will be compared with the name of each process that calls any of the functions currently being monitored; only those processes with names that match the pattern will be displayed. Typically, you will use the MatchName to ensure that certain programs are automatically ignored by SnoopDos. For example, the TurboText text editor has the annoying feature of calling CurrentDir() every time you type a key. Similarly, the Yak commodity calls OpenDevice() every time you type a key when you have key-click enabled. You can use the MatchName pattern shown in the example above to prevent the event buffer from being quickly filled with useless events. In general, you can make SnoopDos ignore several different programs by using a pattern of the form "~(prog1|prog2|prog3|prog4|...)", repeating for as many program names as required. Another less common use for MatchName is to monitor only those events generated by one particular program. For example, a MatchName of "Multiview" would ignore any function calls by programs other than Multiview. A MatchName of "Multiview|AmigaGuide" would monitor calls by either Multiview or AmigaGuide. If a program you're trying to monitor may be run from a Shell rather than Workbench, you may wish to prefix its name with "#?" in the pattern, to ensure that any preceding pathname is ignored. For example: "#?Multiview|#?AmigaGuide". SnoopDos automatically writes this command to the settings file when you save settings. See also: @{" Command Index " link CommandIndex} @ENDNODE @NODE MonitorPackets @TITLE "MonitorPackets command" Command: MONITORPACKETS NOMONITORPACKETS This command enables or disables SnoopDos's MonitorPackets setting. This setting can also be controlled via a gadget in the @{" Function " link FunctionWindow} window. Some programs, particularly those written using GNU C and linked with ixemul.library, bypass the normal dos.library functions and communicate directly with DOS devices using packet I/O. Normally, SnoopDos can't detect such activity. However, if you enable this option, then SnoopDos will monitor the PutMsg() exec.library function. This allows packets to be detected, and displayed in the SnoopDos window just like normal function calls. When a packet is spotted that corresponds to one of the currently monitored DOS functions, the @{" Action " link Format_Action} output field will display the packet type (e.g. Open, Lock, MakeDir, etc.) but it will be prefixed by '*' to indicate that direct packet i/o was involved. Thus, in the examples given, you will see *Open, *Lock, *MakeDir, etc. SnoopDos can monitor packet versions of the following functions: @{" Delete " link Delete} @{" Lock " link Lock} @{" MakeDir " link MakeDir} @{" MakeLink " link MakeLink} @{" Open " link Open} @{" Rename " link Rename} Enabling MonitorPackets can potentially slow down your system, since PutMsg() is one of the most frequently called system functions. Thus, it should only be enabled if you encounter a program that appears to be opening files but which doesn't show up under normal monitoring. Packet operations carried out by AmigaDOS on behalf of an application will not usually be reported by SnoopDos -- this is because there is no need; the corresponding AmigaDOS function will be reported instead. However, if you enable @{" MonitorROMCalls " link MonitorROMCalls} at the same time as MonitorPackets, then you may find some events being listed twice: once as a DOS function, and once as a packet operation. Sometimes SnoopDos is unable to determine the result code of a packet operation. This can happen if you stop monitoring packets while that operation is incomplete, or occasionally when there is heavy packet activity (SnoopDos can keep track of about 5 outstanding packets at any one time). When this happens, the Result field will display "Missed" to indicate it has given up. If you need more information than that provided by MonitorPackets, you can use the @{" PacketDebugger " link PacketDebugger} option. This lets you monitor every single packet sent by an application to a DOS device, though since it generates vast quantities of raw output, it is really only intended for device driver programmers. SnoopDos automatically writes this command to the settings file when you save settings. See also: @{" Command Index " link CommandIndex} @{" MonitorROMCalls " link MonitorROMCalls} @{" PacketDebugger " link PacketDebugger} @ENDNODE @NODE MonitorROMCalls @TITLE "MonitorROMCalls command" Command: MONITORROMCALLS NOMONITORROMCALLS This command enables or disables SnoopDos's MonitorROMCalls setting. This setting can also be controlled via a gadget in the @{" Function " link FunctionWindow} window. When a program calls a system function, that function may in turn trigger internal calls to other system functions. For example, calling OpenLibrary() may result in calls being made to FindResident() and Open() as well. Usually, these additional calls just add to the clutter and aren't needed, so by default SnoopDos doesn't display any calls made by the operating system (i.e. from within the ROM). However, sometimes it can be useful to see these, especially if all else fails. Turning on this option tells SnoopDos to go ahead and print function calls made from within the ROM, along with all the calls made by user applications. Be warned though: this can often double the amount of output produced! If you enable MonitorROMCalls, then you will probably want to ensure that @{" IgnoreShell " link IgnoreShell} is also enabled, to make SnoopDos ignore output generated by Workbench or the Shell. One thing to be aware of is that SnoopDos can only check if a function call has been from ROM by looking at the return address on the stack. If another program has patched a function call after SnoopDos, then SnoopDos will see all calls to the function as coming from that program rather than from the original caller, and so won't ignore them. One such example is the OpenLibrary() call, which is patched by the CodeProbe debugger. SnoopDos automatically writes this command to the settings file when you save settings. See also: @{" Command Index " link CommandIndex} @{" MonitorPackets " link MonitorPackets} @{" PacketDebugger " link PacketDebugger} @ENDNODE @NODE OnlyShowFails @TITLE "OnlyShowFails command" Command: ONLYSHOWFAILS NOONLYSHOWFAILS This command enables or disables SnoopDos's OnlyShowFails setting. This setting can also be controlled via a gadget in the @{" Function " link FunctionWindow} window. Depending on the functions you have enabled, SnoopDos can provide vast quantities of output. Enabling OnlyShowFails provides an easy way to reduce the amount of output you see, while still retaining information that is likely to be of interest. This is achieved, as the name implies, by only showing those functions which failed -- any function call which is successful is not listed. You need to be a little wary when using this option, since it is possible to be misled if you are not careful. Often, a program may search for files or other information in several places. If the first two attempts fail, but the third succeeds, you will only see information about the two failed attempts and may incorrectly surmise that the program is in trouble. Thus, while OnlyShowFails is useful for identifying potential problems early on (and saving valuable space in the event buffer), it's best to turn it off when you are diagnosing an actual program failure. SnoopDos automatically writes this command to the settings file when you save settings. See also: @{" Command Index " link CommandIndex} @ENDNODE @NODE Open @TITLE "Open command" Command: OPEN NOOPEN This command enables or disables monitoring of the Open() dos.library function. It is also available as a gadget in the @{" Function " link FunctionWindow} window. If you only choose to monitor one function, the Open() function will usually provide the most useful information, since missing configuration files are one of the most common reasons an application will not run. Note however that an application may do other checks to determine if a file actually exists, before trying to open it. The most common method is to use the @{" Lock " link Lock} function to try and locate the file. Another alternative, and one which SnoopDos can't easily monitor, is to scan a directory looking at all files in that directory. If you suspect this is happening, you can use SnoopDos's @{" PacketDebugger " link PacketDebugger} option to watch out for this, but be prepared to sift through a lot of superfluous output.) Files may be opened in one of three modes: Read, Write or Modify. Read implies that the file will only be read, not modified. Write implies that a new file should be created, overwriting any file that already exists. Modify is used to write to an already existing file (or to create a new file if none exists). The @{" Options " link Format_Options} output field indicates the mode used to open the file. SnoopDos automatically writes this command to the settings file when you save settings. See also: @{" Command Index " link CommandIndex} @{" Lock " link Lock} @ENDNODE @NODE OpenDevice @TITLE "OpenDevice command" Command: OPENDEVICE NOOPENDEVICE This command enables or disables monitoring of the OpenDevice() exec.library function. It is also available as a gadget in the @{" Function " link FunctionWindow} window. Almost every non-trivial program needs to use devices, and this is the function called to provide access to each device. Monitoring of OpenDevice() can result in quite a lot of output, most of which isn't very useful. If you're only interested in the devices that a program needs to open but can't, they will show up under the output from @{" LoadSeg " link LoadSeg} since the Amiga automatically tries to load any device it can't find in memory from the DEVS: directory. When this function is being monitored, the @{" Options " link Format_Options} output field will show the unit number of the device the program is trying to open. Note to OS experts: All OpenDevice() calls made by CON processes are ignored by SnoopDos. This is because CON frequently opens timer.device, sometimes many times a second, and reporting all these events would quickly fill up the event buffer with useless output. SnoopDos automatically writes this command to the settings file when you save settings. See also: @{" Command Index " link CommandIndex} @{" OpenLibrary " link OpenLibrary} @ENDNODE @NODE OpenFont @TITLE "OpenFont command" Command: OPENFONT NOOPENFONT This command enables or disables monitoring of the OpenFont() graphics.library function. It is also available as a gadget in the @{" Function " link FunctionWindow} window. OpenFont() is called to locate a particular font for display on the screen. The @{" Options " link Format_Options} output field shows the size of the font that's being requested. Usually, there is no need to monitor this function -- if a program can't locate a font in memory, AmigaDOS will automatically try and load it from the FONTS: directory on disk, and it will be displayed under @{" LoadSeg " link LoadSeg}. If you want to see every font used by a program, however, then this is the function to use. SnoopDos automatically writes this command to the settings file when you save settings. See also: @{" Command Index " link CommandIndex} @ENDNODE @NODE OpenFormat @TITLE "OpenFormat command" Command: OPENFORMAT This command opens the @{" Format editor " link FormatEditor} window. You can also open the format editor by selecting the @{" Show format " link Menu_Show_format} menu item on the Windows menu, or by double-clicking on the header line in the @{" Main " link MainWindow} window. Yet another way to open the format editor is using the "Edit..." gadget in the @{" Setup " link SettingsWindow} window. See also: @{" Command Index " link CommandIndex} @{" CloseFormat " link CloseFormat} @{" FormatWindowPos " link FormatWindowPos} @ENDNODE @NODE OpenFunction @TITLE "OpenFunction command" Command: OPENFUNCTION This command opens the @{" Function " link FunctionWindow} window. You can also open the function window by selecting the @{" Show functions " link Menu_Show_functions} item on the Windows menu, or by selecting the "Functions..." gadget in the main window. If your Amiga only has a 68000, you may find that the function window takes a long time to open the first time you access it. This is due to the large number of gadgets it contains. SnoopDos only needs to create the gadgets the first time the window is opened; on the second and subsequent openings, you should find it much quicker. See also: @{" Command Index " link CommandIndex} @{" CloseFunction " link CloseFunction} @{" FunctionWindowPos " link FunctionWindowPos} @ENDNODE @NODE OpenLibrary @TITLE "OpenLibrary command" Command: OPENLIBRARY NOOPENLIBRARY This command enables or disables monitoring of the OpenLibrary() exec.library function. It is also available as a gadget in the @{" Function " link FunctionWindow} window. It's impossible to write a useful program on the Amiga that doesn't call OpenLibrary() at least once. It provides access to the Amiga's multitude of shared libraries. In general, a program will fail to run if it can't find a particular library. However, normally such failed attempts will show up as @{" LoadSeg " link LoadSeg} events, because if AmigaDOS can't find a library in memory, it will try and load it from the LIBS: directory instead. A program won't necessarily stop working if it can't find a particular library; it may just disable some of its features. For example, SnoopDos itself can run without the Commodities or ASL libraries being present, but if they're not around, you won't be able to Hide the main window or call up file and font requesters. The @{" Options " link Format_Options} output field gives the version number of the library being opened. This is useful information, because if a program can't open a library, you can then see the minimum version of the library you must install. Note that SnoopDos automatically ignores all attempts to open dos.library. This is necessary to avoid a few subtle problems that can otherwise occur. Since dos.library must exist to even load the program in the first place, you won't miss out on anything important by not seeing these events. SnoopDos automatically writes this command to the settings file when you save settings. See also: @{" Command Index " link CommandIndex} @{" OpenDevice " link OpenDevice} @ENDNODE @NODE OpenLog @TITLE "OpenLog command" Command: OPENLOG "filename" Example: OPENLOG "ram:snoopdos.log" This command opens a new log file. Any new output displayed in the main SnoopDos window will be written to this file. If the file already exists, it will be overwritten. You can also open a new log file from within SnoopDos by choosing the @{" Open log " link Menu_Open_log} menu option on the Project menu, or by using the @{" Open Log " link MainOpenLog} button in the @{" Main " link MainWindow} window. When SnoopDos displays events in the main window, it can easily handle several different events taking place simultaneously. For example, one program might call RunCommand() to start a command executing, and that command may itself open several files. SnoopDos can display information about those open actions even though the previous RunCommand() call has not yet completed. When the RunCommand() does complete, SnoopDos goes back and fills in the result code accordingly. When outputting events to a log file, it's not so easy to go back and fill in the result field after several additional events have occurred. For example, the log file may actually be a printer or some other device that doesn't allow backtracking. To avoid this problem, SnoopDos behaves slightly differently when printing events to a log file. It will usually wait until an event is fully completed before it tries to output it to the file. However, if a new event arrives before the current event is complete, SnoopDos will output as much of the current event as possible. To show that the event is incomplete, it outputs a '/' character in the first column of the line. Later on, when that event finally completes, SnoopDos will output the entire line a second time, but this time with the result filled in. To indicate that this is the completion of an earlier event, the first column will contain a '\\', to match the '/' used earlier. If you anticipate this happening a lot, it's a good idea to include the @{" Count " link Format_Count} output field in your log format. This will include a sequence number on each line, and you can then easily match each incomplete event with the final completed version since both lines of output will have the same number. See also: @{" Command Index " link CommandIndex} @{" AddLog " link AddLog} @{" AppendLog " link AppendLog} @{" CloseLog " link CloseLog} @{" FlushLog " link FlushLog} @{" LogFormat " link LogFormat} @{" OpenSerialLog " link OpenSerialLog} @ENDNODE @NODE OpenResource @TITLE "OpenResource command" Command: OPENRESOURCE NOOPENRESOURCE This command enables or disables monitoring of the OpenResource() exec.library function. It is also available as a gadget in the @{" Function " link FunctionWindow} window. Resources are typically used to provide very low-level access to standard Amiga hardware, such as the gameport, CIA chips, battery-backed clock, floppy disk, etc. You can monitor OpenResource() to see if a program is trying to access the hardware directly in a system-legal manner. Of course, programs that break the rules and don't allocate hardware properly before using it won't show up (but your system will probably have crashed by then anyway). SnoopDos automatically writes this command to the settings file when you save settings. See also: @{" Command Index " link CommandIndex} @ENDNODE @NODE OpenSerialLog @TITLE "OpenSerialLog command" Command: OPENSERIALLOG This command opens a new log file. Unlike normal log files, the output from this will be directed to a debugging terminal connected to the internal serial port. You can configure the "Open Log" button in the @{" Main " link MainWindow} window to perform this command by setting the @{" LogMode " link LogMode} to SERIALPORT. This is mainly intended for programmers. It is particularly useful if you use Carolyn Scheppner's useful Sushi utility to redirect debugging output to a window or file, since it allows SnoopDos output to be interleaved with output from other tools like @{" Enforcer " link SegTracker} and Mungwall. See the @{" OpenLog " link OpenLog} documentation for more information about how SnoopDos outputs information to a log file. See also: @{" Command Index " link CommandIndex} @{" AddLog " link AddLog} @{" AppendLog " link AppendLog} @{" CloseLog " link CloseLog} @{" FlushLog " link FlushLog} @{" LogFormat " link LogFormat} @{" OpenLog " link OpenLog} @ENDNODE @NODE OpenSetup @TITLE "OpenSetup command" Command: OPENSETUP This command opens the @{" Setup " link SettingsWindow} window. You can also open the setup window by selecting the @{" Show setup " link Menu_Show_setup} menu item on the Windows menu, or by selecting the "Setup..." gadget in the main window. See also: @{" Command Index " link CommandIndex} @{" CloseSetup " link CloseSetup} @{" SetupWindowPos " link SetupWindowPos} @ENDNODE @NODE PacketDebugger @TITLE "PacketDebugger command" Command: PACKETDEBUGGER NOPACKETDEBUGGER This command enables or disables SnoopDos's Packet debugger. This setting can also be controlled via a gadget in the @{" Function " link FunctionWindow} window. The packet debugger provides a way to snoop on packets sent to any mounted filesystem device. This is mainly of use to device driver writers, but can also occasionally be useful if you want to monitor DOS operations not directly supported by SnoopDos, such as Examine()/ExNext(). When the packet debugger is first enabled, SnoopDos makes a list of currently mounted devices. Only packets sent to those devices are monitored. If a new device is mounted while the debugger is running, SnoopDos will usually automatically add it to this list. However, if the device has been mounted using a third-party mount command, you may need to disable and re-enable the packet debugger to get SnoopDos to recognise packets destined for the new device. The first time you enable the packet debugger, you may find that it doesn't seem to have much effect. This is because almost all packets to DOS devices are generated by dos.library, and dos.library is in ROM. By default, SnoopDos ignores any packet activity generated by ROM calls. Enable the @{" MonitorROMCalls " link MonitorROMCalls} setting to change this. SnoopDos can identify all of Commodore's officially defined packets, as of Kickstart 3.0, and can also recognise a few third party packets, as listed in Ralph Babel's excellent book, The Amiga Guru Guide. The name of each packet is displayed in the @{" Action " link Format_Action} output field. Each name is shown in capitals and is prefixed with '#', to help distinguish the output from normal monitored functions. If SnoopDos doesn't recognise a packet, then the packet type will be shown in the form "#(nnn)" where nnn is the packet type code in decimal. Most packets take one or more parameters (dp_Arg1, dp_Arg2, etc). These parameters are listed in the @{" Target name " link Format_TargetName} field as 32-bit hex numbers. The interpretation of each number depends on the packet; see Ralph's book for a comprehensive explanation. The @{" Options " link Format_Options} field shows the name of the device to which the packet is being sent. Finally, the @{" Result " link Format_Result} field shows the return value from the packet. Most packets return a single 32-bit value for success, or a fail code and a secondary error code for failure. SnoopDos will display "OK" or "Fail" for each packet, and will also show the actual value returned. For successful packets, this value matches dp_Res1; for failed packets, it matches dp_Res2. (SnoopDos knows that some packets return -1 for failure, while others return 0). Some packets return two values -- in this case, SnoopDos will display both values. Since the default width of the Result field is only four characters, you may need to widen it to view this additional information. This is easily done by simply dragging the right edge of the Result event heading in the main window with the mouse, or by using the @{" Format editor " link FormatEditor}. Sometimes SnoopDos is unable to determine the result code of a packet operation. This can happen if you disable the packet debugger while a packet operation is still in progress, or occasionally if there is heavy packet activity (SnoopDos can remember up to 5 outstanding packets at a time). When this happens, the Result field will displayed "Missed" to indicate SnoopDos has given up waiting for a result. SnoopDos automatically writes this command to the settings file when you save settings. See also: @{" Command Index " link CommandIndex} @{" MonitorPackets " link MonitorPackets} @{" MonitorROMCalls " link MonitorROMCalls} @ENDNODE @NODE PatchRamLib @TITLE "PatchRamLib command" Command: PATCHRAMLIB NOPATCHRAMLIB This command controls whether or not SnoopDos should apply a patch to the ramlib background process (ramlib is responsible for loading libraries and devices from disk, whenever they are needed by a program). This command is slightly unusual in that it must be given on the CLI command line or as an icon tooltype the first time SnoopDos is started, or it will have no effect. If it is not present, the default action is PATCHRAMLIB. Normally, you should never need to use this command. However, if you like to know exactly what's happening to your Amiga, you may want to read on. The reason for this command is because the ramlib process contains a bug in all versions of Kickstart from 2.0 through 3.1. This bug does not show up during normal use, but when SnoopDos is running, the bug can cause a crash during heavy system activity. For those interested, the bug is that ramlib uses SIGB_SINGLE as the signal bit for its message port, which means that system calls made by ramlib cannot safely use this signal for any purpose -- after all, you never know when a new message might arrive at ramlib's message port, causing a SIGB_SINGLE signal. The most critical use of SIGB_SINGLE in the operating system is to synchronise sempahore operations when two tasks are trying to access a single piece of data simultaneously. The reason this doesn't cause a problem in normal use is because ramlib calls very few system functions that depend on SIGB_SINGLE, and those that do (mainly LoadSeg, which locks the device list) usually don't do anything too terrible if it should fail. SnoopDos makes heavy use of semaphores in its patches. This means that any calls from ramlib that it monitors are potentially at risk. Even then, problems only occur when several programs all ask ramlib to load a library or device at the same time. However, when a problem occurs, it causes an instant crash as SnoopDos metaphorically gets its knickers in a twist. To avoid this problem, SnoopDos patches the ramlib process to use a different signal bit (SIGBREAKB_CTRL_E in fact). This patching is performed in a safe way, so that if a future SetPatch ever corrects the bug, it won't cause any conflicts. If you have the SnoopDos source code from Aminet, you can review the patch code in patches.c:InitRamLibPatch(). Despite the efforts to make the patch safe and upwards compatible, it's possible that it may cause problems with some future revision of the operating system. It's also possible that you may not like the idea of a third party utility altering an internal system structure like this. Thus, NOPATCHRAMLIB provides a way to stop SnoopDos from making this change. A side effect of using NOPATCHRAMLIB is that SnoopDos will automatically ignore all calls made by the ramlib process. This obscures some useful information about what libraries and devices are being loaded loaded, but for the most part, you can simply turn on monitoring of @{" OpenLibrary " link OpenLibrary} and @{" OpenDevice " link OpenDevice} and get the same information. Note that any calls made to the @{" FindResident " link FindResident} function by ramlib are automatically ignored by SnoopDos; this helps keep the amount of information displayed in the window to manageable levels. See also: @{" Command Index " link CommandIndex} @{" StackLimit " link StackLimit} @ENDNODE @NODE Pause @TITLE "Pause command" Command: PAUSE This command is used to temporarily pause any programs calling functions monitored by SnoopDos, so that you have a chance to see exactly what each program is trying to do. It is also available as an item on the Project menu, and as a gadget in the @{" Main " link MainWindow} window. You can use the TAB key to unconditionally select Pause (this is sometimes more convenient than pressing the Pause gadget's keyboard shortcut, since that toggles Pause on and off). Pause is particularly useful if you have a program that crashes during startup, because it allows you to step through the program's initial actions as quickly or as slowly as you like. It is also useful if a program is carrying out many actions, too fast for you to read -- you can pause the output temporarily to give you a chance to catch up. While a program is paused, it goes to sleep. At each step, SnoopDos will display the function the program is about to execute, before the call is actually made. To indicate that the program is currently paused, the result field will read "WAIT". When a task is in a WAIT state, you can tell it to execute the current function but immediately pause again the next time it calls a monitored function. This lets you step through a program's function calls one step at a time. The easiest way to do this is to simply press Space on the keyboard, or click the down arrow scroll gadget using the mouse. See the @{" SingleStep " link SingleStep} command for more details. Note that SnoopDos pauses individual tasks, rather than the main SnoopDos program itself. Thus, if three separate programs try to call a monitored function, you will see all three tasks listed in the main window, with three WAITs in the result column. If you select single step, then all three programs are allowed to execute the current call and advance to the next one. If you execute certain file operations while SnoopDos is paused, such as opening a new log file or selecting a new font from the font requester, then SnoopDos will temporarily unpause itself for the duration of the operation. Any tasks which were WAITing when the action began will remain in the WAIT state, but any new calls made during the file activity will be executed as normal (they will still appear in the event buffer of course). This is to prevent deadlocks occurring -- sometimes accessing a file may involve additional operations by an external program. When SnoopDos is paused, system activity can quite literally come to a halt. To prevent you getting into a situation where you cannot select unpause, SnoopDos will automatically unpause itself if you select the @{" Hide " link Hide} command. See also: @{" Command Index " link CommandIndex} @{" SingleStep " link SingleStep} @{"Unpause " link Unpause} @ENDNODE @NODE Quit @TITLE "Quit command" Command: QUIT This command tells SnoopDos to remove all its patches and unload itself from memory. Usually, SnoopDos can quit immediately -- even though it patches many system functions, it uses a technique that allows those patches to be safely removed. However, sometimes when you try to quit, another program will still be executing one of the functions patched by SnoopDos. A typical example is when a program tries to open a file on a disk not currently in any drive, causing a "Please insert volume..." requester to be displayed. Until that requester is acknowledged, SnoopDos won't be able to unload itself from memory. In a situation like this, SnoopDos will check every two seconds to see if it is safe to quit; if not, it goes back to sleep again. After 10 seconds, it displays a warning requester displaying the name of the function that is currently being executed -- this may give you a clue as to what is going on. It is safe to rerun SnoopDos after quitting, even if the first copy is still not finished cleaning up. However, you can quickly use up all your available memory if you do this too many times. See also: @{" Command Index " link CommandIndex} @{" Hide " link Hide} @ENDNODE @NODE ReadToolTypes @TITLE "ReadToolTypes command" Command: READTOOLTYPES NOREADTOOLTYPES This command enables or disables monitoring of two separate functions in icon.library, FindToolType() and MatchToolValue(). It is also available as a gadget in the @{" Function " link FunctionWindow} window. Both these functions are used by programs that can be started from an icon. FindToolType() is used to search the icon for a particular tooltype, and MatchToolValue() is used to check if a recognised tooltype is set to a particular value. This can be very useful for identifying what tooltypes a program looks for in its icon, and what values those tooltypes can take, as programmers often forget to fully document them. Not all programs use these functions, but most do. For MatchToolValue(), the @{" Target name " link Format_TargetName} output field shows the various possible values for the tooltype, with each option separated by a '|' character. The @{" Options " link Format_Options} output field shows the actual contents of the tooltype being checked. SnoopDos automatically writes this command to the settings file when you save settings. See also: @{" Command Index " link CommandIndex} @ENDNODE @NODE Rename @TITLE "Rename command" Command: RENAME NORENAME This command enables or disables monitoring of the Rename() dos.library function. It is also available as a gadget in the @{" Function " link FunctionWindow} window. Rename() is called by an application to change the name of a disk file. Both the old and new file must be on the same partition, but need not be in the same directory. Rename is slightly unusual in that it produces two lines of output in the SnoopDos window; the first line shows the original name of the file, while the second line gives the new name. SnoopDos automatically writes this command to the settings file when you save settings. See also: @{" Command Index " link CommandIndex} @ENDNODE @NODE RightAligned @TITLE "RightAligned command" Command: RIGHTALIGNED This command controls how the @{" Target name " link Format_TargetName} output field is displayed in the main window. It is also available as a sub option to the Target Name menu option on the Windows menu. Normally, there is enough room to fully display the target name associated with each event, so this command isn't needed. However, if you have a narrow target name column, or if you have enabled the @{" ShowFullPaths " link ShowFullPaths} option, resulting in a lot of long target names, then you may find that the names are too wide to fit in the allocated space. When RightAligned is enabled, the rightmost portion of each name will be displayed, instead of the left portion as with all other output fields. This is often more useful, since if there is not enough room to display the entire filename, the rightmost portion includes the actual filename which would otherwise be truncated or discarded. When a target name is too long to display completely, the symbol '«' will appear in the first column of output. This indicates that there are more characters to the left of the displayed information. Many people find it useful to leave the target name display set to @{" LeftAligned " link LeftAligned} most of the time and only switch to right aligned if a particularly long target name appears. Since both modes have associated menu hotkeys (Amiga-[ and Amiga-]), the switch can be made very quickly using the keyboard. SnoopDos automatically writes this command to the settings file when you save settings. See also: @{" Command Index " link CommandIndex} @{" LeftAligned " link LeftAligned} @{" ShowFullPaths " link ShowFullPaths} @ENDNODE @NODE RowQualifier @TITLE "RowQualifier command" Command: ROWQUALIFIER=IGNORE | NONE | SHIFT | ALT | CTRL | ALL Example: ROWQUALIFIER=ALL This command selects what qualifier key (if any) must be pressed before SnoopDos will allow you to highlight a row in the main window by clicking on it with the mouse. The @{" Row selection key " link Menu_Row_selection_key} menu option lets you change this from within the program. SnoopDos allows you to highlight lines in the main window by clicking on them. This provides a convenient way to quickly identify all the components on a single line of output by providing a horizontal guide for your eye to follow. However, if you use a "click to front" commodity such as that supplied with Workbench, you may notice that clicking the SnoopDos window to the front causes a row highlight to be flashed briefly. This can be distracting. Modifying the row qualifier key allows you to avoid this situation. If your system is configured to bring windows to the front when you perform a shift- double-click, then you can set the row qualifier to NONE -- this indicates that rows will only be highlighted when no qualifier key is pressed. Alternatively, if your system is configured to bring windows to the front when you do a double-click without holding shift (or any other qualifier), you can set the row qualifier to SHIFT, ALT or CTRL. This indicates that the named key must be held down in order to highlight a row -- clicking on the row with no key pressed will no longer be sufficient. The ALL option allows rows to be highlighted as long as at least one of the SHIFT, ALT or CTRL keys is pressed (it doesn't matter which one). This is usually more convenient than choosing any single qualifier. Finally, the default setting is IGNORE. When this is selected, SnoopDos doesn't care whether or not a qualifier key is pressed. If you don't use a click-to-front utility, then this is probably the best option to choose. SnoopDos automatically writes this command to the settings file when you save settings. See also: @{" Command index " link CommandIndex} @{" Event output " link EventOutput} @ENDNODE @NODE RunCommand @TITLE "RunCommand command" Command: RUNCOMMAND NORUNCOMMAND This command enables or disables monitoring of the RunCommand() dos.library function. It is also available as a gadget in the @{" Function " link FunctionWindow} window. Applications call RunCommand() to execute a single disk command with a particular set of parameters. The event output produced for this function is a little unusual, because the name shown in the @{" Process name " link Format_ProcessName} output field is usually the name of the command being executed, and not the process making the call. The @{" Target name " link Format_TargetName} field lists only the command line parameters for the command, and not the command name itself. The @{" Options " link Format_Options} field shows the stack size provided for the command; if this is too small, some commands may not run properly. Finally, the @{" Result " link Format_Result} field is displayed as "----" while the command is executing, and is replaced with the return code from the command after execution completes (usually 0 for a successful execution). A result of "Fail" indicates that the command couldn't be executed at all. Since the executed command will probably produce some SnoopDos output of its own, you may need to scroll back in the SnoopDos buffer to retrieve the final return code from the RunCommand line if you need to find it for some reason. SnoopDos automatically writes this command to the settings file when you save settings. See also: @{" Command Index " link CommandIndex} @{" Execute " link Execute} @{" System " link System} @ENDNODE @NODE SaveBuffer @TITLE "SaveBuffer command" Command: SAVEBUFFER "filename" Example: SAVEBUFFER "ram:SnoopDos.txt" This command saves the entire contents of the SnoopDos event buffer to the named file. This is useful if you want to preserve the output from SnoopDos for later analysis, but forgot to open a log file first. This function is also available as a menu item on the Buffer menu. See also: @{" Command Index " link CommandIndex} @{" CopyBuffer " link CopyBuffer} @{" CopyWindow " link CopyWindow} @{" SaveWindow " link SaveWindow} @ENDNODE @NODE SaveDefSettings @TITLE "SaveDefSettings command" Command: SAVEDEFSETTINGS This command saves the current SnoopDos settings to the default settings file, as defined by the @{" Settings " link Settings} command. It is also available as a gadget in the @{" Main " link MainWindow} window, and as a menu option on the Settings menu. If no file has been explicitly defined, then the settings will be written to the file that was loaded during startup. If no such file could be found, then they will be written to ENVARC:SnoopDos.prefs instead. The next time you load SnoopDos, these settings will automatically be used. The settings saved include the current values of all the gadgets in the Setup and Function windows, and the current value of most boolean menu items, as well as the position and size of each window. See also: @{" Command Index " link CommandIndex} @{" LoadDefSettings " link LoadDefSettings} @{" LoadSettings " link LoadSettings} @{" SaveSettings " link SaveSettings} @{" Settings " link Settings} @ENDNODE @NODE SaveSettings @TITLE "SaveSettings command" Command: SAVESETTINGS "settingsfile" Example: SAVESETTINGS "ram:SnoopDos.prefs" This command writes the current values of all gadgets and menu items to the named file. This file can then be reloaded at a later time to reconfigure SnoopDos with those settings. The settings file generated is plain text and can be edited by hand if required. See also: @{" Command Index " link CommandIndex} @{" LoadDefSettings " link LoadDefSettings} @{" LoadSettings " link LoadSettings} @{" SaveDefSettings " link SaveDefSettings} @{" Settings " link Settings} @ENDNODE @NODE SaveWindow @TITLE "SaveWindow command" Command: SAVEWINDOW "filename" Example: SAVEWINDOW "ram:SnoopDos.txt" This command saves the contents of the main window to the named file. It is also available as a menu option on the Buffer menu. If the current buffer format is too wide to fit completely in the main window, only that portion which is currently displayed will be saved. If this doesn't include enough information, you can use the @{" SaveBuffer " link SaveBuffer} command instead and then delete any extra lines that you don't need. See also: @{" Command Index " link CommandIndex} @{" CopyBuffer " link CopyBuffer} @{" CopyWindow " link CopyWindow} @{" SaveBuffer " link SaveBuffer} @ENDNODE @NODE ScreenName @TITLE "ScreenName command" Command: SCREENNAME "Screen Name" Example: SCREENNAME "Workbench" This command works in conjunction with the NAMED option of the @{" ScreenType " link ScreenType} command to allow SnoopDos to open its windows on a particular public screen. It is also available as a gadget in the @{" Settings " link SettingsWindow} window. If the screen name can't be found, then SnoopDos will use the default screen instead. If the current screen type is set to FRONT or DEFAULT, then the screen name defined here will be ignored. SnoopDos automatically writes this command to the settings file when you save settings. See also: @{" Command Index " link CommandIndex} @{" HotKey " link HotKey} @{" ScreenType " link ScreenType} @ENDNODE @NODE ScreenType @TITLE "ScreenType command" Command: SCREENTYPE=DEFAULT | FRONT | NAMED Example: SCREENTYPE=FRONT This command determines what screen SnoopDos will use for its windows. It is also available as a gadget in the @{" Settings " link SettingsWindow} window. If the screen type is DEFAULT, then SnoopDos will open on the default public screen. This is usually the Workbench screen. If the screen type is FRONT, then SnoopDos will try and open on the frontmost public screen. Many modern application programs automatically make their screens public, and you can use third party utilities to create other public screens. This mode of operation is convenient, because it allows you to call up SnoopDos on your current screen at any time by just pressing the currently defined @{" Hotkey " link Hotkey}. If the screen type is NAMED, then SnoopDos will try and open on a public screen with a name that matches the currently defined @{" ScreenName " link ScreenName}. Note that SnoopDos won't create a screen of this name itself -- the screen must already exist. If no such screen is found, then SnoopDos will open on the default screen instead. SnoopDos automatically writes this command to the settings file when you save settings. See also: @{" Command Index " link CommandIndex} @{" HotKey " link HotKey} @{" ScreenName " link ScreenName} @ENDNODE @NODE ScrollDown @TITLE "ScrollDown command" Command: SCROLLDOWN Example: SCROLLDOWN 10 This command moves the SnoopDos event buffer down by lines. It is equivalent to using the down arrow gadget in the @{" Main " link MainWindow} window, or pressing the down arrow cursor key. See also: @{" Command Index " link CommandIndex} @{" GotoLine " link GotoLine} @{" ScrollUp " link ScrollUp} @ENDNODE @NODE ScrollUp @TITLE "ScrollUp command" Command: SCROLLUP Example: SCROLLUP 10 This command moves the SnoopDos event buffer up by lines. It is equivalent to using the up arrow scroll gadget in the @{" Main " link MainWindow} window or pressing the up arrow cursor key. See also: @{" Command Index " link CommandIndex} @{" GotoLine " link GotoLine} @{" ScrollDown " link ScrollDown} @ENDNODE @NODE SendRexx @TITLE "SendRexx command" Command: SENDREXX NOSENDREXX This command enables or disables monitoring of ARexx messages sent by ARexx scripts or applications. It is also available as a gadget in the @{" Function " link FunctionWindow} window. This can be useful if you want to see how a script is performing its magic, or if you're trying to figure out why an application isn't responding as you expect. The @{" Target Name " link Format_TargetName} output field shows the command being sent to the application, and the @{" Options " link Format_Options} output field shows the application's port name. When this function is enabled, SnoopDos monitors every single message sent by the system, in order to identify which ones are ARexx messages. Thus, you may find that your system runs a little slower. SnoopDos automatically writes this command to the settings file when you save settings. See also: @{" Command Index " link CommandIndex} @{" FindPort " link FindPort} @{" MonitorPackets " link MonitorPackets} @{" PacketDebugger " link PacketDebugger} @ENDNODE @NODE Settings @TITLE "Settings command" Command: SETTINGS="name" Example: SETTINGS="ENVARC:SnoopDos.prefs" This command defines the name of the default settings file that SnoopDos tries to load at startup. Normally, this is something that you would include in the SnoopDos icon's tooltypes, or as a CLI command line option. If you don't define an explicit settings file, SnoopDos will look in the PROGDIR:, ENVARC: and S: directories at startup for a file called SnoopDos.prefs. If it can't find such a file in any of those three directories, it will use the name ENVARC:SnoopDos.prefs for future saves. Note that this command doesn't actually cause the settings file to be loaded; it only shows where the settings file might be found. When you use the Save Settings gadget in the @{" Main " link MainWindow} window, this is the filename that will be used. You can also use this command from within a settings file. For example, suppose you wanted to carry out a certain set of actions each time SnoopDos started -- open a new log file, open the format editor, etc. Normally, if you included those commands in a settings file, they would be overwritten the first time you saved settings. However, by using the SETTINGS command to change the name of the settings file from within the settings file itself, you can avoid this. For example: SETTINGS "ENVARC:SnoopDos.realprefs" LOADDEFSETTINGS OPENLOG "ram:SnoopDos.log" OPENFORMAT If this file was saved as ENVARC:SnoopDos.prefs, then SnoopDos would start out by loading the real default settings from "ENVARC:SnoopDos.realprefs", then open a log file, and finally open the format editor. Any future saving of default settings would also be directed to ENVARC:SnoopDos.realprefs, and so the command file would not be overwritten. See also: @{" Command Index " link CommandIndex} @{" LoadDefSettings " link LoadDefSettings} @{" LoadSettings " link LoadSettings} @{" SaveDefSettings " link SaveDefSettings} @{" SaveSettings " link SaveSettings} @ENDNODE @NODE SetupWindowPos @TITLE "SetupWindowPos command" Command: SETUPWINDOWPOS=, Example: SETUPWINDOWPOS=0,20 This command is used to change the position of the settings window on the current screen. If the settings window is open, then it is moved immediately, else it will appear in the new position the next time it is opened. and are the pixel co-ordinates of the upper left corner of the window. SnoopDos automatically writes this command to the settings file when you save settings. See also: @{" Command Index " link CommandIndex} @{" Settings window " link SettingsWindow} @ENDNODE @NODE SetVar @TITLE "SetVar command" Command: SETVAR NOSETVAR This command enables or disables monitoring of the SetVar() and DeleteVar() dos.library functions. It is also available as a gadget in the @{" Function " link FunctionWindow} window. SetVar() is the logical counterpart to the GetVar() function; it allows a program to create or update an environment variable with a new value. As with GetVar(), Global, Local and Alias variables are recognised, and a trailing * after the type indicates that the program expects the variable to contain binary information, rather than plain text. See the @{" GetVar " link GetVar} command for more information. DeleteVar() is used to delete environment variables from memory. The same three variable types described above are recognised. SnoopDos automatically writes this command to the settings file when you save settings. See also: @{" Command Index " link CommandIndex} @ENDNODE @NODE Show @TITLE "Show command" Command: SHOW This command opens the SnoopDos main window on the currently selected screen (as defined by the @{" ScreenType " link ScreenType} command). If the window was already open, then it is brought to the front. If the window was open, but on different screen, then it is re-opened on the current screen. This command is automatically executed whenever you press the currently defined @{" HotKey " link HotKey}. It is also automatically executed if you run SnoopDos from the CLI with no command line options, or if you double-click on a SnoopDos icon while SnoopDos is already running. See also: @{" Command Index " link CommandIndex} @{" CX_Popup " link CX_Popup} @{" Hide " link Hide} @{" HotKey " link HotKey} @{" Main window " link MainWindow} @ENDNODE @NODE ShowCLI @TITLE "ShowCLI command" Command: SHOWCLI NOSHOWCLI This command enables or disables SnoopDos's ShowCLI setting. It can also be controlled via a gadget in the @{" Function " link FunctionWindow} window. The ShowCLI setting determines how the @{" Process name " link Format_ProcessName} field displays the name of the CLI command that called a monitored function. When enabled, the command name is prefixed with the number of the CLI in which it is running (e.g. "[4] Multiview"). If disabled, then only the name of the command is displayed. Background processes and programs started from Workbench are not affected. SnoopDos automatically writes this command to the settings file when you save settings. See also: @{" Command Index " link CommandIndex} @ENDNODE @NODE ShowFullPaths @TITLE "ShowFullPaths command" Command: SHOWFULLPATHS NOSHOWFULLPATHS This command enables or disables SnoopDos's ShowFullPaths setting. This setting can also be controlled via a gadget in the @{" Function " link FunctionWindow} window. Whenever a program passes a filename to an AmigaDOS function, the filename is interpreted as being relative to the program's current directory, unless an absolute pathname is specified with the filename. If the program being monitored changes directory often, it can become difficult to keep track of which directory it is in at any given time. Selecting this option makes SnoopDos always prefix filenames with a full path before displaying them in the window. This can produce rather long filenames which occupy a lot of space in the SnoopDos window, so you should only use this option if you have a specific need for it, rather than leaving it on all the time. If you have many long filenames displayed, you can use the menu shortcut keys for @{" LeftAligned " link LeftAligned} and @{" RightAligned " link RightAligned}, Amiga-[ and Amiga-], to quickly switch between viewing the start and end of the filename. Note that if a program tries to access a file on a volume that is not currently mounted, SnoopDos will be unable to resolve the full directory path to that file. In this case, only the volume name will be shown, followed by ellipses and the filename, to indicate that the directory information is unavailable. For example, "Work:.../filename". SnoopDos automatically writes this command to the settings file when you save settings. See also: @{" Command Index " link CommandIndex} @{" UseDeviceNames " link UseDeviceNames} @ENDNODE @NODE ShowGadgets @TITLE "ShowGadgets command" Command: SHOWGADGETS This command enables the display of the panel of button gadgets in the @{" Main " link MainWindow} window. It is also available as a menu option on the Windows menu. Having the gadgets easily available is convenient, but some people prefer to have an extra line or two of event output instead. Even when the gadgets are disabled, the keyboard shortcuts for each gadget still operate. The gadgets all have equivalent menu options which can be selected as well. To maximise the amount of room available for displaying event output, you may also like to turn off the @{" Status line " link HideStatus} gadget. SnoopDos automatically writes this command to the settings file when you save settings. See also: @{" Command Index " link CommandIndex} @{" HideGadgets " link HideGadgets} @{" HideStatus " link HideStatus} @{" ShowStatus " link ShowStatus} @{" TextSpacing " link TextSpacing} @ENDNODE @NODE ShowStatus @TITLE "ShowStatus command" Command: SHOWSTATUS This command enables the display of the @{" status line " link StatusLine} gadget in the @{" Main " link MainWindow} window. It is also available as an option on the Windows menu. The status line is not strictly necessary, but it provides a useful "at-a-glance" summary of whether or not a log file is currently open, and whether SnoopDos is currently @{" Paused " link Pause} or @{" Disabled " link Disable}. Some people prefer to sacrifice the status line to allow more lines of event output to be displayed in the main window. If you are doing this, you may like to also disable the @{" Button " link HideGadgets} gadgets, which will allow the maximum number of lines of text to be displayed. SnoopDos automatically writes this command to the settings file when you save settings. See also: @{" Command Index " link CommandIndex} @{" HideGadgets " link HideGadgets} @{" HideStatus " link HideStatus} @{" ShowGadgets " link ShowGadgets} @{" TextSpacing " link TextSpacing} @ENDNODE @NODE SimpleRefresh @TITLE "SimpleRefresh command" Command: SIMPLEREFRESH This command sets the refresh method used for all SnoopDos windows to Simple refresh. It is also available as a sub option to the "Window Type" menu option on the Windows menu. Simple refresh windows help conserve memory. When a window is partially obscured, the obscured portion is discarded, and is then redrawn by SnoopDos when the window is later uncovered. Redrawing the window can take some time on slower Amigas, where @{" Smart refresh " link SmartRefresh} windows may be more appropriate. However, some third party graphics cards actually perform better with simple refresh windows than with smart refresh. The best advice is to try both methods and choose whichever you like best. SnoopDos automatically writes this command to the settings file when you save settings. See also: @{" Command Index " link CommandIndex} @{" SmartRefresh " link SmartRefresh} @ENDNODE @NODE SingleStep @TITLE "SingleStep command" Command: SINGLESTEP This command is used when SnoopDos is paused. It allows each of the currently waiting tasks to execute the current function and advance to the next one. See the @{" Pause " link Pause} command for more information. SingleStep is also available as a menu option on the Projects menu. As an alternative, you can click the down arrow scroll gadget in the main window when the scroll bar is positioned at the end. You can also press Space or Return on the keyboard for convenience. The TAB key will also single step, but has the additional advantage of putting SnoopDos into Pause mode if it wasn't already paused. If you have a buffered @{" log file " link OpenLog} open, then SnoopDos will flush the buffer to disk each time you single step. This allows the most information to be retained in the event of a crash. However, it also means that your disk may become corrupt if a crash should occur in the middle of a disk write. Thus, if you suspect that a particular program is likely to crash, you should probably experiment without a log file first, or log to a safe device like PRT: or RAD:. See also: @{" Command Index " link CommandIndex} @{" Pause " link Pause} @{" Unpause " link Unpause} @ENDNODE @NODE SmartRefresh @TITLE "SmartRefresh command" Command: SMARTREFRESH This command sets the refresh method used for all SnoopDos windows to Smart refresh. It is also available as a sub option to the "Window Type" menu option on the Windows menu. Smart refresh windows are popular, because they allow a partially obscured window to be instantly redrawn when it is uncovered, with no obvious delay. However, they take up more memory than @{" Simple refresh " link SimpleRefresh} windows. They can also be slower on some third party graphics cards, such as the Picasso, especially when running with 256 colours. SnoopDos automatically writes this command to the settings file when you save settings. See also: @{" Command Index " link CommandIndex} @{" SimpleRefresh " link SimpleRefresh} @ENDNODE @NODE StackLimit @TITLE "StackLimit command" Command: STACKLIMIT= Example: STACKLIMIT=1000 This command defines how much free stack space a task or process must have before SnoopDos will monitor one of its function calls. This is needed because some tasks installed by devices have very small stacks and the additional stack space used by SnoopDos would cause a crash if it tried to monitor the function. (CrossDOS is one such example.) is the required amount of free stack space in bytes. Note that this does not necessarily correspond to the total stack size for the task, but to the free stack at the time the function call is made. For example, a task with a 20K stack could use up 19.5K of space before entering a SnoopDos patch (and so would be ignored if StackLimit was 500 or above) whereas a task with a 2K stack might only use 0.5K, leaving 1.5K free for SnoopDos to use. SnoopDos defaults to a stack limit of 1000 bytes. This should be more than sufficient for most purposes, but if need be, this can be reduced to about 600 bytes. You should only need to do this if you are trying to monitor a particular task known to have a very small stack. To determine the current stack size, SnoopDos uses the tc_SPLower and tc_SPUpper values in the task structure. If a task or process has allocated its own stack, then these may not be correct -- if this is the case, SnoopDos will go ahead and monitor the function call anyway, on the assumption that the application will have allocated a stack big enough to handle SnoopDos's requirements. Note that there is no way to set this option from within SnoopDos; you must change it by editing the SnoopDos default settings file directly, or by adding it as a tooltype to the SnoopDos icon. SnoopDos automatically writes this command to the settings file when you save settings. See also: @{" Command Index " link CommandIndex} @{" PatchRamLib " link PatchRamLib} @ENDNODE @NODE System @TITLE "System command" Command: SYSTEM NOSYSTEM This command enables or disables monitoring of the System() dos.library function. It is also available as a gadget in the @{" Function " link FunctionWindow} window. System() is one of the most powerful functions in AmigaDOS. It allows an arbitary command line to be executed, exactly as if it was typed at a Shell prompt. As with @{" RunCommand " link RunCommand} the @{" Options " link Format_Options} field shows the stack size allocated for the command. The @{" Result " link Format_Result} field shows the return code from the command (usually 0), or "Fail" if the command could not be executed. SnoopDos automatically writes this command to the settings file when you save settings. See also: @{" Command Index " link CommandIndex} @{" Execute " link Execute} @{" RunCommand " link RunCommand} @ENDNODE @NODE TaskPri @TITLE "TaskPri command" Command: TASKPRI Example: TASKPRI 5 This command is used to change the priority of the main SnoopDos process. A selection of common priorities is available via the similarly named menu item on the Project menu. Normally, SnoopDos defaults to running at priority 0. However, you may prefer to run at a higher or lower priority. If SnoopDos runs at a priority above 0, then it can always keep up to date when monitoring events. This is particularly true if you are using @{" SegTracker " link Format_SegmentName} to determine the calling module for each event, since otherwise, a module can sometimes unload itself before SnoopDos has a chance to ask SegTracker to locate it. However, running at a higher priority can result in an increase in the number of task switches, which can slow down your machine a little. If SnoopDos runs at a priority lower than 0, then it will have very little impact on system performance, even when its window is open. However, the output will only be updated when no other programs are waiting to run, so it may appear in sudden bursts, rather than evenly. Even at a low priority, SnoopDos will not miss any events. SnoopDos automatically writes this command to the settings file when you save settings. See also: @{" Command Index " link CommandIndex} @{" Pause " link Pause} @ENDNODE @NODE TextSpacing @TITLE "TextSpacing command" Command: TEXTSPACING Example: TEXTSPACING 1 This command sets the number of extra pixels of space between adjacent lines of output in the @{" Main " link MainWindow} window. You can also change the text spacing using the menu option on the Windows menu. If you are using a small font, increasing the spacing can make the output easier to read. The valid values for are 0, 1 or 2. When the spacing is changed, the buffer contents will be immediately redrawn using the new spacing. However, the position of the window gadgets will not be adjusted until the next time the window is resized. Thus, you may find that if you resize the window slighly, you can fit an extra line of text as the gadgets reposition themselves to accomodate the change. SnoopDos automatically writes this command to the settings file when you save settings. See also: @{" Command Index " link CommandIndex} @{" ShowGadgets " link ShowGadgets} @{" ShowStatus " link ShowStatus} @ENDNODE @NODE Unpause @TITLE "Unpause command" Command: UNPAUSE This command undoes the effect of the @{" Pause " link Pause} command. It can be accessed by deselecting the Pause menu option in the Project menu or the Pause gadget in the main window. You can also press SHIFT-TAB to unconditionally cancel any Pause or @{" Disable " link Disable} currently in effect. Deselecting Pause allows any tasks that were previously in WAIT state to resume operations. To allow such tasks to execute a single function call and then go back into WAIT mode again, see the @{" SingleStep " link SingleStep} command. See also: @{" Command Index " link CommandIndex} @{" Pause " link Pause} @{" SingleStep " link SingleStep} @ENDNODE @NODE UseDeviceNames @TITLE "UseDeviceNames command" Command: USEDEVICENAMES NOUSEDEVICENAMES This command enables or disables SnoopDos's UseDeviceNames setting. This setting can also be controlled via a gadget in the @{" Function " link FunctionWindow} window. UseDeviceNames works together with the @{" ShowFullPaths " link ShowFullPaths} setting. If UseDeviceNames is enabled, then any filenames that are expanded to full paths will be displayed using the disk device name. If disabled, then the disk volume name is used instead. For example, when UseDeviceNames is enabled, an expanded name might appear as "HD0:Files/Data". The same name shown with UseDeviceNames disabled would then appear as "System3.0:Files/Data". Using the device name is often preferred, since device names are typically only three characters in length, and so take up less space. They are also normally unique, which can sometimes help to prevent confusion. SnoopDos automatically writes this command to the settings file when you save settings. See also: @{" Command Index " link CommandIndex} @{" ShowFullPaths " link ShowFullPaths} @ENDNODE @NODE WindowFont @TITLE "WindowFont command" Command: WINDOWFONT "fontname.size" Example: WINDOWFONT "helvetica.11" This command selects the font used by SnoopDos for all window gadgets. You can also change the font by using the font requester accessible through the @{" Settings " link SettingsWindow} window. Any font can be selected, and you must specify a size. If the font is too large for a particular window, then SnoopDos automatically switches to a smaller font for that window only. SnoopDos automatically writes this command to the settings file when you save settings. See also: @{" Command Index " link CommandIndex} @{" BufferFont " link BufferFont} @ENDNODE @NODE WindowWidth @TITLE "WindowWidth command" Command: WINDOWWIDTH Example: WINDOWWIDTH 80 This command adjusts the width of the SnoopDos main window so that exactly number of characters can be displayed horizontally. If the main window isn't open, then this command has no effect. If obtaining the requested width would make the window too small or too large, SnoopDos will get as close as possible to the width you asked for. Zero is a special value which will make the width just wide enough to fully display the current format string. The main reason you might want to use this command is so that you can more easily create a custom format suitable for outputting to a file or printer. This is particularly true if you run Workbench at a high resolution like 1024 x 768, where the SnoopDos window might be much wider than the usual 80 characters. Keep in mind that when SnoopDos is printing to a log file, it adds one additional character at the start of each line. Usually that character is a space, but it can sometimes be '\\' or '/' -- see the @{" OpenLog " link OpenLog} command for more details. In any case, this extra character needs to be taken into account when you set the window width. For example, a 79 character window width will result in 80-character lines in the log file. For convenience, the SnoopDos Windows menu offers several common window widths via the "Change window width" submenu. See also: @{" Command Index " link CommandIndex} @{" Format editor " link FormatEditor} @ENDNODE @remark -------------------------------------------------------------- @remark @remark Menu reference @remark @remark -------------------------------------------------------------- @NODE Menu_Index @TITLE "SnoopDos Menu Reference" SnoopDos provides the following menus in the @{" Main " link MainWindow} window. Click on any item for additional information. @{" PROJECT " link Menu_Project } @{" WINDOWS " link Menu_Windows} +----------------------+ +---------------------------+ | @{" Open log... " link Menu_Open_log } | | @{" Show setup... " link Menu_Show_setup } | | @{" Close log " link Menu_Close_log } | | @{" Show functions... " link Menu_Show_functions } | | -------------------- | | @{" Show format... " link Menu_Show_format } | | @{" · Pause " link Menu_Pause } | | ------------------------- | | @{" · Disable " link Menu_Disable } | | @{" Change window width " link Menu_Change_window_width } | | -------------------- | | ------------------------- | | @{" Single step " link Menu_Single_step } | | @{" Text spacing " link Menu_Text_spacing } | | -------------------- | | @{" Window type " link Menu_Window_type } | | @{" Task priority " link Menu_Task_priority } | | @{" Target name " link Menu_Target_name } | | -------------------- | | @{" Row selection key " link Menu_Row_selection_key } | | @{" Help... " link Menu_Help } | | ------------------------- | | @{" About... " link Menu_About } | | @{" · Show status line? " link Menu_Show_status_line } | | -------------------- | | @{" · Show gadgets? " link Menu_Show_gadgets } | | @{" Hide " link Menu_Hide } | | ------------------------- | | @{" Quit " link Menu_Quit } | | @{" · Auto-open on output? " link Menu_Auto_open_on_output } | +----------------------+ | @{" · Disable when hidden? " link Menu_Disable_when_hidden } | +---------------------------+ @{" SETTINGS " link Menu_Settings } @{" BUFFER " link Menu_Buffer} +----------------------+ +---------------------------+ | @{" Load... " link Menu_Load } | | @{" Copy window to clip " link Menu_Copy_window_to_clip} | | @{" Save " link Menu_Save } | | @{" Copy buffer to clip " link Menu_Copy_buffer_to_clip} | | @{" Save as... " link Menu_Save_as } | | ------------------------- | | -------------------- | | @{" Save window... " link Menu_Save_window } | | @{" Reset to defaults " link Menu_Reset_to_defaults} | | @{" Save buffer... " link Menu_Save_buffer } | | @{" Last saved " link Menu_Last_saved } | | ------------------------- | | @{" Restore " link Menu_Restore } | | @{" Clear buffer " link Menu_Clear_buffer } | | -------------------- | +---------------------------+ | @{" · Create icons? " link Menu_Create_icons } | +----------------------+ @ENDNODE @NODE Menu_Project "SnoopDos Project menu" The SnoopDos project menu contains the following program options. Click on any option for additional information. PROJECT MENU +------------------+ | @{" Open log... " link Menu_Open_log } | Start logging output to a new file | @{" Close log " link Menu_Close_log } | Stop logging to current log file | ---------------- | | @{" · Pause " link Menu_Pause } | Pause all tasks calling monitored functions | @{" · Disable " link Menu_Disable } | Disable monitoring of all functions | ---------------- | | @{" Single step " link Menu_Single_step } | Advanced all paused processes by one step | ---------------- | | @{" Task priority " link Menu_Task_priority} | Change task priority of SnoopDos | ---------------- | | @{" Help... " link Menu_Help } | Call up contents page of Help file | @{" About... " link Menu_About } | Display version and author information | ---------------- | | @{" Hide " link Menu_Hide } | Close window and run in background | @{" Quit " link Menu_Quit } | Remove SnoopDos from memory +------------------+ See also: @{" Main window " link MainWindow} @{" Windows menu " link Menu_Windows} @{" Settings menu " link Menu_Settings} @{" Buffer menu " link Menu_Buffer} @ENDNODE @NODE Menu_Open_log "Project menu/Open log..." PROJECT MENU / OPEN LOG... This menu option lets you open a new log file. An ASL file requester will be displayed to let you choose the name of the log file. If you choose a file which already exists, SnoopDos will give you the option of overwriting the existing file, or appending new output to the end of the file. If you want to log to a device rather than a disk file, type the device name in the Directory gadget of the ASL requester (e.g. PRT:). In this case, the filename should be left empty, unless you are logging to a CON: window, when the filename should contain the last window option (which is usually the window name or CLOSE). When a log file is open, SnoopDos copies all output displayed in the main window to that file, allowing a permanent record to be kept. Usually, the format of the log file is the same as that displayed in the main window, but you can change this using the @{" LogFormat " link LogFormat} option. Note that unlike the @{" Open log " link MainOpenLog} button in the main window, this option will always display a file requester. When a log file is open, this menu option is disabled. Selecting the @{" Close log " link Menu_Close_log} menu option enables it again. See also: @{" Project menu " link Menu_Project} @{" Main window " link MainWindow} @{" OpenLog " link OpenLog} @ENDNODE @NODE Menu_Close_log "Project menu/Close log" PROJECT MENU / CLOSE LOG This option is the counterpart of the @{" Open log " link Menu_Open_log} menu option. It closes any currently open log file. If no log file is open, then this option is disabled. See also: @{" Project menu " link Menu_Project} @{" Main window " link MainWindow} @{" CloseLog " link CloseLog} @ENDNODE @NODE Menu_Pause "Project menu/Pause" PROJECT MENU / PAUSE Selecting this option causes any tasks that call a function monitored by SnoopDos to pause before executing the function call. This allows you to see the function parameters before the call is actually carried out. You can then use the @{" Single step " link Menu_Single_step} menu option to execute the call and advance to the next one. Deselecting this menu option will allow the tasks to run as normal again. For a more comprehensive description, see the @{" Pause" link Pause} command. See also: @{" Project menu " link Menu_Project} @{" Main window " link MainWindow} @{" Pause " link Pause} @ENDNODE @NODE Menu_Disable "Project menu/Disable" PROJECT MENU / DISABLE Selecting this option disables monitoring of all functions. It corresponds to the @{" Disable " link Disable} command. This provides a convenient way to turn off SnoopDos without having to quit, or individually deselect each function. To re-enable monitoring, simply deselect the menu option. See also: @{" Project menu " link Menu_Project} @{" Main window " link MainWindow} @{" Disable " link Disable} @ENDNODE @NODE Menu_Single_step "Project menu/Single step" PROJECT MENU / SINGLE STEP This option works in conjunction with the @{" Pause " link Menu_Pause} menu option. Selecting single step allows all currently paused tasks to execute the function they are paused at. Each task will be automatically paused again the next time it calls a function monitored by SnoopDos. See also: @{" Project menu " link Menu_Project} @{" Main window " link MainWindow} @{" SingleStep " link SingleStep} @ENDNODE @NODE Menu_Task_priority "Project menu/Task priority" PROJECT MENU / TASK PRIORITY This menu option allows you to change the priority of the main SnoopDos task. The submenu contains several common task priorities. For more details about the benefits and tradeoffs of changing the task priority, see the @{" TaskPri " link TaskPri} command. See also: @{" Project menu " link Menu_Project} @{" Main window " link MainWindow} @{" TaskPri " link TaskPri} @ENDNODE @NODE Menu_Help "Project menu/Help" PROJECT MENU / HELP This option loads the SnoopDos help file into AmigaGuide, positioned at the contents page. From there, you can access help on any aspect of SnoopDos. If you get an error requester saying "Can't open database", it means that AmigaGuide cannot locate the SnoopDos.guide file. If you copy the file into the SnoopDos program directory, or into HELP:English, it should work properly. See also: @{" Project menu " link Menu_Project} @{" Main window " link MainWindow} @{" Help " link Help} @ENDNODE @NODE Menu_About "Project menu/About" PROJECT MENU / ABOUT This option displays a requester with information about the author of SnoopDos, the current version number, the distribution conditions, and the ARexx port name. See also: @{" Project menu " link Menu_Project} @{" Main window " link MainWindow} @ENDNODE @NODE Menu_Hide "Project menu/Hide" PROJECT MENU / HIDE This option closes all the SnoopDos windows, but leaves SnoopDos monitoring system activity in the background. It corresponds to the @{" Hide " link Hide} command. If the @{" HideMethod " link HideMethod} is set to None, then this option is not available. When SnoopDos is hidden, the main window can be re-opened by pressing the currently defined @{" HotKey " link HotKey}. Depending on the hide method, you may also be able to open the SnoopDos AppIcon, or select the Show SnoopDos menu item on the Workbench Tools menu. See also: @{" Project menu " link Menu_Project} @{" Main window " link MainWindow} @{" Hide " link Hide} @ENDNODE @NODE Menu_Quit "Project menu/Quit" PROJECT MENU / QUIT This option is used to unload SnoopDos from memory. It corresponds to the @{" Quit " link Quit} command. Note that if a call to one of the monitored functions is still in progress, SnoopDos may not be able to exit immediately. See the documentation on the Quit command for more details. See also: @{" Project menu " link Menu_Project} @{" Main window " link MainWindow} @{" Quit " link Quit} @ENDNODE @NODE Menu_Windows "SnoopDos Windows menu" The SnoopDos windows menu contains the following options which control the four windows used by SnoopDos. Click on any option for more information. WINDOWS MENU +---------------------------+ | @{" Show setup... " link Menu_Show_setup } | Open the SnoopDos setup window | @{" Show functions... " link Menu_Show_functions } | Open the SnoopDos function window | @{" Show format... " link Menu_Show_format } | Open the SnoopDos format editor window | ------------------------- | | @{" Change window width " link Menu_Change_window_width } | Change the number of text columns | ------------------------- | | @{" Text spacing " link Menu_Text_spacing } | Adjust the spacing between text lines | @{" Window type " link Menu_Window_type } | Select simple or smart refresh windows | @{" Target name " link Menu_Target_name } | Align target name field on left or right | @{" Row selection key " link Menu_Row_selection_key } | Choose qualifier key for row selection | ------------------------- | | @{" · Show status line? " link Menu_Show_status_line } | Turn on or off the SnoopDos status line | @{" · Show gadgets? " link Menu_Show_gadgets } | Turn on or off the main window gadgets | ------------------------- | | @{" · Auto-open on output? " link Menu_Auto_open_on_output } | If set, automatically open for new output | @{" · Disable when hidden? " link Menu_Disable_when_hidden } | If set, only monitor when window is open +---------------------------+ See also: @{" Main window " link MainWindow} @{" Project menu " link Menu_Project} @{" Settings menu " link Menu_Settings} @{" Buffer menu " link Menu_Buffer} @ENDNODE @NODE Menu_Show_setup "Windows menu/Show setup..." WINDOWS MENU / SHOW SETUP... This menu option opens the SnoopDos @{" Setup " link SettingsWindow} window. It corresponds to the @{" OpenSetup " link OpenSetup} command. If the window was already open, then it is brought to the front. If you hold down SHIFT while selecting this option, then the window will be closed instead. See also: @{" Windows menu " link Menu_Windows} @{" Main window " link MainWindow} @{" OpenSetup " link OpenSetup} @ENDNODE @NODE Menu_Show_functions "Windows menu/Show functions..." WINDOWS MENU / SHOW FUNCTIONS... This menu option opens the SnoopDos @{" Function " link SettingsWindow} window. It corresponds to the @{" OpenFunction " link OpenFunction} command. If the window was already open, then it is brought to the front. If you hold down SHIFT while selecting this option, then the window will be closed instead. See also: @{" Windows menu " link Menu_Windows} @{" Main window " link MainWindow} @{" OpenFunction " link OpenFunction} @ENDNODE @NODE Menu_Show_format "Windows menu/Show format..." WINDOWS MENU / SHOW FORMAT... This menu option opens the SnoopDos @{" Format editor " link FormatEditor}. It corresponds to the @{" OpenFormat " link OpenFormat} command. If the editor was already open, then it is brought to the front. If you hold down SHIFT while selecting this option, then the editor will be closed instead. See also: @{" Windows menu " link Menu_Windows} @{" Main window " link MainWindow} @{" OpenFormat " link OpenFormat} @ENDNODE @NODE Menu_Change_window_width "Windows menu/Change window width" WINDOWS MENU / CHANGE WINDOW WIDTH This menu option allows you to adjust the width of the main window, so that a given number of text columns can be displayed. It corresponds to the @{" WindowWidth " link WindowWidth} command. The sub menu provides several useful window widths. If you are designing a format intended for output to a log file, you can set the window width to 78 or 79 to ensure your format will fit neatly on a printed page or on an 80 column screen. Remember that information output to a log file requires one extra column of space; see the @{" OpenLog " link OpenLog} command for more information. In addition to the preset sizes, you can also select "Best Fit". This will size the window so that it is exactly wide enough to fully display the current format. If you have been resizing the SnoopDos window using the mouse, this provides a convenient way to ensure you are not wasting any horizontal space. See also: @{" Windows menu " link Menu_Windows} @{" Main window " link MainWindow} @{" WindowWidth " link WindowWidth} @ENDNODE @NODE Menu_Text_spacing "Windows menu/Text spacing" WINDOWS MENU / TEXT SPACING This menu option allows you to alter the spacing between adjacent lines of text in the main window. It corresponds to the @{" TextSpacing " link TextSpacing} command. You can choose 0, 1 or 2 pixels of extra spacing from the sub menu. Different people prefer different settings; try all three, and choose the one you like best. See also: @{" Windows menu " link Menu_Windows} @{" Main window " link MainWindow} @{" TextSpacing " link TextSpacing} @ENDNODE @NODE Menu_Window_type "Windows menu/Window type" WINDOWS MENU / WINDOW TYPE This menu item allows you to select which type of refresh method you want SnoopDos to use for each window. The two sub menu options correspond to the @{" SimpleRefresh " link SimpleRefresh} and @{" SmartRefresh " link SmartRefresh} commands. Simple refresh windows take up less memory, and can operate faster on some Amigas with third-party graphics cards. However, they are often slower, since the Amiga has to recreate the contents of each window whenever it is uncovered. Smart refresh windows take up more memory but operate much more quickly on unaccelerated Amigas. Try both settings, and decide which you like best. See also: @{" Windows menu " link Menu_Windows} @{" Main window " link MainWindow} @{" SimpleRefresh " link SimpleRefresh} @{" SmartRefresh " link SmartRefresh} @ENDNODE @NODE Menu_Target_name "Windows menu/Target name" WINDOWS MENU / TARGET NAME This menu option allows you to choose which way you want the @{" Target name " link Format_TargetName} field displayed in the main window. It corresponds to the @{" LeftAligned " link LeftAligned} and @{" RightAligned " link RightAligned} commands. If the target name is left aligned, it looks just like any other output column. If it is right aligned, then when a name is too long to be fully displayed in the column, the rightmost portion of the name is displayed instead of the leftmost portion. This is indicated by a '«' symbol in the first column of the name. Right aligned is particularly useful if you are using the @{" ShowFullPaths " link ShowFullPaths} option, since it allows you to see the filename at the end of a long path, instead of the device or volume name at the start. The menu shortcut key for the two options are set to RAmiga-[ and RAmiga-] (for left and right aligned respectively); this makes it easy to switch to right aligned mode if you see a long target name, and immediately switch back to left aligned once you have seen the ending. See also: @{" Windows menu " link Menu_Windows} @{" Main window " link MainWindow} @{" LeftAligned " link LeftAligned} @{" RightAligned " link RightAligned} @ENDNODE @NODE Menu_Row_selection_key "Windows menu/Row selection key" WINDOWS MENU / ROW SELECTION KEY SnoopDos allows you to highlight lines of output in the main window by clicking on them. This allows you to quickly identify all the components of an event by providing a horizontal guide for your eyes to follow. Normally, a click on its own is sufficient. However, if you use a click- to-front window utility, then the "ghost" flash of a line being briefly highlighted when you click the SnoopDos window to the front can become distracting. This menu option allows you to choose a qualifier key (SHIFT, ALT or CTRL) which must be held down before you can highlight lines of output. By using a qualifier which is different to the qualifier used for your click-to- front utility, you can avoid this annoying effect. A range of qualifier types are listed in the sub menu. The "Ignore" option should be selected if you don't use a click-to-front utility -- it tells SnoopDos not to pay any attention to what key is pressed when you click the mouse. The "None" option makes SnoopDos explicitly check that no qualifier keys are pressed while the row is being selected. Select this if your click-to- front utility uses a keyboard qualifier itself such as SHIFT. The SHIFT, ALT and CTRL options indicate that the appropriate key must be held down for row highlighting to work. The "All" option is similar, but allows any of the thee qualifier keys to be held down, rather than a specific one. If your click-to-front utility doesn't use a qualifier key itself, then "All" is the best option to choose. See also: @{" Windows menu " link Menu_Windows} @{" Main window " link MainWindow} @{" Event output " link EventOutput} @{" RowQualifier " link RowQualifier} @ENDNODE @NODE Menu_Show_status_line "Windows menu/Show status line?" WINDOWS MENU / SHOW STATUS LINE? This menu option allows you to control whether or not the status line should be displayed in the main window. It corresponds to the @{" ShowStatus " link ShowStatus} and @{" HideStatus " link HideStatus} commands. Hiding the status line allows more room for event output. However, leaving it visible allows you to ascertain SnoopDos's current state at a glance. Try both settings and see which you prefer. See also: @{" Windows menu " link Menu_Windows} @{" Main window " link MainWindow} @{" ShowStatus " link ShowStatus} @{" HideStatus " link HideStatus} @ENDNODE @NODE Menu_Show_gadgets "Windows menu/Show gadgets?" WINDOWS MENU / SHOW GADGETS? This menu option allows you to control whether or not the button gadgets should be displayed in the main window. It corresponds to the @{" ShowGadgets " link ShowGadgets} and @{" HideGadgets " link HideGadgets} commands. Hiding the gadgets allows more room for event output. However, leaving them visible allows you to carry out common actions quickly using the mouse. All the gadgets have equivalent menu items which you can use when the gadgets are hidden. You can also continue to use the gadget keyboard shortcuts when they are hidden. See also: @{" Windows menu " link Menu_Windows} @{" Main window " link MainWindow} @{" ShowGadgets " link ShowGadgets} @{" HideGadgets " link HideGadgets} @ENDNODE @NODE Menu_Auto_open_on_output "Windows menu/Auto-open on output?" WINDOWS MENU / AUTO-OPEN ON OUTPUT? This menu option controls whether or not SnoopDos should automatically open if an event occurs while it is hidden. It corresponds to the @{" AutoOpen " link AutoOpen} command. Normally, you will want to leave this option disabled, since otherwise, SnoopDos would rarely run in the background for very long before being automatically opened again, defeating the purpose. However, occasionally, you are waiting for a task to carry out one specific action. In these circumstances, it can be convenient to be able to close the SnoopDos window, confident that you will not miss the vital event when it happens. See also: @{" Windows menu " link Menu_Windows} @{" Main window " link MainWindow} @{" AutoOpen " link AutoOpen} @ENDNODE @NODE Menu_Disable_when_hidden "Windows menu/Disable when hidden?" WINDOWS MENU / DISABLE WHEN HIDDEN? This menu option controls whether or not SnoopDos should automatically stop monitoring all functions when it is running in the background. It corresponds to the @{" DisableWhenHidden " link DisableWhenHidden} command. Usually, you will want to leave this option disabled. However, if you only use SnoopDos occasionally, but still like the convenience of having it always available at the press of a hotkey, enabling this option will allow you to keep SnoopDos loaded and ready, without slowing down your system. See also: @{" Windows menu " link Menu_Windows} @{" Main window " link MainWindow} @{" DisableWhenHidden " link DisableWhenHidden} @ENDNODE @NODE Menu_Settings "SnoopDos Settings menu" The SnoopDos settings menu contains options that control the saving and restoring of program settings. Click on any option for more information. SETTINGS MENU +----------------------+ | @{" Load... " link Menu_Load } | Load in a new settings file | @{" Save " link Menu_Save } | Save the current settings as defaults | @{" Save as... " link Menu_Save_as } | Save the current settings to a new file | -------------------- | | @{" Reset to defaults " link Menu_Reset_to_defaults} | Install the standard SnoopDos settings | @{" Last saved " link Menu_Last_saved } | Install the most recently saved settings | @{" Restore " link Menu_Restore } | Restore the settings loaded at the start | -------------------- | | @{" · Create icons? " link Menu_Create_icons } | If set, save icons with settings files +----------------------+ See also: @{" Main window " link MainWindow} @{" Project menu " link Menu_Project} @{" Windows menu " link Menu_Windows} @{" Buffer menu " link Menu_Buffer} @ENDNODE @NODE Menu_Load "Settings menu/Load..." SETTINGS MENU / LOAD... This menu option allows you to load in a SnoopDos settings file. It corresponds to the @{" LoadSettings " link LoadSettings} command. A settings file is simply a standard text file which contains a list of SnoopDos commands to execute. Usually this will have been created by SnoopDos itself as a result of an earlier @{" SaveSettings " link SaveSettings} command, but it can also be created by the user. The first line must read "" or the file won't be recognised as a valid settings file. See also: @{" Settings menu " link Menu_Settings} @{" Main window " link MainWindow} @{" LoadSettings " link LoadSettings} @ENDNODE @NODE Menu_Save "Settings menu/Save" SETTINGS MENU / SAVE This menu option saves the current SnoopDos settings to the default settings file, as defined by the @{" Settings " link Settings} command. It corresponds to the @{" SaveDefSettings " link SaveDefSettings} command. You can achieve the same effect by selecting the Save Settings gadget in the main window. The next time you start SnoopDos, these settings will be automatically loaded. This allows you to maintain your favourite configuration from session to session. See also: @{" Settings menu " link Menu_Settings} @{" Main window " link MainWindow} @{" SaveDefSettings " link SaveDefSettings} @ENDNODE @NODE Menu_Save_as "Settings menu/Save as..." SETTINGS MENU / SAVE AS... This menu option allows you to save the current settings to a file of your choice. It corresponds to the @{" SaveSettings " link SaveSettings} command. This can be useful as a starting point for generating a custom settings file. It can also be a convenient way to produce a printed list of your current settings for future reference -- simply enter PRT: in the drawer field of the ASL file requester. See also: @{" Settings menu " link Menu_Settings} @{" Main window " link MainWindow} @{" SaveSettings " link SaveSettings} @ENDNODE @NODE Menu_Reset_to_defaults "Settings menu/Reset to defaults" SETTINGS MENU / RESET TO DEFAULTS This menu option provides a convenient way to install the default settings that SnoopDos uses when you start it with no configuration file. This is useful if you've managed to change the settings so much that you just want to start again. See also: @{" Settings menu " link Menu_Settings} @{" Main window " link MainWindow} @{" LoadSettings " link LoadSettings} @ENDNODE @NODE Menu_Last_saved "Settings menu/Last saved" SETTINGS MENU / LAST SAVED This menu option allows you to reload the last set of settings that were saved to disk. Usually, this will be the set that SnoopDos loaded during initialisation, but if you have saved settings since starting, then the more recent set is used instead. The file is actually read back in from disk as if you used @{" LoadSettings " link LoadSettings} so if you have been editing the disk copy by hand, your changes will take effect. You might find this option useful if you make a change to the settings (especially the display format) and then change your mind -- by selecting this option, you can quickly undo the change. See also: @{" Settings menu " link Menu_Settings} @{" Main window " link MainWindow} @{" LoadSettings " link LoadSettings} @ENDNODE @NODE Menu_Restore "Settings menu/Restore" SETTINGS MENU / RESTORE This option restores the settings that SnoopDos loaded during its initialisation. This is useful if you are playing with the settings and then accidentally press Save Settings, which makes your changes permanent. By selecting Restore, you can get back the original settings and then resave them again. See also: @{" Settings menu " link Menu_Settings} @{" Main window " link MainWindow} @{" LoadSettings " link LoadSettings} @ENDNODE @NODE Menu_Create_icons "Settings menu/Create icons?" SETTINGS MENU / CREATE ICONS? This menu option controls whether or not SnoopDos creates icons for any settings files it saves. It corresponds to the @{" CreateIcons " link CreateIcons} command. Creating icons is convenient, because it allows you to manipulate settings files from Workbench. You can double-click on a settings file to load the settings into SnoopDos (assuming SnoopDos is in the same directory or in your AmigaDOS path) and you can also add additional commands to the tool types for that icon to perform actions like opening a log file. See the @{" Settings files " link SettingsFiles} section for more information. Note that no icon is saved for the defaults file -- if you want it to have an icon, use the @{" Save as " link Menu_Save_As} Settings menu option. See also: @{" Settings menu " link Menu_Settings} @{" Main window " link MainWindow} @{" CreateIcons " link CreateIcons} @ENDNODE @NODE Menu_Buffer "SnoopDos Buffer menu" The SnoopDos buffer menu contains options that control the saving and clearing of the event buffer. Click on any option for more information. BUFFER MENU +------------------------+ | @{" Copy window to clip " link Menu_Copy_window_to_clip} | Copy window contents to clipboard | @{" Copy buffer to clip " link Menu_Copy_buffer_to_clip} | Copy buffer contents to clipboard | ---------------------- | | @{" Save window... " link Menu_Save_window } | Save window contents to a file | @{" Save buffer... " link Menu_Save_buffer } | Save buffer contents to a file | ---------------------- | | @{" Clear buffer " link Menu_Clear_buffer } | Clear all events from event buffer +------------------------+ See also: @{" Main window " link MainWindow} @{" Project menu " link Menu_Project} @{" Windows menu " link Menu_Windows} @{" Settings menu " link Menu_Settings} @ENDNODE @NODE Menu_Copy_window_to_clip "Buffer menu/Copy window to clip" BUFFER MENU / COPY WINDOW TO CLIP This menu option copies the current contents of the main window to the clipboard. It corresponds to the @{" CopyWindow " link CopyWindow} command. This is convenient if you want to copy a portion of the SnoopDos event output into a word processor or text editor -- you can simply position the window to display the portion you're interested in, select Copy Window, and then select Paste in your editor. If the window width is too narrow to display a full line of event output, only the portion displayed inside the window will be copied. You can use the @{" Copy buffer " link Menu_Copy_buffer_to_clip} menu option to copy the entire buffer to the clipboard. See also: @{" Buffer menu " link Menu_Buffer} @{" Main window " link MainWindow} @{" CopyWindow " link CopyWindow} @ENDNODE @NODE Menu_Copy_buffer_to_clip "Buffer menu/Copy buffer to clip" BUFFER MENU / COPY BUFFER TO CLIP This menu option copies the entire contents of the event buffer to the clipboard. It corresponds to the @{" CopyBuffer " link CopyBuffer} command. This is convenient if you want to copy the SnoopDos event output into a word processor or text editor -- you can simply select Copy Buffer, and then select Paste in your editor. Since the entire buffer contents are copied, you should think carefully before using this option, especially if there has been a lot of output. You may find it more useful to use the @{" Copy window " link Menu_Copy_window_to_clip} menu option, which only copies the text displayed in the main window, rather than the entire buffer. See also: @{" Buffer menu " link Menu_Buffer} @{" Main window " link MainWindow} @{" CopyBuffer " link CopyBuffer} @ENDNODE @NODE Menu_Save_window "Buffer menu/Save window..." BUFFER MENU / SAVE WINDOW... This menu option allows you to save the current contents of the main window to a file. It corresponds to the @{" SaveWindow " link SaveWindow} command. If the window width is too narrow to display a full line of event output, only the portion displayed in the window will be saved. See also: @{" Buffer menu " link Menu_Buffer} @{" Main window " link MainWindow} @{" SaveWindow " link SaveWindow} @ENDNODE @NODE Menu_Save_buffer "Buffer menu/Save buffer..." BUFFER MENU / SAVE BUFFER... This menu option allows you to save the entire contents of the event buffer to a file. It corresponds to the @{" SaveBuffer " link SaveBuffer} command. This is very convenient if you have been monitoring a program's activities and decide too late that you should have opened a log file; you can use this option to save a permanent record of the program's actions. See also: @{" Buffer menu " link Menu_Buffer} @{" Main window " link MainWindow} @{" SaveBuffer " link SaveBuffer} @ENDNODE @NODE Menu_Clear_buffer "Buffer menu/Clear buffer" BUFFER MENU / CLEAR BUFFER This menu option erases all the output currently stored in the event buffer. It corresponds to the @{" ClearBuffer " link ClearBuffer} command. Clearing the buffer is always a good idea before you start monitoring the activities of a new program, because it avoids confusing output from that program with the output of programs that were run earlier. In addition, the event sequence numbers start counting from one again, which makes it easier to keep track of new events. See also: @{" Buffer menu " link Menu_Buffer} @{" Main window " link MainWindow} @{" ClearBuffer " link ClearBuffer} @ENDNODE @remark -------------------------------------------------------------- @remark @remark End of menu reference @remark @remark -------------------------------------------------------------- @NODE Index @TITLE "SnoopDos Index" -- SNOOPDOS INDEX -- @{" Action field " link Format_Action } @{" Keyboard support " link MainKeys } @{" ARexx monitoring " link SendRexx } @{" ARexx support " link ARexx } @{" Language support " link Language } @{" Author " link Author } @{" Log files " link OpenLog } @{" Call addr field " link Format_CallAddr } @{" Main window " link MainWindow } @{" CLI usage " link CLI } @{" Menu options " link Menu_Index } @{" Clipboard support " link CopyWindow } @{" Command index " link CommandIndex } @{" Options field " link Format_Options } @{" Command syntax " link CommandSyntax } @{" Contents " link MAIN } @{" Packet debugging " link PacketDebugger } @{" Count field " link Format_Count } @{" Pause " link Pause } @{" Credits " link Credits } @{" Process name " link Format_ProcessName } @{" Custom log output " link AddLog } @{" Quickstart " link QuickStart } @{" Date field " link Format_Date } @{" Quitting SnoopDos " link Quit } @{" Disable " link Disable } @{" Distribution " link Distribution } @{" Ramlib Patch " link PatchRamLib } @{" Result field " link Format_Result } @{" Event headings " link EventHeadings } @{" ROM monitoring " link MonitorROMCalls } @{" Event output " link EventOutput } @{" Segment name " link Format_SegmentName } @{" Font support " link WindowFont } @{" Settings files " link SettingsFiles } @{" Format editor " link FormatEditor } @{" Setup window " link SettingsWindow } @{" Format fields " link Format } @{" Single step " link SingleStep } @{" Function window " link FunctionWindow } @{" Stack limit " link StackLimit } @{" Status line " link StatusLine } @{" GNU C support " link MonitorPackets } @{" Target name field " link Format_TargetName } @{" History " link History } @{" TaskID field " link Format_TaskID } @{" Hotkey support " link HotKey } @{" Time field " link Format_Time } @{" Hunk:Offset field " link Format_HunkOffset } @{" What's new " link WhatsNew } @{" Icon support " link CreateIcons } @{" Workbench usage " link Workbench } @{" Iconify " link HideMethod } @{" Ignoring tasks " link MatchName } @{" Introduction " link Introduction } @ENDNODE