ESL's Extended Call Interface (ECI) allows you to access many third party and operating system APIs so that you can use the functionality already implemented by the operating system, rather than implementing it yourself.
Caution: It is essential that you understand how to work with an API and with C language structures.
To call an external function directly from ESL, you must determine the function prototype you wish to call. For specific information, refer to a C language or library reference or an operating system reference manual. The prototype will include the function name, the C data types required to call the function, and the return type. If the types are specified as application-defined types (such as HSTRING), check the header file to find the C type.
Find the DLL where the function resides. Determine the C types that the function uses and the equivalent ESL types.
Note: The ECI can only call functions that are exported by function name.
C Type |
ESL Type |
short |
small integer in function call |
short * |
using integer size 2 |
long |
integer in function call |
long * |
reference integer in function call; integer in subroutine call |
float |
small float in function call |
float * |
using float size 4 |
double |
float in function call |
double * |
reference float in function call, float in subroutine call |
char |
small string in function call |
char * |
using string size N, where N includes NULL |
struct in C |
structure in ESL with optional using clauses for each field |
You can also use structures with using clauses to pass pointers to an API. Passing a structure as a parameter to an external call actually passes a pointer to the first field in the structure. For example, passing a string with the string conversion clause as the first and only field is actually passing a pointer to the string.
Write the ESL function prototype using the equivalent ESL data types and specify the library where the external function resides. To call the function directly from your ESL application, include the prototype.
For example, suppose you wish to call a function that resides in SAM.DLL and has the following prototype:
long APIENTRY Sample(long *, short, float)
ESL has equivalent types for these three C types. Therefore, the ESL prototype would be the following:
function Sample(reference integer:Param1, small integer:Param2, small float:Param3) returns integer library "SAM"
If you encounter predefined constants that are not in decimal format, ESL requires that you convert them as follows:
#define ThisIsFifteen 0x0f
should become
integer constant ThisIsFifteen is 15
