CopyFile

InstallShield 2020 » InstallScript Language Reference

The CopyFile function creates a copy of the file specified by szSrcFile. The new file is given the name specified by szTargetFile. You must specify the name of the file that you want to copy onto the target location in the szTargetFile parameter of this function in order for the function to work.

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.

Tip:It is strongly recommended that you disable the Cancel button using the Disable function before calling the CopyFile 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:For file transfer, XCopyFile is an alternative to CopyFile. XCopyFile can perform version checking, mark locked .dll and .exe files for update after system restart, and increment registry reference counters for shared .dll and .exe files. You can also use XCopyFile to include subdirectories.

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

If the target directory does not exist, CopyFile creates it.

You cannot rename groups of files by using wildcards with CopyFile. You can, however, rename a single file using CopyFile.

Syntax

CopyFile ( szSrcFile, szTargetFile );

Parameters

CopyFile Parameters

Parameter

Description

szSrcFile

Specify the name of the file to copy. If the file name is qualified—that is, if it includes a path—CopyFile copies the file from the specified location. If szSrcFile contains an unqualified file name—without path information—CopyFile copies from the directory that is identified by the system variable SRCDIR. To copy groups of files, use wild card 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 szTargetFile parameter. When passing a URL, do not include wildcard characters. To check the validity of a URL, call the following:

Is (VALID_PATH, szURL);

szTargetFile

Specify the name to give to the copy of the file that is identified by szSrcFile. If the file name is qualified—if it includes a path—CopyFile copies the file to the location specified by the path. If szSrcFile contains an unqualified file name—without path information—the copy is created in the directory specified by the system variable TARGETDIR (in InstallScript installations) or INSTALLDIR (in Basic MSI and InstallScript MSI installations). If the target directory does not exist, it is created.

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

Note:When a wildcard character is included in the file name that is specified by szSrcFile, the file name part of szTargetFile is not ignored; instead, the szTargetFile value is treated as the target path to which each source file is copied to with its existing name. For example, the following code copies files to a folder named File.txt on the D drive:

CopyFile ("C:\\*.*", "D:\\File.txt");

If szTargetFile specifies an unqualified file name, the files are copied to the directory that is specified by TARGETDIR (in InstallScript installations) or INSTALLDIR (in Basic MSI and InstallScript MSI installations). For that reason, CopyFile cannot be used to copy and rename a group of files. The source and target directories must be different when szSrcFile contains one or more wildcard characters.

Return Values

CopyFile Return Values

Return Value

Description

0

Indicates that the function successfully copied the files from source to target directory.

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 requested file.

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 or WriteProfInt, you must flush the cache buffer under before using CopyFile. All .ini files are cached. This behavior can cause a delay in writing changes to the specified files. This delay can interfere with subsequent file operations. To avoid this problem, call WriteProfString with null parameters to force Windows to write the data to the .ini file immediately, as shown below:

    WriteProfString ("C:\\Test.ini", "Windows",

    "KeyboardDelay", "100");

    

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

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

    

    // CopyFile should now have access to updated file.

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

See Also