June, 1985

                       Microsoft Macro Assembler Package
                                  Version 3.01

The Microsoft Macro Assembler Package v 3.01 is a technical update to the Micro-
soft Macro Assembler Package v 3.00.  Version 3.01 contains updated versions of
SYMDEB and MAPSYM, the interactive symbolic debug utility for Microsoft langua-
ges.  The other parts of the package remain unchanged.

The Microsoft Macro Assembler Package v 3.00 was a significantly enhanced ver-
sion of Microsoft Macro Assembler Package v 1.27.  Version 3.00 contained
updated versions of the utilities plus additional development utilities for use
with Macro assembler and High Level Languages.

The following files should be present on the distribution diskette:

    CREF.EXE        LIB.EXE         MAKE.EXE        README.DOC

Each of these files is discussed below.

==( MASM.EXE )=================================================================
  Microsoft MACRO Assembler  Version 3.00
  (C)Copyright Microsoft Corp 1981, 1983, 1984

MASM produces relocatable object modules for the 8086, 80186, 80286 family of
microcomputer systems.  Source language is a superset of the powerful Intel
ASM 86 assembler language.

  1. 186/286/287 microprocessor support
  2. Case sensitivity for symbols may be specified

Differences between this version and the description in the manual:

    - without using the /R or /E switches, the assembler defaults to 
	 the Microsoft MS format for reals
		ex:    DD   real
    - If you do not place    LOCAL   immediately after    MACRO,  you will see
      the diagnostic message "Extra Characters At End Of Line"

    - The recommended method of doing:
           DW  5   dup (offset sym)
       REPT  5
       DW  offset  sym

     - The Macro Assembler does not include an overlay manager

==( LINK.EXE )=================================================================
  Microsoft 8086 Object Linker
  Version 3.00 (C) Copyright Microsoft Corp 1983, 1984, 1985

LINK combines separate relocatable object modules and library routines into a
single program. 

  1. The user can specify from 1 to 1024 segments
  2. Simple overlay manager that can be used in conjunction with Microsoft
	C, FORTRAN and Pascal only.

==( SYMDEB.EXE )===============================================================
  Microsoft Symbolic Debug Utility
  Version 3.01
  (C)Copyright Microsoft Corp 1984, 1985

SYMDEB symbolic debugging utility provides a controlled testing environment for
binary and executable object files.

  1. NEW Interactive Symbolic Debug Utility for Microsoft Languages (Macro
       Assembler and High Level) which replaces the DEBUG utility.
  2. Source line display may be used with Fortran, Pascal and C.
  3. Breakpoints may be set on line numbers and symbols.
  4. Single stepping may be used to follow program execution.
  5. Help command has been added to display the command syntax.

New Switches
/K - Enables Scroll Lock-Break breakpoint (see below).

/N - Enables NMI breakpointing (automatic on IBM machines).

/S - Enables Screen Swapping (see below).

/" - Symdeb command on MS-DOS command line.  The line following the quote up to
     the (required) end quote will be passed to Symdeb for execution as the
     first command.  Example:

     A>symdeb /"s+;g _main;v" cprog.sym cprog.exe

Enhanced I/O Redirection
You can now redirect SYMDEB input and output to any MS-DOS device or file, by
using the "<", ">", and "=" commands.  You can also redirect the input and 
output of the program you are debugging, by using the commands "{" (equivalent
to <), "}" (equivalent to >), and "~" (equivalent to =).  The syntax of these
commands is as follows:

    {redirection command} device

where file is any MS-DOS file name or device, such as CON, COM1, PRN, FOO.DAT,

If input has been re-directed from a file, be sure to use "<CON" or "Q" as the
last command; otherwise your system will hang, waiting for redirected commands.

You can call in a sequence of commands at any time - even automatically at a
breakpoint - to speed debugging and avoid repetitive typing.  You can use the
SYMDEB shell escape to build command sequences without ever leaving SYMDEB.

Screen Swapping
This feature works only on IBM and some strict compatible computers.  Also,
you cannot use this feature with graphic modes that use more than 16K of 

When you specify the new /S switch on the SYMDEB command line, the debugger is
displayed on its own screen, and doesn't interfere with the user screen (the
user screen displays what the program being debugged would display).  For
example, if you entered the following:

        symdeb /S demo.sym demo.exe

you would see only a debugging screen.

To display the user screen, enter a backslash (\) and hit return.  To leave the
user screen and return to the debugging screen, press any key.  If you enter a
backslash and didn't specify the /S switch, SYMDEB returns an error.  Note that
using the /S switch uses 32K more memory.

SCROLL LOCK-BREAK Interactive Breakpoint
When you specify the new /K switch on the SYMDEB command line, you can use the
SCROLL LOCK-BREAK key as an interactive breakpoint.  For example, if you enter
the following:

        symdeb /K file.exe

you can press the SCROLL LOCK-BREAK key at any time to stop executing your
program.  Note that if your program has turned off interrupts, you cannot use
interactive breakpoints.

This interactive breakpoint can also be used from the SYS REQ key if you are
using an IBM PC AT.  This feature is always enabled if you are using an IBM
PC AT (independent of the /K switch).

/N - Enables true hardware NMI breakpoints, if the NMI Hardware is installed.
     SYMDEB automatically supports hardware NMI's on IBM machines, if the
     machine has the NMI hardware installed.  If you install NMI hardware on
     a non-IBM machine, you need to activate the /N switch.

Bigger Symbol Table
SYMDEB now allows about 5,000 symbols per segment, with the number of segments
limited to the memory available.  The model was changed to allow bigger symbol
tables, so symbol files made with earlier versions of MAPSYM do not work with
this version of SYMDEB.  If you try to use an old symbol file, SYMDEB returns an
error.  You can use the new version of MAPSYM to create a new symbol file.

186/286 Opcodes
SYMDEB now recognizes all 186/286 opcodes (except for protected-code mnemonics).
This can be useful when you are debugging C programs, because if you specify the
/G1 or /G2 switches while compiling, the Microsoft C compiler can output 186 or
286 instructions.

Breakpoint Set Command Expanded
The syntax of the Breakpoint Set command is now as follows:

        BP[<n>] <address> [<passcount>] ["<commands>"]

If you specify a command in the optional "commands" clause, that command is
executed each time the breakpoint is taken.  For example, if you have forgotten
to increment the DI register, you can set a breakpoint as follows:

        BP 1234:5678 "rdi di+1;g"

When the breakpoint is taken, the contents of the DI register are incremented
and the program continues.  In this case, neither the "R" command nor the "G"
command produce any output, so the program appears to execute normally albeit
much slower, since Symdeb is executing the breakpoint commands.

Note that SYMDEB normally displays the registers and/or current source line
(depending on whether S-, S&, or S+ is set) after taking a breakpoint.  If,
however, you have specified a command, SYMDEB does not display the registers
and/or current source line.

Comment Command
The Comment command is simply an asterisk (*) followed by text. SYMDEB echoes
the text of the comment to the standard output.  This command is useful with
the redirection commands to save or print commented copies of a SYMDEB session.

Dump Command
The syntax of the new Dump command is as follows:

        D[<type>] [<address>]

The allowable values of <type> are listed below:

        <type>        Type of Value
        ------        -------------     
          A           ASCII
          B           bytes (startup default)
          W           words
          D           doublewords
          S           short reals
          L           long reals
          T           ten-byte reals

Enter Command
The syntax of the new Enter command is as follows:

        E[<type>] <address> [<list>]

The Enter command enters one or more values into memory at the specified
<address>.  The optional <type> field is a single letter that specifies the
type of the values to be entered.  The optional <list> gives the value to be
entered.  Only one value can be entered at a time, except when entering bytes.
When entering bytes, the optional <list> can consist of a series of byte values.
If the type field is omitted, the default is the last type used in an Enter
command (startup type is Byte).

If an error occurs during entry, the value is not changed.

If you do not supply a <list>, SYMDEB prompts for a new value at <address> by
displaying the address and its current value followed by a period (.).  You can
then replace the value by typing the new value after the current value.  The
command ignores extra trailing digits or other characters.  You can skip to the
next value by pressing the SPACE bar, or return to the preceding value by typing
a hyphen (-).

You can exit the Enter command at any time by pressing the RETURN key.

For example, if you enter the following:

        EB CS:100

SYMDEB displays a prompt like this:

        04BA:0100  AE._

You can then change the value AE to a new value by typing the new value, or skip
to the next byte value by pressing the SPACE bar, or return to the previous
value by typing a hyphen, or leave Enter by pressing RETURN.

Here are some more examples:

1.      EB CS:100 1 2B E5
2.      EW 11AC:100 8018
3.      ED pi 80187076

Example 1 replaces the three bytes at CS:100, CS:101, and CS:102 with 1, 2B,
and E5, respectively.

Example 2 replaces the word at 11AC:100 with 8018.

Example 3 replaces the doubleword at the symbolic address "pi" with 80187076.

Source Code Single Step
The "P" and "T" commands have been updated so that in source-only mode (S+) they
operate on source lines.  P steps over function calls, T executes through 
function calls.

You should turn off optimization when compiling programs that you want to debug
with SYMDEB.  When the Microsoft C compiler optimizes a program, it can delete
sections of redundant code, reorder expressions, or move code.  After your code
has been optimized, the code corresponding to one statement in your source file
may not be what you expect, because code may have been deleted, moved, changed,
or added.  If you are having trouble with the P and T commands, make sure that
you compiled the program using the /Od switch to turn off optimization.

Shell Escape Command
The new Shell Escape command allows you to execute COMMAND.COM and MS-DOS
commands from within SYMDEB.  The syntax is as follows:

        ! [<MS-DOS-command>]

If you enter "!" with no arguments, you execute COMMAND.COM with no arguments,
saving the current debugging context.  After you are finished executing MS-DOS
commands, enter the MS-DOS command "exit" and you'll be returned to SYMDEB where
you left off.

If you specify an MS-DOS command, the MS-DOS command is executed and control is
then returned to SYMDEB.

You cannot use semicolons (;) to connect statements after the Shell Escape
command.  All text after the Shell Escape command is passed to COMMAND.COM as
an MS-DOS command line.

You can only use the Shell Escape command if one of the following conditions is

1 - You entered SYMDEB without any filenames.
2 - You are debugging a Microsoft C (v 3.00 or later), Pascal (v 3.30 or later), 
    or FORTRAN (v 3.30 or later) program, and have executed 
    the program up to _main.
3 - The program you are debugging has done a "Modify Allocated Memory"
    MS-DOS call on itself, to free the rest of memory.

If none of these conditions are met, SYMDEB will return the error "Not enough

SYMDEB uses the COMSPEC environment variable to locate a copy of COMMAND.COM.

Source Line Command
Entering a single period (.) displays the current source line.  This command is
not affected by the current source mode.

Stack Trace Command
The new Stack Trace command lets you display the current procedure nest when
debugging Microsoft C programs.  It will also work with other C programs, if
they use the same calling conventions as Microsoft C.  The syntax for the Stack
Trace command is as follows:

        K [<numargs>]

When you specify the Stack Trace command, SYMDEB displays a list of
the procedures that called the current procedure, plus a list of their
arguments.  For each procedure, SYMDEB also lists the file and line
number of the statement that called that procedure.  If you specify
the "numargs" parameter, SYMDEB displays the specified number of
arguments for those procedures for which Symdeb cannot determine the number
of arguments (in this case, the argument list will be displayed with a
question mark; i.e., IGROUP:_main(?)).

Note that SYMDEB does not know the types of arguments, so it displays all
arguments as hexadecimal words.

For example, suppose you have executed to a breakpoint, and when you enter "K"
you see the following:

        IGROUP:_max(0002,0003) from .sample.c:7

This listing tells you that the current procedure, "max", has two arguments,
and their values are 2 and 3.  Max was called from line 7 of the source file
sample.c, in the procedure "main", and main has an undetermined number of
arguments.  A "K" command with numargs set would display arguments for _main
in this case.  For example, the "K 3" command would display:

        IGROUP:_max(0002,0003) from .sample.c:7

Symbol Set Command
The new Symbol Set command sets a given symbol to a specified value.  The
syntax is as follows:

        Z <symbol> <value>

For example, the following command sets the symbol "i" to the offset 100:

        Z i 100

Unassemble Command Changed
The way this command operates in source-only (S+) mode has been changed.
In source-only mode, the Unassemble command now displays both source lines
and disassembled instructions, just as in mixed mode (S&).

View Command
The new View command displays source lines for a given address, and operates
regardless of the current S mode (S-, S&, or S+).  The syntax is as follows:

        V .[<address>]

For example, the following view commands have the meanings listed:

        V .8                  view source line eight of current module
        V .+5                 view fifth line beyond the current line
        V .-7                 view seventh line before the current line
        V .SIEVE:33           view thirty-third line of module SIEVE
        V ._main              view beginning line of _main
        V ._main+10           view tenth line beyond the beginning of _main

When using the form "V .modulename:address" to view a file, or any command
that uses the    line #    syntax, please note that the  "filename"
is actually the name of the module produced by the linker (in contrast
to page 4-13 of the manual).  For example, let us assume that SYMDEB
prompts as follows:

        Source file name for MOD1 (cr for none)?

and the user responds with TEST.PAS.  In this case, even though TEST.PAS is
the source file name, MOD1 is the name of the module produced by the linker.
So, to view the 12th line of the source file (TEST.PAS), the user should type
as follows:

        V .MOD1:12

Help Command
The Help command displays a screenful of information, describing the syntax of
each of the Symdeb commands and the expression operators.

Register Command
The Register command has been enhanced so an expression can be added as the
register replacement value on the same line.  The new syntax of the Register
command is as follows:

        R [<reg> [ [=] <expression> ]]


        RAX = (BP + SI) / 2
        RSI _inputbuffer+1

This makes the Register command very useful in a breakpoint command.

Other Information not in manual
    - WO & BY in expressions assume DS as segment
    - BP & SP in expressions assume SS as segment
    - Unassemble and Assemble commands assume CS
    - Dump and Enter commands assume DS
    - hex numbers have precedence over symbols (symbol FAA can't be used)
    - DOS Terminate (function 4C) call will kill Symdeb if hand-assembled
        without doing exec first (Symdeb execs .EXE file)
    - If you do not have an 8087, do not use 8087 instructions.  "WAIT", for
        example, will cause your system to hang.
    - If you are debugging Microsoft Pascal or FORTRAN versions 3.20 or 
        earlier or IBM Personal Computer FORTRAN or Pascal versions 2.00 or
        earlier, you may want to give the following command at your first
        breakpoint in your code:
           Z  DGROUP  DS
        This changes the segment base for DGROUP to be the current DS.  This
        will allow symbolic variable names to be used or displayed for public
        variables in DGROUP.
     - When using SYMDEB with Microsoft FORTRAN, Pascal or C, please note 
        that if you use interrupts in the range of   32 to  3C  then your
	   screen handling may be different than expected.  

==( MAPSYM.EXE )===============================================================
  Microsoft Symbol File Utility  Version 3.10
  (C)Copyright Microsoft Corp 1984, 1985

MAPSYM creates a symbol table map for use by SYMDEB.

  1. Bigger symbol table allows approximately 5,000 symbols per segment.
       The number of segments is limited only by available user memory.

==( CREF.EXE )=================================================================
  Microsoft Cross Reference Utility  Version 3.00
  (C)Copyright Microsoft Corp 1981, 1983, 1984

CREF creates a cross reference listing for all symbol references within the
assembly language source program.

==( LIB.EXE )==================================================================
  Microsoft Library Manager
  Version 3.00 (C)Copyright Microsoft Corp 1983, 1984, 1985

LIB lets you create and maintain your own libraries of useful functions.  You
can customize the runtime support available to your programs.

  1. The pagesize may be set.  The default is 16 bytes.  This allows the amount
       of wasted spaced inside libraries to be reduced.
  2. A name other than the original may be specified for a modified library.
  3. Over 3000 public symbols may be used by the user.
  4. The process to replace modules has been simplified to a 1 step process.

==( MAKE.EXE )=================================================================
  Microsoft Program Maintenance Utility
  (C)Copyright Microsoft Corp

MAKE is an automated program development tool.  It rebuilds target files based
on source file dependencies, by sensing which files are out of date and
invoking appropriate user-specified command lines.

Differences between this version and the description in the manual:

    - You can execute DOS internal commands by using  
	  COMMAND/C   internal command
		ex:  COMMAND/C  DIR 

    - You need to set up the MAKE file so that the TARGET files and DEPENDENT
      files are on the same drive.  That drive should be the default drive.

    - If a warning or an error message should result from one of the programs
      executing during MAKE,  MAKE will halt.  You should examine the message
      and if you decide you need to continue, execute the next in the process
      yourself and then continue with MAKE.

    - The maximum size of a MAKE script is approximately 160 test process 
	  pairs with 1 blank line in between them.


SYMDEB & MAPSYM Capacities:

SYMDEB v 3.00  - 1500 symbols maximum 
                 3000 line numbers maximum

MAPSYM v 3.00  - 150 segments maximum
                 3000 line numbers
                 1500 symbols maximum 

SYMDEB v 3.01  - 5,000 symbols/segment (average 10 characters)
                 5,000 line numbers/segment 

MAPSYM v 3.01  - 1024 segments
                 5,000 symbols/segment (average 10 characters)
                 5,000 line numbers/segment

The above numbers are approximations
A word of caution:  you can create a file with MAPSYM which is too large
   to be loaded by SYMDEB .

SYMDEB v 3.00 has to be used with MAPSYM v 3.00
SYMDEB v 3.01 has to be used with MAPSYM v 3.01