libcall

Define a function interface to a DLL library.

Syntax

libcall(lib, func,[name], ret-type[,{[byref] arg-type}[,...]][, ...])

Where:

lib	is a string expression indicating the library containing the function to import into SourcePoint.
func	is a string expression specifying the function within the library.
name	is a string expression defining the keyword to be used by SourcePoint when accessing the function. This name must not be the same as SourcePoint keywords or previously defined user functions. If not specified the keyword will be the same as strInterface.
ret-type	is the return type of function: {void | string | data-type}
arg-type	is the type of an argument passed to the function {string | data-type | data-type[ ]}
data-type	is a parameter type specification.
void	specifies there is no return type.
byref	indicates that the following parameter is to be passed in as a reference.
string	is a string parameter.
data-type[ ]	is an array parameter.
...	(ellipsis) indicates a variable type/length parameter list. If specified, it must be last.

Discussion

Use the libcall command to create an interface to an exported function in a DLL that can then be called from the SourcePoint command line as a user defined function.

The first parameter specified is the library in which the exported function resides.

The second parameter specified is the case-sensitive interface name of the exported function within the external library.

The third parameter is the case-sensitive alias within SourcePoint with which the exported function may be accessed. This alias may be omitted (though the trailing comma still must be present) in which case the same name as the exported function is used.

Note:   If the function defined already exists in SourcePoint (e.g., printf), then the internal function in SourcePoint will be used.

After specifying the user-defined function's name and where to access it in a DLL, the return type and parameter list must be specified in a manner which will match the exported function within the DLL.

The return type of a user-defined function may either be a ord, int, real, void, or a string.  Return types cannot be specified as references, arrays, structures, etc.

A parameter defined with the byref keyword is an out or in/out parameter.  Without the byref keyword, the parameter is an in parameter.

Parameter types of byref, string, and array are passed as pointers to the external library call.

An ellipsis as a parameter list or at the end of a parameter list indicates the user-defined function has a variable number and type of parameters.

Libcall determines whether a function is declared in a dll as either _cdecl or _stdcall.

Arrays are not currently supported.

Example 1

To call some functions in the Microsoft run-time library MSVCRTD.DLL:

Command input:

libcall("msvcrt.dll", "atof",,double,string)

define double pi

pi=atof("3.14159")

 

libcall("msvcrtd","rand",,ord2)

define ord4 result

result=rand()

Example 2

To call the MessageBox() function in the Microsoft library USER32.DLL:

Command input:

libcall("user32.dll","MessageBoxA",,ord4 ord4, string, string, ord4)

define ord4 result

result=MessageBoxA(0, "Test Text","Caption",3)

Example 3

To call the sscanf() function in the Microsoft run-time library and rename it to _sscanf:

Command input:

libcall("msvcrt.dll","sscanf",_sscanf,ord4,string,string,...)

define string _str = "1/2/2008"

define ord4 mon, day, yr, result

result = _sscanf(_str,"%d/%d/%d",byref mon,byref day,byref yr)

Example 4

To call the TestCall1() function in a user-created dll called testdll.dll which returns a value in the byref parameter:

Command input:

libcall("testdll.dll","TestCall1",,ord4, byref ord4)

define ord4 outvalue

TestCall1(byref outvalue)

Related Topics:

remove

show