VerUpdateFile

InstallShield 2016 » InstallScript Language Reference

The VerUpdateFile function uses the version information of a specified file to determine whether or not to install the file on the target directory. VerUpdateFile gets the file name specified in szFileName.

VerFindFileVersion uses the following search algorithm to find the file (searches the folders in the following order):

Windows folder

Windows system folder

The folder specified by the TARGETDIR system variable (in InstallScript installations) or the INSTALLDIR system variable (in Basic MSI or InstallScript MSI installations)

The folders specified by the PATH environment variable

The folder from which Setup.exe is running

VerUpdateFile then compares the version of the file with the same name in SRCDIR (the source file), if it exists, with the version of the target file. If the source file has a more recent version number than the target file, the target file is replaced by the source file. If the target file does not exist, InstallShield copies the source file to the target location.

When the SHAREDFILE or LOCKEDFILE option is used in the parameter nUpdateFlag and .dll or .exe files to be updated are in use by the system, renamed copies of the source files are transferred to the target system and the system variable BATCH_INSTALL is set to TRUE. Then, when RebootDialog or SdFinishReboot is called at the end of the setup and the system is restarted, the locked files are updated. For more information on updating locked files, see RebootDialog and SdFinishReboot. The system variable BATCH_INSTALL can be tested to determine if locked .dll or .exe files were encountered. You cannot use the SHAREDFILE and LOCKEDFILE options simultaneously-you must use one or the other.

For file transfer, preferable alternatives to VerUpdateFile may be XCopyFile, which can perform version checking, mark locked .dll and .exe files for update after system reboot, and increment registry reference counters for shared .dll and .exe files.

Syntax

VerUpdateFile ( szFileName, nUpdateFlag, svInstalledFilePath );

Parameters

VerUpdateFile Parameters

Parameter

Description

szFileName

Specifies the qualified or unqualified name of the file to update. If the name is unqualified (that is, if it does not include a drive designation or path), InstallShield searches the Windows or Win95 directory, the System directory, the directories specified by the PATH environment variable, and then the path of the InstallShield executable file for a matching file. VerUpdateFile takes the file name portion of szFileName and uses it to identify the file in SRCDIR that is used as the source file.

nUpdateFlag

Specifies whether the file is updated unconditionally or updated only if the version of the target file found is older than the version of the source file. Pass one of the following predefined constants in this parameter. You can combine the constant SHAREDFILE with one of the other constants using the bitwise OR operator ( | ). However, you cannot combine SHAREDFILE and LOCKEDFILE.

•

LOCKEDFILE—Causes VerUpdateFile to record locked .dll and .exe files for update when Windows or the system is rebooted. A locked file is a file that is in use by an application or the system when InstallShield attempts to access or update the file. The LOCKEDFILE option works like SHAREDFILE except that LOCKEDFILE does not create registry entries or modify the registry reference counter. You cannot use the LOCKEDFILE option when using the SHAREDFILE option. There are some unshared files (such as shell extensions) for which the script writer does not want a registry entry and reference counter. These files should never be uninstalled, except by the application itself. LOCKEDFILE allows VerUpdateFile to handle locked files that are not shared.

•

SHAREDFILE—Combines shared and locked file handling by causing VerUpdateFile to treat all files as shared, and to record locked .dll and .exe files for update when Windows or the system restarts. See RebootDialog and SdFinishReboot.

The SHAREDFILE option causes VerUpdateFile to treat all files as shared files and increment the registry reference counter by one when the file exists in the target directory and it has a reference count greater than 0. If the shared file does not exist in the target directory and it has no reference counter, InstallShield creates the counter and sets it to 1. If the shared file already exists in the target directory but has no reference counter, InstallShield creates the counter and initializes it to 2 as a precaution against accidental removal during uninstallation.

nUpdateFlag (continued)

•

SELFREGISTER—Carries out the self-registration process immediately, when using the “non-batch method” of installing self-registering files.

If you have called Enable(SELFREGISTERBATCH), this option queues up self-registering files for registration. The files are registered once Do(SELFREGISTRATIONPROCESS) is called, when using the “batch method” of installing self-registering files.

Always use SELFREGISTER together with the constant SHAREDFILE, using the bitwise OR operator ( | ).

•

VER_UPDATE_ALWAYS—Updates the file regardless of the version numbers.

•

VER_UPDATE_COND—Updates the file only if the file being replaced is an older version.

svInstalledFilePath

Returns the fully qualified name of the file that was installed. If the file you want to replace is in use, the file is installed to the same directory with a modified name. InstallShield uses a tilde (~) character to replace the first character of the file's extension.

For example, if you are updating the file Shell.dll and the target file is locked, the source file is copied to the target directory as Shell.~ll. This name is returned in the parameter svInstalledFilePath.

If the SHAREDFILE option is used in the parameter nUpdateFlag and locked files are properly committed for update when Windows or the system restarts, the ~ modified name versions of the files are deleted when the update takes place.

Return Values

VerUpdateFile Return Values
Return Value	Description
FILE_INSTALLED (0)	Indicates that the function successfully installed the file. This constant is equal to 0 (zero). All other return values are less than zero (< 0).
FILE_IS_LOCKED (-4)	Indicates that the existing file is in use by Windows and cannot be replaced. The new file is copied to the same directory with a new name, as described above.
FILE_NO_VERSION (-8)	Indicates that the file was found, but it did not contain version information in it. File update is not performed.
FILE_RD_ONLY (-5)	Indicates that the existing file is write-protected. You must reset the read-only bit in the destination file before proceeding with the setup, and then attempt to install the file again.
FILE_SRC_EQUAL (-9)	Indicates that the file you want to install has the same version as the existing file. File update is not performed if the VER_UPDATE_COND flag is set.
FILE_SRC_OLD (-7)	Indicates that the file you want to install is older than the existing file. File update is not performed if the VER_UPDATE_COND flag is set.
OUT_OF_DISK_SPACE (-6)	Indicates that the function cannot create the file due to insufficient disk space on the destination drive. File update is not performed.
-51	A self-registering file did not register successfully.
OTHER_FAILURE (-1)	Indicates an unspecified error occurred. File update is not performed.

VerUpdateFile

InstallShield 2016 Help Library

May 2017