DOSTrace v2.00 User Manual 1 DOSTrace v2.00 Copyright © 1993 Peter Stuer All rights reserved Release date August xx, 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. Crunching or achiving 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.00 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 2.0 DOSTrace monitors a lot more AmigaDOS activity than SnoopDOS. Currently the following functions can be monitored: AddBuffers LoadSeg (InternalLoadSeg, NewLoadSeg) CreateDir Lock CurrentDir MakeLink DeleteFile Open DeviceProc ParentDir ExAll Rename Examine SetComment ExamineFH SetOwner Execute StartNotify GetDeviceProc SystemTagList 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. 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 also requires the ReqTools.library v38 or higher. ReqTools is copyright © 1992, 1993 by Nico François. DOSTrace v2.00 User Manual 3 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 AmyNet 39:120/102.0 DOSTrace v2.00 User Manual 4 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.00 User Manual 5 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 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. 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 specify the CX_POPUP switch, DOSTrace will run DOSTrace v2.00 User Manual 6 without opening its window. By default, the DOSTrace window will not open. CX_ACTIVE You must specify the CX_ACTIVE switch if you want DOSTrace to start tracing immediately when it is run. 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'. 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 output will occur. 'Remove' will tell DOSTrace to quit. The 'Quit' menu item will exit DOSTrace. DOSTrace v2.00 User Manual 7 NOTE DOSTrace will wait 3 seconds before leaving memory to make sure no program is using its code anymore. Try to avoid any AmigaDOS activity while DOSTrace is exiting. The 'delay' method is not fail-safe. 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 :::::::::::::::::::::::: ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: ::: Version 2.00 :::::::::::::::::::::::::::::::::::::::::::::::: - Complete rewrite. - 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. - IMPROVED: Made trace code smaller and faster. - NEW: added monitoring code for InternalLoadSeg and NewLoadSeg. ::: Version 1.00 ::: June 22, 1993 :::::::::::::::::::::::::::::: - First release Table Of Contents DOSTrace v2.00 Chapter 1 Introduction ................................ 2 1.1 What is DOSTrace ? ............................... 2 1.2 Features of DOSTrace 2.0 ......................... 2 1.3 System requirements ............................ 2 1.4 About the author and the program ................... 3 Chapter 2 Using DOSTrace ............................... 4 2.1 Starting DOSTrace from the Shell .................. 4 2.2 Shell Startup Options ........................... 4 2.3 Starting DOSTrace from the Workbench .............. 6 2.4 Workbench Startup Options ....................... 6 2.5 Stopping DOSTrace .............................. 6 2.6 About the trace output ........................... 7 Copyright © 1993 DOSTrace v2.00 written by Peter Stuer _ _ // Thanks to \X/ Amiga for being the best computer ever !