InstallShield 2014 » InstallScript Language Reference
The UseDLL function loads a .dll file into memory. After the .dll file has been loaded into memory, your installation script can call a function from that .dll file. Note that if the .dll file specified by szDLLName requires other .dll files, those other .dll files must reside in the folder from which the .dll file attempts to load them. Normally this will be the current folder. To ensure that those .dll files can be located, call ChangeDirectory to change the current folder to the location of those .dll files before calling UseDLL. Failure to do so may prevent the .dll file from loading properly.
Each time that you load a .dll file into memory, the .dll file’s lock count is incremented. The lock count counts the number of applications that are using a .dll file. You should call UnUseDLL to unload a .dll file as soon as you are done using it. If you do not unload a .dll file when you are done with it, the .dll file will remain in memory when no applications need it, thereby wasting system resources. Every call to UseDLL should have a matching call to UnUseDLL in the script.
Caution: Microsoft Windows system .dll files, such as User.exe, User32.dll, Gdi.exe, Gdi32.dll, Krnl386.exe, Krnl286.exe, and Kernel32.dll, are loaded and unloaded automatically by Windows. Do not call UseDLL and UnUseDLL to load and unload these .dll files.
Syntax
UseDLL ( szDLLName );
Parameters
|
Parameter |
Description |
|
szDLLName |
Specifies the name of the .dll file to be loaded. If you do not specify an extension, InstallShield assumes that the file has the extension .dll or .exe. Including a path in this parameter is recommended but optional. If the path for the .dll file is not specified in this parameter, InstallShield searches for the .dll file using the same search order used by the Windows API function LoadLibrary. See the description of this Windows API function for more information regarding the search order. To include the .dll file in your installation, add it to the appropriate subfolder of the Language Independent folder in the Support Files view. InstallShield compresses it into your installation. When Setup.exe executes, it automatically decompresses and copies the contents of your installation into the temporary directory specified by SUPPORTDIR. You can then append the .dll file name to SUPPORTDIR as follows in order to reference the .dll file: szDLLName = SUPPORTDIR ^ "MyDll.dll"; UseDLL (szDLLName); If you do not place your .dll file into your installation (by inserting it into the appropriate folder in the Support Files view), you can instead distribute the file along with the files of your application and then load it from the target system. However, if you do so, you must specify the location to which you install the .dll file so that your installation can reference it. You must also ensure that your installation does not attempt to load the .dll file before it has been transferred to the target system. Note: The szDLLName parameter does not support uniform resource locators (URLs). |
Return Values
|
Return Value |
Description |
|
0 |
Indicates that the function successfully loaded the .dll file into memory. |
|
< 0 |
Indicates that the function was unable to load the .dll file into memory. If UseDLL fails, the most likely cause is that the .dll file was not found. If this happens, make sure the correct path is specified in the parameter szDLLName. Another common cause of failure associated with using .dll files is related to .dll file dependencies—.dll files accessed by the .dll file that you load. If the .dll files that your .dll file accesses are not loaded or found, your .dll file call may fail. If this occurs, make sure that the other .dll files are on the system and that they are accessible. If the script exits or terminates before properly unloading the .dll file with UnUseDLL, the .dll file will be locked in memory. If you attempt to access the .dll file again, your script may fail. You must remove the .dll file from memory by restarting Windows. |
See Also
InstallShield 2014 Help LibraryMay 2014 |
Copyright Information | Contact Us |