home *** CD-ROM | disk | FTP | other *** search
/ Source Code 1992 March / Source_Code_CD-ROM_Walnut_Creek_March_1992.iso / msdos / asmutl / usoftpd.arc / MIXED.DOC < prev    next >
Text File  |  1987-07-31  |  9KB  |  273 lines
  1.               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.  
  14.    BAMAIN.BAS        BASIC main program that calls assembly module
  15.    CAMAIN.C        C main program that    calls assembly module
  16.    FAMAIN.FOR        FORTRAN main program that calls assembly module
  17.    PAMAIN.PAS        Pascal main    program    that calls assembly module
  18.  
  19. In addition, the directory contains the    following files:
  20.  
  21.    MIXED.INC        Macros for simplifying assembly routines intended
  22.             to be called from high-level languages.
  23.    POWER2.ASM        Macro version of assembly module that can be called
  24.             from BASIC,    C, FORTRAN, or Pascal.
  25.  
  26.              Mixed-Language    Macros
  27.  
  28. MIXED.INC contains macros for defining high-level-language routines.
  29. It can create functions    for Microsoft C, FORTRAN, or Pascal, and for
  30. future versions    of Microsoft BASIC. It can also    create subprograms
  31. for BASIC, subroutines for FORTRAN, or procedures for Pascal.
  32.  
  33.     Note: Some BASIC examples use functions    and the    DECLARE
  34.     statement. These features are not available in versions    of
  35.     Microsoft BASIC    available at release time. They    will work
  36.     if you rewrite functions as subprograms. Functions and
  37.     DECLARE    statements will    be supported in    future versions    of
  38.     Microsoft BASIC    compilers.
  39.  
  40. The following macros are provided:
  41.  
  42.        Macro          Purpose
  43.  
  44.        setModel          Sets memory model    passed from a DOS command line
  45.        hProc          Initializes a procedure
  46.        hLocal          Initializes local    variables
  47.        hRet          Returns from a procedure
  48.        hEndp          Terminates a procedure
  49.  
  50.        ifFP          Assembles    statement if the memory    model uses far data
  51.        FP          Provides ES override if the memory model uses far    data
  52.        pLes          Loads data (through ES for far data)
  53.        pLds          Loads data (through DS for far data)
  54.  
  55. Other internal macros in MIXED.INC are used by these macros, but can
  56. be ignored by the user.
  57.             Macro Syntax
  58.  
  59. The calling convention used in the macros depends on whether the
  60. symbol "cLang" is defined. If "cLang" is defined, the C    calling
  61. convention is used. Otherwise, the calling convention used by
  62. BASIC, FORTRAN,    and Pascal is used.
  63.  
  64. Macro names and    arguments are case insensitive.    The macros and
  65. their syntax are described below:
  66.  
  67. setModel
  68.  
  69.   Sets the memory model    to small, medium, compact, large, or huge.
  70.   This macro is    an alternative to the .MODEL directive.    It enables
  71.   you to pass a    memory model from the MASM command line. For
  72.   example, you can use
  73.  
  74.       setModel
  75.  
  76.   as the first code in your source file    and supply the memory model
  77.   with the /D option as    shown below:
  78.  
  79.       MASM /Dmodel=medium source;
  80.  
  81.  
  82. hProc  <name [NEAR|FAR]> [,<USES reglist>] [,arg[:type]    [,arg[:type]]]...
  83.  
  84.   Initializes a    procedure by pushing BP    and saving SP in BP. The
  85.   macro    also handles the following tasks:
  86.  
  87.     1. Declares    the procedure name public in the format    of the language
  88.        ("doTask" is declared as "_doTask" for the C compiler).
  89.  
  90.     2. Gives the procedure the type NEAR or FAR    if specified, or the
  91.        default type for    the memory model (NEAR for small and compact
  92.        models or FAR for medium, large,    and huge models). If type is
  93.        specified, the name and type must be enclosed in    angle brackets.
  94.  
  95.     3. Saves and restores specified registers. The keyword USES    must
  96.        be given    as a parameter followed    by the registers. USES and
  97.        the registers must be enclosed in angle brackets.
  98.  
  99.     4. Assigns names and types to stack    parameters. The    type for
  100.        parameters can be BYTE, WORD, DWORD, FWORD, QWORD, TWORD, or
  101.        PTR. If no type is given, WORD is assumed. PTR type means
  102.        that the    parameter is a pointer.    It's size is variable
  103.        depending on the    size of    the memory model. Pointers are
  104.        assumed to point    to data, so the    size is    NEAR for small and
  105.        medium models or    FAR for    compact, large,    and huge models.
  106.  
  107.   For example,
  108.  
  109.       hProc   <doTask FAR>, <USES si di>, count:BYTE, array:PTR, number
  110.  
  111.   defines the FAR procedure "doTask" with byte parameter "count",
  112.   pointer paramter "array", and    word parameter "number". The SI    and
  113.   DI registers are saved.
  114.  
  115. hLocal    var[:type] [,var[:type]]...
  116.  
  117.   Saves    space on the stack for local variables and assign them
  118.   variables names. For example,
  119.  
  120.       hLocal   work,temp:DWORD
  121.  
  122.   allocates "work" as a    temporary word variable    and "temp" as a
  123.   temporary doubleword variable.
  124.  
  125.  
  126. hRet
  127.  
  128.   Returns from a procedure. SP is restored from    BP if local variables
  129.   have been used. BP is    popped.    A RET instruction is given in
  130.   the format appropriate for the memory    model and calling
  131.   convention.
  132.  
  133.  
  134. hEndp
  135.  
  136.   Ends a procedure. Note that a    procedure may have several return
  137.   points, but only one end point.
  138.  
  139.  
  140. ifFP  statement
  141.  
  142.   Assembles the    statement if the memory    model uses far data. This
  143.   macro    can be used to push segment registers or take other
  144.   action that is only required for far data. For example,
  145.  
  146.       ifFP     push  ds
  147.  
  148.   pushes the DS    register in compact, large, and    huge memory
  149.   models, but has no effect in small and medium    models.
  150.  
  151.  
  152. FPoperand
  153.  
  154.   Gives    an ES override if the memory model uses    far data. In
  155.   models that use near data, FP    is null. For example,
  156.  
  157.       mov      ax,FP[bx]
  158.  
  159.   assembles as
  160.  
  161.       mov      ax,es:[bx]
  162.  
  163.   in compact, large, and huge memory models, but as
  164.  
  165.       mov      ax,[bx]
  166.  
  167.   in small and medium models.
  168.  
  169. pLes  register,address
  170. pLds  register,address
  171.  
  172.   Loads    a pointer from the specified address to    the specified
  173.   register. If the memory model    uses far data, the segment
  174.   portion of the address will be moved into ES or DS, depending
  175.   on the macro used. For example,
  176.  
  177.       pLes    bx,arg1
  178.  
  179.   is assembled as
  180.  
  181.       les     bx,arg1
  182.  
  183.   in compact, large, and huge memory models, but as
  184.  
  185.       mov     bx,arg1
  186.  
  187.   in small and medium models.
  188.  
  189.                  Notes
  190.  
  191. The macros in MIXED.INC    have several limitations:
  192.  
  193.   1. The memory    model must be set at the start of the source
  194.      file before any mixed-language macros are used. The model
  195.      can be set    with the .MODEL    directive or with the "setModel"
  196.      macro. For    example, start with
  197.  
  198.         INCLUDE   mix.inc
  199.         .MODEL    small
  200.  
  201.      or    with
  202.  
  203.      model  EQU          <small>       ; Or    pass small from    command    line
  204.         INCLUDE   mix.inc
  205.         setModel
  206.  
  207.      The mixed-language    macros only work with simplified segment
  208.      directives. You cannot use    them with full segment definitions.
  209.  
  210.   2. If    the C calling convention is used, the symbol "cLang"
  211.      must be defined before the    start of a procedure. For
  212.      example, define the symbol    in the source file with    the line
  213.  
  214.         cLang   =    1
  215.  
  216.      or    from the command line with the option
  217.  
  218.         /DcLang
  219.  
  220.   3. The macros    do not automatically handle 80386 features such
  221.      as    32-bit pointers.
  222.  
  223.   4. All limitations and techniques described the Mixed-Language
  224.      Programming Guide apply. For instance, you    must save and
  225.      restore the DS, SS, DI, and SI registers if your module
  226.      modifies them. Return values should be passed back    by
  227.      placing them in AL, AX, or    DX:AX before returning.
  228.  
  229.   5. FORTRAN and Pascal    require    that the address for certain
  230.      return values (such as real numbers or arrays) be passed as
  231.      the last argument.    The macros do not handle this situation,
  232.      so    the programmer must handle it specifically. An example
  233.      is    shown below:
  234.  
  235.         hProc FuncFORTRAN,Arg1,Arg2,RetPoint
  236.         .
  237.         .
  238.         .
  239.         mov        RetPoint,bx      ; Assume BX contains a pointer
  240.                   ;   to return    value
  241.         Return
  242.  
  243.   6. The convenience of    using the macros in MIXED.INC has a cost
  244.      in    slower assembly    time.
  245.  
  246.                 Examples
  247.  
  248. The file POWER2.ASM contains a sample assembly module that is
  249. equivalent to the sample modules in BA.ASM, CA.ASM, FA.ASM, and
  250. PA.ASM.    POWER2.ASM uses    the macros in MIXED.INC    and can    be
  251. assembled from the command-line    for any    language or memory
  252. model. The module can be linked    with the high-level-language
  253. modules    created    from BAMAIN.BAS, CAMAIN.C, FAMAIN.FOR, or
  254. PAMAIN.PAS. The    command    lines for default memory models    are
  255. shown below for    each language:
  256.  
  257. BASIC -    CodeView symbolic data and medium model
  258.  
  259.   MASM /ZI /Dmodel=medium power2;
  260.  
  261. C - Case sensitive, CodeView symbolic data, small model, and "cLang" defined
  262.  
  263.   MASM /Mx /Zi /Dmodel=small /DcLang power2;
  264.  
  265. FORTRAN    - CodeView symbolic data and large model
  266.  
  267.   MASM /ZI /Dmodel=large power2;
  268.  
  269. Pascal - CodeView symbolic data    and large model
  270.  
  271.   MASM /ZI /Dmodel=large power2;
  272.  
  273.