External functions are functions written in languages other than PowerScript and stored in dynamic link libraries. On Windows and Windows CE, dynamic libraries have the extension DLL. You can use external functions that are written in any language that supports dynamic libraries.
Before you can use an external function in a script, you must declare it as one of two types:
Global external functions These are available anywhere in the application.
Local external functions These are defined for a particular type of window, menu, user object, or user-defined function. These functions are part of the object’s definition and can always be used in scripts for the object itself. You can also choose to make these functions accessible to other scripts.
To understand how to declare and call an external function, see the documentation from the developer of the external function library.
External function syntax Use the following syntax to declare an external function:
{ access } FUNCTION returndatatype name ( { { REF } datatype1 arg1,
..., { REF } datatypen argn } ) LIBRARY “libname“
ALIAS FOR “extname”
External subroutine syntax To declare external subroutines (which are the same as external functions except that they do not return a value), use this syntax:
{ access } SUBROUTINE name ( { { REF } datatype1 arg1, ...,
{ REF } datatypen argn } ) LIBRARY “libname“
ALIAS FOR “extname”
The following table describes the parameters used to declare external functions and subroutines:
Parameter |
Description |
|---|---|
access (optional) |
(Local external functions only) Public, Protected, or Private specifies the access level of a local external function. The default is Public. For more information, see the section about specifying access of local functions in “Usage”. |
FUNCTION or SUBROUTINE |
A keyword specifying the type of call, which determines the way return values are handled. If there is a return value, declare it as a FUNCTION; if it returns nothing or returns VOID, specify SUBROUTINE. |
returndatatype |
The datatype of the value returned by the function. |
name |
The name of a function or subroutine that resides in a DLL. |
REF |
A keyword that specifies that you are passing by reference the argument that follows REF. The function can store a value in arg that will be accessible to the rest of the PocketBuilder script. |
datatype arg |
The datatype and name of the arguments for the function or subroutine. The list must match the definition of the function in the DLL. Each datatype arg pair can be preceded by REF. For more information on passing arguments, see the Resource Guide or see Application Techniques in the PowerBuilder documentation set. |
LIBRARY “libname” |
A keyword followed by a string containing the name of the dynamic library in which the function or subroutine is stored. libname is a dynamic link library, which is a file that usually has the extension DLL. |
ALIAS FOR “extname” (optional) |
Keywords followed by a string giving the name of the function as defined in the dynamic library. If the name in the dynamic library is not the name you want to use in your script, or if the name in the database is not a legal PowerScript name, you must specify ALIAS FOR “extname” to establish the association between the PowerScript name and the external name. |
Specifying access of local functions When declaring a local external function, you can specify its access level—which scripts have access to the function.
The following table describes where local external functions can be used when they are declared with a given access level:
Access level |
Where you can use the local external function |
|---|---|
Public |
Any script in the application. |
Private |
Scripts for events in the object for which the function is declared. You cannot use the function in descendants of the object. |
Protected |
Scripts for the object for which the function is declared and its descendants. |
Use of the access keyword with local external functions works the same as the access-right keywords for instance variables.
To be available to a PocketBuilder application running on any Windows CE platform, the DLL must be in one of the following directories:
The current directory
The Windows directory
For PowerBuilder applications running on the desktop, the DLL can also be in one of the following directories:
The Windows System subdirectory
Directories on the DOS path
In the examples application that comes with PowerBuilder, external functions are declared as local external functions in a user object called u_external_function_win32. The scripts that call the functions are user object functions, but because they are part of the same user object, you do not need to use object notation to call them.
Example 1 These declarations allow PowerBuilder to call the functions required for playing a sound in the WINMM.DLL:
//playsound FUNCTION boolean sndPlaySoundA (string SoundName, uint Flags) LIBRARY "WINMM.DLL" FUNCTION uint waveOutGetNumDevs () LIBRARY "WINMM.DLL"
A function called uf_playsound in the examples application provided with PowerBuilder calls the external functions. Uf_playsound is called with two arguments (as_filename and ai_option) that are passed through to sndPlaySoundA. Values for ai_option are as defined in the Windows documentation, as commented here:
//Options as defined in mmystem.h.
//These may be or'd together.
//#define SND_SYNC 0x0000
//play synchronously (default)
//#define SND_ASYNC 0x0001
//play asynchronously
//#define SND_NODEFAULT 0x0002
//do not use default sound
//#define SND_MEMORY 0x0004
//lpszSoundName points to a memory file
//#define SND_LOOP 0x0008
//loop the sound until next sndPlaySound
//#define SND_NOSTOP 0x0010
//do not stop any currently playing sound
uint lui_numdevs
lui_numdevs = WaveOutGetNumDevs()
IF lui_numdevs > 0 THEN
sndPlaySoundA(as_filename,ai_option)
RETURN 1
ELSE
RETURN -1
END IF
Example 2 This is the declaration for the Windows GetSysColor function:
FUNCTION ulong GetSysColor (int index) LIBRARY "USER32.DLL"
This statement calls the external function. The meanings of the index argument and the return value are specified in the Windows documentation:
RETURN GetSysColor (ai_index)
Example 3 This is the declaration for the Windows GetSysColor function:
FUNCTION int GetSystemMetrics (int index) LIBRARY "USER32.DLL"
These statements call the external function to get the screen height and width:
RETURN GetSystemMetrics(1)
RETURN GetSystemMetrics(0)
