Equinox Online Help - Language Reference - A to Z
External |
|
|---|---|
| Applies to |     |
| Syntax | [Public] External Module [ExportedName] Call Parameters [Returns Reply] [Public] External Module [ExportedName] Call Parameters [MustReturn Reply] |
| Action | [Statement] Declares a call to a DLL function. |
| Scope | Usable anywhere. |
| Notes | This statement declares a DLL function so that you can call it from an Equinox method. The Public keyword allows an external declaration in a public procedure to be accessible anywhere in the application. It may only be used in a public procedure library. Module is a quoted string literal which describes the location of the DLL file. You may optionally omit the final ".dll". A number of the Windows DLLs which have different names in various versions of the OS have standard Equinox module names: "user", "kernel", and "gdi". If Module doesn't contain a path, Equinox will search for the DLL in the following places:
Call is the unquoted name of the DLL exported function, as documented by its authors. Additionally if the function name conflicts with something else in Equinox, you may supply ExportedName in quotes containing the actual DLL name, and Call as an alias to be used in Equinox. You should not include the Microsoft-generated final "A" in call names as Equinox adds that automatically if required. You may also use the alias system to create multiple versions of the dll call with slightly different parameter requirements. Parameters is a list of comma-separated data types. Use the following special types (which are also available in Equinox generally): byte, ubyte, short, ushort, int32, uint32, int64, uint64, long, ulong, intos, handle, double, string, stringz Equinox will generate errors if other types are used that may have different meanings on different operating systems - for example the int type. You may optionally suppress these errors by using the client ini key EnforceIntegerChecks=0; this is useful when running an application on WOW64, prior to changing the types to one of the above list so that the application can run on Win32 or Win64. If a pointer is required (mandatory for string types), precede the type with the ptr keyword. If a string type is being passed externally as a constant, you may add the readonly keyword to avoid Equinox making a writable copy of the constant. If the DLL expects a pointer, but the type can vary you may use the keyword anyptr and omit the type. The optional Returns keyword allows the return value to be accessed. If there is no return value, or it is not required, this keyword may be omitted. When using the call, add the Returns variable as the final comma-separated parameter. Note that this is unlike other languages which use the pattern returnvalue = function(parameterlist), since Equinox supports external functions by treating them as statements with an extra final return parameter. The MustReturn keyword can be used rather than Returns in External statements to make Equinox generate compilation errors if the return variable is not supplied in a call. If there is no return value (or it is not required) this clause may be omitted. Reply is the return value's data type. Use the NullPtr keyword in order to pass zero as the argument instead of a variable to a parameter declared with the ptr keyword. For more help on using DLLs, refer to Programming with Equinox; supported customers may ask the Support team for help with creating external statements with unfamiliar parameter requirements. |
| Category | Windows and DLLs |
| See Also | Bcopy, WindowHandle, FontHandle, GetMessageParameters, GetNotifyParameters, Hiword, Loword, MakeLong, PaletteRGB, RGB, RGBValues, PrintDC |
| Example | The following example provides an interface to the Windows MessageBox function. define MBOKCANCEL 1 The following procedure library provides access to the Windows clipboard. define CF_TEXT 1 |