InstallShield internal library function 18 extension functions
The extended function allows you to call the functions in the dynamic link library, call the Windows API, or run another application or install the program script. Usedll and unusedll functions allow you to load a DLL to memory or uninstall it and use a DLL. Launchapp and LaunchappandWait functions allow you to run another Windows or DOS app while executing scripts.
Calldllfx
Call the function from an external DLL.
DELAY
Delay the execution of the installer script.
Launchapp
Run another program.
Launchappandwait
Run another program and wait for the program to terminate.
Unusedll
Uninstall a DLL from memory.
USEDLL
Put a DLL into memory.
18.1 CallDLLFX
Syntax: CallDLFX (SZDLL, SZFunction, LvValue, svvalue);
Description: The CallDLLFX function calls a function in a specified DLL. This function must use the following fixed definition, hwnd is the main window handle of the InstallShield main window:
Long Apientry YourFunction (HWND HWND, LPLONG LPIVALUE, LPSTR LPSZVALUE);
parameter:
szdll
Specifies the full-qualified file name of the DLL that contains the function to be executed.
SZFunction
Specifies the name of the function in the DLL specified by SZDLL.
Ivvalue
Specifies the long integer variable that passes when a DLL function is accessed.
svvalue
Specifies a string variable that passes to the DLL function.
return value:
The CallDLLFX function returns a long-intensive number from the function in the DLL.
18.2 Delay
Grammar: delay (nseconds);
Description: The Delay function enables a setup program to execute a specified number of seconds. Other tasks running simultaneously with InstallShield are still working properly when InstallShield is delayed.
parameter:
NSECONDS
Specifies the number of seconds that the program is delayed.
return value:
0: Indicates that the function successfully delayed the execution of the script.
<0: Indicates that the function failed to delay the execution of the script.
18.3 Launchapp
Syntax: launchapp (szcommand, szcmdline);
Description: The Launchapp function allows you to run another application in the script. The application and script run simultaneously. InstallShield does not have control over the running application and cannot determine if the running application is successful. Running applications and other runs like when you start installshield. You can run any applications that you can run in your operating system in InstallShield.
parameter:
SZCommand
Specifies the full qualification of the application to run. If you specify a file name without a path, INSTALLSHIELD is found in the Windows folder, in the Windows folder, in the Windows system folder and columns in the folder in the environment variable PATH.
If the application's full qualification includes long folder names and / or a long file name, pass it to longpathtoquote before passing SZCommand to LaunchappandWait.
Szcmdline
Specifies the command line parameter (if any) that passes the application that passes to the SZCommand identity. If there is no parameters, it is late to be an empty string.
return value:
0: Launchapp successfully runs the application.
<0: Launchapp failed or failed to run the application.
annotation:
• The installation process continues after the application is running. Applications can run even after the installation script is terminated.
· You can also use the FindWindow and SendMessage functions to control or send messages to run. If you want to run a DOS application in a Window, you can provide a PIF (Program Information File) that is the same as the DOS application. In the PIF file, you specify a window mode that the application runs under. • When you run a DOS program, you cannot determine the return result dos_errorlevel. However, you can put a DOS application into a batch file, let the batch file to identify errors and create another file containing the return error code. Then you can read the file and determine the error code returned from the DOS application.
· Launchapp uses the Windows API's createProcess to run the application.
18.4 Launchappandwait
Syntax: Launchappandwait (Szprogram, Szcmdline, Lwait);
Description: The LaunchappandWait function runs an application that is specified by SzProgram with SZCMDline specified command line parameters. The third parameter, LWAIT indicates whether it is necessary to wait until the running application is terminated until the run.
A installer can only monitor applications specified by SZProgram; if the application is running other applications or processes, the installer cannot monitor them. Therefore, the installer will continue after the end of the first application, even if other applications running by the first application is still running. Note If the running application is terminated, the installer will complete the application that is unlimited to wait.
parameter:
Szprogram
Specifies the file name of the application to be run. It is recommended to specify the full path and file name of the application. If you don't include a path, InstallShield will locate the file using the same lookup order used by the Windows API function CreateProcess. If the file is not found in these locations, the function will fail.
If the application's full qualification includes long folder names and / or a long file name, pass it to longpathtoquote before passing SZCommand to LaunchappandWait.
Szcmdline
Specifies the command line parameters of the delivered application. In order to run an application without command line parameters, pass an empty string.
lwait
Specifies whether the installer will terminate if you want to wait for a run. One of the following predefined constants in this parameter location:
NOWAIT: Specifies that the installer continues immediately after running the application, the application will run at the same time. Note Use this parameter to equivore the call function launchapp.
Wait: Specifies the installer to wait until the application running by the function is terminated.
return value:
1: Indicates that the application is successful.
<0: Indicates that the application failed to run.
annotation:
· InstallShield installer uses the function creageprocess. After installshield runs the application, it looks up the window handle of the loaded application. If it finds a window handle, it will wait until the application window disappears until the application window disappears.
• The installer cannot monitor an application that does not create a window. If the specified application does not create a window, the installer continues immediately after running the application. Note that the application's window does not need to be visible, but it must exist so that the installer waits.
Some applications are trying to load DLLS and cannot run correctly when those DLLs cannot be positioned. To ensure that an application can find the DLLS it needs, it is necessary to change the directory containing the executable application before calling LaunchappandWait. To change the current directory, call the ChangeDirectory function.
• If the running application is terminated, the installer completes unlimited operation.
· LaunchappandWait runs the DOS program with a full-screen DOS window. To run a DOS program with a different type of window, you must call the Windows API directly. 18.5 Unusedll
Grammar: unusedll (szdllname);
Note: The unusell function uninstalls a DLL from memory. Unusedll reduces the lock count of the DLL. When the lock count is equal to 0, INSTALLSHIELD uninstalls the DLL. Each of the calls to the USEDLL must have a corresponding call for unusell, so the DLLS will not leave the system resources when they no longer need it. Once you uninstall a DLL, you cannot call the functions in the DLL.
Microsoft Windows system DLLs, such as user.exe, user32.dll, gdi.exe, gdi32.dll, krnl386.exe, krnl286.exe, and kernel32.dll, automatically loaded and uninstalled by Windows. Do not call usedll and unusedll to load and uninstall these DLLs.
parameter:
Szdllname
Specifies the file name of the DLL. This parameter does not include a path.
return value:
0: Indicates that the function successfully unlocked and uninstall the DLL from the memory.
<0: Indicates that the function failed to unlock and uninstall the DLL.
annotation:
If the script exits or terminates before uninstalling the DLL with unusell, the DLL will be locked in memory. If you try to access the DLL again, your script may fail. You must remove the DLL from memory by restarting Windows.
18.6 USEDLL
Syntax: usedll (szdllname);
Description: The USEDLL function puts a DLL into memory. After the DLL has been loaded into memory, your installer script can call the function in the DLL. Note If the DLL specified by szdllname requires other DLLs, those DLLs must be in a folder, which is trying to load them from this folder. It is normal when it is the current directory. To ensure that those DLLs can be positioned, calling ChangeDirectory before calling Usedll to change the location where the current directory to those DLLs. If you can't do it, you may not be installed correctly.
Each time you put a DLL into memory, the DLL's lock count is increased. The number of lock counts calculates the number of applications that use the DLL. When you no longer use the DLL, you must call unusedll immediately to uninstall it. If you don't unload the DLL that is no longer needed, the DLL will remain in memory when no application needs it, so waste system resources. Each call in the script must have a corresponding unusell call.
Microsoft Windows system DLLs, such as user.exe, user32.dll, gdi.exe, gdi32.dll, krnl386.exe, krnl286.exe, and kernel32.dll, automatically loaded and uninstalled by Windows. Do not call usedll and unusedll to load and uninstall these DLLs.
parameter:
Szdllname
Specifies the DLL name to be loaded. If you do not specify an extension, InstallShield assumes that the file extension is .dll or .exe. It is recommended that this parameter includes a path, but it is only optional. If this parameter does not specify a DLL path, InstallShield will use the same lookup sub-sequence used by the Windows API function LoadLibrary to find the DLL.
More information about finding the order can be viewed for the Windows API function.
To include DLL in your installation, add it to the appropriate subfolders of the Language Independent folder in the installation file pane. InstallShield will compress it into your installation. When setup.exe is executed, it automatically decompresses and copies your installation to the temporary directory specified by Supportdir. Then you can add a DLL file name to Supprotdir to point to the DLL, as shown below: szdllname = supportdir ^ "MyDLL.DLL";
Usedll (szdllname);
If you don't place your DLL into your installation (insert it into the appropriate folder in the installation file pane), you can distribute the file with your application file, then load it from the target system. . However, if you do this, you must specify that you install the DLL installed to make your installer to point to it. You must also make sure your installer will not try to load it before the DLL is transferred to the target system.
return value:
0: Indicates that the function successfully puts the DLL into memory.
<0: Indicates that the function failed to load the DLL into memory.
annotation:
· If the USEDLL fails, the biggest possibility is that the DLL is not found. If so, make sure the parameter SZDLNAME specifies the correct path.
· Another common use of DLL errors and DLL dependence: DLLs accessed by the DLL you put into. If your DLL access is not loaded or not found, your DLL call may fail. If this happens, make sure that other DLLs exist on the system and they are accessible.
• If the script exits or terminates before using unusedll correctly uninstall the DLL, the DLL will be locked in memory. If you try to access the DLL again, the script may fail. You must remove the DLL from memory by restarting Windows.
