DECLARE – DLL Command

Example   See Also

Registers a function in an external shared library. Libraries are 32-bit dynamic link library (.DLL) files.

Syntax

DECLARE [cFunctionType] FunctionName IN LibraryName [AS AliasName]
  [cParamType1 [@] ParamName1,
     cParamType2 [@] ParamName2, ...]

Arguments

cFunctionType

Indicates the data type of the return value from the shared library, if any. If the function does not return a value, omit cFunctionType.

cFunctionType can assume the following values:

FunctionName

Specifies the name of the shared library function to register in Visual FoxPro. Function names passed in this parameter are case-sensitive.

Note   A DLL function name may not be the same as stated in the Win32 API manual. For example, the MessageBox function should be named MessageBoxA (for single-byte character), and MessageBoxW (for UNICODE). If Visual FoxPro cannot locate the DLL function you specify with FunctionName, the letter A is appended to the end of the function name and Visual FoxPro searches again for the function with the new name.

If the shared library function you specify has the same name as a Visual FoxPro function or is not a legal Visual FoxPro name, use the AS clause to assign an alias to the function when you register it, as described later in this topic.

IN LibraryName

Specifies the name of the external shared library containing the function specified with FunctionName.

If you specify WIN32API for the LibraryName, Visual FoxPro searches for the 32-bit Windows .dll function in Kernel32.dll, Gdi32.dll, User32.dll, Mpr.dll, and Advapi32.dll.

AS AliasName

Specifies an alias name for a shared library function name that has the same name as a Visual FoxPro function or is not a legal Visual FoxPro name. AliasName should not be a Visual FoxPro reserved word or the name of a shared library function already registered with Visual FoxPro.

If you assign alias to the function, use the alias when calling the shared library function. AliasName is not case-sensitive.

cParameterType1 [@] ParamName1, cParameterType2 [@] ParamName2, ...

Specifies the parameter types passed to the shared library function.

cParameterType is required and specifies the data type of any parameters that the shared library function expects to have passed to it. cParameterType may be one of the following:

Visual FoxPro generates an error if the parameters are not of the type the shared library function expects. Null values can be passed as empty character strings.

To pass a parameter by reference when you call the function, you must include @ after the parameter cParameterType in this command, and before the corresponding variable in the calling function. If you don't include @ in DECLARE, in the calling function, or in both, the parameter is passed by value. For information about shared library functions that require @ to pass parameters by reference, see the programmer's guide for your operating system or environment (for example, refer to the Microsoft Win32 Programmer's Guide for information on passing parameters to Windows DLLs).

Note   The parameter names ParamName1, ParamName2, and so on, are optional, and are not used by Visual FoxPro or the shared library function. You can include them as a reminder of the names and types of parameters the function receives.

Remarks

Before you can call a shared library function from within Visual FoxPro, you must issue DECLARE with the name of the function, the name of the shared library containing the function, and the parameter types the function expects to receive.

For backward compatibility, Visual FoxPro allows calls to external API libraries using the SET LIBRARY command. (Using SET LIBRARY, you can access functions in Foxtools.fll). However, using DECLARE is the preferred method to register shared library functions.

For further information about calling shared library functions, see the programmer's guide for your operating system or environment (for example, refer to the Microsoft Win32 Programmer's Guide for information on calling DLLs).

Issue DISPLAY STATUS or LIST STATUS to display the names of registered functions. Issue CLEAR ALL or CLEAR DLLS to remove registered functions from memory.