Return to masm500.txt CVS log

Up to [OS/2 SDKs] / os2sdk / os2doc

Annotation of os2sdk/os2doc/masm500.txt, revision 1.1

1.1     ! root        1:                    Microsoft Macro Assembler Package
        !             2:                             Version 5.00
        !             3: 
        !             4:        If you purchased the Macro Assembler package as an update to a
        !             5:        previous version, you did not receive a registration card.
        !             6:        This is not a mistake. The update is only available to
        !             7:        registered owners, who do not need to reregister.
        !             8: 
        !             9:        Text files on the Macro Assembler disks are tabbed to save
        !            10:        disk space. If your printer does not automatically handle
        !            11:        tabs during printing, you must use a print program that
        !            12:        expands tabs. For example, use the DOS PRINT program to print
        !            13:        this and other document or source files on the disk.
        !            14: 
        !            15:   ==( MASM.EXE )==
        !            16: 
        !            17:   New Feature
        !            18: 
        !            19:        The /LA option has been added to specify a complete listing
        !            20:        of all symbols, macros, and false conditionals. It is
        !            21:        equivalent to using the .LIST, .LFCOND, .LALL, and .CREF
        !            22:        directives throughout the source file. The option overrides
        !            23:        any conflicting directives in the source file.
        !            24: 
        !            25:   Clarification
        !            26: 
        !            27:        The PTR operator can be used to specify the size of a
        !            28:        register indirect operand for a CALL or JMP instruction.
        !            29:        However, the size cannot be specified with NEAR or FAR. Use
        !            30:        WORD or DWORD instead. (In 80386 32-bit segments, use DWORD
        !            31:        or FWORD.) Examples are shown below:
        !            32: 
        !            33:          ; 8086, 80826, or 80386 16-bit mode
        !            34: 
        !            35:          jmp  WORD PTR [bx]        ; Legal near jump
        !            36:          call NEAR PTR [bx]        ; Illegal near call
        !            37:          call DWORD PTR [bx]       ; Legal far call
        !            38:          jmp  FAR PTR [bx]         ; Illegal far jump
        !            39: 
        !            40:          ; 80386 32-bit mode only
        !            41: 
        !            42:          jmp  DWORD PTR [bx]       ; Legal near jump
        !            43:          call NEAR PTR [bx]        ; Illegal near call
        !            44:          call FWORD PTR [bx]       ; Legal far call
        !            45:          jmp  FAR PTR [bx]         ; Illegal far jump
        !            46: 
        !            47:        This limitation only applies to register indirect operands.
        !            48:        NEAR or FAR can be applied to operands associated with
        !            49:        labels. Examples are shown below:
        !            50: 
        !            51:          jmp  NEAR PTR pointer[bx] ; Legal
        !            52:          call FAR PTR location     ; Legal
        !            53: 
        !            54:   Correction
        !            55: 
        !            56:        When evaluating expressions, MASM does 16-bit arithmetic
        !            57:        except when the 80386 processor is enabled. If the .386 or
        !            58:        .386P directive has been given, MASM does 32-bit arithmetic.
        !            59:        This behavior is consistent with earlier versions of MASM,
        !            60:        which always did 16-bit arithmetic. The notes in Sections
        !            61:        9.2.1, 9.2.1.5, and 9.2.2 of the Programmer's Guide are
        !            62:        incorrect. MASM extends constant operands to 17 bits (33 bits
        !            63:        with .386) before calculations, but then truncates the result
        !            64:        to 16 bits (32 bits with .386). The EQ and NE operators work
        !            65:        on 16-bit operands (32-bit with .386), but the LT, LE, GT, and
        !            66:        GE operators work on 17-bit (33-bit with .386) operands.
        !            67: 
        !            68:   Clarification
        !            69: 
        !            70:        The @FARDATA predefined equate mentioned in Section 5.1.5 does
        !            71:        not exist. References to this equate and examples of it in
        !            72:        several parts of the Programmer's Guide are incorrect. In
        !            73:        particular, the description of declaring external symbols in
        !            74:        Section 8.2 is incomplete and the example is incorrect. You
        !            75:        cannot access the segment of an external far data variable
        !            76:        with the @FARDATA equate or with the segment name FAR_DATA.
        !            77:        Instead you must use the SEG operator as shown below:
        !            78: 
        !            79:                 .FARDATA
        !            80:                 EXTRN     fvar:WORD       ; FAR variable in far data
        !            81:                 .CODE
        !            82:          start: ASSUME    es:SEG fvar     ; Tell the assembler
        !            83:                 mov       ax,SEG fvar     ; Tell the processor
        !            84:                 mov       es,ax
        !            85: 
        !            86:        This is the same limitation described for communal variables
        !            87:        in Section 8.4. The reason is that under the DOS segment
        !            88:        conventions, multiple far data segments share the same name
        !            89:        (FAR_DATA) and have private combine type. Segments with the
        !            90:        same name can only be distinguished indirectly using the SEG
        !            91:        operator.
        !            92: 
        !            93:   Clarification
        !            94: 
        !            95:        New CS assume statements are automatically given each time you
        !            96:        use the .CODE directive, as shown below:
        !            97: 
        !            98:          .CODE TASK1             ; Does ASSUME CS:TASK1_TEXT
        !            99:          .
        !           100:          .
        !           101:          .
        !           102:          .CODE TASK2             ; Does ASSUME CS:TASK2_TEXT
        !           103:          .
        !           104:          .
        !           105:          .
        !           106: 
        !           107:   Clarification
        !           108: 
        !           109:        The .286P and .386P processor directives enable instructions
        !           110:        that are normally used in systems programming. However,
        !           111:        some of these instructions do not necessarily require that
        !           112:        the processor be in privileged or protected mode.
        !           113: 
        !           114:   Correction
        !           115: 
        !           116:        Public absolute symbols must be declared during pass 1. This
        !           117:        means that aliases for absolute symbols or other forward
        !           118:        references to them will cause errors. For example, the
        !           119:        following code generates an error:
        !           120: 
        !           121:                 PUBLIC lines
        !           122:          lines  EQU    rows
        !           123:          rows   EQU    25
        !           124: 
        !           125:        This behavior is different than in previous versions of MASM
        !           126:        and contrary to the note in Section 8.1.
        !           127: 
        !           128:   Behavior Change
        !           129: 
        !           130:        Some errors and questionable practices that were ignored by
        !           131:        earlier versions are now flagged as errors. As a result,
        !           132:        existing source code may produce errors or warnings.
        !           133:        The following are examples:
        !           134: 
        !           135:          - Labels defined only during pass 1 will cause errors if
        !           136:            used in expressions.
        !           137:          - A CS assume that changes from pass 1 to pass 2 causes
        !           138:            an error.
        !           139:          - Constants are now checked for type overflow.
        !           140:          - Reserved words used as labels produce warnings.
        !           141:          - The OFFSET operator used with a constant produces a
        !           142:            warning.
        !           143: 
        !           144:    Correction
        !           145: 
        !           146:        The assembler documentation indicates in several places that
        !           147:        CX will be 0 following a SCAS or CMPS instruction if no match
        !           148:        is found. This is misleading since CX may also be zero after
        !           149:        a search or compare in which the last string element matches.
        !           150: 
        !           151:        Testing the zero flag is more reliable. After a REPNE
        !           152:        comparison or scan, the zero flag will be cleared if no match
        !           153:        was found. After a REPE comparison or scan, the zero flag
        !           154:        will be set if no nonmatch was found. This correction affects
        !           155:        the following references:
        !           156: 
        !           157:           Assembler Reference
        !           158: 
        !           159:              CMPS instruction, last paragraph
        !           160: 
        !           161:              SCAS instruction, last paragraph
        !           162: 
        !           163:           Programmer's Guide
        !           164: 
        !           165:              Section 18.3, last paragraph of description; in example,
        !           166:              change "JCXZ notfound" to "JNZ notfound"
        !           167: 
        !           168:              Section 18.4, last paragraph of description; in example,
        !           169:              change "JCXZ allmatch" to "JZ allmatch"
        !           170: 
        !           171:   Other        Corrections
        !           172: 
        !           173:        Section     Description
        !           174: 
        !           175:        5.2.2       The segment align, combine, use, and class types
        !           176:                    can be given in ANY order.
        !           177: 
        !           178:        13.3        Pushing a value DECREASES the value of SP. Popping
        !           179:                    INCREASES the value.
        !           180: 
        !           181:        16.3        When two 16-bit numbers are multiplied with MUL or
        !           182:                    IMUL, the LEAST-signicant bits of the product will
        !           183:                    be in AX and the MOST-significant bits in DX.
        !           184: 
        !           185:        16.4        To divide a 32-bit number by a 16-bit number with
        !           186:                    DIV or IDIV, put the LEAST-signicant bits in AX
        !           187:                    and the MOST-significant bits in DX.
        !           188: 
        !           189:        16.5        In several cases, the registers and values
        !           190:                    described in text do not match those used in the
        !           191:                    examples. The examples are correct.
        !           192: 
        !           193:   ==( MASM.EXE,        LINK.EXE, and LIB.EXE )==
        !           194: 
        !           195:   Clarification
        !           196: 
        !           197:        The description of STACK combine type in Section 5.2.2.3
        !           198:        does not explain how multiple initialized stack segments are
        !           199:        combined. The total size of the stack is the total size of
        !           200:        all stack definitions. LINK puts initialized data for each
        !           201:        defined stack segment at the end of the stack. Data initialized
        !           202:        in the last segment linked overrides data initialized in
        !           203:        previoussegments. This behavior is usually not relevant, since
        !           204:        most programs only define one stack of uninitialized data.
        !           205:        Stack data cannot be initialized with simplified segment
        !           206:        directives.
        !           207: 
        !           208:   New Feature
        !           209: 
        !           210:        The /NOE[XTDICTIONARY] option has been added to the linker. It
        !           211:        Tells the linker not to use the extended dictionary in
        !           212:        searching libraries. Use this option if you redefine a
        !           213:        standard-library routine (such as _setargv or _nullcheck) in a
        !           214:        program module, or if you get linker error L2044 during
        !           215:        linking. This option may slow linking on some programs.
        !           216: 
        !           217:        The "extended dictionary" is a block of data telling the linker
        !           218:        about interlibrary dependencies; that is, for each module in
        !           219:        the library, the extended dictionary tells the linker which
        !           220:        other modules in the same library are also required. Although
        !           221:        the linker can process libraries faster with this information,
        !           222:        it has trouble in processing if you redefine symbols (such as
        !           223:        the names of standard-library routines) that otherwise would
        !           224:        have been defined in one of the modules described in the
        !           225:        extended dictionary.
        !           226: 
        !           227:        One new LINK error message and two LIB messages have been
        !           228:        added to support this option. The linker message is shown
        !           229:        below:
        !           230: 
        !           231:          L2044   <name> : symbol multiply defined, use /NOE
        !           232: 
        !           233:        The message indicates that the linker found what it interprets
        !           234:        as a public-symbol redefinition, probably because you have
        !           235:        redefined a symbol that is defined in a library. Relink with
        !           236:        the /NOE option. If error L2025 results for the same symbol,
        !           237:        then you have a genuine symbol-redefinition error.
        !           238: 
        !           239:        The following LIB messages are new:
        !           240: 
        !           241:          U4157   insufficient memory, extended dictionary not created
        !           242:          U4158   internal error, extended dictionary not created
        !           243: 
        !           244:        This indicates that LIB could not create an extended
        !           245:        dictionary. The library is still valid, but the linker will
        !           246:        not be able to take advantage of the extended dictionary to
        !           247:        speed linking.
        !           248: 
        !           249:   New Feature
        !           250: 
        !           251:        LIB has a new option, /N[OIGNORECASE]. It tells LIB to ignore
        !           252:        case when comparing symbols in the extended and regular
        !           253:        dictionaries. The default is to ignore case.
        !           254: 
        !           255:   New Message
        !           256: 
        !           257:        The following new LINK message warns about a practice that is
        !           258:        legal in real mode, but illegal in protected mode:
        !           259: 
        !           260:          warning L4003: intersegment self-relative fixup at <position>
        !           261: 
        !           262:        In assembly-language, the warning only occurs if the DOSSEG
        !           263:        directive or /DOSSEG linker option is used. It indicates a
        !           264:        16-bit jump to an address in another segment. For example,
        !           265:        the following code produces the error:
        !           266: 
        !           267:          _TEXT   SEGMENT
        !           268:                  EXTRN    doit:NEAR
        !           269:                  jmp      _TEXT2:doit
        !           270:                  .
        !           271:                  .
        !           272:                  .
        !           273:          _TEXT   ENDS
        !           274: 
        !           275:          _TEXT2  SEGMENT
        !           276:                  PUBLIC   doit
        !           277:          doit    PROC     NEAR
        !           278:                  .
        !           279:                  .
        !           280:                  .
        !           281:          doit    ENDP
        !           282:          _TEXT2  ENDS
        !           283: 
        !           284:        The warning usually indicates a fatal error in high-level-
        !           285:        language programs. It can occur when the /NT option is used
        !           286:        to compile a small-model C program.
        !           287: 
        !           288:   New Messages
        !           289: 
        !           290:        The following LINK messages are related to quick libraries.
        !           291:        See you QuickBASIC or QuickC documentation for details:
        !           292: 
        !           293:          L2043   Quick Library support module missing
        !           294:          L1003   /QUICKLIB, /EXEPACK incompatible
        !           295:          L1115   /QUICKLIB, overlays incompatible
        !           296: 
        !           297:   New Message
        !           298: 
        !           299:        The following new LIB message warns that a module specified to
        !           300:        be replaced does not exist in the library:
        !           301: 
        !           302:          U4155   <modulename> : module not in library
        !           303: 
        !           304:        LIB adds the module anyway.
        !           305: 
        !           306:   ==( CodeView Debugger        )==
        !           307: 
        !           308:   New Feature
        !           309: 
        !           310:        The /R option has been added to enable the CodeView debugger
        !           311:        to use the debug registers (DR0, DR1, DR2, and DR3) of the
        !           312:        80386 processor. The option is ignored if you do not have an
        !           313:        80386 processor.
        !           314: 
        !           315:        The display does not change to indicate that the debug
        !           316:        registers are in use, but debugger operations with
        !           317:        tracepoint or trace memory statements (but not with
        !           318:        watchpoint statements) will be much faster. Any of the
        !           319:        following conditions will prevent the debugger from using
        !           320:        debug registers:
        !           321: 
        !           322:          1) /E is used.
        !           323:          2) More than four tracepoints are set.
        !           324:          3) A tracepoint watches more than four bytes of memory.
        !           325:          4) A watchpoint is set.
        !           326: 
        !           327:   Clarification
        !           328: 
        !           329:        The Pascal expression evaluator described in the CodeView
        !           330:        and Utilities manual is not implemented in this version of
        !           331:        the CodeView debugger. It will be implemented in the
        !           332:        debugger supplied with the next version of Pascal, which
        !           333:        will also produce executable files with CodeView symbolic
        !           334:        information. Current versions of Pascal do not work with the
        !           335:        CodeView debugger.
        !           336: 
        !           337:   Corrections
        !           338: 
        !           339:        Section 4.2 of the CodeView and Utilities manual should mention
        !           340:        that FORTRAN relational operators do not work with string
        !           341:        variables or constants.
        !           342: 
        !           343:        Use the /Zi option, not /D as indicated in Sections 1.2.2 and
        !           344:        1.2.6, when using BC to compile BASIC programs for the
        !           345:        CodeView debugger.
        !           346: 
        !           347:   Warning
        !           348: 
        !           349:        Some versions of the GENOA EGA short card are incompatible
        !           350:        with CodeView when used with a mouse. You can work around this
        !           351:        problem by turning off the mouse with /M.
        !           352: 
        !           353:   ==( CREF.EXE )==
        !           354: 
        !           355:   New Feature
        !           356: 
        !           357:        Cross-reference listing files created with CREF now have an
        !           358:        additional symbol. A line number followed by + indicates
        !           359:        that a symbol is modified at the given line. For example:
        !           360: 
        !           361:          TST . . . . . . . . . . . . . .  134#   237    544+
        !           362: 
        !           363:        The symbol TST is defined at line 134, used at line 237, and
        !           364:        modified at line 544.
        !           365: 
        !           366:   ==( MAKE.EXE )==
        !           367: 
        !           368:   Warning
        !           369: 
        !           370:        MAKE considers a backslash immediately followed by a carriage
        !           371:        return-line feed to be a continuation character. When it finds
        !           372:        this combination in a description file, MAKE concatenates the
        !           373:        line immediately following to the current line.
        !           374: 
        !           375:        If you define a macro that ends in a backslash, make sure that
        !           376:        you put a space after the terminating backslash. For example:
        !           377: 
        !           378:          BINPATH=C:\SRC\BIN\<space><new-line>
        !           379:          LIBPATH=C:\SRC\LIB\<space><new-line>
        !           380: 
        !           381:   New Feature
        !           382: 
        !           383:        The new /X option has the following syntax:
        !           384: 
        !           385:          /X <filename>
        !           386: 
        !           387:        This option redirects errors output by MAKE, or by any
        !           388:        programs that MAKE runs, to the given file. If the <filename>
        !           389:        argument is a dash (-), MAKE redirects error output to STDOUT.
        !           390:        You may send both error output and standard output to the same
        !           391:        file by combining the "/X -" form of this option with DOS
        !           392:        redirection, as in the following example:
        !           393: 
        !           394:          MAKE /X - project.mak >make.log
        !           395: 
        !           396:        DO NOT specify the same file name for /X as the file name
        !           397:        following the redirection symbol (>).
        !           398: 
        !           399:   ==( ERROUT.EXE )==
        !           400: 
        !           401:   Correction
        !           402: 
        !           403:        The ERROUT utility does not accept batch files. To redirect
        !           404:        standard-error output from a batch file, you must enter a
        !           405:        command of the following form:
        !           406: 
        !           407:           ERROUT COMMAND /c <batchfile>
        !           408: 
        !           409:        If no /f option is given, ERROUT redirects standard-error
        !           410:        output to the standard-output device.
        !           411: 
        !           412:   ==( Exit Codes )==
        !           413: 
        !           414:        Exit codes returned by LINK, LIB, and MAKE have changed:
        !           415: 
        !           416:               Code     Meaning
        !           417: 
        !           418:                0       No error.
        !           419: 
        !           420:                2       Program error. Something was wrong with the
        !           421:                        commands or files input to the utility.
        !           422: 
        !           423:                4       System error, such as a file error or user
        !           424:                        interrupt.
        !           425: 
        !           426: 
        !           427:   ==( Mixed-Languages Programming Guide        )==
        !           428: 
        !           429:   Correction
        !           430: 
        !           431:        C recognizes up to 31 characters of symbol names, not eight
        !           432:        as stated in Section 1.2.
        !           433: 
        !           434:   Clarification
        !           435: 
        !           436:        The example programs for BASIC in Chapter 6 will not work
        !           437:        with QuickBASIC Versions 2.0 or 3.0. They will work if you
        !           438:        rewrite the function as a subprogram, and omit the DECLARE
        !           439:        statement. Functions and DECLARE statements are supported
        !           440:        in QuickBASIC 4.0 and in future versions of Microsoft BASIC
        !           441:        compilers.
        !           442: 
        !           443:   Clarification
        !           444: 
        !           445:        Section 6.6 of the Mixed Languages Programming Guide gives
        !           446:        instructions for setting up a call to a high-level language
        !           447:        from assembly language. Before you execute a call to a BASIC,
        !           448:        Pascal, or FORTRAN routine, declare an additional parameter if
        !           449:        the return value is noninteger. This additional parameter must
        !           450:        contain the offset address of the return value, for which you
        !           451:        must allocate room within the stack segment (normally DGROUP,
        !           452:        the same as the default data segment).
        !           453: 
        !           454:   ==( Macro Files )==
        !           455: 
        !           456:   New Feature
        !           457: 
        !           458:        Macro files have been added to the Macro Assembler package.
        !           459:        The following files are provided:
        !           460: 
        !           461:              MIXED.INC       For defining assembler procedures
        !           462:                              that can be called from high-level
        !           463:                              languages
        !           464: 
        !           465:              MIXED.DOC       Documentation for the macros in
        !           466:                              MIXED.INC.
        !           467: 
        !           468:              DOS.INC         For calling common DOS interrupts
        !           469: 
        !           470:              BIOS.INC        For calling common BIOS interrupts
        !           471:                              used on IBM and IBM-compatible computers
        !           472: 
        !           473:              MACRO.DOC       Description, syntax, and reference
        !           474:                              for using the macros in DOS.INC and
        !           475:                              BIOS.INC.

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.