INTERFACING WITH ASSEMBLY LANGUAGE


In addition to supporting a mixed language interface to C and
other high-level langauges, Clipper also supports user-defined
functions written in assembler through the Extend System.  Like
the interface to C, the Extend System provides access to the
parameter passing and returning functions.  These are the same
functions available from C differing only by the method of
access.  Here you must manipulate the stack in order that the
proper values are known when Clipper is called.  To make this
process easier and more rational, two set of macros are included
(EXTENDA.MAC and EXTENDA.INC).  EXTENDA.MAC is similar to
earlier versions of Clipper and is provided in Summer '87 as
means of retaining compatibility with assmbler code written for
Autumn '86.  EXTENDA.INC is a new set of macros developed for
use with Summer '87 and Microsoft MASM version 5.0.

Passing Parameters

These are the functions used for obtaining the parameters being
passed from your Clipper code.  When you use the __PAR
functions,  follow the pseudo sequence below:

                move the parameter number to be obtained into a
                register

                push the register

                call the appropriate __PAR function for the data
                type of the parameter

                the parameter is received in registers, either by
                value or by pointer

                restore the stack

In addition, it is important to remember that Clipper is written
in C and all parameters are passed as C data types.


Sample Assembly Routines

To interface an assembly language routine to Clipper using the
Extend System requires that you follow some specific rules.

                Declare your routine PUBLIC.

                Declare the Extend functions to be used as EXTRN
                and FAR or INCLUDE EXTENDA.INC which makes these
                declarations for you.

                If you define your own data segment, group it
                together with Clipper's DGROUP.  Otherwise, DS must
                point to DGROUP before you call any Extend function.

                Class your data segment as DATA for Autumn '86 or
                _DATA for Summer '87.

                Class your code segment PROG for Autumn '86 or
                CODE for Summer '87.

                If have not passed a value back to Clipper, call
                __RET just before your assembler routine ENDS.

The following is a shell of a typical Clipper user-defined
function written in assembly language that demonstrates these
rules:

PUBLIC  <func_name>
;
EXTRN   <extend_func>:FAR
;
DGROUP GROUP    <data_seg>
<data_seg>      SEGMENT PUBLIC '_DATA'
;
;       <your data declarations>
;
<data_seg>      ENDS
;
;
<code_seg>      SEGMENT 'CODE'
                        ASSUME cs:<code_seg>, ds:DGROUP

<func_name>     PROC FAR
                push    bp                      ; Save registers
                mov     bp,sp
                push ds
                push es
                push si
                push di

                < your code goes here >

                pop  di                 ; Restore registers
                pop  si
                pop  es
                pop  ds
                pop  bp
                <func_name> ENDP        ; End of routine

<code_seg>      ENDS                    ; End of code segment
                END


Example:

The following is an operational assembly language routine that
clears a region of the screen.

In Clipper:

Clearit(10, 10, 20, 60)

In assembly language:

PUBLIC Clearit  ; Declare as public.
;
EXTRN   __PARNI:FAR     ; Declare functions
EXTRN   __RET:FAR               ; as external.
;
DGROUP GROUP    DATASG  ; Combine your data segment
                                ; with Clipper's.
DATASG SEGMENT '_DATA'  ; Start of data segment.

top             DB      0
left    DB      0
bottom  DB      0
right   DB      0

DATASG  ENDS                    ; End of data segment.
;
;
_PROG   segment 'CODE'  ; Start of code segment.
ASSUME  cs:_PROG,ds:DGROUP
;
;
CLEARIT PROC    FAR             ; Start of process.

        push bp                 ; Preserve return address.
        mov     bp,sp

        push ds                 ; Save registers.
        push    es
        push si
        push di

        mov     ax,1                    ; Point to parameter.
        push ax                 ; Place on stack.
        call __PARNI            ; Call Clipper.
        add     sp,2                    ; Restore stack.
        mov     top, al         ; Assign parameter to top.

        mov     ax,2            ; Repeat process for next parameter.
        push    ax
        call __PARNI
        add     sp,2
        mov     left, al                ; Assign to left.

        mov     ax,3            ; Repeat process for next parameter.
        push ax
        call __PARNI
        add     sp,2
        mov     BOTTOM,al               ; Assign to bottom.

        mov     ax,4            ; Repeat process for next parameter.
        push ax
        call __PARNI
        add     sp,2
        mov     right,al                ; Assign to right.

        mov     ch,top          ; Place coordinates in CX:DX.
        mov     cl,left
        mov     dh,bottom
        mov     dl,right

        mov     ax,0600h                ; Request roll up service.
        mov     bh,07           ; Normal attribute.
        int     10h                     ; Issue video interrupt.

        pop     di
        pop     si
        pop     es                      ; Restore registers.
        pop     ds
        pop     bp

        call __RET              ; Clipper return (actual cleaning).

        ret                             ; Actual physical return.
CLEARIT ENDP                    ; End of process.
_prog   ENDS
        END

Note that since assembly language gives you access to the lowest
level of software and hardware interaction, exercise appropriate
caution.  All the above functions require that you save the
registers before you can use them to call the functions.  Make
sure that after calling any Extend function to restore the stack
by incrementing the stack pointer (SP).  Failure to restore the
original environment will usually cause the system to crash.