NOTES:	DDT IS A VERY POWERFUL DEBUGGING AID, BUT IS FAIRLY LARGE, SO
	BE FOREWARNED.  IT ALSO USES UP A LOT OF SYSTEM RESOURCES ON
	SYMBOL SEARCHES THROUGH THE STB FILE.
 
	THE ONLY DOCUMENTATION IS TO READ THE COMMENTS IN THE SOURCE
	LISTING.
 
	USE DDT AS YOU WOULD ODT, IN TASKBUILDING AND MOST OPERATIONS.

    DDT has undergone so many revisions that it has become a tribute to
ridiculously unreadable code  (although it may be no worse than it ever was).
I suspect that the best thing would be to start from scratch and write a new
one, but that is a project few people have the time or inclination for
(there was another DDT on the San Francisco Decus RSX tape from Applicon,
but it's syntax is vastly different from this one).  Anyway, there are
a few things you should know about this DDT (version 01.1):

	1) There are a lot of conditional assembly sections for various
	   options.  They are described in the modification notes at the
	   beginning of the source code.  You will almost certainly want
	   to comment out some of the flags since some of them relate to
	   the type of processor you have  (e.g. R$$EIS, M$$MGE, DDTFIS).

	2) DDT uses the CSI (Command String Interpreter).  This means that
	   it will share code with the user program if the user program
	   also calls CSI.  If there are no user references to CSI, there
	   will be additional CSI code in the program that will not be
	   included in the range of the symbol DDT....in other words, the
	   user program will appear to be larger than it is, and DDT will
	   appear to be smaller.

	3) If you put a copy of DDT.OBJ in LB:[1,1] under the name ODT.OBJ,
	   then TKB and FTB will use it as the default debugger (with the
	   /DA switch on the .TSK filespec).
	N.B. ***** under version 3.1 of 11M, FTB looks for SYSLIB and ODT in
	   SY0:[1,1]  instead of  LB0:[1,1].....this can be changed by
	   getting an ascii dump (with DMP) of the task image and finding
	   the reference to SY0:, then ZAPping it to LB0: *****

	4) FTB doesn't make .STB files.

	5) Read the modification notes (especially DS-18.) to clarify what
	   address is printed when a break occurs....under some conditions
	   it is the address of the next instruction to execute; under
	   others, it is the address of the instruction that caused the
	   break.  Sometimes, like with IL and MM, the PC is backed up
	   to point to the instruction that caused the break.

	6) If DDT is assembled with DDTDFS defined, the symbol PROG will
	   be in DDT's external symbol table, pointing (hopefully) to
	   what corresponds to relocatable location 0 in the 1st (or
	   only) source module.  This is very useful in certain cases,
	   but since DDT doesn't search the .STB file unless there are
	   no possible matches in it's own external symbol table, it
	   will inhibit .STB searches.  This is easily solved by issuing
	   the DDT command:  0;0:PROG   ;which will nullify the definition.
	   Note that the symbol  DDT  is also a pre-defined external symbol
	   which, if DDT is not at the end of the task image, could have
	   the same inhibiting effect  (DDT might not be at the end of
	   a task if it is specified as an input file with the /DA switch
	   e.g.  TKB  PROG = DDT/DA , PROG
	   which is useful in debugging tasks which extend themselves).

	7) Although the task builder allocates two extra LUNs for
	   debugging aids (which DDT uses for terminal and .STB I/O),
	   there is an important problem with the use of .STB files:
	   .PSECT $$FSR1, which contains impure storage space for FCS,
	   is an overlaid .PSECT -- each program module which includes
	   $FSRSZ allocates space for open files in $$FSR1, but the
	   total allocation is equal only to the largest contributor.
	   This means that, in order to run a program under DDT with
	   an .STB file open, the program must have a spare file block
	   in $$FSR1.  This can be accomplished by either increasing by
	   one the number of blocks allocated  ($FSRSZ x+1), or by closing
	   the .STB file before executing your program.  Of course, neither
	   option is satisfactory, and i will bug DEC about this, but it
	   will have to do for the time being.  Note also that there is
	   an implicit FINIT$ performed when the .STB file is opened, if
	   the user program hasn't already done one.  This means that an
	   explicit  FINIT$ (CALL .FINIT) will zero $$FSR1 and lose the
	   context of the .STB file.  I suggest that if mysterious file errors
	   seem to occur, try closing the .STB file before executing
	   user code  (by specifying no filename to the .STB prompt
	   with the  O  command)....you can always reopen the .STB file
	   when you get back to DDT later.

	8) The expressions  "external symbol table"  and  "internal
	   symbol table"  seem to be used interchangeably in the
	   documentation....They refer to the memory-resident table of
	   user-definable symbols which are part of DDT  (in psect $$$SYM).
	   The actual place where  $$$SYM  is defined used to be about
	   half-way through the source program....i moved it to the end.

	9) The SYSLIB module  .GCML  is the Get Command Line code that
	   used to be called for prompt and input for the  O  command.
	   I removed all references to this code for two reasons:
		a) the savings is 330. words if the user called GCML and
		                 1370. words if the user didn't !!
	        b) the  .GCML  module was assembled without local definitions
		   of the I/O functions and FDB offsets (in 11M V3.1).....
		   (i have submitted an SPR to this effect)...............
		   When GCML is used, all the function codes, offsets, and
		   masks are defined globally and are included in the .STB
		   file....this slows searches and provides a zillion address
		   matches to unrecognizable symbols.

	10) The SST vectors defined at SSTVEC are the vectors in use when the
	    program starts up.  Those that conflict with SST vectors that you
	    often use (and must often zero out) can be zeroed in the source
	    (SSTs 6 and 7 are zeroed in this source version).  They can always
	    be restored by the  V  command, regardless of the start-up
	    condition.

	11) The M command (Monitor location) has been added.  It is documented
	    in the change notes.  One thing to watch out for, though, is that,
	    although a single instruction cannot modify more than one location,
	    a TRAP or EMT can (since many instructions occur before the T-bit
	    trace happens).  Due to the ridiculous nature of the SST code in
	    DDT, i haven't tried to print more than one changed location per
	    single instruction.  So, if an EMT changes three monitored words,
	    you'll only be notified that one of them changed.  Oh well....

---- Daniel Steinberg -- April 4, 1979 ----
