| System Functions |
|
| Formats | 1. Load
Library: lib_num
= DLL(ADDR lib_string$[,ERR=stmtref])
2. Unload Library: DLL(DROP lib_num[,ERR=stmtref]) 3. Get Function Address: fnc_addr = DLL(FIND lib_num,fnc_name$ [,ERR=stmtref]) 4. Call Using String: DLL( [FLOATING POINT] lib_string$,fnc_name$,arg[ ,arg,arg...][,ERR=stmtref]) 5. Call by Library Number: DLL( [FLOATING POINT] lib_num,fnc_name$,arg[ ,arg,arg...][,ERR=stmtref]) 6. Call Using Function Address: DLL( [FLOATING POINT] *,fnc_address,arg[ ,arg,arg...][,ERR=stmtref]) 7. Define Callback routine: DLL (CALL OBJECT obj_id EVENT "event_name" [,ERR=stmtref]) (ver 10) 8. Free Callback routine: DLL (CLEAR routine_addr [,ERR=stmtref]) (ver 10)
|
||||||||||||||||||||||||
| Returns | Calls external function or returns DLL identifiers and addresses. | ||||||||||||||||||||||||
| *Note* | DLL( ) and DLX( ) functions are only available under MS Windowsas well as most UNIX/Linux environments -- TCB(196) will return 1 if the function is supported. DLLs do not need to be registered to be used in ProvideX. Under WindX, remember that DLLs run on the host. Use a call to a WindX program to invoke a DLL. | ||||||||||||||||||||||||
| Description | Use the
ProvideX DLL( ) function to access
functions within DLLs that are external to ProvideX. It's
similar to a call to execute external DLL functions from
inside ProvideX applications. The ProvideX DLL( )
function will also return any function identifiers and
addresses, as defined by the DLL routine. In 32-bit environments, the DLX( ) function is unnecessary, since both DLX( ) and DLL( ) functions return 32-bit values. In 16-bit environments, DLL( ) returns 16-bit values while the DLX( ) function returns 32-bit values. A DLL is a free-standing library of 'C'-style functions commonly used in the Microsoft Windows and/or various Unix/Linux systemst. In Windows, all functions controlling the environment are done through DLL calls with function names as the entry points in the DLL. Most Windows API functions reside in the following DLLs:
|
||||||||||||||||||||||||
| *Warning* | You can use third-party DLLs, but make sure you have good documentation on what you're passing and getting back. We can provide assistance on how to call a DLL, but we do not provide support for third-party DLLs. There is no validation on what you pass. Bad pointers can cause memory corruption and potential GPFs. | ||||||||||||||||||||||||
| Format 1 | Load Library
Use the DLL(ADDR ...) format to addresses or load the DLL. This lets you load and lock a library into memory and obtain the addresses of its functions and the internal identifier. You can then use this identifier on subsequent DLL( ) functions to avoid having to reload the DLL. Note that the return value is the handle to the DLL and should be used in all subsequent DLL( ) calls. |
||||||||||||||||||||||||
| *Note* | In some instances (e.g., when the DLL maintains internal data structures) it is mandatory to keep the DLL loaded in order to use or call the function. When in doubt, load the DLL (not needed for Windows API DLLs). Keeping the DLL loaded has memory consequences, but commonly lets you gain access speed. | ||||||||||||||||||||||||
| Format 2 | Unload Library
Use the DLL(DROP ...) format to unload a loaded DLL when you no longer need it. Note that if you LOAD a DLL, you must DROP or unload it to free up the memory that was allocated to it. |
||||||||||||||||||||||||
| Format 3 | Get Function Address
You can obtain the address of a DLL( ) function in an addressed (loaded) library by using the FIND format. This format asks the DLL( ) function to return its current address, which you can then use in subsequent calls. The address is only valid while the library is loaded. In some cases, you may need to use the return value as a memory pointer. The MEM( ) function can be used to obtain memory information (address, contents, etc.). If you need a 32-bit result from a DLL( ) call, use the function DLX( ) instead. When you call an external function and pass arguments to it, you can identify it using a string, a library number, or a function address. For more information, refer to DLL( ) Parameters and MEM( ) Return Memory Value. |
||||||||||||||||||||||||
| Format 4 | Call Using String
Use this format to call the DLL( ) function using strings to identify the library and function by name. |
||||||||||||||||||||||||
| Format 5 | Call by Library Number
Use this format to call the DLL( ) function using a numeric to identify the library by its internal identifier and the function name. |
||||||||||||||||||||||||
| Format 6 | CALLs Using Function Address:
Use this format to call a DLL( ) function in a loaded library using the internal function address as a memory pointer. |
||||||||||||||||||||||||
| *Note* | The address is only valid while the library is loaded. | ||||||||||||||||||||||||
| Formats 7 & 8 | CALLBACK
(Windows only): As of version 10, PxPlus/PxBasic supports a single active callback which can have up to five parameters. It has been implemented as part of the DLL function with two options:
All callback functions MUST be defined within an Object so they can return a value to the caller. The callback is internally processed as an Event and processed by a event handler within the object. To obtain a reference to the Callback routine the DLL(CALL ...) function is called to return the callback address for the event handler within the object specified. When finished with the CALLBACK, the entry must be freed using the CLEAR option of the DLL function. For example, to get the callback address for "NameOfEvent" in obj_id:
You can then pass CB_valu to the external DLL. When finished either drop the object or issue the following to free the Callback.
Here is a sample Callback Object:
And here is a test program which uses the Callback functionality to spin through all the WIndows.
|
||||||||||||||||||||||||
| DLL( ) Parameters | DLLs
normally expect one of two types of parameters: integers
and pointers. The arguments/parameters you use when you
call the DLL( ) function are passed to
the function in the following ways:
|
||||||||||||||||||||||||
| Examples | Example
1. The following example swaps the left and
right mouse buttons:
An integer value of zero swaps the mouse buttons back. Example 2. Pointers are commonly used to pass string values, usually terminating with a null byte. This passes a pointer to a DLL to return the handle of a window with the title Notepad:
Example 3. Sometimes a pointer refers to a region of memory or a structure to receive information from a DLL. You must pre-allocate a string variable to receive the data. The example below returns the window title, given the handle. The returned string terminates with a null byte ($00$):
Example 4. To pass a pointer to a number, define a two- or four-byte string and read the value after swapping the bytes, as follows:
Example 5. Program DLLS1in this example starts Notepad, locates the handle and closes the window handle:
|
||||||||||||||||||||||||
| Inter-Task Communication | The Version
4.10 DireXions example which follows illustrates inter-task
communication. The program DLLS3 starts a second
PVXWIN32session, finds its Window handle, sends CTL
values 101 through 103, defines an atom (pointing to a
string variable in a global string table) and passes the
atom reference to the second session. Then it waits for
the second session to terminate.
|