         DD&T - Debugger Disassembler and Trace Utility
                                
                         [            ]
                         [            ]
                         [DD&T Graphic]
                         [            ]
                         [            ]
                                
                       TABLE OF CONTENTS

    General Information.....................................1
    DD/CMD - Debugger Disassembler..........................2
    DOS Program Trace Utility ..............................3
    PTRACE - Program Trace Module ..........................3
    STRACE - Statistical Trace Report.......................4
                                                                        
DD/CMD, PTRACE/CMD, and STRACE/CMD: Copyright 1984 by Richard N. Deglin, All
rights reserved. DD&T is published by MISOSYS, Inc., Sterling VA 22170.

LDOS and LS-DOS are trademarks of Logical Systems Inc. 
TRSDOS is a trademark of Tandy Corp.

GENERAL INFORMATION
    This documentation covers the Model I/III version of DD&T which functions
under the LDOS 5.1 operating system. It also covers the TRSDOS 6.x or LS-DOS
6.x version of DD&T called PRO-DD&T. The specific version of DD&T is noted on
the diskette label supplied with this package. The D0&T package provides the
assembler programmer with a major enhancement to the debugger supplied with
your DOS. The Debugger Disassembler module is completely relocatable. Its
interface to the DOS debugger is automatic. The TRACE utility can be used to
help hone your programs to optimum efficiency. DD and TRACE together make DD&T
a set of fine tools crafted to provide you with a rewarding assembler
programming experience.

                             DD&T - 1

         DD&T - Debugger Disassembler and Trace Utility

DD/CMD - Debugger Disassembler

    DD/CMD is an enhancement to the DOS system debugger which provides the
added capability of an on-line disassembler during your program debugging
sessions. Once invoked, it resides interfaced to the system's DEBUG module
available at the touch of a button. DD is invoked via the command:

	=================================================
	|						|
	| Db (parameter)				|
	| 						|
	| ON     Loads the DD module into high memory	|
	|	 and links into the system debugger.	|
	|						|
	| OFF    Unlinks DD from the debugger and 	|
	| 	 reclaims high memory if possible.	|
	|						|
	| Abbr: ON=YES or Y. OFF=NO or N		|
	=================================================

     The command "DD (ON)" or "DD" loads the DD high memory module and links
itself into the system debugger. DD may be SYSGENed if you find it convenient
to have the Debugger Disassembler available at each boot. The high memory
module takes less than 1600 bytes of memory. A subsequent entry into the
system debugger (normal or extended) activates the DD module. In the upper
right hand corner of the debugger register display ("X" mode), DD will display
a mnemonic disassembly of the 280 instruction which the current program
counter (PC) points to. After a single-stepping debugger command ("I", "C", or
"J") is executed, or a breakpoint is reached via use of the "G,nnnn" command,
DD will update this instruction disassembly automatically.

     DD also provides for 280 disassembly directly from any memory location in
your computer's 64 Kilobyte address space. The command "Z<ENTER>" will start
the disassembly from the current program counter. The command "Znnnn<ENTER>"
will start the disassembly from the hexadecimal address given in the command
as "nnnn". The screen will clear, and 16 or 24 lines of disassembled
instructions will be displayed, depending on whether you are operating version
5 or 6 of the DOS. You may continue the display with one or more additional
screenfulls of disassembly by typing any keystroke; if you type "X", however,
you will be returned to the prior debugger display screen ("X", or "S" mode).

    The DOS command "DD (OFF)" will unlink DD from the system debugger and
attempt to reclaim high memory space. If DD is the first module found in
protected high memory, the space will be reclaimed and the protected memory
pointer (HIGH$) adjusted. If the DD module is not the first protected module,
DD will unlink but the high memory allocation will remain. If the latter is
the case, and you reload DD with the ON parameter, it will reuse the same high
memory space as it previously occupied.

                             DD&T - 2

         DD&T - Debugger Disassembler and Trace Utility


DOS Program Trace Utility

     The function of the TRACE utility is to simply show you where your program
spends most of its time in execution. Programs may be coded so that they waste
too much time in inefficiently written program routines. TRACE finds these
program sections for you by means of the Statistical TRACE Report. You should
compare your program listing against the TRACE report and analyze the routines
where your program spends its time. Start tracing with a coarse address range.
Once you identify major sections, you can narrow the trace to produce a more
detailed snapshot of a given piece of code. Ask yourself if the section of
code should normally be executed more frequently than other sections. If there
is no reason for such frequent execution, look for another way to code the
routine. By reducing these bottlenecks of inefficient routines, your programs
will run faster.

     The DOS program trace utility is a package of two utilities designed to
help you optimize the design and coding of an assembler application program.
It consists of two utilities; PTRACE which records program activity by
execution address ranges and, STRACE which compiles and displays the
statistics of a series of PTRACE runs.


PTRACE - Program Trace module

    PTRACE allows you to execute the target program in an environment which
maintains a record of all program activity. Note that you cannot directly
trace a library member. Your selected address range is divided evenly into 256
"buckets". PTRACE keeps a counter for each bucket. Two other buckets are used
to track activity in areas above and below the selected range. Every time a
system heartbeat interrupt occurs, PTRACE determines the program counter at
the time of interrupt and updates the counter corresponding to the correct
bucket. PTRACE is invoked via the command:

	=================================================
	|						|
	| PTRACE trace-file (START=X'nnnn',END=X'nnnn')	|
	|						|
	| trace-file The filespec to receive the trace	|
	|	     data table generated during the	|
	|	     target program's invocation.	|
	|						|
	| START	     The lower address range to obtain	|
	|	     trace data.			|
	|						|
	| END	     The upper address range to obtain	|
	|	     trace data.			|
	|						|
	| Abbr: START=S. END=E				|
	=================================================

                             DD&T - 3

         DD&T - Debugger Disassembler and Trace Utility

     The trace file is written out to disk when the trace terminates; i.e. when
the target program exits to DOS Ready. START and END determine the address
range; they must be greater than 255 bytes apart. The defaults are
STAHT=X'0000' and END=X'FFFF' To keep interrupt overhead to a minimum, the
range is rounded up to the next higher power-of-2; e.g 256, 512, 1024. The
maximum range is all of memory, or 65536. If the table filespec [trace-file]
is not entered on the DOS command line, PTRACE will prompt for it. In any
case, PTRACE will prompt for the command line which will execute the target
program. This is entered identically to the DOS command line which would be
used to invoke the target program normally. PTRACE will load and execute the
target program, trace its activity, and terminate by saving the bucket
counters and associated range data as a Program Trace Table to a disk file,
with default extension /PTT. \JVhile the trace is active, PTRACE will place a
blinking asterisk (*) in the upper right corner of the video screen.

     Ten sample trace tables are included on this disk as T0/PTT through
TS/PTT.

STRACE - Statistical TRACE Report

     STRACE will report statistics computed from the data in one or more trace
result files. In many cases, it will be desirable to repeat a PTRACE run
several times. This depends on the range of the trace, how long the target
program executes, and how fast your DOS computer is running (2 MHz or 4MHz,
for instance). If a range is wide, the trace results will be coarser.
If a target program run is short, fewer statistics will be gathered. If your
computer is running fast, the fixed system interrupt interval will fall behind
program activity. In any case, the more trace runs you make, the better the
statistics will be. Use of a Job Control Language file to invoke PTRACE
will ease this process.

	STRACE is invoked by the command:

	  STRACE [trace-file-l] [trace-file-2] ... [trace-file-N]

The file extension default of "/PTT" will be added to the file specification
if you omit it. The report can be redirected to the printer by appending
">PR" to the command line, or to a file by appending ">report file" to the
command line. The quotes are not entered. At least one trace file
specification must be entered, but their order is not significant if more than
one is present.

     If a consecutive series of "buckets" within the trace range all have a
count of zero occurrences, they are squeezed together to form one "bucket" in
the output listing.

     You cannot generate an STRACE report from trace tables with different
address ranges. A sample trace report is included on this disk as TEST/RPT.

                             DD&T - 4

