CALL

    To execute separately compiled or assembled routines and programs.

Syntax

    CALL <process> WITH <exp list>

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 processes ending 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 example below).  All data types are passed by reference.  Your
    program must preserve the BP, SS, SI, DI, ES, and DS registers.

    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.  If you wish to convert a dBASE
    III 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.
    The CALL command executes a binary program file that has been
    loaded in memory with the LOAD command.  Each loaded file is treated as
    a subroutine or module rather than as an external program (which could
    be executed with the RUN command).  As a result, each time you want to
    execute the program, it can simply run from memory without having to be
    reloaded from a disk.  Up to 16 binary program files can be loaded in
    memory at one time, and each can be up to 32,000 bytes in length.

    When you CALL the binary program file, you specify the name of the file
    without the .bin extension.  The program module name is the same as the
    file loaded in memory.  When you call the file, you can pass either a
    character expression or a memory variable of any data type to the
    binary program file.  All character type memory variables and
    expressions end with a null (ASCII value zero).

    Numeric variables are passed as 8 byte floating point representation,
    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:

    - The program must be in the "INTEL 8086 relocatable object file
      format", with the .OBJ file extension.

    - Must follow C language calling and parameter passing conventions.

    - Must be available to the Clipper Linker at link time.  You will need
      runtime support for any language other than assembly language.  See
      your compiler manual for details.

Examples

    The following example in C changes 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 module*/
    test (p1, p2)               
                                
    char *p1;                   
    char *p2;                   
                                
    {                           
        while (*p2)             
        *p1++ = *p2++;          
    }