home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
AmigActive 19
/
AACD19.BIN
/
AACD
/
System
/
DOSTrace
/
DT.doc
< prev
next >
Wrap
Text File
|
1994-01-23
|
23KB
|
834 lines
DOSTrace v2.13 User Manual 1
DOSTrace v2.13
Copyright © 1993 Peter Stuer
All rights reserved
Release date December 14, 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.13 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 Read
ExAll Rename
Examine SetComment
ExamineFH SetOwner
Execute StartNotify
FRead SystemTagList
FWrite UnLock
GetDeviceProc Write
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
DOSTrace v2.13 User Manual 3
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 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.
DOSTrace v2.13 User Manual 4
Fido Node 2:292/603
NLA Node 14:200/101.0
AmyNet 39:120/102.0
DOSTrace v2.13 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.
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 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).
DOSTrace v2.13 User Manual 6
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.
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.
DOSTrace v2.13 User Manual 7
Specifying a trace mask for DONTTRACE will make DOSTrace
ignore the functions that you specify here. For example,
DONTTRACE=abcd will cause the many read/write operations some
programs make not to be shown.
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" 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.
DOSTrace v2.13 User Manual 8
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.
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.
'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.
2.6 The Project menu
The Project menu gives you some control over DOSTrace's behaviour
while it is running.
2.6.1 The Active menu item
DOSTrace is 'active' when it is allowed to monitor AmigaDOS
DOSTrace v2.13 User Manual 9
operations. When this menu item is checked, DOSTrace is active.
2.6.2 The Task menu item
This menu item will cause a requester to pop up that asks you to
enter the address of the Task/Process structure of the program you
want to trace. If you enter an address that does not point to a
Task structure, DOSTrace will beep the display. See also the To Do
list and the TASK startup option.
2.6.3 The Clear menu item
Clears the session history and the window.
2.6.4 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.
2.6.5 The Quit menu item
This causes DOSTrace to try to quit. See also 'Stopping DOSTrace'.
2.7 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)
2.8 To do wishes suggestions...
· A listrequester to select the task that should be monitored
· Auto-detach from the CLI
· Keeping the same position in the session history after a resize
· An ARexx port
· Prefs panel
· An alternative, less verbose output mode
DOSTrace v2.13 User Manual 10
:::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
::::::::::::::::::::::: DOSTRACE HISTORY ::::::::::::::::::::::::
:::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
::: 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.
DOSTrace v2.13 User Manual 11
::: 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.
DOSTrace v2.13 User Manual 12
- 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
Table Of Contents
DOSTrace v2.13
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 ....................... 8
2.5 Stopping DOSTrace .............................. 8
2.6 The Project menu ................................ 8
2.6.1 The Active menu item ........................ 8
2.6.2 The Task menu item .......................... 9
2.6.3 The Clear menu item ......................... 9
2.6.4 The Hide menu item .......................... 9
2.6.5 The Quit menu item .......................... 9
2.7 About the trace output ........................... 9
2.8 To do wishes suggestions... ...................... 9
Copyright © 1993 DOSTrace v2.13 written by Peter Stuer
Thanks to Nico François, Johan van Houtven, Hermans Stevens, Jan
Dujardin, Rafael D'Halleweyn, Bart van Assche, Stu Churchill,
Magnus Holmgren and Per-Anders Josefsson for testing DOSTrace.
_
_ //
Thanks to \X/ Amiga for being the best computer ever!