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

CALL


Syntax:     CALL <process> [WITH <exp list>]

Purpose:    To execute separately compiled or assembled routines and
            programs.

Arguments:  <exp list> is the list of expressions of any data type
            to pass to the external process.

Usage:      CALLed programs must be defined as FAR and end with a FAR
            return.  All data references consist of four-byte pointers
            in the form SEGMENT:OFFSET, and are on top of the stack in
            the order passed (see the examples below).  All data types
            are passed by reference.  Your program must preserve the BP,
            SI, DI, ES, and DS registers; and clear the direction flag.

            Note: Microsoft C version 5.0 places a leading
            underscore on function names when compiled.  To call them,
            therefore, you must use the following form:

            CALL _<function>

            Passing parameters: The CALL command parameter list may
            consist of up to seven parameters.  The DX:BX and ES:BX
            registers point to the first parameter, similar to dBASE III
            PLUS.  If you wish to convert a dBASE III PLUS load module,
            add the following statements to your .ASM file:

               PUBLIC <proc>

            and

               mov ds,dx

            Character strings are passed by reference, and are null
            terminated (a 0 byte at the end of the string).  The length
            of any data item must be preserved, as the data area
            contains many data items consecutively in memory.  If an
            item is lengthened, you will in all likelihood write over
            other data.

            Numeric variables are passed as eight-byte floating point,
            consisting of a 53-bit characteristic and an 11-bit exponent
            biased by 1023.  To pass numeric parameters as integers, use
            WORD() to convert them from the Clipper internal format to
            integer.  If the numeric value you are passing is greater
            than .32,767, it cannot be passed as an integer and
            therefore the use of WORD() is inappropriate.  Note also
            that if you use WORD() to pass a numeric value, it is passed
            by value.

            Compiling and linking: CALLed programs must conform to
            the following rules:

            .  Procedures must be in INTEL 8086 relocatable object file
               format with the .OBJ file extension.

            .  Procedures must follow the C language calling and
               parameter passing conventions.

            .  Procedures must be available to the linker at link time
               along with the library of the source compiler.  You will
               need runtime support for any language other than assembly
               language.  See your compiler manual for further
               information.

Library:    CLIPPER.LIB


----------------------------------- Examples -------------------------------

   The following two examples, the first in C and the second in
   assembler, change the variable "var" from "123" to "ABC."

   var = "123"
   CALL _Test WITH var, "ABC"
   ? var
   RETURN

   To CALL a C program, use the following simple program as a basis:

   /* Compile as large model */
   TEST (p1, p2)

   char *p1;
   char *p2;

   {
      while (*p2)
      *p1++ = *p2++;
   }

   To CALL an assembly language program that accomplishes the same
   result, use the following example:

   var = "123"
   CALL _Test WITH var, "ABC"
   ? var
   RETURN

   Clipper executes the CALL statement above using the following
   parameter passing conventions:

   --------------------------------------------------------------
   Stack Address      Stack                     Command
   --------------------------------------------------------------
   sp+10       [Segment of "ABC"]               push
   sp+8        [Offset of "ABC"]                push
   sp+6        [Segment of var]                 push
   sp+4        [Offset of var]                  push
   sp          [Segment:offset return address]  CALL FAR TEST
   --------------------------------------------------------------

   Thus the assembly language routine could be as follows:  (statements
   with asterisks are standard and therefore required)

   PUBLIC _Test                     ; * Declare process.
   _PROG SEGMENT BYTE 'CODE'        ; * Clipper code segment.

   ASSUME cs:_PROG                  ; * Put in Clipper segment.
   ;
   _Test PROC  FAR                  ; * Required declaration.
         push  bp                   ; Stack + 2.
         mov   bp, sp               ; Get pointer.
         push  ds
         push  es
         push  si
         push  di
         cld
         lds   si,[bp+10]           ; Offset of "ABC"
         les   di,[bp+6]            ; Offset of var
         mov   cx,3
   rep   mov   sb
         pop   di
         pop   si
         pop   es
         pop   ds
         pop   bp
         ret

   _Test ENDP                       ; * End of process.
         PROG ENDS                  ; * End segment.
         END                        ; * Program end.