`
`DEBUG: N
`
`.Finally, to execute the program CLEAN.COM, type
`“G <Enter>
`
`The result is the same 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.- Progmmming Utilities
`
`1041
`
`OLYMPUS EX. 1010 - 1051/1582
`
`

`

`
`
`DEBUG: O
`
`DEBUG: 0
`
`Output to Port
`
`Purpose
`
`Writes 1 byte to an input/output (I/O) port.
`
`Syntax
`
`0 port byte
`where:
`
`port
`byte
`
`is an I/O port address from 0 through FFFFH.
`is a value from 0 through OFFH to be written to the I/O port.
`
`Description
`
`The Output to Port (0) command writes 1 byte of data to the specified I/O port address.
`The data value must be in the range 00H 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, timers, 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/O port IOAH, type
`-0 10A C8 <Enter>
`
`
`
`1042
`
`The MS—DOS Encyclopedia
`
`
`
`OLYMPUS EX. 1010 - 1052/1582
`
`

`

`
`
`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:
`
`address
`number
`
`is the location of the first instruction to be executed.
`is the number of instructions to execute.
`
`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-
`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.
`
`7 Warning: The P command cannot be used to trace through ROM.
`
`Example
`
`Assume that the target program’s location CS:143FH 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
`
`OLYMPUS EX. 1010 - 1053/1582
`
`

`

`
`
`DEBUGzQ
`
`DEBUG: Q
`
`Quit
`
`Purpose
`
`Ends a DEBUG session.
`
`a 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>
`
`
`
`1 044
`
`The MS-DOS Encyclopedia
`
`
`
`OLYMPUS EX. 1010 - 1054/1582
`
`

`

`
`
`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 RP SI DI
`DE 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-
`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-
`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-
`played; then DEBUG prompts with a colon character (Q for a new value. The value is en—
`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 If Set (1)
`
`Value If Clear (0)
`
`Overflow
`
`Direction
`Interrupt
`
`OV (Overflow)
`
`NV (No Overflow)
`
`DN (Down)
`EI (Enabled)
`
`UP (Up)
`DI (Disabled)
`
`(more)
`
`Section IV: Programming Utilities
`
`1045
`
`OLYMPUS EX. 1010 - 1055/1582
`
`

`

` DEBUG: R
`
`Flag Name
`
`Sign
`Zero
`Aux Carry
`Parity
`Carry
`
`Value If Set (1)
`
`Value If Clear (0)
`
`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-
`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>
`
`1046
`
`The MS-DOS Encyclopedia
`
`
`
`This produces a display in the following format:
`AX=0000 BX=0000
`CX=00A1 Dx=oooo
`SP=FFFE BP=0000 51:0000 DI=0000
`DS=19A5
`ES=19A5
`SS=19A5 CS=19A5
`IP=0100
`NV UP EI PL NZ NA PO NC
`19A5:0100 BFBOOO
`’
`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:
`NVUPEIPLNZNAPONC -
`
`The direction and carry flags can then be set by entering
`—DN CY <Enter>
`
`OLYMPUS EX. 1010 - 1056/1582
`
`

`

`
`
`DEBUG: R
`
`Messages
`bf Error
`
`Bad flag: An invalid code for a CPU flag was entered.
`
`br Error
`
`. Bad register: An invalid register name was entered.
`
`df Error
`Double flag: Two values for the same CPU flag were entered in the same command.
`
`Section IV: Programming Utilities
`
`1047
`
`OLYMPUS EX. 1010 - 1057/1582
`
`

`

`
`
`DEBUG: S
`
`DEBUG: S
`
`Search Memory
`
`Purpose
`
`Searches memory for a pattern of 1 or more bytes.
`
`Syntax
`
`8 range list
`
`where:
`
`range
`
`specifies the starting and ending addresses or the starting address and length
`of the area to be searched.
`
`list
`
`is 1 or more consecutive byte values and/or a string to be searched for.
`
`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
`
`To search for the string Copyright in the area of memory from DS:OOOOH through
`DS:1FFFH, type
`
`_1
`i.
`l1
`
`1-:
`
`1“}
`
`-5 0 1FFF 'Copyright'
`
`<Enter>
`
`0‘
`
`'
`
`<Enter>
`-5 0 L2000 "Copyright"
`If matches are found, DEBUG displays the starting address of each:
`20A8:0910
`20AS:094F
`ZOAB : 097C
`
`1048
`
`The MS-DOS Encyclopedia
`
`
`
`OLYMPUS EX. 1010 - 1058/1582
`
`

`

`
`
`DEBUG: S
`
`To search for the byte sequence 3BH 06H in the area of memory from CS:0100H through
`"cs:12A0H, type
`—S CS:100 12A0 3B 06 <Enter>
`
`01‘
`
`—S CS:‘100 L11A1
`
`3B 06 <Enter>
`
`Section IV: Programming Utilities
`
`1049
`
`OLYMPUS EX. 1010 - 1059/1582
`
`

`

`
`
`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:
`
`address
`number
`
`is the location of the first instruction to be executed.
`is the number of machine instructions to be executed.
`
`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 Intel 8259 interrupt mask (ports 20H and 21H on the IBM PC and com—
`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-
`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-
`rupts execution of a sequence of T instructions. Consecutive instructions can then be exe-
`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:1AOOH and then return control to DEBUG, dis-
`playing the contents of the CPU registers and the status of the flags, type
`—-T =1 A00 <Enter>
`
`1050
`
`The MS-DOS Encyclopedia
`
`
`
`OLYMPUS EX. 1010 - 1060/1582
`
`

`

`
`
`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-
`tion boundary, the disassembly will be incorrect.
`
`If range does not include a length or ending address, 32 (20H) bytes of memory are dis—
`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—
`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-
`mands Without parameters.
`
`Example
`
`To disassemble 8 bytes of machine instructions starting at CS:0100H, type
`—U 100 107 <Enter>
`
`01'
`
`—U 100 L8 <Enter>
`
`Section IV: Programming Utilities
`
`1051
`
`OLYMPUS EX. 1010 - 1061/1582
`
`

`

`
`
`DEBUG: W
`
`DEBUG: W
`
`Write File or Sectors
`
`Purpose
`
`Writes a file or individual sectors to disk.
`
`'2 Syntax
`W [address]
`or
`
`W address drive start number
`
`where:
`
`address
`drive
`
`start
`number
`
`Description
`
`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 (O—FFFFH).
`is the number of consecutive sectors to be written (O—FFFFH).
`
`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 the W command is used.
`
`When address is not included in the command line, the target program’s CS:0100H is
`assumed.
`
`The W 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 the W command. The disk’s file structure
`can easily be damaged if the wrong parameters are entered.
`
`1052
`
`The MS—DOS Encyclopedia
`
`
`
`OLYMPUS EX. 1010 - 1062/1582
`
`

`

`
`
`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 0100H. 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 CX <Enter>
`
`DEBUG displays the contents of register CX and prompts with a colon (2). 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
`
`V
`EXE and HEX files cannot be written
`Files with a .EXE or .HEX extension cannot be written to disk with the W command.
`
`,
`Writing mmn bytes
`After a successful write operation, DEBUG displays in hexadecimal format the number of
`bytes written to disk.
`
`Section IV.- Programming Utilities
`
`1053
`
`OLYMPUS EX. 1010 - 1063/1582
`
`

`

`
`
`SYMDEB ‘
`
`SYMDEB
`
`Symbolic Debugger
`
`. Purpose
`
`The Symbolic Debugger (SYMDEB) allows a file to be loaded, examined, altered, and writ—
`ten back to disk. If the file contains a program, the program can be disassembled, modi-
`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
`
`OI‘
`
`SYMDEB [options] [symfz'le [symfz‘la . .1] [filename [parameter. . . ]]
`
`where:
`
`symfile
`
`filename
`parameter
`options
`
`is the name of a symbol file created with 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-
`case or lowercase and can be preceded by a dash (-) instead of a forward
`slash (/).
`
`/I
`/K
`/N
`
`/8
`
`/“commands”
`
`(IBM) specifies that the computer is IBM compatible.
`enables the interactive breakpoint key (Scroll Lock).
`enables the use of nonmaskable interrupt break sys-
`tems on IBM—compatible computers (requires special
`hardware).
`
`enables the Screen Swap (\) command on IBM—com-
`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
`
`:
`
`;
`
`t
`
`1054
`
`TheMS—DOSEncyclopedz’a
`
`
`
`OLYMPUS EX. 1010 - 1064/1582
`
`

`

`' hexadecimal addresses. SYMDEB’s command repertoire also includes I/O redirection
`commands, floating—point number entry and display commands, and source-code display
`capabilities that are not present in DEBUG.
`
`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-
`sion .SYM. See PROGRAMMING UTILITIES: MAPSYM; LINK.
`
`The four command—line switches /I, /K, /N, and /5 provide SYMDEB with information
`about the computer on which the utility is running. The /I switch is used when the com-
`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-
`trol of SYMDIEB.
`
`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 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-
`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 100H. If SYMDEB is
`entered by itself, no file information is read into memory. An appropriate program seg-
`ment prefix (PSP) is synthesized at the head of SYMDEB’s buffer for use by the target pro-
`gram; the PSP includes a command tail at offset 80H and default file control blocks (FCBs)
`at offsets SCH 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.
`
`SYMDEB addresses with labels, variable names, and expressions, rather than only with absolute
`
`The /N 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-
`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, /N, 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-
`sist of one or two letters, usually followed by one or more parameters. SYMDEB treats
`
`Section IV.- Programming Utilities
`
`1055
`
`OLYMPUS EX. 1010 - 1065/1582
`
`

`

`
`
`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.
`
`.
`
`1056
`
`The MS—DOS Encyclopedia
`
`(more)
`
`
`
`OLYMPUS EX. 1010 - 1066/1582
`
`

`

`
`
`Command Action
`
`,
`
`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.
`
`S+
`5—
`88:
`T
`U
`V
`W
`
`0
`
`X
`
`/l“""'“l|V/\N><.'
`
`.‘J.
`!
`‘
`
`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.
`
`SYMDEB
`
`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
`/"commzmds" (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, 52—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-
`ter, an underscore (_), a question mark (.7), 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
`
`OLYMPUS EX. 1010 - 1067/1582
`
`

`

`
`
`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-
`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-
`ter C.) and take one of the following forms:
`
`. [filenamez] linenumber
`.+displacement
`.—displacement
`.symbol[+dz‘splacemem]
`.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—
`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-
`nent can be a valid symbol (including CS, DS, BS, 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—
`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-
`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, O or Q for octal, T
`for decimal, H for hexadecimal) in either uppercase or lowercase. For example, the follow-
`ing values are equivalent:
`
`0040
`OO4OH
`0064t
`
`0100Q
`01000
`1000000Y
`
`1058
`
`The MS-DOS Encyclopedia
`
`
`
`OLYMPUS EX. 1010 - 1068/1582
`
`

`

`
`
`
`
`' SYMDEBWm
`
`Doubleword (52-bit) values are entered as two hexadecimal integers separated by a colon
`'character (z). 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-
`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-
`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
`
`Unary plus
`+
`Unary minus
`—
`One’s (bitwise) complement
`NOT
`/ Segment address of operand
`SEG
`Offset of operand
`OFF
`Low-order byte from specified address
`BY
`Low-order word from specified address
`W0
`Doubleword from specified address
`DW
`Pointer from specified address (same as DW)
`POI
`Byte input from specified port
`PORT
`WPORT Word input from specified port
`
`The available binary operators, listed in order of precedence from highest to lowest, are
`
`Operator Meaning
`
`t
`/
`MOD
`
`;
`+
`—
`AND
`XOR
`OR
`
`Multiplication
`Integer division
`Modulus
`
`Segment override
`Addition
`Subtraction
`Bitwise Boolean AND
`Bitwise Boolean Exclusive OR
`Bitwise Boolean Inclusive 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-
`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
`
`OLYMPUS EX. 1010 - 1069/1582
`
`

`

`
`
`SYMDEB
`
`x
`
`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 (A), followed by the word
`Error. For example:
`—D CS:100,CS:80 <Enter>
`A 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-
`gram is first loaded for debugging, the virtual registers are initialized with the following
`values:
`
`Register
`
`.COM Program
`
`Valid drive code
`
`.EXE Program
`
`Valid drive code
`
`AX
`
`BX
`CX
`DX
`
`SI
`DI
`BP
`
`SP
`
`IP
`
`CS
`DS
`ES
`
`88
`
`Upper half of program size
`Lower half of program size
`Zero
`
`Upper half of program size
`Lower half of program size
`Zero
`
`Zero
`Zero
`Zero
`
`FFFEH or top of available
`memory minus 2
`100H
`
`PSP
`PSP
`PSP
`
`PSP
`
`Zero 1
`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-
`names to verify that they designate valid drives. Register AX contains one of the following
`codes:
`
`Code
`
`Meaning
`
`OOOOH
`
`OOFFH
`FFOOI-I
`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
`
`
`
`OLYMPUS EX. 1010 - 1070/1582
`
`

`

`
`
`. '\_ _
`
`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-
`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, and variable names in the source program PUBLIC. To assemble the program,
`type
`
`C>MASM CLEAN;
`
`<Enter>
`
`This produces the relocatable object module CLEAN.OBJ. Then, to link the object module,
`type
`
`C>LINK /MAP CLEAN:
`
`<Enter>
`
`This results in the executable program file CLEAN.EXE and the map file CLEANMAP.
`
`Note: The /MAP switch must be used even if a map file is specified in the command line.
`Finally, to create the symbol information file required by SYMDEB, type
`
`C>MAPSYM CLEAN <Enter>
`
`. At this point, begin symbolic debugging by typing
`
`C>SYMDEB CLEAN.SYM CLEAN.EXE. <Enter>
`
`Any run-time command-line parameters required by the CLEAN program may be placed
`in the SYMDEB command line after the filename CLEAN.EXE.
`
`To prepare the program