Microsoft Programmer's Library 1.3/Microsoft_Programmers_Library.7z/MPL/masm/masmknwl.txt

Text File | 2013-11-08 | 1.2 MB | 35,316 lines

 Microsoft Macro Assembler [MASM]
 =============================================================================


 1. @DataSize Misspelled

 Product Version(s): 5.00 5.10
 Operating System:   MS-DOS
 Flags: ENDUSER | docerr
 Last Modified:  3-MAR-1989    ArticleIdent: Q26583

 Problem:

 Page 91 of the "MS-DOS Macro Assembler User's Guide" shows @DataSize
 and @CodeSize typed as @datasize and @codesize. This information is
 inconsistent with Mixed.inc, which types them as @Datasize and
 @CodeSize. This process will result in an error when interfacing C and
 MASM using the NOIGNORECASE option.

 Response:

 Both the documentation and Mixed.Inc should show @DataSize and
 @CodeSize. The mistyping only will matter when assembling with the -Ml
 option to preserve case in names.


 2. Cannot Backup Disk

 Product Version(s): 5.10
 Operating System:   MS-DOS
 Flags: ENDUSER |
 Last Modified: 27-MAY-1988    ArticleIdent: Q28216

 Question:
    I am trying to make backup copies of my distribution disks. One
 of the disks will not copy; the disk is labeled "Microsoft CodeView and
 Utilities for MS-OS/2." Is this disk corrupt?

 Response:
    The disk should be fine. The information on this disk is required
 only by individuals who have MS-OS/2 and was intentionally saved on a
 high-density formatted disk.
    Since OS/2 must be run on a 286 or 386 machine, reading this disk
 will not be a problem since these machines have high-density floppy
 drives.
    If your machine is less than a 286, you probably have a low-density
 disk drive and you will not be able to read this disk; however, you
 will not be running under MS-OS/2 and will not need the information on
 the disk anyway.


 3. UNDEL Does Not Work with DOS Version 2.x

 Product Version(s): 5.10
 Operating System:   MS-DOS
 Flags: ENDUSER |
 Last Modified: 27-MAY-1988    ArticleIdent: Q28531

 Problem:
    The UNDEL that came with MASM Version 5.10 does not work properly.
 I am using DOS Version 2.x.

 Response:
    The utilities UNDEL, EXP, RM, and MEGREP are all bound. There is at
 least one known problem with running bound programs under DOS Version
 2.x, that is, you cannot rename the .EXE file to anything other than
 the name BIND outputs it as. For example, if the MAKE file reads as
 follows:

     bind undelp.exe doscalls.lib api.lib -o undelb.exe

 then you cannot rename UNDELB.EXE in order for it to work correctly on
 DOS Version 2.x.


 4. A Loop Instruction in .386 USE16 Segment Which Decrements ECX

 Product Version(s): 5.00 5.10
 Operating System:   MS-DOS
 Flags: ENDUSER |
 Last Modified:  9-FEB-1988    ArticleIdent: Q26707

 Problem:
    What is the mnemonic for a LOOP instruction in a .386 USE16 segment
 which decrements ECX?

 Response:
    You can use a cast override to change the operand size for the LOOP
 instruction. For example, "LOOP dword ptr alabel". In a 16-bit
 segment, ECX will be used instead of CX. If you use a WORD override in
 a 32-bit segment, CX will be used instead of ECX.


 5. PROC and USES Documentation

 Product Version(s): 5.10   | 5.10
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified: 12-JAN-1989    ArticleIdent: Q34293

    The new PROC directive in Macro Assembler Version 5.10 is
 documented on Page 37 of the "Microsoft Macro Assembler 5.1 Updates and
 Microsoft Editor" manual.
    Used in conjunction with the PROC directive are the NEAR, FAR, and
 USES keywords, also documented on Page 37.


 6. Operator "." and the Operator "*"

 Product Version(s): 5.10
 Operating System:   MS-DOS
 Flags: ENDUSER | buglist5.10
 Last Modified: 27-MAY-1988    ArticleIdent: Q27835

 Problem:
    I am using indirect addressing in the following Microsoft Macro
 Assembler instruction (the variable "esi" is a structure variable and
 "eax" is a 386 register):

 mov eax,[eax.esi*2]

    The opcodes generated by MASM indicate that MASM is not using
 indirect addressing.

 Response:
    The problem occurs because the "." operator has a higher precedence
 than the "*" operator. MASM turns "[eax.esi*2]" into "[(eax+esi)*2]"
 as a result of the precedence. MASM evaluates "(eax+esi)" as a
 constant instead of a register; eax being used with a structure
 variable, esi. Thus, the result of the constant expression "(eax+esi)"
 is multiplied by two and the address mode is lost.
    A workaround is to use the "+" operator which has lower precedence
 and produces the correct result. The "." operator should be reserved
 for structure field names as documented.
    Microsoft will correct the problem in a future release.


 7. High and Low Operators on External Items

 Product Version(s): 5.10
 Operating System:   MS-DOS
 Flags: ENDUSER |
 Last Modified: 13-MAY-1988    ArticleIdent: Q28625

 Problem:
    The High and Low operators are not working on my external
 variables. The following source code demonstrates the problem:

    .model small
    extrn e:dword
    .data
    dd  8 dup(low e,high e)
    end

 Response:
    The source code above exhibits the incorrect use of an EXTRN
 statement. The EXTRN statement must be either defined within a segment
 or referenced using a segment override. In the above example, the
 .DATA should be placed before the EXTRN statement in order to
 associate the variable "e" with a segment.


 8. Making Backup Copies

 Product Version(s): 5.00 5.10 | 5.10
 Operating System:   MS-DOS    | OS/2
 Flags: ENDUSER | docerr
 Last Modified: 12-JAN-1989    ArticleIdent: Q34361

    Page 7 in Section 1.1.1 "Making Backup Copies" of the "Microsoft
 Macro Assembler User's Guide" incorrectly suggests that you "put the
 copies in a safe place and use them only to restore the originals if
 they are damaged or destroyed."
    The advice should be to use the backups and to save the original
 disks for making future working copies.



 9. LES Instruction Assembles Incorrectly

 Product Version(s): 5.10
 Operating System:   MS-DOS
 Flags: ENDUSER | buglist5.10
 Last Modified: 23-MAY-1988    ArticleIdent: Q29735

    The following program demonstrates a problem with the LES
 instructions in MASM Version 5.10.
    The first LES instruction (Parm1) assembles correctly, but the
 second instruction (Parm2) generates an "immediate mode illegal"
 message.
    The only difference between the two instructions is the order of
 the arguments. In earlier versions of MASM, they produced identical
 code.

    The problem is with the type operator and the way it handles
 registers inside brackets ([]). The type operator makes things a
 constant on the left of the expression.
    Parm1 works because it handles registers inside brackets
 differently. "Type" turns bp into a constant; +10 then turns it back
 into an addressing mode.
    However, in Parm2, bp+10 has been turned into an addressing mode,
 which is then turned into a constant by "type x". This difference is
 demonstrated in the following code:

               .model   small

 x             struc
 y             dd        ?
 x             ends

 Parm1         equ       dword ptr [bp+type x+10]
 Parm2         equ       dword ptr [bp+10+type x]

               .code

 begin:        les       di,Parm1
               les       di,Parm2

               end       begin


 10. Including a File that Contains CTRL+Z Causes Error Message

 Product Version(s): 5.10
 Operating System:   MS-DOS
 Flags: ENDUSER | buglist5.10
 Last Modified: 12-JAN-1989    ArticleIdent: Q29791

 Problem:

 When I include a file that ends with a CTRL+Z, the error message
 "A2106: Line Too Long" appears.

 Response:

 Microsoft has confirmed this to be a problem in Version 5.10. We are
 researching this problem and will post new information as it becomes
 available.

 You can work around this problem by using the following DOS copy
 command:

 copy oldfilename /a newfilename

 This procedure copies the old filename to the new filename up to, but
 not including, the CTRL+Z.


 11. Error Message A2051 Incorrectly Generated

 Product Version(s): 5.10
 Operating System:   MS-DOS
 Flags: ENDUSER | buglist5.10
 Last Modified: 12-JAN-1989    ArticleIdent: Q30377

 The code given below generates the following error message:

 A2051: Operand not in current CS ASSUME segment

 The error is caused by the JE NEAR PTR statement. However, the first
 jump statement assembles without error. Both statements should or
 should not assemble as they generate full 16-bit fixup records.

 Microsoft has confirmed this to be a problem in Version 5.10. We are
 researching this problem and will post new information as it becomes
 available.

 You can work around this problem by not using the PTR operator in the
 JE instruction.

 The following code demonstrates the problem:

    .386
    PGROUP  group   CODE,NCODE
    CODE    segment use16 byet public 'prog'
            assume  cs:PGROUP
            jmp     SYM
            je      near ptr SYM
    CODE    ends
    NCODE   segment use16 byte public 'prog'
            assume  cs:PGROUP
    SYM:
    NCODE   ends
            end


 12. Structure Prototype Allowed to be Referenced in Program

 Product Version(s): 5.10
 Operating System:   MS-DOS
 Flags: ENDUSER | buglist5.10
 Last Modified: 23-MAY-1988    ArticleIdent: Q30378

    The following code defines a structure-type "mouse", but does not
 declare "mouse" as a location or instance of the structure:

         .MODEL SMALL
    mouse struc

    cat  dw  11
    dog  dw  12

    mouse ends
        .DATA
    duck    mouse   <>
        .CODE
    start: mov ax,@data
           mov ds,ax
           mov ax,mouse.dog

    END start

    The assembler allows access to the structure. The line "mov ax,
 mouse.dog" generates the following:

    mov ax,2

    Microsoft is researching this problem and will post new information
 as it becomes available.



 13. Structure References Using '.' Cause Confusion

 Product Version(s): 5.10
 Operating System:   MS-DOS
 Flags: ENDUSER | buglist5.10
 Last Modified: 23-MAY-1988    ArticleIdent: Q30379

    Variable names in the assembler can begin with following the
 character:

    '.'

    Structure references use the character '.' as an add operator. This
 means the label '.cat' is different than the element 'cat' in a
 structure.
    The assembler can become confused using distinguishing the two
 uses in a program, and can generate the following error message:

    Error A2028: Operator expected' occurs on 'mov ax,duck.cat'

    Microsoft is researching this problem and will post new information
 as it becomes available.

    The following is an example program:

        .MODEL SMALL
    mouse  struc
    cat     dw   1
    dog     dw   2
    mouse  ends
        .DATA
    duck    mouse  <>
        .CODE
    start:  mov  ax,@data
            mov  ds,ax
    .cat    dw   4
            mov  ax,duck.cat
     END start


 14. Text Macros Cannot Serve as Data-Definition Replacements

 Product Version(s): 5.10
 Operating System:   MS-DOS
 Flags: ENDUSER | buglist5.10
 Last Modified: 23-MAY-1988    ArticleIdent: Q30380

    A text macro cannot be used to select data-definition directives.
 The following program demonstrates this problem:

     .MODEL SMALL
     .CODE
 start: mov ax,@data
        mov ds,ax

 gets   equ   <DW>
 boat   gets   3
     END start

  More Information:
    The following assembler error message is generated on the "boat
 gets 3" line:

    A2105 Expected: instruction, directive, or label

    Microsoft is researching this problem and will post new information
 as it becomes available.



 15. Command Line Option /E Generates a Bad Fixup Record

 Product Version(s): 5.10
 Operating System:   MS-DOS
 Flags: ENDUSER | buglist5.10
 Last Modified: 23-MAY-1988    ArticleIdent: Q30381

    The assembler will generate bad fixup records for floating point
 instructions.
    An example of this problem is the "FMUL" instruction, which will
 generate the following fixup record:

 FIXUP
  003:    fixup  seg  rel  offset     offset  0     fixup on 0xde9b
          frame  loc  target ext "FIDRQQ"

    The frame method "loc" means Intel frame method number four. This
 means the fixup frame is the same as the segment of the location.
    For floating point symbols this is meaningless, particularly in
 OS/2 and Windows. The frame method should be changed to frame method
 number five. Frame method number five would make the frame and the
 target segment the same.
    The LINK utility will ignore the frame method.

    Microsoft is researching this problem and will post new information
 as it becomes available.



 16. Command Line Option /Z Is Ignored after Processing

 Product Version(s): 5.10
 Operating System:   MS-DOS
 Flags: ENDUSER | buglist5.10
 Last Modified: 23-MAY-1988    ArticleIdent: Q30382

    The /Z command line option tells the assembler to print out any
 offending lines and any error messages it generates. The switch will
 work up to the first include statement.
    When an include file is processed a flag is cleared by mistake.
    The workaround for this problem is to bracket the include directive
 by the .XLIST or .LIST directive. Do not include a .LIST directive in
 the include file. This process will guarantee that the flag is set
 after the include file is processed.
    Microsoft is researching this problem and will post new information
 as it becomes available.


 17. SUBSTR Directive Will Not Work if Target Is the Same as Source

 Product Version(s): 5.10
 Operating System:   MS-DOS
 Flags: ENDUSER | buglist5.10
 Last Modified: 23-MAY-1988    ArticleIdent: Q30383

    The SUBSTR assignment to A in the following program should not be
 different than the SUBSTR assignment to B:

     .MODEL SMALL
     .CODE
 A   equ    <abcdef>
 B   substr A,4
 A   substr A,4
     END

    In this program, the assignment to B is "abcdef". The assignment to
 A is "def".
    Microsoft is researching this problem and will post new information
 as it becomes available.



 18. MOV with Type Operator Generates Incorrect Opcodes

 Product Version(s): 5.10
 Operating System:   MS-DOS
 Flags: ENDUSER | buglist5.10
 Last Modified: 23-MAY-1988    ArticleIdent: Q30385

    The MOV instruction, using indirect addressing, and the Type
 operator generate incorrect opcodes.

    The first MOV instruction generates the opcode "B8FFF4", which is a
 move-immediate instruction. The assembler should generate the opcode
 "8B44F4".  This opcode is generated on the second move instruction.
    MASM Version 5.00 generates the correct code for both MOV
 instructions. The following code demonstrates the problem:

 seg_1  segment  para  public  'code'
        assume cs:seg_1
 test_str struc
 test_f1  dw  ?
 test_f2  dw  ?
 test_f3  db  8 dup (?)
 test_str ends
 main_entry proc
        mov  ax,word ptr [si] - type test_str
 ;
 ;      This alternate generation works
 ;
        mov  ax,word ptr { si - type test_str]
 main_entry endp
 seg_1  ends
        end

    Microsoft is researching this problem and will post new information
 as it becomes available.



 19. .DATA Directive Causes _DATA Segment Not to Align Paragraph

 Product Version(s): 5.10
 Operating System:   MS-DOS
 Flags: ENDUSER |
 Last Modified: 23-MAY-1988    ArticleIdent: Q30386

    The .DATA directive word aligns the _DATA segment. The .MODEL
 directive defines the _TEXT segment before the _DATA segment.
 Therefore, when the simplified segment directives are used, _DATA does
 not start at a paragraph boundary.

    The following sample code demonstrates this problem:

    .MODEL small
    .DATA
    org 0h
    t1 db "table 1"
    org 100h
    t2 db "table 2"
    .CODE
    mov  ax, dgroup
    mov  ds, ax
    mov  bx, offset t1
    mov  cx, offset t2
    end

    DGROUP begins at the previous paragraph boundary, but _DATA, the
 first segment in DGROUP, actually starts at DGROUP:0006. Therefore,
 the offset of t2 could evaluate to _DATA:0100h. This is equivalent to
 DGROUP:0106h.


 20. EXTRN Data Items Placed Outside Segment

 Product Version(s): 5.10
 Operating System:   MS-DOS
 Flags: ENDUSER | buglist5.10
 Last Modified: 23-MAY-1988    ArticleIdent: Q30398

    The EXTRN statement can be placed outside of a segment declaration.
 When this is done, the item has no segment attributes, so it
 automatically matches the DS register with the item regardless of the
 active ASSUME statements.
    When the EXTRN statement is contained within a segment, the active
 ASSUME statement applies to the data item.
    To avoid this problem, you should define all EXTRN data items
 inside a segment.
    Microsoft is researching this problem and will post new information
 as it becomes available.

    The following example demonstrates the problem caused by the
 current behavior of EXTRN data items:

    If you write a .COM program that assumes DS:NOTHING and ES:NOTHING
 and declare all data items inside segments, MASM will put CS:
 overrides on all data items being accessed.
    If, to correct the problem, you decide to split the file into two
 modules and declare the data items shared with the EXTRN statement at
 the top of each module outside segments (this will not change the
 ASSUME statements), the DS register will be associated with all data
 items by default because you declared all EXTRN items outside
 segments.


 21. Warning A4001: Extra Characters on Line

 Product Version(s): 5.10
 Operating System:   MS-DOS
 Flags: ENDUSER | buglist5.10
 Last Modified: 23-MAY-1988    ArticleIdent: Q30409

    The following code generates the assembler warning, "A4001: Extra
 Characters on Line":

    .MODEL small
    .CODE
    mul ah,10
    end

    Microsoft is researching this problem and will post new information
 as it becomes available.


 22. Omitting Range Keyword after LABEL Directive Causes Errors

 Product Version(s): 5.10
 Operating System:   MS-DOS
 Flags: ENDUSER | buglist5.10
 Last Modified: 23-MAY-1988    ArticleIdent: Q30412

    When a LABEL directive is used without a range keyword, it will
 cause an "Unknown type specifier" error. This error will correctly
 occur if the LABEL directive is the first statement in the segment.
    However, if you also have executable statements prior to the LABEL
 directive in the code segment, error messages will incorrectly occur
 on every statement.
    The following program demonstrates the problem:

    .MODEL small
    .CODE
    main    proc
            mov ax, 1
            pt1 label
    main    endp
    end     main

    The "mov ax, 1" statement will incorrectly generate the error
 message "Symbol not defined: AX." The statement "pt1 label" will
 generate an "Unknown type specifier" error as well.

    Microsoft is researching this problem and will post new information
 as it becomes available.


 23. Only First LOCAL Variable Generates CodeView Information

 Product Version(s): 5.10
 Operating System:   MS-DOS
 Flags: ENDUSER | buglist5.10
 Last Modified: 23-MAY-1988    ArticleIdent: Q30416

    Only the first LOCAL variable on a line will generate CodeView
 information in the following assembler source code:

    .MODEL small
    .CODE
    main    proc
    local   first:word
    local   second:word,third:word
    local   fourth:word
    ret
    main    endp
            end main

    Microsoft is researching this problem and will post new information
 as it becomes available.


 24. Error Message Generated when Include File Has CTRL+Z

 Product Version(s): 5.10
 Operating System:   MS-DOS
 Flags: ENDUSER | buglist5.10
 Last Modified: 12-JAN-1989    ArticleIdent: Q30417

 When assembling a source file with an include file that contains a
 CTRL+Z, the assembler generates the error message, "A2106: line too
 long."

 A workaround is to use the MS-DOS Copy command with the "/a" option,
 as in the following:

 copy /a test.asm test2.asm

 Microsoft has confirmed this to be a problem in Version 5.10. We are
 researching this problem and will post new information as it becomes
 available.


 25. ASSUME Directive Using SEG Operator on Structure Causes Error

 Product Version(s): 5.10
 Operating System:   MS-DOS
 Flags: ENDUSER | buglist5.10
 Last Modified: 23-MAY-1988    ArticleIdent: Q30419

    When the ASSUME directive uses the SEG operator, it causes an
 error.
    The statement "cmp byte PTR fred.d1,0" in the following program
 incorrectly generates the "A2068: Cannot address with segment
 register" error message.
    The program assembles correctly if the statement is modified to
 "cmp byte es:fred.d1,0."
    Microsoft is researching this problem and will post new information
 as it becomes available.

    The following program demonstrates the problem:

    .MODEL LARGE,C

    dog struc
    d1  db  0
    dog ends

    .FARDATA
    COMM fred:dog

    .CODE
    cat proc
    assume es:SEG fred
    cmp byte PTR fred.d1,0
    ret
    cat endp
    end


 26. LOCAL Directive Gives Misleading Error without .MODEL Language

 Product Version(s): 5.10
 Operating System:   MS-DOS
 Flags: ENDUSER | buglist5.10
 Last Modified: 23-MAY-1988    ArticleIdent: Q30420

    The LOCAL directive may give a misleading error message without
 specifying a language on the .MODEL directive.
    The error message "Extra characters on line" is generated on the
 LOCAL directive in the following code:

 .MODEL small
 .code
 main    proc
         local first:word
         mov ax,4c00h
         int 21h
 main    endp
         end main

    The example will work correctly if you change ".MODEL small" to
 ".MODEL small,c'".

    Microsoft is researching this problem and will post new information
 as it becomes available.


 27. Extra Line-Feed Character Generated in Four-Digit Listing File

 Product Version(s): 5.1O
 Operating System:   MS-DOS
 Flags: ENDUSER | buglist5.10
 Last Modified: 23-MAY-1988    ArticleIdent: Q30421

    If the date in the file-header listing has four digits (e.g.
 1/2/88), MASM will produce a file listing with extra line-feed
 characters on the page headings.
    For example, compare the following listings, differing only by
 their dates:

 Listing 1:
 Microsoft (R) Macro Assembler Version 5.10          1/2/88 19:55:07
                                                     Page    1-1
 Listing 2:
 Microsoft (R) Macro Assembler Version 5.10          1/23/88 19:55:07
                                                     Page    1-1

    Microsoft is researching this problem and will post new information
 as it becomes available.



 28. % Operator Used in a Macro Call Generates Incorrect Output

 Product Version(s): 5.10
 Operating System:   MS-DOS
 Flags: ENDUSER | buglist5.10
 Last Modified: 23-MAY-1988    ArticleIdent: Q30422

    The following program, which contains a macro call using the %
 operator and a %out in the macro, will not always print out "assume
 nothing:"

 string  equ <assume nothing>

 usestr  macro   str
         %out    str
         endm

         usestr  %string
         .
         .
         .
         .
         usestr  %string

 end

    Microsoft is researching this problem and will post new information
 as it becomes available.



 29. CV2206 WARNING: Corrupt Debug OMF Detected in FOO.OBJ...

 Product Version(s): 5.10   | 5.10
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified:  6-AUG-1990    ArticleIdent: Q64438

 When loading a Microsoft Macro Assembler (MASM) program into CodeView
 version 3.00, the following warning is received:

    CV2206 WARNING: Corrupt debug OMF detected in FOO.OBJ, discarding
    source line information

 In this example, the program was assembled and linked with CodeView
 information.

 The warning is caused because the program was written with full
 segment declarations and the CODE segment was not declared class
 'code'.

 The problem does not appear when using dot-segment declarations.

 The following code causes this error:

   stack   segment stack para 'stack'
           db      100 dup (?)
   stack   ends

   text    segment
           assume   cs:text

   main    proc
           ret
   main    endp

   text    ends
           end main

 The following code does not cause this error:

   stack   segment stack para 'stack'
           db      100 dup (?)
   stack   ends

   text    segment  'code'
           assume   cs:text

   main    proc
           ret
   main    endp

   text    ends
           end main


 30. IRPC Directive and & Operator Used in Macro Behave Incorrectly

 Product Version(s): 5.10
 Operating System:   MS-DOS
 Flags: ENDUSER | buglist5.10
 Last Modified: 12-JAN-1989    ArticleIdent: Q30424

    The following program demonstrates a problem with the IRPC
 directive and the substitute operator, &, used in a macro.

    The program produces duplicate labels generated from "foo&i". The
 duplicate labels are "fooay", "fooby", "foocy", "foody", "fooey", and
 "foofy".
    The problem occurs when the "a" macro calls the "b" macro with the
 values 0-f. The b macro then calls the "dog" macro, using the
 hexadecimal values 0-f for each parameter, respectively. When the "x"
 parameter for the dog macro is a-f, the & substitute operator does not
 work with "y". As a result, the above labels are duplicated multiple
 times.
    Microsoft is researching this problem and will post new information
 as it becomes available.

 a macro
     irpc x,0123456789abcdef
     b x
     endm
     endm

 b macro
     irpc y,0123456789abcdef
     dog x&y
     endm
     endm

 dog macro i
 foo&i:
     push bp
     mov bp,0&i&h
     jmp reflect
     endm

 code segment para
     assume cs:code
     start:
     a
 reflect:
 code ends
 end start


 31. Structures and Segment Overrides

 Product Version(s): 4.00 5.10
 Operating System:   MS-DOS
 Flags: ENDUSER | buglist4.00
 Last Modified: 17-JUN-1988    ArticleIdent: Q30491

 Problem:
    When I do a segment override, using structures, I get an "Invalid
 Object Module" error when I link.

 Response:
    This is a known problem in Version 4.00 of MASM. This problem was
 corrected in Version 5.10.
    The following example illustrates the problem:

 ;
 ; This is broken under 4.00 w\link 3.x.
 ;
 NODE struc
      integer  dw ?
      next     dw ?
 NODE ends
 ;
 ;
 _DATA  segment
 _DATA  ends
 ;
 ;
 _TEXT segment
       mov si, offset _DATA:next ;   IT WORKS with ds:next
       mov ax, 4C00h             ;   Exit to DOS
       int 21h
 _TEXT ends
       end


 32. LOCAL Directive with Structure Type

 Product Version(s): 5.10
 Operating System:   MS-DOS
 Flags: ENDUSER | buglist5.10
 Last Modified: 10-JUL-1990    ArticleIdent: Q30492

    Page 42 of the MASM 5.10 update states that the LOCAL directive
 accepts a name of a structure defined by a STRUC structure declaration
 such as the one below:

 xy   STRUC
         x     DW   ?
         y     DW   ?
 xy   ENDS

 foo  PROC               ;Assembler responds with
      LOCAL   abc : xy   ;error A2003: Unknown type specifier

    Microsoft is researching this problem and will post new information
 as it becomes available.
 /*MSINTERNAL
 /*CONFIRMED BY: ROLANDS
 /*BUGLIST INFO:
 /*RAID DATABASE: M600
 /*BUG NUMBER: 788
 /*


 33. EXTRN Misspelled in Manual

 Product Version(s): 5.00 5.10 | 5.10
 Operating System:   MS-DOS    | OS/2
 Flags: ENDUSER | docerr
 Last Modified: 12-JAN-1989    ArticleIdent: Q30493

 In the "Microsoft Macro Assembler Programmer's Guide" there are
 misspelled EXTRNs, as follows:

 Page 90:  EXTR   xvariable:FAR
           EXTR   xprocedure:PROC

 Page 95:  EXTR   xvariable:FAR

 The EXTRNs should be as follows:

 Page 90:  EXTRN  xvariable:FAR
           EXTRN  xprocedure:PROC

 Page 95:  EXTRN  xvariable:FAR


 34. Segment Relative Versus Group Relative

 Product Version(s): 5.10
 Operating System:   MS-DOS
 Flags: ENDUSER |
 Last Modified: 23-MAY-1988    ArticleIdent: Q30500

    The following sample code will be used to explain segment relative
 and group relative:

 dgroup  GROUP   aseg,cseg
 ASSUME  cs:dgroup,ds:dgroup
 aseg    SEGMENT public  byte    'CODE'
         org 100h
         start:
         data_pointer    dw  the_data
 aseg    ends
 cseg    SEGMENT public  byte    'CODE'
         the_data    label   byte
 cseg    ends
         end start

    When defining data, fixups are relative to the start of the
 segment. The variable data_pointer will have an address relative to
 the start of the aseg segment. If you want the variable to have an
 address relative to the start of the group, you can explicitly state
 the offset relative to dgroup as follows.

 data_pointer    dw  offset  dgroup:the_data

    The exception is when you are using simplified segment directives.
 In that case, group relative fixups always are used rather than
 segment relative.
    In code segments, fixups are relative to either segment or group
 depending on the ASSUME statements. In other words, the ASSUME
 STATEMENT is checked before the fixup is generated. The exception here
 is the same as above. When using simplified segment directives, group
 relative fixups are the default.

    The OFFSET operator is segment relative and is discussed further in
 a separate article.


 35. .RADIX 16 Directive and Real Number Initialization Statement

 Product Version(s): 5.10
 Operating System:   MS-DOS
 Flags: ENDUSER | buglist5.10
 Last Modified: 23-MAY-1988    ArticleIdent: Q30502

    When .RADIX 16 directive is used, a real number initialization
 statement will generate the error "non-digit in number." The following
 is an example:

 .MODEL small
 .RADIX 16
 .data
 sym dd 1.0
 end

    The problem does not occur under MASM Version 4.00 or 5.00, but
 does occur under MASM Versions 5.00a and MASM 5.10.

    Microsoft is researching this problem and will post new information
 as it becomes available.


 36. OFFSET Operator Is Segment Relative

 Product Version(s): 5.10
 Operating System:   MS-DOS
 Flags: ENDUSER |
 Last Modified: 23-MAY-1988    ArticleIdent: Q30517

    The OFFSET operator is segment relative. The GROUP operator must be
 used to make the OFFSET operator group relative.
    The following is an example of using the OFFSET operator:

 group_1 GROUP seg_1,seg_2,seg_3

 seg_1 SEGMENT word public 'data'
 assume ds:group_1
         dw  0
 item1   dw  20 dup(0)

 seg_1 ends

 seg_2 SEGMENT word public 'code'
 assume cs:group_1

 func1   PROC    NEAR
         mov ax, offset item1
         lea ax, item1
         mov ax, offset group_1:item1
         mov ax, offset item2
         lea ax, item2
         mov ax, offset group_1:item2

 func1   ENDP

 seg_2  ENDS

 seg_3  SEGMENT  word  public  'data2'
 assume ds:group_1
 item2   dw  0
 seg_3  ENDS

    In the first move instruction, item1 will have the offset of 0002
 relative to the start of seg_1 segment. The next move instruction is
 using the group name to force the evaluation of item1 relative to the
 start of the group. The offset for item1 will be 0002 because seg_1 is
 the first segment in the group.
    The third move instruction containing item2 will have an offset
 0002 relative to the start of the seg_3 segment. Due to the alignment
 of the seg_3 segment, which is word aligned, the offset for item2 is
 not 0000. The fourth move instruction forces the item2 offset to be
 calculated from the beginning of the group. The seg_3 segment is not
 the first segment in the group but the third segment. The offset for
 item2 will be 0042.


 37. Fix-Up Overflow Caused By Extrn Statements and .Fardata

 Product Version(s): 5.10
 Operating System:   MS-DOS
 Flags: ENDUSER |
 Last Modified: 12-JAN-1989    ArticleIdent: Q30576

    The following assembler modules produce a fix-up overflow error
 message during linking.
    When linking these two modules together, the .fardata-simplified
 segment directive will cause a link-error fix-up overflow.
    Every module with a .fardata segment is defining a different
 .fardata segment. The linker will keep the segments separate.
 Therefore, declaring the fvar variable external in module 2 generates
 the problem. The extrn far data item, fvar, should be declared outside
 the .fardata segment.

 Module 1

 .model large
 .stack
 .data
 public gvar
 .fardata
 public fvar
 fvar  db  55h

 .code
 extrn t2:proc
 start: mov ax,@DATA
        mov ds,ax
        mov ax,@FARDATA
        mov es,ax

        call dword ptr t2
 end start

 Module 2

 .model large
 .data
 extrn gvar:byte
 .fardata
 extrn fvar:byte

 .code
     public t2
 t2  proc   far
     mov bl, es:fvar
     ret FAR
 t2  endp
     end



 38. Predefined Text Macros Are Case Sensitive

 Product Version(s): 5.10
 Operating System:   MS-DOS
 Flags: ENDUSER |
 Last Modified: 12-JAN-1989    ArticleIdent: Q30579

    When assembling in Microsoft Macro Assembler Version 5.10 with the
 /ML and predefined text macros, each word in the name of the text
 macro must begin with an uppercase letter.
    In MASM Version 5.00, you can use a predefined text macro, such as
 @filename, when assembling with the /ML switch. In MASM Version 5.10,
 use @FileName with the /ML switch.

    This convention does not apply to the predefined equates used with
 segment directives, such as the equate @curseg.



 39. Real-Number Data in IEEE Format

 Product Version(s): 5.10
 Operating System:   MS-DOS
 Flags: ENDUSER |
 Last Modified: 12-JAN-1989    ArticleIdent: Q30601

    By default, the Microsoft Macro Assembler Version 5.10 assembles
 real-number data in IEEE format. The previous versions of the
 assemblers used the Microsoft binary format by default.

    The following is the IEEE format for encoding 4- and 8-byte real
 numbers.

 Short Real Number
   31      23      15      7       0
  _________________________________
 |_|_______|_______|_______|_______|
 ^ ^       ^                       ^
 | |       |                       |
 | Exponent|                       |
 |         |Mantissa ------------->|
 |Sign

    The parts of the real numbers are described below:

    1. Sign (0 for positive or 1 for negative) is in the upper bit of
 the first byte.
    2. Exponent is in the next bits in sequence (8 bits for a short
 real number or 11 bits for a long real number).
    3. All except the first-set bit of Mantissa are in the remaining
 bits of the variable (13 bits for short real numbers, and 52 bits for
 long real numbers). Because the first significant bit is known to be
 set, it does not need to be stored.

    This information is documented on Pages 132-133 of the "Microsoft
 Macro Assembler Programmer's Guide."



 40. MASM 5.10 MIXED.DOC: Converting Mixed-Language Source Files

 Product Version(s): 5.10   | 5.10
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified: 25-MAY-1988    ArticleIdent: Q30784

    The following information is from the Microsoft Macro Assembler
 Version 5.10 MIXED.DOC file.

 Converting Mixed-Language Source Files
    This directory contains mixed-language example programs and macros.
    The following source files are the sample programs from Chapter 6,
 "Assembly-to-High-Level Interface," of the Mixed-Language Programming
 Guide:

    BA.ASM       Assembly module to be called from BASIC
    CA.ASM       Assembly module to be called from C
    FA.ASM       Assembly module to be called from FORTRAN
    PA.ASM       Assembly module to be called from Pascal
    BAMAIN.BAS   BASIC main program that calls assembly module
    CAMAIN.C     C main program that calls assembly module
    FAMAIN.FOR   FORTRAN main program that calls assembly module
    PAMAIN.PAS   Pascal main program that calls assembly module

    In addition, the following files are provided:

    POWER2.ASM   Macro version of assembly module that can be called
                 from BASIC, C, FORTRAN, or Pascal.
    MIXED.INC    Mixed language macros.
    MIXED.DOC    This file.


 41. MASM 5.10 MIXED.DOC: Macros Supported in MIXED.INC

 Product Version(s): 5.10   | 5.10
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified: 17-JUN-1988    ArticleIdent: Q30785

    The following information is from the Microsoft Macro Assembler
 Version 5.10 MIXED.DOC file.

 Converting Mixed-Language Source Files
    The version of MIXED.INC provided with MASM 5.10 is smaller than the
 MASM 5.00 version because most of the functionality has now been built
 into MASM and the macros are no longer needed. The following macros
 are still supported in MIXED.INC:

    Macro   Purpose

    ifFP    Assembles statement if the memory model uses far data

    FP      Provides ES override if the memory model uses far data

    pLes    Loads data (through ES for far data)

    pLds    Loads data (through DS for far data)

    To use these macros with MASM 5.10, you should include MIXED.INC
 after using .MODEL. The macro syntax is shown below:

 ifFP  statement
    Assembles the statement if the memory model uses far data. This
 macro can be used to push segment registers or take other action that
 is only required for far data. For example,

    ifFP     push  ds

 pushes the DS register in compact, large, and huge memory models, but
 has no effect in small and medium models.

 FPoperand
    Gives an ES override if the memory model uses far data. In models
 that use near data, FP is null. For example,

    mov      ax,FP[bx]

 assembles as

    mov      ax,es:[bx]

 in compact, large, and huge memory models, but as

    mov      ax,[bx]

 in small and medium models.

 pLes  register,address
 pLds  register,address
    Loads a pointer from the specified address to the specified
 register. If the memory model uses far data, the segment portion of
 the address will be moved into ES or DS, depending on the macro used.
 For example,

    pLes    bx,arg1

 is assembled as

    les     bx,arg1

 in compact, large, and huge memory models, but as

    mov     bx,arg1

 in small and medium models.


 42. MASM 5.10 MIXED.DOC: Compatiblity with Undocumented Macros

 Product Version(s): 5.10   | 5.10
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified: 17-JUN-1988    ArticleIdent: Q30786

    The following information is from the Microsoft Macro Assembler
 Version 5.10 MIXED.DOC file.

 Converting Mixed-Language Source Files
    The other macros in the MASM 5.00 version of MIXED.INC are provided
 for compatibility with MASM 5.00, but are not documented. The rest of
 this file discusses compatibility options for source code that uses
 5.00 high-level-language macros. If you did not own MASM 5.00, you
 should ignore the rest of this file. Do not use the other macros in
 MIXED.INC.
    You can use the following macros if you have source code that uses
 the macros provided with MASM 5.00.

    Macro      Purpose

    setModel   Sets memory model passed from a DOS command line. No
               longer needed because the expression operator now enables
               you to evaluate text macros passed from the command line
               directly.

    hProc      Initializes a procedure. Replaced by new attributes of
               the PROC directive when you specify a language argument to
               the .MODEL directive.

    hLocal     Initializes local variables. Replaced by new functionality
               of the LOCAL directive.

    hRet       Returns from a procedure. Replaced by new functionality
               of the RET instruction.

    hEndp      Terminates a procedure. Replaced by new functionality of
               the ENDP directive.

    The 5.10 versions of these macros are different than the MASM 5.00
 versions. The new macros use new MASM features to simulate the same
 functionality more efficiently. Do not use the MIXED.INC provided with
 MASM 5.00. It will not work under MASM 5.10.


 43. MASM 5.10 MIXED.DOC: Converting Old Macros of MASM 5.00

 Product Version(s): 5.10   | 5.10
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified: 17-JUN-1988    ArticleIdent: Q30787

    The following information is from the Microsoft Macro Assembler
 Version 5.10 MIXED.DOC file.

 Converting Mixed-Language Source Files
    Rather than use the old macros, you may want to convert your source
 files to use the built-in mixed language features of MASM 5.10. The
 conversion is straightforward and can be done easily with a text
 editor.
    The following changes can be made to source files that use macros
 from the 5.0 MIXED.INC. The source file POWER2.ASM on the MASM 5.10
 distribution disk is an example of a converted source file. You can
 compare it with the POWER2.ASM supplied with MASM 5.00.
    You must define a memory model argument and a language argument
 to the .MODEL directive to use the new mixed-language features of MASM
 5.10. You can do this within the source file:

    .MODEL small, c

    Alternately, you can pass the arguments in from the command line
 using /D. In MASM 5.00, you had to use the setModel macro to receive a
 model argument passed on the command line. You only needed to define
 the language symbol "cLang" for C; no definition was needed for other
 languages.
    The 5.00 source line to accept the argument would be:

    setModel

    For MASM 5.10, change to:

    %      .MODEL model,lang

    Notice that the expression operator (%) is required so that MASM
 can evaluate text arguments passed from the command line.
    The 5.00 command line to define C small model would be:

    MASM /MX /Dmodel=small /DcLang power2;

    For MASM 5.1, change this to:

    MASM /MX /Dmodel=small /Dlang=C power2;

    Replace references to the hProc macro with the PROC directive.
 Remember, new features of the PROC directive only work when a language
 argument is given for the .MODEL directive. The 5.00 macro syntax was:

    hProc  <name [NEAR|FAR]> [,<USES reglist>] [,arglist]

    The 5.10 syntax is:

    name PROC [NEAR|FAR] [,USES reglist] [,arglist]

    The syntax for each MASM 5.00 argument in the arglist was

    argument[:[NEAR|FAR] type]

 where the type could be BYTE, WORD, DWORD, FWORD, QWORD, TBYTE, or PTR
 (to indicate that the variable is a pointer).
    The syntax for each MASM 5.10 argument is:

    argument[:[[NEAR|FAR] PTR] type]

 where the type can be BYTE, WORD, DWORD, FWORD, QWORD, TBYTE, or a
 structure type. Note that structure types can now be given. Also, PTR
 is part of the syntax rather than a type. If PTR is given with a type,
 then it means that the variable is a pointer to a variable of the
 given type. This information makes no difference in what MASM
 assembles, but it can be used by the CodeView debugger.
    For example, consider the following MASM 5.00 source line:

    hProc   <doTask FAR>, <USES si di>, count:BYTE, array:PTR, number

    It should be changed to the following for MASM 5.10:

    doTask  PROC FAR USES si di, count:BYTE, array:PTR WORD, number

    Notice that the array is now declared as pointer to a word (or an
 array of words). In the 5.00 syntax it was simply a pointer to an
 object of undefined size.

    o Replace references to the hLocal macro with the LOCAL directive.
 The syntax for the 5.00 hLocal macro was:

    hLocal  varlist

    The MASM 5.1 syntax is:

    LOCAL   varlist

    The syntax for each 5.00 variable was:

    variable[:[NEAR|FAR] type]

    The syntax for each 5.10 variable is:

    variable[[count]][:[[NEAR|FAR] PTR] type]

    The difference is the same as the difference for arguments to the
 PROC directive. In addition, you can allocate local arrays by
 specifying a count (in brackets) following the variable name. For
 example:

    LOCAL   work[20]:WORD, string:PTR BYTE

    This allocates a local array of 20 words called "work" and a
 pointer to byte (called "string").

    o Replace references to the hRet macro with the RET instruction.

    o Replace references to the hEndp macro with the ENDP directive
 preceded by the procedure name. For example, change

    hEndp

 to

    procname ENDP

    Under MASM 5.10, labels within a procedure are local to the
 procedure if the language argument is given for the .MODEL directive.
 For example, if you use the label "exit:" in one procedure, you can
 use it again in another procedure. A label inside a procedure can be
 made global to the source file by putting two colons after it
 (example, "glabel::"). Under MASM 5.00 all labels were global to the
 source file.
    Note that the 5.00 macros did not automatically handle 80386
 features such as 32-bit pointers. The 5.10 features do. For example, if
 you use the .386 directive before the .MODEL directive to enable
 32-bit segments, near pointers declared with PTR will be 32 bits wide
 and far pointers will be 48 bits wide.


 44. MASM 5.10 OS2.DOC: Calling OS/2 Macros

 Product Version(s): 5.10   | 5.10
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified: 25-MAY-1988    ArticleIdent: Q30800

    The following information is from the Microsoft Macro Assembler
 Version 5.10 OS2.DOC file.

 Calling OS/2 Macros
    You can simplify calls of OS/2 systems services by using the
 macros. The OS/2 macros are organized into groups that can be enabled
 by including the file OS2.INC and defining constants associated with
 each group. For example, to enable file management macros, put the
 following lines in the source file where the macros will be used:

 INCL_DOSFILEMGR EQU 1
 INCLUDE os2.inc

    Note that the constant must be defined before the include file is
 specified. The groups of macros and the constants associated with each
 are described later in this file.
    Macros have the name of the OS/2 call preceded by an at sign (@).
 For example, the macro to call the DosFindNext service is called
 @DosFindNext.
    Parameters are passed to macros by listing them on the same line as
 the macro name in much the same way as in most high-level languages.
 For example, you could use the following lines to call the
 @DosFindNext macro:

 dHandle   DW      -1            ; Directory handle
 dResult   FILEFINDBUF <>        ; Structure for results
 dlResult  EQU     $ - dResult   ;   length of result
 dCount    DW      1             ; Find one file at a time
           .
           .
           .
           @DosFindNext [dHandle], dResult, dlResult, dCount

    When passing memory locations as arguments, you can specify the
 contents of the specified variable by enclosing it in brackets. In the
 command line above, the value of the word variable dHandle (-1) is
 passed as the first argument.
    To pass the far address of a variable, give the argument without
 brackets. The addresses of dResult and dCount are passed in the
 command-line above. Note that dResult is defined as a structure of
 type FILEFINDBUF. The FILEFINDBUF structure is defined in the include
 file.
    You can pass word values in registers or constants by listing them
 without brackets. For example, dlResult is a constant in the example.
 If the file handle were in register DX instead of in the variable
 dHandle, you could substitute the register name. You cannot pass
 doubleword constants. For example, to pass a doubleword zero, you must
 first store the value in a variable.
    The macros do type checking. An error will be generated if you pass
 an argument of an invalid size or if you pass the wrong number of
 arguments. All arguments are expected to be word or doubleword values.
 Addresses are always far, and are thus passed as doublewords.
    Note that the macros cannot check to see that you are actually
 passing an an address when required, since the macro has no way of
 knowing whether you are passing the address as a doubleword pointer
 variable or as a label specifying an address.
    If you wish to pass a value stored in a byte variable or register,
 you must expand this value to a word before passing. For example, use
 CBW to expand a byte in AL to a word in AX.
    Most valid operands can be passed as arguments. For example, the
 following are valid arguments:

     [es:[di]]              ; Contents of a word indirect memory operand
     <[DWORD PTR es:[di]]>  ; Contents of a doubleword indirect memory operand
     <SIZE var1>            ; A constant
     es:table[bx]           ; Address of an indirect memory operand

    Note that arguments containing spaces or tabs must be enclosed in
 angle brackets so that the macro will see them as a single argument.
    The macros assume that DS=SS. If you change either of these
 registers temporarily, you should restore the register before passing
 arguments. The macros may change the contents of AX or BX, so you
 should save any important values in these registers before using an
 OS/2 macro.


 45. MASM 5.10 OS2.DOC: OS/2 Call Summary - Overview

 Product Version(s): 5.10   | 5.10
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified: 25-MAY-1988    ArticleIdent: Q30801

    The following information is from the Microsoft Macro Assembler
 Version 5.10 OS2.DOC file.

 OS/2 Call Summary
    The OS/2 calls are listed below. The constant symbols associated
 with each group of macros are shown before the listings. The listings
 consist of the macro name followed by a one-line description. A second
 line shows the arguments expected by the macro. The following symbols
 are used to indicate the type of each argument:

     W     Word
     D     Doubleword
     PB    Pointer to byte
     PW    Pointer to word
     PD    Pointer to doubleword
     PZ    Pointer to ASCIIZ string
     PS    Pointer to structure

    If the macro expects the address of a structure as one of its
 arguments, the structure will be listed below the argument line. See
 the include files for listings of structure fields. The include files
 also contain definitions for constants often passed to specific
 macros.
    This document makes no attempt to explain the purpose or function
 of the OS/2 systems calls. The calls are described in detail in
 manuals published separately by Microsoft and in some third-party
 books and magazine articles.


 46. MASM 5.10 OS2.DOC: OS/2 Call Summary - @DosBeep, @DosExit

 Product Version(s): 5.10   | 5.10
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified: 27-MAY-1988    ArticleIdent: Q30802

    The following information is from the Microsoft Macro Assembler
 Version 5.10 OS2.DOC file:

 OS/2 Call Summary:
    The following macros are included unconditionally:

    @DosBeep - Generates sound from speaker
    Parameters - Frequency:W, Duration:W

    @DosExit - Terminates a thread
    Parameters - ActionCode:W, ResultCode:W


 47. MASM 5.10 OS2.DOC: OS/2 Call Summary - Error Number Constant

 Product Version(s): 5.10   | 5.10
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified: 25-MAY-1988    ArticleIdent: Q30803

    The following information is from the Microsoft Macro Assembler
 Version 5.10 OS2.DOC file.

 OS/2 Call Summary:
    Named error number constant - INCL_ERRORS


 48. MASM 5.10 OS2.DOC: OS/2 Call Summary - Process Control

 Product Version(s): 5.10   | 5.10
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified: 26-MAY-1988    ArticleIdent: Q30804

    The following information is from the Microsoft Macro Assembler
 Version 5.10 OS2.DOC file.

 OS/2 Call Summary
 Processes control constant - INCL_DOSPROCESS

    @DosCreateThread - Creates an asynchronous thread
    Parameters - PgmAddress:D, ThreadID:PW, NewThreadStack:PB

    @DosResumeThread - Restarts a suspended thread
    Parameters - ThreadID:W

    @DosSuspendThread - Suspends a thread
    Parameters - ThreadID:W

    @DosCWait - Makes thread wait for child process to terminate
    Parameters - ActionCode:W, WaitOption:W, ReturnCodes:PS, ProcessIDWord:PD,
                 ProcessID:W
    Structure - RESULTCODES

    @DosSleep - Suspends current thread for specified interval
    Parameters - Interval:D

    @DosEnterCritSec - Disables other threads
    Parameters - none

    @DosExitCritSec - Reenables other threads
    Parameters - none

    @DosExitList - Maintains list of routines to be executed when thread ends
    Parameters - FnCode:W, RtnAddress:PW

    @DosExecPgm - Requests execution of a child program
    Parameters - ObjNameBuf:PB, ObjNameBufL:W, AsyncTraceFlags:W,
                 ArgPointer:PZ, EnvPointer:PZ, ReturnCodes:PD, PgmPointer,PZ

    @DosGetPid - Gets process identification
    Parameters - Pid:PS
    Structure - PIDINFO

    @DosGetPrty - Returns the priority of a thread
    Parameters - Scope:W, Priority:PW, ID:W

    @DosSetPrty - Sets the priority of a child process or thread
    Parameters - Scope:W, PriorityClass:W, PriorityDelta:W, ID:W

    @DosKillProcess - Terminates a process and returns its termination code
    Parameters - ActionCode:W, ProcessID:W


 49. MASM 5.10 OS2.DOC: OS/2 Call Summary - Segment Information

 Product Version(s): 5.10   | 5.10
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified: 26-MAY-1988    ArticleIdent: Q30805

    The following information is from the Microsoft Macro Assembler
 Version 5.10 OS2.DOC file.

 OS/2 Call Summary
 Information segment constant - INCL_DOSPROCESS

    @DosGetInfoSeg - Returns the addresses of the global and local segment
    Parameters - GlobalSeg:PW, LocalSeg:PW
    Structures - The returned segments contain the addresses of the GINFOSEG
                 and LINFOSEG structures


 50. MASM 5.10 OS2.DOC: OS/2 Call Summary - File Management

 Product Version(s): 5.10   | 5.10
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified: 26-MAY-1988    ArticleIdent: Q30806

    The following information is from the Microsoft Macro Assembler
 Version 5.10 OS2.DOC file.

 OS/2 Call Summary
 File management constant - INCL_DOSFILEMGR

    @DosOpen - Opens a file (creating it if necessary)
    Parameters - FileName:PZ, Handle:PW, ActionTaken:PW, Size:D,
                 FileAttribute:W, OpenFlag:W, OpenMode:@, Reserved:D

    @DosClose - Closes a file handle
    Parameters - FileHandle:W

    @DosRead - Reads bytes from a file to a buffer
    Parameters - FileHandle:W, BufferArea:PB, BufferLength:W, ByteRead:PW

    @DosWrite - Writes bytes synchronously from a buffer to a file
    Parameters - FileHandle:W, BufferAddress:PB, BufferLength:W,
                 BytesWritten:PW

    @DosDelete - Deletes a file
    Parameters - FileName:PZ, Reserved:D

    @DosDupHandle - Returns a new duplicate file handle for an open file
    Parameters - OldFileHandle:W, NewFileHandle:PW

    @DosQFHandState - Gets the state of the specified file
    Parameters - FileHandle:W, FileHandleState:PW

    @DosSetFHandState - Sets the state of a file
    Parameters - FileHandle:W, FileHandleState:W

    @DosQHandType - Determines whether a handle references a file or a device
    Parameters - FileHandle:W, HandType:PW, FlagWord:PW

    @DosReadAsync - Reads bytes from a file to a buffer asynchronously
    Parameters - FileHandle:W, RamSemaphore:PD, ReturnCode:PW, BufferArea:PB,
                 BufferLength:W, BytesRead:PW

    @DosWriteAsync - Writes bytes asynchronously from a buffer to a file
    Parameters - FileHandle:W, RamSemaphore:PD, ReturnCode:PW,
                 BufferAddress:PB, BufferLength:W, BytesWritten:PW

    @DosFindFirst - Finds the first directory entry matching a file
                    specification
    Parameters - FileName:PZ, DirHandle:PW, Attribute:W, ResultBuf:PS
                 ResultBufLen:W, SearchCount:PW, Reserved:D
    Structure - FILEFINDBUF

    @DosFindNext - Finds the next directory entry matching a file specificatio
    Parameters - DirHandle:W, ResultBuf:PS, ResultBufLen:W, SerachCount:PW
    Structure - FILEFINDBUF

    @DosFindClose - Closes a directory search handle
    Parameters - DirHandle:W

    @DosNewSize - Changes the size of a file
    Parameters - FileHandle:W, Size:D

    @DosBufReset - Flushes a file buffer and updates directory information
    Parameters - FileHandle:W

    @DosChgFilePtr - Moves the read/write pointer according to a specified
                     method
    Parameters - FileHandle:W, Distance:D, MoveType:W, NewPointer:PD

    @DosFileLocks - Locks or unlocks a range in an open file
    Parameters - FileHandle:W, UnlockRange:PD, LockRange:PD

    @DosMove - Moves (or renames) a specified file
    Parameters - OldFilename:PZ, NewFileName:PZ, Reserved:D

    @DosMkdir - Creates a directory
    Parameters - DirName:PZ, Reserved:D

    @DosRmdir - Removes a subdirectory from a disk
    Parameters - DirName:PZ, Reserved:D

    @DosSelectDisk - Selects a specified drive as the new default drive
    Parameters - DriveNumber:W

    @DosQCurDisk - Returns the current drive
    Parameters - DriveNumber:PW, LogicalDriveMap:PD

    @DosChdir - Changes to a specified directory
    Parameters - DirName:PZ, Reserved:D

    @DosQCurDir - Retrieves the full path of the current directory
    Parameters - DriveNumber:W, DirPath:PB, DirPathLen:PW

    @DosQFSInfo - Retrieves information from a file system device
    Parameters - DriveNumber:W, FSInfoLevel:W, FSInfoBuf:PB, FSInfoBufSize:W
    Structure - For GDInfoLevel 1, point FSInfoBuf to FSALLOCATE

    @DosSetFSInfo - Sets information for a file system device
    Parameters - DriveNumber:W, FSInfoLevel:W, FSInfoBuf:PB, FSInfoBufSize:W

    @DosQVerify - Returns the value of the verify flag
    Parameters - VerifySetting:PW

    @DosSetVerify - Sets the verify flag
    Parameters - VerifySetting:W

    @DosSetMaxFH - Defines the maximum number of file handles
    Parameters - NumberHandles:W

    @DosQFileInfo - Returns information about a file
    Parameters - FileHandle:W, FileInfoLevel:W, FileInfoBuf:PB,
                 FileInfoBufSize:B
    Structure - At FileInfoLevel 1, can point FileInfoBuf to FILESTATUS

    @DosSetFileInfo - Specifies information for a file
    Parameters - FileHandle:W, FileInfoLevel:W, FileInfoBuf:PB,
                 FileInfoBufSize:W
    Structure - At FileInfoLevel 1, can point FileInfoBuf to FILESTATUS

    @DosQFileMode - Retrieves the mode (attribute) of a file
    Parameters - FileName:PZ, Attribute:PW, Reserved:D

    @DosSetFileMode - Changes the mode (attribute) of a file
    Parameters - Filename:PZ, Attribute:W, Reserved:D


 51. MASM 5.10 OS2.DOC: OS/2 Call Summary - Memory Management

 Product Version(s): 5.10   | 5.10
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified: 26-MAY-1988    ArticleIdent: Q30807

    The following information is from the Microsoft Macro Assembler
 Version 5.10 OS2.DOC file>

 OS/2 Call Summary
 Memory management constant - INCL_DOSMEMMGR

    @DosAllocSeg - Allocates a segment of memory
    Parameters - Size:W, Selector:PW, AllocFlags:W

    @DosReallocSeg - Changes the size of an allocated segment
    Parameters - Size:W, Selector:W

    @DosFreeSeg - Deallocates a segment
    Parameters - Selector:W

    @DosGiveSeg - Gives another process access to a shared memory segment
    Parameters - CallerSegHandle:W, ProcessID:W, RecipientSegHandle:PW

    @DosGetSeg - Gets access to a shared memory segment
    Parameters - Selector:W

    @DosAllocHuge - Allocates memory potentially requiring multiple segments
    Parameters - NumSeg:W, Size:W, Selector:PW, ShareInd:W, MaxNumSeg:W

    @DosReallocHuge - Changes memory amount previously allocated by
                      DosAllocHuge
    Parameters - NumSet:W, Size:W, Selector:W

    @DosGetHugeShift - Returns a shift count used to derive selectors to
                       huge memory allocated with DosAllocHuge
    Parameters - ShiftCount:PW

    @DosAllocShrSeg - Allocates a shared memory segment
    Parameters - Size:W, Name:PZ, Selector:PW

    @DosLockSeg - Locks a discardable segment in memory
    Parameters - Selector:W

    @DosUnlockSeg - Unlocks a discardable segment
    Parameters - Selector:W

    @DosGetShrSeg - Allows a process to access a previously allocated shared
                    memory segment and increments the segment reference count
    Parameters - Name:PZ, Selector:PW

    @DosMemAvail - Returns the size of the largest block of free memory
    Parameters - MemAvailSize:PD

    @DosCreateCSAlias - Creates an executable alias for a data type descriptor
                        passed as input
    Parameters - DataSelector:W, CodeSelector:PW

    @DosSubAlloc - Allocates memory from within a segment that was previously
                   allocated and initialized with DosSubSet
    Parameters - SegSelector:W, BlockOffset:PW, Size:W

    @DosSubFree - Frees memory previously allocated with DosSubAlloc
    Parameters - SegSelector:W, BlockOffset:W, Size:W

    @DosSubSet - Initializes a segment for suballocation, or changes the size
                 of a previous suballocation
    Parameters - SegSelector:W, BlockOffset:W, Size:W


 52. MASM 5.10 OS2.DOC: OS/2 Call Summary - Semaphores

 Product Version(s): 5.10   | 5.10
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified: 26-MAY-1988    ArticleIdent: Q30808

    The following information is from the Microsoft Macro Assembler
 Version 5.10 OS2.DOC file.

 OS/2 Call Summary
 Semaphore constant - INCL_DOSSEMAPHORES

    @DosSemClear - Unconditionally clears a semaphore
    Parameters - SemHandle:D

    @DosSemSet - Unconditionally sets a semaphore
    Parameters - SemHandle:D

    @DosSemWait - Blocks current thread until a specified semaphore is cleared
    Parameters - SemHandle:D, Timeout:D

    @DosSemSetWait - Sets a specified semaphore and blocks current thread
                     until the semaphore is cleared
    Parameters - SemHandle:D, Timeout:D

    @DosSemRequest - Obtains a semaphore
    Parameters - SemHandle:D, Timeout:D

    @DosCreateSem - Creates a system semaphore
    Parameters - NoExclusive:W, SemHandle:PD, SemName:PZ

    @DosOpenSem - Opens a semaphore and assigns it a handle
    Parameters - SemHandle:PD, SemName:PZ

    @DosCloseSem - Closes a system semaphore
    Parameters - SemHandle:D

    @DosMuxSemWait - Blocks the current thread until one or more specified
                     semaphores is cleared
    Parameters - IndexNum:PW, ListAddr:PS, Timeout:D
    Structure - MUXSEMLIST (which contains MUXSEM structures)


 53. MASM 5.10 OS2.DOC: OS/2 Call Summary - Module Management

 Product Version(s): 5.10   | 5.10
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified: 27-MAY-1988    ArticleIdent: Q30809

    The following information is from the Microsoft Macro Assembler
 Version 5.10 OS2.DOC file.

 OS/2 Call Summary
 Module management constant - INCL_DOSMODULEMGR

    @DosLoadModule - Loads a dynamic-link module and assigns it a handle
    Parameters - ObjNameBufAdd:PD, ObjNameBufL:W, ModuleName:PZ,
                 ModuleHandle:PW

    @DosFreeModule - Frees a reference to a dynamic-link module
    Parameters - ModuleHandle:W

    @DosGetProcAddr - Returns the far address of a procedure within a
                      dynamic-link module
    Parameters - ModuleHandle:W, ProcName:PZ, ProcAddress:PD

    @DosGetModHandle - Tests whether a specified dynamic-link module is loaded
    Parameters - ModuleName:PZ, ModuleHandle:PW

    @DosGetModName - Returns the complete pathname of a specified module
    Parameters - ModuleHandle:W, BufferLength:W, Buffer:PB


 54. MASM 5.10 OS2.DOC: OS/2 Call Summary - Resource Management

 Product Version(s): 5.10   | 5.10
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified: 26-MAY-1988    ArticleIdent: Q30810

    The following information is from the Microsoft Macro Assembler
 Version 5.10 OS2.DOC file.

 OS/2 Call Summary
 Resource management constant - INCL_DOSRESOURCES

    @DosGetResource - Returns the selector of a specified resource segment
    Parameters - ModHandle:W, TypeID:W, NameID:W, Selector:PW


 55. MASM 5.10 OS2.DOC: OS/2 Call Summary - National Lang. Support

 Product Version(s): 5.10   | 5.10
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified:  1-JUN-1988    ArticleIdent: Q30811

    The following information is from the Microsoft Macro Assembler
 Version 5.10 OS2.DOC file.

 OS/2 Call Summary
 National language support constant - INCL_DOSNLS

    @DosGetCtryInfo - Obtains country-dependent formatting information
    Parameters - Length:W, CountryCode:PS, MemoryBuffer:PS, DataLength:PW
    Structures - COUNTTRYCODE, COUNTRYINFO

    @DosGetDBCSEv - Obtains the DBCS environmental vector from COUNTRY.SYS
    Parameters - Length:W, CountryCode:PS, MemoryBuffer:PW
    Structure - COUNTRYCODE

    @DosCaseMap - Does case mapping on an ASCII string
    Parameters - Length:W, CountryCode:PS, String:PB
    Structure - COUNTRYCODE

    @DosGetCollate - Obtains an ASCII collating sequence table from
                     COUNTRY.SYS
    Parameters - Length:W, CountryCode:PS, MemoryBuffer:PB, DataLength:PW
    Structure - COUNTRYCODE

    @DosGetCp - Queries the current code page and the prepared system code
                pages
    Parameters - Length:W, CodePageList:PW, DataLength:PW

    @DosSetCp - Sets the code page
    Parameters - CodePage:W, Reserved:W


 56. MASM 5.10 OS2.DOC: OS/2 Call Summary - Signal Management

 Product Version(s): 5.10   | 5.10
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified: 26-MAY-1988    ArticleIdent: Q30812

    The following information is from the Microsoft Macro Assembler
 Version 5.10 OS2.DOC file.

 OS/2 Call Summary
 Signal management constant - INCL_DOSSIGNALS

    @DosSetSigHandler - Establishes a signal handler
    Parameters - RoutineAddress:D, PrevAddress:PD, PrevAction:PW, Action:W,
                 SigNumber:W

    @DosFlagProcess - Sets an external event flag on another process
    Parameters - ProcessID:W, Action:W, FlagNum:W, FlagArg:W

    @DosHoldSignal - Temporarily enables or disables signal processing
    Parameters - ActionCode:W

    @DosSendSignal - Sends a CTRL-C or CTRL-BREAK signal
    Parameters - ProcessID:W, SigNumber:W


 57. MASM 5.10 OS2.DOC: OS/2 Call Summary - Monitor Management

 Product Version(s): 5.10   | 5.10
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified: 26-MAY-1988    ArticleIdent: Q30813

    The following information is from the Microsoft Macro Assembler
 Version 5.10 OS2.DOC file.

 OS/2 Call Summary
 Monitor management constant - INCL_DOSMONITORS

    @DosMonOpen - Initiates device monitoring and assigns a monitor handle
    Parameters - DevName:PZ, Handle:PW

    @DosMonClose - Terminates device monitoring
    Parameters - Handle:W

    @DosMonReg - Establishes input and output buffers to monitor an I/O stream
    Parameters - Handle:W, BufferI:PB, BufferO:PB, PosFlag:W, Index:W

    @DosMonRead - Waits for and reads input from the monitor buffer
    Parameters - BufferI:PB, WaitFlag:W, DataBuffer:PB, ByteCnt:PW

    @DosMonWrite - Writes data to the output buffer of a monitor
    Parameters - BufferO:PB, DataBuffer:PB, ByteCnt:W


 58. MASM 5.10 OS2.DOC: OS/2 Call Summary - Queue Management

 Product Version(s): 5.10   | 5.10
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified: 26-MAY-1988    ArticleIdent: Q30814

    The following information is from the Microsoft Macro Assembler
 Version 5.10 OS2.DOC file.

 OS/2 Call Summary
 Queue management constant - INCL_DOSQUEUES

    @DosMakePipe - Creates a pipe
    Parameters - ReadHandle:PW, WriteHandle:PW, PipeSize:W

    @DosCloseQueue - Closes a queue
    Parameters - QueueHandle:W

    @DosCreateQueue - Creates and opens a queue
    Parameters - QueueHandle:PW, QueuePrt:W, QueueName:PZ

    @DosOpenQueue - Opens a queue
    Parameters - OwnerPID:PW, QueueHandle:PW, QueueName:PZ

    @DosPeekQueue - Retrieves, but does not remove, a queue element
    Parameters - QueueHandle:W, Request:PD, DataLength:PW, DataAddress:PD
                 ElementCode:PW, NowWait:W, ElemPriority:PB, SemHandle:D

    @DosPurgeQueue - Purges a queue of all elements
    Parameters - QueueHandle:W

    @DosQueryQueue - Finds the size of (number of elements in) a queue
    Parameters - QueueHandle:W, NumberElements:PW

    @DosReadQueue - Reads and removes an element from a queue
    Parameters - QueueHandle:W, Request:PD, DataLength:PW, DataAddress:PD
                 ElementCode:W, NoWait:W, ElemPriority:PW, SemHandle:D

    @DosWriteQueue - Adds an element to a queue
    Parameters - QueueHandle:W, Request:W, DataLength:W, DataBuffer:PB,
                 ElemPriority:W


 59. MASM 5.10 OS2.DOC: OS/2 Call Summary - Miscellaneous Functions

 Product Version(s): 5.10   | 5.10
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified: 26-MAY-1988    ArticleIdent: Q30815

    The following information is from the Microsoft Macro Assembler
 Version 5.10 OS2.DOC file.

 OS/2 Call Summary
 Miscellaneous functions constant - INCL_DOSMISC

    @DosError - Enables OS/2 to receive hard-error notification without
                generating a hard-error signal
    Parameters - Flag:W

    @DosSetVec - Registers an address to be used when an exception occcurs
    Parameters - VecNum:W, RoutineAddress:D, PrevAddress:PD

    @DosGetMessage - Retrieves a message from a message file and inserts
                     variable information into the message
    Parameters - IvTable:PD, IvCount:W, DataArea:PB, DataLength:W,
                 MsgNumber:W, FileName:PZ, MsgLength:PW

    @DosErrClass - Enables recognition and processing of error (exit) codes
    Parameters - Code:W, Class:PW, Action:PW, Locus:PW

    @DosInsMessage - Inserts variable text string information into a message
    Parameters - IvTable:PD, IvCount:W, MsgInput:PZ, MsgInLength:W,
                 DataArea:PW, DataLength:W, MsgLength:PW

    @DosPutMessage - Outputs a message from a buffer to a specified handle
    Parameters - FileHandle:W, MessageLength:W, MessageBuffer:PB

    @DosGetEnv - Gets the segment of the environment string and the
                 offset within it of the command line
    Parameters - EnvPointer:PW, CmdOffset:PW

    @DosScanEnv - Searches an environment segment for an environment variable
    Parameters - EnvVarName:PZ, ResultPointer:PD

    @DosSearchPath - Enables applications to find files in specified
                     directories
    Parameters - Control:W, PathRef:PZ, Filename:PZ, ResultBuffer:PB,
                 ResultBufferLen:W

    @DosGetVersion - Gets the current DOS version
    Parameters - VersionWord:PW

    @DosGetMachineMode - Tells whether the processor is in real or
                         protected mode
    Parameters - MachineMode:PB


 60. MASM 5.10 OS2.DOC: OS/2 Call Summary - Date/Time Management

 Product Version(s): 5.10   | 5.10
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified: 26-MAY-1988    ArticleIdent: Q30816

    The following information is from the Microsoft Macro Assembler
 Version 5.10 OS2.DOC file.

 OS/2 Call Summary
 Date and time management constant - INCL_DOSDATETIME

    @DosGetDateTime - Gets the current date and time
    Parameters - DateTime:PS
    Structure - DATETIME

    @DosSetDateTime - Sets the date and time
    Parameters - DateTime:PS
    Structure - DATETIME

    @DosTimerAsync - Starts a timer that is asynchronous to the launching
                     thread
    Parameters - TimeInterval:D, SemHandle:D, Handle:PW

    @DosTimerStart - Starts a periodic interval timer
    Parameters - TimeInterval:D, SemHandle:D, Handle:PW

    @DosTimerStop - Stops an interval or asynchronous timer
    Parameters - Handle:W


 61. MASM 5.10 OS2.DOC: OS/2 Call Summary - Session Management

 Product Version(s): 5.10   | 5.10
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified: 26-MAY-1988    ArticleIdent: Q30817

    The following information is from the Microsoft Macro Assembler
 Version 5.10 OS2.DOC file.

 OS/2 Call Summary
 Session management constant - INCL_DOSSESMGR

    @DosStartSession - Starts a new session
    Parameters - StartData:PS, SessID:PW, PID:PW
    Structure - STARTDATA

    @DosSetSession - Sets status of a child process
    Parameters - SessID:W, StatusData:PS
    Structure - STATUSDATA

    @DosSelectSession - Enables a parent process to switch a child to
                        foreground
    Parameters - SessID,W, Reserved:D

    @DosStopSession - Terminates session previously started with
                      DosStartSession
    Parameters - TargetOption:W, SessID:W, Reserved:D


 62. MASM 5.10 OS2.DOC: OS/2 Call Summary - Device Driver

 Product Version(s): 5.10   | 5.10
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified: 26-MAY-1988    ArticleIdent: Q30818

    The following information is from the Microsoft Macro Assembler
 Version 5.10 OS2.DOC file.

 OS/2 Call Summary
 Device driver constant - INCL_DOSDEVICES

    @DosDevConfig - Gets information about attached devices
    Parameters - DeviceInfo:PB, Item:W, Parameter:W

    @DosDevIOCtl - Performs control functions on a specified device
    Parameters - Data:PB, ParmList:PB, Function:W, Category:W, Handle:W

    @DosSystemService - Requests a special function from the system
    Parameters - ServiceCategory:W, RequestPacket:PB, ResponsePacket:PB

    @DosCLIAccess - Requests privilege to disable (CLI) or enable (STI)
                    interrupts
    Parameters - None

    @DosPortAccess - Requests or releases privilege for I/O port access
    Parameters - Reserved:W, TypeOfAccess:W, FirstPort:W, LastPort:W

    @DosPhysicalDisk - Obtains information on partitionable disks
    Parameters - Function:W, DataPtr:D, DataLength:W, ParmPtr:D, ParmLength:W


 63. MASM 5.10 OS2.DOC: OS/2 Call Summary - Keyboard Input

 Product Version(s): 5.10   | 5.10
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified: 26-MAY-1988    ArticleIdent: Q30819

    The following information is from the Microsoft Macro Assembler
 Version 5.10 OS2.DOC file.

 OS/2 Call Summary
 Keyboard input constant - INCL_KBD

    @KbdRegister - Registers a keyboard subsystem within a screen group
    Parameters - ModuleName:PZ, EntryPoint:PZ, FunctionMask:D

    @KbdCharIn - Returns a character/scan code from the keyboard
    Parameters - CharData:PS, IOWait:W, KbdHandle:W
    Structure - KBDKEYINFO

    @KbdPeek - Returns a character and scan code, if available, without
               removing it from the keystroke buffer
    Parameters - CharData:PS, KbdHandle:W
    Structure - KBDKEYINFO

    @KbdStringIn - Reads a character string from the keyboard
    Parameters - CharBuffer:PB, Length:PS, IOWait:W, KbdHandle:W
    Structure - STRINGINBUF

    @KbdFlushBuffer - Clears the keystroke buffer
    Parameters - KbdHandle:W

    @KbdSetStatus - Sets the characteristics of the keyboard
    Parameters - Structure:PS, KbdHandle:W
    Structure - KBDINFO

    @KbdGetStatus - Gets status information about the keyboard
    Parameters - Structure:PS, KbdHandle:W
    Structure - KBDINFO

    @KbdOpen - Creates a new logical keyboard
    Parameters - KbdHandle:PW

    @KbdClose - Ends a logical keyboard
    Parameters - KbdHandle:W

    @KbdSetCp - Sets the code page identifier for a logical keyboard
    Parameters - Reserved:W, CodePageID:W, KbdHandle:W

    @KbdGetCp - Retrieves the code page identifier for the logical keyboard
    Parameters - Reserved:D, CodePageID:PW, KbdHandle:W

    @KbdGetCp - Ends a logical keyboard
    Parameters - KbdHandle:W

    @KbdFreeFocus - Frees the logical-to-physical bond created by KbdGetFocus
    Parameters - KbdHandle:W

    @KbdGetFocus - Binds the logical keyboard to the physical keyboard
    Parameters - IOWait:W, KbdHandle:W

    @KbdSynch - Synchronizes access to the keyboard subsystem
    Parameters - IOWait:W

    @KbdXlate - Translates a scan code and its shift states into an ASCII code
    Parameters - XlateRecord:PS, KbdHandle:W
    Structure - KBDTRANSLATE

    @KbdSetCustXt - Installs a custom translate table for the logical keyboard
    Parameters - CodePage:PW, KbdHandle:W


 64. MASM 5.10 OS2.DOC: OS/2 Call Summary - Mouse Input

 Product Version(s): 5.10   | 5.10
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified: 26-MAY-1988    ArticleIdent: Q30820

    The following information is from the Microsoft Macro Assembler
 Version 5.10 OS2.DOC file.

 OS/2 Call Summary
 Mouse input constant - INCL_MOU

    @MouRegister - Registers a mouse subsystem or environment manager
    Parameters - ModuleName:PZ, EntryName:PZ, Mask:D

    @MouDeRegister - Deregisters a mouse subsystem or environment manager
    Parameters - None

    @MouFlushQue - Flushes the mouse event queue
    Parameters - DeviceHandle:W

    @MouGetHotKey - Queries to determine which physical key (button) is the
                    system hot key
    Parameters - ButtonMask:PW, DeviceHandle:W

    @MouSetHotKey - Tells the mouse driver which physical key (button) is
                    the system hot key
    Parameters - ButtonMask:PW, DeviceHandle:W

    @MouGetPtrPos - Gets the coordinates (row and column) of the mouse pointer
    Parameters - PtrPos:PS, DeviceHandle:W
    Structure - PTRLOC

    @MouSetPtrPos - Sets new coordinates for the mouse pointer image
    Parameters - PtrPos:PS, DeviceHandle:W
    Structure - PTRLOC

    @MouSetPtrShape - Sets the shape and size for the mouse pointer image
    Parameters - PtrBuffer:PB, PtrDefRec:PS, DeviceHandle:W
    Structure - PTRSHAPE

    @MouGetPtrShape - Copies the pointer shape for the screen group
    Parameters - PtrBuffer:PB, PtrDefRec:PS, DeviceHandle:W
    Structure - PTRSHAPE

    @MouGetDevStatus - Returns the status flags for the mouse device driver
    Parameters - DeviceStatus:PW, DeviceHandle:W

    @MouGetNumButtons - Returns the number of buttons
    Parameters - NumberOfButtons:PW, DeviceHandle:W

    @MouGetNumMickeys - Returns the number of mickeys per centimeter
    Parameters - NumberOfMickeys:PW, DeviceHandle:W

    @MouReadEventQue - Reads an event from the pointing device event queue
                       into the mouse event queue
    Parameters - Event:PS, NoWait:PW, DeviceHandle:W
    Structure - MOUEVENTINFO

    @MouGetNumQueEl - Returns the status for the event queue
    Parameters - QueDataRecord:PS, DeviceHandle:W
    Structure - MOUQUEINFO

    @MouGetEventMask - Returns an event mask for the current pointing device
    Parameters - EventMask:PW, DeviceHandle:W

    @MouSetEventMask - Assigns a new event mask to the current pointing device
    Parameters - EventMask:PW, DeviceHandle:W

    @MouGetScaleFact - Gets scaling factors for the current pointing device
    Parameters - ScaleStruct:PS, DeviceHandle:W
    Structure - SCALEFACT

    @MouSetScaleFact - Assigns scaling factors for the current pointing device
    Parameters - ScaleStruct:PS, DeviceHandle:W
    Structure - SCALEFACT

    @MouOpen - Opens the mouse device for the current screen group
    Parameters - DriverName:PZ, DeviceHandle:PW

    @MouClose - Closes the mouse device for the current screen group
    Parameters - DeviceHandle:W

    @MouRemovePtr - Notifies the mouse device driver that a specified area is
                    for the exclusive use of the application
    Parameters - PtrArea:PS, DeviceHandle:W
    Structure - NOPTRRECT

    @MouDrawPtr - Releases an area previously restricted to the pointer
                  image for use by the mouse device driver
    Parameters - DeviceHandle:W

    @MouSetDevStatus - Sets the pointing device driver status flags
    Parameters - DeviceStatus:PW, DeviceHandle:W

    @MouInitReal - Initializes the real-mode mouse device driver
    Parameters - DriverName:PZ


 65. MASM 5.10 OS2.DOC: OS/2 Call Summary - Video Output

 Product Version(s): 5.10   | 5.10
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified: 26-MAY-1988    ArticleIdent: Q30821

    The following information is from the Microsoft Macro Assembler
 Version 5.10 OS2.DOC file.

 OS/2 Call Summary
 Video output constant - INCL_VIO

    @VioRegister - Registers a video subsystem within a screen group
    Parameters - ModuleName:PZ, EntryPoint:PZ, FunctionMask1:D, FunctionMask2:

    @VioDeRegister - Deregisters a previously registered video subsystem
    Parameters - None

    @VioGetBuf - Returns the address of the logical video buffer
    Parameters - LVBPtr:PD, Length:PW, VioHandle:W

    @VioGetCurPos - Returns the cursor position
    Parameters - Row:PW, Column:PW, VioHandle:W

    @VioSetCurPos - Sets the cursor position
    Parameters - Row:W, Column:W, VioHandle:W

    @VioGetCurType - Returns the cursor type
    Parameters - CursorData:PS, VioHandle:W
    Structure - VIOCURSORINFO

    @VioSetCurType - Sets the cursor type
    Parameters - CursorData:PS, VioHandle:W
    Structure - VIOCURSORINFO

    @VioGetMode - Returns display mode information
    Parameters - ModeData:PS, VioHandle:W
    Structure - VIOMODEINFO

    @VioSetMode - Sets the display mode
    Parameters - ModeData:PS, VioHandle:W
    Structure - VIOMODEINFO

    @VioGetPhysBuf - Returns the address of the physical video buffer
    Parameters - Structure:PS, Reserved:W
    Structure - VIOPHYSBUF

    @VioReadCellStr - Reads a string of character-attributes (cells)
                      from screen
    Parameters - CellStr:PW, Length:PW, Row:W, Column:W, VioHandle:W

    @VioReadCharStr - Reads a string of characters from screen
    Parameters - CharStr:PB, Length:PW, Row:W, Column:W, VioHandle:W

    @VioWrtCellStr - Writes a string of character-attributes (cells) to
                     screen
    Parameters - CellStr:PB, Length:W, Row:W, Column:W, VioHandle:W

    @VioWrtCharStr - Writes a string of characters to screen
    Parameters - CharStr:PB, Length:W, Row:W, Column:W, VioHandle:W

    @VioScrollDn - Scrolls the current screen down
    Parameters - TopRow:W, LeftCol:W, BotRow:W, RightCol:W, Lines:W
                 Cell:PW, VioHandle:W

    @VioScrollUp - Scrolls the current screen up
    Parameters - TopRow:W, LeftCol:W, BotRow:W, RightCol:W, Lines:W
                 Cell:PW, VioHandle:W

    @VioScrollLf - Scrolls the current screen left
    Parameters - TopRow:W, LeftCol:W, BotRow:W, RightCol:W, Lines:W
                 Cell:PW, VioHandle:W

    @VioScrollRt - Scrolls the current screen right
    Parameters - TopRow:W, LeftCol:W, BotRow:W, RightCol:W, Lines:W
                 Cell:PW, VioHandle:W

    @VioWrtNAttr - Writes an attribute to the screen a specified number of
                   times
    Parameters - Attr:PB, Times:W, Row:w, Column:W, VioHandle:W

    @VioWrtNCell - Writes a character-attribute (cell) to the screen
                   a specified number of times
    Parameters - Cell:PW, Times:W, Row:w, Column:W, VioHandle:W

    @VioWrtNChar - Writes a character to the screen a specified number of
                   times
    Parameters - Char:PB, Times:W, Row:w, Column:W, VioHandle:W

    @VioWrtTTy - Writes a character string from the current cursor position
    Parameters - CharString:PB, Length:W, VioHandle:W

    @VioWrtCharStrAtt - Writes a string of characters with a repeated
                        attribute to screen
    Parameters - CharStr:PB, Length:W, Row:W, Column:W, Attr:PB, VioHandle:W

    @VioShowBuf - Updates the physical display with the logical video buffer
    Parameters - Offset:W, Length:W, VioHandle:W

    @VioSetAnsi - Activates or deactivates ANSI support
    Parameters - Indicator:W, VioHandle:W

    @VioGetAnsi - Returns the current ANSI state (on or off)
    Parameters - Indicator:PW, VioHandle:W

    @VioPrtSc - Copies the contents of the screen to the printer
    Parameters - VioHandle:W

    @VioPrtScToggle - Toggles whether session manager input is sent to printer
    Parameters - VioHandle:W

    @VioSavRedrawWait - Notifies a process that it must save or redraw
                        its screen
    Parameters - SavRedrawIndic:W, NotifyType:PW, VioHandle:W

    @VioSavRedrawUndo - Cancels a VioSavRedrawWait issued by another thread
                        within the same process
    Parameters - OwnerIndic:W, KillIndic:W, VioHandle:W

    @VioModeWait - Notifies a graphics application that it must restore its
                   video mode
    Parameters - RequestType:W, NotifyType:PW, Reserved:W

    @VioModeUndo - Enables one thread within a process to cancel a VioModeWait
                   issued by another thread in the same process
    Parameters - OwnerIndic:W, KillIndic:W, Reserved:W

    @VioScrLock - Locks the screen for I/O
    Parameters - WaitFlag:W, Status:PB, VioHandle:W

    @VioScrUnLock - Unlocks the screen for I/O
    Parameters - VioHandle:W

    @VioPopUp - Requests a temporary screen to display a message
    Parameters - WaitFlags:PW, VioHandle:W

    @VioEndPopUp - Releases a temporary screen obtained from a previous
                   VioPopUp
    Parameters - VioHandle:W

    @VioGetConfig - Returns the configuration of the video display
    Parameters - Reserved:W, ConfigData:PS, VioHandle:W
    Structure - VIOCONFIGINFO

    @VioGetFont - Returns either the font table of the specified size, or the
                  font currently in use
    Parameters - RequestBlock:PS, VioHandle:W
    Structure - VIOFONTINFO

    @VioSetFont - Downloads a display font
    Parameters - RequestBlock:PS, VioHandle:W
    Structure - VIOFONTINFO

    @VioGetCp - Returns the code page being used by the specified handle
    Parameters - Reserved:W, CodePageID:PW, VioHandle:W

    @VioSetCp - Sets the code page to be used by the specified handle
    Parameters - Reserved:W, CodePageID:W, VioHandle:W

    @VioGetState - Returns the current setting of either the palette registers
                   overscan (border) color, or blink/background intensity
                   switch
    Parameters - RequestBlock:PS, VioHandle:W
    Structures - VIOPALSTATE, VIOOVERSCAN, or VIOINTENSITY

    @VioSetState - Sets either the palette registers, overscan (border) color,
                   or blink/background intensity switch
    Parameters - RequestBlock:PS, VioHandle:W
    Structures - VIOPALSTATE, VIOOVERSCAN, or VIOINTENSITY


 66. Accessing MASM Structure Fields in a Multimodule Program

 Product Version(s): 5.00 5.10
 Operating System:   MS-DOS
 Flags: ENDUSER |
 Last Modified: 12-JAN-1989    ArticleIdent: Q30887

 To use a structure, defined in one module with the STRUC operator, in
 another module with the Macro Assembler, you must take into account
 the fact that the structure definition must be available to both
 modules at assemble time. The ".structfield" operator can than be used
 on any label.

 The following program demonstrates the use of a structure in a
 two-module program.

 ; Source file 1:

 EXTRN changecow:NEAR                ; Near function call

 animals    STRUC                    ; Structure definition
     cat    db    "catfield      "
     dog    db    "dogfield      "   ; Field widths of 15 characters
     cow    db    "cowfield      "
 animals    ENDS

 .MODEL small

 .DATA
            PUBLIC zoo
 zoo        animals   <"felix","spot","Holstein">  ; Initialize fields

 .CODE
 main:      mov ax, @data            ; Make data addressable
            mov ds,ax
            mov es,ax                ; For string moves

            call changecow           ; Change "Holstein" to "Daisy"
            retf
            END main

 ; Source file 2:
 ;    In source file 2, structure definition must be available for the
 ; field offsets. (Normally it would be placed in an include file,
 ; then the INCLUDE operator would be used; however, for sake of
 ; clarity, the structure definition has been placed in both files).
 ;    The structure information must be included here to correctly
 ; associate the fields with the offset. The structure name does not
 ; need to be "animals"; however, the structure fields should
 ; correspond.

 animals    STRUC                    ; Structure definition
     cat    db    "catfield      "
     dog    db    "dogfield      "   ; Field widths of 15 characters
     cow    db    "cowfield      "
 animals    ENDS

 .MODEL small

 .DATA
 EXTRN zoo:NEAR                       ; Let assembler know about zoo
 newcow    db     "Daisy         "    ; Replace cow with new name
 lenname   EQU    $ - newcow          ; Length of new name

 .CODE
           PUBLIC changecow           ; Changes cow field to "Daisy"
 changecow PROC
           mov     di, offset zoo.cow ; es:di should now point to destination
           mov     si, offset newcow  ; ds:si should now point to the source
           mov     cx, lenname        ; Length of new string
           rep     movsb              ; Do replacement
           ret
 changecow ENDP
           END


 67. MASM 5.10 RUNME.EXE Does Not Set Up for a Two-Floppy System

 Product Version(s): 5.10   | 5.10
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified: 12-JAN-1989    ArticleIdent: Q31000

    The RUNME.EXE on the MASM 5.10 distribution disk labeled "MS OS/2
 and MS-DOS Macro Assemblers" is only for a hard-disk installation; it
 will not set up the product on a two-floppy system.
    The programmer's guide, Page 9, describes a disk configuration that
 is suggested for a two-floppy system. Copy the files by hand to
 working disks.


 68. KBDINFO Incorrectly Defined

 Product Version(s): 5.10
 Operating System:   MS-DOS
 Flags: ENDUSER |
 Last Modified: 12-JAN-1989    ArticleIdent: Q30898

    The KBDINFO structure found in BSESUB.H is incorrectly defined, as
 follows:

                 KBDINFO struc
                         kbxl_cb                 db ?
                         kbxl_fsMask             db ?
                         kbxl_chTurnAround       db ?
                         kbxl_fdInterim          db ?
                         kbxl_fsState            dw ?
                 KBDINFO ends

    The members of the structure should all be declared as words (dw)
 rather than bytes.



 69. MASM 5.10 EXT.DOC: Overview

 Product Version(s): 5.10   | 5.10
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified: 12-JAN-1989    ArticleIdent: Q31515

    The following information is from the MASM Version 5.10 EXT.DOC
 file.

 /*
 EXT.DOC
    This file documents each of the low-level editing functions that
 can be called from a Microsoft-Editor C extension.
    The types COL and LINE, formally declared in the file EXT.H, are
 short and long integers, respectively. A variable of type COL refers
 to a column in a file, and a variable of type LINE refers to a line
 (in other words, a row) in a file. Numbering for both COL and LINE
 variables begins with 0. Therefore, line 0 is the first line in the
 file.
 */


 70. MASM 5.10 EXT.DOC: Replace - Edits Character in File

 Product Version(s): 5.10   | 5.10
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified: 12-JAN-1989    ArticleIdent: Q31516

    The following information is from the MASM Version 5.10 EXT.DOC
 file.
    Please note that numbering for both COL and LINE variables begins
 with 0.

 /*  Replace - edits a character in a file
  *
  * The Replace function inserts character c at position (x, y)
  * in the file pFile. If fInsert equals TRUE (-1) the function
  * moves remaining characters on the line over by one space. If
  * fInsert equals FALSE (0) function replaces the character at
  * specified position. The function takes no action if fInsert
  * equals FALSE, and c is identical to the character at specified
  * position.
  *
  *  c           Character to place into the file
  *  x, y        Column and row (respectively) of position of insertion
  *  pFile       Handle to file being modified
  *  fInsert     If TRUE (-1), inserts before character at specified
  *              position; otherwise, overwrites character at specified
  *              position
  *
  *  returns     TRUE if line is successfully edited, FALSE if line is too
  *              long
  */
 flagType pascal Replace (c, x, y, pFile, fInsert)
 char c;
 COL  x;
 LINE y;
 PFILE pFile;
 flagType fInsert;


 71. MASM 5.10 EXT.DOC: Movecur: Moves Cursor to Specified Location

 Product Version(s): 5.10   | 5.10
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified: 12-JAN-1989    ArticleIdent: Q31517

    The following information is from the MASM Version 5.10 EXT.DOC
 file.
    Please note that numbering for both COL and LINE variables begins
 with 0.

 /* MoveCur - moves the cursor to a specified location in the current
  * file. The MoveCur function moves the cursor to specified position
  * within the current file. If the cursor is within the same window,
  * then no window movement occurs. Otherwise, the cursor is placed at
  * a common position specified by the numeric switch "hike."
  *
  *  x           Column where cursor is to appear in file
  *  y           Line (row) where cursor is to appear in file
  */
 void pascal MoveCur (x, y)
 COL  x;
 LINE y;


 72. MASM 5.10 EXT.DOC: DelLine - Deletes Lines from a File

 Product Version(s): 5.10   | 5.10
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified: 12-JAN-1989    ArticleIdent: Q31518

    The following information is from the MASM Version 5.10 EXT.DOC
 file.
    Please note that numbering for both COL and LINE variables begins
 with 0.

 /*  DelLine - deletes lines from a file
  *
  *  The DelLine function deletes lines yStart through yEnd, inclusive,
  * in the file pFile.
  *
  *  pfile       Handle to file from which lines are to be deleted
  *  yStart      First line to be deleted
  *  yEnd        Last line to be deleted
  */
 void pascal DelLine (pfile, yStart, yEnd)
 PFILE pfile;
 LINE yStart, yEnd;


 73. MASM 5.10 EXT.DOC: DelBox - Deletes a "Box" from a File

 Product Version(s): 5.10   | 5.10
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified: 12-JAN-1989    ArticleIdent: Q31519

    The following information is from the MASM Version 5.10 EXT.DOC
 file.
    Please note that numbering for both COL and LINE variables begins
 with 0.

 /*  DelBox - deletes a rectangular area (box) from a file
  *
  *  The DelBox function deletes all spaces in the box delimited
  *  by the positions (xLeft, yTop) and (xRight, yBottom). The
  *  box includes both corners specified in the function call.
  *
  *  pFile               Handle to file to be modified
  *  xLeft, yTop         Column and line of start of box
  *  xRight, yBottom     Column and line of end of box
  */
 void pascal DelBox (pFile, xLeft, yTop, xRight, yBottom)
 PFILE pFile;
 COL  xLeft, xRight;
 LINE yTop, yBottom;


 74. MASM 5.10 EXT.DOC: DelStream - Deletes Text Stream from File

 Product Version(s): 5.10   | 5.10
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified: 12-JAN-1989    ArticleIdent: Q31520

    The following information is from the MASM Version 5.10 EXT.DOC
 file.
    Please note that numbering for both COL and LINE variables begins
 with 0.

 /*  DelStream - deletes a stream of text from a file
  *
  *  The DelStream function deletes the stream of text beginning with
  *  position (xStart, yStart), up to but not including position
  *  (xEnd, yEnd), within file pFile.
  *
  *  pFile               Handle to file to be modified
  *  xStart, yStart      Column and line of start of stream
  *  xEnd, yEnd          Column and line of end of stream
  */
 void pascal DelStream (pFile, xStart, yStart, xEnd, yEnd)
 PFILE pFile;
 COL  xStart, xEnd;
 LINE yStart, yEnd;


 75. MASM 5.10 EXT.DOC: GetLine - Retrieves Line of Text

 Product Version(s): 5.10   | 5.10
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified: 12-JAN-1989    ArticleIdent: Q31521

    The following information is from the MASM Version 5.10 EXT.DOC
 file.
    Please note that numbering for both COL and LINE variables begins
 with 0.

 /*  GetLine - retrieves a line of text
  *
  *  The GetLine function retrieves a line of text from the specified
  *  file and places the text in the specified buffer. The text has
  *  all tabs expanded into spaces, and no carriage-return or line-feed
  *  character is included. Lines requested beyond the end of the file
  *  are considered empty.
  *
  *  line        Number of the line to be retrieved
  *  buf         Buffer for text of the line
  *  pfile       Handle of file from which the line is to be retrieved
  *
  *  returns     The number of characters retrieved
  */
 int pascal GetLine (line, buf, pfile)
 LINE line;
 char far *buf;
 PFILE pfile;


 76. MASM 5.10 EXT.DOC: AddFile - Creates File Buffer

 Product Version(s): 5.10   | 5.10
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified: 12-JAN-1989    ArticleIdent: Q31522

    The following information is from the MASM Version 5.10 EXT.DOC
 file.
    Please note that numbering for both COL and LINE variables begins
 with 0.

 /*  AddFile - creates a file buffer
  *
  *  The AddFile function creates and initializes a file buffer. The
  *  contents are initially empty. A new file is not placed on disk
  *  until the FileWrite function is called.
  *
  *  p           Character pointer to name
  *
  *  returns     Handle to internal file structure
  */
 PFILE pascal AddFile (p)
 char far *p;


 77. MASM 5.10 EXT.DOC: DelFile - Deletes Contents of File

 Product Version(s): 5.10   | 5.10
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified: 12-JAN-1989    ArticleIdent: Q31523

    The following information is from the MASM Version 5.10 EXT.DOC
 file.
    Please note that numbering for both COL and LINE variables begins
 with 0.

 /*  DelFile - deletes contents of file
  *
  *  The DelFile function deletes the entire contents of an internal
  *  file buffer. The effect of deleting contents can be made
  *  permanent by calling the FileWrite function, which replaces the
  *  contents of the file on disk with the contents of the internal
  *  file buffer.
  *
  *  pFile       Handle to file that is to be cleared
  */
 void pascal DelFile (pFile)
 PFILE pFile;


 78. MASM 5.10 EXT.DOC: FileNameToHandle - Returns Handle

 Product Version(s): 5.10   | 5.10
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified: 12-JAN-1989    ArticleIdent: Q31524

    The following information is from the MASM Version 5.10 EXT.DOC
 file.
    Please note that numbering for both COL and LINE variables begins
 with 0.

 /*  FileNameToHandle - returns handle corresponding to the file name
  *
  *  The FileNameToHandle function searches for the specified file
  *  and returns a handle to the file if found. If pName points to a
  *  zero-length string, then the function returns a handle to the
  *  current file. Otherwise, the function searches for the file named by
  *  pName which may include a complete path. If pName not found and
  *  pShortName is not a NULL pointer, then the function scans the information
  *  file for a file name that matches pShortName. If a match is found,
  *  then the function uses the complete path name in the information file.
  *
  *  pName       Pointer to name of file
  *  pShortName  Pointer to short name of file (this parameter may be NULL)
  *
  *  Returns     Handle to specified file (if found) or NULL.
  */
 PFILE pascal FileNameToHandle (pName, pShortName)
 char far *pName, *pShortName;


 79. MASM 5.10 EXT.DOC: CopyStream - Copies Stream of Text

 Product Version(s): 5.10   | 5.10
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified: 12-JAN-1989    ArticleIdent: Q31525

    The following information is from the MASM Version 5.10 EXT.DOC
 file.
    Please note that numbering for both COL and LINE variables begins
 with 0.

 /*  CopyStream - copies a stream of text
  *
  *  The CopyStream function copies the stream of text (including
  *  newlines) beginning at position (xStart, yStart), up to but not
  *  including position (xEnd, yEnd). The stream of text is inserted
  *  into the destination file just before position (xDst, yDst). If the
  *  source-file handle is NULL, a blank space is inserted.
  *
  *  pFileSrc            Source file handle
  *  pFileDst            Destination file handle
  *  xStart, yStart      Column and line of beginning of copy
  *  xEnd, yEnd          Column and line of end of copy
  *  xDst, yDst          Column and line of destination of copy
  */
 void pascal CopyStream (pFileSrc, pFileDst, xStart, yStart, xEnd, yEnd,
 xDst, yDst)
 PFILE pFileSrc, pFileDst;
 COL  xStart, xEnd, xDst;
 LINE yStart, yEnd, yDst;


 80. MASM 5.10 EXT.DOC: PFileToTop - Makes File Visible in Window

 Product Version(s): 5.10   | 5.10
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified: 12-JAN-1989    ArticleIdent: Q31526

    The following information is from the MASM Version 5.10 EXT.DOC
 file.
    Please note that numbering for both COL and LINE variables begins
 with 0.

 /*  pFileToTop - makes the specified file visible in the current
  *  window
  *  In effect, the pFileToTop function selects a file as the current
  *  file and makes it visible in the current window. The function
  *  accomplishes this operation by moving the specified file handle to
  *  the top of the "stack" of file handles attached to the current
  *  window.
  *
  *  pFileTmp    Handle of file to bring to top of stack
  */
 void pascal pFileToTop (pFileTmp)
 PFILE pFileTmp;


 81. MASM 5.10 EXT.DOC: FileRead - Reads File Contents into Buffer

 Product Version(s): 5.10   | 5.10
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified: 12-JAN-1989    ArticleIdent: Q31527

    The following information is from the MASM Version 5.10 EXT.DOC
 file.
    Please note that numbering for both COL and LINE variables begins
 with 0.

 /*  FileRead - reads the contents of a file into the file buffer
  *
  *  The FileRead function reads the contents of the specified disk
  *  file and stores them in the internal file buffer specified by pFile.
  *  The old contents of the file buffer are lost.
  *
  *  name        Pointer to name of file to be read
  *  pFile       Handle to internal file to receive contents
  *
  *  returns     TRUE (-1) if successful; FALSE (0) if file could not
  *  be read
  */
 flagType pascal FileRead (name, pFile)
 char far *name;
 PFILE pFile;


 82. MASM 5.10 EXT.DOC: FileWrite - Writes Buffer Contents to Disk

 Product Version(s): 5.10   | 5.10
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified: 12-JAN-1989    ArticleIdent: Q31528

    The following information is from the MASM Version 5.10 EXT.DOC
 file.
    Please note that numbering for both COL and LINE variables begins
 with 0.

 /*  FileWrite - writes buffer contents out to disk
  *
  *  The FileWrite function writes the contents of the specified file
  *  buffer out to the disk file specified by savename. If savename is a
  *  NULL pointer, then the function writes the file buffer out to the disk
  *  file with the same name. The FileWrite function first writes contents
  *  to a temporary file; if the write operation is successful, then the
  *  temporary file is renamed to the destination file.
  *
  *  savename    Pointer to name of file to be overwritten
  *  pFile       Handle to file buffer to write
  */
 flagType pascal FileWrite (savename, pFile)
 char far *savename;
 PFILE pFile;


 83. MASM 5.10 EXT.DOC: DoMessage - Outputs String on Dialog Line

 Product Version(s): 5.10   | 5.10
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified: 12-JAN-1989    ArticleIdent: Q31529

    The following information is from the MASM Version 5.10 EXT.DOC
 file.
    Please note that numbering for both COL and LINE variables begins
 with 0.

 /*  DoMessage - outputs a string on the dialog line
  *
  *  The DoMessage function prints the specified string on the dialog
  *  line.
  *
  *  pStr        Pointer to character string to print
  *
  *  returns     Number of characters written
  *
  */
 int pascal DoMessage (pStr)
 char far * pStr;


 84. MASM 5.10 EXT.DOC: PutLine - Places Line of Text in File

 Product Version(s): 5.10   | 5.10
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified: 12-JAN-1989    ArticleIdent: Q31530

    The following information is from the MASM Version 5.10 EXT.DOC
 file.
    Please note that numbering for both COL and LINE variables begins
 with 0.

 /*  PutLine - places a line of text into a file
  *
  *  The PutLine function places the indicated buffer string into
  *  the specified file, replacing an existing line. If the specified
  *  line is out of range, then the PutLine function enlarges the
  *  file, and inserts as many blank lines as needed at the end of
  *  the file. The buffer line should have no carriage return or line
  *  feed; the PutLine function adds a newline automatically.
  *
  *  line        Number of line to be replaced
  *  buf         Buffer with line of text to be placed in file
  *  pfile       Handle to file
  */
 void pascal PutLine (line, buf, pfile)
 LINE line;
 char far *buf;
 PFILE pfile;


 85. MASM 5.10 EXT.DOC: FileLength - Returns Number of Lines in Fil

 Product Version(s): 5.10   |
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified: 12-JAN-1989    ArticleIdent: Q31531

    The following information is from the MASM Version 5.10 EXT.DOC
 file.
    Please note that numbering for both COL and LINE variables begins
 with 0.

 /*  FileLength - returns the number of lines in the file
  *
  *  The FileLength function is particularly useful for global
  *  operations, in which it is necessary to know where the end of the
  *  file is.
  *
  *  pFile       Handle to file
  *
  *  returns     Number of lines in file
  */
 LINE pascal FileLength (pFile)
 PFILE pFile;


 86. MASM 5.10 EXT.DOC: GetCursor - Returns Current Cursor Position

 Product Version(s): 5.10   | 5.10
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified: 12-JAN-1989    ArticleIdent: Q31532

    The following information is from the MASM Version 5.10 EXT.DOC
 file.
    Please note that numbering for both COL and LINE variables begins
 with 0.

 /*  GetCursor - returns the current cursor position
  *
  *  The GetCursor function indicates current cursor position by
  *  modifying the integers that px and py point to. The function
  *  sets *px to the current cursor column, and *py to the current
  *  cursor line.
  *
  *  px          Pointer to column-position variable
  *  py          Pointer to line-position variable
  */
 void pascal GetCursor (px, py);
 COL  far *px;
 LINE far *py;


 87. MASM 5.10 EXT.DOC: ReadCmd - Returns Next Command from User

 Product Version(s): 5.10   | 5.10
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified: 12-JAN-1989    ArticleIdent: Q31533

    The following information is from the MASM Version 5.10 EXT.DOC
 file.
    Please note that numbering for both COL and LINE variables begins
 with 0.

 /*  ReadCmd  - returns next command from user
  *
  *  The ReadCmd waits for input from the user. The next keystroke is
  *  translated into a function that is not executed. Instead, the
  *  editor passes information about the function in the form of a
  *  structure of type cmdDesc. This structure is declared in the file
  *  EXT.H and is described in Chapter 8 of the Microsoft Editor
  *  User's Guide. Once intercepted, the keystroke cannot be placed
  *  back for execution.
  *
  *  returns  Pointer to cmdDesc structure corresponding to next keystroke
  */
 PCMD pascal ReadCmd ();


 88. MASM 5.10 EXT.DOC: ReadChar - Returns Next Raw Keystroke

 Product Version(s): 5.10   | 5.10
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified: 12-JAN-1989    ArticleIdent: Q31534

    The following information is from the MASM Version 5.10 EXT.DOC
 file.
    Please note that numbering for both COL and LINE variables begins
 with 0.

 /*  ReadChar - returns next raw keystroke
  *
  *  The ReadChar intercepts the next keystroke from the user. No action
  *  is taken, but information about the keystroke is passed. Once
  *  intercepted, the keystroke cannot be placed back for execution.
  *
  *  returns     a long value containing information on the keystroke:
  *
  *              byte 0: ASCII code for character
  *              byte 1: scan code for character
  *              byte 2: shift info for character:
  *                          (S)HIFT, (C)TRL, (A)LT, (N)UMLOCK
  *                          Format is: SxCAxNxx
  *              byte 3: 0
  *
  *  In the format for byte 2, each "x" indicates an unused bit. The
  *  bits S, C, A, and N are each on or off, depending on the associated
  *  condition. For example, if the SHIFT, CTRL, and ALT conditions are
  *  all on, but not the NUMLOCK condition, then byte 2 will be returned as
  *  10110000. Note: the "N" bit is always 0, unless the the key pressed
  *  is on the numeric keypad.
  */
 long pascal ReadChar();


 89. MASM 5.10 EXT.DOC: KbUnHook - Disable M's Logical Keyboard

 Product Version(s): 5.10   | 5.10
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified: 12-JAN-1989    ArticleIdent: Q31535

    The following information is from the MASM Version 5.10 EXT.DOC
 file.
    Please note that numbering for both COL and LINE variables begins
 with 0.

 /*  KbUnHook - Disable Microsoft Editor's logical keyboard
  *
  *  The KbUnHook function changes the "focus" of the keyboard so that
  *  keyboard input is no longer read by the editor. When attempting to
  *  use system-level calls to read from the keyboard, it is necessary to
  *  first call this function.
  *
  *  In particular, it is necessary to call the KbUnHook function before
  *  transferring control to a program that reads from the keyboard.
  */
 void pascal KbUnHook();


 90. MASM 5.10 EXT.DOC: KbHook - Enable M's Logical Keyboard

 Product Version(s): 5.10   | 5.10
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified: 12-JAN-1989    ArticleIdent: Q31536

    The following information is from the MASM Version 5.10 EXT.DOC
 file.
    Please note that numbering for both COL and LINE variables begins
 with 0.

 /*  KbHook - Enable Microsoft Editor's logical keyboard
  *
  *  The KbHook function reverses the effect of the KbUnHook function
  *  (described above), and restores normal keyboard-input reading
  *  by the editor.
  */
 void pascal KbHook();


 91. MASM 5.10 EXT.DOC: CopyLine - Copies Lines from File to File

 Product Version(s): 5.10   | 5.10
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified: 12-JAN-1989    ArticleIdent: Q31537

    The following information is from the MASM Version 5.10 EXT.DOC
 file.
    Please note that numbering for both COL and LINE variables begins
 with 0.

 /*  CopyLine - copies lines from one file to another
  *
  *  The CopyLine function copies lines yStart through yEnd, inclusive,
  *  and inserts them into the destination file just before line yDst. If
  *  the handle to the source file is NULL, then the function inserts a
  *  blank line into the destination file (in that case, yStart and yEnd
  *  are ignored).
  *
  *  pFileSrc    Handle to source file
  *  pFileDst    Handle to destination file
  *  yStart      First line to be copied
  *  yEnd        Last line to be copied
  *  yDst        Destination of copy
  */
 void pascal CopyLine (pFileSrc, pFileDst, yStart, yEnd, yDst)
 PFILE pFileSrc, pFileDst;
 LINE yStart, yEnd, yDst;


 92. MASM 5.10 EXT.DOC: RemoveFile - Frees Attached File Resources

 Product Version(s): 5.10   | 5.10
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified: 12-JAN-1989    ArticleIdent: Q31538

    The following information is from the MASM Version 5.10 EXT.DOC
 file.
    Please note that numbering for both COL and LINE variables begins
 with 0.

 /*  RemoveFile - frees up all resources attached to a particular file
  *
  *  The RemoveFile function removes a file handle from memory, along
  *  with the file buffer and all other memory-resident information about
  *  the file. Calling this function helps to free up main memory, but it
  *  has no effect on the file as stored on disk.
  *
  *  pFileRem    File handle to be removed
  */
 flagType pascal RemoveFile (pFileRem)
 PFILE    pFileRem;


 93. MASM 5.10 EXT.DOC: CopyBox - Copies "Box" from File to File

 Product Version(s): 5.10   | 5.10
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified: 13-JUN-1988    ArticleIdent: Q31539

    The following information is from the MASM Version 5.10 EXT.DOC
 file.
    Please note that numbering for both COL and LINE variables begins
 with 0.

 /*  CopyBox - copies a rectangular area (box) from one file to another
  *
  * The CopyBox function copies the box delimited by positions
  * (xLeft, yTop) and (xRight, yBottom) in the source file and inserts
  * this box just before position (xDst, yDst) in the destination file.
  * If the the source-file handle is NULL, a blank space is inserted.
  * The box in the source file includes both corners specified in the
  * function call.
  *
  *  pFileSrc            Handle to source file
  *  pFileDst            Handle to destination file
  *  xLeft, yTop         Column and line of beginning of copy
  *  xRight, yBottom     Column and line of end of copy
  *  xDst, yDst          Column and line of destination of copy
  */
 void pascal CopyBox (pFileSrc, pFileDst, xLeft, yTop, xRight,
                      yBottom, xDst, yDst)
 PFILE pFileSrc, pFileDst;
 COL  xLeft, xRight, xDst;
 LINE yTop, yBottom, yDst;


 94. MASM 5.10 EXT.DOC: Display - Updates the Physical Display

 Product Version(s): 5.10   | 5.10
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified: 13-JUN-1988    ArticleIdent: Q31540

    The following information is from the MASM Version 5.10 EXT.DOC
 file.
    Please note that numbering for both COL and LINE variables begins
 with 0.

 /*  Display - updates the physical display
  *
  * The Display function refreshes the screen, by examining editing
  * changes and making the minimum screen changes necessary.  A
  * keystroke interrupts the function and causes immediate return.
  * You do not normally need to use the Display function to see the
  * results of an edit on the screen. The function is typically useful
  * when you have an SWI_SPECIAL function that alters a file directly.
  */
 void pascal Display ()


 95. MASM 5.10 EXT.DOC: SetKey - Associates Editor Function w/Key

 Product Version(s): 5.10   | 5.10
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified: 12-JAN-1989    ArticleIdent: Q31541

    The following information is from the MASM Version 5.10 EXT.DOC
 file.
    Please note that numbering for both COL and LINE variables begins
 with 0.

 /*  SetKey - associates an editor function with a keystroke
  *
  * The SetKey function creates a function assignment. Any current
  * assignment to the keystroke is discarded and each time that
  * particular keystroke is received, the corresponding editor function
  * will be invoked.
  *
  *  pFunction   Pointer to name of string being assigned
  *  pKey        Pointer to keystroke
  *
  *  returns     TRUE (-1) if a successful assignment was made; FALSE (0)
  *              otherwise
  */
 flagType pascal SetKey (pFunction, pKey)
 char far *pFunction, *pKey;


 96. MASM 5.10 EXT.DOC: BadArg - Displays "Bad Argument" Message

 Product Version(s): 5.10   | 5.10
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified: 13-JUN-1988    ArticleIdent: Q31542

    The following information is from the MASM Version 5.10 EXT.DOC
 file.
    Please note that numbering for both COL and LINE variables begins
 with 0.

 /*  BadArg - displays a message that a bad argument has been received
  *
  *  The "bad argument" message is printed on the dialog line.
  */
 flagType pascal BadArg (void);


 97. MASM 5.10 EXT.DOC: FExecute - Executes an MS-Editor Macro

 Product Version(s): 5.10   | 5.10
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified: 13-JUN-1988    ArticleIdent: Q31543

    The following information is from the MASM Version 5.10 EXT.DOC
 file.
    Please note that numbering for both COL and LINE variables begins
 with 0.

 /*  fExecute - executes a Microsoft-Editor macro
  *
  * The fExecute function executes a macro, using the standard rules
  * for macro execution (see the Microsoft Editor User's Guide for
  * details).
  *  pStr        Pointer to macro string to execute
  *
  *  returns     Return value of last executed macro
  */
 flagType pascal fExecute (pStr)
 char far *pStr;


 98. Sign-Extended Register and Immediate from of AND/OR/XOR

 Product Version(s): 5.00 5.10
 Operating System:   MS-DOS
 Flags: ENDUSER |
 Last Modified: 12-JAN-1989    ArticleIdent: Q31598

    The Microsoft Macro Assembler will generate sign-extended encodings
 whenever possible. The following are MASM instructions that will
 produce sign-extended encodings:

 Assembler           Sign-Extended               Nonsign-Extended
 Instructions        Encodings                   Encodings

 AND bx, 0ffffh      83 E3 FF                    81 E3 FFFF
 ADD bx, 0001h       83 C3 01                    81 C3 0001
 ADC bx, 0fh         83 D3 0F                    81 D3 000F
 OR  bx, 1           83 CB 01                    81 CB 0001
 SBB bx, 0ffffh      83 DB FF                    81 DB FFFF
 SUB bx, 3           83 EB 03                    81 EB 0003
 XOR bx, 0002h       83 F3 02                    81 F3 0002
 CMP bx, 0fff2h      83 FB F2                    81 FB FFF2

    MASM will choose the sign-extended version of the instruction
 because of the 1-byte savings in the encoding. The
 8088/8086/80186/80286 processors do support the sign-extended
 encoding, but documentation on this feature is limited. The support of
 sign-extended encoding is documented in the "8086/8088/80186/80188
 Programmer's Pocket Reference Guide" on Page 43.


 99. @data Group Override Produces Phase Error A2006

 Product Version(s): 5.10    | 5.10a
 Operating System:   MS-DOS  | OS/2
 Flags: ENDUSER | buglist5.10
 Last Modified: 12-NOV-1990    ArticleIdent: Q65244

 Page 91 of the "Microsoft Macro Assembler 5.1 Programmer's Guide"
 states that the @data text equate represents the group name.

 This implies that the code statement with the GROUP override

    mov ax, dgroup:[di]

 is equal to the following:

    mov ax, @data:[di]

 However, the code below generates the following error:

    A2006: phase error between passes

 The following is a sample code:

 .model small
 .code

 delta   proc

         mov   ax, @data:[di]

 delta   endp

         end

 Microsoft has confirmed this to be a problem in the Macro Assembler
 version 5.10a. We are researching this problem and will post new
 information here as it becomes available.


 100. .CONST Directive Creates a DATA Class Instead of a CONST Class

 Product Version(s): 5.10   | 5.10
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER | buglist5.10
 Last Modified: 20-JUL-1988    ArticleIdent: Q32684

    Page 93 of the "Microsoft Macro Assembler Programmer's Guide"
 states that the .CONST directive will produce a segment with CONST
 class; however, the .CONST directive will generate a segment with
 class DATA.
    Microsoft has confirmed this to be a problem in Version 5.10. We
 are researching this problem and will post new information as it
 becomes available.


 101. More Than 127 Segments Will Generate Bad Object Record

 Product Version(s): 5.10   | 5.10
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER | buglist5.10
 Last Modified: 15-JUL-1988    ArticleIdent: Q32686

    When a macro assembler program has more than 127 segments and
 it is compiled with the /Zd switch, an invalid object module is
 produced. The object module contains an invalid LINUM record caused
 by the segment index field.
    Microsoft has confirmed this to be a problem in Version 5.10. We
 are researching this problem and will post new information as it
 becomes available.



 102. Error Message A4100: Impure Memory Reference

 Product Version(s): 5.10   | 5.10
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER | buglist5.10
 Last Modified: 15-JUL-1988    ArticleIdent: Q32691

    MASM incorrectly generates the error message "A4100: Impure memory
 reference" on the following source code:

 .286
 CODE segment
      ASSUME cs:code
      var1   db    ?
      DIV    var1
 CODE ends

     The DIV instruction incorrectly generates the error message. This
 error occurs when the ".386" directive is used instead of the ".286"
 directive and the "dw" directive is used instead of the "db"
 directive. Also, if the ".386" directive is used with the "dd"
 directive, the DIV instruction will generate the error message again.
    Microsoft has confirmed this to be a problem in Version 5.10. We
 are researching this problem and will post new information as it
 becomes available.



 103. RUNME Program Looks for Drive A Only

 Product Version(s): 5.10   | 5.10
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER | buglist5.10
 Last Modified: 15-JUL-1988    ArticleIdent: Q32753

    The MASM setup program is called RUNME. During the setup process,
 the RUNME program will only look to Drive A for the setup files.
 Computers with only a Drive B cannot run the setup program.
    A workaround is to use the MS-DOS Assign command as follows:

    assign b=a

    Microsoft has confirmed this to be a problem in Version 5.10. We
 are researching this problem and will post new information as it
 becomes available.


 104. Forward Reference to Segment Name Gives Phase Error

 Product Version(s): 5.00  5.10 5.10A
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER | buglist5.10
 Last Modified: 10-JUL-1990    ArticleIdent: Q32762

    A forward reference to a segment name in MASM will incorrectly
 give a "A2006: Phase error between passes" error.
    Microsoft has confirmed this to be a problem in Version 5.10. We
 are researching this problem and will post new information as it
 becomes available.
    A workaround is to declare empty segments at the top of your MASM
 source code, defining all segments in the order needed.

    The following source example demonstrates the problem:

 CSEG segment para public 'CODE'
      assume CS:CSEG
 main proc near
      mov bx,seg sseg               ;will generate phase error
      ret
 main endp
 CSEG ends
 SSEG segment stack 'STACK'
      db 100h dup(?)
 SSEG ends
 end  main

    The above example would have the following empty segments declared
 at the top of the source file:

 CSEG segment para public 'CODE'
 CSEG ends
 SSEG segment stack 'STACK'
 SSEG ends

    Because the SSEG segment is declared before the MOV instruction
 is assembled, the phase error is eliminated. The CSEG segment
 is also declared to ensure that the ordering of the two segments
 is unchanged.
    For more information about ordering of segments, refer to the
 "Microsoft Macro Assembler Programmer's Guide" and the "Microsoft
 CodeView and Utilities Guide."



 105. Segments of Type COMMON Are Incorrectly Overlapped

 Product Version(s): 5.10   | 5.10
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER | buglist5.10
 Last Modified: 15-JUL-1988    ArticleIdent: Q32764

    Segments of type COMMON are combined instead of overlapped. MASM
 should not combine them; it should pass them through separately for the
 linker to handle.
    Microsoft has confirmed this to be a problem in Version 5.10. We
 are researching this problem and will post new information as it
 becomes available.



 106. LOCAL Directive Incorrect for Large Types

 Product Version(s): 5.10   | 5.10
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER | buglist5.10 | fixlist5.10A
 Last Modified: 10-JUL-1990    ArticleIdent: Q32773

    The LOCAL directive allocates two bytes too few when applied to
 data items with type larger than word.
    Microsoft has confirmed this to be a problem in Version 5.10.
 The 5.10A MASM update is available as an applications note, from
 Microsoft Product Support Services.

    The following source example demonstrates the problem:

 .model large
 .code
 foo    proc
        local l1:byte
        local l2:word
        local l4:dword
        local l6:fword
        local l8:qword
        local l10:tword
        ret
 foo    endp
 end

    The listing file below illustrates the incorrect offsets generated:

 L1 ........................ TEXT    BYTE PTR [BP]-2
 L10........................ TEXT    TBYTE PTR [BP]-24
 L2......................... TEXT    WORD PTR [BP]-4
 L4......................... TEXT    DWORD PTR [BP]-6
 L6......................... TEXT    FWORD PTR [BP]-10
 L8......................... TEXT    QWORD PTR [BP]-16



 107. Language Names Declared as PUBLIC Cause Error

 Product Version(s): 5.10   | 5.10
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER | buglist5.10
 Last Modified: 15-JUL-1988    ArticleIdent: Q32777

    Starting with Macro Assembler Version 5.10, language names cannot
 be declared PUBLIC. The language names affected are BASIC, C,
 FORTRAN, and PASCAL. The error message displayed does not correctly
 display the name of the offending label. The following example
 demonstrates the problem:

 .model small
 .data
 public c
 test.asm(17): error A2009:Symbol not defined:
 c  db  1
 end

    Note that the use of "c" as a variable is allowed. Microsoft has
 confirmed this to be a problem in Version 5.10. We are researching
 this problem and will post new information as it becomes available.



 108. Illegal Instruction under CodeView

 Product Version(s): 5.10   | 5.10
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER | buglist5.10
 Last Modified: 19-JUL-1988    ArticleIdent: Q32779

     When the following program is assembled with the /Zi switch,
 linked with the /CO switch, and traced under CodeView, an illegal
 instruction occurs:

 _text segment
 assume cs:_text
        db 08h,0c1h
 _text ends
 end

    Microsoft has confirmed this to be a problem in Version 5.10. We
 are researching this problem and will post new information as it
 becomes available.


 109. BSESUB.INC Contains Incorrect Declarations

 Product Version(s): 5.10   | 5.10
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER | buglist5.10
 Last Modified: 15-JUL-1988    ArticleIdent: Q32810

    In BSESUB.INC, the KBDINFO structure fields should all be declared
 with the DW directive; however, the fields are declared by the DB
 directive instead. Also, the fsShift field should be declared with DW
 directive instead of the DD directive.
    Microsoft has confirmed this to be a problem in Version 5.10. We
 are researching this problem and will post new information as it
 becomes available.



 110. Address-Size and Operand-Size Override Generated

 Product Version(s): 5.10   | 5.10
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER | buglist5.10
 Last Modified: 15-JUL-1988    ArticleIdent: Q32811

    MASM will generate both an address-size and operand-size override
 for a far call from a USE16 segment to a USE32 segment. Only the
 operand-size override is necessary.
    Microsoft has confirmed this to be a problem in Version 5.10. We
 are researching this problem and will post new information as it
 becomes available.

    The  following source code demonstrates the problem:

                         .386
                         s32 segment USE32
                             assume cs:@CurSeg
                             p   proc
                             p   endp
                         s32 ends
                         s16 segment USE16
                             assume cs:@CurSeg
 67|66|9A 00000000           call    far ptr p
                         s16 ends
                         end

    The opcodes generated for the Call instruction are shown at the
 left of the instruction. The address-size prefix is 67 and the
 operand-size prefix is 66.



 111. Literal Character Operator (!) in Text Equate

 Product Version(s): 5.10   | 5.10
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER | buglist5.10
 Last Modified: 15-JUL-1988    ArticleIdent: Q32812

   The literal character operator (!) does not allow a right angle
 bracket to be placed in a text equate. For example, the following
 line will cause an error:

     a     equ    < !> >

    The warning message A4001: "Extra characters on line" will be
 generated by the assembler.
    Microsoft has confirmed this to be a problem in Version 5.10. We
 are researching this problem and will post new information as it
 becomes available.


 112. New Command-Line Option /LA

 Product Version(s):
 Operating System:   5.10   | 5.10
 Flags: MS-DOS | OS/2
 Last Modified: 22-JUL-1988    ArticleIdent: Q32832
 ENDUSER |

    Version 5.10 of the Macro Assembler includes a new command-line
 option that shows all code generated by MASM.
    The command-line option /LA displays the results of the simplified
 segment directives and code generated by the high-level language
 support features. The following is a sample source file with simplified
 segment directives and a fragment of the listing file created by using
 /LA:

      .model small
      .data
      .code
      end

      .model small
      assume cs:@code,ds:@data,ss:@data
      .data
      _DATA segment 'DATA'
      .code
      @CurSeg ends
      _TEXT segment  'CODE'
      end
      @CurSeg ends


 113. Line-Continuation Character Added

 Product Version(s): 5.10   | 5.10
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified: 15-JUL-1988    ArticleIdent: Q32834

    The line-continuation character (\) has been added to the
 Microsoft Macro Assembler. A program line can now extend over
 more than one physical line.
    The backslash must be the last character in the line. Using the
 line-continuation character, you may have program lines up to 512
 characters. Physical lines are still limited to 128 characters.



 114. .TYPE Operator Has New Bit Settings

 Product Version(s): 5.10   | 5.10
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified: 15-JUL-1988    ArticleIdent: Q32836

    In previous versions of the Microsoft Macro Assembler, the .TYPE
 operator uses only bits 0, 1, 5, and 7. In MASM Versions 5.10, the use
 of bits 2, 3 and 4 has been added.
    The following is a chart of bit assignments:

     Bit Position        If Bit=0            If Bit=1

     0               Not program related     Program related
     1               Not data related        Data related
     2               Not a constant value    Constant value
     3               Addressing mode is not  Addressing mode is direct
                         direct
     4               Not a register          Expression is a register
     5               Not defined             Defined
     7               Local or public scope   External scope

     For more information on the .TYPE operator please refer to the
 "Microsoft Macro Assembler 5.10 Programmer's Guide."



 115. LOCAL Directive Requires Language Parameter

 Product Version(s): 5.10   | 5.10
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER | buglist5.10
 Last Modified: 15-JUL-1988    ArticleIdent: Q32858

    The LOCAL directive used inside a procedure requires a language
 parameter in the .MODEL directive. The warning A4001: "Extra characters
 on line" will be incorrectly generated by the assembler.
    The following is an example:

     .model small
     .code
     proc1 proc
     local x:dword
     proc1 endp
     end

    The statement "local x:dword" will generate the warning.
    The workaround for this problem is to specify a language parameter.
 To correct the program above, replace the statement ".model small"
 with ".model small,fortran".
    Microsoft has confirmed this to be a problem in Version 5.10. We
 are researching this problem and will post new information as it
 becomes available.


 116. Using /LA and .FARDATA? Generates Incorrect Listing File

 Product Version(s): 5.10   | 5.10
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER | buglist5.10
 Last Modified: 19-JUL-1988    ArticleIdent: Q32860

    The MASM command-line option /LA will show all code generated by
 the high-level-language features. When the .FARDATA? directive is
 used, the code generated in the listing file places the "@CurSeg ends"
 statement in the wrong place.
    Microsoft has confirmed this to be a problem in Version 5.10. We
 are researching this problem and will post new information as it
 becomes available.

    The following is an assembler source and listing file:

     .model small
     .fardata?
     .data
     end

     .model small
     assume cs:@code,ds:@data,ss:@data
     .fardata?
     FAR_BSS segment 'FAR_BSS'
     .data
     _DATA segment 'DATA'
     @CurSeg ends
     end
     @CurSeg ends

     first "@CurSeg ends" statement should be place before the _DATA
 segment is declared.



 117. Invalid Operation and Inexact Result in Control Word

 Product Version(s): 5.10   | 5.10
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified: 12-JAN-1989    ArticleIdent: Q32865

    A good source of information for the 80287 Control and Status Words
 is the INTEL 80286 and 80287 Programmer's Reference Manual.
    The article below gives a brief summary of the information found in
 the INTEL reference concerning the Invalid Operation and Inexact
 Result exceptions.

    When the 80287 processor attempts a numeric operation with invalid
 operands or produces a result that cannot be represented, the
 processor will check certain numeric exceptions. Among the exceptions
 checked are Invalid Operation and Inexact Result.
    The 80287 reports an Invalid Operation if any of the following
 occurs:

    An attempt to load a register that is not empty (stack overflow).
    An attempt to pop an operand from an empty register (stack underflow).
    An operand is a NaN.
    The operands cause the operation to be indeterminate (square root
    of negative number,0/0).

    If the result of an operation is not exactly representable in the
 destination format, the 80287 rounds the number and reports the
 precision exception. For example, the fraction 1/3 cannot be precisely
 represented in binary form.
    The 80287's system of real numbers may be closed by either two
 models of infinity. The two models are projective and affine closure.
 The default means of closure is projective.
    When projective closure is selected, the NPX treats the special
 values +infinity and -infinity as a single unsigned infinity. In the
 affine mode, the NPX respects the signs of infinity.
    While affine mode may provide more information than projective
 mode, there are occasions when the sign may represent misinformation.
 Projective mode, on the other hand, provides less information, but
 never returns misinformation.


 118. Comment Strings Should Not Overlap Onto the Next Line

 Product Version(s): 5.10   | 5.10
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER | docerr
 Last Modified: 12-JAN-1989    ArticleIdent: Q32882

    On Pages 22 and 23 of the "Microsoft Macro Assembler 5.1 Updates
 and Microsoft Editor" manual there is an example using various text
 macros called SaveRegs and RestRegs. In this example, there are
 comment strings that overlap onto the next line because of wrap
 around.
    Please note that this is wrap around from the comment, and not a
 new instruction.



 119. No Symbolic Information Generated for Procedure Labels

 Product Version(s): 5.10   | 5.10
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER | buglist5.10
 Last Modified: 22-JUL-1988    ArticleIdent: Q32885

    MASM does not generate an object-module record that allows a break
 point to be set at a procedure label under CodeView. The following
 code demonstrates this problem:

     .model compact
     .code
     routine proc
     mov ax,ax
     routine endp
     end

    The source code was assembled and linked as follows:

 masm /ZI file.asm;
 link /CO file;
 cv file

    In CodeView, entering "bp routine" gives the "Unknown symbol" error
 message.
    Microsoft has confirmed this to be a problem in Version 5.10. We
 are researching this problem and will post new information as it
 becomes available.



 120. Automatic Labels for Jump Instructions

 Product Version(s): 5.10   | 5.10
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER | jmp
 Last Modified: 22-JUL-1988    ArticleIdent: Q33067

    The Macro Assembler provides a way to generate automatic labels
 for jump instructions.
    To define the local label to be jumped to, use two at signs (@@)
 followed by a colon (:). The jump instruction's operand field can
 either use @B (back) or @F (forward). The @B will jump to the nearest
 preceding local label and the @F will jump to the nearest following
 label.
    The example below illustrates this feature:

     cmp ax,cx
     jge @F
     .
     .
     .
 @@:
     .
     .
     .
     jle @B

    The jump instruction @F will jump to @@: and the jump instruction @B
 will jump back to @@.
    Section 3.3 of the "Microsoft Macro Assembler 5.1 Updates and
 Microsoft Editor" manual discusses this new feature.


 121. Enhancements to Help Use Procedures in MASM

 Product Version(s): 5.10   | 5.10
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified: 12-JAN-1989    ArticleIdent: Q33359

    A series of enhancements were made in MASM Version 5.10 to make
 procedure definitions easier and more high-level-language compatible.
 These enhancements comprise the following:

    USES register-list
    Parameters
    LOCAL variables.

    The implementation of the parameters requires a language to be
 specified so the parameter order can be determined (for any procedures
 with two or more parameters). The other enhancements are not language
 specific.
    However, these features are intended as a package; therefore, the
 extended features are not recognized if no language is specified.


 122. Programmer's Guide FREE ST(num) Reference Is Incorrect

 Product Version(s): 5.00 5.10
 Operating System:   MS-DOS
 Flags: ENDUSER | docerr
 Last Modified: 12-JAN-1989    ArticleIdent: Q33382

    On Page 406 of the "Microsoft Macro Assembler Programmer's Guide,"
 the FREE ST(num) instruction is incorrectly stated. It should read
 FFREE ST(num).


 123. STOS Instruction Must Have String Pointed to ES:DI

 Product Version(s): 5.10   | 5.10
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified: 12-JAN-1989    ArticleIdent: Q34371

    The STOS instruction must have the string pointed to by ES:DI. The
 following command will not generate a warning that an attempt to
 override the DI register was made even though it will continue to
 expect the string to be pointed to by ES:DI:

    STOS  WORD PTR ES:[SI]



 124. Documentation Error on the LGDT Instruction

 Product Version(s): 5.10   | 5.10
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER | docerr
 Last Modified: 12-JAN-1989    ArticleIdent: Q34375

    The "Microsoft Macro Assembler 5.10 Reference Guide" states that
 the LGDT instruction only takes a memory 64 operand while the Intel
 manual states the LGDT instruction takes a memory 48 operand.
    The MASM Reference is incorrect. The correct operand size is memory
 48. These instructions load essentially a 2-field structure whose
 total size is 48 bits. The first two bytes are the limit field and the
 last four bytes are the base field. This can be defined using the DF
 directive, or by defining a structure as described.


 125. Function Pointers

 Product Version(s): 5.10   | 5.10
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified: 12-JAN-1989    ArticleIdent: Q34377

    The following sample program illustrates function pointers, C and
 MASM, from a MASM point of view.
    It takes the address of the function (in this example, the address
 is loaded into ES:DX) and moves it into a 4-byte variable; it then
 does a far call to that address.
    In this example it seems odd to call a function in this manner
 because the function is defined locally and its name in known;
 however, what if the name of the function was not known? What if you
 were programming a device driver and all that was know was the entry
 point of the function?
    Lets say the entry point was given in ES:DX. Using the following
 technique, a name could be given to the address of the function and
 the function could be called like any other function.

    The following sample program demonstrates this information:

 ;
 ;
 ;    NAME:  fptr.asm
 ;
 ;    This program illustrates how to implement a function pointer
 ;    in MACRO Assembler.
 ;
 ;    This technique is the same as the C compiler would generate
 ;    if you were to get an assembly listing of a C program that
 ;    contained a pointer to a function.
 ;
 ;
 dosseg
 .model small

 .data
      fptr dd 1 dup(?)   ; set aside four bytes for function address

 .code
 ;
 ;   MACRO Definitions
 ;
 FARCALL MACRO func_ptr
             call dword ptr func_ptr  ; call by 4-byte far function reference
         ENDM

 DosExit MACRO
              mov  ax, 4C00h    ; ah = 4Ch ( dos exit interrupt) al = 0
              int  21h
         ENDM
 ;
 ;   FUNCTION Definitions
 ;
      PUBLIC _ClrScr
 _ClrScr PROC FAR

      push bp          ; save bp
      mov  bp, sp      ; get sp
      push bx          ; save registers
      push cx
      push dx

      mov ax, 0700h    ;  ah = 7,  al = 0
      mov bx, 0700h    ;  bh = 7,  bl = 0
      xor cx, cx       ;  cx = 0
      mov dx, 184Fh    ;  dh = 24, dl = 79, decimal
      int 10h

      mov ax, 0200h    ; ah = 2, al = 0
      xor bx, bx       ; bx = 0
      xor dx, dx       ; dx = 0
      int 10h

      xor  ax, ax      ; function returns void

      pop  dx          ; restore registers
      pop  cx
      pop  bx

      mov  sp, bp      ; reset sp
      pop  bp          ; restore bp

      ret              ; return

 _ClrScr ENDP

 BEGIN:     ; main part of the program

     ; Get address of the function

     mov  dx, SEG _ClrScr
     mov  es, dx
     mov  dx, OFFSET _ClrScr   ; es:dx is the address of the function

     ; Load function address into fptr

     mov  WORD PTR fptr, dx    ; low word of fptr is the
                               ; offset of the function
     mov  WORD PTR fptr+2, es  ; high word of fptr is the
                               ; segment of the function

     ; Call the function via a function pointer

     FARCALL fptr              ; call function. FARCALL is a macro
                               ; defined above

     ; Exit to DOS

     DosExit                   ; Exit to DOS. DosExit is a macro
                               ; defined above

 END BEGIN


 126. Making Multiple Initialized Far Data Segments

 Product Version(s): 5.00 5.10 | 5.10
 Operating System:   MS-DOS    | OS/2
 Flags: ENDUSER |
 Last Modified: 12-JAN-1989    ArticleIdent: Q34379

 Questions:
    How can I make multiple initialized far data segments with the
 Macro Assembler Version 5.00 or 5.10?

 Response:
    You can have multiple initialized far-data segments by using the
 .fardata Segment_Name directive, as documented on Page 88 of the
 "Microsoft Macro Assembler 5.1 Programmers Guide."
    The sample program below demonstrates using two intialized far-data
 segments. The program size is very large (131k) due to the large
 amount of data that is being stored.
    The following is the sample program:

 ; The contents of SrcBuff will be copied to DesBuff
          .model large
          .fardata
 SrcBuff  db    65535 dup (65)      ; First Initialized far segment

          .fardata BufSeg           ; Name 2nd fardata segment BufSeg
 DestBuff db    65535 dup (66)

          .code
 main:
          mov  ax, @fardata         ; Make ds:si point to SrcBuff
          mov  ds, ax
          mov  si, 0

          mov  ax, BufSeg           ; Make es:di point to DestBuff
          mov  es, ax
          mov  di, 0

          mov  cx, 0ffffh           ; Initialize full segment

          rep  movsb                ; Automatically inc si & di
                                    ; Dec cx till 0
          retf
          end  main


 127. MASM 5.10 MACRO.DOC: Process Control

 Product Version(s): 5.10   | 5.10
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified: 12-JAN-1989    ArticleIdent: Q34454

 The following information was taken from the MASM 5.10 MACRO.DOC file.

 PROCESS CONTROL

 @Exit (4Ch)

 Exits to DOS with return code

 Syntax:         @Exit [#return]

 Argument:       return      = 8-bit code to return to DOS; if
                               none given, AL is used
 Return:         None
 Registers used: AX

 @Exec (4Bh)

 Executes a child process or an overlay

 Syntax:         @Exec path, params [,[segpath] [,[segparams]
                 [,overlay]]]

 Arguments:      path        = Offset of ASCIIZ filespec to be
                               executed
                 params      = Offset of process parameter block
                 segpath     = Segment of filespec (DS if none given)
                 segparams   = Segment of parameter block (ES if none
                               given)
                 overlay     = If not defined, normal process
                               executed; if defined, overlay executed
 Return:         If carry set, error code
 Registers used: AX, SI, and DI; DS and ES if corresponding
                 segments given

 @GetRet (4Dh)

 Gets the return code of a child process

 Syntax:         @GetRet

 Argument:       None
 Return:         Return code in AX
 Register used:  AX

 @TSR (31h)

 Terminates a program, but leaves it resident in memory

 Syntax:         @TSR paragraphs [,#return]

 Arguments:      return      = Code to return to DOS; if none, AL
                               used
                 paragraphs  = Memory in paragraphs (16 bytes) to
                               allocate for resident program
 Return:         None
 Registers used: AX and DX


 128. MASM 5.10 MACRO.DOC: BIOS Macro Syntax, Description

 Product Version(s): 5.10   | 5.10
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified: 12-JAN-1989    ArticleIdent: Q34455

 The following information was taken from the MASM 5.10 MACRO.DOC file.

 BIOS Macro Syntax and Description

 MODE, PAGE, AND COLOR CONTROL

 @GetMode (I 10h F 0Fh)

 Gets the current video mode and page

 Syntax:         @GetMode

 Arguments:      None
 Return:         AL          = Mode
                 AH          = Width in characters
                 BH          = Page
 Registers used: AX and BH

 @SetMode (I 10h F 00h)

 Gets the current video mode and page

 Syntax:         @SetMode mode

 Arguments:      mode        = 8-bit video mode
 Return:         none
 Registers used: AX

 @SetColor (I 10h F 0Bh)

 Sets the background color

 Syntax:         @SetColor color

 Arguments:      color       = 8-bit background color (0-15);
                               border color in text modes
 Return:         none
 Registers used: AX and BX

 @SetPalet (I 10h F 0Bh)

 Sets the color palette

 Syntax:         @SetPalet color

 Arguments:      color       = 8-bit color palette (0-1 for modes
 5 and 6)
 Return:         none
 Registers used: AX and BX

 @SetPage (I 10h F 05h)

 Sets the video page

 Syntax:         @SetPage page

 Arguments:      page        = 8-bit page number; 0-3 for modes 2
                               and 3
 Return:         none
 Registers used: AX


 129. Call to @Mkthread Macro Results in Phase Error

 Product Version(s): 5.10   | 5.10
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER | buglist5.10
 Last Modified: 12-JAN-1989    ArticleIdent: Q34664

 The program below generates a phase error on the call to the @Mkthread
 macro that only includes the line "mov cx, seg fproc". The similar
 MASM statements do not generate a phase error.

 The problem has nothing to do with the macro. The difference between
 the MASM statements is moving into CX versus AX.

 Microsoft has confirmed this to be a problem in Version 5.10. We are
 researching this problem and will post new information as it becomes
 available.

 To work around this problem, change the macro line to the following:

 MOV CX, WORD PTR (SEG PROG)

 The following sample code demonstrates the problem:

 .model large
 @mkthread    macro      prog
              mov cx,seg prog
              endm

 .code
 mov ax, seg fproc
 @mkthread fproc

 fproc       proc
 mov ax,seg fproc
 fproc       endp
 end


 130. No Warning on Immediate Value Out of Range

 Product Version(s): 5.10   | 5.10
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified: 12-JAN-1989    ArticleIdent: Q34667

 In the following instruction MASM doesn't warn that an immediate value
 is too large:

 add structure.element[edi],immediate value

 The element is byte wide, but the immediate value is much larger than
 256. The assembler creates a byte add instruction, silently truncating
 the high part of the immediate value.

 MASM generally generates error messages on values out of range. MASM
 does not generate an out of range error message when the immediate
 value could be a signed number (e.g. 0ffffff75h) that is -8bH. The
 assembler can't tell if the immediate value is a negative number or an
 unsigned number that is out of bounds. In this case, MASM will not
 generate an error message.


 131. FWAIT Prefixes Generated for Processor Control Instructions

 Product Version(s): 5.10   | 5.10
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER | buglist5.10
 Last Modified: 12-JAN-1989    ArticleIdent: Q34774

 For a 80287 or 80387, MASM should not be generating FWAIT prefixes for
 processor control instructions that do not have no-wait forms,
 including the following:

 FLDCW, FLDENV, FRSTOR, FINCSTP, FDECSTP, FFREE, and FNOP.

 The following is an example of the wait incorrectly generated by MASM for
 the FLDCW instruction:

 .386
 .387
 .model small
 .data
 d1 dw 0
 .code
 fldcw d1
 end

 The fldcw generates the opcodes "9B D9 2D" when it should only
 generate "D9 2D" without the "9B" wait.

 Microsoft has confirmed this to be problem in Version 5.10. We are
 researching this problem and will post new information as it becomes
 available.


 132. MASM Generates Stack Overflow on Code with Redefinition

 Product Version(s): 5.10   | 5.10
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER | buglist5.10
 Last Modified: 12-JAN-1989    ArticleIdent: Q34930

 The following example causes MASM to generate the error message,
 "run-time error R6000 - stack overflow":

             .model   small
             .code

       xx    equ      <nop>

       xx    macro
             nop
             endm

             xx

             end

 The workaround is to remove the redefinition "xx".

 Microsoft has confirmed this to be a problem in Version 5.10. We are
 researching this problem and will post new information as it becomes
 available.


 133. Segment Combine Type AT with Equate Variable Causes Problem

 Product Version(s): 5.10
 Operating System:   MS-DOS
 Flags: ENDUSER | buglist5.10
 Last Modified: 12-JAN-1989    ArticleIdent: Q34937

 The sample code below demonstrates a problem with the equate directive
 and the segment combine type AT.

 The segment bios_seg incorrectly evaluates to 0 in the mov
 instruction. If the equate statement is located before the bios-seg
 segment definition, the segment bios_seg correctly evaluates to 40h.

 Microsoft has confirmed this to be a problem in Version 5.10. We are
 researching this problem and will post new information as it becomes
 available.

 The following is a sample code:

 code segment public 'code'
 assume cs:code

 bios_seg segment at BIOS

 bios_seg ends

 BIOS  equ 40h

 start:
   mov ax,bios_seg

 code ends
 end start


 134. Multiple Communal Definitions Incorrectly Allowed

 Product Version(s): 5.10   | 5.10
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER | buglist5.10
 Last Modified: 12-JAN-1989    ArticleIdent: Q34979

 MASM is incorrectly allowing multiple communal definitions of a single
 variable. The COMDEF record produced by MASM in the object module
 contains the definition from the last COMM directive. The problem
 occurs on code similar to the following:

 comm c1:byte:44
 comm far c1:byte:22
 comm far c1:byte:11
 comm c1:byte:33

 Microsoft has confirmed this to be a problem in Version 5.10. We are
 researching this problem and will post new information as it becomes
 available.


 135. MASM 5.10 MACRO.DOC: Calling Macros in DOS.INC, BIOS.INC

 Product Version(s): 5.10   | 5.10
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified: 12-JAN-1989    ArticleIdent: Q34466

 The following information was taken from the MASM 5.10 MACRO.DOC file.

 Calling Macros in DOS.INC and BIOS.INC

 You are responsible for saving and restoring registers used in macros.
 The "Registers used" field identifies registers to save.

 Macros that accept address parameters use internal macros that allow
 you to specify addresses in several ways. The macro automatically
 identifies the type of the argument and handles it appropriately. For
 example, assume the following declarations:

   String    DB   "test$"
   pString   DW   Str
   fpString  DD   Str

 Given these values, the macro @DispStr (which displays the string at
 DS:DX) has the following effects:

   Kind of argument          Example               Value loaded

   Label of byte variable    @DispStr String       DS:OFFSET String
   Near pointer variable     @DispStr pString      DS:pString
   Far pointer variable      @DispStr fpString
   fpString[2]:fpString[0]
   Constant                  @DispStr 0            DS:0
   Pointer in register       @DispStr si           DS:SI
   Near Pointer with segment @DispStr pString,es   ES:pString
   Constant with segment     @DispStr 0,es         ES:0
   Register with segment     @DispStr di,es        ES:DI

 Note that if a far pointer or a segment is given, DS must be saved
 before the macro call and restored afterward. Segments may be given as
 registers, constants, or word variables.

 In syntax, parameters enclosed in brackets are optional. Paramaters
 sometimes have a leading symbol to indicate that the argument must
 have a certain type, as shown below:

   Leading Symbol   Example      Limitation

         #          #return      Must be constant
         &          &vector      Must be offset address as described
                                 above
         $          $terminator  May be constant or register, but not
                                 memory

 Parameters with no leading symbol may be constants, registers, or
 variables. Parameters are 16-bit except where noted in the
 description.

 Symbols must be previously defined before they can be passed as
 arguments to most of the DOS macros. Generally this means that data
 must be declared before code in the source file.


 136. MASM 5.10 MACRO.DOC: DOS Macro Syntax and Description

 Product Version(s): 5.10   | 5.10
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified: 12-JAN-1989    ArticleIdent: Q34467

 The following information was taken from the MASM 5.10 MACRO.DOC file.

 DOS Macro Syntax and Description

 KEYBOARD INPUT

 @GetKey (01h, 07h, 08h, 0Ch)

 Gets a keystroke from the keyboard

 Syntax:         @GetKey [#echo] [,[#break] [,#clearbuf]]

 Arguments:      echo        = nonzero to echo keystroke -
                               default yes
                 break       = nonzero to accept Control-C - default
                               yes
                 clearbuf    = nonzero to clear keyboard buffer -
                               default no
                 (Arguments may be omitted to get defaults)
 Return:         ASCII code of key in AL
 Registers used: AX used for all, DL used if echo on and ctrl
 -c off

 @GetStr (0Ah)

 Gets a string from the keyboard

 Syntax:         @GetStr &buffer [,[$terminator] [,[#limit]
 [,segment]]]

 Arguments:      buffer      = Offset of buffer where string will
                               be stored
                     Byte 1  = Maximum length of string (before call)
                     Byte 2  = Actual length of string (after call)
                     Byte 3+ = Bytes of string
                 terminator  = Terminating byte - usually null (0) or
 $ (24h)
                 limit       = Maximum length of string (if not given
                               as argument, must be in buffer before
                               macro call)
                 segment     = Segment of buffer (DS if not given)
 Return:         Pointer to string in SI, length of string in BX
 Registers used: AX, DX, BX, SI


 137. Misleading Error Message, A2102, on USE16 Segment

 Product Version(s): 5.10   | 5.10
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER | docerr
 Last Modified: 12-JAN-1989    ArticleIdent: Q34985

 The error message A2102, Segment near (or at) 64K limit, is displayed
 when a USE16 data segment exceeds 64K. The documentation refers to the
 80286's problem with code segments larger than 65500, which is
 misleading.


 138. MASM 5.10 MACRO.DOC: Device I/O

 Product Version(s): 5.10   | 5.10
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified: 12-JAN-1989    ArticleIdent: Q34469

 The following information was taken from the MASM 5.10 MACRO.DOC file.

 DEVICE I/O

 @Read (3Fh)

 Reads data from a file or device

 Syntax:         @Read &buffer, length [,[handle] [,segment]]

 Arguments:      buffer      = Offset of buffer where data will
                               be stored
                 length      = Length of data in bytes
                 handle      = File or device handle; if none given,
                               keyboard (handle 0) is assumed
                 segment     = Segment of address string (DS if not
                               given)
 Return:         If carry clear, bytes read in AX
 Registers used: Always AX, DX, BX, and CX; DS if segment
                 changed

 @Write (40h)

 Writes data to a file or device

 Syntax:         @Write &buffer, length, [,[handle] [,segment]]

 Arguments:      buffer      = Offset of buffer where data is
                               stored
                 length      = Length of data in bytes
                 handle      = File or device handle; if none given,
 screen
                               (handle 1) is assumed
                 segment     = Segment of address string (DS if not
                               given)
 Return:         If carry clear, bytes written in AX
 Registers used: Always AX, DX, BX, and CX; DS if segment
                 changed


 139. MASM 5.10 MACRO.DOC: File Control

 Product Version(s): 5.10   | 5.10
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified: 12-JAN-1989    ArticleIdent: Q34470

    The following information was taken from the MASM 5.10 MACRO.DOC
 file.

 FILE CONTROL

 @MakeFil (3Ch, 5Ah, 5Bh)

 Creates a file

 Syntax:         @MakeFil &path [,[attrib] [,[segment] [,#kind]]]

 Arguments:      path        = ASCIIZ string of file
                 attrib      = File atrribute (0 is default if none
                               given)
                 segment     = Segment of address string (DS if not
                               given)
                 kind        = If none given, a file is always
                               created even if one already exists. Under
                               DOS 3+ "tmp" can be given to create a
                               unique file or "new" to create file only
                               if one doesn't already exist.
 Return:         If carrry clear, file handle in AX
 Registers used: Always AX, DX, and CX; DS if segment changed

 @OpenFil (3Dh)

 Opens a file for input or output

 Syntax:         @OpenFil &path, #access [,segment]

 Arguments:      path        = ASCIIZ string of file
                 access      = File access code
                 segment     = Segment of address string (DS if not
 given)
 Return:         If carrry set, error code in AX
 Registers used: Always AX and DX; DS if segment changed

 @ClosFil (3Eh)

 Closes an open file handle

 Syntax:         @ClosFil handle

 Arguments:      handle      = Previously opened file handle
 Return:         If carrry set, error code in AX
 Registers used: AX and BX

 @DelFil (41h)

 Deletes a specified file

 Syntax:         @DelFil &path [,segment]

 Arguments:      path        = Offset of ASCIIZ filespec
                 segment     = Segment of path (DS if none given)
 Return:         If carrry set, error code in AX
 Registers used: AX and DX; DS if segment changed

 @MoveFil (56h)

 Moves or renames a file by changing its path specification.

 Syntax:         @MoveFil &old, &new [,[segold] [,segnew]]

 Arguments:      old         = Offset of file spec to be renamed
                 new         = Offset of new file spec
                 segold      = Segment of old name (DS if none given)
                 segnew      = Segment of new name (ES if none given)
 Return:         If carry set, error code in AX
 Registers used: AX, DX, and DI; DS and ES if corresponding
 segments changed

 @GetFirst (4Eh) and @GetNext (4Fh)

 Parses file specifications (optionally including wild cards)
 into file names

 Syntax:         @GetFirst &path [,[attribute] [,segment]]
                 @GetNext

 Arguments:      path        = Offset of ASCIIZ filespec (can
                               have wild cards)
                 attribute   = File attribute to search for (0 for
                               normal if none given)
                 segment     = Segment of path (DS if none given)
 Return:         If carrry set, error code in AX
 Registers used: @GetFirst   = AX, CX, and DX; DS if segment
 changed
                 @GetNext    = AX only

 @GetDTA (1Ah) and @SetDTA (2Fh)

 Gets or sets the Disk Transfer Address (DTA)

 Syntax:         @GetDTA
                 @SetDTA &buffer [,segment]

 Arguments:      buffer      = Offset of new DTA buffer
                 segment     = Segment of new DTA buffer (DS if none
 given)
 Return:         @GetDTA     = ES:BX points to DTA
                 @SetDTA     = None
 Registers used: AX for both; DS and DX for @SetDTA; ES and
 BX for @GetDTA

 @GetFilSz (42h)

 Gets the file size by moving the file pointer to end of the
 file. Note that the file pointer is reset to zero. Thus this macro
 should not be called during operations that move the pointer.

 Syntax:         @GetFilSz handle

 Arguments:      handle      = Previously opened file handle
 Return:         If carrry clear, file length in DX:AX
 Registers used: AX, BX, CX, and DX

 @MovePrtAbs and @MovePtrRel (42h)

 Moves the file pointer in an open file. The pointer can be
 moved to an absolute position, or relative to its current position.

 Syntax:         @MovePrtAbs handle [,distance]
                 @MovePrtRel handle [,distance]

 Arguments:      handle      = Previously opened file handle
                 distance    = Distance to move pointer - must be a
                               16-bit constant or a 16- or 32-bit variable;
                               or leave blank and set distance in CX:DX
                               before macro call
 Return:         If carrry clear, file pointer position in DX:AX
 Registers used: AX, BX, CX, and DX


 140. MASM 5.10 MACRO.DOC: Directory Control

 Product Version(s): 5.10   | 5.10
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified: 12-JAN-1989    ArticleIdent: Q34471

 The following information was taken from the MASM 5.10 MACRO.DOC file.

 DIRECTORY CONTROL

 @MkDir, (39h), @RmDir (3Ah), and @ChDir (3Bh)

 Creates, deletes, or changes to the specified directory

 Syntax:         @MkDir &path [,segment]
                 @RmDir &path [,segment]
                 @ChDir &path [,segment]

 Arguments:      path        = Offset of ASCIIZ string to
                 segment     = Segment of path (DS if none given)
 Return:         If carrry set, error code in AX
 Registers used: AX and DX; DS if segment changed

 @GetDir (47h)

 Returns the current directory of the specified drive

 Syntax:         @GetDir &path [,[drive] [,segment]]

 Arguments:      buffer      = Offset of buffer to receive ASCIIZ
 directory
                 drive       = 8-bit drive number - 0=current, 1=A,
 2=B,    etc.
                               (0 if none given)
                 segment     = Segment of path (DS if none given)
 Return:         If carrry set, error code in AX
 Registers used: AX, SI, and DL; DS if segment changes


 141. MASM 5.10 MACRO.DOC: Drive Control

 Product Version(s): 5.10   | 5.10
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified: 12-JAN-1989    ArticleIdent: Q34472

 The following information was taken from the MASM 5.10 MACRO.DOC file.

 DRIVE CONTROL

 @GetDrv (0Eh) and @SetDrv (19h)

 Gets or sets the current drive

 Syntax:         @GetDrv
                 @SetDrv drive

 Argument:       drive       = 8-bit drive number (0=A, 1=B,
 etc.)
 Return:         @GetDrv     = Drive number in AL (0=A, 1=B,
 etc.)
                 @SetDrv     = Number of drives in AL
 Registers used: AX for both; DL for @SetDrv

 @ChkDrv (36h)

 Gets various data about a disk

 Syntax:         @ChkDrv [drive]

 Argument:       drive       = 8-bit drive number (0=current,A=1,
                               B=2, etc.); if none given, current
                               assumed
 Return:         AX          = Sectors per cluster (-1 if drive
                               invalid)
                 BX          = Available clusters
                 CX          = Bytes per sector
                 DX          = Clusters per drive
 Registers used: AX, BX, CX, and DX


 142. MASM 5.10 MACRO.DOC: Miscellaneous

 Product Version(s): 5.10   | 5.10
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified: 12-JAN-1989    ArticleIdent: Q34473

 The following information was taken from the MASM 5.10 MACRO.DOC file.

 MISCELLANEOUS

 @GetDate (2Ah) and @SetDate (2Bh)

 Gets or sets the system date

 Syntax:         @GetDate
                 @SetDate month, day, year

 Arguments:      year        = 16-bit year (1980-2099)
                 month       = 8-bit month (1-12)
                 day         = 8-bit day (1-31)
 Return:         For @GetDate:
                         AL  = Day of week (0 = Sunday, 1 = Monday, etc.)
                         CX  = Year (1980-2099)
                         DL  = Month (1-12)
                         DH  = Day (1-31)
                 For @SetDate:
                         AL  = If date was valid 0, else -1
 Registers used: AX, CX, and DX

 @GetTime (2Ch) and @SetTime (2Dh)

 Gets or sets the system time

 Syntax:         @GetTime
                 @SetTime hour,minute,second,hundredth

 Arguments:      hour        = 8-bit hour (0-23)
                 minute      = 8-bit hour (0-59)
                 second      = 8-bit hour (0-59)
                 hundredth   = 8-bit hour (0-99)
 Return:         For @GetTime:
                         CL  = Hour (0-23)
                         CH  = Minute (0-59)
                         DL  = Second (0-59)
                         DH  = Hundredth (0-99)
                 For @SetTime:
                         AL  = If time was valid 0, else -1
 Registers used: AX, CX, and DX

 @GetVer (30h)

 Gets the DOS version

 Syntax:         @GetVer

 Argument:       None
 Return:         AL          = Major version (0 for versions prior to
                               2.0)
                 AH          = Minor version
                 BH          = OEM serial number
                 BL:CX       = 24-bit user number
 Register used:  AX, BX, and CX

 @GetInt (35h) and @SetInt (25h)

 Gets or sets the vector for a specified interrupt routine

 Syntax:         @GetInt #interrupt
                 @SetInt #interrupt, &vector [,segment]

 Arguments:      interrupt   = 8-bit interrupt number
                 vector      = Offset of interrupt routine
                 segment     = Segment of routine - if none given, DS
                               assumed for data; segment ignored for
                               code labels
 Return:         @GetInt     = None
                 @SetInt     = ES:BX points to interrupt routine
 Registers used: AX for both; ES and BX for @GetInt; DS and
 DS for @SetInt


 143. Mixing \ and / in Command Line Causes Problems

 Product Version(s): 5.10   | 5.10
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER | buglist5.10 | fixlist5.10A
 Last Modified: 10-JUL-1990    ArticleIdent: Q34500

 When mixing \ and / on the MASM command line, MASM will sometimes give
 incorrect results and hang. The following command line causes these
 problems (the command lines are broken up for readability only):

 masm
      -I\sl200qr\sl
      -Mx
      -DVERS_DDQR
      -I\sl200qr/sl/cmerge/src/Common
        \sl200qr/sl/cmerge/src/Common/comsup.asm ;

 The command line causes the option -Mx to be ignored. MASM also hangs
 on some assembler files.

 In this case, MASM was incorrectly extracting the base name; it wrote
 the full path into an array big enough only for an 8.3 filename, thus
 overwriting many global flags.

 Microsoft has confirmed this to be a problem in Version 5.10. We are
 researching this problem and will post new information as it becomes
 available.



 144. word Causes "Illegal Operand Size" Warning

 Product Version(s): 5.10   | 5.10
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified: 12-JAN-1989    ArticleIdent: Q34501

 The following command causes the warning "illegal operand size:"

 lds  dx, word ptr [bp+6]

 However, using dword assembles clean.

 The line is from the code below. The procedure foo function
 receives a pointer to a string and writes it to the screen.

 It accept dword and not word because the LDS assembler instruction
 reads and stores a far pointer specified by the source-memory operand.
 Using the word type should cause a warning with small model.
 The following sample code demonstrates the problem:

  .model     medium

  .code
             PUBLIC  _foo
 _foo        PROC
             push    bp
             mov     bp, sp

             lds     dx, word ptr [bp+6]    ;causes 'illegal operand size'.
                                            ;but not with use of 'dword'

             mov     ah, 40h
             mov     bx, 1
             mov     cx, 17
             int     21h

             pop     bp
             ret
 _foo        ENDP
             END


 145. Proc Directive Will Not Work with Structure Type

 Product Version(s): 5.10   | 5.10
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER | docerr
 Last Modified: 12-JAN-1989    ArticleIdent: Q34503

 Page 38 of the "Microsoft Macro Assembler 5.10 Update" guide
 incorrectly states that "the type is the type of the argument and may
 be word, dword, fword, qword, tbyte or the name of a structure defined
 by a STRUC structure declaration."

 The support of the STRUC type has not been added to MASM Version 5.10.
 Microsoft will correct the documentation in the next release.

 The following program illustrates the use of the STRUC type
 that is not supported:

 .model small,c
 .data
 t1 STRUC
   f1  dw 0
 t1 ENDS
 .code
 h1  PROC arg1:t1
 end

 To work around this problem, use the PTR type in the Proc argument.
 Instead of using

 h1 PROC arg1:t1

 the procedure should be declared as follows:

 h1 PROC arg1:PTR t1

 No syntax checking is done on t1.


 146. MASM 5.10 MACRO.DOC: Character and Cursor Control

 Product Version(s): 5.10   | 5.10
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified: 12-JAN-1989    ArticleIdent: Q34575

 The following information was taken from the MASM Version 5.10
 MACRO.DOC file.

 CHARACTER AND CURSOR CONTROL

 @GetCur (I 10h F 04h)

 Gets the cursor position and size

 Syntax:         @GetCur [page]

 Arguments:      page        = 8-bit page with cursor (if none, 0
 assumed)
 Return:         DL          = Column
                 DH          = Row
                 CL          = Starting scan line
                 CH          = Ending scan line
 Registers used: AX, DX, CX, and BH

 @SetCurPos (I 10h F 02h)

 Sets the cursor position

 Syntax:         @SetCurSz [column] [,[row] [,page]]

 Arguments:      column      = 8-bit column; if none, DL used
                 row         = 8-bit row; if none, DH used
                 page        = 8-bit page with cursor (if none, 0
                               assumed)
 Return:         none
 Registers used: AX, DX, and BH

 @SetCurSz (I 10h F 01h)

 Sets the cursor size and shape by specifying active scan lines. The
 CGA adapter the lines are 0-7. The monochrome adapter has lines
 0-13.

 Syntax:         @SetCurSz startline, endline

 Arguments:      startline   = 8-bit starting scan line (default C
 GA=6; MA=12)
                 endline     = 8-bit ending scan line (default CGA=7;
 MA=13)
 Return:         none
 Registers used: AX and CX

 @GetChAtr (I 10h F 08h)

 Gets the character and attribute at the cursor location

 Syntax:         @GetChAtr [page]

 Arguments:      page        = 8-bit page to check (if none, 0
 assumed)
 Return:         AH          = Attribute
                 AL          = ASCII character
 Registers used: AX and BH

 @PutChAtr (I 10h F 09h) and @PutCh (I 10h F 0Ah)

 Puts one or more characters and attributes at the current cursor
 position. For @PutCh, the current attribute is used in text modes and
 any specified attribute is ignored.

 Syntax:         @PutChAtr [character] [,[attrib] [,[page]
 [,count]]]

 Arguments:      character   = 8-bit ASCII character to put; if
                               none, AL used

                 attrib      = 8-bit attribute to put; if none, BL
                               used
                 page        = 8-bit page to put on (if none, 0
                               assumed)
                 count       = Number to put (if none, 1 assumed)
 Return:         AH          = Attribute
                 AL          = ASCII character
 Registers used: AX, BX, CX

 @Scroll (I 10h F 06h and 07h)

 Scrolls a specified window up or down

 Syntax:         @Scroll dist [,[attr] [,[uprow [,[upcol [,[dnrow]
                 [,dncol]]]]]
 Arguments:      dist        = 8-bit number of lines to scroll;
                               positive scrolls down; negative scrolls
                               up; 0 clears
                 attr        = 8-bit attribute for blank lines (if
                               none, 07h)
                 uprow       = Upper left row (if none, CH used)
                 upcol       = Upper left column (if none, CL used)
                 dnrow       = Lower right row (if none, DH used)
                 dncol       = Lower right column (if none, DL used)
 Return:         none
 Registers used: AX, CX, DX, and BH

 @Cls (I 10h F 06, 08h, and 02h)

 Clears the screen of the current page

 Syntax:         @Cls

 Arguments:      None
 Return:         None
 Registers used: AX, BX, CX, and DX


 147. MASM 5.10 MACRO.DOC: Memory Control

 Product Version(s): 5.10   | 5.10
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified: 12-JAN-1989    ArticleIdent: Q34576

 The following information was taken from the MASM Version 5.10
 MACRO.DOC file.

 MEMORY CONTROL

 @FreeBlok (49h)

 Frees a block of memory

 Syntax:         @FreeBlok [segment]

 Argument:       segment     = Starting address of memory to be
                               freed; if none, ES address assumed
 Return:         If carry set, error code in AX
 Register used:  AX; ES if segment given

 @GetBlok (48h)

 Allocates a block of memory

 Syntax:         @GetBlok paragraphs

 Argument:       paragraphs  = Paragraphs (16 bytes) of memory
 wanted
 Return:         AX and ES   = Segment address of allocated
 memory
                 BX          = Paragraphs actually allocated (may be
                               less than requested if memory is short)
 Register used:  AX and BX

 @ModBlok (48h)

 Modifies an allocated block of memory

 Syntax:         @ModBlok paragraphs [,segment]

 Argument:       paragraphs  = Paragraphs (16 bytes) of memory
 wanted
                 segment     = Starting address of memory to be
 freed;
                               if none, ES address assumed
 Return:         If carry set, error code in AX, else:
                         ES  = Segment address of allocated memory
                         BX  = If carry is clear, paragraphs allocated
 Register used:  AX and BX; ES if segment given


 148. MASM 5.10 MACRO.DOC: Output

 Product Version(s): 5.10   | 5.10
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified: 12-JAN-1989    ArticleIdent: Q34577

 The following information was taken from the MASM Version 5.10
 MACRO.DOC file.

 OUTPUT

 @DispCh (02h)

 Displays one or more characters to screen

 Syntax:         @DispCh char [,char]...

 Arguments:      char        = 8-bit ASCII code
 Return:         Code in AL
 Registers used: AX and DL

 @PrtCh (05h)

 Prints one or more characters to LPT1

 Syntax:         @PrtCh char [,char]...

 Arguments:      char        = 8-bit ASCII code
 Return:         Code in AL
 Registers used: AX and DL

 @DispStr (09h)

 Displays a $-terminated string

 Syntax:         @DispStr &address [,segment]

 Arguments:      address     = Address of string terminated by
 "$" (24h)
                 segment     = Segment of address string (DS if not
 given)
 Return:         None
 Registers used: AX and DS


 149. Nested Dups in Structure Cause Recursive Loop

 Product Version(s): 5.10   | 5.10
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER | buglist5.10
 Last Modified: 12-JAN-1989    ArticleIdent: Q35113

 The following code uses nested dup operators in a structure
 initialization:

 seltable SELENTRY MINSELS/4 dup (,.,3 dup (<SEL_UNUSED>))

 MASM goes into a recursive loop at the calculation of the size. You
 can work around this problem by having three instances listed, as
 follows:

 seltable SELENTRY MINSELS/4 dup (<>,<SEL_UNUSED>,<SEL_UNUSED>,
    <SEL_UNUSED>)

 Microsoft has confirmed this to be a problem in Version 5.10. We are
 researching this problem and will post new information as it becomes
 available.


 150. Comparison of a Constant and a Relocatable Are Not Allowed

 Product Version(s): 5.10   | 5.10
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified: 12-JAN-1989    ArticleIdent: Q35114

 The comparison of a constant (left-hand side) and a relocatable
 (right-hand side) are not allowed. The following is an example:

 .errnz 0FFFFh-(MAXSELS * size SELENTRY) GT seltable-1

 A workaround for this problem that will direct the assembler to
 generate the correct opcodes is to use the segment name that contains
 the structure seltable, as follows:

 .errnz data:0FFFFh-(MAXSELS * size SELENTRY) GT seltable -1


 151. Line Parsing Order for MASM: Looks Up Second Token First

 Product Version(s): 5.x    | 5.10
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified: 12-JAN-1989    ArticleIdent: Q35128

 The Microsoft Macro Assembler always looks up the second token on the
 line first. In the case below, it sees "specb". Because that is a
 structure definition, MASM assumes the line declares a structure
 instance with "MOV" being the label. At this point, MASM errors on
 trying to use reserved symbol "MOV" as a structure instance label. The
 assumption is reasonable and would be hard to modify the way MASM
 parses.

 The following sample code demonstrates the problem:

 _DATA SEGMENT
 specb STRUC
         buff  DW  ?
 specb ENDS
 _DATA ENDS

 _CODE SEGMENT
 ASSUME CS:code
 start:
     mov specb.buff,AX
 _CODE ENDS

 END start


 152. Proc Directive with Uses Option and Nine Registers

 Product Version(s): 5.10   | 5.10
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER | SR# G880831-2870 buglist5.10
 Last Modified: 13-JAN-1989    ArticleIdent: Q35214

 The assembler fragment (for MASM Version 5.10) below displays two
 problems when assembled.

 The problem seems to be the use of more than eight registers in a
 "proc uses" clause.

 A workaround for this problem is to specify only eight registers in
 the uses option and include in your procedure the pushes and pops for
 any other registers to be saved.

 Microsoft has confirmed this to be a problem in Version 5.10. We are
 researching this problem and will post new information as it becomes
 available.

 The following assembler fragment demonstrates this problem:

 foo proc uses ax bx cx dx ds cs ss bp
 foo endp
 end

 When assembled as is, MASM returns an out of memory error:

 Microsoft (R) Macro Assembler Version 5.10
 Copyright (C) Microsoft Corp 1981, 1988.  All rights reserved.

 masm.err(12): Out of memory

 When assembled as a part of the complete module, it returns the error:

 Microsoft (R) Macro Assembler Version 5.10
 Copyright (C) Microsoft Corp 1981, 1988.  All rights reserved.

 rd.ASM(84): warning A4016: Reserved word used as symbol: BP
 rd.ASM(89): error A2009: Symbol not defined: BP(ASCII 016)

   47898 Bytes symbol space free

       1 Warning Errors
       1 Severe  Errors


 153. Real-Number Encoding Needs Exact Number of Digits

 Product Version(s): 5.10   | 5.10
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER | SR# S880913-6
 Last Modified: 12-JAN-1989    ArticleIdent: Q35507

 In MASM, real numbers are initialized by using DD, DQ, and DT
 directives. The number of digits for encoded numbers declared with DD,
 DQ, and DT must be 8, 16, and 20 digits, respectively. If a leading 0
 is supplied, the number must be 9, 17, or 21 digits.

 For example, the following MASM line generates the assembler
 warning A4057: Illegal size for operand:

 _x     DQ   0000000000r

 The real number should be defined with exactly 17 digits.
 MASM will correctly evaluate the constant, but the warning
 is telling the user the number of digits used is not correct.
 Information concerning real-number constants can be found
 in the "Microsoft Macro Assembler 5.10 Programmer's Guide."


 154. External Addresses in "=" Directive Documentation Error

 Product Version(s): 5.00 5.10 | 5.10
 Operating System:   MS-DOS    | OS/2
 Flags: ENDUSER | docerr
 Last Modified: 12-JAN-1989    ArticleIdent: Q35803

 On Page 214, section 11.1.1, of the "Microsoft Macro Assembler
 Programmer's Guide," the documentation indicates the equal-sign (=)
 directive may be used with expressions that evaluate to an address. If
 the address refers to an external label, the error A2052 will be
 issued from the assembler.

 MASM has a restriction with the "=" directive that should be
 documented. The use of "=" directive with expressions that evaluate to
 an address is not allowed. The EQU directive should be used instead.


 155. .code Directive with Segment Name Documentation Error

 Product Version(s): 5.00 5.10 | 5.10
 Operating System:   MS-DOS    | OS/2
 Flags: ENDUSER | docerr
 Last Modified: 12-JAN-1989    ArticleIdent: Q35804

 On Page 89, section 5.1.4, of the "Microsoft Macro Assembler
 Programmer's Guide," the last line of the second paragraph states
 "Name will be ignored if given with small or compact models."

 This information is a documentation error. If a name is given with the
 .code directive, a syntax error will be generated by the assembler.


 156. Align Directive Aligns Off Start of Segment

 Product Version(s): 5.10   | 5.10
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified: 12-JAN-1989    ArticleIdent: Q35880

 The ALIGN directive adds the necessary bytes to pad the current offset
 to be divisible by 16.

 In the example below, the offset of the first byte of d1 is 0;
 therefore, the offset of the last is 31. Thus, 1 byte of padding is
 necessary to "align on a paragraph boundary," i.e., make the current
 offset divisible by 16.

 The following example demonstrates this information:

 e.data
 d1   db 'This is to pad the data segment'
 align 16



 157. Name Directive No Longer Supported

 Product Version(s): 5.00 5.10
 Operating System:   MS-DOS
 Flags: ENDUSER |
 Last Modified: 12-JAN-1989    ArticleIdent: Q35881

 The Name directive was available in MASM Version 4.00. The directive,
 Name modulename, sets the name of the current module to modulename. A
 module name is used by the linker when displaying error messages.

 In MASM Versions 5.00 and 5.10, the old directive does not generate an
 assembler error because Microsoft wants to have downward compatibility
 with MASM Version 4.00 source files. The directive does not generate
 any extra information for MASM Versions 5.00 and 5.10.


 158. Warning A5114: Operand Size Does Not Match Segment Word Size

 Product Version(s): 5.00 5.10
 Operating System:   MS-DOS
 Flags: ENDUSER |
 Last Modified: 12-JAN-1989    ArticleIdent: Q35882

 The MASM warning A5114: "Operand size does not match segment word
 size" occurs when using 32-bit operands in USE16 segments. The warning
 is only generated on push and pop instructions using an operand with
 the size other than the size of the segment. For example, using dword
 push in a USE16 segment or using a word push in a USE32 segment. The
 warning is not generated for any other use of 32-bit operands.

 The warning message may have been added to aid the programmer trying
 to convert code from 16-bit segments to 32-bit segments. The warning
 message should only occur in 32-bit segments when 16-bit push/pop
 operands are given, and not in the converse situation.

 Microsoft is researching the subject and will post more information
 when available.


 159. Public Labels Are Prefixed with Underscore Incorrectly

 Product Version(s): 5.10   | 5.10
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER | buglist5.10
 Last Modified: 20-NOV-1990    ArticleIdent: Q35883

 When you assemble the following program with MASM Version 5.10 and
 examine the public labels, you will find an underscore prefixed to the
 public labels. The structure declaration is the cause of the problem.
 The problem is related to the space before the comma in the structure
 initialization. MASM wasn't skipping it, causing a host of problems.

 The workaround to this problem is to remove the space.

 Another symptom of the problem occurs during link-time, the linker
 generates unresolved externals for all public labels with underscores
 prefixed.

 Microsoft has confirmed this to be a problem in Version 5.10. We are
 researching this problem and will post new information as it becomes
 available.

 The following sample code demonstrates the problem:

 ;*******************************************************************
 FooStruc STRUC
 Label1      db      "LPT"
 Label2      db      ?
             db      "    "
 FooStruc ENDS

 DSEG SEGMENT
 FooData1 FooStruc < , "1">
 FooData2 FooStruc < , "2">
 DSEG ENDS

 CSEG SEGMENT
     ASSUME CS:CSEG, DS:DSEG

 PUBLIC FooProc
 FooProc PROC NEAR

         mov     ax, OFFSET DSEG:FooData2

 FooProc ENDP

 CSEG ENDS

         END
 ;*************************************************************


 160. Error L2002: Fixup Overflow for MASM and C

 Product Version(s): 5.10
 Operating System:   MS-DOS
 Flags: ENDUSER |
 Last Modified: 12-JAN-1989    ArticleIdent: Q38216

 If the variable exp_data is declared in MASM as follows

 .data
     EXTRN _exp_data:WORD

 and declared in C as follows, the error L2002: fixup overflow is
 generated:

  .
  .
  .
  int exp_data;

  main()
  {...
  }

 This error occurs because the assembler declaration puts _exp_data in
 the _data logical segment in dgroup. The C declaration, however, will
 put _exp_data in the FAR_BSS as it is an uninitialized global data
 item in large model.

 One way to eliminate this error is to initialize _exp_data in C. This
 will put it in the _data logical segment in dgroup as well.

 Another work around is to delcare _exp_data in MASM outside of the
 .data directive. This will put _exp_data into the FAR_BSS in
 large-memory model.


 161. Expressions in Define Statements

 Product Version(s): 5.10   | 5.10
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified: 12-JAN-1989    ArticleIdent: Q38935

 In all versions of Microsoft Macro Assembler earlier than Version
 5.10, you could not have greater than 16-bit arithmetic in define
 statements. This has been changed in Version 5.10.

 In all versions before Version 5.10, you could use constants of
 greater than 16 bits; however, you could not put an arithmetic
 expression to obtain a number larger than 16 bits.

 The following is an example:

 DD 86400     <-  correct.
 DD 60*60*24  <-  incorrect. This would be truncated at the
                             16-bit value.

 This feature has been implemented in Version 5.10 so that both of the
 above declarations will yield the same answer.


 162.

 Product Version(s): 5.00 5.10 | 5.10
 Operating System:   MS-DOS    | OS/2
 Flags: ENDUSER | docerr
 Last Modified: 12-JAN-1989    ArticleIdent: Q38936

 The code fragment in section 7.1.3 on Page 147 of the "Microsoft Macro
 Assembler Programmer's Guide" causes a warning A4031: "Operand types
 must match." There is an error in the example.

 Change the line below

    mov ax, [bx].month

 to the following:

    mov ah, [bx].month

 Because the structure field month is defined as a byte, the assignment
 to a word register generates the operand-mismatch warning message. The
 change to a byte register resolves the warning. The following is also
 acceptable:

    mov ax, word ptr [bx].month


 163. Addressing above 1 Megabyte

 Product Version(s): 5.00   | 5.10
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER | reference words
 Last Modified: 12-JAN-1989    ArticleIdent: Q39370

 Question:

 The 80286 is capable of addressing a maximum of 16 megabytes of
 memory; however, with 16-bit segment and offset registers, I can only
 reach 1 megabyte. How can I address this extra memory?

 Response:

 When the 80286 is in real mode, it is not possible to reach that
 memory -- you are limited to 1 megabyte. To use that space, you have
 to put the processor into protected mode by using IBM ROM BIOS Call -
 Interupt 15 function 89h.

 For more information about this interrupt, call IBM hardware support
 at [phone]. This information is not covered in the DOS
 Encyclopedia.


 164. Exe2bin Will Not Support exe Files Created with dosseg

 Product Version(s): 5.10   | 5.10
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified: 12-JAN-1989    ArticleIdent: Q39173

 When creating a com file, the exe2bin utility will not accept an
 executable file if the file was created using the dosseg directive
 in MASM.

 This behavior occurs because the dosseg directive places 16 bytes at
 the beginning of the executable to ensure proper byte alignment. This
 format is not acceptable to exe2bin. To work around this problem, do
 not use the dosseg directive when creating an executable to be
 converted into com format.


 165. An Example of Declaring a Communal Variable of a Record Type

 Product Version(s): 5.00 5.10 | 5.10
 Operating System:   MS-DOS    | OS/2
 Flags: ENDUSER |
 Last Modified: 12-JAN-1989    ArticleIdent: Q39235

 Question :

 How can I declare a communal variable that has a record type?

 Response:

 Declare the variable with the size matching the size of the record
 type defined in the same source file. There is no need to specify that
 the variable has the predefined record type.

 The following sample program demonstrates this information:

 ; module 1
         .model small
         dosseg
 extrn   proc2:proc
         .stack 100h
         .data
 color   record   blink:1, back:3, intense:1, fore:3
         comm     near pixel:byte     ; use "byte" because
                                      ; color has size byte.
         .code
 start:  mov ax, @data
         mov ds, ax

         mov pixel, color <1,2,1,3> ; now the variable pixel
                                    ; should have the value "abh",
                                    ; which matches the
                                    ; pattern 1,010,1,011
         call proc2
         mov ax, 4c00h
         int 21h
         end start

 ******************************
 ; module 2
         .model small
         dosseg
         .stack 100h
         .data
 color   record   blink:1, back:3, intense:1, fore:3
         comm     near pixel:byte
         .code
         public proc2
 proc2   proc
         mov ah, 0
         mov ah, pixel  ; ah should have the value "abh"
         ret
 proc2   endp
         end


 166. Proc with ARG Directive Requires Language in .MODEL

 Product Version(s): 5.00   | 5.10
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified: 12-JAN-1989    ArticleIdent: Q39371

 The program below, which uses the PROC directive, will not assemble
 correctly unless you use a language parameter with the .MODEL
 directive. The "Microsoft Macro Assembler Programmer's Guide" does not
 say that the language parameter is required when using the PROC
 directive.

 The language parameter on the .MODEL directive enables the PROC
 extensions, changes the scope of code labels within procedures, and
 may affect naming. When the language parameter is left off, the PROC
 directive will only accept a NEAR or FAR specifier.

 The following is a sample program:

         .model large
 ;       .model large, c  ; This line will permit correct assembly.
         .code
 myadd   proc arg1:ptr, arg2:ptr
         les bx, arg1
         les dx, arg2
         ret
 myadd   endp
         end

 The following errors are generated during assembly:

 A2022: Operand must be type specifier
 A2009: Symbol not defined: ARG1
 A2009: Symbol not defined: ARG2


 167. MOV mem,accum and MOV accum,mem Formats Incorrectly Documented

 Product Version(s): 5.00 5.10
 Operating System:   MS-DOS
 Flags: ENDUSER |
 Last Modified: 12-JAN-1989    ArticleIdent: Q39372

 There is a documentation error on Page 77 of the "Microsoft Macro
 Assembler 5.1 Reference" manual (spiral-bound book). In the
 next-to-bottom big box, the MOV mem,accum and MOV accum,mem formats of
 the MOV instruction are incorrectly documented. The manual describes
 the binary format of these instructions as 101000dw, where a value of
 1 for d means to move from memory to AX and 0 for d means to move from
 AX to memory (as described on Page 27 of the same manual).

 This is reversed, as shown on Page 3-118 of "Intel's iAPX 86/88,
 186/188 User's Manual (Programmer's Reference)" and as assembled
 properly by MASM.

 Note: The Intel manual shows the bit patterns for these two types of
 the instruction separately. The memory to AX form has bit 1 (the d bit
 in our documentation) set to 0; the AX to memory form has bit 1 set to
 1.


 168. Warnings and Incorrect Code from Register Mismatch

 Product Version(s): 5.10
 Operating System:   MS-DOS
 Flags: ENDUSER |  buglist5.10
 Last Modified: 12-JAN-1989    ArticleIdent: Q39373

 The code below is correctly flagged as an error in MASM Version 5.00,
 but is passed in Version 5.10.

 Macro Assembler Version 5.10 fails to generate an error on the MOV
 instruction using the 8-bit registers (AH, BH, CH, DH, AL, BL, CL, DL)
 with segement registers (CS, DS, ES, SS). The code generated is also
 in error. Each of the (8-bit) byte registers maps to the set (SP, DI,
 BP, SI, AX, BX, CX, DX).

 "Warning A4057: Illegal size for operand" is incorrectly generated.
 The correct message should be "Error A2019: Wrong type of register."

 Microsoft has confirmed this to be a problem in Version 5.10. We are
 researching this problem and will post new information as it becomes
 available.

 The following sample code demonstrates the problem:

 _TEXT   segment word public 'CODE'
                                 ; Generated code
         mov     ds, ah          ; mov   ds, sp
         mov     ds, bh          ; mov   ds, di
         mov     ds, ch          ; mov   ds, bp
         mov     ds, dh          ; mov   ds, si

         mov     ds, al          ; mov   ds, ax
         mov     ds, bl          ; mov   ds, bx
         mov     ds, cl          ; mov   ds, cx
         mov     ds, dl          ; mov   ds, dx

         mov     ah, 4ch
         int     21h
 _TEXT   ends
         end


 169. RET Statement Label Appears on RET Listing, Not on First POP

 Product Version(s): 5.10   | 5.10
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified: 12-JAN-1989    ArticleIdent: Q39374

 When the /LA option is used to list an RET statement that has a label
 and is contained in a PROC that has a USES clause and/or parameters,
 the label for the RET statement will be shown in the listing on the
 RET rather then on the first POP generated by MASM for the RET.

 Although the listing looks incorrect, the code generated and the value
 of the label are both correct. A jump to the label will in fact go to
 the first POP instruction, not directly to the RET instruction.

 Because the generated code is correct, no workaround is necessary to
 produce properly assembled code. A workaround to produce correct
 listings is to move the label to an otherwise blank line just before
 the RET instruction, as shown below.

 The USES clause tells MASM which registers the PROC changes. MASM then
 generates appropriate PUSH instructions at the PROC entry and POP
 instructions just before each RET. Using parameters on the PROC
 statement also causes PUSH and POP instructions for BP to be
 generated. When the /LA option is used to show the added instructions
 generated for the RET instruction, the listing shows the original
 source line, including the label, after the POP instruction(s) which
 are inserted by MASM. However, MASM assembles the code correctly so
 that the label actually refers to the first added POP instruction.
 Running the program under CodeView, checking the object code generated
 for jumps, and checking the value of the label on the RET in the
 symbol listing at the end of the program all confirm that MASM is
 producing correct code.

 The workaround to produce a correct listing is to change

    JUMPHERE:   RET

 to the following:

    JUMPHERE:
                RET

 When this is done, the label will appear before the POP instructions.

 The sample code below illustrates the problem. Note: The the first
 three lines are necessary for using the "USES" directive. The
 following is the sample code:

         dosseg
         .model small,c
         .code
 foo     proc uses si di bp
         jz there
 there:  ret
 foo     endp
         end
 ........................................................................
 masm /LA ... :

        1                                        dosseg
        2                                        .model small,c
        3                                assume cs:@code,ds:@data,ss:@data
        4                                        .code
        5 0000                           _TEXT segment 'CODE'
        6 0000                           foo     proc uses si di bp
        7 0000  56                       push SI
        8 0001  57                       push DI
        9 0002  55                       push BP
       10 0003  74 00                            jz there
       11 0005  5D                       pop BP
       12 0006  5F                       pop DI
       13 0007  5E                       pop SI
       14 0008  C3                       there:  ret
       15 0009                           foo     endp
       16                                        end
       17 0009                           @CurSeg ends


 170. SMSW, SGDT, SIDT, SLDT, VERR, VERW Do Not Assemble

 Product Version(s): 5.00   | 5.10
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER | docerr buglist5.00
 Last Modified: 12-JAN-1989    ArticleIdent: Q39439

 The ".286" and ".386" operands do not allow the following to assemble:

    SMSW, SGDT, SIDT, SLDT, VERR, and VERW

 One or two error messages are generated for each occurrence of these
 instructions.

 Microsoft has confirmed this to be a problem in Version 5.00. We are
 researching this problem and will post new information as it becomes
 available.

 Page 412 (section 20.3) of the "Microsoft Macro Assembler Programmer's
 Guide" is incorrect in saying that these instructions require
 "privileged mode." Also, SMSW is spelled incorrectly (as "SMCW").
 These instructions are allowed in all modes; however, behavior may
 differ between real and protected modes.

 The reference guide is also incorrect on several addressing points.
 See the Intel "80286 and 80287 Programmer's Reference Manual" for more
 information.

 The following is a sample program:

 ........................................................................
 ; The following program demonstrates :
 dosseg
 .286
 .model large
 .data
 table   dw 64 dup (?)
 .code
 start:
         SMSW ax
         SGDT table
         SIDT table
         SLDT ax
         VERR ax
         VERW ax

         end start

 ......................................................................

 C> masm test,,,;
 Microsoft (R) Macro Assembler Version 5.10
 Copyright (C) Microsoft Corp 1981, 1988.  All rights reserved.

 test.ASM(6): error A2105: Expected: instruction, directive, or label
 test.ASM(7): error A2105: Expected: instruction, directive, or label
 test.ASM(8): error A2105: Expected: instruction, directive, or label
 test.ASM(9): error A2105: Expected: instruction, directive, or label
 test.ASM(10): error A2105: Expected: instruction, directive, or label
 test.ASM(11): error A2105: Expected: instruction, directive, or label

   24002 Bytes symbol space free

       0 Warning Errors
       6 Severe  Errors
 .......................................................................


 171. MASM Supports the 386SX Chip

 Product Version(s): 5.10   | 5.10
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified: 12-JAN-1989    ArticleIdent: Q39440

 Microsoft Macro Assembler supports the new 386SX chip, which takes a
 32-bit program and processes it to 16-bit. The hardware bus is
 different, but the machine instructions are the same.


 172. The ORG Directive and Actual Offsets

 Product Version(s): 5.10
 Operating System:   MS-DOS
 Flags: ENDUSER |
 Last Modified: 12-JAN-1989    ArticleIdent: Q39441

 The ORG directive in MASM does not necessarily produce an actual
 offset that matches the offset specified by "ORG XXX". For example, if
 you use "ORG 100h" in your program, the following code will not always
 begin at the 100h offset relative to the start of the segment.

 When you are using a .COM source file and there is only one module,
 the "ORG 100h" will result in an actual offset of 100h for the code
 that follows the ORG statement. This behavior also occurs with
 segments with AT combine type (in which case segments are not combined
 by the linker, and no data or code is defined).

 However, if you have multiple modules and/or you are not dealing with
 a .COM source file, the "ORG 100h" produces an actual offset, which is
 somewhat greater than 100h.

 This behavior occurs because the linker, in these circumstances, will
 do some padding that you have no control over.

 In the following illustration (which deals with the source modules
 below), note that the ORG instruction increments the local offset by
 100h, resulting in the offset of the PUSH instruction in foo2 being
 100h (that's what it would report in the listing file). However, when
 these modules are linked, all the portions of segment code are
 concatenated. Thus, foo2.asm:code:100h is converted into code:113h.
 The order of concatenation is the order of linking.

 The following example illustrates the scenario:

      Actual                      Offset
      offset                      from start
      from                        of segment
      code                        code in module
      -------                     ---------------
              +-----------------+
      0117    |   ret           | 0105
      0116    |   pop           | 0103    foo2.asm
      0114    |   mov           | 0101
      0113    |   push          | 0100
      0013    |   org           | 0000
              +-----------------+
      0012    |   ret           | 0004
      0011    |   pop           | 0003    foo1.asm
      000F    |   mov           | 0001
      000E    |   push          | 0000
              +-----------------+
      000C    |   int           | 000C
      0009    |   mov           | 0009    foomain.asm
      0006    |   call          | 0006
      0003    |   call          | 0003
      0000    |   mov           | 0000
              +-----------------+
                  segment code

 |---------------foomain.asm:       |---------------foo1.asm:
   code segment                         PUBLIC  _foo
   assume cs:code                       code segment
                                        assume cs:code
           mov     ax, 0a0ah            _foo proc

           extrn   _foo:proc                push    bp
           extrn   _foo2:proc               mov     bp, sp

           call    _foo                     pop     bp
           call    _foo2                    ret

           mov     ax, 4c00h            _foo    ENDP
           int     21h                  code ends
   code ends

           END                          END

 |---------------foo2.asm:
    code segment
    assume cs:code
            org     100h

            PUBLIC  _foo2
    _foo2    PROC

            push    bp
            mov     bp, sp

            pop     bp
            ret

    _foo2    ENDP
    code ends
            END


 173. asub and ctest Defined Incorrectly in MASM Programmer's Guide

 Product Version(s): 5.10   | 5.10
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER | docerr
 Last Modified: 12-JAN-1989    ArticleIdent: Q39442

 There is a documentation error on Page 91 of the "Microsoft Mixed
 Language Programming Guide" for Microsoft C, FORTRAN, and MASM. In
 figure 6.7, the assembly procedure "asub" should be defined as

    _asub PROC

 not as follows:

    PROC asub

 Also, the call to "ctest" should appear as

    call _ctest

 not as follows:

    call ctest


 174. Use of Parentheses for Operator Precedence Necessary

 Product Version(s): 5.00   | 5.10
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified: 12-JAN-1989    ArticleIdent: Q39443

 You may be able to correct "Illegal size for operand" errors by
 careful use of parentheses.

 Microsoft has confirmed this to be a problem in Version 5.10. We are
 researching this problem and will post new information as it becomes
 available.

 The following code demonstrates warnings, errors, and their solution:

 dosseg
 .model small,c
 .data

 .code
 foo PROC buffer:FAR PTR BYTE

            mov     bx, WORD PTR buffer[0]
            mov     ds, WORD PTR buffer[2]

 ; MASM gives an operand-size error. This is a precedence problem that
 ; you can correct with parentheses:

            mov     bx, WORD PTR (buffer[0])
            mov     ds, WORD PTR (buffer[2])

 foo ENDP

 end
 ......................................................................
 masm test,,,;
 Microsoft (R) Macro Assembler Version 5.10
 Copyright (C) Microsoft Corp 1981, 1988.  All rights reserved.

 test.ASM(9): warning A4057: Illegal size for operand
 test.ASM(10): error A2057: Illegal size for operand

   23666 Bytes symbol space free

       1 Warning Errors
       1 Severe  Errors
 .......................................................................


 175. The Stack Grows into Low Memory

 Product Version(s): 5.10
 Operating System:   MS-DOS
 Flags: ENDUSER | docerr
 Last Modified: 12-JAN-1989    ArticleIdent: Q39444

 On Page 300 of the "Microsoft Macro Assembler Programmer's Guide," the
 first paragraph incorrectly states that "it is possible to return the
 stack to its original status by subtracting the correct number of
 words from the SP register." Instead, after pushing values onto the
 stack, it is possible to return the stack to its original status by
 adding the correct number of words to the SP register.

 Also, the first example on Page 300 uses the SUB command to restore
 the stack pointer. The ADD command should be used instead.


 176. The IN Instruction Receives Data from a Port

 Product Version(s): 5.10
 Operating System:   MS-DOS
 Flags: ENDUSER | docerr
 Last Modified: 12-JAN-1989    ArticleIdent: Q39445

 On Page 300 of the "Microsoft Macro Assembler Programmer's Guide," the
 fourth paragraph incorrectly states that the IN instruction is used to
 send data to a port. Instead, the IN instruction is used to receive
 data from a port.


 177. Division Operators "/" with .186, .286, and .386

 Product Version(s): 5.00 5.10 | 5.10
 Operating System:   MS-DOS    | OS/2
 Flags: ENDUSER | calculation operator, division
 Last Modified: 12-JAN-1989    ArticleIdent: Q39446

 To use calculation operators on constant values larger than 17 bits,
 ".386" has to be enabled. Otherwise, the assembler may generate error
 "A2029 : Division by 0 or overflow."

 Please refer to Page 174 of the "Microsoft Macro Assembler
 Programmer's Guide" in the section "Using Operators" for more specific
 information. The program below demonstrates this information.

 When 80386 is enabled by using .386, the program will be assembled
 without any error message. Then the program has to run on a 80386
 machine.

 The following is the sample program:

     ; sample program
     .186
     .model small
     .data
     dd  989680h/4h          ; the constant value is more than 17 bits.
     .code
     end
 ...................................................................
 masm test,,,;
 Microsoft (R) Macro Assembler Version 5.10
 Copyright (C) Microsoft Corp 1981, 1988.  All rights reserved.

 test.ASM(7): error A2029: Division by 0 or overflow

   23918 Bytes symbol space free

       0 Warning Errors
       1 Severe  Errors


 178. Comparing String Arguments in Macros

 Product Version(s): 5.00 5.10 | 5.10
 Operating System:   MS-DOS    | OS/2
 Flags: ENDUSER | eq if directive ifidn arguments
 Last Modified: 12-JAN-1989    ArticleIdent: Q39517

 When using IF directives, relational operators could be used to form
 the conditions. Note: The relational operators treat the expressions
 as follows:

    EQ and NE treat their operators as 16-bit numbers

    LT, LE, GT, and GE treat their operators as 17-bit numbers.

 The relational operators cannot be used for comparing string
 arguments. It is often necessary to compare string arguments in
 MACROs. IFIDN and IFDIF directives are available for this purpose.
 IFIDN grants assembly if two arguments are identical; IFDIF grants
 assembly if two arguments are different. The syntax is as follows:

     IFIDN <argument1>,<argument2>
     IFDIF <argument1>,<argument2>

 Please refer to "Microsoft Macro Assembler Programmer's Guide" in the
 section "Assembling Conditionally" for more specific information.


 179. EXTR Examples incorrect in MASM Programmer's Guide

 Product Version(s): 5.10   | 5.10
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER | DOCERR
 Last Modified: 12-JAN-1989    ArticleIdent: Q39518

 There are a number of errors in example 2 on Page 90 of the "Microsoft
 MASM 5.1 Programmer's Guide."

 The following lines

    EXTR    xvariable:FAR

    EXTR    xprocedure:PROC

 should be as follows:

    EXTRN   xvariable:FAR

    EXTRN   xprocedure:PROC

 Please use this as a model. It was not intended to be linked and run.


 180. Using Conditional-Assembly to Assemble for COM or EXE File

 Product Version(s): 4.00 5.00 5.10
 Operating System:   MS-DOS
 Flags: ENDUSER |
 Last Modified: 12-JAN-1989    ArticleIdent: Q39519

 By using assembler symbols, macros, and conditional-assembly,
 assembling a file to a COM or EXE file is easy. The following is the
 solution:

 ifdef   COM
 ending  macro   text
         end     start
 endm
 else
 ending  macro   text
         end
 endm
 endif

 _text   segment 'code'
         assume cs:_text
 start:  mov     ax, 08000h
         mov     ds, ax
         ...
 _text   ends

         ending

 Use MASM /DCOM /MX foo.asm for assembling into a COM file. Or use
 MASM /MX foo.asm for EXE files.

 This example assembles code depending on whether the assembler symbol
 COM is defined or not. COM files must have an entry point so the END
 directive requires a start address; whereas, EXE files do not require
 an entry point.

 Under MASM Version 4.00, you can accomplish this with a simple
 conditional-assembly block at the end as follows:

 ifdef   com
         end     start
 endif
         end

 MASM Version 5.10 flags this as an error, which it should according to
 Page 79 of the "Microsoft Macro Assembler 5.1 Programmer's Guide."
 "Any statements following the END directive are ignored by the
 assembler." The error occurs because the endif is not being recognized
 and "Number of open conditionals: 1" error is displayed.


 181. Passing an Integer from C to MASM, Returning a Double

 Product Version(s): 5.10
 Operating System:   MS DOS
 Flags: ENDUSER | S_C
 Last Modified: 12-JAN-1989    ArticleIdent: Q39520

 The following MASM program shows how to receive an integer from a C
 program, then pass the value back to the C program as a double. Note:
 This routine was composed for the large-memory model and assumes that
 a coprocessor exists on the system.

 Below is the C program that calls the MASM routine. It should be
 compiled for large-memory model and either 8087 or emulator-math
 library.

 The following is the sample program:

 #include <stdio.h>

 extern double abc(int x);

 main()
 {

 int x;
 double y;

 x=7;
 y=abc(x);
 printf("%lf is the value of y\n", y);

 }

 Below is the MASM routine. The main piece to this program is the
 filled instruction that transforms the integer to a floating-point
 real, then pushes the value on the co-processor stack. The other point
 is to obtain the segment and offset of the __fac variable. Anything
 over 2 bytes cannot be stored in the AX register, so C will look to
 the memory location pointed to by DX:AX.

 The following is the MASM routine:

         .MODEL LARGE,C ;C so Masm will use C naming conventions
         .DATA
         .CODE
 EXTRN _fac:QWORD       ; __fac is the global variable used by C
                        ; for storing floating point accumulations
         PUBLIC  abc
 abc     PROC FAR
         push    bp
         mov     bp,sp
         fild    WORD PTR [bp+6]
         mov     dx,SEG _fac
         mov     es,dx
         fstp    QWORD PTR es:_fac  ; this pops the value off of
         mov     ax,OFFSET _fac     ; the co-processor and puts it
         fwait                      ; in __fac
         mov     sp,bp
         pop     bp
         ret

 abc     ENDP
         END


 182. How to Declare Externals in MASM

 Product Version(s): 5.00 5.10 | 5.10
 Operating System:   MS-DOS    | OS/2
 Flags: ENDUSER |
 Last Modified: 12-JAN-1989    ArticleIdent: Q39523

 The following are the rules for declaring externals in MASM:

 1. NEAR code labels must be declared in the code segment
    from which they are accessed.

 2. Although FAR code labels can be declared anywhere in the source
    code, it is recommended they be declared outside of any segments.
    You may declare them at the top of your program after the .MODEL
    directive.

 3. Any external data in the DGROUP data segment, must be declared in
    the segment in which it is defined. You may need to create a dummy
    data segment for the external declaration.

 4. Data items declared in .FARDATA segment, that need to be referenced
    as externals, should be declared out of any segments. Otherwise,
    fixup-overflow errors may occur during linking. Note: This
    conflicts with the rules indicated on Page 162 of "Microsoft Macro
    Assembler Programmer's Guide" for Versions 5.x.


 183. TSR in Assembly

 Product Version(s): 5.00 5.10
 Operating System:   MS-DOS
 Flags: ENDUSER |
 Last Modified: 12-JAN-1989    ArticleIdent: Q39524

 Terminate and stay resident (TSR) programs consist of RAM-resident and
 transient portions. When a TSR is executed, the transient portion
 initializes data and installs the interrupt handlers; the transient
 portion only takes place once. On exit, the transient code executes a
 MS-DOS TSR function to leave the RAM-resident portion in memory. The
 RAM-resident portion of the code is now ready and waiting to be
 invoked.

 Typically a TSR is invoked by another program by a sequence of
 keystrokes, or by a system interrupt. The following is an example of a
 TSR that displays the system time in the upper-right corner of the
 screen. During the transient portion, the TSR replaces the
 system-timer interrupt code with its own code and saves the old
 address so the original system-timer interrupt can be invoked by the
 new code. The system-timer interrupt occurs approximately 19 times a
 second, and is required for the system to execute correctly. The
 RAM-resident portion of the TSR first invokes the original
 system-timer interrupt, then calls Interrupt 1AH function 02H to
 obtain the current time. The time is then displayed in the upper-right
 corner of the screen.

 The following sample program demonstrates this behavior:

 _text   segment para public 'CODE'
         org     100h
         .286                    ; Used for PUSHA and POPA intstuctions
                                 ; If 8086 you will need to explictly
                                 ; push all the registers on the stack
         assume  cs:_text,ds:_text
 start:
         jmp     initialize
 old_timer       dd  ?           ; space for old timer vector
 timer_int       proc    far
         sti                     ; enable interupts
         assume  ds:nothing
         pushf                   ; put flags on stack
         call    old_timer
         push    ax              ; save registers
         push    cx
         push    dx
         mov     ah,02h
         int     1ah             ; get time  Returns:
                                 ; ch = hours in BCD
                                 ; cl = minutes in BCD
                                 ; dh = seconds in BCD
                                 ; dl  ignored
         call    print_drv       ; call time to read time
         pop     dx
         pop     cx
         pop     ax              ; restore registers
         iret
 timer_int       endp

 print_drv       proc    near
         assume  cs:_text,ds:_text
         pusha                   ; Save registers
         push    es              ; Save Segment registers
         push    ds
         mov     bx,cs
         mov     ds,bx           ; data seg = code seg
         call    getpos
         push    bx              ; save cursor on stack
         mov     bx,41h
         call    setpos          ; move cursor to right hand corner
         call    display_time
         pop     bx
         call    setpos          ; restore cursor
         pop     ds              ; restore Segment registers
         pop     es              ; restore registers
         popa
         ret
 print_drv       endp

 display_time proc near
         assume cs:_text,ds:_text
         push   ax
         push   bx
         push   cx
         push   si
         mov    ax,cs           ; Data Seg = Code Seg
         mov    ds,ax
 ;   Output hours
         mov        bx,cx       ; move hours to bx
         mov        al,bh
         mov        cl,4        ; Set shift count to 4
         shr        ax,cl       ; rotate to low nybble
         and        ax,000FH    ; Mask out all but low nybble
         mov        si,ax       ; Use low nybble as index into
         mov        al,byte ptr asciitab  [si] ; asciitable
         call       dchar       ; print 1st digit of hours
         mov        al,bh
         and        ax,000FH    ; Mask out all but low nybble
         mov        si,ax       ; Use low nybble as index into
         mov        al,byte ptr asciitab  [si] ; asciitable
         call       dchar
         call       dcolon

 ;   Output Minutes
         mov        al,bl        ; move hours to bx
         mov        cl,4         ; Set shift count to 8
         shr        ax,cl        ; rotate to low nybble
         and        ax,000FH     ; Mask out all but low nybble
         mov        si,ax        ; Use low nybble as index into
         mov        al,byte ptr asciitab  [si] ; asciitable
         call       dchar        ; print 1st digit of hours
         mov        al,bl
         and        ax,000FH     ; Mask out all but low nybble
         mov        si,ax        ; Use low nybble as index into
         mov        al,byte ptr asciitab  [si] ; asciitable
         call       dchar        ; print 1st digit of hours
         call       dcolon

 ;   Output Seconds
         mov        al,dh        ; move hours to bx
         mov        cl,4         ; Set shift count to 4
         shr        ax,cl        ; rotate to low nybble
         and        ax,000FH     ; Mask out all but low nybble
         mov        si,ax        ; Use low nybble as index into
         mov        al,byte ptr asciitab  [si] ; asciitable
         call       dchar        ; print 1st digit of hours
         mov        al,dh
         and        ax,000FH     ; Mask out all but low nybble
         mov        si,ax        ; Use low nybble as index into
         mov        al,byte ptr asciitab  [si] ; asciitable
         call       dchar

         pop     si
         pop     cx
         pop     bx
         pop     ax
         ret
 display_time endp

 ; Get the current cursor position and return it in BX
 getpos  proc    near
         push    ax
         push    cx
         push    dx

         mov     ah,03h
         mov     bh,0    ; page zero
         int     10h
         mov     bx,dx   ; Return the positon in BX

         pop     dx
         pop     cx
         pop     ax
         ret
 getpos  endp

 ; Set the current cursor postion to the vaule in BX
 setpos  proc    near
         push    ax
         push    bx
         push    dx

         mov     ah,02h  ; use int 10h function 2 to set cursor position
         mov     dx,bx
         mov     bh,0
         int     10h

         pop     dx
         pop     bx
         pop     ax
         ret
 setpos endp

 dcolon  proc near
         mov     al,':'
         call    dchar
         ret
 dcolon  endp

 ; Display the character contained in Al
 dchar   proc near
         push    ax
         push    bx
         mov     bh,1
         mov     ah,0eh
         int     10h
         pop     bx
         pop     ax
         ret
 dchar   endp

 asciitab:     db      '0123456789',0
 ; The following section  of code executes during initial program
 ; execution.
 initialize:
                 assume ds:_text
                 mov bx,cs               ; data_seg = code_seg
                 mov ds,bx

                 mov     al,08h          ; get vector of interrupt timer
                 mov     ah,35h          ;
                 int     21h
                 mov     word ptr old_timer, bx ; save vector
                 mov     word ptr old_timer[2],es

                 mov     dx,offset timer_int
                 mov     al,08h
                 mov     ah,25h          ; replace system interrupt
                 int     21h             ; with our timer_int

                 mov     dx,offset initialize  ; terminate and stay resident
                 int     27h                   ; int 21h would work
 _text   ends
         end start


 184. ARPL (Protected Mode Only) Produces Incorrect Code

 Product Version(s): 5.00   | 5.10
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER | buglist5.10
 Last Modified: 12-JAN-1989    ArticleIdent: Q39525

 MASM Versions 5.10 and earlier have the register operands reversed for
 ARPL as follows:

    ARPL AX, CX

 It should have an operand byte of C1 instead of C8.

 Microsoft has confirmed this to be a problem in Version 5.10. We are
 researching this problem and will post new information as it becomes
 available.

 The following code demonstrates this problem and should assemble to
 "63 C1":

 dosseg
 .model small
 .386p
 .code

 start:
         ARPL AX, CX
         end start

 .........................................................................
        1                                dosseg
        2                                .model small
        3                                assume cs:@code,ds:@data,ss:@data
        4                                .386p
        5                                .code
        6 0000                           _TEXT segment 'CODE'
        7
        8 0000                           start:
        9 0000  63 C8                            ARPL AX, CX
       10                                        end start
       11 0002                           @CurSeg ends
 ..........................................................................


 185. How to Declare External struct in MASM

 Product Version(s): 5.00 5.10 | 5.10
 Operating System:   MS-DOS    | OS/2
 Flags: ENDUSER | struc external
 Last Modified: 12-JAN-1989    ArticleIdent: Q39526

 Question:

 In mixed-language programming with MASM and C, how can I declare an
 external variable that is of a "struct" type declared in the C module?

 Response:

 You may declare a type with STRUC directive in your MASM module with
 the same memory-storage template as the "struct" type declared in your
 C module. You also can declare the variable as external with WORD type
 if it is a near data, or DWORD type if it is a far data.

 Note: In C, the packed struct type and the unpacked struct type have
 different storage in memory. As a result, the template constructed in
 your MASM module has to match the memory storage exactly. (See the
 sample program below.) Please refer to the "Microsoft Mixed-Language
 Programming Guide" (Section 9.2, "Structure, Records, and User-Defined
 Types") for more specific information regarding the C storage method.

 You can access the fields of the structure in the assembly module by
 using the "." operator.

 The sample program below demonstrates this information:

 /* sample program, c module */

 struct record {
     char byte_1 ;
     unsigned int word_1 ;
     char byte_2 ;
     unsigned int word_2 ;
     } rec = {0x41, 0xffff, 0x42, 0xeeee} ;

 void proc_rec(void) ;

 main()
 {
 proc_rec() ;
 }

 /* end of the C module */

 Any template you may create in MASM with STRUC directive has to
 have unique field names through the MASM module. The field names
 represent the offset relative to the beginning of the structure. They
 do not have to be literally the same field names of the structure
 defined in the C module.

 The following sample program demonstrates this information:

 ; sample program, MASM module

         .model small
         DOSSEG
         .data
 foo     struc
 byte_1  db   ?      ; if dw is used, next padding byte is not needed.
 junk_1  db   ?      ; necessary padding, unused byte
 word_1  dw   ?
 byte_2  db   ?
 junk_2  db   ?      ; necessary padding, unused byte
 word_2  dw   ?
 foo     ends

 extrn   _rec:word       ; extrn  _rec:foo   is illeage

         .code
         public _proc_rec
 _proc_rec  proc  near
         mov ax, _rec.word_1
         mov bx, _rec.word_2
         mov cl, _rec.byte_1
         mov ch, _rec.byte_2
         ret
 _proc_rec  endp
         end

 ; end of Masm module


 186. DUP Is a Reserved Word in MASM

 Product Version(s): 5.10   | 5.10
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER | docerr
 Last Modified: 12-JAN-1989    ArticleIdent: Q39527

 The table of reserved words in MASM on Page 69 of the "Microsoft Macro
 Assembler Programmer's Guide" does not include DUP. DUP is an operator
 for defining arrays, buffers and other data structures consisting of
 multiple data objects of the same size. DUP cannot be used as a
 variable. For example, the following statement allocates the string
 "Test " five times for a total of 20 bytes:

    DB   5 DUP ("Test ")


 187. Error A2105 with PUSHA and POPA Instructions

 Product Version(s): 5.10
 Operating System:   MS-DOS
 Flags: ENDUSER |
 Last Modified: 12-JAN-1989    ArticleIdent: Q40192

 MASM generates the following error message if the PUSHA or POPA
 instructions are used without a prior .186, .286, or .386 directive:

    A2105: Expected: instruction, directive, or label

 This error does not clearly indicate exactly what the problem is. By
 default, the Macro Assembler generates code for the 8086 processor,
 for which these instructions have not been implemented.

 Page 302 of the "Macro Assembler 5.1 Programmer's Guide" states that
 these instructions are implemented only for the 80186, 80286, and
 80386 processors.

 If you have an 8086-based computer, you will have to push and pop the
 registers individually, using PUSH and POP. If you have a 80186,
 80286, or 80386-based computer, add the appropriate directive to the
 code.


 188. Intra-Segment Near Calls in MASM

 Product Version(s): 4.00 5.00 5.10
 Operating System:   MS-DOS
 Flags: ENDUSER |
 Last Modified: 12-JAN-1989    ArticleIdent: Q40095

 Question:

 When there is an intra-module near call in a MASM program, as in the
 following example, why does the assembler generate a self-relative,
 intra-segment fixup?

 foo proc near
     ...
 foo ends

 bar proc near
     call foo
 bar endp

 These are unnecessary as indicated in Intel's "8086 Relocatable
 Object Module Formats," Appendix 4, which states the following:

    "Self-Relative references within a single LSEG do not require a fixup,
    the translator puts the appropriate value in LOCATION."

 The assembler does not have this problem with near JMPs, only with
 CALLs.

 Response:

 It is correct that Intel states that it is not necessary to perform a
 fixup for intra-segment calls. However, it is not forbidden to do so.
 Microsoft is making efforts to optimize the assembler without causing
 a lack of control by the programmer over the code. While some people
 desire a given optimization, there are others who would decry it as a
 loss of control over their code. There are keywords that allow you to
 force various types of calls and jumps such as the SHORT keyword. Yu
 may want to check these to see if they offer the control you need.

 The workaround for generation of any special opcode is to use the
 "dw" or "db" directive in the code segment. The following can be
 assembled [2A D2] or [28 D2]:

    sub dl,dl

 To get the second generation, you must enter the following:

    db 28h, 0d2h


 189. Phase Error Generated on Instructions Using Equate Variable

 Product Version(s): 5.10   | 5.10
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified: 20-APR-1989    ArticleIdent: Q40452

 When the SAVESIDI is not equated in the following code, the statements
 mov bl,q[bp] and mov bx,q+2[bp] cause a phase error on the label
 intret:

     P equ 4
     SPTR  equ 5

     ifndef SAVESIDI
     SAVESIDI equ 1
     endif

     code segment
     assume cs:code
     q       equ     (P + 4 * SAVESIDI + 2 * SPTR + 2)

     int86 proc
         mov     BL,q[BP]        ;interrupt number
         mov     BX,q+2[BP]              ;input registers
     inret:
     int86 endp
     code ends
     end

 You must define labels used in expressions on both passes. On pass 1
 SAVESIDI isn't defined, so it gets the value of 1. On pass 2 it is
 defined; therefore, you get a phase error.

 The following is the standard workaround for IFDEF label type
 statements. The added lines are highlighted by ">>".

     P equ 4
     SPTR  equ 5

     ifndef SAVESIDI
     SAVESIDI equ 1
 >>  else
 >>  SAVESIDI equ SAVESIDI
     endif

     code segment
     assume cs:code
     q       equ     (P + 4 * SAVESIDI + 2 * SPTR + 2)

     int86 proc
         mov     BL,q[BP]        ;interrupt number
         mov     BX,q+2[BP]              ;input registers
     intret:
     int86 endp
     code ends
     end


 190. Include in MASM Source Effects /Z

 Product Version(s): 5.10   | 5.10
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified: 24-APR-1989    ArticleIdent: Q40462

 After the call to the include file, you cannot use /Z options to
 generate source lines when errors occur if a MASM source file contains
 an include instruction.

 The following source demonstrates this situation if it is assembled:

 masm /Z m9.asm;

 dosseg
 .model small
 .data
 .code
     xxx ds,si
     include m8.asm
     xxx ds,si

 end

 As long as m8.asm contains any characters, the output of the assemble
 is as follows:

 Microsoft (R) Macro Assembler Version 5.10
 Copyright (C) Microsoft Corp 1981, 1988.  All rights reserved.

                                     xxx ds,si
 m9.asm(8): error A2105: Expected: instruction, directive, or label
 m9.asm(10): error A2105: Expected: instruction, directive, or label

   49254 Bytes symbol space free

       0 Warning Errors
       2 Severe  Errors

 If the instruction "include m8.asm" is commented out, the output of
 the assembler is as follows:

 Microsoft (R) Macro Assembler Version 5.10
 Copyright (C) Microsoft Corp 1981, 1988.  All rights reserved.

                                     xxx ds,si
 m9.asm(8): error A2105: Expected: instruction, directive, or label
                                     xxx ds,si
 m9.asm(10): error A2105: Expected: instruction, directive, or label

   49390 Bytes symbol space free

       0 Warning Errors
       2 Severe  Errors


 191. Erroneous 8086 Opcode for Logical AND Instruction

 Product Version(s): m5.10 5.10a | 5.10 5.10a
 Operating System:   MS-DOS     | OS/2
 Flags: ENDUSER | buglist5.10
 Last Modified: 12-JUN-1990    ArticleIdent: Q61054

 Problem:

 I bought an operating system for a V25 processor that runs with the
 INTEL 8086 instruction set. The operating system source code was
 assembled with MASM 5.10 and the .8086 directive. The instruction runs
 on an 8086 machine, but the machine with the V25 processor hangs at
 the following instruction:

       AND Word Ptr [S+10], -5 ; Opcode generated is
                               ; 83 64 0A FB

 Response:

 In Appendix A-4 of the INTEL 8086/8088 programmer's reference manual
 (1986 edition), there is no opcode for AND that begins with 83. There
 is an opcode for AND that begins with 81. The opcode for AND reads as
 follows:

    81 64 0A 00 FB

 However, there is an opcode for a sign-extended immediate instruction
 in the 80386 instruction set that has the first byte of the opcode as
 83.

 The V25 adheres strictly to INTEL's 8086 standard and will not accept
 an 80386 instruction rather than an 8086 instruction.

 Microsoft has confirmed this to be a problem in MASM Version 5.10. We
 are researching this problem and will post new information here as it
 becomes available.


 192. MASM Does Not Support 80386 Flat Model

 Product Version(s): 4.00 5.00 5.10
 Operating System:   MS-DOS
 Flags: ENDUSER |
 Last Modified: 24-APR-1989    ArticleIdent: Q40572

 The Microsoft Macro Assembler Version 5.10 does not support
 programming in the flat model. The flat model is a memory-organization
 model on the Intel 80386 chip that allows full 32-bit addressing and
 segments greater than 64K.

 Microsoft Macro Assembler supports only the tiny-, small-, compact-,
 medium-, and large-memory model. For more information on the flat
 model, consult Intel's "80386 Programmer's Reference Manual."


 193. Mnemonic Letters Indicating Types of Jumps Documentation Error

 Product Version(s): 5.00   | 5.10
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER | docerr
 Last Modified: 24-APR-1989    ArticleIdent: Q40627

 Page 336 of the "Microsoft Macro Assembler Programmer's Guide"
 incorrectly associates the mnemonic letters "G" and "L" with jumps on
 unsigned comparisons, and the letters "A" and "B" with jumps on signed
 comparisons.

 The two sets of letters should be reversed with their respective
 comparisons to form the following, correct table:

    Letter        Meaning

    J             Jump
    G             Greater than (for signed comparisons)
    L             Less than (for signed comparisons)
    A             Above (for unsigned comparisons)
    B             Below (for unsigned comparisons)
    E             Equal
    N             Not


 194. Using "Low" in Conjunction with the "Offset" Operator

 Product Version(s): 5.10
 Operating System:   MS-DOS
 Flags: ENDUSER | buglist5.10 H_MASM 5.10
 Last Modified: 24-APR-1989    ArticleIdent: Q40852

 Problem:

 When attempting to use the "low" in conjunction with the "offset"
 operator, I get the following error message:

    error message A2042: Constant expected

 The following is a code example that generates the error message:

  = 1234           data_equ equ     1234h        ;equate data
  0000             cseg     segment para public
                           assume  cs:cseg, ds:cseg  ss:stack

  0000             testlow  proc    far

  0000  E9 01FF R  start:   jmp     begin
  0003  00         data_a   db      0

  0004  11 03 R            db      11h, low offset data_a
 testlow.asm(29): error A2042: Constant expected

 Response:

 This problem has been confirmed with MASM Version 5.10. Microsoft is
 researching this problem and will post new information as it becomes
 available.

 Please note that the same function has been checked against MASM
 Versions 5.00 and 4.00, and assembled without error.


 195. Setting Page Width of Printed Listing

 Product Version(s): 5.10   | 5.10
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified: 24-APR-1989    ArticleIdent: Q42290

 The PAGE directive allows you to set the width and length of the
 printed page, or generate a page break in the listing. This is
 particularly useful when the listing wraps around to the next line and
 you have a wide carriage printer.

 The syntax is PAGE [[length],width] where length must be in the range
 of 10-255 lines and width must be in the range of 60-132 characters.
 The default page length is 50 lines and the default width is 80
 characters.

 To set the width to 132 characters, use the following command within
 the source code:

    PAGE ,132

 For more information, see Pages 243-244 of the "Microsoft Macro
 Assembler 5.1 Programmer's Guide."


 196. Direct Memory Addressing

 Product Version(s): 4.x 5.00 5.10 | 5.10
 Operating System:   MS-DOS         | OS/2
 Flags: ENDUSER |
 Last Modified: 24-APR-1989    ArticleIdent: Q42729

 Question:

 When I try to do a direct memory operation with the instruction MOV
 AX,[1000], the Macro Assembler generates a move instruction with the
 immediate value of 1000 rather than a direct memory access of the
 location 1000. How can I do a direct memory access instruction?

 Response:

 A segment register must be specified for a direct memory operand that
 contains a constant with no label, as in the following

    MOV AX,DS:[1000]

 This example will not insert a segment override prefix into the
 assemble code because the instruction uses the DS register by default.
 Use of any segment register other than the default register would
 insert the override prefix.

 For more information, see Section 14.3.1 on Direct Memory Operands,
 Page 276 in the MASM 5.10 programmer's guide.


 197. Stack Considerations When Calling Procedures in MASM

 Product Version(s): 5.10   | 5.10
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified: 30-AUG-1989    ArticleIdent: Q44512

 When calling procedures in Microsoft Macro Assembler, you must watch
 the stack manipulations within the called procedure.

 If several items are PUSHed onto the stack, they must be POPped off in
 the same number. This is necessary because when the RET is encountered
 at the end of the procedure, it expects the return address to be on
 the top of the stack.

 This problem can be avoided by temporarily storing the return address
 in a location other than the stack and then PUSHing it back on before
 the RET. However, because the results may not be consistent, this
 workaround is not recommended.


 198. MASM Calling C Making MASM Main Routine

 Product Version(s): 5.10
 Operating System:   MS-DOS
 Flags: ENDUSER |
 Last Modified: 30-AUG-1989    ArticleIdent: Q44923

 You can make a program that starts with MASM and calls C. This method
 of programming is not recommended because starting with MASM will
 mean that the C start-up code will not be executed, which may cause
 future problems calling some of the C library functions. Run-time
 error messages may be affected as well as routines that use system
 symbols.

 The following is an example of the macro-assembler main routine
 which calls a C routine.

         .MODEL LARGE,C
         .CODE
         EXTRN CSUB
 MAIN    PROC           ; Must call main (_main without ,C)
         PUSH     AX             ; Push argument on stack
         PUSH     BX             ; Push another argument
         CALL     CSUB   ; Call C subroutine
         ADD   SP,4      ; Fix-up stack after C subroutine
 MAIN ENDP
         END            ; Do not specify starting location


 199. Some Coprocessor Instructions Not Emulated

 Product Version(s): 4.x 5.00 5.10a
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified: 30-AUG-1989    ArticleIdent: Q45146

 The emulator libraries included with the languages do not support all
 coprocessor instructions. The following error message results from
 unsupported coprocessor instructions:

    run-time error M6107: MATH
    - floating-point error: unemulated

 The following is a list of unemulated coprocessor instructions:

    FBLD   -  (emulated in XENIX 386 but not MS-DOS, OS/2)
    FBSTP  -  (emulated in XENIX 386 but not MS-DOS, OS/2)
    FCOS
    FDECSTP
    FINCSTP
    FINIT  -  (emulated in XENIX 386 but not MS-DOS, OS/2)
    FLDENV -  (emulated in XENIX 386 but not MS-DOS, OS/2)
    FNOP   -  (emulated in XENIX 386 but not MS-DOS, OS/2)
    FPREM1
    FRSTOR
    FSAVE
    FSETPM
    FSIN
    FSINCOS
    FSTENV -  (emulated in XENIX 386 but not MS-DOS, OS/2)
    FUCOM
    FUCOMP
    FUCOMPP
    FXTRACT

 Also, some of the No-Wait forms of instructions are not emulated (e.g.
 FNSTENV, FNINIT).


 200. MASM: Linker Error L2002: Fixup Overflow

 Product Version(s): 5.10
 Operating System:   MS-DOS
 Flags: ENDUSER |
 Last Modified: 30-AUG-1989    ArticleIdent: Q46378

 The following message occurs when data defined in the data segment is
 accessed with a CS segment override:

 foo.OBJ(foo.ASM) : error L2002: fixup overflow at 0012 in segment _TEXT
 pos: 658 Record type: 73EE
 frm seg _TEXT, tgt seg _DATA

 Code Sample
 -----------

        .DATA
 old_dma_vect    dd      0
        .CODE
 ;
 capture proc
       .
         mov     word ptr cs:old_dma_vect,bx  ;(This line caused the error)
       .
         end capture


 201. Passing a Constant from C to Assembly with a Header File

 Product Version(s): 5.10 5.10a
 Operating System:   MS-DOS
 Flags: ENDUSER |
 Last Modified:  3-JUL-1990    ArticleIdent: Q63039

 The example below illustrates how to pass a constant value between C
 and Assembly without passing the constant as a parameter. This
 information also applies to Microsoft C for OS/2 versions 5.10 and
 6.00.

 The constant in C is given the type identifier "const" and placed in a
 header file. This makes the constant public. Within the assembly
 module, the variable is declared as "extrn" in two places.

 At the top of the assembly module it indicates to the assembler that
 the variable is declared externally. It then needs to be declared
 within the procedure. This allows the language translator (assembler)
 to provide the right correction record for the linker to resolve.

 The following code illustrates the above:

 #include <stdio.h>
 #include "test.h"     /*Header file with constant declared*/

 extern void testor();

 main()

 {

  printf("Selec is initially %xH\n", selec);

  testor();

  printf("Selec is modified to %xH\n", selec);

  }

 The contents of the header file "test.h" are as follows:

    const int selec = 0x77;

 The following is the assembly module that is called:

 extrn _selec:far               ;selec declared extrn
 dgroup    group dataseg
 dataseg   segment para public 'data'
 dataseg   ends

 codeseg   segment para public 'code'
 codeseg   ends

 codeseg   segment

           public _testo
 _testor proc far

           extrn  _selec:far            ;selec declared extrn
           push    bp
           mov     bp,sp

           assume  ds:dgroup
           mov ax, dgroup
           mov ds, ax

           lea bx, dgroup:_selec  ;underscore added for compatibility
                                  ;with C language conventions

           mov ax, word ptr dgroup:[bx] ;viewed through CodeView ax=77H

           mov word ptr[bx], 0A8H       ;value in selec changed to A8H

           pop     bp

           ret

 _testor endp

 codeseg ends

      end

 The following is the makefile used to compile and link the above
 files:

 all=1.obj 2.obj
                        ;update pseudo-target ensures a
                        ;compile and link each time make is invoked
 update: 1.c
     cl /Zi /AL /c 1.c

 update: 2.asm
     masm /Zi 2.asm;

 update: $(all)
     link /co /M  $(all),,1,/nod llibcer;


 202. MASM ALIGN Directive May Not Work Properly

 Product Version(s):
 Operating System:   5.00 5.10 5.10a | 5.00 5.10 5.10a
 Flags: MS-DOS          | OS/2
 Last Modified: 30-AUG-1989    ArticleIdent: Q46919
 ENDUSER |

 The ALIGN directive for MASM may not work properly. It aligns values 2
 bytes beyond where they should be aligned, e.g. if ALIGN 4 is being
 used, values align only at the following offsets:

     02h, 06h, 0Ah, 0Eh, ... etc.

 If ALIGN 16 (decimal) is being used, values are aligned only at the
 following offsets:

     02h, 12h, 22h, 32h, ... etc.

 This is not a problem for word alignment. ALIGN 2 has the same effect as
 the EVEN directive.

 Microsoft is researching this problem and will post new information as
 it becomes available.


 203. MASM Err Msg: Error L2002: Fixup Overflow

 Product Version(s): 5.10
 Operating System:   MS-DOS
 Flags: ENDUSER |
 Last Modified: 12-SEP-1989    ArticleIdent: Q47456

 The following message occurs when data defined in the data segment is
 overridden with a Segment Override using the code segment register:

 foo.OBJ(foo.ASM): error L2002: fixup overflow at 0012 in segment_TEXT
 pos: 658 Record type: 73EE
 frm seg _TEXT, tgt seg _DATA

 This error occurs when you incorrectly try to access data in the code
 segment rather than in the data segment in the following line:

         mov     word ptr cs:old_dma_vect,bx     ;

 The line should be as follows:

      mov        word ptr ds:old_dma_vect,bx   ;

 Code Sample:

       .DATA
 old_dma_vect    dd      0
        .CODE
 ;
 capture proc
       .
       .
       .
         mov     word ptr cs:old_dma_vect,bx     ; (INCORRECT)
      mov        word ptr ds:old_dma_vect,bx   ; (CORRECT)
       .
         end capture


 204. MASM Err Msg: REP OUTSW Is a 386-Only Instruction

 Product Version(s): 5.00 5.10 | 5.00 5.10
 Operating System:   MS-DOS    | OS/2
 Flags: ENDUSER |
 Last Modified: 30-AUG-1989    ArticleIdent: Q47504

 Using the REP OUTSW instruction generates the following error:

    A2066: Must have instruction after prefix.

 This problem occurs because the default assembly mode is 8086,
 but the REP OUTSW is a 80386 instruction.

 To enable the assembler to assemble properly, the .386 or .386P
 directive must be previously placed in the source code.


 205. Error in Macro Example in MASM 5.10 Update Manual

 Product Version(s): 5.10
 Operating System:   MS-DOS
 Flags: ENDUSER | docerr
 Last Modified:  2-MAR-1990    ArticleIdent: Q49245

 The macro example on Page Update-23 in the "Microsoft Macro Assembler
 5.1: Updates and Microsoft Editor" has an error in it. The macro in
 the example is called RESTREGS.

 The current example reads as follows:

    The INSTR directive returns the position of a string within
    another string.

     restregs    MACRO
        numloc   instr  regpushed,"#"
               .
               .
               .
                 ENDM

 The second line should read as follows:

         numloc  instr  regpushed,<#>

 This example does not work correctly on MASM Version 5.10 but does
 work on MASM Version 5.10a. This is due to a problem with the SUBSTR
 directive in MASM 5.10 with regard to assigning a string a substring
 of itself.


 206. Using Offset with a Group of Data Segments

 Product Version(s): 5.10a
 Operating System:   MS-DOS
 Flags: ENDUSER | quickassembler quick assembler qasm
 Last Modified: 16-MAR-1990    ArticleIdent: Q49246

 When using the OFFSET directive to refer to a variable defined in a
 segment that is part of a group, the offset generated is from the
 beginning of the segment instead of the beginning of the group. The
 group is defined properly and DS is assumed to be pointing to the
 group.

 This problem occurs in Microsoft Macro Assembler Version 5.10a and in
 QuickAssembler Version 2.00.

 The following example demonstrates this problem:

 dgroup   group data1,data2
          assume cs:code,ds:dgroup

 data1    segment   para  public  'data'
 var1       dw      0
            dw      0
 data1    ends

 data2    segment   para  public  'data'
 var2       dw      0
 data2    ends

 code     segment   'code'
 start:   mov       bx,offset var1
          mov       bx,offset var2         <--incorrect
          mov       bx,offset dgroup:var2  <--works all cases
          lea       bx,var2                <--also works
 code     ends
          end       start

 When the segment align type is PARA or PAGE, the above code will be
 incorrect. The offset directive generates an offset relative to the
 beginning of the segment instead of the beginning of the group. When
 the segment align type is BYTE,WORD or DWORD, the correct offset from
 the group beginning is generated.

 Please note the following:

 1. By default the Assembler uses PARA align.

 2. When a segment override is used in the OFFSET expression (as in the
    above example), the correct offset is then generated.

 3. The LEA instruction also generates the correct offset.


 207. MASM Linker Err Msg: L1083: Cannot Open Run File Under OS/2

 Product Version(s): 5.10a
 Operating System:   OS/2
 Flags: ENDUSER |
 Last Modified: 29-MAR-1990    ArticleIdent: Q49322

 When linking a Macro Assembler program that is currently running in
 another session, the linker returns the following error:

    L1083 CANNOT OPEN RUN FILE

 This error disappears when the program that is running is closed.

 This error occurs because OS/2 may want to discard the program's code
 segment and reload it later. If the linker writes a new EXE file and
 OS/2 reloads the code segment, it will be different and cause the
 accompanying problems.


 208. MASM Err Msg A2063, Name in .MODEL SMALL Not Ignored

 Product Version(s): 5.10
 Operating System:   MS-DOS
 Flags: ENDUSER | docerr
 Last Modified: 29-MAR-1990    ArticleIdent: Q49699

 Page 89 of the "Microsoft Macro Assembler 5.0 for the MS-DOS Operating
 System: Programmer's Guide" incorrectly states that the name is
 ignored if given with small or compact models.

 With .MODEL SMALL or .MODEL COMPACT, the name for code segments is not
 ignored, but does produce the following error:

    A2063: Operand Combination Illegal

 On the other hand, .MODEL MEDIUM inserts a _text or append an _text to
 a name.


 209. MASM Err Msg: A2056: Immediate Mode Illegal

 Product Version(s): 5.00 5.10 | 5.00 5.10
 Operating System:   MS-DOS    | OS/2
 Flags: ENDUSER |
 Last Modified: 29-MAR-1990    ArticleIdent: Q49701

 The following information is from Page 437 of the "Microsoft Macro
 Assembler 5.0 for the MS-DOS Operating System: Programmer's Guide":

    An immediate operand was supplied to an instruction that cannot use
    immediate data. For example, the following statement is illegal:

       mov ds,DGROUP

    You must move the segment address into a general register and then
    move it from that register to DS.


 210. PROC Directive Requires Language Parameter

 Product Version(s): 5.10   | 5.10
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER | buglist5.10
 Last Modified: 29-MAR-1990    ArticleIdent: Q49703

 If the PROC directive is used with arguments and a language specifier
 is not used, the following warning is generated:

    A4001: Extra characters on line

 The following is an example:

     .model small
     .code
     public foo
     foo proc uses di si, arg1:word
     foo endp
     end

 The statement "foo proc uses di si, arg1:word" generates the warning.

 The workaround for this problem is to specify a language parameter. To
 correct the program above, replace the statement ".model small" with
 ".model small,language" where language is either FORTRAN, PASCAL,
 BASIC, or C.

 Microsoft has confirmed this to be a problem in Macro Assembler
 Version 5.10. We are researching this problem and will post new
 information here as it becomes available.


 211. Labeling Variables with Multiple Names in MASM 5.00, 5.10

 Product Version(s): 5.00 5.10 | 5.00 5.10
 Operating System:   MS-DOS    | OS/2
 Flags: ENDUSER |
 Last Modified: 29-MAR-1990    ArticleIdent: Q49705

 You can multiply define a memory location by using the LABEL
 directive. The following information comes from Pages 136-137 of the
 "Microsoft Macro Assembler 5.0 for the MS-DOS Operating System:
 Programmer's Guide":

    name LABEL type

    The name is the symbol assigned to the variable, and type is the
    variable size. The type can be any one of the following type
    specifiers:  BYTE, WORD, DWORD, FWORD, QWORD, or TBYTE. It can also
    be the name of a previously defined structure.

 The following is an example of declaring two names for the same
 variable:

 rainbow LABEL WORD
 wizard  DW ?

 In this case, rainbow and wizard point to the same word in memory.


 212. Shifting (SHL) Using an 8-Bit Constant

 Product Version(s): 5.10   | 5.10
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified: 29-MAR-1990    ArticleIdent: Q49707

 Problem:

 Page 96 of the "Microsoft Macro Assembler for MS OS/2 and MS-DOS
 Operating Systems: Version 5.1 Update" says that I can use the
 shift-left instruction (SHL) with an 8-bit constant. Yet, when I
 assemble my source code, I get the following error:

    A2052: Improper operand type

 Response:

 The third paragraph on Page 96 states the following:

    On the 8088 and 8086, the source operand can be either CL or 1. On
    the 80186-80386 processors, the source operand can be CL or an
    8-bit constant.

 To use the 8-bit constant, you must specify that you are writing 186,
 286, or 386 code. The assembler assumes the worst and defaults to the
 8088 options and doesn't accept the 8-bit constant.

 The following code generates the error:

 .model small
 .code
 shl bl,2
 end

 To correct the problem, use the .186, .286, or .386 directive such as
 the following:

 .model small
 .286
 .code
 shl bl,2
 end


 213. Jumping to an Absolute Addresss with MASM

 Product Version(s): 5.00 5.10 | 5.00 5.10
 Operating System:   MS-DOS    | OS/2
 Flags: ENDUSER | bios rom
 Last Modified: 29-MAR-1990    ArticleIdent: Q49900

 The Microsoft Macro Assembler will not let you jump directly to a
 hexadecimal address; the jump must be done indirectly. If you try to
 assemble the following, you will receive the error message "A2038:
 left operand must have segment":

        jmp 0FFFFh:0000h

 To make this jump, you must create a pointer to point to the offset
 inside the segment in question. For example:

     bios segment at 0FFFFh
     org 0
     reset label far
     bios ends

 Then, any one of the following three jump instructions will perform
 the jump to offset 0000h within segment FFFFh (the opcode that is
 generated is EA 0000 ----):

     jmp far ptr reset
     jmp bios:reset
     jmp reset

 This process is covered on Page 101 of the "Microsoft Macro Assembler
 Programmer's Guide." The second paragraph states the following:

    An AT segment typically contains no code or initialized data.
    Instead, it represents an address template that can be placed over
    code or data already in memory, such as a screen buffer or other
    absolute memory locations defined by hardware. The linker will not
    generate any code or data for AT segments, but existing code or
    data can be accessed by name if it is given a label in an AT
    segment.


 214. Indirect Far Jump/Call in MASM 5.10

 Product Version(s): 5.10
 Operating System:   MS-DOS
 Flags: ENDUSER |
 Last Modified: 29-MAR-1990    ArticleIdent: Q50405

 The following example demonstrates how to generate an indirect far
 call or jump in MASM:

 .model large

 .data
 jumptable   dd    routine1
             dd    routine2

 .code
 start:   mov    ax,@data
          mov    ds,ax
          call   dword ptr  jumptable
          jmp    dword ptr  jumptable+4
          ret

 cseg     segment  word public 'code'
 routine1 proc
            ret
 routine1 endp

 routine2 proc
            ret
 routine2 endp
 cseg     ends

          end    start


 215. @MakeFil Macro Spelled Wrong on MASM 5.10 CodeView Tutorial

 Product Version(s): 5.10
 Operating System:   MS-DOS
 Flags: ENDUSER | MAKEFILE docerr
 Last Modified: 29-MAR-1990    ArticleIdent: Q50862

 In the file MACRO.DOC on the "Microsoft CodeView for MS-DOS with
 Tutorial" disk for Microsoft Macro Assembler Version 5.10, there is a
 documentation error that incorrectly calls the macro @MakeFil.

 The macro is defined in the DOS.INC include file, also on the MS-DOS
 CodeView disk. In the DOS.INC include file, the @MakeFil macro has
 been labeled as @MakFil, not @MakeFil.

 To use this macro correctly, either change the DOS.INC include file
 macro label to @MakeFil, or call the macro as @MakFil.


 216. Using a Macro to Determine the Current Segment

 Product Version(s): 5.10 5.10a
 Operating System:   MS-DOS
 Flags: ENDUSER |
 Last Modified: 29-MAR-1990    ArticleIdent: Q58864

 The following macro can be used to determine the segment from which
 the macro is called during assembly of a source file.

 In the following example, the "findseg" macro is called from within
 two individual segments named code1 and code2, respectively. The macro
 then uses IF statements to determine the segment. Then, depending upon
 the segment, any desired code can be assembled.

         findseg macro segname
           ifidn <code1>, <segname> ; if in segment code1
                   :                ; do what is desired
           endif

           ifidn <code2>, <segname> ; if in segment code2
                   :                ; do what is desired
           endif
           endm                     ; end macro

           findseg code1   ;macro call in segment code1
                      .
                      .
                      .
           findseg code2   ;macro call in segment code2

 Note that invoking the findseg macro with the @curseg equate as a
 macro argument will not yield a true condition for the ifidn
 expression. The value of "segname" is resolved to the string "@curseg"
 which, in the example, is identical to "code1".


 217. Sample to Test Math Coprocessor Instructions FLD FADD FSTP FST

 Product Version(s): 5.10
 Operating System:   MS-DOS
 Flags: ENDUSER |
 Last Modified: 29-MAR-1990    ArticleIdent: Q59127

 The following code was used to view coprocessor instructions on an
 80386 machine with an 80387 coprocessor. It is a combination of the
 examples on Pages 384 and 385 of "Microsoft Macro Assembler 5.1
 for the MS-DOS Operating System Programmer's Guide."

                .model small
                .386
                .387
                .stack 100h
                .data
       m1       dd   1.0
       m2       dd   2.0
                .code
       start    proc
                mov ax, @data ;load address of segment
                mov ds,  ax   ;     register
                fld   m1      ;push m1 into st(0)
                fld   m2      ;push m2 into st(0)
                fadd  m1      ;add m2 to st(0)
                fstp  m1      ;pop st(0) into m1
                fst   m2      ;copy st(0) into m2

                fld1          ;push 1 into st(0)
                fldpi         ;push pi into st(0)
                fadd          ;add st(0) and st(1)
                              ;and pop, place result in st(0)
       start    endp
                end  start

 While assembling the above code, the .386 and .387 directives must be
 placed below the .model directive to generate 16-bit segments. If
 placed above the .model directive, 32-bit segments will be generated
 and will produce erroneous results, as 32-bit segments cannot be run
 under DOS.

 While running the code through CodeView, the number 7 entered in the
 dialog box displays a dump of the present status of the chip.


 218. SYS0491/SYS1107 When Running MASM Under OS/2

 Product Version(s): 5.10
 Operating System:   MS-DOS
 Flags: ENDUSER |
 Last Modified: 29-MAR-1990    ArticleIdent: Q59266

 When assembling code with the Macro-Assembler in OS/2, there are
 certain files and libraries that need to be included, so that the code
 can be run under OS/2. These include the DOSCALLS.LIB library and the
 OS2.INC include file. Dosexit is called as opposed to the traditional
 int 21h that is used in DOS.

 The following is a template of the basics needed to have workable code
 under OS/2:

 ------------------------------------
 includelib doscalls.lib
 include os2.inc
 dosseg
       .MODEL [small,medium,large,etc.]
 extrn dosexit:far

 {BODY OF SOURCE CODE}

 call dosexit
 ------------------------------------

 A "SYS1107: The system cannot complete the process" will occur if a
 MASM executable is run without the above include libraries and files.
 A "SYS0491: The specified parameter for the session type is not
 correct" error will be generated if a MASM executable file, without
 the above include libraries and files, is brought into CodeView. The
 dosexit replaces the standard DOS int 21h exit that is normal for DOS
 MASM executables. The DOSCALLS.LIB and OS2.INC include files are
 located on the MS OS/2 TOOLS disk that comes with MASM 5.10.


 219. Problems with Using TYPE Operator and SI Index Register

 Product Version(s): 5.10 5.10a | 5.10 5.10a
 Operating System:   MS-DOS     | OS/2
 Flags: ENDUSER | buglist5.10a
 Last Modified: 29-MAR-1990    ArticleIdent: Q59374

 There is a problem when using the type operator referenced from a
 variable and the SI register.

 The following commented code can be assembled to demonstrate the
 problem.

  .model small
  .stack 800h                 ; Allocate 2K stack space
  .data
  var1 dw 0
  .code
  main proc
  mov ax,@data                ; This line and the next are required to
  mov ds,ax                   ; access the data segment properly.

  ; Each of the following CMP instructions should produce the exact same
  ; code. The first three items do not produce the correct code.
  ;
  ; The opcode portion of the instruction is 3b84 in the correct examples
  ; and 3b06 in the incorrect examples.
  ;
  ; The type operator returns a number that represents the type of an
  ; expression. This is normally the size of the variable.
  ; For example, a variable declared as dw will cause TYPE to return
  ; the number 2.

  cmp ax,var1[si]+type var1   ; Incorrect code generated
  cmp ax,var1[si]+(type var1) ; Incorrect code generated
  cmp ax,var1[si]+[type var1] ; Incorrect code generated
  cmp ax,type var1+var1[si]   ; correct code generated
  cmp ax,var1[si+type var1]   ; correct code generated
  cmp ax,var1[si]+2           ; correct code generated
  cmp ax,var1[si+2]           ; correct code generated

  main endp
  end main

 Microsoft is researching this problem and will post new information
 here as it becomes available.


 220. Assembly Main Module Calling a C Function

 Product Version(s): 5.10
 Operating System:   MS-DOS
 Flags: ENDUSER | S_QuickASM
 Last Modified: 29-MAR-1990    ArticleIdent: Q59438

 It is possible to call C function from an Assembly main program. It is
 not recommended because the functionality of the C code will be
 limited. Since most C run-time functions call either the C startup
 code or the C stack check routine, it usually is not possible to make
 any C run-time calls.

 When compiling the C source code, it is important to use the /Gs
 switch to disable stack checking and add the following line to the C
 source code to tell the compiler/linker to not link in the startup
 code.

    int _acrtused = 0;

 The following is sample code to demonstrate how to write an Assembly
 main module calling a C function.

 Code Example
 ------------

 ; Assembly switch: MASM /Mx

 .MODEL MEDIUM,C

   EXTRN  ptrmsg:PROC

 .STACK 100h

 .DATA
   arg1 DB 65
   arg2 DW 5

 .CODE

 main   PROC
        mov   ax, @data           ; Set up DGROUP
        mov   ds, ax              ; DS pointing to DGROUP
        xor   ax, ax              ; Clear ax register
        mov   ax, OFFSET arg2
        push  ax                  ; Push second argument
        mov   ax, OFFSET arg1
        push  ax                  ; Push first argument
        call  ptrmsg              ; Call C function
        add   sp,4                ; Restore stack pointer
        mov   ax, 4C00h
        int   21h                 ; Terminate program
 main   ENDP
        END

 -------------------------------

 /* Compiler line: cl /Gs /c /AM      */

 int _acrtused = 0;             /* Do not bring in the startup code */

 void ptrmsg (char *a, int *b)
 {
     *a += 1;
     *b += 1;
 }


 221. "A4100: Impure Memory Reference" Incorrectly Generated

 Product Version(s): 5.00 5.10 5.10a | 5.00 5.10 5.10a
 Operating System:   MS-DOS          | OS/2
 Flags: ENDUSER | buglist5.10
 Last Modified: 29-MAR-1990    ArticleIdent: Q59567

 The /P option tells MASM to generate warning messages if data is
 stored in the code segment when privileged instructions are in use.

 Writing data to the code segment is acceptable in real mode; however,
 it may cause problems in protected mode. If MASM is invoked with the
 /P option and finds an impure memory reference, such as in the
 following code

                .code
        c_word  DW        ?
                .
                .
                mov       cs:c_word,data

 it will generate a warning similar to the following:

    filename.asm(???): warning A4100: Impure memory reference

 MASM may incorrectly generate the warning message. The following
 example demonstrates this problem:

         .model small
         .286p
         .code

         mov     al,cs:[bp]
         mul     word ptr cs:[bp+2]
         end

 MASM incorrectly flags the line that does the multiplication. MASM
 also incorrectly generates the A4100 warning message if the .286,
 .386, and .386p directives are in effect.

 Microsoft has confirmed this to be a problem in Version 5.10. We are
 researching this problem and will post new information here as it
 becomes available.


 222. LOCAL Directive with a Structure

 Product Version(s): 5.10 5.10a | 5.10 5.10a
 Operating System:   MS-DOS     | OS/2
 Flags: ENDUSER | buglist5.10 fixlist5.10a
 Last Modified: 10-JUL-1990    ArticleIdent: Q59585

 Problem:

 On Page Update-42 of the "Microsoft Macro Assembler for MS OS/2 and
 MS-DOS Operating Systems Version 5.1 Update" manual, it states that
 you can use the LOCAL directive with a structure. When this is done,
 you may receive the following errors:

    A2003 Unknown Type Specifier
    A2010 Syntax Error

 The following code demonstrates this problem:

         .model small,c
         .stack 100h

         parms struc
                 p1 dw ?
                 p2 dw ?
         parms ends

         .code

         call test_func

         test_func proc
              LOCAL stuff:parms ;A2003 Unknown type specifier
              mov ax,0ffffh
              mov stuff.p1,ax   ;A2010 Syntax error
              mov stuff.p2,ax   ;A2010 Syntax error
              ret
         test_func endp

         end

 Response:

 Microsoft has confirmed this to be a problem and will post additional
 information as it becomes available.

 To avoid the A2003 Unknown type specifier error, include the PTR
 keyword in the LOCAL directive. For example:

         LOCAL stuff:ptr parms

 To avoid the A2010 Syntax error, use the MASM 5.10a update assembler.
 To obtain MASM5.10A, contact Microsoft Product Support at
 [phone].
 /*MSINTERNAL
 /*CONFIRMED BY: ROLANDS
 /*BUGLIST INFO
 /*RAID DATABASE: MASM600
 /*BUG NUMBER: 788
 /*


 223. MASM Err Msg: A2006: Phase Error Forward Referencing...

 Product Version(s): 5.10 5.10a | 5.10 5.10a
 Operating System:   MS-DOS     | OS/2
 Flags: ENDUSER | buglist5.10
 Last Modified: 12-JUL-1990    ArticleIdent: Q59754

 Using the "SEG" directive in conjunction with forward reference to a
 procedure or a segment name will produce the error "A2006 : phase
 error between passes."

 The assembler incorrectly places a "NOP" instruction in the code
 generated during Pass 1. This NOP is not generated in Pass 2, so the
 assembler generates a phase error. This phase error most often will be
 against the first subsequent instruction that is associated with a
 fixup (an instruction that contains any address, such as a JMP
 <label>, CALL <label>, or MOV <reg>,<label>).

 Microsoft has confirmed this to be a problem in the Microsoft Macro
 Assembler Version 5.10. We are researching this problem and will post
 new information here as it becomes available.

 The following code produces the errors. The errors do not occur when
 the ax register is used. They occur when the bx, cx, and dx registers
 are used.

 _TEXT           SEGMENT PARA PUBLIC 'CODE'
                 ASSUME CS:_TEXT

                 mov     cx, SEG PROC1     ;error using cx, bx or dx

                 mov     ax, SEG PROC1     ;no error using ax

                 mov     cx, SEG STACKSEG ;error using cx, bx, or dx

                 mov     ax, SEG STACKSEG ;no error using ax

 STACKSEG                SEGMENT PARA PUBLIC 'STACK'
                 DB 100 DUP (?)
 STACKSEG                ENDS

 PROC1           PROC    FAR
                 nop
 PROC1           ENDP
 _TEXT           ENDS
                 END

 To work around this problem, introduce a NOP that is seen by the
 assembler only during the second pass. The following code assembles
 without an error:

 filler macro                      ;macro that codes a nop
         if2                          ;in the second pass of the
         nop                          ;assembler
         endif
         endm

 _TEXT           SEGMENT PARA PUBLIC 'CODE'
                 ASSUME CS:_TEXT

                 mov     cx, SEG PROC1
                 filler

                 mov     cx, SEG STACKSEG
                 filler

 STACKSEG                SEGMENT PARA PUBLIC 'STACK'
                 DB 100 DUP (?)
 STACKSEG                ENDS

 PROC1           PROC    FAR
                 nop
 PROC1           ENDP
 _TEXT           ENDS
                 END


 224. Multiply Defined Structures and /Zi Option Locks Assembler

 Product Version(s): 5.10 5.10a | 5.10 5.10a
 Operating System:   MS-DOS     | OS/2
 Flags: ENDUSER | buglist5.10a
 Last Modified: 19-APR-1990    ArticleIdent: Q60072

 If the assembler source file has a structure declared twice with the
 same name, and the /Zi option is used, the assembler will go into an
 infinite loop.

 The following file demonstrates the problem:

 junk struc     ; Declaration of Structure
 junk ends
 junk struc     ; Repeat Declaration of Structure
 junk ends
 end            ; End of Assembler file

 Microsoft has confirmed this to be a problem in MASM 5.10a. We are
 researching this problem and will post new information here as it
 becomes available.


 225. Error A2057 with Include File DOS.INC and .386 Directive

 Product Version(s): 5.10 5.10a | 5.10 5.10a
 Operating System:   MS-DOS     | OS/2
 Flags: ENDUSER | buglist5.10 buglist5.10a
 Last Modified: 19-APR-1990    ArticleIdent: Q60267

 The error "A2057: Illegal size of operand" occurs with the use of the
 DOS.INC include file and the .386 or .386P directive.

 The DOS.INC files are provided on Disk 2 of the MASM Version 5.10
 disks for simplified use of the DOS calls.

 Microsoft has confirmed this to be a problem with MASM 5.10. We are
 researching this problem and will post new information here as it
 becomes available.

 The following assembly listing produces the error mentioned above:

         DOSSEG
         title   test1
         .386P

         include     \include\dos.inc

 _datas  segment word 'data'
 mess            db      'Hi,there'
 messlen         equ     $-mess
 _datas  ends

         assume cs:_codes
 _codes  segment word 'code'
 start:  mov     ax,_datas
                 mov     ds,ax           ;set data segment to point
                                                 ;to message

                 @write  mess,messlen    ; here is where the
                                                         ; offset error is
                 @exit

 _codes  ends
                 end     start

 No errors occur if the use16 use type is used in the segment
 statement. This generates a 16-bit offset for the DOS.INC macros
 (where a 32-bit offset is generated without the USE 16, and produces
 an error).

 The following code demonstrates the segment use type to overcome the
 error:

         DOSSEG
         title   test1
         .386P

         include     \include\dos.inc

 _datas  segment use16 word 'data'
 mess            db      'Hi,there'
 messlen         equ     $-mess
 _datas  ends

         assume cs:_codes
 _codes  segment word 'code'
 start:  mov     ax,_datas
                 mov     ds,ax           ; set data segment to point
                                         ; to message

                 @write  mess,messlen    ; here is where the
                                         ; offset error is
                 @exit

 _codes  ends
                 end     start


 226. MASM 5.10 Setup Shows Blank Display on LCD/Monochrome Monitor

 Product Version(s): 5.10   | 5.10
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified: 13-APR-1990    ArticleIdent: Q60307

 When running the RUNME setup program for Microsoft Macro Assembler
 Version 5.10, the setup program changes the screen colors. On LCD
 displays and some monochrome displays, the colors that the setup
 program changes to are not visible. Therefore, when the setup program
 is run, you can't see anything on the screen. The program is running
 properly, but the text color is the same as the background color.

 On the MS OS/2 and MS-DOS Macro Assemblers setup disk, there is a file
 that holds all of the commands that the setup program RUNME uses. The
 file is called SETUP.SUS and the first line in that file is as
 follows:

    CLS a: 30 "Microsoft(R) MASM 5.10 Setup"

 To have the setup program use the standard colors of the operating
 system, remove the "a: 30" from the file and rerun RUNME. This will
 correct the problem.

 The new line should be as follows:

    CLS "Microsoft(R) MASM 5.10 Setup"


 227. Using the C Emulator Library with an Assembly Program

 Product Version(s): 5.10 5.10a | 5.10 5.10a
 Operating System:   MS-DOS     | OS/2
 Flags: ENDUSER |
 Last Modified: 12-JUN-1990    ArticleIdent: Q60429

 An Assembler module may use a C emulator library if the assembler
 module is called by a main C module. The C emulator library must be
 used during the linking of the assembler and C modules.

 Linking with the emulator library ensures that the assembler will have
 floating-point math support with or without a a math coprocessor.

 The math functions in the C run-time library require floating-point
 support to perform calculations with real numbers. This support can be
 provided by the floating-point emulator libraries that accompany your
 compiler software or by an 8087 or 80287 coprocessor.

 The assembler module -- if run as a stand-alone module, without a math
 coprocessor, and linked to an emulator library -- generates emulator
 interrupts for floating-point math code, but will not run because the
 interrupts will not be initialized. The C start-up code is necessary
 to initialize the interrupts. If you want to run the assembler module
 as stand-alone, you must write your own emulator library.

 With C, /FPi is the default switch. This switch selects the emulator
 math package and generates inline floating-point instructions.

    CL /c calling.c

 The assembler module is assembled with the following command, where
 (by default) code is generated for a math coprocessor (if
 floating-point instructions are used)

    MASM /E called.asm

 where CALLING.C and CALLED.ASM are the calling and called modules,
 respectively.

 While programming in the QuickC environment, /FPi must be specified in
 the Global Custom Flags field of the Assembler Flags Dialog box
 (reached through the Options menu). This allows the C emulator library
 to be used for all the assembler modules.


 228. .MODEL Directive Makes All Procedure Names Public

 Product Version(s): 5.10   | 5.10
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER | .MODEL PUBLIC
 Last Modified:  4-MAY-1990    ArticleIdent: Q61502

 When you use the .MODEL directive followed by a parameter (for
 example, C, FORTRAN, etc.), there is no means of having the procedures
 considered private.

 The Microsoft Macro Assembler automatically makes all procedure names
 PUBLIC. This is a feature of the assembler. This information can be
 found on Page 34 in the "High-Level-Language Support" section of the
 "Microsoft Macro Assembler" version 5.1 update manual.

 An example using the C parameter following the .MODEL directive is as
 follows:

      ;PUBLIC myadd was required in version 5.0 of MASM to declare
      ;     the procedure public.

 .MODEL MEDIUM,C

          .CODE
 myadd         PROC arg1:WORD, arg2:WORD

          mov   ax,arg1
          add   ax,arg2

          ret

 myadd         ENDP
          END


 229. Passing a LONG INT in C to an Assembly Module

 Product Version(s): 5.10 5.10a
 Operating System:   MS-DOS
 Flags: ENDUSER |
 Last Modified: 21-MAY-1990    ArticleIdent: Q61590

 The following code demonstrates passing a LONG INT (4 bytes) via a
 LONG pointer (4 bytes) to an assembly routine that accesses the LONG
 integer.

 Each integer is incremented in the assembly routine and its new value
 returned to the calling C program.

 The code is as follows:

 *********************************************************

 #include <stdio.h>
 #include <process.h>
 #include<conio.h>

  extern void stuff (long *, long *);

 main()
 {
   long *n1,*n2;               /*4 byte pointers*/

   long int t1 = 9999999L; /*4 byte variables*/
   long int t2 = 2256789L;

  n1 = &t1;
  n2 = &t2;

                               /*initial values*/
   printf("The values are  %ld and  %ld\n ", *n1, *n2);

   printf("Incrementing values...\n");
   stuff(n1,n2);

               /*values returned by the assembly routine*/
   printf("The values are  %ld and  %ld\n ", *n1, *n2);

 }

 ========================================================

 .LALL
 .model large,C
 .data
 .code
   stuff proc far arg1:dword, arg2:dword
     push es                ;save registers
     push si
     les si,arg1            ;load in es:si the seg:offset of
                            ; n1
     inc word ptr es:[si]
     jnc doarg2
     inc word ptr es:[si+2] ;if carry then increment the high
                            ; word of n1
 doarg2:
     les si,arg2            ;load in es:si the seg:offset of
                            ; n2
     inc word ptr es:[si]
     jnc finis
     inc word ptr es:[si+2] ;if carry then increment the high
                            ;word of n2
 finis:
     pop si                 ;restore registers
     pop es
     mov sp,bp
     ret
   stuff endp

   end

 *********************************************************
 *Makefile 'new':-
 *
 *all=1.obj 2.obj    (macro for all the obj's)
 *
 *1.obj: 1.c         (compiles the C module)
 *  cl /AL /c 1.c
 *
 *2.obj: 2.asm       (assembles the Assembler module)
 *  masm 2.asm,,2;
 *
 *1.exe: $(all)      (links modules with library)
 *   link /co $(all),,1,/nod llibcer;  (emulator lib name)
 *
 *Command Line to run makefile:  MAKE new
 *
 *********************************************************


 230. EXE2BIN.EXE File Does Not Come with PC-DOS 3.30, 4.00 and 4.01

 Product Version(s): 5.00 5.10
 Operating System:   MS-DOS
 Flags: ENDUSER | docerr
 Last Modified: 29-MAY-1990    ArticleIdent: Q62136

 Page 19 of the "Microsoft Macro Assembler 5.1 Programmer's Guide"
 incorrectly states that "(EXE2BIN.EXE file) is not included in the
 Macro Assembler package, but it does come with the MS-DOS and PC-DOS
 operating systems." The Macro Assembler package comes with MS-DOS,
 but does not come with PC-DOS versions 3.30, 4.00, and 4.01.

 The following is an example:

    EXE2BIN comes with:    Works with:         Does not work with:
    -------------------    ----------          -------------------

    1. MS-DOS 3.30         MS-DOS 3.30         MS-DOS 4.00 & 4.01
                           PC-DOS 3.30         PC-DOS 4.00 & 4.01

    2. MS-DOS 4.40 & 4.41  MS-DOS 4.00 & 4.01  MS-DOS 3.30
                           PC-DOS 4.00 & 4.01  PC-DOS 3.30

       Note: You will get the message "Incorrect DOS version."

 The EXE2BIN.EXE files that come with MS-DOS versions 4.00 and 4.01 are
 identical. They have been tested by using the COMP command.


 231. Trapping a Keystroke and Displaying Its Extended Scan Code

 Product Version(s): 5.10 5.10a
 Operating System:   MS-DOS
 Flags: ENDUSER | S_C
 Last Modified: 12-NOV-1990    ArticleIdent: Q64439

 The following example causes a main C program to call an assembly
 routine to print the ASCII code and the extended code resulting from a
 keystroke.

 For example, if you press the A key, the output is an ASCII 61 and an
 extended code of 1E indicating the position of the key. If F1 is
 pressed, there is no ASCII equivalent for it, and a 0 is returned for
 the ASCII code and hex 3B for the extended code.

 The following is the example:

 ******************************************************
 #include <stdio.h>
 extern key_read(int*, int*);

 void main(void)
 {
    int *ascii_ptr, *scan_ptr, num, num1;
    num=0;
    num1=0;
    ascii_ptr = #               // initialize pointers to zero
    scan_ptr = &num1;

    key_read(ascii_ptr, scan_ptr);  // call assembly routine

 // print the high byte - ASCII code, and the low byte - extended
 // code of the character placed in the keyboard buffer

    printf("The ASCII code is hex %x or decimal %d\n", *ascii_ptr,"
           " *ascii_ptr);
    printf("The EXTENDED Code is hex %x "
           "or decimal %d\n", *scan_ptr, *scan_ptr);
 }

 ******************************************************
 .model small,c
 .data

 .code
        public  key_read
 key_read proc
          push  bp          ;save the base pointer
          mov   bp, sp

 ; Invoke Int 21h Function Ch to clear the keyboard buffer before
 ; accepting a keystroke.

          mov   ah, 0CH
          mov   al, 0
          int   21h

 ; Invoke Int 16h Function 0h to place the character code in the AX
 ; register.

          mov   ah, 0H
          int   16H

          mov   bx, [bp+4]  ;ASCII returned
          mov   [bx], al

          mov   bx, [bp+6]  ;Extended code returned
          mov   [bx], ah

          pop   bp
          ret

 key_read endp
          end

 ********************************************************
 Contents of Makefile:

 1.obj: 1.c
      cl /Zi /c 1.c

 2.obj: 2.asm
      masm /Zi 2.asm;

 .exe: 1.obj 2.obj
      link /co 1 2,,,/nod slibcer;
 *********************************************************

 A keystroke is sensed by the keyboard microprocessor that deposits an
 8-bit scan code at Port A of the 8255 peripheral interface chip. (Bit
 1=1 when the key contact is made; 0 when the key is released.)

 Following the scan code, keyboard Interrupt 9H is invoked and a 2-byte
 character code is placed in the keyboard buffer. The status of the
 SHIFT and toggle keys is stored in memory and is checked before the
 character code is generated. This allows for uppercase or lowercase
 characters.

 The upper byte of the character code contains an ASCII code if one is
 generated; the lower byte contains the extended code, depending on the
 position of the key pressed.

 A few key combinations do not generate scan codes: <CTRL+BREAK>,
 <CTRL+ALT+DEL>, <PRINT SCREEN>, and <ALT+SYSRQ> on a 286 computer.
 These combinations cause special predefined results.


 232. Passing a Structure from C to Assembly

 Product Version(s): 5.10 5.10a
 Operating System:   MS-DOS
 Flags: ENDUSER | Struc
 Last Modified: 12-JUN-1990    ArticleIdent: Q62626

 The code sample below illustrates how to pass a structure from a C
 module to an assembly module. This code makes it possible to access
 the structure fields within the assembly module using the "." field
 operator.

 Within the assembly module a structure is declared. This structure is
 used as a template by the assembler to resolve accessing the fields of
 the structure. The structure may be given any label name.

 The following is the sample code:

 #include <stdio.h>
 #include "d:\testm\struc\alpha.h" /*include file & path*/

 /*Contents of the Header File*/
 /*=================================*/
 /*struct foo{
  *      int num;
  *      char one[5];
  *      }
  */

 struct foo good,*f_ptr;
 extern void ptr_proc(struct foo*);

 main()

 {
 f_ptr = &good;
  good.one[0]='R';  /*hex 52*/
  good.one[2]='O';  /*hex 4F*/
  good.num=0x0b12;
  ptr_proc (f_ptr);

 /*Incremented Values on returning to C*/
 /*====================================*/

 printf("Good.one[0] is now  %c\n", good.one[0]);

 printf("Good.one[2] is now  %c\n", good.one[2]);

 printf("Good.num is now %x\n",  good.num);

 }

 /*************************************************/

  ; Contents of the DELTA.INC Include file. The structure provides a
  ; template that the assembler recognizes.

  ;  delta struc
  ;        num dw ?
  ;        one db 5 dup (?)
  ;  delta ends

 .model small,C
 .data

 .code

 ptr_proc proc

        push bp
        mov bp,sp

        include d:\testm\struc\DELTA.INC

        mov bx,offset [bp+4].num
        mov ax, word ptr[bx].num
        inc [bx].num

        mov di,word ptr[bx].one
        inc [bx].one

        mov ax, word ptr[bx+2].one
        inc [bx+2].one

        pop bp
        ret

 ptr_proc endp

        end
  /**************************************************/

 The following MAKE file "new" was used:

 all = 1.obj 2.obj

 1.obj: 1.c
      CL /c 1.c

 2.obj: 2.asm
      MASM 2.asm;

 1.exe: $(all)
      link $(all),,,/nod slibcer;

 The command line was: MAKE new

 /******************************************************/

 The output is as follows:

    Good.one[0] is now  S
    Good.one[2] is now  P
    Good.num is now b13


 233. IRET Can't Be Used with proc USES

 Product Version(s): 5.10 5.10a | 5.10 5.10a
 Operating System:   MS-DOS     | OS/2
 Flags: ENDUSER |
 Last Modified: 17-OCT-1990    ArticleIdent: Q64535

 A procedure that uses the USES keyword cannot return by using IRET.
 The USES statement pushes the specified registers on the stack upon
 entry and pops them before exiting a procedure. If the USES keyword is
 used with a procedure that ends with an IRET instruction, the pushes
 will be generated for the procedure, but the pops will not.

 The following code demonstrates the problem:

 The Source File
 ---------------

 .model large,c

 .code
 proctest segment 'CODE'

 first proc far uses di si bp
       mov si,3
       mov di,4
       iret
 first end
       end first

 The Assembled Listing
 ---------------------

 assume cs:@code,ds:@data,ss:@data

 proctest_TEXT segment 'CODE'

 first  proc far uses di si bp

 push DI
 push SI
 push BP
       mov si,3
       mov di,4
                     <--- missing pops for bp,si, and di
       iret
 first  endp
       end  first
 @CurSeg ends


 234. How to Create Overlays with Macro Assembler

 Product Version(s): 5.10 5.10a
 Operating System:   MS-DOS
 Flags: ENDUSER |
 Last Modified: 12-NOV-1990    ArticleIdent: Q66054

 The following code illustrates the creation of an overlay with an
 assembly module. The first procedure _main in the root module calls
 the procedure rt2 in the overlaid module.

 It is possible to create overlays while linking with the medium- and
 large-memory model libraries.

 The Overlay Manager is a part of a higher-level language's run-time
 library (C for instance). While linking, this library must be used if
 the code for the Overlay Manager is to be linked with the program.

 Page 285 of the "Microsoft Macro Assembler 5.1 CodeView and Utilities
 Guide" explains the use of overlays with assembly-language modules.
 Only modules with a 32-bit (long) call/ret instruction can be
 overlaid. Routines called should be declared as FAR. The linker is
 unable to produce overlay modules that can be called indirectly with
 function pointers. The root module is the resident (nonoverlaid)
 portion of the program, and the overlaid module is the transient
 portion.

 There are two segments created by the linker. The Overlay_Area and the
 Overlay_Data. The size of the Overlay_Area (class "code") is
 determined by the Overlay_End statement that points to the end of the
 Overlay_Area segment. The Overlay_Data is placed in DGROUP. The two
 segments can be viewed in a MAP file.

 LINK sets the Overlay_Area to fit the largest overlay. Only the code
 is overlaid. The Overlay_Data is initialized by LINK with information
 about the executable file and information useful to the run-time
 Overlay Manager (for example, number of overlays).

 LINK replaces all FAR calls from root to overlay, or overlay to
 overlay with the following information:

 1. A software interrupt (usually INT 3FH, which can be overridden
    the /OVERLAYINTERRUPT option on the LINK line).

 2. The overlay number.

 3. The offset into the overlay segment.

 This information provides the overlay manager with a mechanism to do
 the following:

 1. Load a specified overlay into memory.

 2. Transfer control to a specified offset within an overlay.

 If you need to modify the behavior of the Overlay Manager, the source
 code is available as part of the Microsoft C run-time source code,
 which can be ordered through Microsoft Sales and Service by calling
 [phone].

 Code Example
 ------------

 ;main module      (1.asm)

 assume cs:cseg,ds:dseg,ss:sseg

 DSEG segment word public
 line02  db 'In the Root module'
         db (13)         ;CR
         db (10)         ;LF
         db (36)         ;$ String Terminator
 DSEG ends

 EXTRN rt2:far

 cseg segment byte public
 public _main            ;necessary as the run-time library
                         ;following the entry point at _astart
                         ;calls _main (in C startup module crt0.asm)
 _main   proc   FAR
    mov  ax,DSEG
    mov  ds,ax
    mov  ah,09           ;String output Function 09H
    mov  dx,seg line02
    mov  ds,dx
    mov  dx,offset line02
    int  21h             ;Invoking DOS Interrupt 21H

    call rt2             ;Call to the Overlay Procedure
    mov  ah,4Ch          ;Function 4CH return to DOS
    int  21h
 _main   endp

 cseg ends

 sseg segment stack
         db 20 dup (0)
 sseg ends
    end

 ------------------------------------
 ;overlaid module  (2.asm)

 ;assume cs:c1seg,ds:d1seg

 D1SEG segment word public
 line03  db 'In the Overlaid module'
         db (13)
         db (10)
         db (36)
 D1SEG ends

 public rt2
 c1seg segment byte public

 rt2   proc   FAR
    mov  ax,D1SEG
    mov  ds,ax
    mov  ah,09
    mov  dx,seg line03
    mov  ds,dx
    mov  dx,offset line03
    int  21h
    ret
 rt2   endp

 c1seg ends
    end

 ------------------------------------

 The following are commands to assemble and link:

 MASM /MX 1.asm;
 MASM /MX 2.asm;
 LINK /NOI /NOD 1.obj + (2.obj),,,slibcer;

 Notes
 -----

 Consider the following:

 1. Either use Segmented Linker version 5.01.20 or later, or OverLay
    Linker version 3.64 or later.

 2. Use the appropriate run-time library from C version 6.00 and C
    versions 5.x (medium or large).

 3. Use /MX and /NOI to preserve case sensitivity.

 Output from .EXE occurs in the following:

 1. In the Root module

 2. In the Overlaid module


 235. Repeat Prefix (REP) Documentation Error

 Product Version(s): 5.00   | 5.10
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER | docerr
 Last Modified: 12-NOV-1990    ArticleIdent: Q66170

 On Page 368 of the "Microsoft Macro Assembler Programmer's Guide," the last
 sentence in the second paragraph from the bottom states the following:

    Segment overrides can be used safely when interrupts are turned
    off, when a string instruction is used without a segment override,
    or when a 80386 processor is used.

 It should read as follows:

    Segment overrides can be used safely when interrupts are turned
    off, when a string instruction is used without a repeat prefix, or
    when a 80386 processor is used.

 The repeat prefix may be used safely with segment overrides if a CLI
 instruction is performed before the REP instruction and a STI
 instruction is performed after it. This process shuts off interrupts
 during the REP instruction that contains a segment override. Clearing
 interrupts in this manner is only needed for instructions with segment
 overrides that are preceded with REP.

 Please note that the execution of a repeated instruction can take a
 considerable amount of time; you may not want to have interrupts shut
 off for that much time. It is the programmer's responsibility to
 ensure that interrupts are not missed while interrupts are off.

 A better alternative if you are moving a large amount of data is to
 change the DS register for the duration of the repeated instruction
 (so that the segment override is not needed) and restore it
 afterwards.

 The following is an example of using the CLI instruction to disable
 interrupts and using the STI instruction to re-enable them:

     ;   set SI and DI

     MOV CX, 20   ; relatively small number of bytes--won't take long
     CLI
     REP MOVS dest,ES:source
     STI

     ;   ...

 The following is an example of temporarily using the DS register to
 avoid the segment override:

     ;   set SI and DI

     MOV  CX, 4000h ; lots to move -- this will take some time
     PUSH DS        ; save for later
     PUSH ES        ; same as ES: override -- change for other overrides
     POP  DS        ; load into DS
     REP  MOVS dest, source
     POP  DS        ; restore DS


 236. C and c Are Illegal Symbols in MASM 5.10 and 5.10a

 Product Version(s): 5.10 5.10a | 5.10 5.10a
 Operating System:   MS-DOS     | OS/2
 Flags: ENDUSER |
 Last Modified: 12-NOV-1990    ArticleIdent: Q66497

 If you assemble the code below with the Microsoft Macro Assembler
 version 5.10 or 5.10a, the following error is generated:

    error A2009: Symbol not defined:

 This error occurs because "c" or "C" can be used in your .MODEL
 statement to identify that you are doing mixed-language programming
 with C. This process makes C a reserved symbol, and therefore it
 cannot be used in your program.

 This behavior is by design and is not considered a problem with the
 Microsoft Macro Assembler.

 Code Example
 ------------

 public c

 c PROC FAR
 c ENDP

 end

 Workaround
 ----------

 Change "c" or "C" to something else.


 237. MASM Instructions Operand Size Documented Wrong

 Product Version(s): 5.00 5.10 | 5.10
 Operating System:   MS-DOS    | OS/2
 Flags: ENDUSER | docerr
 Last Modified:  6-FEB-1991    ArticleIdent: Q67439

 In the "Microsoft Macro Assembler 5.1 Reference" manual, a number of
 instructions indicate that their operand size is a mem64 when they
 should indicate an operand size of mem48. The instructions are
 documented incorrectly as LGDT, LIDT, LLDT, SGDT, SIDT, and SLDT.
 These instructions require the FWORD PTR operator and not the QWORD
 PTR operator. If the QWORD PTR operator is used, the Microsoft Macro
 Assembler (MASM) will generate the following warning:

    warning A4057: illegal size for operand

 These instructions are privileged 286 and 386 instructions that are
 used to load and save the protected mode descriptor table registers.
 These registers are only 6 bytes long, even though descriptor table
 entries are normally 8 bytes.


 238. Tracing into a Macro When Debugging Assembly Programs

 Product Version(s): 5.10   | 5.10
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER | S_QUICKASM
 Last Modified:  6-FEB-1991    ArticleIdent: Q67440

 When you use a macro in an assembly-language routine and you are
 debugging, you cannot trace into the macro definition as you can with
 a procedure. The debugger simply executes the macro call (steps over
 it) as if it were a single instruction.

 This behavior is by design. There is no symbolic information
 generated to allow the debugger to step into the macro. If you are
 using CodeView, you can switch to assembler mode (not source mode) and
 single step through the code. However, if you are using Microsoft
 Quick Assembler, you will have to expand the macro before assembly if
 you want to step through the code.

 Note: There is a CodeView update for Quick Assembler version 2.51
 owners. Call Microsoft Sales and Service at [phone] for more
 information.


 239. Conditional Jump Instruction Is Incorrectly Documented

 Product Version(s): 5.00 5.10 | 5.10
 Operating System:   MS-DOS    | OS/2
 Flags: ENDUSER | docerr
 Last Modified:  6-FEB-1991    ArticleIdent: Q67757

 Page 336 of the "Microsoft Macro Assembler 5.1 Programmer's Guide"
 shipped with MASM version 5.00 and 5.10 has a table that lists the
 various conditional jump instructions, what each means, and whether
 each acts on a signed or unsigned value. The table has the
 signed/unsigned values mixed up.

 The table currently states:

    Letter  Meaning
    ------  -------

     J      Jump
     G      Greater than (for unsigned comparisons)
     L      Less than (for unsigned comparisons)
     A      Above (for signed comparisons)
     B      Below (for signed comparisons)
     E      Equal
     N      Not

 It should read:

    Letter  Meaning
    ------  -------

     J      Jump
     G      Greater than (for signed comparisons)
     L      Less than (for signed comparisons)
     A      Above (for unsigned comparisons)
     B      Below (for unsigned comparisons)
     E      Equal
     N      Not


 240. MASM Err Msg: Unable to Open Input File: options.asm

 Product Version(s): 5.10   | 5.10
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified:  6-FEB-1991    ArticleIdent: Q67758

 The MASM fatal error "Unable to open input file: options.ASM" occurs
 when the MASM environment variable "MASM" is set to "options". After
 the variable has been set to "options", it needs to be cleared. This
 can be done as follows:

    SET MASM=<ret>

 When the Runme program is executed to install MASM, it tells you
 to set your AUTOEXEC.BAT file as follows:

    MOUSE                 (load mouse driver if you have a mouse)
    SET PATH=d:\masm...   (directory containing MASM and utilities)
    SET INCLUDE=d:\masm...(directory containing include files)
    SET LIB=d:\masm....   (directory containing library and object files)
    SET MASM=options      (standard assembly options)
    SET LINK=options      (standard link options)
    SET TMP=tempDir       (LINK work directory - use RAM disk if available)

 People often set their AUTOEXEC.BAT files literally as the Runme program
 shows.


 241. Bad Object File Generated with MASM 5.10

 Product Version(s): 5.10   | 5.10
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER | buglist5.10
 Last Modified:  6-FEB-1991    ArticleIdent: Q67760

 The following mixed-language program does not assemble properly under
 MASM version 5.10. The assembler doesn't generate the correct .OBJ
 record for the linker to resolve the reference properly. When the
 .EXE is built, the _foo variable is located in the NULL segment
 instead of the _DATA segment. Therefore, instead of the residing 1
 byte apart, they are actually 42h bytes apart.

 Removing the ASSUME statements from the assembly code eliminates the
 problem. These ASSUME statements are not necessary.

 Microsoft has confirmed this to be a problem in MASM version 5.10. We
 are researching this problem and will post new information here as it
 becomes available.

 Sample Code
 -----------

   dosseg
   .model small

   .data
   assume ds: nothing
   public _foo
 _foo db 1
   assume ds: @data
   public _bar
 _bar db 2

   .code
   public _func
 _func proc
   mov ax, offset _bar
   sub ax, offset _foo
   ret
 _func endp

   end

 #include <stdio.h>
 extern char foo;
 extern char bar;

 main ()
 {
   printf ("C distance of bar - foo = %X\n", &bar - &foo);
   printf ("MASM distance of bar - foo = %X\n", func ());
 }


 242. STRUC Defined Structures Cannot Be Tested

 Product Version(s): 5.10 5.10a | 5.10 5.10a
 Operating System:   MS-DOS     | OS/2
 Flags: ENDUSER | buglist5.10a
 Last Modified:  6-FEB-1991    ArticleIdent: Q67787

 The STRUC command in MASM does not allow for the definition of nested
 structures. The example code below shows a nested structure definition
 which gives the following error:

    test.ASM(10): error A2078: Directive illegal in structure

 Sample Code
 -----------

 .MODEL SMALL
 .DATA
 foo STRUC
         f1 db ?
         f2 db ?
 foo ENDS

 goo STRUC
         f3 db ?
         s1 foo <>          ;; this is the nested structure
                            ;; declaration that is illegal
 goo ENDS

 end

 Microsoft has confirmed this to be a problem in MASM versions 5.10 and
 5.10a. We are researching this problem and will post new information
 here as it becomes available.


 243. IRP Directive Has Single Line Limit of 120 Characters

 Product Version(s): 5.10 5.10a | 5.10 5.10a
 Operating System:   MS-DOS     | OS/2
 Flags: ENDUSER | buglist5.10a
 Last Modified:  6-FEB-1991    ArticleIdent: Q67788

 The IRP (Instruction Repeat) directive in MASM has a single line limit
 of 120 characters. The example code below shows a macro with an IRP
 that has 125 characters. The result of this program is an error
 message that states:

         End of file encountered on input file
         Number of open conditionals:14
         End of file encountered on input file

 This error occurs because the assembler is looking for a closing
 bracket (>), but the line is over the limit of 120 characters. As a
 result, the assembler accepts the rest of the code to be part of the
 IRP parameters. By shortening the final parameter to be within the
 limit (change TP$_EOS to TP), the bracket is read correctly and the
 remainder of the program is assembled with no errors.

 NOTE: In this example, the IRP argument list is stated in three lines;
 however, it should be all on the same line to cause the error. The
 120-character limit is only on the same line. A workaround is to
 continue the argument on the next line as seen below.

 Microsoft has confirmed this to be a problem in MASM version 5.10 and
 5.10a. We are researching this problem and will post new information
 here as it becomes available.

 Sample Code
 -----------

 $tran   macro   keyword
    irpc TP$_DUMMY,<keyword>
       ifidn <&TP$_DUMMY>,<T>
          irp TP$_DUMMY2,<TP$_ANY,TP$_ALPHA,TP$_DIGIT,
                         TP$_STRING,TP$_SYMBOL,TP$_BLANK,TP$_DECIMAL,
                         TP$_OCTAL,TP$_HEX,TP$_LAMBDA,TP$_EOS>
             %out TP$_DUMMY2
          endm
       endif
    endm
 endm

    $tran     if_anything_cmd
 end


 244. MASM Aligns on 4-Byte Boundary After Offset 8000h

 Product Version(s): 5.10 5.10a | 5.10 5.10a
 Operating System:   MS-DOS     | OS/2
 Flags: ENDUSER | buglist5.10 buglist5.10a
 Last Modified:  6-FEB-1991    ArticleIdent: Q68071

 The module below demonstrates a problem with the Macro-Assembler. If
 an EVEN directive is used after an offset of 8000h within a segment,
 the assembler will try to align the next instruction or data element
 on a 4-byte boundary. In other words, more bytes for padding will be
 added than are necessary to achieve even alignment.

 Microsoft has confirmed this to be a problem in MASM versions 5.10 and
 5.10a. We are researching this problem and will post new information
 here as it becomes available.

 Sample Code
 -----------

  _TEXT SEGMENT
    ASSUME CS:_TEXT
    clc
    even
    clc
    org 8000h
    clc
    even
    clc

  _TEXT ENDS
  ENDS

 ASSEMBLY LISTING
 ----------------

 Code Generated   Source
 --------------   ------

 F8               clc
 90               even
 F8               clc
                  org 8000h
 F8               clc
 87 DB 90         even
 F8               clc


 245. Language Parameter with .MODEL Directive Doesn't Preserve Case

 Product Version(s): 5.10 5.10a | 5.10 5.10a
 Operating System:   MS-DOS     | OS/2
 Flags: ENDUSER | s_quickasm
 Last Modified:  6-FEB-1991    ArticleIdent: Q68072

 The .MODEL directive can be followed by a language parameter that
 determines naming, calling, and returning conventions that are used
 by the specified language. The example below demonstrates the syntax.

 Although the language type determines the naming convention, it does
 not determine the case of any names used. For example if the statement
 ".MODEL SMALL, C" is used, case sensitivity of names is not preserved,
 even though C preserves case by default. However, an underscore is
 added in front of any names. Similarly, if the statement ".MODEL
 SMALL, PASCAL" is used in a program, all names are not forced to
 uppercase (the default for Pascal).

 To ensure proper case sensitivity, use the command line option /MX
 (preserves case in public and external names), /MU
 (converts names to uppercase), or /ML (preserves case in names).

 Sample Code
 -----------

    .model small,c ; <--- Language specifier
    .code

    foo proc
        ret
    end


 246. .MODEL Directive Forces DOSSEG Segment Ordering in MASM

 Product Version(s): 5.00 5.10 5.10a | 5.10 5.10a
 Operating System:   MS-DOS          | OS/2
 Flags: ENDUSER | S_QUICKASM
 Last Modified:  6-FEB-1991    ArticleIdent: Q68562

 The .MODEL assembler directive forces the segments in the resulting
 executable program to be ordered as if the DOSSEG directive had been
 used. This will override any other directives used to organize
 segments in an executable program. The code below demonstrates this
 behavior.

 Because of this, the options below will be ignored:

    /A and /S command line switches
    .ALPHA and .SEQ assembler directives

 This behavior is not documented and no warnings or errors are
 generated.

 This behavior is also true with QuickAssembler versions 2.01 and 2.51.
 The .MODEL assembler directive was designed for use in mixed-language
 programming. Because of this, it will automatically order the segments
 in a way compatible with the way higher-level language compilers order
 them. This will happen even if the <,language> option on the .MODEL
 directive is not used.

 Sample Code:

 The map file created from the linker is included below.

 .MODEL medium
 .286
 .SEQ
 .STACK 100h

 A SEGMENT WORD PUBLIC 'DATA'

 test_data DW 10

 A ENDS

 B SEGMENT WORD PUBLIC 'CODE'

         mov ax,1

 B ENDS
         END

 Map file:

 Start  Stop   Length Name                        Class
 00000H 00000H 00000H _TEXT                       CODE
 00000H 00002H 00003H B                           CODE
 00004H 00004H 00000H _DATA                       DATA
 00004H 00005H 00002H A                           DATA
 00010H 0010FH 00100H STACK                       STACK

 Origin   Group
 0000:0   DGROUP

 When the .MODEL and .STACK directives are removed (.STACK must be
 removed because it requires .MODEL), the following map file results.
 Note that the segments appear in the proper order in this case.

 Start  Stop   Length Name                        Class
 00000H 00001H 00002H A                           DATA
 00002H 00004H 00003H B                           CODE


 247. How to Reboot Your Machine Within a MASM 5.10 Application

 Product Version(s): 5.10
 Operating System:   MS-DOS
 Flags: ENDUSER | S_QUICKASM
 Last Modified:  6-FEB-1991    ArticleIdent: Q68805

 You can perform a complete reboot (cold boot) on an 8086-based machine
 by jumping to the address F000:FFF0. This action also reboots many
 80286 and 80386 machines. The address contains a jump instruction that
 leads to the machine's initialization code. For this method to
 succeed, your machine must be in real-mode operation.

 To prevent a memory check on IBM and many compatibles (warm boot), you
 should store the value 0 x 1234 in the memory location at 0040:0072.
 On 100-percent IBM BIOS compatible machines, an alternative method
 is to call int 19h instead of jumping to the address mentioned
 above.

 Code Example
 ------------

     .MODEL SMALL
     .CODE

 Start:
     mov ax, @data                 ; Load ds with data segment
     mov ds, ax

     mov ax, 40h                   ; These three lines cause a memory
     mov es, ax                    ; test NOT to be performed. To
     mov WORD PTR es:[72h], 1234h  ; do a memory test, remove them.

     jmp DWORD PTR b_vec           ; Jump to the reboot address

     .DATA
 b_vec   DW 0FFF0h                 ; Offset of reboot vector
         DW 0F000h                 ; Segment of reboot vector
     .STACK
     END Start


 248. Warning A4057 When Using Local Variables

 Product Version(s): 5.10   | 5.10
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER | buglist5.10 fixlist5.10a
 Last Modified:  6-FEB-1991    ArticleIdent: Q68873

 The code below produces the following error:

    Warning A4057: illegal size for operand

 This warning is falsely generated and does not occur with version
 5.10a of the Microsoft Macro Assembler (MASM).

 The variable arg1, shown in the code below, is a local variable that
 is defined as a double word. The warning occurs when arg1 is used as
 a WORD PTR. This is acceptable and should not be flagged.

 Microsoft has confirmed this to be a problem in MASM
 version 5.10. This problem was corrected in version 5.10a.

 Sample Code
 -----------

     .MODEL small,c
     .CODE

     Begin proc arg1:dword
       mov ax, word ptr arg1
       ret
     Begin endp
     end Begin


 249. DWORD Local Variables Use Wrong Offset in MASM

 Product Version(s): 5.10   | 5.10
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER | buglist5.10 fixlist5.10a
 Last Modified:  6-FEB-1991    ArticleIdent: Q68945

 When using the LOCAL directive in the Microsoft Macro Assembler (MASM)
 version 5.10 to declare stack space for a DWORD variable, the offset
 that is generated for the variable is [BP-2]. This may result in the
 saved value of the BP register to be overwritten when a value is
 stored in the DWORD local variable.

 Microsoft has confirmed this to be a problem in MASM version 5.10.
 This problem was corrected in version 5.10a.

 Beginning with MASM 5.10, if the optional language parameter is used
 with the .MODEL directive, the LOCAL directive may be used to declare
 local variables for a procedure (PROC). When the LOCAL directive is
 used in a procedure, stack space is set aside for the number and size
 of the local variables that were declared. For example, upon
 executing the first line of the sample assembly routine below, the
 stack frame appears as follows if assembled with MASM 5.10:

       ----------
       | Return | 2 bytes
       | address|
       ----------
       | Saved  | 2 bytes
       |   BP   |
       ----------
       | storage| 2 bytes
 SP--> | for foo|
       ----------

 The problem is that DWORD needs four bytes of storage. Because the
 "saved BP" is at a higher memory location than the storage of foo, foo
 will "overflow" into the saved BP area. Using MASM 5.10a will solve
 the problem by properly allocating 4 bytes of storage for a DWORD.

 Sample Code
 -----------

         .MODEL SMALL, C
         PUBLIC C myproc
         .CODE

 myproc  PROC
         LOCAL   foo:DWORD
         nop
         ret
 myproc  ENDP

         END


 250. Long Command Line Generates Protection Violation in MASM

 Product Version(s): 5.10
 Operating System:   OS/2
 Flags: ENDUSER | buglist5.10 fixlist5.10a
 Last Modified: 11-FEB-1991    ArticleIdent: Q69123

 Executing the Microsoft Macro Assembler (MASM) version 5.10 with a
 parameter list greater than 129 characters generates a protection
 violation under OS/2.

 The following example illustrates the problem:

    MASM /Mx /Zi .\.\.\.\.\.\.\.\.\.\.\.\.\.\.\.\.\.\.\.\.\.\.\
    .\.\.\.\.\.\.\.\.\.\.\.\.\.\.\.\.\.\.\.\.\.\.\.\.\.\.\.\.\.\
    .\.\.\.\.\t.asm;

 Workarounds
 -----------

 The following lists two valid workarounds:

 1. Shorten the command line by using the MASM environment
    variable to declare options (that is, set MASM=/Mx /Zi).

 2. Contact Microsoft Product Support Services by calling (206)
    454-2030 and ask for the incremental update MASM 5.10a.

 Microsoft has confirmed this to be a problem in MASM version 5.10.
 This problem was corrected in version 5.10a.






 Microsoft QuickAssembler
 =============================================================================


 1. New Command-Line Options in Qasm

 Product Version(s): 2.01
 Operating System:   MS-DOS
 Flags: ENDUSER |
 Last Modified: 26-JUN-1989    ArticleIdent: Q44742

 Quick Assembler recognizes the new ML-style options to be similar and
 consistent with CL options. Qasm does not recognize old-style options
 (MASM Version 5.10 and previous).

 Like CL, if the /c switch is not specified, the linker is invoked
 following a successful assembly. Unlike old-style Macro Assembler
 options, Qasm switches are case sensitive.

 The following are the switches which the Quick Assembler supports:

 /a        Alphabetical segment order (was /A)
 /c        Assemble only (new switch)
 /D        Define symbol (was /Dsym[=value])
 /Ez       Displays error lines on the screen (was /Z)
 /FPi      Generate emulator calls (was /E)
 /help     Print help listing (was /H)
 /I        Include path (was /I)
 /l        Generate a listing file with the default name (was /L)
 /L[cr]    Specifies flags for the linker (new switch)
 /Fefile   Names the output .EXE file (new switch)
 /Flfile   Generate a listing file with specified name (new switch)
 /Fofile   Name the output .OBJ file (new switch)
 /M[uxl]   Controls case sensitivity (was /M[uxl]
 /s        Sequential segment order (was /S)
 /Sa       List all lines (was /La..implies listing is on)
 /Sd       Create pass 1 listing (was /D) (implies listing is on)
 /Se       Listing is editor oriented (new switch) (implies listing is on)
 /Sn       Suppresses symbol table in list file (was /N)
           (implies listing is on)
 /Sp       Listing is printer oriented (new switch)
           (implies listing is on)
 /Sq       Generate line-number index in listing (new switch)
           (implies listing is on)
 /Sx       Suppresses listing of false conditionals (was /X)
           (implies listing is on)
 /t        Suppresses messages for successful assembly (was /T)
 /v        Verbose messages  (was /V)
 /W[012]   Warning level setting 0, 1, or 2 (was /W[012])
 /Z[di]    Generate debug information (was /Z[di])


 2. Major Changes between QuickC 2.00 and Quick Assembler

 Product Version(s): 2.01
 Operating System:   MS-DOS
 Flags: ENDUSER |
 Last Modified: 26-JUN-1989    ArticleIdent: Q44743

 The following lists the major changes between QuickC 2.00 and Quick
 Assembler 2.01:

  1. Quick Assembler 2.01 is bundled with a modified QuickC which has
     version number 2.01 (this can be found by typing QCL at the DOS
     command prompt).

  2. Quick Assembler is a super-set of QuickC. It contains ALL of the
     functionality and capabilities of QuickC, with the additional power
     of a quick assembler.

  3. Quick Assembler does not exist without a QuickC 2.01. It is a
     bundled package. There will continue to be a stand alone QuickC
     2.00 package, but no stand alone Quick Assembler.

  4. No Floppy Disk Support: Quick Assembler requires a hard disk. It
     does not support execution on a floppy disk system.

  5. New Type Casts for debugging: BY, WO, DW are used by CodeView to
     simulate MASM <type> PTR. These type casts are now acceptable to
     the Watch expression evaluator in the Quick environment.

     Note: BY <reg>      is the same as * (char *) <reg>
           BY <addrexpr> is same as  * (char *) <addrexpr>
           BY <var>      is the same as * (char *) &<var>

     WO and DW behave analogously, with WO equivalent to * (int*) and
     DW equivalent to * (long *).

  6. Segmentation Support: The colon ':' operator is recognized
     as indicating a full segmented address in Watch expressions. The
     segment portion can be either a segment register or a numeric
     value.

  8. .COM File Production and Debugging: Quick Assembler allows for
     both the production and debugging of .COM files. LINK.EXE has been
     modified to check if /TINY and /CODEVIEW are both specified. If
     so, the symbolic information will be emitted into a separate .DEB
     file (instead of placing it in the .EXE file as per normal).

     The debugger checks the extension of the file it is loading, and
     if it is a .COM, the debugger will get CodeView information from
     the .DEB file.

     Note: This support of .COM files is currently restricted to the
     Quick Assembler and does not extend to the QuickC portion of the
     package. Microsoft is actively pursuing extending the .COM support
     to a future release of QuickC.

  9. Ten-Byte Real Support: In assembly, ten-byte reals may be defined
     using the DT directive. Support has been added to allow Watches of
     ten-byte reals, and to allow their values to be modified using
     Debug.Modify Value. As in CodeView, they will not be allowed in
     expressions.

 10. Screen Swapping: The debugger will force screen swapping when
     tracing a file with a .ASM extension so that direct output is not
     misplaced.

 11. First Trace into Assembly Programs: The first Trace into a pure
     assembly program (i.e., no C startup code) will actually execute the
     first statement. This differs from CodeView and the way the QuickC
     debugger operates on .C files.

 12. Qasm will be called by QCL: The Quick Assembler will be directly
     callable through QCL. This means that when a *.ASM file is
     specified to QCL it will invoke Qasm with all arguments passed
     through unchanged.


 3. What is Quick Assembler?

 Product Version(s): 2.01
 Operating System:   MS-DOS
 Flags: ENDUSER |
 Last Modified: 26-JUN-1989    ArticleIdent: Q44744

 Question: What is Quick Assembler?

 Quick Assembler is, simply put, QuickC 2.00 with the addition of a
 Quick Assembler which is completely functional within the Quick
 environment. You can edit, assemble, and debug pure assembly programs
 with the benefit of Online Assembly Help. It also is designed to make
 mixed-language programming even easier and faster than before.

 This package has all the capabilities of QuickC 2.00 with the added
 performance enhancement of a full assembler.

 Quick Assembler does NOT replace the Inline Assembler. It is a full
 assembler which supports pure assembly source. The Inline Assembler is
 still available as a feature of QuickC.

 Quick Assembler is NOT a stand-alone package. It is bundled with
 specific QuickC 2.01 packages. There is a fulfillment package for
 owners of QuickC 2.00 which allows the upgrading to QuickC/Quick
 Assembler.


 4. /AT Tiny Model and Quick Assembler

 Product Version(s): 2.01
 Operating System:   MS-DOS
 Flags: ENDUSER |
 Last Modified: 26-JUN-1989    ArticleIdent: Q44745

 The Tiny model is supported by the Quick Assembler Version 2.01 to
 allow for the creation of .COM files. This support alleviates the
 required use of EXE2BIN. This memory model is supported in the
 following way:

 1. Segment _TEXT will be included as the first segment of DGROUP.

 2. An "assume" will be done of all segment registers to DGROUP.

 3. The code segment will be opened, and an ORG 100h done.

 As a result of this change, constructs that result in segment fixups
 will be flagged as errors where possible. This includes use of a
 segment as an immediate value, and the use of the SEG operator, as in
 the following example:

    1. MOV    ax, _DATA
    2. MOV    ax, SEG MySymbol

 In the above example, the following new error message will be
 generated in Tiny model:

    error 116: Segment reference illegal in tiny model.

 Please note that this support for .COM files currently resides only in
 the Quick Assembler portion of this package. The possibility of
 embedding this support within Quick C is under review and will be
 considered for inclusion in a future release.


 5. .MODEL and FAR_STACK, LOCAL_STACK in Quick Assembler

 Product Version(s): 2.01
 Operating System:   MS-DOS
 Flags: ENDUSER |
 Last Modified: 26-JUN-1989    ArticleIdent: Q44746

 Prior to Quick Assembler Version 2.01, the .MODEL directive expanded
 into instructions that assumed that SS=DS=DGROUP. This situation is
 not upheld at the start of a stand-alone assembly program (initially,
 SS is set to the stack segment, and SP is set to the size of the
 stack). The startup code of all Microsoft high-level languages sets
 SS=DGROUP and adjusts SP accordingly.

 Two new attributes have been added to the .MODEL directive:

 1. FAR_STACK

 2. LOCAL_STACK  (the default, if neither is specified)

 These new options are designed to simplify setting up segments for
 DS=SS and DS!=SS.

 LOCAL_STACK is the default, and will direct .MODEL and .STACK to
 behave as they have previously, i.e., set up segments assuming DS=SS.

 FAR_STACK will direct the .MODEL and .STACK to do the correct setup
 for a DS!=SS environment.

 The following lists the expansion of a sample .MODEL and .STACK
 directive:

 .MODEL small = _data  SEGMENT WORD PUBLIC 'data'
                dgroup GROUP  _data
                _data  ENDS
                _text  SEGMENT WORD PUBLIC 'text'
                _text  ENDS
                       ASSUME cs:_text, ds:_data, ss:dgroup

 .STACK 100h  = stack  SEGMENT PARA STACK 'stack'
                dgroup GROUP  stack
                       org 100h
                stack  ENDS

 This setup assumes that DS==SS, which is the default. Specifying
 ".MODEL small, LOCAL_STACK" expands to the same instructions.

 If you specify FAR_STACK in the above example, the expansion is as
 follows:

 .MODEL small, FAR_STACK
                _data  SEGMENT WORD PUBLIC 'data'
                dgroup GROUP  _data
                _data  ENDS
                _text  SEGMENT WORD PUBLIC 'text'
                _text  ENDS
                       ASSUME cs:_text, ds:_data, ss:NOTHING

 .STACK 100h
                stack  SEGMENT PARA STACK 'stack'
                       ASSUME  SS:stack
                       org 100h
                stack  ENDS

 Please note that the stack segment is not placed in DGROUP when
 FAR_STACK is specified. Additionally, the "assume" generated by the
 .MODEL assumes NOTHING for SS, and the .STACK performs an "assume" to
 the stack segment.

 An error is generated if FAR_STACK is specified along with the TINY
 memory model.


 6. Differences between Quick Assembler and Macro Assembler

 Product Version(s): 2.01
 Operating System:   MS-DOS
 Flags: ENDUSER |
 Last Modified: 26-JUN-1989    ArticleIdent: Q44747

 The following article lists the major changes between the Microsoft
 Quick Assembler Versions (Qasm) 2.01 and the Macro Assembler.

 1. Quick Assembler Supports Only Real Mode 286

    Qasm supports all Intel assembly instructions that lie within
    the scope of real mode 80286. This means the directives .386,
    .386p, .387, and .286p will be recognized; however, they produce
    one of the following two errors:

       A2119:    80386 processor not supported.
       A2120:    Privileged instructions not supported.

 2. .MODEL TINY Is Supported to Allow for .COM Files

    The Tiny model is now supported by the Quick Assembler and the
    linker shipped with Qasm. This means that EXE2BIN is not needed for
    .COM file production.

 3. .MODEL Changes and Additional Features

    To assist you in writing code that can be easily switched between
    memory models, a new predefined equate, @MODEL, is available. This
    equate has the following values:

       1 = TINY.  2 = SMALL. 3 = MEDIUM.
       4 = COMPACT. 5 = LARGE.  6 = HUGE.

    The following code fragment shows how this equate can be used to
    switch between small and tiny models:

 .model    <specified model>
 .data
 .code

 start:
           if @MODEL NE 1      ; if not TINY model
           mov  ax, @data
           mov  ds, ax
           endif
           .
           .

 4. FAR_STACK and LOCAL_STACK attributes to .MODEL

       .Model Small, c, FAR_STACK
       .Model Small, c, LOCAL_STACK

    LOCAL_STACK is the default and directs .MODEL and .STACK to behave
    as they have done in the past, i.e., set up the segments for an
    SS = DS environment.

    FAR_STACK instructs Qasm to perform the correct setup for a
    SS!= DS environment.

 5. New Directive .STARTUP

    .STARTUP expands to the correct code for the given model and
    FAR/LOCAL_STACK value. This expansion includes initializing DS,
    SS, and SP when necessary. It also defines a start address
    label and directs the END directive to use this start label.

    This directive is designed only for stand-alone programs. It should
    not be used for code that is mixed with higher-level languages such
    as C, FORTRAN, etc., because it conflicts with their startup
    code.

    Likewise, this directive should be used for stand-alone DOS
    programs. The load conditions for OS/2 are different.

    6. /P1 switch Implies a One-Pass Assembly

    Qasm supports a one-pass assembly run as well as the standard
    two-pass assembly run.

    A listing cannot be produced when the single-pass option is chosen,
    i.e., /Fl and /a are not tolerated when the /P1 option is given).

 7. Screen-Oriented Listing File

    /Se is a new option that instructs Qasm to generate a listing
    file that is oriented to the screen rather than a disk file. Use of
    this option implies the following:

    a. No page headers or formfeeds will be inserted.

    b. The first argument to the PAGE command will have no effect.

    c. The default PAGE's second argument will be 255.

    d. TITLE and SUBTTL directives will be ignored.

 8. /Sp Is the Counter Option to /Se

    /Sp produces a printer-oriented listing file.

 9. Object Code Improvements

    Near JMPs and CALLs to nonexternal labels used to have associated
    FIXUPs generated. Qasm now calculates the relative displacement
    internally, rather than having the linker do it. This process
    saves 7 bytes per JMP/CALL in terms of .obj size.

    Shorthand fixup forms are now used. If the frame is equal to the
    target, a frame=target form of fixup is used, and the frame datum
    is not needed. Similarly, if the frame is equal to the location,
    the frame=location form is used.

    Threads are now defined, and thread fixups are used where possible.

 All of these changes should decrease the size of the resultant object.
 Savings in size should range from 5 to 20 percent.



 7. Error C4096: "Unkown Warning" May Be Caused by C1.ERR Omission

 Product Version(s): 2.01
 Operating System:   MS-DOS
 Flags: ENDUSER | docerr
 Last Modified: 28-JUN-1989    ArticleIdent: Q45680

 An error was made in the file C1.ERR, which is included in the
 Microsoft QuickAssembler package, where one error listing was omitted.

 This omission produces the following warning whenever you compile a C
 program and have the "Generate Com file" option chosen in the menu
 Options.Make.Linker Flags:

    C4096: UNKNOWN WARNING
           Contact Microsoft Technical Support

 This warning is not "unknown"; rather, it is just omitted. Actually, C4096
 means the following:

    C4096    "-AT treated as -AS"

 To correct this problem, you need only insert the following line in
 the file C1.ERR:

    C4096    "-AT treated as -AS"

 You should insert this line into the file so that it is correctly
 ordered (i.e., C4096 should follow C4095...).

 This ommission will be corrected in subsequent releases of the
 QuickAssembler package.


 8. -P1 One-Pass Assembly Can Result in A2006 Phase Error

 Product Version(s): 2.01
 Operating System:   MS-DOS
 Flags: ENDUSER | buglist2.01
 Last Modified: 26-JUL-1989    ArticleIdent: Q46380

 A phase error message is generated by the QuickAssembler Version 2.01
 if the -P1 one pass assembly option is chosen and the following
 scenario is fulfilled:

 1. On any binary arithmetic instruction (AND, ADD, OR, CMP, SUB, XOR,
    SBB, ADC) where the first operand contains a forward reference to a
    WORD data label

 2. The second operand is a nonforward referenced symbolic immediate
    whose value could be represented in a sign-extended byte (i.e.,
    007fh, 0ff84h, -1, 12, but not 0081h since it sign-extends to
    0ff81h)

 Any of the following actions will resolve this error:

 1. Use -P2.

 2. Define the data label before the point of reference.

 3. Use a BYTE PTR type cast operation on the immediate symbol (i.e.,
    "cmp foo, byte ptr bar").

 Microsoft has confirmed this to be a problem in QuickAssembler Version
 2.01. We are researching this problem and will post new information as
 it becomes available.

 The following example will reproduce this problem:

 TRUE            equ     1               ; Boolean True value
 CSEG    SEGMENT PARA PUBLIC 'CODE'
         ASSUME  CS:CSEG,DS:CSEG,SS:CSEG ; Already set by DOS loader (COM File
         ASSUME  CS:CSEG,SS:CSEG         ; Already set by DOS loader (COM File

         org     100h
 entry:                                  ; Program entry point
 queueScreen proc near                   ; Procedure declaration
         cmp     cs:screenQueued,TRUE    ; screenQueued is forward referenced.
         ret
 queueScreen endp

 screenQueued    dw      0

 CSEG    ENDS
         END     entry

 to resolve the phase error in this specific example, do one of the
 following:

 1. Select -P2, the two-pass assembly option.

 2. Change the following line

       cmp     cs:screenQueued, TRUE

    to the following:

       cmp     cs:screenQueued, byte ptr TRUE

 3. Move the definition of screenQueued so that it is defined prior to
    the compare instruction, for example:

                 screenQueued    dw      0
                 .
                 .
                 .
                 cmp     cs:screenQueued, TRUE

 Any of these solutions will work around this phase error problem in
 this specific example. These solutions prevent many phase errors from
 occurring when assembling similar kinds of data references with either
 QuickAssembler or MASM since the source of phase errors is usually due
 to the assembler making an incorrect assumption about the type of a
 variable that is referred to before it is defined.



 9. QuickAssembler 2.01 PACKING.LST

 Product Version(s): 2.01
 Operating System:   MS-DOS
 Flags: ENDUSER | distribution directory disks
 Last Modified: 26-JUL-1989    ArticleIdent: Q46840

 The following is the packing list file (PACKING.LST) for the
 QuickC/QuickAssembler Version 2.01 5.25-inch disk set:

 Disk 1 : QuickAssembler/QuickC Setup

 Files                       Description
 -----                       -----------

 PACKING.LST                 Packing list (this file)
 SETUP.EXE                   Setup program for QuickC with QuickAssembler
 README.DOC                  Release notes for QuickC with QuickAssembler
 HELPMAKE.EXE                Creates and customizes help files
 MSHERC.COM                  TSR -- supports Hercules card graphics
 FIXSHIFT.COM                Fixes BIOS bug for some Compaq and other keyboard

 DOSPATCH\PATCH320.DOC       Patch files for MS-DOS 3.20 and PC-DOS 3.20
 DOSPATCH\SETRHS.EXE         " -- Read the .DOC files for details
 DOSPATCH\RMRHS.EXE          " "
 DOSPATCH\STKPAT.BAT         " "
 DOSPATCH\STKPAT.SCR         " "
 DOSPATCH\PATCH87.DOC        " "
 DOSPATCH\PATCH87.EXE        " "

 SAMPLES\SAMPLES.DOC         Sample C programs
 SAMPLES\GRDEMO.C            " -- Read SAMPLES.DOC for details
 SAMPLES\GRDEMO.MAK          " "
 SAMPLES\MENU.C              " "
 SAMPLES\MENU.H              " "
 SAMPLES\TURTLE.C            " "
 SAMPLES\TURTLE.H            " "
 SAMPLES\LIFE.C              " "
 SAMPLES\TOOLS.C             " "
 SAMPLES\TOOLS.H             " "
 SAMPLES\LIFE.MAK            " "
 SAMPLES\CRLF.C              " "

 Disk 2 : Learning the QuickC Integrated Environment

 Files                       Description
 -----                       -----------

 LEARN.COM                   On-line tutorial and introduction to QuickC
 LC.PGM                      Tutorial support files
 QCCBT.CTX                   " "
 QCCBT.SCN                   " "
 QCCBT.SOB                   " "
 LINK.EXE                    Special linker for Windows and OS/2 developers

 Disk 3 : Integrated Development Environment 1

 Files                       Description
 -----                       -----------

 QC.EXE                      QuickCintegrated programming environment
 QC.INI                      Default .INI file for QuickC

 Disk 4 : Integrated Development Environment 2

 Files                       Description
 -----                       -----------

 QCC.OVL                     QuickCoverlay for the integrated environment
 C1.ERR                      Compiler error messages for QC and QCL
 NMAKE.EXE                   Stand-alone program maintenance utility

 INCLUDE\ASSERT.H            Include files
 INCLUDE\BIOS.H              "  -- Read the beginning of each file for details
 INCLUDE\CONIO.H             " "
 INCLUDE\CTYPE.H             " "
 INCLUDE\DIRECT.H            " "
 INCLUDE\DOS.H               " "
 INCLUDE\ERRNO.H             " "
 INCLUDE\FCNTL.H             " "
 INCLUDE\FLOAT.H             " "
 INCLUDE\GRAPH.H             " "
 INCLUDE\IO.H                " "
 INCLUDE\LIMITS.H            " "
 INCLUDE\MALLOC.H            " "
 INCLUDE\MATH.H              " "
 INCLUDE\MEMORY.H            " "
 INCLUDE\PGCHART.H           " "
 INCLUDE\PROCESS.H           " "
 INCLUDE\SEARCH.H            " "
 INCLUDE\SETJMP.H            " "
 INCLUDE\SHARE.H             " "
 INCLUDE\SIGNAL.H            " "
 INCLUDE\STDARG.H            " "
 INCLUDE\STDDEF.H            " "
 INCLUDE\STDIO.H             " "
 INCLUDE\STDLIB.H            " "
 INCLUDE\STRING.H            " "
 INCLUDE\TIME.H              " "
 INCLUDE\VARARGS.H           " "

 INCLUDE\SYS\LOCKING.H       " "
 INCLUDE\SYS\STAT.H          " "
 INCLUDE\SYS\TIMEB.H         " "
 INCLUDE\SYS\TYPES.H         " "
 INCLUDE\SYS\UTIME.H         " "

 Disk 5 : Utilities

 Files                       Description
 -----                       -----------

 CRLF.EXE                    Removes CTRL characters and inserts CR/LFs
 LINK.EXE                    Linker
 ILINK.EXE                   Incremental linker
 ILINKSTB.OVL                Ilink overlay
 LIB.EXE                     Library maintenance utility
 ERRORS.HLP                  Help on error messages
 QCC.DAT                     Data file used by QC environment
 MOUSE.COM                   Microsoft mouse driver - Version 6.24a
 MKKEY.EXE                   Creates customized keyboard command files
 BRIEF.KEY                   Keyboard files
 EMACS.KEY                   " "
 EPSILON.KEY                 " "
 ME.KEY                      " "
 QC.KEY                      " "

 Disk 6 : Microsoft Quick Advisor

 Files                       Description
 -----                       -----------

 QC.HLP                      Help on C and library functions

 Disk 7 : Command-Line Compiler

 Files                       Description
 -----                       -----------

 QCCOM.EXE                   Command-line compiler
 QCL.EXE                     Driver for command-line compiler
 QCL.HLP                     Help on QCL
 CL.ERR                      Error messages for QCL and QC
 GRAPHICS.HLP                Help on graphics functions

 Disk 8 : Libraries 1

 Files                       Description
 -----                       -----------

 SLIBC.LIB                   Library for small model
 SLIBFP.LIB                  Floating-point math library (small model)
 SVARSTCK.OBJ                Small model competing heap/stack object file
 MLIBC.LIB                   Library for medium model
 MLIBFP.LIB                  Floating-point math library (medium model)
 MVARSTCK.OBJ                Medium model competing heap/stack object file

 Disk 9 : Libraries 2

 Files                       Description
 -----                       -----------

 BINMODE.OBJ                 Changes default file I/O mode from text to binary
 SETARGV.OBJ                 Allows wildcards in command-line arguments
 RMFIXUP.OBJ                 Removes interrupts; forces coprocessor math
 DBUSED.OBJ                  Needed when linking with C 5.10 OS/2 libraries
 EM.LIB                      FP math library for software emulation of 8087
 LIBH.LIB                    General helper library
 GRAPHICS.LIB                Low-level graphics library
 PGCHART.LIB                 Presentation graphics library
 CLIBC.LIB                   Library for compact model
 CLIBFP.LIB                  Floating-point math library (compact model)
 CVARSTCK.OBJ                Compact model competing heap/stack object file

 Disk 10 : Libraries 3/fonts

 Files                       Description
 -----                       -----------

 87.LIB                      Floating-Point math library for 8087 coprocessor
 LLIBC.LIB                   Library for large model
 LLIBFP.LIB                  Floating-point math library (large model)
 LVARSTCK.OBJ                Large model competing heap/stack object file

 FONT\COURB.FON              Font files
 FONT\HELVB.FON              " "
 FONT\MODERN.FON             " "
 FONT\ROMAN.FON              " "
 FONT\SCRIPT.FON             " "
 FONT\TMSRB.FON              " "

 NOTES.HLP                   User-defined help file

 Disk 11 : Quickassembler 1

 Files                       Description
 -----                       -----------

 QAS.OVL                     QuickAssembler overlay

 SAMPLES\QASAMPLE.DOC        Sample C and Assembler programs
 SAMPLES\FILEDEMO.MAK        " -- Read QASAMPLE.DOC for details
 SAMPLES\FILEDEMO.C          " "
 SAMPLES\FILE.ASM            " "
 SAMPLES\MATHDEMO.MAK        " "
 SAMPLES\MATHDEMO.C          " "
 SAMPLES\MATH.ASM            " "
 SAMPLES\MISCDEMO.MAK        " "
 SAMPLES\MISCDEMO.ASM        " "
 SAMPLES\MISC.ASM            " "
 SAMPLES\COMMON.ASM          " "
 SAMPLES\DEMO.H              " "
 SAMPLES\DEMO.INC            " "
 SAMPLES\CHRTDEMO.C          " "
 SAMPLES\CHRTDEMO.H          " "
 SAMPLES\CHRTSUPT.C          " "
 SAMPLES\CHRTOPT.C           " "
 SAMPLES\CHRTDEMO.MAK        " "

 Disk 12 : Quickassembler 2

 Files                       Description
 -----                       -----------

 QA.HLP                      Help on the QuickAssembler - Part 1 of 2

 Disk 13 : Quickassembler 3

 Files                       Description
 -----                       -----------

 QA1.HLP                     Help on the QuickAssembler - Part 2 of 2
 QCENV.HLP                   Help on the QuickC environment


 10. .DBG File Needed to Debug .COM File

 Product Version(s): 2.01
 Operating System:   MS-DOS
 Flags: ENDUSER |
 Last Modified: 26-JUL-1989    ArticleIdent: Q47029

 To debug a .COM file produced with the QuickAssembler, the linker
 places necessary symbolic information in a file with the extension
 .DBG. If this file is deleted, no error message is issued, but the
 QuickAssembler will report that the program does not contain debug
 information. At this point, it asks if you would like to rebuild with
 the debug information. In general, you should do this rebuild so that
 you can use the full power of the QuickAssembler debugger.

 If you choose not to rebuild by selecting "No", then any debugging
 command that requires debugging information, including breakpoints and
 displays of variables by name, will be unavailable. Because of this,
 Microsoft recommends rebuilding to include debugging information
 before debugging.



 11. .COM File Example Produces Warning

 Product Version(s): 2.01
 Operating System:   MS-DOS
 Flags: ENDUSER |
 Last Modified: 26-JUL-1989    ArticleIdent: Q47030

 Page 80 of the "QuickAssembler Programmer's Guide" contains an example
 of a .COM file. This example produces a nonfatal warning if assembled
 and run. The warning reads as follows:

    warning A5132: .Startup found without matching .Exit

 Accessing Quick Help reveals that the use of the .Startup directive
 should be used in conjunction with an .Exit directive. To eliminate
 this warning, place an .Exit directive on the line preceding the END
 statement in the example shown in the "QuickAssembler Programmer's
 Guide." The warning issued is a nonfatal warning. The program should
 function correctly.


 12. .Startup Not Interchangeable with ORG Instruction, Tiny Model

 Product Version(s): 2.01
 Operating System:   MS-DOS
 Flags: ENDUSER | docerr
 Last Modified: 26-JUL-1989    ArticleIdent: Q47031

 Page 80 of the "QuickAssembler Programmer's Guide" implies that the
 .Startup directive in a tiny model program can be readily replaced
 with an ORG 100h instruction. This is not true. The .Startup directive
 does more than just generate an ORG 100h in the tiny memory model. If
 you try to replace .Startup with ORG 100h, you get the following error
 during the link phase:

    LINK : fatal error L2051: start address not equal to 0x100 for /TINY

 In all memory models, the .Startup directive generates necessary
 start-up code for the given memory model and stack type. It also
 initializes DS, SS, and SP, as necessary.

 Be sure to use .Exit as well as .Startup to avoid other errors.


 13. QuickC Hangs When Running .COM if "SET LINK=/CO"

 Product Version(s): 2.01
 Operating System:   MS-DOS
 Flags: ENDUSER | buglist2.01 S_QuickC
 Last Modified: 10-OCT-1989    ArticleIdent: Q47233

 The QuickC (QC) Version 2.01 environment hangs if you perform the
 following steps:

 1. Set the link environment variable at the DOS prompt with the /CO
    option (i.e., "d:\> set link=/CO").

 2. Enter the QuickAssembler (QA) environment with an assembly file in
    .COM format.

 3. Assemble and link the source code.

 4. Run the program in the environment; at this point you're now hung.

    Run this program at the DOS prompt, and the program executes
    properly without hanging.

 To resolve this problem, you must remove the link environment variable,
 delete the .COM file, and then reassemble/link the assembly source.

 Microsoft has confirmed this to be a problem with Version 2.01 of
 QuickC/QuickAssembler. We are researching this problem and will post
 new information as it becomes available.

 Note: It is not necessary to set the link environment variable
 with the /CO CodeView option since this facility is offered within
 the QuickC shell. This can be set by selecting the following:

    OPTIONS.Make.Linker Flags.CodeView Information

 The following source code demonstrates this problem:

 ;Program: HANG.COM
 ;Purpose: Demonstrates hanging problem in QuickC 2.01.
 .MODEL  TINY
 .DATA

 msg     DB      "Hello, world.", 13, 10, "$"

 .CODE
                 org 100h
 entry:                                       ; Program entry point
 HELLO proc near
                 nop
                 mov     ah, 9h               ; Request DOS Function 9
                 mov     dx, OFFSET msg       ; Load DX with offset of string

                 int     21h                  ; Display String

                 mov     ax, 4C00h
                 int     21h

 HELLO endp
 END entry

 The hang occurs before the first instruction is executed. QC switches
 to the output screen, displays the "HANG.COM" title, and hangs.

 The .COM file is polluted when you assemble with the link=/CO
 environment variable set from DOS. This can be demonstrated by the
 fact that if you hang your machine as noted above, reboot (without
 link=/CO env var), and then run HANG.COM from within QA (without
 reassembling), you again successfully hang your computer.


 14. QuickC and QuickAssembler Cannot Debug Code in Include Files

 Product Version(s): 2.01
 Operating System:   MS-DOS
 Flags: ENDUSER | docerr S_QuickC S_CodeView
 Last Modified: 10-OCT-1989    ArticleIdent: Q49067

 The QuickC and QuickAssembler environment debuggers do not allow the
 debugging of executable code in include files. The problem occurs when
 stepping through the program using the F8 key. When the debugger
 encounters the line containing the include statement, the debugger
 attempts to execute the code that is outside of the main module, with
 unpredictable results.

 The explanation of the include directive for assembly programs on Page
 240 of the Microsoft "QuickAssembler Programmer's Guide" is unclear.
 This explanation notes that "any standard code can be placed in an
 include file." However, it is not mentioned in this explanation that
 subsequent problems will arise when attempting to debug these
 routines.

 This problem is related to the way in which symbolic information is
 coded and is a known limitation of the QuickAssembler and QuickC
 debuggers, as well as the CodeView debugger.

 The solution to this problem is to include only macros, equates, and
 standard segment definitions in the include files when debugging.


 15. QuickAssembler Error Messages Are Not in Manuals

 Product Version(s): 2.01 2.51
 Operating System:   MS-DOS
 Flags: ENDUSER |
 Last Modified: 15-AUG-1990    ArticleIdent: Q61588

 Error messages for QuickAssembler versions 2.01 and 2.51 are available
 only through online help. The "Microsoft QuickAssembler Programmer's
 Guide" contains no error messages and the "Microsoft QuickC Toolkit"
 manual contains only QuickC compiler, command- line, run-time, LINK,
 LIB, NMAKE, and HELPMAKE errors.

 To obtain information on QuickAssembler errors, use the online help in
 the QuickC environment. The following are two different ways to do
 this:

 1. Type the error number in the environment and press the F1 key or
    press the right mouse button.

 2. After compiling, when error messages are viewable in the ERROR
    window, either place the cursor on the error number and press the
    F1 key or press the right mouse button.

 For example, if you want to obtain extra information on the Assembler
 error "A2009: Symbol not defined," type A2009 from within the QuickC
 environment and press the F1 key. A help window will pop up with
 information concerning the A2009 error.


 16. /Ta Switch Is Not Used By QuickC with QuickAssembler

 Product Version(s): 2.00 2.01 2.50 2.51
 Operating System:   MS-DOS
 Flags: ENDUSER | docerr buglist2.01 buglist2.51
 Last Modified: 14-DEC-1990    ArticleIdent: Q67511

 Page 100 of the Microsoft QuickC "Toolkit" manual states that the
 /Ta"filename" option is used to specify an assembly file to assemble,
 even if the file does not have a .ASM extension. It also states that
 the Microsoft Macro Assembler will be used to assemble the file. For
 the QuickC with QuickAssembler product, this is incorrect.

 The /Ta switch is used by QuickC version 2.00 and 2.50 to allow
 assembly files to be assembled by MASM. QuickC with QuickAssembler
 versions 2.01 and 2.51 ignore the switch. This causes a problem
 because the filename specified after the /Ta switch will be
 interpreted as an option, and the following error message will be
 generated:

    command line fatal error A1017: unknown option: file.ext

 The only workaround for this avoid the /Ta switch all together and
 specify all assembler files with the .ASM file extension.

 Microsoft has confirmed this to be a problem in QuickC with
 QuickAssembler versions 2.01 and 2.51. We are researching this problem
 and will post new information here as it becomes available.


 17. Use /Ln When Creating .COM Files from Command Line

 Product Version(s): 2.51
 Operating System:   MS-DOS
 Flags: ENDUSER | s_quickc docerr
 Last Modified:  6-FEB-1991    ArticleIdent: Q67756

 When using the command line version of QuickC with QuickAssembler
 version 2.51 to create a .COM file from a .ASM file, it is necessary
 to specify the /Ln switch to stop the C run time from being linked in.
 If the /Ln switch is not used, the run-time library CRTCOM.LIB is
 added to the link line and the following unresolved external error
 messages will be generated:

    _main
    __setargv
    __setenvp
    __nullcheck
    __fptrap
    __acrtmsg

 Page 383 of the "Programmer's Guide" for QuickC with QuickAssembler
 doesn't mention this in the example command line.


 18. PUBLIC Keyword Necessary in Most Multiple Modules Programs

 Product Version(s): 2.01
 Operating System:   MS-DOS
 Flags: ENDUSER | docerr
 Last Modified: 17-JUL-1990    ArticleIdent: Q50349

 According to Page 173 of the "QuickAssembler Programmer's Guide," a
 function must be declared PUBLIC in the case of full segment
 definitions, but is not needed when using simplified segments. This is
 only partially correct. Simplified segment directives must be used
 with a language declaration to resolve external symbols to avoid the
 need for the PUBLIC keyword. If a high level language is not
 specified, the PUBLIC keyword must be included on every symbol that
 will be accessed from another module.


 19. Formatted Listings Are Not Created in Environment

 Product Version(s): 2.01
 Operating System:   MS-DOS
 Flags: ENDUSER |
 Last Modified: 21-MAR-1990    ArticleIdent: Q51651

 Creating formatted listings to include page breaks and page headers is
 not possible within the Quick Assembler environment.

 It might appear that this could be done because within the Quick
 Assembler environment, you can choose to have a listing created and
 then view that listing after it has been created.

 It then follows that this listing would be of the same format as the
 one that can be created from the command line (using QCL). However,
 this is not the case. The listings that are created within the
 environment do not contain either page headers or page breaks.

 If you want to put page breaks in the document, a comment can
 be entered as follows:

    ; [ALT 12]

 This will put the formfeed character into the document and cause the
 listing to page forward when it is printed.


 20. QuickAssembler 2.01 Cannot Debug Code in INCLUDELIB Libraries

 Product Version(s): 2.01
 Operating System:   MS-DOS
 Flags: ENDUSER | buglist2.01
 Last Modified: 18-DEC-1989    ArticleIdent: Q50521

 Due to the INCLUDELIB directive, the QuickAssembler cannot debug
 source code in libraries that are linked in. When tracing into the
 library that is included with the directive, the debugger stops
 execution of the program and reassembles the source for the library
 routine. This is not the expected behavior of the assembler/debugger,
 but the following workarounds are quite simple.

 The first option is to debug the library routine before placing it in
 the library. To do this, include the file in the program list, which
 then links the object file instead of the library. In this form, the
 routine can be traced into and the code can be debugged. When the
 modules have been debugged, they can then be included in a library
 that is linked in by use of the INCLUDELIB directive. After the
 routines are included in the library, use the F10 key to step over the
 calls to routines in the library. This executes the routine without
 trying to display the source for it.

 Another workaround is to put the library in the program list instead
 of using INCLUDELIB. By including the library in the program list,
 QuickAssembler will debug source code that is in the library routine.
 Therefore, you can trace into the source code (even when it is
 included in a library) without problem. Use this option if you want to
 trace into any function in your program (meaning routines in both
 object modules and libraries.

 Microsoft has confirmed this to be a problem with QuickAssembler
 Version 2.01. We are researching this problem and will post new
 information as it becomes available.

 Below is a sample program (consisting of two files) that demonstrates
 the problem:

 ******** FILE 1 ********

 ;  HELLO.ASM
 ;
 ;  This is a simple hello world program that will use
 ;  both DOS display string and DOS Write functions.

 TITLE  HELLO
 DOSSEG
 ; Uncomment the following INCLUDELIB statement, then step through the
 ; CALL WRT line to step into the code for WRT. This will cause the
 ; problem.
 ;INCLUDELIB wrt.lib
 .MODEL SMALL
 .DATA
 MSG      DB   "Hello World",0Dh,0Ah,24h

 .STACK 800H

 .CODE
                 EXTRN WRT:PROC
 .STARTUP
                 PUSH  DX
                 PUSH  CX
                 PUSH  BX

                 MOV   AH, 09h           ; DOS DISPLAY STRING
                 MOV   DX, OFFSET MSG    ; ADDRESS OF STRING
                 INT   21h

                 CALL  WRT               ; MAKE THE WRITE CALL!

     XOR   AL,AL             ; SET UP RETURN CODE
 .EXIT
                 END

 ******** FILE 2 ********

 ; WRT.ASM
 ;
 ; Assemble this file and put it into a library called WRT.LIB. (This
 ; can be done by typing LIB WRT.LIB+WRT.OBJ; after you have assembled
 ; WRT.ASM.
 ;
 ; This file MUST be linked to the above program to avoid unresolved
 ; externals. Either link the .OBJ file or the .LIB file with a program
 ; list, OR uncomment the INCLUDELIB directive above.

 TITLE  WRT
 DOSSEG
 .MODEL SMALL
 .DATA
 MYNAME   DB   "John Smith",0Dh, 0Ah,24h
 LNAME    EQU  $-MYNAME-1

 .CODE
 PUBLIC WRT
 WRT   PROC
                 MOV   AH, 40h           ; DOS WRITE FUNCTION
                 MOV   BX, 01h           ; HANDLE FOR STDOUT
                 MOV   CX, LNAME         ; NUMBER OF CHARACTER TO WRITE
                 MOV   DX, OFFSET MYNAME ; OFFSET OF STRING TO PRINT
                 INT   21h

                 RET
 WRT   ENDP
                 END


 21. Generating .COM Files with QuickAssembler Can Cause Link Error

 Product Version(s): 2.01
 Operating System:   MS-DOS
 Flags: ENDUSER | docerr
 Last Modified: 17-JAN-1990    ArticleIdent: Q51751
 The QuickC Version 2.01 compiler (i.e., QuickAssembler) can and will
 generate .COM files for assembly language programs. Current support
 for the TINY model (.COM files) is not extended to C programs. Thus,
 the program must be in assembly language source code, not in C source
 code.

 Both the assembler and linker in QuickC 2.01 support the TINY memory
 model. The C module does not support the TINY memory model.

 The information contained in the README.DOC, Part 5, Subsection 386,
 states the following:

    "...the following command lines each produce a file with a .COM
     extension:

       QCL /AT sample.asm /link /TINY
       QCL /Fesample.com sample.asm /link /TINY  ..."

 The second command successfully generates a .COM file, but the first
 command generates the following error message:

    LINK: fatal error L1093: CRTCOM.OBJ: object not found

 Typing the following also generates the same error message:

    qcl /AT sample.asm

 The following are four ways to correctly generate a .COM file:

 1. Type the following as listed in the README.DOC.:

       QCL /Fesample.com sample.asm /link /TINY

 2. Type the following:

       qcl /AT /c sample.asm

    Then, type the following:

       link /TINY sample.obj

 3. Through the menu options in the environment, make the following
    selections:

       Options.Make.Linker_Flags.Global_Flags.Generate .COM file

    Note: Full menus must be activated and then Options.Make.
    Linker_Flags.Debug_Flags.Incremental_Link must be disabled.

 4. Type the following:

       QCL sample.asm /link /TINY

    This creates a sample.EXE file that is actually in the .COM format.
    It should be renamed immediately to SAMPLE.COM. This method is also
    correctly listed in the README.DOC.

 Note: The source code must also contain the ".MODEL tiny" directive
 for all of the above methods.

 Microsoft is researching this problem and will post new information
 here as it becomes available.


 22. A1022 Error If Include Environment Variable Is Not Set

 Product Version(s): 2.51
 Operating System:   MS-DOS
 Flags: ENDUSER | buglist2.51
 Last Modified: 11-MAY-1990    ArticleIdent: Q61790

 In QuickC with QuickAssembler version 2.51, when using QCL.EXE to
 compile assembly language programs, if the INCLUDE environment
 variable is not set, the following error is generated:

    command line fatal error A1022: source file name not specified

 This problem does not occur in the QuickC with QuickAssembler
 environment (QC.EXE) or with QuickC with QuickAssembler version 2.01.

 Microsoft has confirmed this to be a problem with QuickAssembler
 version 2.51. We are researching this problem and will post new
 information here as it becomes available.

 The following DOS commands reproduce the "A1022: source file name not
 specified" error:

    SET INCLUDE=
    QCL test.asm

 To compile programs successfully, set the INCLUDE environment variable
 to the QuickC with QuickAssembler INCLUDE directory; for example, SET
 INCLUDE=D:\QCQA\INCLUDE.


 23. QuickAssembler Does Not Support 64K Data Segments

 Product Version(s): 2.01
 Operating System:   MS-DOS
 Flags: ENDUSER  | buglist2.01
 Last Modified: 17-JAN-1990    ArticleIdent: Q51977

 When attempting to create a data segment that is equal to 65536 bytes,
 QuickAssembler (QA) will generate an object file that does not link.
 After assembling a program with 65536 bytes of data, the error L1103
 is generated at link time. This problem occurs with any of the linkers
 provided with Microsoft QuickC with QuickAssembler. The Microsoft
 Macro Assembler produces a valid object module under similar
 conditions.

 The following is sample code:

 ; DATA.ASM
 ; To see the problem, uncomment the second declaration and compile
 ; using the QCL DATA.ASM

        .model small
        .data
 ok     db 65535 dup(?)
 ; bad  db ?
   end

 The problem lies in the size of data segment the QuickAssembler
 generates. Using the Microsoft Macro Assembler, the segment size
 requested in the object module is 10000 for a 64K segment. This same
 64K segment is given length 0 (zero) (rounded at 16-bits) by the
 QuickAssembler.

 Microsoft has confirmed this to be a problem in Version 2.01. We are
 researching this problem and will post new information here as it
 becomes available.


 24. Manual Set Up for QuickAssembler on 3.5-Inch, 720K Floppies

 Product Version(s): 2.01
 Operating System:   MS-DOS
 Flags: ENDUSER |
 Last Modified: 17-JAN-1990    ArticleIdent: Q52200

 The following information describes how to set up Microsoft QuickC
 with QuickAssembler Version 2.01 on a 3.5-inch 720K disk.

 Since the QuickC with QuickAssembler Setup program requires a hard
 drive to work properly, this information describes how to manually set
 up QuickC with QuickAssembler on 3.5-inch 720K floppy disks.

 Disk 1: Integrated Environment
 ------------------------------

    File                     Source Disk
    ----                     -----------

    QC.EXE                   Integrated Development Environment
    QCC.OVL                  QuickAssembler 2
    QAS.OVL                  Integrated Development Environment
    QCC.DAT                  Utilities/Microsoft Quick Advisor
    C1.ERR                   Integrated Development Environment
    LINK.EXE                 Utilities/Microsoft Quick Advisor
    ILINK.EXE                Utilities/Microsoft Quick Advisor
    ILINKSTB.OVL             Utilities/Microsoft Quick Advisor

 Disk 2: Command Line Compiler
 -----------------------------

    File                     Source Disk
    ----                     -----------

    QCL.EXE                  Command-Line Compiler/Libraries 1
    QCL.HLP                  Command-Line Compiler/Libraries 1
    QCENV.HLP                QuickAssembler 2
    QCCOM.EXE                Command-Line Compiler/Libraries 1
    C1.ERR                   Integrated Development Environment
    LINK.EXE                 Utilities/Microsoft Quick Advisor
    ILINK.EXE                Utilities/Microsoft Quick Advisor
    ILINKSTB.OVL             Utilities/Microsoft Quick Advisor

 Disk 3: QuickC Help Files
 -------------------------

    File                     Source Disk
    ----                     -----------

    CL.HLP                   Command-Line Compiler/Libraries 1
    ERRORS.HLP               Utilities/Microsoft Quick Advisor
    GRAPHICS.HLP             Command-Line Compiler/Libraries 1
    NOTES.HLP                Libraries 2/Fonts
    QC.HLP                   Utilities/Microsoft Quick Advisor
    README.DOC               Setup and Learning the Integrated Environment

 Disk 4: QuickAssembler Help Files
 ---------------------------------

    File                     Source Disk
    ----                     -----------

    CL.HLP                   Command-Line Compiler/Libraries 1
    ERRORS.HLP               Utilities/Microsoft Quick Advisor
    GRAPHICS.HLP             Command-Line Compiler/Libraries 1
    NOTES.HLP                Libraries 2/Fonts
    QA.HLP                   QuickAssembler 2
    README.DOC               Setup and Learning the Integrated Environment

 Disk 5: Libraries and Include Files
 -----------------------------------

 Copy the following files onto this disk:

    *   xLIBC.LIB           ("x" can be S, M, C, or L)
    *   xLIBFP.LIB          ("x" can be S, M, C, or L)
    *   EM.LIB or           (For emulator library)
    *   87.LIB              (For 80x87 Library)
    *   LIBH.LIB
        GRAPHICS.LIB        (Optional)
        PGCHART.LIB         (Optional)
        LIB.EXE

 Note: The libraries with an "*" next to them are the component
 libraries that must be in the build library. GRAPHICS.LIB and
 PGCHART.LIB are optional libraries and do not need to be in the
 combined library.

 The following is an example of how to build a small memory model
 emulator library with graphics and pgchart libraries included:

    >LIB SLIBCE.LIB

    Microsoft (R) Library Manager  Version 3.14
    Copyright (C) Microsoft Corp 1983-1989.  All rights reserved

    Library does not exist.  Create? (y/n) y
    Operations:+SLIBC.LIB +SLIBFP.LIB +EM.LIB +LIBH.LIB&
    Operations:+GRAPHICS.LIB +PGCHART.LIB
    List file:<PRESS RETURN>

 The environment variable settings corresponding to this set up are as
 follows:

    SET PATH=A:\;B:\
    SET LIB=B:\
    SET INCLUDE=B:\INCLUDE
    SET TMP=B:\

 Start QuickC with Integrated Environment in Drive A and the Help disk
 for either QuickC or QuickAssembler in Drive B. It is necessary to swap
 the Help disk with the Libraries and Include Files disk during compile
 and link time.

 To compile from the command line, insert the Command Line Compiler
 Disk into Drive A and the Libraries and Include Files in Drive B.

 Note: A similar procedure may be followed for manually setting up
 QuickC with QuickAssembler Fulfillment Kit on 3.5-inch disks, except that
 the libraries do not need to be built. The existing libraries from
 QuickC 2.00 can be used for QuickC with QuickAssembler Version 2.01.


 25. JMP Back More Than 128 Bytes Not Flagged

 Product Version(s): 2.01
 Operating System:   MS-DOS
 Flags: ENDUSER | s_quickc buglist2.01
 Last Modified: 12-FEB-1990    ArticleIdent: Q57484

 The QuickC/QuickAssembler compiler Version 2.01 does not flag an
 attempt to make a short jump backwards further than 128 bytes when one
 pass assembly is enabled. The compiler produces an object file, but it
 is erroneous. If incremental linking is enabled, the file will not
 link properly and the following error message will be returned:

    SOURCE.OBJ (source.asm) : error L2002:  Fixup overflow at 1 in segment
    _TEXT : pos: 175 record type: 9C

 If standard linking is enabled, the file will link, but the program
 will not run properly.

 One pass assembly is enabled by default, both inside and outside the
 environment. Two pass assembly can be enabled by toggling the "One
 Pass Assembly" switch inside the environment. It can also be enabled
 by using the undocumented /P2 switch outside the environment. Two pass
 assembly catches the error and produces the desired message.

 Microsoft has confirmed this to be a problem in QuickC Version 2.01.
 We are researching this problem and will post new information here as
 it becomes available.

 The following source code assembles without errors with one pass
 enabled but should generate an error on a short backward jump of
 further than 128 bytes.

           .model small

           .code

 start:    mov ax, DGROUP
           mov ds, ax
           xor cx, cx

 back:     inc cx
           cmp cx, 2
           jmp done

           xor ax,ax       ; You need 60 or so of these pups.
           xor ax,ax
           .
           .
           .
           xor ax,ax
           xor ax,ax

           jmp short back

 done:     mov ax, 4c00h
           int 21h

           end start


 26. How to Get Sample Programs in QuickAssembler 2.51

 Product Version(s): 2.51
 Operating System:   MS-DOS
 Flags: ENDUSER |
 Last Modified: 11-JUL-1990    ArticleIdent: Q63703

 Question:

 Why do I get a beep when I try to select a sample assembly program
 under QuickAssembler version 2.51?

 Response:

 For all sample programs that are not listed in uppercase, you must
 place your cursor on the filename and click the right mouse button. If
 a mouse is not available, use the TAB key to get the the topic and
 then press F1.

 Note: Programs listed in uppercase are programs that have their own
 help contexts. Therefore, they can be selected by clicking on the left
 mouse button, or by pressing ENTER after placing the cursor on the
 filename. Programs listed in lowercase are accessed via the hyperlink,
 meaning you MUST select the right mouse button.


 27. QuickAssembler Doesn't Generate Debug Information

 Product Version(s): 2.51
 Operating System:   MS-DOS
 Flags: ENDUSER | buglist2.51
 Last Modified: 12-NOV-1990    ArticleIdent: Q64441

 The Microsoft QuickAssembler that comes with Microsoft QuickC version
 2.51 does not generate debug information if assembled from the command
 line (either with QCL or NMAKE).

 If the file is assembled inside the integrated environment, the debug
 information is generated.

 Microsoft has confirmed this to be a problem with version 2.51. We are
 researching this problem and will post new information here as it
 becomes available.


 28. Screen Output Fails When Using Animate with Assembly Files

 Product Version(s): 2.51
 Operating System:   MS-DOS
 Flags: ENDUSER | buglist2.51
 Last Modified: 17-OCT-1990    ArticleIdent: Q65591

 While debugging an assembler program under Microsoft QuickAssembler
 version 2.51, if Animate is selected from the Run menu, the code below
 will not print anything to the output screen if Screen Swap is set to
 On in the Options Run/Debug menu.

 Sample Code
 -----------

         TITLE   HELLO
         .MODEL  small, c
         DOSSEG

         .STACK  100h

         .DATA
 msg     DB      "Hello, world.", 13, 10, "$"

         .CODE
         .STARTUP

         mov     ah, 9h
         mov     dx, OFFSET msg

         int     21h

         .EXIT   0

         END

 The following are three valid workarounds:

 1. In the Run menu, disable Animate.

 2. Make sure Screen Swap is set to On, and then trace (F8) or Step
    (F10) through the program instead.

 Microsoft has confirmed this to be a problem with QuickAssembler
 version 2.51. We are researching this problem and will post new
 information here as it becomes available.


 29. Error L2029 with Unresolved Externals in CRTCOM.LIB

 Product Version(s): 2.51
 Operating System:   MS-DOS
 Flags: ENDUSER |
 Last Modified: 31-JAN-1991    ArticleIdent: Q68689

 If you are attempting to build a .COM file from a .ASM file and you
 get the following unresolved external references on the link step, you
 may have included CRTCOM.LIB in error:

    _main            __NMSG_WRITE
    __FF_MSGBANNER   __nullcheck
    __setenvp        __fptrap
    __setargv        __acrtmsg

 This file is automatically included on the link line if the link
 options are set to generate a .COM file from a .C file. To change this,
 choose Make from the Options menu, choose the Linker Flags menu, and
 change "Generate .COM file" to ASM.






 Microsoft Programmer's Work Bench [Development Environment]
 =============================================================================


 1. Using the Features of PWB to Build a Program with Overlays

 Product Version(s): 1.00   | 1.00
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified: 18-APR-1990    ArticleIdent: Q60050

 A MAKE file built with PWB can be modified (within reason) with the
 user supplied information section. This section, coded as

    # << User_supplied_information >>

 can contain other instructions that PWB (actually NMAKE or NMK) is
 supposed to carry out during the MAKE cycle. All instructions that
 follow this "fence" are not changed by PWB.

 The following instructions detail two implementations of that "fence"
 to allow PWB to build a program that uses overlays.

 While the following steps appear tedious, they are simple in practice.

 Once the changes are made, the only time you need to edit the MAKE
 file directly is to change your overlay structure, or to add or delete
 modules. When adding or deleting modules, you must both edit the
 program list with Make.Edit Program List and modify the commands in
 the user section. If you are only modifying the overlay structure, you
 change just the user section.

 The overlay structure in the example is as follows:

    HELLO.OBJ  (root)
        |
        +----A.OBJ (first  overlay)
        |
        +----B.OBJ (second overlay)

 All of the .OBJs are built from .C files with the same base name.

 1. Use PWB to build the program list in the normal way. This step is
    the same for any new program list.

    a. Start PWB.

    b. Choose Make.Set Program List and specify a new name -- HELLO.MAK
       in this example.

    c. Add HELLO.C, A.C, and B.C to the list. (If you have additional
       .C or .OBJ files, you would add them as well.) When all the
       files are listed, select Set Dependencies.

    d. Choose Options.Build Options and click on the Set Initial
       Build Options button and select DOS EXE.

    e. From Options.Compile Options, select the proper memory model.

    f. From Options.Link Options.Set Debug Options, turn off
       Incremental Link.

    g. From the Options.Browse Options dialog box, turn Generate Browse
       Information on.

    h. Choose Make.Rebuild All to make sure that the program builds
       properly without overlays. If it doesn't, review your work in
       previous steps.

 2. Now that you have a working program list, add the non-PWB
    information to the end.

    a. Choose Make.Clear Program List so that you can edit the MAKE
       file. Attempting to edit the current program list results in the
       message "No-edit file may not be modified."

    b. Choose File.Open to open the MAKE file so you can modify it.

    c. Go to the end of the file and start a blank line.

       Starting in column 1, add the following line:

          # << User_supplied_information >>

       Be sure to enter the line exactly as shown -- spacing is
       significant. This line is a "fence". Everything below the fence
       is yours and is not modified by PWB. Conversely, you should not
       modify anything above the fence because that section belongs to PWB.

    d. Below the fence starting in column one, add the pseudo-target:

          OVERLAID : $(OBJS)

       Be sure it starts column 1. Do not put a blank line after this line.

    e. Copy the command section from the $(PROJ).EXE description block
       to immediately follow the pseudo-target. The command section begins
       on the line following the line that reads

          $(PROJ).exe : $(OBJS)

       and ends at the next blank line. Do not copy the $(PROJ).EXE
       line, and do not leave a blank after the target. After you have
       copied the commands, your file should appear as follows:

          ... PWB section here, unmodified ...

          # << User_supplied_information >>

          OVERLAID : $(OBJS)
          !IF $(DEBUG)                    # copy of commands...
                  $(LRF) @<<$(PROJ).lrf
          $(RT_OBJS: = +^
          ) $(OBJS: = +^
          )
          $@
          ...

    f. Use the following procedure to modify the commands to link an
       overlaid EXE instead of a normal EXE.

       Note: There are two subsections in this section: a debug section
       that starts at the first "!IF $(DEBUG)" and ends at "!ELSE", and
       a release section that starts after the "!ELSE" and ends at the
       first "!ENDIF".

       You need to make the following modifications to both
       subsections.

       i. Delete the line that reads as follows:

             ) $(OBJS: = +^

          After the right parenthesis on the line that moved up, put
          your list of .OBJ files with parentheses to indicate which
          ones go in which overlays. If you need to use more than one
          line for all of your objects, be sure to put a plus sign (+)
          at the end of each line except the last.

      ii. Replace "$@" on the next line with "$(PROJ).EXE".

          In our example,

                 $(LRF) @<<$(PROJ).lrf
             $(RT_OBJS: = +^
             ) $(OBJS: = +^     # delete this line
             )                  # append OBJ list here ...
             $@                 # replace this line with $(PROJ).EXE

          becomes:

                 $(LRF) @<<$(PROJ).lrf
             $(RT_OBJS: = +^
             ) hello.obj +
             (a.obj) +
             (b.obj)
             $(PROJ).exe

          Remember to make the changes in both branches of the !IF
          $(DEBUG).

    g. The last step is to modify the browser database build commands.
       These are the two lines at the very end of the file that begin
       with "$(NMAKEBSC...". PWB adds and deletes these lines in the
       PWB section as you turn browser information on and off.

       Since PWB won't delete and add these lines in the user section,
       enclose them in !IF $(BROWSE)...!ENDIF so they'll be executed
       only when you ask for browse information. You also need to
       delete the "$(NMFLAGS)" macro from the second line to prevent
       infinite NMAKE recursion.

       The following lines

          $(NMAKEBSC1) MAKEFLAGS=
          $(NMAKEBSC2) $(NMFLAGS) -f $(PROJFILE) $(PROJ).bsc

       become:

          !IF $(BROWSE)
              $(NMAKEBSC1) MAKEFLAGS=
              $(NMAKEBSC2) -f $(PROJFILE) $(PROJ).bsc
          !ENDIF

       If you need special NMAKE options for building the browser
       database, just add them where you removed $(NMFLAGS).

 3. Reactivate the MAKE file by selecting Make.Set Program List.

 4. With these changes, if you select Make.Rebuild All, you will still
    get a non-overlaid program because PWB normally builds the first
    target in the MAKE file. To build the overlaid program, modify the
    command line passed to NMAKE so that NMAKE builds your overlay
    target rather than the regular EXE. Select Options.NMAKE Options
    and specify "OVERLAID" as the target by putting it in the NMAKE
    options box, or use Make.Build Target.

 5. With "OVERLAID" in Options.NMAKE Options you can build your program
    by either selecting Make.Rebuild All or Make.Build *.EXE, as usual.
    If you want to build a non-overlaid program, delete "OVERLAID" from
    the NMAKE options box.

    Note that if you use debug options with overlays you will get a
    linker warning L4047. This warning, and the dialog box that says
    that CRT0DAT.ASM can't be found, are normal when building overlaid
    programs for debugging and can be ignored. You can debug the overlaid
    program normally, with full debugging information available.

    This MAKE file behaves almost identically to a regular PWB MAKE
    file. The only differences are that NMAKE options are NOT  passed
    to the browser build unless you add them to the browser build line,
    and that you must edit the user supplied section if you add or
    delete modules from the project.


 2.

 Product Version(s): 1.00   | 1.00
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER | buglist1.00 fixlist1.10 s_c
 Last Modified:  5-FEB-1991    ArticleIdent: Q60392

 TOOLS.PRE is a sample Programmer's WorkBench (PWB) initialization file
 that is installed (and modified) when C 6.00 is installed by running
 the Setup program. On pages 19 and 20 of "Microsoft C: Installing and
 Using the Professional Development System," it states that the
 contents of TOOLS.PRE can be merged with an existing TOOLS.INI file,
 if one exists, or it can be renamed to TOOLS.INI, if there isn't one.
 To work correctly, you must make sure that the contents of this file
 are preceded by a PWB tag (for example, [PWB]) because the supplied
 TOOLS.PRE lacks this tag.

 When merging the PWB 1.00 TOOLS.PRE file into an existing TOOLS.INI
 file, a [PWB] tag should be added just above the area where the file
 is merged. For example:

 [PWB]
   .
   .
   .
   (TOOLS.PRE contents)
   .
   .
   .

 [NEXT-TAG]

 If TOOLS.PRE is being renamed to TOOLS.INI, the tag should be added as
 the first line in the file. In either case, failure to add the tag
 will result in PWB ignoring the initialization information.

 Microsoft has confirmed this to be a problem in PWB version 1.00. This
 problem was corrected in PWB version 1.10.


 3. How to Abort Compilation When Using PWB

 Product Version(s): 1.00   | 1.00
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER | s_c
 Last Modified: 17-JUL-1990    ArticleIdent: Q60500

 Question:

 How do I abort a compile that is in progress when using the
 Programmer's WorkBench (PWB) environment?

 Response:

 Under MS-DOS (or the OS/2 3.x compatibility box), use CTRL+C to abort.

 Under OS/2, use "Arg Meta Compile" to abort a compilation taking place
 in the background.

 The default keystrokes for Arg Meta Compile are ALT+A F9 CTRL+F3.

 You can also create a macro and assign it to a key to abort the
 compile process. Below is a sample macro that you could place in your
 TOOLS.INI file under the [pwb] tag.

    [pwb]
    Abort:=Arg Meta Compile
    Abort:Ctrl+F5

 Note: In either OS/2 or MS-DOS, the ESC key and CTRL+BREAK do not
 abort a compilation.


 4. PWB Makefiles Are Read-Only When Set as Active Program List

 Product Version(s): 1.00   | 1.00
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified: 25-MAY-1990    ArticleIdent: Q60749

 When you choose the Make.Set Program List option within the
 Programmer's WorkBench (PWB) environment to set a program list for the
 current project, the makefile associated with the current program list
 is marked as read-only and is not editable.

 Code Example
 ------------

 // FOO.C

 #include <stdio.h>
 void main ( void )
 {
    printf ( "Foobar\n" ) ;
 }

 1. Using the above sample program, choose the Make.Set Program List
    menu options and call the program list FOO.MAK.

 2. Save the list.

 3. Choose the File.Open menu, and enter FOO.MAK as the file you want
    to open.

 4. Place your cursor anywhere in the file and press ENTER. You will be
    greeted with the following a pop-up message:

       No-edit file may not be modified.

 If you want to edit the makefile, choose the Make.Clear Program List
 options, and you can edit the makefile as you want.


 5. Why Zero-Length .SBR Files Are Left on the Disk by the PWB

 Product Version(s): 1.00   | 1.00
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified: 16-JAN-1991    ArticleIdent: Q61056

 When using the Source Browser functionality within the Programmer's
 WorkBench, you can expect to have zero-length .SBR files on your disk.
 This is by design of the PWBRMAKE utility.

 PWBRMAKE.EXE is a utility that converts the .SBR files created by the
 compiler for each program module into a single database file that can
 be read by the Programmer's WorkBench (PWB) Source Browser. The
 resulting Source Browser database file has the extension .BSC.

 When a Source Browser database (a .BSC file) is built from .SBR files,
 the .SBR files are truncated to zero length to save disk space since
 they can be quite large. .SBR files are truncated to zero length,
 rather than being deleted, because PWBRMAKE performs incremental
 updates to the database and, therefore, needs the time and date stamp
 from the files.

 When you rebuild part of your project, new .SBR files are built for
 those modules. Each .SBR file that has not been re-created during a
 build is included as a zero-length file. This tells PWBRMAKE that the
 file has no new contribution to make to the database, so no update of
 that part of the database is required.


 6. Do Not Start Programmer's WorkBench by Typing PWBED

 Product Version(s): 1.00
 Operating System:   MS-DOS
 Flags: ENDUSER |
 Last Modified: 11-JUL-1990    ArticleIdent: Q61307

 You cannot start the Programmer's WorkBench by typing PWBED. This is
 incorrect. Type PWB to start the Programmer's WorkBench environment.

 In the REAL MODE directory specified during setup, there will be two
 executables for the PWB, PWB.COM and PWBED.EXE. PWB.COM actually
 spawns PWBED.EXE. If you use PWBED to start the PWB, it will consume
 approximately 500K of memory. By executing a DOS SHELL from within the
 PWB and running CHKDSK, you will notice there is very little memory
 left.

 When you invoke the PWB the correct way (by typing PWB), then shell-
 out and do a CHKDSK, you will see that the PWB has only consumed
 approximately 8K of available memory.

 The PWB appears to work correctly if you invoke it with PWBED.
 However, since it is using so much memory, you will receive memory
 problems, such as "out of memory," "cannot compile," or "cannot
 build." These are caused because there is not enough memory to spawn
 either NMAKE, the compiler, or the linker.


 7. Steps Needed to Make Source Browser Usable

 Product Version(s): 1.00    | 1.00
 Operating System:   MS-DOS  | OS/2
 Flags: ENDUSER |
 Last Modified: 11-JUL-1990    ArticleIdent: Q61309

 Before using the Browse menu options, you must first define and build
 the database the Source Browser will use. If this database is not
 already built, all options on the Browse menu will be grayed out and
 unusable.

 The following steps must be taken to define a database that is usable
 by the Source Browser menu options:

 1. Generate a program list using the Set Program List command in the
    Make menu. The PWB creates one internally if you do not specify one
    and the program only uses one source file. If a program is larger
    than one source file and a program list is not set, it is
    impossible to generate a Source Browser database.

 2. Choose Browse Options from the Options menu. You must select the
    Generate Browse Information field in the dialog box to create the
    Source Browser database.

 3. Build your program using the Make Menu option. You MUST have a
    successful build (compile AND link) of the program for a Source
    Browser database to be generated.

 The Browse Menu options should now be available for use.

 If, after taking the steps outlined above, the Browse Menu options
 are still unavailable for use, query on the following keywords:

    Browse and Options and Unavailable and Strange and Circumstances
 For printed documentation explaining the setup and use of the Source
 Browser, see Pages 50-52 of "Installing and Using the Professional
 Development System." You can also find information about the Source
 Browser in the online help under Programmer's WorkBench, Using the PWB
 Source Browser.


 8. SYS2070 Issued When Executing PWB.EXE for the First Time

 Product Version(s): 1.00
 Operating System:   OS/2
 Flags: ENDUSER |
 Last Modified: 13-JUN-1990    ArticleIdent: Q61572

 When running the Programmer's WorkBench (PWB) for the first time, the
 following OS/2 system error may be issued:

    Session Title:
    PWBED.EXE

    SYS2070: The system could not demand load the
    application's segment. MSHELP HELPSHRINK is in error.
    For additional detailed information also see message SYS0127

 This system error is caused by the PWB's use of a version of
 MSHELP.DLL that is not as current as the one that was shipped with C
 version 6.00. For the PWB to function correctly, the correct version
 of MSHELP.DLL must be in the LIBPATH.

 The README.DOC on the C version 6.00 Setup/Compiler 1 Disk warns of
 this potential problem, and suggests that QuickHelp (QH) be terminated
 as a background keyboard monitor before Setup is run.

 This problem is usually caused as a result of the Setup program not
 being able to copy its version of MSHELP.DLL over the old version of
 MSHELP.DLL. If another process (most likely a detached session of
 QH.EXE) was accessing this file during the execution of Setup, the
 Setup program will issue a message similar to the following:

    ERROR: Could not create file C:\OS2\DLL\mshelp.dll
    ERROR: File copy failed: A:\the PWB\mshelp.dll to C:\OS2\dll\mshelp.dll

 To solve this problem, take the following steps:

 1. Disable QH as a keyboard monitor:

    a. Press ALT+Q (to invoke QH).

    b. Press O (for the Options menu).

    c. Press T (to Terminate the monitor).

 2. Copy the up-to-date version of MSHELP.DLL from the distribution
    disk:

    a. Insert the Setup/Compiler 1 Disk into Drive A.

    b. Change the default Drive A.

    c. Run Setup with the /copy option by typing the following:

          setup /copy

    d. Press ENTER

    e. Press ENTER again (unless the setup files are in a drive other
       than A).

    f. At the prompt asking for the name of the file to copy, type
       MSHELP.DLL and press ENTER.

    g. At the prompt asking for the name of the directory to which to
       copy this file, type the directory in which the old MSHELP.DLL
       is located (most likely C:\OS2\DLL).

    h. Setup should then ask for the Programmer's WorkBench/Utilities
       for OS/2 Disk to be inserted into the setup drive.

    i. When Setup is finished copying the file, press ENTER at the
       next prompt.

 The PWB should now start up correctly.


 9. U1355 Bad Command or File Name

 Product Version(s): 1.00   | 1.00
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER | docerr filename
 Last Modified: 27-SEP-1990    ArticleIdent: Q61607

 The following undocumented error may occur when attempting to run an
 executable file such as CL.EXE, LINK.EXE, NMAKE.EXE, etc., from inside
 the Programmer's WorkBench (PWB).

    U1355 Bad Command or File Name

 The error occurs because the directory containing the .EXE file is not
 specified in the search path or an incorrect LINK.EXE is being
 executed.

 This problem can be corrected by adding the missing directory name(s)
 to the path in the AUTOEXEC.BAT or STARTUP.CMD and rebooting, or
 executing NEW-VARS.BAT or NEW-VARS.CMD. If an incorrect linker is the
 problem, the search path can be rearranged to find the new version of
 the linker first, or the old linkers can be deleted or renamed.
 Finally, it may be necessary to delete the CURRENT.STS and PROG.STS
 files before the PWB will work correctly. This error is not documented
 in the PWB online help.


 10. Saving Compiler Results File in the PWB

 Product Version(s): 1.00   | 1.00
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified: 25-MAY-1990    ArticleIdent: Q61636

 The Programmer's WorkBench (PWB) deletes the compiler results file
 upon exiting the PWB. In DOS or OS/2, the file can be saved if the
 compiler results window is made current and the File.Save As menu
 option is selected.

 The compiler results file will appear similar to the following:

    +++ PWB  [E:\] Rebuild
            NMAKE  /z /a /f E:\pwb.mak
         cl /c /W4 /Fm /Ot /FoGLOBL.obj GLOBL.C
    Microsoft (R) C Optimizing Compiler Version 6.00
    Copyright (c) Microsoft Corp 1984-1990. All rights reserved.

    GLOBL.C
         echo @GLOBL.lrf > NUL
         link @GLOBL.lrf

    Microsoft (R) Segmented-Executable Linker  Version 5.10
    Copyright (C) Microsoft Corp 1984-1990.  All rights
    reserved.

    Object Modules [.OBJ]: GLOBL.obj,GLOBL.exe,NUL, /NOD:SLIBCE
    SLIBCEP , /NOI /BATCH /EXE /FAR /PACKC;


 11. Programmer's WorkBench Edit Switch Is Unimplemented

 Product Version(s): 1.00   | 1.00
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER | docerr
 Last Modified: 14-MAY-1990    ArticleIdent: Q61642

 The edit switch for the Programmer's WorkBench (PWB), documented on
 Page 79 of the version 6.00 "Microsoft C Reference" manual, is
 unimplemented in PWB version 1.00. The switch is designed to set the
 active file as read-only so that it cannot be edited.

 If you add an option in your TOOLS.INI file under the PWB tag to read
 either

    Edit:yes
    Edit:no

 PWB will return an error message saying "Edit is not an editor
 switch."

 As a workaround, invoke PWB with the /r option to open up the current
 file as read-only.


 12. Certain Key Sequences Cause R6003 or SYS1943 in PWB 1.00

 Product Version(s): 1.00   | 1.00
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER | buglist1.00 fixlist1.10
 Last Modified:  4-FEB-1991    ArticleIdent: Q61660

 In the Programmer's Workbench (PWB) version 1.00, it has been observed
 that certain unusual editing sequences can cause the following errors:

 In DOS:

    Run-time error R6003 - integer divide by 0

 In OS/2:

    SYS1943 protection violation, trap number 13

 The following sequences reproduce the errors:

    Procedure                             Keystrokes
    ---------                             ----------

 1. Bring up several files.               ALT+F O x3
    Select the Options menu.              ALT+O
    Select Linker options.                L
    Select Set Debug Options.             ALT+G
    Pull up help on the options.          F1
    Arg-refresh through several files.    ALT+A SHIFT+F7 x3
    Escape back to the Editor screen.     ESC x3

 2. Select the Options menu.              ALT+O
    Select Editor Settings.               S (or K)
    Go down thirteen lines.               DOWN ARROW key x13
    Backspace.                            BACKSPACE
    Undo.                                 ALT+BACKSPACE

 Note: Step 2 reproduces only the R6003 error in DOS, not the SYS1943
 error.


 13. PWB 1.00 Requires Decimal Value for Stack Size in LINK Options

 Product Version(s): 1.00    | 1.00
 Operating System:   MS-DOS  | OS/2
 Flags: ENDUSER | buglist1.00 fixlist1.10
 Last Modified:  5-FEB-1991    ArticleIdent: Q61871

 In the Programmer's WorkBench (PWB) version 1.00, there is a problem
 with changing a program's stack size in some situations. When
 specifying the stack size in the Link Options dialog box (from the
 Options menu), you must enter the value in the form of a decimal
 integer. Although the Help menu tells you this field accepts positive
 integers in octal and hexadecimal form, PWB 1.00 will not accept them.

 When an octal or hexadecimal value is entered in the stack-size field,
 any digits specified as A-F are discarded and replaced by 0 (zero). If
 digits precede a letter, the digits are retained and the letters are
 discarded.

 Microsoft has confirmed this to be a problem in PWB version 1.00. This
 problem was corrected in PWB version 1.10.


 14. SYS0002 Produced If MSHELP.DLL Not Installed

 Product Version(s): 1.00
 Operating System:   OS/2
 Flags: ENDUSER | pwbhelp
 Last Modified: 23-JAN-1991    ArticleIdent: Q61955

 Under OS/2, if MSHELP.DLL is not installed correctly or is not on the
 LIBPATH, the following error may appear in a window when starting the
 Programmer's WorkBench (PWB):

                     Cannot Autoload Extension
                     e:\c600\binp\pwbhelp.pxt
 MSHELP:  SYS0002:  The system cannot find the file specified

                         < OK >   < Help >

 Make sure that the latest version of MSHELP.DLL (the one that was
 included with the Microsoft C Compiler version 6.00) is installed in a
 directory contained in your LIBPATH.

 If this file was not copied off the disks during setup, you can
 execute the following command with your Setup disk in Drive A:

    a:setup /copy

 Specify the file MSHELP.DLL at the prompt, then specify the
 destination directory.

 The default for SETUP.EXE is to put OS/2 DLLs in the C:\OS2\DLL
 directory. If you choose to install the DLLs in some other directory,
 you must edit the LIBPATH in your CONFIG.SYS file and restart the
 system.


 15. Enabling of Source Browser Menu Related to .BSC and .MAK Files

 Product Version(s): 1.00   | 1.00
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified: 29-MAY-1990    ArticleIdent: Q61968

 The Source Browser feature of the Programmer's WorkBench (PWB) is
 enabled or disabled depending upon the existence of a database file
 (.BSC file) AND a program list (.MAK file). The existence of a .BSC
 database file alone does not guarantee that the Browse menu will be
 enabled for all modules in a project, even if the .BSC file was built
 from .SBR files for every module. The setting of a program list is
 also required.

 Thus, if a .BSC file is built outside of the PWB with PWBRMAKE, then
 upon entering the PWB, the Browser will be enabled for only one module
 at most (see below). The easiest method to enable the Browse menu for
 ALL modules is to select "Set program list" on the Make menu, then
 type in the base name of the .BSC file (with the .MAK or no extension)
 when it prompts you for the filename. If the .MAK file you enter does
 not exist, then the dialog box appears for adding files to the program
 list, whereas you can just select "Save List" without actually adding
 any files. At this point, the Browser menu will be enabled for all
 files you bring up into the PWB editor.

 The existence of a Source Browser database file means that the Browse
 menu will be enabled for a source file with a matching base name of
 the .BSC file.

 For example, assume a project consists of several modules, with the
 main source module called PROJECT.C. In addition, assume a Browser
 database file called PROJECT.BSC is built from the .SBR Browser
 information files produced by the compiler for every module in this
 project. If the file PROJECT.C is brought up in the PWB, the Browse
 menu will be enabled because the base name (PROJECT) is the same as
 the base name of the database file PROJECT.BSC.

 On the other hand, if any of the other source files in the project are
 opened in the PWB, the Browse menu will be disabled because the base
 names do not match the base name of the database file. Also, if
 PROJECT.C is made the current file (which enables the Browse menu) and
 an option is selected on the browse Menu, such as "Goto Reference"
 (which causes a jump to a different module), the Browse menu will
 become disabled. The only way to re-enable the Browse menu in this
 case is to make PROJECT.C the current file again.

 The way to enable the Browse menu for all modules is to set a program
 list to a file with the .MAK extension and the same base name as the
 .BSC file. Thus, in the example above, setting the program list to
 PROJECT.MAK will enable the Browse menu for all modules. In fact, this
 connection between the .BSC file and the .MAK file enables the Browse
 menu for the modules in the current project, and for ANY file opened
 under the PWB.

 The result is that if you bring up a file in the editor that is
 completely unrelated to the current project (and may not even have a
 related .BSC file), you can still use the Browse menu options.
 However, in this situation, the information available from the Browser
 still only pertains to the original project.

 In summary, the .MAK file and .BSC file relationship is based solely
 on the file existence, NOT the file contents. The program list does
 NOT need to contain the names of the modules in the current project
 (or even be an actual makefile) for the Browser to function.


 16. Modifying TOOLS.INI May Have No Effect on PWB Environment

 Product Version(s): 1.00   | 1.00
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified: 17-JUL-1990    ArticleIdent: Q62170

 Changing settings in the TOOLS.INI file to modify the behavior of the
 Programmer's WorkBench (PWB) may not work under certain circumstances.
 For instance, if you decide to change the PWB to 50-line mode by
 setting "height:50" in the TOOLS.INI file, it will not work if the PWB
 was previously used in the 25- or 43-line mode.

 This is because some environment information is also recorded in the
 CURRENT.STS file, which is read in after the TOOLS.INI file --
 overriding the TOOLS.INI settings.

 The following are three workarounds for this problem:

 1. Use the /DS switch when invoking the PWB. This will ignore the
    CURRENT.STS file. However, this option also causes the current file
    history (of files being edited) to be ignored.

 2. Delete the CURRENT.STS file. This also causes the current list of
    programs being edited to be ignored.

 3. The better option is to select Editor Settings from the Options
    menu. When the list of editor switch settings appears, it can be
    changed and saved to the TOOLS.INI file by pressing SHIFT+F2. This
    will save the settings and cause the selection to take effect.


 17. Reversing Mouse Buttons in the PWB Cannot Be Done

 Product Version(s): 1.00   | 1.00
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified: 25-JUL-1990    ArticleIdent: Q62330

 Currently under the Programmer's WorkBench (PWB) released with version
 6.00 of the Microsoft C Optimizing Compiler, it is not possible to
 reverse the functionality of the mouse buttons.

 It is possible to change the functionality of the mouse buttons under
 OS/2 and DOS, but this will be overridden by the PWB environment.


 18. Attempting to Expand a Help Dialog Box Hangs DOS

 Product Version(s): 1.00   | 1.00
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER | buglist1.00
 Last Modified: 25-JUL-1990    ArticleIdent: Q62331

 When one of the pull-down menus in the Programmer's WorkBench (PWB)
 version 1.00 is selected (File, Edit, View, etc.) and then F1 is
 chosen for help on that menu, a small help screen appears. If CTRL+F10
 is chosen in an attempt to expand the window to full screen, the
 machine will hang under DOS. If the machine doesn't hang, it may
 require another invocation of CTRL+F10 to cause the problem.

 Under OS/2, the machine may not hang, but the PWB's functionality will
 be disrupted and attempts to free oneself may cause a GP fault. It may
 be possible to exit the PWB, but at the very least, the CURRENT.STS
 file will be corrupted so that future entrances to PWB will result in
 very odd window configurations.

 Microsoft has confirmed this to be a problem with the PWB version
 1.00. We are researching this problem and will post new information
 here as it becomes available.


 19. PWB Doesn't Update Mark Location If Mark Moves Up or Left

 Product Version(s): 1.00 | 1.00
 Operating System:   OS/2 | 1.00
 Flags: ENDUSER | buglist1.00
 Last Modified: 13-JUN-1990    ArticleIdent: Q62388

 If you set a mark in a file, and that location then moves upward or
 toward the left in the file, PWB does not reset the mark location;
 however, it does correctly update marks that move downward or to the
 right in the file.

 Consider the following file:

 /* Test.dat */
 test1

 test2

 test3

 Place the cursor on the "2" in test2. Choose the Search.Define Mark
 menu option. Name the mark "mark1" and press ENTER. Now, move the
 cursor to another location in the file. Choose the Search.Go To Mark
 option from the menus. Go to "mark1". Note that the cursor is back on
 the "2" in test2.

 Next, add another blank line between test1 and test2. Again, move your
 cursor and go to mark1. Note that the cursor is back on the "2" in
 test2.

 Now, delete both the lines between test1 and test2. Select the
 Search.Go To Mark option from the menus. Note that the cursor is on
 the same location as it was before you deleted these lines. The same
 behavior will happen if you delete any of the characters before the
 "2" in the test2 line.

 Microsoft has confirmed this to be a problem in the Programmer's
 WorkBench (PWB) version 1.00. We are researching this problem and will
 post new information here as it becomes available.


 20. PWB 1.00 "Set Dependencies" Fails with Spaces in #include Line

 Product Version(s): 1.00   | 1.00
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER | buglist1.00 fixlist1.10 s_c
 Last Modified:  5-FEB-1991    ArticleIdent: Q62578

 The Programmer's WorkBench (PWB) version 1.00 (shipped with C version
 6.00) includes a "Set Dependencies" option in the "Set Program List"
 window. This option automatically sets up build dependencies for all
 include files used in the current project. This option will fail with
 a message that the include file does not exist if there are embedded
 spaces between the left angle bracket (<) and the include-file name in
 an include directive line.

 The Set Dependencies option will work correctly if the space(s) are
 removed or if a new build option is added to the TOOLS.INI file.

 Although embedded spaces are legal in C programming syntax, the
 Programmer's WorkBench fails to parse the include line correctly if
 spaces exist before the filename. The following line of code shows the
 situation where the "Set Dependencies" error will occur:

    #include < stdio.h >

 The space before the "s" in stdio.h prevents PWB from finding the
 STDIO.H include file. (The trailing space after stdio.h does not
 affect the behavior of "Set Dependencies".)

 The full text of the error message window for the line above is as
 follows:

         stdio.h does not exist
    Cannot build its dependency tree.
    Abort dependency lists generation?
         <Yes>    <No>    <Help>

 Selecting <Help> displays a help screen that describes the problem as
 being either a mistyped filename or a nonexistent file, but the actual
 file DOES exist. Removing the embedded space will correct the problem.

 You can also add two new "build" lines to the TOOLS.INI file to make
 the PWB recognize include directives that contain spaces. These lines
 should be included under the section with the [PWB] tag, and should
 have the following syntax:

    build: include .c                                              \
        "^[ \t]*#[ \t]*include[ \t]*\"[ \t]*\\([^\"]+[ \t]*\\)\""  \
        case
    build: include .c                                              \
       "^[ \t]*#[ \t]*include[ \t]*<[ \t]*\\([^>]+\\)[ \t]*>"      \
        case system

 (Note: These build switch statements are broken down into multiple
 lines with the line continuation character (\) because of space
 limitations; you may enter each of them into the TOOLS.INI file on a
 single line, rather than multiple lines.)

 There is one drawback to this workaround; you will still get the error
 message shown above because the "old" build switch is applied before
 the new one. To have the new build switch take effect, you need to
 select "No" when prompted to abort the dependency list generation.
 Once you have selected "No" for each file with spaces in the include
 directive, the dependencies will then be generated correctly.

 Microsoft has confirmed this to be a problem in the Programmer's
 WorkBench version 1.00. This problem was corrected in the Programmer's
 WorkBench version 1.10.


 21. PWB 1.10 Dialog Boxes May Blink After Dialog Help Is Obtained

 Product Version(s): 1.10
 Operating System:   MS-DOS
 Flags: ENDUSER | buglist1.10 flicker
 Last Modified: 19-FEB-1991    ArticleIdent: Q69347

 When working with the Programmer's WorkBench (PWB) version 1.10 under
 DOS, there are several instances where a dialog box may start flashing
 incorrectly. This situation occurs when you obtain help on a PWB
 informational pop-up dialog box and then return from the Help dialog
 screen. At this point you may find that the original dialog box is
 rapidly blinking.

 This problem may occur when trying to get help on a topic for which
 there is no help, trying to use an unassigned key, or when PWB informs
 you that you changed a file but didn't save it before you tried to
 exit. In each of these cases, PWB gives you a pop-up dialog box
 informing you of the situation. If you get help on this informational
 dialog box and then press ESC or click Cancel, the original dialog box
 will start blinking.

 This is not normal behavior, however, PWB is still fully functional
 and you may proceed by selecting an appropriate choice from the
 flashing dialog box.

 Microsoft has confirmed this to be a problem in the Programmer's
 WorkBench version 1.10. We are researching this problem and will post
 new information here as it becomes available.


 22. R6000 Stack Overflow After Deleting Current Makefile

 Product Version(s): 1.00   | 1.00
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified: 25-JUL-1990    ArticleIdent: Q62668

 If you are viewing your makefile in a window in PWB 1.00, then delete
 the makefile from a shell; attempting to make the window containing
 the makefile active will cause a run-time error R6000, stack overflow.

 To duplicate this problem, bring up a sample program and set the
 program list to that file's makefile. Next, open up another window
 and open the makefile in that window. Now, either from the Run.Run
 <DOS-OS/2> Command menu or the File.<DOS-OS/2> Shell, delete that
 makefile.

 After returning back to the PWB, make the window containing the
 makefile the active program list either by pressing the F6 key to
 toggle windows or by clicking the left mouse button in that window.

 You will be faced with a popup message saying "File has been deleted
 from disk. Delete from memory?" Answering "yes" brings up the popup
 six to eight more times. Then, PWB will abort to the system prompt
 with an R6000 (stack overflow) error message and another message, "File
 has been deleted from disk."

 Microsoft has confirmed this to be a problem in PWB version 1.00. We
 are researching this problem and will post new information here as it
 becomes available.


 23. PWB 1.00 Extensions Only Return True Under DOS

 Product Version(s): 1.00
 Operating System:   MS-DOS
 Flags: ENDUSER | buglist1.00
 Last Modified: 15-AUG-1990    ArticleIdent: Q63052

 Extensions written for use by the Programmer's WorkBench (PWB) version
 1.00 under the DOS operating system are recognized as returning true
 regardless of their actual return values.

 The use of return values as a way of providing conditional jumps
 inside PWB macros is a common practice that is affected by the above
 limitation for PWB extensions. The following sample extension and
 macro demonstrate the above problem. Once installed, both the foo()
 and foo2() functions will be seen as returning true to PWB.

 Sample Code
 -----------

 // foo.c

 #include <string.h>
 #include <stdlib.h>
 #include <ext.h>

 PWBFUNC foo( unsigned argData, ARG far *pArg, flagType fMeta );
 PWBFUNC foo2( unsigned argData, ARG far *pArg, flagType fMeta);

 // Switches.
 struct swiDesc swiTable[] =
 {
    { NULL, NULL, 0 }
 };

 // Commands.
 struct cmdDesc cmdTable[] =
 {
    { "foo", foo, 0, NOARG },
    { "foo2",foo2,0, NOARG },
    { NULL, NULL, 0, 0 }
 };

 void EXTERNAL WhenLoaded()
 {
     SetKey( "foo",         "alt+f" );
     SetKey( "foo2",       "ctrl+f" );
     return;
 }

 PWBFUNC foo( unsigned argData, ARG far *pArg, flagType fMeta )
 {
  return(FALSE);  /* FALSE is defined as 0 in ext.h */
 }

 PWBFUNC foo2( unsigned argData, ARG far *pArg, flagType fMeta)
 {
  return(TRUE);   /* TRUE is defined as 1 in ext.h  */
 }

 // End of foo.c

 ; macros in tools.ini to test foo and foo2

 load foo

 test:=foo ->loc1 arg "true" message => :>loc1 arg "false" message
 test2:=foo2 ->loc2 arg "true" message => :>loc2 arg "false" message

 test:alt+t
 test2:ctrl+2

 Microsoft has confirmed this to be a problem with PWB version 1.00. We
 are researching this problem and will post new information here as it
 becomes available.


 24. PWB Text Highlight with Mouse Acts Strange After Search

 Product Version(s): 1.00   | 1.00
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified: 15-AUG-1990    ArticleIdent: Q63059

 The click-and-drag method of selecting text with the mouse in the
 Programmer's Workbench (PWB) sometimes works incorrectly when used
 after a search function.

 To reproduce this problem, do the following:

 1. Select a word in the text using the mouse (double-click on a single
    word).

 2. Execute the search function (select the Search menu, choose Find,
    then OK).

 3. Now try to highlight the text a few lines below the word you used
    to search on (using the click-and-drag method).

 The text will be highlighted starting at the original word that was
 searched for, rather than at the starting mouse position.

 To work around this problem, click the left button anywhere in the
 text window, then perform the text highlight.

 Microsoft has confirmed this to be a problem with the Programmer's
 Workbench version 1.00. We are researching this problem and will post
 new information here as it becomes available.


 25. PWB Does Not Return from DOS Shell with ";" in TMP

 Product Version(s): 1.00
 Operating System:   MS-DOS
 Flags: ENDUSER |
 Last Modified: 25-JUL-1990    ArticleIdent: Q62702

 If there is a semicolon ";" in your TMP environment variable, you may
 not be able to return to the Programmer's Workbench by typing "exit"
 after selecting "DOS Shell" from the File menu in PWB.

 Since the TMP environment variable is used to specify a single
 directory rather than a path, the semicolon character should not be
 used.

 To re-create this situation, type the following at the command line:

    set TMP=C:\TMP;

 Then select DOS Shell from within PWB. Typing "exit" on the DOS
 command line will not bring you back into PWB.

 To correct the problem, remove the semicolon from the end of the TMP
 environment variable.


 26. PWB BACKUP.BAK Does Not Create Backup of Source File Correctly

 Product Version(s): 1.00   | 1.00
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER| buglist1.00
 Last Modified: 24-JUL-1990    ArticleIdent: Q63234

 Version 1.00 of the Programmer's Workbench does not create a backup of
 your source file correctly if the PROJECT.MAK has the same base name
 as the SOURCE.C file. When you build or rebuild the project, the file
 saved as your backup is a copy of the CURRENT.STS file.

 A workaround to this problem is to name your PROJECT.MAK with a
 different base name than your SOURCE.C file. This will still save a
 copy of your CURRENT.STS file with the base name of the PROJECT.MAK.
 However, it will correctly save a backup of the SOURCE.C as
 SOURCE.BAK.

 Microsoft has confirmed this to be a problem in version 1.00 of the
 Programmer's Workbench and will post new information here as it
 becomes available.



 27. PWB menukey Switch Resets to ALT When Shelling Out to DOS

 Product Version(s): 1.00
 Operating System:   MS-DOS
 Flags: ENDUSER | buglist1.00
 Last Modified: 10-JUL-1990    ArticleIdent: Q63267

 If the "menukey" switch in the DOS version of the Programmer's
 Workbench (PWB) version 1.00 is set to anything other than ALT (which
 is the default), it will be redefined to the ALT key after shelling
 out to DOS. This means the menukey switch will lose its assignment
 anytime you choose Compile, Run Program, Debug Program, or DOS Shell.

 The menukey switch determines which keystroke activates the PWB main
 menu bar. The ALT key is normally used for this, but menukey can be
 redefined to any keystroke. For example, menukey is automatically
 defined to F9 if you select Brief Editor emulation when installing the
 Programmer's WorkBench.

 Whenever you invoke any function (such as Build) that goes out to DOS
 for execution and then returns, the menukey switch is reset to ALT, so
 that both ALT AND the user-defined keystroke invoke the menu.

 To work around this problem, you can use the Restart command to invoke
 a macro that redefines the menukey to the desired value each time you
 return from a DOS SHELL command, which will then keep ALT from
 activating the menu. For example, to make it so that F9 is always
 reset as the only menukey, put the following line in the PWB tagged
 section of the TOOLS.INI file:

    restart:= arg "menukey:F9" assign

 Since the Restart command, if it exists in TOOLS.INI, is invoked
 automatically when returning from a SHELL command, this guarantees
 that the key assignment will always remain consistent.

 Microsoft has confirmed that the automatic reactivation of ALT as the
 menukey is a problem with the Programmer's WorkBench version 1.00. We
 are researching this problem and will post new information here as it
 becomes available.


 28. PWB: Print Does Not Put CR/LF at EOL If Text Selected

 Product Version(s): 1.00   | 1.00
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER | buglist1.00
 Last Modified: 25-JUL-1990    ArticleIdent: Q63318

 Using the Programmer's Workbench version 1.00, when a region of text
 is selected and the Print function is invoked, the resulting output
 contains linefeed characters (0x0A) at the end of each line, rather
 than a carriage return/linefeed (<CR><LF>) combination (0x0D and
 0x0A).

 Some printer drivers do not recognize this as a valid end-of-line
 (EOL) character and do not print correctly.

 To reproduce this problem, open a file that contains the <CR><LF>
 combination at the end of each line. Highlight a region of text in the
 file and from the File menu choose Print. Tab to the second field and
 type in the following:

    copy %s test.txt

 This will copy the region of selected to the file TEST.TXT. Using a
 standard hex file viewer, you can see that the end of a line is
 denoted by a single 0A. If you look at the original file using the hex
 viewer, it will contain 0A 0D at the end of each line.

 The Programmer's Workbench will recognize this type of file (with a
 single 0A at each end of line) and display it correctly if you try to
 open it within the Workbench, but many printer drivers do not
 understand this type of file.
 The workaround for this problem is to write a program that translates
 each 0x0A found in the output file to the bytes 0x0D and 0x0A, or use
 a printer driver that understands this type of file. In fact, most
 printers have an escape sequence or dip switch to make it recognize
 this type of file.

 Microsoft has confirmed this to be a problem with the Programmer's
 Workbench version 1.00. We are researching this problem and will
 post new information here as it becomes available.


 29. Unknown Function psrch with Brief Emulation in PWB

 Product Version(s): 1.00   | 1.00
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified: 25-JUL-1990    ArticleIdent: Q63319

 When using the Brief emulation feature of the Programmer's WorkBench
 version 1.00, reinitialization of the TOOLS.INI file will cause a
 number of unknown functions to appear when you try to use them. In
 short, most of the unknown functions that may be reported are related
 to search features such as the psearch switch. The error message
 associated with this search feature is commonly "Unknown function
 psrch."

 This error occurs only after you use the Initialize function.

 The Initialize function discards current macro definitions and rereads
 the appropriate section of TOOLS.INI. This is not exactly the same as
 restarting PWB; the Autostart macro is not executed after Initialize.
 The BRIEF emulation depends on the Autostart macro to define the
 search functions.

 To recover the definition of the missing macros, execute the toggle_re
 BRIEF emulation macro (CTRL+F6). To avoid having to remember to
 execute this macro, you can add this to the main section of TOOLS.INI:

    reinit:=Initialize Autostart
    reinit:Shift+F8

 Or you can define the macros as follows:

    psrch:=arg arg "String to Search for" prompt ->can
                                            psearch => :>can cancel
    msrch:=arg arg "String to Search for" prompt ->can
                                            msearch => :>can cancel
    qrepl:=arg arg qreplace
    srchname:="REoff"


 30. Problems Viewing README.DOC Inside PWB Online Help and QH

 Product Version(s): 1.00
 Operating System:   MS-DOS
 Flags: ENDUSER  |
 Last Modified: 15-AUG-1990    ArticleIdent: Q63661

 Problems can occur when attempting to access the README.DOC from
 within the DOS versions of Programmer's WorkBench (PWB) or QH via the
 online help.

 When attempting to view the README.DOC file using the online help
 inside the DOS version of PWB, the messages "Error displaying help"
 and then "Cannot process cross reference" may be displayed in
 successive dialog boxes.

 When attempting to view the README.DOC file from within QH, the
 message "The database README.DOC is not open, or the topic is not
 found" may be displayed.

 Again, these problems are found only in the DOS version of PWB and QH.
 Access of the README.DOC in this manner does not produce errors under
 the OS/2 versions of PWB or QH.

 The following are two possible workarounds for the problem in PWB:

 1. The README.DOC can be loaded into the help system by typing the
    following

       arg "$PATH:readme.doc!" arg pwbhelp

    with default keys:

       Alt+A $PATH:readme.doc! F1

    Note that this method may fail if there is another file named
    README.DOC in the path before the C 6.00 README.DOC. If this is the
    case, the other README.DOC will be loaded instead of the C 6.00
    README.DOC. This method can also fail if there is not enough memory
    to load the file into the help system.

 2. If the previous method fails, the C 6.00 README.DOC can be loaded
    into PWB as a normal text file via the File.Open menu option. The
    README.DOC can be found in the C 6.00 bound executable directory
    (for example, C:\C600\BINB).

 The following are three possible workarounds for the problem in QH:

 1. Inside QH, select View.Search, type "$PATH:readme.doc!" and press
    ENTER. Again, this will bring up the first README.DOC on the path.

 2. You can also select File.Open and load the the file by giving the
    full path and filename of the C 6.00 README.DOC. QH allows you to
    open any text file under 64K in size.

 3. To enable direct access of the README.DOC from within QH via the
    README.DOC button, it is necessary to point the QH environment
    variable to the directory where the README.DOC is located. For
    example:

       set qh=c:\c600\binb\readme.doc

    The QH environment variable is not documented in the C 6.00 printed
    or online documentation.

 Microsoft is researching this problem and will post new information
 here as it becomes available.


 31. CTRL+NUM/ May be Read as CTRL+/ in DOS with NUM LOCK On

 Product Version(s): 1.00 1.10 | 1.00 1.10
 Operating System:   MS-DOS    | OS/2
 Flags: ENDUSER | buglist1.10
 Last Modified: 15-NOV-1990    ArticleIdent: Q66740

 In versions 1.00 and 1.10 of Programmer's WorkBench (PWB), the
 CTRL+NUM/ (CTRL+/ on the numeric keypad) and ALT+NUM/ (ALT+/ on the
 numeric keypad) combinations may be interpreted as CTRL+/ and ALT+/
 (on the main keyboard). This problem happens only in DOS or the OS/2
 DOS 3.x box, and only on certain computers. This behavior will cause
 any macro or function assigned to CTRL+NUM/ or ALT+NUM/ to not execute
 when NUM LOCK is on.

 To reproduce this problem, assign a function or macro to CTRL+NUM/.
 Then execute the TELL function (CTRL+T by default) and press CTRL+NUM/.
 The TELL function prompts for a keystroke, then displays the name of
 the keystroke and the function assigned to it. With NUM LOCK on, TELL
 will return the following:

    unassigned:Ctrl+/.

 With NUM LOCK off, TELL will return the following:

    <function name>:Ctrl+num/.

 This behavior is identical for the ALT+NUM/ key name, but works
 properly for all other key names on the numeric keypad.

 If NUM LOCK is off, or if the protected-mode version of PWB is run,
 this behavior does not occur.

 This behavior has been observed on the following machines:

    Northgate 386-33
    PS/2 Model 70
    PS/2 Model 80-311

 Microsoft has confirmed this to be a problem in PWB version 1.00 and
 1.10. We are researching this problem and will post new information
 here as it becomes available.


 32. PWB Command-Line Option /DP Is Documented But Not Implemented

 Product Version(s): 1.00   | 1.00
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER | docerr
 Last Modified: 27-JUL-1990    ArticleIdent: Q63951

 The /DP switch for the Programmer's WorkBench (PWB), documented on
 Page 49 of the version 6.00 "Microsoft C Reference," is not
 implemented in version 1.00 of the PWB. This switch is designed to
 ignore the most recent program list upon starting the PWB.

 The /DP switch is mentioned only in the "Microsoft C Reference" and
 not in the online help.

 Upon invocation, the Programmer's WorkBench version 1.00 does not
 automatically set the program list to the last program list used.
 Therefore, the /DP command-line switch was not implemented because it
 would have no purpose.

 With the PWB version 1.00, there is no way to have the last program
 list set automatically at startup.


 33. With the "deflang" Switch PWB Prompts for Setting Program List

 Product Version(s): 1.00   | 1.00
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER | docerr
 Last Modified:  3-AUG-1990    ArticleIdent: Q64353

 As documented on Page 79 of the "Microsoft C Reference" shipped with C
 version 6.00 and in the online help, the "deflang" switch in the
 Programmer's WorkBench (PWB) sets the default filename extension for
 list boxes in PWB dialog boxes. Another (undocumented) feature of this
 switch is to enable you to be prompted to "Set Program List?" when
 loading a source file with a .MAK file associated with it in the
 current directory.

 By default, "deflang" is not set. You can set the deflang switch in
 the [PWB] tagged section of the TOOLS.INI file, for example:

    deflang:C

 This changes the default filename extension in the PWB's dialog boxes
 (such as Open in the File menu) from "*.*" to "*.c", so that only
 files with the .c extension show up by default. Other languages can be
 specified as well, as shown below:

    Switch Setting     Extension
    --------------     ---------

    no value            .*
    C                   .c
    Asm                 .asm
    BASIC               .bas
    FORTRAN             .for
    Pascal              .pas
    COBOL               .cbl
    LISP                .lsp

 Note that the online documentation specifies "Assembler" as the switch
 to use for .ASM files, but this is incorrect. "Asm" is the correct
 switch to use to make Assembler the default language.

 The deflang switch also enables you to be prompted as to whether or
 not the program list should be set automatically. If you load a file
 that has the extension specified by the "deflang" switch and you also
 have a .MAK file with the same base filename in the same directory,
 the PWB will prompt you about loading the program list.

 For example, assume that deflang is set to C and FOO.MAK and FOO.C are
 in the same directory. If you type PWB FOO.C at the command-prompt,
 the PWB will pause when loading and prompt with "Set Program List?
 FOO.MAK". At this point you can specify <yes> or <no>.

 When already in the PWB, if you select Open from the File menu, and
 select FOO.C as the file to open, the PWB will also prompt you at this
 point regarding whether or not you want FOO.MAK loaded as the program
 list, but only if NO program list is currently set.


 34. Can't Resize a Window with a Macro in PWB

 Product Version(s): 1.00   | 1.00
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified: 30-AUG-1990    ArticleIdent: Q64433

 A window cannot be resized using the "resize" function in a macro.
 After Programmer's WorkBench (PWB) performs the resize function, it
 waits for the you to respond with the UP ARROW or DOWN ARROW key.
 Functions that are placed in the macro after the resize function are
 ignored. If "record on" is selected and you try to record the resizing
 of a window, the macro will stop recording until the ENTER key on the
 numeric keypad is pressed.

 The following is an example:

    resizeit:= cancel arg arg nextmsg window resize up up up NumEnter

 The above example stops at the resize function and waits for you to
 resize the window. The remaining functions are ignored.

 To make a window a specified size, move the cursor to a location on
 the screen and then open the window with the "window" function.

 The following is an example of a macro that opens the "<compile>"
 window with a specified size:

 compile_size:= up up up up up up up up up up
 resize_it:=cancel meta down compile_size arg window window arg \
            "<compile>" setfile window
 resize_it:ALT+U

 Note: The size of the compile window can be adjusted by changing the
 number of ups on the compile_size line.


 35. PWB Hangs When Run with Some Communication Programs Under OS/2

 Product Version(s): 1.00
 Operating System:   OS/2
 Flags: ENDUSER |
 Last Modified: 30-AUG-1990    ArticleIdent: Q64435

 When running Programmer's WorkBench (PWB) under OS/2 while
 simultaneously running communication programs, PWB will appear to
 hang. To correct the problem, terminate any communication programs and
 PWB will resume as normal.


 36. "Cannot Open File current.$" May Mean Incorrect INIT Variable

 Product Version(s): 1.00   | 1.00
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified: 17-DEC-1990    ArticleIdent: Q64566

 When using the Programmer's Workbench (PWB), the following message may
 appear as a pop-up dialog box when selecting Compile or DOS Shell (or
 OS/2 Shell for OS/2):

    +----- Cannot open file! -----+
    |   D:\TEST\SRC\X\current.$   |
    |  No such file or directory  |
    |-----------------------------|
    |      < OK >   < Help >      |
    +-----------------------------+

 One cause for this error is an incorrect setting of the INIT
 environment variable. To remedy the situation, exit PWB and make sure
 that the INIT environment variable is set to a valid directory name
 (for example, a directory that exists).

 To reproduce this message, set your INIT environment variable to an
 invalid directory, for instance (if a directory named X does not exist
 on your drive):

    SET INIT=X

 Then start PWB and try to compile a program. The message will appear
 in the middle of the screen.

 One possible reason why your INIT environment variable may be set
 incorrectly, even if your AUTOEXEC.BAT sets it correctly, is that you
 might have run out of environment space in the setting of the
 variable. You can refer to the "MS-DOS Encyclopedia," Article 2, for
 more information about increasing your environment space.


 37. How to Use the PWB with the Windows 3.00 SDK

 Product Version(s): 1.00   | 1.00
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified: 15-AUG-1990    ArticleIdent: Q64788

 Detailed step-by-step instructions on how to set up the Programmer's
 WorkBench (PWB) for use with the Windows version 3.00 Software
 Development Kit (SDK) can be found in a file provided with the SDK
 called PWBINFO.WRI.

 The file explains how to set PWB switches so that Windows applications
 can be built from within PWB. The file also explains how to access the
 SDK's online help.

 This file can be viewed and printed with the WRITE program, which is
 packaged with the Windows 3.00 package.


 38. Tips for Using the Microsoft Advisor Online Help

 Product Version(s): 1.00 1.10 | 1.00 1.10
 Operating System:   MS-DOS    | OS/2
 Flags: ENDUSER | s_quickc s_c s_qh
 Last Modified: 23-JAN-1991    ArticleIdent: Q64829

 The following are some tips for more effectively using the online
 documentation included with the Microsoft C Compiler version 6.00
 Programmer's Workbench (PWB) as well as the Microsoft Advisor
 command-line help system:

 1. Finding help on a topic for which the exact name is not known.

    If the exact spelling of a topic is not known, the help for that
    topic can't be accessed directly (for instance, by using the F1 key
    in PWB), but it can usually be found indirectly.

    By using the table of contents and selecting links that pertain to
    the subject in question, the topic can usually be found. To get to
    the table of contents from within QuickHelp, select the Categories
    menu, then "C 6.00".  From within PWB, choose the Help menu, then
    select Contents.

    If you know the general spelling of the topic, an alphabetical
    index is available by choosing Index from the main contents screen.

 2. "Paging" through the online documentation.

    The online documentation can be "paged through" like you would page
    through a manual.

    In PWB, CTRL+F1 takes you from one topic to the next sequential
    topic in the help file. In QuickHelp, Choose Next or Back from the
    View menu to move in either direction.

 3. Scanning a list of available topics (as in a printed index).

    There are alphabetical indices for every major component of the
    product. Just choose Index from the main contents screen and select
    the appropriate topic.

 4. Techniques for using the online help.

    For more information on how to use the help system, as well as on
    the general organization and structure of the help system, choose
    Using Help from the main contents screen.

    For additional help, see Chapter 4, "Using the On-Line Reference,"
    of the "Microsoft C Installing and Using the Professional
    Development System" manual that comes with C version 6.00.

 5. Printing out the online help files.

    By using the HELPMAKE utility, the help files can be decoded to
    readable text files, which can then be printed. For more
    information about the HELPMAKE utility, see Chapter 7 of the
    "Microsoft C Advanced Programming Techniques" manual that comes
    with C version 6.00.


 39. Predefined Identifiers in Microsoft C 6.00

 Product Version(s): 6.00   | 6.00
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER | s_quickhelp s_c s_utils
 Last Modified: 24-OCT-1990    ArticleIdent: Q65472

 The following information is contained in the online help for the
 Microsoft C Compiler version 6.00.

 This information below can be accessed by using the following steps:

 1. Obtain help on the text "cl" using either the F1 key from the
    Programmer's WorkBench, or by using "qh cl" from the DOS or OS/2
    command lines.

 2. Select Preprocessor Options, then Predefined Identifiers.
 The compiler automatically defines identifiers useful in writing
 portable programs. You can use these identifiers to compile code
 sections conditionally. These identifiers are always defined unless
 otherwise stated.

    Identifier       Target Identified
    ----------       -----------------

    MSDOS            MS-DOS operating system
    M_I86            Member of the I86 processor family
    M_I86mM          Memory model type
                     <m> = T    Tiny
                           S    Small (default)
                           C    Compact model
                           M    Medium model
                           L    Large model
                           H    Huge model
    M_I8086          8088 or 8086 processor; default or with /G0
                        option
    M_I286           80286 processor; defined with /G1 or /G2 option
    _MSC_VER         Identifies the version of Microsoft C
    NO_EXT_KEYS      Disables Microsoft-specific language extensions
                        and extended keywords; defined only with /Za
                        option
    _CHAR_UNSIGNED   Changes default char type to unsigned; defined
                        only with /J option

 The _MSC_VER identifier has a value of 600 for the Microsoft C Compiler
 version 6.00. This identifier is not defined in Microsoft C versions
 5.10 and earlier.


 40. How to Add Other Language Compilers to PWB's Build Options

 Product Version(s): 1.00 1.10 | 1.00 1.10
 Operating System:   MS-DOS    | OS/2
 Flags: ENDUSER | s_pascal b_basiccom s_c h_masm h_fortran b_cobol
 Last Modified: 24-OCT-1990    ArticleIdent: Q65568

 The Programmer's WorkBench (PWB) is an environment capable of
 utilizing different compilers for mixed-language programming. When
 installed during BASIC version 7.10 setup, PWB version 1.10 shows
 build options for the BASIC language only. However, it is possible to
 include other language compilers to utilize the full features of the
 PWB utility.

 The following information applies to the Programmer's WorkBench
 version 1.10 utility supplied with Microsoft BASIC Professional
 Development System (PDS) version 7.10 for MS-DOS and MS OS/2.

 Note that the 1.00 version of PWB is shipped with Microsoft C
 Professional Development System (PDS) version 6.00. The steps below
 should also apply to PWB version 1.00.

 The Programmer's WorkBench (PWB.EXE) is an advanced development
 environment capable of integrating several language compilers,
 NMAKE.EXE, LINK.EXE, and the CodeView debugger. It offers the ability
 to accomplish tasks, such as program development under protected mode
 and mixed-language programming. This ability is not available in the
 QuickBASIC extended development environment (QBX.EXE).

 Two special files, PWBC.PX$ (for protected mode OS/2) and PWBC.MX$
 (for DOS mode), reside on the BASIC PDS 7.10 disks and support the
 option of using the C compiler in PWB. Since SETUP.EXE (in BASIC PDS
 7.10) does not copy PWBC.PX$ and PWBC.MX$ during installation, these
 files must be unpacked and transferred to your machine, for example to
 the \BINP subdirectory located in the \BC7 directory. (Note: The
 UNPACK.EXE utility is found on disk 1 of the BASIC PDS package.) After
 unpacking, the files will have the names PWBC.PXT and PWBC.MXT.

 Next, the following command lines must be added to the TOOLS.INI file
 to make the C compiler available to PWB:

    [pwb - .BAS .BI]
       LOAD: LogicalDrive:\[Path]\PWBC.PXT

 For further information about installing PWBC.PXT and PWBC.MXT, see
 Page 54 of the "Microsoft BASIC 7.1: Getting Started" manual.

 If you want to program in languages other than BASIC or C [such as
 Microsoft Macro Assembler (MASM), Microsoft Pascal, Microsoft FORTRAN,
 or Microsoft COBOL 3.00/3.00a], the following steps will insert the
 initial build options to include other languages to PWB's build
 options menu. In the example below, options to include the MASM.EXE
 assembler are specified. If some other language's compiler is desired,
 substitute appropriate changes for that compiler, where noted in the
 specified areas:

  1. In PWB, go to the Options menu and select Build Options.

  2. Choose Save Current Build Options.

  3. Enter a meaningful message, such as "Options to Include MASM" in
     the window's edit field (if some other language is desired, change
     MASM to the appropriate name). Select the OK button from the "Save
     Current Build Options" and "Build Options" windows.

  4. Open the "TOOLS.INI" file in the PWB utility and go down to the
     bottom of the file. Somewhere near the bottom should be the tag
     "[PWB-Build Options: Options to Include MASM]" (or the language
     that was specified).

  5. In this section, add the following NMAKE instructions:

        build: inference .asm.obj masm_asm_obj
        build: command masm_asm_obj "masm $<;"

     Note: For languages other than MASM, distinguish a variable name
     in the inference rule to be used in the commands line (such as
     masm_asm_obj has been used above) and then specify the appropriate
     compiler in the commands line within the quotation marks. The
     special filename macro specified in the quotation marks, "$<",
     applies the command to any object that has an out-of-date
     executable file.

  6. Press SHIFT+F8 to reinitialize the file and then close it.

  7. Go to the File menu and select New (it is a good idea to close any
     files that are currently open before this step).

  8. Go to the Options menu and select Build Options.

  9. Choose Initial Build Options.

 10. Select the "Options to Include MASM" option (it should be near the
     bottom of the list).

 After completing these instructions, the PWB utility will now be ready
 to compile assembler along with BASIC source code, provided that paths
 to the necessary compilers are furnished.


 41. PWB Err Msg: Out of Local Memory. Unable to Recover.

 Product Version(s): 1.00
 Operating System:   MS-DOS
 Flags: ENDUSER |
 Last Modified: 17-OCT-1990    ArticleIdent: Q65913

 When setting a program list inside of the Programmer's WorkBench
 (PWB), the following message may occur:

    Out of Local Memory.  Unable to Recover.

 The error is printed on the screen and the PWB exits to DOS. This
 error may occur when the program list contains too many names. To
 resolve the problem, combine object modules into libraries whenever
 possible. Remove the .OBJ files from the program list and replace them
 with the new libraries. This will reduce the number of object modules
 that need to be defined in the program list.

 Another method that sometimes helps to alleviate the error is to open
 the File menu and close as many unneeded files as possible. This
 should be done before setting the program list.


 42. Situation Where PWB Online Help Text Disappears

 Product Version(s): 1.00 1.10 | 1.00 1.10
 Operating System:   MS-DOS    | OS/2
 Flags: ENDUSER | SR# S901010-118 B_BasicCom S_C B_cobol
 Last Modified: 24-OCT-1990    ArticleIdent: Q66229

 When requesting help in Microsoft Programmer's WorkBench (PWB)
 versions 1.00 and 1.10, the following sequence of events will cause
 the Help screen text to disappear, leaving only the hyperlinks.

 This information applies to Programmer's WorkBench version 1.00 (which
 comes with Microsoft C Professional Development System version 6.00
 for MS-DOS and MS OS/2), and to Programmer's WorkBench version 1.10
 (which comes with Microsoft COBOL Professional Development System
 version 4.00 and with Microsoft BASIC Professional Development System
 (PDS) version 7.10 for MS-DOS and MS OS/2).

 Microsoft has confirmed this to be a problem in PWB. We are
 researching this problem and will post new information here as it
 becomes available.
 Follow these steps to reproduce the problem:

 1. From the DOS or OS/2 prompt, enter PWB. From the File menu, select
    New. Type PLINES and request help by pressing F1 or single-clicking
    the right mouse button.

 2. In the Help dialog, double-click the left mouse button with the
    cursor on the hyperlink "Using PWB Functions."

 3. Double-click the left mouse button with the cursor on the hyperlink
    "PWB Functions by Category."

 4. Double-click the left mouse button with the cursor on the hyperlink
    "Moving Through Files."

 5. The vertical scroll bar will show that you are at the bottom of the
    dialog. Press PGUP and you will notice that the hyperlinks to Up,
    Index, Contents, and Back have disappeared. Double-click the left
    mouse button with the cursor on any of these empty hyperlinks; the
    text on the screen will disappear, with empty hyperlinks appearing
    on the screen.


 43. How to Insert Spaces Before a Block of Text in PWB

 Product Version(s): 1.00   | 1.00
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER | S_EDITOR
 Last Modified: 24-OCT-1990    ArticleIdent: Q66231

 It is sometimes desirable to indent or move over a block of text in
 the Programmer's WorkBench (PWB) or the M Editor. The following steps
 can be used to insert spaces before a block of text to indent it:

 1. Get into boxarg mode. You can select this mode from the Edit menu
    under the Programmer's Workbench, or select the boxstream function
    under the Microsoft Editor.

 2. Highlight the area you want to contain the spaces. This may be
    anywhere in the file.

 3. Select the linsert function. By default, this is CTRL+N.

 The highlighted area should now be moved over and replaced by spaces.

 You don't have to be in boxarg mode for this to work; linsert always
 treats its argument as a boxarg regardless of the current mode.
 However, the highlight on the screen won't match the area that is
 going to be inserted unless you use boxarg mode.

 Also, ldelete can be used to unindent a block of text. However, you
 must be in boxarg or streamarg mode for it to work correctly. In
 linearg mode, it will delete entire lines.


 44. PWB's Use of Expanded Memory

 Product Version(s): 1.00 1.10
 Operating System:   MS-DOS
 Flags: ENDUSER |
 Last Modified: 23-OCT-1990    ArticleIdent: Q66308

 The DOS version of the Programmer's WorkBench (PWB) will utilize
 expanded memory to swap its own segment overlays if it detects that
 expanded memory is available in the system. When PWB needs a new
 overlay, the existing overlay in memory is first copied into expanded
 memory. If there is not enough room in expanded memory to copy the
 overlay, the least recently used overlay is discarded to make room for
 it. This scheme allows most overlays to be read from expanded memory
 instead of from disk.

 Note that this is the only method by which PWB will take advantage of
 available expanded memory, and that PWB versions 1.00 and 1.10 have no
 internal provisions to make use of extended memory in any way.


 45. PWB May Exit to DOS If TMP Not Set Correctly

 Product Version(s): 1.00 1.10
 Operating System:   MS-DOS
 Flags: ENDUSER | buglist1.00 buglist1.10
 Last Modified: 24-OCT-1990    ArticleIdent: Q66309

 If the tmp environment variable is set only to a drive (with no path
 specified), the PWB may "crash" out to DOS when a compile is
 attempted. The screen will still show the PWB, but there will be a
 prompt displayed.

 This problem may be reproduced using the following procedure:

 1. Set up the environment to run the PWB.

 2. Set the tmp environment variable to the current drive, without
    specifying a path. For example:

       SET TMP=C:

 3. Execute the PWB and create or load a simple source file.

 4. Attempt to compile the source file. (Note: If the COMPILE option is
    not available on the make menu, make sure the file has a name with a
    .c extension.)

 Microsoft has confirmed this to be a problem with the Programmer's
 WorkBench versions 1.00 and 1.10. We are researching this problem and
 will post new information here as it becomes available.


 46. MASM Build Switches for PWB 1.10

 Product Version(s): 1.10    | 1.10
 Operating System:   MS-DOS  | OS/2
 Flags: ENDUSER |
 Last Modified:  5-DEC-1990    ArticleIdent: Q66339

 When setting a program list containing .ASM files in Programmer's
 WorkBench (PWB) version 1.10, the following error message occurs:

    Program List: file 'filename' will be ignored
    File type unused by current build options

 The .ASM files are not recognized because PWB 1.10 does not contain
 build switches specific to any language. Build switches are now loaded
 from language extension files (.MXT for DOS and .PXT for OS/2). If you
 have an assembly language extension file, you will not see this error
 message. Language extensions are not necessary and are only a
 convenience for controlling the build process; only the build switches
 are really needed.

 The following build switches can be added to a tagged section in your
 TOOLS.INI file. To use these build options, first choose your language
 options from the Options Build Options menu, then initialize this
 section by typing {arg} tag_name {reinitialize} (type the following to
 invoke the sample build switch below:

    ALT+A asm_rules SHIFT+F8

 These switches can also be added to a custom set of build options
 saved by Save Current Build Options. They may then be initialized by
 choosing Build Options from the Options menu, and then selecting Set
 Initial Build Options to choose the new custom language options.

 Sample Build Switches
 ---------------------

 [pwb-asm_rules]
 ;
 ;   MASM build rules
 ;
 build:macro ASM "MASM"
 build:macro AFLAGS_G "/Mx /T"
 build:macro AFLAGS_D "/Zi"
 build:macro AFLAGS_R ""
 build:inference .asm.obj as_asm_obj
 build:release command as_asm_obj  \
             "$(ASM) $(AFLAGS_G) $(AFLAGS_R) $<, $@;"
 build:debug command as_asm_obj  \
             "$(ASM) $(AFLAGS_G) $(AFLAGS_D) $<, $@;"
 build:include .asm "^[ \t]*include[ \t]+\\([^ \t]+\\)"
 build:include .inc "^[ \t]*include[ \t]+\\([^ \t]+\\)"

 These assembly flags can then be modified from PWB by using the
 following macros. The macros must be assigned to keystrokes to be
 activated. This can be done using the <ASSIGN> pseudo file. They can
 then be used to redefine the flags to pass to MASM.

 ;
 ;   MASM option-setting macros
 ;
 setAFG:= arg "Global MASM Options?"  prompt -> cancel lasttext home \
         "build:macro AFLAGS_G \"" endline "\"" assign

 setAFD:= arg "Debug MASM Options?"   prompt -> cancel lasttext home \
         "build:macro AFLAGS_D \"" endline "\"" assign

 setAFR:= arg "Release MASM Options?" prompt -> cancel lasttext home \
         "build:macro AFLAGS_R \"" endline "\"" assign


 47. Unexpected Behavior with the /Gt Switch and the PWB

 Product Version(s): 1.00   | 1.00
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER | S_C
 Last Modified: 15-JAN-1991    ArticleIdent: Q66828

 Adding the /Gt compiler switch with an argument to the Additional
 Options section of the C Compiler Options on the Programmer's
 WorkBench (PWB) Options menu can cause the value of the argument to be
 changed or dropped.

 Microsoft has confirmed this to be a problem in the Programmer's
 WorkBench version 1.00. We are researching this problem and will post
 new information here as it becomes available.

 When you add the /Gt switch with an argument (for example, /Gt30) and
 click OK, then immediately go back into the Compiler Options dialog
 box; you will see that the /Gt30 switch you just set is now /Gt3.

 If you set a /Gt switch and specify a value, it will compile with that
 correct value because it was written to the file on disk that is used
 to build the program.

 If you go back in and look at the compiler options and see that the
 value is incorrect and Cancel the options dialog, you will still
 compile with your initial correct /Gt value.

 You will compile with the incorrect /Gt value only if you make another
 change in that dialog and select OK. This is because you changed the
 options, so PWB rewrites the options to the file on disk. In the case
 of /Gt, that option is written incorrectly and from that point on, you
 will compile with the incorrect /Gt value.

 Not all values of /Gt are incorrect. The most common incorrect values
 end in zero. The following are examples where the problem occurs:

    /Gt40 will turn into /Gt4
    /Gt0  will turn into /Gt
    /Gt20 will turn into /Gt

 Some other values that get changed are the following:

    /Gt113 will turn into /Gt3
    /Gt305 will turn into /Gt35
    /Gt14  will turn into /Gt4
    /Gt22  will turn into /Gt

 As a possible work around, do not set /Gt in the PWB, and set the
 environment variable CL to the desired threshold, as in the following
 example:

    set cl=/Gt40

 This value will be read by the compiler when it is called from the
 PWB.

 Also, you can set the /Gt switch on the Additional Options line in
 either Set Debug Options or Set Release Options, rather than the
 global Additional Options.


 48. REsearch() Function Prototype Not Found in EXT.H Header File

 Product Version(s): 1.00 1.10 | 1.00 1.10
 Operating System:   MS-DOS    | OS/2
 Flags: ENDUSER | buglist1.00 buglist1.10
 Last Modified:  4-DEC-1990    ArticleIdent: Q67274

 The Programmer's WorkBench (PWB) function REsearch(), although
 included in EXTSUP.LIB, is not prototyped in the EXT.H header file. To
 call REsearch(), use the following prototype:

 int REsearch( PFILE pFile, flagType fForward, flagType fAll,
               flagType fCase, flagType fWrap, char _far *pattern,
               fl *pflStart );

 For more information, see online help.

 Microsoft has confirmed this to be a problem in PWB versions 1.00 and
 1.10. We are researching this problem and will post new information
 here as it becomes available.


 49. PWB Help Crashes When Using "Moving Through a File"

 Product Version(s): 1.10   | 1.10
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER | buglist1.10
 Last Modified: 14-DEC-1990    ArticleIdent: Q67361

 When using the online help through the Programmer's WorkBench (PWB),
 the help system will crash if you do the following:

 1. After entering help, choose Contents.

 2. Select the Microsoft Advisor from the list of contents.

 3. Select the Programmer's WorkBench button followed by the "Moving
    Through a File" selection.

 At this point a header will appear on the screen and the elevator for
 the window will appear as though it is at the bottom of a page.

 The page can be scrolled up and the contents viewed, especially if
 highlighted, but the menu items at the top will be blacked out
 (although they are present). From this point, no further help can be
 accessed.

 If you exit help and then reenter, nothing will come up.
 Re-initializing does not reinstate the help system. Only shelling out,
 exiting, and reentering will allow you to access the help system.

 Microsoft has confirmed this to be a problem in the Programmer's
 WorkBench version 1.10. We are researching this problem and will post
 new information here as it becomes available.


 50. PWB Hangs with Novell NetWare

 Product Version(s): 1.00 1.11
 Operating System:   MS-DOS
 Flags: ENDUSER | s_quickc s_codeview s_c
 Last Modified: 14-DEC-1990    ArticleIdent: Q67483

 On certain installations of a Novell network, the network will cause
 the Programmer's WorkBench (PWB) to hang. This problem may also occur
 in CodeView or QuickC. The hang usually occurs when an attempt is made
 to use the mouse.

 If you have a peripheral (such as a mouse) that uses Interrupt Request
 Level (IRQ) 3, and your system is part of a network using Novell
 NetWare version 2.15 or earlier, your system may hang when you load
 QuickC, PWB, or CodeView. As a temporary solution, set your peripheral
 to use another interrupt. For more information, contact your Novell
 NetWare dealer.

 If taking these steps does not solve the problem, please contact
 Microsoft Product Support Services.


 51. PWB Menu Hyperlink in PWB.HLP is Inconsistent in Version 1.10

 Product Version(s): 1.10   | 1.10
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified: 23-JAN-1991    ArticleIdent: Q67614

 When selecting help on the Programmer's WorkBench (PWB) version 1.10
 from the Categories menu in QuickHelp version 1.70, the help screen
 for Microsoft Advisor Help System is presented instead. This behavior
 may be duplicated by following the procedure outlined below:

 1. Start QuickHelp without an argument to get help on any topic. This
    will bring up the main help screen.

 2. Select the Programmer's WorkBench choice under the Categories menu.

 Instead of bringing up the help screen for Programmer's WorkBench, you
 will see the screen for the Microsoft Advisor Help System.

 If the PWB.HLP help file is decoded using helpmake as follows

    helpmake /D /T /Opwb.doc pwb.hlp

 we can see that the reason for this is that the .context directive for
 Programmer's WorkBench appears in the wrong section in the decoded
 help file. The following line

    .context Programmer's Workbench

 appears above the section for "Microsoft Advisor Contents." To correct
 the problem, move the .context directive for Programmer's WorkBench to
 the proper section, which is the "Programmer's WorkBench Contents."

 The helpfile must then be recompressed, as follows:

    helpmake /E7 /T /Opwb.hlp pwb.doc

 The choice of /E7 is shown here for demonstration purposes only, and
 is strictly arbitrary in this case. If maximum compression is desired,
 the numerical argument to the /E switch may be left off, or /E15 may
 be specified. Maximum compression will restore the database as close
 to its original size and state as possible.


 52. "missing ':' in ->" Caused by Control Character

 Product Version(s): 1.00 1.10 | 1.00 1.10
 Operating System:   MS-DOS    | OS/2
 Flags: ENDUSER |
 Last Modified: 14-DEC-1990    ArticleIdent: Q67736

 When invoking the Programmer's WorkBench (PWB), if there is a control
 character at the end of the TOOLS.INI file, [usually a CTRL+Z (ASCII
 26) end-of-file marker] and you only have a [pwb] tagged section, an
 error message will appear stating "missing ':' in ->". Note that the
 "->" is the graphic right-arrow symbol.

 This is not a problem in the PWB. A control character is a legal macro
 name. The message indicates that a macro definition or key assignment
 is expected after the character. To keep this message from appearing,
 place the tag

    [end]

 before the control character at the end of your TOOLS.INI file. With
 this tag at the end of the file, you always suppress the message, even
 if you edit TOOLS.INI with an editor that inserts CTRL+Z's at the end
 of the file. This is because the -> symbol must be within the [pwb]
 tagged section for this error message to be displayed, and the [end]
 tag forces the -> into its own tagged section.

 Simply deleting the control character will work until you edit the
 file with an editor that replaces the CTRL+Z, then this message
 reappears. This may also when using the COPY command to concatenate
 files.


 53. Inconsistent Error Attempting to Load Nonexistent Extension

 Product Version(s): 1.00 1.10
 Operating System:   OS/2
 Flags: ENDUSER |
 Last Modified: 28-DEC-1990    ArticleIdent: Q67777

 When attempting to load a Programmer's WorkBench extension through a
 macro definition in the TOOLS.INI file, if the extension file does not
 exist, or is not in the current path, the following error message is
 displayed in a dialog box:

    pwbhelp:  SYS0123:  A file name or volume label contains an
                        incorrect character

 This error message should indicate that the extension file could not
 be found; however, the message is generated by the OS/2 operating
 system's DLL loading code, and therefore, cannot be changed by PWB.

 The following error message is generated in the DOS version of PWB,
 which displays this message in a dialog box:

    No such file or directory

 To correct the problem, make sure that the directory in which the
 extension resides is in the current path.


 54. PWB May Record Incorrect Paths for Dependencies in Makefile

 Product Version(s): 1.00 1.10  | 1.00 1.10
 Operating System:   MS-DOS     | OS/2
 Flags: ENDUSER | buglist1.00 buglist1.10
 Last Modified:  6-FEB-1991    ArticleIdent: Q67780

 Creating a program list with dependencies in directories other than
 the project (makefile) directory may result in the Programmer's
 WorkBench (PWB) recording the wrong paths to these dependencies.

 The following steps illustrate the problem:

 1. Create subdirectories named TEST and TESTA under the same
    directory, with sample files FOO.C in TEST and GOO.C in TESTA.

 2. Invoke PWB from the TESTA directory.

 3. Create a program list.

 4. Add FOO.C and GOO.C with full path.

 5. Save the list.

 The resulting makefile will contain the line:

    OBJS = goo.c foo.c

 The correct line should read:

    OBJS = goo.c ..\TEST\foo.c

 Changing the location of the project makefile or changing the names of
 the subdirectories will generate the correct paths for dependencies in
 the makefile.

 Microsoft has confirmed this to be a problem in the Programmer's
 WorkBench versions 1.00 and 1.10. We are researching this problem and
 will post new information here as it becomes available.


 55. PWB Extensions in DOS Cannot Shell to DOS

 Product Version(s): 1.00 1.10
 Operating System:   MS-DOS
 Flags: ENDUSER |
 Last Modified:  6-FEB-1991    ArticleIdent: Q67792

 Extensions written for the Programmer's WorkBench (PWB) that require a
 call to the operating system do not work correctly under DOS. One
 example of this is the FILTER.C sample extension packaged with
 Microsoft C 6.00.

 When PWB.COM is executed under DOS, it spawns the main editor
 (PWBED.EXE). PWBED.EXE is cleared from memory when a DOS shell is
 executed from within the editor. Once the shell has completed,
 PWBED.EXE is reloaded from disk and initialized. The initialization is
 what causes the problem because it also initializes any extensions to
 the editor at the same time. This means that any information that the
 extension was keeping track of is lost.


 56. Not Enough Core Message Caused by Lack of Memory

 Product Version(s): 1.00 1.10
 Operating System:   MS-DOS
 Flags: ENDUSER |
 Last Modified:  6-FEB-1991    ArticleIdent: Q68070

 When loading the Programmer's WorkBench (PWB), a message box may
 appear on the screen containing the message "Cannot Autoload
 Extension, not enough core." The extension file that could not be
 loaded will be indicated. You need to free more memory so that the
 extensions can be loaded.


 57. Windows DLL Build Options Ignore .RC Files in PWB 1.10

 Product Version(s): 1.10   | 1.10
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER | buglist1.10 S_C P_WINSDK
 Last Modified: 11-JAN-1991    ArticleIdent: Q68155

 In the Programmer's WorkBench version 1.10, the default build options
 for creating a Windows DLL will ignore any .RC files included in the
 Program List, and therefore, will not build them into the project.

 Use the following steps to correct this problem:

  1. If there is a Program List currently set, clear it.

  2. Set the Main Language to C.

  3. Set the Initial Build Options to Windows DLL.

  4. Create a new Program List containing all the files you want in your
     project.

  5. Save the Program List. At this point, PWB will tell you that your
     .RC file will be ignored. Choose OK when that dialog box appears.

  6. Choose Editor Settings from the Options menu.

  7. Find the line that starts:

        build: target $(PROJ).dll

  8. Change the word "res_dll" on that line to "rc_dll".

  9. Move the cursor off that line to highlight the change. Press SHIFT+F2
     to save the new settings.

 10. Press F2 to exit the ASSIGN pseudofile.

 11. Choose Edit Program List from the Make menu.

 12. Choose Save List. The .RC file will now be saved in the Program
     List and used as expected.

 After these steps are taken, the settings will be saved in the .STS
 file for that project, and will remain correct as long as Set Initial
 Build Options is never selected when this Program List is set. In
 order to keep from repeating these steps for future projects, the
 build options should be saved under a descriptive name, such as
 "Corrected Windows DLL Settings." They can then be chosen for any
 future Windows DLLs.

 Microsoft has confirmed this to be a problem in the Programmer's
 WorkBench version 1.10. We are researching this problem and will post
 new information here as it becomes available.


 58. PWB Build Switch Reference Available as an Application Note

 Product Version(s): 1.00 1.10 | 1.00 1.10
 Operating System:   MS-DOS    | OS/2
 Flags: ENDUSER | appnote softlib SW0330
 Last Modified: 29-JAN-1991    ArticleIdent: Q68367

 The "PWB Build Switch Reference" contains detailed descriptions and
 examples for customizing PWB build switches.

 The Programmer's WorkBench (PWB) can build various types of projects
 based on the information contained in "build switches." These build
 switches are interpreted by PWB in order to create a makefile for a
 project. The switches are normally set for you by PWB for common types
 of projects, but you may define your own build switches to handle an
 advanced project where you require more control over the build
 process. For example, customized build switches will allow you to
 utilize different languages, to incorporate other tools into a
 project, or to build new kinds of targets.

 Although build switch customization is documented in the PWB online
 help, the information is somewhat limited. Therefore, an application
 note was created to cover the customization process in detail. The
 title of this application note is "PWB Build Switch Reference" and it
 can be obtained by calling Microsoft Product Support Services at (206)
 637-7096.

 The "PWB Build Switch Reference" can also be found in the Software/
 Data Library (as file SW0330.ARC) by searching on the keyword SW0330,
 the Q number of this article, or S12875. SW0330 was archived using the
 PKware file-compression utility.

 Note that the application note found in the Software/Data Library is
 an ordinary text file, which lacks the typefaces and formatting of the
 printed version that is available by calling Microsoft Product Support
 Services. Because the printed application note is clearer and easier
 to follow, it is highly recommended that you call for the printed
 version, and that you use the downloaded version only as an interim
 copy.

 Also note that you normally DO NOT need to modify build switches just
 to customize the compile and link operations -- this can generally be
 done by selecting commands from the Options menu. By selecting options
 from the Compile or LINK Options dialog boxes, the correct build
 switches are automatically modified to contain the desired
 information.


 59. Brown Screen Color Changes to Yellow After Running PWB

 Product Version(s): 1.00 1.10
 Operating System:   MS-DOS
 Flags: ENDUSER | s_c buglist1.00 buglist1.10 remapping
 Last Modified:  6-FEB-1991    ArticleIdent: Q69064

 After running PWB, the brown screen color changes to yellow until the
 system is rebooted or the video mode is reset.

 For example, if you run PWB and then run the Microsoft editor, the
 brown characters will appear yellow.

 To work around this problem, you can create a batch file called
 PWB.BAT. In this file, you can start PWB and then reset the video
 mode. For example:

     pwb.bat
             pwb %1 %2 %3 %4
             mode co80,25

 Microsoft has confirmed this to be a problem in PWB versions 1.00 and
 1.10. We are researching this problem and will post new information
 here as it becomes available.


 60. Reinitializing After Changing Editor Settings Is Very Slow

 Product Version(s): 1.10   | 1.10
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified: 11-FEB-1991    ArticleIdent: Q69142

 The current editor settings in the Programmer's WorkBench (PWB) may be
 changed by choosing Editor Settings from the Options menu, making a
 change to the <assign> pseudofile, and then saving that file. If
 SHIFT+F8 (initialize) is pressed while the <assign> pseudofile is
 still displayed, PWB may appear as though it is hung; it is actually
 reinitializing each statement of the editor settings (<assign>)
 pseudofile.

 The following steps will reproduce this behavior:

 1. Enter PWB and select the Options menu.

 2. Choose the Editor Settings menu.

 3. Make a change in the <assign> pseudofile and then save it.

 4. Press the "initialize" keystroke combination (SHIFT+F8) and a popup
    box will appear stating "reinitializing...". The reinitialization
    is actually taking place but it is very slow because PWB is
    rebuilding the <assign> pseudofile for each entry in your TOOLS.INI
    file.

 This behavior does not occur in PWB version 1.00. Version 1.10
 includes a change to the earlier version; you can see a new assignment
 (made via "arg textarg <assign>") immediately updated if you are
 viewing the <assign> pseudofile.

 This is expected behavior because the <assign> pseudofile is meant to
 show the settings that were in effect at the time the file was
 displayed. It is not recommended that it be dynamically updated except
 via the mechanism of actually editing the file. If you changed a
 setting via "arg textarg assign" (ALT+A textarg ALT+=), a better way
 to view your new setting(s) is by using "refresh" (SHIFT+F7), or by
 switching away and back again via "setfile" (F2).


 61. PWB Ignores Certain Compiler Switches in Additional Options

 Product Version(s): 1.00 1.10 | 1.00 1.10
 Operating System:   MS-DOS    | OS/2
 Flags: ENDUSER | s_c
 Last Modified: 25-FEB-1991    ArticleIdent: Q69145

 The compiler switches

    /Fo, /Fe, /F hexnum, /Fm, and /link link-info

 are ineffective when entered in the Additional Options field of the C
 Compiler Options dialog box from the Options menu of the Programmer's
 Workbench (PWB). This is the intended behavior. The functionality of
 all of these switches is provided through the Compiler, Link, and
 Build Options dialog boxes from the Options menu.

 The /Fo switch is overridden by PWB as it creates the .MAK file needed
 to build the project. To perform this function correctly:

 1. Set a program list from the Make menu.
 2. Choose Build Options from the Options menu.
 3. Choose the Build Directory button.
 4. Enter the destination path in that field, such as:

       C:\C600\PROJECT\

 5. Rebuild the project, and both the .EXE and .OBJ files will be placed
    in that directory.

 The other switches are used only to pass information to the linker
 when the CL command is used outside PWB without the /c option. Because
 PWB always compiles and links separately, these switches are lost. To
 utilize these switches from within PWB, select the appropriate options
 in the Link Options dialog box from the Options menu.


 62. How to Increase the Size of the PWB Build Status Box Under DOS

 Product Version(s): 1.00 1.10
 Operating System:   MS-DOS
 Flags: ENDUSER | window dialog
 Last Modified: 22-FEB-1991    ArticleIdent: Q69475

 In the DOS version of the Microsoft Programmer's WorkBench (PWB)
 versions 1.00 and 1.10, the status box displayed in the center of the
 screen during a compile can be made larger by increasing the length of
 the command being executed.

 When Build or Rebuild All is selected from the Make menu in PWB, a
 build status box appears on the screen showing the command currently
 being executed. Unfortunately, this box is often too small and the
 current command being displayed gets truncated. One way to increase
 the size of this box is to increase the length of the NMAKE command
 line.

 To increase the length of the NMAKE command line, add the following
 text (without the quotation marks) to the NMAKE Options dialog box,
 which can be selected from the Options menu:

    "                                                /NOLOGO"

 Be sure to include the spaces when you type this line. Then, when you
 select Build or Rebuild All from the Make menu, the build status box
 will be almost as wide as the screen, allowing most of the subsequent
 commands to fit completely into the box.

 If you use the PWB "compile" command, or choose the Compile File
 option from the Make menu, the build status box behaves similarly --
 the longer the command to be executed command, the larger the box will
 be.






 Microsoft CodeView
 =============================================================================


 1. Sequential Mode Not Available in CodeView Version 3.00

 Product Version(s): 3.00 3.01 3.11  | 3.00 3.01 3.11
 Operating System:   MS-DOS          | OS/2
 Flags: ENDUSER |
 Last Modified:  6-FEB-1991    ArticleIdent: Q69065

 The CodeView sequential mode (/T option) is not available in CodeView
 version 3.00.

 In CodeView versions 2.30 and earlier, the /T option caused the
 debugger to operate in "sequential mode," which means that only a
 command-line interface was available. You could then type the command
 "=COM1" to redirect the input and output to the COM port, which
 allowed debugging via a remote terminal.

 The /T option and the "=COM1" command are not available in CodeView
 3.00, 3.10, and 3.11 because of the new windowing environment used in
 these versions.

 However, you can still redirect CodeView output to COM1 using the
 Redirected Output command.

 The Redirected Output command causes the CodeView debugger to write
 all subsequent command output to a device, such as another terminal, a
 printer, or a file. The term "output" includes not only the output
 from commands but also the command characters that are echoed as you
 type them.

 The second greater-than symbol (optional) appends the output to an
 existing file. If you redirect output to an existing file without this
 symbol, the existing file will be replaced. For example:

    >>COM1

 In the example above, output is redirected to the device designated as
 COM1 (probably a remote terminal). You might want to enter this
 command, for example, when you are debugging a graphics program and
 want CodeView commands to be displayed on a remote terminal while the
 program display appears on the originating terminal.

    >>OUTFILE.TXT

 In the example above, output is redirected to the file OUTFILE.TXT.
 This command is helpful in keeping a permanent record of a CodeView
 session.


 2. How Interrupts Are Handled in CodeView

 Product Version(s): 1.00 1.10 2.00 2.10 2.20 2.30
 Operating System:   MS-DOS
 Flags: ENDUSER | TAR55548
 Last Modified:  9-AUG-1989    ArticleIdent: Q11817

 Question:

 How does CodeView handle interrupt vectors? Does it mask any
 interrupts when it runs?

 Response:

 CodeView saves and restores about 60 interrupt vectors as a safety
 feature. However, it only redirects the following nine vectors for its
 own use:

    0       Divide By 0
    1       Single Step
    2       NMI
    3       Breakpoint
    9       Keyboard
    21H     DOS functions
    22H     DOS terminate
    23H     ^C
    24H     Critical Error

 The remaining estimated 51 vectors are never altered by CodeView
 unless something else (e.g. the program being debugged) alters them
 after CodeView has started up. In this case, CodeView restores them to
 their original value as it exits.

 When you enter G(o) and let your program run, CodeView relinquishes
 control and lets all interrupts (except the nine listed above) flow
 into your application for processing. However, when you hit a
 breakpoint, the 8259 Programmable Interrupt Controller is masked. This
 prevents interrupts from coming into your application while your
 program is suspended. If you enter G(o) again, CodeView reenables
 interrupts to your application.

 To avoid a bug in the 8086 family, CodeView masks the interrupt
 controller during T(race) commands and some P(rogram step) commands.
 CodeView Versions 2.00 and above solve this restriction by emulating
 the interrupts for your application.

 You normally do not single-step or trace real-time code, so this
 should not be a problem for developers writing interrupt-driven code.
 However, it is something you should be aware of if you are depending
 on interrupts to get to your application. For example, it will not
 work if you enter "T 1000" and expect your program to catch and
 process interrupts during the trace. You will need to set a breakpoint
 at the instruction with which you are concerned, then enter G(o).


 3. Debugging Routines That Are in Libraries

 Product Version(s): 1.00 1.10 2.00 2.10 2.20 2.30 | 2.20 2.30
 Operating System:   MS-DOS                        | OS/2
 Flags: ENDUSER | TAR55321
 Last Modified: 21-AUG-1989    ArticleIdent: Q11877

 Question:

 When CodeView attempts to debug a function from a library module, it
 is unable to find the source even when that module was compiled with
 -Zi. It prompts me to "Enter Directory for Program (CR for None)?". I
 enter the directory in which PROGRAM.C resides, but CodeView cannot
 find it. Is there any solution other than not placing modules I wish
 to debug in libraries?

 Response:

 This is a consequence of the way the LIB utility works. When adding an
 object module to a library, LIB records only the source file's base
 name, not its extension. Therefore, "c:\c\source\module1.c" becomes
 "c:\c\source\module1" (no extension). When you are debugging an
 application that calls "module1", CodeView attempts to find
 "c:\c\source\module1". However, it does not accept the filename you
 give because the file is really named "module1.c".

 One way to work around this restriction is to rename your source file
 from "c:\c\source\module1.c" to "c:\c\source\module1" (no extension)
 after you have compiled it and put it into a library. This way, the
 actual name will match the name CodeView is searching for.

 Another solution is to use Library Manager Version 3.07 (which came
 with MASM 5.00) or later; this solves the problem by not stripping the
 file's extension as it is put into a library.


 4. CVP May Generate a Trap B with Large Programs Under OS/2 1.30

 Product Version(s): 2.20 2.30 3.00 3.10 3.11
 Operating System:   OS/2
 Flags: ENDUSER | gp fault protection violation
 Last Modified: 25-FEB-1991    ArticleIdent: Q69348

 Debugging a large application with CodeView under OS/2 version 1.30
 may result in a Trap B system error. Trap B is a "segment not present"
 exception, which results from changes that were made to this version
 of the operating system.

 In version 1.30 of OS/2, the code for DosPTrace() was made swappable,
 while in previous versions it was not. DosPTrace() is part of the OS/2
 API that allows a parent process to control the execution of a child
 process, and to access the child process's memory directly to insert
 breakpoints or change data.

 Because CodeView relies heavily on DosPTrace(), problems arise if this
 code is swapped from memory. The majority of problems occur when
 execution reaches a breakpoint while the DosPTrace() code is not
 present; control should then jump to code that is not currently in
 RAM.

 Because large programs (or heavily loaded systems) tend to result in
 more swapping, this problem appears much more readily when debugging
 large applications.

 The only sure workaround for this problem is to turn off swapping
 while debugging, but it also may help to increase or free up available
 memory. To disable swapping, modify the MEMMAN switch in CONFIG.SYS as
 follows:

    MEMMAN=NOSWAP

 To increase available memory, either install more memory in the
 computer itself or terminate all other unnecessary processes before
 debugging (to remove them from memory).

 This problem is the result of a design change with OS/2 1.30 and is
 not a problem with CodeView. This change is being reconsidered for
 future versions of OS/2. New information will be posted here as it
 becomes available.


 5. Using Two Monitors with CodeView

 Product Version(s): 1.00 1.10 2.00 2.10 2.20 2.30 | 2.20 2.30
 Operating System:   MS-DOS                        | OS/2
 Flags: ENDUSER | TAR56465
 Last Modified: 11-SEP-1989    ArticleIdent: Q11966

 Question:

 How do I use CodeView with two monitors? Where is this option
 documented?

 Response:

 Invoke CodeView with the following command:

    CV /2 PROGRAM

 This command tells CodeView to put its display on your secondary
 monitor and lets your program's output go to the default display. This
 option is documented in the "CodeView Options" section of the
 "Microsoft CodeView and Utilities Software Development Tools for the
 MS-DOS Operating System" manual in all products except Microsoft C
 Version 4.00, where it is documented in the README file.

 You must have two monitors and two display adapters to use this
 feature. You must have a monochrome and a non-monochrome monitor;
 because a monochrome monitor's video memory is in a different
 location than a CGA, EGA, or VGA's. This is how CodeView implements
 the /2 option, by writing to both sets of video memory.

 When you use the /2 option, your program's display appears on the
 current default adapter and monitor, while the debugging display
 appears on the secondary adapter and monitor. You can switch which
 monitor is the current default adapter with the MS-DOS MODE command.
 "MODE MONO" causes standard output to go to the MDA, while "MODE CO80"
 causes standard output to go to your CGA, EGA, or VGA.

 For example, if you have both a CGA and an MDA, you might want to set
 the CGA up as the default adapter. You could then debug a graphics
 program with the graphics display appearing on the graphics monitor
 and the debugging display appearing on the monochrome adapter.


 6. /L Must Give Full Pathname to .DLL Unless in Current Directory

 Product Version(s): 2.20 2.30 | 2.20 2.30
 Operating System:   MS-DOS    | OS/2
 Flags: ENDUSER |
 Last Modified: 16-AUG-1989    ArticleIdent: Q47937

 When debugging dynamic link modules with CodeView Protect (CVP), you
 must use the /L switch. Before invoking CVP, make certain that the
 .DLL is in the LIBPATH specified in the CONFIG.SYS file. When invoking
 CVP with the /L switch, if the .DLL is not located in the current
 directory, you must specify the full drive and pathname to the DLL. An
 example is the following:

    CVP /L d:\os2\dll\stdll.dll stmain.exe

 In this example, the full drive and pathname are given for the DLL to
 be debugged. If the full pathname is not given, CodeView will come up.
 However, you will be unable to step into the DLL. CodeView will simply
 step over that call.


 7. CodeView Cannot Trace into Single-Line Functions

 Product Version(s): 2.20 2.30 | 2.20 2.30
 Operating System:   MS-DOS    | OS/2
 Flags: ENDUSER |
 Last Modified: 15-SEP-1989    ArticleIdent: Q47624

 CodeView Versions 2.20 and 2.30 do not trace into a function that is
 contained in a single line of code. For example, if the following
 program is compiled and loaded into CodeView, an attempt to trace into
 the function funct() results in the trace stepping over the function,
 rather than tracing into it.

 Sample Program
 --------------

 /* SIMPLE.C ... a very simplistic sample program                    */

 int funct(void);
 int x;

 void main(void)
 {
   x = funct()
  }

 /* single-line function. It does nothing more than return a value.  */

 int funct(void){return 1;}

 If the above function is modified so that it performs exactly the same
 task but is located on multiple lines, as follows, then CodeView
 handles it correctly:

 int funct(void)
  {
    return 1;
   }



 8. Trace Stops on Line Following a Loop Before Loop Is Done

 Product Version(s): 2.20 2.30 | 2.20 2.30
 Operating System:   MS-DOS    | OS/2
 Flags: ENDUSER | S_C
 Last Modified: 15-SEP-1989    ArticleIdent: Q47625

 In trace mode, CodeView stops on the line following a loop that does
 not have open and close braces ({}), before the loop is done.

 When tracing through a loop without the braces ({}), the trace stops
 on the statement immediately following the loop each time through the
 loop, giving the impression that the statement is being executed
 inside the loop. Actual program execution is correct.

 The following program was compiled with C Version 5.10 with the
 command line

    cl /Zi /Od program.c

 and run using CodeView 2.20, as follows:

     cv program.exe

 The trace stops at the printf each time through the loop even though
 printf is not part of the loop, but does not print anything until the
 end of the program.

 Sample Program
 --------------

 #include <stdio.h>

 void main(void)
 {
     int i;
     int count;

     count = 0;

     for(i=0;i<3;i++)
         if(i)
             count++;

     printf("Count is %d\n",count);
 }


 9. The 37th Call Added to the Calls Menu Corrupts CodeView Screen

 Product Version(s): 2.20   | 2.20
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER | buglist2.20 fixlist2.30
 Last Modified: 10-NOV-1989    ArticleIdent: Q50496

 The CodeView Calls menu shows the current depth of function calls as
 well as the line number the routine was called from and the parameters
 passed. The current routine is always at the top and the routine from
 which the current routine was called is directly below.

 The routines in the Calls menu are first labeled 0-9, and if you are
 nested more than ten levels deep, CodeView labels the next 26 calls
 A-Z, for a display that can accept 36 levels of subroutine calls. If
 you exceed this limit and then select the Calls menu, the CodeView
 display becomes corrupted.

 If the display is corrupted in this manner, the Redraw ("@") dialog
 command can be used to restore the display to it's original state.

 The Stack Trace dialog command (K) has the same function as the Calls
 menu and correctly handles nesting of more than 36 levels deep.

 Microsoft has confirmed this to be a problem with CodeView Version
 2.20. This problem was corrected in Version 2.30.


 10. Quickwatch Seems to Hang When Expanding Very Large Arrays

 Product Version(s): 3.00 3.10 3.11 | 3.00 3.10 3.11
 Operating System:   MS-DOS         | OS/2
 Flags: ENDUSER | s_quickc
 Last Modified:  6-FEB-1991    ArticleIdent: Q68010

 When expanding an element in a large array (usually greater than 1000
 elements, but system dependent), the quickwatch function appears to
 hang. This apparent problem is caused by the time it takes to re-align
 the data in the window, and is actually normal operation. If you place
 the same array element in the Watch Window, it will expand instantly.


 11. Structures Declared with Near, Far, Pascal, and Fortran

 Product Version(s): 2.20 2.30 | 2.20 2.30
 Operating System:   MS-DOS    | OS/2
 Flags: ENDUSER | S_C S_QuickC buglist2.20 buglist2.30
 Last Modified: 16-AUG-1989    ArticleIdent: Q47694

 CodeView is unable to display elements of structures declared with the
 following keywords:

    near
    far
    pascal
    fortran

 Using ?? to display a structure yields the structure table with only
 one value inside. This value is the first element in the structure.
 Using w? or ? yields the following error message:

    Operand types incorrect for this operation

 Microsoft has confirmed this to be a problem with CodeView Versions
 2.20 and 2.30. We are researching this problem and will post new
 information as it becomes available.

 To work around this problem, recompile without these keywords, or
 obtain the address of the structure element and put a watch on the
 memory location.

 Consider the following large model program:

 struct { int x;
          int y;
          int z;} near a;    /* or far, pascal, fortran */

 void main(void)
 {
   a.x = 1;
 }

 To put a watch on a.x, you could issue the following commands:

 ? &a
 0x0345:0000       <- result is the address of the structure
 ww 0x0345:0x0     <- address of x
 ww 0x0345:0x2     <- address of y (two byte int from x)

 This puts a watch on the first and second elements (x and y) in the
 structure.


 12. Older Vega VGAs Hang CodeView When in VGA Mode

 Product Version(s): 2.10 2.20 2.30 | 2.20 2.30
 Operating System:   MS-DOS         | OS/2
 Flags: ENDUSER |
 Last Modified: 14-AUG-1989    ArticleIdent: Q27212

 Question:

 Why does my old Vega VGA card cause CodeView to hang when I start it
 in VGA mode? It works properly when I start CodeView when the card is
 in CGA mode.

 Response:

 Some of the older Vega VGAs do not work correctly with CodeView. The
 Vega VGA card uses the same maskable interrupt for detecting graphics
 mode as CodeView.

 We recommend that you contact Vega by calling 1 [phone] for
 advice if you experience this problem.


 13. Ambiguous Documentation of Enter ASCII (EA) Command

 Product Version(s): 2.10 2.20 | 2.10 2.20
 Operating System:   MS-DOS    | OS/2
 Flags: ENDUSER |
 Last Modified: 16-AUG-1989    ArticleIdent: Q47764

 In the "Microsoft C 5.1 Optimizing Compiler" manual, the "CodeView and
 Utilities" section does not thoroughly document the EA command for
 CodeView. The following is a more complete explanation:

    EA address [list]

    The Enter ASCII (EA) command modifies array to the value of [list].
    Address refers to what you want to modify. [list] refers to a
    string literal such as "hello". EA will copy [list] to array. Thus,
    if you specify address by giving an array, such as an array of
    characters, the array will have [list] copied into it. However, if
    you were to give a pointer to a character, then the bytes that make
    up the pointer will be directly modified, not the block of memory
    the pointer is pointing at.

 Consider the following examples:

 char array[] = "Hello";
 char *ptr    = "Hello";

 >EA array "Hi"
 >EA ptr   "Hi"

 The result is that the array would contain "Hillo", and ptr will be
 pointing to some unknown memory location.

 The array is considered a constant pointer to a block of memory, and
 as such, any operations on it can only affect the block of memory.
 However, ptr is a variable; therefore, any operations on it affect the
 value of ptr, which happens to be a two- or four-byte number. That
 number happens to refer to a location in memory.

 If you want to changed the block of memory that ptr points to, you
 must do the following:

    >EA &ptr[0] "Hi"

 Essentially, this takes the address of the character that ptr is
 pointing at, gives a constant address, and thus modifies the block of
 memory there. To clarify, imagine you have a character located some
 place in memory. To move a character, you must make a copy of it to
 some other memory location; it is not possible to take its address and
 modify the address directly to change where the character is located.
 Thus, the address of that character is always a constant value. ptr[0]
 happens to be a character located someplace in memory. As such, the
 address of that specific character is a constant value. Since a
 constant cannot be modified, EA changes the block of memory starting
 at where the constant pointer is pointing.


 14. Debugging of DLLs That Do Not Have the .DLL Extension

 Product Version(s): 2.30   | 2.30
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified: 21-AUG-1989    ArticleIdent: Q47938

 CodeView Protect (CVP) Version 2.30 has the ability to debug DLLs that
 are called with DosLoadModule(). DosLoadModule() can load DLLs that
 do not have the .DLL extension. However, CVP 2.30 cannot debug DLLs
 that do not have the .DLL extension. If you want to debug DLLs that
 are called with DosLoadModule, they must have the .DLL extension.

 Microsoft is aware of this limitation with CodeView Protect 2.30. We
 are researching this problem and will post new information as it
 becomes available.


 15. Resident Software May Cause "Internal Debugger Error 80"

 Product Version(s): 1.x 2.00 2.10 2.10 2.30
 Operating System:   MS-DOS
 Flags: ENDUSER |
 Last Modified: 29-AUG-1989    ArticleIdent: Q47989

 Question:

 Sometimes when I run CodeView, I get an "Internal Debugger Error 80"
 message. What causes this?

 Response:

 Internal Debugger Error messages are usually caused by problems in
 your MS-DOS environment; the most likely cause is the presence of
 memory-resident software, commonly referred to as TSRs (terminate-
 and-stay-resident software).

 For example, running CodeView with Borland's Sidekick loaded has been
 known to cause "Internal Debugger Error 80" and "R6002: Floating Point
 not loaded" error messages. "Internal Debugger Error 80" has also been
 reported when CodeView was run with Software Solutions' "Software
 Carousel" loaded into memory.

 CodeView Versions 2.00 and later have become increasingly more
 sensitive to TSRs. If you receive an Internal Debugger Error message,
 or you are experiencing strange problems within CodeView, make sure
 you are running CodeView with no memory-resident software loaded
 (including, but not limited to, device drivers, screen savers,
 keyboard enhancers, command-line editors, etc.). Disabling your
 resident software, but not rebooting, may not completely remove its
 interference, so be sure to "boot clean" when trying to resolve a
 problem of this type.

 If you continue to receive the error message without memory-resident
 programs, try running CodeView on some other program to see if the
 error is related to particular code. If the error is related to the
 specific code, and you are unable to determine the cause, you may want
 to call Microsoft Product Support for assistance at [phone].

 If the error is not dependent on your code, the problem might be the
 particular sequence of CodeView commands you execute. Make a note of
 what operations you performed, i.e., the sequence of Trace, Go, Watch,
 Tracepoint, etc., commands that were issued, and contact Microsoft
 Product Support via phone, letter, or Microsoft OnLine.


 16. CVP Restart Command (Dialog Version) Doesn't Properly Set argc

 Product Version(s): 2.20 2.30 | 2.20 2.30
 Operating System:   MS-DOS    | OS/2
 Flags: ENDUSER | buglist2.20 buglist2.30
 Last Modified: 28-AUG-1989    ArticleIdent: Q48000

 When using the dialog version of the Restart command, you can restart
 your program with command-line arguments; however, under CodeView
 Protect (CVP) Versions 2.20 and 2.30, argc does not get properly set.

 The Dialog Restart command is often used to restart a program with
 command line arguments. For example, you could use the following:

    L arg1 arg2 arg3

 This example restarts the current executable file, retaining any
 breakpoints, watchpoints, and tracepoints, with arg1, arg2, and arg3
 loaded into argv[1], argv[2], and argv[3], respectively. Argv[0] is
 always set to the name of the current executable file. Argc, at this
 point, should be set to four. The problem presents itself here; argc
 either remains unchanged from the value it was initially set to when
 CodeView was started, or is decremented by one. If, for example,
 CodeView is started with two command-line arguments (argc would then
 be set to three) and then executed, the previous example argc (which
 should then set argc to four) would remain unchanged. When using the
 Dialog Restart command and specifying fewer arguments than were
 specified at start up, argc sometimes is decremented by one.

 Microsoft has confirmed this to be a problem with CodeView Versions
 2.20 and 2.30. We are researching this problem and will post new
 information as it becomes available.


 17. Cannot Load CTRL+Z-Terminated Files with Less than 129 Bytes

 Product Version(s): 1.00 1.10 2.00 2.10
 Operating System:   MS-DOS
 Flags: ENDUSER | buglist1.00 buglist1.10 buglist2.00 buglist2.10 qfbv
 Last Modified:  4-NOV-1988    ArticleIdent: Q26548

 Problem:

 When using the F(ile) O(pen) command to load a text file which has
 less than 129 bytes and is terminated with a hex 1A (decimal 26,
 CTRL+Z, EOF), CodeView issues the error message "Not a text file." If
 the CTRL+Z character is removed, or if the file size is 129 bytes or
 greater, CodeView has no problem loading it.

 Response:

 Microsoft has confirmed this to be a problem in Version 1.00, 1.10,
 2.00, and 2.10. We are researching this problem and will post new
 information as it becomes available.


 18. Debugging High Resolution EGA or VGA Graphics

 Product Version(s): 1.00 1.10 2.00 2.10 2.20 2.30 | 2.20 2.30
 Operating System:   MS-DOS                        | OS/2
 Flags: ENDUSER | TAR61178
 Last Modified: 14-AUG-1989    ArticleIdent: Q23308

 Question:

 I am trying to debug a program that does EGA or VGA graphics. When I
 continue from a breakpoint after the program has painted the screen,
 the screen is not as it was before the breakpoint. I think that all
 colors have been turned to black, but I am not sure.

 I tried this procedure with no switches, with /s, and with /t. The
 program is using the EGA in 640x350 16-color mode. Is this supposed to
 work? If it does not work, why not? What will you do about supporting
 the higher modes for the new machines such as the Personal System 2
 series from IBM?

 Response:

 This behavior is partly related to the size of the buffer that
 CodeView creates for storing screen information. If you are running on
 a CGA, EGA or VGA board, this buffer is by default 16K. If you are running
 on a monochrome board, this buffer is by default 4K. As you are
 finding, 16K is simply not enough memory for a color image using
 640x350 resolution (the maximum resolution supported would be
 640x200).

 One of the reasons why CodeView does not have the ability to handle
 the buffer requirements of an EGA image is that the EGA registers are
 write only. There is no way for CodeView to detect what mode the EGA
 currently is in so it can adjust the size accordingly. Also note that
 with the different resolutions the image is stored in different memory
 locations. The black on black characters may simply be a blank image
 because CodeView cannot tell that the resolution is different and
 therefore the image is located elsewhere.

 With the PS/2 machines this is not an issue because the EGA registers
 have read capability. We are reviewing this with regard to future
 implementations of CodeView.

 The following are some ways to work around this current limitation:

 1. Try writing a routine that will place the display in the desired
    mode before you invoke CodeView. CodeView will be able to judge
    which mode is currently in effect and can locate the image in the
    correct area of memory. Note that the image will not be displayed
    in color. You will only see the higher resolution since the buffer
    is not big enough.

 2. Debug your applications that run in high resolution graphics with a
    second monitor (use the /2 switch). Since the display is going to a
    different screen, CodeView will not have to worry about changing
    the video modes or the buffering.


 19. CodeView Version 2.20 Is Called CVPCK.EXE by DOS Version 2.10

 Product Version(s): 2.20
 Operating System:   MS-DOS
 Flags: ENDUSER | CV CVPCK CVPACK 2.x
 Last Modified: 21-SEP-1989    ArticleIdent: Q48689

 Question:

 When trying to invoke CodeView Version 2.20 under DOS Version 2.10 or
 2.11, I get the messages "Cannot Find CVPCK.EXE" and "Please enter new
 program spec:". How can I get CodeView 2.20 to work under DOS Versions
 2.1x?

 Response:

 If you rename CV.EXE to CVPCK.EXE, you can run CodeView Version 2.20
 under DOS Version 2.10 or 2.11. You must also rename CV.HLP to C.HLP
 to make the on-line help accessible.

 CodeView Version 2.20 is included with C Version 5.10, FORTRAN Version
 4.10, Pascal Version 4.00, and Macro Assembler (MASM) Version 5.10.

 Many people mistakenly assume that CodeView is actually looking for
 CVPACK.EXE, which also comes with the software packages listed above.
 If you rename CVPACK.EXE to CVPCK.EXE and then try to run CVPCK.EXE,
 you will receive the error message "overlay not found." If you receive
 this error, delete CVPCK.EXE, copy both CV.EXE and CVPACK.EXE from the
 installation disks, and follow the instructions above.

 Under DOS Versions 3.x, a C program's name is available from argv[0].
 Under DOS Versions 2.x, argv[0] always equals the letter "C", so
 programs that need to find themselves under DOS Versions 2.x also have
 their own names hard coded as the filename to locate. Unfortunately,
 the hard-coded name within CodeView Version 2.20 is "CVPCK.EXE", so
 this is what it looks for under DOS Versions 2.x.


 20. CodeView String Search Length Limited to 19 Characters

 Product Version(s): 2.10 2.20 2.30 | 2.10 2.20 2.30
 Operating System:   MS-DOS         | OS/2
 Flags: ENDUSER | SR# G890810-24574 P_WinSDK
 Last Modified: 19-SEP-1989    ArticleIdent: Q48863

 CodeView Versions 2.20 and 2.30 and CodeView for Windows Version 2.10
 have a 19-character limit in the "Find..." option of the Search menu,
 even though the dialog box is much longer than 19 characters. Entering
 a search string longer than 19 characters results in one of two error
 messages.

 If the search string entered is 20 or 21 characters long, CodeView
 displays the erroneous message "No match of regular expression," even
 if the search string does exist in the file. If the search string is
 22 characters or more in length, CodeView displays the more
 appropriate message "Regular expression too long."

 Although 19 characters sometimes can be limiting, CodeView does
 substring searches so that searching for the following

    AFunctionWithAVeryL

 finds the following string:

    AFunctionWithAVeryLongName

 You will have problems only if you have both of the following and
 you are trying to locate one, but not the other:

    AFunctionWithAVeryLongName()
    AFunctionWithAVeryLongParameterList(a,b,c,d,e,f,g,h,i,j)

 In this case, you won't be able to specify search strings long enough
 to distinguish between the two. However, you can repeatedly use the
 Next command from the Search menu to find the next occurrence of the
 following:

    AFunctionWithAVeryL

 The Next command will find whichever of the above two function names
 that comes next in the source file.


 21. Files, Environment Inaccessible Only While Running under CVP

 Product Version(s): 2.20
 Operating System:   OS/2
 Flags: ENDUSER |
 Last Modified: 30-NOV-1989    ArticleIdent: Q49313

 Due to combined problems in both protected-mode CodeView (CVP) Version
 2.20 and OS/2 Version 1.00 or 1.10, programs that correctly access
 data files and/or system environment information could fail when
 attempting this same access while running under CVP 2.20. This is
 strictly a protected-mode problem and is unrelated to the use of
 CodeView under MS-DOS. The sample program at the end of this article
 can be used to demonstrate this problem.

 The system environment information includes such items as the path and
 other environment variables, as well as the current working directory
 for each disk drive. This information is normally available to an
 executing program, but for a program being debugged with CVP 2.20
 running under OS/2 1.00 or 1.10, most of this environment information
 is inaccessible.

 This inaccessibility is a result of environment handling problems in
 both CVP 2.20 and OS/2 Version 1.00. Since CodeView is run from the
 command prompt, all the current environment information is available
 to CodeView itself, but the program being debugged is given its own
 new screen group in which to run. It is in this new screen group that
 the current environment information is lost because it is not carried
 over by either OS/2 or CodeView.

 Although the OS/2 problem has been corrected in Version 1.10, the
 CodeView problem still prevents access to the environment. Therefore,
 upgrading either CodeView or OS/2 alone does not solve the problem.
 Only with CodeView Version 2.30 running under OS/2 Version 1.10 is the
 problem eliminated.

 There may be some environment information available to the program
 being debugged, but only if it was set in the CONFIG.SYS file at start
 up. Since each new screen group is begun with a copy of the original
 start-up system environment, any SET commands carried out in the
 CONFIG.SYS file will then be duplicated for all subsequent screen
 groups.

 Otherwise, if a program needs access to environment variables that
 were set in the current screen group where CodeView will be invoked,
 then the only way to make the information available while debugging is
 to temporarily hard code the information into the program. After
 debugging, the program can be changed back to using the actual
 environment strings.

 The only other alternative to temporarily hard code the environment
 information into the program is to set the environment variables in the
 CONFIG.SYS file at boot time, rather than setting them in the current
 screen group.

 The only reason a file access will fail only while the program is
 running under CodeView is if the program is assuming the file is in
 the current working directory on the current or another drive.

 If this is the case, then one of the following workarounds may be used
 to gain access to files while debugging:

 1. Use full pathnames for all file accesses, since this alleviates any
    dependency on knowing the current working directory for the drive
    that is being accessed. If it is not feasible to have hard-coded
    pathnames in the completed program, at least adding the full paths
    temporarily will allow debugging.

 2. Put the files to be accessed in the root directory of the boot
    drive. This allows them to be found even under CodeView because
    with no environment information, the current working directory
    defaults to the root of the boot drive.

 3. Use a two-monitor debugging setup and start CodeView with the /2
    option. In this situation, CVP does not need to start a new screen
    group for the program being debugged because it can run it on the
    second monitor. Thus, the current environment information is
    available to both programs because they are both running in the
    current screen group.

    For more information about debugging with a two-monitor setup, query
    on the following:

       CodeView two monitor debugging

 The following C program can be used to demonstrate this environment
 problem:

 Program Example:
 ---------------

     /* TEST.C - shows inaccessible files under CodeView

        Compile with : CL /Zi /Od test.c
        Run with : test <filename>      where <filename> is any file
                        in the current directory.  The file will be
                        opened properly.
        Begin CVP with : CVP test <filename>     where <filename> is
                        the same as before. The file will not be
                        found when the program is run or traced.
     */

     #include <stdio.h>
     void main(int, char *[]);

     void main(int argc, char *argv[])
     {
         FILE *dfile ;

         if ((dfile = fopen(argv[1], "rb")) == NULL) {
             perror ("") ;
             printf ("Cannot open file '%s'.\n\n", argv[1]) ;
         }
         else {
             printf("File %s opened OK.\n\n", argv[1]) ;
             fclose (dfile) ;
         }
     }


 22. COM Port Time-Out Halts Redirection of CVP to Remote Terminal

 Product Version(s): 2.20 2.30
 Operating System:   OS/2
 Flags: ENDUSER |
 Last Modified: 27-OCT-1989    ArticleIdent: Q49376

 When using protected-mode CodeView (CVP) under OS/2, there is a
 problem with the serial communications (COM) ports timing out after 60
 to 90 seconds of inactivity. This time-out makes it essentially
 impossible to do remote terminal debugging with CVP. Once the time-out
 occurs, no further input is accepted from the remote terminal. The
 only workaround is to quit CodeView and begin again, or to do a break
 and then restart the redirection to the COM port.

 The CodeView Debugger allows redirection of input and output to a file
 or device. This procedure is commonly used to set up a remote (dumb)
 terminal for CodeView input and output, while the PC screen is used
 for displaying the program input and output. The terminal is connected
 through a COM port, which eliminates the need for a second video
 adapter as is required when using two monitors with the /2 option.
 Entering "=COM1" at the CodeView command prompt enables input and
 output redirection to the device designated as COM1.

 This debugging arrangement works great with CodeView under MS-DOS, but
 it becomes unworkable with CVP under OS/2 because the internal calls
 that are used to set up the redirection do not account for time-outs
 due to inactivity. Thus, if you are entering commands from the remote
 terminal at a steady pace, everything proceeds smoothly. However, if you
 stop and wait for more than about 60 seconds without doing any input,
 the port will time-out and leave you stranded because the keyboard no
 longer responds.

 In a normal debugging session, it is quite likely that there would be
 many instances greater than 60 seconds where input is not yet needed
 or desired; therefore, this situation quickly becomes intolerable. The
 only way to regain control is to enter CTRL+C at the PC keyboard,
 which ends the redirection. At that point, you could enter "=COM1"
 again on the PC keyboard to restart the redirection if you so desired.


 23. CVP 2.30 Does Not Allow Pathnames for DLLs Specified with /L

 Product Version(s): 2.30
 Operating System:   OS/2
 Flags: ENDUSER | buglist2.30
 Last Modified: 10-OCT-1989    ArticleIdent: Q49377

 Protected-mode CodeView (CVP) Version 2.30 allows debugging of dynamic
 link libraries (DLLs) by specifying their names on the command line
 with the /L switch. Because of a problem exclusive to CVP 2.30, this
 particular version of the debugger does not allow a pathname to be
 used with /L to specify the DLL's location in another directory.
 Therefore, all DLLs to be debugged with CVP 2.30 must reside in the
 current working directory.

 Since DLLs are also required to be in a directory that is on the
 LIBPATH, two copies of the DLL may need to be resident on the disk,
 unless the current working directory is also a LIBPATH directory.

 Microsoft has confirmed this to be a problem with CodeView Version
 2.30. We are researching this problem and will post new information as
 it becomes available.

 When tracing a program under CodeView that calls DLLs, the only way to
 trace into the code of a particular DLL is if the DLL was specified
 ahead of time on the command line with /L when CVP was invoked. If a
 program statement is traced that calls a DLL that was not specified by
 /L, then CodeView executes all the code in the DLL and returns control
 back at the line following the call to the DLL. Thus, the call is
 handled as if the step command, rather than the trace command, had
 been used.

 You can indicate only one DLL with the /L switch, so debugging
 multiple DLLs requires multiple /L switches. Normally, the switch is
 followed by a space and the name of the DLL to be debugged, and if the
 DLL is not located in the current directory, a path may precede the
 DLL name. It is only with CVP 2.30 that this becomes a problem because
 a pathname is not recognized with this version, so tracing into the
 DLL is prevented.

 Unfortunately, CodeView does not display error messages for improper
 use of the /L switch, so if the DLL is not found, there is no message
 indicating this. Instead, CodeView does not allow debugging of the
 improperly specified DLL. Use of a pathname with /L with CVP 2.30
 causes this same behavior.

 The only workaround for DLL debugging with CVP 2.30 is to keep a copy
 of the DLL in the current working directory from which CodeView is
 invoked. Thus, if the current directory is not a directory specified
 on the LIBPATH, there must be two copies of the DLL on the disk. It is
 very important that the two copies are exactly the same because
 differing code makes any attempts at debugging very difficult and
 confusing.

 A common practice is to put a period (.) as the first directory on
 the LIBPATH because this makes the current working directory a LIBPATH
 directory, eliminating the need for two copies of the DLL. More
 information on this practice can be found by querying on the
 following words:

    CodeView DLL debugging and libpath


 24. Label Finding Command Does Whole Word Search, Not Text Search

 Product Version(s): 2.20 2.30 | 2.20 2.30
 Operating System:   MS-DOS    | OS/2
 Flags: ENDUSER |
 Last Modified: 27-OCT-1989    ArticleIdent: Q49378

 In CodeView Versions 2.20 and 2.30, under the Search menu is the Label
 option for searching for a label. Unlike the Find option, which
 searches the source code for any regular expression, the Label option
 searches the executable code for an assembly language label.

 This search is not a text search and does not accept regular
 expressions. The only way to find a label is to specify the entire
 label name as the search string. In addition, if the Case Sense option
 is selected on the Options menu, the label is found only if the case
 of each character matches exactly.

 For example, if you want to find the code for the standard C
 stack-checking function "_chkstk", choose Search Label, and type in
 "__chkstk" (without the quotation marks), and press ENTER. This
 switches you into assembly mode, if you weren't there already, and
 puts the line with the __chkstk label at the top of the window. The
 two underscores are required since C appends an underscore to the
 front of all labels and the original function name is "_chkstk".

 You will receive the error message "Unknown Symbol" if the label
 cannot be found or if you mistype or incompletely type the correct
 name. For example, "_chkstk", "chkstk", "__chk", and "__chkstks" all
 fail to find a match in the above example. If Case Sense is on,
 searching for the label "__CHKSTK" also results in failure.


 25. The Assemble Command with ADD Instructions

 Product Version(s): 2.20 2.30  | 2.20 2.30
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER | buglist2.20 buglist2.30
 Last Modified:  9-AUG-1989    ArticleIdent: Q40225

 Problem:

 In CodeView, I'm using the assemble command to change my ADD
 instruction, and it changes all the code from that point on.

 Response:

 If you had the instruction ADD AL,44, for example, and you wanted to
 change the 44 to 45 (or any other number), you could use the Assemble
 command to do it. The Microsoft Macro Assembler generates a 04 44 for
 that instruction; however, when changing the 44 to 45, CodeView
 generates an 80 C0 45, which is still the correct instruction of ADD
 AL,45. However, it's a 3-byte instruction. Inserting one extra byte
 into your code will cause each op code from that point on to be off by
 one.

 Microsoft has confirmed this to be a problem in Versions 2.20
 and 2.30 of CodeView. We are researching this problem and will
 post new information as it becomes available.



 26. CV Prior to 3.00 Needs /S for Mouse to Appear in OS/2 DOS Box

 Product Version(s): 1.00 1.10 1.11 2.00 2.10 2.20 2.30 2.35
 Operating System:   MS-DOS
 Flags: ENDUSER |
 Last Modified:  6-FEB-1991    ArticleIdent: Q23646

 With all versions of real-mode CodeView (CV) earlier than version
 3.00, the mouse cursor does not display when running in a DOS session
 under OS/2 in the DOS compatibility box.

 The situation exists because the mouse draws the pointer only in video
 page zero, while CodeView uses video page one. This problem is caused
 by OS/2 itself because the mouse cursor works normally under DOS.

 To work around this limitation with CV 1.x or 2.x, invoke CodeView
 with the /S switch so screen swapping is used as the method of screen
 exchange. This method forces CodeView to swap in and out of page zero.

 Beginning with version 3.00, CodeView detects whether it is running in
 a DOS session under OS/2, and if so, automatically starts up with /S
 as the default in order to make the mouse visible.


 27. CVPACK /p Causes a More Complete Packing

 Product Version(s): 2.20
 Operating System:   MS-DOS
 Flags: ENDUSER |
 Last Modified: 28-MAR-1989    ArticleIdent: Q38020

 When you are unable to load your program into CodeView, try packing
 the program with CVPACK.EXE. If you want a more complete packing of
 your executable, then run CVPACK.EXE with the /p option. This option
 will take longer to run, but it will generate better results.

 The /p option for CVPACK.EXE is documented on Page update-17 in the
 "Microsoft C 5.1 Optimizing Compiler, CodeView and Utilities,
 Microsoft Editor Mixed-Language Programmer's Guide."

 Normally, CVPACK discards unused debugging information and appends
 it to the file. With the /p option, CVPACK discards the unused
 debugging information, then proceeds to sort it throughout the
 executable file.


 28. Mouse Cursor Disappears After Right Click

 Product Version(s): 2.20 2.30 | 2.20 2.30
 Operating System:   MS-DOS    | OS/2
 Flags: ENDUSER |
 Last Modified: 14-AUG-1989    ArticleIdent: Q38021

 Problem:

 I have just clicked my right mouse button to acknowledge a pop-up
 message and my mouse cursor has disappeared. I had just clicked my
 right mouse button before for another operation.

 Note: This also occurs when you hit any button on the three button
 Logitech mouse.

 Response:

 To get your mouse cursor back again, redraw the screen with the "@"
 command.


 29. CVP 2.30 Hangs When /O Is Specified, but Child Is Not Debugged

 Product Version(s): 2.30
 Operating System:   OS/2
 Flags: ENDUSER | buglist2.30
 Last Modified: 27-OCT-1989    ArticleIdent: Q49381

 Beginning with protected-mode CodeView (CVP) Version 2.30, you can
 debug child processes from within a parent process's CodeView session
 by invoking CodeView with the /O switch. When the program is executed
 to the point where the child process is invoked, CodeView displays a
 prompt showing you the child's process ID (PID) and asks, "Do you wish
 to debug (y/n)?". Entering "y" brings up the child process and allows
 you to debug it. Pressing "n" should cause the child to execute
 without any debugging.

 Unfortunately, there is a problem in CVP 2.30 that causes CodeView to
 hang if you answer no to debugging the child. The only workaround is
 to always answer yes when prompted to debug a child process, or to
 invoke CodeView without the /O switch because this prevents the prompt
 entirely.

 Microsoft has confirmed this to be a problem with CodeView Version
 2.30. We are researching this problem and will post new information as
 it becomes available.

 If the program you are debugging is not a Presentation Manager (PM)
 application, you may be able to kill the CodeView session if it should
 hang as a result of answering "n" to the debugging child process. You
 must switch to the Task Manager and use it to close the hung CodeView
 session. If you are working on a PM application, the only workaround
 may be to reboot the computer.


 30. Cannot Debug Code in Overlays in Small or Compact Model

 Product Version(s): 2.10 2.20 2.30
 Operating System:   MS-DOS
 Flags: ENDUSER |
 Last Modified: 14-AUG-1989    ArticleIdent: Q27128

 Question:

 I have a C program, compiled with Microsoft C Version 5.00, which
 consists of several modules linked together as overlays. I am not able
 to trace into code in the overlays. I compiled in the default memory
 model. What is wrong?

 Response:

 The modules must be compiled in medium or large memory model to be
 overlaid. In the default model (small), or in the compact model, there
 is only one code segment, which cannot be overlaid. The main module is
 always resident and cannot be overlaid. You must use the compile
 option /AH, /AL, or /AM.


 31. Code that Will Hang IBM XTs or Compatibles

 Product Version(s): 1.00
 Operating System:   MS-DOS
 Flags: ENDUSER | TAR57675 buglist1.00
 Last Modified:  8-NOV-1988    ArticleIdent: Q23856

 Problem:

 The following code will hang IBM XTs or compatibles if specific
 commands are issued when inside of CodeView:

    #include <stdio.h>
    main()
    {
         int n;
         double f;

         while(1)   {
                    scanf("%d",&n);
                f=1.0;
                while (n>1) f=f*n--;
                   printf("%.101g%c",f,'\n');
                    }
    }

 For the program to fail in CodeView, first set a breakpoint at
 instruction f=1.0. Issue the Go command, then the P command.

 Response:

 This is corrected in CodeView version 2.20.

 A workaround is to place a breakpoint at the instruction before or
 after the assignment to f.


 32. /DOSSEG Link Switch Fails to Make CodeView .exe

 Product Version(s): 2.20 2.30
 Operating System:   MS-DOS
 Flags: ENDUSER |
 Last Modified:  9-AUG-1989    ArticleIdent: Q38163

 Question:

 CodeView is failing on an .exe produced using the /DOSSEG linker
 switch. CodeView responded to an attempt to run with this .exe
 with a "not enough space" diagnostic. What is the problem?

 Response:

 The modules below demonstrate the problem. In this case, compiling the
 C source module and assembling the MASM source module with the
 appropriate CodeView switches, then linking with the /CO /DO switches
 generates a bad .exe. The problem is that CodeView displays source
 with extended ASCII characters.

 To work around this problem, put .DOSSEG in the MASM modules
 being linked, and omit the /DO switch rather that trying to
 force the linker to do the work. Also, switching the order of
 the linker switches may solve the problem.

 The following example demonstrates the problem:

 #include <stdio.h>
 main ()
   {
   long int getds(void), getdsq(void);
   printf("ds.DATA  = %lX\nds.DATA? = %lX\n",getds(),getdsq());
   }

 **************************************************************
 ;        DOSSEG could be put here
         .MODEL  small
         .DATA
 array   dd      0
         .DATA?
 arrayq  dd      ?
         .CODE
         PUBLIC  _getds,_getdsq
 _getds  PROC
         mov     ax,SEG array
         mov     dx,ds
         ret
 _getds  ENDP
 _getdsq PROC
         mov     ax,SEG arrayq
         mov     dx,ds
         ret
 _getdsq ENDP
         END


 33. 3270 ERMA Emulator

 Product Version(s): 1.00 1.10 2.00 2.10 2.20 2.30
 Operating System:   MS-DOS
 Flags: ENDUSER |
 Last Modified:  9-AUG-1989    ArticleIdent: Q24200

 Question:
    Does CodeView support the 3270 ERMA emulator?

 Response:
    CodeView does not directly support any other program. In this case,
 the 3270 ERMA emulator would have to accommodate CodeView. CodeView
 performs some hardware specific routines (e.g. checking to see if an
 EGA is present) and makes some assumptions on the state of the
 machine. If another program changes the state of the machine, it may
 not work with CodeView. It has been reported that CodeView will hang
 if the 3270 ERMA emulator is enabled; we recommend you disable the
 emulator before running CodeView.


 34. Flipping and Swapping Screens

 Product Version(s): 1.00 1.10 2.00 2.10 2.20 2.30
 Operating System:   MS-DOS
 Flags: ENDUSER |
 Last Modified:  9-AUG-1989    ArticleIdent: Q24201

 Question:
    What is the difference between flipping and swapping in CodeView?

 Response:
    Both are ways of maintaining two alternate screens for display on
 one monitor. The difference is in the way the task is accomplished.
    When swapping is selected, CodeView allocates a 16K buffer (a 4K
 buffer for a monochrome adapter) to hold the alternate screen. When
 the other screen is required, CodeView swaps the screen into the
 display buffer and places the other screen into the storage buffer.
 Swapping takes memory and time, but it does not have the limitations
 of flipping.
    Flipping uses the video-display pages of the graphics adapter to
 store each screen of text. When the alternate screen is required, the
 other page is selected. Flipping is much faster than swapping and does
 not require the 16K buffer. However, it cannot be used with a
 monochrome adapter, or with programs that display graphics or use the
 video pages.


 35. CODEVIEW.DOC Incorrectly States /E Uses Extended Memory

 Product Version(s): 2.20
 Operating System:   MS-DOS
 Flags: ENDUSER | docerr
 Last Modified: 10-NOV-1988    ArticleIdent: Q27763

 The CODEVIEW.DOC file included in Microsoft C Version 5.10 states that
 the /E switch enables use of extended memory for CodeView's symbol
 table.

 This is a documentation error in the CODEVIEW.DOC file. CodeView uses
 expanded, not extended memory.


 36. WINDOWCOMPAT Directs CodeView to Create a Window

 Product Version(s): 2.20 2.30
 Operating System:   OS/2
 Flags: ENDUSER | S_C
 Last Modified: 10-NOV-1989    ArticleIdent: Q49423

 The WINDOWCOMPAT directive in a linker definition file can cause
 strange behavior in non-Presentation Manager (PM) programs being
 debugged under CodeView. WINDOWCOMPAT is one of three application
 types that can be specified after the NAME directive. WINDOWCOMPAT is
 used for OS/2 programs that use VIO, MOU, and KBD calls and can be
 used inside a PM window or as a separate screen group.

 Debugging a non-PM application that was linked with the WINDOWCOMPAT
 option instructs CodeView to create a PM window to run the program. In
 some cases this feature could be desirable, but for most debugging, a
 PM window is only cumbersome. The way to work around this feature is
 to relink without the WINDOWCOMPAT directive.


 37. The CodeView Port Input Command Example Is Unclear

 Product Version(s): 2.20 2.30 | 2.20 2.30
 Operating System:   MS-DOS    | OS/2
 Flags: ENDUSER | H_MASM H_FORTRAN S_Pascal
 Last Modified: 27-OCT-1989    ArticleIdent: Q49537

 The CodeView example for port input command is unclear in the
 following manuals:

 1. Page 150 of Microsoft C 5.10 "CodeView And Utilities, Microsoft
    Editor, Mixed Language Programming Guide"

 2. Page 150 of Microsoft Macro Assembler 5.10 CodeView and Utilities

 3. Page 150 of Microsoft Pascal 4.00 CodeView and Utilities

 4. Page 127 of Microsoft FORTRAN 5.10 CodeView and Utilities

 The example assumes the radix is in hexadecimal. To set the radix to
 hexadecimal, type in the following command:

    >n16

 After setting the radix to hexadecimal, the example works properly.

 If the radix is not in hexadecimal, a "0x" must be present for
 CodeView to recognize the value as a hex format. The following example
 shows how to use the port input command if CodeView is not in
 hexadecimal radix:

    >I 0x2f8


 38. The Difference Among Watch, Watchpoint, and Tracepoint

 Product Version(s): 1.00 1.10 2.00 2.10 2.20 2.30 | 2.20 2.30
 Operating System:   MS-DOS                        | OS/2
 Flags: ENDUSER |
 Last Modified: 14-AUG-1989    ArticleIdent: Q24225

 Question:

 What is the difference between a watch, a watchpoint, and a
 tracepoint?

 Response:

 A "watch" command will monitor an expression or a range of memory
 addresses, and update the watch window each time the expression or any
 location in the range changes. Using a watch never will cause program
 execution to stop; it simply "watches" unconditionally.

 A "watchpoint" monitors an expression (and an expression only) during
 program execution. It will update its value in the watch window
 whenever it changes. However, when the watchpoint expression becomes
 true (nonzero), program execution is stopped.

 A "tracepoint" monitors an expression or a range of memory addresses
 and displays the expression or the range being monitored in the watch
 window. It will stop program execution when the expression or any
 location in the range changes. Please note that writing over the old
 value at a memory location with the same value is not considered a
 change.

 The following example summarizes this information:

 Command     Object To Watch          Conditionally    Condition To
                                      Stops            Stop On
 -------     ---------------          -------------    ------------

 WATCH       expression or            No               (none)
             range of memory

 WATCHPOINT  expression               Yes             expression becomes
                                                      true (nonzero)

 TRACEPOINT  expression or            Yes             expression or
             range of memory                          in range changes
                                                      location

 Note: the "monitoring" described above is done in only window mode. If
 sequential mode is being used, you must use the Watch List command to
 see the values of any of the three types of watch statements.


 39. Tracking Down a Null Pointer Assignment Error

 Product Version(s): 1.00 1.10 2.00 2.10 2.20 2.30 | 2.20 2.30
 Operating System:   MS-DOS                        | OS/2
 Flags: ENDUSER | S_C
 Last Modified: 21-AUG-1989    ArticleIdent: Q24270

 Question:

 I consistently get the error number R6001 "null pointer assignment"
 when I run my program. How can I use CodeView to determine the point
 at which the null pointer assignment is occurring?

 Response:

 Use a tracepoint, which can be set to watch a range of memory up to
 128 bytes. It will halt the execution of the program when any value in
 this range is changed. If you set a tracepoint over the entire range
 of the null segment, the program will halt immediately after the
 instruction that wrote over the null segment.

 The location of the null segment is available in the link maps of
 Microsoft compilers. It starts at DS:0 and is 42H bytes long. The
 Microsoft copyright notice is written there at program startup and
 if this area is written to during the course of the program, the
 error r6001 is generated. The most common cause of this error is
 using a pointer that has not been initialized to point to a memory
 area. Pointers that have not had space allocated for them (using
 malloc for example) or that have not been assigned to a specific
 data element (arrays or structures for example) are considered
 uninitialized.

 An example of using CodeView to determine where an unitialized pointer
 is being used follows:

 g main                  /* go to the beginning of main() */
 n16                     /* switch to hexadecimal (base 16) */
 tpb DS:0 DS:42          /* set a Trace Point of type Byte starting
                               at address DS:0 and extending to DS:42 */

 When any value in the specified range changes, CodeView will stop the
 execution of your program. The previously executed line was probably
 the line that caused the R6001 error.


 40. How to Successfully Debug VioPopUp() Code with CodeView

 Product Version(s): 2.20 2.30 2.35
 Operating System:   OS/2
 Flags: ENDUSER |
 Last Modified: 27-FEB-1990    ArticleIdent: Q58647

 Debugging programs that take advantage of OS/2's VioPopUp() call can
 present a potentially dangerous situation. Due to the nature of the
 VioPopUp() call, any attempts to trace into the VioPopUp call will cause
 your machine to hang. The workaround for this difficulty is to set a
 breakpoint outside of the VioPopUp() call [after the VioEndPopUp()], and
 then press F5 to instruct CodeView to execute to the next breakpoint.

 The VioPopUp() call brings forward a temporary pop-up text screen group
 that can be used to display text information without altering the
 context of the foreground screen. When a VioPopUp() call is executed, the
 current foreground screen group loses the keyboard focus to the pop-up
 screen. Therefore, when you trace into a VioPopUp() call, the pop-up
 text comes forward and CodeView, running in the foreground, loses the
 keyboard focus and cannot execute a trace instruction. At this time,
 CTRL+ESC or ALT+ESC will not change the deadlock situation and the
 only alternative is to reboot.

 To work around this problem, it is essential that you do NOT step into
 a VioPopUp call. Instead, press F5 to execute to the next breakpoint.
 Setting the breakpoint AFTER the VioEndPopUp() call is critical.


 41. Capabilities of Real Mode CodeView and the 386

 Product Version(s): 2.00
 Operating System:   MS-DOS
 Flags: ENDUSER | s_c, h_masm, h_fortran, s_pascal
 Last Modified:  1-DEC-1988    ArticleIdent: Q38205

 The information below discusses the CodeView debugger and its use
 of 80386 hardware capabilities.

 The DOS CodeView does not keep track of any of this information because
 DOS does not use any of these features. Essentially, a 386 running DOS
 is just a very fast PC and CodeView treats it as such.

 The OS/2 CodeView does not have the privilege to track many of the
 OS/2 functionality.

 The following is a list of CodeView behaviors:

 1. CodeView does not keep track of task states.

 2. CodeView does not handle privilege levels.

 3. CodeView Version 2.20 makes limited use of the 386 debug
    registers. Previous versions do not use these registers.

 4. CodeView does not keep track of interrupt gates and trap gates.

 5. CodeView cannot operate in both real and Virtual 86 mode.

 6. CodeView cannot trace to protected mode and back to real mode.

 7. CodeView does not handle traces in protected mode.


 42. Flip/Swap Setting Crucial to Debugging PM Apps with Children

 Product Version(s): 2.30
 Operating System:   OS/2
 Flags: ENDUSER |
 Last Modified: 10-NOV-1989    ArticleIdent: Q50514

 Using protected mode CodeView (CVP) to debug Presentation Manager (PM)
 programs that spawn one or more child processes can be rather
 difficult. CVP works correctly for debugging just the parent PM
 process, but once you begin CodeView with the /O option to specify
 that you also want to debug child processes, you may find that you
 hang the computer quite regularly during your debugging session.

 CodeView itself does not have a problem with PM programs even if they
 do invoke child processes. It is only when you use the /O switch to
 debug the children at the same time that you run into difficulty. This
 is because of problems with CodeView conflicting with the OS/2 kernel
 as you bring a process to the foreground for debugging, while a
 system-dependent process like the PM parent is relegated to the
 background where it can become blocked.

 For example, if the parent gets to a point where it is waiting on a
 message, but it is not in the foreground, there is no way to get the
 focus back to this waiting process and you are essentially hung. The
 parent cannot process the message because it must be in the foreground
 to do so, and CodeView cannot continue until the message is processed,
 so it just waits.

 The key to debugging the parent and child processes of a PM program at
 the same time is the setting of Flip/Swap on the Options menu. Under
 CodeView, Flip/Swap ON forces messaging, Flip/Swap OFF does not.
 Therefore, you must turn Flip/Swap on and off as you go, depending on
 which particular part of the program you are currently debugging. The
 Flip/Swap setting is crucial in determining whether you hang the
 system or not.

 The ability to debug child processes from the parent's CodeView
 session became an available option beginning with CVP Version 2.30. By
 specifying the /O switch on the command line, CVP allows you to trace
 into child processes. (See the CVP 2.30 Note below if you are using
 that particular version of CodeView.)

 As far as actually debugging child processes in PM programs, you must
 proceed in an exacting manner. Unfortunately, the specifics are
 different for every program, so an all-encompassing set of debugging
 procedures cannot be devised. Nevertheless, the following general
 guidelines can be used for debugging most PM applications with their
 accompanying child processes:

  1. It is only with the /O option that any of this becomes critical.

  2. You need to debug in a full screen and not a PM window.

  3. Remember, Flip/Swap ON forces messaging, Flip/Swap OFF does not.
     Therefore, while you begin debugging in the parent program, you
     should have Flip/Swap ON, since you need messaging whenever you
     are doing any of the window initialization routines.

  4. Set a breakpoint in the parent somewhere after the window
     initialization code, but before the call to start the child
     process. It varies, but it usually works to put the breakpoint at
     the "while get message - dispatch message" loop or in the
     ClientWndProc procedure at the main switch statement.

  5. You must make sure that the breakpoint is placed in a position
     where you will stop at it before the prompt appears to ask you if
     you want to debug the child, but after ALL the window
     initialization has been completed. You will also probably need to
     set another breakpoint at the point where the parent program is
     going to begin executing again after you have finished working
     with the child.

  6. Do a GO, and when the breakpoint is reached, turn Flip/Swap OFF.
     Make sure that the prompt to debug the child is not already
     visible or you will lock up.

  7. Do a GO (or some traces) and you should get the prompt to debug
     the child. Answer "Y" and you should be able to debug the child
     process at this point.

  8. Use the Process command (the "|") to gain access to the child.
     Never use CTRL+ESC or ALT+ESC to switch to the other processes
     because these will almost assuredly cause you to hang.

  9. Go ahead and set breakpoints, watches, etc. in the child and do
     your debugging.

 10. After the child process is completed, use the Quit command to exit
     the child process's CodeView screen or use the Process command to
     reselect the parent process.

 11. Once you have returned to the parent process, and before you do a
     Restart (or load), or before you do ANY other window
     initialization, you MUST turn Flip/Swap ON again.

 12. Remember to always be aware of where you are in the program and
     what the current state of Flip/Swap is, since turning Flip/Swap on
     or off at the wrong time will almost always cause you to hang.

 Again, this is only the general outline of steps to follow and each
 application requires different specific steps. Don't be too surprised
 if you still run into occasional lock-ups.

 CVP 2.30 Note: When using the /O switch with CVP Version 2.30, there
 is a bug that may also cause you to hang. The problem involves using
 /O on the command line and then saying "No" when asked if you want to
 debug the child. So, with this version of CodeView, you should always
 answer "Yes" when asked if you wish to debug the child.

 For more information on this problem, use the following query:

    CodeView 2.30 hangs debugging child processes


 43. Can't Debug .COM Files in Source Mode

 Product Version(s): 2.00 2.10 2.20 2.30
 Operating System:   MS-DOS
 Flags: ENDUSER |
 Last Modified:  9-AUG-1989    ArticleIdent: Q38288

 The .COM format files created with the Microsoft Macro Assembler
 cannot contain symbolic and source-line information for the CodeView
 debugger. You can only debug these files in assembly mode.


 44. CODEVIEW.DOC File Error: Mouse Works with the /2 Option

 Product Version(s): 2.20
 Operating System:   MS-DOS
 Flags: ENDUSER |
 Last Modified:  8-NOV-1988    ArticleIdent: Q27764

 Question:
    The CODEVIEW.DOC file included with Microsoft C Version 5.10 states
 that using the /2 switch disables mouse support on the debugging
 display. Is this true?

 Response:
    This is an error in the CODEVIEW.DOC file.
    CodeView does support the mouse when using the /2 switch. In fact,
 if you are debugging a program which itself uses the mouse, using the
 /2 switch will allow you to use the mouse on CodeView's debugging
 screen as well as your application's output screen.


 45. "?CANNOT DISPLAY" After Column 135 in Command Window

 Product Version(s): 3.00 3.11 | 3.00 3.11 3.50
 Operating System:   MS-DOS    | OS/2
 Flags: ENDUSER |
 Last Modified:  6-FEB-1991    ArticleIdent: Q68696

 The code below demonstrates a limitation of the CodeView debugger.
 When the command "?y" is executed in the COMMAND window, the structure
 "y" is displayed. However, CodeView displays the structure only to
 column 135 and then prints "?CANNOT DISPLAY," ignoring the rest of the
 elements in the structure. The output appears as follows:

    --------------------------command----------------------------
   |>?y                                                          |
   |{this_field_01=0x0000, ... ,this_field_07=?CANNOT DISPLAY    |
   |                        ^                 ^                  |
   |                        |                 |                  |
   |                  Fields 2-6 displayed    Column 135         |
   |                                                             |
    -------------------------------------------------------------

                       CodeView Command Window

 To view all elements of a structure, you should use the QUICK WATCH
 function. In the example below, the contents of the whole structure
 can be seen by typing "??y". A dialog box will appear on the screen
 showing the contents of the structure. By scrolling down in the dialog
 box, the contents of every element of the structure can be seen. The
 structure contents are displayed as follows:

           --------------- Quick Watch -----------------
          |                                             |
          |-y                                           |
          |   this_field_01=0                           |
          |   this_field_02=0                           |
          |   this_field_03=0                           |
          |   this_field_04=0                           |
          |   this_field_05=0                           |
          |   this_field_06=0                           |
          |   this_field_07=0                           |
          |   this_field_08=0                           |
          |   this_field_09=0                           |
          |   this_field_10=0                           |
          |   this_field_11=0                           |
          |   this_field_12=0                           |
          |   this_field_13=0                           |
          |   this_field_14=0                           |
          |   this_field_15=0                           |
           ---------------------------------------------

                       Quick Watch of Variable

 Sample Code
 -----------

 struct x {
    int this_field_01;
    int this_field_02;
    int this_field_03;
    int this_field_04;
    int this_field_05;
    int this_field_06;
    int this_field_07;
    int this_field_08;
    int this_field_09;
    int this_field_10;
    int this_field_11;
    int this_field_12;
    int this_field_14;
    int this_field_15;
    int this_field_16;
    int this_field_17;
    int this_field_18;
    int this_field_19;
    int this_field_20;
 };

 main()
 {
     struct x y;
 }


 46. Debugging PM Apps with Two Monitors Does Not Require /2 Switch

 Product Version(s): 2.20 2.30
 Operating System:   OS/2
 Flags: ENDUSER |
 Last Modified: 17-JUL-1990    ArticleIdent: Q49824

 Problem:

 I am using CodeView to debug my Presentation Manager (PM) program and
 I am using the /2 switch to redirect the CodeView screen to a
 monochrome monitor. When I press F5 to start my program, a protection
 violation occurs, but it works correctly when I run it from the OS/2
 command line.

 Response:

 The /2 switch for CodeView is not supported for Presentation Manager
 application debugging. However, you may redirect the CodeView screen to
 a monochrome monitor if you do the following:

 1. Start a full-screen command prompt.

 2. At the prompt, type the following command (this puts the prompt on
    the monochrome monitor):

       mode mono

    Note: You must be in a 25-line screen mode before you attempt the
    mode mono. If you are in a 43- or 50-line mode, the display is
    corrupted.

 3. At the prompt, type the following command, where "appname" is your
    application's name:

       cvp appname

 4. After you are finished debugging, you can return the prompt to your
    primary display by typing the following command:

       mode co80


 47. How CodeView Interprets Values (octal, decimal, hexadecimal)

 Product Version(s): 1.x 2.00 2.10 2.20 | 2.20
 Operating System:   MS-DOS             | OS/2
 Flags: ENDUSER |
 Last Modified: 23-NOV-1988    ArticleIdent: Q38299

 Problem:

 When trying to watch a portion of memory, I have a problem with
 the following command at the dialog prompt:

    WW DS:0050 L 4.

 I thought this should have created a watch on the four words starting
 at offset 0x50. It actually set the watch starting at 0x28, CodeView
 interpreted the number as if it had been in base 8. Using the N
 command to change the radix doesn't make any difference.

 Response:

 In this case, the 0's before the offset cause CodeView to evaluate the
 expression in octal. CodeView provides three different prefixes for
 numbers to use an explicit base: 0 signifies octal, 0n signifies
 decimal, and 0x signifies hexadecimal. The current radix setting will
 have no bearing on numbers entered with these prefixes; however, it
 will affect those without prefixes.

 The lines below have different meanings when setting watches.
 The left column is the command, while the right column is an example
 of the display produced in the watch window. Radix is assumed to be 10.

 The following is an example:

 1. ww 50               50    :  0067:0032  6942

 2. ww 050              050   :  0067:0028  6328

 3. ww 0n50             0n50  :  0067:0032  6942

 4. ww 0x50             0x50  :  0067:0050  6163

 The first command sets the watch at the address specified using the
 current radix. This address will change when you use the N command to
 change the radix; the 50 on the left of the watch remains the same;
 however, the offset in the address will change to watch 50 in the new
 base. This address will always be displayed in hexadecimal, but 50
 will be evaluated differently.

 Examples 2 through 4 show watches being set in octal, decimal, and
 hexadecimal modes, respectively. These addresses will never change
 with a change of radix.

 Notice that watches 1 and 3 match. This is because by default CodeView
 is in base 10, so 50 and 0n50 evaluate to the same thing. Using N 8 will
 cause watches 1 and 2 to match, and N 16 will match 1 and 4.


 48. Interrupt Conflict with Greenleaf Libraries

 Product Version(s): 2.20    | 2.20
 Operating System:   MS-DOS  | OS/2
 Flags: ENDUSER | CV CVP
 Last Modified: 23-NOV-1988    ArticleIdent: Q38314

 The Greenleaf Comm Library, a collection of asynchronous
 communications functions for use with the C compiler, causes severe
 complications with CodeView (e.g. crashes, lockups) due to interrupt
 conflicts. Greenleaf Software is aware of this difficulty and will
 advise customers of the incompatibility.

 No workarounds are available. Greenleaf Software is located in
 Carrollton, TX, and can be reached at [phone].


 49. CodeView Gives "Illegal Instruction" on Clone 386

 Product Version(s): 2.20
 Operating System:   MS-DOS
 Flags: ENDUSER | CV
 Last Modified: 23-NOV-1988    ArticleIdent: Q38317

 Some clones that are not entirely IBM-compatible under CodeView may
 give an "illegal instruction" message upon executing Go (F5), and then
 hang, requiring a warm boot. If the instruction being called illegal
 is FINIT or FNINIT, the particular ROM BIOS probably has a built-in
 387 emulator. Either turn off the emulator, or set the environment
 variable SET NO87=(some string).



 50. Thirty-Two-Bit Register Not Visible under OS/2

 Product Version(s): 2.20
 Operating System:   OS/2
 Flags: ENDUSER |
 Last Modified: 23-NOV-1988    ArticleIdent: Q38375

 Thirty-two-bit registers are not viewable (using F2) under CVP even if
 you have an 80386-based machine. This is not a problem with CodeView;
 it is a limitation.

 Real mode CodeView (CV) DOES support viewing 32-bit registers. This
 is because of the unprotected and generally more flexible nature of
 DOS. Using the full 32-bits of the 80386 under OS/2 is considered
 hazard-prone and is not supported by CVP.



 51. CodeView Instruction Pointer Miscounts Very Long Lines

 Product Version(s): 2.20
 Operating System:   MS-DOS
 Flags: ENDUSER | buglist2.20
 Last Modified:  1-DEC-1988    ArticleIdent: Q38382

 CodeView may display the "current instruction" highlight on the wrong
 line if the source file contains lines that are very long.

 The compiler counts the long lines as one line, but CodeView counts
 the very long lines as two lines. This makes the line number
 calculations incorrect and causes the "current line" highlight to
 appear on the wrong line. This problem does not occur if the source
 lines are less than 251 characters in length.

 Because the Microsoft Editor breaks lines that are longer than 250
 characters, this problem does not occur if you create and maintain
 your source files with the Microsoft Editor.

 Microsoft has confirmed this to be a problem in CodeView Version 2.20.
 We are researching this problem and will post new information as it
 becomes available.


 52. CodeView Requires PUBLIC to Trace MASM Program in Source Mode

 Product Version(s): 2.20
 Operating System:   MS-DOS
 Flags: ENDUSER | H_MASM
 Last Modified:  3-MAY-1989    ArticleIdent: Q44006

 A MASM program that runs perfectly from a DOS prompt refuses to trace
 in source mode inside of CodeView. The program single-steps in
 assembly mode, but an attempt to trace into the code in source mode
 results in the program terminating upon reaching the first data
 declaration.

 In addition, the program does not come up in source mode when CodeView
 is started, but can be changed into source mode with "View" "Source".

 This problem happens when the code and data segments are not declared
 as "PUBLIC". The code is valid and executes perfectly inside of
 CodeView or from a DOS prompt. However, CodeView cannot follow the
 logic at a source level.

 A program constructed in the following manner exhibits the symptoms
 described above:

 TITLE    myprog

 StackSeg Segment STACK
 .
 .
 .
 DataSeg  Segment DATA
 .
 .
 .
 CodeSeg  Segment CODE
 .
 .
 .
 END      myprog

 However, if the following minor changes are made to the program, and
 the segments are declared as "PUBLIC", CodeView can trace through the
 program in source mode:

 TITLE    myprog

 StackSeg Segment STACK
 .
 .
 .
 DataSeg  Segment WORD PUBLIC 'DATA'
 .
 .
 .
 CodeSeg  Segment WORD PUBLIC 'CODE'
 .
 .
 .
 END      myprog


 53. Cannot Use /2 Switch on IBM PS/2 in CodeView

 Product Version(s): 2.10 2.20  2.30 | 2.20 2.30
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER | SR# G881031-5515
 Last Modified:  9-AUG-1989    ArticleIdent: Q38865

 To use the /2 switch with CodeView, your computer must be equipped
 with a monochrome display (MDA) and a color display (CGA/EGA/VGA). The
 IBM PS/2 computers aren't currently configurable this way because they
 come with built-in VGAs or MDAs, but not both.

 If a hardware vendor starts selling MDAs that can be added to systems
 with built-in VGAs, this problem will be solved. An MDA card is
 needed that plugs into the PS/2 and works correctly in conjunction
 with the built-in VGA so that PS/2 owners can have a dual-monitor
 system.

 Currently, there is no solution to this debugging restriction other
 than using CodeView through the com port in sequential mode (/T) with
 a debugging terminal.


 54. CodeView Does Not Support Debugging Spawned Process

 Product Version(s): 2.20 2.30
 Operating System:   MS-DOS
 Flags: ENDUSER |
 Last Modified: 26-FEB-1990    ArticleIdent: Q58653

 The following are several reasons why CodeView doesn't provide
 debugging support for spawned processes under DOS:

 1. DOS is not a multitasking operating system. CodeView cannot start
    another thread/process to watch the execution of the spawned
    process.

 2. DOS does not provide debugging support for the DOS BIOS calls (int
    21h). Since all spawn() and exec() functions under DOS have to go
    through the BIOS to run, CodeView cannot follow the spawned
    program.

 3. DOS only recognizes 640K of memory; therefore, there is
    insufficient memory to debug a large program, since both the parent
    and child processes have to reside in memory at the same time.


 55. Display Settings for Compaq Gas Plasma Screen

 Product Version(s): 1.00 2.10 2.20 | 2.20
 Operating System:   MS-DOS         | OS/2
 Flags: ENDUSER |
 Last Modified:  6-DEC-1988    ArticleIdent: Q38866

 The default monitor settings for CodeView do not work properly with
 the Compaq gas plasma display adapter. Invoking CodeView with the /b
 switch corrects the problem.


 56. CodeView: Watchpoints and Tracepoints with Enumerated Types

 Product Version(s): 2.20   | 2.20
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER | s_c
 Last Modified: 28-MAR-1989    ArticleIdent: Q42601

 CodeView will not display the members of an enumerated type as they
 are declared in a C program. Only the integer representations of these
 types of variables can be shown. The following is an example:

 /*  Example enumerated type.
  */

 enum e_type
 {
     var1,
     var2,
     var3
 };

 enum e_type foo = var1;

 CodeView will not display "var1", "var2", or "var3" when watching a
 variable of type e_type, such as foo. CodeView will instead show the
 integer values of the variable: 0, 1, and 2, respectively. In order to
 watch the variable foo, you must explicitly display its value as an
 integer. The following command will add the proper watch:

     w? foo,d

 To set a watchpoint or a tracepoint on the same variable, further type
 casts must be made. These lines will produce watchpoints and
 tracepoints on foo, as follows:

     wp? *(int *)&foo == 1
     tp? *(int *)&foo

 Trying to set a watchpoint without the proper type cast will result in
 the following error:

     Operand types incorrect for this operation

 Setting a tracepoint on foo without this type cast will set the
 tracepoint but will only show "?CANNOT DISPLAY" in the watch window.
 Going through the right steps will display the current integer value
 of the variable, as it should.


 57. "?CANNOT DISPLAY" Error Not Documented in CodeView Documents

 Product Version(s): 2.00 2.10 2.20 2.30 | 2.20 2.30
 Operating System:   MS-DOS              | OS/2
 Flags: ENDUSER | TAR64267 docerr
 Last Modified: 21-AUG-1989    ArticleIdent: Q24877

 Problem:

 When trying to evaluate (?), a function that returns void, I get the
 error "?CANNOT DISPLAY". I cannot find this error message in the
 "Microsoft CodeView Utilities and Editor" manual.

 Response:

 This error message is not contained in the CodeView manual.

 The "?CANNOT DISPLAY" error message will be displayed in cases where
 the expression evaluator cannot return a value, such as a function
 returning void.


 58. Watch Bytes (wb) Command Can Be Used to Watch a Buffer in HEX

 Product Version(s): 2.20 2.30 | 2.20 2.30
 Operating System:   MS-DOS    | OS/2
 Flags: ENDUSER |
 Last Modified: 17-JUL-1990    ArticleIdent: Q50224

 Question:

 Is there a way to keep tabs on the contents of a buffer via a watch
 command? We want to observe the contents of a 20-character buffer in
 HEX. The buffer is not necessarily null terminated.

 Response:

 The way to watch a buffer in CodeView in hexadecimal with the Watch
 command is to use Watch Bytes (wb) as follows:

    >wb *buffer L 10  ; this will watch the first 10 bytes of
                        buffer in HEX

 For the given example, you should follow the previous command with the
 following:

    >wb *(buffer + 10) L 10  ; this will watch the next 10
                               bytes in HEX.

 Please note that both the length specifier as well as the number 10
 used to offset the pointer in the second command are taken in the
 current radix. The example above assumes a radix of 10. You can
 explicitly specify the base of the number in hex as follows:

    >wb *buffer L 0x0a
    >wb *(buffer + 0x0a) L 0x0a

 For more information on the wb command in CodeView, see the "Microsoft
 CodeView and Utilities, Microsoft Editor, Mixed-Language Programming
 Guide" manual.


 59. Specifying Both /T and /W Disables Mouse

 Product Version(s): 2.20    | 2.20
 Operating System:   MS-DOS  | OS/2
 Flags: ENDUSER |
 Last Modified:  6-DEC-1988    ArticleIdent: Q38867

 If you invoke CodeView with the following, the use of your mouse is
 disabled:

    CV /T /W program

 Don't specify the /T switch. Using /T with /W produces mutually
 exclusive modes of operation.


 60. Illegal Instruction in CodeView

 Product Version(s): 1.x 2.00 2.10 2.20 | 2.20
 Operating System:   MS-DOS             | OS/2
 Flags: ENDUSER | S_C h_fortran S_PASCAL
 Last Modified:  6-DEC-1988    ArticleIdent: Q38868

 Question:

 When I compile and link my C program and try to run it under CodeView,
 execution stops on the open curly brace of main. The view then goes to
 assembly, and the message "Illegal instruction" appears in the dialog
 window. Is there something wrong with the startup code?

 Response:

 This error can be produced when the main module of a program is
 compiled for one memory model and is then explicitly linked with a
 library for a different model. When the startup code is linked to the
 entry point of the program, different size instructions are used for
 the different memory models. If the program expects one size and the
 linker links in a different size, the startup instructions will be
 misinterpreted and result in this error.


 61. Entering Double Words at a Prompt Prevents Reloading Program

 Product Version(s): 2.20 2.30
 Operating System:   MS-DOS
 Flags: ENDUSER| | S_C S_PASCAL H_FORTRAN H_MASM buglist2.30
 Last Modified: 30-NOV-1989    ArticleIdent: Q50410

 When using the Enter Double word (ED) command within the CodeView
 symbolic debugger and allowing the debugger to prompt, you will
 prevent the debugger from reloading your executable (using the L
 command). This problem occurs only when you allow the debugger to
 prompt you for the double word and you enter a double word.

 This problem can manifest itself in several ways, depending on the
 version and on other unpredictable circumstances. Symptoms of the
 problem include the following:

 1. Giving the message "No such file/directory"

 2. Giving the message "Arg list too long"

 3. Generating an internal debugger error 7

 Valid workarounds consist of entering words (not double words) at the
 prompt, or entering double words on the command line (without being
 prompted).

 Microsoft has confirmed this to be a problem with CodeView Version
 2.30. We are researching this problem and will post new information
 here as it becomes available.


 62. CodeView 2.20 Does Not Allow Routine.Variable Specification

 Product Version(s): 2.20   | 2.20
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER | S_PASCAL S_C H_FORTRAN H_MASM DOCERR
 Last Modified: 10-NOV-1989    ArticleIdent: Q50698

 On Pages 91-92 of the "CodeView and Utilities" manual that accompanied
 C 5.10 and Pascal 4.00 for CodeView Version 2.20, the period is
 documented as being useful as a specifier of local variables in parent
 functions. The syntax is stated to be as follows:

    routine_name.variable_name

 However, this feature was not implemented in Version 2.20 of CodeView.
 It was implemented in CodeView Version 2.30 (which accompanied FORTRAN
 5.00).

 This feature is useful in all languages, but particularly helpful in
 Pascal because of the "nested-scoping" (the ability of a function to
 access variables from the routine that called it) that occurs in
 Pascal.

 To use this feature in CodeView 2.30, you must be in either the
 routine where the variable is defined or in a routine that is a child
 (or grandchild, etc.) of that routine. After entering the proper
 routine, any variable name can be referenced with a routine and
 variable name (see example below).

 program first (input, output) ;
 var a: integer ;            { Available throughout the program }

     procedure second ;
     var b: integer ;        { Available in second and third }

         procedure third ;
         var c: integer ;    { Available in third }

         begin
             a := 3 ;
             b := 3 ;
             c := 3 ;
         end ;

     begin
         a := 2 ;
         b := 2 ;
         third ;
     end ;

 begin
     a := 1 ;                { Cannot watch second/third variables }
     second ;
 end.

 When in procedure third, you can place a watch on the variables in
 procedure second in the following manner:

 w? second.b

 This will display the variable in procedure second. This variable
 cannot be displayed from the main program, however.


 63. Using a Debugging Terminal with CodeView

 Product Version(s): 2.20
 Operating System:   MS-DOS
 Flags: ENDUSER |
 Last Modified: 12-JAN-1989    ArticleIdent: Q39179

 It is possible to use either a dumb terminal or another machine (PC or
 Macintosh, running a communications package at 9600 baud) as a
 debugging terminal for CodeView. To take advantage of this option, do
 the following:

 1. Connect the second terminal to the com port (COM1 or COM2).

 2. Initialize the communications package to set up the
    second machine as a dumb terminal. Set the baud rate at
    9600.

 3. Start CodeView in either window or sequential mode.

 4. Redirect either the output ( >COM1 ) or both input and output
    ( =COM1 ) to the second terminal.

    If you redirect just the output to the second terminal, you will
    see the debugging output on the second terminal, and program output
    on the primary terminal. If you redirect input and output, you will
    also be able input program information (responses to prompts,
    input from the keyboard, etc.) on the primary terminal, and input
    CodeView information on the secondary terminal.

 5. Set your options and run the program.


 64. Pascal Version of CodeView Version 2.20

 Product Version(s): 2.20   | 2.20
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER | S_PasCal
 Last Modified: 14-AUG-1989    ArticleIdent: Q39181

 CodeView Version 2.20 is different for Pascal then the rest of the
 languages. The Pascal version of CodeView 2.20 is the only version
 that has the Pascal Expression Evaluator. The way you can determine
 whether you are running the Pascal version is that Pascal will appear
 under the Languages menu.

 If you have multiple Microsoft Languages, you do not have to keep
 multiple versions of CodeView on your system. CodeView Version 2.20 is
 compatible with all of our languages. However, there is one exception
 -- if you are using Microsoft Pascal, make sure you use the version
 that came with Pascal. It is the only version that has the Pascal
 Expression Evaluator and all of the other language evaluators.

 To check if the version you have is the Pascal version, invoke
 CodeView and pull down the Languages menu. If it lists Pascal in the
 menu, you are using the Pascal version that is compatible with all of
 the Microsoft languages.


 65. "." on the LIBPATH Eases DLL Debugging, But Not for CVP 2.20

 Product Version(s): 2.20 2.30
 Operating System:   OS/2
 Flags: ENDUSER |
 Last Modified: 10-NOV-1989    ArticleIdent: Q50711

 When debugging OS/2 DLLs with protected mode CodeView (CVP), you must
 specify each DLL on the command line with an /L switch, and the DLL
 must be in the current directory as well as in a directory on the
 LIBPATH as set in CONFIG.SYS.

 For ease of debugging, if you put a period ("."), which means the
 current directory, as one of the directories on your LIBPATH, then a
 DLL in the current directory will also be on the LIBPATH and you won't
 need to have two copies of a DLL present on disk for debugging.

 This method only works for versions of CVP beginning with 2.30. CVP
 Version 2.20 will not recognize DLLs in a "." LIBPATH directory.

 If a copy of the DLL called by the program being debugged is not in
 the current working directory, you will not be able to trace into the
 DLL. If a copy of the DLL is not in a LIBPATH directory, CodeView will
 not be able to find the DLL. In this case, instead of coming up in the
 usual "debugging mode," CodeView immediately exits and returns to the
 command prompt after several seconds.

 Many DLL debugging problems arise from the fact that the copy of a DLL
 that is on the LIBPATH may be inadvertently out of date compared to
 the version in the current directory that is being used for debugging.
 By putting a period on the LIBPATH, the current directory becomes a
 LIBPATH directory and only one copy of the DLL needs to exist, thus
 eliminating any DLL update inconsistencies.


 66. CodeView Trace Skips Statement Following Switch Statement

 Product Version(s): 2.20 2.30 | 2.20 2.30
 Operating System:   MS-DOS    | OS/2
 Flags: ENDUSER | buglist2.20 buglist2.30
 Last Modified:  7-MAR-1990    ArticleIdent: Q59315

 CodeView incorrectly maps assembly level instructions to source code
 in the first statement following a switch statement with seven or more
 cases.

 As shown in the code sample below, the statement following the switch
 is executed correctly, but CodeView steps over the statement while
 tracing in source mode. In mixed source and assembly mode, the
 statement following the switch may be traced into.

 Sample Code
 -----------

 # include<stdio.h>

 void main(void)
 {

    short tag, marker;

    marker = 0;
    tag = 5;

    switch(tag){
       case 1:
          break;
       case 2:
          break;
       case 3:
          break;
       case 4:
          break;
       case 5:
          break;
       case 6:
          break;
       case 7:
          break;
       default:
          break;
    }

       marker = 2;

 }


 67. Using CodeView to Create Disassembled Program Listings

 Product Version(s): 2.20 2.30 | 2.20 2.30
 Operating System:   MS-DOS    | OS/2
 Flags: ENDUSER |
 Last Modified: 12-APR-1990    ArticleIdent: Q51323

 The following steps can be used to create an assembly listing of a
 program with CodeView:

 1. Begin CodeView in sequential mode by using the /T command-line
    switch.

 2. Specify a listing file to redirect CodeView output to by typing the
    redirection operator ">" followed by a filename at the dialog
    prompt. You may redirect the output directly to a printer by
    specifying the printer after the ">" (e.g., >PRN).

    (Note: From this point on, commands will not be viewable.)

 3. Use the Unassemble command "U" to disassemble the code and send a
    listing of the program to the output file. If you do not specify
    the starting address and the range to unassemble, CodeView will
    unassemble the next eight lines of code. See the CodeView
    documentation for more information on the Unassemble command.

 You can use this method on any files, whether or not they contain
 CodeView information. In this regard, you can create assembly listings
 of programs that were not created with a Microsoft compiler. Please
 also note that you cannot create assembly listings of instructions
 other than 8086 instructions.


 68. Debugging DLLs with Codeview

 Product Version(s): 2.20 2.30
 Operating System:   OS/2
 Flags: ENDUSER |
 Last Modified: 18-DEC-1989    ArticleIdent: Q51764

 To debug most DLLs (Dynamic Link Libraries) in CodeView, CVP
 (protected mode CodeView) Version 2.20 or later is required. For DLLs
 loaded via DosLoadModule(), CVP Version 2.30 or later is required.

 Invoke CodeView with the /L switch as follows:

    cvp /L dll1name /L dll2name main.exe

 Make sure that each DLL you want to trace into is specified by the /L
 option.

 CodeView cannot debug DLLs that have either IOPL or EXECUTEONLY
 specified with the CODE directive in the associated definition (.DEF)
 file. For DLLs that require these controls, the Kernel Debugger
 supplied with the SDK is required.

 Note: With CVP 2.30, pathnames cannot be specified for DLLs;
 therefore, the DLL must reside in the current directory. For more
 information, query on the following:

     CODEVIEW DLL LIBPATH


 69. Debugging Bound Applications

 Product Version(s): 1.00 1.10 2.00 2.10 2.20 | 1.11 2.02.02 2.20 2.30
 Operating System:   MS-DOS                   | OS/2
 Flags: ENDUSER | TAR63888
 Last Modified: 14-AUG-1989    ArticleIdent: Q25219

 CodeView does not support the debugging of bound applications in real
 mode. However, CVP in protected mode will allow you to debug such
 applications.


 70. No Symbolic Information Generated for Pascal Units

 Product Version(s): 2.20   | 2.20
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER | s_pascal
 Last Modified: 12-JAN-1989    ArticleIdent: Q39811

 The Microsoft Pascal Compiler Version 4.00 generates no symbolic
 debugging information for Pascal Units. As a result, when tracing
 through a Pascal program Unit, attempting to access any local
 variables by using trace/watchpoints, dumps, examines, etc. yields a
 "symbol unknown" error.

 The only workaround is to transform the program Units into Modules.


 71. "Internal Debugger Error: 0" When Watching Structure Members

 Product Version(s): 2.20 2.30 | 2.20 2.30
 Operating System:   MS-DOS    | OS/2
 Flags: ENDUSER | buglist2.30 cv
 Last Modified: 29-DEC-1989    ArticleIdent: Q51834

 When watching a member of a structure using the "w?" or "?" commands,
 it is possible to get the message "internal debugger error: 0". When
 this happens, the only way to view the contents of the member is to
 use the "D" or "??" commands.

 Code Example
 ------------

 typedef struct {
    char *(*instruction)[];
    } *structype;

 structype mac;

 void main (void)
 {
 }

 If you set a watch on an element of the structure variable in the
 above program such as "w? mac->instruction[0]" (without the quotation
 marks) you'll get the message "internal debugger error: 0." Use the
 dump command "D" or the special "??" structure viewing command to look
 at the contents of the member.

 Microsoft has confirmed this to be a problem in CodeView Version 2.30.
 We are researching this problem and will post new information here as
 it becomes available.


 72. Incorrect Error Generated for Very Small COM Files

 Product Version(s): 2.00 2.10 2.20 2.30
 Operating System:   MS-DOS
 Flags: ENDUSER | TAR65183 buglist2.00
 Last Modified: 21-AUG-1989    ArticleIdent: Q25365

 Problem:

 If my COM file is less than 8 bytes long and I try to load it into
 CodeView, I get the error message "Invalid executable file format -
 please relink."

 Response:

 This problem occurs only on COM files less than 8 bytes in length.

 Microsoft has confirmed this to be a problem with CodeView Version
 2.00. We are researching this problem and will post new information as
 it becomes available.


 73. Dual-Monitor Setup Requires 8-Bit Data Paths for Both Monitors

 Product Version(s): 1.00 2.00 2.10 2.20 2.30 | 2.20 2.30
 Operating System:   MS-DOS                   | OS/2
 Flags: ENDUSER | s_c s_pascal h_fortran h_masm b_basiccom
 Last Modified: 21-MAR-1990    ArticleIdent: Q51870

 When writing to a system that has a dual-monitor setup, you must make
 sure that both the monochrome monitor and the color monitor are using
 an 8-bit data path. In any dual-monitor write scheme, both display
 cards must be configured to write to a common data path (either both
 8-bit or both 16-bit mode). Today's monochrome adapters use 8-bit
 paths exclusively.

 Most display cards that use a 16-bit mode can autosense whether they
 are being written to in a dual-monitor mode, but some cards, such as
 the ATI VGA Wonder card, do not sense for this situation; therefore,
 you must set the card to an 8-bit path manually.

 If you are using dual monitors and you experience strange behavior
 such as garbage or blinking characters on the monochrome screen, make
 sure that your 16-bit video card is running in 8-bit mode.

 The most common use for a dual-monitor setup is for debugging graphics
 applications in CodeView.


 74. Retrieving Previously Entered Commands

 Product Version(s): 1.00 1.10 2.00 2.10 2.20 2.30 | 2.20 2.30
 Operating System:   MS-DOS                        | OS/2
 Flags: ENDUSER | TAR65921
 Last Modified: 14-AUG-1989    ArticleIdent: Q25539

 Question:

 Is there a method to retrieve commands after typing them in once? For
 instance, if I type "d some_data_area l 40", I would like to retrieve
 the command without having to retype it. A suggested method would be
 to allow the user to scroll on the command, then press a key to make
 the command active.

 Response:

 The only way to retrieve commands is to highlight them with the mouse
 and press the INS key. This method inserts the command into the
 command line. We are considering making an easier way to scroll
 through the commands and may implement it in a future version.


 75. system() Call May Cause CodeView to Terminate Process

 Product Version(s): 2.20 2.30
 Operating System:   MS-DOS
 Flags: ENDUSER | buglist2.20 buglist2.30
 Last Modified: 22-JAN-1990    ArticleIdent: Q57867

 Using real-mode CodeView to trace over the system() run-time function
 will cause the debugger to terminate the parent process upon return
 from the child process in certain situations where the child does a
 multiple directory-level traversal.

 Instead of tracing, use the "Go" Command (F5) to run past the system()
 call. This procedure allows the program to run to completion.

 The program below demonstrates this problem, but it requires that
 TREE.COM be somewhere in the path. Compile the code with the /Zi and
 /Od options and use CodeView to trace into the program, using F8.
 After TREE.COM executes, CodeView will display the "Program terminated
 normally" message, preventing the last printf() from being executed.

 Microsoft has confirmed this to be a problem with CodeView Versions
 2.20 and 2.30. We are researching this problem and will post new
 information here as it becomes available.

 Code Example
 ------------

 #include <process.h>
 #include <stdio.h>

 void main (void)
 {
         printf ("This is the beginning of the program\n");
         printf ("Calling TREE.COM\n");
         system ("tree");

         /* This line will never be executed */
         printf ("Back from spawn\n");
 }


 76. CodeView Versions 2.10 to 2.30 Use Four Extra File Handles

 Product Version(s): 2.30 2.20 2.10 2.00
 Operating System:   MS-DOS
 Flags: ENDUSER |
 Last Modified: 19-JAN-1990    ArticleIdent: Q25950

 Problem:

 CodeView Versions 2.00 to 2.30 seem to be using four additional file
 handles. The following program attempts to open 20 files, reporting
 its success or failure after each attempt:

     #include <stdio.h>
     #include <string.h>
     #include <stdlib.h>

     main()
     {
             FILE *streams[20];
             int i;
             char buffer[12];
             char *p;

             for (i = 0; i < 20; i++) {
                     p = itoa(i, buffer, 10);
                     p = strcat(buffer, ".dat");
                     streams[i] = fopen(buffer, "w+");
                     printf("streams[%d] = %d\n", i, streams[i]);
             }
     }

 Running outside of CodeView, the call to fopen() fails after 15
 streams have been opened. Running in CodeView Versions 1.x, the call
 fails after 15 files have been opened. However, in CodeView Versions
 2.00 to 2.30, it fails after 11 file handles have been opened.

 Response:

 CodeView Versions 2.00 to 2.30 require four file handles for their own
 use. Remember that MS-DOS itself has five preopened file handles. If
 you want to open more than 15 files, follow the steps specified in the
 C Version 5.10 README.DOC to modify the C start-up code to allow
 opening more than 20 files.


 77. Copying Text from Display Window to Dialog Window

 Product Version(s): 2.20   | 2.20
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified: 12-JAN-1989    ArticleIdent: Q40110

 Question:

 Is it possible to copy text from the display window down to the dialog
 window to use at the command line in Microsoft CodeView?

 Response:

 Yes, if you have a mouse. You can highlight with the mouse the section
 of text you would like to copy and press the INSERT key. The
 highlighted text will appear in the dialog box.

 This is very useful if you have very long variable names that you want
 to watch and don't want to retype the long variable name each time.
 Simply type a w? on the command line, then highlight the variable name
 with the mouse and press the INSERT key.

 Strange behavior can occur if you use the SHIFT key in combination
 with the INSERT key. For example, if you use the INSERT key on the
 extended keyboard along with the SHIFT key, it works the same as using
 INSERT alone. However, if you turn NUM LOCK off on the keypad so you
 can you the INSERT key with the SHIFT key, you will get a zero instead
 of the string of text. To get the string of text, you have to turn NUM
 LOCK on. This seems backwards because with NUM LOCK on you would
 expect to get a zero, but you get the text.

 The workaround is not to use the SHIFT key in conjunction with the
 INSERT key. INSERT alone works correctly.


 78. OS2PATCH for CVP Not Needed in OS/2 Version 1.10.

 Product Version(s): 2.20 2.30
 Operating System:   OS/2
 Flags: ENDUSER |
 Last Modified: 14-NOV-1988    ArticleIdent: Q30976

    The OS2PATCH supplied with CodeView (protected) Versions 2.20 and
 2.30 allows you to use command 7 on machines with math coprocessors.
 This patch works only with OS/2 Version 1.00. The PTRACE feature was
 updated in Version 1.10, so this patch is not needed in OS/2 Version
 1.10.
    This patch only works on IBMs version of OS/2 1.00.  If they have
 a different version have them talk to the people who they received
 OS/2 from.  If it was from us then they need to systems languages
 support.
    Please refer to the file OS2PATCH.DOC for more information.



 79. I/O Redirection Under CV Not Supported Prior to Version 2.30

 Product Version(s): 1.x 2.10 2.20 2.30 | 2.20 2.30
 Operating System:   MS-DOS             | OS/2
 Flags: ENDUSER |
 Last Modified: 23-JAN-1990    ArticleIdent: Q57870
 In versions of CodeView earlier than Version 2.30, it was not possible
 to redirect the input or output of the program being debugged. For
 example, a "filter" program that takes input from a file specified by
 the input redirection operator ("<") is hindered by this limitation
 under pre-2.30 CodeView because there is no way to specify that you
 want the redirection to apply to the application rather than to
 CodeView itself.

 In CodeView (CV) or protected-mode CodeView (CVP) Version 2.30,
 redirection on the command line following the program name is directed
 to the program being debugged. For example, invoking CodeView 2.30
 with the following command line

    CV test < test.dat

 causes all input to the program TEST.EXE to be read from the file
 TEST.DAT.

 Redirecting I/O to CodeView itself is useful for involved debugging
 sessions where many CodeView dialog commands can be put into a
 separate text file that is automatically read by CodeView during
 debugging. For instance, this method will allow a complicated
 debugging scenario to be accurately repeated any number of times.
 Prior to CV and CVP 2.30, this was the only type of redirection
 supported while debugging.

 Starting with CodeView 2.30, you can redirect I/O to both the
 application being debugged and to CodeView. The CodeView redirection
 is done with the /C command-line option, or from within CV itself with
 the redirection dialog commands ("<" and ">"). Since the /C switch
 allows you to specify CV dialog commands on the command line, you can
 specify the redirection at this point. For example, the following
 command line

    CV "/C<cv.dat" test < test.dat

 brings up CodeView with TEST.EXE as in the example above (with the
 TEST.EXE input coming from TEST.DAT), but this time CodeView also
 reads the debugging instructions to perform from the file CV.DAT.


 80. /2 and /O Switches Not Compatible

 Product Version(s): 2.30
 Operating System:   OS/2
 Flags: ENDUSER |
 Last Modified:  9-NOV-1988    ArticleIdent: Q30978

    The UTILITY.DOC states that the /O switch is not compatible with
 the /2 switch. However, the SDK Installation Notes file uses the
 following code as the example of how to debug child processes:

     cvp /2 /O <program> <program arguments>

    This file recommends that the /2 switch be used when debugging PM
 applications. The UTILITY.DOC file is correct. You cannot use the /2
 and /O switches at the same time.


 81. CVP Prompts "SYS0197 OS/2 Not Configured..." Error Message

 Product Version(s): 2.20
 Operating System:   OS/2
 Flags: ENDUSER |
 Last Modified:  9-NOV-1988    ArticleIdent: Q31658

    When loading CodeView protected mode (CVP), the "SYS0197 OS/2 not
 configured to run this application" error message may appear. A
 request for help on 0197 prompts the "requires input/output privilege"
 message. You need to set IOPL=YES in CONFIG.SYS to run CVP.

    The following information is from the section titled "Microsoft(R)
 CodeView(R) Debugger" of the Microsoft C Version 5.10 UTILITY.DOC
 file, the FORTRAN Version 4.10 CVREADME.DOC file, and the Microsoft
 Macro Assembler Version 5.10 README.DOC file.

 CONFIG.SYS Setting for CVP
    To run the protected-mode CodeView debugger (CVP.EXE), you must
 have the following line in your CONFIG.SYS file:

    IOPL=YES



 82. Methods for Debugging Large Programs within the 640K DOS Limit

 Product Version(s): 1.00 1.10 2.00 2.10 2.20 2.30
 Operating System:   MS-DOS
 Flags: ENDUSER |
 Last Modified: 12-FEB-1990    ArticleIdent: Q57941
 Because of the 640K limit under DOS, it is common to run out of memory
 when trying to debug large programs with CodeView. CodeView requires
 over 200K of RAM, not including the program being debugged. In
 addition, the symbolic information added by compiling with the /Zi
 switch greatly increases the executable size of the program you are
 trying to debug.

 The following is a list of the possible ways of getting around the
 limited memory problems for debugging:

 1. Include full symbolic information only in those modules that
    contain source code that you are currently trying to debug. In
    other words, compile only those modules with the /Zi switch. For
    the other modules, compile with the /Zd option, to put only line
    number information in the object files.

 2. Use overlays to swap parts of your code in and out, even if it is
    just during the development process. You can always link without
    overlays once your application is debugged.

 3. If you have expanded memory, use it by invoking CodeView with the
    /E switch. To work properly with CodeView, you should have LIM EMS
    3.2 or (preferably) 4.0. Expanded memory is used for storing the
    symbolic information, which can be a great percentage of your .EXE
    size.

 4. Use the CVPACK utility, which is documented in the Update Section
    of the C 5.1 "Microsoft CodeView and Utilities Software Development
    Tools for MS OS/2 and MS-DOS Operating Systems Update" manual.
    CVPACK will compress the debug information in the file by removing
    duplicate references. Use the /p option to achieve maximum
    compression.

 In trying to obtain a workable solution, you can use any combination
 of the above methods. If adequate debugging is still impossible, then
 you might look into the following possibilities:

 5. Switch to the OS/2 operating system. This may be limited as far as
    how much real mode program debugging you can do, depending on how
    compatible your application is with protected mode requirements.

 6. You might look into MagicCV from Nu-Mega Technologies of New
    Hampshire. MagicCV requires a 386-based computer because it uses
    virtual-86 mode of the processor to run CodeView in extended
    memory. This method reportedly allows CodeView to use only about 8K
    of conventional DOS memory. It should be noted that Microsoft does
    not endorse MagicCV or make any claims as to its usage. The
    information is offered only as a potential option. Nu-Mega can be
    reached at [phone].


 83. Problems with CodeView and Logitech Mouse with Older Drivers

 Product Version(s): 2.00 2.10 2.20
 Operating System:   MS-DOS
 Flags: ENDUSER |
 Last Modified: 23-JAN-1990    ArticleIdent: Q31918

 Incompatibility problems have been reported with Logitech's mouse and
 CodeView. Some of the problems encountered are as follows:

 1. The Logitech mouse fails to function correctly with CodeView
    Version 2.20 when in 43-line mode. The characters within
    highlighted cells are incorrect until they are unhighlighted.

 2. When in either 43-line or 25-line mode, garbage characters are
    occasionally found at the DOS prompt following an exit from
    CodeView.

 The problems seem to be with Versions 3.20 and earlier of the Logitech
 mouse driver. An update of the mouse driver is available that corrects
 these problems. Logitech can be reached at [phone]. Logitech
 also has a bulletin board service, which may contain the latest driver
 and can be reached at [phone].

 A Microsoft Mouse or 100 percent Microsoft-compatible mouse is
 required for use with CodeView. In addition, you must use Microsoft's
 mouse driver Version 6.00 or later, or a driver that exactly emulates
 these Microsoft drivers.


 84. Using the T Command to Echo CodeView Output

 Product Version(s): 2.00 2.10 2.20
 Operating System:   MS-DOS
 Flags: ENDUSER |
 Last Modified: 16-NOV-1988    ArticleIdent: Q31919

    To generate and record a history of the source lines stepped
 through in the course of a debugging session, do the following:

    1. Start CodeView in sequential mode using the /T option.
    2. While in sequential mode, enter the Redirect Output (>) command,
 followed by a filename. If no filename is specified, then stdout will
 be assumed.
    3. If you wish to view the output as it is redirected, precede the
 redirection operator with the echo command (T).
    4. If a second redirection operator is specified, the redirection
 file is appended to rather than truncated before output.

    For more information on output redirection, refer to the "System
 Commands" section of the "Microsoft CodeView and Utilities" manual.

    The following example demonstrates this process:

 CV> T > log.dat  or T >> log.dat
 CV> t
 CV> t
 CV> t
 CV> .
 CV> .
 CV> .
 CV> q

    The lines traced will be written both to the console and to the log
 file.


 85. CHAIN Statement in Compiled BASIC Not Supported by CodeView

 Product Version(s): 2.20
 Operating System:   MS-DOS
 Flags: ENDUSER | B_QuickBas B_BasicCom
 Last Modified: 16-NOV-1988    ArticleIdent: Q32265

    In Microsoft CodeView, when debugging compiled BASIC programs that
 CHAIN, you can view only the first program executed (the one given in
 the CV command line). The modules that are CHAINed-to cannot be viewed
 or stepped through, and their variables cannot be looked at, even if
 these modules are successfully executed. In fact, you cannot gain any
 information about the CHAINed modules, other than whether or not they
 execute correctly, unless you execute them separately in CodeView.
    This information applies to QuickBASIC Versions 4.00 and 4.00b,
 and the Microsoft BASIC Compiler Version 6.00 for MS-DOS and OS/2.



 86. CodeView Cannot Debug Source Code in Include Files

 Product Version(s): 1.00 1.10 1.11 2.00 2.02.02 2.10 2.20
 Operating System:   MS-DOS
 Flags: ENDUSER |
 Last Modified:  9-NOV-1988    ArticleIdent: Q34922

 CodeView cannot debug source code in include files. This information
 is documented on Page 7 of the "Microsoft CodeView and Utilities"
 manual. The explanation for the restriction on include files says "You
 will not be able to use the CodeView debugger to debug source code in
 include files."

 This information means programs with include files that contain
 executable statements cannot be debugged with CodeView.

 The usual symptom of this problem is that after tracing or otherwise
 trying to execute your program, you will be viewing one of your
 include files instead of your normal source code. Repeated attempts
 to view the main or other source files will result in viewing the
 include file again.

 This is program design for the product. Microsoft's compilers do not
 generate symbolic information for code in include files. As a result,
 CodeView is confused by the discrepancies, and the subsequent behavior
 is unpredictable. Include files only can contain prototypes,
 declarations, #defines or #includes, etc.

 (Note that these items are all "nonexecutable" statements )

 Although it is valid C code, include files must not contain
 initializations or function definitions or other executable statements
 for CodeView to be able to debug your programs properly.


 87. No Symbolic Information Generated for Pascal Units

 Product Version(s): 2.10 2.20 2.30 | 2.20 2.30
 Operating System:   MS-DOS         | OS/2
 Flags: ENDUSER | s_pascal
 Last Modified:  8-MAR-1990    ArticleIdent: Q57943

 The Microsoft Pascal Compiler Version 4.00 does not generate symbolic
 debugging information for Pascal units. As a result, when tracing
 through a Pascal program unit, any attempt to access local variables
 by using trace/watchpoints, dumps, examines, etc. yields a "symbol
 unknown" error.

 The only workaround is to transform the program units into modules.


 88. CVP Accessing I/O Ports

 Product Version(s): 2.20 2.30
 Operating System:   OS/2
 Flags: ENDUSER | buglist2.20 buglist2.30
 Last Modified: 14-AUG-1989    ArticleIdent: Q36885

 In the "Microsoft CodeView and Utilities Software Development Tools
 for the MS-DOS Operating System," Sections 6.6 and 10.5 discuss the
 Port Input and Port Output commands respectively. These commands
 function correctly in CV under MS-DOS. However, CVP under OS/2
 generates a protection violation when trying to access a port. The
 port input and output commands do not function in CVP Version 2.20
 under OS/2.

 Microsoft has confirmed this to be a problem in Version 2.20. We are
 researching this problem and will post new information as it becomes
 available.


 89. Using CodeView to Examine FORTRAN Arrays

 Product Version(s): 2.20 2.30 | 2.20 2.30
 Operating System:   MS-DOS    | OS/2
 Flags: ENDUSER |
 Last Modified: 14-AUG-1989    ArticleIdent: Q37548

 Question:

 I have allocated memory for a three-dimensional array in FORTRAN. How
 can I examine the contents of a row using CodeView?

 Response:

 You can use CodeView to display a single element of the array using
 ?arrayname(x,x,x), where "arrayname" consists of the first six
 characters of the array name and "(x,x,x)" must be a valid cell in the
 array.

 There is no way to display more than one cell of the array using this
 command. To display many cells, you must do a memory dump of the
 addresses where the array is stored. Use the examine command (X) to
 get the starting address of the array, and dump (D) to dump the
 elements.

 FORTRAN stores array elements in column-major order. Use the following
 formula to determine the address where any cell (i,j,k) is stored,
 where Max_Row is the maximum i possible and Max_Col is the maximum j
 possible:

     MemAddr = start_addr+(size of elements)*
                      (Max_Row((k-1)(Max_Col)+(j-1))+(i-1))

 "Size of elements" is the number of bytes of each element in the
 array.


 90. CodeView Unexpectedly Exits to DOS

 Product Version(s): 2.10 2.20
 Operating System:   MS-DOS
 Flags: ENDUSER |
 Last Modified:  8-APR-1990    ArticleIdent: Q37566

 When debugging a program with CodeView, certain operations cause it to
 exit to DOS without giving any warning or error message. Some of the
 things that cause this behavior are trying to access help, setting a
 watch variable, and returning from a DOS shell.

 This problem occurs because not enough file handles are being
 allocated at boot time with "files=XX" in CONFIG.SYS. An error message
 is printed, but then over written before most people can see it.

 The solution is to make sure files are set to 20 in CONFIG.SYS.


 91. How CodeView Handles DosExitList Routines

 Product Version(s): 2.20
 Operating System:   OS/2
 Flags: ENDUSER |
 Last Modified: 12-JAN-1989    ArticleIdent: Q40270

 Question:

 CodeView does not seem to be executing my DosExitList. What should I
 do to execute the exit list?

 Response:

 If you are in your program and issue the GO command, your program
 executes to the end of your application, giving the message "Thread
 terminated normally." At this point, you can use the GO command or
 trace into your exit routine. However, if you would like to quit your
 program and go to your exit handler in the middle of executing your
 program, you have two choices.

 When you quit CodeView ("q"), your code including your DosExitList
 will not be executed. The first method to execute your DosExitList is
 the safest, but you are not able to trace through your exit routine.
 When you want to exit, type the following:

    ? myexithandler()

 This command executes the function "myexithandler", which is your
 DosExitList routine. After this command has been performed, you can
 quit CodeView ("q") because all of your cleanup has been accomplished.

 The second method, which is less reliable, is to modify the instruction
 pointer (IP) so that you can effectively jump to the end of your
 program. Before you do this, make certain that you are not in a
 subfunction. If you are not in main(), jumping to the end of the
 program causes problems with the stack. While in your main() routine,
 enter the following at the CodeView command line, where XXXX is the
 value of the IP when you are at the last curly brace at the end of
 your program:

    R IP XXXX

 This command causes a jump to the last curly brace; you can step
 through your program from there. This method allows you to step
 through your exit routine, but it is a little more risky.


 92. You Cannot Display Past Column 71 in CodeView

 Product Version(s): 2.20   | 2.20
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified: 20-JAN-1989    ArticleIdent: Q40428

 Can I view my code beyond column 71 in CodeView like I can in the
 Microsoft editor?

 In CodeView Version 2.20, you cannot scroll your code to the right.
 You should either rewrite the source code or, if you used tabs in the
 source code, reduce the tab size with the # dialog command, as
 described on Page 240 of the "Microsoft CodeView and Utilities"
 manual.



 93. Display Command Returns Incorrect Result for FORTRAN Function

 Product Version(s): 2.20 2.30 | 2.20 2.30
 Operating System:   MS-DOS    | OS/2
 Flags: ENDUSER | buglist2.20 buglist2.30
 Last Modified: 14-AUG-1989    ArticleIdent: Q40586

 The display command does not return correct values for the
 user-defined FORTRAN real functions in Microsoft CodeView.

 The display command calls integer functions and returns correct
 results.

 Microsoft has confirmed this to be a problem in Version 2.20. We are
 researching this problem and will post new information as it becomes
 available.

 The display command is discussed in Chapter 6 of the "Microsoft
 CodeView and Utilities" manual. The valid FORTRAN expressions for
 CodeView are discussed in the Chapter 4 of the same manual.


 94. CodeView Does Not Work with Grouped Code Segments

 Product Version(s): 2.20   | 2.20
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER | H_MASM
 Last Modified:  9-FEB-1989    ArticleIdent: Q40784

 When using MASM it is possible to associate various segments into a
 group; DGROUP is an example of this technique. Grouped data or stack
 segments do not affect CodeView, but CodeView does not recognize
 grouped code segments. The program will execute correctly under
 CodeView, but none of the CodeView functions will be available on the
 second and subsequent segments in the code group.

 The following code segment illustrates this behavior:

 codegroup  GROUP ASEG,BSEG
         assume cs:codegroup

 ASEG    SEGMENT WORD PUBLIC 'CODE'
 A:
         mov ax,1
         mov ax,1
         JMP B
 ASEG    ends

 ;   Will not be able to single step through this section
 BSEG    SEGMENT WORD PUBLIC 'CODE'
 B:      mov ax,1
         mov ax,1
         mov ax,1
         int 21h
 BSEG    ends
         end A

 Once the program executes into the BSEG segment, all CodeView
 functionality will be lost. You cannot set any breakpoints or single
 step through the BSEG segment of code. It appears that CodeView does
 not store any symbolic information for the BSEG segment. Any attempt
 to single step through this section of code will result in CodeView
 executing the BSEG segment of code until the program is completed.

 Microsoft is researching this problem and will post new information as
 it becomes available.


 95. CodeView and Video Pages

 Product Version(s): 2.00 2.10 2.20 | 2.20
 Operating System:   MS-DOS         | OS/2
 Flags: ENDUSER |
 Last Modified:  2-MAR-1989    ArticleIdent: Q41101

 Question:

 Is there anyway to specify which video page CodeView uses? I have an
 application that uses video page one; I am not able to use CodeView
 with it because CodeView also uses video page one.

 Response:

 CodeView does not allow you to specify which video page it will use.
 As a result, any application that uses video page one conflicts with
 CodeView and the screen becomes corrupted.

 The recommend work around in this situation is to use the two monitor
 option for CodeView. This option allows CodeView to send the
 application's output to one screen while using the first screen for
 its own output.

 Another less desirable workaround would be to avoid the use of video
 page one in programs that will be used under CodeView.



 96. Removing CodeView Information from .LIBs and .EXEs

 Product Version(s): 2.20   | 2.20
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER | SR# G890207-11424
 Last Modified:  2-MAR-1989    ArticleIdent: Q41371

 Question:

 Is there a way to remove CodeView symbols from a .LIB or .EXE file?

 Response:

 Although there is no utility that removes CodeView information from
 libraries, EXEPACK will remove CodeView information from .EXE files in
 the course of packing them. You can also remove information from an
 .EXE file by relinking it without the /CODEVIEW option.

 The only way to remove CodeView information from a library is to
 recompile the source modules and use the LIB utility to rebuild the
 library.


 97. CodeView: Debugging Presentation Manager Printer Drivers

 Product Version(s): 2.20 2.30
 Operating System:   OS/2
 Flags: ENDUSER |
 Last Modified: 28-MAR-1989    ArticleIdent: Q42780

 To debug OS/2 Presentation Manager (PM) printer drivers, you must use
 the kernel debugger. Currently, PM printer drivers fall under the same
 category as lower-level device drivers. These device drivers cannot be
 debugged using the current version of CodeView.


 98. Dump Command on Arrays in FORTRAN Gives Syntax Error

 Product Version(s): 1.10 2.20 | 2.20
 Operating System:   MS-DOS    | OS/2
 Flags: ENDUSER | H_FORTRAN buglist2.20 buglist2.30
 Last Modified: 21-AUG-1989    ArticleIdent: Q42942

 Microsoft CodeView Versions 2.20 and 2.30 gives a "Syntax error" when
 attempting to use the Dump command on an array of dimension greater
 than 1.

 For example, issuing the DI i(1,3) command to dump the contents of an
 array element fails.

 To work around this problem use one of the following methods:

 1. Use the "?" command, as follows:

       ? i(1,3)

 2. Enclose each dimension index within parentheses and omit the comma,
    as follows:

       DI i((1)(3))

    DI i(1(3)) and DI i((1)3) are also acceptable.

    A three dimensional example would look like the following:

       DI j(1(2)3)

    Any permutation of the parenthesis around the index is sufficient.

 Microsoft has confirmed this to be a problem in Versions 2.20 and
 2.30. We are researching this problem and will post new information as
 it becomes available.


 99. CodeView Protect: /43 Switch Doesn't Work on VGA Adapters

 Product Version(s): 2.20
 Operating System:   OS/2
 Flags: ENDUSER | buglist2.20
 Last Modified: 18-APR-1989    ArticleIdent: Q43043

 The /43 switch for CodeView, used to debug in 43 line mode, is ignored
 when a VGA video adapter is being used under OS/2. This switch works
 properly as documented in DOS, or when an EGA adapter is being used.
 The /50 switch, used to debug in 50 line mode, also works properly as
 documented.

 If you wish to use CodeView Version 2.20 in 43 line mode under OS/2,
 the MODE command can be used first to set the entire screen group into
 43 line mode. Using MODE 80,43 at the OS/2 prompt will accomplish this
 result. Starting CodeView without any switches will then cause it to
 use the current video mode.

 Microsoft has confirmed this to be a problem in CodeView Protect
 Version 2.20. This feature is under review and will be considered for
 inclusion in a future release.


 100. CV: K Command in Secondary Module Sets Breakpoints in Main

 Product Version(s): 2.20   | 2.20
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER | buglist2.20
 Last Modified:  6-APR-1989    ArticleIdent: Q43170

 In some cases the K (call stack) command will cause CodeView to become
 uncertain as to where to set breakpoints.

 If an attempt to set a breakpoint is made in a module of a
 multi-module program immediately after using the K command then the
 breakpoint will be set in the module containing main() instead of in
 the current module.

 If the corresponding line in the first module is not an executable
 line then CodeView will issue the expected beep to indicate that the
 breakpoint could not be set.

 If the corresponding line is an executable line then there will be no
 indication at all that the breakpoint has been set until that module
 is again in view. At that point the breakpoint will be highlighted as
 usual. This behavior will occur in any module accessed after the one
 containing main().

 Breakpoints will be set properly after using the K command if any
 stepping is performed, the view is changed, or the Calls menu is
 accessed.

 Microsoft is researching this problem and will post new information as
 it becomes available.


 101. Vertical Scroll Inactive with MODE CO40 and Dual Monitors

 Product Version(s): 2.x
 Operating System:   MS-DOS
 Flags: ENDUSER | S_C buglist2.20
 Last Modified: 18-APR-1989    ArticleIdent: Q43260

 While debugging a program using Microsoft CodeView and dual monitors,
 the vertical scroll bar is disabled when the video mode is set to
 40-line color text. This occurs if the mode is set either at the
 command line

    MODE CO40

 or from within a program as follows:

    _setvideomode(_TEXTC40);

 The scroll bar remains inactive until the mode is changed. This
 problem does not occur on a single monitor system or in any other
 video modes.

 Microsoft has confirmed this to be a problem in Version 2.20. We are
 researching the problem and will post new information as it becomes
 available.

 The following program demonstrates the problem:

 #include <graph.h>

 void main (void)
 {
   _setvideomode(_TEXTC40);
   _setvideomode(DEFAULTMODE);
 }



 102. Selecting Text for Use with Commands

 Product Version(s): 2.20 2.30 | 2.20 2.30
 Operating System:   MS-DOS    | OS/2
 Flags: ENDUSER | docerr insert
 Last Modified:  9-APR-1990    ArticleIdent: Q59408

 In CodeView Versions 2.20 and 2.30, you supposedly can press the left
 mouse button to highlight the command to be copied, and then press the
 INS key to copy the command. However, this method works only with the
 mouse and not with the keyboard.

 On Page 64 of the "Microsoft FORTRAN CodeView and Utilities User's
 Guide" Version 5.0 manual, it incorrectly states that you can copy any
 text that appears in any window. This is incorrect because you can
 only copy text in the command window.


 103. CodeView: View Command Fails with Underscore in Filenames

 Product Version(s): 2.20   | 2.20
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER | buglist2.20
 Last Modified:  3-MAY-1989    ArticleIdent: Q43508

 Assume that two source files, MAINPROG.C and FILE_NAM.C, have been
 compiled with CodeView information. The main function in MAINPROG.C
 calls a function in FILE_NAM.C.

 When the following command is executed in CodeView, CodeView responds
 with "syntax error":

    V.FILE_NAM.C

 When FILE_NAM.C is renamed and recompiled as FILENAM.C, the following
 command works properly, and the source code in FILENAM.C is displayed:

    V.FILENAM.C

 Attempts to open a file with an underscore character will work
 correctly through the "Open" menu in CodeView, but will fail with the
 View command.

 Microsoft has confirmed this to be a problem in Version 2.20. We are
 researching this problem and will post new information as it becomes
 available.


 104. Cannot Set Breakpoint on an Executable Line with CodeView 3.00

 Product Version(s): 3.00   | 3.00
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified: 19-APR-1990    ArticleIdent: Q60338

 If you cannot set a breakpoint on a particular line of code, make sure
 you have used the -Zi and -Od options to create executable code that
 has full CodeView debugging capabilities.

 Some code in the executable is concatenated if the -Od option is not
 used.

 Sample Code
 -----------

 #include <stdio.h>

 int foo();

 void main (void)
 {
    int a,b,c;

    a = foo();/* this line would be concatenated into the next */
    b = a + c;/* line to look like b=(a=foo())+c.              */
 }

 int foo()
 {
    return(10);
 }


 105. Commands Invoked with "?" Command Must Be Compiled with /Zi

 Product Version(s): 2.20   | 2.20
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified:  3-MAY-1989    ArticleIdent: Q43556

 Invoking C functions in CodeView using the "?" command works as
 expected as long as the function is contained in a module that was
 compiled with /Zi for the CodeView information. However, if you invoke
 a run-time library function, CodeView returns the error message
 "syntax error."

 The reason for the error message is that the module containing the
 library function is not compiled with the CodeView option /Zi. The
 error message is not dependent on the fact that the function is in the
 library rather than being user-defined. If a user-defined function is
 contained in a module that is compiled without /Zi for the CodeView
 information and you try to invoke it with the "?" command, CodeView
 will return the same error message.

 The "?" command is formally referred to in the CodeView Utilities
 menu as the Display Expression command.


 106. CodeView May Single Step onto a Comment Line

 Product Version(s): 2.20   | 2.20
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER | buglist2.20
 Last Modified:  2-JUN-1989    ArticleIdent: Q43601

 When using CodeView to single step the following program, the current
 execution line will be put on the first comment line. CodeView should
 always skip over the comment line.

 The program is compiled as required for running in CodeView. The
 compiling command used could be the following:

    cl /Zi /Od test.c

 Microsoft has confirmed this to be a problem with CodeView Version
 2.20. We are researching the problem and will post new information as
 it becomes available.

 This problem has no effect on the application program's performance.

 The following is the program:

 /*   test.c   */
 #include <stdio.h>
 int i = 1 ;
 void main (void)
 {
 if ( i )
      i = 0 ;
      /* first comment line */
 else
      /* more comment */
      i = 1 ;
 }


 107. Returning Control to CodeView

 Product Version(s): 2.20
 Operating System:   MS-DOS
 Flags: ENDUSER | CONTROL-C CONTROL+C CONTROL+BREAK CONTROL-BREAK ^C ^BREAK
 Last Modified:  3-MAY-1989    ArticleIdent: Q43648

 The following are two software methods of returning control to
 CodeView during program execution:

 1. Use the debug interrupt, interrupt 03, in your code. Interrupt 03
    is called a microprocessor (or logical) interrupt. It is the
    interrupt that CodeView uses to make breakpoints. Hard code
    interrupt 03 into your code in selected places where you want to
    return control to CodeView. The following sample program will
    demonstrate the technique. Note that a macro could easily be
    constructed to insert breakpoints where desired.

         #include <dos.h>
         #include <stdio.h>

         void main()
         {
             union REGS    inregs;
             int           i = 1;

             for( ;; )
             {
                 printf( "Loop iteration: %d\n", i++ );
                 int86( 0x03, &inregs, &inregs );
             }

 2. Use CTRL+C and CTRL+BREAK to return control to CodeView. This is
    a useful method for breaking out of a program is currently running
    or that has locked up.  The position in the source code to which
    you are returned depends on when you hit the ^C and what caused
    the system to hang, e.g. an infinite loop, a bad pointer, etc.
    Execution may be continued from this point in the usual manner
    (F5, F8, F10, etc.).

    Under OS/2 CTRL+BREAK does not return control to CodeView. CTRL+C
    may be used to abort a normally executing program but you cannot
    continue to debug from that point as you can in DOS.

 There is no hardware interrupt that will return control to CodeView.


 108. Cannot Open Source File Under CVP

 Product Version(s): 2.20
 Operating System:   OS/2
 Flags: ENDUSER | buglist2.20 buglist2.30 buglist2.4.1
 Last Modified: 18-SEP-1989    ArticleIdent: Q45135

 Problem:

 When using CodeView Protect (CVP) Version 2.20, I trace my program
 through a number of source files and after some number of files CVP is
 no longer able to open source files. When CVP gets into this
 situation, it automatically goes into mixed mode -- displaying line
 numbers but no source text. In this state, trying to use the "v"
 command to look at another (not previously looked at) file results in
 a red message box telling me that CVP can't open the file.

 Response:

 This is a problem with CVP Version 2.20 and 2.30. CVP is running into a
 file limit. To work around this problem, before you step out of the first
 module, open the source file containing the code you wish to debug and
 set a breakpoint there. Now "go" to this location by pressing the F5
 key. This procedure allows you to start debugging at a location deep
 into the file without opening multiple source files.

 Microsoft has confirmed this to be a problem with CodeView versions
 2.20 and 2.30. We are researching this problem and will post new
 information as it becomes available.


 109. Incorrect Handling of SP Can Cause CodeView to Corrupt Stack

 Product Version(s): 2.20 2.30 | 2.20 2.30
 Operating System:   MS-DOS    | OS/2
 Flags: ENDUSER |
 Last Modified:  7-JUN-1989    ArticleIdent: Q45183

 CodeView will use your program's stack for temporary variables in
 between assembly instructions. Thus, when writing an assembly language
 program, if you forget to increase the stack pointer (SP) to point
 beyond the memory locations you are using on the stack, CodeView will
 overwrite that memory.

 This is expected behavior. Even if CodeView did not use the stack, you
 would still have to increment the stack pointer to keep your program
 from overwriting your variables when you make a call, or with any
 operation that pushes values on the stack.


 110. Switching Out of PM Application Hangs System under Codeview

 Product Version(s): 2.20
 Operating System:   OS/2
 Flags: ENDUSER |
 Last Modified: 16-MAY-1989    ArticleIdent: Q44418

 Question:

 I am using CodeView to debug my Presentation Manager (PM) application.
 Why does my machine sometimes hang when I use CTRL+ESC to switch to
 the OS/2 program selector?

 Response:

 Presentation Manager applications require the use of the Presentation
 Manager shell. To debug PM applications, CodeView must put hooks into
 the Presentation Manager before the PM application is executed. This
 process works properly while inside CodeView, but if you try to switch
 back to the program selector, PM is in an unknown execution state.

 Therefore, to switch out of CodeView while debugging a PM application,
 you must first restart or end the program inside CodeView. This tells
 CodeView to restore the Presentation Manager to its original
 condition.


 111. SYS0317 Caused by Running CVP on a DOS Application

 Product Version(s): 2.20
 Operating System:   OS/2
 Flags: ENDUSER |
 Last Modified: 31-MAY-1989    ArticleIdent: Q44707

 The following message results from running a DOS application under
 Microsoft CodeView Version 2.20 or 2.30 for protected mode:

    SYS0317: The system cannot find message 0491
    in message file OSO001.MSG

 The screen is then cleared and the OS/2 prompt returns.


 112. /43 Starts CodeView with Screen Swapping Enabled

 Product Version(s): 2.20 2.30 | 2.20 2.30
 Operating System:   MS-DOS    | OS/2
 Flags: ENDUSER |
 Last Modified:  7-JUN-1989    ArticleIdent: Q45185

 When CodeView is started with the /43 switch to bring it up in 43-line
 mode, screen swapping is automatically enabled. This behavior is by
 design, although it is not stated in the documentation for the
 product.


 113. Setting a Breakpoint Highlights More Than One Line

 Product Version(s): 2.20
 Operating System:   MS-DOS
 Flags: ENDUSER | buglist2.20
 Last Modified:  7-JUN-1989    ArticleIdent: Q45241

 When setting a breakpoint, CodeView may highlight two or more lines of
 code when you do the following:

 1. Compile C program (e.g., "Hello, world") with /Zi /Od.

 2. Load CodeView with 50 line mode (in VGA mode) as follows:

       cv /50 hello.c).

 3. Display mixed source and assembly.

 4. Move the cursor to the edit window and scroll down two or three
    pages of start-up assembly code.

 5. Set and remove breakpoints at arbitrary locations. In some cases,
    multiple lines will be highlighted and the display altered. The
    code itself is not changed. To restore the altered display, page
    down and then page up to the altered location.

 CVP does display this problem.

 Microsoft has confirmed this to be a problem in CodeView Version 2.20.
 We are researching this problem and will post more new as it becomes
 available.

 After setting a breakpoint that highlights more than one line of code,
 using the BL command will list only the one breakpoint you set.


 114. "No Symbolic Information" May Be Caused by Using Wrong Linker

 Product Version(s): 1.00 1.10 2.00 2.10 2.20 2.30 2.35 | 2.20 2.30 2.35
 Operating System:   MS-DOS                             | OS/2
 Flags: ENDUSER | S_LINK
 Last Modified: 19-SEP-1990    ArticleIdent: Q59540

 To debug programs at the source level with CodeView, it is critical
 that a proper version of LINK be used. Particular versions of CodeView
 are matched to particular versions of LINK and using a version of LINK
 newer than the versions matched to a particular version of CodeView
 will prevent CodeView from recognizing the symbolic information in the
 .EXE file.

 This mismatch will cause CodeView to come up in assembly mode and
 produce the message "No Symbolic Information," even though the source
 files may have been compiled and linked with the correct options for
 CodeView symbolic debugging.

 The difference between the linkers is in the way they store symbolic
 information in .EXE files. A newer version of CodeView generally can
 always display symbolic information for programs produced with
 previous versions of LINK, but the opposite is NOT true. Using a more
 recent linker with an older version of CodeView is where potential
 problems arise.

 The following information applies to both real-mode CodeView (CV) and
 protected-mode CodeView (CVP).

 Versions of CodeView prior to Version 3.00 cannot display symbolic
 information for .EXE files produced with LINK 5.10. In other words,
 if LINK 5.10 (supplied with C 6.00) is used for linking, then
 CodeView 3.00 is the ONLY matched version of CodeView that can
 display the program's symbolic information.

 CodeView Version 2.35 is matched to LINK 5.05 (both were released with
 BASIC 7.00). Therefore, CodeView 2.35 is the ONLY version of CodeView
 that can display symbolic information for a program linked with LINK
 5.05.

 For CodeView Versions 2.00, 2.10, 2.20, and 2.30, any linker with a
 version number from 3.60 to 5.03 is acceptable.

 For CodeView Versions 1.00 and 1.10, LINK versions later than or equal
 to 3.51, but earlier than 3.60, must be used.


 115. Mouse Disabled When Single-Stepping over Video Mode Change

 Product Version(s): 2.20 2.30
 Operating System:   OS/2
 Flags: ENDUSER | buglist2.20 buglist2.30
 Last Modified: 21-JUN-1989    ArticleIdent: Q45617

 When CodeView is run in the OS/2 compatibility box with screen
 swapping enabled (started with either /s or /43), single-stepping (F8)
 over a _setvideomode() call or an INT 10 call to change the video mode
 to a graphics mode causes the mouse cursor to disappear. Exiting
 CodeView and running another mouse-driven program reveals that the
 mouse has been completely disabled in the compatibility box. The only
 way to regain the mouse is to reboot the computer. Attempting to
 reload the mouse by typing "mouse" at a prompt results in the
 following message:

    Session Title: DOS Command Prompt

 This error occurs because a DOS mode program changes an interrupt
 vector that is owned by the system causing the program to end.

 The behavior described above applies to tracing in SOURCE mode.
 Attempting to trace in assembly language or mixed mode through the
 code that changes the video mode produces erratic results, which range
 from hanging the DOS box to halting the entire system with an
 "internal processing error."

 Microsoft has confirmed this to be a problem in CodeView Versions 2.20
 and 2.30. We are researching this problem and will post new information
 as it becomes available.

 The following program illustrates the problem:

 #include <graph.h>

 void main(void)
 {
   _setvideomode(_ERESCOLOR);    /* when this line is executed, the  */
                                 /* mouse cursor will disappear.     */
   _setvideomode(_DEFAULTMODE);

 }


 116. CodeView "??" Command Can't Show All of Large Structures

 Product Version(s): 2.20 2.30 | 2.20 2.30
 Operating System:   MS-DOS    | OS/2
 Flags: ENDUSER | SR# G890607-19918
 Last Modified:  8-AUG-1989    ArticleIdent: Q45624

 Question:

 How can I view structures with many members in CodeView with the "??"
 command? It shows only those members that fit on the screen. Is there
 some trick I haven't found?

 Response:

 Unfortunately, the "??" command is limited in this respect -- there is
 no way to view the last members of a large structure with this
 command. This feature is under review and will be considered for
 inclusion in a future release.

 Instead, however, you can view each element of the structure by itself
 by dereferencing the struct and element, i.e., "?structname.field".

 There are at least two ways to work around the problem in CodeView
 Versions 2.20 and 2.30. One way is to shrink or nest the structures.
 Another workaround is to use the "?" or Watch command to look at the
 individual member(s) you want to see.


 117. Problem Debugging StartSession from a Child Process

 Product Version(s): 2.30
 Operating System:   OS/2
 Flags: ENDUSER | buglist2.30
 Last Modified:  9-AUG-1989    ArticleIdent: Q45707

 When a program spawns another program that starts a new session,
 CodeView has difficulty stepping into that new session. This process
 is shown graphically in the following diagram:

        --------------        -------------------
    A --| DosExecPgm |--> B --| DosStartSession |--> C
        --------------        -------------------

 The following describes how to duplicate this process and re-create
 the problem:

 1. Invoke CodeView on Program A with offspring debugging enabled, as
    follows:

       CVP /O A

 2. Program A calls DosExecPgm to spawn Program B. Trace into Program B
    by pressing F8 on the DosExecPgm function. You will be informed
    that a new process has begun and you will be asked if you wish to
    debug it. Answer yes and switch to the newly created CodeView
    session.

 3. Program B calls DosStartSession to begin a new session. The program
    that will execute in that session is Program C. Attempt to trace
    into the new session by pressing F8 on the DosStartSession function.

 The problem is demonstrated in Step 3. CodeView does not give you the
 opportunity to debug Program C as it should. Further, when Program B
 has completed execution and CodeView returns back to Program A, the
 first single step will inform you that a new process has been started.
 This message should have been presented on the call to
 DosStartSession.

 CodeView has no difficulty stepping into a new session when the
 initial program being debugged is Program B. To work around this
 problem, invoke CodeView on Program B with the /O switch.

 Microsoft has confirmed this to be a problem with CodeView Version
 2.30. We are researching this problem and will post new information
 as it becomes available.

 The following three modules demonstrate this problem:

 //***********************************************************
 // A.C - spawn a child from here.

 #define INCL_BASE
 #include <os2.h>

 void main (void)
 {
   char        failbuf[80];
   RESULTCODES ExecCode;

   DosExecPgm (failbuf, 40, EXEC_ASYNC, NULL, NULL, &ExecCode, "B.EXE");
   VioWrtTTY ("End of A.\r\n", 11, 0);
 }

 //***********************************************************
 // B.C - start a new session from here.

 #define INCL_BASE
 #include <os2.h>
 #include <string.h>

 void main (void)
 {
   USHORT    Disk;
   ULONG     Drives;
   BYTE      SessionProg [80];
   USHORT    MaxLen = sizeof(SessionProg)-14;
   STARTDATA StartData;
   USHORT    Session;
   USHORT    Process;

   // Build program name to run in new session.
   DosQCurDisk (&Disk, &Drives);
   strcpy (SessionProg, "*:\\");
   SessionProg[0] = (char) ('A' + Disk - 1);
   DosQCurDir (0, SessionProg + strlen(SessionProg), &MaxLen);
   strcat (SessionProg, "\\C.EXE");

   StartData.Length      = sizeof(STARTDATA);
   StartData.Related     = 1;
   StartData.FgBg        = 0;
   StartData.TraceOpt    = 0;
   StartData.PgmTitle    = "Test Session";
   StartData.PgmName     = SessionProg;
   StartData.PgmInputs   = "sample param";
   StartData.TermQ       = NULL;
   StartData.Environment = NULL;
   StartData.InheritOpt  = 0;
   StartData.SessionType = 1;
   StartData.IconFile    = NULL;
   StartData.PgmHandle   = 0;

   DosStartSession (&StartData, &Session, &Process);
   VioWrtTTY ("End of B.\r\n", 11, 0);
 }

 //***********************************************************
 // C.C - the test session.

 #define INCL_VIO
 #include <os2.h>

 void main (void)
 {
   VioWrtTTY ("In test session", 15, 0);
 }


 118. CodeView Skips Over a Line of Source Code

 Product Version(s): 2.20 2.30 | 2.20 2.30
 Operating System:   MS-DOS    | OS/2
 Flags: ENDUSER | S_QuickC
 Last Modified: 14-AUG-1989    ArticleIdent: Q46010

 After setting a breakpoint on the indicated line in the program below
 and executing the program, CodeView executes that line without
 stopping. Likewise, if you single step through the code, CodeView
 steps past that line. This problem also occurs in the QuickC
 integrated debugger.

 The workaround is to flip your source into mixed mode and set the
 breakpoint on the correct assembly line.

 This is due to the fact that CodeView is line-based and the C compiler
 is token-based. This will not be corrected; it is a restriction.

 Sample Program
 --------------

 int i, j, k, l;

 void main(void)
 {
     for(i = 0; i < 20; i++)
     {
         j = 0;
         for(k = 0; k < 20; k++)
             if(j == 0)
                 break;

         j = 1; /*** set breakpoint here ***/
     }

     l = 0;
 }


 119. Capabilities and Limits of the /R switch on 80386 Machines

 Product Version(s): 2.20 2.30 2.35 3.00 | 2.20 2.30 2.35 3.00
 Operating System:   MS-DOS              | OS/2
 Flags: ENDUSER | 386
 Last Modified: 12-APR-1990    ArticleIdent: Q46448

 The /R command line switch for CodeView beginning with Version 2.20 is
 used only on 80386 machines. The /R switch tells CodeView to use the
 four debug registers available on the 80386 chip, and also allows
 hardware breakpoints. This causes CodeView to run faster when
 performing debugger-intensive steps such as monitoring a tracepoint.

 The /R switch works under DOS and OS/2's DOS compatibility box. It is
 an unrecognized switch under OS/2. The /R switch speeds operation of
 Tracepoint but not Watchpoint or Breakpoint commands.

 Note: because there are only four debug registers, only four
 tracepoints (of up to 4 bytes each) may be specified when utilizing
 these registers. Specifying any combination of tracepoints greater
 than 16 bytes will require CodeView to use software tracepoints rather
 than the debug registers and all performance gains will be lost.


 120. Using CodeView /2 with Hercules Graphics Cards and Libraries

 Product Version(s): 2.20 2.30
 Operating System:   MS-DOS
 Flags: ENDUSER |
 Last Modified: 16-OCT-1990    ArticleIdent: Q46949

 Using CodeView in the dual-monitor mode with a Hercules graphics card
 as the primary (application) monitor requires the Hercules card to be
 configured in the half mode. Using the Hercules graphics library, the
 monitor must be configured using the config(0) function call. This
 function call is a part of the Hercules graphics library and does not
 use Microsoft graphics library or the MSHERC.COM program. Therefore,
 this information applies only if you are using the Hercules graphics
 libraries. This is NOT the same as using the /h switch with CodeView.

 The first page of the Hercules graphics display card is mapped to
 memory location B0000 (same as MDA), and the second page is mapped to
 B8000. The CGA/EGA/VGA also use B8000 as the beginning of their video
 memory. CodeView uses these two different address to run in the
 dual-monitor mode, sending the application output to the primary
 address, usually located at B8000, and the CodeView information to the
 secondary monitor, usually located at B0000.

 This works well until a Hercules graphics card is used as the primary
 monitor (in graphics mode) and the CGA/EGA/VGA card is used as the
 secondary monitor. The Hercules graphics card uses both pages (one at
 B0000 and the other at B8000) in the full mode. Therefore, use
 config(0) and only the first page (B0000) will be used and CodeView
 will function properly in dual-monitor mode.


 121. DEF File Entry of EXECUTEONLY Causes Problems with CVP

 Product Version(s): 2.20 2.30
 Operating System:   OS/2
 Flags: ENDUSER |
 Last Modified: 30-AUG-1989    ArticleIdent: Q47103

 Question:

 When I step into my DLL, I can see and step through the source code
 correctly. I also can look at local variables. However, I cannot set
 breakpoints in the DLL. Also, when I try to look at the disassembled
 code I see the following:

    ??? No Code ???

 I am using the correct Compile and Link options. Why is CodeView
 acting strangely?

 Response:

 In the .DEF file for the DLL, you had the EXECUTEONLY attribute as
 opposed to the default EXECUTEREAD. When you choose EXECUTEONLY,
 CodeView cannot read the code segment as it must to work correctly.
 Removing the EXECUTEONLY attribute corrects the problem.


 122. OS/2 SDK Version of CVP 2.30 Won't Debug DosLoadModule DLLs

 Product Version(s): 2.30
 Operating System:   OS/2
 Flags: ENDUSER |
 Last Modified: 11-JUL-1990    ArticleIdent: Q59610

 The OS/2 version 1.10 Software Development Kit (SDK) includes a
 prerelease version of protected-mode CodeView (CVP) version 2.30. This
 version is identical to the regular retail release of CVP 2.30, except
 that it does not allow the debugging of DLLs loaded with
 DosLoadModule. The regular retail version of CVP 2.30 is included with
 FORTRAN 5.00 and the OS/2 Presentation Manager Toolkit for OS/2
 version 1.10. This release DOES support debugging DLLs loaded at run
 time with DosLoadModule.

 The prerelease version of CVP 2.30 released in the OS/2 SDK may be
 identified by a file date of 2-24-89. The regular release version is
 dated 3-21-89. The file date is the only discernible difference
 between these two versions since the files themselves are exactly the
 same size.


 123. Minimum Extended Memory (384K) Causes CV 3.00 to Use Extra RAM

 Product Version(s): 3.00
 Operating System:   MS-DOS
 Flags: ENDUSER | docerr HIMEM
 Last Modified: 27-SEP-1990    ArticleIdent: Q59890

 Real-mode CodeView (CV) Version 3.00 is documented as being able to
 run in extended memory as long as there is at least 384K of extended
 memory available. This 384K minimum is accurate as far as CV being
 able to utilize the extended memory, but it is not enough for CodeView
 to remove all of itself from conventional RAM. In fact, a system
 configuration with only 384K extended memory will result in LESS
 memory being available for the debuggee (the program being debugged)
 than if no extended memory is utilized at all.

 The CodeView 3.00 documentation states that "if HIMEM.SYS or another
 extended-memory driver is installed, all but 16K of CodeView, plus all
 of the symbolic information for the program you are debugging, are
 placed in extended memory." But, for CodeView to truly work with this
 16K "footprint" in conventional memory, a minimum of approximately
 600K extended memory must be available.

 When no extended memory is available, CodeView normally utilizes
 overlays to keep as much of itself out of memory as possible, so that
 the debuggee can have more space to load. (The new /Dnnn option
 actually allows you to specify the size of the overlays -- a bigger
 overlays means CV runs faster, but a smaller overlays mean a bigger
 program can be loaded for debugging.)

 Once CodeView detects extended memory, it assumes that overlays are no
 longer needed, since CV itself and the debuggee's symbolic information
 will both (supposedly) be loaded into extended memory. However, the
 result may be that CodeView seems to get bigger because what Codeview
 can't fit into extended memory is loaded into conventional memory.

 Since no overlays are used, this can result in a much larger
 footprint. For instance, if the minimum of 384K extended memory is all
 that is available, then the footprint will be well over 200K.
 Obviously, as the amount of extended memory is increased from 384K,
 the footprint will shrink accordingly.

 The /X command-line option instructs CodeView to use extended memory.
 However, CV will automatically detect extended memory and use it if it
 is available. Consequently, if the /X option is not specified, CodeView
 will still use extended memory.

 Thus, if you have a limited amount of extended memory and decide to
 run CodeView in conventional RAM only, you have two options. You can
 explicitly specify /D (for example, /D16) to tell CodeView to use
 overlays, or you can remove (or comment out) the line in your
 CONFIG.SYS file that loads the extended memory driver (HIMEM.SYS) and
 reboot.


 124. If COMSPEC Is Invalid, Invoking DOS Shell May Hang Machine

 Product Version(s): 2.x 3.00
 Operating System:   MS-DOS
 Flags: ENDUSER | s_quickc s_pwb s_quickasm s_editor
 Last Modified: 19-APR-1990    ArticleIdent: Q60748

 If you set your COMSPEC environment variable to point to an invalid
 command interpreter, and then shell out of any DOS application, your
 machine will hang. This problem occurs because the file that COMSPEC
 points to is assumed to be a valid command interpreter and cannot be
 checked for validity.

 This is expected behavior. Because .COM files have no standard file
 header structure, they cannot be checked for validity. Therefore, DOS
 must assume that whatever the COMSPEC environment variable points to
 must be a valid command interpreter, and can do no further error
 checking.

 This behavior can easily be demonstrated in any program that allows
 you to access a DOS shell, including CodeView, Programmer's WorkBench
 (PWB), the Microsoft Editor (M), and the Quick environments. Type the
 following line at the DOS prompt:

    set comspec=a:\foo.c ; Invalid command.com file

 Then enter a DOS application and shell out. Your machine will hang,
 and you may receive strange error messages.

 If you are running under OS/2, you will be warned about an invalid
 command interpreter when you attempt to shell to the operating system.
 Under OS/2, the system expects an .EXE file to be the command
 interpreter, and .EXE files have a standard, recognizable structure
 that can be checked.


 125. /I Documented Incorrectly in "Advanced Programming Techniques"

 Product Version(s): 3.00   | 3.00
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER | docerr
 Last Modified: 19-APR-1990    ArticleIdent: Q60829

 In Section 9.7, "Controlling CodeView with Command-Line Options," on
 Page 204 of the "Microsoft C Advanced Programming Techniques" manual,
 it incorrectly states that the /I switch (used to turn the nonmaskable
 interrupts and 8259 interrupts on or off) is followed by either a 1 or
 a 2 (either /I1 or /I2).

 The correct switch options are /I0 to trap these interrupts, or /I1 to
 ignore these interrupts. Both the online documentation and the
 "Microsoft C Reference" give this correct usage of the /I switch.


 126. OS/2 1.20 Requirements for Dual-Monitor Debugging

 Product Version(s): 2.x 3.00
 Operating System:   OS/2
 Flags: ENDUSER | PM
 Last Modified: 17-JUL-1990    ArticleIdent: Q60866

 To do dual-monitor debugging under OS/2 Version 1.20 with CodeView,
 make sure that you have the correct display DLLs specified in your
 CONFIG.SYS file.

 For example, the following three lines in your OS/2 CONFIG.SYS file
 specify the device drivers needed to use a VGA and a monochrome
 adapter:

    set video_devices=bvh_vga,bvh_mpa
    set bvh_vga=device(bvhvga)
    set bvh_mpa=device(bvhmpa)

 If you have a CGA or an EGA monitor and adapter for your primary
 (color) display, replace device(bvhvga) with device(bvhcga) or
 device(bvhega), depending on your adapter type.

 Next, make sure that both of the BVH*.DLL files (in the above case,
 BVHVGA.DLL and BVHMPA.DLL) specified in the device(name) section are
 in your LIBPATH. OS/2 setup places these files in your C:\OS2\DLL
 directory by default.

 Note: You can substitute any name for bvh_vga or bvh_mpa, as long as
 those two placeholders match up with the name tab in the set
 <name>=device... lines.

 Remember, the two monitors must be unique for OS/2 to determine which
 monitor is which. For instance, debugging with two VGA monitors will
 not work because OS/2 and, therefore, CodeView will be unable to
 determine which adapter/monitor is the primary adapter/monitor and
 which is the secondary adapter/monitor.

 This point is critical to remember when considering dual-monitor
 debugging on a microchannel machine (for example, an IBM PS/2 Model 50
 and above). Since there are currently no microchannel monochrome
 adapter cards on the market, the only alternative is to use a VGA and
 an 8514 as the two monitors. The following are the matching three
 lines for your OS/2 CONFIG.SYS file for that scenario:

    set video_devices=bvh_vga,bvh_8514
    set bvh_8514=device(bvh8514)
    set bvh_vga=device(bvhvga)

 Using this setup, the 8514 monitor displays the graphics output (or
 the Presentation Manager screen) and the VGA is the debug monitor and
 displays all text output.


 127. Debugging Large DOS Applications in CodeView 3.0 with /X /E /D

 Product Version(s): 3.00
 Operating System:   MS-DOS
 Flags: ENDUSER |
 Last Modified: 15-MAY-1990    ArticleIdent: Q61473

 CodeView version 3.00 includes enhanced support for debugging
 applications under DOS. CodeView 3.00 may access extended memory or
 expanded memory, or the size of the overlay swap area that CodeView
 uses may be adjusted.

 CodeView 3.00 offers three command-line parameters (/X, /E, and /D)
 for specifying memory utilization. If you DO NOT specify the /X, /E,
 or /D options when you start a CodeView session, CodeView will
 automatically search for extended memory. If CodeView finds extended
 memory, it will place the symbolic information and most of itself into
 extended memory (as long as enough extended memory is available).

 If there is no extended memory on your system, Codeview will search
 for expanded memory. If there is expanded memory, Codeview will place
 the symbolic information for your program in expanded memory.

 If there is no extended or expanded memory on your machine, CodeView
 will load itself, your application, and symbolic information for your
 program in base memory.

 Since CodeView does this automatic scan for extended and expanded
 memory, the /X and /E switches are needed only if you explicitly want
 to specify the use of one form of memory or the other and you do not
 want to enter CodeView if this memory type is not available.

 CodeView's /X option tells the debugger to load into extended memory
 ONLY, and to return an error message if extended memory is not
 available on your system. This message has the following form:

    CV1302 Error: /X : HIMEM.SYS not loaded

 CodeView's /E option tells the debugger to access expanded memory
 ONLY, and to return an error message if there is no expanded memory on
 your machine. This message has the following form:

    CV1304 Error: /E : EMM driver not loaded

 CodeView's /D option specifies that CodeView should use disk overlays.
 When you use this option, you can also specify a decimal size in
 kilobytes between 16K and 128K to explicitly set the overlay swap area
 size. The default size of the swap area is 64K if /D is used but no
 size is explicitly specified. If extended and expanded memory are not
 available, /D will not need to be specified for the default 64K
 overlay swap area to be used.

 A larger overlay swap area allows CodeView to run faster because it
 doesn't have to swap to disk as frequently as with a smaller swap
 area, but it means more memory is used up by CodeView itself. A
 smaller swap area allows you to debug larger applications under DOS,
 but CodeView runs slower because of the more frequent need to swap
 code from disk to memory.


 128. P70 Display Creates Problems Under CodeView and PWB

 Product Version(s): 3.00
 Operating System:   OS/2
 Flags: ENDUSER | buglist3.00 S_PWB S_Editor
 Last Modified: 15-AUG-1990    ArticleIdent: Q61557

 CodeView version 3.00 and Programmer's WorkBench (PWB) version 1.00
 have problems recognizing the built-in monitor of IBM P70 portables
 under OS/2. Symptoms of this problem include the following error
 messages:

    Product     Error Message
    -------     -------------

    CodeView    Internal Debugger Error 0 at load time
    PWB         Inability to change from 43-line mode

 Microsoft has confirmed this to be a problem with CodeView version
 3.00. We are researching this problem and will post new information
 here as it becomes available.

 This problem is directly related to the video configuration of the IBM
 P70. In its documentation, IBM mentions briefly that it might be
 necessary to type MODE CO80 to make some software recognize the
 built-in plasma display. An added condition for PWB and CodeView is
 the necessity of being in 43-line mode. PWB automatically places you
 in 43-line mode no matter what you previous mode was and thus gets
 around this limitation. If you attempts to change the height switch
 while editing, PWB doesn't complain but still stays in 43-line mode.

 CodeView cannot make the mode change in the same way that PWB can. If
 invoked without the above considerations, CodeView will crash with an
 Internal Debugger Error 0. The following are several ways to work
 around this problem if want to use CodeView with this type of
 configuration.

 1. Type MODE CO80 or BW80 and invoke CodeView with the /43 switch.

 2. Type MODE CO80,43 or BW80,43 before invoking CodeView.

 3. Use an external monitor with the built-in VGA port.

 4. Invoke CodeView from PWB, which makes the change automatically.


 129. CodeView Does Not Reset Initial Graphics Mode on Exit

 Product Version(s): 2.x 3.00    | 2.x 3.00
 Operating System:   MS-DOS      | OS/2
 Flags: ENDUSER |
 Last Modified: 29-MAY-1990    ArticleIdent: Q61611

 When CodeView exits, it leaves the screen in the current video mode
 and does not reset the mode to the mode that was active when CodeView
 was initially loaded.

 This behavior is by design. However, if you start CodeView with the /s
 option to enable screen swapping, the video mode that was active when
 CodeView was loaded will be reset because CodeView has separate
 swappable video memory pages to hold the output screen as well as the
 CodeView screen.


 130. CV 3.00 Gives R6000, Hangs When Accessing Help During Start-Up

 Product Version(s): 3.00
 Operating System:   MS-DOS
 Flags: ENDUSER | buglist3.00 fixlist3.10
 Last Modified:  5-FEB-1991    ArticleIdent: Q61919

 Accessing help in the "Enter directory for filename.c (cr for none)?"
 window results in the following error in CodeView version 3.00:

    run-time error R6000
    -stack overflow

 Then, the machine hangs requiring a cold reboot.

 To reproduce the error, do the following:

 1. Compile and link a program with symbolic information for CodeView.

 2. Delete or rename the source file and then go into CodeView. A
    window will appear asking you to "Enter directory for filename.c
    (cr for none)?".

 3. Choose the Help option at the bottom of the window. The run-time
    error message will be printed over the CodeView screen and the machine
    will be hung.

 The problem does not occur under OS/2.

 Microsoft has confirmed this to be a problem in CodeView version 3.00.
 This problem was corrected in CodeView version 3.10.


 131. CodeView 3.00 Fades with Monochrome VGA

 Product Version(s): 3.00   | 3.00
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified: 11-JUL-1990    ArticleIdent: Q61970

 If you invoke CodeView version 3.00 on certain machines with
 monochrome VGA monitors and then trace through several lines of code,
 the screen will fade and become unreadable. Exiting and re-entering
 CodeView refreshes the screen, but the screen immediately starts to
 fade again.

 This problem is caused by an error in the video ROM BIOS and has been
 verified to occur on the following machines:

 l. PS/2 Model P70 with monochrome VGA

 2. Siemens with Video 7 monochrome VGA

 3. Northgate 386 with Video 16 monochrome VGA

 The following are different methods of working around this problem:

 1. Switch into color mode using the mode CO80 command (may not have
    any effect).

 2. From the options menu inside Codeview, turn flip/swap off using
    the screen-swap option.

    If you don't want to give up flip/swap functionality, try option 3.

 3. If the video BIOS is replaceable, replace it with an updated video
    BIOS.

 4. If the video BIOS is not replaceable, replace the card.


 132. CodeView 3.00 Hangs on gets() with Screen Swap Off

 Product Version(s): 3.00   | 3.00
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER | s_c s_quickc s_quickasm
 Last Modified: 25-JUL-1990    ArticleIdent: Q62663

 CodeView 3.00 will hang if you step or execute past a call to the
 gets() run-time routine if the Screen Swap option is turned off.

 Sample Code
 -----------

 #include <stdio.h>

 char string[256];

 void main (void)
 {
     printf ( "Enter a string: ") ;
     gets ( string ) ;
     printf ( "Echoing : %s\n", string) ;
 }

 Compile the above file with the following:

    cl /Od /Zi test.c

 Bring the file up in CodeView, then select the Options.Screen Swap
 option. Next, step past the gets() call. Under DOS, your machine will
 hang, and under OS/2, the current screen group will be hung.


 133. DosSetMaxFH Between 0-39 Fails Under CodeView 3.00

 Product Version(s): 3.00
 Operating System:   OS/2
 Flags: ENDUSER | buglist3.00
 Last Modified: 25-JUL-1990    ArticleIdent: Q62666

 OS/2's DosSetMaxFH routine can be called to reset the OS/2 default
 limit of a maximum of 20 open file handles to a larger number. By
 definition, DosSetMaxFH fails when trying to set the number smaller
 than the current maximum amount of handles. Under OS/2, the default
 maximum number of files is 20, so a DosSetMaxFH to a number between
 0-19 should fail.

 However, under CodeView 3.00, calling DosSetMaxFH with a number
 between 0-39 will return a fail value.

 Sample Code
 -----------

 /* compile with : cl /Od /Zi file.c */

 #define INCL_DOSFILEMGR

 #include <stdio.h>
 #include <os2.h>

 void main(void)
 {
    int i;
    for ( i = 0 ; i < 1000 ; i ++ )

    if ( DosSetMaxFH ( i ) )
    {
       printf ( " DosSetMaxFH to %d failed!\n ",i ) ;
    }
 }

 This program prints the error message on parameters from 0 to 39.

 You can call the DosSetMaxFH routine to set at least 40 file handles
 to work around this problem.


 134. CV Limits Input of Period Character (2Eh) into Memory Window

 Product Version(s): 3.00 3.10 | 3.00 3.10
 Operating System:   MS-DOS    | OS/2
 Flags: ENDUSER | buglist3.00 buglist3.10 decimal point dot
 Last Modified: 31-AUG-1990    ArticleIdent: Q65241

 When viewing memory in byte format in a memory window in CodeView
 version 3.00 or 3.10, you cannot change the value of a byte in memory
 to the hexadecimal value 2E. The hex value 2E has an ASCII character
 equivalent of the period ("."). In CodeView, a period is used to
 display any nondisplayable character (for example, null, a carriage
 return, control characters, etc.), which means the period character
 can sometimes have special meaning to CodeView when it appears in a
 memory window.

 Because of the special usage of the period character in a memory
 window, CodeView does not allow periods to be typed directly into
 memory. In CodeView 3.00, attempts to change a byte value to 2E
 results in either the 2 or the E being entered and the other digit
 being ignored, depending on which value you enter first. In CodeView
 3.10, both the 2 and the E are returned to their original values once
 they have both been entered. If you move to the right side of the
 memory window where the ASCII equivalents are shown and you try to
 type in a period there, CodeView will also ignore that input.

 If you switch the memory window so that you are viewing memory in
 ASCII mode, actual periods can be typed in to any memory location.
 However, there is a problem with this because ALL other periods on the
 same line, which really represent various nondisplayable ASCII
 characters, are all converted to 2Es.

 If you use are viewing memory in a format other than bytes or ASCII,
 CodeView will allow a 2E to be entered. The workaround, then, if a
 period needs to be entered into memory, is to choose a different
 viewing mode other than ASCII or byte-mode, and then enter the period
 in the desired location as the value 2E. You can cycle through the
 available memory viewing modes by repeatedly pressing SHIFT+F3, or you
 can select the desired mode from the Memory Window option on the
 Options menu.

 Microsoft has confirmed this to be a problem in CodeView versions 3.00
 and 3.10. We are researching this problem and will post new
 information here as it becomes available.


 135. CV 3.00 Incorrectly Documents helpbuffer Switch as helpbuffers

 Product Version(s): 3.00   | 3.00
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER | docerr
 Last Modified: 25-FEB-1991    ArticleIdent: Q63236

 In the "Configure CodeView" section of the online help for CodeView
 version 3.00, the "helpbuffer" switch is incorrectly listed as
 follows:

    helpbuffers:<size>

 This switch should be spelled as follows:

    helpbuffer:<size>

 CodeView will not recognize the first spelling. The correct spelling
 was incorporated into the online help beginning with CodeView version
 3.10.


 136. CodeView Crashes in DOS on "Drive Not Ready" Error

 Product Version(s): 3.00
 Operating System:   MS-DOS
 Flags: ENDUSER | buglist3.00
 Last Modified: 25-JUL-1990    ArticleIdent: Q64026

 CodeView version 3.00 may hang after encountering a "Drive Not Ready"
 error. This error may occur if a file is opened on Drive A and a disk
 is not in the drive.

 To reproduce this problem, compile the following program with CodeView
 options (cl /Zi /Od):

    main () {
      FILE *fp;
      fp = fopen("a:\readme.doc","r");
    }

 If you run the program in CodeView version 3.00 without a disk in
 Drive A and press F5 to run the program, the following error will
 appear:

    Not ready reading drive A
    Abort, Retry, Fail?

 Regardless of what is typed, the machine will hang and you must do a
 cold reboot to remedy the crash.

 Note: CodeView versions 2.20 and 2.30 do not hang the machine if the
 above steps are executed. The fopen() just returns a NULL. OS/2 also
 handles the error correctly in versions 2.20, 2.30, and 3.00 of
 CodeView.

 Microsoft has confirmed this to be a problem with CodeView version
 3.00. We are researching this problem and will post new information
 here as it becomes available.


 137. CV1319 Error May Be Caused by CodeView DOS Extender

 Product Version(s): 3.00
 Operating System:   MS-DOS
 Flags: ENDUSER | buglist3.00 fixlist3.10
 Last Modified: 31-AUG-1990    ArticleIdent: Q65242

 Real-mode CodeView (CV) version 3.00 (shipped with Microsoft C 6.00)
 may encounter problems on certain computers when extended memory is
 utilized for debugging programs. These problems involve the processing
 of interrupts while CodeView 3.00's internal DOS extender is being
 used to run CodeView in protected mode in conjunction with HIMEM.SYS,
 the extended memory (XMS) driver.

 The problems manifest themselves in various ways, due to both the
 varied interrupt handling speeds of different machines and the varied
 interactions of CodeView itself running in protected mode while the
 DOS program being debugged is still being run in real mode. The most
 common error is a protection violation, which shows up in CodeView as
 either a CV1319 error (internal error - unrecoverable fault) or as a
 system hang. The errors usually occur when you are paging through the
 code or manipulating the mouse.

 Registered Microsoft C 6.00 owners who are experiencing any of these
 problems with CodeView version 3.00 are encouraged to call Microsoft
 Technical Support at [phone] to obtain information concerning a
 possible correction for these errors. However, there may be some cases
 where the only solution is to obtain a newer computer BIOS or to use
 CodeView without extended memory.
 Most reported problems have involved IBM PS/2 computers, but a number
 of these problems have also been reported on computers with an AMI
 BIOS. Note that CodeView version 3.10 includes modifications that are
 expected to eliminate most of these interrupt problems, but in some
 instances (especially with older AMI BIOS machines), an update of the
 BIOS may be the only solution.

 The easiest workaround to these protected-mode errors is to start
 CodeView without the use of extended memory. This can be done by
 removing the line in CONFIG.SYS that loads the HIMEM.SYS driver (and
 then rebooting the computer). Another option, if HIMEM is already
 loaded, is to start CodeView with the /D command-line option to
 specify explicitly that CodeView should use disk overlays, rather than
 extended or expanded memory. (Otherwise, if extended memory is
 available, CodeView will use the /X option by default.)

 Because these problems can occur only when CodeView is running in
 protected mode in extended memory, and because CodeView 3.00 requires
 HIMEM.SYS in order to run in protected mode, the problems are often
 mistakenly attributed to HIMEM.SYS. In reality, HIMEM.SYS is not
 responsible for the errors because it is just the memory manager that
 CodeView utilizes to get at extended memory. The errors are the result
 of an interrupt handling incompatibility between certain hardware
 configurations and the DOS extender built into CodeView.

 Microsoft has confirmed this to be a problem in CodeView version 3.00.
 This problem has been corrected in version 3.10.


 138. Label/Function Search Command Fails Under Codeview 3.00/3.10

 Product Version(s): 3.00 3.10 | 3.00 3.10
 Operating System:   MS-DOS    | OS/2
 Flags: ENDUSER | buglist3.00 buglist3.10
 Last Modified: 31-AUG-1990    ArticleIdent: Q65312

 Under CodeView versions 3.00 and 3.10, the Label/Function search
 command is described in the online help as performing a search of the
 current source window for an assembly-language label or function name.
 If the label is found, the debugger should switch from source to
 assembly mode to display a label in a library routine or assembly
 language module.

 In reality, this command fails with a message "Error - Unknown
 Symbol". The debugger does not switch into assembly mode. This problem
 can be reproduced by selecting Search from the CodeView menu, then
 selecting Label/Function and typing in "__chkstk" (without the
 quotation marks).

 Microsoft has confirmed this to be a problem with CodeView Versions
 3.00 and 3.10. We are researching this problem and will post new
 information here as it becomes available.


 139. Cannot Enable A20! with Orchid 386s

 Product Version(s): 3.00
 Operating System:   MS-DOS
 Flags: ENDUSER |
 Last Modified: 17-DEC-1990    ArticleIdent: Q65360

 Using HIMEM.SYS version 2.50 with Orchid 386/25 motherboards with the
 caching controllers can cause the following error message:

    Cannot enable A20!

 Orchid Technology has verified that this is a problem with the PAL
 chip on these motherboards. Customers who are experiencing this
 problem should call Orchid Technology at [phone] for an update
 of their PAL chip. Please have the revision of the motherboard on hand
 when calling.


 140. Mouse Cursor on Wrong Monitor During Dual-Monitor Debugging

 Product Version(s): 3.00 3.10
 Operating System:   MS-DOS
 Flags: ENDUSER | H_MOUSE
 Last Modified: 17-SEP-1990    ArticleIdent: Q65528

 Under certain conditions, when invoking real-mode CodeView (CV) in
 dual-monitor mode with /2, the mouse cursor appears on the wrong
 monitor. When this occurs, a "sprite" mouse cursor appears on the
 monitor that the application is to run on, while the secondary monitor
 where CodeView is running does not have a mouse cursor. Several
 workarounds to this problem are given below.

 The sprite mouse cursor is a "graphic" arrow cursor similar to that in
 Windows 3.00 or OS/2 Presentation Manager (PM), as opposed to the
 traditional "text" block cursor that usually appears when running
 CodeView or the Programmer's WorkBench (PWB).

 The problem of the mouse appearing on the wrong monitor occurs only on
 computers that have "extended register" video boards, such as some of
 the Video 7 VGA cards. Certain mouse drivers enable the sprite cursor
 when they detect these extended video registers. Because a monochrome
 monitor cannot support this extended mode mouse cursor, the cursor
 fails to switch to the secondary monitor when focus is switched to
 that monitor after CodeView is invoked with the /2 switch.

 The following are three possible workarounds to this problem:

 1. Upgrade to mouse driver version 7.04 or later. This version
    provides a new switch, /Y, which can be used with either the
    MOUSE.COM program or the MOUSE.SYS device driver. The /Y switch
    tells the mouse driver to disable the sprite cursor. The mouse
    driver update can be obtained free of charge by contacting
    Microsoft Product Support Services at [phone].

 2. If a mouse driver earlier than version 7.04 is used, the problem
    may be worked around by creating a batch file or adding the
    following commands to the AUTOEXEC.BAT file:

       mode mono
       mouse
       mode co80

    These commands will switch focus to the monochrome monitor while
    the mouse is being invoked and then will switch the focus back to
    the color monitor. This method will prevent the mouse driver from
    detecting the extended registers and using the sprite cursor.

 3. Disable the extended video registers. Check the video card
    documentation to see if this method is possible with your
    particular card.


 141. CV May Come Up Only in Monochrome with 8514/A Display Adapter

 Product Version(s): 3.00 3.10
 Operating System:   MS-DOS
 Flags: ENDUSER | appnote SV0337.ARC B_QuickBas
 Last Modified: 16-OCT-1990    ArticleIdent: Q65701

 Real-mode CodeView (CV) may display only in monochrome (black and
 white) mode on some systems with an 8514 or color VGA monitor attached
 to an 8514/A display adapter. On these systems, the installation of an
 8514/A video card causes the BIOS video functions to return an
 incorrect value indicating that a monochrome VGA monitor is attached,
 rather than a color monitor.

 This same BIOS information contributes to the way in which these
 versions of CodeView (and various other programs) detect the type of
 video adapter present; thus, CodeView may incorrectly determine that
 it is running on a monochrome system and may display the screen only
 in black and white.

 Workaround
 ----------

 As a workaround, an application note titled "8514/A Monochrome to
 Color Patch" is available from Microsoft Product Support Services by
 calling [phone]. This application note contains a program,
 which may be run before CodeView is invoked and which will configure
 the BIOS information correctly for CodeView to come up in color.
 The program is also available in the Software/Data Library by querying
 on SV0337, the Q number of the article, or S12719. SV0337 was archived
 using the PKware file-conversion utility.

 This monochrome video problem is specific to DOS, and therefore, does
 not occur with protected-mode CodeView (CVP) under OS/2. However, the
 problem may appear if real-mode CodeView is run in the DOS
 compatibility box under OS/2. In addition, the problem may occur with
 other software, such as Microsoft QuickBASIC.

 With CodeView, another symptom of this problem is that the program
 output screen (which can be accessed by pressing F4) will usually
 appear as dark blue characters on a black background. This screen is
 essentially unreadable and remains this way even after CodeView is
 terminated. Typing MODE CO80 at the DOS prompt after exiting CV should
 restore the system to the default colors.

 Microsoft intends to change the video detection routine in future
 software releases in order to circumvent this problem. Although the
 problem is not specifically caused by CodeView, a more sophisticated
 video detection routine will determine what video adapter and monitor
 are present without relying on the possibly inaccurate BIOS data.


 142. CV /E Avoids Windows 3.00 386 Enhanced Mode Protection Error

 Product Version(s): 2.35 3.00 3.10
 Operating System:   MS-DOS
 Flags: ENDUSER | SR# S900919-57 B_QuickBas B_BasicCom W_Win3
 Last Modified: 24-OCT-1990    ArticleIdent: Q65934

 When you start Microsoft CodeView under Windows 3.00 in a 386 enhanced
 mode DOS box, the following error message is displayed:

    You have attempted to run protected-mode application under 386
    enhanced mode. To run the application, exit and run Windows using
    either the WIN /s or the WIN /r command.

 However, using WIN /s or /r is unnecessary. To avoid the error
 message, start CodeView with the /E option to tell CodeView that
 expanded memory is available, as follows:

    CV /E

 This information applies to Microsoft CodeView versions 2.35, 3.00,
 and 3.10 for MS-DOS.
 Note that CodeView version 2.35 is shipped with Microsoft BASIC
 Professional Development System (PDS) version 7.00; CodeView version
 3.00 is shipped with Microsoft C Compiler PDS version 6.00; and
 CodeView 3.10 is shipped with Microsoft BASIC PDS version 7.10.

 You may find that after the error message is generated, if you return
 to the DOS box and wait a few seconds, CodeView will start up. To
 avoid the error message, start CodeView as follows with the expanded
 memory (/E) switch (where <filename.exe> is the name of the program
 you want to debug):

    CV /E <filename.exe>

 To increase the size of programs that can be loaded into CodeView in
 conjunction with the /E switch, you can create a PIF file for CodeView
 and specify -1 for the Expanded Memory KB Limit, which instructs
 Windows to give the program all the EMS that it needs.

 CodeView will run without the above error message in a Windows 3.00
 DOS box in standard mode, WIN /S.


 143. CV1319 Error May Be Caused by Generic Breakpoints

 Product Version(s): 3.00   | 3.10
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified: 24-OCT-1990    ArticleIdent: Q66215

 In some situations a program will hang with the CodeView
 initialization error CV1319 even though the program runs correctly
 outside of CodeView. Deleting any generic breakpoints in the
 CURRENT.STS file may resolve this problem. The following is an
 example:

    [debug-]
          genericbp='E 0x47:0x0007

 The problem is that when you recompile your program, the code moves
 and the absolute breakpoint may now be set in the middle of a
 multibyte instruction rather than the beginning of the instruction.

 Additional Workaround
 ---------------------

 Invoke CodeView with the /TSF ("Toggle StateFileread") option. This
 option will either read or ignore the CURRENT.STS file based on what
 the statefileread switch is set to in the TOOLS.INI file.

 For example, if the statefileread switch is set to "yes" (the default)
 and CodeView is invoked with the /TSF option, the CURRENT.STS file
 will be ignored.


 144. Running Out of Memory in CodeView with /X

 Product Version(s): 3.00 3.10 3.11
 Operating System:   MS-DOS
 Flags: ENDUSER |
 Last Modified: 24-OCT-1990    ArticleIdent: Q66230

 Under some circumstances, CodeView may still run out of memory while
 debugging large applications with the /X switch invoked to take
 advantage of extended memory with HIMEM.SYS. The debug information
 gets expanded when CodeView loads the program, so the following
 suggestions may help the problem:

 1. Don't use the quick compile (/qc) option. The symbolic information
    created by the quick compiler may expand much more when loaded by
    CodeView than the symbolic information created by the standard
    compiler. In addition, the quick compiler may create some duplicate
    debug references in the executable file. These duplicate references
    can take up significant memory when CodeView loads the program.

 2. Use the CVPACK utility, which is documented in the online
    documentation and on Page 21 of the "Microsoft C Reference" manual.
    CVPACK will compress the debug information in the file by removing
    duplicate references. Use the /P option to achieve maximum
    compression.


 145. CodeView Fails to Return Value in ES

 Product Version(s): 3.00 3.10 3.11
 Operating System:   MS-DOS
 Flags: ENDUSER | buglist3.00 buglist3.10 buglist3.11
 Last Modified:  9-NOV-1990    ArticleIdent: Q66507

 When CodeView is running in extended memory and a call is made to
 interrupt 15h function C0h, the value in the ES register is not
 changed. This interrupt call should return the segment of the system
 configuration table in the ES register. If CodeView is run with the /D
 or /E option, a value is returned in the ES register as it should be.

 Microsoft has confirmed this to be a problem in CodeView versions
 3.00, 3.10, and 3.11. We are researching this problem and will post
 new information here as it becomes available.

 Sample Code
 -----------

 main ()
   {
    _asm mov ah, 0xC0
   _asm int 0x15
   }


 146. Memory Requirements for Real-Mode CodeView (CV.EXE)

 Product Version(s): 3.00 3.10 3.11 | 3.00 3.10 3.11
 Operating System:   MS-DOS         | OS/2
 Flags: ENDUSER |
 Last Modified: 11-NOV-1990    ArticleIdent: Q66513

 Real-mode versions of CodeView (CV) beginning with version 3.00 offer
 a number of ways to utilize available memory in order to make the
 greatest amount of conventional memory available to the program being
 debugged. The amount of memory actually used depends on the
 command-line options specified as well as the configuration of the
 system used for debugging.

 The following table shows the size of CodeView in standard DOS memory
 with each of the memory-specific command-line options (see the "More
 Information" section below for further details):

    Option  RAM Usage                   Option  RAM Usage
    ------  ---------                   ------  ---------

     /X       16K                       /D16     210K
     /E      192K                       /D32     225K
     /D      256K (same as /D64)        /D128    320K

 The following descriptions of the three memory-related CodeView
 options explain the ways in which each option affects memory
 utilization in addition to the respective amounts of conventional
 memory that CodeView requires with each. (This information pertains
 only to CodeView versions 3.00 and later -- versions of CodeView
 earlier than 3.00 require approximately 230K of RAM specifically for
 CodeView.)

 /X - Specifies that CodeView should utilize extended memory. Assuming
      that enough extended memory is available, this option moves both
      the symbolic information and most of CV itself into extended
      memory. Allowing CV to be loaded into high memory requires that
      approximately 16K to 19K of "control" code remain in conventional
      memory, thus all free conventional RAM over 19K is available to
      load the program to be debugged (the "debuggee").

 /E - Specifies that CodeView should utilize expanded memory. Assuming
      that enough expanded memory is available, this option moves both
      the symbolic information and CodeView's own overlays into
      expanded memory. The size of the CV "root" without the extra
      overlayed code is approximately 192K. Since the overlays do not
      cause any additional overhead with /E, all free conventional RAM
      over 192K is available to load the debuggee.

 /D - Specifies that CodeView should utilize disk overlays in
      conventional memory. By default, this option creates a 64K buffer
      area for loading disk overlays. With the 192K root, the 64K
      buffer means CV will take about 256K of conventional memory with
      /D. In addition, the symbolic information must also be loaded
      into conventional memory; therefore, since symbolic data varies
      with each program, it is not possible to specify the amount of
      memory available for the debuggee alone.

      The /D option can also be specified with a value that indicates
      the size of the overlay buffer area. This parameter can be any
      value from 16 to 128, which represents an overlay buffer size
      from 16K to 128K. Specifying /D16 will minimize CodeView's size
      with disk overlays to approximately 210K. This maximizes the
      amount of conventional memory that will be available to load the
      debuggee and the symbolic information. At the other extreme,
      /D128 causes CV to use approximately 320K of conventional RAM.
      This provides faster CodeView execution speed, but it will only
      work with smaller debuggees.

 Note: CodeView will default to the best memory usage possible. In
 other words, if NO memory usage option is specified, CV will try to
 use extended memory. If extended memory is unavailable, CV looks for
 expanded memory. CV will use disk overlays on its own only if expanded
 memory is not found.


 147. CV2206 Warning: Corrupt OMF Detected in <filename>

 Product Version(s): 2.x 3.00 3.10 | 2.x 3.00 3.10
 Operating System:   MS-DOS        | OS/2
 Flags: ENDUSER | S_MASM H_MASM
 Last Modified: 11-NOV-1990    ArticleIdent: Q66702

 When trying to debug a Macro Assembler program with CodeView, the
 following message may appear:

    CV2206 Warning: Corrupt debug OMF detected in <filename>,
       discarding source line information

 The error occurs when code segments are not of class "CODE". Page 104
 of the "Macro Assembler 5.10 Programmer's Guide" states the following:

    The CodeView debugger also expects code segments to have the class
    name 'CODE'. If you fail to assign a class type to a code segment,
    or if you give it a class type other than 'CODE', then labels may
    not be properly aligned for symbolic debugging.

 This is also mentioned in the "CodeView and Utilities" manual under
 section 1.3.8 titled "Preparing Assembly Programs."

 The following is an example of the problem:

 _text segment para public   ; 'CODE' should be added to this line

 begin    proc
       mov ah, 4ch
       int 21h
 begin    endp

 _text ends
       end begin


 148. How to Execute a Function From the Command or Watch Window

 Product Version(s): 2.x 3.00 3.10 3.11 | 2.x 3.00 3.10 3.11
 Operating System:   MS-DOS             | OS/2
 Flags: ENDUSER | docerr s_c 6.00 6.00a
 Last Modified:  4-DEC-1990    ArticleIdent: Q67007

 Page 201 of the "Advanced Programming Techniques" (APT) manual that
 accompanies Microsoft C versions 6.00 and 6.00a states that "any C
 function in your program (whether user-written or from the library)
 can be called from the Command window or the Watch window."

 This statement is not completely true. Actually, only functions
 compiled with full CodeView symbolic information can be called. This
 restriction eliminates all of the C run-time functions from being
 executed in this manner because they contain no symbolic information.
 A simple example of how to call a C run-time function is shown below.

 If an attempt is made to execute a function that has not been compiled
 with symbolic information via the Command window, the following error
 will be displayed in the Command window:

    CV1017 Error: Syntax error

 In CodeView versions 2.x, an "unknown symbol" error is displayed in
 the Command window.

 If an attempt is made to add the function to the Watch window via the
 Watch menu and the "Add Watch" command, CodeView will ignore the entry
 and beep. In versions 2.x, CodeView will give an "unknown symbol"
 error.

 The APT gives an example of calling a C function from the Command
 window via the following command:

    ?funcname (varlist)

 This command will only invoke the function and display its return
 value in the Command window. To add the function to the Watch window,
 a slightly different command must be used, as follows:

    w?funcname (varlist)

 The function name can also be added to the Watch window by choosing
 the Watch menu and the "Add Watch" command, and typing only the
 function name plus its variable list enclosed in parenthesis. Neither
 the "w" or the "?" are needed in this situation.

 It is important to note that you should be sure that the screen
 flip/swap option on the Options menu is turned on if the function you
 execute performs any screen input or output.

 For example, if you want to call a C run-time function or any other
 function that does not contain CodeView symbolic information, you must
 create a shell function that calls the desired function itself and
 gives the same return value.

 Therefore, if you wanted to call the C run-time function sqrt()
 directly from the CodeView Command window or Watch window, you would
 create a shell function that resembles the following:

 1. #include <math.h>
 2. double my_sqrt(double x)
 3. {
 4.    return(sqrt(x)) ;
 5. }

 You would then compile this function with CodeView information by
 compiling with the /Zi switch, and then link it into your program
 being sure to include /CO in your link command. Note that your program
 does not need to make a call to the function in order for it to be
 available for direct execution.

 To execute this function from the Command window, enter the following
 command:

    ?my_sqrt(4.0)

 The return value should be displayed on the next line in the Command
 window. In this example, 2.0000000000000 should be displayed as a
 result of the square root of 4.0.

 To add the function to the Watch window via the Command window, you
 would enter the following command:

    w?my_sqrt(4.0)

 The function could also be added to the watch window by choosing the
 "Add Watch" command from the Watch menu and entering the following at
 the Add Watch prompt:

    my_sqrt(4.0)

 When a function is added to the Watch window, that function is
 executed any time the Watch window is updated.

 Although these examples show a constant value as the parameter to the
 function, any variable that is in scope at the time could be entered
 as a parameter.


 149. Syntax Error When Watching Variables That Begin with "P"

 Product Version(s): 2.20 2.30 | 2.20 2.30
 Operating System:   MS-DOS    | OS/2
 Flags: ENDUSER | buglist2.10 buglist2.20 fixlist3.00
 Last Modified: 18-NOV-1990    ArticleIdent: Q67008

 When the following command is entered in the Command window to watch a
 variable that begins with the letter "p", the result is a syntax
 error:

 > W pvariable

 The syntax for watching a memory location is W[type] range, where the
 type and range specify the format and length of memory to be
 displayed, respectively.

 When no type is declared, as in the above example, the default type is
 used. The default type will be the last type used by a Dump, Enter,
 Watch Memory, or Tracepoint Memory command. If none of these commands
 has been used during the session, the default type is byte.

 The workaround for this problem is to explicitly declare a type in the
 watch statement, for example:

 > WB pvariable.

 Microsoft has confirmed this to be a problem in Microsoft CodeView
 versions 2.x. This problem has been corrected in Microsoft CodeView
 version 3.00.

 Additional keywords: buglist2.30 buglist2.35


 150. CV1017: Syntax Error Can Be Caused by a Leading Zero

 Product Version(s): 3.00 3.10 3.11 | 3.00 3.10 3.11
 Operating System:   MS-DOS         | OS/2
 Flags: ENDUSER |
 Last Modified:  4-JAN-1991    ArticleIdent: Q67160

 Since CodeView treats all values with a leading zero as octal numbers,
 the following error is reported when the value is not a valid octal
 number:

    CV1017: syntax error

 To enter a number in hexadecimal form, the value must be preceded with
 "0x" (without the quotation marks). If the value is a number in
 decimal form, any leading zeros should be dropped.

 You can also use the "0n" prefix to specify decimal numbers,
 independent of the current radix.


 151. CodeView Asks for Path to a Source File Without Extension

 Product Version(s): 2.x 3.00 3.10 3.11 3.50
 Operating System:   MS-DOS
 Flags: ENDUSER | s_lib s_utility
 Last Modified:  4-DEC-1990    ArticleIdent: Q67271

 If an old version of the LIB utility is used to store OBJ modules in a
 library, the extension may not be stored. This can cause a problem if
 a module is compiled with debug information and an .EXE is built for
 CodeView to debug. When CodeView attempts to open the source file for
 the module in the library, it will fail because there is no extension.
 It will then prompt you for the filename.

 This is a problem with the Microsoft LIB utilities earlier than version
 3.08 and some third-party library managers. Beginning with LIB version
 3.08, the full filename is stored in the library.


 152. CodeView Does Not Debug kbhit() Correctly

 Product Version(s): 3.00 3.10 3.11  | 3.00 3.10 3.11
 Operating System:   MS-DOS          | OS/2
 Flags: ENDUSER | buglist3.00 buglist3.10 buglist3.11
 Last Modified:  4-DEC-1990    ArticleIdent: Q67360

 When setting a breakpoint between the kbhit() function and a function
 to read a character from the input stream, CodeView will grab the
 character from the input stream when the breakpoint is executed.

 The following code example demonstrates the problem. If a breakpoint
 is placed on the line containing the getch() function, the character
 input from the keyboard will be placed in CodeView before the getch()
 function is actually stepped over. You will not be prompted for the
 character when you step over the getch() function. The character you
 typed to stop the kbhit() loop will be used for the getch() function
 call when that line is executed.

 Microsoft has confirmed this to be a problem in CodeView versions
 3.00, 3.10, and 3.11. We are researching this problem and will post
 new information as it becomes available.

 Sample Code
 -----------

 #include <stdio.h>
 #include <conio.h>

 void main(void)
 {
         int a;

         do {
                 printf(".");
         } while(!kbhit());

         a = getch();         // put breakpoint here

         printf("%c\n", a);
 }






 Microsoft Linker
 =============================================================================


 1. Corrupted Library Causes Error L1102

 Product Version(s): 3.61 3.64 3.65 | 5.01.20 5.01.21
 Operating System:   MS-DOS         | OS/2
 Flags: ENDUSER |
 Last Modified:  6-DEC-1988    ArticleIdent: Q38201

 The link error "L1102: unexpected end-of-file" is generated when the
 linker attempts to resolve externals in a corrupted or null-length
 library.

 This error most commonly occurs with a combined library, mlibx.lib,
 that is corrupted during the library creation stage of SETUP. Make
 sure to check the \LIB subdirectory for odd or null size libraries.
 Library rebuilding is needed if insufficiently-sized libraries are
 found.

 The L1102 error can also be generated if you inadvertently type in the
 name of a used library at the "list file" prompt, as follows:

    Run File  [SPUD.EXE]:      main.exe
    List File [NUL.MAP]:       libname.lib    (generates faulty library)
    Libraries [.LIB]:          libname.lib
    Definition File [NUL.DEF]: main.def

 This process creates a map listing with the specified library name in
 the current working directory. Because this directory is searched
 before the directory specified in the LIB environment variable, the
 incorrect library containing the map listing is used during linkage,
 causing the error L1102.


 2. /I Linker Option Should Read /INF

 Product Version(s): 3.61 3.65
 Operating System:   MS-DOS
 Flags: ENDUSER | docerr
 Last Modified: 18-OCT-1988    ArticleIdent: Q30515

 Pages 266 and 267 of the "Microsoft C Optimizing Compiler CodeView and
 Utilities" manual for Versions 5.00 and 5.10 incorrectly list the
 shortened name of the /INFORMATION option as /I.

 If /I is given as an option, the result is an error stating that /I is
 an unrecognized option.

 The correct shortened name for /INFORMATION is /INF.


 3. Maximum Libraries LINK Can Handle

 Product Version(s): 3.x 5.01.20 5.01.21
 Operating System:   MS-DOS
 Flags: ENDUSER |
 Last Modified: 18-OCT-1988    ArticleIdent: Q31986

    LINK can handle no more than 32 libraries, i.e., on the LIBRARY
 prompt, you can specify up to 32 libraries.
    If you have more libraries, you have two choices: combine libraries
 or specify some of them at the object modules prompt. In the second
 case, LINK will treat the library as a collection of object modules,
 all of which should be included in your .EXE file.


 4. Maximum Number of Object Modules LINK Allows

 Product Version(s): 3.x 5.01.20 5.01.21
 Operating System:   MS-DOS
 Flags: ENDUSER |
 Last Modified: 18-OCT-1988    ArticleIdent: Q31987

    There is no limit to the number of object modules LINK allows;
 however, LINK can operate only in certain limits imposed by the amount
 of available resources.


 5. The Meaning of an Invalid Object Module

 Product Version(s): 3.x 5.01.20 5.01.21
 Operating System:   MS-DOS
 Flags: ENDUSER |
 Last Modified: 13-OCT-1988    ArticleIdent: Q31988

 An invalid object-module error message means that an object module
 does not conform to Microsoft object format. The description of object
 format can be found in "MS-DOS Encyclopedia Part E: Programming Tools
 Article 19: Object Module."


 6. Object Modules Handled by LINK

 Product Version(s): 3.x 5.01.20 5.01.21
 Operating System:   MS-DOS
 Flags: ENDUSER |
 Last Modified: 15-JUL-1988    ArticleIdent: Q31989

    Successive versions of LINK always are backward compatible, but not
 necessarily upward compatible, i.e., the most recent versions should
 link any existing object module, but not necessarily any future object
 module.
    To solve this problem, update to the latest version of LINK.



 7. How LINK Orders and Combines Segments

 Product Version(s): 3.x 5.01.20 5.01.21
 Operating System:   MS-DOS
 Flags: ENDUSER |
 Last Modified: 15-JUL-1988    ArticleIdent: Q31991

    Every segment belongs to a named class such as 'CODE', 'DATA', or
 'BSS'. LINK orders all segments with the same class name contiguously.
    Within each class, segments are placed in the same order as LINK
 encounters them. Segment classes are placed in the order they appear.
 If you do not give a class name when you define a segment in assembly,
 the segment gets the null class, which is treated like any other segment.
 If the /DOSSEG option is given, or one of the Microsoft language run-time
 libraries is used, LINK imposes the following additional order:

       code (class ending in 'CODE')
       far data (everything but DGROUP and 'CODE')
       DGROUP - the default data segment
           class 'BEGDATA' (special runtime segment)
           near initialized data (everything but 'BSS' and 'STACK')
           near BSS--uninitialized data  (class 'BSS')
           stack



 8. Link Error L1053 Symbol Table Overflow

 Product Version(s): 3.x 5.01.20 5.01.21
 Operating System:   MS-DOS
 Flags: ENDUSER |
 Last Modified: 13-OCT-1988    ArticleIdent: Q31992

 Question:

 I am receiving link error L1053: symbol table overflow. What is the
 limit of the symbol table?

 Response:

 Under MS-DOS, this limit using the DOS-only linker (Versions
 3.x) is dependent on the amount of available memory in your computer.
 LINK can use all conventional memory available under DOS (up to 640K).

 Under OS/2, the segmented-executable linker (Versions 5.x and above)
 has no limit on the size of the symbol table because it extends the
 symbol table in virtual memory.


 9. Temporary Files Created at Link Time

 Product Version(s): 3.x 5.01.20 5.01.21
 Operating System:   MS-DOS
 Flags: ENDUSER |
 Last Modified: 22-JUL-1988    ArticleIdent: Q31993

    The linker creates a temporary file when it runs out of memory to
 hold the symbol table or the load image and run-time relocations of
 the program being linked.



 10. How Overlays Are Set Up By the Linker

 Product Version(s): 3.x 4.06 4.07 5.01.20 5.01.21 5.03
 Operating System:   MS-DOS
 Flags: ENDUSER |
 Last Modified: 26-JAN-1990    ArticleIdent: Q31994

 The overlay linker uses an interrupt to call in overlaid files. By
 default, the interrupt number used for passing control to overlays is
 63 (3f hex).

 The linker links the Microsoft overlay manager from the standard
 Microsoft language run-time libraries. The linker assigns segments to
 overlays based on the grouping you indicate. It replaces
 overlay-to-overlay far calls and root-to-overlay far calls with an
 interrupt sequence that calls the overlay manager. The overlay manager
 swaps overlays if necessary and returns control to the program.

 The linker replaces root-to-overlay and overlay-to-overlay far calls
 with the following sequence:

    INT     3Fh         ; can change # with /OVERLAYINTERRUPT:#
    DB      ?           ; target overlay segment number, where
                        ; every non-root code segment is numbered
                        ; starting at 1
    DW      ?           ; target offset within segment

 The interrupt handler is set to the overlay manager code that swaps
 out the resident overlay if necessary and swaps in the target overlay,
 then jumps to the target address. The overlay manager does nothing
 unusual in servicing the interrupts; it does not disable interrupts.
 However, it may issue INT 21h calls to swap overlays.

 The overlay manager assumes that once your initialization code has
 been executed, DS and SS will always be the same. Furthermore, it
 assumes you will initialize DS and SS to the value of DGROUP (the
 default data segment defined by Microsoft languages). Note that your
 program also must have a stack segment.

 A more detailed description of the overlay manager can be found on
 Page 715 of the "MS-DOS Encyclopedia," "Article 20: The Microsoft
 Object Linker."


 11. Why the First Module in the Code Segment Starts at Offset 16

 Product Version(s): 3.x 4.06 4.07 5.01.21 5.03 | 5.01.21 5.03
 Operating System:   MS-DOS                     | OS/2
 Flags: ENDUSER | s_c s_quickc s_quickasm h_masm h_fortran
 Last Modified: 14-FEB-1990    ArticleIdent: Q58688

 Question:

 Under some circumstances, I get 16 zero bytes at the beginning of my
 code segment. I'm linking with my own replacement C library with
 start-up code. The entry point to this start-up module is the first
 item in the module, and it always ends up at offset 16. Why is this?

 Response:

 The linker will insert 16 bytes at the beginning of the code segment
 if it determines that you are using standard segment naming
 conventions (/MS-DOSSEG) and the NULL segment is not explicitly
 removed (/NONULLSMS-DOSSEG). In your case, the linker assumes that you
 need support for signal() and allocates the first 16 bytes for it.

 Note: This will always be done for C programs by the compiler.


 12. Linker Outputs Information with Invalid Object Module

 Product Version(s): 3.x 5.01.20 5.01.21
 Operating System:   MS-DOS
 Flags: ENDUSER |
 Last Modified: 15-JUL-1988    ArticleIdent: Q31999

    When an invalid object-module error message occurs, some
 information about the record and the position is printed.
    This information includes the object record type and the relative
 position of the record in the .OBJ file. There is little you can do
 with this information; it is mainly for compiler and assembler
 developers to point to the wrong object record.


 13. Incremental Linking

 Product Version(s): 3.x 5.01.20 5.01.21
 Operating System:   MS-DOS
 Flags: ENDUSER |
 Last Modified: 15-JUL-1988    ArticleIdent: Q32000

    The following is a description of the incremental-linking process.
    Your file is built from a set of .OBJ files. Each .OBJ file is
 produced by the compiler or assembler from a source file. If a set of
 .OBJ files is large, then linking time can be long. If you change only
 one source file (i.e., in your set of .OBJ files you have one new .OBJ
 file), you can link all .OBJs one more time, or patch your .EXE file
 with the new .OBJ file. This patching is called incremental linking.
    Incremental linking only is supported for OS/2 and Windows
 programs.



 14. Explanation of a MAP File

 Product Version(s): 3.x 5.01.20 5.01.21
 Operating System:   MS-DOS
 Flags: ENDUSER |
 Last Modified: 15-JUL-1988    ArticleIdent: Q32001

    A MAP file gives you a picture of how your code and data are
 arranged in memory when the program is loaded.
    First you get the list of segments in the order in which they will
 be loaded into memory. For each segment, you have its starting
 address, length, name, and class. Following the segments are groups,
 each specifying the starting address of the group.
    If you specify the /MAP switch and list filename, in the MAP you
 will get two lists of public symbols in your program. The first list
 will be sorted alphabetically, the second by addresses.
    If you specify the /LINENUMBERS switch, then in the MAP, you will
 get line numbers and the associated addresses of your source program.
 To produce line numbers in the MAP, give LINK an object file with
 line-number information. Use the /Zd option with any Microsoft
 compiler to include line numbers in the object file.
    Information from the MAP will help you debug your program and
 understand how the program is loaded into memory.


 15. L1087: "Unexpected End-of-File on Scratch File"

 Product Version(s): 3.x 5.x  | 5.10
 Operating System:   MS-DOS   | OS/2
 Flags: ENDUSER |
 Last Modified: 13-OCT-1988    ArticleIdent: Q34669

 The Link Utility generates the error message L1087: "unexpected
 end-of-file on scratch file" when a disk with the temporary linker
 output file has been removed. This information is documented in the
 "Microsoft Macro Assembler CodeView and Utilities Guide."

 The error message L1087 also can be caused by insufficient memory
 available on the disk that contains the temporary linker output file.
 The disk can be a hard disk, floppy disk, or RAM disk.


 16. Assigning Addresses to Overlay Segments

 Product Version(s): 3.x 5.01.20 5.01.21
 Operating System:   MS-DOS
 Flags: ENDUSER |
 Last Modified: 15-JUL-1988    ArticleIdent: Q32003

    The linker assigns only code segments (identified by class names
 ending in "CODE") to overlays. Data segments go in the root. The
 particular overlay the segment goes in is determined by the module
 that first defines the segment.

    Note that the linker assigns segments, not object modules, to
 overlays. Therefore, if you have the following command

     LINK A+(B+C)

 where

     A   defines public SEG1
     B   defines public SEG2
     C   defines public SEG1

 then C's contribution to SEG1 goes in the root, not in the first
 overlay, because SEG1 was first defined in a root module.
    The linker orders all segments as it normally would, ignoring the
 overlays and using the class and combine-type rules described
 elsewhere. The linker then assigns addresses for every segment in the
 root up to the first overlay segment. Before the first overlay
 segment, it defines a special empty segment called OVERLAY_AREA. Then
 for each overlay it assigns addresses for every segment in the overlay
 so that the first segment in the overlay starts at OVERLAY_AREA. One
 particular overlay will end at a higher address than all the others;
 at this address, the linker defines a special empty segment called
 OVERLAY_END. Finally, the linker assigns addresses for all remaining
 segments in the root so that the first one starts at OVERLAY_END. The
 load image looks like the following:

         ------------+-> 0000
         |           |
         |  root     |
         |           |
         +-----------+-> OVERLAY_AREA
         |  overlay  |
         |  area     |
         |           |
         +-----------+-> OVERLAY_END
         |  root     |
         +-----------+

    The resultant MAP file has some different contents than the
 pre-overlay file. All items listed are declared as "res", meaning
 resident. The items contained within the overlay modules are also
 declared as "res".
    At the top of the MAP file, the segments are listed in the exact
 order in which they will be in the load image, and each segment is
 identified as being in a particular overlay or the root.
    Every symbol marked "res" is in a root segment and every symbol
 marked "ovl" is in an overlay segment. If symbols are not where you
 think they ought to be, remember the linker assigns segments, not
 modules, to overlays.
    For more information on overlays, refer to the 1988 "MS-DOS
 Encyclopedia."


 17. Link Error L1089

 Product Version(s): 3.51 3.55 3.60 3.61 3.64 3.65 5.01.20 5.01.21
 Operating System:   MS-DOS
 Flags: ENDUSER |
 Last Modified: 22-JUL-1988    ArticleIdent: Q32829

    If you are receiving the following error message, check to see if
 the TMP environment variable is set correctly:

    L1089   'filename' : cannot open response file

   If the TMP variable is not set, temporary files cannot be created
 and this error may occur.



 18. Cannot Overlay Small-Model Code

 Product Version(s): 3.60 3.61 3.64 3.65 5.01.20 5.01.21
 Operating System:   MS-DOS
 Flags: ENDUSER |
 Last Modified: 12-OCT-1988    ArticleIdent: Q34294

 Problem:

 I have specified overlays for my small-model code, but the link map
 shows that no overlays are produced.

 Response:

 You cannot overlay small-model code. You must change the memory model
 to medium, large, or huge. Page 285 of the "Microsoft CodeView
 Utilities" manual that comes with C Versions 5.00 and 5.10, MASM
 Versions 5.00 and 5.10, and Pascal Version 4.00, and Page 135 of the
 "Microsoft FORTRAN Optimizing Compiler User's Guide" states that you
 can overlay only modules to which control is transferred and returned
 by a standard 8086 long (32-bit) call/return instruction.


 19. Link Error 4051

 Product Version(s): 3.60 3.61 3.64 3.65 5.01.20 5.01.21
 Operating System:   MS-DOS
 Flags: ENDUSER |
 Last Modified: 22-JUL-1988    ArticleIdent: Q32831

    If you receive link error 4051, check the following:

    1. Is the LIB environment variable set correctly? Check
       for spaces around the equal sign or any extra characters
       at the end of the line.
    2. Which version of the linker is being used? Old versions of
       the linker do not recognize the LIB environment variable.
          Make sure the linker being used is the one that came with
       the product.
    3. Are the library names being asked for component libraries or
       combined libraries? Libraries compiled under C Version 4.00 or
       earlier have component library names embedded in the .OBJ files.
       With later versions of the C compiler, combined libraries are used
       and the component libraries will not be found.
          This behavior also exist when upgrading from Pascal Versions 3.32
       or earlier to Pascal Versions 4.00 or greater.
          The work-around for this behavior is to recompile all .OBJ file
      (and libraries) with the new compiler or to use the /NOD switch
      when linking, and specify all the libraries (combined and otherwise)
      to be used. The following is an example:

             link /NOD  test,,,llibce.lib;

    4. Is the correct library available for the math option chosen?
    FORTRAN defaults to the co-processor library (e.g. LLIBFOR7.LIB).
    C and Pascal default to the emulator math library (e.g. SLIBCE.LIB
    and LIBPASE.LIB)



 20. LINK /CO /DO in OS/2 Gives Protection Violation

 Product Version(s): 5.01.21 | 5.01.21
 Operating System:   MS-DOS  | OS/2
 Flags: ENDUSER | buglist5.01.21
 Last Modified: 13-OCT-1988    ArticleIdent: Q34374

 The Microsoft Segmented Link Utility Version 5.01.21 will
 incorrectly generate a protection violation under OS/2 when the
 command line uses the options /CO /DO, respectively.

 OS/2 gives the message SYS1943: "A program caused a protection
 violation." The SYS1811 violation follows, indicating the process has
 stopped.

 The work around for this problem is to order the switches differently.
 Instead of including /CO /DO in the command line, the command line can
 be reorder to /DO /CO.

 Microsoft has confirmed this to be a problem in Version 5.01.21. We are
 researching this problem and will post new information as it becomes
 available.


 21. /NOE Option for Redefinition Error L2044

 Product Version(s): 3.x 5.x | 5.10
 Operating System:   MS-DOS  | OS/2
 Flags: ENDUSER |
 Last Modified: 13-OCT-1988    ArticleIdent: Q34502

 The /NOEXTDICTIONARY switch tells the linker NOT to take advantage of
 additional information recorded in Extended Dictionary in the library
 file. This additional information describes which module in the library
 calls any other module from the same library, saving linker number
 of passes through the library file to pick up all required modules.

 If you have a call in your code to the library function FOO and FOO
 calls another function BAR from the same library, then at processing
 time of FOO, the linker will pull out BAR. This process occurs because
 the extended dictionary has a link between FOO and BAR.

 Linking without /NOE causes the following error if you want to pull
 FOO in from the library but you want to provide its own BAR:

 L2044 BAR : symbol multiply defined, use /NOE

 This error resulted from the linker pulling FOO and BAR from the
 same library, then later it sees BAR coming from user .OBJ file.

 Using /NOE in this case prevents the linker from pulling out
 BAR from the library, so your BAR routine is used instead.

 If you have genuine symbol redefinition, then when linking with /NOE
 you will see the following error:

 L2025 BAR : symbol defined more than once


 22. L2001 Fixups without Data

 Product Version(s): 3.65 5.01.21 | 5.01.21
 Operating System:   MS-DOS       | OS/2
 Flags: ENDUSER |
 Last Modified: 12-OCT-1988    ArticleIdent: Q35155

 The Link Utility can generate the linker error message L2001:
 fixup(s) without data. In the manual, the linker error is described
 as follows:

 A FIXUPP record occurred without a data record immediately
 preceding it. This is probably a compiler error. (See
 the "Microsoft MS-DOS Programmer's Reference" for more information
 on FIXUPP.

 In most cases, the error message is generated from an
 assembly-language program that doesn't make sense from the linker's
 point of view, but is convenient for users. The following is an
 example:

     extrn   foo:word

     ABSEG   segment at 123          ; absolute segment

     dw      offset DGROUP:foo       ; offset portion of address of "foo"

     ABSEG   ends

 This tells the linker to fix up a location in ABSEG with the address
 of foo. But ABSEG is an absolute segment and has no data to be fixed
 up.

 Another example is when you include the same STRUC definitions in both
 absolute and non-absolute segments, so that the STRUC definitions
 contain relocatable addresses.



 23. Setting the Overlay Interrupt (/O) in LINK

 Product Version(s): 3.61 3.65
 Operating System:   MS-DOS
 Flags: ENDUSER | docerr
 Last Modified: 20-JAN-1989    ArticleIdent: Q40408

 Question:

 Page 272, Section 12.2.12, of the "Microsoft CodeView and Utilities
 Software Development Tools for the MS-DOS Operating System" manual
 states that you can change the default overlay interrupt. The default
 interrupt is 3F hexadecimal. Is the manual correct? Do you have to
 change the interrupt if you have a program that uses overlays and it
 spawns a program that also uses overlays?

 Doesn't the compiler save interrupts? Suppose both Programs A and B
 use overlays and A spawns B. If B is a Microsoft C Version 5.00 or
 5.10 program, shouldn't it restore the original INT 3F address when it
 exits? Thus, everything should work correctly without
 /OVERLAYINTERRUPT.

 Response:

 You are correct; the C Versions 5.00 and 5.10 compiler saves and
 restores the interrupt so there should be no conflict. The C Versions
 5.00 and C 5.10 manual is incorrect. This switch need only be used if
 you are linking a program with overlays, and INT 3F is being used by
 something else when you run the program. For example, INT 3F might be
 used to communicate with a hardware board or a TSR might use it;
 however, this is unlikely.

 This option is for advanced users who know their configurations well
 enough to know who is using which interrupt vectors and know there is
 a conflict.


 24. LINK Environment Variable Ignored When Linking Through CL

 Product Version(s): 5.00 5.10 | 5.10
 Operating System:   MS-DOS    | OS/2
 Flags: ENDUSER | S_C S_QuickC
 Last Modified: 15-AUG-1989    ArticleIdent: Q47503

 Problem:

 To increase the size of my stack, when I set an environment variable
 called LINK equal to /ST:4096, it doesn't work correctly when I link
 using CL.

 Response:

 Before CL spawns the linker, it clears the environment of all
 variables except LIB. Consequently, the LINK environment variable
 doesn't exist when the linker is invoked, and any options that were
 specified by it are not seen. When linking with CL, any desired linker
 options should be specified on the CL command line after the /link
 switch.

 The same behavior is seen with the command line compilers from QuickC
 Version 1.00 and 1.01, but not with QuickC 2.00 or QuickAssembler.


 25. Why Unitialized Global Variables Don't Appear in C 5.10

 Product Version(s): 3.65
 Operating System:   MS-DOS
 Flags: ENDUSER | SR# G881021-5044
 Last Modified:  6-DEC-1988    ArticleIdent: Q38725

 Questions:

 Why don't uninitialized global variables show up in the library
 listing when the module containing them has been placed in the
 library? It appears that the librarian does not "see" uninitialized
 global variables.

 If my main program declares an extern, and an .OBJ with which its
 linked declares it globally (without extern), but doesn't initialize
 it, the symbol appears in the link map and space is allocated for it
 in the .EXE. This behavior seems different from previous versions of
 the compiler. If the .OBJ file is placed as a library rather than
 linked explicitly, the symbol does not appear in the .EXE. Why does it
 behave differently?

 Response:

 In Version 5.00 of the C Compiler, we introduced a new concept into
 our linking process called "communal data." Communal data can be
 declared in many modules, but only one copy of the data will exist
 in the linked .EXE file. (It is similar to the concept of COMMON
 blocks in FORTRAN.)

 In C, data declared outside of a function without a storage class is
 now considered to be communal data. (This is a change from previous
 versions.) Communal data declarations generate no definitions, just
 declarations; whereas initialized, or global, data declarations
 generate both definitions and declarations.

 Communal declarations may refer to a global definition. If they do,
 the linker simply adjusts the address as necessary. However, if
 there is no global definition of the variable, the linker combines
 the declarations into one definition and allocates the appropriate
 amount of space. For example, it is legal to declare

    int x;

 in several different modules without a corresponding

    int x = 0;

 Communal declarations are NOT copied into libraries. (This is
 documented on Page 84 of the "Microsoft C Language Reference Manual.")
 If you want the variable to appear in a library, it MUST be
 initialized so that it is global rather than communal. Communal
 variables are not included in libraries because they can cause
 strange conflicts. For example, let's suppose you
 unwittingly used a variable name that was also the name of a communal
 variable in your library. At link time, the linker would allocate
 only ONE copy of that variable without generating any warning.

 The symptom would be that your variable would mysteriously change
 every time you called the library function that used the communal
 variable. This problem would be a very difficult to trace.

 Now that we understand communal variables and how they interact with
 libraries, we can answer your questions.

 The first question was basically, "Why don't my communal variables
 show up in the library listing?" Because communal data is not placed
 into the library, it won't show up in the listing.

 The second question was, "How come the communal variable shows up in
 the .EXE file if I link it from an .OBJ file but not from a .LIB
 file?" It shows up from the .OBJ file because the communal variable
 is allocated space by the linker if it doesn't resolve to a global
 definition. It does NOT appear in the link produced by the .LIB file
 because it does not appear in the library dictionary.

 Note: this behavior is the result of doing something we ask you not to
 do; namely, putting communal data in a library. Data intended to be
 placed in a library must be initialized.


 26. Example of Using a Response File with LINK

 Product Version(s): 3.65   | 5.01.20
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified: 20-JAN-1989    ArticleIdent: Q40429

 The following is a small example of using a response file with LINK.

 A response file contains responses to the LINK prompts. The responses
 must be in the same order as the LINK prompts.

 LINK treats the input from the response file just as if you had
 entered it in response to prompts or in a command line. It treats any
 carriage-return-linefeed combination in the response file the same as
 if you had pressed the ENTER key in response to a prompt or included a
 comma in a command line.

 Note: You cannot put comments in response files.

 The following is an example of a file named RESPONSE.ONE:

 file1 file2 file3 file4
 /pause /map
 filelist
 graphics.lib

 Type the following at the command line:

    LINK @response.one


 27. Error L2025: Symbol Defined More than Once

 Product Version(s): 5.10   | 5.10
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified: 20-JAN-1989    ArticleIdent: Q40485

 Problem:

 I cannot link a function name in my object file with a library
 containing that same function name and have the resulting EXE call my
 function and not the library's.

 I am using /NOE; however, I receive the following error:

 (...): error L2025: (my function name) : symbol defined more than once
  pos: (some number) Record type: 53E8

 Response:

 You can only perform this task if the function name is an individual
 module. The following procedure demonstrates the error:

 1. Create a file CALL.C that calls functions A() and B().

 2. Create functions A() and B() in fileA.c and fileB.c, and compile
    them to objects.

 3. Do the following to create TEST.LIB:

       LIB TEST +fileA +fileB, test.lst

 4. Change B() in fileB.c and compile the following:

       cl call.c fileB.c test.lib /link /NOE /INF

    You will have an EXE that calls A() from the library and B() from
    your modified fileB.c.

 5. Combine fileA.c and fileB.c into one file called TEST.C.

 6. Compile to object code.

 7. Delete the old TEST.LIB, and do the following:

       LIB TEST +test, test.lst

    (Normally you would change fileB.c, but this is not necessary here.)

       cl call.c fileB.c test.lib /link /NOE /INF

 You will receive the following error:

 TEST.LIB(test.c) : error L2025: _B : symbol defined more than once
  pos: 13E Record type: 53E8
 There was 1 error detected

 When you encounter this error, it is usually because the function you
 are trying to overwrite is part of a set appearing in one module.

 The library listing looks as follows in the first case:

 _A................fileA             _B................fileB

 fileA             Offset: 00000010H  Code and data size: 95H
   _A

 fileB             Offset: 000002a0H  Code and data size: 92H
   _B

 You will be able to replace A() or B(). The listing in the
 second example looks as follows:

 _A................test              _B................test

 test              Offset: 00000010H  Code and data size: deH
   _A                _B

 You will not be able to replace either A() or B() without removing the
 TEST module with the LIB utility. You may have to provide replacements
 for both functions and not just the one you want to change. For more
 information, query on the following words in this KnowledgeBase:

    L2029 unresolved externals


 28. Default for NODATA When Using the _export Keyword

 Product Version(s): 5.01.21 | 5.01.21
 Operating System:   MS-DOS  | OS/2
 Flags: ENDUSER | buglist5.10.21 buglist5.02 fixlist5.03
 Last Modified: 21-AUG-1989    ArticleIdent: Q47826

 Question:

 What is the default for NODATA when using the _export keyword? The
 _export keyword is used to mark functions in DLLs for export. It
 appears that for real-mode windows, for normal applications, _export
 does not use NODATA. However, for DLLs (also for real-mode windows)
 _export marks the function NODATA. How does the keyword _export mark
 functions (NODATA or not).

 Response:

 The default as issued by the compiler is not NODATA, i.e., the
 exported routine is assumed to use the shared data segment.
 Unfortunately, the linker has a problem that causes it to mistakenly
 assume NODATA for all exports declared from the .OBJ file.

 Microsoft has confirmed this to be a problem with LINK Version 5.01.21
 and 5.02. The problem was corrected in LINK Version 5.03 and later.

 In OS/2 this should not make any difference. In Windows, the program
 loader looks for the -Gw sequence in the prolog of the exported entry
 and replaces it with a sequence to load DS. The _loadds keyword will
 generate the load-DS sequence in the first place.

 In any case, a workaround is to not use the _export keyword and
 declare the routine in EXPORTS in the .DEF file.


 29. No Default Extension for a Linker Response File

 Product Version(s): 3.55 3.60 3.61 3.64 3.65  | 5.01.21 5.01.21
 Operating System:   MS-DOS                    | OS/2
 Flags: ENDUSER |
 Last Modified:  2-MAR-1989    ArticleIdent: Q41611

 The Microsoft Overlay Linker does not have a default extension for a
 response file; unlike Phoenix's PLINK, which uses a default .LNK
 extension.

 This information also applies to the Microsoft Segmented-Executable
 Linker.


 30. Ambiguous Switch /PAC with QuickC 2.00 Linker

 Product Version(s): 4.06
 Operating System:   MS-DOS
 Flags: ENDUSER | s_quickc b_quickbas docerr
 Last Modified: 22-JAN-1990    ArticleIdent: Q42027

 Using the /PAC switch with LINK Version 4.06 results in the
 following error:

    fatal error L1001: PAC : option name ambiguous

 This same option works correctly on Versions 3.65 and 5.01.21, and is
 documented as being a valid shorthand name for /PACKCODE on Page 131
 of the "QuickC Tool Kit."

 The problem is due to a conflict with an option that is not documented
 in the Tool Kit, but is displayed when LINK is invoked with /HELP. The
 option that causes the ambiguity is /PACKDATA, which causes data
 segments to be combined.

 The shortest version of /PACKCODE that can be used is /PACKC.
 Similarly, /PACKD is the shortest version of /PACKDATA that can be
 used.


 31. /CO before /DO Causes Problems in LINK

 Product Version(s): 3.65 4.06 5.01
 Operating System:   MS-DOS
 Flags: ENDUSER | h_masm s_pascal h_fortran buglist3.65 buglist5.01
 Last Modified: 28-MAR-1989    ArticleIdent: Q42212

 When compiling or assembling with the /Zi switch to include CodeView
 symbolic information and linking with /CO to preserve it, the
 placement of the /DO switch is crucial. If the /CO switch is specified
 before /DO, the following behavior may occur when running CodeView:

    Message                                Behavior

    Enter directory for  (cr for none)?    When CodeView is executed,
                                           no source code will appear.

    Unable to open file

    Internal debugger error: 13            When attempting to change
                                           from assembly view to source
                                           CodeView. Hanging of the
                                           machine when executing
                                           CodeView.

 If switching the order of the /CO and the /DO switches does not
 take care of the problem then you have to put the .DOSSEG into
 your MASM routines and not use the /DO switch.

 Microsoft has confirmed this to be a problem in Versions 3.65 and
 5.01. We are researching this problem and will post new information as
 it becomes available.

 While LINK Version 5.01 may be used in OS/2, the /DO switch has no
 meaning. Using it, however, causes the linker to GP fault if /CO
 precedes /DO.



 32. Unimplemented Switch /BI with QuickC 2.00 Linker

 Product Version(s): 4.06
 Operating System:   MS-DOS
 Flags: ENDUSER | S_QUICKC
 Last Modified: 24-JAN-1990    ArticleIdent: Q42849

 The /BINARY switch for Link Version 4.06 is documented on Page 122 of
 the "Microsoft QuickC Tool Kit" as a switch used to create .COM files
 for assembly-language programs. Its shorthand version is /BI. This
 switch is an alternative to creating .EXE files and then running them
 through EXE2BIN.

 This switch is currently not implemented, a fact documented in the
 README.DOC on line 665, "Creating a .COM file." Using it will result
 in the following error:

     fatal error L1002: BINARY : unrecognized option name


 33. How /NOE (No Extended Dictionary) Is Used by the Linker

 Product Version(s): 3.65 4.06 5.01 | 5.01
 Operating System:   MS-DOS         | OS/2
 Flags: ENDUSER | S_C H_FORTRAN S_QUICKC
 Last Modified:  6-APR-1989    ArticleIdent: Q43009

 This article contains information about the LINK option /NOE and how
 it relates to the three following topics:

 1. The Extended Dictionary and how LINK uses it

 2. The definition of genuine redefinition

 3. Why redefinitions are not detected in some situations

 The LINK option /NOE stands for No Extended Dictionary.

 What is the extended dictionary and how does LINK use it? How does
 LINK use the extended dictionary?

 LINK uses the extended dictionary to speed up library searching. For
 example, if the library module A calls functions in module B and
 module C, the extended dictionary tells LINK that, if your program
 requires module A from library, it will also require modules B and C.
 According to this information, LINK pulls in the three modules A, B,
 and C all at once. This way, LINK doesn't have to search the library a
 second time to resolve references from module A to modules B and C.

 What is a genuine redefinition?

 The ERRMSG.DOC file states that when linker error L2044 occurs, the
 /NOE switch should be used. When linker error L2025 occurs, the
 program has a genuine redefinition problem.

 A genuine redefinition is any redefinition that has nothing to do with
 the extended dictionary. A redefinition error that occurs when you
 specify the /NOE switch indicates a genuine redefinition, as in the
 following example:

     FOO.OBJ:
         defines "_foo"
         calls "_libfunc"

     Module A: (in XYZ.LIB):
         defines "_libfunc"
         defines "_foo"

 If you run "LINK foo /NOE,,,xyz.lib", the L2025 error will be produced
 because module A is pulled in and redefines the symbol "_foo".

 When LINK encounters the redefinition while processing a library
 module, it assumes that the error might go away if you were to add the
 /NOE switch. This would be true if the symbols were defined like this
 as follows:

     FOO.OBJ:
         defines "_foo"
         calls "_libfunc"

     Module A (in XYZ.LIB):
         defines "_libfunc"
         calls "_foo"

     Module B ( in XYZ.LIB ):
         defines "_foo"

 The extended dictionary tells LINK to link modules A and B, even
 though module B should not be linked because "_foo" is already
 defined. In this case, the /NOE switch will eliminate the error.

 LINK cannot figure out when the error is due to the extended
 dictionary and when it is not; therefore, it assumes that the extended
 dictionary will cause a redefinition error when processing a library
 module.

 Please note that redefinitions not detected in some situations. For
 example, when the function 'printf' is redefined in a program module
 and the module is linked with SLIBCER.LIB without using the /NOE
 switch, LINK does not complain about the redefinition at all. LINK
 does not detect a redefinition because the module that defines printf
 in the library is not pulled in; thus, there is no redefinition.

 If your program module redefines a library function that is also
 called by other library functions used by your program, you will get a
 redefinition error. The extended dictionary specifies which library
 modules call routines in other library modules. Consider a
 "second-level" function to be any library function called by a library
 function in another module. For example, spawnve and _setargv are
 second-level functions because they are called by other library
 functions; printf is not. You can get a redefinition error only if you
 redefine a second-level library function called by some first-level
 routine being linked into your program.


 34. Producing an _TEXT Segment for Multiple Object Modules

 Product Version(s): 3.x 4.06 | 5.01.20 5.01.21
 Operating System:   MS-DOS   | OS/2
 Flags: ENDUSER | S_C
 Last Modified:  6-APR-1989    ArticleIdent: Q43128

 In a map file, a <modulename>_TEXT will be produced for each logical
 code segment in your program. Since small and compact model programs
 have only one code segment, you only get one logical segment, _TEXT.
 Medium- and large-model programs, however, will have a separate
 logical segment for each object module in the program, and thus produce
 a <modulename>_TEXT for each logical segment.

 To generate a map file, use the /M option with LINK or the /Fm option
 with CL.

 The following is an example map file generated when compiling a
 program with two object modules in small-memory model:

  Start  Stop   Length Name                   Class
  00000H 016EAH 016EBH _TEXT                  CODE
  ...

 The following is an example map file generated when compiling the same
 program with two object modules in large-memory model:

  Start  Stop   Length Name                   Class
  00000H 0000DH 0000EH MAPL_TEXT              CODE
  0000EH 00023H 00016H MAP2_TEXT              CODE
  00024H 01B2CH 01B09H _TEXT                  CODE
  ...

 MAPL_TEXT and MAP2_TEXT come from the files MAPL.OBJ and MAP2.OBJ,
 respectively. The _TEXT is the Microsoft run-time library and any
 third-party libraries.



 35. LINK: Renaming Overlayed Executables Will Cause Problems

 Product Version(s): 5.01.21
 Operating System:   DOS
 Flags: ENDUSER | s_C s_Pascal h_FORTRAN
 Last Modified:  6-APR-1989    ArticleIdent: Q43139

 When the Microsoft linker creates an executable file with overlays,
 the name of that EXE is hard coded into the file for use by the overlay
 manager. The Microsoft linker only creates internal overlays, i.e.,
 rather than producing FOO.EXE, FOO1.OVL, and FOO2.OVL, the two
 overlays are contained in FOO.EXE.

 If the executable is renamed at any point after linking, the overlay
 manager will still use the hard-coded name found in the EXE to locate
 the overlays, and will fail with the following prompt:

    Cannot find <oldname>
    Please enter new program spec:

 In order to change the name of the executable without receiving this
 error, it must be relinked and given the new name at that time.


 36. LINK: Creating and Accessing _edata and _end

 Product Version(s): 3.X 4.06 | 5.01.20 5.01.21
 Operating System:   MS-DOS   | OS/2
 Flags: ENDUSER | s_c
 Last Modified:  6-APR-1989    ArticleIdent: Q43165

 LINK creates the two symbols _edata and _end when the LINK option
 /DOSSEG is used. If a program is compiled by a Microsoft high-level
 language compiler, or if an assembly program written in Microsoft MASM
 uses .DOSSEG directive, LINK uses this option automatically.

 LINK gives _edata the address of the beginning of BSS segment and
 gives _end the address of the end of BSS segment. Since the STACK
 segment is directly above the BSS segment, the address of _end also
 marks the lowest address of the STACK segment.

 To obtain the addresses for these two symbols, declare the following
 in your C program:

 unsigned char edata, end ;

 The addresses, &edata and &end, can now be used to locate _BSS and
 STACK. They can also be examined in CodeView. Modifying these two
 variables is not recommended.

 Note: The segment BSS referred to in this article actually includes
 the segment C_COMMON. However in a map file created by LINK, BSS and
 C_COMMON are listed as two separate segments.



 37. Linker Options /PADDATA and /PADCODE

 Product Version(s): 4.06
 Operating System:   MS-DOS
 Flags: ENDUSER | S_QuickC docerr
 Last Modified: 18-SEP-1989    ArticleIdent: Q44928

 Question:

 I ran the linker Version 4.06 that comes with the Microsoft QuickC
 Compiler Version 2.00 with the /help option as follows:

    LINK /HELP

 I noticed two switches for which I couldn't find documentation:
 /PADDATA and /PADCODE. What are these options for?

 Response:

 The /PADC[ODE]:padsize option causes LINK to add filler bytes to the
 end of each code module. The option is followed by a colon and the
 number of bytes to add. (Decimal radix is assumed, but you can specify
 special octal or hexadecimal numbers by using a C-language prefix.)
 Thus, the following adds an additional 256 bytes to each code module:

    /PADCODE:256

 The default size for code-module padding is 0 bytes.

 The /PADD[ATA]:padsize option performs a function similar to
 /PADCODE, except that it specifies padding for data segments (or data
 modules, if the program uses small or medium-memory models). Thus,
 the following adds an additional 32 bytes to each data module:

    /PADDATA:32

 The default size for data-segment padding is 16 bytes. Note that if
 you specify too large a value for padsize, you may exceed the 64K
 limitation on the size of the default data segment.

 These two options are quite useful when used in conjunction with
 QuickC Version 2.00's incremental linking option. Using them correctly
 increases the incremental linking speed of a program.

 These two options are documented on Page 64 in the update section of
 the Microsoft C Optimizing Compiler Version 5.10 "CodeView and
 Utilities, Microsoft Editor, Mixed-Language Programming Guide" manual.


 38. Linker Error L2013 May Be a Result of a Problem in MASM 5.10

 Product Version(s): 3.x 4.06 4.07 5.01.21 5.02 5.03 5.05
 Operating System:   MS-DOS
 Flags: ENDUSER | h_masm
 Last Modified: 27-DEC-1990    ArticleIdent: Q59894

 The error message for linker error L2013 is as follows:

    error L2013 LIDATA record too large
       pos: xxx Record type: 743C

 In the README.DOC file that comes with MASM version 5.10, Microsoft C
 version 5.10, and the "Microsoft FORTRAN CodeView and Utilities User's
 Guide" version 5.00 manual, the recommended course of action is to
 call Microsoft Product Support at [phone].

 The error is a result of an invalid object module. This is a known
 problem in MASM 5.10. The most likely cause is a duplication of some
 large data item, such as a structure.

 The easiest workaround is to break up the duplication(s) into smaller
 parts.


 39. LINK 5.02 Should Not Be Used with ILINK 1.10

 Product Version(s): 5.02
 Operating System:   MS-DOS
 Flags: ENDUSER | S_QuickC
 Last Modified: 30-AUG-1989    ArticleIdent: Q45536

 LINK Version 5.02, which comes as a secondary linker for QuickC 2.00,
 should not be used with ILINK Version 1.10, which also comes with
 QuickC 2.00.

 Inside the QuickC environment, this combination has caused problems
 with floating point-values being printed with printf. Outside of the
 environment, the same executable results in math error M6104.

 The source code below prints "FP = 0.00000" instead of "FP =
 5.020000". Running from the DOS prompt, in this case, produces the
 same results.

 Source Code
 -----------

     #include <stdio.h>

     void main( void )
     {
         float fp = 5.02F;

         printf( "FP = %f\n", fp );
     }

 LINK Version 4.06 should be used if ILINK is also to be used. If it is
 necessary to use Version 5.02 of the linker, incremental linking
 should be disabled from within the environment.

 Microsoft is researching this problem and will post new information as
 it becomes available.


 40. Linker Errors L4013, L2048, and L4038: Overlaying in OS/2

 Product Version(s): 5.01.20 | 5.03
 Operating System:   MS-DOS  | OS/2
 Flags: ENDUSER | S_C H_Fortran
 Last Modified: 21-JUN-1989    ArticleIdent: Q45619

 The linker does not overlay files when linking with protected mode
 run-time libraries. If told to overlay a program that is being linked
 with a protected mode run-time library, the linker responds with one
 or more of the following errors:

    LINK : warning L4013: invalid option for new-format executable file
    ignored
    LINK : error L2048: Microsoft Overlay Manager module not found
    LINK : warning L4038: program has no starting address

 possibly followed by (in DOS):

    run-time error R6001
    - null pointer assignment

 or possibly followed by (in OS/2):

    A general protection (GP) fault. It may also go into an infinite
    loop after creating the temporary file (for large executables).

 The workaround is to create two versions of the executable, an
 overlayed DOS version and a non-overlayed OS/2 version.

 Microsoft is researching this problem and will post new information as
 it becomes available.


 41. Link Error L1005: /PACKCODE: Packing Limit Exceeds 65,536

 Product Version(s): 3.65
 Operating System:   MS-DOS
 Flags: ENDUSER | docerr
 Last Modified: 21-JUN-1989    ArticleIdent: Q45724

 The Microsoft Overlay Linker Version 3.65 presents the following error
 message when the /PACKCODE: switch is used with a value greater than
 65,536 (64K):

    Link Fatal Error L1005:

 No error message text is supplied, and the error cannot be referenced
 in the Microsoft C 5.10 "CodeView and Utilities, Microsoft Editor,
 Mixed-Language Programming Guide." The error message should read as
 follows:

    Link Fatal Error L1005: /PACKCODE: Packing Limit Exceeds 65,536

 The error is reported correctly by the Microsoft QuickC Linker Version
 4.06 and all 5.0x versions of the Microsoft Segmented-Executable
 Linker. It is correctly documented in the Version 2.00 "Microsoft
 QuickC Tool Kit," on Page 278, and on Page 373 of the Version 5.00
 "Microsoft FORTRAN, Microsoft CodeView and Utilities User's Guide"
 manual, as follows:

    The value supplied with the /PACKCODE option exceeds the limit of
    65,536 bytes.


 42. What the /HIGH and /DS Linker Options Do

 Product Version(s): 3.65
 Operating System:   MS-DOS
 Flags: ENDUSER | SR# G890607-19979
 Last Modified: 13-JUL-1989    ArticleIdent: Q46745

 Question:

 I would like information on the /HIGH and /DS options of the linker.
 Specifically, what changes are needed in the .EXE file to tell the
 loader to put it high?

 Response:

 Basically, these are hold-over features from DOS Version 1.00 and from
 the original Microsoft/IBM Pascal and FORTRAN Compilers -- they're of
 little or no use under DOS 2.00 and later. Specifically, programs
 linked with the /HIGH switch are allocated all of the memory in the
 machine and cannot release unneeded memory back to DOS; therefore, no
 other program can be loaded into memory.

 The /HIGH switch sets both the minalloc and maxalloc fields in the .EXE
 header to zero. This combination of values causes the loader to load
 the program in high memory.

 /DSALLOCATE (or /DS) causes DGROUP to be "shifted" upwards so that the
 high address in the group is always FFFFh. Offsets into DGROUP are
 adjusted appropriately.

 These switches are strictly incompatible with our current high-level
 languages -- the only possible use for them is in a MASM program.
 Microsoft doesn't recommend using them at all unless you know
 precisely what you're doing.

 There is good documentation on what the /HIGH and /DSALLOCATE switches
 do, as well as how the loader works, in the "MS-DOS Encyclopedia,"
 starting on Page 719. (This excellent reference manual is now less
 expensive and available in paperback).


 43. How Minimum Load Size Is Calculated

 Product Version(s): 3.65
 Operating System:   MS-DOS
 Flags: ENDUSER | SR# G890607-19979
 Last Modified: 13-JUL-1989    ArticleIdent: Q46774

 The MS-DOS program loader uses the following formula to calculate the
 number of 16-byte paragraphs to use when loading a program:

    TotPages * 20h - NumHeader + 10h + MaxAlloc

 The formula calculates the number of 16-byte paragraphs, unless
 there's not enough memory, in which case all the available memory is
 used. If there are not at least

    TotPages * 20h - NumHeader + 10h + MinAlloc

 paragraphs available, DOS cannot and will not load the program.

 The 20h is the size of a page in paragraphs, which is the size of a
 page (512 bytes) divided by the size of a paragraph (16 bytes).

 The 10h is the size in paragraphs of the 256-byte Program Segment
 Prefix that precedes all programs in memory.

 All of the values used in the formulae shown above are words (shown in
 the following) that are stored in standard Intel low-byte-first format
 in the .EXE file header:

    Value           Name used by EXEHDR             Offset in .EXE header
    -----           -------------------             ---------------------

    TotPages        Pages in file                   4 - 5
    NumHeader       Paragraphs in header            8 - 9
    MinAlloc        Extra paragraphs needed         0Ah - 0Bh
    MaxAlloc        Extra paragraphs wanted         0Ch - 0Dh

 For more information, refer to a good MS-DOS reference such as the
 "MS-DOS Encyclopedia."


 44. L1074 Name: Group Larger Than 64K Bytes

 Product Version(s): 4.06
 Operating System:   MS-DOS
 Flags: ENDUSER | S_C S_QuickC
 Last Modified: 24-JUL-1989    ArticleIdent: Q46996

 The Microsoft QuickC Compiler Version 2.00 returns the following
 linker error message when the size of DGROUP (the default data
 segment) exceeds 64K:

    L1074 name: group larger than 64K bytes

 This error is documented on Page 282 of the "Microsoft QuickC Tool
 Kit" manual as follows:

    The given group exceeds the limit of 65,536 bytes.

    Reduce the size of the group, or remove any unneeded segments from
    the group (refer to the map file for a listing of segments).

 There are four ways to resolve this data segment overflow when using
 QuickC:

 1. Reduce the stack size in order to reduce the size of DGROUP. In the
    environment this can be done in the Options.Make.Linker Flags menu.
    Outside the environment this can be done at compile time with the
    "/F hexnum" switch, where hexnum is the size of the requested stack
    in hexadecimal format. Outside the environment, at link time, this
    can be done with the "/ST:decnum" switch, where decnum is the size
    of the requested stack in decimal format.

 2. Declare data with the FAR keyword to move it out of DGROUP.

    Note: In the small and medium memory models the Microsoft run-time
    library functions can no longer be used with this data. You must
    copy this far to a near heap location, before you use the run-time
    routines on this data.

 3. Outside the environment, compile in the compact, large, or huge
    memory models with the "/GtX" switch, where X is a data threshold.
    All data items larger than X bytes are moved out of DGROUP into a
    far data segment.

 4. Reduce the amount of data declared in the program. In the compact,
    large, and huge memory models, try dynamically allocating space for
    the data. Memory can also be dynamically allocated outside DGROUP
    in the small and medium memory models by using _fmalloc() but, as
    stated in Number 2, the run-time library functions do not work with
    this data.

    Reduce the amount of string literals in this default data segment by
    reading from a data file at run time, or in C 5.00, by using the
    /Gt patch to allow string literals to be moved from the _CONST
    segment in DGROUP into a far segment.


 45. /CP:X Is Not Valid When Linking Protected-Mode Programs

 Product Version(s): 5.01.21 | 5.01.21
 Operating System:   MS-DOS  | OS/2
 Flags: ENDUSER | docerr
 Last Modified: 26-JUL-1989    ArticleIdent: Q47036

 Question:

 I cannot seem to get the /CPARMAXALLOC linker option to work when I
 link for OS/2 protected mode. When linking a real-mode application, it
 works correctly. Also, when I type "link /help" in protected mode, the
 output indicates that this is a valid option. However, when I try to
 use this option for a protected-mode application, the linker produces
 the following warning:

    LINK : warning L4013: invalid option for new-format executable file
                          ignored

 What am I doing wrong and what does this error message mean?

 Response:

 As documented on Page 27 in the update section of the Microsoft C
 Optimizing Compiler Version 5.10 "CodeView and Utilities, Microsoft
 Editor, Mixed-Language Programming Guide" manual, the /CPARMAXALLOC
 option is for real-mode applications only. The "link /help" indicates
 that this is a valid option because this option IS valid whenever
 you're linking real-mode applications, regardless of whether the
 linker is running under OS/2 or DOS. (By the same token, it is invalid
 when you're linking a protected-mode application, regardless of which
 operating system you're using.)

 This error message was omitted from the documentation. It indicates
 that one of the options that the linker was passed is invalid.

 This option is not supported in a protected-mode application because
 the functionality of it is done automatically by the linker.
 Protected-mode applications are not given a 64K default data segment;
 they are only allocated the space that they need. This is documented
 on Page 33 of the same section and manual listed above.


 46. Cannot Use Overlays in a Bound Application

 Product Version(s): 5.01.21 5.03 | 5.01.21 5.03
 Operating System:   MS-DOS       | OS/2
 Flags: ENDUSER |
 Last Modified: 30-AUG-1989    ArticleIdent: Q47104

 Question:

 How can I incorporate overlays into my bound application?

 Response:

 You cannot use overlays in a bound application. To bind an
 application, you must first have a runnable OS/2 executable; then, you
 use the BIND utility to make it run in both OS/2 and DOS. OS/2
 executables do not understand overlays so you cannot incorporate them
 into an OS/2 executable. Hence, you cannot use overlays in a bound
 program.


 47. Linker Error L1063 and Linking Over 1000 Object Modules

 Product Version(s): 5.01.21 5.03
 Operating System:   OS/2
 Flags: ENDUSER | S_C S_CodeView
 Last Modified: 16-AUG-1989    ArticleIdent: Q47931

 Question:

 When attempting to link a large OS/2 application consisting of over
 1500 object modules with C 5.10's Link 5.01.21 or FORTRAN 5.00's Link
 5.03 by using the options /co /map:2078 /noe /se:2078 /packcode, I get
 the link error "L1063 out of memory for CodeView information." Only
 one of the .C source files was compiled with /Zi. All were compiled
 with /AL. Linking without /co (CodeView information) successfully
 produces a 700K executable file (.EXE), but I need to do some
 debugging with CVP.

 What is the L1063 error, and how can I work around it?

 Response:

 Information on L1063 is not in the C 5.10 text files or documentation,
 but it is in Pascal 4.00's README.DOC and in FORTRAN 4.10's
 CVREADME.DOC as noted in another article in this knowledge base. The
 following reiterates the error message and its description:

    L1063 out of memory for CodeView information

    The linker was given too many object files with debug information,
    and the linker ran out of space to store it. Reduce the number of
    object files that have debug information.

 In this case, it is not the number of modules with CodeView
 information that is causing the problems exactly; it is the great
 number of modules and trying to link in any CodeView information.

 The following are ways to workaround this linker limitation:

 1. The most effective method is to demodularize your application. That
    is, put more functions into fewer .C source files.
 2. Reduce the linker option /se: value to as low as possible for the
    number of logical segments in the application.
 3. Link the object files from the current working directory. If you
    must use different directories for your .OBJs, make the pathnames
    as short as possible.


 48. Description of a Linker .MAP File

 Product Version(s): 3.60 3.61 3.64 3.65 5.01.20 5.01.21 5.03  | 5.01.20 5.01.
 Operating System:   MS-DOS                                    | OS/2
 Flags: ENDUSER | S_C S_PasCal H_FORTRAN
 Last Modified: 19-SEP-1989    ArticleIdent: Q47960

 A .MAP file generated by the linker is a listing of the addresses and
 names of a program, as follows:

    Logical Segments
    Groups (defined collections of logical segments)
    Public Symbols listed by name
    Public Symbols listed again by their relative address
    Entry Point address (first executable instruction)

 A linker .MAP file (with a .MAP file extension) contains the address,
 size, name, and class of logical code and data segments. (One or more
 logical segments of either code or data can be combined into a
 physical segment of either code or data, respectively, by the linker.)

 In DOS or real-mode OS/2, the addresses are 20-bit hex addresses that
 are RELATIVE to the beginning of the program's load image. In
 protected-mode OS/2, the hex addresses are in 32-bit segment
 selector:offset notation (16 bits for the segment selector and 16 bits
 for the offset) starting with segment selector 1.

 The _TEXT segment names of class CODE are the code in your object
 files. The various forms of near logical data segments are described
 in the DGROUP diagram, which you probably already have. (Briefly,
 _DATA is initialized near global data, _BSS is uninitialized near
 "static" data, C_COMMON is uninitialized near data, and CONST is for
 floating point constants. FAR_DATA and HUGE_DATA are global
 initialized far and huge data, respectively, and FAR_BSS is global
 unitialized far or huge data.)

 Next in the .MAP is the ORIGIN (address) and name of the defined
 groups of logical segments, notably DGROUP, which is used in our
 high-level languages for grouping many logical data segments into the
 "default" physical data segment. The name "default" data segment
 refers to the fact the the DS register will point to this segment by
 default so that offset (near) addressing can be used without loading
 the DS register. Groups allow multiple logical segments to be
 associated with the same starting address, so near (non-far) data in
 Microsoft high-level languages is addressed relative to DGROUP.

 Following the segment descriptions, under the heading of "Publics by
 Name", the names of Public symbols (i.e., global or extern functions,
 including numerous internal C library functions, and variables) are
 listed in ASCII order (capital letters first, then lowercase letters,
 and finally underscores) along with their hex relative segment:offset
 addresses (or segment selector:offset in protected-mode OS/2). Public
 symbols are then listed again, in order of their relative
 segment:offset addresses under the heading "Publics by Value".

 Only Public (e.g. global) symbols such as function and variable names
 appear in the .MAP. No "static" functions or data, "auto" storage
 class data (e.g. local function data), or data types are listed in the
 .MAP.

 A high-level language such as C creates many logical segments in
 DGROUP for "internal" (e.g. undocumented) purposes, calls numerous
 internal library functions, and refers to variables for the main
 program initialization and start-up code. C refers to additional
 initialization functions and variables for the library functions that
 your program explicitly calls, still more for floating point
 functions, as well as termination functions.

 To get an idea of the functions automatically linked in from the C
 library, generate and compare .MAP files for simple source modules
 such as foo(){} or main(){}, main(){puts("hi");}, and a small program
 that performs floating point arithmetic or calls a C library floating
 point math function that calls "fp..." routines.

 The "Program entry point" is the last item in the .MAP file. It refers
 to the segment:offset address of the first instruction of the program
 to be executed, relative to the lowest memory address in the .EXE load
 image.

 For more information on the entry point, please use the following
 query:

    .map file's program entry point


 49. Linker Can Indiscriminately Bind Different Types

 Product Version(s): 1.x 2.x 3.x 4.x 5.01 5.02 5.03 | 5.01
 Operating System:   MS-DOS                         | OS/2
 Flags: ENDUSER | S_C S_QuickC S_QuickASM S_Pascal S_QuickPas
 Last Modified:  2-AUG-1990    ArticleIdent: Q48204

 The object module format used by the Microsoft languages contains a
 record type that is used to bind symbol definitions to symbol
 references in other modules. This record is known as a "fixup." As
 defined by Intel, the fixup record type contains no information as to
 the type of data that is to be fixed up. Under certain circumstances,
 this can cause unexpected and undesired binding at link time. The code
 below demonstrates such an instance:

     /*----- FILE1.C -----*/

     void bar( void );

     void main( void )
     {
         bar();
     }

     /*----- FILE2.C -----*/

     int bar;

 These files both compile without error. When compiled for a model with
 a single code segment, linker error L2003 is produced saying that an
 intersegment self-relative fixup was attempted. If a multiple code
 segment model is used, no link errors are produced. Although a clean
 link can be obtained, the resultant EXE does not perform as expected
 due to the fact that the function reference of bar in FILE1.C has been
 bound to the integer definition of bar in FILE2.C.

 The linker has no way of determining the types of the reference to,
 and definition of, bar. This is a limitation of the object file
 format. If an include file was used to prototype bar and was then
 included in both files, the compiler could have detected the
 redefinition of bar.

 This information applies to all 1.x, 2.x, and 3.x versions of LINK
 including 3.60, 3.61, 3.64, and 3.65, as well as LINK Versions 4.06,
 4.07, 5.01, 5.02, and 5.03.


 50. Novell Network Software May Cause L1084 Error

 Product Version(s): 5.03
 Operating System:   MS-DOS
 Flags: ENDUSER | h_fortran h_masm s_c s_pascal
 Last Modified: 23-JAN-1990    ArticleIdent: Q57304

 The resident software used to access a Novell network may cause the
 following error when linking large programs:

    L1084:  Cannot create temporary file

 This problem was observed with Netware versions 2.10 SFT and 2.15 of
 the Novell network software.


 51. Relationship between Map File Addresses and Location in Memory

 Product Version(s): 3.61 3.65
 Operating System:   MS-DOS
 Flags: ENDUSER |
 Last Modified: 19-SEP-1989    ArticleIdent: Q48241

 In situations where memory is very short or where CodeView interacts
 with your program, it is sometimes necessary to use the DEBUG.COM
 program supplied with DOS.

 Using DEBUG is more difficult than using SYMDEB or CodeView because
 DEBUG has no symbolic features. You must use the map produced by the
 /M option when you link with a standard DOS overlay linker (i.e., not
 a segmented executable linker) to locate specific parts of your
 program.

 However, since DOS relocates programs when it loads them, the
 addresses given in the map need conversion before you can use them.

 This conversion is simple: DOS adds the address of the start segment
 (defined below) to each segment address in the load map. The offsets
 never change from the values shown in the link map -- only the
 segments change.

 The start segment is the base address of the Program Segment Prefix
 (PSP) plus the size of the PSP in paragraphs. Since the PSP is always
 100h (256) bytes long, the size of the PSP is 10h paragraphs.

 Note: DOS puts the base segment address of the PSP in DS and in ES
 when a program begins execution.

 For example, assume that the link map says that the function _funct is
 at 0004:05A0 (all values in hex) and that the global variable _errno
 is at 0192:00E3. Suppose further that when the program is loaded into
 DEBUG, the DS and ES registers contain 2BA5 -- the segment address of
 the PSP. (Use the R command to display the values of the registers.)

 The start segment for loading the program will be 2BB5 -- the value of
 the PSP base address (2BA5) + 10h to allow for the 10h paragraph
 length of the PSP (100h bytes).

 Thus, the function _funct will be located as follows:

    0004:05A0   -- address of _funct in the link map
    2BB5        -- start segment address (PSP + 10h)
    ---------
    2BB9:05A0

 And _errno will be located as follows:

    0192:00E3   -- address of _funct in the link map
    2BB5        -- start segment address (PSP + 10h)
    ---------
    2D47:00E3

 Use this calculation on any address in the link map to find where the
 symbol is located in memory when actually loaded.

 The H (Hex Arithmetic) command in DEBUG can be helpful when performing
 these calculations, as can a hex calculator with constant feature.


 52. Warning L4014: /PACKDATA: Option Ignored for Real Mode

 Product Version(s): 4.06 4.07 5.02 5.03 | 5.02 5.03
 Operating System:   MS-DOS              | OS/2
 Flags: ENDUSER |
 Last Modified: 21-SEP-1989    ArticleIdent: Q48839

 /PACKDATA is incorrectly listed as an available switch for LINK
 Versions 4.06 and 4.07. LINK Version 4.06 comes with the QuickC
 compiler, and LINK Version 4.07 comes with the QuickAssembler.

 The /PACKDATA option is valid ONLY for segmented-executable files --
 OS/2 or Windows; it has no meaning for DOS. Real mode executable means
 a DOS-only program. To use the /PACKDATA switch, create a .DEF file
 with at least the following statement:

    NAME    MyProtectModeProgram

 This switch is implemented in segmented-executable LINK Versions 5.02
 and later.


 53. /NOI Switch May Cause L2022 and L2029 in PM Programs

 Product Version(s): 5.10   | 5.10
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified: 27-OCT-1989    ArticleIdent: Q49008

 I am compiling and linking a Presentation Manager (PM) program from
 Charles Petzold's "Programming the OS/2 Presentation Manager" and I
 get the following link errors:

    LINK : error L2022: ClientWndProc (alias ClientWndProc) : export
           undefined

         : error L2029 : 'ClientWndProc' : unresolved external

 I get the same errors when compiling WELCOME1.C from the companion
 disk to "Programming the OS/2 Presentation Manager."

 The /NOI switch instructs the linker to preserve case. If you are
 using the /NOI switch, the linker will generate these errors because
 EXPENTRY (the export entry point) is defined in OS2DEF.H as follows:

    #define EXPENTRY far pascal

 The "pascal" keyword instructs the compiler to use the left-to-right
 calling sequence for the functions that it modifies. The keyword also
 causes the conversion of the function's name to uppercase letters.

 All window procedures are defined as EXPENTRY. Thus, the name of your
 window procedure is converted to uppercase letters. In your .DEF, you
 export your window procedures as follows:

    EXPORTS         ClientWndProc

 Because of the /NOI switch, the linker does not view ClientWndProc and
 CLIENTWNDPROC as being equal. Consequently, you get the first error
 message "export undefined."

 The second error message is generated because ClientWndProc (mixed
 uppercase and lowercase letters) is not recognized as being defined,
 so the linker considers it an "unresolved external."

 Removing the /NOI switch from your link line corrects both errors.


 54. LINK 5.03 and Later Require EXETYPE WINDOWS in .DEF File

 Product Version(s): 5.03
 Operating System:   MS-DOS
 Flags: ENDUSER |
 Last Modified: 17-JUL-1990    ArticleIdent: Q49445

 Microsoft LINK (LINK.EXE) versions 5.03 and later require that the
 WINDOWS descriptor be placed in the EXETYPE section of your project's
 .DEF (definitions) file if you are developing a Windows' application.

 This marks a change from previous linkers' behavior, which would allow
 the programmer to fail in specifying the type of executable to be
 created, but still produce a Windows-compatible .EXE file. This
 failure is no longer acceptable to LINK Versions 5.03 and later.

 If you fail to inform the linker (via the .DEF file) that you are
 creating a Windows executable, the linker reaches completion but the
 resulting .EXE does not execute.

 To specify the executable type, you must create a .DEF file and submit
 this to the linker at link time. For example, if you had a project
 called WINTEST.C, you must modify WINTEST.DEF so that it contains the
 following line:

    EXETYPE   WINDOWS

 The default EXETYPE is OS/2, as stated in the "Microsoft FORTRAN,
 CodeView and Utilities User's Guide" packaged with FORTRAN Version
 5.00.

 For further information regarding the definitions file and other
 descriptors, consult Section 7, "Using Module-Definition Files," in
 the "CodeView and Utilities, Microsoft Editor, Mixed Language
 Programming Guide" (Update Section) for C 5.10.

 LINK Version 5.03 is shipped with the FORTRAN version 5.00 package.


 55. Long TMP Environment Variable Causes L1089

 Product Version(s): 5.03   | 5.03
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER | h_fortran
 Last Modified:  6-DEC-1989    ArticleIdent: Q48869

 L1089 occurs when the LINK Utility Version 5.03 is called from FORTRAN
 Version 5.00 and the TMP environment variable is set to a long
 pathname.

 Normal troubleshooting indicates that the TMP variable is corrupt, but
 this is not the case. It seems that the temporary filename is being
 truncated.

 The following sequence produces the error if the subdirectory
 D:\COMPILER\FORTRAN5\TMP\ already exists:

 SET TMP=d:\compiler\fortran5\tmp
 fl sieve.for

 LINK : fatal error L1089: D:\COMPILER\FORTRAN5\TMP\000054l
 : cannot open response file

 This problem occurs in FORTRAN 5.00 and Link 5.03.


 56. L2041: Stack Plus Data Exceeds 64K -- Documentation Supplement

 Product Version(s): 3.65 4.06 | 5.01.21
 Operating System:   MS-DOS    | OS/2
 Flags: ENDUSER  | s_pascal h_fortran h_masm s_c s_quickc s_quickasm s_error d
 Last Modified: 30-NOV-1989    ArticleIdent: Q50130

 The following indicates that there is more than 64K of stack and data
 to be put into the 64K DGROUP (default data segment):

    L2041    stack plus data exceeds 64K

             The combined size of the program stack segment plus DGROUP
             was greater than 64K; as a result, the program will not
             load up correctly.

 To correct this problem, do the following:

 1. If the file(s) was compiled with C 5.00, a large amount of string
    literal data in the program may cause this error. Unlike C 5.10,
    5.00 cannot move string literals out of DGROUP with the /Gt option.
    This problem can be corrected with the "C 5.00 /Gt Fix" application
    note, which is available from Microsoft Product Support Services by
    calling [phone].

 2. Reduce the stack size.

 3. Use a large data model (compact, large, or huge). Try applying the
    /Gt compilation option to lower the threshold.

 4. Use the FAR keyword to move data out of DGROUP.

 This error is documented in "Linker Error Messages" in the "Microsoft
 QuickC Compiler for IBM Personal Computers and Compatibles
 Programmer's Guide," Section D.4, Page 374. It is also in the file
 ERRMSG.DOC on Compiler Disk 1 for Microsoft C Version 5.10, on the
 Setup disk for Microsoft C Version 5.00, in the file README.DOC on
 Disk 1 for Microsoft Macro Assembler Version 5.10, and in the file
 CVREADME.DOC on the CodeView for MS-DOS disk for Microsoft FORTRAN
 Version 4.10. It is not found in the "CodeView and Utilities,
 Microsoft Editor, Mixed-Language Programming Guide" manual.

 Nonfatal errors indicate problems in the executable file. LINK
 produces the executable file. Nonfatal error messages have the
 following format:

    location : error L2xxx: messagetext

 In these messages, location is the input file associated with the
 error, or LINK if there is no input file. If the input file is an .OBJ
 or .LIB file and has a module name, the module name is enclosed in
 parentheses.

 Additional reference words: appnote


 57. Link Error L2028 Caused by HEAPSIZE, STACKSIZE and DGROUP Size

 Product Version(s): 5.01.21 | 5.01.21
 Operating System:   MS-DOS  | OS/2
 Flags: ENDUSER | docerr
 Last Modified: 17-JUL-1990    ArticleIdent: Q49935

 The error L2028 "Automatic data segment plus heap exceeds 64K" was
 omitted from the linker error messages in the "CodeView and Utilities,
 Microsoft Editor, Mixed-Language Programming Guide" manual that
 accompanies Microsoft C 5.10. This error occurs when the stack and
 data plus the near heap exceeds 64K. The near heap size is set with
 the HEAPSIZE option in the .DEF file.

 The error can be corrected by using one of the following methods:

 1. Reducing the amount of data in the default data segment.

 2. Decreasing the stack size that was set by /ST:xxxx at the link line
    or by the STACKSIZE option in the .DEF file.

 3. Decreasing the amount of near heap that is being requested with the
    HEAPSIZE option in .DEF file.


 58. Specifying Link Options with "-" Causes L4046, L1083, or U1013

 Product Version(s): 5.01.21
 Operating System:   OS/2
 Flags: ENDUSER |
 Last Modified: 10-NOV-1989    ArticleIdent: Q50333

 LINK command line switches must begin with the linker's option
 character, the forward slash (/). While it is valid to begin
 compilation switches with a dash (-), the same is not true for the
 linker.

 Code Example
 ------------

 #--------------------
 # test make file
 #--------------------

 test.obj : test.c test.h
      cl -c -Zi -G2sw -W3 test.c

 test.exe : test.obj test.def
      link test, -CO -align:16, NUL, os2, test

 You type:
         make test

 Microsoft (R) Program Maintenance Utility  Version 4.07
 Copyright (C) Microsoft Corp 1984-1988. All rights reserved.

   link test, -CO -align:16, NUL, os2, test

 Microsoft (R) Segmented-Executable Linker  Version 5.01.21
 Copyright (C) Microsoft Corp 1984-1988.  All rights reserved.

 TEST.DEF(12) : warning L4046: module name different from output file name
 LINK : fatal error L1083: cannot open run file
 test(16) : fatal error U1013: 'link test, -CO -align:16, NUL, os2, test'
          : error 2


 59. /PACKCODE Incompatible with IOPL Segments with LINK 5.01.21

 Product Version(s): 5.01.21
 Operating System:   OS/2
 Flags: ENDUSER | S_C
 Last Modified: 10-NOV-1989    ArticleIdent: Q50702

 LINK Version 5.01.21 does not support the combination of using the
 /PACKCODE switch and having code segments declared as IOPL (i.e., as
 having I/O privilege).

 When combining segments as directed by the /PACKCODE option, LINK
 5.01.21 will combine the IOPL segment(s) with other segments that do
 not have I/O privilege. The result is an invalid executable that
 returns the system error SYS1059 when it is invoked.

 The lack of ability to combine these options is a limitation of this
 particular linker version. LINK Version 5.03 allows the combination of
 /PACKCODE and IOPL segments without a problem.


 60. LINK : Warning L4011 Caused By Invalid /PACKCODE Group Size

 Product Version(s): 3.65 4.06 4.07 5.01.21 5.03 | 5.01.21 5.03
 Operating System:   MS-DOS                      | OS/2
 Flags: ENDUSER | S_C S_QUICKC S_QUICKASM S_PASCAL DOCERR
 Last Modified: 10-NOV-1989    ArticleIdent: Q50705

 The LINK code packing option, /PAC[:n], groups together neighboring
 code segments into the same segment of maximum size "n" bytes. The
 results of using /PAC will only be reliable when "n" is in the range
 of 0 to 65500. Page 278 of the "Microsoft C 5.1 CodeView and
 Utilities" reference manual states the default value for "n" is 65530.
 This is incorrect.

 The linkers from the following products were tested with the /PAC
 option to determine their behavior with various values of "n":

    C 5.10
    Pascal 4.00
    FORTRAN 5.00
    QuickC 1.01
    QuickC 2.00
    QuickASM 2.01

 Note: Linkers were checked in both real and protected mode where
 appropriate.

 The following table shows the acceptable values that can be used with
 the /PAC[:n] option and what error message will occur when the value
 of "n" is out of range:

 ----------------------------------------------------------------------
 Value of "n"      LINK Vers.   Error Message
 ----------------------------------------------------------------------
 0 to 65500        3.65         No Errors/Warnings
                   4.06         No Errors/Warnings
                   4.07         No Errors/Warnings
                   5.01.21      No Errors/Warnings
                   5.03         No Errors/Warnings

 65501 to 65536    3.65         LINK : warning L4011:
                   4.06         LINK : warning L4011: PACKCODE value
                                exceeding 65500 unreliable
                   4.07         (same as above)
                   5.01.21      (same as above)
                   5.03         (same as above)

 65537 and over    3.65         LINK : fatal error L1005:
                   4.06         LINK : fatal error L1005: packing limit
                                exceeds 65536 bytes
                   4.07         (same as above)
                   5.01.21      (same as above)
                   5.03         (same as above)
 ----------------------------------------------------------------------

 Note : With LINK Version 5.03 and later, the /PAC option has been
 changed to /PACKC to differentiate /PACKC[ODE] from the new
 /PACKD[ATA] option.


 61. How and When to Specify Stack Size (Clarification)

 Product Version(s): 3.65 4.06 4.07 | 5.01.21
 Operating System:   MS-DOS         | OS/2
 Flags: ENDUSER |
 Last Modified: 30-NOV-1989    ArticleIdent: Q50950

 Question:

 When I want to specify a certain stack size for a program, should I
 use the /F compiler option, the /ST linker option, or both?

 Response:

 This depends on how you are compiling and linking. If you using the CL
 command to compile and link, the /F compiler option is all that is
 necessary. This option will pass the correct size of the stack to the
 linker.

 On the other hand, if you are invoking the compiler and the linker
 separately (as in a make file), the /ST link option can be used to get
 the desired stack size. The /ST link option is documented on Page 123
 of the "Microsoft C Optimizing Compiler User's Guide."

 No stack information is stored in the object module. Therefore, using
 the /F and /c (compile only) options together and then invoking link
 separately will not generate the desired stack size. The /F compile
 option is documented on Page 102 of the "Microsoft C Optimizing
 Compiler User's Guide."


 62. Linking Method May Result in Unexpected Increase in .EXE Size

 Product Version(s): 3.x 4.06 4.07 5.01.21 5.03 | 5.01.21 5.03
 Operating System:   MS-DOS                     | OS/2
 Flags: ENDUSER |
 Last Modified: 21-FEB-1990    ArticleIdent: Q58689

 Question:

 When my program is linked in the following manner

    link  file1.obj file2.obj library.lib;

 the resulting executable file is much larger than if the program is
 linked this way:

    link  file1.obj file2.obj,,,library.lib;

 What causes the difference in size?

 Response:

 This is expected behavior, the difference in size is due to the
 difference in linking method.

 The first method has the library name in the same field as the object
 files. Libraries entered in this field are called "load libraries" as
 opposed to "regular libraries." Link automatically links in every
 object module in a load library; it does not search for unresolved
 external references first.

 The effect of using a load library is exactly the same as if you had
 entered all the names of the library's object modules as separate
 object files on the link command line. This feature is useful if you
 are developing software using many modules and want to avoid having to
 retype each module on the LINK command line.

 With the second method, LINK links in only the objects from the
 library that are required for program execution.

 Please see documentation on LINK, such as Section 12.1.2 of the
 Microsoft C 5.1 "CodeView and Utilities Software Development Tools for
 the MS-DOS Operating System" manual (Page 257) for more information.


 63. Linker Uses Library Sequence to Resolve External References

 Product Version(s):
 Operating System:   1.x 2.x 3.x 4.06 4.07 5.01.21 5.02 5.03 | 5.01.21 5.02 5.
 Flags: MS-DOS                                  | OS/2
 Last Modified: 26-FEB-1990    ArticleIdent: Q57706
 ENDUSER |

 "The MS-DOS Encyclopedia," Pages 407 and 408, states the following:

    When a public symbol required to resolve an external reference is
    declared more than once among the object modules in the input
    libraries, LINK uses the first object module that contains the
    public symbol. This means that the actual executable code or data
    associated with a particular external reference can be varied by
    changing the order in which LINK processes its input libraries...

    Each individual library is searched repeatedly (from first library
    to last, in the sequence in which they are input to LINK) until no
    further external references can be resolved.

 The following simple case demonstrates the concept:

    Module MAIN   Library A     Library B1    Library C     Library B2
    +---------+   +----------+  +----------+  +----------+  +----------+
    | calls A |   | contains |  | contains |  | contains |  | contains |
    +---------+   |    A,    |  |    B     |  |    C,    |  |    B     |
                  | calls  C |  +----------+  | calls  B |  +----------+
                  +----------+                +----------+

 The linker determines which copy of Module B to use depending on the
 library sequence. For example, when you link with the following, the
 Module B from Library B2 is selected:

    LINK MAIN,,,A B1 C B2;

 The linker looks first in Library C and, unable to resolve the
 reference, proceeds to the next library, B2. If the linker is still
 unable to resolve the reference, it continues searching at Library A.

 A slightly more complex case, when Library A contains both Module A
 and Module B, produces different results, as shown below:

    Module MAIN   Library A     (remove B1)   Library C     Library B2
    +---------+   +----------+                +----------+  +----------+
    | calls A |   | contains |                | contains |  | contains |
    +---------+   |    A,    |                |    C,    |  |    B     |
                  | calls  C |                | calls  B |  +----------+
                  +----------+                +----------+
                  | contains |
                  |    B     |
                  +----------+

 Link with "LINK MAIN,,,A C B2;". In this case, Module B from Library A
 is selected.

 Although the linker always follows the same rules for resolution, it
 gets more difficult to determine which version of a module will be
 selected in more complex cases. When feasible, you can avoid this
 problem by putting your selected versions in an .OBJ instead of an
 .LIB. The linker uses any .OBJs to resolve references before it
 uses libraries.

 For more information, refer to "The MS-DOS Encyclopedia," Article 20:
 "The Microsoft Object Linker," in the "Object Module Order" section,
 Pages 703-706.


 64. Calling Overlaid Functions Through Pointers Not Supported

 Product Version(s): 1.x 2.x 3.x 4.06 4.07 5.01.21 5.02 5.03
 Operating System:   MS-DOS
 Flags: ENDUSER | S_C S_QuickC
 Last Modified: 30-JAN-1990    ArticleIdent: Q58098

 LINK does not support using function pointers for calling functions in
 overlays unless the function is being called from within the same
 overlay. If an overlaid function is being called from the root or from
 a different overlay, then the call must not be made through a pointer.

 LINK cannot support calling overlaid functions indirectly through
 pointers because the address of the indirect function is determined at
 load time.

 In a program with overlays, a normal function call (that is, not a
 call through a pointer) is recognized by the linker and an interrupt
 call is placed into the .EXE in place of the function call. When the
 function is called at run time, the interrupt directs control to the
 overlay manager. The overlay manager checks whether the right overlay
 is loaded into memory, loads it if necessary, and calls the function.
 Because there is a fixup record in the .OBJ for the function call, the
 linker can set everything up correctly.

 On the other hand, with a function pointer, the compiler creates a
 fixup record for the address that the pointer references. However,
 there is no indication in the fixup record that this address is for a
 function. Therefore, if you link the function in as an overlay, the
 linker does not insert a call to the overlay manager and instead does
 a standard fixup.

 As a result, if you indirectly call a function located in a not-as-yet
 loaded overlay, the overlay does not get loaded. Nevertheless, control
 is still transferred to the address at which the function is thought
 to reside, which can only mean disaster for the executing program.


 65. /PAU Linker Option Doesn't Function in Some Versions of LINK

 Product Version(s): 3.61 3.65 3.69 5.01.20 5.05 | 5.01.20 5.05
 Operating System:   MS-DOS                      | OS/2
 Flags: ENDUSER |
 Last Modified: 21-FEB-1990    ArticleIdent: Q58781

 The /PAU (PAUSE) linker option tells LINK to pause in the link session
 and display a message before it writes the executable file to disk,
 allowing you to insert a new disk on which to store the executable
 file.

 In Microsoft LINK.EXE Versions 3.61, 3.65, 3.69, 5.01.20, and 5.05,
 the /PAU linker option does not pause the link session.

 Microsoft is researching this problem and will post new information
 here as it becomes available.

 In versions where the /PAU linker option functions correctly, LINK
 displays the following message before it creates the executable file:

    About to generate .EXE file
    Change diskette in drive ___ and press <ENTER>

 LINK resumes processing after the ENTER key is pressed.


 66. /INC and Overlays Are Not Supported at the Same Time

 Product Version(s): 5.01.20 5.01.21 5.02 5.03
 Operating System:   MS-DOS
 Flags: ENDUSER | docsup
 Last Modified: 15-MAY-1990    ArticleIdent: Q59279

 LINK.EXE does not support the use of /INCREMENTAL (or /INC) switch and
 overlays at the same time. This is because ILINK.EXE, which is invoked
 by the /INC option, does not support overlays. One of the two
 operations is ignored.

 The linker produces a working executable file, but one of the
 following WARNING messages may be produced:

    L4013: Overlays: option ignored for segmented-executable file
    L4014: /INCREMENTAL : Option ignored for realmode executable file

 If no warning message is produced, the linker takes an unpredictable
 path. If this is the case, the executable file that is produced could
 be corrupted and should NOT be relied upon.


 67. Incomplete EXPORTS List May Cause L2022 and L2029

 Product Version(s): 3.65
 Operating System:   MS-DOS
 Flags: ENDUSER |
 Last Modified: 12-MAR-1990    ArticleIdent: Q59385

 Compiling and linking a Windows program and receiving the following
 two link errors can be caused by an incomplete EXPORTS list:

    LINK : error L2022: ProcedureName : export undefined
    LINK : error L2029: 'ProcedureName' : unresolved external

 Windows programming involves the creation of a .DEF (definitions)
 file. All Windows procedures to be exported must be listed in this
 file. The following is an example:

    EXPORTS     ProcedureName

 When this list is incomplete, the L2022 error is generated. The L2029
 error can be generated if the case of the EXPORT line doesn't match
 the case of the actual function.

 Listing all procedures to be exported in the .DEF file prevents both
 of these errors.

 Note: These errors can also occur with Presentation Manager programs
 or programs that use DLLs under OS/2.


 68. Why the /HIGH Switch Is Not Used with High-Level Languages

 Product Version(s): 3.65
 Operating System:   MS-DOS
 Flags: ENDUSER |
 Last Modified: 15-MAR-1990    ArticleIdent: Q59535

 The linker option /HIGH is used with assembly language programs to
 load an .EXE file as high as possible in memory. Without the /HIGH
 option, LINK places the .EXE file as low as possible.

 /HIGH is not used with high-level languages because it prohibits the
 use of dynamic memory allocation by the program. Furthermore, C
 run-time start-up code specifies /DOSSEG, which forces low load and
 Microsoft run-time segment layout.

 When a program is linked with /HIGH, MS-DOS loads the program at the
 highest possible memory location available, usually 0xFFF0. All memory
 between the program's segments (which are high) and the program's PSP
 (which is low) is now considered program RAM, owned by the program.
 You can no longer allocate or free that memory.

 Therefore, calls to routines such as malloc() and free() fail. This
 causes problems for the following reasons:

 1. Some memory is dynamically allocated during function calls from
    high-level languages.

 2. The memory structure required by Microsoft high-level languages for
    tracking used/freed memory is not available.

 You can use /HIGH if you write your own start-up code, but your
 programs cannot call most of the routines from the C run-time library.

 The only reason /HIGH is still available to the linker is that early
 versions of Microsoft FORTRAN and Microsoft Pascal generated code that
 had to be linked with /DSALLOCATE, which relocates all addresses
 within DGROUP in such a way that the last byte in the group has the
 offset 0xFFFF. The /HIGH switch is used in conjunction with the
 /DS(ALLOCATE) switch.

 For more information, search the knowledge base with the following
 query:

    S_LINK and /HIGH and /DS

 You can also read the section "Using the /HIGH and /DSALLOCATE
 Switches" on Page 719 ff in the "MS-DOS Encyclopedia."


 69. OS/2 Module Definition File Syntax

 Product Version(s): 5.01.21 5.02 5.03 5.05
 Operating System:   OS/2
 Flags: ENDUSER | S_C
 Last Modified: 16-MAR-1990    ArticleIdent: Q59536

 The following is extracted from Ray Duncan's "Advanced OS/2
 Programming," Page 737:

    Module definition (DEF) files are simple ASCII text files that are
    interpreted by the linker during the construction of an application
    program, dynlink library, or device driver. The directives in DEF
    files cause information to be built into the executable file's
    header, which is later interpreted by the system when the program,
    library, or driver is loaded.

    Enter all DEF file directives and keywords in uppercase letters.
    File, segment, group, and procedure names can be lowercase or
    uppercase. Lines beginning with a semicolon (;) are treated as
    comments.

    Figure E-1. DEF file directives documented in Appendix E
    --------------------------------------------------------

    CODE        Assigns characteristics to code segments
    DATA        Assigns characteristics to data segments
    DESCRIPTION Embeds text in executable file
    EXETYPE     Specifies host operating system
    EXPORTS     Names functions exported for dynamic linking by other
                programs
    HEAPSIZE    Specifies initial size of local heap (C programs only)
    IMPORTS     Names functions that will be dynamically linked at load
                time
    LIBRARY     Builds dynlink library or device driver
    NAME        Builds application program
    OLD         Specifies ordinal compatibility with previous version of
                dynlink library
    PROTMODE    Flags file as executable in protected mode only
    REALMODE    Allows file to be executed in real mode
    SEGMENTS    Assigns characteristics to selected segments
    STACKSIZE   Specifies size of stack used by primary thread
    STUB        Embeds MS-DOS-compatible program in new executable file

 For further information, refer to Appendix E, Module Definition File
 Syntax, in "Advanced OS/2 Programming" or Chapter 19, Using Module-
 Definition Files, in the "Microsoft FORTRAN CodeView and Utilities
 User's Guide," packaged with FORTRAN Version 5.00.


 70. Linker Error L4047 May Be Benign

 Product Version(s): 5.10    | 5.10
 Operating System:   MS-DOS  | OS/2
 Flags: ENDUSER |
 Last Modified: 18-APR-1990    ArticleIdent: Q59936

 The following linker error may be a benign error if it occurs with an
 application that links with the C Version 6.00 start-up code:

    L4047 - Multiple code segments in module of overlayed program
            incompatible with /CO

 This is a new error for LINK Version 5.10 and is to be expected.

 If an application is built with the C Version 6.00 run-time library,
 there is a second segment to hold floating-point math routines. This
 segment (EMULATOR_TEXT) does not have any CodeView information in it.
 However, from the linker's perspective, the extra segment MAY be an
 error and it is warning the user of such. In this case, it is a benign
 warning message.


 71. NODATA and pwords Parameters Reversed in EXPORT Statement Docs

 Product Version(s): 5.01.21 5.02 5.03 5.05 5.10 | 5.01.21 5.02 5.03 5.05 5.10
 Operating System:   MS-DOS                      | OS/2
 Flags: ENDUSER | docerr
 Last Modified: 25-MAY-1990    ArticleIdent: Q61605

 The EXPORT statement used in module definition (.DEF) files is
 incorrectly documented in several places with the last two parameters
 reversed. The "pwords" parameter should be the last parameter, but it
 is listed second from the end. The "NODATA" parameter is listed last,
 but should be second from the end. The correct EXPORT statement syntax
 is as follows:

    entryname [=internalname] [@ord[RESIDENTNAME]] [NODATA] [pwords]

 Note that the "pwords" parameter is listed as "iopl-parmwords" in some
 of the documentation.

 The documentation with the incorrect EXPORT statement syntax with
 reversed parameters is as follows:

 - The C version 6.00 online help for LINK under the EXPORT statement
   syntax

 - On Page 334 of "The Microsoft CodeView and Utilities User's
   Guide" for version 2.30 in Section 19.9, "The EXPORTS
   Statement" (shipped with FORTRAN 5.00 and BASIC PDS 7.00)

 - On Page Update-52 of "The Microsoft CodeView and Utilities
   Update" for version 2.20 in Section 7.8, "The EXPORTS
   Statement" (shipped with C 5.10, MASM 5.10, and Pascal 4.00)


 72. Fatal /nologo and /e Switch Interaction

 Product Version(s): 1.20   | 1.20
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER | buglist1.20
 Last Modified: 22-JUN-1990    ArticleIdent: Q62375

 Using the /nologo switch in conjunction with /e switch can cause ILINK
 version 1.20 to fail. The problem will occur when an incremental link
 cannot be performed and the command specified by the /e switch is
 performed instead. If the /e switch is preceded anywhere on the
 command line by /nologo, then the link will fail.

 For example, the following command line

     ILINK /nologo /e "link hello;" hello.exe

 where hello.obj exists but hello.exe doesn't, will produce the
 following messages:

    Microsoft (R) Segmented-Executable Linker  Version 5.10
    Copyright (C) Microsoft Corp 1984-1990.  All rights reserved.

    LINK : fatal error L1089:  : cannot open response file
    ILINK : warning L4252: file '/e.exe' does not exist
    ILINK : performing full link
    ILINK : fatal error L1233: 'link' returned 2

 Placing the /nologo switch after the /e switch on the command line
 will alleviate the problem.

 Microsoft has confirmed this to be a problem with LINK version 1.20.
 We are researching this problem and will post new information here as
 it becomes available.


 73. L4050 Incorrectly Documented in Online Help

 Product Version(s): 5.10   | 5.10
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER | docerr buglist5.10 S_PWB
 Last Modified: 24-JUL-1990    ArticleIdent: Q63235

 When linking a very small program with /EXEPACK, Microsoft LINKer
 version 5.10 sometimes gives the following error message:

    LINK: warning L4050: file not suitable for /EXEPACK; relink without

 The online Help documentation returns the following incorrect
 information:

    LINK warning L4050

    too many public symbols for sorting

    The linker uses the stack and all available memory in the near
    heap to sort public symbols for the /MAP option. If the number of
    public symbols exceeds the space available for them, this warning
    is issued and the symbols are not sorted in the map file but are
    listed in an arbitrary order.

    Reduce the number of symbols.

 The correct documentation for this error (except the number) is as
 follows and can be found in the online Help under L1114:

    Fatal LINK error L1114

    file not suitable for /EXEPACK; relink without

    For the linked program, the size of the packed load image plus
    packing overhead was larger than that of the unpacked load image.

    Relink without the /EXEPACK option.

 Because of its noncritical nature, this LINKer error was changed from
 its previous status of a fatal error to a simple warning in LINK
 version 5.10. The warning associated with L4050 in earlier versions of
 the LINKer will rarely appear in LINK 5.10, but if it does, it will
 have the number L4070.



 74. Parenthesis in Filename May Cause L1027: Unmatched Parenthesis

 Product Version(s): 3.x 4.06 4.07 5.01.21 5.03 5.05 5.10 | 5.01.21 5.03 5.05
 Operating System:   MS-DOS                               | OS/2
 Flags: ENDUSER |
 Last Modified: 10-JUL-1990    ArticleIdent: Q63624

 When linking object files into executable programs, the error L1027:
 "Unmatched left/right parenthesis" may be incorrectly generated for
 files that contain a parenthesis in the filename. This will only occur
 when the object module is in the current directory and either of the
 following conditions is true:

 1. If the object module being linked has a left parenthesis as the
    first character in its name, but NOT a right parenthesis as the last
    character.

 2. If an object filename has a right parenthesis as the last
    character in the name, but NOT a left parenthesis as the first.

 If the object module is NOT in the current directory, then the L1027
 error will occur only if the second condition above is true.

 This information applies to all versions of LINK.EXE that support
 overlays.

 Normally, parentheses are put around the names of one or more object
 modules when linking to inform LINK that the enclosed modules are to
 be in an overlay. Therefore, if a left (or right) parenthesis comes
 immediately before (or after) the name of an object module, LINK will
 expect a right (or left) parenthesis immediately after (or before) the
 name. If the parentheses do not match, a fatal L1027 error will be
 generated.

 For example, the following LINK command line causes an "Unmatched left
 parenthesis" error when the object module ABC.OBJ is in the current
 directory:

    link (abc;

 However, if ABC.OBJ is in a subdirectory, then the parenthesis is
 embedded in the middle of the path/filename string and no error is
 generated, as shown below:

    link temp\(abc;

 For the same reason, a file ABC).OBJ will NOT give an error if linked
 with the following line:

    link abc).obj;

 On the other hand, leaving off the .OBJ extension will result in the
 L1027 error:

    link abc);

 By the same reasoning, the placement of a left or right parenthesis in
 the middle of an object filename does not cause an error. The
 following three LINK lines all work correctly:

    link a(bc;
    link a()bc;
    link a)bc;


 75. ILINK 1.20 and 1.21 Are Not Backwards Compatible

 Product Version(s): 1.20 1.21 | 1.20 1.21
 Operating System:   MS-DOS    | OS/2
 Flags: ENDUSER |
 Last Modified: 24-OCT-1990    ArticleIdent: Q65817

 Using ILINK version 1.20 or 1.21, after doing a full link using a
 bound linker earlier than version 5.10 or a DOS linker earlier than
 version 4.10, causes the following message:

    ILINK : warning L4267: invalid .ILK file
    ILINK : performing full link

 If you use the ILINK version that came with the linker you are using,
 the .ILK file will be recognized correctly. ILINK versions 1.20 and
 1.21 are not "backwards compatible" and will not work correctly with
 earlier .ILK files.


 76. Unexpected DOS Error: 14 Generated by Using /INC

 Product Version(s): 5.10
 Operating System:   MS-DOS
 Flags: ENDUSER | s_quickc s_c
 Last Modified: 24-OCT-1990    ArticleIdent: Q66055

 Programs linked with the /INC (Prepare for Incremental Link) switch
 cause the following error if the program is executed using the
 Microsoft Windows version 3.00 Run command:

    Unexpected DOS error: 14.

 The Run command is located on the File menu in both the Windows
 Program Manager and the File Manager. If the program is run from a
 prompt in real DOS or in a DOS session of Windows 3.00, it executes
 properly.

 While this seems like a problem with the Microsoft Linker, Windows 3.0
 is actually at fault here. The use of the /INC switch causes the
 linker to create a segmented executable. When Windows attempts to run
 this .exe, it fails to recognize that it is a full screen application
 (ie: not a windows app) and subsequently tries to execute it as a
 Windows application. This bug has been entered into the Windows bug
 database and should be fixed in a future release.

 Note: This may appear to be a problem with QuickC and/or C version
 6.00 if the incremental link option is turned on. In fact, it is a
 linking issue, not a compiler issue.

 To workaround this problem, turn off the /INC switch.


 77. Response Filename Cannot Exceed 32 Characters

 Product Version(s): 5.01.21 5.03 5.05 | 5.01.21 5.03 5.05
 Operating System:   MS-DOS            | OS/2
 Flags: ENDUSER | buglist5.01.21 buglist5.03 buglist5.05 fixlist5.10
 Last Modified: 12-NOV-1990    ArticleIdent: Q66698

 When using a complete path specification for a response file with
 LINK.EXE versions 5.01.21, 5.03, and 5.05, there is a limit of 32
 characters that cannot be exceeded. The following example illustrates
 this:

    LINK @d:\c600\files\project\test\myfile.lnk

 This will fail with the following error:

    LINK : Fatal error L1089 : D:\C600\FILES\PROJECT\TEST\MYFIL :
         cannot open response file

 In LINK version 5.10, this limit has been increased to 255 characters.


 78. Linker Does Not Search Specified Drive for Libraries

 Product Version(s): 5.01.21 5.03 5.05 5.10 5.11  | 5.01.21 5.03 5.05 5.10 5.1
 Operating System:   MS-DOS                       | OS/2
 Flags: ENDUSER | buglist5.01.21 buglist5.03 buglist5.05 buglist5.10 buglist5.
 Last Modified: 12-NOV-1990    ArticleIdent: Q66699

 A library name can be embedded into an .OBJ module for the linker to
 search to resolve external references. This library name can either be
 the library name itself or the full path to the library. In the case
 of the full path to the library, the linker cannot handle a drive
 specifier.

 For example, with Microsoft C, the #pragma comment command is used to
 specify the library. If the following line is used

    #pragma comment (lib, "c:\C600\LIB\graphics.lib")

 the compiler will add a COMENT record to the .OBJ instructing the
 linker to search the C600\LIB subdirectory on drive C for the
 GRAPHICS.LIB library.

 The problem is that the linker will not search drive C but will
 instead search the default drive. When the library and/or path is not
 found, it will prompt for the path to the library. This is an error.

 Microsoft has confirmed this to be a problem in the Segmented Linker
 versions 5.01.21, 5.03, 5.05, 5.10, and 5.11. We are researching this
 problem and will post new information here as it becomes available.


 79. L2002 When Creating a Dynamic Link Library

 Product Version(s): 5.10 5.11
 Operating System:   OS/2
 Flags: ENDUSER | buglist5.10 buglist5.11
 Last Modified:  4-DEC-1990    ArticleIdent: Q67004

 The code sample below produces the following error when compiled and
 linked with the following switches:

 cl /c /Gs /Alfu /ML foo.c

 link foo.obj, foo.dll,,, foo.def;

 Error
 -----

    L2002: fix-up overflow at 2 in segment FOO_TEXT
     frm seg _DATA, tgt seg _DATA, tgt offset 0

 This error is produced when creating a dynamic link library and
 specifying _loadds on function entry (either with the /Au switch or
 the _loadds keyword). If each segment that comprises the default data
 segment is of zero length, the linker will return this error. In
 earlier linkers, the error wasn't generated.

 The following are three possible workarounds:

 1. If the function does not contain any static data, compile with the
    option /Aw (DS not reloaded on function entry) and/or remove the
    _loadds keyword from the function declaration.

 2. Turn on stack checking (compile without /Gs option).

 3. Declare data so at least one of the segments in DGROUP is not zero
    length.

    a. For _DATA, declare initialized global or static data.

    b. For _CONST, declare a constant in the program.

    c. For _BSS, declare uninitialized static data.

 Microsoft has confirmed this to be a problem in versions 5.10 and
 5.11. We are researching this problem and will post new information
 here as it becomes available.

 Sample Code
 -----------

 void foo(int i)
 {
    char c;

    c=i;
 }


 80. NOF Is Default for LINK, Not /F as C "Reference" States

 Product Version(s): 5.10   | 5.10
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER | docerr S_C
 Last Modified:  4-JAN-1991    ArticleIdent: Q67085

 On pages 30 and 31 of the "Microsoft C Reference" manual shipped with
 C versions 6.00 and 6.00a, there are contradictory references to the
 far-call translation options available for LINK. On page 30 under the
 /F[ARCALLTRANSLATION] option, far-call translations are listed as
 being "turned on by default." On the other hand, on page 31 under the
 /NOF[ARCALLTRANSLATION] option, far-calls are listed as being "off by
 default."

 The statement on page 30 is the one that is incorrect because the
 correct default for far-call translations is "off." Far calls are done
 only when /F is explicitly specified to LINK.

 Note that when the CL command is used to invoke LINK, CL itself is
 responsible for passing the /F option to the linker.


 81. EXE Checksum Incorrect If linked with /CO or /E

 Product Version(s): 3.xx 4.0x 4.10 5.0x 5.10 5.13 | 5.0x 5.10 5.13
 Operating System:   MS-DOS                        | OS/2
 Flags: ENDUSER |
 Last Modified:  6-FEB-1991    ArticleIdent: Q67795

 According to "The MS-DOS Encyclopedia," a DOS .EXE file contains a
 checksum value in the .EXE file header. This checksum value should
 allow the summation of all words in the .EXE file to equal FFFFh.
 However, if you use the /Exepack or the /COdeview options when linking
 a program, the checksum value will not be calculated correctly.
 Current versions of MS-DOS ignore this checksum so this will not cause
 any noticeable problems.

 Sample Code:
 ------------

 #include <stdio.h>
 #include <stdlib.h>

 main (int argc, char * argv[])
 {
    FILE * fp;
    unsigned int nxt= 0, sum= 0;
    unsigned char bl, bh;

    if (argc != 2)
       exit (-1);
    if ((fp= fopen (argv[1], "rb"))== NULL)
       exit (-1);
    while (! feof(fp))
    {
       bl= fgetc (fp);
       if (! feof(fp))
          bh= fgetc (fp);
       else
          {
          bl= 0;
          bh= 0;
          }
       sum= sum+ nxt;
       nxt= (unsigned int) bh* 256U+ (unsigned int) bl;
    }
    nxt&= 0xFF;
    sum+= nxt;
    printf ("sum = %X\n", sum);
 }


 82. L1008: "Segment Limit Too High" May Be Caused by Missing Colon

 Product Version(s): 3.x 4.06 4.07 5.01.21 5.03 5.05 5.10 | 5.01.21 5.03 5.05
 Operating System:   MS-DOS                               | OS/2
 Flags: ENDUSER |
 Last Modified: 17-DEC-1990    ArticleIdent: Q46733

 When linking, the following error may be caused by incorrectly
 specifying the parameters for the /SE switch on the link command line
 with the colon:

    LINK : fatal error L1008: SE: segment limit set too high

 To generate the error, link using the /SE switch, then insert a space
 and the number of segments for the linker to use, such as the
 following:

    LINK /SE 1024

 The correct syntax for the /SE option is with a colon separating the
 switch from the numeric argument as follows:

    LINK /SE:1024


 83. The Purpose of Module Definition Files

 Product Version(s): 5.01.21 5.02 5.03 5.05 5.10 5.13 | 5.01.21 5.02 5.03 5.05
 Operating System:   MS-DOS                           | OS/2
 Flags: ENDUSER |
 Last Modified: 17-DEC-1990    ArticleIdent: Q27134

 Module-definition files (.DEF) are used by LINK when building Windows
 and OS/2 programs and dynamic-link libraries (DLLs). A .DEF file
 describes the name, size, format, functions, and segments of an
 application or DLL.

 A module-definition file contains one or more module statements. Each
 module statement defines an attribute of the executable file. The
 module statements and the attributes they define are listed below:

 Statement         Attribute
 ---------         ---------

 NAME              Name and type of application
 LIBRARY           Name of dynamic-link library
 DESCRIPTION       One-line description of the module
 CODE              Default attributes for code segments
 DATA              Default attributes for data segments
 SEGMENTS          Attributes for specific segments
 STACKSIZE         Local-stack size, in bytes
 EXPORTS           Exported functions
 IMPORTS           Imported functions
 STUB              Adds a DOS Version 3.x executable file to the beginning
                   of the module, usually to terminate the program when
                   run in real mode
 HEAPSIZE          Local-heap size, in bytes
 PROTMODE          Specifies that the module runs only in OS/2 protected
                   mode
 REALMODE          Specifies that the module is for real-mode Windows.
 OLD               Preserves export ordinal information from a previous
                   version of the library

 The following rules govern the use of these statements in a module-
 definitions file:

 1. If you use either a NAME or a LIBRARY statement, it must precede
    all other statements in the module-definition file.

 2. You can include source-level comments in the module-definition
    file, by beginning a line with a semicolon (;). The OS/2 utilities
    ignore each such comment line.

 3. Module-definition keywords (such as NAME, LIBRARY, and SEGMENTS)
    must be entered in uppercase letters.

 For more information, refer to the utility reference or online help
 that accompanied your particular compiler or assembler.


 84. Working Around Link Error "L1064: Out of Memory"

 Product Version(s): 5.03 5.05 5.10 5.13 | 5.03 5.05 5.10 5.13
 Operating System:   MS-DOS              | OS/2
 Flags: ENDUSER |
 Last Modified: 17-DEC-1990    ArticleIdent: Q45718

 The linker error "L1064: Out Of Memory" is new with LINK version 5.03,
 which was first shipped to individuals using IMSL libraries with
 FORTRAN 4.10, and was then shipped with FORTRAN 5.00. The description
 of the error is as follows (from the "Microsoft FORTRAN, Microsoft
 CodeView and Utilities User's Guide"):

    The linker was not able to allocate enough memory from the
    operating system to link the program. On OS/2 try increasing the
    swap space. Otherwise, reduce the size of the program in terms of
    code, data, and symbols. On OS/2, consider splitting the program
    into dynalink libraries.

 In DOS, the only ways to work around the error are the following:

 1. Remove any memory-resident software or device drivers that may be
    limiting the available memory of the machine.

 2. Reduce the program size, as described above.

 In OS/2, the easiest way to work around the error is to increase the
 swap space, as follows:

 1. Close other screen groups and remove other processes from
    memory to free up both RAM and swap space on the swap drive.

 2. Create more free disk space on the drive that is pointed to by
    the SWAPPATH setting in the CONFIG.SYS file. (Delete or move files,
    or change the setting to a drive with more free space.)

 3. Possibly DECREASE the swap value set by the SWAPPATH variable (do
    this with caution -- read below).

 Explanation of the SWAPPATH Setting in CONFIG.SYS
 -------------------------------------------------

 Swapping must be enabled via the MEMMAN setting in CONFIG.SYS for the
 SWAPPATH setting to be acknowledged at all (usually "MEMMAN=SWAP" or
 "MEMMAN=SWAP,MOVE").

 The default setting for SWAPPATH after setting up OS/2 is usually as
 follows:

    SWAPPATH=C:\OS2\SYSTEM 512

 The drive setting indicates the drive and directory where the space
 for the swapper file will be allocated. If no SWAPPATH variable is
 set, the swapper file is allocated in the root directory on the boot
 drive. The number that follows indicates the amount of free space
 which must be left on this drive when the swapper file has grown to
 its maximum size. (This number, by itself, says nothing about the
 maximum size of the swapper file.) Given the settings above, the
 maximum size of the swapper file can be easily calculated by the
 following:

    (free space on Drive C) - (SWAPPATH value) = max. swap file size

 Therefore, increasing the SWAPPATH value DECREASES the amount of space
 available for the swapper file.

 The swapper value can be decreased, and the system will allow values
 down to 0 (zero). However, because OS/2 does time-slicing between
 processes and may need to write to the disk in question, decreasing
 the swapper value below 512K (the system default) is not recommended.
 This workaround should be used only if you have the value set to
 greater than 512K (the range of valid values is from 0 to 32,767). If
 this is the case, set the SWAPPATH value to 512 and reboot the
 machine. If this method does not solve the problem, you must clear
 space on the hard disk by deleting or moving files.


 85. Patches Available for Running Utilities Under Novell NetWare

 Product Version(s): 5.10
 Operating System:   MS-DOS
 Flags: ENDUSER | appnote SC0381.ARC s_codeview s_pwb s_c
 Last Modified:  6-FEB-1991    ArticleIdent: Q68659

 When LINK version 5.10 is run under a Novell network, LINK may fail
 with the following error:

    L1085: cannot open temporary file

 In addition, the C version 6.00 Setup program (SETUP.EXE), the
 Programmer's WorkBench (PWB) for DOS versions 1.00 and 1.10, and
 real-mode CodeView (CV.EXE) versions 3.00, 3.10, and 3.11 may all hang
 when run under some Novell NetWare software.

 These problems are directly related to the network software, but may
 be corrected with a set of patch files available from Microsoft as an
 application note titled "Network Patches for Utilities" (SC0381).
 Application notes can be obtained by calling Microsoft Product Support
 Services at [phone].

 The "Network Patches for Utilities" application note can also be found
 in the Software/Data Library by searching on the keyword SC0381, the Q
 number of this article, or S12898. SC0381 was archived using the
 PKware file-compression utility.

 The following is the complete text of the application note, which
 includes the details of the problems mentioned above:

 ======================================================================
                     Network Patches for Utilities
 ======================================================================

 The enclosed Network Patches for Microsoft Utilities disk contains the
 following five files:

    README.DOC
    CVPATCH.EXE
    PWBPATCH.EXE
    SETUPFIX.EXE
    LINK.EXE

 These files solve conflicts with certain network setups. Please be
 sure to make backup copies of the original files.

 Network Patch Files
 -------------------

 When run under certain network software, some Microsoft utilities may
 hang. The enclosed patch files are designed to correct these problems
 for CodeView versions 3.00, 3.10, and 3.11; the Programmer's WorkBench
 (PWB) versions 1.00 and 1.10; and the C 6.00 Setup program.

 To install the patches, first copy the patch files (PWBPATCH.EXE,
 CVPATCH.EXE, and SETUPFIX.EXE) to the directories where you have
 installed PWB, CodeView, and Setup, respectively. Each patch assumes
 that the utility file it is to patch is in the same directory.

 Run SETUPFIX.EXE to patch SETUP.EXE. The original file will be saved
 as SETUP.BAK. Run CVPATCH.EXE to patch CV.EXE. The original file will
 be saved as CV.BAK. Run PWBPATCH.EXE to patch PWBED.EXE. The original
 file will be saved as PWBED.BAK. The patched utilities should run free
 of network interference.

 Microsoft LINK Version 5.13
 ---------------------------

 LINK version 5.13 includes code to work around another problem that
 sometimes occurs when running on a network. On large projects, the
 linker needs to open some temporary files to work around DOS memory
 limitations. LINK version 5.10 (supplied with C 6.00) will sometimes
 fail in its attempts to open a temporary file when run under certain
 network software.

 The problem actually lies in the network software, not the linker.
 When the network is loaded, the return value from an open call
 sometimes gets corrupted. When the call fails, it is because an "Out
 of handles" error (EMFILE) is returned as a "No such file or
 directory" error (ENOENT). If this occurs, LINK 5.10 halts with an
 "L1085: cannot open temporary file" error.

 LINK 5.13 includes a change to correct for the above situation (even
 though the problem is in the network software). When LINK version 5.13
 receives an ENOENT error on a failed open call, it will still try to
 free some file handles and reopen the temporary file, regardless of
 the error returned.

 To make the correction, locate LINK version 5.10 and replace it with
 LINK version 5.13 from the enclosed disk. Again, be sure to save a
 backup copy of the original file (LINK 5.10).


 86. L2025 LINK Error May Be Caused by Conflicting Library Routines

 Product Version(s): 3.x 4.06 4.07 5.0x 5.10 5.13 | 5.01.21 5.02 5.03 5.10 5.1
 Operating System:   MS-DOS                       | OS/2
 Flags: ENDUSER | s_lib
 Last Modified: 24-JAN-1991    ArticleIdent: Q44465

 All variables and routines in a module within a library will be linked
 into a program when any single variable or routine residing in that
 module is referenced. This can cause the following linker error if two
 or more modules contain definitions for the same symbol:

    L2025  symbol defined more than once

 For example, in the diagram below, module1 contains routines "a", "b",
 and "c". The module2 contains routines "c", "d", and "e". When main()
 references "a" and "e", the linker links module1 and module2 from the
 library. This results in "c" being defined twice. Removing "c" from
 one of the modules, recompiling the module, and replacing the module
 in the library with the LIB utility operator "-+" will prevent "c"
 from being multiply defined.

                         +-----------+
                         |           |
                         | calls "a" |
                         | calls "e" |
                       / |           | \
                      /  +-----------+  \
                     /       main()      \
                    v                     v
                +-------+             +-------+
                |   a   |             |   c   |
                |   b   |             |   d   |
                |   c   |             |   e   |
                |       |             |       |
                +-------+             +-------+
                 module1               module2

 For each routine you want to be linked separately, compile a separate
 object file and add it to the library.






 Microsoft `M' Editor
 =============================================================================


 1. How to Put Microsoft Editor (M or MEP) into 43-Line Mode

 Product Version(s): 1.00   | 1.00
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified:  1-SEP-1988    ArticleIdent: Q28580

 To use the Microsoft Editor (M.EXE or MEP.EXE) in EGA 43-line mode,
 the TOOLS.INI file must be modified to include the following
 statement:

 HEIGHT:41

 (The number 41 is used because the last two lines are used by the
 editor as status/error lines. See Page 59 of the "Microsoft Editor for
 MS OS/2 and MS-DOS: User's Guide".)

 Once the TOOLS.INI is modified, the editor must be re-initialized.
 This process is done with the Initialize command. The default key
 stroke for this command is SHIFT+F8. Appendix A lists the values for
 the other .INI files provided with the editor. The following example
 demonstrates this process:

 1. Load TOOLS.INI.
 2. Modify TOOLS.INI.
 3. Save the file (ARG ARG SETFILE or leave and re-enter).
 4. Use the Initialize command (SHIFT+F8).

 After the initialization, the changes in the TOOLS.INI become active
 and the 43-line mode is in use.

 M.EXE runs in MS-DOS real mode, and MEP.EXE runs in OS/2 protected
 mode.


 2. Creating Macros for the Microsoft Editor

 Product Version(s): 1.00   | 1.00
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified:  1-SEP-1988    ArticleIdent: Q23051

 Macros for the Microsoft Editor are sequences of editor functions. For
 example, a macro to delete the word to the right of the cursor is
 defined as follows:

 worddelete:=arg meta pword sdelete

 The above macro is named "worddelete". To associate "worddelete" with
 a particular keystroke, the following command is needed:

 worddelete:ALT+W

 The macro "worddelete" is now bound to the keystroke "ALT+W". Note
 that the macro definition (i.e., ":=") resembles a Pascal assignment
 statement, but the keybinding uses a colon to delimit the macro name
 from the key to which it is assigned. The following is another
 example:

 filestamp:=curfilenam curfileext " - " curdate " " curtime
 filestamp:ALT+S

 This macro creates a file-time stamp that contains the filename, the
 current date, and the current time; it is assigned to the keystroke
 "ALT+S".


 3. File Size Limitations for the Microsoft Editor

 Product Version(s): 1.00   | 1.00
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER | TAR62237
 Last Modified: 29-AUG-1988    ArticleIdent: Q23609

 Question:

 What is the largest file the Microsoft Editor can load?

 Response:

 The size of the file is controlled by the operating system, not by
 the editor. The editor will read in a file of any number of bytes;
 however, you are limited by the temporary file space.

 The size of the drive pointed to by the TMP variable is the limiting
 factor. Because TMP often points to a (relatively small) RAM drive,
 such as VDISK or MS-RAMDRIVE, this is the most common file size
 limitation.

 A safe rule-of-thumb is that your TMP drive may need to be up to
 two times the size of the file being edited.

 The maximum number of lines a file can contain is 0x7FFFFFFF, but you
 will run out of disk space before you have too many lines.

 Both MS-DOS and OS/2 currently limit disk size (hence, file size)
 to 64K sectors, which normally is 32 megabytes.


 4. Unassigning Predefined Keys

 Product Version(s): 1.00   | 1.00
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER | TAR62300
 Last Modified:  1-SEP-1988    ArticleIdent: Q23754

 The following are two ways to unassign a predefined key:

 1. Assign the key to a different function.
 2. Assign the key to the "unassigned" function.

 If ALT+A currently is assigned to the ARG function, you can assign
 it to another function by putting the following line in your
 TOOLS.INI file:

 NewFunct:ALT+A

 If you don't want ALT+A to be assigned to any function, place the following
 line in your TOOLS.INI file:

 Unassigned:ALT+A.


 5. Error C1015 "Can't Open Include File" with MEP

 Product Version(s): 1.00
 Operating System:   OS/2
 Flags: ENDUSER | S_C buglist1.00
 Last Modified:  2-NOV-1988    ArticleIdent: Q35140

 The example program below generates the following error:

 Error C1015 "Can't open include file"

 The program must be compiled with one of the output-file switches
 (such as /Fc) or through a make file to generate this error.

 The include file os2.h opens two other include files: os2def.h and
 bse.h. The bse.h include file, in turn, opens three other include
 files: bsedos.h, bsesub.h, and bseerr.h.

 Microsoft has confirmed this to be a problem in Version 1.00. We are
 researching this problem and will post new information as it becomes
 available.

 The compiler attempts to open the last include file and generates the
 C1015 error. The total file count at this point is 15, as follows:

  1. stdin
  2. stdout
  3. stdprn
  4. stderror
  5. stdaux
  6. MEP
  7. source
  8. listing file
  9. os2.h
 10. os2 def.h
 11. bse.h
 12. bsedos.h
 13. bsesub.h
 14. bseerr.h
 15. tmp file

 The following sample code demonstrates the problem:

 #define INCL_BASE
 #include <os2.h>

 void main (void)
 void main (void)
 {
 }



 6. Maximum Number of Defined Macros Allowed in TOOLS.INI File

 Product Version(s): 1.00   | 1.00
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER | TAR63148
 Last Modified: 17-MAY-1988    ArticleIdent: Q24696

 Question:
    Is there a maximum number of macros, predefined and user-defined,
 allowed in the TOOLS.INI file?

 Response:
    The maximum number of defined macros allowed is 1024.


 7. BRIEF TOOLS.INI File Assigns Two Commands to F5 in M.EXE

 Product Version(s): 1.00    | 1.00
 Operating System:   MS-DOS  | OS/2
 Flags: ENDUSER |
 Last Modified:  1-SEP-1988    ArticleIdent: Q30474

 Problem:

 After I configure the Microsoft M.EXE Editor in the BRIEF mode and
 invoke Psearch (F5 key), I receive the following error message:

 "Invalid argument."

 However, Msearch (ALT+F5) functions correctly.

 Response:

 The BRIEF TOOLS.INI file assigns two commands to F5. The first
 occurrence in the file is for Psearch and the second is for
 DeleteWindow.

 To correct the problem, one of the commands should be mapped to a
 different key. Make sure the new key is not already in use.

 The following is an example of the incorrect portion of the
 BRIEF.INI file:

    ; TOOLS.INI file for BRIEF(tm) configuration
    [M]
           .
           .
           .
    Psearch:F5
           .
           .
           .
    ; WINDOWS
    ;
    ; Delete Current Window is F5
    DeleteWindow:=meta window
    DeleteWindow:F5
    ;
    ;
    ;
    ; BRIEF is a trademark of UnderWare, INC.


 8. Assigning Key Sequence to ENTER and BACKSPACE Keys

 Product Version(s): 1.00   | 1.00
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified: 29-AUG-1988    ArticleIdent: Q25407

 Functions can be assigned to the ENTER and BKSP (BACKSPACE) keys in
 the TOOLS.INI file, as in the following example:

 emacsnewl:enter
 emacscdel:bksp

 Consult Chapter 6 of the "Microsoft Editor User's Guide," titled
 "Function Assignments and Macros."


 9. CALLTREE Ignores Conditional Compilation Statements in Editor

 Product Version(s): 1.00   | 1.00
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER | S_C H_MASM
 Last Modified: 17-MAY-1989    ArticleIdent: Q44417

 The CALLTREE utility provided with the Microsoft Editor can be used to
 produce a graphical call-tree listing of a project. The following
 command line is an example of this utility. This command line creates
 a file called CALLS.TXT showing the relationship of the functions
 found in the four C source files shown below:

    calltree /c calls.txt main.c sub1.c sub2.c sub3.c

 If any of the files use conditional compilation directives, these are
 disregarded by CALLTREE and any functions that would not have been
 called appear in the call listing. An example of code that produces a
 misleading call listing is shown below. Although only one set of calls
 is compiled, both sets show up in the file produced by CALLTREE.

     void main( void )
     {
     #ifdef DEBUG
         dshow();
         ddone();
     #else
         fshow();
         fdone();
     #endif
     }

 To avoid this situation, a preprocessor listing should be produced
 using the /P switch with CL, and CALLTREE should then be run on the
 resultant file.

 This is a limitation of the utility. CALLTREE is meant to be a
 general-purpose tool for C and assembly programs, and is not designed
 to do any parsing or syntax checking.


 10. Microsoft Editor Fails to Find TOOLS.INI Using DOS Version 2.x

 Product Version(s): 1.00
 Operating System:   MS-DOS
 Flags: ENDUSER |
 Last Modified: 20-OCT-1988    ArticleIdent: Q28590

 Problem:

 When running the M.EXE editor under DOS Versions 2.x, the editor does
 not find the TOOLS.INI file. The error reported is "Unable to Read
 TOOLS.INI[]".

 The following demonstrates the problem:

 1. Rename QUICK.INI to TOOLS.INI.
 2. Set the environment variable INIT to the directory c:\mytools
    as follows:

    SET INIT=c:\mytools

 3. Load the M.EXE editor. It will come up with default settings,
    instead of reading TOOLS.INI.

 When running DOS Version 3.20 on an IBM PC AT, M.EXE correctly finds
 the TOOLS.INI file.

 Response:

 M.EXE and MEP.EXE use their startup name to find the right section in
 TOOLS.INI. For example, if you rename the editor to Z, it will look
 for [z] instead of [m] in the editor's section in TOOLS.INI.

 This process occurs in all cases except under DOS Versions 2.x. Under
 any 2.x version of DOS, the name of your program is not available, and
 instead, the compiler provides the arbitrary name "C".

 To work around this limitation in DOS Versions 2.x, change the
 editor's tagged section in TOOLS.INI file to use the tag [c] instead
 of [m]. If it is necessary to share files with DOS Versions 3.x
 systems, the editor's section in TOOLS.INI can be tagged [m c].

 The editor uses the same method to name the following, where * is
 replaced by the editor name or by "C" under DOS Versions 2.x:

 1. The virtual memory file, *-XXXX.VM
 2. The history-and-state file, *.TMP
 3. The compiler message file, *.MSG


 11. Using Full Pathnames to Compile Programs with M or MEP

 Product Version(s): 1.00   | 1.00
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER | TAR75085
 Last Modified: 20-OCT-1988    ArticleIdent: Q29150

 The full pathname of a file is not transferred to the compiler when an
 ARG COMPILE is executed in the Microsoft Editor for MS-DOS and OS/2.
 The following is an example:

 1. Invoke M.EXE as follows:

 M \c5\source\test.c

 2. Compile the program with ARG COMPILE. (The default value is
    ALT+A SHIFT+F3). The following line is displayed:

    CL /c /Zep /D LINT_ARGS test.c

    The full pathname is not given.

 If you plan on compiling from other directories, you should define
 the compile command using the %|F option. The default option %s uses
 only the filename. For example, the TOOLS.INI file could be modified
 as follows to get the default compile with the full pathname:

 extmake:c cl /c /Zep /D LINT_ARGS %|F

 You also can select portions of the full pathname, and use the name
 more than once, as in the following example:

 %d|F - obtains the drive (and colon)
 %p|F - obtains the path
 %f|F - obtains the filename (no extension)
 %e|F - obtains the extension

 You can combine the "dpfe" any way you wish, as in the following:

 %dpf|F.xyz

 This combination produces the drive, path, and filename, with the
 extension .XYZ added to the filename.


 12. Editor "User's Guide" C-Extension Sample Generates Warnings

 Product Version(s): 1.00   | 1.00
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified: 12-JUL-1988    ArticleIdent: Q29730

 Problem:
     When I compile the sample program on Page 85 of the "Microsoft
 Editor for MS OS/2 and MS-DOS: User's Guide," I get two warning
 messages.
    These warning messages are generated on the following two sections
 of the sample program:

    1. struct swiDesc swiTable [] = {
             { NULL, NULL, NULL }
        };

    2. struct cmdDesc cmdTable [] = {
             { "Upper", Upper, 0, BOXSTR | TEXTARG },
             { NULL, NULL, NULL, NULL }
        };

 Response:
   These warnings will not cause a problem. You can, however, make the
 following two changes:

    1. struct swiDesc swiTable [] = {
             { NULL, NULL, 0 }
        };

    2. struct cmdDesc cmdTable [] = {
             { "Upper", Upper, 0, BOXSTR | TEXTARG },
             { NULL, NULL, 0, 0 }
        };


 13. Missing Semicolon on Line 17 of Example on Page 85 in Manual

 Product Version(s): 1.00   | 1.00
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER | docerr
 Last Modified: 29-AUG-1988    ArticleIdent: Q29731

    On Page 85 of the "Microsoft Editor for MS OS/2 and MS-DOS: User's
 Guide," there is a missing semicolon on line 17.
    The following line is incorrect:

    cfile = FileNameToHandle("", NULL)

    It should read as follows:

    cfile = FileNameToHandle("", NULL);


 14. M.EXE Editor Macro to Join Current Line with Next Line

 Product Version(s): 1.00    | 1.00
 Operating System:   MS-DOS  | OS/2
 Flags: ENDUSER |
 Last Modified: 29-AUG-1988    ArticleIdent: Q30030

    The following macro will join the current line with the following
 line, leaving one space between the last character on the current line
 and the first character of the next line.
    Place the following three lines in the [M] and/or [MEP] section(s)
 of your TOOLS.INI file, or enter them from the keyboard using the
 ASSIGN function (ALT+= in the default keyboard setup):

    ;Macro to join current line with next line.
        join:=endline right arg down begline sdelete
        join:alt+j

    The following is a description of how the join macro works:

    1. Endline moves one place beyond the last character on the current
       line.
    2. Right moves one character further, to insert a space.
    3. arg introduces the argument to the next command (in this case,
       sdelete).
    4. down begline moves to the first character on the next line.

    This process defines a Streamarg for the command sdelete (S stands
 for Stream).
    Note that sdelete should be used, not ldelete, because the down
 begline sequence would have defined either a Linearg or a Boxarg,
 neither of which would join the lines.
    Use sdelete because it closes the stream of characters and/or white
 space between the starting cursor position and the ending cursor
 position.


 15. Microsoft Editor Macro Moves Text with TAB Key

 Product Version(s): 1.00   | 1.00
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified:  6-JAN-1989    ArticleIdent: Q30033

 The TAB key only moves the cursor. It does not move both the cursor
 and the text under the cursor (as it does in QuickC, Word, and many
 other editors).

 To move text and the cursor, put the following macro in your TOOLS.INI
 file in the [M] and/or [MEP] section(s):

    ;Macro to tab with insertion, as in QuickC and Word
        emacstab:=arg tab sinsert tab
        emacstab:ctrl+tab

 The "emacstab" macro (there is no significance to the name other than
 its similarity to M.EXE's EMACSNEWL and EMACSDEL functions) is invoked
 by pressing CTRL+TAB.

 Note: assigning this macro to CTRL+TAB will only function on
 enhanced-style keyboards. Older-style keyboards must use another set
 of keys for this macro assignment. On the older keyboards, assigning
 this macro to CTRL+TAB causes the macro to be ignored.

 The emacstab macro functions as follows:

 1. The Arg command introduces the argument (in this case, a
    "stream" arg).

 2. The Tab command moves you one tab stop to the right.

 3. The Sinsert command moves the highlighted text over to the tab
    stop.

 This macro leaves your cursor back where it started, so one more TAB
 moves your cursor to the right (on top of the shifted text).


 16. C Extension to Make Psearch Prompt for an Input in M.EXE

 Product Version(s): 1.00
 Operating System:   OS/2
 Flags: ENDUSER |
 Last Modified: 23-MAY-1988    ArticleIdent: Q30285

 Question:
    I wish to emulate the Brief Psearch (Plus Search) with the M.EXE
 editor. I want Psearch to prompt me to enter a search string. Can this
 be done with a macro or do I have to use a Microsoft C extension?

 Response:
     This emulation cannot be done with macros. However, it can be done
 with Microsoft C extensions.
     The following is an example of how to do so in a Microsoft C
 extension:

     1. Use DoMessage() to output a string saying something similar to
 the following:

     "Please enter the search string:"

     2. Use KbUnHook() to disable M.EXE's "logical keyboard." This
 gives you the "focus" of the keyboard so that keyboard input is no
 longer read by the editor, thus freeing you to input a string from the
 user.
     3. Parse the keyboard input and then process it appropriately by
 invoking the Psearch function.
     4. Use KbHook() to reenable the logical keyboard in M.

     The following is an alternate method:

     Use "ReadChar()" instead of "KbUnHook()" and "KbHook()."
 (Mentioned in steps two and four above.)

     For more information on the functions available for writing C
 extensions, please read the files EXT.DOC and EXT.H that are included
 with the Microsoft Editor Version 1.00.
     For general information on programming C extensions, please
 consult Chapter 8 of the "Microsoft Editor User's Guide."
     Appendix A of the "Microsoft Editor User's Guide" provides a
 comprehensive list of editing functions such as Psearch.
     Psearch searches forward for the previously defined string or
 pattern. Msearch (Minus Search) searches backward for the previously
 defined string or pattern.


 17. Debug Shown on M.EXE Help Screen Is Not a Supported Switch

 Product Version(s): 1.00   | 1.00
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER | docerr
 Last Modified: 15-JUN-1988    ArticleIdent: Q30365

    The Debug numeric switch that appears in the information file of
 the help screen in the Microsoft Editor Version 1.00 has not been
 implemented.
    There is no function associated with Debug.


 18. M.EXE C Extensions Documented in UTILITY.DOC, Not README.DOC

 Product Version(s): 1.00
 Operating System:   OS/2
 Flags: ENDUSER | docerr
 Last Modified: 26-MAY-1988    ArticleIdent: Q30534

    Page 70 of the "Microsoft Editor User's Guide" incorrectly states
 the following:

    "To create a successful C extension, you need to follow these
 guidelines:
        1. Check the README.DOC file to see what functions you can call
 from the standard C run-time library."

    Contrary to the above manual statement, C extensions are documented
 in UTILITY.DOC on the release disk, not in the README.DOC.



 19. Making Assignments to PLUS, MINUS and PRINT SCREEN Keys

 Product Version(s): 1.00   | 1.00
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER | tar66615
 Last Modified:  1-SEP-1988    ArticleIdent: Q31485

 It is possible to make key assignments to the PLUS, MINUS, and
 PRINT SCREEN keys on the numeric keypad.

 For more information on function assignments, macros, and keystrokes,
 consult section 6.2.1 of "The Microsoft Editor User's Guide."


 20. How to Load a C Extension that Is Not in Current Directory

 Product Version(s): 1.00
 Operating System:   OS/2
 Flags: ENDUSER | TAR75933 docerr
 Last Modified:  8-JUN-1988    ArticleIdent: Q30826

    Page 84 of the "Microsoft Editor for OS/2 and MS-DOS User's Guide"
 incorrectly infers that the M.EXE editor will search for a C-extension
 module along the DOS PATH under MS-DOS or OS/2 real mode when you
 place the following statement in the TOOLS.INI file:

    load:myext.exe

    To search for a C-extension module along the DOS PATH, you must
 instead use the following load switch syntax in the TOOLS.INI file:

    load:{$ENVAR: | dos path}filename.ext

 where you have the option of using $ENVAR: (a DOS environment
 variable) or an explicit directory path specification.
    You can prefix your filename with $PATH: or $INIT:. For example,
 "$PATH:filename.ext" means the "filename.ext" is to be found in the
 directories in the DOS PATH. This format is valid in any filename
 context. The following example will go to the STDIO.H file that
 actually is being used by the compiler:

    <arg> "$INCLUDE:stdio.h" <setfile>

    Also, when operating under OS/2, $ENVAR:, the explicit DOS path,
 and the extension on the filename are ignored. Instead, filename.DLL
 is searched for in your LIBPATH. Please note that LIBPATH under OS/2
 is not an environment variable. LIBPATH is a directive in the
 CONFIG.OS2 file.
    The following are examples of using the load switch in TOOLS.INI:

    ; load 'my.ext' from the current directory.
    ; Under OS/2, load my.dll from LIBPATH.
    load:my.ext

    ; load 'your.ext' from either the current directory or one
    ; of the directories on path
    ; Under OS/2, load 'your.dll' from LIBPATH
    load:$PATH:your.ext

    ; load 'c:\init\ourext'.
    ; Under OS/2, load 'ourext.dll' from LIBPATH
    load:c:\init\ourext



 21. An Example Where a Protect Mode C Extension Will Not Load

 Product Version(s): 1.00
 Operating System:   OS/2
 Flags: ENDUSER | TAR76121 TAR76251
 Last Modified:  8-JUN-1988    ArticleIdent: Q30827

 Problem:
    I am trying to create an extension to the MEP.EXE editor. I am
 unable to get the editor to load my C extension. To simplify things I
 tried to get the editor to load the sample SKEL; however, I was
 unsuccessful. I receive the following error messages when loading:

    "cannot load skel - invalid argument"
    "skel is an illegal setting"

    My LIBPATH is c:\os2\dll and skel.dll is placed there. If skel.dll
 is not in my libpath I would get the error "no such file or
 directory". My MAKE and DEF files for SKEL are as follows:

 SKEL MAKE FILE
 #
 # Makefile for the MEP Editor Extensions
 #
 SYS=\os2\dll

 .c.obj:
  cl -c -Gs -Asfu -G2 -Lp $*.c

 .obj.dll:
  link  /NOI /NOD exthdrp.obj $*.obj,$*.dll,nul.map,,$*.def;

 skel.obj:    skel.c skel

 skel.dll:    skel.obj skel.def

 $(SYS)\skel.dll:  skel.dll
        copy skel.dll $(SYS)

 SKEL DEF FILE

 LIBRARY  SKEL

 EXPORTS
  _ModInfo
  SKEL

 Response:
    The extension is not loaded because the DEF file is incorrect. The
 file should be as follows:

 SKEL.DEF:
    LIBRARY

    EXPORTS
            _ModInfo
            EntryPoint

    This file should be used with all the extensions that are written.
 It need not be modified.



 22. Tags Let You Use the Same TOOLS.INI File for M and MEP

 Product Version(s): 1.00
 Operating System:   OS/2
 Flags: ENDUSER | TAR76127
 Last Modified:  8-JUN-1988    ArticleIdent: Q30828

 Question:
    I have the same commands for M and for MEP. I want to load the
 QUICKHELP utility if I am running OS/2. However, in my TOOLS.INI file,
 if I put in the following information, MEP never reads the rest of
 the TOOL.INI file:

    [mep]
     load:qhmep
    [m mep]
     rest of the commands
     .
     .

    How should I do this without making two (almost identical) files,
 one for [m] and one for [mep]?

 Response:
    Through the use of tags, it is possible to use the same TOOLS.INI
 file in both protect mode and real mode/DOS. The tag must specify the
 program name along with the version of the operating system as in the
 following example:

    [m-3.2]    => MS-DOS 3.2
    [m-10.0]   => OS/2 1.0 protect mode
    [m-10.0R]  => OS/2 1.0 real mode
    [m-10.10]  => OS/2 1.1 protect mode
    [m-10.10R] => OS/2 1.1 real mode

    The following change should be made to your TOOLS.INI file:

        [m mep]
                 commands that are non operating system dependent
             .
             .
             .

        [mep-10.0]
             load:qhmep

    The number used in the tag is the major and minor version number of
 of the operating system being used. Under OS/2 this information can be
 found by calling the API routine DosGetVersion. The call can be made
 from any language that supports the use of the API,including C Version
 5.10, MASM Version 5.10, FORTRAN Version 4.10, PASCAL Version 4.10,
 and BASCOM Version 6.00. Under DOS, this information is displayed with
 the DOS VER command.


 23. Setting TMPSAV in TOOLS.INI file; M.TMP Cannot Be Suppressed

 Product Version(s): 1.00
 Operating System:   OS/2
 Flags: ENDUSER | TAR76606
 Last Modified:  8-JUN-1988    ArticleIdent: Q30829

 Question:
    How do I get the Microsoft Editor (both ME and MEP) to not create
 and use the M.TMP to record past editing sessions?
    I have tried setting the switch tmpsave:0 in the TOOLS.INI file,
 but this does not solve the problem. Is there some other switch I have
 not set properly or a way to exit without creating M.TMP?

 Response:
    There is no way to prevent the creation of the temporary file.
    The TMPSAV switch is used to control the maximum number of files
 about which information is kept between editing sessions. This
 information includes the cursor position and window layouts.
    When you edit one of these files again, the screen starts up as you
 left it. The default value is 20. If TMPSAV is set to 0, it causes all
 files to be saved. All other numeric values refer to the number of
 files that will be saved. The /t option specifies that any files
 edited are temporary; they are not saved in the M.TMP file.



 24. Protected-Mode C Extensions Fail with "Protection Fault"

 Product Version(s): 1.00 | 1.00
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER | docerr
 Last Modified: 29-AUG-1988    ArticleIdent: Q31009

 Problem:
    I am writing C extensions for the protected mode of OS/2. All my
 extensions fail with a general-protection fault. The sample program on
 Page 85 of the "Microsoft Editor for MS OS/2 and MS-DOS: User's Guide"
 also fails.

 Response:
    Page 78 of the "Microsoft Editor for MS OS/2 and MS-DOS: User's
 Guide" incorrectly states that the second argument is a NULL pointer.
    The programs are crashing because the incorrect value is being
 passed to the FileNameToHandle routine. This routine requires a
 pointer to a null string, not a null pointer.
    For example, the following statement

    cfile=FileNameTohandle("",NULL);

 should read as follows:

    cfile=FileNameTohandle("","");


 25. Two Toned Colors in <assign> Pseudo File Can Occur

 Product Version(s): 1.02    | 1.02
 Operating System:   MS-DOS  | OS/2
 Flags: ENDUSER | buglist1.02
 Last Modified: 29-JAN-1990    ArticleIdent: Q58029

 The <assign> pseudo file can consist of lines in blocks that alternate
 in color starting at the middle of the file. This appears as if you've
 changed multiple editor options, which have just been activated, when
 no changes were actually made. This does not affect the way M.EXE (or
 MEP.EXE) operates.

 To see the blocks of alternating color, follow the steps below:

 1. Invoke the editor.

 2. Press ALT+A <ASSIGN> F2, which implies ARG <ASSIGN> SETFILE.

 3. Press ALT+BACKSPACE, which implies UNDO.

 4. Press F9 ALT+BACKSPACE, which implies META UNDO.

 5. Page down until you see the colored blocks.

 Microsoft has confirmed this to be a problem with the Microsoft Editor
 Version 1.02. We are researching this problem and will post new
 information here as it becomes available.


 26. Return Type for ReadCmd Is PSWI, Not PCMD

 Product Version(s): 1.00 | 1.00
 Operating System:   OS/2 | MS-DOS
 Flags: ENDUSER | docerr
 Last Modified: 12-JAN-1989    ArticleIdent: Q31143

 Page 7 of the EXT.DOC file, located in the SOURCE\ME\EXT directory of
 the Microsoft C Optimizing Compiler Version 5.10, incorrectly lists
 the return type for the ReadCmd command as being PCMD.

 The correct return type is PSWI, which is documented in the EXT.H
 file.


 27. MEP Crashes OS/2 when Switching from Real-Mode Screen Group

 Product Version(s): 1.00   | 1.00
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |  TAR75546 TAR76522
 Last Modified: 28-OCT-1988    ArticleIdent: Q31144

 When running in OS/2 protected mode, the system may crash when
 switching between protected mode and real mode and using the ALT+ESC
 sequence. It may take several iterations of ALT+ESC before the failure
 occurs.

 The system crashes when switching from the real-mode session into a
 protected-mode session that is running MEP. When the system crash
 occurs, the following message appears:

     TRAP 000D

     <register contents>

     The system detected an internal processing error
     at location # 3430:0590
     Exception while in kernel mode

     The system is stopped

 This is not a problem in MEP; it is a problem in OS/2.

 You can work around this problem by not running MEP in the original
 ("default") protected-mode screen group. Instead, start a second
 protected-mode screen group and run MEP there. To move to the second
 protected-mode screen group, do the following:

 1. Press ALT+ESC from real mode to get to the original
    protected-mode screen group.

 2. Press ALT+ESC again to get to the MEP screen group.

 Running MEP in a second screen group prevents you from switching
 directly from real mode into the MEP screen group.

 Another workaround for this problem is to use the CTRL+ESC hotkey
 rather than the ALT+ESC command to leave the real-mode screen group.
 The CTRL+C hotkey brings you back to the program selector. Once
 there, you can select the next screen group by using the mouse or
 cursor keys.


 28. "Unable to Read TOOLS.INI" Message Appears in OS/2 with MEP

 Product Version(s): 1.00
 Operating System:   OS/2
 Flags: ENDUSER |
 Last Modified:  8-JUN-1988    ArticleIdent: Q31155

     MEP.EXE, the OS/2 version of the Microsoft editor, will give the
 following message when the INITIALIZE function is invoked (i.e.,
 SHIFT-F8 in the default keyboard setup):

    "Unable to read TOOLS.INI"

    This message will appear if the editor's name is left as MEP while
 the TOOLS.INI tag for the editor is labeled [M]. The two names must
 match.
    To correct the problem, either rename the editor to M, or label the
 tag [MEP].
    The tag can be set to [M MEP] if you wish to use the same TOOLS.INI
 settings for both real-mode and protected-mode versions of the editor.


 29. Purpose of ECH.EXE with the Microsoft Editor

 Product Version(s): 1.00
 Operating System:   OS/2
 Flags: ENDUSER |
 Last Modified:  8-JUN-1988    ArticleIdent: Q31280

    ECH.EXE is used by the editor to generate the list of files you
 receive when you do <arg> "*.C" <setfile>.



 30. NOSOFTCR Parameter in TOOLS.INI Disables Auto Indentation

 Product Version(s): 1.00
 Operating System:   OS/2
 Flags: ENDUSER | tar69375
 Last Modified: 14-JUN-1988    ArticleIdent: Q31486

    The automatic indentation at the beginning of lines can be
 disabled.
    The NOSOFTCR parameter prohibits the Microsoft Editor from making
 indentation "guesses." NOSOFTCR is specified in the TOOLS.INI file, as
 follows:

    nosoftcr:



 31. Features Supported when Editing TextArgs in Microsoft Editor

 Product Version(s): 1.00
 Operating System:   OS/2
 Flags: ENDUSER | tar69726
 Last Modified:  6-JAN-1989    ArticleIdent: Q31487

 When editing TextArgs, not all editing features are supported. The
 following features are supported:

 QUOTE, INSERT, SDELETE, RIGHT, LEFT, UP, DOWN, HOME, and END

 When an unsupported feature is entered, the editor will beep. Macros
 may be used, but they can contain only supported features.

 The END key allows you to find the length of the search/replace
 string; pressing ARG clears the entire string.


 32. UTILITY.DOC: Filetab Switch Expands Tabs

 Product Version(s): 1.00 | 1.00
 Operating System:   OS/2 | MS-DOS
 Flags: ENDUSER | tar71845
 Last Modified: 16-JUN-1988    ArticleIdent: Q31488

    Information about the filetab switch can be found in the
 UTILITY.DOC file that comes with the Microsoft BASIC Compiler Version
 6.00, the Microsoft C Compiler Version 5.10, the Microsoft FORTRAN
 Compiler Version 4.10 and the README.DOC for Microsoft MASM Version
 5.10.
    The filetab switch is a numeric switch that determines how the
 editor translates tabs when loading a file into memory. The value of
 the switch gives the number of spaces associated with each tab column.
    For example, the setting "filetab:4" assumes a tab column every four
 positions on each line of a file.
    Every time the editor finds a tab character in a file, it loads the
 buffer with the number of spaces necessary to get to the next tab
 column. Depending on the value of the entab switch, the editor also
 uses the filetab switch to determine how to convert spaces into tabs
 when writing a file.
    The default value of filetab is eight (8).



 33. Tabs Expanded to Eight Spaces; Filetab Switch Changes Spacing

 Product Version(s): 1.00   | 1.00
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER | Tar70793
 Last Modified:  1-SEP-1988    ArticleIdent: Q31489

 Question:

 Why are tabs expanded to eight spaces even though I set the tabstop
 variable and the entab switch?

 Response:

 Neither the tabstops or the entab switch affect how tabs are expanded
 when the file is read. The filetab switch is used to determine how
 many spaces to expand each tab. For example, "filetab:4" will expand
 each tab in the file to four spaces.

 The entab switch controls how the editor converts multiple spaces
 into tabs when a line is changed or a file is saved. The default is
 one (1). The following chart shows different values and their
 meanings:

 Value   Meaning

 0       Tabs are not used to represent white space.
 1       All multiple spaces outside of quoted strings
         are converted to tabs (default).
 2       All multiple spaces are converted to tabs.

 Tabstops control the number of spaces between each logical tabstop
 for the editor. The default is four (4).


 34. Resizing Windows

 Product Version(s): 1.00   | 1.00
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER | tar63957
 Last Modified:  1-SEP-1988    ArticleIdent: Q31490

 It is not possible to directly resize windows in the Microsoft Editor.
 A window can only be opened or closed. To resize a window, it must be
 closed and then reopened. Direct resizing of windows is not currently
 possible.

 This feature is under review and will be considered for inclusion in a
 future release.


 35. Parentheses Matching in Microsoft Editor; Arg Meta PBal

 Product Version(s): 1.00
 Operating System:   OS/2
 Flags: ENDUSER | tar63957
 Last Modified: 31-OCT-1988    ArticleIdent: Q31491

 The Microsoft Editor has the capability of matching parentheses
 without altering the current file. Meta PBal prevents the file from
 being edited while balancing parentheses and brackets.

 The following are various other options for Pbal:

 1. Pbal: Scan backwards through the file, balancing parentheses and
    brackets. The first unbalanced one is highlighted when found. If it
    is found and is not visible, the editor displays the matching line,
    with the highlighted matching character. Note that the search does
    not include the current cursor position, and that the scan only
    looks for more left brackets or parentheses than right, not just an
    unequal amount.

 2. Arg Pbal: Performs similarly to Pbal, except that it scans
    forward in the file and looks for more right brackets or parentheses
    than left.

 3. Arg Meta Pbal: Performs similarly to Arg Pbal except that the
    file is not updated.


 36. Editing Nonexisting Files with the Microsoft Editor

 Product Version(s): 1.00
 Operating System:   OS/2
 Flags: ENDUSER | tar62913
 Last Modified: 16-JUN-1988    ArticleIdent: Q31492

    If the Microsoft Editor is invoked to edit a nonexisting file, it
 creates a file with a length of zero in the DELETED directory in
 addition to creating a new file. This occurs with the backup switch
 set to "undel" (the default) in the TOOLS.INI file.
    This behavior is expected and is program design for the product.
 When the Microsoft Editor is invoked to edit an existing file, the
 previous version is moved to the DELETED directory.
    The EXP command allows you to remove this file, and all other files
 from the DELETED directory.



 37. Macro to Toggle HOME Key

 Product Version(s): 1.00
 Operating System:   OS/2
 Flags: ENDUSER | tar66615
 Last Modified: 12-JAN-1989    ArticleIdent: Q31493

 You can create a macro to do the following:

 1. Press HOME key (cursor goes to beginning of line).

 2. Press HOME key again (cursor goes to top of window).

 3. Press HOME key again (cursor goes to top of buffer).

 This technique usually is used to create a toggle key, but it is
 equally applicable to the desired three-step toggle. The technique is
 as follows:

 home1:= begline arg "home2:f10" assign
 home2:= home arg "home3:f10" assign
 home3:= mark arg "home1:f10" assign
 home1:f10

 After following this procedure, the F10 key will toggle among begline,
 home, and mark.


 38. Inserting Time and Date into Files

 Product Version(s): 1.00   | 1.00
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified:  1-MAY-1989    ArticleIdent: Q40176

 To write a macro to insert the time and date into your file, use the
 following insert commands:

    Command     Action

    Curdate     Inserts current date
    Curday      Inserts current day of the week
    Curfile     Inserts current filename
    Curfileext  Inserts current file extension
    Curfilenam  Inserts base name of current file
    Curtime     Inserts current time
    Curuser     Inserts name specified in USER environment variable

 The following macro can be inserted into your TOOLS.INI to insert the
 filename, time, and date:

 ;Macro for time and date.
     Header:= Curfilenam tab Curtime tab Curdate
     Header:Alt+H


 39. Macro to Enter Form Feed or Control Characters in Editor

 Product Version(s): 1.00 | 1.00
 Operating System:   DOS  | OS/2
 Flags: ENDUSER | tar62237
 Last Modified:  1-NOV-1988    ArticleIdent: Q31495

 The form-feed characters and control characters below can be entered
 in a file being edited by the Microsoft Editor.

 The following macro inserts a linefeed, (CTRL+L), and a newline, and
 binds it to the F6 key. To enter a CTRL+L, use the Graphic assignment
 on Page 48 of the "Microsoft Editor User's Guide" when editing your
 TOOLS.INI file:

 graphic:ctrl+l

 FFM:="L" newline   ; Instead of the L shown here, insert a CTRL+L
 FFM:F6             ; with the quote function "CTRL+P CTRL+L"

 The macro below allows you to enter control key values. The
 following line binds "quote" to F5. Quote allows you to enter any key
 as input (i.e., control key values, etc). This means if you type "F5"
 followed by a "CTRL+X", you will see a "\030" instead of "arg":

 quote:F5.


 40. "Unsupported Video Mode" When Loading Microsoft Editor

 Product Version(s): 1.00 1.02 | 1.00 1.02
 Operating System:   MS-DOS    | OS/2
 Flags: ENDUSER |
 Last Modified: 28-JUL-1989    ArticleIdent: Q31498

 It is possible when loading M.EXE or MEP.EXE to receive an
 "Unsupported video mode, please change modes and restart" error
 message. This message may mean that the hardware is not supported.

 Graphics cards supported in this situation include IBM's CGA, EGA,
 MCGA, MDPA, and VGA and the Hercules card. An example of an
 unsupported system is the 8514 video adapter.

 In MS-DOS (or OS/2 real mode), the Microsoft Editor (M) supports the
 8514/A graphics card, but in OS/2 protected mode, MEP Version 1.00
 does not support this graphics card. A "video mode not supported"
 error message occurs in protected mode.

 The Microsoft Editor Version 1.02 supports the 8514/A graphics card in
 both real and protected mode. This version is currently available with
 FORTRAN 5.00.


 41. Environment Variables Used by the Microsoft Editor

 Product Version(s): 1.00
 Operating System:   OS/2
 Flags: ENDUSER |
 Last Modified: 16-JUN-1988    ArticleIdent: Q31547

    The Microsoft Editor uses the following environment variables:

    1. TMP: This directory stores all temporary files.
    2. INIT: This directory stores the TOOLS.INI, M.TMP, and temporary
 files if TMP is not set.

    Please note, if neither environment variable is set, all temporary
 files except M.TMP are written to the root directory of the disk being
 used. M.TMP is written to the current directory.
    The environment variables usually are set in the AUTOEXEC.BAT file.
 For example the following lines can be placed in the AUTOEXEC.BAT
 file:

     SET INIT=c:\init
     SET TMP=c:\temp

    Also, if the TMP environment variable ends with a semicolon, the
 temporary files (i.e., swapping files) will not be created. The editor
 will try to use the semicolon in the name of the file that is created.


 42. Editor Utilities DOS Version 2.x and 8086/8 Corrections

 Product Version(s): 1.00
 Operating System:   OS/2
 Flags: ENDUSER | appnote
 Last Modified:  6-JAN-1989    ArticleIdent: Q31801

 The following files are included in this application note:

    MEGREP.EXE, RM.EXE, UNDEL.EXE, ECH.EXE and EXP.EXE.

 These files are replacements for the original utilities that were
 shipped with the Microsoft Editor Version 1.00. They have been updated
 to correct two specific problems only; they do not include any additional
 functionality over the originals.

 These files correct the problem of embedded 286 instructions that
 prevented the programs from correctly running on 8086 and 8088
 machines (the machines would hang). The files also have been updated
 to correct problems when used with DOS Version 2.x.

 To install the files, copy the files from the appnote disk over the
 files (of the same names) that are installed on the machine.

 This application note can be obtained by calling Microsoft Product
 Support Services at [phone].


 43. Preventing Generation of Tabs in the Edited Disk Files

 Product Version(s): 1.00   | 1.00
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified: 25-JUL-1988    ArticleIdent: Q32033

    It is impossible to search for a tab or replace a string with a tab
 in the M editor.
    When a file is being edited, there are no tab characters in the
 file. When the M editor reads from disk to memory, it converts tabs to
 spaces. When it writes from memory to disk, it converts spaces to tabs
 (unless you set the ENTAB switch to 0).
    This may create problems when devices other than your machine
 access the file. For example, if you edit a source file on your IBM PC
 with the M editor, then try to compile the source file on a mainframe,
 the source file may not compile because of the tabs in the disk file
 created by the M editor.
    The solution is to set ENTAB to 0 in the TOOLS.INI file; this value
 will prevent tabs from being used to represent white space when
 writing from memory to disk.
    For more information on the ENTAB switch, please refer to Table 7.2
 on Page 59 of the "Microsoft Editor User's Guide."


 44. M Hangs on Tandy 2000 with MS-DOS Version 2.11

 Product Version(s): 1.00
 Operating System:   MS-DOS
 Flags: ENDUSER |
 Last Modified:  1-SEP-1988    ArticleIdent: Q32052

 M, the Microsoft Editor for MS-DOS, hangs when run on a Tandy 2000
 computer running MS-DOS Version 2.11.

 M does not support the Tandy 2000. There is no workaround to this
 incompatibility.


 45. Scrolling One Line at a Time

 Product Version(s): 1.00   | 1.00
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |  buglist1.00
 Last Modified: 20-OCT-1988    ArticleIdent: Q32053

 Problem:

 The editor jumps seven lines at a time when I Scroll off the top or
 bottom of the screen. I want it to Scroll one line at a time, but it
 Scrolls four lines at a time when I set VSCROLL to 1.

 Response:

 Hike and Scroll are designed to be independent functions; however,
 they are incorrectly tied together.

 Microsoft has confirmed this to be a problem in Version 1.00 of the
 editor. We are researching this problem and will post new information
 as it becomes available.

 A workaround to this problem is to set both VSCROLL and HIKE to 1 in
 your TOOLS.INI file in the [M] section, as in the following example:

 [M]
     hike:1
     vscroll:1


 46. Installing M with Msetup

 Product Version(s): 1.00    | 1.00
 Operating System:   MS-DOS  | OS/2
 Flags: ENDUSER | h_fortran
 Last Modified: 19-JUL-1988    ArticleIdent: Q32094

 Question:
    The FORTRAN Version 4.10 setup program did not install the
 Microsoft Editor. I could not find any documentation on how to use
 msetup in the UTILITIES.DOC. How do I set up the Editor?

 Response:
    To run the msetup program, place the "Microsoft Editor" disk in
 Drive A and type "msetup". A help screen will be displayed showing
 the syntax for using msetup. An example of running msetup is as
 follows:

    A:>msetup c: \m \init \binp

    This procedure will install the M Editor and M tools (MEGREP, ECH,
 UNDEL, etc.) in the M directory, TOOLS.INI in the INIT directory, and
 MEP in a BINP directory. If you do not specify any directories, the
 program will use default directories. It will show these default
 directories on the screen and prompt you for any changes. These
 directories must be created before running msetup; otherwise, it will
 not be installed correctly.
    Please note that when the msetup prompts you for the type of
 emulation to use for the TOOLS.INI file, a TOOLS.INI file will not be
 created if you type a "0" for the default tools (the defaults are
 already built into Editor). If any of the other emulations are used,
 msetup will rename the appropriate file to TOOLS.INI and install it.


 47. Exit Does Not Save Files when NoAutosave Is Set

 Product Version(s): 1.00   | 1.00
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified: 31-OCT-1988    ArticleIdent: Q32095

 When the boolean switch Autosave is disabled (by setting it to
 NoAutosave), a file will not be saved when exiting the editor.

 As documented on Page 61 of the "Microsoft Editor User's Guide," when
 the Autosave switch is turned on, the current file is saved when the
 user switches away from it. When Autosave is off (NoAutosave), the
 file must be explicitly saved when desired; this can be done by
 entering Arg Arg Setfile (ALT+A ALT+A F2 in the default keyboard
 setup).


 48. Arg *.* Setfile: "Bad Command or Filename" Error

 Product Version(s): 1.00   | 1.00
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER | tar78150
 Last Modified: 29-AUG-1988    ArticleIdent: Q32224

    Entering the command Arg *.* Setfile causes M to display a list of
 all files in the current directory.
    ECH.EXE is a utility used to generate the list of files for ARG
 textarg SETFILE. If this utility cannot be found, you will receive a
 message saying "Bad command or filename." ECH.EXE must be located in a
 directory on the path.


 49. Using the SHORTNAMES Switch

 Product Version(s): 1.00   | 1.00
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER | tar78150
 Last Modified: 31-MAR-1989    ArticleIdent: Q32225

 SHORTNAMES is a boolean switch. When it is set (the default), if you
 type <arg> "foo" <setfile>, you will be sent to the first file in your
 history list with the base name "foo". You do not have to specify the
 full pathname for a file in another directory. If there is no
 d:\path\foo.xxx anywhere in your file history, you only get foo.

 If you have a file "foo" in your current directory, SHORTNAMES still
 tries to find a file in your history list first. The history of files
 is stored in M.TMP. The number of files saved is determined by the
 TMPSAV switch.

 To disable this feature, set noshortnames: in your TOOLS.INI file.

 To avoid this behavior without changing the switch value, include a
 period in the path specification. For example, enter <arg> "foo."
 <setfile>, which will look only in the current directory. The presence
 of any path character (".", etc.) disables the SHORTNAMES feature for
 the file being referenced.


 50. Cancel Clears the Type-Ahead Buffer

 Product Version(s): 1.00   | 1.00
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER | tar75933
 Last Modified: 19-JUL-1988    ArticleIdent: Q32226

    The Cancel command clears the type-ahead buffer. This is a feature
 of the editor and is not considered a problem.
    Cancel is mapped to the ESC key in the default keyboard setup.


 51. Loading a TAGGED Section Reinitializes the Editor

 Product Version(s): 1.00   | 1.00
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER | buglist1.00 tar76973
 Last Modified: 29-AUG-1988    ArticleIdent: Q32228

 When a TAGGED section is initialized (<arg> "section name"
 <initialize>), all current macros are destroyed before
 reinitialization.

 The curdate, curtime, etc., macros are reset, your extmake: settings
 are set to the default, and the OS-dependent and video-dependent
 sections of TOOLS.INI are read in. If you type <initialize>, the main
 section is read in place of the TAGGED section.

 Microsoft has confirmed this to be a problem in Version 1.00. We
 are researching this problem and will post new information as it
 becomes available.



 52. The extmake Compile Switch Is Case Sensitive

 Product Version(s): 1.00   | 1.00
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER | buglist1.00
 Last Modified:  1-MAY-1989    ArticleIdent: Q32242

 The following extmake entry will be ignored, causing the default
 command line to be used:

 extmake:C cl /c /Zi /Od %s

 Microsoft has confirmed this to be a problem in Version 1.00. We
 are researching this problem and will post new information as it
 becomes available.

 Although there is no case sensitivity for the extmake switch name, the
 extension specified ("C" in this example) must be in lowercase. If the
 extension is not in lowercase, the help screen will show a separate
 entry for that extension, as follows:

    C   cl /c /Zi /Od %s
    c   cl /c /Zep /D LINT_ARGS %s

 The second command line will be used when compiling a C program.


 53. Loading Tagged Sections in OS/2 Version 1.10

 Product Version(s): 1.00
 Operating System:   OS/2
 Flags: ENDUSER | docerr
 Last Modified: 29-AUG-1988    ArticleIdent: Q33348

 Problem:

 I have followed the instructions on Page 64 of the "Microsoft Editor
 User's Guide" for loading tagged sections in OS/2, but the editor
 never loads this section. My TOOLS.INI file has a tag titled [M MEP]
 containing assignments for both protected and real modes and a tag
 titled [M-10.0] for OS/2 protected-mode assignments. I am running
 Microsoft OS/2 Version 1.10.

 Response:

 Your [M-10.0] tag is not loaded in OS/2 Version 1.10 because [M-10.0]
 means OS/2 Version 1.00. The version number should be changed from
 10.0 to 10.10; your tag should be [M-10.10]. If you want the tag to
 work correctly for both OS/2 Versions 1.00 and 1.10, create a tag
 titled [M-10.0 M-10.10].

 This information is not contained in the "Microsoft Editor User's
 Guide."


 54. C.TMP Files in Current Directory

 Product Version(s): 1.00
 Operating System:   MS-DOS
 Flags: ENDUSER |
 Last Modified:  2-SEP-1988    ArticleIdent: Q34251

 Question:

 Every time I edit a file with the Microsoft Editor, I receive a C.TMP
 file in that directory. I am using DOS Version 2.10. Why is it
 creating this file?

 Response:

 The C.TMP file is where the editor keeps its information about
 previous files that have been edited. This file normally is called
 M.TMP; however, due to a limitation of DOS Versions 2.x, the editor
 believes its name is C rather than M.

 The files are placed in the directory where the file was edited
 because unless the INIT environment variable is set, the .TMP file is
 written to the current directory.

 When using M on DOS Versions 2.x, change the tag field of the TOOLS.INI
 from [M] to [C] and set the INIT environment variable to the directory
 that contains TOOLS.INI.



 55. How to Perform Spell Checking in M

 Product Version(s): 1.00   | 1.00
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified: 29-AUG-1988    ArticleIdent: Q34274

 Question:
    Does the Microsoft Editor have any spell checking capabilities?

 Response:
    The M editor does not have built-in spell checking. If you have a
 separate spell-check program you can write a macro to invoke it on
 your current file.
    For example, you could use the spell checker that comes with
 Microsoft Word Version 4.00 by doing the following:

     [M]
         ...
         Spell:=Arg "spell-am " Curfile Shell
         Spell:ALT+S

    The macro works as follows:

    1. Arg introduces an argument to the shell command.
    2. "spell-am" is the name of the spell-check utility
       included in Word Version 4.00.
    3. Curfile is the name of the current file you are editing. Note
       the space at the end of "spell-am "; this space is needed so the
       argument you pass to Shell is "spell-am YourCurrentFile" instead
       of "spell-amYourCurrentFile".
    4. The Shell command invokes COMMAND.COM and passes it the
       spell-am command. When spell-am completes its spell-check,
       it will return to the editor.


 56. Changing Height Switch Not Sufficient to Change Video Modes

 Product Version(s): 1.00   | 1.00
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified:  1-SEP-1988    ArticleIdent: Q34411

 Microsoft Editor does not immediately change video modes (CGA/EGA/VGA)
 when changing the numeric switch HEIGHT: to either 23, 41, or 48 in the
 TOOLS.INI file.

 For the new height setting to take effect, one of the following must
 be done:

 1. The INITIALIZE function can be invoked to force the editor to
    update its settings based on the switch values in TOOLS.INI. This
    will reset the video-display configuration. (INITIALIZE is ALT+F10
    for Quick and EPSILON emulation, SHIFT+F10 for BRIEF emulation, or
    SHIFT+F8 for the default emulation).

 2. The assignment can be made directly to the editor by invoking
    <arg> height:41 <assign>. In the default keyboard configuration,
    this would be ALT+A "height:41" ALT+=.

 3. While editing the "height:41" line in TOOLS.INI, move to the
    beginning of the line and enter <arg> <assign>, which is ALT+A
    ALT+= in the default keyboard assignments.

 The video mode is stored in the M.TMP file in the directory pointed to
 by the TMP environment variable; if TMP is not set, M.TMP is placed in
 the current default directory. Invoking the INITIALIZE function causes
 M to reset the settings in M.TMP based on the settings in TOOLS.INI.


 57. Accessing Switch Values in C Extensions

 Product Version(s): 1.00   | 1.00
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified:  2-SEP-1988    ArticleIdent: Q35025

 There is no direct function call to access switch values defined in
 the editor, such as rmargin or vscroll or hike, in your C Extension.
 However, you can find the value by using fExecute() to switch to the
 help file, then use the psearch or msearch functions to locate
 rmargin. At the end of that line you will find the value associated
 with rmargin.

 The following is an example:

 fExecute("Arg \"<assign>\" Setfile");  /* switch to "<assign>" file   */
 fExecute("Mark");                      /* go to beginning of it       */
 fExecute("Arg \"rmargin\" Psearch");   /* search for "rmargin"        */
 fExecute("Pword");                     /* get the number after it     */

 You also can use the GetLine() function to read through the <assign>
 file; this method involves more coding, but it will run faster than
 using fExecute() to execute macros.


 58. Passing Textargs to M with the /E Switch

 Product Version(s): 1.00   | 1.00
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified:  1-SEP-1988    ArticleIdent: Q35028

 Question:

 How can I pass textargs to the editor using the /e command-line
 switch?

 Response:

 Type in the name of the function you want the editor to execute. If
 you want to use more than one function, enclose the functions in
 double-quotation marks. If your functions require arguments, use the C
 syntax for specifying quotation marks within strings, i.e., the
 backslash escape character (\). Thus, a double-quotation mark within
 a string is specified with \".

 The following examples demonstrate various methods of passing
 command-line arguments to M:

 m /e psearch myfile

 This example invokes the Microsoft Editor on the file "myfile",
 passing it the command "psearch" to be executed immediately. The
 psearch will search for whatever string was last specified (in the
 search buffer).

 m /e "mark psearch" myfile

 This example again edits "myfile", but this time it passes two
 commands to M: "mark" and "psearch". The Mark command goes to the
 beginning of the file, and psearch searches forward for an occurrence
 of the search-string (which must have been specified in a previous
 search).

 m /e "arg \"search string\" psearch" myfile

 This example passes the editor the following string:

 "arg "search string" psearch"

 The \" characters are a C escape sequence that evaluates to a
 double-quotation mark ("); as a result, the entire string has a string
 embedded in it. The effect of this command is to tell the editor to
 search for the literal text "search string".

 m /e "arg \"\\\"a quoted search string\\\"\" psearch" myfile

 This is the most complicated case of argument passing. It
 passes the following string to the editor:

 "arg "\"a quoted search string\"" psearch"

 This command searches for the QUOTED literal text ""a quoted search
 string"".  The "\" and \"" are necessary to cause M itself to postpone
 evaluation of the double-quotation marks until actual search time.


 59. A Workaround for the MGREP Problem in M/MEP Version 1.02

 Product Version(s): 1.02   | 1.02
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified: 29-JAN-1991    ArticleIdent: Q68386

 In the M/MEP Editor version 1.02, there is a problem in the MGREP
 function; it will fail to find some matches to the query in the file.
 (This is due to certain regular-expression matches failing when they
 shouldn't.) Below is a macro that will use the MEGREP.EXE utility to
 search for a string, and return the results in the compile window. The
 benefits are:

 1. It should be faster, especially under OS/2.

 2. If run under OS/2, it will be a background process enabling you
    to continue working.

 Macro Code
 ----------

 Add the following to your TOOLS.INI file. You can then assign it to a
 keystroke, if desired:

 megreplist:="*.c *.h"
 mg1:=copy arg "<megrep>" setfile mark emacsnewl mark paste begline
 mg2:="arg arg \"megrep \\\"" endline "\\\" " megreplist
 mg3:=" \" compile" begline arg endline execute setfile
 megrep:= mg1 mg2 mg3

 The following is another option, which avoids using an extra
 pseudo-file:

 megreplist:="*.c *.h"
 mg:= copy arg "<clipboard>" setfile            \
      begfile "megrep \"" endline "\" " megreplist  \
      begline arg arg endline compile setfile

 Notes
 -----

 1. The first macro is in three parts due to line-length limits of the
    knowledge base; the macro could be just one line. The second macro
    uses line continuation characters to achieve the same result as
    breaking up the first macro.

 2. The macro assumes that all files on disk are up to date.


 60. MHELP Driver Not Completely Compatible with QuickC Help Files

 Product Version(s): 1.02   | 1.02
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER | s_quickc buglist1.02
 Last Modified:  5-MAR-1990    ArticleIdent: Q58603

 The MHELP driver cannot process some cross-references inherent to the
 QuickC Versions 2.00 and 2.01 help files. Results range from the MHELP
 message "Cannot Process Cross Reference," to hanging the computer. In
 general, direct reference to a QuickC help file from within the editor
 is fine. However, moving around within the help file system using the
 built-in cross-references produces unpredictable results.

 The MHELP driver seems unable to access unformatted text files such as
 header, source, and DOC files. For example, QuickC allows you to
 access both the README.DOC file and QuickC header files from within
 the help system. Attempting these feats from within M leads to one of
 the following problems:

 1. "Cannot Process Cross Reference," if file not found.

 2. DOS will hang the machine if the file is found.

 3. OS/2 may cause a SYS 1943 protection violation if the file is
    found.

 The M editor also cannot use the <back> menu option to access a
 previously viewed help file. Attempting this yields the message
 "Cannot Process Cross Reference" at the bottom of the screen. The
 syntax of the <back> cross-reference in unencrypted help form is
 help file to access the previous help screen. This undocumented
 feature is not allowed in MHELP.

 Certain series of cross references cause sporadic errors. You should
 be careful to avoid internal cross-referencing within the QC help
 files. The problem can be shown with the following sequence using the
 QuickC and QuickAssembler help files from within the M Editor.

    <arg> seg <F1> <TAB> <RETURN> <TAB> <RETURN> <TAB>

 This example reaches the help-contents window via the "seg" example
 program. Upon reaching this point, it may hang DOS with the run-time
 error R6003 or R6001. OS/2 displays a black box in the upper-right
 corner of the screen and may crash at this point.

 Microsoft has confirmed this to be a problem with the M Editor Version
 1.02. We are researching this problem and will post new information
 here as it becomes available.


 61. Compiling in M Produces No .OBJ File

 Product Version(s): 1.00   | 1.00
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified: 20-OCT-1988    ArticleIdent: Q35233

 If compilation from within the editor gives no .OBJ file when the
 same compilation outside of M succeeds in creating an object module,
 check the CONFIG.SYS files setting.

 In one case, a user had "files=25" while running under DOS Version
 3.20, which doesn't support a file setting greater than 20. If files
 exceed 20, DOS uses its default of eight files. When the user set
 "files=20" an .OBJ was created from a compilation within M.


 62. Creating Windows in M and MEP

 Product Version(s): 1.00   | 1.00
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified:  1-MAY-1989    ArticleIdent: Q35235

 Question:

 How can I create multiple windows and edit multiple files with the
 Microsoft Editor?

 Response:

 Both horizontal and vertical windows can be created. You can have up
 to eight windows on the screen.

 To create a horizontal window, position the cursor on the screen where
 you would like the window break and press ARG WINDOW (ALT+A F6 in the
 default).

 This process creates a new window with a copy of the file you were
 currently editing. You then can load a different file into that window
 (ARG SETFILE ALT+A F2).

 To create a vertical window, position the cursor on the screen where
 you would like the window break and press ARG ARG WINDOW (ALT+A ALT+A
 F6 in the default). You then can load a different file into the
 window.

 Once you have several windows on the screen you can move around from
 window to window using the WINDOW command (F6 in the default setup).

 See also section 4.6 of the "Microsoft Editor User's Guide."

 Note: Each window must have a minimum of five lines and 10 columns to be
 created.


 63. M Does Not Respond to Changes in the Height Switch

 Product Version(s): 1.00   | 1.00
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified: 31-MAR-1989    ArticleIdent: Q35252

 The Microsoft Editor does not change video modes (EGA/VGA) when
 changing the numeric switch height to either 23, 41, or 48 in the
 TOOLS.INI file.

 The INITIALIZE function must be invoked to reset the video display
 configuration. (INITIALIZE = ALT+F10 for Quick and EPSILON emulation,
 SHIFT+F10 for BRIEF emulation, or SHIFT+F8 for the default emulation).

 The video mode also is stored in the M.TMP file in the directory
 pointed to by the INIT environmental variable or the current default
 directory.


 64. Toggling Display Modes: 25-, 43-, and 50-Row Modes

 Product Version(s): 1.00   | 1.00
 Operating System:   MS-DOS | MS-DOS
 Flags: ENDUSER |
 Last Modified: 14-NOV-1988    ArticleIdent: Q37628

 The following Microsoft Editor macro allows you to toggle the EGA
 display between 25-row mode and 43-row mode by pressing ALT+E:

 ;Macro to toggle 25/43 line EGA modes
     to23:=arg "height:23" assign
     to41:=arg "height:41" assign
     toggle23:=to23 arg "toggle41:alt+e" assign
     toggle41:=to41 arg "toggle23:alt+e" assign
     toggle41:alt+e

 The example below is a variation of the above macro. It allows you to
 toggle the VGA display between 25-row mode, 43-row mode, and 50-row
 mode by pressing ALT+E. Instead of switching back and forth between
 two modes, it cycles through all three.

 The macro is as follows:

 ;Macro to toggle 25/43/50 line VGA modes
     to23:=arg "height:23" assign
     to41:=arg "height:41" assign
     to48:=arg "height:48" assign
     toggle23:=to23 arg "toggle41:alt+e" assign
     toggle41:=to41 arg "toggle48:alt+e" assign
     toggle48:=to48 arg "toggle23:alt+e" assign
     toggle41:alt+e

 These macros should be placed in your TOOLS.INI file as described
 in Chapters 6 and 7 of the "Microsoft Editor User's Guide."

 Note: the "toggle" functions in these macros not only set the video
 mode, they also change the assignment of function ALT+E. This makes
 these macros similar to self-modifying code. For example, "toggle23"
 not only sets the video mode to 23-rows (with a call to "to23"), it
 also assigns ALT+E to "toggle41" by using the following sequence:

    arg "toggle41:alt+e" assign

 This technique is very useful in learning to write macros.


 65. "Softer" Should Be "Softcr" in M 1.0 User's Guide

 Product Version(s):
 Operating System:   1.00   | 1.00
 Flags: MS-DOS | OS/2
 Last Modified: 18-DEC-1989    ArticleIdent: Q35256
 ENDUSER | docerr

 On Page 61 of the "Microsoft Editor User's Guide," there is a
 documentation error. Softcr is listed as Softer; the correct listing
 is Softcr.


 66. Why Compiling after Editing in M Shows Old Errors

 Product Version(s): 1.00   | 1.00
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified: 20-OCT-1988    ArticleIdent: Q35258

 When using the M editor (either M.EXE or MEP.EXE) to correct compiler
 or assembler errors, and then compiling/assembling from within M using
 the COMPILE function, it is possible to get the old set of errors
 returned. If the errors occur, check that the autosave switch is set
 correctly. If autosave is off, the corrections are not saved before
 compilation.

 When turned on, the autosave boolean initialization switch causes the
 current file to be saved whenever it is switched away from. The
 default value is on, i.e., the files are automatically saved. The
 setting can be changed from within the editor using Arg textarg Assign
 or else in TOOLS.INI.

 In either case, specify noautosave: to prevent automatic saving of
 files, or autosave: to restore automatic file saving.


 67. How to Read the Contents of the M Editor Clipboard

 Product Version(s): 1.00   | 1.00
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified: 31-MAR-1989    ArticleIdent: Q35259

 The Clipboard is contained in a pseudofile named <clipboard>. It can
 be loaded the same way any other file is loaded. The contents of the
 Clipboard pseudofile can be examined in several ways.

 The pseudofile <clipboard> can be loaded with the command sequence Arg
 textarg Setfile, which is ALT-A <clipboard> F2 in default keystrokes.
 This process loads the named file. The contents of the clipboard then
 can be seen on the screen, and even can be edited and saved as a
 separate file.

 The file also can be loaded by bringing up the information file with
 the INFORMATION function (SHIFT-F1).

 Finally, if the clipboard is the file most recently switched from, the
 SETFILE function (F2) alone will call it up.

 The information file describes the nature of the Clipboard contents in
 two ways. The Clipboard line appears in the form in the list of
 files, as follows:

 <clipboard>                    *n lines

 Additionally, at the bottom of the information file is a line that
 gives information in one of two ways, as follows:

 n lines in line clipboard

 n lines in box clipboard

 This information indicates whether the Clipboard holds a block of text
 or a stream of text.


 68. How to Write Selected Text to a File in M Editor

 Product Version(s): 1.00   | 1.00
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified:  1-NOV-1988    ArticleIdent: Q35260

 To write a block or stream of text from a file currently being edited
 to another file (either new or currently existing), do the following:

 1. Select text by using Arg (ALT+A) and the cursor movement keys.

 2. Put the text block or stream into the Clipboard by using the
    functions Copy (CTRL+INSERT, or + on the keypad) or Ldelete
    (CTRL+Y) or Sdelete (DELETE).

 3. Load the desired new file (see the "Working with Multiple Files"
    section of the "Microsoft Editor" manual).

 4. Paste (SHIFT+INSERT) the contents of the Clipboard into the new
    file.

 When writing to a file that does not yet exist, another procedure can
 be used, as follows:

 1. Write the selected text to the Clipboard as described above.

 2. Use Setfile to load the <clipboard> pseudofile the same way that
    other files are loaded.

 3. When the Clipboard contents appear on the screen, save the file to
    the desired new filename with Arg Arg textarg Setfile (ALT+A ALT+A
    filename F2). If a file by that name already exists, it will be
    overwritten.

 4. Return to the originally edited file with Setfile (F2).

 The second method can be put into a macro in one of the following two
 ways:

 1. Create a macro definition for copying to a file of prespecified name
    by using, for example, the following:

 sendtofil:=copy arg "<clipboard>" setfile arg arg "foo.txt" setfile
 setfile

 Assign the macro to a keystroke with an argument of the following
 form, for example:

 sendtofil:alt+s.

 This macro can be placed in TOOLS.INI, or can be the textarg in the
 command to enter a macro, as follows:

 Arg textarg Assign (ALT+A textarg ALT+=).

 2. Create a macro definition for copying to a file of any name by
    using two macros in sequence, for example, as follows:

 send1:=copy arg "<clipboard>" setfile arg arg
 send2:=setfile setfile

 Enter and assign them as described above. To execute this set of
 macros, select the text block or stream, execute the first macro, type
 the desired filename, then execute the second macro.


 69. Macro to Print Part or All of a File from within M

 Product Version(s): 1.00  1.02 | 1.00 1.02
 Operating System:   MS-DOS     | OS/2
 Flags: ENDUSER |
 Last Modified: 21-AUG-1989    ArticleIdent: Q35261

 Microsoft Editor Version 1.00 contains no built-in primitives for
 printing; there is no actual "print" command. However, a set of steps
 can be performed involving the shell function, and a macro can be
 written to execute the steps conveniently. The 1.02 version of the
 Microsoft Editor does contain a print function. For more information
 on Version 1.02's print function, please see Section 4.9, "Printing a
 File," in the "Microsoft Editor User's Guide for MS OS/2 and MS-DOS
 Operating Systems."

 The following is a sample macro for the 1.00 Editor:

    print1:=copy arg "<clipboard>" setfile
    print2:=arg arg "PRINT.TMP" setfile
    print3:=arg "print PRINT.TMP" shell
    print4:=arg "del PRINT.TMP" shell setfile
    print:=print1 print2 print3 print4

 Note: The DOS PRINT command is a resident program. If you shell out of
 M and invoke the PRINT command for the first time, PRINT will be
 loaded above M and you will fragment memory. To prevent this, invoke
 the PRINT command before entering M, so that it will be loaded into
 low memory.

 The following explains the above example:

 1. copy: This copies the currently selected region into the
    clipboard. This way, you can select a region, using a boxarg or
    linearg, and then execute this macro to print it. Because the
    selected region defines what is to be printed, it can be modified
    to suit your needs.

 2. arg "<clipboard>" setfile: This loads the <clipboard> pseudo file
    as the current file.

 3. arg arg "PRINT.TMP" setfile: This saves the contents of the current
    file (which is now <clipboard>) to the file PRINT.TMP.

 4. arg "print PRINT.TMP" shell: This executes a DOS shell that prints
    PRINT.TMP.

 5. arg "del PRINT.TMP" shell setfile: This executes a DOS shell that
    deletes PRINT.TMP, then uses Setfile to return to the original file.


 70. The Difference between M and MEP

 Product Version(s): 1.00   | 1.00
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER | appnote
 Last Modified:  6-JAN-1989    ArticleIdent: Q35522

 The following information is taken from an application note called
 "Microsoft Editor Questions and Answers." The application note also is
 available from Microsoft Product Support Services by calling (206)
 454-2030.

 The Difference between M and MEP?

 M.EXE is the Microsoft Editor that runs under DOS or MS OS/2 real
 mode. MEP.EXE runs under MS OS/2 protected mode only. You may want to
 rename MEP.EXE to M.EXE. Functionally, the two editors are the same,
 except for slight differences in background compilation.


 71. Reassigning Default Keystrokes for Editor Functions

 Product Version(s): 1.00   | 1.00
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER | appnote
 Last Modified:  6-JAN-1989    ArticleIdent: Q35523

 The following information is taken from an application note called
 "Microsoft Editor Questions and Answers." The application note also is
 available from Microsoft Product Support Services by calling (206)
 454-2030.

 Reassigning the Default Keystrokes for Editor Functions

 The function can simply be assigned to an unused keystroke, as
 follows:

 Home:Ctrl+H

 Consult your "Microsoft Editor User's Guide" for valid keystroke
 combinations. If necessary, you can unassign a keystroke by assigning
 it to the function Unassigned, as follows:

 Unassigned:Ctrl+Home


 72. Separating TOOLS.INI Entries for M

 Product Version(s): 1.00   | 1.00
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER | appnote
 Last Modified:  6-JAN-1989    ArticleIdent: Q35524

 The following information is taken from an application note called
 "Microsoft Editor Questions and Answers." The application note also is
 available from Microsoft Product Support Services by calling (206)
 454-2030.

 Making Separate TOOLS.INI Entries for M if You Want to Have Different
 Configurations for M Running Under DOS, OS/2 Real Mode, or OS/2
 Protected Mode, or a Combination of the Three

 Various combinations of tags can be used in TOOLS.INI to set up
 different configurations for different environments. Each environment
 has its own recognized tag. The following is an example:

 Environment:                  Tag:

 MS-DOS                        [M-3.30] (your particular
                                        DOS version)
 OS/2 real mode                [M-10.0R]
 OS/2 protected mode           [M-10.0]

 The following is an examples of combinations:

 MS-DOS and OS/2 real mode     [M-3.30 M-10.0R]
 OS/2 real and protected mode  [M-10.0R M-10.0]

 If you have renamed M.EXE, the "M" used in the tag must be replaced
 with the name you are using for the editor. However, each M-XX.XX
 sub-tag only can appear once in a tag. For example, if you used the
 double tags above, and you were running M in OS/2 real mode, only the
 information from first tag would be loaded.

 By using these tags, only certain sections will be loaded from
 TOOLS.INI to initialize the editor, depending on the environment in
 which the editor is running. The statements in the [M] section are
 always loaded.


 73. Loading a New File into the Editor

 Product Version(s): 1.00   | 1.00
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER | appnote
 Last Modified:  6-JAN-1989    ArticleIdent: Q35525

 The following information is taken from an application note called
 "Microsoft Editor Questions and Answers." The application note is
 available from Microsoft Product Support Services by calling (206)
 454-2030

 Loading a New File into the Editor

 Loading a new file into the editor can be done by using the keystrokes
 corresponding to the following functions:

 Arg textarg Setfile, where textarg is the name of the file you wish to
 load.


 74. Exiting without Saving

 Product Version(s): 1.00   | 1.00
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER | appnote
 Last Modified:  6-JAN-1989    ArticleIdent: Q35526

 The following information is taken from an application note called
 "Microsoft Editor Questions and Answers." The application note is
 available from Microsoft Product Support Services by calling (206)
 454-2030.

 How to Exit without Saving

 Normally, when the keystroke for exit is invoked, the file will be
 saved before exiting. However, typing the keystroke for "Meta" before
 the exit keystroke allows you to exit without saving your file.


 75. Merging Two Files Together

 Product Version(s): 1.00   | 1.00
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER | appnote
 Last Modified:  6-JAN-1989    ArticleIdent: Q35527

 The following information is taken from an application note called
 "Microsoft Editor Questions and Answers." The application note also is
 available from Microsoft Product Support Services by calling (206)
 454-2030.

 How to Merge Two Files Together

 A separate file can be merged into the current file by using the
 keystrokes corresponding to the following functions:

    Arg Arg textarg Paste, where textarg is the name of file to be merged.


 76. Placing Control Characters in Text of File

 Product Version(s): 1.00   | 1.00
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER | appnote
 Last Modified:  6-JAN-1989    ArticleIdent: Q35528

 The following information is taken from an application note called
 "Microsoft Editor Questions and Answers." The application note also is
 available from Microsoft Product Support Services by calling (206)
 454-2030.

 Placing Control Characters in the Text of My File

 The editor function "Quote" can be used to place special characters in
 your text. Use the keystroke assigned to "Quote", then enter the
 combination of keys necessary to produce the character. For example, a
 Form Feed would be a combination of the CTRL key and the L key.


 77. Compiling the Program Currently Loaded in Editor

 Product Version(s): 1.00   | 1.00
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER | appnote
 Last Modified:  6-JAN-1989    ArticleIdent: Q35529

 The following information is taken from an application note called
 "Microsoft Editor Questions and Answers." The application note is
 available from Microsoft Product Support Services by calling (206)
 454-2030.

 How to Compile the Program Currently Loaded in the Editor

 The current file can be compiled by using the keystrokes corresponding
 to the following functions:

    Arg Arg textarg Compile, where textarg is the compiler command
    line typed as you normally would outside of the editor; however,
    the filename does not have to be the current file.

 The text switch "extmake" can be entered in TOOLS.INI to associate a
 frequently used command line with a particular file extension. The
 following is an example:

    extmake:c cl /Zi /Od %s

 The %s will be replaced with the current filename.


 78. Differences between the vscroll and hike Numeric Switches

 Product Version(s): 1.00   | 1.00
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER | appnote
 Last Modified:  6-JAN-1989    ArticleIdent: Q35530

 The following information is taken from an application note called
 "Microsoft Editor Questions and Answers." The application note also is
 available from Microsoft Product Support Services by calling (206)
 454-2030.

 The Differences between the vscroll and hike Numeric Switches

 The vscroll switch determines how many lines are vertically scrolled
 when the cursor is moved to a location not visible in (outside of) the
 current window but within vscroll lines of the edge of the current
 window.

 The hike switch determines the cursor position when an editing
 function moves the cursor more than vscroll lines beyond the edge of
 the current window. In this case, the cursor would appear hike lines
 from the top of the window.

 Note: Currently, these switches are broken. Even when vscroll is
 correctly set to 1, hike will overide it if hike has a greater value
 than vscroll. Until this problem is corrected, both switches must be
 set to 1 to scroll one line at a time.


 79. Making the Editor Default to Insert Mode

 Product Version(s): 1.00   | 1.00
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER | appnote
 Last Modified:  6-JAN-1989    ArticleIdent: Q35531

 The following information is taken from an application note called
 "Microsoft Editor Questions and Answers." The application also is
 available from Microsoft Product Support Services by calling (206)
 454-2030.

 How to Make the Editor Default to Insert Mode

 The boolean switch "Enterinsmode" can be set in the TOOLS.INI file to
 allow the editor to start up in insert mode rather than overtype mode.
 This switch is off by default, but can be set by adding the following
 entry to TOOLS.INI:

    enterinsmode:


 80. Saving Files Under a Different Name

 Product Version(s): 1.00   | 1.00
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER | appnote
 Last Modified:  6-JAN-1989    ArticleIdent: Q35532

 The following information is taken from an application note called
 "Microsoft Editor Questions and Answers." The application note also is
 available from Microsoft Product Support Services by calling (206)
 454-2030.

 How to Save Your File Under a Different Name

 Saving a file under a different name can be done by including a
 textarg when saving a file without exiting, as follows:

    Arg Arg textarg Setfile, where textarg is the filename you wish to
    save the file under.


 81. "Unable to Open Swapping File c:\temp\m-0029.vm"

 Product Version(s): 1.00   | 1.00
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER | appnote
 Last Modified:  6-JAN-1989    ArticleIdent: Q35533

 The following information is taken from an application note called
 "Microsoft Editor Questions and Answers." The application note also is
 available from Microsoft Product Support Services by calling (206)
 454-2030.

 "Unable to Open Swapping File c:\temp\m-0029.vm No Such File or
 Directory" Error

 The editor assumes that environment variables are set so that
 important editor information can be loaded from and saved to your
 disk. The following is an example:

    SET INIT=c:\init
    SET TMP=c:\temp

 In this example, c:\temp would be the directory that would hold
 temporary or swapping files, usually named M-0029.VM. This file is
 used to allow the editor to switch to previous files. C:\INIT would
 hold TOOLS.INI and M.TMP. The swapping file also would be stored here
 if the TMP variable was not set. If neither of these variables is
 set, the swapping file would be stored in the root directory and M.TMP
 would be stored in the current directory.

 However, if the TMP variable is set to a directory that does not
 exist, or if extra characters were included after the "p" in "c:\temp"
 such as a space or a semicolon, the swapping file will not be created
 and the error above will be generated.


 82. Why the Editor Cannot Find or Load TOOLS.INI

 Product Version(s): 1.00   | 1.00
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER | appnote
 Last Modified:  6-JAN-1989    ArticleIdent: Q35534

 The following information is taken from an application note called
 "Microsoft Editor Questions and Answers." The application note also is
 available from Microsoft Product Support Services by calling (206)
 454-2030.

 Why the Editor Can't Find or Load the TOOLS.INI File

 There are several reasons this problem may occur. First of all, you
 may have never created a TOOLS.INI file. If TOOLS.INI is not in the
 working directory, the INIT environment variable must specify the
 directory that contains this file. Within the TOOLS.INI file, there
 must be a tag that has the same name as the editor (M.EXE), as
 follows:

    [m]

 If you have renamed the editor you also must rename the tag. Entries
 concerning the editor then would follow after this tag. Under DOS
 Versions 2.x, the Microsoft Editor looks for a [c] tag rather an [m]
 tag or whatever you have renamed M.EXE to.


 83. Keeping the Editor from Saving Backup Files

 Product Version(s): 1.00   | 1.00
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER | appnote
 Last Modified:  6-JAN-1989    ArticleIdent: Q35535

 The following information is taken from an application note called
 "Microsoft Editor Questions and Answers." The application note also is
 available from Microsoft Product Support Services by calling (206)
 454-2030.

 How to Keep the Editor from Saving Backup Files

 The text switch "Backup" determines what happens to old copies of
 files that are modified. If you do not wish to keep any backup files,
 a value of "none" can be given, as follows:

    Backup:none

 Backup files can be saved in two ways. A value of "bak" will save the
 previous version of the file with a .BAK extension. A value of "undel"
 will save a history of old copies of your file in a hidden directory
 disk space.

 Older copies can be restored by using UNDEL.EXE. Typing "undel" will
 list all the backup copies; "undel <filename>" will either restore the
 file, or if there is more than one backup, it will allow you to choose
 which version you would like to restore. Because these files take up
 actual disk space, they should be periodically removed from the disk
 by using EXP.EXE. Typing "exp" will delete these files permanently.


 84. How to Write and Use C Extensions

 Product Version(s): 1.00   | 1.00
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER | appnote
 Last Modified:  6-JAN-1989    ArticleIdent: Q35536

 The following information is taken from an application note called
 "Microsoft Editor Questions and Answers." The application note also is
 available from Microsoft Product Support Services by calling (206)
 454-2030.

 C Extensions and How to Write and Use Them

 C extensions allow you to further customize the editor by creating new
 editor functions and switches through programs that you write in the C
 programming language. They are much more powerful than macros because
 macros depend on the existence of editor functions.

 C extensions are compiled with a special memory-model that does not
 use a main() function, but rather uses special names and structures
 that the editor alone recognizes. They are linked with an object
 module that makes low-level functions used within the editor itself
 available to be called by your C extension. The file produced from
 linking is separate from the main program but is loaded into memory
 with the editor. The editor then will call your module whenever you
 invoke one of your C extension functions.


 85. Developing Macros

 Product Version(s): 1.00   | 1.00
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER | appnote
 Last Modified:  4-MAY-1989    ArticleIdent: Q35537

 The following information is taken from an application note called
 "Microsoft Editor Questions and Answers." The application note also is
 available from Microsoft Product Support Services by calling (206)
 454-2030.

 Develop my Own Macros

 Developing a macro is similar to programming in a high-level language.
 Each macro represents a command. Instead of a collection of library
 routines, you have a collection of editor functions. You begin with an
 idea of a process that you would like to be performed by simply
 pressing one keystroke.

 Suppose you would like to be able to move the cursor to the lower-left
 corner of the editing window. You know you can do this "manually" with
 the arrow keys that are assigned to the "Left" and "Down" editor
 functions. However, it can be simplified more. "Meta Down" moves the
 cursor to the bottom of the window; "Meta Begline" moves the cursor to
 the first column of the line. Together, these functions will do the
 job.

 This macro must now be given a unique name, for example, "Bottom". The
 TOOLS.INI statement would look as follows:

    Bottom:=Meta Begline Meta Down

 A macro also can be a combination of other macros. The following is an
 example:

    Waydown:=Meta Down
    Wayleft:=Meta Begline
    Bottom:=Waydown Wayleft

 Suppose that the "Meta Begline" command did not exist. You would need
 to find some way to know that the cursor is in the first column.
 Almost all of the editor functions have boolean (TRUE/FALSE) Return
 Values that can be useful in developing macros.

 For the "Bottom" macro, you know that "Begline" will at least move the
 cursor to the first nonblank character on the line. Any further cursor
 movement would have to be done using "Left". "Left" returns TRUE when
 the cursor moves and FALSE when the cursor does not move.

 You would want to move left until the cursor does not move anymore,
 i.e., move left until "Left" returns FALSE. The editor allows you to
 do this with Macro Conditionals. The following is an example:

    Bottom:=Begline :>LT Left +>LT Meta Down

    :>LT   defines a label LT
    +>LT   if Left returns TRUE, go to label LT
           if Left returns FALSE, continue

 Macro Conditionals and a table of Return Values can be found in the
 "Microsoft Editor User's Guide."

 The final step is to assign the macro to a keystroke, as follows:

    Bottom:CTRL+END


 86. Saving without Exiting

 Product Version(s): 1.00   | 1.00
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER | appnote
 Last Modified:  6-JAN-1989    ArticleIdent: Q35538

 The following information is taken from an application note called
 "Microsoft Editor Questions and Answers." The application note also is
 available from Microsoft Product Support Services by calling (206)
 454-2030.

 Saving without Exiting

 You can save a file without exiting by using the keystrokes
 corresponding to the following functions:

    Arg Arg Setfile.

 A macro can be written to perform these functions in one keystroke
 (Alt+S), as follows:

    Save:=Arg Arg Setfile
    Save:Alt+S


 87. None Assignment Must Be Lowercase

 Product Version(s): 1.00   | 1.00
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified:  1-NOV-1988    ArticleIdent: Q35648

 When using the backup:none option in the TOOLS.INI file, the none
 cannot begin with a capitol N.

 The "None is an illegal setting" error will be generated if you have
 Backup:None (capitol N) in the TOOLS.INI file.

 The correct form is backup:none


 88. Width Function Not implemented

 Product Version(s): 1.00   | 1.00
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified: 20-OCT-1988    ArticleIdent: Q35649

 Some graphics cards allow the monitor to go into modes greater than 80
 columns. The Microsoft Editor has a function called Width to allow
 more than 80 columns, however, this function has not yet been
 implemented.

 This feature is under review and will be considered for inclusion in
 a future release.


 89. M on an AMDEK System 88 XT Clone

 Product Version(s): 1.00
 Operating System:   MS-DOS
 Flags: ENDUSER |
 Last Modified: 30-SEP-1988    ArticleIdent: Q35817

 Problem:

 When running M on an AMDEK System 88, which is an XT clone, the M
 editor hangs the machine requiring a warm boot. The machine was using
 an EPC Keyboard that is an AT style keyboard.

 Response:

 This is a known incompatibility with this hardware configuration and M
 Version 1.00. AMDEK is aware of this problem and has a patch that they
 can send you. To obtain a patch, call AMDEK at [phone]. The
 patch contains the following three files:

 READ.ME
 CLREPC.EXE
 SETEPC.EXE.

 The problem is that M was checking the keyboard, which in this case
 was an AT style keyboard, and assuming it was running on an AT clone.
 This situation caused the hang.

 By running SETEPC.EXE, a switch is set so M sees the keyboard as a XT
 keyboard and everything functions properly. CLREPC.EXE clears this
 switch.


 90. Placing the NULL Character in a File with M/MEP

 Product Version(s): 1.00   | 1.00
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified: 20-OCT-1988    ArticleIdent: Q35819

 Problem:

 I would like to place the null character in a file using M or MEP. I
 have tried using the Quote function and successfully put other
 non-printable characters in the file, such as the bell character.
 However, attempts to place a null in the file with the Quote function
 were ignored. Is this possible?

 Response:

 No. Placing null characters in a file with M/MEP is not possible. The
 editor uses null-terminated strings internally, as well as NULL return
 values from some character functions. Because the editor uses the null
 character, you are not allowed to use null.


 91. Case Sensitivity of Switches

 Product Version(s): 1.00
 Operating System:   MS-DOS
 Flags: ENDUSER |
 Last Modified: 31-OCT-1988    ArticleIdent: Q36415

 The BACKUP text switch is case sensitive with the arguments given it.
 The arguments "undel", "bak", and "none" need to be lowercase, otherwise
 an error will be reported.



 92. Intitialize function is Shift+F8

 Product Version(s): 1.00   | 1.00
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER | docerr
 Last Modified:  2-NOV-1988    ArticleIdent: Q36567

 There is a documentation error on Page 64 of the "Microsoft Editor for
 MS OS/2 and MS-DOS Operating Systems User's Guide". The line

 3. Invoke the Initialize function (press F10).

 should read as follows :

 3. Invoke the Initialize function (press SHIFT+F8)

 The F10 should be replaced with SHIFT+F8. SHIFT+8 is the default.


 93. Percent (%) Character in Filenames

 Product Version(s): 1.00   | 1.00
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER | buglist1.00
 Last Modified: 20-OCT-1988    ArticleIdent: Q36570

 The Microsoft Editor cannot handle a percent sign as the first
 character in the filename (%test.dat). While this is a valid DOS
 filename, it will cause garbage to be printed on the status line and
 may generate a run-time error.

 Microsoft has confirmed this to be a problem in Version 1.00. We are
 researching this problem and will post new information as it becomes
 available.

 If you fill a line with 250 characters (the maximum), then press HOME
 to go to the beginning of the line and delete the line by pressing
 CTRL-Y, the editor will crash with the following error:

         run-time error R6003
         -integer divide by 0

 Both of the above problems only occur when a percent sign is used as
 the first character in the filename. To work around this problem, do
 not use the percent sign as the first character.



 94. How Tabs Are Treated in the Microsoft Editor

 Product Version(s): 1.00   | 1.00
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified: 14-OCT-1988    ArticleIdent: Q36580

 Problem:

 Some text editors preserve tab characters automatically. These editors
 maintain tabs (ASCII 9 characters) as they are stored in a file, and
 distinguish between tab characters and spaces.

 The Microsoft Editor translates tab characters into spaces. This
 behavior only affects lines that you modify. If you load and save a
 file without changing any lines of text, the lines are written back to
 disk with all tab characters and spaces intact. Only the modified
 lines are affected by this conversion.

 It is not possible to disable this translation of tab characters into
 spaces in a modified line.

 In the Microsoft Editor, "tab"  is both a function name and the name
 of a key. The TAB key is assigned to the tab function by default. As a
 function, tab is nothing more than a move-to-next-column movement
 function. The placement of columns in determined by the TABSTOPS
 switch.

 When ever you edit a line, tab characters are translated to space
 characters using the FILETAB switch. So modified lines in the file are
 stored in the editor with spaces only. The FILETAB switch determines
 how the editor translates tab characters to spaces when reading in a
 line of text. If ENTAB is set to 1 or 2, then FILETAB also determines
 how the editor translates spaces to tabs when you save the file to
 disk. (Again, only modified lines are affected.)

 If you need to view the tabs as they are situated in your file you can
 use the TABDISP switch to show you which spaces will be compressed
 into a tab character at the next write to the disk file.


 95. 43- and 50-Line Modes

 Product Version(s): 1.00   | 1.00
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified: 20-OCT-1988    ArticleIdent: Q36613

 The M editor can make use of the 43-line EGA text mode and 50-line VGA
 text mode. The "height" numeric switch in the TOOLS.INI file specifies
 the number of lines used in the editing window; however, this number
 does NOT include the dialog and status display lines. Thus, to use 43
 lines of text you must set height=41; to use 50 lines you must set
 height=48.


 96. Microsoft System Journal M macros Fail

 Product Version(s): 1.00 1.01 | 1.00 1.01
 Operating System:   MS-DOS    | OS/2
 Flags: ENDUSER |
 Last Modified: 20-OCT-1988    ArticleIdent: Q36798

 In the September 1988 issue of the "MS System Journal," the article
 entitled "Customizing the Features of the M Editor Using Macros and C
 Extensions" contains erroneous examples.

 Both of the macros below fail in Version 1.00. Only the Bigprint macro
 fails in Version 1.01.

 The following is an example:

 Macro 1)

 ;print selected text macro
 print1:= copy arg "<clipboard>" setfile
 print2:= arg arg "TEMP.DAT" setfile setfile
 print3:= arg "PRINT TEMP.DAT" shell
 print4:= arg "DEL TEMP.DAT" shell
 printa:=print1 print2 print3 print4
 Printa:alt+P

 The above macro is supposed to print selected text. In M Version 1.00
 it works correctly the first time it is called from inside a file.
 However, it fails on subsequent calls to the macro prior to exiting
 the file. It does work correctly in the unreleased Version 1.01
 referenced in the article.

 The following macro is supposed to print the entire file. Instead, it
 prints only the line on which the cursor sits when the macro is
 called. As mentioned above, this fails in both Versions 1.00 and the
 unreleased Version 1.01 referred to in the article on Pages 59-72.

 The following is an example:

 Macro 2)

 ;bigprint macro to print entire file
 select1:= arg ppage
 select2:= arg arg "endoffile" mark
 select3:= arg mpage
 select4:= arg "endoffile"
 selectall:= select1 select2 select3 select4
 bigprint:=meta +>nometa cancel selectall meta :>nometa meta printa

 bigprint:Alt+z
 ;end of bigfoot macro.


 97. meta Anomalous Behavior

 Product Version(s): 1.00   | 1.00
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER | buglist1.00
 Last Modified: 31-OCT-1988    ArticleIdent: Q37072

 The following macros written for the M editor exhibit anomalous
 behavior for the function modifier meta. It appears that meta cannot
 modify itself, as demonstrated by the following macros.

 Microsoft has confirmed this to be a problem in Version 1.00. We are
 researching this problem and will post new information as it becomes
 available.

 Consider the following macros:

    MetaTest:= meta meta +> "meta off"=>0 :>1 "meta on":>0
    MetaTest:alt+0
    ; the above macro is supposed to check to see if the function
    ; modifier meta, invoked by the F9 key, is on or off. Compare
    ; the results of this macro with the macro immediately following.
    MetaTest1:= meta +> "meta off"=>0 :>1 "meta on":>0
    MetaTest1:alt+1
    ; the MetaTest1 macro fails to differ from the MetaTest macro in
    ; a significant manner. in contrast, consider the following
    ; macro, employing the insetmode function modifier.
    InsertTest:=insertmode insertmode +> "ins off"=>0 :>1 "ins on":>0
    InsertTest:alt+2.


 98. MASM m.exe Is Different than FORTRAN m.exe when Using DOS Comp

 Product Version(s): 1.00   | 1.00
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER | h_fortran
 Last Modified:  6-JAN-1989    ArticleIdent: Q38015

 Question:

 When I do a Comp command at the DOS prompt, why do the FORTRAN Version
 4.10 and MASM Version 5.10 packages contain m.exe files that differ at
 offset 15F9F, where the MASM m gives 37 and the FORTRAN m gives 38?
 Which one should I use for mixed-language programming?

 Response:

 This behavior is an error that was discovered after MASM Version 5.10
 was released, but before FORTRAN Version 4.10 was shipped. You can see
 this by invoking the editor and entering SHIFT+F1, which gives you
 file information. The date given in the MASM file is Jan. 29, 1987
 (hex37) when it should be Jan. 29, 1988 (hex 38). Other than this
 character in the date, they are identical, so you can use either one
 for mixed-language programming.


 99. Selecting Large Text Blocks with Microsoft Editor

 Product Version(s): 1.00   | 1.00
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified:  4-MAY-1989    ArticleIdent: Q38309

 Question:

 When I want to select a large block of code for the clipboard, I press
 ALT+A, then the DOWN ARROW key until I reach the last line I want to
 select. This process is very slow if the block I am selecting is
 several pages long (almost a whole file). Is there a way to move
 faster to select a block than by using the CURSOR key (such as the
 equivalent of ^K-B and ^K-K in Wordstar)?

 Response:

 CTRL+PGDN (Ppara) serves this purpose, as documented on Pages 91 and
 104 of the "Microsoft Editor for MS OS/2 and MS-DOS Operating Systems:
 User's Guide." This key sequence will move you to a new paragraph each
 time you press the keys. If the movement sequence you want to use
 contains an Arg, it is either used by the command or canceled.

 A faster method is to define a couple of macros to help out. First, we
 need a macro that will mark the beginning spot in the text, as
 follows:

    txtmark:=arg arg "first" mark
    txtmark:alt+t

 The second macro automates using the mark as an argument, as follows:

   callmark:=arg "first"
   callmark:alt+u

 You can put these lines in your TOOLS.INI file.

 To use this pair, move to the first spot, press ALT+T, then move up or
 down using any movement keys to the second spot. Finally, press ALT+U
 and press a key that allows a markarg as an argument. (The Copy and
 Ldelete functions are among these.) Note: no highlighting occurs, so
 you'll have to be careful.

 Note: if you want the argument to be entire lines rather than a box,
 the cursor MUST be in the same column when you press ALT+U as it was
 when you pressed ALT+T. If you put it in a different column, you will
 be selecting a box argument rather than a line argument.


 100. Moving to the Beginning of the Line with Microsoft Editor

 Product Version(s): 1.00   | 1.00
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified:  6-JAN-1989    ArticleIdent: Q38310

 Question:

 Is there a way to go to column 1 of the screen with a key sequence
 instead of pressing the LEFT ARROW key until the cursor stops at
 column 1? I find myself wasting a lot of time doing this repetitive
 chore. The HOME key only takes me to the beginning of the text on the
 line, not the beginning of the line, which is where I want to be if I
 want to delete a line, for example. I currently use ^K-S with the
 Wordstar extension.

 Response:

 Meta Begline (F9 HOME in the standard configuration) will do it. If
 you'd like it on one key, you can assign the functions to a key using
 the macro facility.


 101. Inserting a Line from Clipboard into File with Editor

 Product Version(s): 1.00   | 1.00
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified: 15-MAY-1989    ArticleIdent: Q38311

 Question:

 I am confused by the way a line is inserted from the clipboard into a
 file. It seems to depend on whether Insert is On or Off. Also, it
 sometimes pushes the other lines down and sometimes it pushes the
 existing line to the right. I see no consistency to all this. Can you
 explain the concepts?

 Response:

 The Insert mode has no bearing on line insertion. However, how you
 delete the line has a lot to do with it. In general, don't use the
 DEL key for multiple-character deletions. It is usually assigned to
 the sdelete function, which always deletes a stream of text, as
 documented on Page 107 of the "Microsoft Editor for MS OS/2 and MS-DOS
 Operating Systems: User's Guide."

 A stream is all of the text between the place where the cursor was
 when you typed Arg and where it is when you press sdelete, regardless
 of the beginning and ending cursor columns or how many lines are
 contained in the region. Whenever you mark an area and press sdelete
 (the DEL key), you will delete the STREAM you have marked, even
 though the region highlighted may look different.

 It's usually best to use CTRL+Y (Ldelete) for deletions which begin
 and end on different lines. Note that the COPY key (CTRL+INS) does not
 accept stream arguments, therefore, it always copies the highlighted
 area.


 102. Use a Colon when Assigning a Macro to a Keystroke

 Product Version(s): 1.00   | 1.00
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER | docerr
 Last Modified: 12-JAN-1989    ArticleIdent: Q39574

 There is a documentation error on Page 50 of the "Microsoft Editor
 User's Guide." Section 6.3.2 incorrectly shows a semicolon when
 assigning a macro to a keystroke as follows:

    Header;ALT+H

 The correct example should contain a colon as follows:

    Header:ALT+H


 103. Quote Function and Typing in Graphic Characters in M

 Product Version(s): 1.00   | 1.00
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified: 16-MAY-1989    ArticleIdent: Q39806

 Question:

 I want to input some graphics characters in the M editor. However,
 when I try to input the ASCII character 31 using the ALT key and the
 numeric keypad, the M editor beeps and displays the following message:

    "ctrl+_ is not assigned to any editor function"

 For the ASCII character 30, the M editor displays the following
 message:

    "ctrl+^ is not assigned to any editor function."

 How can I input those characters?

 Response:

 Use the editing Quote function in the M editor. The Quote function is
 associated with CTRL+P by default. After the Quote function is
 invoked, the following keystroke is taken literally. This function is
 mentioned in the "Microsoft Editor for MS OS/2 and MS-DOS Operating
 Systems User's Guide" on Page 105.

 The first 32 characters in the ASCII character set have two
 conflicting uses. As standard ASCII characters, they are used for
 communications control and printer control. They are also used by IBM
 to represent some useful graphics characters.

 Using the Quote function in the M editor can prevent these ASCII
 characters from being interrupted as control characters.


 104. M Hangs if the textarg Given to ArgCompile Is Incomplete

 Product Version(s): 1.00
 Operating System:   MS-DOS
 Flags: ENDUSER |
 Last Modified: 12-JAN-1989    ArticleIdent: Q40235

 If you want to compile a program inside the M editor using the
 following command, textarg should contain the full compile line as
 typed at the DOS prompt:

    Arg Arg textarg ArgCompile

 The following is an example:

    cl /Zi /Od demo.for

 If textarg contains just the name of the program (demo), the hard disk
 light will come on and the message "compilation complete" will appear
 on the bottom of the screen even though demo.for was not compiled.

 If textarg contains the full program name (demo.for), your computer
 hangs if you press SHIFT+F3. Sometimes, there will be lost clusters
 and allocation errors as reported by chkdsk.

 This problem was not encountered under OS/2.



 105. Redirecting Errors to an Error File in M

 Product Version(s): 1.00   | 1.00
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified:  1-MAY-1989    ArticleIdent: Q40177

 Under DOS, M Version 1.00 will store the error messages in the M.MSG
 file. This file is located in the directory the TMP environment
 variable points to. If TMP is not set, this file is located in
 the current working directory. Under OS/2, MEP uses named pipes, so
 there is no file to look at.


 106. FileWrite() Function Fails to Write Back Out to the File

 Product Version(s): 1.00   | 1.00
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified: 15-MAY-1989    ArticleIdent: Q40356

 Problem:

 I have a problem using the FileWrite Function programming with the M
 and MEP Editor Version 1.00. I want to read a file (EXAMPLE.DOC) and
 write exactly the same in a new file (FOO.DOC).

 Response:

 To test the example below, you only have to create a file named
 EXAMPLE.DOC. See the compiler switches at the end of this article. The
 second file FOO.DOC is created, but it is never written to it always
 has zero length.

 This is a problem with MEP Version 1.00's FileWrite() function. This
 is one of the problems that kept the filter extension described in the
 "Microsoft Systems Journal" September 1988 from working in Version
 1.00.

 Microsoft has confirmed this to be a problem in Version 1.00. We are
 researching this problem and will post new information as it becomes
 available.

 The following is a short example where the problem (Function FileWrite
 does not write) occurs:

 #include "ext.h"
 #define TRUE    -1
 #define FALSE   0
 #define NULL    ((char *) 0)

 flagType pascal EXTERNAL Write(
 unsigned int argData,
 ARG far * pArg,
 flagType fMeta)
 {
     flagType flg;
     PFILE pFile;
     char  *p = "EXAMPLE.DOC";
     char  *w = "FOO.DOC";

     if((pFile = FileNameToHandle(p,NULL)) == 0)
     {
         pFile = AddFile(p);
         FileRead(p, pFile);
     }
     flg = FileWrite(w, pFile);
     return (flg);
 }

 struct swiDesc  swiTable[] ={
     { NULL, NULL, 0 }
 };

 struct cmdDesc  cmdTable[] ={
     {"Write", Write, 0, NOARG },
     {NULL,  NULL, 0, 0}
 };

 void EXTERNAL WhenLoaded (void)
 {
     SetKey("Write", "alt+w");
     DoMessage("Write function now loaded.");
 }

 /*

 *** Compiler switches I used ***

 cl /c /Gs /Asfu %1.c
 cl /Lp /AC /Fe%1.dll exthdrp.obj %1.obj skel.def

   */


 107. Optimizing C or QuickC 2.00 Required for Writing C Extensions

 Product Version(s): 1.00   | 1.00
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER | S_C S_QuickC
 Last Modified: 17-MAY-1989    ArticleIdent: Q39997

 Question:

 I would like to customize the Microsoft Editor by writing C
 extensions. Can I use QuickC Version 1.00, QuickC Version 1.01, or
 QuickC Version 2.00?

 Response:

 No. You must use the Microsoft C Version 4.00 Optimizing Compiler or a
 later version to write C extensions to the Microsoft Editor. QuickC
 Versions 1.00 and 1.01 cannot be used because they do not support the
 required switch /Asfu.

 However, Version 2.00 does support the /Asfu switch when using QCL.
 Therefore, you can use Version 2.00 and QCL to create C extensions.

 For more information, see Pages 68 and 83 of the "Microsoft Editor for
 MS OS/2 and MS-DOS Operating Systems: User's Guide."


 108. Search and Replace Macro for M Editor

 Product Version(s): 1.00   | 1.00
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified: 12-JAN-1989    ArticleIdent: Q39998

 Question:

 Can you write a macro to perform a search and replace on a particular
 string? When I try to do so, the replace function prompts me for a
 string argument. I want the replace function to read the string from
 the macro.

 Response:

 The following is an example of a replace macro that accepts its
 argument from inside the macro:

    myreplace:=replace "oldtext" newline "newtext" newline

 When the myreplace macro is invoked, all the occurrences of "oldtext"
 string, from the cursor position to the end of the file, are replaced
 with the "newtext" string. The use of the newline function allows the
 macro to respond to the replace-function prompt for a string argument.

 To define the myreplace macro and assign it to the F12 key, enter the
 following keystrokes from inside the M editor:

    ALT+A
    MyReplace:=replace "oldtext" newline "newtext" newline
    ALT+=

    ALT+A
    MyReplace:F12

 To execute the myreplace macro, press the F12 key.


 109. M.TMP Reset When Window Closed

 Product Version(s): 1.00   | 1.00
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER | mep buglist1.00
 Last Modified: 15-MAY-1989    ArticleIdent: Q40681

 Question:

 When I invoke the M editor, open a second window (arg F6 or arg arg
 F6), and close the first window (meta F6), my M.TMP file is reset. The
 only file in my M.TMP file is the one that I edited to perform this
 operation. Is there a way to prevent this from happening?

 Response:

 This phenomena occurs whenever you close a window that has had a file
 opened in it. Hence, if you open a file in the second window, then
 close the second window, M.TMP is reset. To avoid this behavior, don't
 close a window in which a file has been opened.

 Microsoft has confirmed this to be a problem in Version 1.00. We are
 researching this problem and will post new information as it becomes
 available.



 110. QHMEP.DLL Remaps Two Keys in MEP Version 1.00

 Product Version(s): 1.00
 Operating System:   OS/2
 Flags: ENDUSER | buglist1.00
 Last Modified: 16-MAY-1989    ArticleIdent: Q41324

 Problem:

 I have remapped the keys CTRL+S and CTRL+P in MEP Version 1.00 to the
 psearch and up functions. After loading the extension QHMEP.DLL, which
 comes with the Version 1.06 OS/2 SDK, the two keys CTRL+S and CTRL+P
 are not mapped to psearch and up anymore. Furthermore, these keys
 cannot be reassigned back to psearch and up. I seem to be locked out
 of using these keys.

 Response:

 This problem occurs because the editor is taking over these keys,
 preventing them from being reassigned.

 Microsoft has confirmed this to be a problem in MEP Version 1.00. We are
 researching this problem and will post new information as it becomes
 available.



 111. Useful Macros for the Microsoft Editor

 Product Version(s): 1.00    |  1.00
 Operating System:   MS-DOS  | OS/2
 Flags: ENDUSER |
 Last Modified: 16-MAY-1989    ArticleIdent: Q40755

 Below are macros for the Microsoft Editor that allow you to save a
 marked portion of a file and insert it into another file. Also, there
 are macros that speed up marking large areas of text.

 To save a marked area of a file, mark the area and invoke this macro
 by typing ALT+V. Note that although the macro is broken onto two lines
 here, you should put it on one line in your TOOLS.INI file.

 savemark:=copy arg "command /c del c:\\t" shell arg "\\t" setfile
           refresh paste setfile
 savemark:alt+v

 A one-key way to include the file in another file is to use the macro
 by typing ALT+I:

 insertmark:=arg arg "\\t" paste
 insertmark:alt+i

 To mark the top and bottom of the text area, use these macros. Type
 ALT+T to place the marker, then ALT+U to use it. Type CTRL+INS or
 CTRL+Y to copy or delete the text. Note that if your cursor is not in
 the same column when you type ALT+U as when you typed ALT+T, the area
 marked will be a box rather than a set of lines. Note also that the
 marked area will NOT show up on the screen.

 tempmark:=arg arg "temp" mark
 usemark:=arg "temp"
 tempmark:alt+t
 usemark:alt+u



 112. Using Brief Emulation and Tags in TOOLS.INI

 Product Version(s): 1.00   | 1.00
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER | buglist1.00
 Last Modified: 17-MAY-1989    ArticleIdent: Q41475

 If you invoke a tagged section from your TOOLS.INI when using the
 Microsoft editor with brief keystroke emulation, some of the key
 assignments will revert back to the default.

 Microsoft has confirmed this to be a problem in Version 1.00. We are
 researching this problem and will post new information as it becomes
 available.

 As demonstrated in the following example, some of the keystrokes are
 reassigned to the default keystrokes if you rename the BRIEF.INI file
 to be TOOLS.INI and then add a new tag section:

 [m-mono]
     height:23
     fgcolor:07
     errcolor:0F
     stacolor:70
     infcolor:70

 Start editing a file, then bring in this new tag field by typing the
 following:

    arg "mono" shift+f10

 The following demonstrates this behavior and all compile lines revert
 to default:

    window             will change from F1 to unassigned
    help               will change from ALT+H to F1
    argcompile         will change from ALT+F10 to F5
    save               will change from ALT+W to undefined
    linemark           will change from ALT+I to undefined
    linetotop          will change from CTRL+T to undefined
    leftsideofwindow   will change from SHIFT+HOME to undefined
    rightsideofwindow  will change from SHIFT+END to undefined
    createhorizwindow  will change from F3 to undefined
    createvertwin      will change from F4 to undefined
    deletewindow       will change from F5 to undefined



 113. Minimum Requirements for Writing a M Extension

 Product Version(s): 1.00   | 1.00
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified: 16-MAY-1989    ArticleIdent: Q42241

 Question:

 What files and software do I need to be able to write an extension for
 the Microsoft Editor?

 Response:

 To create C extensions, you need to have the following files and
 software present in your current directory (or directories listed in
 the PATH or INCLUDE environment variables, as appropriate):

 1. The Microsoft C Optimizing Compiler Version 4.00 or later;
    or Microsoft QuickC Version 2.00

 2. The Microsoft Overlay Linker Version 3.60 or later; or the
    Microsoft Segmented-Executable Linker Version 5.01

 3. EXTHDR.OBJ (supplied with the editor) or EXTHDRP.OBJ (a file
    supplied with the editor for creating protected-mode extensions)

 4. EXT.H header file provided with the editor

 5. SKEL.DEF, the standard definitions file supplied with the editor;
    to be used with all extension

 You need a minimum 150K of available memory for the editor to load a C
 extension at run time in addition to the size of the extension itself.


 114. 43- and 50-Line Modes with the IBM 8514 Monitor

 Product Version(s): 1.00 1.02
 Operating System:   MS-DOS
 Flags: ENDUSER | buglist1.00 fixlist1.02
 Last Modified: 28-JUL-1989    ArticleIdent: Q42365

 The Microsoft Editor does not go into 43- or 50-line line mode on the
 IBM 8514 monitor.

 Version 1.00 of the Microsoft Editor does not support higher line
 modes with the IBM 8514 monitor. Regardless of the switch setting you
 give in the TOOLS.INI file, it always comes up in 25-line mode.

 For example, setting the height:41 or height:48 switch in the
 TOOLS.INI file results in the Microsoft Editor coming up in 25-line
 mode.

 Microsoft has confirmed this to be a problem in Version 1.00 of the
 Microsoft Editor. This problem was corrected in the Microsoft Editor
 Version 1.02.


 115. Savecur and Restcur Save Relative Position in File, on Screen

 Product Version(s): 1.00   | 1.00
 Operating System:   MS-DOS | OS2
 Flags: ENDUSER |
 Last Modified: 17-MAY-1989    ArticleIdent: Q42758

 The Microsoft Editor functions Savecur and Restcur save the current
 cursor position relative to the file and the screen. Therefore, the
 screen will be restored exactly as it appeared when the Savecur
 function was invoked.

 The following macros were intended to scroll the screen up and down
 while leaving the cursor position relative to the terminal screen to
 be stationary:

 ReposDown:=Savecur Meta Up Up Restcur
 ReposDown:Ctrl+Down

 ReposUp:=Savecur Meta Down Down Restcur
 ReposUp:Ctrl+Up

 Because Savecur and Restcur preserve and restore the cursor position
 relative to the screen, the macros appear to do nothing. But actually,
 each executes correctly. For example, the ReposDown does the following:

 1. Savecur : saves the current position relative to the file and the
              screen

 2. Meta Up : moves the cursor to the top of the screen

 3. Up      : moves the cursor up one line, (thus scrolling the screen
              down one line)

 4. Restcur : restores the screen to the original configuration
              (appears as if nothing had happened)

 One way to achieve the desired result is to use the Mark function. The
 Mark function saves the current location in the file. The relative
 screen position is not preserved, whereas the Savecur and Restcur
 functions do save the relative screen position.

 The following macros give the desired result:

 ReposDown:=Arg Arg "tag" Mark Meta Up Up Arg "tag" Mark Up
 ReposDown:Ctrl+Up

 ReposUp:=Arg Arg "tag" Mark Meta Down Down Arg "tag" Mark Down
 ReposUp:Ctrl+Down

 The word "tag" is an arbitrary tagname for the Mark function.


 116. Copy Is a Reserved Word

 Product Version(s): 1.00   | 1.00
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified: 17-MAY-1989    ArticleIdent: Q42763

 The word copy is a reserved word in the Microsoft Editor. If you write
 an M extension and name it "copy", the editor will load but not
 execute your extension.

 If you name the function (for example) cpy rather than copy, it will
 work correctly.

 The following declaration incorrectly uses the reserved word "copy."
 Renaming the the function "cpy" will resolve the problem:

 flagType pascal EXTERNAL copy (argData, Parg, fMeta)
 unsigned int argData;
 ARG far *Parg;
 flagType fMeta;



 117. A C Extension to Select an Arbitrary Number of Lines of Text

 Product Version(s): 1.00
 Operating System:   MS-DOS
 Flags: ENDUSER | extension highlight select
 Last Modified:  1-JUN-1989    ArticleIdent: Q43006

 To select an arbitrary number of lines of text in the Microsoft
 Editor, I must use the Arg function, then use the DOWN ARROW key until
 the desired number of lines are selected. This is inconvenient if more
 than a few lines are to be selected.

 This article provides a simple editor extension that selects the
 number of lines you specify.

 For information on loading the function, refer to the M editor
 reference manual.

 To invoke the function, use the Arg key to introduce the argument
 (i.e., the number of lines to be selected), then press the key
 assigned to the function. In Version 1.00 of M, the selected text will
 not be highlighted.   In Version 1.02 of M, the selected text will be
 highlighted, however further cursor movements will change the selected
 area without altering the highlighted area.

 ================ Make file ===============

 BASE=select
 CFLAGS=-c -W2 -Asfu -Gs
 LINKFLAGS=/NOI /NOD

 $(BASE).obj : $(BASE).c
     cl $(CFLAGS) $(BASE).c

 $(BASE).exe : $(BASE).obj
     link exthdr.obj $(BASE), $(BASE), \
     $(LINKFLAGS),clibcer.lib;

 ================ select.c ================

 #include "ext.h"
 #include <stdlib.h>

 #define TRUE    -1
 #define FALSE   0
 #define NULL    ((char *) 0)

 flagType pascal EXTERNAL Select (argData, pArg, fMeta)
 unsigned int argData;
 ARG far * pArg;
 flagType fMeta;
 {
     int  nCount, i ;

     if (pArg->argType == TEXTARG)
         if (nCount = atoi (pArg->arg.textarg.pText))
             {
             for (i = 0 ; i < nCount ; i++)
                 fExecute ("Arg Down") ;
             }

     return TRUE;
 }

 struct swiDesc  swiTable[] =
 {
     {   NULL, NULL, NULL    }
 };

 struct cmdDesc  cmdTable[] =
 {
     {"Select", Select, 0, TEXTARG},
     {NULL,  NULL, NULL, NULL}
 };

 WhenLoaded ()
 {
      SetKey("SELECT","ALT+B");
      return TRUE;
 }


 118. Cannot Use Standard Device Names as Filenames

 Product Version(s): 1.00   | 1.00
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified: 17-MAY-1989    ArticleIdent: Q43074

 You cannot use the standard device names (COMx, LPTx, and CON) as the
 base filename in the Microsoft Editor.

 For example, the command "M COM1.C" under DOS will attempt to open the
 communications port for editing and will hang the computer.

 This information has been tested for the following devices: COM1,
 COM2, LPT1, LPT2, CON. The different devices give slightly different
 results. COM1 and COM2 will hang the computer immediately, but the
 others will give errors or hang when the file is saved.

 The protect-mode editor behaves in the same fashion.


 119. Accessing Predefined Switches in C-Extension

 Product Version(s): 1.02   |  1.02
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER | FindSwitch
 Last Modified: 17-MAY-1989    ArticleIdent: Q43436

 When writing a C extension for Microsoft Editor Version 1.02, you can
 access the predefined editor switches through the function
 FindSwitch(). FindSwitch() is intended to be used to access the values
 of the predefined editor switches, not to modify the values. Modifying
 the switches through FindSwitch() has undefined results.

 The following code fragment retrieves the value of the switch
 "tabstops" for use in your C extension:

 #include "ext.h"
       .
       .
       .

 PSWI pTabStops ;
 int  nTabStops ;
       .
       .
       .

 pTabStops = FindSwitch ("tabstops") ;
 nTabStops = *(pTabStops->act.ival) ;

 Any change to the value of the switch "tabstops" made outside your
 C extension will be reflected in the value of nTabStops inside your
 C extension.

 You can find the FindSwitch() prototype in the include file EXT.H. The
 function FindSwitch() is not available in the Microsoft Editor Version
 1.00.

 The structure, swiTable, consists of a series of structures, each
 structure describing a user-defined switch. The purpose of swiTable is
 to add user-defined, not predefined, switches. It is incorrect to name
 the predefined switches in the switch table. For that reason the
 following example is incorrect as it names "tabstops," a predefined
 switch:

 struct swiDesc swiTable [] =
  {
   {"tabstops", &nTabStops, NUMERIC | RADIX10}   /*  INCORRECT  */
   { NULL, NULL, 0}
  } ;

 Do not modify the predefined switches through the switch table. You
 can change the values of the predefined switches from within an
 editing session or in TOOLS.INI.


 120. The Editor Can Be Very Slow When MEP Memory Limit Is Pushed

 Product Version(s): 1.00 1.02
 Operating System:   OS/2
 Flags: ENDUSER |
 Last Modified: 17-MAY-1989    ArticleIdent: Q44000

 Problem:

 I have a file FOO, which is 21733 bytes long and contains 850 lines.
 When I perform the following steps the compiler appears to hang. In
 fact, however, the compiler is being forced to go to disk for its own
 memory management.

 When performing the steps described below with the README.DOC from C
 Version 5.10 (which is 64964 bytes) and running on a 16mHz machine,
 after Arg Refresh, it took almost 30 seconds for MEP to return
 control.

 This problem is due to the fact that MEP does its own memory
 management. When you do Arg Refresh, MEP must reread the buffer
 containing the modified file from disk. In addition, MEP must store
 back to disk the buffer containing the last block of text pasted to
 the file. This swapping of two large files is what causes the delay.

 Microsoft has confirmed this lack of speed to be a limitation with
 Version 1.00 and 1.02 of the Microsoft Editor. We are researching this
 problem  and will post new information as it becomes available.

 To duplicate this problem, perform the following steps:

 1. Invoke the following to run the editor:

       [C:\]m foo

 2. Make some changes to modify the buffer.

 3. Issue the following command to the editor:

       arg "bar" setfile

    The editor responds "File c:\bar does not exist, create?"

 4. Respond "y" for yes. You are now in bar's buffer.

 5. Issue the following command to read in the original contents of the
    file:

       arg arg "foo" paste

    This process should work correctly.

 6. If you now want to get rid of the new buffer, issue the following
    command:

       arg refresh

    The editor responds with something similar to the following:

       "Do you really want to delete the buffer?"

 7. Respond "y" for yes.

    The editor appears to hang.


 121. Why Syntax Errors Might Not Display While Compiling in M

 Product Version(s): 1.00   | 1.00
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified:  1-MAY-1989    ArticleIdent: Q43647

 Question:

 While inside the Microsoft Editor, I compiled a program that I know
 contained syntax errors. The message "Compilation Complete - return
 code is x" (where "x" is an integer value) appeared, signifying that
 an error had occurred while compiling.

 I pressed SHIFT+F3 to display those errors and the message "No more
 compilation messages" was displayed on the bottom of the screen. Why
 aren't my program's error messages displayed inside the editor?

 Response:

 You see error messages only if the compiler or linker runs correctly
 and passes the error messages in the correct format to the editor; if
 the compiler itself fails, you will not see any messages.

 Because M spawns the compiler, you could be running out of file
 handles. You know that the system has run out file handles if the
 M.MSG file is not created. Setting files=20 in your CONFIG.SYS file
 should correct the problem.

 Other possible causes for not getting error messages are as follows:

 1. You could be running out of memory. You can check this by shelling
    out of M.EXE (with SHIFT+F9) and issuing the DOS CHKDSK command to
    display the available memory.

 2. The compiler might not be able to find the specified file.
    Consider the following example, in which you invoke M.EXE as
    follows:

       C:\> M c:\c5\source\test.c

    If you compile the program with ARG COMPILE, the information line
    displays the following:

       CL /c /Zep /D LINT_ARGS test.c.

    The compiler will not find TEST.C in the current directory, so an
    error is returned.

    For more information, query on the following phrases:

       Microsoft Editor
       full path

 3. The EXTMAKE switches might have been incorrectly modified in the
    TOOLS.INI file, as in the following example:

       EXTMAKE:bas BC /Zi /O %s

    The line above is incorrect because it is missing a semicolon (;)
    at the end. The command line following the extension must be complete.
    Both the Microsoft BASIC Compiler and MASM will prompt you for
    additional information if a semicolon is not at the end of the line.

 4. Make sure the options used are valid for the compiler. In the
    following example, the option /Fa is an invalid option for the
    QCL.EXE compiler:

       QCL /Fa filename.c

 5. The compiler must be in the current path. If the compiler fails to
    execute, due to some problem external to the editor, M will
    display the ambiguous message "No more compilation messages."

    A good way to check the validity of the Compile command and to check
    for the presence of the compiler is to type in the compile line with
    all of the options directly from DOS.


 122. MEP GP Faults After Consecutive Searches.

 Product Version(s): 1.00
 Operating System:   OS/2
 Flags: ENDUSER | buglist1.00
 Last Modified:  1-JUN-1989    ArticleIdent: Q44887

 MEP gets an access violation and crashes after several searches for a
 string.

 Microsoft has confirmed this to be a problem with MEP.EXE Version
 1.00. This problem was corrected in MEP.EXE Version 1.02.

 Note: Version 1.02 of the Microsoft Editor is only available with
 FORTRAN 5.00. The documentation required for M and MEP Version 1.02
 make it impossible to release except with a major language release.

 The text file that caused MEP to fail was 54400 bytes and contained
 the string "error" in 81 different locations. To reproduce this
 problem, search for the string "error". The default keystrokes are

    Arg "error" F3

 for the first search, and the following for each additional search:

    F3

 On the 81st search, the Microsoft Editor for Protect, generates a
 General Protection Violation.


 123. Status Line Input with a Blinking Cursor

 Product Version(s): 1.00   | 1.00
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER | GETINPUT.ARC S12311.EXE
 Last Modified: 13-SEP-1989    ArticleIdent: Q44925

 Question:

 Is it possible in the Microsoft Editor to write an extension that will
 accept a line of input from the user, preferably from the status line?

 Response:

 Version 1.02 of the Microsoft Editor offers a very convenient way to
 do this. The GetString() callback function performs exactly this type
 of input. Version 1.00 of the Editor, however, does not have such a
 callback. It is possible to put together a routine that reads user
 input using the ReadChar() function in M Version 1.00. However, since
 ReadChar() waits for the next available character, there is no
 convenient way to flash a cursor during input when using this
 approach.

 The function provided below is a status-line input routine that does
 provide a flashing cursor. It uses the KbHook() and KbUnHook()
 functions to prevent the editor from scanning the keyboard and then
 reads the keyboard directly using the kbhit() and getch() functions
 from the C run-time library.

 An example C extension that demonstrates this function is available
 in the Software\Data Library. This file can be found by searching on
 the keyword GETINPUT, the Q number of this article, or S12311.
 GETINPUT was archived using the PKware file-compression utility.

 Status-Line Input Routine
 -------------------------

 #include "ext.h"
 #include <stdio.h>
 #include <string.h>
 #include <stdlib.h>
 #include <conio.h>

 #define TRUE            1
 #define FALSE           0

 typedef unsigned        BOOL;

 char *GetInput( int BufLen, char *theBuffer );

 /* GetInput provides a means of getting user input from the status line
  * with a blinking cursor in a manner similar to M 1.02's GetString().
  * KbUnHook is used to capture keyboard input. KbHook restores normal
  * keyboard reading to the editor.
  *
  * Receives:    BufLen - Length of input buffer
  *              theBuffer - Pointer to input buffer
  *
  * Returns:     A pointer to the modified buffer, or NULL if ESC was
  *              used to cancel input.
  */
 char *GetInput(
     int             BufLen,
     char            *theBuffer )
 {
     char            Key;                        /* ASCII code of key */
     int             i = 0;                      /* Position in buffer */
     BOOL            CursorOn = TRUE;            /* State of cursor */
     int             FlashCount = 0;             /* Cursor state counter */
     int             CursorToggleCount = 100;    /* Iterations between changes
                                                    in cursor state */
     char            *r;                         /* Return pointer */

     /* Unhook the keyboard so that the editor no longer intercepts
      * keystrokes.
      */
     KbUnHook();

     /* Get keyboard input from user, stopping when ESC or ENTER is hit.
      * Characters not in the range of 32 to 127 are ignored.  Backspace
      * will work properly.  No more than (BufLen - 2) characters may
      * be entered.
      */
     do
     {
         /* Flash a cursor while waiting for the next keypress.
          */
         while( !kbhit() )
         {
             if( ++FlashCount == CursorToggleCount )
             {
                 FlashCount = 0;
                 CursorOn = !CursorOn;
                 if( CursorOn )
                 {
                     strcat( theBuffer, "_" );
                     DoMessage( theBuffer );
                 }
                 else
                 {
                     theBuffer[i] = '\0';
                     DoMessage( theBuffer );
                 }
             }
         }

         /* Snarf the key
          */
         Key = (char)getch();

         /* Handle backspace.
          */
         if( (Key == 8) && (i > 0) )
         {
             theBuffer[--i] = '\0';
             DoMessage( theBuffer );
         }

         /* Handle normal character.
          */
         if( (Key >=32) && (Key <= 127) && (i < BufLen - 2) )
         {
             theBuffer[i++] = Key;
             theBuffer[i] = '\0';
             DoMessage( theBuffer );
         }
     } while( (Key != 13) && (Key != 27) );

     /* If ESC was pressed, toss the input and NULL the input buffer,
      * else perform a little cleanup.
      */
     if( Key == 27 )
     {
         theBuffer[0] = '\0';
         DoMessage( theBuffer );
         r = NULL;
     }
     else
     {
         if( CursorOn )
             theBuffer[i] = '\0';
         DoMessage( theBuffer );
         r = theBuffer;
     }

     /* Restore normal keyboard input.
      */
     KbHook();

     return( r );
 }


 124. CALLTREE Produces No Warnings When Out of Disk Space

 Product Version(s): 1.00   | 1.00
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER | S_C H_MASM H_Fortran S_PasCal
 Last Modified: 23-JUN-1989    ArticleIdent: Q45618

 The CALLTREE.EXE utility shipped with the Microsoft Editor (included
 with MASM, Optimizing C, FORTRAN, and Pascal) does not produce a
 warning if it runs out of disk space while writing output files. It
 simply closes the file being currently written and attempts to produce
 the next file. If the disk has no space free, the file will be created
 and closed with a length of 0 (zero) bytes. No error messages are
 produced in any case.

 Microsoft is aware of this limitation of CallTree. The error checking
 and messages features are under review and will be considered for
 inclusion in a future release.


 125. Documentation Errors in "Configuring On-Line Help" for M 1.02

 Product Version(s): 1.02   | 1.02
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER | docerr
 Last Modified: 11-SEP-1989    ArticleIdent: Q46272

 There are several documentation errors in the section "Configuring
 On-Line Help" on Page 101 of the "Microsoft Editor User's Guide for MS
 OS/2 and MS-DOS Operating Systems." This is the documentation for the
 Microsoft Editor (M) Version 1.02, which first became available with
 FORTRAN Version 5.00. These errors prevent access to M help. The
 documentation says to add the following tagged section to your
 TOOLS.INI file:

    [m-help.mxt mep-help.mxt]
    helpfiles:path\file.hlp

 The tag header should be as follows:

    [m-help mep-mhelp]

 Including ".mxt" prevents M from accessing help.

 Also, in the paragraph labeled Number 2 that describes installation
 for on-line Help when running under OS/2 protected mode only, there is
 a misprint. The following sentence refers to a nonexistent file
 "MHELP.DLL":

    MHELP.DLL is an extension to the editor.

 The correct file is MHELP.PXT, so the sentence should read as follows:

    MHELP.PXT is an extension to the editor.


 126. CMD.EXE Shell Fails with Incorrect COMSPEC

 Product Version(s): 1.00 1.02
 Operating System:   OS/2
 Flags: ENDUSER |
 Last Modified: 26-SEP-1989    ArticleIdent: Q47763

 Question:

 When I attempt to shell out of the MEP editor environment via the
 Shell editor function (SHIFT+F9), why does the following message
 appear at the bottom of the screen?

    Spawn failed on C:\OS2\CMD.EXE   - No such file or directory

 Response:

 The problem is usually due to an incorrect setting of the COMSPEC
 environment variable in the CONFIG.SYS file. A faulty setting of this
 variable, which informs the operating system of the command
 interpreter's location, prevents the DOS EXEC system call from finding
 and executing the command interpreter. Use the following procedure to
 eliminate the problem:

 1. Verify that the CMD.EXE file is in the directory specified by the
    COMSPEC environment variable.

 2. Ensure the syntax correctness of the COMSPEC setting. There should
    be no spaces on either side of the equal sign, and a carriage
    return must appear immediately following the last character of the
    path and filename setting.

        Correct example:       SET COMSPEC=C:\OS2\CMD.EXE<cr>

        Incorrect examples:    SET COMSPEC = C:\OS2\CMD.EXE<cr>
                               SET COMSPEC=C:\OS2\CMD.EXE;<cr>
                               SET COMSPEC=C:\OS2\CMD.EXE<space><cr>

 Under MEP 1.02, the COMSPEC environment variable is used to locate the
 command interpreter. If the command interpreter is not found according
 to the COMSPEC variable, the "Spawn failed...." error message is
 displayed. MEP Version 1.02 does not use the PATH environment variable
 for additional searching of CMD.EXE.

 Under MEP Version 1.00, however, the PATH variable is used when the
 CMD.EXE is not found via the COMSPEC setting. Hence, if the spawn
 failure error occurs when attempting to shell out of the MEP 1.00
 environment, examine the COMSPEC setting and also verify that CMD.EXE
 is traversed by the search path of the PATH environment variable in
 the CONFIG.SYS.


 127. Curtime Function Pulls In Time Editor Was Invoked

 Product Version(s): 1.00 | 1.00
 Operating System:   OS/2 | MS-DOS
 Flags: ENDUSER | buglist1.00 fixlist1.02
 Last Modified: 28-JUL-1989    ArticleIdent: Q46790

 The Microsoft Editor Version 1.00 does not implement the Curtime
 function correctly. The manual states that the current time will be
 inserted at the cursor when this function is invoked. Actually, the
 time the editor was invoked is inserted at the cursor. To get around
 this problem, simply initialize the editor before calling the Curtime
 function.

 Microsoft has confirmed this to be a problem in Version 1.00. This
 problem was corrected in Version 1.02 of the Microsoft Editor.

 The following macro illustrates how the Curtime function is invoked.
 This macro should be placed in the TOOLS.INI file under the [m] tag.

    time:=Curtime
    time:ALT+T

 When editing a file, pressing ALT+T inserts the time that the editor
 was loaded at the cursor. To obtain the current system time, either
 invoke the Initialize function by pressing SHIFT+F8 before ALT+T, or
 change the macro as follows:

    time:=Initialize Curtime
    time:ALT+T

 Now, pressing ALT+T inserts the current system time at the cursor.

 This function is documented on Pages 30 and 96 of the "Microsoft
 Editor User's Guide," which is contained in the "CodeView and
 Utilities, Microsoft Editor, Mixed-Language Programming Guide" manual
 from the Microsoft C Optimizing Compiler Version 5.10.


 128. QUICK.INI Needs Modification for Use with M 1.02 or MEP 1.02

 Product Version(s): 1.02   | 1.02
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified: 28-JUL-1989    ArticleIdent: Q46802

 To use the QUICK.INI file provided with the Microsoft M Editor Version
 1.02 as the TOOLS.INI file, it is necessary to make two modifications
 to the file. Without the modifications the editor gives the following
 error messages:

    Argcompile is not an editor function               press any key...
    Help is not an editor function                     press any key...

 To get past the Argcompile error message, add the following line to
 the TOOLS.INI file before the Argcompile:F5 line:

    Argcompile:=arg compile

 The Argcompile macro is also defined in the TOOLS.PRE file provided
 with the editor. The Help:F1 line is a leftover from previous versions
 of the editor and is not implemented in this version. To eliminate the
 Help error message, either delete or comment out the Help:F1 line.


 129. Documentation Error for "Mark" Functions in M User's Guide

 Product Version(s): 1.02   | 1.02
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER | docerr
 Last Modified:  2-AUG-1989    ArticleIdent: Q47236

 On Page 179 of the Version 1.02 "Microsoft Editor for MS OS/2 and
 MS-DOS Operating Systems: User's Guide," there is a documentation
 error. In the section of the reference table describing the "Mark"
 function, the marker deletion and marker definition descriptions are
 reversed. To define a marker at the cursor position, the correct
 syntax is Arg Arg textarg Mark. To delete a marker definition, the
 syntax is Arg Arg textarg Meta Mark. The entries SHOULD appear as
 follows:

    Entry                         Function
    -----                         --------

    Arg Arg textarg Mark          Defines a file marker at the
                                  initial cursor position. This
                                  does not record the file marker
                                  in the file specified by the
                                  markfile switch, but allows you
                                  to refer to this position as
                                  textarg.

    Arg Arg textarg Meta Mark     Deletes a marker definition.

 On Page 39, the reference to Arg Arg textarg Mark is correct.


 130. CopyBox Function Doesn't Work Across Files

 Product Version(s): 1.00   | 1.00
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER | S_C S_Pascal H_Fortran H_MASM
 Last Modified: 26-SEP-1989    ArticleIdent: Q47765

 CopyBox is a C-extension function for the Microsoft editor that is
 designed to copy square regions of text from one location to another,
 including to another file.

 This function works properly when copying to the same file, but fails
 when copying to another file. The function appears to work
 successfully, but the copied text does not appear in the target file.
 This lack of functionality has been corrected in Version 1.02 of the
 editor.

 You can work around this problem by using the GetLine and PutLine
 functions. A line can be read from the source file, trimmed to get the
 proper portion of the line, and then written to the target file. This
 procedure must be followed for each line of the box to copy.


 131. Getting SYS2070 While Using MEP

 Product Version(s): 1.02
 Operating System:   OS/2
 Flags: ENDUSER | MEP
 Last Modified: 26-SEP-1989    ArticleIdent: Q47767

 Problem:

 When I start MEP, I receive the following error:

      |---------------------------------------------------------------|
      | SYS2070: The system could not demand load the                 |
      | application's segment. MSHELP HELPGETINFO is in error.        |
      | For additional detailed information also see message SYS0127. |
      |---------------------------------------------------------------|
      |                     End the program                           |
      |_______________________________________________________________|

 After selecting "End the program," I receive the following message:

    A non-recoverable error occurred.
    The process ended.

 Response:

 The MEP program is picking up an old version of MSHELP.DLL. The likely
 source is from the OS/2 Presentation Manager Toolkit. To correct this
 problem, replace the old MSHELP.DLL with the current MSHELP.DLL.

 If there is no MSHELP.DLL on the LIB path, then MEP loads and seems to
 function correctly, but there will be no help available.


 132. Possible Explanation for "Cannot Close This Window" Error

 Product Version(s): 1.00   | 1.00
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified: 26-SEP-1989    ArticleIdent: Q47770

 Problem:

 Under M Version 1.00 I have two horizontal windows open, each viewing
 separate files. When I attempt to close a window (META+WINDOW or F9+F6),
 I sometimes get the error message "Cannot close this window." Under
 seemingly similar conditions, this error message does not occur and
 the window closes properly.

 Response:

 This message occurs when you attempt to close a window that contains
 modified text. If you want to abandon edits on the file, you can
 reread the file using SHIFT+F7 and then successfully close the window.


 133. ECH.EXE Utility Is Used Internally by the Microsoft Editor

 Product Version(s): 1.00   | 1.00
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified: 26-SEP-1989    ArticleIdent: Q47772

 ECH.EXE is a character echoing utility that is included with the
 Microsoft Editor (M) Version 1.00. This utility is mentioned in the
 appendix of the editor's user guide simply because it is an external
 file.

 The file is used with the Setfile command using wildcards. When
 issuing the command "Arg *.* Setfile", M will use ECH.EXE to display
 the files in alphabetical order. If ECH.EXE is not found in the
 current path, the message "NO MATCHING FILES" is generated.

 If this error message occurs in a subdirectory that does contain
 files, then ECH.EXE is not being found.

 M 1.02 does not use this external file. The utility has been
 incorporated into the editor.


 134. Invoking M or MEP with the /D Switch Prevents Initialization

 Product Version(s): 1.00 1.02 | 1.00 1.02
 Operating System:   MS-DOS    | OS/2
 Flags: ENDUSER | reinitialize
 Last Modified: 26-SEP-1989    ArticleIdent: Q48687

 Invoking the Microsoft M editor with the /D switch to prevent it from
 initializing from the TOOLS.INI file also prevents the Initialization
 function (SHIFT+F8) from reading the TOOLS.INI file.

 There is currently no workaround for this designed limitation other
 than to exit the editor and re-invoke M without using the /D switch.


 135. Microsoft Editor (M) Version 1.02: On-Line Help Not Loaded

 Product Version(s): 1.02
 Operating System:   MS-DOS
 Flags: ENDUSER |
 Last Modified: 26-SEP-1989    ArticleIdent: Q48130

 Trying to access on-line help after initializing (reloading the editor
 settings from TOOLS.INI) generates the following message:

    Online Help Not Loaded

 The following steps will demonstrate the problem:

 1. M (Start the editor, with or without a file.)

 2. F1 (Request on-line help -- success.)

 3. SHIFT+F8 (Initialize editor settings.)

 4. F1 (Request on-line help -- receive error message.)

 Microsoft is researching this problem and will post new information
 as it becomes available.


 136. Invalid Arg Filename Followed By F2 Causes Screen Error

 Product Version(s): 1.00   | 1.00
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER | buglist1.00
 Last Modified: 26-SEP-1989    ArticleIdent: Q48871

 When trying to read in a file with the Arg Setfile function, an
 improper filename returns an operating system error. If the Microsoft
 editor (M) is in split-screen mode, any horizontal divider bars are
 lost in MEP. The error contains the two following lines, which cause
 the screen to scroll one position erroneously:

    Next filSYS1041: The name specified is not recognized as an
    internal or external command, operable program, or batch file.

 In M, screen integrity is preserved, but the following error is
 returned:

    Bad command or filename.

 For example, invoke arg (ALT+A) to start an argument and enter about
 20 or so shifted numbers (e.g. ^&%$&^%$^%$#^%$#^%$@%(^&*(*^&&*), and
 then invoke Setfile (F2).

 The screen becomes corrupted and the next keystroke may crash the
 editor with an integer divide by 0 (zero).

 Microsoft has confirmed this to be a problem with the Microsoft Editor
 Version 1.00. We are researching this problem and will post new
 information as it becomes available.


 137. How to Search and Replace Control Characters with M Editor

 Product Version(s): 1.00 1.01 1.02 | 1.00 1.01 1.02
 Operating System:   MS-DOS         | OS/2
 Flags: ENDUSER |
 Last Modified: 10-OCT-1989    ArticleIdent: Q49010

 To search for and replace control characters with the M editor, use
 the following procedure:

 1. Invoke the search and replace function (CTRL+\).

    The editor prompts with "Query Search String:".

 2. Invoke the quote function (CTRL+P).

 3. Type the control character and press ENTER.

    The editor prompts with "Replace string:".

 4. Invoke the quote function.

 5. Type the control character.


 138. Background Color Greater Than Seven Causes Region to Blink

 Product Version(s): 1.00 1.02 | 1.00 1.02
 Operating System:   MS-DOS    | OS/2
 Flags: ENDUSER |
 Last Modified: 26-FEB-1990    ArticleIdent: Q57585

 It is possible to configure both the background and foreground color
 of the various text items that the Microsoft Editor (M) displays. If
 you attempt to set the background color to a color greater than seven,
 the color region blinks. This behavior, however unusual, is expected,
 and is documented in the "Microsoft Editor for MS OS/2 and MS-DOS
 User's Guide" on Page 87.

 The following M Editor color switches control the colors of various
 text display regions:

    Switch        Controls
    ------        --------

    hgcolor       Background and text color
    hgcolor       Search highlight colors
    infocolor     Information message colors
    selcolor      Cursor highlight colors
    stacolor      Status line colors
    wdcolor       Window border colors

 The following are the colors these switches can be set to:

    Black                 0
    Blue                  1
    Green                 2
    Cyan                  3
    Red                   4
    Magenta               5
    Brown                 6
    Light Gray            7
    Dark Gray             8   Will blink when set to background
    Light Blue            9   Will blink when set to background
    Light Green           A   Will blink when set to background
    Light Cyan            B   Will blink when set to background
    Light Red             C   Will blink when set to background
    Light Magenta         D   Will blink when set to background
    Light Yellow          E   Will blink when set to background
    White                 F   Will blink when set to background

 These colors are set in your TOOLS.INI as follows:

                +------------------- Background Color
                |
                v

    colorswitch:BF <---------------- Foreground Color

 The following example, inserted in your TOOLS.INI, sets the foreground
 and background colors of the editing windows (90 percent of the
 screen):

    fgcolor:62 < ------------------- Green

            ^
            |
            +----------------------- Brown


 139. M Editor Version 1.00 Does Not Clear Compiler Error Buffer

 Product Version(s): 1.00   | 1.00
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER  | buglist1.00 fixlist1.02
 Last Modified: 11-OCT-1989    ArticleIdent: Q49536

 When using the compile function from within the editor, the errors
 stored in memory are not cleared. Thus, if you do not go through all
 errors with the nextmsg function, the errors remain even if another
 compile is done. Therefore, if the second compile process does not
 produce any errors, the errors from the previous compile show up and
 put the cursor on an unpredictable line.

 To work around this problem, make sure you look at all of your error
 messages from each compile.

 Microsoft has confirmed this to be a problem with the Microsoft Editor
 Version 1.00. This problem was corrected in Version 1.02 of the
 Editor.


 140. Configuring On-Line Help for M 1.02

 Product Version(s): 1.02   | 1.02
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified: 30-NOV-1989    ArticleIdent: Q49576

 The following is the correct way to configure on-line help for the
 Microsoft Editor (M) Version 1.02 for both MS-DOS (real mode) and
 OS/2 (protected mode).

 Copy files from the distribution disk, as follows:

 1. Under MS-DOS real mode, copy M.HLP and MHELP.MXT to any directory
    specified in the PATH environment variable in the AUTOEXEC.BAT
    file.

 2. Under OS/2 protected mode, copy M.HLP and MHELP.PXT to any
    directory specified in the PATH environment variable in the
    STARTUP.CMD file. Also copy MSHELP.DLL to any directory listed in
    the LIBPATH variable in the CONFIG.SYS file.

 3. For both DOS and OS/2, perform both the preceding steps.

 Other Microsoft products include .HLP files that the editor can
 read. If you want to add additional .HLP files to help, you must
 include the following tagged section in your TOOLS.INI:

 1. Include the following tagged section:

       [M-MHELP]                    ; For DOS real mode

       [MEP-MHELP]                  ; For OS/2 protected mode

       [M-MHELP MEP-MHELP]          ; For both DOS and OS/2

 2. Add the following switch to load in the help files:

       Helpfiles: M.HLP .BAS:C:\QB\QB.HLP .C.H:C:\QC\QC.HLP .PAS:C:\QP\QP.HLP

    This is an example of help files that are loaded upon startup of M
    or MEP. Help searches QB.HLP first when the file has a .BAS
    extension, QC.HLP when the current file has a .C or .H extension,
    and QP.HLP when the current file has a .PAS extension. Please note
    that these help files come with their respective language, not M
    1.02.

 For more information on this topic, refer to the Microsoft Editor for
 MS OS/2 and MS-DOS Operating Systems: User's Guide" that accompanies
 with M 1.02.


 141. Undocumented Switch "Sethelp" for M Version 1.02

 Product Version(s): 1.02   | 1.02
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER | docerr
 Last Modified: 24-JAN-1991    ArticleIdent: Q50012

 If you have the M (or MEP) Editor version 1.02 configured for online
 help, you can use the undocumented "Sethelp" switch to load additional
 help files within the editor by using the following syntax:

    Arg textarg Sethelp      ;ALT+A textarg ALT+S

 Textarg corresponds to the full pathname of the .HLP file you want to
 load. By default, the sethelp function is mapped ALT+S.

 For example, load the QC.HLP help file that comes with QuickC with the
 following command:

    ALT+A D:\QC\QC.HLP ALT+S

 Now you could place the cursor on printf (or any other C language item
 that is in the Help file) and press F1 to get help on that topic.


 142. Printing Double Quotation Marks from within an M Editor Macro

 Product Version(s): 1.00 1.02 | 1.00 1.02
 Operating System:   MS-DOS    | OS/2
 Flags: ENDUSER |
 Last Modified: 30-NOV-1989    ArticleIdent: Q50223

 To get double quotation marks ("") printed from within a macro in the
 M Editor, use the backslash key (\) followed by the double quotation
 marks (""). The following example (placed in the correct section of
 the TOOLS.INI file) demonstrates how this is done:

    text:=arg "say \"hello\"" paste
    text:alt+z

 In this case, pressing ALT+Z inserts the following string into your
 text, with the double quotation marks around the word hello.

    say "hello"


 143. Controlling the Use of Tabs in the Microsoft Editor

 Product Version(s): 1.00 1.02 | 1.00 1.02
 Operating System:   MS-DOS    | OS/2
 Flags: ENDUSER |
 Last Modified: 30-NOV-1989    ArticleIdent: Q50588

 The Microsoft Editor (M) provides the following two ways of using tab
 characters:

 1. Treat tabs as real characters.

 2. Convert each tab into a series of spaces. This is controlled
 through the use of the "realtabs" switch. Other switches may also
 effect the way tabs appear to be handled by the editor.

 The following chart, taken from Section 7.2.6 of "Microsoft Editor for
 MS OS/2 and MS-DOS User's Guide" describes the switches dealing with
 tabs.

 1. realtabs

    On by default, controls whether or not tabs are treated as real tab
    characters.

 2. entab

    Controls the extent to which the editor converts a series of tabs
    and spaces to tabs when saving a file. The following are the valid
    choices:

       0 - The editor does not replace spaces by tabs. If realtabs is off,
           tabs are converted to spaces.

       1 - (default) The editor can replace a series of tabs and spaces by
           tabs when the tabs fall outside of quoted strings.

       2 - The editor will replace all series of tabs and spaces with
           tabs.

    Note: The entab switch only effects the lines you modify during the
    current editing session.

 3. filetab

    Controls the meaning of tab characters on a disk file. If realtabs
    is on, the filetab switch determines tab alignment. If realtabs is
    off, the filetab switch determines how the editor translates tab
    characters to spaces when a line of text is modified.

    If entab, as described above, is set to 1 or 2, filetab also
    determines how the editor translates spaces to tabs when you save
    the file to disk.

    Note: The filetab switch only effects the lines you modify during
    the current editing session.

 4. tabalign

    When off (the default), the cursor may be placed anywhere inside a
    column of a tab character. If turned on, along with realtabs, the
    cursor is placed to the first column position of tab characters.

 5. tabstops

    Determines the size of columns associated with the TAB and BACKTAB
    ( SHIFT+TAB) keys. This only moves the cursor and has no effect on
    the actual tab character. The default value is 4.

    The following example sets up tabs so that they act the same way
    they do in other editors, such as QuickC or Word:

       realtabs:yes
       tabalign:yes
       graphic:tab
       trailspace:yes
       filetab:4

 The trailspace switch is needed to use tabs on blank lines. The
 tabdisp switch may also be used with realtabs to make the tab
 characters visible on the screen.


 144. Mhelp Function Is Always Assigned to SHIFT+F1

 Product Version(s): 1.02   | 1.02
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified: 17-JUL-1990    ArticleIdent: Q50642

 In the Microsoft Editor (M) Version 1.02, the mhelp function is like
 any other function that can be assigned to any key. However, mhelp is
 always assigned to SHIFT+F1 unless this key is unassigned using the
 unassigned keyword in the m-mhelp block of the TOOLS.INI file.

 It is perfectly acceptable to assign the mhelp to any key, and it will
 work properly with that keystroke. However, in addition to the newly
 assigned key, the mhelp function is always assigned to SHIFT+F1. This
 assignment can be taken out by placing the following line in the
 [M-MHELP] section of the TOOLS.INI file:

    [M-MHELP]
    unassigned:shift+f1


 145. Adding helpwindow in TOOLS.INI as a Switch

 Product Version(s): 1.02   | 1.02
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified: 30-NOV-1989    ArticleIdent: Q50644

 To get the Microsoft Editor (M) to recognize helpwindow as a switch in
 the TOOLS.INI file, the switch must be under the [M-MHELP] or
 [MEP-MHELP] tag section. The example below shows what a TOOLS.INI file
 might look like:

    [M-MHELP MEP-MHELP]
    nohelpwindow:

    [M MEP]
      .
      .

 The helpwindow switch can also be set in the environment by typing the
 following:

    <arg> nohelpwindow: <assign>


 146. Searching in the M Editor with Regular Expressions

 Product Version(s): 1.00 1.02 | 1.00 1.02
 Operating System:   MS-DOS    | OS/2
 Flags: ENDUSER |
 Last Modified: 30-NOV-1989    ArticleIdent: Q51324

 Question:

 When using the M Editor, every time I execute a search command using a
 Regular Expression, the editor takes the command literally and doesn't
 recognize the textarg as a Regular Expression. How can I get this
 search to work?

 Response:

 The correct method is as follows:

       arg arg textarg <search_function>

               arg -> ALT+A
           textarg -> A Regular Expression (i.e., ^S[te].*end)
 <search_function> -> Psearch, Msearch, Replace, Qreplace

 For more information, see Chapter 5, Pages 51-63, in the "Microsoft
 FORTRAN Microsoft Editor User's Guide."


 147. mgreplist Incorrectly Documented As megreplist in Example

 Product Version(s): 1.02
 Operating System:   MS-DOS
 Flags: ENDUSER | docerr
 Last Modified: 15-MAR-1990    ArticleIdent: Q51622

 The examples given on Pages 180 and 181 of the FORTRAN "Microsoft
 Editor User's Guide" incorrectly identifies the megreplist command as
 mgreplist. The documentation shows the following:

    megreplist:="DATA.FIL *.FOR $INCLUDE:*.H"

 This should be the following:

    mgreplist:="DATA.FIL *.FOR $INCLUDE:*.H"

 The megreplist macro does not exist and should be changed to
 mgreplist.

 The example above sets mgreplist to a series of files to be searched
 when Mgrep is called. If the textarg string (specified as an argument
 to Mgrep) is found in any of these files, the instance will be
 reported in the pseudo file <compile>. All succeeding calls to Mgrep
 will reset this file.

 The following are the files that are searched in the above example:

 1. DATA.FIL.

 2. Any file in the current directory with a .FOR extension.

 3. Any file along the INCLUDE environment variable path with a .H
    extension.


 148. C Extensions: Link Errors on __acrtused and _main Explained

 Product Version(s): 1.00    | 1.02
 Operating System:   MS-DOS  | OS/2
 Flags: ENDUSER |
 Last Modified: 21-DEC-1989    ArticleIdent: Q51636
 Question :

 I am writing a C extension for the Microsoft Editor (M). When I link,
 I get the following error message:

    c:\usr\lib\CLIBCE.LIB(dos\crt0.asm)
            error  L2044:  __acrtused
            symbol multiply defined, use /NOE  pos
            1CC Record type: 53E4

    LINK : error L2029: Unresolved externals:
    _main in file(s):  c:\usr\lib\CLIBCE.LIB(dos\crt0.asm)
    Two errors were detected.

 I am compiling and linking as follows:

    cl /c /Gs /Asfu c_extension.c
    link /NOI /NOE exthdr.obj c_extension.obj, c_extension;

 These options seem to be correct according to the Editor manuals. Why
 am I getting these linker errors?

 Response:

 The linker gives these error messages if you are linking with a
 run-time function that must be initialized from the C start-up source
 code. This start-up source code is not used within a C extension.

 The art of writing C extensions for M Version 1.00 is documented in
 Chapter 8 of the Editor section of the "CodeView and Utilities,
 Microsoft Editor, Mixed-Language Programming Guide," which is included
 with C 5.00, C 5.10, Pascal 4.00, FORTRAN 4.10, and MASM 5.10.
 References to M Version 1.02 extensions are discussed in Chapter 8 of
 the "Microsoft Editor User's Guide," which came with FORTRAN 5.00.

 Please contact Microsoft Product Support Services at [phone] to
 obtain an application note that discusses further techniques of writing C
 extensions for the Microsoft Editor.


 149. U1013 Link: Error 2: Not Enough Memory for Exec in M

 Product Version(s): 1.00 1.02
 Operating System:   MS-DOS
 Flags: ENDUSER | s_nmake s_make
 Last Modified: 23-JAN-1991    ArticleIdent: Q57653

 Question:

 In DOS, I am spawning either MAKE or NMAKE within the Microsoft Editor
 (M), and I receive an error message from the Editor on the status line
 saying "U1013 : Link file.obj: Error 2." What does this error mean and
 how do I get around it?

 Response:

 The U1013 error means that one of the procedures called by MAKE or
 NMAKE returned a nonzero error code. In this case, the error can be
 understood as M's equivalent of a "Not enough memory for exec" error,
 meaning that there is not enough memory for the parent process to
 execute a child process. The error typically occurs when you spawn
 either MAKE or NMAKE from within the Editor, the compilation is
 complete, and the link process is beginning.

 If you receive this error, you may be able to free up memory by
 removing any TSRs and unnecessary device drivers. However, the best
 workaround would be to use MAKE or NMAKE to link your file outside of
 M, because M will have problems exec'ing the linker in any sizable
 application due to the size of LINK and MAKE.


 150. Mgrep Can Skip Occurrences of Pattern When Using Mgreplist

 Product Version(s): 1.02   | 1.02
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER | buglist1.02
 Last Modified: 16-JAN-1990    ArticleIdent: Q57705

 "Mgrep" may find every other occurrence of a search string when used
 to search a list of input files defined my the "mgreplist" macro.

 Mgrep searches all files defined by the mgreplist macro, then writes
 the location of a match to the <compile> pseudo file. When using
 either regular expression search patterns or standard search strings,
 mgrep may post every other occurrence of the matched string to the
 <compile> pseudo file. This also causes SHIFT+F3 to display every
 other match in the file being searched.

 To see the problem, set the mgreplist:="test.dat" where TEST.DAT
 contains the following:

    #include1
    #include2
    #include3
    #include4
    #include5
    #include6
    #include7
    #include8
    #include9
    #include10
    #include11
    #include12

 Invoke the mgrep search on the string "include" and then press
 SHIFT+F3 to view the next match. You will see that only every other
 occurrence of "include" is found. Also, if you view the <compile>
 pseudo file it will only contain a list every other occurrence of
 "include".


 151. M "Keyboard" Switch Doesn't Work As Documented

 Product Version(s): 1.02
 Operating System:   MS-DOS
 Flags: ENDUSER | S_FORTRAN buglist1.02
 Last Modified: 20-JAN-1990    ArticleIdent: Q57750

 The Microsoft Editor (M) Version 1.02 "keyboard" switch, documented on
 Page 198 of the the "Microsoft Editor User's Guide for MS OS/2 and
 MS-DOS Operating Systems," does not work as documented.

 The switch was implemented to allow control of which BIOS keyboard
 calls are used to get keystrokes. The "compatible" setting uses the
 standard INT 16H, AH = 0 to get keystrokes. The "enhanced" setting
 uses INT 10H, allowing the F11 and F12 keys to be read, and allowing
 you to use old versions of packages that may fail when your keyboard
 is treated as enhanced.

 If you set the "keyboard" option in your TOOLS.INI file by adding a
 line reading

    keyboard:"compatible"

 and then bring up the editor, M accepts the setting, but fails to set
 correctly. If you press SHIFT+F1 for help and choose Current
 Assignments, the list of current key assignments is given. The
 keyboard switch will now be set to the following:

    keyboard::enhanced

 Note the double colon, and that the compatible option has been
 changed to enhanced.

 If you try to set the option within the editor by entering the
 following, the editor returns the same options as above:

    ALT+A keyboard:compatible ALT+=

 Microsoft has confirmed this to be a problem in the Microsoft Editor
 Version 1.02. We are researching this problem and will post new
 information here as it becomes available.


 152. Incorrect Message from "searchall" with Regular Expressions

 Product Version(s): 1.02   | 1.02
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER | M MEP buglist1.02
 Last Modified: 23-JAN-1990    ArticleIdent: Q57932

 The Microsoft Editor searchall function (that is, SHIFT+F6) may return
 the following invalid error message when using regular expressions:

    +'pattern' not found

 'pattern' is the actual regular expression for which the search was
 requested.

 In this situation, searchall still finds all occurrences of the search
 pattern correctly -- only the message is incorrect.


 153. Version 1.02 of M and MEP Incorrectly Reports Version As 1.2

 Product Version(s): 1.02   | 1.02
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER | docerr
 Last Modified: 26-FEB-1990    ArticleIdent: Q58687

 If you access help for the Microsoft Editor (M/MEP) Version 1.02, the
 version is incorrectly displayed as 1.2, rather than 1.02. This
 incorrect version number appears in both the internal online help and
 when invoking help from the command line with the /? switch.

 The following information is incorrectly displayed when using the /?
 command-line switch for help:

    Microsoft (R) Editor Version 1.2
    Copyright (C) Microsoft Corp 1987-1989. All rights reserved
    Usage: [/D] [/e cmd-string] [/m mark] [/r] [[/t] filename]*


 154. Quote Function (CTRL+P) Can Fail to Work Properly

 Product Version(s): 1.00 1.02 | 1.00 1.02
 Operating System:   MS-DOS    | OS/2
 Flags: ENDUSER | buglist1.00 buglist1.02
 Last Modified: 26-FEB-1990    ArticleIdent: Q58720

 The Quote function (CTRL+P) in conjunction with CTRL+I or CTRL+T fails
 to display the valid character associated with that key sequence. For
 CTRL+P with CTRL+I, a space character (Hex 20) results instead of the
 correct foreground color rectangle with a background color dot (hex
 09). For CTRL+P with CTRL+T, a lowercase "a" with an accent mark (hex
 A0) results instead of the paragraph sign (hex 14).

 The Quote function reads one keystroke from the keyboard and treats it
 literally. This is useful for inserting text into a file that happens
 to be assigned to an editor function. For example, the key sequence
 Quote (CTRL+P) CTRL+A displays a happy face character.

 For the Quote CTRL+I sequence, the only workaround is to use a Quote
 TAB key sequence. This puts the correct hex value in that position
 (09H), but the correct character is not displayed and the tab is
 treated as a tab by the M Editor.

 For the Quote CTRL+T sequence, there is no workaround.

 Microsoft has confirmed this to be a problem with the M Editor Versions
 1.00 and 1.02. We are researching this problem and will post new
 information here as it becomes available.



 155. Replacing Normal String Takes Longer Than Regular Expression

 Product Version(s): 1.00 1.02 | 1.00 1.02
 Operating System:   MS-DOS    | OS/2
 Flags: ENDUSER | buglist1.00 buglist1.02
 Last Modified: 15-MAR-1990    ArticleIdent: Q59085

 Replacing a regular expression takes less time than replacing a normal
 string in the Microsoft M Editor, Versions 1.00 and 1.02. To
 demonstrate the time difference, perform test replacements in the
 following manner:

 1. Load the M Editor with a large file -- greater than 5000 lines.

 2. Perform and time a replacement on a regular expression, one that
    fails to match in the file, for example:

       arg arg CTRL+L     zzzz   <- search for this regular expression
                          zzzz   <- replace with this regular expression

 3. Perform and time a replacement on a normal string (one that fails
    to match in the file), for example:

       arg CTRL+L     zzzz   <- search for this string
                      zzzz   <- replace with this string

 The string replacement may take twice as long as the
 regular-expression replacement. To obtain the higher replace speed,
 use the regular-expression replacement (arg arg CTRL+L) even when you
 are not fully using the regular-expression syntax.

 Note that a psearch on a regular expression psearch is NOT quicker
 than a psearch on a normal string.

 Microsoft has confirmed this to be a problem in Versions 1.00 and
 1.02. We are researching this problem and will post new information
 here as it becomes available.

 For details on regular expression, refer to the "Microsoft Editor
 User's Guide," Chapter 5, "Regular Expressions."


 156. Incorrect Version Numbers Cause Tagged Sections to Be Ignored

 Product Version(s): 1.00 1.02 | 1.00 1.02
 Operating System:   MS-DOS    | OS/2
 Flags: ENDUSER | pwb
 Last Modified: 25-MAY-1990    ArticleIdent: Q59256

 With the Microsoft Editor (M) or the Programmers WorkBench (PWB), it
 is possible to include information in your TOOLS.INI file that is
 specific to the operating system you are using. For information on how
 to create sections with tags, see the "Microsoft Editor User's Guide,"
 Section 7.5.1. However, you must be sure to include a trailing 0
 (zero) on the label for OS/2 versions 1.10 or 1.20. Failure to do so
 causes these sections to be ignored by the Editor.

 The following headers cause the tagged sections to be ignored when
 running under OS/2 version 1.10:

    [M-10.0 M-10.1]
    fgcolor:0B
    hgcolor:30
    stacolor:0E

    [M-3.30 M-10.0R M-10.1R]
    fgcolor:0E
    hgcolor:E0
    stacolor:0B

 The tags must be rewritten as follows:

    [M-10.0 M-10.10]
    fgcolor:0B
    hgcolor:30
    stacolor:0E

    [M-3.30 M-10.0R M-10.10R]
    fgcolor:0E
    hgcolor:E0
    stacolor:0B

 Furthermore, the tagged sections must not be placed in the middle of
 an [M] or [M MEP] tagged section. They must be placed before or after
 the [M] or [M MEP] sections. Failure to do this causes information
 located below these sections to be ignored in the DOS compatibility
 box.

 Note: For the PWB, the above examples would change to PWB-xxxx instead
 of M-xxx.


 157. Unassigning Help Keystrokes Must Be Done Under

 Product Version(s): 1.02   | 1.02
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified: 13-MAR-1990    ArticleIdent: Q59494

 It is possible with the Microsoft Editor Version 1.02 to disable
 an assigned keystroke so that it invokes no editor function at all.
 The keystroke can then be assigned to any other function or macro. By
 putting the disable information in the M Editor section of the
 TOOLS.INI file, the changes will be in effect whenever the Editor is
 invoked. For further information, see the Version 1.02 edition of
 "Microsoft Editor User's Guide," Section 6.2.3, Page 70.

 To regularly disable a keystroke that has been assigned to any preset
 Editor HELP function, such as F1 or SHIFT+F1, the command must be
 placed under the [M-MHELP MEP-MHELP] tag in TOOLS.INI -- not under the
 [M MEP] tag.

 For example, to disable the keystroke for F1, include the following
 line in your TOOLS.INI file:

    unassigned:F1

 Placing this line under the section tagged [M MEP] rather than the
 [M-MHELP MEP-MHELP] tag causes this command to be ignored. This is
 also applicable to the undocumented "sethelp" function, whose default
 keystroke is ALT+S. You can unassign ALT+S, as well as reassign a
 different keystroke to "sethelp", but it must be done under the
 [M-MHELP MEP-MHELP] tag.


 158. Using RIGHT ARROW on Dialog Line Locks Keyboard or GP Faults

 Product Version(s): 1.02   | 1.02
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER | buglist1.02
 Last Modified: 15-MAY-1990    ArticleIdent: Q59527

 Manipulating text on the dialog line must be handled differently in
 the Microsoft Editor (M) Version 1.00 than in 1.02. If you use an M
 Version 1.00 procedure in M Version 1.02 under DOS, the keyboard will
 lock up and alternating screens of jumbled characters may appear on
 the screen. Under OS/2, you will get a GP fault resulting in the
 termination of MEP by the operating system.

 The problem can be observed by using the following steps from within
 the editor:

 Note: Remember that under DOS your machine will hang!

 1. Press ALT+A to invoke the <arg> function.

 2. Type any character (for example, the letter "d").

 3. Hold down the RIGHT ARROW key. When the text in the dialog line has
    scrolled off the left side of the screen, in M 1.00 the editor will
    issue a beep. In M 1.02, the machine will lock in DOS or GP fault
    in OS/2. This problem occurs even if you omit Step 2, but it is
    more difficult to see the error.

 To retain the same functionality in M 1.02, instead of using the RIGHT
 ARROW key to move the cursor to the right, use the SPACEBAR. Using
 the SPACEBAR rather than the RIGHT ARROW key allows you to take
 advantage of the maximum arg line limit without the error.

 Microsoft has confirmed this to be a problem in Version 1.02. We are
 researching this problem and will post new information here as it
 becomes available.


 159. Reference to "Push" Function Incorrect Editor User's Guide

 Product Version(s): 1.00   | 1.00
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER | docerr
 Last Modified: 17-JUL-1990    ArticleIdent: Q60339

 On Page 61 of the "Microsoft Editor User's Guide" for Microsoft C
 5.10, there is a documentation error. It is stated that the Boolean
 switch Savescreen is "for use with the Push and Exit functions." Since
 there is no "Push" function, this should read "for use with the Shell
 and Exit functions."


 160. Prototype in User's Guide for tglcase() Is Incorrect

 Product Version(s): 1.02    | 1.02
 Operating System:   MS-DOS  | OS/2
 Flags: ENDUSER | docerr
 Last Modified: 15-APR-1990    ArticleIdent: Q60487

 In the sample program for a C extension on Page 126 of the "Microsoft
 Editor User's Guide" for Microsoft FORTRAN 5.00 and Microsoft BASIC
 PDS Version 7.00, the prototype for tglcase() is incorrect.

 The function is prototyped as follows:

    flagType pascal EXPORT tglcase (unsigned int, ARG far *, flagType);

 It should be as follows:

    flagType pascal EXTERNAL tglcase (unsigned int, ARG far *, flagType);

 Note: The word EXTERNAL replaces EXPORT.


 161. Creating a Compile Window Macro for the M Editor Version 1.02

 Product Version(s): 1.02   | 1.02
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified: 27-JUL-1990    ArticleIdent: Q63950

 The macro below creates a "compile window" in either the M or MEP
 Editor version 1.02 when you press ALT+C. Note that a compile window
 is helpful for viewing general compilation errors and errors generated
 from utilities that were invoked.

 The following macro, CompWindow, can be added to the [M] or [MEP]
 tagged section of the TOOLS.INI file to create a compile window:

    CompWindow:= savecur home meta down  \
                 up up up up arg window  \
                 window arg "<compile>" setfile  \
                 window restcur

    CompWindow: alt+c

 The CompWindow macro above creates a compile window by performing the
 following steps:

 1. Use the "savcur" function to save the current position of the
    cursor.

 2. Use the "home" function to place the cursor in the upper-left
    corner of the screen. This function guarantees that the cursor will
    be in a left-most position when the compile window is created.

 3. Use the "meta down" function to move the cursor to the bottom of
    the window without changing the column position.

 4. Use "up up up up arg window" functions to create a horizontal
    window four lines above the bottom of the screen. A larger compile
    window can be created by adding more "up" functions to this line in
    the macro.

 5. Use the 'arg "<compile>" setfile' function to create a
    dynamic-compile log. More information concerning the
    dynamic-compile log can be found on Pages 47-48 of the "Microsoft
    Editor User's Guide."

 6. Finally, the original position of the cursor is restored in the
    original window by using the "window restcur" functions.

 7. The macro is assigned to the ALT+C keystroke, although any unused
    keystroke may be used.

 Error messages will now be displayed in the compile window when
 running a compilation or invoking a utility.


 162. C 6.00 UNDEL.EXE Is Not Compatible with the Microsoft Editor

 Product Version(s): 1.00 1.02 | 1.00 1.02
 Operating System:   MS-DOS    | OS/2
 Flags: ENDUSER |
 Last Modified: 25-JUL-1990    ArticleIdent: Q64024

 If backup copies of files are stored in the \DELETED subdirectory by
 the M Editor, typing "undel" should bring up a listing of backup
 copies. However, if the C 6.00 version of UNDEL.EXE is used, the
 following message will be displayed: "

    0(0) bytes in 0 deleted files.

 The C 5.10 version of UNDEL.EXE will successfully bring up a listing
 of backup copies saved by either the M Editor or the Programmer's
 WorkBench (PWB).

 This problem can be reproduced by setting the text backup switch in
 the M section of the TOOLS.INI file to "undel". After saving various
 copies, backups are added to the \DELETED subdirectory and a listing
 can be brought up by using the C 5.10 UNDEL.EXE. Using the C 6.00
 version of UNDEL.EXE causes the erroneous message listed above to be
 displayed. This incompatibility was caused by adding OS/2 version 1.20
 filename support to UNDEL.EXE and EXP.EXE.

 As a workaround, rename the C 5.10 UNDEL.EXE to UNDEL51.EXE and the C
 6.00 UNDEL.EXE to UNDEL60.EXE.


 163. Invalid Switch and Extensions in Brief Emulation

 Product Version(s): 1.02   | 1.02
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified:  6-FEB-1991    ArticleIdent: Q67762

 The M editor version 1.02 comes with a BRIEF.INI file, which contains
 the key settings for Brief emulation. If you want Brief emulation, you
 must rename this file to "TOOLS.INI". This file will generate the
 following three messages when M loads the TOOLS.INI file during
 initialization:

    mhctx is not an editor switch
    load:$PATH:ulcase - no such file or directory
    load:$PATH:justify - no such file or directory

 The messages are caused by the following three lines:

    Line 223: "mhctx:Alt+H"
    Line 263: "load:$PATH:ulcase"
    Line 369: "load:$PATH:justify"

 Deleting these three lines will not change the performance of the M
 editor, and will eliminate the messages they cause when M is
 initialized.






 Microsoft NMake [Make Utility]
 =============================================================================


 1. NMAKE and the Backslash "\" Character

 Product Version(s): 1.00   | 1.00
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified:  3-MAY-1989    ArticleIdent: Q43064

 The backslash "\" character in NMAKE has two different meanings
 depending on how it is used. One of its uses is as a line-continuation
 character. The other use is as a path specifier.

 The primary use of "\" is as a line continuation-character. For
 example, if you have a dependency line that extends more than one
 line, use the "\" character to continue to the next line. It is
 correct to include a space prior to the "\" or to append it to the
 last dependent, as in the following examples:

 FOO : obj1 obj2 obj3 obj4 obj5 \  (CORRECT)
 obj6 obj7...etc.

 FOO : obj1 obj2 obj3 obj4 obj5\   (CORRECT)
 obj6 obj7...etc.

 The "\" character is also used as a path specifier. When "\" is the
 last character on the line and is meant as a path specifier, you must
 precede it with the caret "^" character to tell NMAKE to override its
 meaning as a line-continuation character.

 The following macro definition is an example demonstrating the use of
 "\" as a path specifier:

 exe_dir = c:\bin^\    (CORRECT)

 exe_dir = c:\bin\     (INCORRECT)

 The following will be interpreted as a line-continuation character.

 exe_dir = c:\bin\     (INCORRECT)

 Preceding the "\" with another "\" will nullify the meaning as a
 line-continuation character. However, when this macro is expanded,
 both backslashes will appear, producing an incorrect path.


 2. NMAKE Is Case Sensitive

 Product Version(s): 1.00
 Operating System:   MS-DOS
 Flags: ENDUSER |
 Last Modified:  3-MAY-1989    ArticleIdent: Q43999

 It is not clearly stated in the manual that NMAKE IS case sensitive.
 Case sensitivity is imposed on the following:

 1. Macros

    For instance, if you define "TEXT" as a macro, you must use $(TEXT)
    to insert it. If $(text) is used, the macro is undefined and
    nothing happens.

 2. Predefined Macros (.SUFFIXES;.PRECIOUS, CC, etc.)

    Predefined macros such as .SUFFIXES must be in all in uppercase
    letters. If you use .suffixes, NMAKE returns the error ".suffixes
    too long: truncated to 8.3".

 3. File extensions

    When adding file extensions to the .SUFFIXES list, you must
    preserve case. For example, to add the file extension .dll to the
    suffix list, you would put the following line in your makefile:

       .SUFFIXES : .dll

    Then, all files with the .dll extension must have the .dll
    extension in lowercase letters.


 3. NMAKE Uses "makefile " Ignoring File Name on Command Line

 Product Version(s): 1.00
 Operating System:   MS-DOS
 Flags: ENDUSER | S_QuickC
 Last Modified: 10-NOV-1989    ArticleIdent: Q44777

 When using NMAKE, you normally put the makefile's name on the command
 line as follows:

    NMAKE test.mak

 Although this works correctly for most cases, if there is a file named
 "makefile." in the current working directory, NMAKE uses that file
 instead of the one specified on the command line.

 To be sure NMAKE uses the makefile specified on the command line, you
 must have a /F switch before the makefile name as follows:

    NMAKE /F test.mak

 This is expected behavior, as documented on Page 156 of the "Microsoft
 QuickC ToolKit" manual for QuickC Version 2.00.


 4. Modifications for an Existing Make File Used with MAKE

 Product Version(s): 1.00   | 1.10
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER | s_quickc  s_c  h_FORTRAN
 Last Modified: 16-JAN-1990    ArticleIdent: Q44130

 Question:

 What modifications need to be made to an existing make file that was
 used with MAKE, and why?

 Response:

 To use NMAKE on make files originally designed for MAKE, the first
 descriptor block (target:dependent) must be a pseudotarget (see QuickC
 Version 2.00 ToolKit, Sections 7.3.5 and 7.5) that lists all of the
 original make targets in the file as the dependent files. The
 following is an example:

    ALL : test.exe test1.exe test2.exe

 The reason you must include a pseudotarget descriptor block as the
 first descriptor block in a make file is that the previous MAKE
 utility tested EACH descriptor block sequentially throughout the file.
 NMAKE, however, tests only the FIRST descriptor block unless targets
 are specifically listed on the NMAKE command line. By using a
 pseudotarget, ALL in the above example, NMAKE must now assume
 that each dependent is out of date and attempt to make it. NMAKE now
 searches the make file for each dependent file listed (test.exe,
 test1.exe, and test2.exe) to see if a descriptor block exists for it.
 This causes NMAKE to behave just like MAKE.

 Example:
 -------

    ALL : test.exe test1.obj

    test1.obj : test1.c
            cl /c test1.c

    test.exe : test.obj test1.obj
            link test test1;

 Without the pseudotarget, NMAKE tests only the first descriptor block
 and ignores any following descriptor block.


 5. How to Specify Paths in Inference Rules in NMAKE

 Product Version(s): 1.00   | 1.10
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER | s_quickc  s_c  h_FORTRAN
 Last Modified: 23-MAR-1990    ArticleIdent: Q44131

 Question:

 How to I specify paths in inference rules?

 Response:

 Note: For a complete description of this feature, see QuickC Version 2.00
 Toolkit, Section 7.3.3. One of the most powerful new features of
 NMAKE is that it allows paths to be specified in an inference rule.

 The syntax of an inference rule without paths is as follows:

    .fromext.toext:

 This syntax is somewhat limited, however, because both the "fromfile"
 and the "tofile" are evaluated as if they existed in the current
 directory. With NMAKE, a path specifier may be added to an inference
 rule by doing the following:

    {frompath}.fromext{topath}.toext:

 Note: If you use a path on one element of the inference rule, you must
 use it on both. For instance, if you want to compare any .c file in
 the current directory with its .obj file in my object directory, the
 inference rule would look like the following:

 {.}.c{c:\objects}.obj:
         cl /c $<;

 Note that the fromext (.c) has to be preceded with a path. In the case
 of the current directory, the ".", or current directory works nicely.

 When NMAKE encounters a descriptor block that has no commands
 following, it will look for an inference rule that matches the
 descriptor block. When checking for matching, NMAKE expects that the
 base name of both the target and the dependents be the same. Also, the
 paths must match exactly. In other words, the following descriptor
 line would not use the inference rule just defined because the paths
 do not match on the .obj file:

    test.obj : test.c

 In this case, the predefined inference rule for .c.obj: would be
 invoked. To invoke the inference rule just defined, the descriptor
 line would be as follows:

    c:\objects\test.obj : test.c


 6. Multiple Targets in NMAKE Do Not Work

 Product Version(s): 2.00
 Operating System:   MS-DOS
 Flags: ENDUSER | buglist2.00 docerr S_QUICKC
 Last Modified:  2-JUN-1989    ArticleIdent: Q44757

 Multiple targets in the QuickC Version 2.00 NMAKE utility do not work
 properly. The example on the top of Page 167 of the "Microsoft QuickC
 Tool Kit" manual shows that each target listed before the dependencies
 should be evaluated; however, only the first target is evaluated, and
 the others are ignored. Make files that are simplified even more
 respond the same way.

 The following make file demonstrates the problem:

     target1.exe target2.exe: depend1.obj depend2.obj
         echo $@

 For the make file to work properly, change the file to the
 following:

     BUILD: target1.exe target2.exe

     target1.exe: depend1.obj depend2.obj
         echo $@

     target2.exe: depend1.obj depend2.obj
         echo $@

 Microsoft has confirmed this to be a problem in QuickC Version 2.00.
 We are researching this problem and will post new information as it
 becomes available.



 7. Modifying a QuickC 2.00 Make File to Run MAKE

 Product Version(s): 1.00   | 1.10
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER | s_quickc  s_c  h_FORTRAN
 Last Modified: 26-MAY-1989    ArticleIdent: Q44133

 Question:

 What modifications must I make to a make file generated by QuickC
 Version 2.00 so that I can run NMAKE on it and use my Microsoft C
 Version 5.10?

 Response:

 Only a few modifications must be made to allow a make file generated
 by QuickC to invoke C Version 5.10. The following three items need to
 be changed:

 1. Change the CC macro from qcl to cl. To do this, locate the
    following line in the make file generated by QuickC and change qcl
    to cl:

       CC=qcl

 2. Take out references to ilink. The ilink references are embedded
    into your make file if you have the ilink option turned on in your
    environment. The following line in the make file

       ilink -a -e "link $(LFLAGS) @$(PROJ).crf" $(PROG)

    must be changed to the following:

       link "$(LFGLAGS) @$(PROJ).crf" $(PROG)

 3. Remove any compiler switches in the make file that cl will not
    recognize. To eliminate this problem, turn off incremental compile
    in the QuickC environment prior to making the make file.


 8. NMAKE Version 1.00 with "!" and User and Predefined Macros

 Product Version(s): 1.00
 Operating System:   MS-DOS
 Flags: ENDUSER | S_QuickC buglist1.00 fixlist1.01
 Last Modified: 30-NOV-1989    ArticleIdent: Q48859

 The following NMAKE file does not produce the correct results when
 using NMAKE Version 1.00, which is supplied with the Microsoft QuickC
 compiler Version 2.00. The file replaces the user-defined macro in the
 second command line with the predefined macro in the first command
 line. The workarounds are as follows:

 1. Remove the "!" at the beginning of the first command line, which
    causes the command to be executed for each dependent file if the
    command uses one of the special macros $? or $**.

 2. Do not use a predefined macro for the first command.

 3. Do not use the predefined macro $**, a complete list of dependent
    files, for the dependent files in the first command line.

 4. Do not use a user-defined macro in the second command line.

 5. Update to the Microsoft QuickAssembler package, which is shipped
    with NMAKE Version 1.01, in which this problem is corrected.

 More information on the NMAKE utility can be found starting on Page
 155 of the "Microsoft QuickC Toolkit" manual. The following is the
 NMAKE file that fails:

 SOURCE=test.c

 test.exe: $(SOURCE)
     !$(CC) $**
     copy $(SOURCE) new

 This produces the following output:

 cl test.c
 copy cl new

 The following is the NMAKE file with the first workaround:

 SOURCE=test.c

 test.exe: $(SOURCE)
     $(CC) $**
     copy $(SOURCE) new

 This produces the following correct output:

 cl test.c
 copy test.c new

 The following is the NMAKE file with the second workaround:

 SOURCE=test.c

 test.exe: $(SOURCE)
     !cl $**
     copy $(SOURCE) new

 This also produces the correct output.

 The following is the NMAKE file with the third workaround:

 SOURCE=test.c

 test.exe: $(SOURCE)
     !$(CC) $(SOURCE)
     copy $(SOURCE) new

 This also produces the correct output.

 The following is the NMAKE file with the fourth workaround:

 SOURCE=test.c

 test.exe: $(SOURCE)
     !$(CC) $(SOURCE)
     copy test.c new
     copy $(SOURCE) new

 This produces the following output:

 cl test.c
 copy test.c new
 copy test.c new


 9. Incrementally Updating Libraries with NMAKE

 Product Version(s): 1.00 1.01 1.10 1.11 1.12 | 1.11 1.12
 Operating System:   MS-DOS                   | OS/2
 Flags: ENDUSER |
 Last Modified: 25-FEB-1991    ArticleIdent: Q48862

 The repetition modifier "!" (without the quotation marks) provided in
 NMAKE allows libraries to be maintained and incrementally updated very
 easily. By using this modifier with the special macro for dependents
 out-of-date with the target (for example, "$?"), the library update
 becomes an automated part of modifying a project.

 The following NMAKE makefile keeps FOO.LIB up-to-date based on the
 four object files listed in the OBJS macro. These object files can be
 based on C or assembly source files. The list of source-file types can
 be extended by adding the appropriate inference rules to the
 description file.

 Sample NMAKE Makefile
 ---------------------

     #
     # List of object files to be kept in library
     #
     OBJS = foo1.obj foo2.obj foo3.obj foo4.obj

     .c.obj:
         cl /c $?

     .asm.obj:
         masm $?;

     foo.lib : $(OBJS)
         !lib foo.lib -+ $?;

 The command for the library dependency line uses a predefined macro
 and a special NMAKE directive. Placing "$?" on the end of the LIB line
 expands to the list of all dependents that are out-of-date with the
 target. This list combined with "!" causes the LIB line to be executed
 once for each member in the list.

 If FOO1.OBJ and FOO3.OBJ are out-of-date with respect to FOO.LIB, "$?"
 evaluates to "FOO1.OBJ FOO3.OBJ". With "!", the following commands are
 executed:

    lib foo.lib -+ foo1.OBJ;
    lib foo.lib -+ foo3.OBJ;


 10. Explanation of Why NMAKE May Not Produce .OBJ and .EXE Files

 Product Version(s): 1.00 1.10 1.11 | 1.00 1.11
 Operating System:   MS-DOS         | OS/2
 Flags: ENDUSER |
 Last Modified: 27-OCT-1989    ArticleIdent: Q49502

 Question:

 When using the NMAKE utility, no warnings occur and the compiler
 appears to execute properly; however, the .OBJ and .EXE files are not
 created.

 If I use the MAKE utility on the same .MAK file, I get the following
 two warnings:

    warning U4000: Target does not exist.

    warning U4001: Dependent does not exist; Target not built.

 The first warning message is a standard warning that I would expect.
 Why is there a second and why aren't the .OBJ and .EXE files created?

 Response:

 Remove unexpected trailing characters from the .MAK file.

 This problem can occur because extra characters occur at the end of a
 line within the .MAK file. Common mistakes such as placing a trailing
 semicolon in the CL compile line or in the dependency line can cause
 this behavior. This applies to any unexpected characters, not just
 semicolons.

 The following example demonstrates the problem:

    file.obj: file.c <ENTER>
       CL /c /Lp file.c;  <-- Semicolon CANNOT be used with the CL command.

    file.exe: file.obj <ENTER>
       LINK file;      <-- OK, Semicolon CAN be used with the LINK command.

 Removing the semicolon at the end of the CL line eliminates the
 problem.


 11. Command Line Too Long in Makefile Can Cause Error: U1082

 Product Version(s): 1.00 1.01 1.10 1.11 1.12 | 1.11 1.12
 Operating System:   MS-DOS                   | OS/2
 Flags: ENDUSER | s_make
 Last Modified: 24-JAN-1991    ArticleIdent: Q49757

 NMAKE and MAKE require that all commands issued after a target
 dependency are less than the DOS command-line limit of 128 characters.
 If the command is too long, you may receive the following error

    U1082:  Not enough memory '...' cannot execute '...'

 where '...' is the command that was attempted. This problem most
 likely occurs with the link command line and can be easily resolved
 with a response file. Response files are documented in the utilities
 manual or the online help supplied with each compiler.


 12. Special Macros Not Recognized in NMAKE Inline Files

 Product Version(s): 1.00 1.01 | 1.00 1.01
 Operating System:   MS-DOS    | OS/2
 Flags: ENDUSER |
 Last Modified: 10-NOV-1989    ArticleIdent: Q50693

 When you use special macros to indicate targets or dependents in
 inline files, NMAKE Version 1.00 will generate the error message
 U4108, "special macro undefined." These special macros are $@, $*,
 $**, and $?.

 To prevent the problem, avoid use of these special macros in inline
 files. Instead of using those << inline files, create the response
 file in a separate NMAKE target, and redirect TYPE and ECHO commands
 to the desired file.

 $@ refers to the full name of the target, base plus extension. $*
 refers only to the base name of the target.

 $** represents the complete list of dependent files for the target. $?
 represents only the dependents that are out of date relative to the
 target.

 The following makefile will generate U4018 for $**:

 #makefile test
 FOO.EXE: *.OBJ
     LINK @<<FOO.LRF
 $**;
 <<

 To avoid the problem, break this up into two steps, the makefile and a
 linker response file with output redirected:

 #makefile test
 FOO.EXE: *.OBJ FOO.LRF
     LINK @FOO.LRF

 FOO.LRF: *.OBJ
     echo $**; >FOO.LRF


 13. Inference Rule May Fail If Blank Command Line Contains Spaces

 Product Version(s): 1.00 1.01 1.10 1.11 1.12 | 1.11 1.12
 Operating System:   MS-DOS                   | OS/2
 Flags: ENDUSER |
 Last Modified: 24-JAN-1991    ArticleIdent: Q50383

 When using inference rules in an NMAKE description file, the target/
 dependency line must be followed by a blank line (no space
 characters); otherwise, the inference rule commands will not be
 executed. NMAKE checks this line for any ASCII characters; if ANY
 characters exist, NMAKE will ignore the inference rule and try to
 execute the line, even if it contains only a space or spaces.

 The following is a simple example, which demonstrates this problem:

 .c.exe:
   cl $**

 ALL : main.exe

 main.exe : main.c
 <space>

 Nothing happens if this description file is passed to NMAKE because
 the space character will cause NMAKE to assume there are explicit
 commands following the target/dependency line, causing it to ignore
 the inference rule. Note that this is expected behavior for NMAKE.

 MAKE version 4.x inference rules/description blocks do not exhibit
 this behavior. This is something to keep in mind when converting
 description files from MAKE to NMAKE.


 14. Using "." for Path in Inference Rules Causes U1073

 Product Version(s): 1.00 1.01 | 1.01
 Operating System:   MS-DOS    | OS/2
 Flags: ENDUSER | buglist1.01
 Last Modified: 18-DEC-1989    ArticleIdent: Q51723

 NMAKE does not accept a dot (.) to identify the current directory in
 inference rule paths. When specifying paths for each of the
 extensions, using the following form

    {frompath}.fromextension{topath}.toextension

 and using "{.}" (without the quotation marks) to indicate the current
 directory for the "topath", causes the following error:

    NMAKE : fatal error U1073: don't know how to make 'filename.ext'

 To work around this, the current directory for topath must be
 specified with "{}". However, both notations are acceptable when
 specifying the "frompath".

 The following makefile causes the error:

 .SUFFIXES: .h .c .obj .exe

 #macros
 a=tools.h
 jbo=grdemo.obj turtle.obj menu.obj
 cc=qcl -c

 #inference rules
 {d:\qc2\work}.c{.}.obj:          #*** the '{.}' must be '{}' ***
  $(cc) $<

 {}.obj{d:\qc2\lib}.exe:
  link $(**R),,, graphics.lib;

 #target-dependencies
 run: d:\qc2\lib\grdemo.exe

 d:\qc2\lib\*.obj: d:\qc2\work\*.c

 d:\qc2\lib\grdemo.exe: $(jbo)


 15. Redirecting NMAKE 1.00/1.01 Output with -p Gives False Errors

 Product Version(s): 1.00 1.01
 Operating System:   MS-DOS
 Flags: ENDUSER | buglist1.00 buglist1.01 fixlist 1.11
 Last Modified: 24-JAN-1991    ArticleIdent: Q57500

 Redirecting the output of NMAKE version 1.00 or 1.01 can cause
 inference rules to fail if all of the following conditions are met:

 1. The inference rules are in uppercase letters.
 2. The -p option is used.
 3. The output is redirected.

 This problem is somewhat obscure, and it can be frustrating if you
 unwittingly meet all of these conditions. The error message displayed
 depends on the inference rule used, but it resembles the following:

    NMAKE : warning U4017: ignoring rule .C.OBJ (extension not in
            .SUFFIXES)

 The above error message is displayed with the following description
 file initiated with the command "NMAKE -p > out.txt":

 Description File
 ----------------

 # start

 .C.OBJ:
   cl $*

 main.obj : main.c

 # end

 Microsoft has confirmed this to be a problem in NMAKE versions 1.00
 and 1.01. This problem was corrected in NMAKE version 1.11.


 16. Missing Right Parenthesis in Sample NMAKE File Hangs Machine

 Product Version(s): 1.00
 Operating System:   MS-DOS
 Flags: ENDUSER | h_fortran s_quickc s_quickasm buglist1.00
 Last Modified: 15-MAR-1990    ArticleIdent: Q59069

 If you forget the right parenthesis in an IF "$(flag)"=="comparison"
 line in a makefile and run the makefile through NMAKE, you can receive
 machine hangs or corrupt COMMAND.COM messages under DOS or an Internal
 Processing Error under OS/2.

 Microsoft has confirmed this to be a problem with Version 1.00. We are
 researching this problem and will post new information here as it
 becomes available.

 The following makefile, simplified from the sample makefile on Page
 172 of the "QuickC ToolKit" manual, demonstrates this problem:

 debug=Y
 CC=qcl
 !CMDSWITCHES +D
 HELLO.EXE : HELLO.OBJ
 !IFDEF debug
 !   IF "$(debug"=="y"
                 LINK /CO hello;
 !   ELSE
                 LINK hello;
 !   ENDIF
 !ELSE
 !   ERROR Macro named debug is not defined.
 !ENDIF

 Adding a right parenthesis after "$(debug solves the problem.

 The error seems to occur because NMAKE does not recognize the end of
 the line and continues to parse the line until the end of the file. A
 customer has reported receiving "U1076, Line too long" messages,
 followed by a DOS level error reading "Invalid COMMAND.COM - system
 halted."

 Testing the same problem under an OS/2 1.20 DOS Box returned Internal
 Processing Errors and halted the system with no other error messages.


 17. NMAKE 1.01 Does Not Properly Expand Wildcard Arguments

 Product Version(s): 1.01   | 1.01
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified: 15-MAY-1990    ArticleIdent: Q59254

 NMAKE version 1.01 doesn't properly expand wildcard command-line arguments.
 For example, if we were to have a makefile that looked similar to the
 following

 a.exe : a.c
     echo cl a.c

 b.exe : b.c
     echo cl b.c

 And we were to say:

 NMAKE *.exe /A

 NMAKE wouldn't properly expand "*.exe" to equate to both a.exe and
 b.exe; it would merely build only the first target in the list.

 NMAKE versions 1.00 and 1.10 do not exhibit this behavior.


 18. NMAKE /D /C Switches Suppress Modification Date

 Product Version(s): 1.00 1.01 1.10 1.11
 Operating System:   MS-DOS
 Flags: ENDUSER | buglist1.00 buglist1.01 buglist1.10 buglist1.11
 Last Modified: 18-NOV-1990    ArticleIdent: Q59384

 When using the NMAKE /D and /C switches together, the modification
 date of each file will not be displayed when the date is checked. A
 short description of each switch is described as follows:

    /D  Displays the modification date of each file when the date is
        checked.

    /C  Suppresses the NMAKE copyright message and prevents nonfatal
        error or warning messages from being displayed.

 Microsoft has confirmed this to be a problem with NMAKE Versions 1.00,
 1.01, and 1.10. We are researching this problem and will post new
 information here as it becomes available.


 19. Trouble with Filenames Containing a Dollar Sign ($)

 Product Version(s): 1.01    | 1.01
 Operating System:   MS-DOS  | OS/2
 Flags: ENDUSER | buglist1.01
 Last Modified: 14-MAR-1990    ArticleIdent: Q59409

 If you use a filename that contains a dollar sign ($) in a NMAKE
 description file, you can use the escape character (^) to tell NMAKE
 that the dollar sign is part of your filename, not a macro character.
 However, using the escape character within an inline response file
 does not work and you must use the double dollar sign ($$).

 Consider the following NMAKE description file:

     all:test^$.exe;

     test^$.obj: test^$.c
        cl /c test^$.c

     test^$.exe: test^$.obj
        link @<<
              test^$.obj,
              test^$.exe,
              NUL,;
     <<

 In this file, the escape character (^) is used to tell NMAKE that the
 $ is part of the filename TEST$.* and is not denoting the use of a
 macro. When TEST$.C is compiled, everything works correctly until you
 get to the inline response file for LINK. NMAKE does not interpret the
 ^ character, but instead passes it on to LINK.EXE. LINK then tries to
 link TEST^$.OBJ instead of TEST$.OBJ and fails. If you eliminate the ^
 to pass TEST$.OBJ to link, NMAKE fails with an error about an invalid
 macro.

 NMAKE is in error here. NMAKE should do one of two things when parsing
 the inline response file.

 1. NMAKE should interpret the ^ to leave the $ as part of the filename.

 2. NMAKE should ignore the $ so that you can just list TEST$.OBJ
    because it doesn't make sense to have macros in external response
    files when parsing an inline response file.

 Microsoft has confirmed this to be a problem with NMAKE Version 1.01.
 We are researching this problem and will post new information here as
 it becomes available.

 The following are two suggested workarounds:

 1. Use an external response file. Then your link line would appear
    similar to link @FILE.RES and you could put TEST$.OBJ directly in
    the response file.

 2. Use $$ as the escape sequence instead of ^$ in the inline response
    file. For example, change

       link @<<
           test^$.obj,
           test^$.exe,
           NUL,;
       <<

    to the following

       link @<<
           test$$.obj,
           test$$.exe,
           NUL,;
       <<

    and NMAKE will correctly pass TEST$.OBJ to the linker.


 20. In What Order Does NMAKE Build Files?

 Product Version(s): 1.00   | 1.00
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER |
 Last Modified: 15-MAY-1990    ArticleIdent: Q59420

 Question:

 I need to have my source files built in a particular order but I can't
 get NMAKE to build them that way. NMAKE seems to build the source
 files in the order it wants. What is the order in which NMAKE builds
 files?

 It is definitely possible to specify the order in which NMAKE builds
 your files.

 The first thing NMAKE does is check the command line. You can specify
 the targets in the order you want them built and NMAKE will build them
 in that order. If NMAKE doesn't find any targets on the command line,
 it builds the first target in the description file.

 NMAKE will build all of the dependents in the order in which they are
 specified on the first target line. For most description files, the
 first target in the file is the ALL:FILENAME.EXE pseudotarget. In this
 case, NMAKE will build FILENAME.EXE, and then the order depends on the
 dependency for FILENAME.EXE.

 This can be more clearly explained in the following examples:

 Example 1
 ---------

 Consider the following description file:

             all:three.obj two.obj one.obj main.exe

             one.obj:one.c
                 cl /c one.c

             two.obj:two.c
                 cl /c two.c

             three.obj:three.c
                 cl /c three.c

             main.exe:three.obj one.obj two.obj
                 link one two three, main;

 In this example, the files are compiled in the order: THREE.C, TWO.C,
 ONE.C. After those three files are compiled, the link for MAIN.EXE is
 executed. They are executed in that order because that is the explicit
 order given in the first target in the file and NMAKE builds the first
 target in the file when nothing is specified on the command line.

 Example 2
 ---------

 Now, consider the following description file that has been slightly
 modified from the one shown in Example 1 above:

             all:main.exe

             one.obj:one.c
                 cl /c one.c

             two.obj:two.c
                 cl /c two.c

             three.obj:three.c
                 cl /c three.c

             main.exe:three.obj one.obj two.obj
                 link one two three, main;

 In this example the files are compiled in the order: THREE.C, ONE.C,
 TWO.C. After that, the link statement will then be executed because
 there is nothing specified on the command line, so NMAKE will build
 the first target in the file, which is MAIN.EXE. When NMAKE looks at
 what it needs to build MAIN.EXE, it sees the list of dependents and
 builds them in that order.

 In summary, NMAKE looks first on the command line. If nothing is found
 there, it builds the first target in the description file by building
 each of its dependents in the order specified. If the dependent of the
 first target specifies another target, the dependents of that target
 are built in the order they are specified and so on.


 21. Multiple Dependency Blocks Are Not Cumulative

 Product Version(s): 1.00 1.01 1.10 1.11 | 1.01 1.10 1.11
 Operating System:   MS-DOS              | OS/2
 Flags: ENDUSER |
 Last Modified: 16-OCT-1990    ArticleIdent: Q59526

 Question:

 Specifying a target in multiple dependency blocks seems to confuse
 NMAKE. If my make file says something similar to the following

 FOO.EXE:: FOO1.obj
 FOO.EXE:: FOO2.obj
 FOO.EXE:: FOO3.obj
   link foo.exe

 FOO.EXE:: FOO.RES
   RC FOO.RES FOO.EXE

 and FOO1.OBJ and FOO2.OBJ are newer than FOO.EXE but FOO3.OBJ is not,
 FOO.EXE will not be built. To further confuse the issue, the following
 is the output from running NMAKE with the /d (display file dates)
 option:

 C:\>NMAKE /d foo.mak

   foo.exe                    Wed Mar 07 08:42:38 1990
     foo1.obj                 Thu Mar 08 15:25:44 1990
 ** foo1.obj newer than foo.exe
     foo2.obj                 Wed Mar 08 08:38:56 1990
 ** foo2.obj newer than foo.exe
     foo3.obj                 Thu Mar 01 09:49:52 1990
     foo.res                  Thu Mar 01 09:49:52 1990
 'foo.exe' is up-to-date.

 Obviously, NMAKE realizes the foo1 and foo2 .OBJs are newer, but
 FOO.EXE is never linked. Why not?

 Response:

 The multiple dependency construct, indicated by a double colon (::)
 following the target, is very useful in NMAKE because it allows the
 programmer to specify what operations are to take place on a target
 based on various dependents. For instance, in PM (Presentation
 Manager) programming the MAKE file can indicate that if the .OBJs
 change, execute the linker to rebuild the application. On the other
 hand, if all that changes is the resource file, only the resource
 compiler needs to be executed.

 However, there is a limitation to this feature. The command block for
 a target-dependency group MUST immediately follow it. They are not
 cumulative like normal dependency blocks. Therefore, one workaround to
 the above example is the following:

 FOO.EXE:: FOO1.obj
   link foo.exe

 FOO.EXE:: FOO2.obj
   link foo.exe

 FOO.EXE:: FOO3.obj
   link foo.exe

 FOO.EXE:: FOO.RES
   RC FOO.RES FOO.EXE

 The second alternative is to put all the dependencies on the same
 line as the target, for example:

 FOO.EXE:: FOO1.obj FOO2.obj FOO3.obj
   link foo.exe

 FOO.EXE:: FOO.RES
   RC FOO.RES FOO.EXE


 22. A Complete Example of Utilizing Paths in NMAKE

 Product Version(s): 1.00 1.01 1.11
 Operating System:   MS-DOS
 Flags: ENDUSER |
 Last Modified: 18-APR-1990    ArticleIdent: Q60340

 The make file shown below is an NMAKE example of using paths in
 macros, inference rules, and target dependencies (descriptor blocks).
 This is a working example of what is described on Page 298 of the
 "Microsoft FORTRAN CodeView and Utilities User's Guide" and Page 168
 of the "Microsoft QuickC Tool Kit."

 This make file compares the modification dates of the .H and the .C
 files with the .OBJ files, and the .OBJ files with the .EXE files. If
 any of the dependent files have changed more recently than the target
 files, the specified series of commands is executed. The .H and the
 .C files in the work directory are compared to the .OBJ files of the
 lib directory.

 If any of the source file(s) have changed since the last .OBJ was
 .created, then it is recompiled and copied from the current
 directory to the lib directory. The .OBJ files in the lib directory
 are compared to the .EXE files in the current directory. If any of the
 .OBJ files have changed since the last .EXE was created, then the
 .OBJs are relinked.

 Sample Make File
 ----------------

 #macros

 objdir =d:\qc2\lib
 wrkdir =d:\qc2\work
 list   =$(objdir)\grdemo.obj $(objdir)\turtle.obj \
 $(objdir)\menu.obj
 cc     =qcl -c

 #inference rules

 #compile
 {$(wrkdir)}.c{$(objdir)}.obj:
  $(cc) $<
  copy $(*F).obj $(*R).obj
  erase $(*F).obj

 #link
 {$(objdir)}.obj{}.exe:
  link $(**R);

 #target-dependencies

 run: grdemo.exe

 $(objdir)\*.obj: $(wrkdir)\$$(@B).c $(wrkdir)\menu.h \
 $(wrkdir)\turtle.h

 grdemo.exe: $(list)


 23. NMAKE May Invoke MASM Instead of the C Compiler

 Product Version(s): 1.00 1.01 1.11 | 1.01 1.11
 Operating System:   MS-DOS         | OS/2
 Flags: ENDUSER | docsup s_pwb h_fortran
 Last Modified: 17-JUL-1990    ArticleIdent: Q60746

 When using an NMAKE file in combination with adding /Fa to the
 compiler options within Programmer's WorkBench (PWB), NMAKE will
 invoke the Macro Assembler, if it is in the current search path.

 This does not occur the first time you build your application, but it
 does occur the second time, and thereafter, because of the generation
 of the .ASM created by the compiler.

 Files with the .ASM extension have a predefined inference rule within
 NMAKE to invoke MASM. However, the inference rule for .ASM files takes
 place before the rule for files with the .C or .OBJ extension.
 Therefore, if you have a filename with the same base name, but one has
 an .ASM extension and the other has a .C extension (as is the case
 with the /FA switch), the .ASM file will be assembled before the .C
 file will be compiled. Since the assembly step generates an .OBJ file
 that is newer than the .C file, the .C file is never compiled.

 Use the following procedures to work around this behavior:

 1. The best workaround is to use /Fa [LSTFILE.EXT] with a filename
    included as a compiler option, instead of allowing the /Fa option
    to default to its <filename>.ASM.

    Example: /Fa <filename>.ASC

    In using this method, the .C file will be compiled, instead of the
    .ASM version being assembled.

 2. Use the /Fc compiler option in place of the /Fa option (if you just
    want to look at an assembly source listing). This produces a .COD
    file (combined assembly and C source listing).

 3. Use the /R switch for the NMAKE invocation to ignore inference
    rules and macros that are predefined or defined in the TOOLS.INI
    file.

 For a more in-depth discussion on the /R switch and its effects, see
 the following references:

 1. The "Microsoft C Advanced Programming Techniques" reference manual

    Page(s) 112-114 Predefined macros
            118-119 Predefined inference rules
            125     /R Switch

 2. The "Microsoft FORTRAN, CodeView and Utilities User's Guide"

    Page(s) 288     /R Switch
            295-297 Predefined macros
            299-230 Predefined inference rules

 3. The "Microsoft QuickC Toolkit" reference manual

    Page(s) 158     /R Switch
            165-197 Predefined macros
            169     Predefined inference rules


 24. Looking for Files in Different Directories

 Product Version(s): 1.00 1.01 1.10 1.11 | 1.01 1.10 1.11
 Operating System:   MS-DOS              | OS/2
 Flags: ENDUSER | s_c s_quickc s_quickasm h_fortran
 Last Modified: 17-JUL-1990    ArticleIdent: Q60867

 If you use the "directory search" feature of NMAKE (curly braces "{}")
 to use a separate directory for some files, the location of these
 files cannot be inferred in subsequent dependency rules.

 The following code example demonstrates this confusion:

    test.exe: {\obj}test.obj
       link \obj\test.obj graphics.lib;

    test.obj: test.c test.h
       cl /c /Fo\obj\test.obj test.c

 If TEST.EXE and \OBJ\TEST.OBJ were up to date and we were to change
 one of the dependencies for TEST.OBJ, nothing would happen. This is
 because \OBJ\TEST.OBJ doesn't have any dependencies. The TEST.OBJ
 dependency line is only for the current directory. If we were to
 change the TEST.OBJ line to the following

    {\obj}test.obj: test.c test.h

 a change to TEST.C or TEST.H would cause \OBJ\TEST.OBJ and TEST.EXE
 to be updated.

 Note: NMAKE has a predefined inference rule for C.EXE that causes
 TEST.EXE to be relinked in the above example if it is out of date with
 TEST.C.


 25. /MAKE Option Is Invalid with NMAKE

 Product Version(s): 1.11   | 1.11
 Operating System:   MS-DOS | OS/2
 Flags: ENDUSER | docerr
 Last Modified: 25-MAY-1990    ArticleIdent: Q61619

 On Page 43 of the "Microsoft C Reference" manual for version 6.00,
 NMAKE is described as being upwardly compatible with the earl