Click above to get retro games delivered to your door ever month!

Overview -- EXTENDA.INC


   A new system of assembly language macros is included 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

   Using 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, FUNC1, FUNC2, FUNC3, FUNC4>

      ;*******
      ;
      ; 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 Four Basic Macros

   There are many other macros in the package, but the four described
   below represent a minimum for getting started, so take a close look
   at them and the concept in general.


   . CLpublic <CRYPT, FUNC1, FUNC2, FUNC3, FUNC4>

     Every function to be called from within Clipper must be declared
     public in this way.  Note that function 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 runtime 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 two 16-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.