DOSTrace v2.10 User Manual 1 DOSTrace v2.10 Copyright © 1993 Peter Stuer All rights reserved Release date November 15, 1993 FREEWARE User Manual COPYRIGHT NOTICE DOSTrace software and documentation are Copyright © 1993 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 v2.10 User Manual 2 Chapter 1 Introduction 1.1 What is DOSTrace ? 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. 1.2 Features of DOSTrace 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 Rename ExAll SetComment Examine SetOwner ExamineFH StartNotify Execute SystemTagList GetDeviceProc UnLock Info You can specify which functions DOSTrace should monitor. DOSTrace saves the trace information it gathers as session history. It provides a scrollbar which enables you to scroll through the session history. 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. 1.3 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 v2.10 User Manual 3 DOSTrace also requires the ReqTools.library v38 or higher. ReqTools is copyright © 1992, 1993 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... 1.4 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. The DOSTrace documentation was formatted with PRoff. 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): Great Balls Of Fire BBS ReqTools Support BBS Herman Stevens Lubbeek 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 DOSTrace v2.10 User Manual 4 AmyNet 39:120/102.0 DOSTrace v2.10 User Manual 5 Chapter 2 Using DOSTrace 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, the copy of DT that is already running will be notified and its window will open or come to the front. The second copy will exit quietly. 2.1 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. If no window is displayed, consult Appendix A (Troubleshooting) for more assistance. 2.2 Shell Startup Options DOSTrace can be started with various options. If you run DOSTrace with a questionmark (?) as argument you'll get the argument template. HISTORY This option tells DOSTrace how many lines of 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. WIDTH This option specifies the width of the DOSTrace output window DOSTrace v2.10 User Manual 6 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. 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. TRACEMASK By specifying a trace mask 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: 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 For example, TRACEMASK=CDMNQI will only trace the AmigaDOS functions that SnoopDOS 1.7 traces. By default, DOSTrace monitors all AmigaDOS functions it knows about. 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. This will pop up a requester that asks you to enter the address of the Task/Process structure of the program you want to trace. If you enter an DOSTrace v2.10 User Manual 7 address that does not point to a Task structure, DOSTrace will beep the display. 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" menuitem of the "Project" menu and clear the address shown there. If you then select "Ok", the title bar will reset and DOSTrace will continue to trace all tasks. 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'). CX_POPUP If you do not want DOSTrace to open its window, you can specify the CX_POPUP switch like this: DT 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. 2.3 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. 2.4 Workbench Startup Options You can specify the same options as explained in the paragraph "Shell Startup Options" by adding 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. DOSTrace v2.10 User Manual 8 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. 2.5 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. The "Active" menuitem of the "Project" menu will also allow you to toggle the activation status of DOSTrace. 'Remove' will tell DOSTrace to quit. The 'Quit' menu item will exit DOSTrace. 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. 2.6 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 HISTORY :::::::::::::::::::::::: ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: DOSTrace v2.10 User Manual 9 ::: 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 DOSTrace v2.10 User Manual 10 managers. ::: Version 1.00 ::: June 22, 1993 :::::::::::::::::::::::::::::: - First release Table Of Contents DOSTrace v2.10 Chapter 1 Introduction ................................ 2 1.1 What is DOSTrace ? ............................... 2 1.2 Features of DOSTrace ............................ 2 1.3 System requirements ............................ 2 1.4 About the author and the program ................... 3 Chapter 2 Using DOSTrace ............................... 5 2.1 Starting DOSTrace from the Shell .................. 5 2.2 Shell Startup Options ........................... 5 2.3 Starting DOSTrace from the Workbench .............. 7 2.4 Workbench Startup Options ....................... 7 2.5 Stopping DOSTrace .............................. 8 2.6 About the trace output ........................... 8 Copyright © 1993 DOSTrace v2.10 written by Peter Stuer Thanks to Nico François, Johan van Houtven, Hermans Stevens, Jan Dujardin, Rafael D'Halleweyn, Stu Churchill, Magnus Holmgren and Per-Anders Josefsson for testing DOSTrace. _ _ // Thanks to \X/ Amiga for being the best computer ever !