AddShared()

Description

AddShared() is used to add new intrinsic functions to EASI which are actually C (or C compatible) functions in a shared library or DLL.

Call Signature

string AddShared ( string library , string function , string arg_types , string return_type )

Return Value

string

The string "TRUE" is returned for success and "FALSE" for failure.

Arguments

string library:

The name of the shared library or DLL to find the function int.

string function:

The name of the function in the shared library.

string arg_types:

A string containing one character for each argument to the function. The character defines the type of this argument and should be one of "I" for int, "L" for long, "D" for double, "P" for void *, or "S" for char *.

string return_type:

A string expression of one character defining the return type of the function. It is one of "I", "L", "D", "P", "S" or "V", where the meaning is as for argtypes and where "V" indicates a void function.

Remarks

Note that access to shared libraries is not supported on all platforms. Even on platforms where it is supported there are limitations to the function that can be invoked. Functions taking variable Arguments (such as sprintf()), or that are passed Arguments that cannot be easily mapped into one of the supported types, will be inaccessible.

In addition, there is a limit on the number of Arguments the added function can take. At the time of initial implementation, this limit is 4.

This intrinsic function is built on the PCI C Library function IMPGetSymbol() and IMPInvokeFunction() and suffers any limitations that these function suffer.

The argument and return type "S" (char *) are similar to "P" (void *) except that Return Values are returned as string constants rather than BYTE PTR's. It is also possible to pass string expressions through Arguments of type "S", while only PTR type values can be passed through Arguments taking "P".

Example

Add the C library function strlen() as an EASI intrinsic (Unix). Note that the char * pointer is defined as a string argument, rather than just a pointer so that arbitrary string expressions can be passed.

 call AddShared( "libc.so", "strlen", "S", "I" )
 print strlen("ABC")

The next Example adds the C library function strcat() as an EASI intrinsic. The string "abcdef" will be printed twice: the first time as the output returned by the strcat() function, and the second time by printing the variable CharBuf.

The first argument to strcat() is given a type of "P" (void *) because the strcat() function treats the first argument as a pointer to a buffer into which the resulting concatenated value can be placed. If we had used "S", the string would have been copied into a local buffer before being passed to strcat() and the end of the buffer would have been overwritten, corrupting memory.

 call AddShared( "libc.so", "strcat", "PS", "S")
 
 local char CharBuf[128]

 CharBuf = "abc"
 print strcat(CharBuf,"def")   
 print CharBuf