DEBUG:N
`
`Finally, to execute the program CLEAN. COM, type
`
`-G <Enter>
`
`The result is the sa.me as if the CLEAN.COM program had been run from the MS-DOS
`command level with the entry
`
`C>CLEAN MYFILE.DAT <Enter>
`
`except that the program is executing under the control of DEBUG and within DEBUG's
`memory buffer.
`
`Section IV· Programming Utilities
`
`1041
`
`ZTE (USA) 1007, Page 1051
`
`

`

`DEBUG:O
`
`DEBUG:O
`Output to Port
`
`Purpose
`
`Writes 1 byte to an input/output (I/O) port.
`Syntax
`
`0 port byte
`
`where:
`
`is an I/0 port address from 0 through FFFFH.
`is a value from 0 through OFFH to be written to the I/0 port.
`
`port
`byte
`Description
`The Output to Port (O) command writes 1 byte of data to the specified I/O port address.
`The data value must be in the range OOH through OFFH.
`
`Warning: The 0 command should be used with caution because it directly accesses the
`computer hardware and no error checking is performed. Attempts to write to some port
`addresses, such as those for ports connected to peripheral device controllers, ~imers, or the
`system's interrupt controller, may cause the system to crash or damage data stored on disk.
`Example
`
`To write the value C8H to I/0 port lOAH, type
`
`-o 10A cs <Enter>
`
`1042
`
`The MS-DOS Encyclopedia
`
`ZTE (USA) 1007, Page 1052
`
`

`

`DEBUG:P
`
`DEBUG:P
`Proceed Through Loop or Subroutine
`
`Purpose
`Executes a loop, repeated string instruction, software interrupt, or subroutine call
`to completion.
`Syntax
`P [=address] [number]
`
`where:
`
`is the location of the first instruction to be executed.
`is the number of instructions to execute.
`
`address
`number
`Description
`The Proceed Through Loop or Subroutine (P) command transfers control from DEBUG
`to the target program. The program executes without interruption until the loop, repeated
`string instruction, software interrupt, or subroutine call at address is completed or until
`the specified number of machine instructions have been executed. Control then returns
`to DEBUG, and the contents of the target program's registers and the status of the flags are
`displayed.
`
`If the address parameter does not include an explicit segment, DEBUG uses the target pro(cid:173)
`gram's CS register; if address is omitted entirely, execution begins at the address specified
`by the target's CS:IP registers. The address parameter must be preceded by an equal sign
`( =) to distinguish it from number.
`
`If the instruction at address is not a loop, repeated string instruction, software interrupt,
`or subroutine call, the P command functions just like the Trace Program Execution (T)
`command. The optional number parameter specifies the number of instructions to be
`executed before control returns to DEBUG. If number is omitted, DEBUG executes only
`one instruction. After each instruction is executed, DEBUG displays the contents of the
`target program's registers, the status of the flags, and the next instruction to be executed.
`
`Warning: The P command cannot be used to trace through ROM.
`Example
`Assume that the target program's location CS:l43FH contains a CALL instruction. To
`execute the subroutine that is the destination of CALL and then return control to
`DEBUG, type
`
`-p =143F <Enter>
`
`Section IV: Programming Utilities
`
`1043
`
`ZTE (USA) 1007, Page 1053
`
`

`

`DEBUG:Q
`
`DEBUG:Q
`Quit
`
`Purpose
`Ends a DEBUG session.
`Syntax
`
`Q
`Description
`The Quit (Q) command terminates the DEBUG program and returns control to MS-DOS or
`the command shell that invoked DEBUG. Any changes to a program or other file that were
`not saved on disk with the Write File or Sectors (W) command are lost.
`Example
`To exit DEBUG, type
`
`-Q <Enter>
`
`1044
`
`The MS-DOS Encyclopedia
`
`ZTE (USA) 1007, Page 1054
`
`

`

`DEBUG:R
`
`DEBUG:R.
`Display or Modify Registers
`
`Purpose
`Displays the contents of one or all registers and the status of the CPU flags and allows
`them to be modified.
`Syntax
`R [register]
`
`where:
`
`register
`
`is the two-character name of an Intel 8086/8088 register from the following
`list:
`
`AX BX CX DX SP BP SI DI
`DS ES SS CS IP PC
`
`or the character F, which specifies the CPU flags.
`
`Description
`The Display or Modify Registers (R) command displays the target program's register con(cid:173)
`tents and the status of the CPU flags and allows them to be modified.
`
`If R is entered without a register parameter, the contents of all registers and the status of
`the CPU flags are displayed, followed by a disassembly of the machine instruction cur(cid:173)
`rently pointed to by the target program's CS:IP registers.
`
`If register is included in the R command line, the contents of the specified register are dis(cid:173)
`played; then DEBUG prompts with a colon character(:) for a new value. The value is en(cid:173)
`tered by typing one to four hexadecimal digits and then pressing the Enter key. Pressing
`the Enter key without entering any values leaves the register contents unchanged.
`
`Note: The register name PC is not fully supported in some versions of DEBUG, so the
`register name IP should be used instead.
`
`Specifying the character F instead of a register name causes DEBUG to display the status of
`the program's CPU flags as two-character codes from the following list:
`
`Flag Name
`
`Value HSet (1)
`
`Value H Clear (0)
`
`Overflow
`Direction
`Interrupt
`
`OV (Overflow)
`DN(Down)
`EI (Enabled)
`
`NV (No Overflow)
`UP(Up)
`DI (Disabled)
`
`(more)
`
`Section IV: Programming Utilities
`
`1045
`
`ZTE (USA) 1007, Page 1055
`
`

`

`DEBUG:R
`
`Flag Name
`
`Value If Set (1)
`
`ValuelfClear(O)
`
`Sign
`Zero
`AuxCarry
`Parity
`Carry
`
`NG (Minus)
`ZR(Zero)
`AC (Aux Carry)
`PE(Even)
`CY(Carry)
`
`PL(Plus)
`NZ (Not Zero)
`NA (No Aux Carry)
`PO(Odd)
`NC (No Carry)
`
`After displaying the flag values, DEBUG displays a hyphen(-) prompt on the same line.
`Any or all flags can then be altered by typing one or more codes (in any order and op(cid:173)
`tionally separated by spaces) from the list above and pressing the Enter key. Pressing the
`Enter key without entering any codes leaves the status of the flags unchanged.
`Examples
`To display the contents of the target program's CPU registers and the status of the CPU
`flags, followed by the disassembled mnemonic for the next instruction to be executed
`(pointed to by CS:IP), type
`
`-R <Enter>
`
`This produces a display in the following format:
`
`SP=FFFE BP=OOOO SI=OOOO DI=OOOO
`AX=OOOO BX=OOOO CX=OOA1 DX=OOOO
`IP=0100
`NV UP EI PL NZ NA PO NC
`DS=19A5 ES=19A5 SS=19A5 CS=19A5
`19A5:0100 BF8000
`MOV
`DI,0080
`
`To display the value of the target program's BX register, type
`
`-R BX <Enter>
`
`If BX contains 0200H, for example, DEBUG displays that value and then issues a prompt in
`the form of a colon:
`
`BX 0200
`
`The contents of BX can then be altered by typing a new value and pressing the Enter key
`or left unchanged by pressing the Enter key alone.
`
`To set the direction and carry flags, first type
`
`-R F <Enter>
`
`DEBUG displays the flag values, followed by a hyphen(-) prompt:
`
`NV UP EI PL NZ NA PO NC
`
`-
`
`The direction and carry flags can then be set by entering
`
`-DN CY <Enter>
`
`1046
`
`The MS-DOS Encyclopedia
`
`ZTE (USA) 1007, Page 1056
`
`

`

`DEBUG:R
`
`Messages
`bfError
`Bad flag: An invalid code for a CPU flag was entered.
`
`brError
`Bad register: An invalid register name was entered.
`
`dfError
`Double flag: Two values for the same CPU flag were entered in the same command.
`
`Section IV: Programming Utilities
`
`1047
`
`ZTE (USA) 1007, Page 1057
`
`

`

`DEBUG:S
`
`DEBUG:S
`Search Memory
`
`Purpose
`Searches memory for a pattern of 1 or more bytes.
`Syntax
`S range list
`
`where:
`
`range
`
`specifies the starting and ending addresses or the starting address and length
`of the area to be searched.
`is 1 or more consecutive byte values and/ or a string to be searched for.
`
`list
`Description
`The Search Memory (S) command searches a designated range of memory for a specified
`list of consecutive byte values and/or a text string. The starting address of each set of
`matching bytes is displayed. The contents of the searched area are not altered.
`
`The range parameter specifies the starting and ending addresses or the starting address
`and length in bytes of the area to be searched. If a segment is not included in range,
`DEBUG uses DS. If a segment is specified for the starting address, DEBUG uses the same
`segment for the ending address. If a starting address and length in bytes is specified, the
`starting address plus the length minus 1 cannot exceed FFFFH.
`
`The list parameter specifies one or more consecutive hexadecimal byte values and/or a
`string to be searched for, separated by spaces, commas, or tab characters. Strings must be
`enclosed within single or double quotation marks, and case is significant within a string.
`Examples
`
`I
`
`To search for the string Copyright in the area of memory from DS:OOOOH through
`DS:1FFFH, type
`-P 0 1FFF
`
`'Copyright' <Enter>
`
`or
`-P 0 L2000 "Copyright" <Enter>
`
`If matches are found, DEBUG displays the starting address of each:
`
`20A8:0910
`20A8:094F
`20A8:097C
`
`1048
`
`The MS-DOS Encyclopedia
`
`ZTE (USA) 1007, Page 1058
`
`

`

`DEBUG:S
`
`I
`l
`I
`
`To search for the byte sequence 3BH 06H in the area of memory from CS:OlOOH through
`CS:12AOH, type
`
`-S CS:100 12AO 3B 06 <Enter>
`
`or
`
`-S CS:100 111A1 3B 06 <Enter>
`
`Section IV.· Programming Utilities
`
`1049
`
`ZTE (USA) 1007, Page 1059
`
`

`

`DEBUG:T
`
`DEBUG:T
`Trace Program Execution
`
`Purpose
`Executes one or more instructions, displaying the CPU status after each instruction.
`Syntax
`T [=address] [number]
`
`where:
`
`is the location of the first instruction to be executed.
`is the number of machine instructions to be executed.
`
`address
`number
`Description
`The Trace Program Execution (T) command executes one or more instructions, starting at
`the specified address, and after each instruction displays the contents of the CPU registers,
`the status of the flags, and the instruction pointed to by CS:IP.
`
`Warning: The T command should not be used to execute any instructions that change
`the contents of the Intel8259 interrupt mask (ports 20H and 21H on the IBM PC and com(cid:173)
`patibles) or to trace calls made to MS-DOS through Interrupt 21H. The Go (G) command
`should be used instead.
`
`The address parameter points to the first instruction to be executed. If address does not
`include a segment, DEBUG uses the target program's CS register; if address is omitted en(cid:173)
`tirely, execution begins at the address specified by the target program's CS:IP registers. If
`address is included, it must be preceded by an equal sign ( =) to distinguish it from
`number.
`
`The number parameter specifies the hexadecimal number of instructions to be executed
`before the DEBUG prompt is redisplayed (default= 1). Pressing Ctrl-C or Ctrl-Break inter(cid:173)
`rupts execution of a sequence ofT instructions. Consecutive instructions can then be exe(cid:173)
`cuted individually by entering T commands with no parameters. Pressing Ctrl-S suspends
`execution and pressing any key then resumes the trace.
`
`Note: The T command can be used to trace through ROM.
`Example
`To execute one instruction at location CS:lAOOH and then return control to DEBUG, dis(cid:173)
`playing the contents of the CPU registers and the status of the flags, type
`
`-T =1 AO 0 <Enter>
`
`1050
`
`The MS-DOS Encyclopedia
`
`ZTE (USA) 1007, Page 1060
`
`

`

`DEBUG:U
`
`DEBUG:U
`Disassemble (Unassemble) Program
`
`Purpose
`Disassembles machine instructions into assembly-language mnemonics.
`·Syntax
`
`U[range]
`
`where:
`
`range
`
`specifies the starting and ending addresses or the starting address and length
`of the machine code to be disassembled.
`
`Description
`The Disassemble (Unassemble) Program (U) command translates machine instructions
`into assembly-language mnemonics.
`
`The range parameter specifies the starting and ending addresses or starting address and
`length in bytes of the machine instructions to be disassembled. If range does not specify a
`segment, DEBUG uses CS. Note that if the starting address does not fall on an 8086 instruc(cid:173)
`tion boundary, the disassembly will be incorrect.
`
`If range does not include a length or ending address, 32 (20H) bytes of memory are dis(cid:173)
`assembled beginning at the specified starting address. If range is omitted, 32 bytes of
`memory are disassembled, starting at the address following the last instruction dis(cid:173)
`assembled by the previous U command. If a U command has not been used before
`and range is omitted, disassembly begins at the address specified by the target
`program's CS:IP registers.
`
`Note: The actual number of bytes displayed may vary slightly from the amount specified
`in range or from the default of 32 bytes because the length of instructions may vary. Also,
`the U command does not understand instructions specific to the 80186, 80286, and 80386
`microprocessors. It displays such instructions as DBs.
`
`Successive 32-byte fragments of code can be disassembled by entering additional U com(cid:173)
`mands without parameters.
`Example
`To disassemble 8 bytes of machine instructions starting at CS:OlOOH, type
`
`-U 100 107 <Enter>
`
`or
`
`-U 100 18 <Enter>
`
`Section IV.· Programming Utilities
`
`1051
`
`ZTE (USA) 1007, Page 1061
`
`

`

`DEBUG:W
`
`DEBUG:W
`Write File or Sectors
`
`Purpose
`Writes a file or individual sectors to disk.
`·.syntax
`
`W[address]
`
`or
`
`W address drive start number
`
`where:
`
`address
`drive
`
`is the first memory location of the data to be written.
`is the number of the destination disk drive (0 = drive A, 1 = drive B, 2 = drive
`C, and so on).
`is the number of the first logical sector to write (0-FFFFH).
`is the number of consecutive sectors to be written (0-FFFFH).
`
`start
`number
`Description
`The Write File or Sectors (W) command transfers a file or individual sectors from memory
`to the disk.
`
`When the W command is entered without parameters or with only an address, the number
`of bytes specified by the contents of registers BX:CX is written from memory into the file
`named in the most recently used Name File or Command-Tail Parameters (N) command or
`the first file specified in the DEBUG command line if the N command has not been used.
`Files with a .EXE or .HEX extension cannot be written with the DEBUG W command.
`
`Note: If a Trace Program Execution (T), Go (G), or Proceed Through Loop or Subroutine
`(P) command has been used or the contents of the BX or CX registers have been changed,
`the contents of BX:CX must be restored before theW command is used.
`
`When address is not included in the command line, the target program's CS:0100H is
`assumed.
`
`TheW command can also be used to bypass the MS-DOS file system and directly access
`logical sectors on the disk. The memory address (address), disk drive number (drive),
`starting logical sector number (start), and number of sectors to be written (number) must
`all be provided in the command line in hexadecimal format. The W command should not
`be used to write sectors on network drives.
`
`Warning: Extreme caution must be used with theW command. The disk's file structure
`can easily be damaged if the wrong parameters are entered.
`
`1052
`
`The MS-DOS Encyclopedia
`
`ZTE (USA) 1007, Page 1062
`
`

`

`DEBUG:W
`
`Example
`Assume that the interactive Assemble Machine Instructions (A) command was used to
`create a program in DEBUG's memory buffer that is 32 (20H) bytes long, beginning at
`offset OlOOH. This program can be written to the file QUICK. COM by using the DEBUG
`Name File or Command-Tail Parameters (N), Display or Modify Registers (R), and Write
`File or Sectors (W) commands sequentially. First, use the N command to specify the name
`of the file to be written:
`
`-N QUICK.COM <Enter>
`
`Next, use the R command to set registers BX and CX to the length to be written. Register
`BX contains the upper, or most significant half, of the length, whereas register CX contains
`the lower, or least significant half. Type
`
`-R ex <Enter>
`
`DEBUG displays the contents of register CX and prompts with a colon (:). Enter the
`length after the prompt:
`
`:20 <Enter>
`
`To use the R command again to set register BX to zero, type
`
`-R BX <Enter>
`
`followed by
`
`:0 <Enter>
`
`Finally, to create the disk file QUICK. COM and write the program into it, type
`
`-W <Enter>
`
`DEBUG responds:
`
`Writing 0020 bytes
`Messages
`EXE and HEX files cannot be written
`Files with a .EXE or .HEX extension cannot be written to disk with the W command.
`
`Writing nnnn bytes
`After a successful write operation, DEBUG displays in hexadecimal format the number of
`bytes written to disk.
`
`4
`
`Section IV: Programming Utilities
`
`1053
`
`ZTE (USA) 1007, Page 1063
`
`

`

`SYMDEB
`
`SYMDEB
`Symbolic Debugger
`
`Purpose
`The Symbolic Debugger (SYMDEB) allow1; a file to be loaded, examined, altered, and writ(cid:173)
`ten back to disk. If the file contains a program, the program can be disassembled, modi(cid:173)
`fied, traced one instruction at a time, or executed at full speed with breakpoints. SYMDEB
`can also be used to read, modify, and write absolute disk sectors.
`
`The SYMDEB utility is supplied with the Microsoft Macro Assembler (MASM) versions 4.0
`and earlier. This documentation describes SYMDEB version 4.0.
`Syntax
`SYMDEB
`
`or
`
`SYMDEB [options] [symfile [symfile ... ]] [filename [parameter ... ]]
`
`where:
`
`symfile
`
`filename
`parameter
`options
`
`is the name of a symbol file created wi~h the MAPSYM utility
`(extension= .SYM).
`is the name of the binary or executable program file to be debugged.
`is a command-line parameter required by the program being debugged.
`is one or more of the following switches. Switches can be either upper(cid:173)
`case or lowercase and can be preceded by a dash (-) instead of a forward
`slash(/).
`
`/I
`!K
`IN
`
`IS
`
`/"commands''
`
`(IBM) specifies that the computer is IBM compatible.
`enables the interactive breakpoint key (Scroll Lock).
`enables the use of nonmaskable interrupt break sys(cid:173)
`tems on IBM-compatible computers (requires special
`hardware).
`enables the Screen Swap (\) command on IBM-com(cid:173)
`patible computers (the /I switch is also required).
`specifies one or more SYMDEB commands, separated
`by semicolons and enclosed in quotation marks.
`
`Description ·
`
`The SYMDEB commands and capabilities are a superset of those in DEBUG. SYMDEB is
`also able to load and interpret special symbol files that correlate line numbers, symbols,
`and memory addresses. With the aid of such files, SYMDEB enables the user to specify
`
`1054
`
`The MS-DOS Encyclopedia
`
`ZTE (USA) 1007, Page 1064
`
`

`

`SYMDEB
`
`addresses with labels, variable names, and expressions, rather than only with absolute
`hexadecimal addresses. SYMDEB's command repertoire also includes I/0 redirection
`commands, floating-point number entry and display commands, and source-code display
`capabilities that are not present in DEBUG.
`
`The SYMDEB command line typically includes the filename parameter, which is the
`name of an executable program (with the extension .COM or .EXE) to be loaded into
`SYMDEB's memory buffer. Files with the extension .EXE are loaded in a manner compat(cid:173)
`ible with the MS-DOS loader. Files with the extension .HEX are converted to binary images
`and loaded at the internally specified address. All other files are assumed to be direct
`memory images and are read directly into memory starting at offset lOOH. If SYMDEB is
`entered by itself, no file information is read into memory. An appropriate program seg(cid:173)
`ment prefix (PSP) is synthesized at the head of SYMDEB's buffer for use by the target pro(cid:173)
`gram; the PSP includes a command tail at offset SOH and default file control blocks (FCBs)
`at offsets 5CH and 6CH, constructed from the optional parameters following filename. If
`necessary, contents of the file are relocated so that the file is ready to execute.
`
`The command line can also contain the names of one or more symfiles, symbol files that
`contain symbol and line-number information for the object modules that constitute the
`program being debugged. A symbol file is created with the MAPSYM utility from a map
`file produced by the Microsoft Object Linker (LINK). A symbol file always has the exten(cid:173)
`sion .SYM. See PROGRAMMING UTILITIES: MAPSYM; LINK.
`The four command-line switches /I, /K, IN, and /S provide SYMDEB with information
`about the computer on which the utility is running. The /I switch is used when the com(cid:173)
`puter is IBM compatible; this causes SYMDEB to take full advantage of special hardware
`features such as the 8259 Programmable Interrupt Controller or the memory-mapped
`video display. The /K switch enables the interactive breakpoint key (Scroll Lock), which
`can then be pressed at any time to interrupt a program that is being traced under the con(cid:173)
`trol of SYMDEB.
`
`Note: The /K switch is not necessary on an IBM PC/AT, because the Sys Req key is always
`active as an interactive break key.
`
`The IN switch enables the use of the nonmaskable interrupt as a breakpoint signal on
`IBM-compatible computers; this interrupt is triggered by hardware-assisted debugging
`packages such as Periscope and Atron Corporation's Software Probe. The /S switch en(cid:173)
`ables the Screen Swap (\) command, which allows the output from the program being
`traced to be maintained and displayed on demand on a virtual screen separate from the
`SYMDEB commands and messages.
`Note: The /I, IN, and /S switches are unnecessary on personal computers built by IBM
`Corporation; SYMDEB automatically enables the capabilities provided by those switches
`when SYMDEB finds the IBM copyright notice in the machine's ROM.
`
`After SYMDEB and any files named in the command line are loaded, SYMDEB displays its
`special prompt character, a hyphen(-), and awaits a command. SYMDEB commands con(cid:173)
`sist of one or two letters, usually followed by one or more parameters. SYMDEB treats
`
`Section IV: Programming Utilities
`
`1055
`
`ZTE (USA) 1007, Page 1065
`
`

`

`SYMDEB
`
`uppercase and lowercase characters equivalently except when they are contained in
`strings enclosed within single or double quotation marks. SYMDEB does not execute
`commands until the Enter key is pressed.
`
`The SYMDEB commands discussed in this section are
`
`Command Action
`
`A
`BC
`BD
`BE
`BL
`BP
`c
`D
`DA
`DB
`DD
`DL
`DS
`DT
`DW
`E
`EA
`EB
`ED
`EL
`ES
`ET
`EW
`F
`G
`H
`I
`K
`L
`M
`N
`0
`p
`Q
`R
`s
`
`Assemble machine instructions.
`Clear breakpoints.
`Disable breakpoints.
`Enable breakpoints.
`List breakpoints.
`Set breakpoints.
`Compare memory areas.
`Display memory.
`Display ASCII.
`Display bytes.
`Display doublewords.
`Display long reals.
`Display short reals.
`Display 10-byte reals.
`Display words.
`Enter data.
`Enter ASCII string.
`Enter bytes.
`Enter doublewords.
`Enter long reals.
`Enter short reals.
`Enter 10-byte reals.
`Enter words.
`Fill memory.
`Go execute program.
`Perform hexadecimal arithmetic.
`Input from port.
`Perform stack trace.
`Load file or sectors.
`Move (copy) data.
`Name file or command-tail parameters.
`Output to port.
`Proceed through loop or subroutine.
`Quit debugger.
`Display or modify registers.
`Search memory.
`
`:~J:II ·i
`b·li
`fli:
`1':!
`tlii
`~~~~.:
`
`1056
`
`The MS-DOS Encyclopedia
`
`(more)
`
`ZTE (USA) 1007, Page 1066
`
`

`

`SYMDEB
`
`.Command Action
`
`S+
`S-
`S&
`T
`U
`V
`W
`X
`XO
`Z
`<
`>
`
`\
`
`Enable source display mode.
`Disable source display mode.
`Enable source and machine code display mode.
`Trace program execution.
`Disassemble (unassemble) program.
`View source code.
`Write file or sectors.
`Examine symbol map.
`Open symbol map.
`Set symbol value.
`Redirect SYMDEB input.
`Redirect SYMDEB output.
`Redirect SYMDEB input and output.
`Redirect target program input.
`Redirect target program output.
`Redirect target program input and output.
`Swap screen.
`Display source line.
`Help or evaluate expression.
`Escape to shell.
`Enter comment.
`
`One or more SYMDEB commands, separated by semicolons and enclosed in double
`quotation marks, can be included in the original SYMDEB command line in the form
`/"commands" (for example, /"r;d;q"). These commands, which must precede the filename
`of the program being debugged, are carried out immediately when SYMDEB is loaded.
`(This is a convenient way to invoke SYMDEB and execute a series of batch commands.)
`
`The parameters for a SYMDEB command include symbols; line numbers; addresses;
`ranges; and 8-bit, 16-bit, 32-bit, or floating-point values, expressions, and lists. Multiple
`parameters can be separated by spaces, tabs, or commas.
`
`A symbol is a name that represents a register, an absolute value, a segment address, or a
`segment offset. A symbol consists of one or more characters but always begins with a let(cid:173)
`ter, an underscore(_), a question mark(?), an at sign(@), or a dollar sign($). The names
`of the various 8086/8088/80286 registers and CPU flags are built into SYMDEB and can be
`used at any time. Other symbols can be used only when one or more symbol files have
`been loaded in conjunction with the program to be debugged.
`
`Note: SYMDEB regards symbols whose spellings differ only in case as the same symbol.
`A unique symbol name that does not conflict with programming instructions, register
`names, or hexadecimal numbers should always be used.
`
`In MASM programs, symbols must be declared PUBLIC in the source code in order to be
`accessible during debugging (except for segment and group names, which are PUBLIC by
`default). In programs compiled with the current versions of Microsoft C, FORTRAN,
`
`Section IV: Programming Utilities
`
`1057
`
`ZTE (USA) 1007, Page 1067
`
`

`

`SYMDEB
`
`and Pascal, all symbols are passed through for debugging if the proper compilation switch
`is used; however, familiarity with the compiler's particular naming conventions is neces(cid:173)
`sary (for example, the Microsoft C Compiler adds an underscore character to the beginning
`of every symbol).
`
`A line number is a combination of decimal numbers, filenames, and symbols that specifies
`a unique line of text in a program source file. Line numbers always start with a dot charac(cid:173)
`ter (.) and take one of the following forms:
`,,
`
`. (jilename:]linenumber
`. +displacement
`.-displacement
`.symbol[ +displacement]
`.symbol[ -displacement]
`
`The second and third variations specify a line relative to the current line number; the
`fourth and fifth specify a line number relative to a designated symbol. Line numbers can
`be used only with programs developed with compilers that generate line-number informa(cid:173)
`tion. Programs developed with MASM or an incompatible compiler cannot generate line
`numbers.
`
`An address identifies a unique location in memory. An address can be a simple offset or a
`complete address consisting of two 16-bit values in the form segment:offset. Each compo(cid:173)
`nent can be a valid symbol (including CS, DS, ES, or SS, in the case of segments), a 16-bit
`hexadecimal number in the range 0 through FFFFH, or a symbol plus or minus a displace(cid:173)
`ment. When the segment portion of an address is absent, the segment specified in the
`previous instance of the same command is used; if no segment was previously specified,
`SYMDEB uses DS unless an A, G, L, P, T, U, or W command is used, in which case SYMDEB
`uses CS.
`
`A range specifies an area of memory or a number of data items and can be expressed as
`either two addresses or a starting address and a length. A length is represented by the letter
`L followed by a hexadecimal value in the range 0 through FFFFH. The meaning of the
`length varies with the SYMDEB command used: The length can signify a number of bytes,
`words, doublewords, real numbers, machine instructions, or source-code lines. If a com(cid:173)
`mand requires a range and the ending address is not supplied, SYMDEB usually assumes
`128 bytes.
`
`A value represents an integral number and is a combination of one or more digits. The
`default base for values is hexadecimal, except in the case of floating-point numbers, but
`other bases can be used by appending a radix character (Y for binary, 0 or Q for octal, T
`for decimal, H for hexadecimal) in either uppercase or lowercase. For example, the follow(cid:173)
`ing values are equivalent:
`
`0040
`0040H
`0064t
`
`OlOOQ
`01000
`1000000Y
`
`1058
`
`The MS-DOS Encyclopedia
`
`ZTE (USA) 1007, Page 1068
`
`

`

`SYMDEB
`
`Doubleword (32-bit) values are entered as two hexadecimal integers separated by a colon
`character (:). Real numbers are always entered in decimal radix, with or without a decimal
`point or exponent. Leading zeros can be omitted.
`
`An expression is a ·combination of symbols, numeric constants, and operators that evalu(cid:173)
`ates to an 8-, 16-, or 32-bit value. An expression can be used in place of a simple value in
`any command. Unary address operators use DS as the default segment for addresses. Ex(cid:173)
`pressions are evaluated in order of operator precedence; operators with equal precedence
`are evaluated from left to right. Parentheses can be used to override the normal operator
`precedence.
`
`The available unary operators, listed in order of precedence from highest to lowest, are
`
`Operator Meaning
`
`+
`
`NOT
`SEG
`OFF
`BY
`wo
`DW
`POI
`PORT
`WPORT
`
`Unary plus
`Unary minus
`One's (bitwise) complement
`~Segment address of operand
`Offset of operand
`Low-order byte from specified address
`Low-order word from specified address
`Doubleword from specified address
`Pointer from specified address (same as DW)
`Byte input from specified port
`Word input from specified port
`
`The available binary operators, listed in order of precedence from highest to lowest, are
`
`Operator Meaning
`•
`I
`MOD
`
`Multiplication
`Integer division
`Modulus
`Segment override
`Addition
`Subtraction
`Bitwise Boolean AND
`Bitwise Boolean Exclusive OR
`Bitwise Boolean Inclusive OR
`
`+
`
`AND
`XOR
`OR
`
`A list is composed of one or more values, expressions, or strings, separated by spaces or
`commas. A string is one or more ASCII characters, enclosed within single or double quota(cid:173)
`tion marks. Case is significant within a string. If the same type of quote character that is
`used to delimit the string occurs inside the string, the character must be doubled inside the
`string in order to be interpreted correctly (for example,"A ""quoted"" word").
`
`Section IV: Programming Utilities
`
`1059
`
`4
`
`ZTE (USA) 1007, Page 1069
`
`

`

`SYMDEB
`
`In a few cases, SYMDEB displays a specific and informative error message in response to
`an invalid command. In general, though, SYMDEB responds in a generic fashion, pointing
`to the approximate location of the error with a caret character ("), followed by the word
`Error. For example:
`
`-D CS:100,CS:80 <Enter>
`"' Error
`
`SYMDEB maintains a set of virtual CPU registers and flags for a program being debugged.
`These registers can be examined and modified with SYMDEB commands. When a pro(cid:173)
`gram is first loaded for debugging, the virtual registers are initialized with the following
`values:
`
`Register
`
`.COM Program
`
`.EXE Program
`
`AX
`BX
`ex
`DX
`SI
`DI
`BP
`SP
`
`IP
`
`cs
`DS
`ES
`ss
`
`Valid drive code
`Upper half of program size
`Lower half of program size
`Zero
`Zero
`Zero
`Zero
`FFFEH or top of available
`memory minus 2
`lOOH
`
`PSP
`PSP
`PSP
`PSP
`
`Valid drive code
`Upper half of program size
`Lower half of program size
`Zero
`Zero
`Zero
`Zero
`Size of stack segment
`
`Offset of entry point within target
`program's code segment
`Base of target program's code segment
`PSP
`PSP
`Base of target program's stack segment
`
`Note: SYMDEB checks the first three parameters in the command line. If the second and
`third parameters are filenames, SYMDEB checks any drive specifications with those file(cid:173)
`names to verify that they designate valid drives. Register AX contains one of the following
`codes:
`
`Code
`
`Meaning
`
`OOOOH
`
`OOFFH
`FFOOH
`FFFFH
`
`The drives specified with the second and third filenames are both valid, or
`only one filename was specified in the command line.
`The drive specified with the second filename is invalid.
`The drive specified with the third filename is invalid.
`The drives specified with the second and third filenames are both invalid.
`
`1060
`
`The MS-DOS Encyclopedia
`
`ZTE (USA) 1007, Page 1070
`
`

`

`SYMDEB
`
`Before SYMDEB transfers control to the target program, it saves the actual CPU registers
`and then loads them with the current values of the virtual registers; conversely, when con(cid:173)
`trol reverts to SYMDEB from the target program, the returned register contents are stored
`back into the virtual register set for inspection and alteration by the SYMDEB user.
`Examples
`To prepare the program CLEAN.ASM for debugging with SYMDEB, declare all vital labels,
`procedures, a