17 Bit Software 4: Phase Four

home *** CD-ROM | disk | FTP | other *** search

/ 17 Bit Software 4: Phase Four / 17Bit_Phase_Four.iso / files / 3137.dms / 3137.adf / DOSTrace2.20 / DT.doc < prev next >

Wrap

Text File | 1978-01-07 | 25.2 KB | 685 lines

-------------------------------------------------------------------------------- DOSTrace Help -------------------------------------------------------------------------------- DOSTrace 2.20 Copyright © 1993, 1994 Peter Stuer All rights reserved Release date 12 May 1994 FREEWARE User Manual 'Introduction ' What can I do with DOSTrace ? 'Feature List ' What features does DOSTrace have ? 'Requirements ' Will it run on my system ? 'Usage ' How do I use DOSTrace ? 'Known bugs ' Things I should know... 'To do ' Wishes, to do's, etc... 'How to reach me ' How can I reach the author ? 'Acknowledgements ' Who does the author want to thank ? 'History ' What's new in this version ? -------------------------------------------------------------------------------- DOSTrace: Introduction -------------------------------------------------------------------------------- DOSTrace is a program that allows you to monitor what AmigaDOS is doing while you are working with your Amiga. You can watch which files your programs use, if they find all the files they require, where they are looking for them and much other activity of that kind. If this sounds familiar to you, you must be one of the many SnoopDos users in the Amiga community. This tool was written to replace SnoopDos. It shows you a lot more information than SnoopDos and it does this in a verbose way. SnoopDos is written by Eddy Carroll and freely distributable. COPYRIGHT NOTICE DOSTrace software and documentation are Copyright © 1993, 1994 by Peter Stuer. All rights reserved. DISCLAIMER DOSTrace has proven to be stable in everyday use. 'The author' is not responsible for any loss of data, damages to software or hardware that may result directly or indirectly from the use of this program. The author reserves the right to make changes to the software or documentation without notice. PREFACE This program is freeware, this means that you can copy it freely as long as you don't ask any more money for it than a nominal fee for copying. If you want to distribute this program you should keep this document with it. This program cannot be used for commercial purposes without written permission from the author. None of the files of the DOSTrace package may be modified or left out without permission of the author. Crunching or archiving is allowed only if none of the DOSTrace files get modified by it. Special permission is hereby granted to include DOSTrace in Public-Domain collections such as Fred Fish's Amiga Library. -------------------------------------------------------------------------------- DOSTrace: Features -------------------------------------------------------------------------------- DOSTrace monitors a lot more AmigaDOS activity than SnoopDOS. Currently the following functions can be monitored: AddBuffers LoadSeg (InternalLoadSeg, NewLoadSeg) Close Lock CreateDir MakeLink CurrentDir Open DeleteFile ParentDir DeviceProc Read ExAll Rename Examine SetComment ExamineFH SetOwner Execute StartNotify FRead SystemTagList FWrite UnLock GetDeviceProc Write Info You can specify which functions DOSTrace should monitor via the 'commandline' or via a 'list requester'. DOSTrace saves the trace information it gathers as session history. It provides a scrollbar which enables you to scroll through the session history. This session history can be 'saved' and 'printed'. DOSTrace is also a commodity. You can specify a 'hotkey' to show or hide the output window. DOSTrace can open on any 'public screen'. DOSTrace can trace a single 'task' specified by the user. -------------------------------------------------------------------------------- DOSTrace: System requirements -------------------------------------------------------------------------------- DOSTrace should run on any Amiga system with at least 512K RAM and one disk-drive. DOSTrace requires KickStart v2.04 or higher to run. Special care has been taken in the program design to make the program work with 68020, 68030 and 68040 processors without sacrificing 68000 compatibility. DOSTrace also requires the ReqTools.library v38 or higher. ReqTools is copyright © 1992, 1993, 1994 by Nico François. DOSTrace is KickStart 3.0 compatible and aware. It will show you some of the new features available with this version of the operating system. Should you have any trouble running DOSTrace on your machine, please 'contact me' with the full specifications of your machine, that is KickStart version, model, expansion boards etc... -------------------------------------------------------------------------------- DOSTrace: About the author and the program -------------------------------------------------------------------------------- DOSTrace has been created using the Macro68 Assembler and CygnusEd Professional 3 on an Amiga A3000 25/100 with 10MB memory. If you have suggestions or remarks about this program, or if you find any bugs, please let me know. When sending in bug reports, please state exactly under what circumstances the bug occurred, what equipment was used and what happened. If possible also try to give me enough information to reproduce the bug. It is very difficult to find bugs when you don't know exactly what happened. Write to the following address: Fido : 2:292/603.7 (Peter Stuer) AmigaNet : 39:120/102.7 (Peter Stuer) NLA Net : 14:200/101.7 (Peter Stuer) UUCP : Peter.Stuer@p7.f603.n292.z2.FidoNet.Org SnailMail: Peter Stuer Beatrijslaan 2 bus 13 B-2050 Antwerpen L.O. Belgium - Europe I will also try to put the latest available version of DOSTrace on the following BBS (this may change without further notice): NightBreed BBS (Herman Stevens, Lubbeek) ReqTools Support BBS ADS Distribution HUB ABC Host Belgium AFN Host Belgium Tel. +32-(0)16-64.09.12 ZyXEL U1496+ 16800 BPS (N.8.1) v32bis v42bis 24-24 h. Fido Node 2:292/603 NLA Node 14:200/101.0 AmyNet 39:120/102.0 -------------------------------------------------------------------------------- DOSTrace: Usage -------------------------------------------------------------------------------- You can be start DOSTrace from the 'CLI/Shell' or the 'Workbench'. DOSTrace will always check to make sure it is not already running. If so, a copy of DOSTrace that is already running will be notified and its window will open or come to the front. The second copy will exit quietly. DOSTrace has 3 menus: 'Project' 'History' 'Prefs' Additional information: 'Stopping DOSTrace' 'About the output ' -------------------------------------------------------------------------------- DOSTrace: Starting DOSTrace from the Shell -------------------------------------------------------------------------------- To start DOSTrace from the Shell simply type: 1> DOSTrace followed by a return. If you want to continue using the Shell while DOSTrace is running, you need to prepend the Run command before DOSTrace as follows: 1> run DOSTrace If DOSTrace is succesful in initializing itself, you see the DOSTrace window and will start monitoring AmigaDOS. DOSTrace can be started with various 'Options'. If you run DOSTrace with a questionmark (?) as argument you'll get the argument template. -------------------------------------------------------------------------------- DOSTrace: Options -------------------------------------------------------------------------------- HISTORY This option tells DOSTrace how many lines of session history it should keep. Use 0 to disable the history feature. The default number of history lines is 256. OUTPUT With this option you can direct the trace information to some other AmigaDOS device of file in addition or in place of the information being displayed in the window. If you have a debugging terminal attached to the serial port you could use 'DOSTrace OUTPUT=AUX:' to have all trace information appear at the terminal. A special symbol is DEBUG. 'OUTPUT=DEBUG' will output all trace information to the serial port at 9600 baud. LEFT This option specifies the left position of the DOSTrace output window in pixels. By default, the leftedge will be zero (0). TOP This option specifies the top position of the DOSTrace output window in pixels. By default, DOSTrace will open its window 1 pixel under the screen title bar. WIDTH This option specifies the width of the DOSTrace output window in pixels. By default, DOSTrace will open a window that is as wide as the visible width of the public screen it is appearing on. HEIGHT This option specifies the height of the DOSTrace output window in screen lines. By default, DOSTrace will open a window that is as high as the visible height of the public screen it is appearing on, without overlapping the title bar. ALTLEFT This option specifies the alternale left position of the DOSTrace output window in pixels. By default, the alternate leftedge is zero (0). ALTTOP This option specifies the alternate top position of the DOSTrace output window in pixels. By default, the alterante top is zero (0). ALTWIDTH This option specifies the alternate width of the DOSTrace output window in pixels. By default, this is ¼ of the normal width. ALTHEIGHT This option specifies the height of the DOSTrace output window in screen lines. By default, this is ¼ of the normal height. SCREEN If you do not use this option, DOSTrace will open on the default public screen which is most of the times the Workbench screen. DOSTrace will try to open on the public screen whose name is specified after this argument. TRACE/DONTTRACE By specifying a trace mask using the TRACE parameter you can determine which AmigaDOS functions DOSTrace will actually trace. The trace mask consists of a string of characters. The function corresponding to the character will be traced. Use the following characters (case sensitive): A: AddBuffers M: LoadSeg B: CreateDir N: Lock C: CurrentDir O: MakeLink D: DeleteFile P: NewLoadSeg E: DeviceProc Q: Open F: ExAll R: ParentDir G: Examine S: Rename H: ExamineFH T: SetComment I: Execute U: SetOwner J: GetDeviceProc V: StartNotify K: Info W: SystemTagList L: InternalLoadSeg X: Close Y: UnLock a: Read c: FRead b: Write d: FWrite For example, TRACE=CDMNQI will only trace the AmigaDOS functions that SnoopDOS 1.7 traces. By default, DOSTrace monitors all AmigaDOS functions it knows about. Specifying a trace mask for DONTTRACE will make DOSTrace ignore the functions that you specify here. For example, DONTTRACE=abcd will hide the many read/write operations some programs make. The DONTTRACE trace mask always takes precedence over the TRACE trace mask. TASK If you want to trace the dos operations of a particular task, this option will allow you to specify the address of that task. For example, DT TASK=_$0786ecc8 will only show the activity of the program that has its Task/Process structure at address _$0786ECC8. The dollar sign ($) is optional and the number is case-insensitive. When DOSTrace is already running, you can use the 'Task' menuitem of the "Project" menu. The name of the task currently being traced will be shown in the title bar of the DOSTrace window. To stop tracing a particular task, select the {" Task " link MenuProject} menuitem of the "Project" menu and close the list requester that appears without selecting a new task. The title bar will reset and DOSTrace will continue to trace all tasks. USEICON{ub} Some people like to keep all settings of a program in the icon. If you start DOSTrace from the CLI with this argument, DOSTrace will try to find its icon and use the tooltypes it finds there. This argument has no equivalent tooltype. CX_PRIORITY This option allows you to specify priority relative to the other Commodities programs. Default priority is 0. CX_POPKEY This option allows you to change the default hot key for DOSTrace. The default hot key is 'ralt d' (right Alt key pressed with 'd'). The current hot key will be shown in the title bar of the DOSTrace window. CX_POPUP If you do not want DOSTrace to open its window, you can specify the CX_POPUP switch like this: DOSTrace CX_POPUP=NO. By default, the DOSTrace window will open. CX_ACTIVE By specifying CX_ACTIVE=NO, DOSTrace start without its tracing code enabled. By default, tracing starts immediately. -------------------------------------------------------------------------------- DOSTrace: Starting DOSTrace from the Workbench -------------------------------------------------------------------------------- To start DOSTrace from the Workbench, simply double-click on the DOSTrace icon to start the program or use the 'Execute Command' item from the 'Workbench' menu. To modify DOSTrace's behaviour you can add several 'tooltypes' to the DOSTrace icon. NOTE If you use the CX_POPUP and/or the CX_ACTIVE tooltype you must specify them with '=YES' appended to them. For example, 'CX_POPUP=YES'. Not using them defaults to CX_POPUP=YES and CX_ACTIVE=YES. To change the task priority of DOSTrace you can add the TOOLPRI tooltype to the DOSTrace icon. For example, adding TOOLPRI=5 will start running DOSTrace with task priority 5. -------------------------------------------------------------------------------- DOSTrace: Stopping DOSTrace -------------------------------------------------------------------------------- You can stop DOSTrace at any time by sending it a break signal. If you started DOSTrace from the Shell, you can do this by pressing Ctrl-C. Since DOSTrace is a commodity you can use the Exchange utility to control it. 'Show Interface' will open the DOSTrace output window 'Hide Interface' will close the DOSTrace output window The 'Active/Inactive' cycle gadget will toggle DOSTrace's activation status. When DOSTrace is active it will update it's internal history even when the output window is closed; when it is inactive, no tracing will occur. 'Remove' will tell DOSTrace to quit. NOTE DOSTrace will try to quit immediately. If any of the patches are still in use, it will wait until no program uses the DOSTrace patches anymore. -------------------------------------------------------------------------------- DOSTrace: The Project menu -------------------------------------------------------------------------------- The Project menu gives you some control over DOSTrace's behaviour while it is running. The Active menu item DOSTrace is 'active' when it is allowed to monitor AmigaDOS operations. When this menu item is checked, DOSTrace is active. The Task menu item Selecting this menu item will pop up list requester showing all the tasks and processes that are running on your system. If you click on any of the entries displayed, DOSTrace will only trace the DOS calls made by the selected process. To make DOSTrace trace all DOS calls again, bring up the list requester again and just close it. To close the requester, click on the window close button or press Esc. The About menu item Displays the version number and release date of DOSTrace. The Hide menu item Does the same as the Hide gadget of the Exchange program. DOSTrace stays in memory and, depending on its activation status, continues to trace AmigaDOS. The Quit menu item This causes DOSTrace to try to quit. See also 'Stopping DOSTrace' -------------------------------------------------------------------------------- DOSTrace: The History Menu -------------------------------------------------------------------------------- The 'Clear' menu item clears the session history and the window. The 'Save' menu item will bring up a file requester allowing you to specify the directory and the filename that DOSTrace should use to save the current history to. During saving the tracing is temporarily deactivated. The 'Print' menu item allows you to print the current history log to the printer selected in the Printer preference program. -------------------------------------------------------------------------------- DOSTrace: The Prefs Menu -------------------------------------------------------------------------------- The 'Patches' menu item will pop up a list requester that shows all the patches that DOSTrace has installed to trace AmigaDOS calls. Next to the name of the patch is its status. Click on the patch name to toggle its status. While this requester is visible, tracing is temporarily deactivated. To close the requester, click on the window close button or press Esc. -------------------------------------------------------------------------------- DOSTrace: About the trace output -------------------------------------------------------------------------------- The information shown depends on which function is being traced but all messages have 3 components in common: Process Name The name of the process calling the AmigaDOS function. Trace Info Verbose information about the function being executed. Result Whether the call was succesfull or not (if applicable) -------------------------------------------------------------------------------- DOSTrace: Known bugs -------------------------------------------------------------------------------- A note about DOSTrace and MultiView: Several users have reported that when DOSTrace is running, MultiView does not show any AmigaGuide file. I have experienced this during development too and have narrowed it down to the NameFromLock() call DOSTrace makes while tracing UnLock(). Apparently, MultiView or the amigaguide.datatype does not like this. Since everything works fine when I remove this call from the UnLock() trace code, I can only suspect this is some sort of bug in MultiView or the amigaguide.datatype. A workaround is to disable the UnLock() trace code using: DT donttrace Y -------------------------------------------------------------------------------- DOSTrace: To do, wishes, suggestions... -------------------------------------------------------------------------------- · Keeping the same position in the session history after a resize. · An ARexx port. · An alternative, less verbose output mode. · A horizontal scroll bar. -------------------------------------------------------------------------------- DOSTrace: History -------------------------------------------------------------------------------- ::: Version 2.20 ::: May 12, 1994 ::::::::::::::::::::::::::::::: - NEW: A much requested feature: selecting the Task menu item now produces a listrequest showing all tasks and processes. The TASK commandline argument still expects an address. - NEW: The new 'History' menu groups all functions that act on the history buffer. 'Save' and 'Print' suggested by Alex Van Boxel. - NEW: Use the 'Patches' menu item of the new 'Prefs' menu to pop up a list requester with all patches and their activation states. This requester will allow you to dynamically change the active patches while DOSTrace is running. - NEW: New commandline options/tooltypes to specify the alternate window position and dimension. Suggested by Bill Beogelein. - NEW: If you specify the USEICON argument, DOSTrace will try to read the tooltypes from its icon. Suggested by Paul Colclough. - BUG FIX: The 'Active' menu item did not always reflect the true state of DOSTrace when the program reopened its window. Thanks to Stefan Odendahl for reporting this. - BUG FIX: Ctrl-C can be used again to quit DOSTrace. - IMPROVED: The window title of the DOSTrace window now shows the hotkey. Thanks to Magnus Holmgren for suggesting this. - IMPROVED: DOSTrace now issues an error message if there is something wrong with any of the commandline arguments. To remain compatible with earlier version, this message does not cause DOSTrace to stop running. Suggested by Magnus Holmgren. - IMPROVED: Made the restoring of the patched vectors more OS friendly. - IMPROVED: A Magic Workbench icon is included. Created by Tobias Ferber. ::: Version 2.13 ::: December 14, 1993 :::::::::::::::::::::::::: - BUG FIX: Fixed a small bug that caused high-ASCII characters in filenames to disappear. Thanks to Stefan Ottosson for reporting this. - BUG FIX: The session history was not redrawn if there were less lines in the session history than could be displayed. Thanks to David Nouls & Bart van Assche for reporting this. ::: Version 2.12 ::: December 6, 1993 ::::::::::::::::::::::::::: - NEW: Added trace code for Read(), Write(), FRead() and FWrite(). Thanks to Preben Nielsen for suggesting this. - NEW: LEFT and TOP options let you specify the left and top position of the DOSTrace window. Thanks to Preben Nielsen for suggesting this. - NEW: DOSTrace remembers the position and dimensions of its window when it shows it window again after a 'Hide'. - NEW: You can use the following keys to control the position of the session history: Cursor Up/Cursor Down 1 line up/down Shift Cursor Up/Cursor Down 1 page up/down Control Cursor Up/Cursor Down top/bottom Thanks to Magnus Holmgren for suggesting this. - NEW: To avoid using a ridiculously long TRACEMASK parameter if you DON'T want to see the trace results of a function, I replaced the TRACEMASK parameter with the TRACE and DONTTRACE parameter. For more information, see the documentation. - NEW: Brought the manual up to date and added more links in the AmigaGuide file. - BUG FIX: Due to register leaking DOSTrace would exit sometimes when it reopened its window after another copy of DOSTrace woke the original up. Thanks to Rafael D'Halleweyn and Magnus Holmgren for reporting this. - BUG FIX: DOSTrace ignored the CX_PRIORITY argument. Thanks to Rafael D'Halleweyn for reporting this. - BUG FIX: The broker name of DOSTrace did not fit completely in the provided space by Exchange. Thanks to Rafael D'Halleweyn for reporting this. - BUG FIX: Fixed a bug that could cause a lock-up of the console device during a refresh of the history. Thanks to Bart van Assche for helping me to track it down. ::: Version 2.11 ::: Not released ::::::::::::::::::::::::::::::: - This version accidentally leaked out as ßeta. ::: Version 2.10 ::: November 15, 1993 :::::::::::::::::::::::::: - NEW: Added trace code for Close and UnLock. - NEW: Removed the annoying delay when quitting DOSTrace. Thanks to Rafael D'Halleweyn for the suggestion. - NEW: Added up/down gadgets to scroll up/down line by line. - NEW: Added the TASK option and Task menu item (requested by Jan Dujardin) - NEW: Added Clear menu item to clear the history buffer while DOSTrace is running. - NEW: Added an Active menu item to make activating and deactivating DOSTrace on the fly easier. - IMPROVED: Optimized some of the core routines. - IMPROVED: DOSTrace starts active and with the output window open when run from the CLI. - IMPROVED: Removed inner border to make DOSTrace more conform to the Style Guide. - IMPROVED: Execute() and SystemTagList() now show which program they are trying to run before the program starts running. - IMPROVED: When DOSTrace is unable to determine the filename of the object a DOS function is acting on it will use the name "Unknown Object" instead. You will notice this especially when closing or unlocking objects that do not or incompletely support a file system like CON:, PRT: or NIL:. - BUG FIX: Removed a bug that caused a signal to stay allocated. - BUG FIX: Fixed a display bug. ::: Version 2.00 ::: August 21, 1993 :::::::::::::::::::::::::::: - Complete rewrite. - NEW: Added monitoring code for InternalLoadSeg and NewLoadSeg. - IMPROVED: Made trace code smaller and faster. - BUG FIX: Suppressing Workbench's background DOS operations did not work always. - BUG FIX: I forgot (again) that some programs still wrongly expect that D0 and D1 are equal when returning from LoadSeg. This should fix problems with programs that use old overlay managers. ::: Version 1.00 ::: June 22, 1993 :::::::::::::::::::::::::::::: - First release -------------------------------------------------------------------------------- DOSTrace: Acknowledgments -------------------------------------------------------------------------------- Thanks to Nico François, Johan van Houtven, Hermans Stevens, Jan Dujardin, Rafael D'Halleweyn, Bart van Assche, Stu Churchill, Magnus Holmgren, Per-Anders Josefsson and Alex Van Boxel for testing DOSTrace. _ _ // Thanks to \\X/ Amiga for being the best computer ever!