SdRMFilesInUse

InstallShield 2014 » InstallScript Language Reference

Project: The InstallScript MSI project type support the SdFilesInUse function.

The SdRMFilesInUse function displays a dialog that includes a list box containing a list of the applications that are open and are locking files. The dialog also includes two radio buttons that allow end users to specify whether the installation should attempt to use the Restart Manager to shut down the applications that are locking files or overwrite the locked files (which most likely results in the need for a reboot to complete the installation).

Typically, the OnRMFilesInUse event handler displays this dialog in an InstallScript MSI installation as a response to an INSTALLMESSAGE_FILESINUSE message sent by the Windows Installer. When this occurs, the Windows Installer provides to the installation the list of applications that are locking files. The list of applications are passed through the szMessage parameter to the OnRMFilesInUse event. The event passes this information to the SdRMFilesInUse function through the szMessage parameter. The event then passes the return value from the function as the return value of the event, which causes the Windows Installer to act appropriately.

Project: The SdRMFilesInUse dialog can also be called manually in InstallScript projects and in InstallScript MSI projects; however, the installation must provide the list of applications that are locking files through the nvlistApps parameter, and it must handle the return value appropriately. It must also interact with the Restart Manager to attempt to shut down applications that are locking files if the end user selects the corresponding option on the SdRMFilesInUse dialog.

Syntax

SdRMFilesInUse ( byval string szTitle, byval string szMsg, byval string szFilesInUse, byref LIST nvlistApps, byref BOOL bvCloseRestart );

Parameters

SdRMFilesInUse Parameters
Parameter	Description
szTitle	Specifies the title of the dialog. To display the default title (Files in Use), pass a null string (“”) in this parameter.
szMsg	Specifies the message to display in the dialog. To display the default instructions for this dialog, pass a null string (“”) in this parameter.
szFilesInUse	When SdRMFilesInUse is called by the OnRMFilesInUse event handler in an InstallScript MSI installation, this parameter specifies the list of applications that the Windows Installer found to be locking files. The function parses this string in order to display the list of applications in the dialog's list box. If you manually call SdFilesInUse, pass an empty string ("") in this parameter. Note that if nvlistApps is a valid string list, this parameter is ignored.
nvlistApps	When SdRMFilesInUse is called by the OnRMFilesInUse event handler in an InstallScript MSI installation, this parameter is specified as an uninitialized list variable—that is, a variable with a value of 0. If you manually call SdRMFilesInUse, specify a string list of applications that are locking files and that should be displayed in the dialog. Each string in the list indicates one application. (Use the ListCreate function and associated list functions to create and initialize the string list.) Note: You must provide a variable for this parameter; you cannot specify a literal value.
bvCloseRestart	Indicates the default for the aforementioned radio buttons. TRUE indicates that the close-and-restart-applications radio button is the default. FALSE indicates that the ignore-and-reboot-later radio button should be the default. Project: In InstallScript MSI projects, the OnRMFilesInUse event sets the value of bvCloseRestart based on the current value of the Windows Installer property called MSIRESTARTMANAGERCONTROL Property. When the SdRMFilesInUse function returns, this value indicates which radio button the end user selected—TRUE for the close-and-restart-applications option or FALSE for the ignore-and-reboot-later option. Note that the function also returns the same information in the return value of the function.

Return Values

SdRMFilesInUse Return Values
Return Value	Description
IDOK	Indicates that the end user selected the close-and-restart-applications option and then clicked the OK button.
IDIGNORE (5)	Indicates that the end user selected the ignore-and-reboot-later option and then clicked the OK button. Note that this value can be returned even though the dialog does not include an Ignore button.
IDCANCEL	Indicates that the end user clicked the Exit button. Note: Note that unlike other script dialogs, this dialog does not call the OnCanceling event handler when the user clicks the Exit button. Therefore, if you are calling this function manually, you must handle this return value manually in order to display the Cancel Setup dialog.

SdRMFilesInUse

InstallShield 2014 Help Library

May 2014