XCopyFile

InstallShield 2019 » InstallScript Language Reference

The XCopyFile function copies one or more files from a source directory to a target directory. The function creates and logs the target directory if necessary. This function can copy subdirectories as well as files. XCopyFile creates subdirectories on the target directory if necessary when the constant INCLUDE_SUBDIR is passed in the parameter nOp.

If you use this function to transfer files to WINSYSDIR64, you must first disable file system redirection using WOW64FSREDIRECTION. Otherwise, files being transferred to WINSYSDIR64 are incorrectly redirected to the 32-bit SysWOW64 folder. Since some Windows functionality that could be used by the installation requires that redirection be enabled to work, Windows documentation recommends that you disable redirection only for as long as necessary. It is recommended that you then enable file system redirection as soon as you have completed transferring the necessary files to WINSYSDIR64. To learn more, see Targeting 64-Bit Operating Systems with InstallScript Installations.

You cannot rename files using XCopyFile. To rename a file during a file copy operation, use the CopyFile function.

Tip • It is strongly recommended that you disable the Cancel button using the Disable function before calling the XCopyFile function if the status dialog is displayed during the copy. If you do not disable the Cancel button and the end user cancels during the copy file operation, the OnCancelling event handler is not called. Instead, the copy file operation returns a failure error code, which your script must handle by calling the appropriate event and then relaunching the copy file operation. You can enable and disable the Cancel button using the Enable and Disable functions.

Note • If you use unqualified file names and set values for SRCDIR and TARGETDIR when using XCopyFile, save the current values using VarSave before calling XCopyFile and then restore them using VarRestore.

Syntax

XCopyFile ( szSrcFile, szTargetPath, nOp );

Parameters

XCopyFile Parameters

Parameter

Description

szSrcFile

Specify which files to copy. If the file specified is qualified—that is, if it includes a path—XCopyFile copies the file from the specified location. If szSrcFile contains an unqualified file name—without path information—XCopyFile copies from the folder that is identified by the system variable SRCDIR. To copy multiple files, use wildcard characters in this parameter.

You can specify a valid URL in this parameter. If you pass a CGI or ASP request (for example, "http://www.mydomain.net/login.asp?name=Me&pwd=wow"), the response is sent to the file that is specified in the szTargetPath parameter. When passing a URL, do not include wildcard characters. To check the validity of a URL, call the following:

Is (VALID_PATH, szURL);

szTargetPath

Specify the directory to which the files that are specified by szSrcFile should be copied. If this parameter contains a null string (""), the files are copied to the directory that is specified by the system variable TARGETDIR (in InstallScript installations) or INSTALLDIR (in Basic MSI and InstallScript MSI installations).

You cannot specify a URL in this parameter. If you do, the function fails and returns ISERR_INVALID_ARG.

nOp

Specify the type of copy operation to perform. Pass one of the following predefined constants in this parameter. To specify more than one option, combine constants with the OR (|) operator.

•

COMP_NORMAL—Copies files to the target system, updating existing same-named files regardless of date, time, or version information.

•

COMP_UPDATE_SAME—Update the files even if the date, time, or version of the source file is identical to the target file. You must also specify either COMP_UPDATE_DATE or COMP_UPDATE_VERSION with this constant. Otherwise, this constant is ignored.

•

COMP_UPDATE_DATE—Updates the files based on the file date and time. This constant updates the file if the source file is newer than the target file.

•

COMP_UPDATE_VERSION—Updates the files based on the file version. This constant updates the file if the source file is newer than the target file. If the file version does not exist in both the source and the target files, date and time are used for comparison. If the file version does not exist for only one file, InstallShield treats the file containing version information as the newer file.

•

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 SHAREDFILE option, combining them with the bitwise OR operator ( | ).

•

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

The SHAREDFILE option causes XCopyFile 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, the installation creates the counter and sets it to 1. If the shared file already exists in the target directory but has no reference counter, the installation creates the counter and initializes it to 2 as a precaution against accidental removal during uninstallation.

•

LOCKEDFILE—Causes XCopyFile 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 the installation 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 XCopyFile to handle locked files that are not shared.

•

EXCLUDE_SUBDIR—Specifies to exclude subdirectories contained in the source path. Note that empty subdirectories are not copied.

•

INCLUDE_SUBDIR—Specifies that subdirectories below the source path must also be copied.

•

CLEAR_FILE_ATTR—Specifies to clear the attributes of the copied file. When you use this parameter, the file in the target folder does not have any file attributes set by default. If you do not use this parameter, XCopyFile uses the attributes of the original file for the copied file.

Return Values

XCopyFile Return Values
Return Value	Description
0	Indicates that the function successfully copied the files.
ISERR_INVALID_ARG	Indicates that an invalid argument was passed to the function.
All other negative values	Indicates that the function was unable to copy the files. You can obtain the error message text associated with a large negative return value—for example, -2147024891 (0x80070005)—by calling FormatMessage.

Additional Information

After you modify .ini files with WriteProfString, you must flush the cache buffer before using XCopyFile. All .ini files are cached; this behavior can cause a delay in writing changes to the specified files. This in turn can interfere with subsequent file operations. To avoid this problem, simply call WriteProfString with null parameters to force Windows to write the data to the .ini file immediately, as show below:

WriteProfString ("C:\\Test.ini", "Windows", "KeyboardDelay", "100");

// null string ("") for all four parameters

WriteProfString ("", "", "", "");

// XCopyFile should now have access to updated file.

XCopyFile ("C:\\Test.ini", "C:\\Temp", EXCLUDE_SUBDIR);

XCopyFile

InstallShield 2019 Help Library

April 2019