Purpose
Declare an entity defined in a DLL to the compiler.
Syntax
[Attributes] [Modifiers] _DLL FUNCTION | PROCEDURE
[([<idParam> [AS | REF <idType>] [, ...])]
[AS <idType>]
[<idConvention>]
:<idDLL>.<idEntity>
[CharSet= AUTO|ANSI|UNICODE]
Arguments
| <idEntity> | The name or number of the entity as defined in the DLL. This is normally, but not necessarily, the same as the entity name defined in <EntityDeclaration>, which may define an alias by which the entity is called in your application. <idEntity> must be part of the public protocol of the DLL identified by <idDLL>. IdEntity may also be specified as a literal string. This should be done to specify names of exported functions in DLLs that contain characters that are not allowed as part of an identifier in X#. |
| <idParam> | A parameter variable. A variable specified in this manner is automatically declared local. These variables, also called formal parameters, are used to receive arguments that you pass when you call the entity. |
| AS | REF|OUT|IN <idType> | Specifies the data type of the parameter variable (called strong typing). AS indicates that the parameter must be passed by value, and REF indicates that it must be passed by reference with the @ operator. OUT is a special kind of REF parameter that does not have to be assigned before the call and must be assigned inside the body of the entity. IN parameters are passed as READONLY references. The last parameter in the list can also be declared as PARAMS <idType>[] which will tell the compiler that the function/method may receive zero or more optional parameters. Functions or Methods of the CLIPPER calling convention are compiled to a function with a single parameter that this declared as Args PARAMS USUAL[] |
| <idConvention> | Specifies the calling convention for this entity. <idConvention> must be one of the following: |
o CLIPPER
o STRICT
o PASCAL
o CALLBACK
o THISCALL
| Most calling conventions are for backward compatibility only. There are 2 exceptions: CLIPPER declares that a method has untyped parameters. This is usually only needed for methods without any declared parameters. Otherwise the compiler will assume CLIPPER calling convention when it detects untyped parameters. Methods and Functions in external DLL may have STRICT, PASCAL, CALLBACK |
| <idDLL> | The name of the DLL file that contains the entity definition, specified without an extension or path name (that is, its base name). A .DLL extension is assumed (with some exceptions determined by Windows that may have an .EXE extension), and the rules used to search for the file at runtime are explained in the Description section below. |
| Charset | Optionally specifies which character set string parameters have |
Description
_DLL declares an entity that is used by your application but defined in a DLL. This statement tells the compiler not only the location and name (or number) of the DLL entity, but also its calling convention (that is, what parameters it expects and the type of value that it returns). When you declare an entity with the _DLL statement, it also indicates to the compiler that the entity has no additional source code following its declaration.
Once declared, the entity may be called in your application in the standard way.
Warning: Entity names contained within the _DLL statement are case sensitive. This is in direct contradiction to the X# compiler which is not case sensitive but is consistent with Windows calling protocols. For this reason you must take extra care if Case Sensitization is turned on or you have the Caps Lock on.
Examples
The following examples illustrate _DLL declarations for two Windows API functions:
_DLL FUNCTION MessageBeep(siLevel AS SHORTINT) AS VOID PASCAL:User.MessageBeep
_DLL FUNCTION MessageBox(hwndParent AS PTR, pszText AS PSZ, pszCapt AS PSZ, dwFlags AS DWORD) ;
AS LONG PASCAL:User.MessageBox
// You can also declare a function with "normal" string parameters if you want. Add the ANSI or UNICODE clause to indicate which version you want to call.
_DLL FUNCTION MessageBox(hwndParent AS PTR, pszText AS STRING, pszCapt AS STRING, dwFlags AS DWORD) ;
AS LONG PASCAL:User.MessageBox ANSI
See Also
ACCESS, ASSIGN, FUNCTION, METHOD, PROCEDURE
