Click above to get retro games delivered to your door ever month!

_DLL
Create a function to call a DLL
------------------------------------------------------------------------------

Syntax
#include "dll.ch"
_DLL [ STATIC ] FUNCTION <name> ( [ <p1> AS | REF <type1>, ] ... )
     AS <returnType>
     [ PASCAL | C]
     : [ <lib> ] . <entryName>

Arguments
<name> is the name of the Clipper function to be defined.

<p1> AS | REF <type1> specifies the first parameter of a comma-
separated list of parameters required by the DLL, where:

<p1> is the name of the parameter, optionally preceded by "@"
to mean it is changed/set by the DLL (in which case you must
pass your actual parameter by reference, of course).  If you
use REF, the "@" is assumed.

AS | REF shows the parameter is passed by value (AS) or
reference (REF).

<type1> is the data type of the parameter (upper/lower case
are treated the same).  Most common Windows and C types are
handled, as well as Clipper ones with an obvious conversion,
including HANDLE, HWND, INT, SHORT, WORD, DWORD, LONG, STRING,
PTR, LPSTR, BOOL, and LOGIC.  See GetProcAddress() for a
complete list.

AS <returnType> is the data type of the return value.  The
types available for <type1> are generally understood, as well
as VOID and NIL.  See GetProcAddress() for a complete list.

PASCAL | C specifies the calling convention used by the DLL.
Use PASCAL even for DLL's written in C, unless you're sure the
DLL uses the C convention.  This is because the PASCAL calling
convention is almost a standard, even for DLL's implemented in
C (or C++).

: [ <lib> ] . <entryName> specifies the DLL and the name of
the function in the DLL.  The <lib> should not specify an
extension, as .EXE or .DLL will be added internally (.EXE is
added for the Windows modules USER, GDI, and KERNEL).  You can
omit the <lib> if you want one of the DLL's searched by
GetProcAddress(), but it's wiser to specify it if you know it.

Description
This command can be used to create a Clipper function to
interface to a non-Clipper function in a DLL (including a
function in the Windows API).  For your convenience, the
syntax is similar to VB / VO.

This command pre-processes into a function that uses the
Clip-4-Win LoadLibrary(), GetProcAddress(), and FreeLibrary()
functions.  If speed is a concern (i.e. if you willl call the
DLL function very often), you can use these functions
yourself, with STATIC variables, for example.  However, a
short C function to do the interfacing will be much faster
(see SOURCE\WINAPI\*.C for examples).

Example
// From SOURCE\OO\CLASSES\MENU.PRG (to allow cnResId, and call the
// API function differently according to the type):
static function LoadMenu(hInst, cnResId)
return iif(valtype(cnResId) == "C", LoadMenuS(hInst, cnResId), ;
           LoadMenuN(hInst, cnResId))

_DLL function LoadMenuS(hInst AS HINSTANCE, cResId AS STRING) ;
     AS HMENU  PASCAL:USER.LoadMenu

_DLL function LoadMenuN(hInst AS HINSTANCE, nResId AS LONG) ;
     AS HMENU  PASCAL:USER.LoadMenu

// From RRWAPI.PRG (R & R for Windows):
_DLL Func ChooseReport(AppName AS PTR,            ;
                       LibName AS PTR,            ;
                       RepName AS PTR,            ;
                       Size    AS SHORT)          ;
          AS SHORT PASCAL:RReport.ChooseReport