ASSEMBLY LANGUAGE EXTEND MACROS


A macro in assembler serves a similar function to macro
substution in Clipper.  Essentially you substitute a symbolic
name for the text of command statements.  In Clipper, you can
substitute macros for expressions and literal constants.  In
assembler, the implementation is much broader.  You can
substitute macros for entire blocks of code and additionally
pass parameters to the macro code.  When MASM encounters the
macro reference at assembly time, it substitutes the associated
code for the macro name and the text of the parameter name with
the actual parameter information.

Macros can be defined within the source file in which they are
used or within INCLUDE files.  INCLUDE files are the most
fruitful place to store macros since this allows you to isolate
code that is volital or environment specific.


EXTENDA.MAC

EXTENDA.MAC is provided in Clipper Summer '87 to give
compatility with assembler routines that interface with Autumn

Warning: EXTENDA.MAC macros do not save registers used
automatically.  You must, therefore, save registers of
importance to you before calling any of these macros.

The file EXTENDA.MAC contains the following macros:

                EXTENDA.MAC Macros

Macro                   Function
------------------------------------------
GET_PCOUNT              Number of parameters passed
GET_PTYPE           Type of parameter passed
GET_CHAR            Address of a string in DX:AX
GET_INT                 Integer in AX
GET_LONG                Long integer in DX:AX
GET_DBL                 Double in AX:BX:CX:DX
GET_DATESTR             Address of date string in DX:AX
GET_LOGICAL             Logical in AX
RET_CHAR                Returns string pointed to
RET_INT                 Returns integer
RET_LONG                Returns long integer
RET_DBL                 Returns double
RET_DATESTR             Returns date string
RET_LOGICAL             Returns logical value



EXTENDA.INC

A new system of Assembler Macros has been developed by Nantucket
to facilitate the use of Assembly language within Clipper
applications.  These Macros require an assembler compatible with
Microsoft MASM 5.0.  To use them, place the following directive
at the beginning of the Assembler source file:

INCLUDE EXTENDA.INC

With the use of this Macro system, a User Defined Function
written in Assembly language has the following general format:

    CLpublic  list_of_UDFs

;*******
;
    CLfunc  function_type  function_name  [parameter_list]
    CLcode
        .
        . body of function
        .
    CLret  return_value


    More specifically, and to illustrate actual syntax:

    CLpublic  <CRYPT, MYFUNC, YOURFUNC, THISFUNC, THATFUNC>

;*******
;
;   str = CRYPT(str, len)
;   encrypt/decrypt a character string
;
    CLfunc  char  CRYPT  <char str, int len>

    CLcode
        PUSH    ES

    ; test for valid parameter
        CMP     PCOUNT, 2
        JB      CRYPT_RET
        TESTNUL str
        JZ      CRYPT_RET

    ; parameters acceptable
        LES     SI, str
        MOV     BX, 0

CRYPT_LOOP:
       CMP      BX, len
       JE      CRYPT_RET
       NOT     BYTE PTR ES:[BX + SI]
       INC     BX
       JMP     CRYPT_LOOP

CRYPT_RET:
        POP     ES
    CLret  str

The angle brackets <> are required by MASM.  The use of mixed
upper and lower case is necessary only if the file is to be
assembled with case sensitivity enabled.  We will assume that
case sensitivity IS enabled for the remainder of this
discussion.


The Basic Four Macros: CLpublic, CLfunc, CLcode, CLret

There are many other macros in the package, but these four
represent a minimum for getting started, so let's take a closer
look at them and the concept in general.

CLpublic  <CRYPT, MYFUNC, YOURFUNC, THISFUNC, THATFUNC>

Every function to be called from within Clipper must be declared
public in this way.  Note that funcion names are upper case and
separated by commas.

CLfunc  char  CRYPT  <char str, int len>

This is the function declaration.  It tells the macro system
several things about the function including the return type,
function name, and parameter list.  Note that each parameter in
the list is declared to be of a particular type.  This list must
be omitted completely if there are no parameters.

CLcode

This is implemented as a separate step because some of the
optional macros are allowed or required to appear between the
function declaration and the start of the function.  The actual
code for setting up a user-defined function is placed here.
Everything necessary for the Clipper interface (including the
fetching of parameters and run-time type checking) is generated
by this macro.  When this code is executed at runtime, it stores
PCOUNT (the Clipper Parameter COUNT) so that it may be accessed
at any point in the function.  Additionally, parameters that are
not supplied and parameters of the wrong data type are set to
zero (NUL).  The macro TESTNUL can be used to test for any null
parameter, and should ALWAYS be used to test for a null pointer.

CLret  str

This macro generates the cleanup code for a proper return to
Clipper.  It performs an assembly-time type check of the return
value based on the function type declared in CLfunc.  If a
function is declared as type "int," the return value can be any
16-bit register (i.e. "CLret CX"), or any variable of type
"int".  Similarly, a function declared as type "char" will
return a pointer to a string.  In this case, the return value
can be any 2 sixteen bit registers (i.e. "CLret BX DX"), or any
variable of type "char".  Although functions declared "void"
have NO return value, the CLret macro must still be called but
without the return value.

Macros designed to appear in assembler source code are listed
below with syntax and some detail.  See EXAMPLEA.ASM for more
examples.  Also, many of these macros call each other within the
include file itself.