The MS-DOS Encyclopedia: Section IV: Programming Utilities

Archive of outdated Microsoft articles and reference materials


The MS-DOS Encyclopedia

Section IV: Programming Utilities

INTRODUCTION


    This section of The MS-DOS Encyclopedia describes the Microsoft
    utilities, documentation aids, and debuggers that can be used with the
    Microsoft C, FORTRAN, Pascal, and BASIC compilers and with the
    Microsoft Macro Assembler (MASM). Included are operating instructions
    for MASM, the Macro Assembler; LIB, the Library Manager; LINK, the
    Microsoft Object Linker; the DEBUG, SYMDEB, and CodeView program
    debuggers; MAKE, which automates maintenance of programs; CREF, which
    produces a cross-reference listing of symbols;  and EXE2BIN, EXEMOD,
    and EXEPACK, which modify executable files.

    Entries (except for the program debuggers) are arranged alphabetically
    by the name of the programming utility. The three Microsoft debuggers
    are listed at the end of the section in the following order: DEBUG,
    SYMDEB, CodeView. Individual DEBUG and SYMDEB commands appear
    alphabetically under the headings DEBUG and SYMDEB.

    Each utility entry includes

    ■  Utility name
    ■  Utility purpose
    ■  Prototype command line and summary of options
    ■  Detailed description of utility
    ■  One or more examples of utility use
    ■  Return codes (where applicable)
    ■  Error messages and warnings (where applicable)

    The experienced user can find information with a quick glance at the
    first part of a utility entry; a less experienced user can refer to
    the detailed explanation and examples in a more leisurely fashion. The
    next two pages contain an example of a typical entry from the
    Programming Utilities section, with explanations of each
    component.



EXEPACK

Compress .EXE File


Purpose

    Compresses an executable .EXE program file so that it requires less
    space on the disk. The EXEPACK utility is supplied with the Microsoft
    Macro Assembler (MASM), C Compiler, FORTRAN Compiler, and Pascal
    Compiler. This documentation describes EXEPACK version 4.04.

Syntax

    EXEPACK exe file packed file

    where:

    exe file        is the name of the executable .EXE program file to be
                    compressed.

    packed file     is the name of the compressed program file.

Description

    The EXEPACK utility compresses an executable .EXE program by packing
    sequences of identical bytes and optimizing the relocation table. The
    EXEPACK utility is not compatible with versions of MS-DOS earlier than
    2.0.

    The exe file parameter specifies the name of the program file
    produced by the Microsoft Object Linker (LINK) and must contain the
    extension .EXE. The packed file parameter specifies the name and
    extension of the resulting compressed file. EXEPACK has no default
    extensions.

    The name for packed file must be different from the exe file
    filename. Although it is possible to fool EXEPACK into creating a
    packed file with the same name by specifying a different but
    equivalent pathname for the output file, the resulting packed file
    will probably be damaged. If the packed file is to replace the
    original .EXE file, a different name should be specified for the
    packed file; then the input file should be deleted and the packed file
    renamed with the name of the original file.

    When EXEPACK is used to compress an executable overlay file or a
    program that calls overlays, the packed file should be renamed with
    its original name before use to avoid interruption by the overlay-
    manager prompt.

    The effects of EXEPACK depend on program characteristics. Most
    programs can be processed with EXEPACK to occupy significantly less
    disk space. Programs thus compressed also load for execution more
    quickly. Occasionally programs (particularly small ones) actually
    become larger after processing with EXEPACK; in such cases the file
    produced by EXEPACK should be discarded. Microsoft Windows programs or
    programs to be debugged under DEBUG, SYMDEB, or CodeView should not be
    compressed with EXEPACK.

    Using EXEPACK on a previously linked program is equivalent to
    specifying LINK's /EXEPACK switch while linking that program.

    Note: When using the EXEMOD utility with packed .EXE files created
    with EXEPACK or the /EXEPACK linker switch, use the EXEMOD version
    shipped with LINK or with the EXEPACK utility to ensure
    compatibility.

Return Codes

    0  No error; the EXEPACK operation was successful.
    1  An error was encountered that terminated execution of the EXEPACK
        utility.

Example

    To compress the file BUILD.EXE into a file named BUILDX.EXE,
    type

    C>EXEPACK BUILD.EXE BUILDX.EXE  <Enter>

Messages

    fatal error U1100: out of space on output file
    The destination disk has insufficient space for the output file, or
    the root directory is full.

    fatal error U1101: filename: file not found
    The .EXE file specified in the command line cannot be found.

    fatal error U1102: filename: permission denied
    A file with the same name as the specified output file already exists
    and is read-only.

    fatal error U1103: cannot pack file onto itself
    The file cannot be compressed because the name specified for the
    packed file is the same as the name of the source .EXE file.

    fatal error U1104: usage : exepack <infile> <outfile>
    The command line contained a syntax error, or the output filename was
    not specified.

    fatal error U1105: invalid .EXE file; bad header
    The file is not an executable file or has an invalid file
    header.

    fatal error U1106: cannot change load-high program
    The file cannot be compressed because the minimum allocation value and
    the maximum allocation value are both zero. See also PROGRAMMING
    UTILITIES: EXEMOD.

    fatal error U1107: cannot pack already-packed file
    The file specified has already been packed with EXEPACK.

    fatal error U1108: invalid .EXE file; actual length less than
    reported
    The file size indicated in the .EXE file header does not match the
    size recorded in the disk directory.

    fatal error U1109: out of memory
    The EXEPACK utility did not have enough memory to operate.



CREF
Generate Cross-Reference Listing


Purpose

    Produces a cross-reference listing of all symbols in an assembly
    language program. The CREF utility is supplied with the Microsoft
    Macro Assembler (MASM). This documentation describes CREF version
    4.0.

Syntax

    CREF

    or

    CREF crf_file[;]

    or

    CREF crf_file,ref_file

    where:

    crf_file   is the input file previously produced by MASM (default
                extension = .CRF).

    ref_file   is the output ASCII text file to be created (default
                extension = .REF).

Description

    The CREF utility processes a file produced by MASM and generates an
    ASCII cross-reference listing in a file on disk or directly on a
    character device (such as a printer). The output file contains an
    alphabetic list of the symbols in the assembled program, including the
    line number of each reference to the symbol and the total number of
    symbols in the program. A pound sign (#) follows the line number of
    the reference that defines the symbol.

    The crf_file has the default extension .CRF. It is produced by
    providing MASM with a filename other than NUL in the cross-reference
    position in the command line, by responding to the Cross-reference:
    prompt, or by including the /C switch in the MASM command line or at
    any MASM prompt. An assembly source listing file (.LST) must also be
    requested in the MASM command line or in response to the MASM prompts
    in order to generate a valid .CRF file.

    If a semicolon follows the crf_file parameter in the CREF command,
    the resulting ref_file containing the cross-reference listing is given
    the same drive and pathname as crf_file, with a .REF extension. If the
    optional ref_file parameter is present, it can consist of any
    pathname with an optional extension (default is .REF). The cross-
    reference listing can be sent directly to a character device, rather
    than to a file, by specifying a valid character device name (such as
    PRN) in the ref_file position.

    If the CREF utility is run without any parameters or with some
    parameters missing, the CREF utility prompts the operator for the
    necessary information.

Return Codes

    0     No error; the CREF operation was successful.

    1     An error was encountered that terminated execution of the CREF
        utility.

Examples

    To process the file MENUMGR.CRF (created during assembly of
    MENUMGR.ASM) into the cross-reference file MENUMGR.REF, type

    C>CREF MENUMGR;  <Enter>

    To process the file MENUMGR.CRF and assign the name MENU.REF to the
    resulting cross-reference file, type

    C>CREF MENUMGR,MENU  <Enter>

    To process the file MENUMGR.CRF and send the cross-reference listing
    directly to the printer, type

    C>CREF MENUMGR,PRN  <Enter>

    To run the CREF program in interactive mode, type

    C>CREF  <Enter>

    The following is an example of an interactive CREF session:

C>CREF  <Enter>
Microsoft (R) Cross Reference Utility  Version 4.00
Copyright (C) Microsoft Corp 1981, 1983, 1984, 1985. All rights reserved.

Cross-reference [.CRF]: MENUMGR  <Enter>
Listing [MENUMGR.REF]:  <Enter>

9 Symbols

C>

    The following sequence of commands produces the cross-reference
    listing HELLO.REF from the assembly-language source file
    HELLO.ASM:

    C>MASM HELLO,HELLO,HELLO,HELLO  <Enter>
    C>CREF HELLO;  <Enter>

Contents of the file HELLO.ASM:

            name    hello
            page    55,132
            title   HELLO.ASM - print Hello on terminal
    ;
    ; HELLO.COM utility to demonstrate CREF listing
    ;
    cr      equ     0dh             ;ASCII carriage return
    lf      equ     0ah             ;ASCII linefeed

    cseg    segment para public "CODE"

            org     100h

            assume  cs:cseg,ds:cseg,es:cseg,ss:cseg

    print   proc    near
            mov     dx,offset message
            mov     ah,9            ;print the string "Hello"
            int     21h
            mov     ax,4c00h        ;exit to MS-DOS
            int     21h             ;with "return code" of zero
    print   endp

    message db      cr,lf,'Hello!',cr,lf,'$

    cseg    ends

            end     print

    Contents of the file HELLO.REF:

Microsoft Cross-Reference  Version 4.00          Mon Sep 07 23:31:21  1987
HELLO.ASM - print Hello on terminal

    Symbol Cross-Reference           (# is definition)               Cref-1

CODE . . . . . . . . . . . . . .   10
CR . . . . . . . . . . . . . . .    7     7#     24     25
CSEG . . . . . . . . . . . . . .   10    10#     14     14    14   14  27

LF . . . . . . . . . . . . . . .    8     8#     24     25

MESSAGE. . . . . . . . . . . . .    17   24      24#

PRINT. . . . . . . . . . . . . .    16   16#     29


6 Symbols

Messages

    can't open cross-reference file for reading
    The pathname or drive specified for the input .CRF file is invalid or
    does not exist.

    can't open listing file for writing
    A write error has halted the creation of the .REF listing file. This
    indicates that the disk is full or write-protected, that the specified
    output file is read-only, or that the specified device is not
    available.

    cref has no switches
    A switch was specified in the command line; CREF has no optional
    switches.

    DOS 2.0 or later required
    CREF does not work with versions of MS-DOS earlier than 2.0.

    extra file name ignored
    More than two filenames were specified in the command line. The CREF
    utility generates the cross-reference listing using the first two
    filenames specified.

    line invalid, start again
    No .CRF file was specified in the command line or at the prompt.
    Specify a valid .CRF file at the prompt following this message.

    out of heap space
    Memory is insufficient to process the .CRF file. Remove memory
    resident programs and shells or add more memory.

    premature eof
    The input file specified is damaged or is not a valid .CRFfile.

    read error on stdin
    A Control-Z was received from the keyboard or a redirected file and
    has halted CREF.



EXE2BIN
Convert .EXE File to Binary-Image File


Purpose

    Converts an executable file in the .EXE format to a memory-image file
    in binary format. The EXE2BIN utility is supplied with the MS-DOS
    distribution disks.

Syntax

    EXE2BIN exe_file [bin_file]

    where:

    exe_file        is the .EXE-format file to be converted (default
                    extension = .EXE).

    bin_file        is the name to be given to the converted file
                    (default extension = .BIN).

Description

    The .EXE executable program files produced by the Microsoft Object
    Linker (LINK) contain a special header and a relocation table as well
    as the program code and data. The EXE2BIN utility can be used to
    convert a .EXE file to a .COM executable file, which is an absolute
    memory image of the program to be executed and does not contain a
    special header or relocation table. The EXE2BIN utility can also be
    used to convert .EXE files with an origin of zero (such as installable
    MS-DOS device drivers) to pure memory-image files. Files in memory-
    image format (a common format for device drivers and for programs to
    be placed in ROM for execution) usually have a .BIN or .SYS
    extension.

    To convert a .EXE program to a binary-image file, the following are
    required:

    ■  The program must be a valid .EXE file produced by LINK.

    ■  The program can contain only one segment and cannot contain a
        declared stack segment.

    ■  The program code and data portion of the .EXE file must be less
        than 64 KB.

    To convert a .EXE program to an executable .COM file, the following
    are required:

    ■  The origin of the program must be 0100H, which must also be
        specified as the entry point.

    ■  The program code and data portion of the .EXE file must be less
        than 65227 bytes (64 KB minus 256 bytes used by the program segment
        prefix minus 2 bytes initially placed on the stack).

    ■  The program must not include any FAR references.

    Note: Many compilers cannot create programs that can be converted to
    .COM files. Check the compiler documentation for specific information
    concerning executable .COM files.

    The exe_file parameter in the command line can have any filename and
    can include a drive and path; the default extension is .EXE. The
    optional bin_file parameter can also contain any filename and a drive
    and path; the default extension is .BIN. If no path is specified with
    the bin_file parameter, the output file is given the same drive and
    path as the exe_file. If no bin_file parameter is supplied, the
    output file is given the same name as the exe_file, with the
    extension .BIN.

    If the program in the .EXE file requires segment fixups (that is, if
    the program contains instructions requiring segment relocation, which
    would ordinarily be done by the MS-DOS loader using the .EXE file's
    relocation table), EXE2BIN prompts for a base segment address.  When
    segment fixups are necessary, the resulting program is not relocatable
    and must be loaded at the given location to be executed; the MS-DOS
    loader cannot load the program.

Examples

    To convert the file HELLO.EXE to the file HELLO.BIN, type

    C>EXE2BIN HELLO  <Enter>

    To convert the file CLEAN.EXE, which has an origin of 0100H and meets
    the requirements for an executable .COM file, to the file CLEAN.COM,
    type

    C>EXE2BIN CLEAN.EXE CLEAN.COM  <Enter>

    To convert the file ASYNCH.EXE, produced by assembling and linking the
    device-driver source file ASYNCH.ASM, to the installable device-driver
    file ASYNCH.SYS, type

    C>EXE2BIN ASYNCH.EXE ASYNCH.SYS  <Enter>

Messages

    File cannot be converted
    The program to be converted has one of the following problems: The
    program has an origin of 0100H but a different entry point; the
    program requires segment fixups; the program code and data are larger
    than 64 KB; the program has more than one declared segment; or the
    file is not a valid .EXE-format file.

    File creation error
    EXE2BIN cannot create the output file because a read-only file with
    the same name already exists, because the specified directory is full,
    or because the specified disk is full, write-protected, or
    unreadable.

    File not found
    The file does not exist or the incorrect path was given.

    Fixups needed - base segment (hex):
    The .EXE-format file contains segment references that would ordinarily
    be relocated by the .EXE file loader. Specify the absolute segment
    address at which the converted module will be executed.

    Incorrect DOS version
    The version of EXE2BIN is not compatible with the version of MS-DOS
    that is running.

    Insufficient disk space
    The destination disk has insufficent space to create the memory-image
    output file.

    Insufficient memory
    Not enough memory is available to run EXE2BIN.

    WARNING - Read error in EXE file.
            Amount read less than size in header.
    The file size given in the .EXE header is inconsistent with the actual
    size of the file.



EXEMOD
Modify .EXE File Header


Purpose

    Allows inspection or modification of the fields in a .EXE file header.
    The EXEMOD utility is supplied with the Microsoft Macro Assembler
    (MASM), C Compiler, FORTRAN Compiler, and Pascal Compiler. This
    documentation describes EXEMOD version 4.02.

Syntax

    EXEMOD exe_file [/H]

    or

    EXEMOD exe_file [/STACK n] [/MAX n] [/MIN n]

    where:

    exe_file        is the name of an executable program in .EXE format
                    (the extension .EXE is assumed).

    /H              displays the values in the file's header.

    /STACK n        modifies the size of the program's stack segment to n
                    (hexadecimal) bytes.

    /MAX n          sets the maximum memory allocation for the program to
                    n (hexadecimal) paragraphs.

    /MIN n          sets the minimum memory allocation for the program to
                    n (hexadecimal) paragraphs.

    Note: Switches can be either uppercase or lowercase and can be
    preceded by a dash (-) instead of a forward slash (/).

Description

    Programs that are executable under MS-DOS can be in one of two file
    formats: .COM, which is an absolute image of the file to be executed
    and limits the program size to 65227 bytes (64 KB minus 256 bytes used
    by the program segment prefix minus 2 bytes initially placed on the
    stack); or .EXE, which allows a program of any size to be loaded and
    has a special header containing information about the program's entry
    point, stack size, and memory requirements, plus a relocation
    table.

    The EXEMOD utility can be used to display or modify those fields of a
    .EXE program header that control the size of the stack segment and the
    amount of memory allocated to the program when MS-DOS loads the
    program into the transient program area for execution.

    The /STACKn switch controls the number of bytes in the program's
    STACK segment by setting the initial SP to the hexadecimal value
    specified. The minimum paragraph allocation value is adjusted if
    necessary. The EXEMOD /STACKn switch should be used only with
    programs compiled by Microsoft C version 3.0 or later, Microsoft
    Pascal version 3.3 or later, or Microsoft FORTRAN version 3.0 or
    later. Use of the /STACKn switch with a program developed with
    another compiler can cause the program to fail or cause EXEMOD to
    return an error message.

    The /MAXn switch specifies the maximum number of additional
    paragraphs of memory to allocate for use by the program. The /MINn
    switch specifies the minimum number of paragraphs of memory, in
    addition to the size of the program itself and its stack and data
    segments, that are required for the program to execute. If enough
    memory exists to satisfy the minimum additional paragraphs requested
    but not enough exists to satisfy the maximum, MS-DOS allocates all
    available memory to the program.

    To display the current memory allocation and stack size values from a
    .EXE file's header, the /H switch can be used or the file's name can
    be entered as the only parameter in the command line.

    When EXEMOD is used on a previously packed .EXE file (a file that was
    processed by EXEPACK or linked with the /EXEPACK switch), the values
    set or displayed in the file's header are the values that will apply
    after the file is expanded at load time. EXEMOD displays a message
    advising the user that the file being modified was previously
    packed.

    The EXEMOD switches /MAXn and /STACKn correspond to the Microsoft
    Object Linker's /CPARMAXALLOC:n and /STACK:n switches, respectively.
    See PROGRAMMING UTILITIES: LINK.

Return Codes

    0  No error; EXEMOD operation was successful.
    1  An error was encountered that terminated execution of the EXEMOD
        program.

Examples

    To display the values in the file header of the DUMP.EXE program,
    type

    C>EXEMOD DUMP.EXE  <Enter>

    or

    C>EXEMOD DUMP.EXE /H  <Enter>

    The EXEMOD utility displays the following:

    Microsoft (R) EXE File Header Utility  Version 4.02
    Copyright (C) Microsoft Corp 1985.  All rights reserved.
    DUMP.EXE                           (hex)           (dec)

    .EXE size (bytes)                    580            1408
    Minimum load size (bytes)            383             899
    Overlay number                         0               0
    Initial CS:IP                  0000:0000
    Initial SS:SP                  0034:0040              64
    Minimum allocation (para)              5               5
    Maximum allocation (para)           FFFF           65535
    Header size (para)                    20              32
    Relocation table offset               20              32
    Relocation entries                     1               1

    To change the size of the STACK segment for the DUMP.EXE program to
    400H (1024) bytes, type

    C>EXEMOD DUMP.EXE /STACK 400  <Enter>

    EXEMOD displays the message

    EXEMOD : warning U4051: minimum allocation less than stack; correcting
            minimum

Messages

    error U1050: usage : exemod file [-/h] [-/stack n] [-/max n] [-/min n]
    An error was detected in the EXEMOD command line.

    error U1051: invalid .EXE file : bad header
    The file is not an executable file or has an invalid file header.

    error U1052: invalid .EXE file : actual length less than reported
    The file size indicated in the .EXE file header does not match the
    size recorded in the disk directory.

    error U1053: cannot change load-high program
    The header of the file cannot be modified because the minimum
    allocation value and the maximum allocation value are both zero.

    error U1054: file not .EXE
    The file specified does not have a .EXE extension.

    error U1055: filename : cannot find file
    The .EXE file specified in the command line cannot be found.

    error U1056: filename : permission denied
    The .EXE file specified in the command line is read-only.

    warning U4050: packed file
    The specified file is a packed file; that is, it was previously
    processed with the EXEPACK utility or was linked with the /EXEPACK
    switch. This is an informational message only; EXEMOD still modifies
    the file. The header values displayed are the values that will apply
    after the packed value is expanded at load time.

    warning U4051: minimum allocation less than stack; correcting
    minimum
    The minimum allocation value is not large enough to accommodate the
    stack; the minimum allocation value is adjusted. This is an
    informational message only.

    warning U4052: minimum allocation greater than maximum; correcting
    maximum
    If the minimum allocation value is greater than the maximum allocation
    value, the maximum value is adjusted. This is an informational message
    only.



EXEPACK
Compress .EXE File


Purpose

    Compresses an executable .EXE program file so that it requires less
    space on the disk. The EXEPACK utility is supplied with the Microsoft
    Macro Assembler (MASM), C Compiler, FORTRAN Compiler, and Pascal
    Compiler. This documentation describes EXEPACK version 4.04.

Syntax

    EXEPACK exe_file packed_file

    where:

    exe_file        is the name of the executable .EXE program file to be
                    compressed.
    packed_file     is the name of the compressed program file.

Description

    The EXEPACK utility compresses an executable .EXE program by packing
    sequences of identical bytes and optimizing the relocation table. The
    EXEPACK utility is not compatible with versions of MS-DOS earlier than
    2.0.

    The exe_file parameter specifies the name of the program file
    produced by the Microsoft Object Linker (LINK) and must contain the
    extension .EXE. The packed_file parameter specifies the name and
    extension of the resulting compressed file. EXEPACK has no default
    extensions.

    The name for packed_file must be different from the exe_file
    filename. Although it is possible to fool EXEPACK into creating a
    packed file with the same name by specifying a different but
    equivalent pathname for the output file, the resulting packed file
    will probably be damaged. If the packed file is to replace the
    original .EXE file, a different name should be specified for the
    packed file; then the input file should be deleted and the packed file
    renamed with the name of the original file.

    When EXEPACK is used to compress an executable overlay file or a
    program that calls overlays, the packed file should be renamed with
    its original name before use to avoid interruption by the overlay-
    manager prompt.

    The effects of EXEPACK depend on program characteristics. Most
    programs can be processed with EXEPACK to occupy significantly less
    disk space. Programs thus compressed also load for execution more
    quickly. Occasionally programs (particularly small ones) actually
    become larger after processing with EXEPACK; in such cases the file
    produced by EXEPACK should be discarded. Microsoft Windows programs or
    programs to be debugged under DEBUG, SYMDEB, or CodeView should not be
    compressed with EXEPACK.

    Using EXEPACK on a previously linked program is equivalent to
    specifying LINK's /EXEPACK switch while linking that program.

    Note: When using the EXEMOD utility with packed .EXE files created
    with EXEPACK or the /EXEPACK linker switch, use the EXEMOD version
    shipped with LINK or with the EXEPACK utility to ensure
    compatibility.

Return Codes

    0  No error; the EXEPACK operation was successful.
    1  An error was encountered that terminated execution of the EXEPACK
        utility.

Example

    To compress the file BUILD.EXE into a file named BUILDX.EXE,
    type

    C>EXEPACK BUILD.EXE BUILDX.EXE  <Enter>

Messages

    fatal error U1100: out of space on output file
    The destination disk has insufficient space for the output file, or
    the root directory is full.

    fatal error U1101: filename: file not found
    The .EXE file specified in the command line cannot be found.

    fatal error U1102: filename: permission denied
    A file with the same name as the specified output file already exists
    and is read-only.

    fatal error U1103: cannot pack file onto itself
    The file cannot be compressed because the name specified for the
    packed file is the same as the name of the source .EXE file.

    fatal error U1104: usage : exepack <infile> <outfile>
    The command line contained a syntax error, or the output filename was
    not specified.

    fatal error U1105: invalid .EXE file; bad header
    The file is not an executable file or has an invalid file
    header.

    fatal error U1106: cannot change load-high program
    The file cannot be compressed because the minimum allocation value and
    the maximum allocation value are both zero. See also PROGRAMMING
    UTILITIES: EXEMOD.

    fatal error U1107: cannot pack already-packed file
    The file specified has already been packed with EXEPACK.

    fatal error U1108: invalid .EXE file; actual length less than
    reported
    The file size indicated in the .EXE file header does not match the
    size recorded in the disk directory.

    fatal error U1109: out of memory
    The EXEPACK utility did not have enough memory to operate.

    fatal error U1110: error reading relocation table
    The file cannot be compressed because the relocation table cannot be
    found or is invalid.

    fatal error U1111: file not suitable for packing
    The file could not be packed because the packed load image of the
    specified file was larger than the unpacked load image.

    fatal error U1112: filename: unknown error
    An unknown system error occurred while the specified file was being
    processed.

    warning U4100: omitting debug data from output file
    EXEPACK has stripped all symbolic debug information from the output
    file.



LIB
Library Manager


Purpose

    Creates or modifies an object module library file. The LIB utility is
    supplied with the Microsoft Macro Assembler (MASM), C Compiler,
    FORTRAN Compiler, and Pascal Compiler. This documentation describes
    LIB version 3.06.

Syntax

    LIB

    or

    LIB library_file [/PAGESIZE:n] [operation][,[list_file]
    [,[new_library_file]]] [;]

    or

    LIB @response_file

    where:

    library_file           is the name of the object module library file
                            to be created or modified (default extension
                            = .LIB).

    /PAGESIZE:n            is the page size of the library file and must
                            immediately follow library_file if used; n
                            is a power of 2 between 16 and 32768,
                            inclusive (default = 16). Can be abbreviated
                            /P:n.

    operation              is one or more library manipulations to be
                            performed. Each operation is specified as a
                            code followed by an object module name (case
                            is not significant):

                            +name  Add object module or another library to
                                library.

                            -name  Delete object module from library.

                            -+name Replace object module in library.

                            *name  Copy object module from library to
                                object file.

                            -*name Copy object module to object file and
                                then delete object module from library.

    list_file              is the name of the file or character device to
                            receive the cross-reference listing for the
                            library file (default = NUL device).

    new_library_file       is the name to be assigned to the modified
                            object module library file. (The default name
                            is the same as library_file; if the default is
                            used, the original library_file is renamed
                            with the extension .BAK.)

    response_file          is the name of a text file containing LIB
                            parameters in the same order in which they are
                            supplied if entered interactively. The name of
                            the response file must be preceded by the @
                            symbol.

Description

    The Microsoft Library Manager (LIB) creates and modifies library
    files, checks existing library files for consistency, and prints
    listings of the contents of library files. The LIB utility does not
    work with versions of MS-DOS earlier than 2.0.

    A library file consists of relocatable object modules that are indexed
    by their names and public symbols. The Microsoft Object Linker (LINK)
    uses these files during the creation of an executable (.EXE) program
    to resolve external references to routines and variables contained in
    other object modules.

    The library_file parameter specifies the name of the object module
    library file to be created or modified. This parameter is required; if
    it is not included, LIB prompts for it. The default extension for a
    library file is .LIB.

    The /PAGESIZE:n switch (abbreviated /P:n) sets the page size (in
    bytes) for a new library file or changes the page size of an existing
    library file. The value of n must be a power of 2 between 16 and
    32768, inclusive. The default is 16 for a new library file; for an
    existing library file, the default is the current page size. Because
    the index to a library file is contained in a fixed number of pages,
    setting a larger page size increases the number of index entries (and
    thus the number of object modules) that a library file can contain but
    results in more wasted disk space (an average of half a library page
    per object module).

    The operation parameter specifies one or more relocatable object
    modules to add to, replace in, copy from, move from, or delete from
    library_file. Each operation is represented by a code specifying the
    type of operation, followed by the object module name. When an object
    module is copied or moved from the library file, the drive and
    pathname of the object module are set to the default drive, current
    directory, and specified module name, and the extension of the object
    module defaults to .OBJ. When an object module is added or replaced,
    LIB assumes a default extension of .OBJ.

    The operation +name adds the object module in the file name.OBJ to
    the library file. This operation can also be used to add the contents
    of another entire object module library file to the library file being
    updated, in which case the extension .LIB must be included in name.
    The operation -name deletes the object module name from the library.
    The operation -+name deletes the object module name from the library
    file and replaces it with the contents of the file name.OBJ. The
    operation *name copies the object module name from the library file
    into the file name.OBJ, which LIB creates in the current directory.
    The operation -*name also copies the object module name from the
    library file into a .OBJ file but then deletes the module from the
    library file. (Although name must have exactly the same spelling as
    the name in the library's reference listing, case is not
    significant.)

    Note: LIB does not actually delete object modules from the specified
    library file. Instead, it marks the selected object modules for
    deletion, creates a new library file, and copies only the modules not
    marked for deletion into the new file. Thus, if LIB is terminated for
    any reason, the original file is not lost. Enough space must be
    available on the disk for both the original library file and the
    copy.

    The list_file parameter specifies the file or character device to
    receive a reference listing for the library file. Any valid drive,
    pathname, and extension or any valid character device, such as PRN, is
    permitted (default = NUL). If this parameter is omitted, no listing is
    generated.

    The reference listing consists of two tables. The first table contains
    all the public symbols in the object modules in the library, listed
    alphabetically, with each symbol followed by the name of the object
    module in which it is referenced. The second table contains the names
    of all the object modules, listed alphabetically, with each name
    followed by the offset from the start of the library file, the code
    and data size, and an alphabetic listing of the public symbols in that
    object module.

    The new_library_file parameter specifies the name for the modified
    library file that is created. If this parameter is omitted, LIB gives
    the modified library file the same name as the original library file,
    and the original library file is renamed with a .BAK extension. When a
    new library file is being created, this parameter is not
    necessary.

    When the command line is used to supply LIB with filenames and
    switches, typing a semicolon character (;) after any parameter (except
    library_file) causes LIB to use the default values for the remaining
    parameters. If a semicolon is entered after library_file, LIB simply
    checks the file for consistency and usability. (This is seldom
    necessary, because LIB checks each object module for consistency
    before adding it to the library.)

    If the LIB command is entered without any parameters, LIB prompts the
    user for each parameter needed. If there are too many operations to
    fit on one line, the line can be ended with the ampersand character
    (&), causing LIB to repeat the Operations: prompt. If any response
    except library_file is terminated with a semicolon character, LIB
    uses the default values for the remaining filenames. When the library_
    file parameter is followed by a semicolon or a semicolon is entered at
    the Operations: prompt, LIB takes no action except to verify that the
    contents of the specified file are consistent and usable.

    The response_file parameter allows the automation of complex LIB
    sessions involving many files. A response file contains ASCII text
    that corresponds line for line to the responses that are entered in a
    normal interactive LIB session, in the form

    library_file [/P:n]
    [Y]
    [operations]
    [list_file]
    [new_library_file] [;]

    The response file name must be preceded in the command line by the at
    symbol (@) and can also be preceded by a path and/or drive letter. If
    library_file is a new file, the letter Y  must appear by itself on
    the second line of the response file to approve the creation of a
    library file. The last line of the response file must end with a
    semicolon or a carriage return. (LIB ignores any lines following a
    semicolon.) If all the parameters required by LIB are not present in
    the response file or the response file does not end with a semicolon,
    LIB prompts the user for the missing information.

Return Codes

    0  No error; LIB operation was successful.
    1  An error that terminated execution of the LIB utility was
        encountered.

Examples

    To create a library file named MYLIB.LIB and insert the object files
    VIDEO.OBJ, COMM.OBJ, and DOSINT.OBJ, type

    C>LIB MYLIB +VIDEO +COMM +DOSINT;  <Enter>

    To print a listing of the object modules in the library file
    MYLIB.LIB, type

    C>LIB MYLIB,PRN  <Enter>

    If the LIB command is entered without parameters, the user is prompted
    for the necessary information. For example, if the user wanted to add
    the module VIDEO.OBJ to the library file SLIBC.LIB, produce a
    reference listing in the file SLIBC.LST, and produce a new output
    library file named SLIBC2.LIB, the following dialogue would take
    place:

    C>LIB  <Enter>

    Microsoft (R) Library Manager  Version 3.06
    Copyright (C) Microsoft Corp 1983, 1984, 1985, 1986. All rights reserved

    Library name: SLIBC  <Enter>
    Operations: +VIDEO  <Enter>
    List file: SLIBC.LST  <Enter>
    Output library: SLIBC2  <Enter>

Messages

    filename: cannot access file.
    LIB is unable to access an object module specified in a response file,
    in the command line, or at the Operations: prompt.

    filename: cannot create extract file
    The object module cannot be copied or moved from the library file into
    a separate disk file called filename because the root directory or
    disk is full or because filename already exists and is read-only.

    filename: cannot create listing
    The list file specified in the response file, in the command line, or
    at the List file: prompt cannot be created because the root directory
    or disk is full or because filename already exists and is read-only.

    filename: invalid format (xxxx); file ignored.
    The hexadecimal signature byte or word xxxx of the specified file was
    not one of the following recognized types: Microsoft library, Intel
    library, Microsoft object, or XENIX archive.

    filename: invalid library header.
    The input library file either is not a library file or is damaged.

    filename: invalid library header; file ignored.
    The input library file is in the wrong format.

    modulename: invalid object module near location
    The specified object module has an invalid format near the hexadecimal
    offset indicated.

    modulename: module not in library; ignored
    The object module specified in the response file, in the command line,
    or at the Operations: prompt is not in the specified input library
    file.

    modulename: module redefinition ignored
    An object module was specified to be added to a library file but an
    object module with the same name was already in the library file, or
    the same object module was specified twice in an add operation in the
    command line.

    number: page size too small; ignored
    The size specified with a /P:n switch must be a power of 2 between 16
    and 32768 bytes, inclusive.

    symbol (modulename): symbol redefinition ignored
    The specified symbol was defined in more than one module. Only the
    first definition of a symbol is accepted. All redefinitions are
    ignored.

    cannot create new library
    The root directory is full, or a library file with the same name
    already exists and is read-only.

    cannot open response file
    The specified response file cannot be found or does not exist.

    cannot rename old library
    The old library file cannot be renamed with a .BAK extension because
    such a file already exists and is read-only.

    cannot reopen library
    The old library file could not be reopened after it was renamed with
    the .BAK extension. This error usually indicates damage to the
    operating system or to the disk directory structure.

    comma or new line missing
    A comma or carriage return was expected in the command line but was
    not found.

    Do not change diskette in drive X:
    LIB may have placed important temporary files on the specified disk.
    Do not remove the disk until the LIB operation is complete or these
    files may be lost.

    error writing to cross-reference file
    The disk or root directory is full.

    error writing to new library
    The new library file cannot be created because the disk is full.

    free: not allocated
    This is a serious problem. Note the circumstances of the failure and
    notify Microsoft Corporation.

    insufficient memory
    Not enough memory is available in the transient program area for LIB
    to successfully perform the requested operations.

    internal failure
    This is a serious problem. Note the circumstances of the failure and
    notify Microsoft Corporation.

    Library does not exist. Create?
    The specified library_file does not exist on disk. Respond with Y to
    create the library file; respond with N to terminate the LIB
    utility.

    mark: not allocated
    This is a serious problem. Note the circumstances of the failure and
    notify Microsoft Corporation.

    option unknown
    The command line included a switch other than /P:n.

    output-library specification ignored
    An output library file was specified in addition to a new library
    file. This is only a warning. The output library file specification
    will be disregarded.

    page size too small
    The page size of an input library file was less than 16 bytes,
    indicating a damaged or otherwise invalid .LIB file. See LIB message
    number: page size too small; ignored.

    syntax error
    The command line included an invalid parameter or switch.

    syntax error: illegal file specification
    A command operator (such as *, -, or +) was given without an object
    module name.

    syntax error: illegal input
    The command line included an invalid parameter or switch.

    syntax error: option name missing
    The command line included a forward slash (/) that was not followed by
    P:n.

    syntax error: option value missing
    The /P switch was not followed by the page size value in bytes.

    terminator missing
    Either a control character (such as Control-Z) was specified at the
    Output library: prompt or the response file line that corresponds to
    LIB's Output library: prompt was not terminated by a carriage return
    or semicolon.

    too many symbols
    The maximum number of public symbols allowed in a library file has
    been exceeded. The limit for all object modules (combined) is
    4609.

    unexpected end-of-file on command input
    The response file did not include all the necessary LIB parameters.

    write to extract file failed
    The destination disk has insufficient space for the complete object
    module, or the root directory is full.

    write to library file failed
    The destination disk has insufficient space to create the new library
    file, or the root directory is full.



LINK
Create .EXE File


Purpose

    Combines relocatable object modules into an executable (.EXE) file.
    The Microsoft Object Linker (LINK) is supplied with the Microsoft
    Macro Assembler (MASM), C Compiler, Pascal Compiler, and FORTRAN
    Compiler. This documentation describes LINK version 3.50.

Syntax

    LINK

    or

    LINK obj_file[+obj_file...][,[exe_file]][,[map_file]][,[library
    [+library...]]] [options] [;]

    or

    LINK @response_file

    where:

    obj_file        is the name of a file containing a relocatable object
                    module produced by MASM or by a high-level-language
                    compiler (default extension = .OBJ).

    exe_file        is the name of the executable file to be produced by
                    LINK (default extension = .EXE).

    map_file        is the name of the file or character device to
                    receive a listing of the names, load addresses, and
                    lengths of the segments in exe_file (default = NUL
                    device; default extension = .MAP).

    library         is the name of an object module library to be
                    searched to resolve external references in the
                    object file(s) (default extension = .LIB).

    response_file   is the name of a text file containing LINK parameters
                    in the order in which they are supplied during an
                    interactive LINK session.

    options         specifies one or more of the following switches.
                    Switches can be either uppercase or lowercase.

                    /CP:n       (/CPARMAXALLOC:n) Sets the maximum number
                                of extra memory paragraphs required by
                                exe_file (default = 65535).

                    /DS         (/DSALLOCATE) Loads the data in DGROUP at
                                the high end of the data segment.

                    /DO         (/DOSSEG) Arranges segments according to
                                the Microsoft language segment-ordering
                                convention.

                    /E          (/EXEPACK) Compresses repetitive sequences
                                of bytes and optimizes exe_file's
                                relocation table.

                    /HI         (/HIGH) Causes exe_file to be loaded as
                                high as possible in memory when exe_file
                                is executed.

                    /HE         (/HELP) Lists LINK options on the screen.
                                No other switches or filenames should be
                                used with this switch.

                    /LI         (/LINENUMBERS) Copies line-number
                                information (if available) from obj_file
                                to map_file. If a map file was not
                                specified, this switch creates one.

                    /M          (/MAP) Copies a list of all public symbols
                                declared in obj_file to map_file. If a
                                map file was not specified, this switch
                                creates one.

                    /NOD        (/NODEFAULTLIBRARYSEARCH) Causes LINK to
                                ignore any library names inserted in the
                                object file by the language compiler.

                    /NOG        (/NOGROUPASSOCIATION) Causes LINK to
                                ignore GROUP associations when assigning
                                addresses.

                    /NOI        (/NOIGNORECASE) Causes LINK to be case
                                sensitive when resolving external names.

                    /O:n        (/OVERLAYINTERRUPT:n) Overrides the
                                interrupt number used by the overlay
                                manager (0-255, default = 63, or 3FH).
                                This switch should be used only when
                                linking with a run-time module from a
                                language compiler that supports overlays.

                    /P          (/PAUSE) Causes LINK to pause and prompt
                                the user to change disks before writing
                                the exe_file.

                    /SE:n       (/SEGMENTS:n) Sets the maximum number of
                                segments that can be processed (1-1024,
                                default = 128).

                    /ST:n       (/STACK:n) Sets the size of the exe_file's
                                stack segment to n bytes (1-65535).

Description

    LINK combines relocatable object modules into an executable file in
    the .EXE format. LINK can be used with object files produced by any
    high-level-language compiler or assembler that supports the Microsoft
    object module format. See PROGRAMMING IN THE MS-DOS ENVIRONMENT:
    PROGRAMMING TOOLS: Object Modules; The Microsoft Object Linker.

    The obj_file parameter, which is required, specifies one or more
    files containing relocatable object modules. If multiple object files
    are linked, their names should be separated by a plus operator (+) or
    a space. If an extension is not specified for an object file, LINK
    supplies the extension .OBJ. Some high-level-language compilers
    support partitioning of the executable program into a root segment and
    one or more overlay segments and include a special overlay manager in
    their libraries; when these compilers are used, the object modules
    that compose each overlay segment should be surrounded with
    parentheses in the LINK command line.

    The exe_file parameter specifies the name of the executable file that
    is created by LINK. The default is the same filename as the first
    object file, but with the extension .EXE.

    The map_file parameter designates the file or character device to
    receive LINK's listing of the name, load address, and length of each
    of exe_file's segments. The map file also includes the names and load
    addresses of any groups in the program, the program entry point, and,
    if the /M switch is used, all public symbols and their addresses. If
    the /LI switch is used and if line numbers were inserted into obj_file
    by the compiler, the starting address of each obj_file program line
    is also copied to map_file. The default extension for a map file is
    .MAP. If the /M or /LI switch is used, a map file is created using the
    name of the specified .EXE file even if map_file is not specified. If
    neither the /M nor the /LI switch is used and map_file is not
    specified, no listing is created.

    The library parameter specifies the object module library or
    libraries that will be searched to resolve external references after
    all the object files are processed. The default extension for library
    files is .LIB. Multiple library names should be separated by plus
    operators (+) or spaces. A maximum of 16 search paths can be specified
    in the LINK command line. If a library name is preceded by a drive
    and/or path, LINK searches only the specified location. If no drive or
    path precedes a library name, LINK searches for library files in the
    following order:

    1.  Current drive and directory

    2.  Any other library search paths specified in the command line, in
        the order they were entered

    3.  Directories specified in the LIB= environment variable, if one
        exists

    In the following example, LINK searches only the \ALTLIB directory on
    drive A to find the library MATH.LIB. To find the library COMMON.LIB,
    LINK searches the current directory on the current drive, then the
    current directory on drive B, then directory \LIB on drive D, and
    finally, any directories named in the LIB environment variable.

    C>LINK TEST,,TEST,A:\ALTLIB\MATH.LIB+COMMON+B:+D:\LIB\  <Enter>

    If default libraries are specified within the object files through
    special records inserted by certain high-level-language compilers,
    those libraries will be searched after the libraries named in the
    command line or response file.

    If the LINK command is entered without parameters, LINK prompts the
    user for each filename needed. The default response for each prompt
    (except the obj_file prompt) is displayed in square brackets and can
    be selected by pressing the Enter key. If there are too many obj_file
    or library names to fit on one line, the line can be terminated by
    entering a plus operator (+) and pressing the Enter key; LINK then
    repeats the prompt. If the user ends any response with a semicolon
    character (;), LINK uses the default values for the remaining fields.

    When the command line contains filenames and switches, commas must be
    used to separate the obj_file, exe_file, map_file, and library
    parameters. If a filename is not supplied, a comma must be used to
    mark its place. If the user places a semicolon after any parameter in
    the command line, LINK terminates the command line at the semicolon
    and uses the default values for any remaining parameters.

    The user can automate complex LINK sessions involving multiple files
    by creating a response file. The response_file parameter must be the
    name of an ASCII file that corresponds line for line to the responses
    that are entered in a normal interactive LINK session. The last line
    of the response file must end with a semicolon character (;) or a
    carriage return. If all parameters required by LINK are not present in
    the response file and the response file does not end with a semicolon
    or carriage return, LINK prompts the user for the missing information.

    LINK supports many options that can be invoked by including a switch
    in the command line, as part of the response to a LINK prompt, or in a
    response file. To simplify this description, these switches are
    grouped according to their functions.

    The /E, /HE, /NOD, /NOI, /P, and /SE:n switches affect LINK's general
    operation. The /E switch compresses repetitive sequences of bytes in
    exe_file and optimizes certain parts of the relocation table in
    exe_file's header. The /E switch functions exactly like the
    EXEPACK utility.

    Note: The /E switch does not always save a significant amount of disk
    space and may even increase file size when used with small programs
    that have few load-time relocations or repeated characters. The
    Microsoft Symbolic Debugger (SYMDEB) utility cannot be used with
    packed files.

    The /HE switch displays the available options on the screen. No other
    switches or filenames should be specified if the /HE switch is used.
    The /NOD switch causes LINK to ignore any default libraries that have
    been added to the object modules by the high-level-language compiler
    that produced the modules, thus restricting searches to those
    libraries specified in the command line or response file. The /NOI
    switch causes LINK to be case sensitive when resolving external
    references to symbols between object modules. The /NOI switch is
    typically used with object files created by high-level-language
    compilers that differentiate between uppercase and lowercase
    letters.

    The /P switch causes LINK to pause and prompt the user before writing
    exe_file to disk, thus allowing the user to exchange the disk used
    during the linking operation for another that has more space
    available. The /SE:n switch controls the number of program segments
    processed by LINK. The n must be a decimal, octal, or hexadecimal
    number from 1 through 1024, inclusive (default = 128). Octal numbers
    must have a leading zero; hexadecimal numbers must begin with 0x.

    The /M and /LI switches affect the production and contents of the
    optional map file. The /M switch creates a map file with the same name
    as exe_file or, if exe_file is not specified, with the same name as
    the first object file and the extension .MAP. The resulting map file
    includes a list of all public symbols and their addresses. The /LI
    switch also creates a map file and includes line-number information if
    available in the object file. (MASM and some high-level-language
    compilers do not insert line-number information into object files.)

    The /D, /DO, /NOG, and /O:n switches affect the structure of the code
    in exe_file. Use of the /D switch places the data in DGROUP at the top
    (highest address) of the memory segment pointed to by the DS register,
    rather than at the bottom (the default). The /DO switch arranges the
    program segments according to a convention expected by all Microsoft
    language compilers: All segments with the class name CODE are placed
    first in the executable file; any other segments that do not belong to
    DGROUP are placed immediately after the CODE segments; all segments
    belonging to DGROUP are placed at the end of the file. The /NOG switch
    causes LINK to ignore group associations specified in the object
    modules when assigning addresses to data and code items; that is,
    segments that would ordinarily have been collected into the same
    physical memory segment because of their association within a GROUP
    are decoupled. The /NOG switch provides compatibility with LINK
    versions 2.02 and earlier and with early versions of Microsoft
    language compilers. The /O:n switch controls the interrupt number
    used by the resident overlay manager if the linked program includes
    overlays. The number n can be any decimal, octal, or hexadecimal
    number in the range 0 through 255 (default = 63, or 3FH). Octal
    numbers must have a leading zero; hexadecimal numbers must begin with
    0x.

    Note: MASM and many high-level-language compilers do not include
    overlay managers in their libraries. Users should check their compiler
    documentation to determine if the /O:n switch can be used.

    Warning: Interrupt numbers that conflict with the software interrupts
    used to obtain MS-DOS or ROM BIOS services or with hardware interrupts
    assigned to peripheral device controllers should not be used in the
    /O:n switch.

    The /C:n, /H, and /ST:n switches control the information in exe_
    file's header that affects the behavior of the MS-DOS system loader
    when the file is read from the disk into RAM for execution. The /C:n
    switch sets the maximum number of 16-byte paragraphs of memory to be
    made available to the program when it is loaded into memory, in
    addition to the memory required to hold the program's code, data, and
    stacks; the default is 65535, which causes the program to be allocated
    all available memory. The /H switch causes the program to be loaded as
    high as possible in the transient program area (free memory), rather
    than as low as possible (the default). The /ST:n switch sets the
    stack size (in bytes) to be allocated for the program when it is
    loaded and overrides any stack segment size declarations in the
    original source code. The number n can be any decimal, octal, or
    hexadecimal number from 1 through 65535; however n must be large
    enough to accommodate any initialized data in the stack segment. Octal
    numbers must have a leading zero; hexadecimal numbers must begin with
    0x. If the /ST:n switch is not used, LINK calculates a program's
    stack size, basing the size on the size of any stack segments given in
    the object files. The /C:n and /ST:n values in the exe_file header
    can be altered after linking by using the EXEMOD utility.

    If LINK is unable to hold in RAM all the data it is processing, it
    creates a temporary disk file named VM.TMP (Virtual Memory) in the
    current directory of the default disk drive. If a floppy disk is in
    the default drive, LINK issues a warning message to prevent the user
    from changing disks until the LINK session is completed. After LINK
    finishes processing, it deletes the temporary file.

    Warning: Any file named VM.TMP that is already on the disk will be
    destroyed if LINK creates the temporary disk file.

Return Codes

    0    No errors or unresolved references were encountered during
            creation of exe_file.
    1    A miscellaneous LINK error occurred that was not covered by
            the other return codes.
    16    A data record was too large to process.
    32    No object files were specified in the command line or response
            file.
    33    The map file could not be created.
    66    A COMMON area was declared that is larger than 65535 (one
            segment).
    96    Too many libraries were specified.
    144    An invalid object module (obj_file) was detected.
    145    Too many TYPDEFs were found in the specified object modules.
    146    Too many group, segment, or class names were found in one
            object module.
    147    Too many segments were found in all the object modules
            combined, or too many segments were found in one
            object module.
    148    Too many overlays were specified.
    149    The size of a segment exceeded 65535.
    150    Too many groups or GRPDEFs were found in one object module.
    151    Too many external symbols were found in one object module.
    177    The size of a group exceeded 65535.

Examples

    The simplest use of LINK is to process a single object file to produce
    an executable file, using all the default values. For example, to
    process the file SHELL.OBJ, create an executable file named SHELL.EXE,
    and search only the default libraries, type

    C>LINK SHELL;  <Enter>

    The semicolon after the filename causes LINK to use the default values
    for all other parameters.

    To link three object files named SHELL.OBJ, VIDEO.OBJ, and DOSINT.OBJ
    into an executable file named SHELL.EXE and search the library
    DEVLIB.LIB on drive B before searching any default libraries,
    type

    C>LINK SHELL+VIDEO+DOSINT,,,B:DEVLIB  <Enter>

    If the LINK command is entered without parameters, LINK prompts the
    user for the necessary information. For example, the following
    interactive session links the file MENUMGR.OBJ into the executable
    file MENUMGR.EXE, creates a map file named MENUMGR.MAP, and searches
    the math floating-point emulator library EM.LIB before any default
    libraries:

    C>LINK  <Enter>

    Microsoft (R) 8086 Object Linker  Version 3.05
    Copyright (C) Microsoft Corp 1983,1984,1985.  All rights reserved.

    Object Modules [.OBJ]: MENUMGR  <Enter>
    Run File [MENUMGR.EXE]:  <Enter>
    List File [NUL.MAP]:  MENUMGR  <Enter>
    Libraries [.LIB]:  EM  <Enter>

Messages

    filename is not a valid library
    The file specified as an object module library either is corrupt or is
    not a library in the format created by the Microsoft LIB
    utility.

    About to generate .EXE file
    Change diskette in drive X and press <ENTER>
    The /P switch was used in the command line. LINK is prompting the user
    to change disks before LINK creates the file containing the executable
    program.

    Ambiguous switch error: "option"
    A valid switch was not entered after a forward slash (/) in the
    command line.

    Array element size mismatch
    A FAR communal array was declared with two or more different array-
    element sizes (for example, once as an array of characters and once as
    an array of real numbers). This error occurs only with programs
    produced by the Microsoft C Compiler or other compilers that support
    FAR communal arrays; it does not occur with object files produced by
    MASM.

    Attempt to access data outside segment bounds
    A data record in an object module specified data extending beyond the
    end of a segment. This is a translator error. Note which compiler or
    assembler produced the invalid object module and notify Microsoft
    Corporation.

    Attempt to put segment name in more than one group in file filename
    A segment was declared to be a member of two groups. Correct the
    source code and recreate the object modules.

    Bad value for cparMaxAlloc
    The value specified using the /C:n option is not in the range 1
    through 65535.

    Cannot create temporary file
    The destination disk has insufficient space for the temporary file, or
    the root directory is full.

    Cannot find file filename
    Change diskette and press <ENTER>
    The specified object file cannot be found in the current drive.

    Cannot find library: filename
    Enter new file spec:
    The specified library file cannot be found or does not exist. Enter
    the correct drive letter, check the spelling of the filename and path,
    or make sure that the LIB environment variable has been set up
    properly.

    Cannot nest response files
    A response file was named within a response file. Revise the response
    file to eliminate the nested file.

    Cannot open list file
    The destination disk has insufficient space for the listing, or the
    root directory is full.

    Cannot open response file: filename
    LINK cannot find the specified response file.

    Cannot open run file
    The destination disk has insufficient space for the .EXE file, or the
    root directory is full.

    Cannot open temporary file
    The destination disk has insufficient space for the temporary file, or
    the root directory is full.

    Cannot reopen list file
    The original disk was not replaced when requested. Restart LINK.

    Common area longer than 65536 bytes
    The program has more than 64 KB of communal variables. This error
    occurs only with programs produced by the Microsoft C Compiler or
    other compilers that support communal variables.

    Data record too large
    An LEDATA record (in an object module) contains more than 1024 bytes
    of data. This is a symptom of an error in the compiler used to
    generate the object module. Document the circumstances and contact
    Microsoft Corporation.

    Dup record too large
    An LIDATA record (in an object module) contains more than 512 bytes of
    data. This error may be caused by a complex structure definition or by
    a series of deeply nested DUP operators.

    File not suitable for /EXEPACK, relink without
    The file linked with the /E switch would have been smaller if it had
    not been compressed. Relink without the /E switch.

    Fixup overflow near number in segment name in filename offset number
    A group is larger than 64 KB, the original source file contains an
    intersegment short jump or intersegment short call, the name of a data
    item conflicts with that of a library subroutine, or an EXTRN
    declaration is placed inside the wrong segment.

    Incorrect DOS version, use DOS 2.0 or later
    LINK uses the extended file management calls to provide path support
    and, thus, does not work with versions of MS-DOS earlier than 2.0.

    Insufficient stack space
    Not enough memory is available to run LINK.

    Interrupt number exceeds 255
    The number specified in the /O:n switch is not in the range 0 through
    255.

    Invalid numeric switch specification
    An incorrect value was entered with one of the LINK options.

    Invalid object module
    One of the object modules is invalid. Recompile the source file. If
    the error persists after recompiling, document the circumstances and
    contact Microsoft Corporation.

    NEAR/HUGE conflict
    Conflicting NEAR and HUGE definitions were given for a communal
    variable. This error occurs only with programs produced by the
    Microsoft C Compiler or other compilers that support communal
    variables.

    Nested left parentheses
    An opening (left) parenthesis is needed on the left side of an overlay
    module.

    Nested right parentheses
    A closing (right) parenthesis is needed on the right side of an
    overlay module.

    No object modules specified
    No object file names were specified in the command line or response
    file.

    Object not found
    One of the object files specified in the command line was not
    found.

    Out of space on list file
    The destination disk has insufficient space for the listing.

    Out of space on run file
    The destination disk has insufficient space for the .EXE file.

    Out of space on scratch file
    The disk in the default drive has insufficient space for temporary
    files.

    Overlay manager symbol already defined: name
    A symbol name was defined that conflicts with one of the special
    overlay manager names. Use another symbol name.

    Please replace original diskette
    in drive X and press <ENTER>
    The /P switch was specified in the command line and the disk to
    receive the .EXE file produced by LINK has already been inserted. This
    message indicates that the .EXE file was successfully created and that
    the original disk should again be placed in the drive.

    Relocation table overflow
    More than 32768 long calls, long jumps, or other long pointers were
    found in the program. The program may need to be restructured to
    reduce the number of FAR references. (Pascal and FORTRAN users should
    try turning off the debugging option before restructuring the
    program.)

    Response line too long
    A line in a response file had more than 127 characters.

    Segment limit set too high
    The number specified in the /SE:n switch was not in the range 1
    through 1024.

    Segment limit too high
    Not enough memory is available for LINK to allocate tables to describe
    the number of segments requested (default = 128 or the number
    specified in the /SE:n switch). Use the /SE:n switch to specify a
    smaller number of segments, or alter the system configuration to
    increase the amount of free memory.

    Segment size exceeds 64K
    The program is a small-model program with more than 64 KB of code or
    data, a compact-model program with more than 64 KB of code, or a
    medium-model program with more than 64 KB of data. Selection of a
    different model or alteration of the program code may be required to
    successfully complete the LINK process.

    Stack size exceeds 65536 bytes
    The size specified for the stack in the /ST:n switch was too large,
    or the combined length of multiple declared stack segments exceeded
    64 KB.

    Symbol already defined: "symbol"
    One of the special overlay symbols required for overlay support was
    previously defined.

    Symbol defined more than once: "symbol" in file
    A symbol has been defined more than once in the object module. Remove
    the extra symbol definition.

    Symbol table overflow
    The program has more than 256 KB of symbolic information (publics,
    externals, segments, groups, classes, files, and so on). Eliminate as
    many public symbols as possible, combine modules and/or segments, and
    recreate the object files.

    Terminated by user
    Ctrl-C or Ctrl-Break was pressed, causing the LINK session to be
    terminated prematurely.

    Too many external symbols in one module
    An object module contains more than the limit of 1023 external
    symbols.

    Too many group-, segment-, and class-names in one module
    One of the object modules for the program contains too many group,
    segment, and class names. The source file for the object module may
    need to be divided or restructured.

    Too many groups
    The program defines more than nine groups (including DGROUP). Groups
    must be combined or eliminated.

    Too many GRPDEFs in one module
    LINK encountered more than nine group definitions (GRPDEFs) in a
    single object module. Reduce the number of GRPDEFs or split the object
    module.

    Too many libraries
    More than 16 libraries were specified. Combine libraries or use object
    modules that require fewer libraries.

    Too many overlays
    The program defines more than 63 overlays. Reduce the number of
    overlays.

    Too many segments
    The program has more than the maximum number of segments as specified
    by the default of 128 or with the /SE:n switch. Use the /SE:n switch
    to specify a greater number of segments.

    Too many segments in one module
    An object module has more than 255 segments. Split the module or
    combine segments.

    Too many TYPDEFs
    An object module contains too many TYPDEF records (these records
    describe communal variables). This error occurs only with programs
    produced with the Microsoft C Compiler or other compilers that support
    communal variables.

    Unexpected end-of-file on library
    This message may indicate that the disk containing the library in use
    was removed prematurely.

    Unexpected end-of-file on scratch file
    The disk containing VM.TMP was removed.

    Unmatched left parenthesis
    A syntax error was detected in the specification of an overlay
    structure. Refer to the language compiler manual for instructions on
    specifying overlays to LINK.

    Unmatched right parenthesis
    A syntax error was detected in the specification of an overlay
    structure. Refer to the language compiler manual for instructions on
    specifying overlays to LINK.

    Unrecognized switch error: "option"
    An unrecognized character was entered after a forward slash (/) in the
    command line.

    Unresolved COMDEF; Microsoft internal error
    This is a serious problem. Note the circumstances of the failure and
    contact Microsoft Corporation.

    Unresolved externals: list
    A symbol was declared external (EXTRN) in one object module but was
    not declared PUBLIC in the object module in which it was defined, or a
    necessary library specification was omitted from the command line or
    response file.

    VM.TMP is an illegal file name
    and has been ignored
    VM.TMP was specified as an object file name. If an object file named
    VM.TMP exists, rename it.

    Warning: load-high disables exepack
    The /H and /E switches cannot be used at the same time.

    Warning: no stack segment
    The program contains no segment with the STACK combine type. This
    message can be ignored if there is a specific reason for not defining
    a stack (for example, if the .EXE file will subsequently be converted
    to a .COM file) or for defining one without the STACK combine
    type.

    WARNING: Segment longer than reliable size
    Although code segments can be as long as 65536 bytes, code segments
    longer than 65500 bytes can be unreliable on the Intel 80286
    microprocessor. Reduce all code segments to 65500 bytes or less.

    Warning: too many public symbols
    The /M switch was used to request a sorted listing of public symbols
    in the map file, but there are too many symbols to sort. LINK will
    produce an unsorted listing instead.



MAKE
Maintain Programs


Purpose

    Interprets a text file of commands to compare dates of files and carry
    out other operations on the basis of the comparison. MAKE is
    customarily used to update the executable version of a program after a
    change to one or more of its source files. The MAKE utility is
    supplied with the Microsoft Macro Assembler (MASM), C Compiler, and
    FORTRAN Compiler. This documentation describes MAKE version 4.05.

Syntax

    MAKE [/D] [/I] [/N] [/S] [name=value ...] filename

    where:

    filename         is an ASCII text file that contains MAKE dependency
                    statements, commands, macro definitions, and
                    inference rules.

    name=value       declares a MAKE macro, associating a specific value
                    with the dummy parameter name.

    /D               displays the last modification date of each file as
                    it is scanned.

    /I               causes MAKE to ignore exit codes returned by programs
                    called by filename.

    /N               displays but does not execute the commands in
                    filename.

    /S               selects "silent" mode (commands are not displayed as
                    they are executed).

    Note: Switches can be either uppercase or lowercase and can be
    preceded by a dash (-) instead of a forward slash (/). Versions of
    MAKE earlier than 4.0 have no switches.

Description

    The MAKE utility allows maintenance of complex programs to be
    automated. Its basic operation is to compare the dates of files and to
    carry out, or not carry out, an associated list of commands on the
    basis of the comparison.

    The filename parameter specifies an ASCII text file often referred to
    as a make file. By convention, filename is the same as the name of
    the executable program being maintained, but without an extension. A
    make file can contain the following types of entries:

    ■  Dependency statements
    ■  Commands
    ■  Macro definitions
    ■  Inference rules
    ■  Comments

    The basic form of a make file is a dependency statement followed by
    one or more valid MS-DOS command lines:

    targetfile: dependentfile1 [dependentfile2...]
            command1
            [command2]
            ...

    where targetfile designates the file that may need updating,
    dependentfile is a source file or files on which targetfile depends,
    and command1, command2, and so forth are any valid MS-DOS internal
    commands or external programs. These commands or programs are executed
    only if the date and time stamps of any dependent file are more recent
    than those of the target file or if the target file does not exist.
    Only one target file can be specified. Any number of dependent files
    can be included; each dependent filename must be separated from the
    next by at least one space. If too many dependent files are included
    to fit on a single line, the line can be terminated with a backslash
    character (\) and the list continued on the next line.

    Any number of MS-DOS command lines can follow a dependency statement.
    The last command line should be followed by a blank line to set it off
    from the next MAKE entry. It is recommended that each command line
    include a leading space or tab character for compatibility with future
    versions of MAKE and existing versions of XENIX MAKE.

    A macro definition takes the form

    name=value

    where both name and value are any string. Whenever name is referenced
    in the make file in the form $(name), name is replaced by the string
    value before the statement that contains it is evaluated or executed.
    Macro definitions can be nested, although very complex macro
    definitions can result in the premature termination of the MAKE
    process because of lack of memory. If name is not defined in the file
    but is defined in the system environment block by a previous SET
    command, $(name) is replaced by the string following the equal sign
    (=) in the environment block. If the command line contains a parameter
    of the form name=value, the command line overrides any definition of
    name in the make file or in the environment block. Thus, the
    precedence for macro definitions with the same name is

    1.  Command line
    2.  Make file
    3.  Environment block

    MAKE contains several special macros that make it more convenient to
    form commands:

╓┌────────────────┌──────────────────────────────────────────────────────────╖
    Macro       Action
    ─────────────────────────────────────────────────────────────────────
    $*          Substitutes as the base portion of targetfile (the
                filename without the extension).

    $@          Substitutes as the complete targetfile name.

    $**         Substitutes as the complete dependentfile list.

    An inference rule specifies a series of commands to be carried out for
    a matching dependency statement that is not followed by its own list
    of commands. Inference rules allow a set of commands to be applied to
    more than one targetfile: dependentfile description, eliminating
    repetition of the same set of commands for several descriptions. An
    inference rule takes the form

    .dependentextension.targetextension:
        command1
        [command2]
        ...

    Whenever MAKE finds a dependency statement not followed by any
    commands, the utility first searches the make file for an inference
    rule. If MAKE doesn't find an inference rule in the make file, the
    utility then searches the current drive and directory (or any
    directories specified with the MS-DOS PATH command) for the tools
    initialization file (TOOLS.INI) and searches the [make] section of
    TOOLS.INI for an inference rule that matches the extensions of the
    target file and dependent files in the dependency statement.

    A make file can contain any number of comment lines. If a comment is
    placed where MAKE expects to find a command, the comment must be on a
    separate line and must have the pound character (#) as the first
    character of the line. Elsewhere, a pound character and following
    comment text can be placed either on a line alone or after the last
    dependent file or command listed on a line. Characters appearing on a
    line after the pound character are ignored during execution.

    The /D, /N, and /S switches affect MAKE's output to the display while
    MAKE is executing. The /D switch causes the last modification date of
    each file to be displayed as the file is scanned. The /N switch causes
    the commands in the make file to be expanded and displayed, but not
    executed; this is useful for determining the result of a specific MAKE
    process without first examining the file dates and without recompiling
    or relinking files. The /S switch selects "silent" mode, in which
    commands are not displayed as they are executed.

    The /I switch causes MAKE to ignore error codes returned by the
    compilers, assemblers, linkers, or other programs called by the make
    file. When the /I switch is used, the MAKE process proceeds to
    completion regardless of errors instead of terminating immediately as
    it ordinarily would, but the resulting files may not be
    executable.

Return Codes

    0  No error; the MAKE process was successful.
    1  Processing was terminated because of a fatal error by MAKE or by
        one of the programs called by MAKE.

Example

    Assume that the file SHELL contains the following MAKE dependency
    statements and commands:

    video.obj: video.asm
            masm video;

    shell.obj: shell.c
            msc shell;

    shell.exe: shell.obj video.obj
            link /map shell+video,shell,shell,slibc2

    The SHELL file asserts that the executable program SHELL.EXE is
    composed of the files SHELL.OBJ and VIDEO.OBJ, which are in turn
    compiled or assembled from the source files SHELL.C and VIDEO.ASM. To
    update the file SHELL.EXE if either of the source files for its
    constituent modules has been changed, type

    C>MAKE SHELL  <Enter>

Messages

    fatal error U1001: macro definition larger than 512
    A single macro was defined to have a value string longer than the 512-
    byte maximum. Rewrite the make file to use two or more short lines
    instead of one long line.

    fatal error U1002: infinitely recursive macro
    The macros defined in the make file form a circular chain.

    fatal error U1003: out of memory
    The make file cannot be processed because insufficent memory is
    available in the transient program area. Split the make file into two
    make files or reconfigure the system to increase available memory.

    fatal error U1004: syntax error : macro name missing
    A macro name is missing from the left side of the equal sign (=).

    fatal error U1005: syntax error : colon missing
    A line that should be a dependency statement lacks the colon that
    separates a target file from its dependent files. MAKE expects any
    line that follows a blank line to be a dependency statement.

    fatal error U1006: targetname : macro expansion larger than 512
    A single macro expansion, plus the length of any string to which it
    may be concatenated, is longer than 512 bytes. Rewrite the make file
    to use two or more short lines instead of one long line.

    fatal error U1007: multiple sources
    An inference rule has been defined more than once in the make
    file.

    fatal error U1008: filename : cannot find file
    The specified file does not exist.

    fatal error U1009: command : argument list too long
    A command line in the make file is longer than 128 characters (the
    maximum MS-DOS allows).

    fatal error U1010: filename : permission denied
    The specified file is read-only.

    fatal error U1011: not enough memory
    Memory is insufficient in the transient program area to execute a
    program listed in the make file. Reconfigure the system to increase
    available memory, if necessary.

    fatal error U1012: filename : unknown error
    This is a serious problem. Note the circumstances of the failure and
    notify Microsoft Corporation.

    fatal error U1013: command : error returncode
    One of the programs or commands called by MAKE was not able to execute
    correctly. MAKE terminates and displays the error code from the
    program that failed.

    warning U4000: filename : target does not exist
    The target file does not already exist. The dependency statement is
    evaluated as though the target file exists and has a date earlier than
    that of any of the dependent files.

    warning U4001: dependent filename does not exist;
    target filename not built
    One of the dependent files does not exist or could not be found, so
    MAKE terminated without creating a new target file.

    warning U4013: command : error returncode (ignored)
    One of the programs or commands called by MAKE did not execute
    successfully and has returned the specified return code. Because MAKE
    was run with the /I switch, MAKE ignores the error and continues
    processing the make file.

    warning U4014: usage : make [/n] [/d] [/i] [/s] [name=value ...] file
    An error was detected in the MAKE command line.



MAPSYM
Create Symbol File for SYMDEB


Purpose

    Processes a map file generated by the Microsoft Object Linker (LINK)
    to create a special symbol file for use with SYMDEB, the symbolic
    debugging program. The MAPSYM utility is supplied with the Microsoft
    Macro Assembler (MASM). This documentation describes MAPSYM version
    4.0.

Syntax

    MAPSYM [/L] map_file

    where:

    map_file    is a map file produced by LINK (default extension = .MAP).

    /L          causes information about the symbol file to be
                displayed as it is created.

    Note: The /L switch can be either uppercase or lowercase and can be
    preceded by a dash (-) instead of a forward slash (/).

Description

    LINK combines relocatable object records (produced by MASM or a high-
    level-language compiler) into an executable program, which is stored
    in a specially formatted file with a .EXE extension. LINK can also
    produce an optional map file that contains information about public
    symbols and addresses in the linked program. The map file is an
    ordinary ASCII text file and has a default extension of .MAP.

    To create a map file to use with MAPSYM, the LINK command line should
    include the /MAP switch, which creates the file, and the /LINENUMBERS
    switch, which includes line numbers. See PROGRAMMING UTILITIES:
    LINK.

    The MAPSYM utility processes a map file into a special symbol file
    that can be used by SYMDEB. A drive and pathname can be specified if
    the map file is not in the current directory. If a file extension is
    not specified, .MAP is assumed.

    The symbol file created by MAPSYM is placed in the current directory
    and has the same name as the map file but has the extension .SYM. It
    can contain a maximum of 1024 segments (or as many segments as can fit
    into available memory) and 10,000 symbols per segment. See
    PROGRAMMING UTILITIES: SYMDEB.

    When the /L switch precedes map_file in the command line, MAPSYM
    displays the names of groups defined in the program described by the
    map and symbol files, plus the program's starting address. The /L
    switch does not affect the format of the symbol file that is
    generated.

Return Codes

    0  No error; the MAPSYM process was successful.
    1  Processing was terminated because of a write failure, because the
        map file specified does not exist, or because the symbol file could
        not be created.
    4  Processing was terminated because an unexpected end-of-file mark
        was detected, because too many segments exist in the map file,
        because no public symbols exist in the map file, or because not
        enough memory is available to create the symbol file.

Example

    To convert the file HELLO.MAP, which was produced by assembling and
    linking the file HELLO.ASM, to a symbol file that can be used by
    SYMDEB, type

    C>MAPSYM /L HELLO  <Enter>

    MAPSYM displays the following:

    Microsoft (R) Symbol File Generator  Version 4.00
    Copyright (C) Microsoft Corp 1984, 1985.  All rights reserved.
    Building: HELLO.SYM
    HELLO.MAP
            Program entry point at 0000:0100
    HELLO     0 segment

    The symbol file produced by MAPSYM symbol has the name
    HELLO.SYM.

Messages

    Can't create: <filename>
    The drive specified does not exist, the current disk or directory is
    full, or the output file already exists and is read-only.

    Can't open MAP file: <filename>
    The file named in the command line does not exist.

    DOS 2.0 or later required
    MAPSYM does not work with versions of MS-DOS earlier than 2.0.

    mapsym: out of memory
    System memory is insufficient to process the map file.

    mapsym: segment table (n) exceeded.
    More than 1024 segments have been used in the map file. The number
    displayed is the total number of segments in the map file.

    No public symbols
    Re-link file with the /M switch!
    The map file created by LINK does not include a list of public names.
    The .EXE file must be relinked using the /MAP switch to generate a map
    file that can be used with MAPSYM.

    Unexpected eof reading: <filename>
    The map file contains no symbols, is corrupt, or is otherwise invalid.
    The .EXE file must be relinked and a new map file generated.

    usage: MAPSYM [/l] maplist
    A syntax error was detected in the command line.

    Write fail on: <filename>
    An error occurred during the creation of the output file.



MASM
Microsoft Macro Assembler


Purpose

    Translates an assembly-language source program into a relocatable
    object module. MASM is part of the Microsoft Macro Assembler (MASM)
    retail package. This documentation describes MASM version 4.0.

Syntax

    MASM

    or

    MASM source_file [,[object_file][,[list_file][,[cref_file]]]]
    [options] [;]

    where:

    source_file     is the name of the file containing the assembly-
                    language source code (default extension = .ASM).

    object_file     is the name of the file to receive the assembled
                    object module (default extension = .OBJ).

    list_file       is the name of the file or device to receive the
                    assembly listing (default = NUL). (If destination =
                    file, default extension = .LST.)

    cref_file       is the name of the cross-reference file to receive
                    information for later processing by the CREF utility
                    (default = NUL). (If destination = file, default
                    extension = .CRF.)

    options         is one or more switches from the list below.

                    /A         Writes the program segments in alphabetic
                                order.

                    /Bn        Sets the size of the source-file buffer in
                                kilobytes (1-63, default = 32).

                    /C         Creates a cross-reference (.CRF) file.

                    /D         Adds a first-pass program listing to
                                list_file if a list file was specified
                                (default = second-pass listing only).

                    /Dsymbol   Defines symbol as a null text string.

                    /E         Assembles code for an 8087/80287 emulator.

                    /Ipath     Defines a directory to be searched for
                                include files.

                    /L         Creates a list (.LST) file with line-
                                number information.

                    /ML        Preserves case sensitivity in all symbol
                                names.

                    /MU        Converts all lowercase names to uppercase
                                names.

                    /MX        Preserves lowercase in public and external
                                names only.

                    /N         Suppresses generation of tables of macros,
                                structures, records, groups, segments,
                                and symbols at the end of the list file.

                    /P         Checks for impure code in 80286 protected
                                mode; has no effect unless the .286P
                                directive is included in the source file.

                    /R         Assembles code for an 8087/80287 math
                                coprocessor.

                    /S         Arranges program segments in order of
                                occurrence.

                    /T         Selects terse mode, suppressing all
                                messages generated during assembly except
                                error messages.

                    /V         Selects verbose mode, displaying the
                                number of lines and symbols at the end of
                                assembly.

                    /X         Includes false conditionals in the list
                                file.

                    /Z         Displays source lines with errors during
                                assembly.

    Note: Switches can be either uppercase or lowercase and can be
    preceded by a dash (-) instead of a forward slash (/).

Description

    MASM translates assembly-language source code into relocatable object
    modules. The object modules can then be placed in a library file or
    processed by the Microsoft Object Linker (LINK) to create an
    executable program.

    The source_file parameter is the only required filename. It specifies
    a file containing the assembly-language source code in ASCII text. If
    no extension is specified, MASM uses .ASM. If no source file is
    entered in the command line, MASM prompts for a source file name.

    The object_file parameter specifies the file that will contain the
    assembled relocatable object code. If this parameter is not supplied,
    MASM uses the same filename as source_file but substitutes the
    extension .OBJ.

    The list_file parameter specifies a destination file or device for
    the optional program listing. The listing contains the original source
    code, the assembled machine code, macro definitions and expansions,
    and other useful information, formatted into pages with titles, dates,
    and page numbers. If the destination of the listing is a file, the
    file's default extension is .LST. If the list_file parameter is not
    included in the command line, MASM sends the listing to NUL (that is,
    a listing is not produced).

    The cref_file parameter specifies the name of a cross-reference file
    to receive information to be processed by the CREF utility. If a file
    extension is not specified, MASM uses .CRF. If the cref_file
    parameter is not included in the command line, MASM sends the file to
    NUL (that is, no cross-reference file is generated).

    If the MASM command is entered without parameters, MASM prompts the
    user for each filename. The default response for each prompt (except
    the source file prompt) is displayed in square brackets and can be
    selected by pressing the Enter key.

    After the source file is specified, if MASM encounters a semicolon
    character (;) in the command line or at any prompt, it uses default
    values for the remaining parameters. MASM ignores any parameters
    specified after the semicolon.

    MASM does two passes to translate the assembly-language code in the
    source file into relocatable object code. Any errors detected during
    translation are displayed on standard output and included in the
    program listing (if one is requested). Two types of errors may be
    detected: warning errors and severe errors. If MASM encounters a
    warning error, it still creates the object file, although the
    resulting file may be unusable. If MASM encounters a severe error, it
    does not create the object file. After a file has been successfully
    assembled without errors, the LINK utility can be used to convert the
    resulting object file into an executable program file.

    MASM supports a wide variety of options that can be selected by
    including switches in the command line or by responding to any
    prompt.

    The /A and /S switches determine the order of segments in the
    resulting object module file. The /A switch places the segments into
    the object file in alphabetic order. The /S switch (the default)
    arranges the segments in the same order they occur in the source
    file.

    The /Bn, /Dsymbol, and /Ipath switches have rather general effects on
    the behavior of MASM. The /Bn switch sets the size (in kilobytes) of
    the source file's RAM buffer; the value of n must be between 1 and
    63, inclusive (default = 32). If the RAM buffer is large enough, the
    entire source file can be kept resident in memory, reducing disk
    activity during passes. The /Dsymbol switch defines a null text-
    string symbol from the command line. This symbol can be referenced
    inside the program with the IFDEF directive to control the conditional
    assembly of portions of the program. The /Ipath switch specifies a
    directory that will be searched for files named in assembler INCLUDE
    statements if those statements do not include an explicit directory.
    As many as 10 such search paths can be specified with individual
    /Ipath switches.

    The /E and /R switches affect the generation of code for the
    8087/80287 emulator or 8087/80287 math coprocessor. (Support for the
    80287 is included with MASM versions 3.0 and later.) The /E switch
    generates software interrupts to floating-point-processor emulator
    routines. A subprogram assembled with the /E switch can be linked to
    C, Pascal, and FORTRAN programs and can use the emulator libraries.
    The /R switch produces in-line machine instructions for the math
    coprocessor when floating-point mnemonics are used.

    The /ML, /MU, and /MX switches control MASM's handling of uppercase
    and lowercase names. The /ML switch makes MASM case sensitive; that
    is, it makes MASM differentiate a name in uppercase letters from the
    same name in lowercase letters. (The /ML switch should not be used if
    the source file contains 8087 WAIT instructions and MASM 4.0 is being
    used to translate the file.) The /MU switch (the default) makes MASM
    case insensitive; all lowercase letters are converted to uppercase for
    purposes of assembly. The /MX switch makes MASM case sensitive for
    public and external names only (names defined with PUBLIC or EXTRN
    directives). The /MX switch is often used to process assembly-language
    functions for C programs.

    The /P switch checks for impure code segments that will cause problems
    if the assembled program is run in 80286 protected mode. The switch
    checks by flagging any instruction that will change a memory location
    addressed through the processor's CS register. The /P switch has no
    effect unless the assembly-language source file includes the .286P
    directive.

    The /C, /D, /L, /N,  and /X switches control the contents of the
    program listing and other optional files that are generated as a
    result of assembly. The /C switch causes the creation of a cross-
    reference (.CRF) file and the addition of line numbers to the list
    (.LST) file (if one exists). The /C switch should be included in the
    command line if the cross-reference file will be used later with the
    CREF utility to produce a cross-reference listing. The /D switch
    includes a listing from the first pass as well as a listing from the
    second pass in the list file if a list file was specified (default =
    second-pass listing only). By comparing the two listings, the user can
    isolate an instruction causing a phase error. (A phase error occurs
    when MASM makes assumptions about addresses, values, or data types on
    the first pass that are not valid in the second pass.) The /L switch
    creates a list file with line-number information and gives it the same
    name as the source file, with the extension .LST. The /N switch
    suppresses generation of tables--symbols, segments, groups,
    structures, records, and macros--at the end of a program listing. The
    /X switch includes statements inside false conditional statements in
    the list file, allowing conditionals that do not generate code to be
    displayed. /X has no effect if the .SFCOND or the .LFCOND directive is
    used in the source file; if the .TFCOND directive is used, the effects
    of /X are reversed.

    Note: The effects of /X are also reversed in MASM version 1.2. In
    that version, statements within a false conditional are included in
    the list file by default, and /X will suppress them.

    The /T, /V, and /Z switches affect MASM's display on standard output.
    The /T (terse) switch suppresses messages to standard output, except
    for messages indicating warning errors or severe errors. The /V
    (verbose) switch displays information about the number of source lines
    and symbols at the end of the assembly, in addition to displaying the
    normal error and symbol space information. The /Z switch displays the
    actual source lines producing assembly errors (rather than displaying
    just the error type and line number).

    Note: Versions of MASM earlier than 4.0 always show both the source
    line and the error message.

Return Codes

    0   No errors were found during assembly.
    1   An error was detected in one of the command-line parameters.
    2   The assembly-language source file could not be opened.
    3   The list file could not be created.
    4   The object file could not be created.
    5   The cross-reference file could not be created.
    6   An include file could not be opened.
    7   At least one severe error was detected during assembly. (MASM
        deletes the invalid object file.)
    8   The assembly was terminated because a memory allocation error
        occurred.
    10  An error occurred in defining a symbol (with the /Dsymbol switch)
        from the command line.
    11  Assembly was interrupted by the user's pressing Ctrl-C or Ctrl-
        Break.

Examples

    To assemble the source file CLEAN.ASM in the current drive and
    directory and place the resulting relocatable object module in the
    file CLEAN.OBJ without producing a listing or a cross-reference file,
    type

    C>MASM CLEAN;  <Enter>

    The semicolon after the first parameter causes MASM to use the default
    values for the rest of the parameters.

    To assemble the source file CLEAN.ASM, put the object code in a file
    named CLEAN.OBJ, create a list file named CLEAN.LST, and place
    information for later processing by the CREF utility in the cross-
    reference file CLEAN.CRF, type

    C>MASM CLEAN,CLEAN,CLEAN,CLEAN  <Enter>

    or

    C>MASM CLEAN,,CLEAN,CLEAN  <Enter>

    To use MASM interactively, enter its name without parameters:

    C>MASM  <Enter>

    MASM then prompts for all the necessary information. For example, the
    interactive session on the next page assembles the file HELLO.ASM into
    the file HELLO.OBJ, producing no listing or .CRF file.

    C>MASM  <Enter>
    Microsoft (R) Macro Assembler  Version 4.00
    Copyright (C) Microsoft Corp 1981, 1983, 1984, 1985. All rights reserved

    Source filename: [.ASM]: HELLO  <Enter>
    Object filename: [HELLO.OBJ]:  <Enter>
    Source listing [NUL.LST]:  <Enter>
    Cross-reference [NUL.CRF]:  <Enter>

    51004 Bytes symbol space free

        0 Warning Errors
        0 Severe Errors

Messages

    8087 opcode can't be emulated
    An 8087 opcode or the operands used with it produced an instruction
    the emulator cannot support.

    Already defined locally
    An attempt was made to define a symbol as EXTRN that had already been
    defined locally.

    Already had ELSE clause
    An attempt was made to define an ELSE clause within an existing ELSE
    clause. (ELSE cannot be nested without nesting IF...ENDIF.)

    Already have base register
    More than one base register was specified within an operand.

    Already have index register
    More than one index register was specified within an operand.

    Block nesting error
    A segment, structure, macro, IRC, IRP, REPT, or nested procedure was
    not terminated properly.

    Byte register is illegal
    A byte register was used incorrectly in an instruction.

    Can't override ES segment
    An attempt was made to override the ES segment in an instruction in
    which this override is invalid.

    Can't reach with segment reg
    No ASSUME directive was given to make the variable reachable.

    Can't use EVEN on BYTE segment
    An EVEN directive was used on a segment declared to be a byte
    segment.

    Circular chain of EQU aliases
    An alias EQU ultimately points to itself.

    Constant was expected
    A constant was expected, but an item was received that does not
    evaluate to a constant.

    CS register illegal usage
    The CS register was used incorrectly in one of the instructions.

    Data emitted with no segment
    Code that is not located within a segment attempted to generate
    data.

    Directive illegal in STRUC
    All statements within STRUC blocks must be either comments preceded by
    a semicolon character (;) or one of the define directives (DB, DW, and
    so on).

    Division by 0 or overflow
    An expression was encountered that resulted in either a division by 0
    or a number too large to be represented.

    DUP is too large for linker
    Nesting of DUP operators was such that a record too large for LINK was
    created.

    End of file, no END directive
    No END statement was encountered, or a nesting error occurred.

    Extra characters on line
    Superfluous characters were detected on a line after sufficient
    information to define an instruction was interpreted.

    extra file name ignored
    The command line contained more than four filename parameters.

    Field cannot be overridden
    An attempt was made to give a value to a field that cannot be
    overridden with a STRUC initialization statement.

    Forced error
    An error was forced with the .ERR directive.

    Forced error - expression equals 0
    An error was forced with the .ERRE directive.

    Forced error - expression not equal 0
    An error was forced with the .ERRNZ directive.

    Forced error - pass1
    An error was forced with the .ERR1 directive.

    Forced error - pass2
    An error was forced with the .ERR2 directive.

    Forced error - string blank
    An error was forced with the .ERRB directive.

    Forced error - string not blank
    An error was forced with the .ERRNB directive.

    Forced error - strings different
    An error was forced with the .ERRDIF directive.

    Forced error - strings identical
    An error was forced with the .ERRIDN directive.

    Forced error - symbol defined
    An error was forced with the .ERRDEF directive.

    Forced error - symbol not defined
    An error was forced with the .ERRNDEF directive.

    Forward reference is illegal
    An item was referenced in the operand of an EQU or equal-sign (=)
    directive before it was defined.

    Illegal register value
    A specified register value does not fit into the reg field (that is,
    the value is greater than 7).

    Illegal size for item
    The size of the referenced item is invalid. This error also frequently
    occurs when an attempt is made to assemble source code written for
    assemblers with less strict type-checking than that of the Microsoft
    Macro Assembler (such as early versions of the IBM assembler). The
    problem can usually be solved by overriding the type of the operand
    with the PTR operator.

    Illegal use of external
    A variable that was declared external was used incorrectly.

    Illegal use of register
    An attempt was made to use a register with an instruction in which a
    register cannot be used.

    Illegal value for DUP count
    The DUP count was not a constant that evaluates to a positive integer
    greater than zero.

    Improper operand type
    An operand was used in a way that prevents opcode generation.

    Improper use of segment register
    An attempt was made to use a segment register in an instruction in
    which use of a segment register is not permitted.

    Impure memory reference
    An attempt was made to store data in the code segment when the .286P
    directive and the /P switch were in effect.

    Index displ. must be constant
    An index displacement was used incorrectly or did not evaluate to an
    absolute number or memory address.

    Internal error
    An internal logic error was detected in the assembler. Document the
    circumstances and contact Microsoft Corporation.

    Label can't have seg. override
    A segment override was used incorrectly.

    Left operand must have segment
    The content of the right operand requires that a segment be specified
    in the left operand.

    Line too long expanding symbol
    A symbol defined by an EQU or equal-sign (=) directive is so long that
    expanding it will cause the assembler's internal buffers to overflow.
    This message may indicate a recursive text macro.

    Missing data; zero assumed
    An operand is missing from a statement and MASM assumes its value is
    zero. This is a warning error; the object file is not deleted as it is
    with severe errors.

    More values than defined with
    Too many initial values were given when defining a variable using a
    REC or STRUC type.

    Must be associated with code
    A data-related item was used where a code-related item was
    expected.

    Must be associated with data
    A code-related item was used where a data-related item was
    expected.

    Must be AX or AL
    A register other than AX or AL was specified where only these are
    acceptable.

    Must be in segment block
    An attempt was made to generate code by instructions that were not
    contained within a segment.

    Must be index or base register
    An instruction requires a base or index register, and some other
    register was specified within square brackets ([]).

    Must be record field name
    A record field name was expected, but something else was
    encountered.

    Must be record or fieldname
    A record name or field name was expected, but something else was
    encountered.

    Must be register
    A register was expected as the operand, but something else was
    encountered.

    Must be segment or group
    A segment or group was expected, but something else was
    encountered.

    Must be structure field name
    A structure field name was expected, but something else was
    encountered.

    Must be symbol type
    A BYTE, WORD, DWORD, or similar designation was expected, but
    something else was encountered.

    Must be var, label or constant
    A variable, label, or constant was expected, but something else was
    encountered.

    Must have opcode after prefix
    A REP, REPE, REPNE, REPZ, or REPNZ instruction was not followed by the
    mnemonic for a string operation.

    Near JMP/CALL to different CS
    An attempt was made to do a NEAR jump or call to a location in a code
    segment defined with a different ASSUME:CS.

    No immediate mode
    Immediate data was supplied as an operand for an instruction that
    cannot use immediate data. For example, immediate data cannot be moved
    directly with a MOV instruction to a segment register; it must first
    be moved into a general register and then copied to the segment
    register.

    No or unreachable CS
    An attempt was made to jump to a label that is unreachable.

    Normal type operand expected
    A STRUC, BYTE, WORD, or some other invalid operand was encountered
    when a variable label was expected.

    Not in conditional block
    An ENDIF or ELSE statement was encountered, and no previous
    conditional-assembly directive was active.

    Not proper align/combine type
    The SEGMENT parameters are incorrect. Check the align and combine
    types to be sure they are valid.

    One operand must be const
    The addition operator was used incorrectly.

    Only initialize list legal
    An attempt was made to use a STRUC name without angle brackets (<>).

    Operand combination illegal
    A two-operand instruction was specified and the combination specified
    was invalid.

    Operand must have segment
    A SEG directive was used incorrectly.

    Operand must have size
    An operand was encountered that needed a specified size, but none had
    been provided. Often this error can be remedied by using the PTR
    operator to specify a size type.

    Operand not in IP segment
    An operand cannot be accessed because it is not in the segment last
    assigned to CS with an ASSUME directive.

    Operand types must match
    MASM encountered different kinds or sizes of arguments in a case where
    they must match.

    Operand was expected
    MASM expected an operand, but an operator was encountered.

    Operands must be same or 1 abs
    The subtraction operator was used incorrectly.

    Operator was expected
    MASM expected an operator, but an operand was encountered.

    Out of memory
    System memory is insufficient to complete the assembly. If a listing
    (.LST) or cross-reference (.CRF) file was being generated, retry the
    assembly, generating only an object file. It may also be necessary to
    modify the source program to reduce the load on the symbol table (by
    shortening names or reducing the number of EQU statements or macros,
    for example).

    Override is of wrong type
    An attempt was made to use a data item of incorrect size in a STRUC
    initialization statement.

    Override value is wrong length
    The override value for a structure field is too large to fit in the
    field.

    Override with DUP is illegal
    An attempt was made to use DUP to override in a STRUC initialization
    statement.

    Phase error between passes
    The program has ambiguous instruction directives that caused the
    location of a label in the program to change in value between the
    first and second passes of MASM. A common cause is a forward reference
    to a typed data item in the instructions preceding the label that
    generated the phase error message. Use the /D switch to produce a
    first-pass listing to aid in resolving phase errors between passes.

    Redefinition of symbol
    This message is displayed during first pass upon the second
    declaration of a symbol that has been defined in more than one place.

    Reference to mult defined
    The instruction references a symbol that has been defined more than
    once.

    Register already defined
    An internal error was detected. Note the circumstances of the failure
    and contact Microsoft Corporation.

    Relative jump out of range
    A conditional jump references a label that is out of the allowed range
    of -128 to +127 bytes relative to the current instruction. The problem
    usually can be corrected by reversing the condition of the jump and
    using an unconditional jump (JMP) to the out-of-range label.

    Segment parameters are changed
    The list of parameters encountered for a SEGMENT was not identical to
    the list specified the first time the segment was used.

    Shift count is negative
    A shift expression was generated that resulted in a negative shift
    count.

    Should have been group name
    A group name was expected, but something else was encountered.

    Symbol already different kind
    An attempt was made to redefine an already defined symbol.

    Symbol has no segment
    An attempt was made to use a variable with SEG that has no known
    segment.

    Symbol is already external
    An attempt was made to redefine a symbol as local that has already
    been defined as external.

    Symbol is multi-defined
    This message is displayed during the second pass upon each declaration
    of a symbol that has been defined in more than one place.

    Symbol is reserved word
    An attempt was made to use a reserved MASM word as a symbol.

    Symbol not defined
    A symbol that had not been defined was used.

    Symbol type usage illegal
    A PUBLIC symbol was used incorrectly.

    Syntax error
    The syntax of the statement does not match any recognizable syntax.

    Type illegal in context
    The type specified is of an unacceptable size.

    Unable to open input file filename
    The specified source file cannot be found.

    unknown switch letter
    The command line included an invalid switch.

    Unknown symbol type
    MASM does not recognize the size type specified in a label or external
    declaration. Rewrite with a valid type such as BYTE, WORD, or NEAR.

    Value is out of range
    A value is too large for its expected use.

    Wrong type of register
    A directive or instruction expected one type of register, but another
    type was encountered.



DEBUG
Program Debugger


Purpose

    Allows the controlled execution of a program for debugging purposes or
    the alteration of the binary contents of any file. The DEBUG utility
    is supplied with the MS-DOS distribution disks.

Syntax

    DEBUG

    or

    DEBUG filename [parameter ...]

    where:

    filename         is the name of the file that contains data to be
                    modified or a program to be debugged. If filename
                    includes an extension, it must be specified.

    parameter ...    is one or more filenames or switches required by a
                    program being debugged.

Description

    The DEBUG program allows a file to be loaded, examined, and altered.
    If the file is not a .EXE file or a .HEX file, it may also be written
    back to disk. If the file contains a program, the program can be
    disassembled, modified, traced one instruction at a time, or executed
    at full speed with preset breakpoints. DEBUG can also be used to read
    from and write to input/output (I/O) ports and to read, modify, and
    write absolute disk sectors.

    The 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 DEBUG's memory buffer. Files with the extension .EXE
    are loaded in a manner compatible with the MS-DOS loader; if
    necessary, the contents of the file are relocated so that the program
    is ready to execute. 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.

    An appropriate program segment prefix (PSP) is synthesized at the head
    of DEBUG's buffer for use by the target program (the program being
    debugged). The PSP includes a command tail at offset 80H and default
    file control blocks (FCBs) at offsets 5CH and 6CH, constructed from
    the optional parameters following filename.

    After DEBUG is loaded and the first file named in the command line is
    also located and loaded, DEBUG displays its special prompt character,
    a hyphen (-), and awaits a command. DEBUG commands consist of a single
    letter, usually followed by one or more parameters. Uppercase and
    lowercase characters are treated the same except when they are
    contained in strings enclosed within single or double quotation marks.
    All commands are executed by pressing the Enter key.

    The DEBUG commands are

╓┌─────────────────┌─────────────────────────────────────────────────────────╖
    Command      Action
    ──────────────────────────────────────────────────────────────────────
    A            Assemble machine instructions (versions 2.0 and later).
    C            Compare memory areas.
    D            Display memory.
    E            Enter data.
    F            Fill memory.
    G            Go execute program.
    H            Perform hexadecimal arithmetic.
    I            Input from port.
    L            Load file or sectors.
    M            Move (copy) data.
    N            Name file or command-tail parameters.
    O            Output to port.
    P            Proceed through loop or subroutine (versions 3.0 and
                later).
    Q            Quit debugger.
    R            Display or modify registers.
    S            Search memory.
    T            Trace program execution.
    U            Disassemble (unassemble) program.
    W            Write file or sectors.

    The parameters for a DEBUG command include addresses, ranges, 8-bit or
    16-bit hexadecimal values, and lists. Multiple parameters can be
    separated by spaces, tabs, or commas, but separators are required
    only between hexadecimal values.

    An address can be a simple offset or a complete address in the form
    segment:offset. The offset is always a hexadecimal number in the range
    00H through FFFFH; the segment can be either a hexadecimal value in
    the same range or a two-character segment register name (CS, DS, ES,
    or SS). If the segment portion of an address is absent, DEBUG uses DS
    unless an A, G, L, T, U, or W command is used, in which case DEBUG
    uses CS.

    A range specifies an area of memory and can be expressed as either two
    addresses or a starting address and a length. A segment can be
    included only in the first element of a range; an error message is
    displayed if a segment is found in the second address. A length is
    represented by the letter L, followed by a hexadecimal value between
    00H and FFFFH that indicates the number of bytes following the
    starting address that the command should operate on.

    Note: Any length that causes an address to exceed 16 bits will
    generate an error.

    A byte, or 8-bit, value is entered as one or two hexadecimal digits,
    whereas a word, or 16-bit, value is entered as one to four hexadecimal
    digits. Leading zeros can be omitted.

    A list is composed of one or more byte values or strings, separated by
    spaces, commas, or tabs. A string is one or more ASCII characters
    enclosed within single or double quotation 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 itself, the character must
    be doubled inside the string in order to be interpreted correctly. For
    example:

    "This ""string"" is OK."

    When used, a list must be the last parameter in the command
    line.

    DEBUG responds to an invalid command by pointing to the approximate
    location of the error with a caret character (^) and displaying the
    word Error. For example:

    -D CS:0100,CS:0200  <Enter>
                ^ Error

    DEBUG maintains a set of virtual CPU registers for a program being
    debugged. These registers can be examined and modified with DEBUG
    commands. When a program is first loaded for debugging, the virtual
    registers are initialized with the following values:

╓┌──────────────┌─────────────────────────────┌──────────────────────────────╖
    Register  .COM Program                  .EXE Program
    ──────────────────────────────────────────────────────────────────────
    AX        Valid drive error code        Valid drive error code
    BX        Upper half of program size    Upper half of program size
    CX        Lower half of program size    Lower half of program size
    DX        Zero                          Zero
    SI        Zero                          Zero
    DI        Zero                          Zero
    BP        Zero                          Zero
    SP        FFFEH or top of available     Size of stack segment
            memory minus 2
    IP        100H                          Offset of entry point within
                                            target program's code segment
    CS        PSP                           Base of target program's code
                                            segment
    DS        PSP                           PSP
    ES        PSP                           PSP
    SS        PSP                           Base of target program's stack
                                            segment

    Note: DEBUG checks the first three parameters in the command line. If
    the second and third parameters are filenames, DEBUG checks any drive
    specifications with those filenames to verify that they designate
    valid drives. Register AX contains one of the following codes:

╓┌──────────────┌────────────────────────────────────────────────────────────╖
    Code      Meaning
    ──────────────────────────────────────────────────────────────────────
    0000H     The drives specified with the second and third filenames are
            both valid, or only one filename was specified in the
            command line.

    00FFH     The drive specified with the second filename is invalid.

    FF00H     The drive specified with the third filename is invalid.

    FFFFH     The drives specified with the second and third filenames are
            both invalid.

    DEBUG also maintains a set of virtual flags, which may be set or
    cleared. The flags are

╓┌───────────────────────┌───────────────────┌───────────────────────────────╖
    Flag Name          Value If Set (1)    Value If Clear (0)
    ──────────────────────────────────────────────────────────────────────
    Overflow           OV (Overflow)       NV (No Overflow)B
    Direction          DN (Down)           UP (Up)
    Interrupt          EI (Enabled)        DI (Disabled)
    Sign               NG (Minus)          PL (Plus)
    Zero               ZR (Zero)           NZ (Not Zero)
    Aux Carry          AC (Aux Carry)      NA (No Aux Carry)
    Parity             PE (Even)           PO (Odd)
    Carry              CY (Carry)          NC (No Carry)

    Before DEBUG 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 control reverts to DEBUG
    from the target program, the returned register contents are stored
    back in the virtual register set for inspection and alteration by the
    user.

Examples

    To load the file SHELL.EXE in the current directory for execution
    under the control of DEBUG, type

    C>DEBUG SHELL.EXE  <Enter>

    To use the DEBUG program to inspect or modify memory or to read,
    modify, and write absolute disk sectors, simply type

    C>DEBUG  <Enter>

Message

    File not found
    The filename supplied as the first parameter in the DEBUG command line
    cannot be found.



DEBUG: A
Assemble Machine Instructions


Purpose

    Allows entry of assembler mnemonics and translates them into
    executable machine code.

Syntax

    A [address]

    where:

    address    is the starting location for the assembled machine code.

Description

    The Assemble Machine Instructions (A) command accepts assembly-
    language statements, rather than hexadecimal values, for the Intel
    8086/8088 microprocessors and the Intel 8087 math coprocessor and then
    assembles each statement into executable machine code.

    The address parameter specifies the location where entry of assembly-
    language mnemonics will begin. If address is omitted, DEBUG uses the
    address following the last instruction generated the last time the A
    command was used. If the A command has not been used, DEBUG uses the
    current value of the target program's CS:IP registers.

    After an A command is entered, DEBUG prompts for each assembly-
    language statement by displaying the address, in the form of a segment
    and an offset, in which the assembled code will be stored. When the
    Enter key is pressed, the assembly-language statement is translated,
    and each byte of the resulting machine instruction is stored
    sequentially in memory (overwriting existing information), beginning
    at the displayed address. The address following the last byte of the
    machine instruction is then displayed so that the user can enter the
    next assembly-language statement. Pressing the Enter key alone in
    response to the address prompt terminates the A command.

    The syntax of assembly-language statements accepted by the DEBUG A
    command differs slightly from that of the usual Microsoft Macro
    Assembler programming statements. The differences can be summarized as
    follows:

    ■  All numbers are assumed to be hexadecimal integers and should be
        entered without a trailing H character.

    ■  Segment overrides must be specified by preceding the entire
        instruction with CS:, DS:, ES:, or SS:.

    ■  File control directives (NAME, PAGE, TITLE, and so forth), macro
        definitions, record structures, and conditional assembly directives
        are not supported by DEBUG.

    ■  Specific hexadecimal values, rather than program labels, must be
        included.

    ■  When the data type (word or byte) is not implicit in the
        instruction, the type must be specified by preceding the operand
        with BYTE PTR (or BY) or WORD PTR (or WO).

    ■  The size of the string in a string operation must be specified by
        adding a B (byte) or W (word) to the string instruction mnemonic
        (for example, LODSB or LODSW).

    ■  The DB and DW instructions accept a parameter of the type list and
        assemble byte and word values directly.

    ■  The WAIT or FWAIT opcodes for 8087 assembler statements are not
        generated by default, so they must be coded explicitly.

    ■  Memory locations are differentiated from immediate operands by
        enclosing memory addresses in square brackets.

    ■  Repeat prefixes, such as REP, REPZ, or REPNZ, can be entered either
        alone on the line preceding the statement they affect or
        immediately preceding the statement on the same line.

    ■  Although the assembler generates the optimal form (SHORT, NEAR, or
        FAR) for jumps or calls, depending on the destination address,
        these designations can be overridden by preceding the operand with
        a NEAR (or NE) or FAR (no abbreviation) prefix.

    ■  The mnemonic for a FAR RETURN is RETF.

    Examples

    To begin assembling code at address CS:0100H, type

    -A 100  <Enter>

    To assemble the instruction sequence

    LODS  WORD PTR [SI]
    XCHG  BX,AX
    JMP   [BX]

    beginning at address CS:0100H, the following dialogue would take
    place:

    -A 100  <Enter>
    1983:0100  LODSW  <Enter>
    1983:0101  XCHG BX,AX  <Enter>
    1983:0103  JMP [BX]  <Enter>
    1983:0105  <Enter>


    To continue assembling at the location following the last instruction
    generated by a previous A command, type

    -A  <Enter>



DEBUG: C
Compare Memory Areas


Purpose

    Compares two areas of memory and reports any differences.

Syntax

    C range address

    where:

    range      is the starting and ending addresses or the starting
                address and length of the first area of memory to be
                compared.

    address    is the starting address of the second area of memory to be
                compared.

Description

    The Compare Memory Areas (C) command compares the contents of two
    areas of memory. The location and contents of any differing bytes are
    displayed in the following format:

    address1  byte1  byte2  address2

    If no differences are found, the DEBUG prompt returns.

    The range parameter specifies the starting and ending addresses or
    the starting address and length in bytes of the first area of memory
    to be compared. The address parameter specifies the beginning address
    of the second area of memory to be compared. If a segment is not
    included in range or address, DEBUG uses DS.

Example

    To compare the 64 bytes beginning at CS:CE00H with the 64 bytes
    beginning at CS:CF0AH, type

    -C CS:CE00 CE3F CS:CF0A  <Enter>

    or

    -C CS:CE00 L40 CS:CF0A  <Enter>

    If any differences are found, DEBUG displays them in the following
    format:

    2124:CE06  00  FF  2124:CF10



DEBUG: D
Display Memory


Purpose

    Displays the contents of an area of memory in hexadecimal and ASCII
    format.

Syntax

    D [range]

    where:

    range      is the starting and ending addresses or the starting
                address and length of the area to be displayed.

Description

    The Display Memory (D), or Dump, command displays the contents of a
    specified range of memory addresses in hexadecimal and ASCII format.

    The range parameter gives the starting and ending addresses or the
    starting address and length in bytes of the memory to be displayed. If
    range does not include a segment, DEBUG uses DS.

    If range is omitted the first time the D command is used, the display
    starts at the target program's CS:IP registers. If range was
    specified in a preceding D command, the memory address following the
    last address displayed by that command is used. If a length is not
    explicitly stated in a D command, 128 bytes are displayed.

    Each line displays a segment and offset, followed by the contents of
    16 bytes of memory represented as hexadecimal values and separated by
    spaces (except the eighth and ninth values, which are separated by a
    dash), followed by the ASCII character equivalents (if any) of the
    same 16 bytes. In the ASCII portion, nonprinting characters are
    displayed as periods.

Examples

    To display the contents of the 128 bytes of memory beginning at
    7F00:0100H, type

    -D 7F00:0100  <Enter>

    The contents of the memory addresses are displayed in the following
    format:

7F00:0100  20 64 65 76 69 63 65 0D-0A 00 60 39 0D 0A 00 7C  device...'9...|
7F00:0110  39 08 20 08 00 81 39 04-1B 5B 32 4A 42 BD 11 44 9. ...9..[2JB=.D
7F00:0120  2E 26 45 AF 11 47 B3 11-48 A5 11 4C B8 11 4E D3 .&E/.G3.H%.L8.NS
7F00:0130  11 50 DF 11 51 AB 11 54-DF 1E 56 37 11 5F 9F 16 .P_.Q+.T_.V7._..
7F00:0140  24 C0 11 00 03 4E 4F 54-C1 07 0A 45 52 52 4F 52 $@...NOTA..ERROR
7F00:0150  4C 45 56 45 4C 85 08 05-45 58 49 53 54 18 08 00 LEVEL...EXIST...
7F00:0160  03 44 49 52 03 91 0C 06-52 45 4E 41 4D 45 01 C0 .DIR....RENAME.@
7F00:0170  0F 03 52 45 4E 01 C0 0F-05 45 52 41 53 45 01 68 ..REN.@..ERASE.h

    To view the next 128 bytes of memory, type

    -D  <Enter>

    In this case, the contents of memory addresses 7F00:0180H through
    7F00:01FFH are displayed.



DEBUG: E
Enter Data


Purpose

    Enters data into memory.

Syntax

    E address [list]

    where:

    address    is the first memory location for data entry.

    list       specifies the data to be entered into successive bytes of
                memory, starting at address.

Description

    The Enter Data (E) command allows data to be entered into successive
    memory locations. The data can be entered in either hexadecimal or
    ASCII format. Data previously stored in the specified locations is
    lost.

    The address parameter specifies the first byte to be modified. If
    address does not include a segment, DEBUG uses DS. The address is
    incremented for each byte of data stored.

    The list parameter is one or more hexadecimal byte values and/or
    strings, separated by spaces, commas, or tab characters. Strings must
    be enclosed within single or double quotation marks, and case is
    significant within a string.

    If list is included in the command line, the changes to memory are
    made unless an error is detected in the command line, in which case an
    error message is displayed and the E command is terminated. If list
    is omitted from the command line, the user is prompted byte by byte
    for data to be entered into memory, starting at address. The current
    contents of a byte are displayed, followed by a period. A new value
    for that byte can be entered as one or two hexadecimal digits (extra
    characters are ignored) or the contents can be left unchanged.
    Pressing the spacebar displays the contents of the next byte. Entering
    a minus sign or hyphen character (-) instead of pressing the spacebar
    displays the contents of the previous byte. A maximum of 8 bytes can
    be entered on each input line; a new line is begun each time an 8-byte
    boundary is crossed. Pressing the Enter key without pressing the
    spacebar or entering any data terminates data entry.

    Text strings can be entered only by using the list parameter; they
    cannot be entered in response to an address prompt.

Examples

    To store the byte values 00H, 0DH, and 0AH in the three bytes
    beginning at DS:1FB3H, type

    -E 1FB3 00 0D 0A  <Enter>

    To store the string MAIN MENU into memory beginning at address
    ES:0C14H, type

    -E ES:C14 "MAIN MENU"  <Enter>



DEBUG: F
Fill Memory


Purpose

    Stores a repetitive data pattern in an area of memory.

Syntax

    F range list

    where:

    range      is the starting and ending addresses or starting address
                and length of the memory to be filled.

    list       is the data to be entered.

Description

    The Fill Memory (F) command fills an area of memory with the data from
    a list. The data can be entered in either hexadecimal or ASCII format.
    Any data previously stored at the specified locations is lost. If an
    error message is displayed, the original values in memory remain
    unchanged.

    The range parameter specifies the starting and ending addresses or
    the starting address and hexadecimal length in bytes of the area of
    memory to be filled. If range does not specify a segment, DEBUG uses
    DS.

    The list parameter specifies one or more hexadecimal byte values
    and/or strings, separated by spaces, commas, or tab characters.
    Strings must be enclosed in single or double quotation marks, and case
    is significant within a string.

    If the area to be filled is larger than the data list, the list is
    repeated as often as necessary to fill the area. If the data list is
    longer than the area of memory to be filled, it is truncated to fit
    into the area.

Examples

    To fill the area of memory from DS:0B10H through DS:0B4FH with the
    value 0E8H, type

    -F B10 B4F E8  <Enter>

    or

    -F B10 L40 E8  <Enter>

    To fill the 16 bytes of memory beginning at address CS:1FA0H by
    replicating the 2-byte sequence 0DH 0AH, type

    -F CS:1FA0 1FAF 0D 0A  <Enter>

    or

    -F CS:1FA0 L10 0D 0A  <Enter>

    To fill the area of memory from ES:0B00H through ES:0BFFH by
    replicating the text string BUFFER, type

    -F ES:B00 BFF "BUFFER"  <Enter>

    or

    -F ES:B00 L100 "BUFFER"  <Enter>



DEBUG: G
Go


Purpose

    Transfers control from DEBUG to the program being debugged.

Syntax

    G [=address] [break0 [... break9]]

    where:

    address                is the location DEBUG begins execution.

    break0...break9        specify from 1 to 10 temporary breakpoints.

Description

    The Go (G) command transfers control from DEBUG to the program being
    debugged. If no breakpoints are set, the program executes until it
    crashes or finishes, in which latter case the message Program
    terminated normally is displayed and control returns to DEBUG. (After
    this message is displayed, the program may need to be reloaded before
    it can be executed again.)

    The address parameter can specify any location in memory. If no
    segment is specified, DEBUG uses the target program's CS register. If
    address is omitted, DEBUG transfers to the current address in the
    target program's CS:IP registers. An equal sign (=) must precede
    address to distinguish it from the breakpoints break0...break9.

    The parameters break0...break9 are addresses that represent from 1 to
    10 temporary breakpoints that can be set as part of the G command. A
    breakpoint is an address at which execution stops. Breakpoints can be
    placed in any order, because execution stops at the first breakpoint
    address encountered, regardless of the position of that breakpoint in
    the list. Each breakpoint address must contain the first byte of an
    8086 opcode. DEBUG installs breakpoints by replacing the first byte of
    the machine instruction at each breakpoint address with an INT 03H
    instruction (opcode 0CCH). If the program encounters a breakpoint,
    execution is suspended and control returns to DEBUG. DEBUG then
    restores the original machine code to the breakpoint addresses;
    displays the contents of the registers, the status of the flags, and
    the instruction pointed to by CS:IP; and displays the DEBUG prompt. If
    the program executes to completion without encountering any of the
    breakpoints or stops for any reason other than because it encountered
    a breakpoint, DEBUG does not replace the INT 03H instructions with the
    original machine code, and the Load File or Sectors (L) command must
    be used to reload the original program.

    The G command requires that the target program's SS:SP registers point
    to a valid stack that has at least 6 bytes of stack space available.
    When the G command is executed, it pushes the target program's flags
    and CS and IP registers onto the stack and then transfers control to
    the target program with an IRET instruction. Thus, if the target
    program's stack is not valid or is too small, the system may
    crash.

Examples

    To begin execution of the program in DEBUG's buffer at location
    CS:110AH and set breakpoints at CS:12FCH and CS:1303H, type

    -G =110A 12FC 1303  <Enter>

    To resume execution of the program after a breakpoint has been
    encountered and control has been returned to DEBUG, type

    -G  <Enter>

Messages

    bp Error
    More than 10 breakpoints were specified in a G command. The command
    must be entered again with 10 or fewer breakpoints.

    Program terminated normally
    No breakpoints were encountered and the target program executed to
    completion. If breakpoints were set, the original program should be
    restored with the L command.



DEBUG: H
Perform Hexadecimal Arithmetic


Purpose

    Displays the sum and difference of two hexadecimal numbers.

Syntax

    H value1 value2

    where:

    value1 and value2     are any two hexadecimal numbers from
                        0 through FFFFH.

Description

    The Perform Hexadecimal Arithmetic (H) command displays the sum and
    the difference of two 16-bit hexadecimal numbers--that is, the result
    of the operations value1+value2 and value1-value2. If value2 is
    greater than value1, the difference of the two values is displayed as
    a two's complement number. This command is convenient for quickly
    calculating addresses and other values during an interactive debugging
    session.

Examples

    To display the sum and the difference of the values 4B03H and 104H,
    type

    -H 4B03 104  <Enter>

    This produces the following display:

    4C07  49FF

    If the addition produces an overflow, the four least significant
    digits are displayed. For example, the command line

    -H FFFF 2  <Enter>

    produces the following display:

    0001 FFFD

    If the second number is bigger than the first, the difference is
    displayed in two's complement form. For example, the command
    line

    -H 1 2  <Enter>

    produces the following display:

    0003 FFFF



DEBUG: I
Input from Port


Purpose

    Reads and displays 1 byte from an input/output (I/O) port.

Syntax

    I port

    where:

    port      is an I/O port address from 0 through FFFFH.

Description

    The Input from Port (I) command reads the specified I/O port address
    and displays the data as a two-digit hexadecimal number.

    Warning: The I command should be used with caution because it
    directly accesses the computer hardware and no error checking is
    performed. Input operations directed to the ports assigned to some
    peripheral device controllers may interfere with the proper operation
    of the system. If no device has been assigned to the specified I/O
    port or if the port is write-only, the value displayed by an I command
    is unreliable.

Example

    To read and display the contents of I/O port 10AH, type

    -I 10A  <Enter>

    An example of the output of this command is

    FF



DEBUG: L
Load File or Sectors


Purpose

    Loads a file or individual sectors from a disk into DEBUG's
    memory.

Syntax

    L [address]

    or

    L address drive start number

    where:

    address    is the memory location for the data to be read from the
                disk.

    drive      is the number of the disk drive to read (0 = drive A, 1 =
                drive B, 2 = drive C, and so on).

    start      is the hexadecimal number of the first logical sector to
                load (0-FFFFH).

    number     is the hexadecimal number of consecutive sectors to load
                (0-FFFFH).

Description

    The Load File or Sectors (L) command loads a file or individual
    sectors from a disk. When the L command is entered without parameters
    or with only an address, the file specified in the DEBUG command line
    or the one in the most recent Name File or Command-Tail Parameters (N)
    command line is loaded from the disk into memory. If no segment is
    specified in address, DEBUG uses CS. If the file's extension is .EXE,
    the file is placed in DEBUG's target program buffer at the load
    address specified in the .EXE file's header. If the file's extension
    is .COM, the file is loaded at offset 100H. (If for some reason an
    address other than 100H is entered for a .EXE or .COM file, an error
    message is displayed; if the address is 100H, the specification is
    ignored.) The length of the file or, in the case of a .EXE file, the
    actual length of the program (the length of the file minus the header)
    is placed in the target program's BX and CX registers, with the most
    significant 16 bits in register BX.

    The L 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 load (number) must all be specified
    in the command line.

    Note: The L command should not be used to access logical sectors on
    network drives.

Examples

    To load the file specified in the DEBUG command line or in the most
    recent N command into DEBUG's target program buffer, type

    -L  <Enter>

    To load eight sectors from drive B, starting at logical sector 0, to
    memory location CS:0100H, type

    -L 100 1 0 8  <Enter>

Messages

    Disk error reading drive <FI>X
    The specified drive does not exist or the disk in the specified drive
    is defective.

    File not found
    The file specified in the most recent N command cannot be found.



DEBUG: M
Move (Copy) Data


Purpose

    Copies the contents of one area of memory to another.

Syntax

    M range address

    where:

    range      specifies the starting and ending addresses or the
                starting address and length of the area of memory to be
                copied.

    address    is the first byte in which the copied data will be placed.

Description

    The Move (Copy) Data (M) command copies data from one memory location
    to another without altering the data in the original location. If the
    source and destination areas overlap, the data is copied so that the
    resulting copy is correct; the data in the original location is
    changed where the two areas overlap.

    The range parameter specifies either the starting and ending
    addresses or the starting address and length of the memory to be
    copied. The address parameter is the first byte in which the copy
    will be placed. If range does not contain an explicit segment, DEBUG
    uses DS; if address does not contain a segment, DEBUG uses the
    segment used for range.

Example

    To copy the data in locations DS:0800H through DS:08FFH to locations
    DS:0900H through DS:09FFH, type

    -M 800 8FF 900  <Enter>

    or

    -M 800 L100 900  <Enter>



DEBUG: N
Name File or Command-Tail Parameters


Purpose

    Inserts filenames and/or switches into the simulated program segment
    prefix (PSP).

Syntax

    N parameter [parameter...]

    where:

    parameter       is one or more filenames or switches to be placed in
                    the simulated PSP.

Description

    The Name File or Command-Tail Parameters (N) command is used to enter
    one or more parameters into the simulated PSP that is built at the
    base of the buffer holding the program to be debugged. The N command
    can also be used before the Load File or Sectors (L) and Write File or
    Sectors (W) commands to name the file to be read from or written to a
    disk.

    The count of the characters following the N command is placed at
    DS:0080H in the simulated PSP, and the characters themselves are
    copied into the PSP starting at offset 81H. The string is terminated
    by a carriage return (0DH), which is not included in the count. If the
    first and second parameters follow the naming conventions for MS-DOS
    files, they are parsed into the default file control blocks (FCBs) in
    the simulated PSP at offsets 5CH and 6CH, respectively. (Switches
    specified as parameters are stored in the PSP starting at offset 81H
    along with the rest of the command line but are not included in the
    FCBs.)

    If the N command line contains only one filename, any parameters
    placed in the default FCBs by a previous N command are destroyed. If
    the drive specified with the first filename parameter is invalid, the
    AL register is set to 0FFH. If the drive specified with the second
    filename parameter is invalid, the AH register is set to 0FFH. The
    existence of a file specified with the N command is not verified until
    it is loaded with the L command.

Examples

    Assume that DEBUG was started without specifying the name of a target
    program in the command line. To load the program CLEAN.COM for
    execution under the control of DEBUG, use the N and L commands
    together as follows:

    -N CLEAN.COM  <Enter>
    -L  <Enter>

    Then, to place the parameter MYFILE.DAT in the simulated PSP's command
    tail and parse MYFILE.DAT into the first default FCB, type

    -N MYFILE.DAT  <Enter>

    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.



DEBUG: O
Output to Port


Purpose

    Writes 1 byte to an input/output (I/O) port.

Syntax

    O port byte

    where:

    port       is an I/O port address from 0 through FFFFH.

    byte       is a value from 0 through 0FFH to be written to the I/O
                port.

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 00H through
    0FFH.

    Warning: The O 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 10AH, type

    -O 10A C8  <Enter>



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    is the location of the first instruction to be executed.

    number     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 program'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: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>



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>



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 contents 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 currently 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 displayed; then DEBUG prompts with a colon
    character (:) for a new value. The value is entered 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           OV (Overflow)       NV (No Overflow)
    Direction          DN (Down)           UP (Up)
    Interrupt          EI (Enabled)        DI (Disabled)
    Sign               NG (Minus)          PL (Plus)
    Zero               ZR (Zero)           NZ (Not Zero)
    Aux Carry          AC (Aux Carry)      NA (No Aux Carry)
    Parity             PE (Even)           PO (Odd)
    Carry              CY (Carry)          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 optionally 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:

    AX=0000  BX=0000  CX=00A1  DX=0000  SP=FFFE  BP=0000 SI=0000  DI=0000
    DS=19A5  ES=19A5  SS=19A5  CS=19A5  IP=0100   NV UP EI PL NZ NA PO NC
    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>

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.



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.

    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:0000H through DS:1FFFH, type

    -S 0 1FFF 'Copyright'  <Enter>

    or

    -S 0 L2000 "Copyright"  <Enter>

    If matches are found, DEBUG displays the starting address of
    each:

    20A8:0910
    20A8:094F
    20A8:097C

    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>

    or

    -S CS:100 L11A1 3B 06  <Enter>



DEBUG: T
Trace Program Execution


Purpose

    Executes one or more instructions, displaying the CPU status after
    each instruction.

Syntax

    T [=address] [number]

    where:

    address    is the location of the first instruction to be executed.

    number     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 compatibles) 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 entirely, 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 interrupts execution of a sequence of T
    instructions. Consecutive instructions can then be executed
    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:1A00H and then return
    control to DEBUG, displaying the contents of the CPU registers and the
    status of the flags, type

    -T =1A00  <Enter>



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 instruction
    boundary, the disassembly will be incorrect.

    If range does not include a length or ending address, 32 (20H) bytes
    of memory are disassembled beginning at the specified starting
    address. If range is omitted, 32 bytes of memory are disassembled,
    starting at the address following the last instruction disassembled 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 commands without parameters.

Example

    To disassemble 8 bytes of machine instructions starting at CS:0100H,
    type

    -U 100 107  <Enter>

    or

    -U 100 L8  <Enter>



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    is the first memory location of the data to be written.

    drive      is the number of the destination disk drive (0 = drive A,
                1 = drive B, 2 = drive C, and so on).

    start      is the number of the first logical sector to write
                (0-FFFFH).

    number     is the number of consecutive sectors to be written
                (0-FFFFH).

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 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.

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
    (:). 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.



SYMDEB
Symbolic Debugger


Purpose

    The Symbolic Debugger (SYMDEB) allows a file to be loaded, examined,
    altered, and written back to disk. If the file contains a program, the
    program can be disassembled, modified, 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        is the name of a symbol file created with the MAPSYM
                    utility (extension = .SYM).

    filename       is the name of the binary or executable program file
                    to be debugged.

    parameter      is a command-line parameter required by the program
                    being debugged.

    options        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           (IBM) specifies that the computer is IBM
                                compatible.

                    /K           enables the interactive breakpoint key
                                (Scroll Lock).

                    /N           enables the use of nonmaskable interrupt
                                break systems on IBM-compatible
                                computers (requires special hardware).

                    /S           enables the Screen Swap (\) command on
                                IBM-compatible computers  (the /I
                                switch is also required).

                    /"commands"  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 addresses with labels,
    variable names, and expressions, rather than only with absolute
    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 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 compatible 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 segment prefix
    (PSP) is synthesized at the head of SYMDEB's buffer for use by the
    target program; the PSP includes a command tail at offset 80H 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
    extension .SYM. See PROGRAMMING UTILITIES: MAPSYM; LINK.

    The four command-line switches /I, /K, /N, and /S provide SYMDEB with
    information about the computer on which the utility is running. The /I
    switch is used when the computer 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 control 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 /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 enables 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 consist of one or two letters, usually
    followed by one or more parameters. SYMDEB treats 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            Assemble machine instructions.
    BC           Clear breakpoints.
    BD           Disable breakpoints.
    BE           Enable breakpoints.
    BL           List breakpoints.
    BP           Set breakpoints.
    C            Compare memory areas.
    D            Display memory.
    DA           Display ASCII.
    DB           Display bytes.
    DD           Display doublewords.
    DL           Display long reals.
    DS           Display short reals.
    DT           Display 10-byte reals.
    DW           Display words.
    E            Enter data.
    EA           Enter ASCII string.
    EB           Enter bytes.
    ED           Enter doublewords.
    EL           Enter long reals.
    ES           Enter short reals.
    ET           Enter 10-byte reals.
    EW           Enter words.
    F            Fill memory.
    G            Go execute program.
    H            Perform hexadecimal arithmetic.
    I            Input from port.
    K            Perform stack trace.
    L            Load file or sectors.
    M            Move (copy) data.
    N            Name file or command-tail parameters.
    O            Output to port.
    P            Proceed through loop or subroutine.
    Q            Quit debugger.
    R            Display or modify registers.
    S            Search memory.
    S+           Enable source display mode.
    S-           Disable source display mode.
    S&           Enable source and machine code display mode.
    T            Trace program execution.
    U            Disassemble (unassemble) program.
    V            View source code.
    W            Write file or sectors.
    X            Examine symbol map.
    XO           Open symbol map.
    Z            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 letter, 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, 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 necessary (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 character (.) and take one of the
    following forms:

    .[filename:]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 information.
    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 component 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 displacement. 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 command 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 following values are equivalent:

    0040             0100Q
    0040H            0100O
    0064t            1000000Y

    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 evaluates 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. Expressions 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
    NOT       One's (bitwise) complement
    SEG       Segment address of operand
    OFF       Offset of operand
    BY        Low-order byte from specified address
    WO        Low-order word from specified address
    DW        Doubleword from specified address
    POI       Pointer from specified address (same as DW)
    PORT      Byte input from specified port
    WPORT     Word input from specified port

    The available binary operators, listed in order of precedence from
    highest to lowest, are

╓┌──────────────┌────────────────────────────────────────────────────────────╖
    Operator  Meaning
    ──────────────────────────────────────────────────────────────────────
    *         Multiplication
    /         Integer division
    MOD       Modulus
    :         Segment override
    +         Addition
    -         Subtraction
    AND       Bitwise Boolean AND
    XOR       Bitwise Boolean Exclusive OR
    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 quotation 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").

    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 program is first loaded for debugging,
    the virtual registers are initialized with the following values:

╓┌──────────────┌───────────────────────────┌────────────────────────────────╖
    Register  .COM Program                .EXE Program
    ──────────────────────────────────────────────────────────────────────
    AX        Valid drive code            Valid drive code
    BX        Upper half of program size  Upper half of program size
    CX        Lower half of program size  Lower half of program size
    DX        Zero                        Zero
    SI        Zero                        Zero
    DI        Zero                        Zero
    BP        Zero                        Zero
    SP        FFFEH or top of available   Size of stack segment
            memory minus 2
    IP        100H                        Offset of entry point within
                                        target program's code segment
    CS        PSP                         Base of target program's code
                                        segment
    DS        PSP                         PSP
    ES        PSP                         PSP
    SS        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 filenames to verify that they
    designate valid drives. Register AX contains one of the following
    codes:

╓┌──────────────┌────────────────────────────────────────────────────────────╖
    Code      Meaning
    ──────────────────────────────────────────────────────────────────────
    0000H     The drives specified with the second and third filenames are
            both valid, or only one filename was specified in the
            command line.
    00FFH     The drive specified with the second filename is invalid.
    FF00H     The drive specified with the third filename is invalid.
    FFFFH     The drives specified with the second and third filenames are
            both invalid.

    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 control 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
    CLEAN.MAP.

    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 SHELL.C for debugging with SYMDEB, first
    compile the program with the switches that disable optimization and
    cause line-number information to be written to the relocatable object
    module:

    C>MSC /Zd /Od SHELL;  <Enter>

    Next, to convert the object module to an executable program and create
    a map file with line-number information, type

    C>LINK /MAP /LI SHELL;  <Enter>

    To create the symbol information file required by SYMDEB for symbolic
    debugging, type

    C>MAPSYM SHELL  <Enter>

    To begin debugging, type

    C>SYMDEB SHELL.SYM SHELL.EXE  <Enter>

    To use the SYMDEB utility to inspect or modify memory or to read,
    modify, and write absolute disk sectors, type

    C>SYMDEB  <Enter>

Message

    File not found
    The filename supplied as the first parameter in the SYMDEB command
    line cannot be found.



SYMDEB: A
Assemble Machine Instructions


Purpose

    Allows entry of assembler mnemonics and translates them into
    executable machine code.

Syntax

    A [address]

    where:

    address   is the starting location for the assembled machine code.

Description

    The Assemble Machine Instructions (A) command accepts assembly-
    language statements, rather than hexadecimal values, for the Intel
    8086/8088, 80186, and 80286 (running in real mode) microprocessors and
    the Intel 8087 and 80287 math coprocessors and assembles each
    statement into executable machine language.

    The address parameter specifies the location where entry of assembly-
    language mnemonics will begin. If address is omitted, SYMDEB uses the
    last address generated by the previous A command; if there was no
    previous A command, SYMDEB uses the current value of the target
    program's CS:IP registers.

    After the user enters an A command, SYMDEB prompts for each assembly-
    language statement by displaying the address (a segment and an offset)
    in which the assembled code will be stored. When the user presses the
    Enter key, SYMDEB translates the assembly-language statement and
    stores each byte of the resulting machine instruction sequentially in
    memory (overwriting any existing information), beginning at the
    displayed address. SYMDEB then displays the address following the last
    byte of the machine instruction to prompt the user to enter the next
    assembled instruction. The user can terminate assembly mode by
    pressing the Enter key in response to the address prompt.

    The assembly-language statements accepted by the SYMDEB A command have
    some slight syntactic differences and restrictions compared with the
    Microsoft Macro Assembler programming statements. These differences
    can be summarized as follows:

    ■  All numbers are assumed to be hexadecimal integers unless otherwise
        specified with a radix character suffix.

    ■  Segment overrides must be specified by preceding the entire
        instruction with CS:, DS:, ES:, or SS:.

    ■  File control directives (NAME, PAGE, TITLE, and so forth), macro
        definitions, record structures, and conditional assembly directives
        are not supported by SYMDEB.

    ■  When the data type (word or byte) is not implicit in the
        instruction, the type must be specified by preceding the operand
        with BYTE PTR (or BY), WORD PTR (or WO), DWORD PTR (or DW), QWORD
        PTR (or QW), or TBYTE PTR (or TB).

    ■  In a string operation, the size of the string must be specified
        with a B (byte) or W (word) added to the string instruction
        mnemonic (for example, LODSB or LODSW).

    ■  The DB and DW instructions accept a parameter of the type list and
        assemble byte and word values directly into memory.

    ■  The WAIT or FWAIT opcodes for 8087/80287 assembler statements are
        not generated by the system and must be coded explicitly. (Note:
        8087/80287 instructions can be assembled if the system is not
        equipped with a math coprocessor, but the system will crash if an
        attempt is made to execute them.)

    ■  Addresses must be enclosed in square brackets to be differentiated
        from immediate operands.

    ■  Repeat prefixes such as REP, REPZ, and REPNZ can be entered either
        alone on a line preceding the statement they affect or on the same
        line immediately preceding the statement.

    ■  The assembler will generate the optimal form (SHORT, NEAR, or FAR)
        for jumps or calls, depending on the destination address, but these
        can be overridden if the operand is preceded with a NEAR (or NE) or
        FAR prefix.

    ■  The mnemonic for a FAR RETURN is RETF.

    Examples

    To begin assembling code at address CS:0100H, type

    -A 100  <Enter>

    To assemble the instruction sequence

    LODS WORD PTR [SI]
    XCHG BX,AX
    JMP [BX]

    beginning at address CS:0100H, the following dialogue would take
    place:

    -A 100  <Enter>
    1983:0100  LODSW  <Enter>
    1983:0101  XCHG BX,AX  <Enter>
    1983:0103  JMP [BX]  <Enter>
    1983:0105  <Enter>

    To continue assembling at the last address generated by a previous A
    command (1983:0105H in the preceding example), type

    -A  <Enter>



SYMDEB: BC
Clear Breakpoints


Purpose

    Permanently removes sticky breakpoints.

Syntax

    BC *

    or

    BC list

    where:

    *          represents all sticky breakpoints.

    list       is one or more integers (sticky breakpoint numbers) in the
                range 0 through 9.

Description

    The Clear Breakpoints (BC) command permanently clears the sticky
    breakpoints previously set with the Set Breakpoints (BP) command. A
    sticky breakpoint remains in memory throughout a SYMDEB session,
    unlike a breakpoint set with the Go (G) command, which remains in
    effect only while the G command executes.

    If an asterisk character (*) follows the BC command, SYMDEB deletes
    all sticky breakpoints. If a list parameter containing one or more
    sticky breakpoint numbers in the range 0 through 9 follows the BC
    command, SYMDEB selectively deletes sticky breakpoints. Each sticky
    breakpoint is assigned a number when the breakpoint is created with
    the BP command. The List Breakpoints (BL) command can be used to
    display all current sticky breakpoint locations and numbers.
    Breakpoint numbers should be separated by spaces.

    Sticky breakpoints can be temporarily disabled with the Disable
    Breakpoints (BD) command and subsequently re-enabled with the  Enable
    Breakpoints (BE) command.

Examples

    To clear sticky breakpoints 0, 4, and 8, type

    -BC 0 4 8  <Enter>

    To clear all sticky breakpoints, type

    -BC *  <Enter>

Messages

    Bad breakpoint number! (0-9)
    A sticky breakpoint number in the command line was not an integer in
    the range 0 through 9.

    Breakpoint list or '*' expected!
    The BC command was entered without parameters.



SYMDEB: BD
Disable Breakpoints


Purpose

    Temporarily disables sticky breakpoints.

Syntax

    BD *

    or

    BD list

    where:

    *           represents all sticky breakpoints.

    list        is one or more integers (sticky breakpoint numbers) in the
                range 0 through 9.

Description

    The Disable Breakpoints (BD) command temporarily disables the sticky
    breakpoints previously set with the Set Breakpoints (BP) command. A
    sticky breakpoint remains in memory throughout a SYMDEB session,
    unlike a breakpoint set with the Go (G) command, which remains in
    effect only while the G command executes.

    If an asterisk character (*) follows the BD command, SYMDEB disables
    all sticky breakpoints. If a list parameter containing one or more
    sticky breakpoint numbers in the range 0 through 9 follows the BD
    command, SYMDEB selectively disables sticky breakpoints. Each sticky
    breakpoint is assigned a number when the breakpoint is created with
    the BP command. The List Breakpoints (BL) command can be used to
    display all current sticky breakpoint locations and numbers.
    Breakpoint numbers should be separated by spaces.

    Sticky breakpoints disabled with the BD command can be re-enabled with
    the Enable Breakpoints (BE) command. The Clear Breakpoints (BC)
    command can be used to permanently delete a sticky breakpoint.

Examples

    To disable sticky breakpoints 0, 4, and 8, type

    -BD 0 4 8  <Enter>

    To disable all sticky breakpoints, type

    -BD *  <Enter>

Messages

    Bad breakpoint number! (0-9)
    A sticky breakpoint number in the command line was not an integer in
    the range 0 through 9.

    Breakpoint list or '*' expected!
    The BD command was entered without parameters.



SYMDEB: BE
Enable Breakpoints


Purpose

    Enables disabled sticky breakpoints.

Syntax

    BE *

    or

    BE list

    where:

    *          represents all sticky breakpoints.

    list       is one or more integers (sticky breakpoint numbers) in the
                range 0 through 9.

Description

    The Enable Breakpoints (BE) command enables the sticky breakpoints
    disabled with the Disable Breakpoints (BD) command. A sticky
    breakpoint remains in memory throughout a SYMDEB session, unlike a
    breakpoint set with the Go (G) command, which remains in effect only
    while the G command executes.

    If an asterisk (*) character follows the BE command, SYMDEB enables
    all sticky breakpoints. If a list parameter containing one or more
    sticky breakpoint numbers in the range 0 through 9 follows the BE
    command, SYMDEB selectively enables sticky breakpoints. Each sticky
    breakpoint is assigned a number when the breakpoint is created with
    the Set Breakpoints (BP) command. The List Breakpoints (BL) command
    can be used to display all current sticky breakpoint locations and
    numbers. Breakpoint numbers should be separated by spaces.

Examples

    To enable sticky breakpoints 0, 4, and 8, type

    -BE 0 4 8  <Enter>

    To enable all sticky breakpoints, type

    -BE *  <Enter>

Messages

    Bad breakpoint number! (0-9)
    A sticky breakpoint number in the command line was not an integer in
    the range 0 through 9.

    Breakpoint list or '*' expected!
    The BE command was entered without parameters.



SYMDEB: BL
List Breakpoints


Purpose

    Displays information about all sticky breakpoints.

Syntax

    BL

Description

    The List Breakpoints (BL) command lists the current status of each
    sticky breakpoint created with the Set Breakpoints (BP) command. A
    sticky breakpoint remains in memory throughout a SYMDEB session,
    unlike a breakpoint set with the Go (G) command, which remains in
    effect only while the G command executes.

    The BL command lists each sticky breakpoint number, its status code,
    its address in the target program, the number of passes remaining, and
    the initial number of passes specified with the BP command (in
    parentheses). If source display mode was selected with the Enable
    Source Display Mode (S+) command, SYMDEB also displays the source-file
    name and the line number that corresponds to each breakpoint location.
    Breakpoint status codes are

    e   Enabled
    d   Disabled
    v   Virtual

    (A virtual breakpoint is a sticky breakpoint set at a symbol contained
    in a .EXE file that has not yet been loaded into SYMDEB.)

Example

    To view the current status of all breakpoints, type

    -BL  <Enter>

    If the BP commands

    -BP0 _TEXT:_main  <Enter>
    -BP1 _TEXT:_printf  <Enter>

    were previously entered, the BL command displays

    0 e 456E:0010 [_TEXT:_main] dump.C:32
    1 e 456E:0612 [_TEXT:_printf]



SYMDEB: BP
Set Breakpoints


Purpose

    Sets sticky breakpoint locations within the program being
    debugged.

Syntax

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

    where:

    n             is the sticky breakpoint number (0-9).

    address       is the location of the breakpoint in the target
                program.

    passcount     is the number of times the instruction at address
                should be executed before the breakpoint is taken.

    "commands"    is one or more SYMDEB commands, separated by
                semicolons. The entire list must be enclosed in double
                quotation marks. (Limit = 30 characters.)

Description

    The Set Breakpoints (BP) command sets a sticky breakpoint in the
    program being debugged. A sticky breakpoint remains in memory
    throughout a SYMDEB session, unlike a breakpoint set with the Go (G)
    command, which remains in effect only while the G command executes.
    When the target program reaches the breakpoint, execution of the
    program is suspended and control returns to SYMDEB. SYMDEB displays
    the contents of the registers and flags, followed by a prompt so that
    the user can enter more commands.

    The optional n parameter associates an integer in the range 0 through
    9, called the breakpoint number, with the sticky breakpoint location.
    If n is omitted, the next available breakpoint number is used. No
    space is allowed between BP and n.

    The address parameter must point to the first byte of a machine
    instruction in the program. This parameter may be a symbol, a literal
    address, or a source-code line number. If a segment is not included,
    SYMDEB uses the target program's CS register.

    The optional passcount parameter is the number of times execution
    should pass through the specified location before the break is taken
    and control is returned to SYMDEB. The value of passcount must be a
    hexadecimal number in the range 0 through FFFFH (default = 0).

    The optional "commands" parameter is one or more SYMDEB commands with
    their associated parameters. Each command must be separated from the
    others by a semicolon character (;) and the entire list enclosed in
    double quotation marks ("). A maximum of 30 characters can be
    specified within the quotation marks. The commands are executed
    whenever the break is taken.

Examples

    To set a sticky breakpoint at location next_file in the target
    program and dump the contents of memory locations DS:0000H through
    DS:00FFH when the breakpoint is reached, type

    -BP NEXT_FILE "DB DS:0 L100"  <Enter>

    To associate the breakpoint number 4 with the location CS:4230H in the
    program being debugged and pass the breakpoint 16 (10H) times before
    suspending execution of the program, type

    -BP4 CS:4230 10  <Enter>

Messages

    Bad breakpoint number! (0-9)
    A sticky breakpoint number in the command line was not an integer in
    the range 0 through 9.

    Breakpoint command too long!
    The "commands" parameter exceeded 30 characters.

    Breakpoint error!
    The BP command was entered without an address parameter.

    Breakpoint redefined!
    A new address was assigned to an existing breakpoint number, or an
    attempt was made to create a breakpoint with the same address as an
    existing breakpoint.

    Duplicate breakpoint ignored!
    An attempt was made to change an existing breakpoint to a breakpoint
    already specified in the breakpoint list.

    Too many breakpoints!
    No more sticky breakpoints are available.



SYMDEB: C
Compare Memory Areas


Purpose

    Compares two areas of memory and reports any differences.

Syntax

    C range address

    where:

    range      specifies the starting and ending addresses or the
                starting address and length of the first area of memory
                to be compared.

    address    points to the beginning of the second area of memory to be
                compared.

Description

    The Compare Memory Areas (C) command compares the contents of two
    areas of memory. The location and contents of any differing bytes are
    listed in the following form:

    address1  byte1  byte2  address2

    If no differences are found, the SYMDEB prompt returns.

    The range parameter specifies the first through last addresses or the
    starting address and length in bytes of the first area of memory to be
    compared.

    The address parameter points to the beginning of the second area of
    memory to be compared, which is the same size as range. If a segment
    is not included in either range or address, SYMDEB uses DS.

Example

    To compare the 64 bytes beginning at CS:CE00H with the 64 bytes
    beginning at CS:CF0AH, type

    -C CS:CE00,CE3F CS:CF0A  <Enter>

    or

    -C CS:CE00 L40 CS:CF0A  <Enter>

    If any differences are found, SYMDEB displays them in the following
    format:

    2124:CE06  00  FF  2124:CF10



SYMDEB: D
Display Memory


Purpose

    Displays the contents of an area of memory.

Syntax

    D [range]

    where:

    range      specifies the starting and ending addresses or the
                starting address and length of the area of memory to be
                displayed.

Description

    The Display Memory (D) command displays the contents of a specified
    range of memory addresses in the same format used in the most recent
    Display command (DA, DB, DD, DL, DS, DT, or DW). If no Display command
    has previously been entered, the memory is displayed in hexadecimal
    bytes and their ASCII equivalents (the DB format).

    The range parameter specifies the starting and ending addresses of
    the memory area to be displayed or the starting address followed by
    the length of the area, expressed by an L and the hexadecimal number
    of data items to be displayed. When range does not include a segment,
    SYMDEB uses DS.

    The size in bytes of each item and the default value for the length
    depend on the type of Display command used: the Display Byte (DB),
    Display Doubleword (DD), and Display Word (DW) commands default to a
    length of 128 (80H) bytes; Display ASCII (DA) displays 128 bytes or up
    to a null byte, whichever is smaller; Display Short Reals (DS),
    Display Long Reals (DL), and Display 10-Byte Reals (DT) default to the
    display of one floating-point number.

    If a Display command has not previously been used and range is
    omitted from a D command, the display starts at the address specified
    in the target program's CS:IP registers. If a Display command has
    previously been used and range is omitted from a D command, the
    display starts at the memory address following the last address
    displayed by the most recent Display command.

Examples

    Assume that the only Display commands used during this SYMDEB session
    are D and DB. To display the contents of the 128 bytes of memory
    beginning at offset 100H in the program's DGROUP, type

    -D DGROUP:0100  <Enter>

    SYMDEB displays the contents of the range of memory addresses in the
    following format:

7F00:0100  20 64 65 76 69 63 65 0D-0A 00 60 39 0D 0A 00 7C  device...'9...|
7F00:0110  39 08 20 08 00 81 39 04-1B 5B 32 4A 42 BD 11 44 9....9..[2JB=.D
7F00:0120  2E 26 45 AF 11 47 B3 11-48 A5 11 4C B8 11 4E D3 .&E/.G3.H%.L8.NS
7F00:0130  11 50 DF 11 51 AB 11 54-DF 1E 56 37 11 5F 9F 16 .P_.Q+.T_.V7._..
7F00:0140  24 C0 11 00 03 4E 4F 54-C1 07 0A 45 52 52 4F 52 $@...NOTA..ERROR
7F00:0150  4C 45 56 45 4C 85 08 05-45 58 49 53 54 18 08 00 LEVEL...EXIST...
7F00:0160  03 44 49 52 03 91 0C 06-52 45 4E 41 4D 45 01 C0 .DIR....RENAME.@
7F00:0170  0F 03 52 45 4E 01 C0 0F-05 45 52 41 53 45 01 68 ..REN.@..ERASE.h

    To view the next 128 bytes of memory, type

    -D  <Enter>

    SYMDEB displays the contents of memory addresses 7F00:0180H through
    7F00:01FFH.



SYMDEB: DA
Display ASCII


Purpose

    Displays the contents of memory in ASCII format.

Syntax

    DA [range]

    where:

    range      specifies the starting and ending addresses or the
                starting address and length of the area of memory to be
                displayed.

Description

    The Display ASCII (DA) command displays the contents of a specified
    range of memory addresses in ASCII format.

    The range parameter specifies the starting and ending addresses of
    the memory area to be displayed in ASCII format or the starting
    address followed by the length of the area, expressed by an L and a
    hexadecimal number of bytes. When range does not include a segment,
    SYMDEB uses DS.

    If a Display command has not previously been used and range is
    omitted from a DA command, the display starts at the address specified
    in the target program's CS:IP registers. If a Display command has
    previously been used and range is omitted from a DA command, the
    display starts at the memory address following the last address
    displayed by the most recent Display command.

    When a range is not explicit in a DA command, the display terminates
    after 128 bytes or when a null (zero) byte is encountered. If a range
    is specified, the entire range is displayed, including any null bytes,
    with nonprinting characters displayed as period (.) characters.

    Each line of the display is formatted as a segment and offset,
    followed by the contents of 16 bytes of memory (or less if a null byte
    was encountered) represented as an ASCII string.

    See also PROGRAMMING UTILITIES: SYMDEB:EA.

Examples

    If memory beginning at location 7F00:0100H contains the characters
    This is a test string followed by a null (zero) byte, the
    command

    -DA 7F00:0100  <Enter>

    produces the following display:

    7F00:0100  This is a test string

    To view additional memory in the same format, type

    -D  <Enter>



SYMDEB: DB
Display Bytes


Purpose

    Displays the contents of memory as hexadecimal bytes and their
    equivalent ASCII characters.

Syntax

    DB [range]

    where:

    range      specifies the starting and ending addresses or the
                starting address and length of the area of memory to be
                displayed.

Description

    The Display Bytes (DB) command displays the contents of a specified
    range of memory addresses as hexadecimal bytes and their ASCII
    character equivalents. This is the default format for the Display
    Memory (D) command.

    The range parameter specifies the starting and ending addresses of
    the memory area to be displayed or the starting address followed by
    the length of the area, expressed by an L and a hexadecimal number of
    bytes. When range does not include a segment, SYMDEB uses DS.

    If a Display command has not previously been used and range is
    omitted from a DB command, the display starts at the address specified
    in the target program's CS:IP registers. If a Display command has
    previously been used and range is omitted from a DB command, the
    display starts at the memory address following the last address
    displayed by the most recent Display command. When a range is not
    explicit in a DB command, the display terminates after 128
    bytes.

    Each line of the display is formatted as a segment and offset,
    followed by the contents of 16 bytes of memory represented as
    hexadecimal values separated by spaces (except the eighth and ninth
    values, which are separated by a dash), followed by their ASCII
    character equivalents (if any). In the ASCII section, nonprinting
    characters are displayed as periods.

    See also PROGRAMMING UTILITIES: SYMDEB:EB.

Examples

    To display the contents of the 128 bytes of memory beginning at
    7F00:0100H, type

    -DB 7F00:0100  <Enter>

    The contents of the range of memory addresses are displayed in the
    following format:

7F00:0100  20 64 65 76 69 63 65 0D-0A 00 60 39 0D 0A 00 7C  device...'9...|
7F00:0110  39 08 20 08 00 81 39 04-1B 5B 32 4A 42 BD 11 44 9....9..[2JB=.D
7F00:0120  2E 26 45 AF 11 47 B3 11-48 A5 11 4C B8 11 4E D3 .&E/.G3.H%.L8.NS
7F00:0130  11 50 DF 11 51 AB 11 54-DF 1E 56 37 11 5F 9F 16 .P_.Q+.T_.V7._..
7F00:0140  24 C0 11 00 03 4E 4F 54-C1 07 0A 45 52 52 4F 52 $@...NOTA..ERROR
7F00:0150  4C 45 56 45 4C 85 08 05-45 58 49 53 54 18 08 00 LEVEL...EXIST...
7F00:0160  03 44 49 52 03 91 0C 06-52 45 4E 41 4D 45 01 C0 .DIR....RENAME.@
7F00:0170  0F 03 52 45 4E 01 C0 0F-05 45 52 41 53 45 01 68 ..REN.@..ERASE.h

    To view the next 128 bytes of memory, type

    -D  <Enter>

    SYMDEB displays the contents of memory addresses 7F00:0180H through
    7F00:01FFH.



SYMDEB: DD
Display Doublewords


Purpose

    Displays the contents of memory in hexadecimal doubleword
    format.

Syntax

    DD [range]

    where:

    range      specifies the starting and ending addresses or the
                starting address and length of the area of memory to be
                displayed.

Description

    The Display Doublewords (DD) command displays the contents of a
    specified range of memory addresses 4 bytes at a time, as if they were
    FAR memory pointers (offset followed by segment in reverse byte
    order).

    The range parameter specifies the starting and ending addresses of
    the memory to be displayed or the starting address followed by the
    length of the area, expressed by an L and a hexadecimal number of
    doublewords. When range does not include a segment, SYMDEB uses DS.

    If a Display command has not previously been used and range is
    omitted from a DD command, the display starts at the address specified
    in the target program's CS:IP registers. If a Display command has
    previously been used and range is omitted from a DD command, the
    display starts at the memory address following the last address
    displayed by the most recent Display command. When a range is not
    explicit in a DD command, 32 doublewords (128 bytes) are
    displayed.

    Each line of the display is formatted as a segment and offset,
    followed by the contents of 16 bytes of memory represented as 4 paired
    16-bit segments and offsets. The 4 bytes that make up the segment and
    offset of each doubleword pointer are displayed in reverse order from
    their actual storage in memory.

    See also PROGRAMMING UTILITIES: SYMDEB:ED.

Examples

    To see how DD represents the 4 bytes that make up a doubleword,
    first type

    -DB 100  <ENTER>

    This produces the following output:

3929:0100  CF 0B 9D 0D 33 0E C3 0E-F2 0E 06 0F 39 0F 49 0F 0...3.C.r...9.I.

    Then type

    -DD 100  <Enter>

    This produces the following output:

    3929:0100  0D9D:0BCF 0EC3:0E33 0F06:0EF2 0F49:0F39

    Notice that DD switches the order of the first 2 bytes in a 4-byte set
    and designates them as the offset; then it switches the order of the
    second 2 bytes in the 4-byte set and designates them as the segment
    address.

    To display the contents of the first 128 (80H) bytes of the system
    interrupt vector table, which is based at address 0000:0000H, type

    -DD 0:0  <Enter>

    This produces the following output:

    0000:0000  2075:03D2 0070:01F0 16F3:2C1B 0070:01F0
    0000:0010  0070:01F0 F000:FF54 F000:9805 F000:9805
    0000:0020  0AE3:0395 16F3:2BAD F000:9805 F000:9805
    0000:0030  0972:0B40 F000:9805 F000:EF57 0070:01F0
    0000:0040  0AE3:03D6 F000:F84D F000:F841 0070:0D43
    0000:0050  F000:E739 F000:F859 F000:E82E F000:EFD2
    0000:0060  F000:E76C 0070:0ADD F000:FE6E 1078:3BEC
    0000:0070  F000:FF53 F000:F0E4 0000:0522 F000:0000

    To view the next 128 bytes of memory in the same format, type

    -D  <Enter>

    SYMDEB displays the contents of memory addresses 0000:0080H through
    0000:00FFH.



SYMDEB: DL
Display Long Reals


Purpose

    Displays the contents of memory as long (64-bit) floating-point
    numbers.

Syntax

    DL [range]

    where:

    range      specifies the starting and ending addresses or the
                starting address and length of the area of memory to be
                displayed.

Description

    The Display Long Reals (DL) command displays the contents of a
    specified range of memory addresses 8 bytes at a time, as hexadecimal
    values and their decimal equivalents. The hexadecimal values are
    formatted as 64-bit floating-point numbers. The decimal values have
    the form

    +|-0.decimaldigitsE+|-mantissa

    The sign of the number (+ or -) is followed by a zero, a decimal
    point, and a maximum of 16 decimaldigits; this, in turn, is followed
    by the designator of the mantissa (E) and the mantissa's sign (+ or -)
    and digits.

    The range parameter specifies the starting and ending addresses of
    the memory to be displayed or the starting address followed by the
    length of the area, expressed by an L and a hexadecimal number of 8-
    byte values. When range does not include a segment, SYMDEB uses DS.

    If a Display command has not previously been used and range is
    omitted from a DL command, the display starts at the address specified
    in the target program's CS:IP registers. If a Display command has
    previously been used and range is omitted from a DL command, the
    display starts at the memory address following the last address
    displayed by the most recent Display command. When a range is not
    explicit in a DL command, one 64-bit floating-point number is
    displayed.

    Each line of the display is formatted as a segment and offset,
    followed by the contents of 8 bytes of memory represented as a
    hexadecimal value, followed by its decimal floating-point
    equivalent.

    See also PROGRAMMING UTILITIES: SYMDEB:EL.

Examples

    Assume that the memory beginning at location DS:0100H contains the
    value 6.624 * 10^-27 (Planck's constant, in erg-seconds) as a 64-
    bit floating-point number. The command

    -DL 100  <Enter>

    produces the following output:

    43E8:0100  5F A2 20 73 75 66 80 3A  +0.6624E-26

    To view the next 8 bytes of memory in the same format, type

    -D  <Enter>



SYMDEB: DS
Display Short Reals


Purpose

    Displays the contents of memory as short (32-bit) floating-point
    numbers.

Syntax

    DS [range]

    where:

    range      specifies the starting and ending addresses or the
                starting address and length of the area of memory to be
                displayed.

Description

    The Display Short Reals (DS) command displays the contents of a
    specified range of memory addresses 4 bytes at a time, as hexadecimal
    values and their decimal equivalents. The hexadecimal values are
    formatted as 32-bit floating-point numbers. The decimal values have
    the form

    +|-0.decimaldigitsE+|-mantissa

    The sign of the number (+ or -) is followed by a zero, a decimal
    point, and a maximum of 16 decimaldigits (only the first 7 digits are
    significant); this, in turn, is followed by the designator of the
    mantissa (E) and the mantissa's sign (+ or -) and digits.

    The range parameter specifies the starting and ending addresses of
    the area of memory to be displayed or the starting address followed by
    the length of the area, expressed by an L and a hexadecimal number of
    4-byte values. When range does not include a segment, SYMDEB uses DS.

    If a Display command has not previously been used and range is
    omitted from a DS command, the display starts at the address specified
    in the target program's CS:IP registers. If a Display command has
    previously been used and range is omitted from a DS command, the
    display starts at the memory address following the last address
    displayed by the most recent Display command. When a range is not
    explicit in a DS command, one 32-bit floating-point number is
    displayed.

    Each line of the display is formatted as a segment and offset,
    followed by the contents of 4 bytes of memory represented as a
    hexadecimal value, followed by its decimal floating-point
    equivalent.

    See also PROGRAMMING UTILITIES: SYMDEB:ES.

Examples

    Assume that the memory beginning at location 43E8:0100H contains the
    value 6.02 * 10^+23 (Avogadro's number) as a 32-bit floating-point
    number. The command

    -DS 43E8:100  <Enter>

    produces the following output:

    43E8:0100  F9 F4 FE 66  +0.6020000172718952E+24

    To view the next 4 bytes of memory in the same format, type

    -D  <Enter>



SYMDEB: DT
Display 10-Byte Reals


Purpose

    Displays the contents of memory as 10-byte (80-bit) floating-point
    numbers.

Syntax

    DT [range]

    where:

    range      specifies the starting and ending addresses or the
                starting address and length of the area of memory to be
                displayed.

Description

    The Display 10-Byte Reals (DT) command displays the contents of a
    specified range of memory addresses 10 bytes at a time, as hexadecimal
    values and their decimal equivalents. The hexadecimal values are
    formatted as 80-bit floating-point numbers. (This format is ordinarily
    used by the Intel 8087 math coprocessor only for intermediate results
    during chained floating-point calculations.)  The decimal value has
    the form

    +|-0.decimaldigitsE+|-mantissa

    The sign of the number (+ or -) is followed by a zero, a decimal
    point, and a maximum of 16 decimaldigits; this, in turn, is followed
    by the designator of the mantissa (E) and the mantissa's sign (+ or -)
    and digits.

    The range parameter specifies the starting and ending addresses of
    the area of memory to be displayed or the starting address followed by
    the length of the area, expressed by an L and a hexadecimal number of
    10-byte values. When range does not include a segment, SYMDEB uses
    DS.

    If a Display command has not previously been used and range is
    omitted from a DT command, the display starts at the address specified
    in the target program's CS:IP registers. If a Display command has
    previously been used and range is omitted from a DT command, the
    display starts at the memory address following the last address
    displayed by the most recent Display command. When a range is not
    explicit in a DT command, one 10-byte floating-point number is
    displayed.

    Each line of the display is formatted as a segment and offset,
    followed by the contents of 10 bytes of memory represented as a
    hexadecimal value, followed by its decimal floating-point
    equivalent.

    See also PROGRAMMING UTILITIES: SYMDEB:ET.

Examples

    Assume that the memory beginning at location DS:0100H contains the
    value 2.99 * 10^+10 (the speed of light in centimeters per second)
    as an 80-bit floating-point number. The command

    -DT 100  <Enter>

    produces the following output:

    43E8:0100  00 00 00 00 60 B9 C5 DE 21 40  +0.299E+11

    To view the next 10 bytes of memory in the same format, type

    -D  <Enter>



SYMDEB: DW
Display Words


Purpose

    Displays the contents of memory as 2-byte (16-bit) words.

Syntax

    DW [range]

    where:

    range      specifies the starting and ending addresses or the
                starting address and length of the area of memory to be
                displayed.

Description

    The Display Word (DW) command displays the contents of a specified
    range of memory addresses 2 bytes at a time, as 16-bit hexadecimal
    integers.

    The range parameter specifies the starting and ending addresses of
    the area of memory to be displayed or the starting address followed by
    the length of the area, expressed by an L and a hexadecimal number of
    words of memory to be displayed. When range does not include a
    segment, SYMDEB uses DS.

    If a Display command has not previously been used and range is
    omitted from a DW command, the display starts at the address specified
    in the target program's CS:IP registers. If a Display command has
    previously been used and range is omitted from a DW command, the
    display starts at the memory address following the last address
    displayed by the most recent Display command. When a range is not
    explicit in a DW command, 64 words are displayed.

    Each line of the display is formatted as a segment and offset,
    followed by the contents of 16 bytes of memory represented as eight 4-
    digit hexadecimal numbers. The 2 bytes that make up each word are
    displayed in reverse order from their actual storage in memory. That
    is, the first byte in a 2-byte word is displayed after the second
    byte.

    See also PROGRAMMING UTILITIES: SYMDEB:EW.

Examples

    To display the contents of the 64 words of memory beginning at
    DS:0080H in word format, type

    -DW 80  <Enter>

    This produces the following output:

    1FEE:0080  6977 646E 776F 5C73 696C 0062 494C 3D42
    1FEE:0090  3A63 6D5C 6373 6C5C 6269 633B 5C3A 6977
    1FEE:00A0  646E 776F 5C73 696C 0062 4D54 3D50 3A63
    1FEE:00B0  745C 6D65 0070 4554 504D 633D 5C3A 6574
    1FEE:00C0  706D 4400 4149 3D4C 3A63 645C 6169 006C
    1FEE:00D0  4350 3346 3D32 3A63 665C 726F 6874 705C
    1FEE:00E0  3363 0032 4350 3350 3D32 3A63 665C 726F
    1FEE:00F0  6874 705C 756C 3373 0032 5255 3146 3D30

    To view the next 64 words of memory in the same format, type

    -D  <Enter>

    SYMDEB displays the contents of memory addresses 1FEE:0100H through
    1FEE:017FH.



SYMDEB: E
Enter Data


Purpose

    Enters data into memory.

Syntax

    E address [list]

    where:

    address    is the first memory location for storage.

    list       is the data to be placed into successive bytes of memory,
                starting at address.

Description

    The Enter Data (E) command enters into memory one or more data items,
    using the same format as the most recent Enter command (EA, EB, ED,
    EL, ES, ET, or EW). If no Enter command has previously been used, the
    data can be entered as either hexadecimal values or ASCII strings (the
    EA or EB format). Any data previously stored at the specified
    locations is lost. If SYMDEB displays an error message, no changes are
    made.

    The address parameter specifies the first byte to be modified. If
    address does not include a segment, SYMDEB uses DS. SYMDEB increments
    the address for each byte of data stored.

    The list parameter must meet the requirements of the last Enter
    command used. All SYMDEB Enter commands are described in alphabetic
    order on the following pages. If list is included in the command line,
    the changes are made unless an error is detected in the command line.
    If list is omitted from the command line, the current contents of
    address are displayed, followed by a period (.), and the user is
    prompted for new data. If no value is entered and the Enter key is
    pressed, the original value remains unchanged and the Enter command is
    terminated.

Examples

    The following two examples assume that no previous Enter commands have
    been used or that the most recent Enter command was EA or EB.

    To store the byte values 00H, 0DH, and 0AH into the 3 bytes beginning
    at DS:1FB3H, type

    -E 1FB3 00 0D 0A  <Enter>

    If the command

    -E 2C3 ABC  <Enter>

    is entered and the last Enter command used was EA or EB, the value BCH
    is stored at DS:2C3H, and the leading `A' character on the hexadecimal
    number `ABC' is ignored.



SYMDEB: EA
Enter ASCII String


Purpose

    Enters an ASCII string or hexadecimal byte values into memory.

Syntax

    EA address [list]

    where:

    address    is the first memory location for storage.

    list       is one or more ASCII strings or hexadecimal byte values.

Description

    The Enter ASCII String (EA) command enters data into successive memory
    bytes. The data can be entered as either hexadecimal byte values or
    ASCII strings. Any data previously stored at the specified locations
    is lost. If SYMDEB displays an error message, no changes are made. The
    EA command functions exactly like the Enter Bytes (EB) command.

    The address parameter specifies the first byte to be modified. If
    address does not include a segment, SYMDEB uses DS. SYMDEB increments
    the address for each byte of data stored.

    The list parameter is one or more ASCII strings and/or hexadecimal
    byte values, separated by spaces, commas, or tab characters. Extra or
    trailing characters are ignored. Strings must be enclosed within
    single or double quotation marks, and case is significant within a
    string.

    If list is included in the command line, the changes are made unless
    an error is detected in the command line. If list is omitted from the
    command line, the user is prompted byte by byte for new data, starting
    at address. The current contents of a byte are displayed, followed by
    a period. A new value for that byte can be entered as one or two
    hexadecimal digits (extra characters are ignored), or the contents can
    be left unchanged. To display the next byte, the user presses the
    spacebar. If the user enters a minus sign, or hyphen character (-),
    instead of pressing the spacebar, SYMDEB backs up to the previous
    byte. A maximum of 8 bytes can be entered on each input line; a new
    line is begun each time an 8-byte boundary is crossed. Data entry is
    terminated by pressing the Enter key without pressing the spacebar or
    entering any data.

    Text strings can be used only as part of the list parameter in an EA
    command line; they cannot be entered in response to an address prompt.

Example

    To store the string MAIN MENU into memory beginning at address
    ES:0C14H, type

    -EA ES:C14 "MAIN MENU"  <Enter>



SYMDEB: EB
Enter Bytes


Purpose

    Enters hexadecimal byte values or ASCII strings into memory.

Syntax

    EB address [list]

    where:

    address    is the first memory location for storage.

    list       is one or more hexadecimal byte values or ASCII strings.

Description

    The Enter Bytes (EB) command enters data into successive memory bytes.
    The data can be entered as either hexadecimal byte values or ASCII
    strings. Any data previously stored at the specified locations is
    lost. If SYMDEB displays an error message, no changes are made. The EB
    command functions exactly like the Enter ASCII String (EA) command.

    The address parameter specifies the first byte to be modified. If
    address does not include a segment, SYMDEB uses DS. SYMDEB increments
    the address for each byte of data stored.

    The list parameter is one or more hexadecimal byte values and/or
    ASCII strings, separated by spaces, commas, or tab characters. Extra
    or trailing characters are ignored. Strings must be enclosed within
    single or double quotation marks, and case is significant within a
    string.

    If list is included in the command line, the changes are made unless
    an error is detected in the command line. If list is omitted from the
    command line, the user is prompted byte by byte for new data, starting
    at address. The current contents of a byte are displayed, followed by
    a period. A new value for the byte can be entered as one or two
    hexadecimal digits (extra characters are ignored), or the contents can
    be left unchanged. To display the next byte, the user presses the
    spacebar. If the user enters a minus sign, or hyphen character (-),
    instead of pressing the spacebar, SYMDEB backs up to the previous
    byte. A maximum of 8 bytes can be entered on each input line; a new
    line is begun each time an 8-byte boundary is crossed. Data entry is
    terminated by pressing the Enter key without pressing the spacebar or
    entering any data.

    Text strings can be used only as part of the list parameter in an EB
    command line; they cannot be entered in response to an address prompt.

Examples

    To store the byte values 00H, 0DH, and 0AH into the 3 bytes beginning
    at DS:1FB3H, type

    -EB 1FB3 00 0D 0A  <Enter>

    To store the string MAIN MENU into memory beginning at address
    ES:0C14H, type

    -EB ES:C14 "MAIN MENU"  <Enter>



SYMDEB: ED
Enter Doublewords


Purpose

    Enters hexadecimal doubleword values into memory.

Syntax

    ED address [value]

    where:

    address    is the first memory location for storage.

    value      is a doubleword (32-bit) hexadecimal value.

Description

    The Enter Doublewords (ED) command enters into memory 32-bit
    hexadecimal doubleword values in the form of FAR memory pointers
    (offset followed by segments in reverse byte order). Any data
    previously stored at the specified locations is lost. If SYMDEB
    displays an error message, no changes are made.

    The address parameter specifies the first memory location to be
    modified. If address does not include a segment, SYMDEB uses DS.

    The value parameter is one doubleword value, entered as two 16-bit
    hexadecimal words separated by a colon character (:). Each value is
    entered in the form segment:offset. The offset portion is stored at
    address, and the segment portion is stored at address+2, both in
    reverse byte order. For example, a value of AABB:CCDDH would be stored
    in memory as DDH, CCH, BBH, and AAH, starting at address. Multiple
    values cannot be used in an ED command line; SYMDEB ignores any values
    after the first value.

    If value is omitted from the command line, SYMDEB prompts the user
    for new data, starting at address. The current contents of the
    location are displayed, followed by a period. The user can then enter
    a new doubleword value and press the Enter key or leave the contents
    unchanged by pressing the Enter key alone, which also terminates the
    ED command. If a new value is entered, SYMDEB increments address and
    displays the next doubleword value.

Example

    To store the doubleword value F000:1392H at the address DS:0200H,
    type

    -ED 200 F000:1392  <Enter>



SYMDEB: EL
Enter Long Reals


Purpose

    Enters 64-bit floating-point numbers into memory.

Syntax

    EL address [value]

    where:

    address    is the first memory location for storage.

    value      is a 64-bit floating-point decimal number.

Description

    The Enter Long Reals (EL) command enters into memory 64-bit floating-
    point numbers in decimal format. Any data previously stored at the
    specified memory locations is lost. If SYMDEB displays an error
    message, no changes are made.

    The address parameter specifies the first byte to be modified. If
    address does not include a segment, SYMDEB uses DS.

    The value parameter is a floating-point number entered in decimal
    radix, with or without a decimal point and/or exponent. Multiple
    values cannot be used in an EL command line; SYMDEB ignores any
    values after the first value.

    The 64-bit floating-point decimal value must be entered in the
    form

    [+|-]decimaldigits[E[+|-]mantissa]

    where:

    +|-             is the sign of the long floating-point value or the
                    mantissa.

    decimaldigits   is a decimal number. A maximum of 16 digits is
                    allowed, including digits before and after a decimal
                    point.

    E               denotes the beginning of the mantissa.

    mantissa        is the decimal mantissa value.

    If value is omitted from the command line, SYMDEB prompts the user
    for new data, starting at address. The current contents of the
    location are displayed. The user can enter a new value and press the
    Enter key or leave the contents unchanged by pressing the Enter key
    alone, which also terminates the EL command. If a new value is entered
    and the Enter key is pressed, SYMDEB increments address and displays
    the next long real number.

Example

    To store an approximation of the value pi in the form of a 64-
    bit floating-point number at address DS:0020H, type

    -EL 20 +0.3141592653589793E+1  <Enter>

    or

    -EL 20 3.141592653589793  <Enter>



SYMDEB: ES
Enter Short Reals


Purpose

    Enters 32-bit floating-point numbers into memory.

Syntax

    ES address [value]

    where:

    address    is the first memory location for storage.

    value      is a 32-bit floating-point decimal number.

Description

    The Enter Short Reals (ES) command enters into memory 32-bit floating-
    point numbers in decimal format. Any data previously stored at the
    specified locations is lost. If SYMDEB displays an error message, no
    changes are made.

    The address parameter specifies the first byte to be modified. If
    address does not include a segment, SYMDEB uses DS.

    The value parameter is a floating-point number entered in decimal
    radix, with or without a decimal point and/or exponent. Multiple
    values cannot be used in an ES command line; SYMDEB ignores any values
    after the first value.

    The 32-bit floating-point decimal value must be entered in the
    form

    [+|-]decimaldigits[E[+|-]mantissa]

    where:

    +|-             is the sign of the short floating-point value or the
                    mantissa.

    decimaldigits   is a decimal number. A maximum of 16 digits is
                    allowed, including digits before and after a decimal
                    point.

    E               denotes the beginning of the mantissa.

    mantissa        is the decimal mantissa value.

    Note: For short floating-point values, the last nine decimaldigits
    are not significant. This can be demonstrated by using the Display
    Short Reals (DS) command to check the new value in memory.

    If value is omitted from the command line, SYMDEB prompts the user
    for new data, starting at address. The current contents of the
    location are displayed. The user can then enter a new value and press
    the Enter key or leave the contents unchanged by pressing the Enter
    key alone, which also terminates the ES command. If a new value is
    entered and the Enter key is pressed, SYMDEB increments address and
    displays the next short floating-point number.

Example

    To store an approximation of the value pi in the form of a 32-bit
    floating-point number at address DS:0020H, type

    -ES 20 +0.31415927E+1  <Enter>

    or

    -ES 20 3.1415927  <Enter>



SYMDEB: ET
Enter 10-Byte Reals


Purpose

    Enters 10-byte (80-bit) floating-point numbers into memory.

Syntax

    ET address [value]

    where:

    address    is the first memory location for storage.

    value      is an 80-bit floating-point decimal number.

Description

    The Enter 10-Byte Reals (ET) command enters into memory 10-byte (80-
    bit) floating-point numbers in decimal format. Any data previously
    stored at the specified locations is lost. If SYMDEB displays an error
    message, no changes are made. (This 10-byte format is ordinarily used
    by the Intel 8087 math coprocessor only for intermediate results
    during chained floating-point calculations.)

    The address parameter specifies the first memory location to be
    modified. If address does not include a segment, SYMDEB uses DS.

    The value parameter is a floating-point number entered in decimal
    radix, with or without a decimal point and/or exponent. Multiple
    values cannot be used in an ET command line; SYMDEB ignores any values
    after the first value.

    The 10-byte floating-point decimal value must be entered in the form

    [+|-]decimaldigits[E[+|-]mantissa]

    where:

    +|-             is the sign of the 10-byte floating-point value or
                    the mantissa.

    decimaldigits   is a decimal number. A maximum of 16 digits is
                    allowed, including digits before and after a decimal
                    point.

    E               denotes the beginning of the mantissa.

    mantissa        is the decimal mantissa value.

    If value is omitted from the command, SYMDEB prompts the user for new
    data, starting at address. The current contents are displayed. The
    user can enter a new value and press the Enter key or leave the
    contents unchanged by pressing the Enter key alone, which also
    terminates the ET command. If a new value is entered and the Enter key
    is pressed, SYMDEB increments address and displays the next 10-byte
    floating-point number.

Example

    To store an approximation of the value pi in the form of an 80-
    bit floating-point number at address DS:0020H, type

    -ET 20 +0.31415926535897932384E+1  <Enter>

    or

    -ET 20 3.1415926535897932384  <Enter>



SYMDEB: EW
Enter Words


Purpose

    Enters word values into memory.

Syntax

    EW address [value]

    where:

    address    is the first memory location for storage.

    value      is a word (16-bit) hexadecimal value.

Description

    The Enter Words (EW) command enters into memory 16-bit hexadecimal
    word values. Any data previously stored at the specified locations is
    lost. If SYMDEB displays an error message, no changes are made.

    The address parameter specifies the first memory location to be
    modified. If address does not include a segment, SYMDEB uses DS.

    The value parameter is one word value in the range 0 through FFFFH.
    The value is stored in reverse byte order. For example, a value of
    AABBH would be stored in memory as BBH and AAH, starting at address.
    Multiple values cannot be used in an EW command line; SYMDEB ignores
    any values after the first value.

    If value is omitted from the command line, SYMDEB prompts the user
    word by word for new data, starting at address. The current contents
    are displayed, followed by a period. The user can enter a new word
    value as one to four hexadecimal digits and press the Enter key or
    leave the contents unchanged by pressing the Enter key alone, which
    also terminates the EW command. If a new value is entered, SYMDEB
    increments address and displays the next word value.

Example

    To store the word value 1355H at the address DS:1C00H, type

    -EW 1C00 1355 <Enter>



SYMDEB: F
Fill Memory


Purpose

    Stores a repetitive data pattern into an area of memory.

Syntax

    F range list

    where:

    range      specifies the starting and ending addresses or the
                starting address and length of memory to be filled.

    list       is the data to be used to fill memory.

Description

    The Fill Memory (F) command fills an area of memory with the data from
    a list. The data can be entered in either hexadecimal or ASCII format.
    Any data previously stored at the specified locations is lost. If
    SYMDEB displays an error message, no changes are made.

    The range parameter specifies the starting and ending addresses or
    the starting address and hexadecimal length in bytes of the area of
    memory to be filled. If range does not include an explicit segment,
    SYMDEB uses DS.

    The list parameter is one or more hexadecimal byte values and/or
    strings, separated by spaces, commas, or tab characters. Strings must
    be enclosed in single or double quotation marks, and case is
    significant within a string.

    If the area to be filled is larger than the data list, the list is
    repeated as often as necessary to fill the area. If the data list is
    longer than the area of memory to be filled, the list is truncated to
    fit.

Examples

    To fill the area of memory from DS:0B10H through DS:0B4FH with the
    value 0E8H, type

    -F B10 B4F E8  <Enter>

    or

    -F B10 L40 E8  <Enter>

    To fill the 16 bytes of memory beginning at address CS:1FA0H by
    replicating the 2-byte sequence 0DH 0AH, type

    -F CS:1FA0 1FAF 0D 0A  <Enter>

    or

    -F CS:1FA0 L10 0D 0A  <Enter>

    To fill the area of memory from ES:0B00H through ES:0BFFH by
    replicating the text string BUFFER, type

    -F ES:B00 BFF "BUFFER"  <Enter>

    or

    -F ES:B00 L100 "BUFFER"  <Enter>



SYMDEB: G
Go


Purpose

    Transfers execution control from SYMDEB to the target program being
    debugged.

Syntax

    G[=address] [break0[... break9]]

    where:

    address                is the location at which to begin execution.

    break0 ... break9      specify from 1 to 10 breakpoints.

Description

    The Go (G) command transfers control from SYMDEB to the target
    program. If no breakpoints are set, the program will execute until it
    crashes or until it reaches a normal termination, in which case the
    message Program terminated normally is displayed and control returns
    to SYMDEB. (After this message has been displayed, it may be necessary
    to reload the program before it can be executed again.)

    The address parameter can be any location in memory. If no segment is
    specified, SYMDEB uses the target program's CS register. If address
    is omitted, SYMDEB transfers to the current address in the target
    program's CS:IP registers. An equal sign (=) must precede address to
    distinguish it from the breakpoints break0 ... break9.

    The parameters break0 ... break9 specify from 1 to 10 breakpoints
    that can be set as part of the G command. Breakpoints can be placed in
    any order, because execution stops at the first breakpoint address
    encountered, regardless of the position of that breakpoint in the
    list. Each of the breakpoint addresses must contain the first byte of
    an 8086 opcode. SYMDEB installs breakpoints by replacing the first
    byte of the machine instruction at each breakpoint address with an
    Interrupt 03H instruction (opcode 0CCH). If the program encounters a
    breakpoint, program execution is suspended and control returns to
    SYMDEB. SYMDEB then restores the original machine code in the
    breakpoint locations, displays the contents of the current registers
    and flags and the instruction pointed to by CS:IP, and issues the
    standard SYMDEB prompt. If the target program executes to completion
    and terminates without encountering any of the breakpoints or is
    halted by some means other than a breakpoint, the Interrupt 03H
    instructions are not replaced with the original machine code and the
    Load File or Sectors (L) command must be used to reload the original
    program.

    The G command requires that the target program's SS:SP registers point
    to a valid stack that has at least 6 bytes of stack space available.
    When the G command is executed, it pushes the target program's flags
    and CS and IP registers onto the stack and then transfers control to
    the program with an IRET instruction. Thus, if the target program's
    stack is not valid or is too small, the system may crash.

    The G command also recognizes any sticky breakpoints set with the Set
    Breakpoint (BP) command. These sticky breakpoints are not counted as
    part of the transient breakpoints specified in the G command line and
    are not removed after a breakpoint has been encountered.

Examples

    To begin execution of the program in SYMDEB's buffer at location
    CS:110AH, setting breakpoints at CS:12FCH and CS:1303H, type

    -G =110A 12FC 1303  <Enter>

    To resume execution of the program following a breakpoint, type

    -G  <Enter>

    To begin execution at the label main, setting breakpoints at the
    procedures fopen() and printf(), type

    -G =_main _fopen _printf  <Enter>

Messages

    Program terminated normally
    The program being debugged executed successfully without encountering
    any breakpoints and performed a normal termination with Interrupt 20H,
    Interrupt 21H Function 00H, or Interrupt 21H Function 4CH. If any
    breakpoints were set, the original program should be reloaded with the
    Load File or Sectors (L) command.

    Too many breakpoints!
    More than 10 breakpoints were specified in a Go (G) command. Enter the
    command again with 10 or fewer breakpoints.



SYMDEB: H
Perform Hexadecimal Arithmetic


Purpose

    Displays the sum and difference of two hexadecimal numbers.

Syntax

    H value1 value2

    where:

    value1 and value2     are any two hexadecimal numbers in the range 0
                        through FFFFH.

Description

    The Perform Hexadecimal Arithmetic (H) command displays the sum and
    difference of two 16-bit hexadecimal numbers--that is, the result of
    the operations value1+value2 and value1-value2. If value2 is
    greater than value1, SYMDEB displays their difference as a two's
    complement hexadecimal number. This command is convenient for
    performing quick calculations of addresses and other values during an
    interactive debugging session.

Examples

    To display the sum and difference of the values 4B03H and 104H,
    type

    -H 4B03 104  <Enter>

    This produces the following display:

    4C07  49FF

    If the addition produces an overflow, the four least significant
    digits are displayed. For example, the command line

    -H FFFF 2  <Enter>

    produces the following display:

    0001 FFFD

    If value2 is greater than value1, the difference is displayed in
    two's complement form. For example, the command line

    -H 1 2  <Enter>

    produces the following display:

    0003 FFFF



SYMDEB: I
Input from Port


Purpose

    Reads and displays 1 byte from an input/output (I/O) port.

Syntax

    I port

    where:

    port       is a 16-bit I/O port address in the range 0 through FFFFH.

Description

    The Input from Port (I) command performs a read operation on the
    specified I/O port address and displays the data as a two-digit
    hexadecimal number.

    Warning: This command must be used with caution because it involves
    direct access to the computer hardware and no error checking is
    performed. Input operations directed to the ports assigned to some
    peripheral device controllers may interfere with the proper operation
    of the system. If no device has been assigned to the specified I/O
    port or if the port is write-only, the value that will be displayed by
    an I command is unpredictable.

Example

    To read and display the contents of I/O port 10AH, type

    -I 10A  <Enter>

    An example of the result of this command is

    FF



SYMDEB: K
Perform Stack Trace


Purpose

    Displays the current stack frame.

Syntax

    K [number]

    where:

    number     is the number of parameters supplied to the current
                procedure.

Description

    The Perform Stack Trace (K) command displays the contents of the
    current stack frame. The first line of the display shows the name of
    the current procedure, parameters to the procedure, and the filename
    and line number of the call to the procedure. The subsequent lines
    trace the flow of execution that led to the current procedure.

    In cases where SYMDEB cannot determine the number of parameters for a
    procedure by inspection of the stack frame (for example, if the number
    of parameters sent to a procedure varies), the number option can be
    used in the command to force the display of one or more
    parameters.

    The K command can be used only on procedures that follow the calling
    conventions used by Microsoft high-level-language compilers.

Examples

    Assume that a breakpoint has been set within the C library printf()
    routine, that the breakpoint has been reached, and that the SYMDEB
    prompt has reappeared. The command

    -K  <Enter>

    produces the following output:

    _TEXT:_printf(00D4,0000,0000) from .dump.C:108
    _TEXT:_dump_para(0000,0000,0FB8) from .dump.C:92
    _TEXT:_dump_rec(0FB8,0001,0000,0000) from .dump.C:61
    _TEXT:_main(?)

    In this example, the breakpointed procedure printf() was called by
    the routine dump_para() with three parameters. Dump_para() was
    called by dump_rec(),  which in turn was called by main(). Because
    SYMDEB cannot determine the depth of the stack frame for the routine
    main(), it displays no parameters for it. The display of at least two
    parameters for every procedure can be forced by the command

    -K 2  <Enter>

    which produces the following example display:

    _TEXT:_printf(00D4,0000,0000) from .dump.C:108
    _TEXT:_dump_para(0000,0000,0FB8) from .dump.C:92
    _TEXT:_dump_rec(0FB8,0001,0000,0000) from .dump.C:61
    _TEXT:_main(0002,1044)

    From a knowledge of C conventions, it follows that the first parameter
    for main() is argc, or the number of tokens in the command line that
    invoked the program being debugged; the second parameter is the offset
    within DGROUP of argv, or an array of pointers to each token.



SYMDEB: L
Load File or Sectors


Purpose

    Loads a file or individual sectors from a disk.

Syntax

    L [address]

    or

    L address drive start number

    where:

    address    is the starting address in memory that data read from a
                disk is placed into.

    drive      is the decimal number (0-3) of the disk to read
                (0 = drive A, 1 = drive B, 2 = drive C, 3= drive D).

    start      is the hexadecimal number of the first sector to load
                (0-FFFFH).

    number     is the hexadecimal number of consecutive sectors to load
                (0-FFFFH).

Description

    The Load File or Sectors (L) command loads a file or individual
    sectors from a disk.

    When the L command is entered without parameters or with an address
    alone, the file specified in the SYMDEB command line or with the most
    recent Name File or Command-Tail Parameters (N) command is loaded from
    the disk into memory. If no segment is specified in address, SYMDEB
    uses CS. If the file's extension is .EXE, the file is placed in
    SYMDEB's target program buffer at the load address specified in the
    .EXE file's header; if the file's extension is .COM, the file is
    loaded at offset 100H. (If for some reason an address is entered for a
    .EXE or .COM file and the address is anything but 100H, an error
    message is displayed; if the address is 100H, it will be ignored.) If
    the file has a .HEX extension, the .HEX file's starting address is
    added to address before loading the file. If address is not
    specified, the .HEX file is placed at its own starting address. The
    length of the file or, in the case of a .EXE file, the actual length
    of the program (the length of the file minus the header) is placed in
    the target program's BX and CX registers, with the most significant 16
    bits in register BX.

    The L command can also be used to bypass the MS-DOS file system and
    obtain direct access to logical sectors on the disk. The memory
    address (address), disk drive number (drive), starting logical sector
    number (start), and number of sectors to read (number) must all be
    specified in the command line.

    Note: The L command should not be used to access logical sectors on
    network drives.

Examples

    To load the file specified in the SYMDEB command line or in the most
    recent N command into SYMDEB's target program buffer, type

    -L  <Enter>

    To load eight sectors from drive B, starting at logical sector 0, to
    memory location CS:0100H in SYMDEB's memory buffer, type

    -L 100 1 0 8  <Enter>

Messages

    Disk error reading disk  <FI>X<FS>
    A hardware-related disk error, such as a checksum error or seek
    incomplete, was encountered during the execution of an L command.

    File not found
    The file specified in the most recent N command cannot be found.



SYMDEB: M
Move (Copy) Data


Purpose

    Copies the contents of one area of memory to another.

Syntax

    M range address

    where:

    range      specifies the starting and ending addresses or the
                starting address and length of the area of memory to be
                copied.

    address    is the first byte of the destination of the copy
                operation.

Description

    The Move (Copy) Data (M) command copies data from one location in
    memory to another without altering the data in the original location.
    If the source and destination areas overlap, the data is copied in the
    correct order so that the resulting copy is correct; the data in the
    original location is changed only when the two areas overlap.

    The range parameter specifies the starting and ending addresses or
    the starting address and length of the memory to be copied. The
    address parameter is the first byte in which the copy will be placed.
    If range does not contain an explicit segment, SYMDEB uses DS; if
    address does not contain a segment, SYMDEB uses the same segment used
    for range.

Example

    To copy the data in locations DS:0800H through DS:08FFH to locations
    DS:0900H through DS:09FFH, type

    -M 800 8FF 900  <Enter>

    or

    -M 800 L100 900  <Enter>



SYMDEB: N
Name File or Command-Tail Parameters


Purpose

    Inserts parameters into the simulated program segment prefix
    (PSP).

Syntax

    N parameter [parameter...]

    where:

    parameter       is a filename or switch to be placed into the
                    simulated PSP.

Description

    The Name File or Command-Tail Parameters (N) command is used to enter
    one or more parameters into the simulated PSP that is built at the
    base of the buffer holding the program to be debugged. The N command
    can also be used before the Load File or Sectors (L) and Write File or
    Sectors (W) commands to name a file to be read from a disk or written
    to a disk.

    The count of the characters following the N command is placed at
    DS:0080H in the simulated PSP and the characters themselves are copied
    into the PSP starting at DS:0081H. The string is terminated by a
    carriage return (0DH), which is not included in the count. If the
    second and third parameters follow the naming conventions for MS-DOS
    files, they are parsed into the default file control blocks (FCBs) in
    the simulated PSP, at offset 5CH and offset 6CH, respectively. Note
    that this is different from the N command in DEBUG, which loads the
    first and second parameters into the default FCBs. (Switches and other
    filenames specified as parameters are stored in the PSP starting at
    offset 81H along with the rest of the command line but are not parsed
    into the default FCBs.)

    If the N command line contains only one filename, any parameters
    placed in the default FCBs by a previous N command are destroyed. If
    the drive included with the second filename parameter is invalid, the
    AL register is set to 0FFH. If the drive included with the third
    filename parameter is invalid, the AH register is set to 0FFH. The
    existence of a file specified with the N command is not verified until
    it is loaded with the L command.

    The filename at DS:0081H specifies the file that is read or written by
    a subsequent L or W command.

Example

    Assume that SYMDEB was started without specifying the name of a target
    program in the command line. To load the program CLEAN.COM for
    execution under the control of SYMDEB and include the parameter
    MYFILE.DAT in the simulated PSP's command tail and FCB, use the N and
    L commands together as follows:

    -N CLEAN.COM  MYFILE.DAT  <Enter>
    -L  <Enter>

    To execute the program CLEAN.COM, type

    -G  <Enter>

    The net effect is the same as if the CLEAN.COM program had been run
    from the MS-DOS command level with the command line

    C>CLEAN MYFILE.DAT  <Enter>

    except that the program is executing under the control of SYMDEB and
    within SYMDEB's memory buffer.



SYMDEB: O
Output to Port


Purpose

    Writes 1 byte to an input/output (I/O) port.

Syntax

    O port byte

    where:

    port       is a 16-bit I/O port address in the range 0 through FFFFH.

    byte       is a value to be written to the I/O port (0-0FFH).

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 00H through
    0FFH.

    Warning: This command must be used with caution because it involves
    direct access to 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 may
    even result in damage to data stored on disk.

Example

    To write the value C8H to I/O port 10AH, type

    -O 10A C8  <Enter>



SYMDEB: P
Proceed Through Loop or Subroutine


Purpose

    Executes a loop, string instruction, software interrupt, or subroutine
    to completion.

Syntax

    P[=address] [number]

    where:

    address    is the location of the first instruction to be executed.

    number     is the number of instructions to execute.

Description

    The Proceed Through Loop or Subroutine (P) command transfers control
    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
    SYMDEB and the current contents of the target program's registers and
    flags are displayed.

    Warning: The P command should not be used to execute any instruction
    that changes the contents of the Intel 8259 interrupt mask (ports 20H
    and 21H on the IBM PC and compatibles) and cannot be used to trace
    through ROM. Use the Go (G) command instead.

    If the address parameter does not contain a segment, SYMDEB uses the
    target program's CS register; if address is omitted, execution begins
    at the current address specified by the target's CS:IP registers. The
    address parameter must be preceded by an equal sign (=) to
    distinguish it from number.

    The number parameter specifies the number of instructions to be
    executed before control returns to SYMDEB. If number is omitted, one
    instruction is executed.

    When the Enable Source Display Mode (S+) command is selected, the P
    command operates directly on source-code lines, passing over function
    or procedure calls. (The S+ command can be used only with programs
    created by high-level-language compilers that insert line-number
    information into object modules.)

    When source display mode is disabled with the S- command or when the
    program being debugged does not have a .SYM file or has been created
    with the Microsoft Macro Assembler (MASM) or with a compiler that does
    not support line numbers in relocatable object modules, the P command
    behaves like the Trace Program Execution (T) command except that when
    P encounters a loop, repeated string instruction, software interrupt,
    or subroutine call, it executes it to completion and then returns to
    the instruction following the call. For example, if the user wants to
    trace the first three instructions in a program and if the second
    instruction is a subroutine call, a P3 command executes the first
    instruction, goes to the second instruction, identifies it as a CALL
    instruction, jumps to the subroutine and executes the entire
    subroutine, comes back and executes the third instruction, and then
    stops. A T3 command, on the other hand, executes the first
    instruction, executes the second, executes the first instruction of
    the subroutine as its third instruction, and then stops. If the
    instruction at address is not a loop, repeated string instruction,
    software interrupt, or subroutine call, the P command functions just
    like the T command. After each instruction is executed, SYMDEB
    displays the current contents of the target program's registers and
    flags and the next instruction to be executed.

Examples

    Assume that the program being debugged was compiled with Microsoft C,
    a .SYM file was loaded with the executable program to provide line-
    number information, and source-code display has been enabled with the
    S+ command.  To execute the machine instructions corresponding to the
    next four lines of source code, type

    -P 4  <Enter>

    Assume that the target program was created with MASM and location
    CS:143FH contains a CALL instruction. To execute the subroutine that
    is the destination of CALL at full speed and then return control to
    SYMDEB, type

    -P =143F  <Enter>



SYMDEB: Q
Quit


Purpose

    Ends a SYMDEB session.

Syntax

    Q

Description

    The Quit (Q) command terminates the SYMDEB program and returns control
    to MS-DOS or the command shell that invoked SYMDEB. Any changes made
    to a program or other file that were not previously saved to disk with
    the Write File or Sectors (W) command are lost when the Q command is
    used.

Example

    To exit SYMDEB, type

    -Q  <Enter>



SYMDEB: R
Display or Modify Registers


Purpose

    Displays one or all registers and allows a register to be
    modified.

Syntax

    R

    or

    R register [[=] value]

    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, to indicate the CPU flags.

    =          is an optional equal sign preceding value.

    value      is a 16-bit integer (0-FFFFH) that will be assigned to
                the specified register.

Description

    The Display or Modify Registers (R) command allows the target
    program's register contents and CPU flags to be displayed and
    modified.

    If R is entered without a register parameter, the current contents of
    all registers and CPU flags are displayed, followed by a disassembly
    of the machine instruction currently pointed to by the target
    program's CS:IP registers.

    A register can be assigned a new value in a single command by entering
    both register and value parameters, optionally separated by an equal
    sign (=). If a register is named but no value is supplied, SYMDEB
    displays the current contents of the specified register and then
    prompts with a colon character (:) for a new value to be placed in the
    register. The user can enter the value in any valid radix or as an
    expression and then press the Enter key. If no radix is appended to
    the new value, hexadecimal is assumed. If the user presses the Enter
    key alone in response to the prompt, no changes are made to the
    register contents.

    Note: The PC register name is not supported properly in some versions
    of SYMDEB, so the IP register name should always be used
    instead.

    Use of the character F instead of a register name causes SYMDEB to
    display the current status of the traced program's CPU flags as a set
    of two-character codes from the following list:

╓┌─────────────────┌───────────────────┌─────────────────────────────────────╖
    Flag Name    Value If Set (1)    Value If Clear (0)
    ──────────────────────────────────────────────────────────────────────
    Overflow     OV (Overflow)       NV (No Overflow)
    Direction    DN (Down)           UP (Up)
    Interrupt    EI (Enabled)        DI (Disabled)
    Sign         NG (Minus)          PL (Plus)
    Zero         ZR (Zero)           NZ (Not Zero)
    Aux Carry    AC (Aux Carry)      NA (No Aux Carry)
    Parity       PE (Even)           PO (Odd)
    Carry        CY (Carry)          NC (No Carry)

    After displaying the current flag values, SYMDEB again displays its
    prompt (-). Any or all of the individual flags can then be altered by
    typing one or more two-character flag codes (in any order and
    optionally separated by spaces) from the list above and then pressing
    the Enter key. If the user responds to the prompt by pressing the
    Enter key without entering any codes, no changes are made to the
    status of the flags.

Examples

    To display the current contents of the target program's CPU registers
    and flags, followed by the disassembled mnemonic for the next
    instruction to be executed (pointed to by CS:IP), type

    -R  <Enter>

    This produces the following display:

    AX=0000  BX=0000  CX=00A1  DX=0000  SP=FFFE  BP=0000 SI=0000  DI=0000
    DS=19A5  ES=19A5  SS=19A5  CS=19A5  IP=0100   NV UP EI PL NZ NA PO NC
    19A5:0100 BF8000       MOV   DI,0080

    If the source display mode is enabled, the R command displays the
    following:

    AX=0000  BX=1044  CX=0000  DX=0102  SP=103C  BP=0000  SI=00EA  DI=115E
    DS=2143  ES=2143  SS=2143  CS=1F6E  IP=0010   NV UP EI PL ZR NA PE NC
    32:    int   argc;
    _TEXT:_main:
    1F6E:0010 55             PUSH    BP                            ;BR0

    This format includes the source code that corresponds to the next
    instruction to be executed.

    To set the contents of register AX to FFFFH without displaying its
    current value, type

    -R AX=FFFF  <Enter>

    or

    -R AX -1  <Enter>

    To display the current value of the target program's BX register, type

    -R BX  <Enter>

    If BX contains 200H, for example, SYMDEB 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 the contents can be left unchanged by
    pressing the Enter key alone.

    To set the direction and carry flags, first type

    -R F  <Enter>

    SYMDEB displays the current flag values, followed by a prompt in the
    form of a hyphen character (-). For example:

    NV UP EI PL NZ NA PO NC  -

    The direction and carry flags can then be set by entering

    -DN CY  <Enter>

    on the same line as the prompt.

Messages

    Bad Flag!
    An invalid code for a CPU flag was entered.

    Bad Register!
    An invalid register name was entered.

    Double Flag!
    Two values for the same CPU flag were entered in the same
    command.



SYMDEB: S
Search Memory


Purpose

    Searches memory for a pattern of one or more bytes.

Syntax

    S range list

    where:

    range      is the starting and ending address or the starting address
                and length in bytes of the area to be searched.

    list       is one or more byte values or a string to be searched for.

Description

    The Search Memory (S) command searches a designated range of memory
    for a sequence of byte values or text strings and displays the
    starting address of each set of matching bytes. The contents of the
    searched area are not altered.

    The range parameter specifies the starting and ending address or the
    starting address and length in bytes of the area to be searched. If a
    segment is not included in range, SYMDEB uses DS. If a segment is
    specified only for the starting address, SYMDEB uses the same segment
    for the ending address. If a starting address and length in bytes are
    specified, the starting address plus the length less 1 cannot exceed
    FFFFH.

    The list parameter is one or more hexadecimal byte values and/or
    strings separated by spaces, commas, or tab characters. Strings must
    be enclosed in 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:0000H through DS:1FFFH, type

    -S 0 1FFF 'Copyright'  <Enter>

    or

    -S 0 L2000 "Copyright"  <Enter>

    If a match is found, SYMDEB displays the address of each
    occurrence:

    20A8:0910
    20A8:094F
    20A8:097C

    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>

    or

    -S CS:100 L11A1 3B 06  <Enter>



SYMDEB: S+
Enable Source Display Mode


Purpose

    Displays source-code lines, rather than machine instructions.

Syntax

    S+

Description

    The Enable Source Display Mode (S+) command affects the display format
    of certain SYMDEB commands: Proceed Through Loop or Subroutine (P),
    Trace Program Execution (T), and Display or Modify Registers (R). The
    S+ command causes source code, rather than disassembled machine
    instructions, to be displayed by those commands.

    The S+ command is useful only if the program being debugged was
    created with a high-level-language compiler capable of placing line-
    number information into the relocatable object modules processed by
    the Microsoft Object Linker (LINK). When debugging Microsoft Macro
    Assembler (MASM) programs or programs generated by language compilers
    that do not pass line-number information to LINK, the S+ command has
    no effect.

Example

    To enable the display of source-code statements during debugging,
    type

    -S+  <Enter>



SYMDEB: S-
Disable Source Display Mode


Purpose

    Displays disassembled machine instructions, rather than source-code
    lines.

Syntax

    S-

Description

    The Disable Source Display Mode (S-) command affects the display
    format of certain SYMDEB commands: Proceed Through Loop or Subroutine
    (P), Trace Program Execution (T), and Display or Modify Registers (R).
    The S- command causes disassembled machine instructions, rather than
    source code, to be displayed by those commands. By default, SYMDEB
    displays disassembled machine instructions when debugging Microsoft
    Macro Assembler (MASM) programs or programs generated by language
    compilers that do not pass line-number information to the Microsoft
    Object Linker (LINK).

Example

    To disable the display of source-code statements during debugging,
    type

    -S-  <Enter>



SYMDEB: S&
Enable Source and Machine Code Display Mode


Purpose

    Displays both source-code lines and disassembled machine
    instructions.

Syntax

    S&

Description

    The Enable Source and Machine Code Display Mode (S&) command affects
    the display format of certain SYMDEB commands: Proceed Through Loop or
    Subroutine (P), Trace Program Execution (T), and Display or Modify
    Registers (R). The S& command causes both the disassembled machine
    instructions and the corresponding source-code lines to be displayed
    by those commands.

    The S& command is useful only if the program being debugged was
    created with a high-level-language compiler capable of placing line-
    number information into the relocatable object modules processed by
    the Microsoft Object Linker (LINK). When debugging Microsoft Macro
    Assembler (MASM) programs or programs generated by language compilers
    that do not pass line-number information to LINK, the S& command has
    no effect.

Example

    To enable the display of both source-code statements and disassembled
    machine-code statements during debugging, type

    -S&  <Enter>



SYMDEB: T
Trace Program Execution


Purpose

    Executes one or more machine instructions in single-step mode.

Syntax

    T[=address] [number]

    where:

    address     is the location of the first instruction to be executed.

    number      is the number of machine instructions to be executed.

Description

    The Trace Program Execution (T) command executes one or more machine
    instructions, starting at the specified address. If source display
    mode has been enabled with the S+ command, each trace operation
    executes the machine code corresponding to one source statement and
    displays the lines from the source code. If source display mode has
    been disabled with the S- command, each trace operation executes an
    individual machine instruction and displays the contents of the CPU
    registers and flags after execution.

    Warning: The T command should not be used to execute any instruction
    that changes the contents of the Intel 8259 interrupt mask (ports 20H
    and 21H on the IBM PC and compatibles). Use the Go (G) command
    instead.

    The address parameter points to the first instruction to be executed.
    If address does not include a segment, SYMDEB uses the target
    program's CS register; if address is omitted entirely, execution is
    begun at the current address specified by the target program's CS:IP
    registers. The address parameter must be preceded by an equal sign (=)
    to distinguish it from number.

    The number parameter specifies the hexadecimal number of source-code
    statements or machine instructions to be executed before the SYMDEB
    prompt is displayed again (default = 1). If source display mode is
    enabled, the number parameter is required. Execution of a sequence of
    instructions using the T command can be interrupted at any time by
    pressing Ctrl-C or Ctrl-Break and can be paused by pressing Ctrl-S
    (pressing any key resumes the trace).

Examples

    To execute one instruction at location CS:1A00H and then return
    control to SYMDEB, displaying the contents of the CPU registers and
    flags, type

    -T =1A00  <Enter>

    Consecutive instructions can then be executed by entering repeated T
    commands with no parameters.

    If source display mode has been enabled with a previous S+ command, to
    begin execution at the label main and continue through the machine
    code corresponding to four source- code statements, type

    -T =main 4  <Enter>



SYMDEB: 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 the number of instructions of the
                machine code to be disassembled.

Description

    The Disassemble (Unassemble) Program (U) command translates machine
    instructions into their assembly-language mnemonics.

    The range parameter specifies the starting and ending addresses or
    the starting address and number of machine instructions to be
    disassembled. If range does not include an explicit segment, SYMDEB
    uses CS. Note that the resulting disassembly will be incorrect if the
    starting address does not fall on an 8086 instruction boundary.

    If range does not include the number of machine instructions to be
    executed or an ending address, eight instructions are disassembled. If
    range is omitted completely, eight instructions are disassembled
    starting at the address following the last instruction disassembled by
    the previous U command, if a U command has been used; if no U command
    has been used, eight instructions are disassembled starting at the
    address specified by the current value of the target program's CS:IP
    registers.

    The display format for the U command depends on the current source
    display mode setting and on whether the program was developed with a
    compatible high-level-language compiler. If the source display mode
    setting is S- or the program was developed with the Microsoft Macro
    Assembler (MASM) or a noncompatible high-level-language compiler, the
    display contains only the address and the disassembled equivalent of
    each instruction within range. (For 8-bit immediate operands, SYMDEB
    also displays the ASCII equivalent as a comment following a
    semicolon.) If the setting is S+ or S& and a compatible symbol file
    containing line-number information was loaded with the program being
    debugged, the display contains both the source-code lines and their
    corresponding disassembled machine instructions.

    Note: The 80286 instructions that are considered privileged when the
    microprocessor is running in protected mode are not supported by
    SYMDEB's disassembler.

Examples

    To disassemble four machine instructions starting at CS:0100H,
    type

    -U 100 L4  <Enter>

    This produces the following display:

    44DC:0100 EC             IN     AL,DX
    44DC:0101 B80200         MOV    AX,0002
    44DC:0104 E86102         CALL   0368
    44DC:0107 57             PUSH   DI

    Successive eight-instruction fragments of machine code can be
    disassembled by entering additional U commands without
    parameters.

    When a program is being debugged with a symbol file that contains
    line-number information and source display mode has been enabled,
    disassembled machine code is accompanied by the corresponding source
    code:

    43:        if (argc != 2)
    28A5:0031 837E0402       CMP    Word Ptr [BP+04],+02
    28A5:0035 7503           JNZ    _main+2A (003A)
    28A5:0037 E91400         JMP    _main+3E (004E)
    44:         {  fprintf(stderr,"\ndump: wrong number of parameters\n");
    28A5:003A B83600         MOV    AX,0036
    28A5:003D 50             PUSH   AX
    28A5:003E B8F600         MOV    AX,00F6
    28A5:0041 50             PUSH   AX
    28A5:0042 E8AC04         CALL   _fprintf
    28A5:0045 83C404         ADD    SP,+04
    45:                return(1);
    28A5:0048 B80100         MOV    AX,0001
    28A5:004B E9AA00         JMP    _main+E8 (00F8)



SYMDEB: V
View Source Code


Purpose

    Displays lines from the source-code file for the program being
    debugged.

Syntax

    V address [length]

    or

    V [.sourcefile:linenumber]

    where:

    address         is the location of an executable instruction in the
                    target program.

    length          is an ending address or the number of source-code
                    lines.

    .sourcefile     is the base name of the source file of the program
                    being debugged, preceded by a period (.).

    linenumber      is the first literal line number of .sourcefile to
                    be displayed.

Description

    The View Source Code (V) command displays lines of source code for the
    program being debugged, beginning at the location specified by
    address. If address does not include a segment, SYMDEB uses the
    target program's CS register.

    The optional length parameter can be an ending address or an L
    followed by a hexadecimal number of source-code lines. If length is
    not specified, eight lines of source code are displayed.

    If the .sourcefile parameter is specified, followed by a colon
    character (:) and a line number, eight lines of source code are
    displayed, starting at linenumber. If the V command is entered
    without parameters after the .sourcefile:linenumber parameter has
    been specified, eight lines are displayed from the current source
    file, beginning with the line after the last line displayed with the V
    command. The .sourcefile parameter must be the name of a high-level-
    language source file in the current directory. Pathnames and
    extensions are not supported. The length option cannot be used with
    the .sourcefile parameter.

    Warning: Specifying a file that does not exist in the current
    directory may cause the system to crash.

    The V command can be used only with programs created by a high-level-
    language compiler that is capable of placing line-number information
    into the relocatable object modules processed by the Microsoft Object
    Linker (LINK). The current source display mode setting (S-, S+, or S&)
    has no effect on the V command.

Examples

    Assume that the program DUMP.EXE is being debugged with the aid of the
    symbol file DUMP.SYM and that the source file DUMP.C is available in
    the current directory. To display eight lines of source code beginning
    at the label main, type

    -V _main  <Enter>

    This produces the following output:

32:        int   argc;
33:        char  *argv[];
34:
35:    {   FILE *dfile;              /* control block for input file */
36:        int status = 0;           /* status returned from file read */
37:        int file rec = 0;         /* file record number being dumped */
38:        long file ptr = 0L;       /* file byte offset for current rec */
39:        char file buf[REC SIZE];  /* data block from file */

    To view eight lines of source code from the file DUMP.C, beginning
    with line 20, type

    -V .DUMP:20  <Enter>

Message

    Source file for filename (cr for none)?
    The current directory does not contain the source file specified with
    the .sourcefile parameter. Enter the correct filename or press Enter
    to indicate no source file.



SYMDEB: 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    is the first location in memory of the data to be written.

    drive      is the number of the destination disk drive (0 = drive A,
                1 = drive B, 2 = drive C, 3 = drive D).

    start      is the number of the first logical sector to be written
                (0-FFFFH).

    number     is the number of consecutive sectors to be written (0-
                FFFFH).

Description

    The Write File or Sectors (W) command transfers a file or individual
    sectors from memory to disk.

    When the W command is entered without parameters or with an address
    alone, the number of bytes specified by the contents of registers
    BX:CX are written from memory to the file named by the most recent
    Name File or Command-Tail Parameters (N) command or to the first file
    specified in the SYMDEB command line if the N command has not been
    used.

    Note: If a Go (G), Proceed Through Loop or Subroutine (P), or Trace
    Program Execution (T) command was previously used or the contents of
    the BX or CX registers were changed, BX:CX must be restored before the
    W command is used.

    When address is not included in the command line, SYMDEB uses the
    target program's CS:0100H. Files with a .EXE or .HEX extension cannot
    be written with the W command.

    The W command can also be used to bypass the MS-DOS file system and
    obtain direct access to logical sectors on the disk. To use the W
    command in this way, the memory address (address), disk unit 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.

    Warning: Extreme caution should be used with the W command. The
    disk's file structure can easily be damaged if the command is entered
    incorrectly. The W command should not be used to write logical sectors
    to network drives.

Example

    Assume that the interactive Assemble Machine Instructions (A) command
    was used to create a program in SYMDEB's memory buffer that is 32
    (20H) bytes long, beginning at offset 100H. This program can be
    written into the file QUICK.COM by sequential use of the Name File or
    Command-Tail Parameters (N), Display or Modify Registers (R), and
    Write File or Sectors (W) commands. 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 half or most significant part
    of the length; register CX contains the lower half or least
    significant part. Type

    -R CX  <Enter>

    SYMDEB displays the current contents of register CX and issues a colon
    character (:) prompt . Enter the length after the prompt:

    :20  <Enter>

    To use the R command again to set the BX register to zero, type

    -R BX  <Enter>

    Then type

    :0  <Enter>

    To create the disk file QUICK.COM and write the program into it,
    type

    -W  <Enter>

    SYMDEB 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, SYMDEB displays in hexadecimal
    format the number of bytes written to disk.



SYMDEB: X
Examine Symbol Map


Purpose

    Displays names and addresses in the symbol maps.

Syntax

    X[*]

    or

    X? [map!] [segment:] [symbol]

    where:

    map!        is the name of a symbol file, without the .SYM extension,
                followed by an exclamation point (!).

    segment:    is the name of a segment within the currently open or
                specified map, followed by a colon character (:).

    symbol      is a symbol name within the specified segment.

Description

    The Examine Symbol Map (X) command displays the addresses and names of
    symbols in the currently open symbol maps. (SYMDEB maintains a symbol
    map for each symbol file specified in the SYMDEB command line.)

    If the X command is followed by the asterisk wildcard character (*),
    the map names, segment names, and segment addresses for all currently
    loaded symbol maps are displayed. If X is entered alone, the
    information is displayed only for the active symbol map.

    Information from the symbol maps can be displayed selectively by
    following the X? command with the map!, segment:, and symbol
    parameters. The three parameters may be used individually or in
    combination, but at least one parameter must be specified.

    The map! parameter must be terminated by an exclamation point and
    consists of the name, without the extension, of a previously loaded
    symbol file. If map! is omitted, SYMDEB uses the currently open symbol
    map. If more than one .SYM file is specified in the command line, the
    one with the same name as the program being debugged is opened first.

    The segment: parameter must be terminated with a colon; it is the name
    of a segment declared within the specified or currently open symbol
    map.

    The symbol parameter is the name of a label, variable, or other
    object within the specified segment.

    Any or all parameters can consist of or include the asterisk wildcard
    character. For example, X?* displays everything in the current map.

Examples

    Assume that the program DUMP.EXE is being debugged with the symbol
    file DUMP.SYM. If the following is typed

    -X  <Enter>

    SYMDEB displays:

    [456E DUMP]
        [456E _TEXT]
            4743 DGROUP

    This indicates that the program contains one executable code segment
    (named _TEXT), which is loaded at segment 456EH, and one NEAR DATA
    group and segment (named DGROUP), which is loaded at segment 4743H.

    To display the addresses of all procedures in the same example program
    whose names begin with the character f, type

    -X? _TEXT:_F*  <Enter>

    This produces the following listing:

    _TEXT: (456E)
    0428 _fclose           04CB _fopen            04F1 _fprintf
    0528 _fread            0ACB _fflush           0BC2 _free
    19AD _flushall

    Note: Unlike the Microsoft C Compiler, SYMDEB is not case
    sensitive.



SYMDEB: XO
Open Symbol Map


Purpose

    Selects the active symbol map and/or segment.

Syntax

    XO [map!] [segment]

    where:

    map!       is the name of a symbol file, without the .SYM extension,
                followed by an exclamation point (!).

    segment    is the name of the segment that will become the active
                segment in the current symbol map.

Description

    The Open Symbol Map (XO) command selects the active symbol map and/or
    the active segment within the current symbol map to be used during
    debugging.

    The optional map! parameter must be terminated by an exclamation point
    and must be the name, without the extension, of a symbol file
    specified in the original SYMDEB command line. If map! is omitted, no
    changes are made to the active symbol map.

    The optional segment parameter must be the name of a segment within
    the current or specified symbol map. All segments in the active symbol
    map are accessible; the active segment is searched first for symbols
    specified in other SYMDEB commands. If segment is omitted and a new
    active symbol map is specified, the segment with the smallest address
    in the new active symbol map will become the active segment.

Examples

    Assume that the program SHELL.EXE has been loaded with the two symbol
    files SHELL.SYM and VIDEO.SYM. To use the information loaded from
    VIDEO.SYM as the active symbol map for debugging, type

    -XO VIDEO!  <Enter>

    Subsequent entry of the command

    -XO _TEXT  <Enter>

    causes the segment _TEXT within the symbol map VIDEO to be searched
    first for symbol names.

Message

    Symbol not found
    The specified symbol map or segment does not exist.



SYMDEB: Z
Set Symbol Value


Purpose

    Assigns a value to a symbol.

Syntax

    Z [map!] symbol value

    where:

    map!       is the name of a symbol file, without the .SYM extension,
                followed by an exclamation point (!).

    symbol     is an existing symbol name in the active symbol map or in
                the symbol map specified by map!.

    value      is the new address of symbol (0-FFFFH).

Description

    The Set Symbol Value (Z) command allows the address associated with a
    name in one of the loaded symbol maps to be overridden by a new
    value.

    Note that altering the address of a symbol at debugging time will not
    affect other addresses or values that were derived from the value of
    the same symbol at compilation or assembly time.

    The optional map! parameter must be terminated by an exclamation point
    and must be the name, without the extension, of a symbol file
    specified in the original SYMDEB command line. If map! is omitted,
    SYMDEB uses the active symbol map.

    The symbol parameter specifies the name of a label, variable, or
    other object in map! or the active symbol map.

    The value parameter specifies a new address to be associated with
    symbol.

    To debug programs created with older versions of FORTRAN and Pascal
    (Microsoft versions earlier than 3.3 or IBM versions earlier than
    2.0), the user must start SYMDEB, locate the first procedure of the
    program being debugged, and then use the Z command to set the address
    of DGROUP to the current value of the DS register. (Later versions of
    FORTRAN and Pascal do this by default.)

Examples

    To change the segment address for the symbol DGROUP to 5000H, type

    -Z DGROUP 5000  <Enter>

    The actual data associated with the label DGROUP must be moved to the
    new address before debugging can continue.

    To change the segment address for the symbol CODE in the inactive
    symbol map COUNT to 0F00H, type

    -Z COUNT! CODE F00  <Enter>



SYMDEB: <
Redirect SYMDEB Input


Purpose

    Redirects input to SYMDEB.

Syntax

    < device

    where:

    device     is the name of any MS-DOS device or file.

Description

    The Redirect SYMDEB Input (<) command causes SYMDEB to read its
    commands from the specified text file or character device, rather than
    from the keyboard (CON).

    The device parameter specifies the name of any MS-DOS device or file
    from which commands will be read. If the device parameter is a
    filename, the file must be an ASCII text file and each command in the
    file must be on a separate line.

    If input will be taken from a terminal attached to one of the serial
    communications ports (AUX, COM1, or COM2), the port must be properly
    configured with the MODE command before the SYMDEB session is
    started.

    When SYMDEB commands are redirected from a file, the last entry in the
    file must be either the < CON command, which restores the keyboard as
    the input device, or the Quit (Q) command.  Otherwise, SYMDEB will
    lock and the system will have to be restarted.

Examples

    Assume that the text file FILL.TXT contains the following SYMDEB
    commands:

    F CS:0100 L100 00
    D CS:0100 L100
    R
    Q

    To process FILL.TXT during a SYMDEB session (which in turn exits
    SYMDEB with the Quit [Q] command), type

    -< FILL.TXT  <Enter>

    Assume that the text file SEARCH.TXT contains the following SYMDEB
    commands:

    S BUFFER L2000 "error"
    < CON

    To process SEARCH.TXT during a SYMDEB session and return control to
    the console, type

    -< SEARCH.TXT  <Enter>



SYMDEB: >
Redirect SYMDEB Output


Purpose

    Redirects SYMDEB's output to a device or file.

Syntax

    > device

    where:

    device     is the name of any MS-DOS device or file.

Description

    The Redirect SYMDEB Output (>) command causes SYMDEB to send all its
    messages to the specified device or file, rather than to the video
    display (CON). This is useful for creating a record of a debugging
    session that can be viewed later with an editor or listed on a
    printer.

    After SYMDEB output is redirected, commands typed on the keyboard are
    not echoed to the video display. Therefore, the user must know in
    advance which commands to use and which parameters to supply.

    The device parameter specifies the name of an MS-DOS device or file
    to receive SYMDEB's output. If output will be redirected to one of the
    serial communications ports (AUX, COM1, or COM2), the port must be
    properly configured with the MODE command before the SYMDEB session is
    started.

    Output can be restored to the video display by entering the > CON
    command or by terminating SYMDEB with the Quit (Q) command.

Examples

    To cause SYMDEB to send all prompts and messages to the file
    SESSION.TXT, type

    -> SESSION.TXT  <Enter>

    After this command, new commands are still accepted by SYMDEB, but the
    keypresses are not echoed to the screen until the command

    -> CON  <Enter>

    is entered or SYMDEB is terminated with the Quit (Q) command.

    To cause SYMDEB to send all its prompts and messages to the standard
    printing device, PRN, type

    -> PRN  <Enter>



SYMDEB: =
Redirect SYMDEB Input and Output


Purpose

    Redirects both input and output for SYMDEB.

Syntax

    = device


    where:

    device     is the name of any MS-DOS device.

Description

    The Redirect SYMDEB Input and Output (=) command causes SYMDEB to read
    its commands from and send its output to the specified device, rather
    than reading from the keyboard and sending output to the video display
    (CON). This command is especially useful for debugging programs that
    run in graphics mode; the SYMDEB commands can be entered on a terminal
    attached to the computer's serial port while the graphics program has
    the full use of the system's video display.

    The device parameter specifies the name of any MS-DOS device. If
    input and output will be redirected to one of the serial
    communications ports (AUX, COM1, or COM2), the port must be properly
    configured with the MODE command before the SYMDEB session is started.

    Input and output can be restored to the standard settings with the =
    CON command.

Example

    To redirect SYMDEB's input and output to the first serial
    communications port (COM1), type

    -= COM1  <Enter>



SYMDEB: {
Redirect Target Program Input


Purpose

    Redirects input to the program being debugged.

Syntax

    { device

    where:

    device     is the name of any MS-DOS device or file.

Description

    The Redirect Target Program Input ({) command causes read operations
    by the program being debugged to be taken from the specified file or
    device when the program is executed, rather than from the keyboard
    (CON).

    The device parameter specifies the name of an MS-DOS device or file
    from which the target program will read. If the device parameter is a
    filename, the file must be an ASCII text file and each command in the
    file must be on a separate line.

    If input will be taken from a terminal attached to one of the serial
    communications ports (AUX, COM1, or COM2), the port must be properly
    configured with the MODE command before the SYMDEB session is
    started.

Example

    To cause input for the program being debugged to be taken from the
    file TEST.TXT, type

    -{ TEST.TXT  <Enter>



SYMDEB: }
Redirect Target Program Output


Purpose

    Redirects the output of the program being debugged.

Syntax

    } device

    where:

    device     is the name of any MS-DOS device or file.

Description

    The Redirect Target Program Output (}) command causes write operations
    by the program being debugged to be redirected to the specified device
    or file when the program is executed, rather than to the video display
    (CON). This is useful for capturing the output of a program in a file
    for later listing on a printer.

    The device parameter specifies the name of an MS-DOS device or file
    to receive the target program's output. If output will be redirected
    to one of the serial communications ports (AUX, COM1, or COM2), the
    port must be properly configured with the MODE command before the
    SYMDEB session is started.

Example

    To send the output from the program being debugged to the file
    SESSION.TXT, type

    -} SESSION.TXT  <Enter>



SYMDEB: ~
Redirect Target Program Input and Output


Purpose

    Redirects both input and output for the program being debugged.

Syntax

    ~ device

    where:

    device     is the name of any MS-DOS device.

Description

    The Redirect Target Program Input and Output (~) command causes all
    read and write operations by the program being debugged to be
    redirected to the specified character device.

    The device parameter specifies the name of an MS-DOS device that the
    target program will read from and write to. If input and output are
    redirected to one of the serial communications ports (AUX, COM1, or
    COM2), the port must be properly configured with the MODE command
    before the SYMDEB session is started.

Example

    To redirect input and output for the program being debugged to the
    first serial communications port (COM1), type

    -~ COM1  <Enter>



SYMDEB: \
Swap Screen


Purpose

    Exchanges the SYMDEB display for the target program's display.

Syntax

    \

Description

    The Swap Screen (\) command causes the SYMDEB status display to be
    exchanged for the virtual screen used by the program being debugged.
    After the program's output has been inspected on the virtual screen,
    the SYMDEB display can be restored by pressing any key. This command
    is useful for debugging programs that perform direct screen access or
    run in graphics mode.

    Note: Any information on the display when SYMDEB was invoked will
    also appear on the virtual screen. When SYMDEB is terminated, the
    current display is set to match the virtual screen.

    The Swap Screen command is available only if the /S switch (or the /I
    switch, if the computer is IBM compatible) preceded the names of the
    symbol and program files in the original SYMDEB command line.

Example

    To exchange the SYMDEB status display for the virtual screen of the
    program being debugged, type

    -\  <Enter>

    To restore the SYMDEB display, press any key.



SYMDEB: .
Display Source Line


Purpose

    Displays the current source-code line.

Syntax

    .

Description

    The Display Source Line (.) command displays the line from the source-
    code file that corresponds to the machine instruction currently
    pointed to by the target program's CS:IP registers.

    The . command is independent of the current Source Display Mode status
    (S+, S-, or S&). However, if the program being debugged was not
    created with a high-level-language compiler that inserts line numbers
    into the object modules, the . command has no effect.

Example

    To display the source-code line corresponding to the next instruction
    to be executed, type

    -.  <Enter>

    This produces output in the following form:

    56:        printf( '\nDump of file: %s ', argv[1] );



SYMDEB: ?
Help or Evaluate Expression


Purpose

    Displays the help screen or the value of an expression.

Syntax

    ? [expression]

    where:

    expression      is any valid combination of symbols, addresses,
                    numbers, and operators.

Description

    When ? is entered alone, a help screen summarizing all valid SYMDEB
    commands, operators, and types is displayed.

    When ? is followed by the expression parameter, expression is
    evaluated and the value is displayed. The expression parameter can
    include any valid combination of symbols, addresses, numbers, and
    operators.

    The form and content of the resulting display depends on the type of
    expression entered. If expression is a symbol or an address
    (optionally including operators), the value is shown first as a FAR
    address pointer in the form segment:offset, then as a 32-bit
    hexadecimal number representing the value's physical location in
    memory (followed by its decimal equivalent in parentheses), and
    finally as the physical location's ASCII character equivalents
    displayed as a string enclosed in quotation marks (which have no
    practical value if expression is an address or symbol).

    If expression includes numbers (interpreted as signed hexadecimal
    values unless a radix is specified) and operators, the resulting value
    is shown first as a 16-bit hexadecimal value, then as a 32-bit
    hexadecimal value (followed by its decimal equivalent in parentheses),
    and finally as the value's ASCII character equivalents displayed as a
    string enclosed in quotation marks.

    (The ASCII characters within the string are displayed as dots if their
    value is less than 20H [32] or greater than 7EH [126].)

Examples

    Assume that the pointer array argv in the program DUMP.C is located
    at address 4743:029CH. The command

    -? _argv+4  <Enter>

    produces the following display:

    4743:02A0h  000476D0  (292560)

    To display the result of an exclusive OR operation between the values
    0FCH and 14H, type

    -? FC XOR 14  <Enter>

    SYMDEB displays

    00E8h  000000E8  (232)



SYMDEB: !
Escape to Shell


Purpose

    Invokes the MS-DOS command processor.

Syntax

    ! [command]

    where:

    command         is the name of any MS-DOS command, program, or batch
                    file and its required parameters.

Description

    The Escape to Shell (!) command loads a copy of the system's command
    processor (COMMAND.COM), optionally passing it the name of a program
    or batch file to be executed. This allows MS-DOS functions such as
    listing or copying files to be carried out without losing the context
    of the debugging session.

    If the ! command is entered alone, an additional copy of COMMAND.COM
    gains control and displays the system prompt. Control can be returned
    to SYMDEB by leaving the new shell with the EXIT command.

    If the ! character is followed by a command parameter that specifies
    any valid MS-DOS command, program name, or batch-file name, the
    specified command is executed immediately and control returns directly
    to SYMDEB.

    The SYMDEB statement connector (;) cannot be used on the same line as
    the ! command; all text encountered after this command is passed to
    COMMAND.COM and is interpreted as an MS-DOS command line.

Example

    To list the files in the current directory, type

    -! DIR /W  <Enter>

Messages

    COMMAND.COM not found!
    SYMDEB could not find COMMAND.COM because it was not present in the
    directory location specified in the environment block's COMSPEC
    variable.

    Not enough memory!
    Free memory in the transient program area (TPA) is insufficient to
    execute the requested command or program. This is a common occurrence
    when debugging a large program with symbol files.



SYMDEB: *
Enter Comment


Purpose

    Allows insertion of a comment that will be ignored by SYMDEB's command
    interpreter.

Syntax

    *text

    where:

    text       is any ASCII text up to and including a carriage return.

Description

    The Enter Comment (*) command causes the remainder of the text on that
    line to be ignored, thereby providing a means of commenting a SYMDEB
    debugging session. SYMDEB echoes any text following the asterisk to
    the screen or redirected output device, providing the user with a
    convenient way to comment program output redirected to a file or a
    printer. A maximum of 78 characters can be included on each comment
    line. Comment lines are also useful for documenting lines within a
    text file that SYMDEB will use as redirected input for the program
    being debugged.

Example

    To echo the reminder Errors in program output start here: to the
    screen or redirected output device, type

    -*Errors in program output start here:  <Enter>

    A line in a text file that will be used by SYMDEB for redirected input
    to the program being debugged may be "commented out" by inserting an
    asterisk at the beginning of the line. For example:

    *EB CS:1200 90



CodeView
Window-Oriented Debugger


Purpose

    Allows the controlled execution of an assembly-language program or
    high-level-language program for debugging purposes. Both source code
    and the corresponding unassembled machine code can be displayed as
    program execution is traced. In addition, watch variables, CPU
    registers and flags, and program output can be examined in separate
    debugging windows. CodeView is supplied with the Microsoft Macro
    Assembler (MASM), C Compiler, Pascal Compiler, and FORTRAN Compiler.
    This documentation describes CodeView version 2.0.

Syntax

    CV [options] exe_file [parameters]

    where:

    exe_file        is the name of the executable file containing the
                    program to be debugged (default extension = .EXE).

    parameters      is one or more filenames or switches required by the
                    program being debugged.

    options         is one or more switches from the following list.
                    Switches can be either uppercase or lowercase and
                    can be preceded by a dash (-) instead of a forward
                    slash (/).

                    /2           Allows the use of two video displays for
                                debugging.

                    /43          Enables 43-line display mode. (An IBM-
                                compatible computer with an enhanced
                                graphics adapter [EGA] and an enhanced
                                color display is required for this
                                option.)

                    /B           Forces the attached monitor to use two
                                shades of color when displaying
                                information.

                    /Ccommands   Executes the specified list of startup
                                commands when CodeView is invoked. If
                                the list of startup commands contains
                                any spaces, the entire list must be
                                enclosed in double quotation marks (").
                                Commands in the list must be separated
                                by a semicolon character (;).

                    /D           Turns off nonmaskable interrupt trapping
                                and Intel 8259 interrupt trapping.
                                (This switch prevents system crashes on
                                some IBM-compatible machines that do
                                not support certain IBM-specific
                                interrupt trapping functions.)

                    /E           Stores the symbolic information of the
                                program in expanded memory.

                    /F           Enables the screen-flipping method of
                                switching between the debugging display
                                and the virtual output display. Screen
                                flipping is the default method for IBM-
                                compatible computers with color/graphics
                                adapters.

                    /I           Enables nonmaskable interrupt trapping
                                and Intel 8259 interrupt trapping on
                                computers that are not IBM-compatible.

                    /M           Disables mouse support within CodeView.

                    /P           Enables palette register restore mode,
                                which allows non-IBM EGAs to restore
                                the proper colors upon return from the
                                virtual output screen.

                    /R           Enables Intel 80386 debugging registers.

                    /S           Enables the screen-swapping method of
                                switching between the debugging display
                                and the virtual output display. Screen
                                swapping is the default method for IBM-
                                compatible computers with monochrome
                                adapters.

                    /T           Disables window mode. This switch is
                                necessary for some non-IBM computers or
                                when a sequential debugging session is
                                desired.

                    /W           Enables window mode. This switch allows
                                CodeView to operate in multiple windows
                                on the same screen. (This option is not
                                the default for some computers.)

Description

    CodeView is a window-oriented menu-driven debugger that allows tracing
    and debugging of high-level-language programs and assembly-language
    programs. In general, any valid C, FORTRAN, BASIC, Pascal, or MASM
    source code can be debugged with CodeView.

    To prepare a program for debugging under CodeView, the program must be
    compiled and linked so that the resulting executable file has the
    extension .EXE and contains line-number information, a symbol table,
    and executable code. (To a limited extent, text files and .COM files
    can also be examined under CodeView.) During the debugging session,
    the program source file must remain in the current directory if
    source-code display is desired.

    The CodeView screen contains four windows that display information
    about the pro- gram being debugged: the display window, which contains
    program source code and (if requested) the unassembled machine code
    corresponding to the source code; the dialog window, where line-
    oriented commands similar (and in some cases identical) to SYMDEB can
    be entered and viewed (see PROGRAMMING UTILITIES: SYMDEB);
    the register window (optional), which contains the current status of
    the microprocessor's registers and flags; and the watch window
    (optional), which contains program variables or memory locations to be
    examined during program execution. CodeView also provides a virtual
    output screen (stored internally) that contains all display output
    generated during the CodeView session.

    A typical CodeView debugging screen looks like this:


            ╔══════════════════════════════════════════╗
            ║                                          ║
            ║  The CodeView display is found on page   ║
            ║ 1159 in the printed version of the book. ║
            ║                                          ║
            ╚══════════════════════════════════════════╝


    The CodeView display.

Display window commands

    Commands that control the display window are available in nine pull-
    down menus whose names appear in a menu bar near the top of the
    screen. Commands can be selected with the keyboard or the mouse.
    Commands are selected with the keyboard by pressing the Alt key,
    pressing the first letter in the menu name, and then pressing the
    first letter of the command. Commands are selected with the mouse by
    pulling down the menu with the mouse pointer, highlighting the
    command, and then releasing the mouse button. Commands with small
    double arrows to the left of the command name are currently active.
    The CodeView menus and commands are described below.

    File menu
    The File menu includes commands that manipulate the current source or
    program file. To select the File menu with the keyboard, press Alt-F.

╓┌─────────────────┌─────────────────────────────────────────────────────────╖
    Command      Action
    ──────────────────────────────────────────────────────────────────────
    Open...      Opens the specified source file, include file, or text
                file in the display window.

    DOS Shell    Exits to the shell temporarily. Type exit to return to
                CodeView.

    Exit         Ends the current CodeView session.


    View menu
    The View menu includes commands that select source or assembly modes
    and commands that select the debugging screen or the virtual output
    screen. To select the View menu with the keyboard, press Alt-V.

╓┌─────────────────┌─────────────────────────────────────────────────────────╖
    Command      Action
    ──────────────────────────────────────────────────────────────────────
    Source       Displays only the high-level-language or assembly-
                language source code corresponding to the program being
                debugged.

    Mixed        Displays both the unassembled machine code and the source
                code corresponding to the program being debugged.

    Assembly     Displays only the unassembled machine code corresponding
                to the program being debugged.

    Registers    Displays or removes the optional register window.

    Output       Replaces the debugging screen with the virtual output
                screen. Press any key to return to the debugging screen.


    Search menu
    The Search menu includes commands that search through text files for
    text strings and through executable code for labels. To select the
    Search menu with the keyboard, press Alt-S.

╓┌───────────────────────┌───────────────────────────────────────────────────╖
    Command            Action
    ──────────────────────────────────────────────────────────────────────
    Find...            Searches the current source file or other text file
                        for the specified expression.

    Next               Searches forward through the file for the next
                        match of the last expression specified with the
                        Find... command.

    Previous           Searches backward through the file for the next
                        match of the last expression specified with the
                        Find... command.

    Label...           Searches the executable code for the specified
                        procedure name or program label.


    Run menu
    The Run menu includes commands that run the program being debugged. To
    select the Run menu with the keyboard, press Alt-R.

╓┌───────────────────────┌───────────────────────────────────────────────────╖
    Command            Action
    ──────────────────────────────────────────────────────────────────────
    Start              Runs the program at full speed from the first
                        instruction.

    Restart            Reloads the program and moves to the first
                        instruction.

    Execute            Runs the program at reduced speed from the current
                        instruction.

    Clear Breakpoints  Clears all breakpoints.


    Watch menu
    The Watch menu includes commands that add watch statements to and
    delete watch statements from the watch window. Watch statements
    describe expressions or areas of memory to be examined during program
    execution. To select the Watch menu with the keyboard, press Alt-W.

╓┌───────────────────────┌───────────────────────────────────────────────────╖
    Command            Action
    ──────────────────────────────────────────────────────────────────────
    Add Watch...       Adds the specified watch-expression statement to
                        the watch window.

    Watchpoint...      Adds the specified watchpoint statement to the
                        watch window. A watchpoint is a conditional
                        breakpoint that is taken when the expression
                        becomes nonzero (true).

    Tracepoint...      Adds the specified tracepoint statement to the
                        watch window. A tracepoint is a conditional
                        breakpoint that is taken when a given expression
                        or range of memory changes.

    Delete Watch...    Deletes the specified statement from the watch
                        window.

    Delete All Watch   Deletes all statements from the watch window.


    Options menu
    The Options menu contains commands that affect the general behavior of
    CodeView. To select the Options menu with the keyboard, press Alt-O.

╓┌─────────────────┌─────────────────────────────────────────────────────────╖
    Command      Action
    ──────────────────────────────────────────────────────────────────────
    Flip/Swap    When on (the default), enables screen swapping or screen
                flipping (whichever option CodeView was started with);
                when off, disables swapping or flipping. Either method
                can be used to display the CodeView virtual output
                screen.

    Bytes Coded  When on (the default), displays the instructions,
                instruction addresses, and the bytes for each
                instruction; when off, displays only the instructions.

    Case Sense   When on, causes CodeView to assume that symbol names are
                case sensitive; when off, causes CodeView to assume that
                symbol names are not case sensitive. This option is on
                by default for C programs and off by default for
                FORTRAN, BASIC, and assembly programs.

    386           When on, allows instructions that reference 32-bit
                instructions to be assembled and executed and the
                register window to display 32-bit values. When off, does
                not allow Intel 80386 instructions and registers to be
                supported.


    Language menu
    The Language menu contains commands that select the language-dependent
    expression evaluator or instruct CodeView to select it for you. To
    select the Language menu with the keyboard, press Alt-L.

╓┌─────────────────┌─────────────────────────────────────────────────────────╖
    Command      Action
    ──────────────────────────────────────────────────────────────────────
    Auto         Forces CodeView to select the expression evaluator of the
                source file being loaded, based on the extension of the
                source file.

    Basic        Uses a BASIC expression evaluator to determine the value
                of source-level expressions.

    C            Uses a C expression evaluator to determine the value of
                source-level expressions.

    Fortran      Uses a FORTRAN expression evaluator to determine the
                value of source-level expressions.


    Calls menu
    The Calls menu is different from other menus in that its contents vary
    depending on the status of the program. The Calls menu lists the names
    of specific routines that will be displayed on the screen when that
    routine name is selected. Routine names in the Calls menu can be
    selected by typing the number displayed immediately to the left of a
    routine name. The cursor will move to the line at which the selected
    routine was last executing.

    The current value of each parameter, if any, is shown in parentheses
    following the name of the routine in the Calls menu. The menu expands
    to accommodate the parameters of the widest line. Parameters are shown
    in the current radix (default = decimal). If the program contains more
    active routines than will fit on the screen or if the routine
    parameters are too wide, the menu expands to the left and right.

    To select the Calls menu with the keyboard, press Alt-C.

    Help menu
    The Help menu lists the major topics in the CodeView "linked-list"
    help system. For help, pull down the Help menu and then select the
    topic of interest. To select the Help menu with the keyboard, press
    Alt-H.

╓┌───────────────────────┌───────────────────────────────────────────────────╖
    Command            Action
    ──────────────────────────────────────────────────────────────────────
    Intro to Help      Displays information about the "linked-list" help
                        system.

    Keyboard/Mouse     Displays information about keyboard and mouse
                        commands.

    Run commands       Displays information about Run commands.

    Display cmds.      Displays information about Display commands.

    Watch/Break        Displays information about setting, listing, and
                        deleting watchpoints and breakpoints.

    Memory Ops         Displays information about viewing and modifying
                        memory.

    System cmds.       Displays information about system and environment
                        commands.

    About CodeView     Displays information about the current CodeView
                        version, time, and date.


Key commands

    CodeView supports a variety of function keys and key combinations that
    modify the active window.

╓┌─────────────────┌─────────────────────────────────────────────────────────╖
    Key          Action
    ──────────────────────────────────────────────────────────────────────
    F1           Displays the introductory help screen.

    F2           Displays or removes the register window.

    F3           Changes the display in the display window to source,
                mixed, or assembly mode.

    F4           Displays the virtual output screen (press any key to
                return).

    F5           Executes to the next breakpoint or to the end of the
                program if no breakpoint is encountered.

    F6           Toggles between the display window and the dialog window.

    F7           Sets a temporary breakpoint on the line containing the
                cursor and executes to that line (or the next
                breakpoint).

    F8           Executes a trace command, stepping through program calls
                if present.

    F9           Sets or clears a breakpoint on the line containing the
                cursor.

    F10          Executes the next source line (in source mode) or the
                next instruction (in assembly mode), stepping over
                program calls if present.

    Ctrl+G       Increases the size of the display window or the dialog
                window, whichever is active.

    Ctrl+T       Decreases the size of the display window or the dialog
                window, whichever is active.


Dialog window commands

    After CodeView and the specified executable file are loaded, CodeView
    displays its special prompt character (>) at the bottom of the dialog
    window and awaits a dialog command. CodeView dialog commands consist
    of one, two, or three characters, usually followed by one or more
    parameters. CodeView treats uppercase and lowercase characters the
    same except when they are contained in strings enclosed within single
    or double quotation marks. The default radix for dialog command
    parameters is 10 (decimal). Dialog commands are executed when the
    Enter key is pressed.

    A detailed explanation of CodeView dialog commands and parameters is
    not presented in this entry. CodeView dialog commands and parameters
    are similar to SYMDEB commands and parameters. See PROGRAMMING
    UTILITIES: SYMDEB. Additional information about using CodeView
    dialog commands and parameters can be found in the CodeView
    documentation supplied with the Microsoft Macro Assembler (MASM), C
    Compiler, Pascal Compiler, and FORTRAN Compiler. A sample debugging
    session using CodeView dialog commands and window commands is
    documented in this book. See PROGRAMMING IN THE MS-DOS ENVIRONMENT:
    PROGRAMMING TOOLS: Debugging in the MS-DOS Environment.

    The dialog commands available with CodeView are as follows:

╓┌─────────────────┌─────────────────────────┌───────────────────────────────╖
    Command      Syntax                    Action
    ──────────────────────────────────────────────────────────────────────
    !            ! [command]               Escape to shell.
    "            "                         Pause redirected file
                                            execution.
    #            #number                   Set display window tabs.
    *            *comment                  Echo comment to output device.
    .            .                         Display current source line.
    /            /[searchtext]             Search for regular expression.
    7            7                         Display 8087 registers.
    :            :[:]...[:]                Delay redirected file
                                            execution.
    <            < device                  Redirect dialog window input.
    =            = device                  Redirect dialog window input
                                            and output.
    >            [T] > [>] device          Redirect dialog window output.
    ?            ? expression[,format]     Evaluate expression.
    @            @                         Redraw screen.
    A            A [address]               Assemble machine instructions.
    BC           BC [*] [list]             Clear breakpoints.
    BD           BD [*] [list]             Disable breakpoints.
    BE           BE [*] [list]             Enable breakpoints.
    BL           BL                        List breakpoints.
    BP           BP [address [passcount]   Set breakpoints.
                ["cmds"]]
    C            C range address           Compare memory areas.
    D            D [range]                 Display (dump) memory.
    DA           DA [range]                Display ASCII.
    DB           DB [range]                Display bytes.
    DD           DD [range]                Display doublewords.
    DI           DI [range]                Display integers.
    DL           DL [range]                Display long reals.
    DS           DS [range]                Display short reals.
    DT           DT [range]                Display 10-byte reals.
    DU           DU [range]                Display unsigned integers.
    DW           DW [range]                Display words.
    E            E address [list]          Enter data.
    EA           EA address [list]         Enter ASCII string.
    EB           EB address [list]         Enter bytes.
    ED           ED address [value]        Enter doublewords.
    EI           EI address [list]         Enter integers.
    EL           EL address [value]        Enter long reals.
    ES           ES address [value]        Enter short reals.
    ET           ET address [value]        Enter 10-byte reals.
    EU           EU address [value]        Enter unsigned integers.
    EW           EW address [value]        Enter words.
    F            F range list              Fill memory.
    G            G [breakpoint]            Go execute program.
    H            H                         Display help screen.
    I            I port                    Input from port.
    K            K [number]                Perform stack trace.
    L            L [parameters]            Reload program.
    M            M range address           Move (copy) data.
    N            N [radix]                 Change current radix.
    O            O port byte               Output to port.
    O            O                         Display all options.
    O3           O3[+|-]                   Toggle Intel 80386 option.
    OB           OB[+|-]                   Toggle bytes coded option.
    OC           OC[+|-]                   Toggle case-sense option.
    OF           OF[+|-]                   Toggle flip/swap option.
    P            P [count]                 Step through program (over
                                            calls).
    Q            Q                         Quit debugger.
    R            R [register [value]]      Display or modify registers.
    RF           RF [flags]                Display or modify flags.
    S            S range list              Search memory.
    S            S                         Display current display mode.
    S+           S+                        Display source code.
    S-           S-                        Display assembly language.
    S&           S&                        Display source code and
                                            assembly language.
    T            T [count]                 Trace program execution
                                            (through calls).
    TP           TP [type] range           Set memory-tracepoint
                                            statement.
    TP?          TP? expression[,format]   Set tracepoint-expression
                                            statement.
    U            U [range]                 Disassemble (unassemble)
                                            program.
    USE          USE [language]            Switch expression evaluators.
    V            V [.[filename:]linenumber View source code.
    W            W                         List watchpoints and
                                            tracepoints.
    W            W [type] range            Set memory-watch statement.
    W?           W? expression[,format]    Set watch-expression statement.
    WP?          WP? expression[,format]   Set watchpoint.
    X            X[?[module!]              Examine program symbols.
                [routine.]symbol|*]
    Y            Y [*] [list]              Delete watch statements.
    \            \                         Display virtual output screen.


Examples

    To prepare the source file SHELL.C for debugging with CodeView, first
    compile the source file with the switches that disable optimization
    and cause symbol-table and line-number information to be written to
    the relocatable object module:

    C>MSC /Zi /Od SHELL;  <Enter>

    Next, to convert the object module to an executable program and
    prepare it for CodeView, type

    C>LINK /CO SHELL;  <Enter>

    To begin debugging, type

    C>CV SHELL  <Enter>

    To start CodeView in 43-line mode with TEST.EXE as the executable file
    and INFO.DAT as the command-tail parameter, type

    C>CV /43 TEST INFO.DAT  <Enter>

    In both examples the source file corresponding to the specified
    executable file must be in the current directory if source-code
    display is desired.

Messages

    Argument to IMAG/DIMAG must be simple type
    An invalid parameter to an IMAG or DIMAG function, such as an array
    with no subscripts, was specified.

    Array must have subscript
    An array without any subscripts was specified in an expression, such
    as IARRAY + 2. A correct example is IARRAY[1] + 2.

    Bad address
    An invalid address was specified. For example, an address containing
    hexadecimal characters might have been specified when the radix is
    decimal.

    Bad breakpoint command
    An invalid breakpoint number was specified with the BC, BD, or BE
    dialog command. The breakpoint number must be in the range 0 through
    19.

    Bad flag
    An invalid flag mnemonic was specified with the RF dialog command.

    Bad format string
    An invalid format specifier was used following an expression.
    Expressions used with the ?, W?, WP?, and TP? dialog commands can have
    format specifiers set off from the expression by a comma. The valid
    format specifiers are c, d, e, E, f, g, G, i, o, s, u, x, and X. Some
    format specifiers can be preceded by the prefix h (to specify a 2-byte
    integer) or l (to specify a 4-byte integer).

    Bad integer or real constant
    An invalid numeric constant was specified in an expression.

    Bad intrinsic function
    An invalid intrinsic function name was specified in an expression.

    Badly formed type
    The type information in the symbol table of the file being debugged is
    incorrect. This is a serious problem. Note the circumstances of the
    failure and notify Microsoft Corporation.

    Bad radix (use 8, 10, or 16)
    An invalid radix was specified with the N dialog command. Use an
    octal, decimal, or hexadecimal radix.

    Bad register
    An invalid register name was specified with the R dialog command. Use
    AX, BX, CX, DX, SP, BP, SI, DI, DS, ES, SS, CS, or IP. If your machine
    is equipped with an Intel 80386 microprocessor, use EAX, EBX, ECX,
    EDX, ESP, EBP, ESI, EDI, DS, ES, FS, GS, SS, CS, or IP.

    Bad subscript
    An invalid subscript expression was specified for an array, such as
    IARRAY (3.3) or IARRAY ((3,3)). The correct expression for this
    example (in BASIC or FORTRAN) is IARRAY (3,3).

    Bad type cast
    Incompatible types of operands were specified in an expression.

    Bad type (use one of 'ABDILSTUW')
    An invalid type was used in a Display (D, DA, DB, DF, DU, DW, DD, DS,
    DL, or DT) dialog command. The valid types are ASCII (A), byte (B),
    integer (I), unsigned (U), word (W), doubleword (D), short real (S),
    long real (L), and 10-byte real (T).

    Breakpoint # or '*' expected
    The BC, BD, or BE dialog command was entered without a parameter.

    Cannot cast complex constant component into REAL
    An incompatible real or imaginary component was specified in a COMPLEX
    constant. Both real and imaginary components must be compatible with
    type REAL.

    Cannot cast IMAG/DIMAG argument to COMPLEX
    An invalid parameter was specified with an IMAG or DIMAG function.
    IMAG and DIMAG parameters must be simple numeric types.

    Cannot use struct or union as scalar
    A struct or union variable was used as a scalar value in a C
    expression. Such variables must be followed by a file specifier or
    preceded by the address-of (&) operator.

    Can't find filename
    CodeView could not find the executable file specified in the command
    line.

    Character constant too long
    A character constant that is too long for the FORTRAN expression
    evaluator was specified. The limit is 126 bytes.

    Character too big for current radix
    A radix that is larger than the current CodeView radix was specified
    in a constant. Use the N dialog command to change the radix.

    Constant too big
    An unsigned constant number larger than 4,294,967,295 (FFFFFFFFH) was
    specified.

    CPU not an 80386
    The 386 option was selected but a machine without an Intel 80386
    microprocessor is being used.

    Divide by zero
    An expression in a parameter of a dialog command attempted to divide
    by zero.

    EMM error
    CodeView failed to use the Expanded Memory Manager (EMM) correctly.
    This is a serious problem. Note the circumstances of the failure and
    notify Microsoft Corporation.

    EMM hardware error
    The Expanded Memory Manager (EMM) routines reported a hardware error.
    Check your expanded memory board for defects.

    EMM memory not found
    The /E option was used but expanded memory has not been installed.
    Install software that accesses the memory according to the
    Lotus/Intel/Microsoft  Expanded Memory Specification (LIM EMS).

    EMM software error
    The Expanded Memory Manager (EMM) routines reported a software error.
    Reinstall the EMM software.

    Expression too complex
    An expression given as a dialog-command parameter is too complex.

    Extra input ignored
    Too many parameters were specified with a command. CodeView evaluates
    the valid parameters and ignores the rest. In this situation, CodeView
    often does not evaluate the parameters as intended.

    Flip/Swap option off--application output lost
    The program being debugged is writing to the screen, but the output
    cannot be displayed because the flip/swap option has been disabled.

    Floating point error
    This is a serious problem. Note the circumstances of the failure and
    notify Microsoft Corporation.

    Illegal instruction
    This message usually indicates that a machine instruction attempted to
    divide by zero.

    Index out of bound
    A subscript value was specified that is outside the bounds declared
    for the array.

    Insufficient EMM memory
    Expanded memory is insufficient to hold the program's symbol table.

    Internal debugger error
    This is a serious problem. Note the circumstances of the failure and
    notify Microsoft Corporation.

    Invalid argument
    An invalid CodeView expression was specified as a parameter.

    Invalid executable file format--please relink
    The executable file was not linked with the version of LINK released
    with this version of the CodeView debugger. Relink with the
    appropriate version of LINK.

    Invalid option
    An invalid switch was specified with the O command.

    Missing ' " '
    A string specified as a parameter to a dialog command did not have a
    closing double quotation mark.

    Missing '('
    A parameter to a dialog command was specified as an expression
    containing a right parenthesis but no left parenthesis.

    Missing ')'
    A parameter to a dialog command was specified as an expression
    containing a left parenthesis but no right parenthesis.

    Missing ']'
    A parameter to a dialog command was specified as an expression
    containing a left bracket but no right bracket, or a regular
    expression was specified with a right bracket but no left
    bracket.

    Missing '(' in complex constant
    An opening parenthesis of a complex constant in an expression was
    expected but was not found.

    Missing ')' in complex constant
    A closing parenthesis of a complex constant in an expression was
    expected but was not found.

    Missing ')' in substring
    A closing parenthesis of a substring expression was expected but was
    not found.

    Missing '(' to intrinsic
    An opening parenthesis for an intrinsic function was expected but was
    not found.

    Missing ')' to intrinsic
    A closing parenthesis for an intrinsic function was expected but was
    not found.

    No closing single quote
    A character was specified in an expression used as a dialog-command
    parameter, but the closing single quotation mark is missing.

    No code at this line number
    A breakpoint was set on a source line that does not correspond to
    machine code. (In other words, the source line does not contain an
    executable statement.) For example, the line might be a data
    declaration or a comment.

    No free EMM memory handles
    CodeView could not find an available EMM handle. Expanded Memory
    Manager (EMM) software allocates a fixed number of memory handles
    (usually 256) to be used for specific tasks.

    No match of regular expression
    No match was found for the regular expression specified with the
    Search (S) dialog command or with the Find... command from the Search
    menu.

    No previous regular expression
    The Previous command was selected from the Search menu, but CodeView
    found no previous match for the last regular expression specified.

    No source lines at this address
    The address specified as a parameter for the V dialog command does not
    have any source lines. For example, it could be an address in a
    library routine or an assembly-language module.

    No such file/directory
    The specified file or directory does not exist.

    No symbolic information
    The executable file specified is not in the CodeView format. The
    program cannot be debugged in source mode unless the file is created
    in the CodeView format. The program can be debugged in assembly
    mode.

    Not an executable file
    The file specified to be debugged when CodeView started is not an
    executable file with a .EXE or .COM extension.

    Not a text file
    An attempt was made to load a file with the Open... command from the
    File menu or with the V dialog command, but the file is not a text
    file. CodeView determines if a file is a text file by checking the
    first 128 bytes for characters that are not in the ASCII ranges 9
    through 13 and 20 through 126.

    Not enough space
    The ! dialog command or the DOS Shell command from the File menu was
    chosen, but free memory is insufficient to execute COMMAND.COM.
    Because memory is released by code in the FORTRAN startup routines,
    this error always occurs if the ! command is used before executing any
    code. Use any of the code-execution dialog commands (T, P, or G) to
    execute the FORTRAN startup code; then try the ! command again. This
    message also occurs with assembly-language programs that do not
    specifically release memory.

    Object too big
    A TP? dialog command was entered with a data object (such as an array)
    that is larger than 128 bytes.

    Operand types incorrect for this operation
    An operand in a FORTRAN expression had a type incompatible with the
    operation applied to it. For example, if P is declared as CHARACTER P
    (10), then ? P+5 would produce this error, because a character array
    cannot be an operand of an arithmetic operator.

    Operator must have a struct/union type
    One of the C member-selection operators (-, >, or .) was used in an
    expression that does not reference an element of a structure or
    union.

    Operator needs lvalue
    An expression was specified that does not evaluate to a memory
    location in an operation that requires one. (An lvalue is an
    expression that refers to a memory location.) For example,
    buffer (count) is correct; it represents a symbol in memory.
    However, I .EQV. 10 is invalid because it evaluates to TRUE or
    FALSE instead of to a single memory location.

    Overlay not resident
    An attempt was made to unassemble machine code from a function that is
    currently not in memory.

    Program terminated normally (exitcode)
    The program terminated execution normally. The number displayed in
    parentheses is the exit code returned to MS-DOS by the program.

    Radix must be between 2 and 36 inclusive
    A radix that is outside the allowable range was specified.

    Register variable out of scope
    An attempt was made to specify a register variable by using the period
    (.) operator and a routine name.

    Regular expression too complex
    The regular expression specified is too complex for CodeView to
    evaluate.

    Regular expression too long
    The regular expression specified is too long for CodeView to
    evaluate.

    Restart program to debug
    The program being debugged has executed to the end.

    Simple variable cannot have argument
    A parameter to a simple variable was specified in an expression. For
    example, given the declaration INTEGER NUM, the expression NUM(I) is
    not allowed.

    Substring range out of bound
    A character expression exceeded the length specified in the CHARACTER
    statement.

    Syntax error
    An invalid command line was specified for a dialog command, or an
    invalid assembly-language instruction was entered with the A dialog
    command.

    Too few array bounds given
    The bounds specified in an array subscript do not match the array
    declaration. For example, given the array declaration INTEGER
    IARRAY(3,4), the expression IARRAY(I) would produce this error
    message.

    Too many array bounds given
    The bounds specified in an array subscript do not match the array
    declaration. For example, given the array declaration INTEGER
    IARRAY(3,4), the expression IARRAY(I,3,J) would produce this error
    message.

    Too many breakpoints
    An attempt was made to specify more than 20 breakpoints; CodeView
    permits only 20.

    Too many files
    Too few file handles were specified for CodeView to operate correctly.
    Specify more files in your CONFIG.SYS file.

    Type clash in function argument
    The type of an actual parameter does not match the corresponding
    formal parameter, or a subroutine that uses alternate returns was
    called and the values of the return labels in the actual parameter
    list are not 0.

    Type conversion too complex
    An attempt was made to typecast an element of an expression in a type
    other than the simple types or with more than one level of
    indirection. An example of a complex type would be typecasting to a
    struct or union type. An example of two levels of indirection is
    char **.

    Unable to open file
    A file specified in a command parameter or in response to a prompt
    cannot be opened.

    Unknown symbol
    An identifier that is not in CodeView's symbol table was specified, or
    a local variable was used in a parameter when not in the routine where
    the variable is defined, or a subroutine that uses alternate returns
    was called and the values of the return labels in the parameter list
    are not 0.

    Unrecognized option option
    Valid options: /B /C<command> /D /E /F /I /M /P /R /S /T /W /43 /2
    An invalid switch was entered when starting CodeView.

    Usage: cv [options] file [arguments]
    An executable file was not specified when starting CodeView.

    Video mode changed without /S option
    The program changed video modes (either to or from graphics modes)
    when screen swapping was not specified. Use the /S option to specify
    screen swapping when debugging graphics programs. Debugging can be
    continued after receiving this message, but the output screen of the
    debugged program may be damaged.

    Warning: packed file
    CodeView was started with a packed file as the executable file. The
    program cannot be debugged in source mode because all symbolic
    information is stripped from a file when it is packed with LINK's
    /EXEPACK option or the EXEPACK utility. Try to debug the program in
    assembly mode. (The packing routines at the start of the program might
    make this difficult.)

    Wrong number of function arguments
    An incorrect number of parameters was specified when evaluating a
    function in a CodeView expression.

Return to The MS-DOS Encyclopedia: Contents