home *** CD-ROM | disk | FTP | other *** search
/ For Beginners & Professional Hackers / cd.iso / softcrc / masm / masm.510 / mixed.doc < prev    next >
Encoding:
Text File  |  1988-02-01  |  8.9 KB  |  259 lines
  1.         Converting Mixed-Language Source Files
  2.  
  3. This directory contains    mixed-language example programs    and macros.
  4.  
  5. The following source files are the sample programs from    Chapter    6,
  6. "Assembly-to-High-Level Interface," of the Mixed-Language Programming
  7. Guide:
  8.  
  9.    BA.ASM        Assembly module to be called from BASIC
  10.    CA.ASM        Assembly module to be called from C
  11.    FA.ASM        Assembly module to be called from FORTRAN
  12.    PA.ASM        Assembly module to be called from Pascal
  13.    BAMAIN.BAS        BASIC main program that calls assembly module
  14.    CAMAIN.C        C main program that    calls assembly module
  15.    FAMAIN.FOR        FORTRAN main program that calls assembly module
  16.    PAMAIN.PAS        Pascal main    program    that calls assembly module
  17.  
  18. In addition, the following files are provided:
  19.  
  20.    POWER2.ASM        Macro version of assembly module that can be called
  21.             from BASIC,    C, FORTRAN, or Pascal.
  22.    MIXED.INC        Mixed language macros.
  23.    MIXED.DOC        This file.
  24.  
  25. The version of MIXED.INC provided with MASM 5.1    is smaller than    the
  26. MASM 5.0 version because most of the functionality has now been    built
  27. into MASM and the macros are no    longer needed. The following macros
  28. are still supported in MIXED.INC:
  29.  
  30.        Macro          Purpose
  31.  
  32.        ifFP          Assembles    statement if the memory    model uses far data
  33.  
  34.        FP          Provides ES override if the memory model uses far    data
  35.  
  36.        pLes          Loads data (through ES for far data)
  37.  
  38.        pLds          Loads data (through DS for far data)
  39.  
  40. To use these macros with MASM 5.1, you should include MIXED.INC    after
  41. using .MODEL. The macro    syntax is shown    below:
  42.  
  43. ifFP  statement
  44.  
  45.   Assembles the    statement if the memory    model uses far data. This
  46.   macro    can be used to push segment registers or take other
  47.   action that is only required for far data. For example,
  48.  
  49.       ifFP     push  ds
  50.  
  51.   pushes the DS    register in compact, large, and    huge memory
  52.   models, but has no effect in small and medium    models.
  53.  
  54. FPoperand
  55.  
  56.   Gives    an ES override if the memory model uses    far data. In
  57.   models that use near data, FP    is null. For example,
  58.  
  59.       mov      ax,FP[bx]
  60.  
  61.   assembles as
  62.  
  63.       mov      ax,es:[bx]
  64.  
  65.   in compact, large, and huge memory models, but as
  66.  
  67.       mov      ax,[bx]
  68.  
  69.   in small and medium models.
  70.  
  71. pLes  register,address
  72. pLds  register,address
  73.  
  74.   Loads    a pointer from the specified address to    the specified
  75.   register. If the memory model    uses far data, the segment
  76.   portion of the address will be moved into ES or DS, depending
  77.   on the macro used. For example,
  78.  
  79.       pLes    bx,arg1
  80.  
  81.   is assembled as
  82.  
  83.       les     bx,arg1
  84.  
  85.   in compact, large, and huge memory models, but as
  86.  
  87.       mov     bx,arg1
  88.  
  89.   in small and medium models.
  90.  
  91. The other macros in the    MASM 5.0 version of MIXED.INC are provided for
  92. compatibility with MASM    5.0, but are not documented. The rest of this
  93. file discusses compatibility options for source    code that uses 5.0
  94. high-level-language macros. If you did not own MASM 5.0, you should
  95. ignore the rest    of this    file. Do not use the other macros in
  96. MIXED.INC.
  97.  
  98. You can    use the    following macros if you    have source code that uses the
  99. macros provided    with MASM 5.0.
  100.  
  101.        Macro          Purpose
  102.  
  103.        setModel          Sets memory model    passed from a DOS command line.
  104.               No longer    needed because the expression operator
  105.               now enables you to evaluate text macros passed
  106.               from the command line directly.
  107.  
  108.        hProc          Initializes a procedure. Replaced    by new
  109.               attributes of the    PROC directive when you
  110.               specify a    language argument to the .MODEL
  111.               directive.
  112.  
  113.        hLocal          Initializes local    variables. Replaced by new
  114.               functionality of the LOCAL directive.
  115.  
  116.        hRet          Returns from a procedure.    Replaced by new
  117.               functionality of the RET instruction.
  118.  
  119.        hEndp          Terminates a procedure. Replaced by new
  120.               functionality of the ENDP    directive.
  121.  
  122. The 5.1    versions of these macros are different than the    MASM 5.0
  123. versions. The new macros use new MASM features to simulate the same
  124. functionality more efficiently.    Do not use the MIXED.INC provided with
  125. MASM 5.0. It will not work under MASM 5.1.
  126.  
  127. Rather than use    the old    macros,    you may    want to    convert    your source
  128. files to use the built-in mixed    language features of MASM 5.1. The
  129. conversion is straightforward and can be done easily with a text
  130. editor.
  131.  
  132. The following changes can be made to source files that use macros from
  133. the 5.0    MIXED.INC. The source file POWER2.ASM on the MASM 5.1
  134. distribution disk is an    example    of a converted source file. You    can
  135. compare    it with    the POWER2.ASM supplied    with MASM 5.0.
  136.  
  137.   o You    must define a a    memory model argument and a language argument
  138.     to the .MODEL directive to use the new mixed-language features of
  139.     MASM 5.1. You can do this within the source    file:
  140.  
  141.       .MODEL small, c
  142.  
  143.     Alternately, you can pass the arguments in from the    command    line
  144.     using /D. In MASM 5.0, you had to use the setModel macro to
  145.     receive a model argument passed on the command line. You only
  146.     needed to define the language symbol "cLang" for C;    no
  147.     definition was needed for other languages.
  148.  
  149.     The    5.0 source line    to accept the argument would be:
  150.  
  151.        setModel
  152.  
  153.     For    MASM 5.1, change to:
  154.  
  155.        %      .MODEL model,lang
  156.  
  157.     Notice that    the expression operator    (%) is required    so that    MASM
  158.     can    evaluate text arguments    passed from the    command    line.
  159.  
  160.     The    5.0 command line to define C small model would be:
  161.  
  162.        MASM /MX    /Dmodel=small /DcLang power2;
  163.  
  164.     For    MASM 5.1, change this to:
  165.  
  166.        MASM /MX    /Dmodel=small /Dlang=C power2;
  167.  
  168.   o Replace references to the hProc macro with the PROC    directive.
  169.     Remember, new features of the PROC directive only work when    a
  170.     language argument is given for the .MODEL directive. The 5.0
  171.     macro syntax was:
  172.  
  173.        hProc  <name [NEAR|FAR]> [,<USES reglist>] [,arglist]
  174.  
  175.     The    5.1 syntax is:
  176.  
  177.        name PROC [NEAR|FAR] [,USES reglist] [,arglist]
  178.  
  179.     The    syntax for each    MASM 5.0 argument in the arglist was
  180.  
  181.        argument[:[NEAR|FAR] type]
  182.  
  183.     where the type could be BYTE, WORD,    DWORD, FWORD, QWORD, TBYTE, or
  184.     PTR    (to indicate that the variable is a pointer).
  185.  
  186.     The    syntax for each    MASM 5.1 argument is:
  187.  
  188.        argument[:[[NEAR|FAR] PTR] type]
  189.  
  190.     where the type can be BYTE,    WORD, DWORD, FWORD, QWORD, TBYTE, or a
  191.     structure type. Note that structure    types can now be given.    Also,
  192.     PTR    is part    of the syntax rather than a type. If PTR is given with
  193.     a type, then it means that the variable is a pointer to a variable
  194.     of the given type. This information    makes no difference in what
  195.     MASM assembles, but    it can be used by the CodeView debugger.
  196.  
  197.     For    example, consider the following    MASM 5.0 source    line:
  198.  
  199.        hProc   <doTask FAR>, <USES si di>, count:BYTE, array:PTR, number
  200.  
  201.     It should be changed to the    following for MASM 5.1:
  202.  
  203.        doTask  PROC FAR    USES si    di, count:BYTE,    array:PTR WORD,    number
  204.  
  205.     Notice that the array is now declared as pointer to a word (or an
  206.     array of words). In the 5.0 syntax it was simply a pointer to an
  207.     object of undefined size.
  208.  
  209.   o Replace references to the hLocal macro with    the LOCAL directive.
  210.     The    syntax for the 5.0 hLocal macro    was:
  211.  
  212.        hLocal  varlist
  213.  
  214.     The    MASM 5.1 syntax    is:
  215.  
  216.        LOCAL   varlist
  217.  
  218.     The    syntax for each    5.0 variable was:
  219.  
  220.        variable[:[NEAR|FAR] type]
  221.  
  222.     The    syntax for each    5.1 variable is:
  223.  
  224.        variable[[count]][:[[NEAR|FAR] PTR] type]
  225.  
  226.     The    difference is the same as the difference for arguments to the
  227.     PROC directive. In addition, you can allocate local    arrays by
  228.     specifying a count (in brackets) following the variable name. For
  229.     example:
  230.  
  231.        LOCAL   work[20]:WORD, string:PTR BYTE
  232.  
  233.     This allocates a local array of 20 words called "work" and a
  234.     pointer to byte (called "string").
  235.  
  236.   o Replace references to the hRet macro with the RET instruction.
  237.  
  238.   o Replace references to the hEndp macro with the ENDP    directive
  239.     preceded by    the procedure name. For    example, change
  240.  
  241.        hEndp
  242.  
  243.     to
  244.        procname    ENDP
  245.  
  246.   o Under MASM 5.1, labels within a procedure are local    to the
  247.     procedure if the language argument is given    for the    .MODEL
  248.     directive. For example, if you use the label "exit:" in one
  249.     procedure, you can use it again in another procedure. A label
  250.     inside a procedure can be made global to the source file by
  251.     putting two colons after it (example, "glabel::"). Under MASM
  252.     5.0 all labels were global to the source file.
  253.  
  254.   o Note that the 5.0 macros did not automatically handle 80386
  255.     features such as 32-bit pointers. The 5.1 features do. For
  256.     example, if    you use    the .386 directive before the .MODEL directive
  257.     to enable 32-bit segments, near pointers declared with PTR will be
  258.     32 bits wide and far pointers will be 48 bits wide.
  259.