See Also: Array Types, Structured Types, Field, Function, GetBuff, Put, Type
To import an external function defined in a Dynamic Link Library (DLL) file. This command allows a DataFlex program to directly access functions of the Windows operating system and many of its extensions.
The syntax is the same as the Function command, except that the parameter list is preceded by a case-sensitive name (as defined in the Dynamic Link Library) and the name of the DLL.
External_Function {function-name} {lib-function} {library-name} ;
[{type} {param} ...]
Returns {return-type}
{function-name} Is the name of the function as it is to be called from the DataFlex program. This must be a literal name, not the value of a variable. This name is global to the program.
{lib-function} Is the case-sensitive name of the function as it is defined in the external DLL. This must be enclosed in quotes.
{library-name} The filename of the DLL that contains the function. This must be a literal name, not the value of a variable.
{type} The data type of the parameter. Valid types are Address, Boolean, Char, DWord, Float, Handle, Integer, Pointer, Real, Short, String, UChar, UInteger and UShort.
{param} The name of the parameter.
{return-type} Is the return data type of the function. This must be one of Boolean, Char, UChar, Short, UShort, Integer, UInteger, Float, Real, String, Address, Pointer, DWord, Handle or VOID_TYPE. You can use VOID_TYPE to make it more clear that the function does not return anything.
The External_Function command creates a global function that allows the DataFlex program to invoke an imported function of a DLL. The function is used like any other DataFlex function.
The following example creates a global function named PlaySound that invokes the PlaySoundA function of the DLL, WinMM.DLL (a Multimedia DLL). Note that while it is a good idea to make the {function-name} parameter as close as possible to {lib-function}, it is not necessary.
External_Function PlaySound "PlaySoundA" WinMM.dll String sFileName Handle hmod DWORD fdwSound Returns Integer
PlaySound returns an integer and takes 3 parameters, a string, a handle, and a DWORD. This function may be invoked as follows:
// Define wave sound constants.
Enum_List
Define SND_SYNC SND_ASYNC SND_NODEFAULT
Define SND_LOOP FOR 9
End_Enum_List
Function WaveLooping String sWaveFile Returns Integer
Function_Return (PlaySound( sWaveFile, 0, SND_LOOP ))
End_Function
This example wraps the Windows ShellExecute function. Read more about ShellExecute in the runprogram topic.
External_Function ShellExecute "ShellExecuteA" Shell32.Dll ;
Handle hwnd String sOperation String sFile String sParameters String sDirectory Integer nShowCmd ;
Returns VOID_TYPE
This function can then be called like this:
// this will perform an operation on a file with the application
// registered in the Windows Registry to print that type of file (via its extension)
// sOperation would be "print" (it could also be "edit" etc).
Procedure DoStartDocument GLOBAL String sOperation String sDocument
Handle hInstance hWnd
Get Window_Handle to hWnd
Move (ShellExecute (hWnd, sOperation, (Trim (sDocument)), '', '', 1)) to hInstance
End_Procedure
This example wraps the Windows GetLogicalDriveStringsA function, which allows enumeration of logical drives.
The string variable passed to the function must be pre-filled with null (ASCII zero) characters using ZeroString, then a pointer to the string variable passed using AddressOf.
External_Function WinAPI_GetLogicalDriveStrings "GetLogicalDriveStringsA" Kernel32.Dll Dword nBufferLength Pointer lpBuffer ;
Returns Integer
Procedure Test
String sLogicalDrivesString
Integer iLength iPos
ZeroString 255 to sLogicalDrivesString
Move (WinAPI_GetLogicalDriveStrings (255, AddressOf (sLogicalDrivesString))) to iLength
Showln "iLength: " iLength
For iPos From 1 To iLength
Showln (Mid (sLogicalDrivesString, 3, iPos))
Move (iPos + 3) to iPos
Loop
End_Procedure
If you want to use a string returned by a DLL function in it's entirety after it has been returned using AddressOf, for example sLogicalDrivesString in the sample code above, you must convert it from a C-Style string to a DataFlex string using CString.
Move (CString(sLogicalDrivesString)) to sLogicalDrivesString