home *** CD-ROM | disk | FTP | other *** search
/ For Beginners & Professional Hackers / cd.iso / docum / advdos.doc / s1c04 < prev    next >
Encoding:
Text File  |  1992-04-21  |  48.3 KB  |  1,088 lines

  1. ────────────────────────────────────────────────────────────────────────────
  2. Chapter 4  MS-DOS Programming Tools
  3.  
  4.   Preparing a new program to run under MS-DOS is an iterative process with
  5.   four basic steps:
  6.  
  7.   ■  Use of a text editor to create or modify an ASCII source-code file
  8.  
  9.   ■  Use of an assembler or high-level-language compiler (such as the
  10.      Microsoft Macro Assembler or the Microsoft C Optimizing Compiler) to
  11.      translate the source file into relocatable object code
  12.  
  13.   ■  Use of a linker to transform the relocatable object code into an
  14.      executable MS-DOS load module
  15.  
  16.   ■  Use of a debugger to methodically test and debug the program
  17.  
  18.   Additional utilities the MS-DOS software developer may find necessary or
  19.   helpful include the following:
  20.  
  21.   ■  LIB, which creates and maintains object-module libraries
  22.  
  23.   ■  CREF, which generates a cross-reference listing
  24.  
  25.   ■  EXE2BIN, which converts .EXE files to .COM files
  26.  
  27.   ■  MAKE, which compares dates of files and carries out operations based on
  28.      the result of the comparison
  29.  
  30.   This chapter gives an operational overview of the Microsoft programming
  31.   tools for MS-DOS, including the assembler, the C compiler, the linker, and
  32.   the librarian. In general, the information provided here also applies to
  33.   the IBM programming tools for MS-DOS, which are really the Microsoft
  34.   products with minor variations and different version numbers. Even if your
  35.   preferred programming language is not C or assembly language, you will
  36.   need at least a passing familiarity with these tools because all of the
  37.   examples in the IBM and Microsoft DOS reference manuals are written in one
  38.   of these languages.
  39.  
  40.   The survey in this chapter, together with the example programs and
  41.   reference section elsewhere in the book, should provide the experienced
  42.   programmer with sufficient information to immediately begin writing useful
  43.   programs. Readers who do not have a background in C, assembly language, or
  44.   the Intel 80x86 microprocessor architecture should refer to the tutorial
  45.   and reference works listed at the end of this chapter.
  46.  
  47.  
  48. File Types
  49.  
  50.   The MS-DOS programming tools can create and process many different file
  51.   types. The following extensions are used by convention for these files:
  52.  
  53.  
  54.   Extension  File type
  55.   ──────────────────────────────────────────────────────────────────────────
  56.   .ASM       Assembly-language source file
  57.  
  58.   .C         C source file
  59.  
  60.   .COM       MS-DOS executable load module that does not require relocation
  61.              at runtime
  62.  
  63.   .CRF       Cross-reference information file produced by the assembler for
  64.              processing by CREF.EXE
  65.  
  66.   .DEF       Module-definition file describing a program's segment behavior
  67.              (MS OS/2 and Microsoft Windows programs only; not relevant to
  68.              normal MS-DOS applications)
  69.  
  70.   .EXE       MS-DOS executable load module that requires relocation at
  71.              runtime
  72.  
  73.   .H         C header file containing C source code for constants, macros,
  74.              and functions; merged into another C program with the #include
  75.              directive
  76.  
  77.   .INC       Include file for assembly-language programs, typically
  78.              containing macros and/or equates for systemwide values such as
  79.              error codes
  80.  
  81.   .LIB       Object-module library file made up of one or more .OBJ files;
  82.              indexed and manipulated by LIB.EXE
  83.  
  84.   .LST       Program listing, produced by the assembler, that includes
  85.              memory locations, machine code, the original program text, and
  86.              error messages
  87.  
  88.   .MAP       Listing of symbols and their locations within a load module;
  89.              produced by the linker
  90.  
  91.   .OBJ       Relocatable-object-code file produced by an assembler or
  92.              compiler
  93.  
  94.   .REF       Cross-reference listing produced by CREF.EXE from the
  95.              information in a .CRF file
  96.   ──────────────────────────────────────────────────────────────────────────
  97.  
  98.  
  99.  
  100. The Microsoft Macro Assembler
  101.  
  102.   The Microsoft Macro Assembler (MASM) is distributed as the file MASM.EXE.
  103.   When beginning a program translation, MASM needs the following
  104.   information:
  105.  
  106.   ■  The name of the file containing the source program
  107.  
  108.   ■  The filename for the object program to be created
  109.  
  110.   ■  The destination of the program listing
  111.  
  112.   ■  The filename for the information that is later processed by the
  113.      cross-reference utility (CREF.EXE)
  114.  
  115.   You can invoke MASM in two ways. If you enter the name of the assembler
  116.   alone, it prompts you for the names of each of the various input and
  117.   output files. The assembler supplies reasonable defaults for all the
  118.   responses except the source filename, as shown in the following example:
  119.  
  120.   C>MASM  <Enter>
  121.  
  122.   Microsoft (R) Macro Assembler Version 5.10
  123.   Copyright (C) Microsoft Corp 1981, 1988. All rights reserved.
  124.  
  125.   Source filename [.ASM]: HELLO  <Enter>
  126.   Object filename [HELLO.OBJ]:  <Enter>
  127.   Source listing  [NUL.LST]:  <Enter>
  128.   Cross-reference [NUL.CRF]:  <Enter>
  129.  
  130.     49006 Bytes symbol space free
  131.  
  132.         0 Warning Errors
  133.         0 Severe Errors
  134.  
  135.   C>
  136.  
  137.   You can use a logical device name (such as PRN or COM1) at any of the MASM
  138.   prompts to send that output of the assembler to a character device rather
  139.   than a file. Note that the default for the listing and cross-reference
  140.   files is the NUL device──that is, no file is created. If you end any
  141.   response with a semicolon, MASM assumes that the remaining responses are
  142.   all to be the default.
  143.  
  144.   A more efficient way to use MASM is to supply all parameters in the
  145.   command line, as follows:
  146.  
  147.     MASM [options] source,[object],[listing],[crossref]
  148.  
  149.   For example, the following command lines are equivalent to the preceding
  150.   interactive session:
  151.  
  152.   C>MASM HELLO,,NUL,NUL  <Enter>
  153.  
  154.   or
  155.  
  156.   C>MASM HELLO;  <Enter>
  157.  
  158.   These commands use the file HELLO.ASM as the source, generate the
  159.   object-code file HELLO.OBJ, and send the listing and cross-reference files
  160.   to the bit bucket.
  161.  
  162.   MASM accepts several optional switches in the command line, to control
  163.   code generation and output files. Figure 4-1 lists the switches accepted
  164.   by MASM version 5.1. As shown in the following example, you can put
  165.   frequently used options in a MASM environment variable, where they will be
  166.   found automatically by the assembler:
  167.  
  168.   C>SET MASM=/T /Zi  <Enter>
  169.  
  170.   The switches in the environment variable will be overridden by any that
  171.   you enter in the command line.
  172.  
  173.   In other versions of the Microsoft Macro Assembler, additional or fewer
  174.   switches may be available. For exact instructions, see the manual for the
  175.   version of MASM that you are using.
  176.  
  177.  
  178.   Switch     Meaning
  179.   ──────────────────────────────────────────────────────────────────────────
  180.   /A         Arrange segments in alphabetic order.
  181.   /Bn        Set size of source-file buffer (in KB).
  182.   /C         Force creation of a cross-reference (.CRF) file.
  183.   /D         Produce listing on both passes (to find phase errors).
  184.   /Dsymbol   Define symbol as a null text string (symbol can be referenced
  185.              by conditional assembly directives in file).
  186.   /E         Assemble for 80x87 numeric coprocessor emulator using IEEE
  187.              real-number format.
  188.   /Ipath     Set search path for include files.
  189.   /L         Force creation of a program-listing file.
  190.   /LA        Force listing of all generated code.
  191.   /ML        Preserve case sensitivity in all names (uppercase names
  192.              distinct from their lowercase equivalents).
  193.   /MX        Preserve lowercase in external names only (names defined with
  194.              PUBLIC or EXTRN directives).
  195.   /MU        Convert all lowercase names to uppercase.
  196.   /N         Suppress generation of tables of macros, structures, records,
  197.              segments, groups, and symbols at the end of the listing.
  198.   /P         Check for impure code in 80286/80386 protected mode.
  199.   /S         Arrange segments in order of occurrence (default).
  200.   /T         "Terse" mode; suppress all messages unless errors are
  201.              encountered during the assembly.
  202.   /V         "Verbose" mode; report number of lines and symbols at end of
  203.              assembly.
  204.   /Wn        Set error display (warning) level; n=0─2.
  205.   /X         Force listing of false conditionals.
  206.   /Z         Display source lines containing errors on the screen.
  207.   /Zd        Include line-number information in .OBJ file.
  208.   /Zi        Include line-number and symbol information in .OBJ file.
  209.   ──────────────────────────────────────────────────────────────────────────
  210.  
  211.  
  212.   Figure 4-1.  Microsoft Macro Assembler version 5.1 switches.
  213.  
  214.   MASM allows you to override the default extensions on any file──a feature
  215.   that can be rather dangerous. For example, if in the preceding example you
  216.   had responded to the Object filename prompt with HELLO.ASM, the assembler
  217.   would have accepted the entry without comment and destroyed your source
  218.   file. This is not too likely to happen in the interactive command mode,
  219.   but you must be very careful with file extensions when MASM is used in a
  220.   batch file.
  221.  
  222.  
  223. The Microsoft C Optimizing Compiler
  224.  
  225.   The Microsoft C Optimizing Compiler consists of three executable files──
  226.   C1.EXE, C2.EXE, and C3.EXE──that implement the C preprocessor, language
  227.   translator, code generator, and code optimizer. An additional control
  228.   program, CL.EXE, executes the three compiler files in order, passing each
  229.   the necessary information about filenames and compilation options.
  230.  
  231.   Before using the C compiler and the linker, you need to set up four
  232.   environment variables:
  233.  
  234.   Variable                 Action
  235.   ──────────────────────────────────────────────────────────────────────────
  236.   PATH=path                Specifies the location of the three executable C
  237.                            compiler files (C1, C2, and C3) if they are not
  238.                            in the current directory; used by CL.EXE.
  239.  
  240.   INCLUDE=path             Specifies the location of #include files (default
  241.                            extension .H) that are not found in the current
  242.                            directory.
  243.  
  244.   LIB=path                 Specifies the location(s) for object-code
  245.                            libraries that are not found in the current
  246.                            directory.
  247.  
  248.   TMP=path                 Specifies the location for temporary working
  249.                            files created by the C compiler and linker.
  250.   ──────────────────────────────────────────────────────────────────────────
  251.  
  252.   CL.EXE does not support an interactive mode or response files. You always
  253.   invoke it with a command line of the following form:
  254.  
  255.     CL [options] file [file ...]
  256.  
  257.   You may list any number of files──if a file has a .C extension, it will be
  258.   compiled into a relocatable-object-module (.OBJ) file. Ordinarily, if the
  259.   compiler encounters no errors, it automatically passes all resulting .OBJ
  260.   files and any additional .OBJ files specified in the command line to the
  261.   linker, along with the names of the appropriate runtime libraries.
  262.  
  263.   The C compiler has many optional switches controlling its memory models,
  264.   output files, code generation, and code optimization. These are summarized
  265.   in Figure 4-2. The C compiler's arcane switch syntax is derived largely
  266.   from UNIX/XENIX, so don't expect it to make any sense.
  267.  
  268.  
  269.   Switch                   Meaning
  270.   ──────────────────────────────────────────────────────────────────────────
  271.   /Ax                      Select memory model:
  272.                            C = compact model
  273.                            H = huge model
  274.                            L = large model
  275.                            M = medium model
  276.                            S = small model (default)
  277.   /c                       Compile only; do not invoke linker.
  278.   /C                       Do not strip comments.
  279.   /D<name>[=text]          Define macro.
  280.   /E                       Send preprocessor output to standard output.
  281.   /EP                      Send preprocessor output to standard output
  282.                            without line numbers.
  283.   /F<n>                    Set stack size (in hexadecimal bytes).
  284.   /Fa [filename]           Generate assembly listing.
  285.   /Fc [filename]           Generate mixed source/object listing.
  286.   /Fe [filename]           Force executable filename.
  287.   /Fl [filename]           Generate object listing.
  288.   /Fm [filename]           Generate map file.
  289.   /Fo [filename]           Force object-module filename.
  290.   /FPx                     Select floating-point control:
  291.                            a = calls with alternate math library
  292.                            c = calls with emulator library
  293.                            c87 = calls with 8087 library
  294.                            i = in-line with emulator (default)
  295.                            i87 = in-line with 8087
  296.   /Fs [filename]           Generate source listing.
  297.   /Gx                      Select code generation:
  298.                            0 = 8086 instructions (default)
  299.                            1 = 186 instructions
  300.                            2 = 286 instructions
  301.                            c = Pascal style function calls
  302.                            s = no stack checking
  303.                            t[n] = data size threshold
  304.   /H<n>                    Specify external name length.
  305.   /I<path>                 Specify additional #include path.
  306.   /J                       Specify default char type as unsigned.
  307.   /link [options]          Pass switches and library names to linker.
  308.   /Ox                      Select optimization:
  309.                            a = ignore aliasing
  310.                            d = disable optimizations
  311.                            i = enable intrinsic functions
  312.                            l = enable loop optimizations
  313.                            n = disable "unsafe" optimizations
  314.                            p = enable precision optimizations
  315.                            r = disable in-line return
  316.                            s = optimize for space
  317.   /Ox                      t = optimize for speed (default)
  318.                            w = ignore aliasing except across function
  319.                            calls
  320.                            x = enable maximum optimization (equivalent to
  321.                            /Oailt /Gs)
  322.   /P                       Send preprocessor output to file.
  323.   /Sx                      Select source-listing control:
  324.                            l<columns> = set line width
  325.                            p<lines> = set page length
  326.                            s<string> = set subtitle string
  327.                            t<string> = set title string
  328.   /Tc<file>                Compile file without .C extension.
  329.   /u                       Remove all predefined macros.
  330.   /U<name>                 Remove specified predefined macro.
  331.   /V<string>               Set version string.
  332.   /W<n>                    Set warning level (0─3).
  333.   /X                       Ignore "standard places" for include files.
  334.   /Zx                      Select miscellaneous compilation control:
  335.                            a = disable extensions
  336.                            c = make Pascal functions case-insensitive
  337.                            d = include line-number information
  338.                            e = enable extensions (default)
  339.                            g = generate declarations
  340.                            i = include symbolic debugging information
  341.                            l = remove default library info
  342.                            p<n> = pack structures on n-byte boundary
  343.                            s = check syntax only
  344.   ──────────────────────────────────────────────────────────────────────────
  345.  
  346.  
  347.   Figure 4-2.  Microsoft C Optimizing Compiler version 5.1 switches.
  348.  
  349.  
  350. The Microsoft Object Linker
  351.  
  352.   The object module produced by MASM from a source file is in a form that
  353.   contains relocation information and may also contain unresolved references
  354.   to external locations or subroutines. It is written in a common format
  355.   that is also produced by the various high-level compilers (such as FORTRAN
  356.   and C) that run under MS-DOS. The computer cannot execute object modules
  357.   without further processing.
  358.  
  359.   The Microsoft Object Linker (LINK), distributed as the file LINK.EXE,
  360.   accepts one or more of these object modules, resolves external references,
  361.   includes any necessary routines from designated libraries, performs any
  362.   necessary offset relocations, and writes a file that can be loaded and
  363.   executed by MS-DOS. The output of LINK is always in .EXE load-module
  364.   format. (See Chapter 3.)
  365.  
  366.   As with MASM, you can give LINK its parameters interactively or by
  367.   entering all the required information in a single command line. If you
  368.   enter the name of the linker alone, the following type of dialog ensues:
  369.  
  370.   C>LINK  <Enter>
  371.  
  372.   Microsoft (R) Overlay Linker  Version 3.61
  373.   Copyright (C) Microsoft Corp 1983-1987. All rights reserved.
  374.  
  375.   Object Modules [.OBJ]: HELLO  <Enter>
  376.   Run File [HELLO.EXE]:  <Enter>
  377.   List File [NUL.MAP]: HELLO  <Enter>
  378.   Libraries [.LIB]:  <Enter>
  379.  
  380.   C>
  381.  
  382.   If you are using LINK version 4.0 or later, the linker also asks for the
  383.   name of a module-definition (.DEF) file. Simply press the Enter key in
  384.   response to such a prompt. Module-definition files are used when building
  385.   Microsoft Windows or MS OS/2 "new .EXE" executable files but are not
  386.   relevant in normal MS-DOS applicatio s.
  387.  
  388.   The input file for this example was HELLO.OBJ; the output files were
  389.   HELLO.EXE (the executable program) and HELLO.MAP (the load map produced by
  390.   the linker after all references and addresses were resolved). Figure 4-3
  391.   shows the load map.
  392.  
  393.   ──────────────────────────────────────────────────────────────────────────
  394.    Start  Stop   Length Name                   Class
  395.    00000H 00017H 00018H _TEXT                  CODE
  396.    00018H 00027H 00010H _DATA                  DATA
  397.    00030H 000AFH 00080H STACK                  STACK
  398.    000B0H 000BBH 0000CH $$TYPES                DEBTYP
  399.    000C0H 000D6H 00017H $$SYMBOLS              DEBSYM
  400.  
  401.     Address         Publics by Name
  402.  
  403.     Address         Publics by Value
  404.  
  405.   Program entry point at 0000:0000
  406.   ──────────────────────────────────────────────────────────────────────────
  407.  
  408.   Figure 4-3.  Map produced by the Microsoft Object Linker (LINK) during the
  409.   generation of the HELLO.EXE program from Chapter 3. The program contains
  410.   one CODE, one DATA, and one STACK segment. The first instruction to be
  411.   executed lies in the first byte of the CODE segment. The $$TYPES and
  412.   $$SYMBOLS segments contain information for the CodeView debugger and are
  413.   not part of the program; these segments are ignored by the normal MS-DOS
  414.   loader.
  415.  
  416.   You can obtain the same result more quickly by entering all parameters in
  417.   the command line, in the following form:
  418.  
  419.     LINK options objectfile, [exefile], [mapfile], [libraries]
  420.  
  421.   Thus, the command-line equivalent to the preceding interactive session is
  422.  
  423.   C>LINK HELLO,HELLO,HELLO,,  <Enter>
  424.  
  425.   or
  426.  
  427.   C>LINK HELLO,,HELLO;  <Enter>
  428.  
  429.   If you enter a semicolon as the last character in the command line, LINK
  430.   assumes the default values for all further parameters.
  431.  
  432.   A third method of commanding LINK is with a response file. A response file
  433.   contains lines of text that correspond to the responses you would give the
  434.   linker interactively. You specify the name of the response file in the
  435.   command line with a leading  character, as follows:
  436.  
  437.     LINK filename
  438.  
  439.   You can also enter the name of a response file at any prompt. If the
  440.   response file is not complete, LINK will prompt you for the missing
  441.   information.
  442.  
  443.   When entering linker commands, you can specify multiple object files with
  444.   the + operator or with spaces, as in the following example:
  445.  
  446.   C>LINK HELLO+VMODE+DOSINT,MYPROG,,GRAPHICS;  <Enter>
  447.  
  448.   This command would link the files HELLO.OBJ, VMODE.OBJ, and DOSINT.OBJ,
  449.   searching the library file GRAPHICS.LIB to resolve any references to
  450.   symbols not defined in the specified object files, and would produce a
  451.   file named MYPROG.EXE. LINK uses the current drive and directory when they
  452.   are not explicitly included in a filename; it will not automatically use
  453.   the same drive and directory you specified for a previous file in the same
  454.   command line.
  455.  
  456.   By using the + operator or space characters in the libraries field, you
  457.   can specify up to 32 library files to be searched. Each high-level-
  458.   language compiler provides default libraries that are searched
  459.   automatically during the linkage process if the linker can find them
  460.   (unless they are explicitly excluded with the /NOD switch). LINK looks for
  461.   libraries first in the current directory of the default disk drive, then
  462.   along any paths that were provided in the command line, and finally along
  463.   the path(s) specified by the LIB variable if it is present in the
  464.   environment.
  465.  
  466.   LINK accepts several optional switches as part of the command line or at
  467.   the end of any interactive prompt. Figure 4-4 lists these switches. The
  468.   number of switches available and their actions vary among different
  469.   versions of LINK. See your Microsoft Object Linker instruction manual for
  470.   detailed information about your particular version.
  471.  
  472.  
  473.   Switch   Full form                   Meaning
  474.   ──────────────────────────────────────────────────────────────────────────
  475.   /A:n     /ALIGNMENT:n                Set segment sector alignment factor.
  476.                                        N must be a power of 2 (default =
  477.                                        512). Not related to logical-segment
  478.                                        alignment (BYTE, WORD, PARA, PAGE,
  479.                                        and so forth). Relevant to segmented
  480.                                        executable files (Microsoft Windows
  481.                                        and MS OS/2) only.
  482.  
  483.   /B       /BATCH                      Suppress linker prompt if a library
  484.                                        cannot be found in the current
  485.                                        directory or in the locations
  486.                                        specified by the LIB environment
  487.                                        variable.
  488.  
  489.   /CO      /CODEVIEW                   Include symbolic debugging
  490.                                        information in the .EXE file for use
  491.                                        by CodeView.
  492.  
  493.   /CP      /CPARMAXALLOC               Set the field in the .EXE file header
  494.                                        controlling the amount of memory
  495.                                        allocated to the program in addition
  496.                                        to the memory required for the
  497.                                        program's code, stack, and
  498.                                        initialized data.
  499.  
  500.   /DO      /DOSSEG                     Use standard Microsoft segment naming
  501.                                        and ordering conventions.
  502.  
  503.   /DS      /DSALLOCATE                 Load data at high end of the data
  504.                                        segment. Relevant to real-mode
  505.                                        programs only.
  506.  
  507.   /E       /EXEPACK                    Pack executable file by removing
  508.                                        sequences of repeated bytes and
  509.                                        optimizing relocation table.
  510.  
  511.   /F       /FARCALLTRANSLATION         Optimize far calls to labels within
  512.                                        the same physical segment for speed
  513.                                        by replacing them with near calls and
  514.                                        NOPs.
  515.  
  516.   /HE      /HELP                       Display information about available
  517.                                        options.
  518.  
  519.   /HI      /HIGH                       Load program as high in memory as
  520.                                        possible.
  521.  
  522.   /I       /INFORMATION                Display information about progress of
  523.                                        linking, including pass numbers and
  524.                                        the names of object files being
  525.                                        linked.
  526.  
  527.   /INC     /INCREMENTAL                Force production of .SYM and .ILK
  528.                                        files for subsequent use by ILINK
  529.                                        (incremental linker). May not be used
  530.                                        with /EXEPACK. Relevant to segmented
  531.                                        executable files (Microsoft Windows
  532.                                        and MS OS/2) only.
  533.  
  534.   /LI      /LINENUMBERS                Write address of the first
  535.                                        instruction that corresponds to each
  536.                                        source-code line to the map file. Has
  537.                                        no effect if the compiler does not
  538.                                        include line-number information in
  539.                                        the object module. Force creation of
  540.                                        a map file.
  541.  
  542.   /M[:n]   /MAP[:n]                    Force creation of a .MAP file listing
  543.                                        all public symbols, sorted by name
  544.                                        and by location. The optional value n
  545.                                        is the maximum number of symbols that
  546.                                        can be sorted (default = 2048); when
  547.                                        n is supplied, the alphabetically
  548.                                        sorted list is omitted.
  549.  
  550.   /NOD     /NODEFAULTLIBRARYSEARCH     Skip search of any default compiler
  551.                                        libraries specified in the .OBJ file.
  552.  
  553.   /NOE     /NOEXTENDEDDICTSEARCH       Ignore extended library dictionary
  554.                                        (if it is present). The extended
  555.                                        dictionary ordinarily provides the
  556.                                        linker with information about
  557.                                        inter-module dependencies, to speed
  558.                                        up linking.
  559.  
  560.   /NOF     /NOFARCALLTRANSLATION       Disable optimization of far calls to
  561.                                        labels within the same segment.
  562.  
  563.   /NOG     /NOGROUPASSOCIATION         Ignore group associations when
  564.                                        assigning addresses to data and code
  565.                                        items.
  566.  
  567.   /NOI     /NOIGNORECASE               Do not ignore case in names during
  568.                                        linking.
  569.  
  570.   /NON     /NONULLSDOSSEG              Arrange segments as for /DOSSEG but
  571.                                        do not insert 16 null bytes at start
  572.                                        of _TEXT segment.
  573.  
  574.   /NOP     /NOPACKCODE                 Do not pack contiguous logical code
  575.                                        segments into a single physical
  576.                                        segment.
  577.  
  578.   /O:n     /OVERLAYINTERRUPT:n         Use interrupt number n with the
  579.                                        overlay manager supplied with some
  580.                                        Microsoft high-level languages.
  581.  
  582.   /PAC[:n] /PACKCODE[:n]               Pack contiguous logical code segments
  583.                                        into a single physical code segment.
  584.                                        The optional value n is the maximum
  585.                                        size for each packed physical code
  586.                                        segment (default = 65,536 bytes).
  587.                                        Segments in different groups are not
  588.                                        packed.
  589.  
  590.   /PADC:n  /PADCODE:n                  Add n filler bytes to end of each
  591.                                        code module so that a larger module
  592.                                        can be inserted later with ILINK.
  593.                                        Relevant to segmented executable
  594.                                        files (Windows and MS OS/2) only.
  595.  
  596.   /PADD:n  /PADDATA:n                  Add n filler bytes to end of each
  597.                                        data module so that a larger module
  598.                                        can be inserted later with ILINK.
  599.                                        Relevant to segmented executable
  600.                                        files (Microsoft Windows and MS OS/2)
  601.                                        only.
  602.  
  603.   /PAU     /PAUSE                      Pause during linking, allowing a
  604.                                        change of disks before .EXE file is
  605.                                        written.
  606.  
  607.   /SE:n    /SEGMENTS:n                 Set maximum number of segments in
  608.                                        linked program (default = 128).
  609.  
  610.   /ST:n    /STACK:n                    Set stack size of program in bytes;
  611.                                        ignore stack segment size
  612.                                        declarations within object modules
  613.                                        and definition file.
  614.  
  615.   /W       /WARNFIXUP                  Display warning messages for offsets
  616.                                        relative to a segment base that is
  617.                                        not the same as the group base.
  618.                                        Relevant to segmented executable
  619.                                        files (Microsoft Windows and MS OS/2)
  620.                                        only.
  621.   ──────────────────────────────────────────────────────────────────────────
  622.  
  623.  
  624.   Figure 4-4.  Switches accepted by the Microsoft Object Linker (LINK)
  625.   version 5.0. Earlier versions use a subset of these switches. Note that
  626.   any abbreviation for a switch is acceptable as long as it is sufficient to
  627.   specify the switch uniquely.
  628.  
  629.  
  630. The EXE2BIN Utility
  631.  
  632.   The EXE2BIN utility (EXE2BIN.EXE) transforms a .EXE file created by LINK
  633.   into an executable .COM file, if the program meets the following
  634.   prerequisites:
  635.  
  636.   ■  It cannot contain more than one declared segment and cannot
  637.      define a stack.
  638.  
  639.   ■  It must be less than 64 KB in length.
  640.  
  641.   ■  It must have an origin at 0100H.
  642.  
  643.   ■  The first location in the file must be specified as the entry point
  644.      in the source code's END directive.
  645.  
  646.   Although .COM files are somewhat more compact than .EXE files, you should
  647.   avoid using them. Programs that use separate segments for code, data, and
  648.   stack are much easier to port to protected-mode environments such as MS
  649.   OS/2; in addition, .COM files do not support the symbolic debugging
  650.   information used by CodeView.
  651.  
  652.   Another use for the EXE2BIN utility is to convert an installable device
  653.   driver──after it is assembled and linked into a .EXE file──into a
  654.   memory-image .BIN or .SYS file with an origin of zero. This conversion is
  655.   required in MS-DOS version 2, which cannot load device drivers as .EXE
  656.   files. The process of writing an installable device driver is discussed in
  657.   more detail in Chapter 14.
  658.  
  659.   Unlike most of the other programming utilities, EXE2BIN does not have an
  660.   interactive mode. It always takes its source and destination filenames,
  661.   separated by spaces, from the MS-DOS command line, as follows:
  662.  
  663.     EXE2BIN sourcefile [destinationfile]
  664.  
  665.   If you do not supply the source-file extension, it defaults to .EXE; the
  666.   destination-file extension defaults to .BIN. If you do not specify a name
  667.   for the destination file, EXE2BIN gives it the same name as the source
  668.   file, with a .BIN extension.
  669.  
  670.   For example, to convert the file HELLO.EXE into HELLO.COM, you would use
  671.   the following command line:
  672.  
  673.   C>EXE2BIN HELLO.EXE HELLO.COM  <Enter>
  674.  
  675.   The EXE2BIN program also has other capabilities, such as pure binary
  676.   conversion with segment fixup for creating program images to be placed in
  677.   ROM; but because these features are rarely used during MS-DOS application
  678.   development, they will not be discussed here.
  679.  
  680.  
  681. The CREF Utility
  682.  
  683.   The CREF cross-reference utility CREF.EXE processes a .CRF file produced
  684.   by MASM, creating an ASCII text file with the default extension .REF. The
  685.   file contains a cross-reference listing of all symbols declared in the
  686.   program and the line numbers in which they are referenced. (See Figure
  687.   4-5.) Such a listing is very useful when debugging large
  688.   assembly-language programs with many interdependent procedures and
  689.   variables.
  690.  
  691.   CREF may be supplied with its parameters interactively or in a single
  692.   command line. If you enter the utility name alone, CREF prompts you for
  693.   the input and output filenames, as shown in the following example:
  694.  
  695.   C>CREF  <Enter>
  696.  
  697.   Microsoft (R) Cross-Reference Utility  Version 5.10
  698.   Copyright (C) Microsoft Corp 1981-1985, 1987. All rights reserved.
  699.  
  700.   Cross-reference [.CRF]: HELLO  <Enter>
  701.   Listing [HELLO.REF]:
  702.  
  703.   15 Symbols
  704.  
  705.   C>
  706.  
  707.   ──────────────────────────────────────────────────────────────────────────
  708.   Microsoft Cross-Reference  Version 5.10       Thu May 26 11:09:34 1988
  709.   HELLO.EXE --- print Hello on terminal
  710.  
  711.     Symbol Cross-Reference    (# definition, + modification)Cref-1
  712.  
  713.   CPU . . . . . . . . . . . . . .   1#
  714.   VERSION . . . . . . . . . . . .   1#
  715.  
  716.   CODE . . . . . . . . . . . . . .  21
  717.   CR . . . . . . . . . . . . . . .  17#    46     47
  718.  
  719.   DATA . . . . . . . . . . . . . .  44
  720.  
  721.   LF . . . . . . . . . . . . . . .  18#    46     47
  722.  
  723.   MSG. . . . . . . . . . . . . . .  33     46#
  724.   MSG_LEN. . . . . . . . . . . . .  32     49#
  725.  
  726.   PRINT. . . . . . . . . . . . . .  25#    39     60
  727.  
  728.   STACK. . . . . . . . . . . . . .  23     54#    54     58
  729.   STDERR . . . . . . . . . . . . .  15#
  730.   STDIN. . . . . . . . . . . . . .  13#
  731.   STDOUT . . . . . . . . . . . . .  14#    31
  732.  
  733.   _DATA. . . . . . . . . . . . . .  23     27     44#    51
  734.   _TEXT. . . . . . . . . . . . . .  21#    23     41
  735.  
  736.    15 Symbols
  737.   ──────────────────────────────────────────────────────────────────────────
  738.  
  739.   Figure 4-5.  Cross-reference listing HELLO.REF produced by the CREF
  740.   utility from the file HELLO.CRF, for the HELLO.EXE program example from
  741.   Chapter 3. The symbols declared in the program are listed on the left in
  742.   alphabetic order. To the right of each symbol is a list of all the lines
  743.   where that symbol is referenced. The number with a # sign after it denotes
  744.   the line where the symbol is declared. Numbers followed by a + sign
  745.   indicate that the symbol is modified at the specified line. The line
  746.   numbers given in the cross-reference listing correspond to the line
  747.   numbers generated by the assembler in the program-listing (.LST) file, not
  748.   to any physical line count in the original source file.
  749.  
  750.   The parameters may also be entered in the command line in the following
  751.   form:
  752.  
  753.     CREF CRF_file, listing_file
  754.  
  755.   For example, the command-line equivalent to the preceding interactive
  756.   session is:
  757.  
  758.   C>CREF HELLO,HELLO  <Enter>
  759.  
  760.   If CREF cannot find the specified .CRF file, it displays an error message.
  761.   Otherwise, it leaves the cross-reference listing in the specified file on
  762.   the disk. You can send the file to the printer with the COPY command, in
  763.   the following form:
  764.  
  765.     COPY listing_file PRN:
  766.  
  767.   You can also send the cross-reference listing directly to a character
  768.   device as it is generated by responding to the Listing prompt with the
  769.   name of the device.
  770.  
  771.  
  772. The Microsoft Library Manager
  773.  
  774.   Although the object modules that are produced by MASM or by high-level-
  775.   language compilers can be linked directly into executable load modules,
  776.   they can also be collected into special files called object-module
  777.   libraries. The modules in a library are indexed by name and by the public
  778.   symbols they contain, so that they can be extracted by the linker to
  779.   satisfy external references in a program.
  780.  
  781.   The Microsoft Library Manager (LIB) is distributed as the file LIB.EXE.
  782.   LIB creates and maintains program libraries, adding, updating, and
  783.   deleting object files as necessary. LIB can also check a library file for
  784.   internal consistency or print a table of its contents (Figure 4-6).
  785.  
  786.   LIB follows the command conventions of most other Microsoft programming
  787.   tools. You must supply it with the name of a library file to work on, one
  788.   or more operations to perform, the name of a listing file or device, and
  789.   (optionally) the name of the output library. If you do not specify a name
  790.   for the output library, LIB gives it the same name as the input library
  791.   and changes the extension of the input library to .BAK.
  792.  
  793.   The LIB operations are simply the names of object files, with a prefix
  794.   character that specifies the action to be taken:
  795.  
  796.   Prefix     Meaning
  797.   ──────────────────────────────────────────────────────────────────────────
  798.   -          Delete an object module from the library.
  799.   *          Extract a module and place it in a separate .OBJ file.
  800.   +          Add an object module or the entire contents of another library
  801.              to the library.
  802.   ──────────────────────────────────────────────────────────────────────────
  803.  
  804.   You can combine command prefixes. For example, -+ replaces a module, and
  805.   *- extracts a module into a new file and then deletes it from the library.
  806.  
  807.   ──────────────────────────────────────────────────────────────────────────
  808.   _abort............abort             _abs..............abs
  809.   _access...........access            _asctime..........asctime
  810.   _atof.............atof              _atoi.............atoi
  811.   _atol.............atol              _bdos.............bdos
  812.   _brk..............brk               _brkctl...........brkctl
  813.   _bsearch..........bsearch           _calloc...........calloc
  814.   _cgets............cgets             _chdir............dir
  815.   _chmod............chmod             _chsize...........chsize
  816.        .
  817.        .
  818.        .
  819.   _exit             Offset: 00000010H  Code and data size: 44H
  820.     __exit
  821.  
  822.   _filbuf           Offset: 00000160H  Code and data size: BBH
  823.     __filbuf
  824.  
  825.   _file             Offset: 00000300H  Code and data size: CAH
  826.     __iob             __iob2            __lastiob
  827.        .
  828.        .
  829.        .
  830.   ──────────────────────────────────────────────────────────────────────────
  831.  
  832.   Figure 4-6.  Extract from the table-of-contents listing produced by the
  833.   Microsoft Library Manager (LIB) for the Microsoft C library SLIBC.LIB. The
  834.   first part of the listing is an alphabetic list of all public names
  835.   declared in all of the modules in the library. Each name is associated
  836.   with the object module to which it belongs. The second part of the listing
  837.   is an alphabetic list of the object-module names in the library, each
  838.   followed by its offset within the library file and the actual size of the
  839.   module in bytes. The entry for each module is followed by a summary of the
  840.   public names that are declared within it.
  841.  
  842.   When you invoke LIB with its name alone, it requests the other information
  843.   it needs interactively, as shown in the following example:
  844.  
  845.   C>LIB  <Enter>
  846.  
  847.   Microsoft (R) Library Manager  Version 3.08
  848.   Copyright (C) Microsoft Corp 1983-1987. All rights reserved.
  849.  
  850.   Library name:  SLIBC  <Enter>
  851.   Operations: +VIDEO  <Enter>
  852.   List file:  SLIBC.LST  <Enter>
  853.   Output library:  SLIBC2  <Enter>
  854.  
  855.   C>
  856.  
  857.   In this example, LIB added the object module VIDEO.OBJ to the library
  858.   SLIBC.LIB, wrote a library table of contents into the file SLIBC.LST, and
  859.   named the resulting new library SLIBC2.LIB.
  860.  
  861.   The Library Manager can also be run with a command line of the following
  862.   form:
  863.  
  864.     LIB library [commands],[list],[newlibrary]
  865.  
  866.   For example, the following command line is equivalent to the preceding
  867.   interactive session:
  868.  
  869.   C>LIB SLIBC +VIDEO,SLIBC.LST,SLIBC2;  <Enter>
  870.  
  871.   As with the other Microsoft utilities, a semicolon at the end of the
  872.   command line causes LIB to use the default responses for any parameters
  873.   that are omitted.
  874.  
  875.   Like LINK, LIB can also accept its commands from a response file. The
  876.   contents of the file are lines of text that correspond exactly to the
  877.   responses you would give LIB interactively. You specify the name of the
  878.   response file in the command line with a leading  character, as follows:
  879.  
  880.     LIB filename
  881.  
  882.   LIB has only three switches: /I (/IGNORECASE), /N (/NOIGNORECASE), and
  883.   /PAGESIZE:number. The /IGNORECASE switch is the default. The /NOIGNORECASE
  884.   switch causes LIB to regard as distinct any symbols that differ only in
  885.   the case of their component letters. You should place the /PAGESIZE
  886.   switch, which defines the size of a unit of allocation space for a given
  887.   library, immediately after the library filename. The library page size is
  888.   in bytes and must be a power of 2 between 16 and 32,768 (16, 32, 64, and
  889.   so forth); the default is 16 bytes. Because the index to a library is
  890.   always a fixed number of pages, setting a larger page size allows you to
  891.   store more object modules in that library; on the other hand, it will
  892.   result in more wasted space within the file.
  893.  
  894.  
  895. The MAKE Utility
  896.  
  897.   The MAKE utility (MAKE.EXE) compares dates of files and carries out
  898.   commands based on the result of that comparison. Because of this single,
  899.   rather basic capability, MAKE can be used to maintain complex programs
  900.   built from many modules. The dates of source, object, and executable files
  901.   are simply compared in a logical sequence; the assembler, compiler,
  902.   linker, and other programming tools are invoked as appropriate.
  903.  
  904.   The MAKE utility processes a plain ASCII text file called, as you might
  905.   expect, a make file. You start the utility with a command-line entry in
  906.   the following form:
  907.  
  908.     MAKE makefile [options]
  909.  
  910.   By convention, a make file has the same name as the executable file that
  911.   is being maintained, but without an extension. The available MAKE switches
  912.   are listed in Figure 4-7.
  913.  
  914.   A simple make file contains one or more dependency statements separated by
  915.   blank lines. Each dependency statement can be followed by a list of MS-DOS
  916.   commands, in the following form:
  917.  
  918.     targetfile : sourcefile ...
  919.  
  920.       command
  921.  
  922.       command
  923.  
  924.       .
  925.  
  926.       .
  927.  
  928.       .
  929.  
  930.   If the date and time of any source file are later than those of the target
  931.   file, the accompanying list of commands is carried out. You may use
  932.   comment lines, which begin with a # character, freely in a make file. MAKE
  933.   can also process inference rules and macro definitions. For further
  934.   details on these advanced capabilities, see the Microsoft or IBM
  935.   documentation.
  936.  
  937.   Switch     Meaning
  938.   ──────────────────────────────────────────────────────────────────────────
  939.   /D         Display last modification date of each file as it is processed.
  940.   /I         Ignore exit (return) codes returned by commands and programs
  941.              executed as a result of dependency statements.
  942.   /N         Display commands that would be executed as a result of
  943.              dependency statements but do not execute those commands.
  944.   /S         Do not display commands as they are executed.
  945.   /X         Direct error messages from MAKE, or any program that MAKE runs,
  946.   <filename> to the specified file. If filename is a hyphen (-), direct
  947.              error messages to the standard output.
  948.   ──────────────────────────────────────────────────────────────────────────
  949.  
  950.   Figure 4-7.  Switches for the MAKE utility.
  951.  
  952.  
  953. A Complete Example
  954.  
  955.   Let's put together everything we've learned about using the MS-DOS
  956.   programming tools so far. Figure 4-8 shows a sketch of the overall
  957.   process of building an executable program.
  958.  
  959.   Assume that we have the source code for the HELLO.EXE program from Chapter
  960.   3 in the file HELLO.ASM. To assemble the source program into the
  961.   relocatable object module HELLO.OBJ with symbolic debugging information
  962.   included, also producing a program listing in the file HELLO.LST and a
  963.   cross-reference data file HELLO.CRF, we would enter
  964.  
  965.   C>MASM /C /L /Zi /T HELLO;  <Enter>
  966.  
  967.   To convert the cross-reference raw-data file HELLO.CRF into a
  968.   cross-reference listing in the file HELLO.REF, we would enter
  969.  
  970.   C>CREF HELLO,HELLO  <Enter>
  971.  
  972.   ┌───────────────┐             ┌───────────────┐
  973.   │     MASM      │             │  C or other   │
  974.   │  source-code  │             │  HLL source-  │
  975.   │     file      │             │   code file   │
  976.   └───┬───────────┘             └───┬───────────┘
  977.       │       ┌─────────────────────┘  Compiler
  978.   ┌─────────────┐
  979.   │  Relocatable  │
  980.   │ object-module ├────┐
  981.   │  file (.OBJ)  │    │
  982.   └───┬───────────┘    │
  983.       │ LIB            │
  984.   ┌──────────────┐    │        ┌───────────────┐
  985.   │ Object-module │      LINK  │  Executable   │
  986.   │   libraries   ├─────────────   program     │
  987.   │    (.LIB)     │            │    (.EXE)     │
  988.   └───────────────┘      │      └───┬───────────┘
  989.                          │          │ EXE2BIN
  990.   ┌───────────────┐      │      ┌──────────────┐
  991.   │     HLL       │      │      │   Executable  │
  992.   │   runtime     ├──────┘      │    program    │
  993.   │  libraries    │             │     (.COM)    │
  994.   └───────────────┘             └───────────────┘
  995.  
  996.   Figure 4-8.  Creation of an MS-DOS application program, from source code
  997.   to executable file.
  998.  
  999.   To convert the relocatable object file HELLO.OBJ into the executable file
  1000.   HELLO.EXE, creating a load map in the file HELLO.MAP and appending
  1001.   symbolic debugging information to the executable file, we would enter
  1002.  
  1003.   C>LINK /MAP /CODEVIEW HELLO;  <Enter>
  1004.  
  1005.   We could also automate the entire process just described by creating a
  1006.   make file named HELLO (with no extension) and including the following
  1007.   instructions:
  1008.  
  1009.   hello.obj : hello.asm
  1010.    masm /C /L /Zi /T hello;
  1011.    cref hello,hello
  1012.  
  1013.   hello.exe : hello.obj
  1014.    link /MAP /CODEVIEW hello;
  1015.  
  1016.   Then, when we have made some change to HELLO.ASM and want to rebuild the
  1017.   executable HELLO.EXE file, we need only enter
  1018.  
  1019.   C>MAKE HELLO  <Enter>
  1020.  
  1021.  
  1022. Programming Resources and References
  1023.  
  1024.   The literature on IBM PC─compatible personal computers, the Intel 80x86
  1025.   microprocessor family, and assembly-language and C programming is vast.
  1026.   The list below contains a selection of those books that I have found to be
  1027.   useful and reliable. The list should not be construed as an endorsement by
  1028.   Microsoft Corporation.
  1029.  
  1030. MASM Tutorials
  1031.  
  1032.   Assembly Language Primer for the IBM PC and XT, by Robert Lafore. New
  1033.   American Library, New York, NY, 1984. ISBN 0-452-25711-5.
  1034.  
  1035.   8086/8088/80286 Assembly Language, by Leo Scanlon. Brady Books, Simon and
  1036.   Schuster, New York, NY, 1988. ISBN 0-13-246919-7.
  1037.  
  1038. C Tutorials
  1039.  
  1040.   Microsoft C Programming for the IBM, by Robert Lafore. Howard K. Sams &
  1041.   Co., Indianapolis, IN, 1987. ISBN 0-672-22515-8.
  1042.  
  1043.   Proficient C, by Augie Hansen. Microsoft Press, Redmond, WA, 1987. ISBN
  1044.   1-55615-007-5.
  1045.  
  1046. Intel 80x86 Microprocessor References
  1047.  
  1048.   iAPX 88 Book. Intel Corporation, Literature Department SV3-3, 3065 Bowers
  1049.   Ave., Santa Clara, CA 95051. Order no. 210200.
  1050.  
  1051.   iAPX 286 Programmer's Reference Manual. Intel Corporation, Literature
  1052.   Department SV3-3, 3065 Bowers Ave., Santa Clara, CA 95051. Order no.
  1053.   210498.
  1054.  
  1055.   iAPX 386 Programmer's Reference Manual. Intel Corporation, Literature
  1056.   Department SV3-3, 3065 Bowers Ave., Santa Clara, CA 95051. Order no.
  1057.   230985.
  1058.  
  1059. PC, PC/AT, and PS/2 Architecture
  1060.  
  1061.   The IBM Personal Computer from the Inside Out (Revised Edition), by Murray
  1062.   Sargent and Richard L. Shoemaker. Addison-Wesley Publishing Company,
  1063.   Reading, MA, 1986. ISBN 0-201-06918-0.
  1064.  
  1065.   Programmer's Guide to PC & PS/2 Video Systems, by Richard Wilton.
  1066.   Microsoft Press, Redmond, WA, 1987. ISBN 1-55615-103-9.
  1067.  
  1068.   Personal Computer Technical Reference. IBM Corporation, IBM Technical
  1069.   Directory, P. O. Box 2009, Racine, WI 53404. Part no. 6322507.
  1070.  
  1071.   Personal Computer AT Technical Reference. IBM Corporation, IBM Technical
  1072.   Directory, P. O. Box 2009, Racine, WI 53404. Part no. 6280070.
  1073.  
  1074.   Options and Adapters Technical Reference. IBM Corporation, IBM Technical
  1075.   Directory, P. O. Box 2009, Racine, WI 53404. Part no. 6322509.
  1076.  
  1077.   Personal System/2 Model 30 Technical Reference. IBM Corporation, IBM
  1078.   Technical Directory, P. O. Box 2009, Racine, WI 53404. Part no. 68X2201.
  1079.  
  1080.   Personal System/2 Model 50/60 Technical Reference. IBM Corporation, IBM
  1081.   Technical Directory, P. O. Box 2009, Racine, WI 53404. Part no. 68X2224.
  1082.  
  1083.   Personal System/2 Model 80 Technical Reference. IBM Corporation, IBM
  1084.   Technical Directory, P. O. Box 2009, Racine, WI 53404. Part no. 68X2256.
  1085.  
  1086.  
  1087.  
  1088.