Function DllLoad() | Xbase++

Loads a DLL file dynamically during runtime.

DllLoad( <cDllName> [, <cFuncPrefix> ] [, <lSuppressInitExit>] ) --> nDllHandle

<cDllName> is a character string containing the name of the DLL file to be loaded during runtime.

The parameter <cFuncPrefix> is only significant when the DLL to be loaded complies with the Xbase++ calling convention. In this case, an optional character string which is used as prefix for the names of DLL functions when they are executed can be specified. This is useful when two or more DLLs that contain functions with identical names are loaded. Such functions can then be called individually by specifying different function prefixes. In this case, the prefix must preceed the name of a DLL function name when it is called.

If the optional parameter <lSuppressInitExit> is passed as .T., DllLoad() will not execute any INIT PROCEDUREs on load and suppress execution of EXIT PROCEDUREs on DllUnload(). This applies to Xbase++ DLLs only. The feature can be used for testing and debugging purposes. The code implemented in the DLL in question might not work after loading because INIT PROCEDUREs are usually used to initialize data structures required by the DLL later. The feature can also be used to put the DLL into a demonstration mode. The default value of this parameter is .F..

The function DllLoad() loads a DLL and returns its numeric DLL handle. When an error occurs, the return value is 0 and the error condition can be determined using the DosError() function.

DllLoad() is used to load 32bit DLL files during runtime of an Xbase++ application. If the DLL is already requested by another process, it is not loaded again. Instead, the current process achieves access to the DLL file by using the DLL handle. The function can load DLL files which are created by Xbase++ as well as system DLLs and other external DLLs. When a DLL is loaded, contained functions can be executed without having them specified to the linker during the creation of the EXE file. DLL functions are executed using the functions DllCall() or DllPrepareCall() and DllExecuteCall().

If other DLLs are linked statically to the loaded DLL, DllLoad() also executes the INIT PROCEDUREs that are programmed in the statically linked DLLs. However, the parameter specified with <cFuncPrefix> is not propagated from the dynamically loaded DLL to statically linked DLLs. Therefore, the parameter <cFuncPrefix> is only valid for the file <cDllName>.

When DLLs are built with Xbase++ and are to be loaded dynamically, all PRG files for that DLL must be compiled with the compiler option /dll:dynamic. If /dll:dynamic is not used, an attempt to load the resulting DLL dynamically will succeed, but DllUnload() will raise a runtime error.

If the name of the DLL file is a full qualified name (including drive and path), this file is loaded when it exists. However, the file name may be specified without drive and path. In this case, the operating system searches for the DLL in the start directory of the application program first. If the DLL exists in this directory, it is loaded. If the DLL is not found, a further search depends on the operating system:

OS/2 searches for the DLL file in all directories listed in the LIBPATH environment variable.

Windows searches directories for the DLL file in the following order: current directory, Windows System directory, Windows directory and finally all directories listed in the PATH environment variable.

If you see anything in the documentation that is not correct, does not match your experience with the particular feature or requires further clarification, please use this form to report a documentation issue.

Function DllLoad() Foundation