DOCUMENT:Q72701  06-MAY-2001  [masm]
TITLE   :Writing Macro Functions and Using the EXITM Directive
PRODUCT :Microsoft Macro Assembler
PROD/VER::6.0,6.0a,6.0b
OPER/SYS:
KEYWORDS:

======================================================================
-------------------------------------------------------------------------------
The information in this article applies to:

 - Microsoft Macro Assembler (MASM), versions 6.0, 6.0a, 6.0b 
-------------------------------------------------------------------------------

SUMMARY
=======

Beginning with the Microsoft Macro Assembler (MASM) version 6.0, a macro can be
written that will return either a text or numeric value. This is called a "Macro
Function" and is implemented with the EXITM directive.

In MASM versions earlier than 6.0, the EXITM directive was used to exit a macro
immediately. There were no arguments or parameters. With versions 6.0 and later,
the EXITM directive takes an optional argument that specifies the return value.
This argument must be either text, a text equate name, or the result of another
macro function. In addition, the EXITM directive must be at the end of a macro
block if it is to be used to return a value.

MORE INFORMATION
================

The two examples below illustrate a couple of ways to use a macro function. In
the first example, a macro function is used to concatenate a text string to
create unique labels for a procedure definition. The example code is followed by
an extract from the list file showing the concatenated names for the
procedures.

The second example illustrates how a numeric value may be returned by using the
expansion operator (%). This example is followed by a preprocessor listing
showing the resultant code.

Sample Code 1
-------------

   ; Assemble options needed: /c /Fl

           .model small

   prefix  TEXTEQU <mycode_>

   paste   MACRO   arg1,arg2       ;Macro function that concatenates
           EXITM   <arg1&&arg2>    ;  strings arg1 and arg2
   ENDM

   n_proc  MACRO new_name          ;Macro that calls the paste
           paste   (%prefix,&new_name) PROC ;  macro function.
           paste   (%prefix,&new_name) ENDP ; The % expansion operator
   ENDM                            ;  evaluates the expression
                                   ;  associated with prefix.
           .code

           n_proc   fun_1
           n_proc   fun_2

           END

   =================== EXTRACT FROM LIST FILE =========================

   Macros:
          N a m e         Type

   n_proc .............   Proc
   paste  .............   Func

   Procedures,  parameters and locals:
          N a m e            Type    Value   Attr

   mycode_fun_1 ..........  P Near   0000    _TEXT  Length= 0000 Public
   mycode_fun_2 ..........  P Near   0000    _TEXT  Length= 0000 Public

   ====================================================================

Sample Code 2
-------------

   ; Assemble options needed: /c /EP

            .model small

   get_rate MACRO val              ; macro function that accepts a
            LOCAL thin             ;   value and returns the results of
            thin TEXTEQU <val*300> ;   an expression.
            EXITM %thin
   ENDM

   baudrate MACRO
            FOR b_rate, <1, 4, 8>     ; Equivalent to IRP with MASM 5.1a.
               BYTE b_rate
               WORD get_rate(b_rate)  ; Call to Macro Function.
            ENDM
   ENDM

            .code

            baudrate

            END

   ====================== PREPROCESSOR LISTING =========================

      .model small

      .code
            BYTE 1
         ??0000 TEXTEQU <1*300>  ; An expression
            WORD 300             ; Call to Macro Function
            BYTE 4
         ??0001 TEXTEQU <4*300>  ; An expression
            WORD 1200            ; Call to Macro Function
            BYTE 8
         ??0002 TEXTEQU <8*300>  ; An expression
            WORD 2400            ; Call to Macro Function
      end
   =====================================================================

Additional query words: kbinf 6.00 6.00a 6.00b

======================================================================
Keywords          :  
Technology        : kbMASMsearch kbAudDeveloper kbMASM600 kbMASM600a kbMASM600b
Version           : :6.0,6.0a,6.0b

=============================================================================

THE INFORMATION PROVIDED IN THE MICROSOFT KNOWLEDGE BASE IS
PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND.  MICROSOFT DISCLAIMS
ALL WARRANTIES, EITHER EXPRESS OR IMPLIED, INCLUDING THE WARRANTIES
OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.  IN NO
EVENT SHALL MICROSOFT CORPORATION OR ITS SUPPLIERS BE LIABLE FOR
ANY DAMAGES WHATSOEVER INCLUDING DIRECT, INDIRECT, INCIDENTAL,
CONSEQUENTIAL, LOSS OF BUSINESS PROFITS OR SPECIAL DAMAGES, EVEN IF
MICROSOFT CORPORATION OR ITS SUPPLIERS HAVE BEEN ADVISED OF THE
POSSIBILITY OF SUCH DAMAGES.  SOME STATES DO NOT ALLOW THE EXCLUSION
OR LIMITATION OF LIABILITY FOR CONSEQUENTIAL OR INCIDENTAL DAMAGES
SO THE FOREGOING LIMITATION MAY NOT APPLY.

Copyright Microsoft Corporation 2001.