home *** CD-ROM | disk | FTP | other *** search
/ CD Actual 15 / CDACTUAL15.iso / cdactual / program / asm / PROC.ZIP / PROC.DOC next >
Encoding:
Text File  |  1988-10-31  |  6.7 KB  |  178 lines
  1. PROC.MAC
  2.  
  3.    A macro file to simplify interfacing assembly language programs
  4.    with higher level programs.
  5.  
  6.    This file was tested with the Microsoft MACRO Assembler version 3.00.
  7.  
  8.    All identifiers that are of no interest to a programmer when using
  9.    the macro file have the form @aaa@@: where 'aaa' represents three
  10.    letters.  No one is likely to redefine these symbols.
  11.  
  12.    A few of the macroes exist for cosmetic purposes only.  None of the
  13.    @aaa@@ words appear in a listing when the normal switches are in
  14.    effect.  Also every identifier generated in the macro file or in the
  15.    macro expansions are deleted from the symbol listing with .XCREF,
  16.    with the exception of the procedure names.
  17.  
  18.    The file begins with the definitions of TRUE, FALSE and some
  19.    frequently used control characters.  TRUE = NOT FALSE (-1).
  20.  
  21.    A few structures are defined to give size attributes and high byte
  22.    or word offsets to operands.  The operand:
  23.  
  24.     WOMBAT.B
  25.        or
  26.     WOMBAT.LB
  27.  
  28.    is equivalent to
  29.  
  30.     BYTE PTR WOMBAT
  31.  
  32.    The operand
  33.  
  34.     [BX].HW
  35.  
  36.    is equivalent to
  37.  
  38.     WORD PTR [BX] + 2
  39.  
  40.    The modifiers defined are B, LB, HB, W, LW, HW & D.
  41.  
  42.    Most of the file consists of macro definitions.  The assembler manual
  43.    states that macro expansionss should not be recursive.  However I
  44.    have had no problem with this.  The depth is limited to five by
  45.    limiting the number of parameters to ten.  I have even found that
  46.    string equates can be redefined (to other strings) without causing
  47.    errors.  While this permits redefining identifiers for the parameters
  48.    of different procedures, I would not reccommend it.  This may be
  49.    an oversight in the assembler.  If so, it might occasionally have
  50.    some unpredictable side-effects; furthermore it might have been
  51.    corrected in later versions.
  52.  
  53.    When using this file, some attention must be given to whether a
  54.    particular parameter has a value to be used or the address of that
  55.    value.  It is also necessary to know something about how a specific
  56.    compiler passes parameters.  Regardless of which calling convention
  57.    is used, the $PARM macro defines the parameters in the inverse of
  58.    the order in which they were pushed.
  59.  
  60. $PASCAL
  61. $C
  62.  
  63.    The $PASCAL macro tells any $PRET macro following it to clean up
  64.    the stack.  The $C macro tells it not to clean up the stack.
  65.    Each remains in effect until the other is invoked.  Near the
  66.    end of the macro file the statement @PAS@@ = TRUE sets $PASCAL
  67.    as the default.
  68.  
  69. $PROC
  70.  
  71.    This macro needs at least two parameters.  The first is the
  72.    procedure name; the second is NEAR or FAR.  $PROC declares the
  73.    procedure PUBLIC and depending whether it is NEAR or FAR,
  74.    determines where the first parameter (the last one pushed)
  75.    is located on the stack.  It also executes the PROC directive.
  76.    If $PROC has more than two parameters, it executes $PARM with
  77.    the remainder of its parameters.
  78.  
  79. $IPROC
  80.  
  81.    This declares an interrupt procedure.  It takes one or two
  82.    parameters.  The first is the procedure name, which is declared
  83.    as a FAR procedure.  The second, if used, is an identifier for
  84.    the position on the stack where the flags are saved.  $PROC may
  85.    be used in situations where this is inadequate.
  86.  
  87. $PARM
  88.  
  89.    $PARM takes from one to five pairs of parameters.  The first of
  90.    each pair, becomes an identifier for a position on the stack
  91.    representing one of the procedure's parameters.  The second of
  92.    each pair, is an integer or integer identifier that tells how
  93.    many bytes of stack space the parameter occupies.  It does NOT
  94.    give a size attribute to the procedure's parameter; it determines
  95.    where the next parameter will be located on the stack, and adds
  96.    to the count of bytes to be popped from the stack, when applicable.
  97.    The modifiers mentioned above are convenient for specifying size
  98.    attributes.  A procedure may have more than one $PARM expansion,
  99.    and any parameters after the first two in the $PROC expansion
  100.    become $PARM parameters.
  101.  
  102.    The special parameter $LAST is not one of a pair, and is used to
  103.    tell $PRET to pop only the parameters preceeding it.  In Turbo
  104.    Pascal, in some circumstances (differing in the earlier and later
  105.    versions) not all parameters will be popped from the stack.
  106.  
  107.    When the $C macro has been used, the number of parameters defined
  108.    in $PARM expansions does not have to match the number of parameters
  109.    passed to the procedure.
  110.  
  111. $VAR
  112.  
  113.    This macro is used to assign identifiers to local variables on the
  114.    stack.  Like $PARM, it does NOT give size attributes to these
  115.    identifiers.  Also like $PARM, it takes pairs of parameters; the
  116.    first an identifier and the second an integer indicating the number
  117.    of bytes.
  118.  
  119.    Since identifiers defined in $PARM and $VAR are [BP] relative,
  120.    they can only be indexed by [DI] or [SI] and/or a constant.
  121.  
  122. $SAVE
  123.  
  124.    REMEMBER TO $SAVE; otherwise procedures do stupid things.
  125.  
  126.    $SAVE should be used whenever $PARM parameters or $VAR variables
  127.    need to be accessed in the procedure.  It generates the instructions:
  128.  
  129.     PUSH    BP
  130.     MOV    BP, SP
  131.  
  132.    and reminds $PRET or $IRET that this has been done.  In addition,
  133.    if any $VAR variables have been defined, it makes room for them on
  134.    the stack.
  135.  
  136.    Normally $SAVE is used after all $VAR variables have been defined.
  137.    However $VAR may be used after $SAVE to reference variables that
  138.    will be pushed onto the stack by the procedure.  A little caution
  139.    is needed if register values from the calling procedure are also
  140.    pushed onto the stack.  $PRET and $IRET assume that any such values
  141.    have already been popped.
  142.  
  143. $RET
  144. $PRET
  145. $IRET
  146.  
  147.    $RET executes $PRET if the procedure was defined in $PROC, or
  148.    $IRET if it was dfined in $IPROC.
  149.  
  150.    Both $PRET and $IRET clean up the local stack and pop the calling
  151.    procedure's BP if $SAVE was executed.
  152.  
  153.    $PRET then generates a return instruction.  If the procedure had
  154.    $PARM parameters and the $PASCAL convention was in effect, the
  155.    return pops the parameters.  If $LAST appeared in the $PARM
  156.    parameters, only the parameters defined before it are popped.
  157.  
  158.    $IRET then generates the IRET instruction.
  159.  
  160.    If $RET, $PRET or $IRET have a parameter, the $TERM macro is
  161.    executed and the parameter passed to it.
  162.  
  163. $TERM
  164.  
  165.    The $TERM macro must have a parameter which must be the procedure
  166.    name.  It generates the ENDP directive then sets up default values
  167.    except the $PASCAL/$C value for the next procedure.
  168.  
  169. $LIST
  170.  
  171.    This supports a personal preference of restarting a listing
  172.    without having:
  173.  
  174.     .LIST
  175.  
  176.    appear on the listing, when the listing control switches are in
  177.    their usual modes.
  178.