External_Function

Purpose

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.

Syntax

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}

Argument Explanation

{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.

What It Does

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.

Example

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

Example

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

Example

This example wraps the WindowsGetLogicalDriveStringsA 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 its 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