Declaration

Declare an external function.

function FUNCT_NAME (

  [ [small] TYPE:ARG1_NAME | [TYPE] reference:ARG1_NAME

  [, [small] TYPE:ARG2_NAME | [TYPE] reference:ARG2_NAME ]...] )

  returns {boolean|[small] {integer|string|float}}

  [external name EXTERNAL_NAME]

  library LIB_NAME

FUNCT_NAME

The name of the function you are declaring.

small

Pass the smaller form of the ESL data type by value. Use small with integer, float, or string only. See the table in the "Description" section for information about corresponding C data types.

TYPE

One of the following: integer, string, boolean, float, or structure STRUCTDEF_NAME, where STRUCTDEF_NAME is the identifier of a previously defined structure type.

ARGn_NAME

A descriptive name for the argument. This is a placeholder, so it does not need to be a variable in the program. However, if TYPEn is structure STRUCTDEF_NAME, then ARGn_NAME must not be the identifier for a previously declared structure variable.

reference

Pass the argument by reference, rather than by value. You do not need to specify reference with structure STRUCTDEF_NAME because structures are only passed by reference. You can abbreviate this as ref.

returns

The type of value that the function returns: boolean, integer, string, or float. Use small with integer, string, or float only.

external name EXTERNAL_NAME

A string value that is the external name of the function, if different from FUNCT_NAME. EXTERNAL_NAME can be used to create multiple aliases for external functions, and can be used to call functions that are exported only by ordinal. See the "Description" section below for more information.

library LIB_NAME

The identifier for a dynamic link library.

Description

Use this statement to define an external function. You must declare all external functions before calling them. If you do not, an error is generated at compile- time. An external function can take a maximum of 13 arguments.

To call an external function that is not exported by name, EXTERNAL_NAME should be a quoted string containing an 'at' character (@) followed by the ordinal number, in decimal. To call the function at ordinal 1, EXTERNAL_NAME should be "@1".

Be aware that Windows does not return an error if ESL tries to access a non-existent function by ordinal. ESL will try to call the non-existent function, most likely leading to a General Protection Fault (GPF).

Libraries provided with ESL have include files that contain declarations for all the external functions in the library.

To call a function that takes an argument of type structure STRUCTDEF_NAME, specify the identifier of the structure variable as the argument name.

When using small values, be sure that the value stored in the ESL argument will convert to a small value without loss of data.

Calling Functions

The following table summarizes the correspondence between ESL argument types and the C argument types passed to external functions.

 

1 This type can be a simple variable, an array element, or a field in a structure.

2 This type must be a simple variable. It cannot be an array element or a field in a structure.

3 This type can be a simple variable or an array element.

Example

function SIN(float:X)

returns float

library "mathlib"

The following three examples show how you might declare and call external C functions.

The examples use the following ESL variable and structure definitions:

integer variable   Int1

                   Int2

                   IntResult

float variable     Float1

                   Float2

string variable    String1

                   String2

structure Struct is

    integer I1

    integer I2

    float   F1

    float   F2

    string  S1

    string  S2

end structure

 

structure Struct Struct1

    integer IntArray[2]

    float FloatArray[2]

    string StringArray[2]

end structure

 

# Example 1: Passing By Reference

# This function passes one argument by value and one by

# reference.

function ReferenceArg (integer: I, integer reference: J)

        returns integer

        library "funclib"

# Sample calls:

    copy (ReferenceArg (Int1, Int2)) to IntResult # Int2 is passed as

# a long far *.

    copy (ReferenceArg (Struct1.I1, IntArray[2])) to IntResult

# The C function prototype:

# long ReferenceArg (long Arg1, long far *Arg2);

 

# Example 2: Where a Reference Type Is Not Specified

# This function passes one argument by value and one argument by

# reference, but without a type specified.

function VoidArg (integer: I, reference: J)

    returns integer

    library "funclib"

# Sample calls:

    copy (VoidArg (Int1, Int2)) to IntResult # Int2 is passed as

# a void far *.

    copy (VoidArg (Int1, Float1)) to IntResult

    copy (VoidArg (Int1, String1)) to IntResult

    copy (VoidArg (Int1, Struct1.F1)) to IntResult

    copy (VoidArg (Int1, StringArray[2])) to IntResult

# The C function prototype:

# long VoidArg (long Arg1, void far *Arg2);

 

# Example 3: Using the keyword small

function SmallArgs (small integer: I, small float: F,

    small string: C)

    returns small integer

    library "funclib"

# Sample call:

# Note that Int1 is passed as a short, Float1 as a float,

# and String 1 as the first character in the string. The return

# from the function is cast from a short to a long.

    copy (SmallArgs (Int1, Float1, String1)) to ResultInt

# The C function prototype:

# short SmallArgs (short Arg1, float Arg2, char Arg3);

 

The following example shows how to call a function using an alias:

 

# Windows API SetWindowText( ), using an alias

structure String80 is

    string String using string size 80

end structure

 

function SetWinText(

    small integer: Hwnd,

    structure String80: Text)

    returns small integer

    external name "SetWindowText"

# could also use 'external name "@37"'

    library "USER"

    structure String80 Title

response to Primary

    copy "New Title" to Title.String

    send SetWinText( handle of Primary, Title ) "\n" to errorlog

See Also

structure Variable Declaration

structure is Type Definition

subroutine Declaration