DOSTRACE

Dostrace is a TSR Utility that will allow you to trace and display the DOS
operating system calls your program is making.

Dostrace requires a 80286 processor, or better running DOS. It also requires
a color montior.

In addition to tracing operating system calls it will also show you :

1) what files are open, and the last IO operation against them.

2) The current PSP.

3) The current environment.

4) a Memory map of your system.

5) Display and edit any memory location. (You cannot edit ROM).

6) Display the value of the CPU registers for the executing program.

7) Watch a specified area of memory and Break when it changes.

After loading Dostrace you activate it by pressing left_shift-F1.
You will see a menu with the following Options.

Trace Table
Psp
Environment
File Table
Memory Map
Storage
Watch
Break
Registers
Display
Uninstall

Press the first letter of any menu item to select that item.

Trace Table.
++++++++++++

The trace table stores the last 100 calls made to the operating system
the general layout of a trace entry is.

(1)(2) (3) <------- 4 --------> (5) (6)
1234 READ DOSTRACE.COM 0005:0060 3BD6 0000 0060 0246

(1). This is a counter of the number of calls made to the operating system.
It will reset at 10,000

(2) This is the type of operating system request.

(3) This is the file,program etc that the request was made against.

(4) This is useful data for the type of request. In this example they
are :
0005 = The file Handle
0060 = number of bytes to read
3BD6 0000 = address to read the data into

(5) The return code from DOS. In this examples the number of bytes read.

(6) The value of the Flags register.

Dostrace will only store 100 entrys. After that the trace table WRAPS by
discarding the oldest entry.

Dostrace does not trace all possible DOS Calls.

Psp.
++++

This selections allows you to display, and edit the current PSP.

Environment.
++++++++++++

This selection allows you to display, and edit the currently executing
programs Environment.

File Table.
+++++++++++

This selection shows you what files are open on your system. The layout
is as follows.

(1) (2) (3) (4) (5) (6)
20 1DFA 3800:0000 0020 R DOSTRACE.ASM

1 = file handle from DOS.
2 = Owning PSP address.
3 = address of last read/write buffer.
4 = number of bytes for the last read write operation
5 = R if last operation was a read. W if it was a write.
6 = the file name.

The file table will keep track of 40 files.

File handles 0-4 are not displayed unless they have been closed and opened
as new files.

Memory Map.
+++++++++++

Thisselection will show you how memory is being used by programs and
TSRs on your computer. The display layout is as follows.

(1) (2) (3) (4) (5)
Address Size Owner Type Parent

0DE4 0010 0DF5 DOSEDIT ENV
0DF5 007B 0DF5 DOSEDIT PSP 0CCB DOS
67F8 3800 FREE

1 = The address of the memory block.
2 = The size of the memory block, in paragraphs. (1 paragraph = 16 bytes)
3 = The address of the PSP that owns this block and, if dostrace can
determine it, the owning programs name. If this block of memory is
free the owner is shown as FREE.
4 = the type of memory. ENV = Program environment.
PSP = Program PSP and its associated code.
MEM = program memory allocated via an operating
system call.
5 = if the type is PSP this will show the parents PSP and, if dostrace
can determine it the parent programs name.

The currently active program will be shown in yellow.

Storage.
++++++++

This selection allows you to enter a memory address, in hex. The program
will then display, and allow you to edit, memory at that address. you can
use page up, page down and the cursor keys to scroll through memory.

Watch.
++++++

Watch allows you to enter a memory address and a length. Dostrace then uses
the single step feature of the processor to monitor that memory area.
If the areais changed Dostrace will POP-UP telling you where in the memory
area the change was made. You may then make use of the dostrace features
to determine which area of your program made the change.


Break.
++++++

This option allows you to enter a DOS Function Code, in Hex (i.e 3D = OPEN FILE),
and an optional character of (G)ood return from DOS (B)ad return from DOS
or (A)ll. Dostrace will then break when ever a program makes that DOS call
and will display the trace table at the entry for that call. This option
can be deactivated by selecting Break from the menu and pressing ESC.

Registers.
++++++++++

This option shows you the value of the CPU registers at the time you
pressed left_shift-F1.


Display.
++++++++

This option shows you the current programs screen image.

Uninstall.
++++++++++

This option Uninstalls Dostrace and frees up any memory allocated to it.
If a subsequent TSR or the current program has hooked into an interrupt
that Dostrace uses you will get the message 'CANNOT UNINSTALL'



Startup Parameters.
+++++++++++++++++++

Dostrace currently accepts two start up parameters -e and -f :

-e will attempt to place the trace table in expanded memory. If
none is found Dostrace will use conventional memory.

-f will trace entrys to the file specified by file_name.
this will continue until your disk fills up or you uninstall Dostrace.
Registered users will receive an EXE that will display the contents of
this file in a readable form.


Dostrace will also break and display a message if your program attempts
to execute an invalid instruction. You may then use any of the above
features to try and determine what went wrong. On exiting Dostrace, by
pressing the escape key, Dostrace will attempt to close any open files
your program may have and terminate your program in an orderly fashion.
The success of this depends on how much damage your program did before
the invalid instruction.


Dostrace is distributed as is. Please feel free to copy it.
If you find this product useful and would like to register for free
upgrades and a more comprehensive manual send $25 to the address below.
If you would like the source code and make file for Dostrace plus the
manual send $60 to the address below. If you have any questions, comments
or problems you can email me at CIS (ID 71507,1033).

Steve Bridges
1391 union street
Manchester NH 03104.