FileCopy() function

Copies a source file to a destination file and returns a status result. This function may take a longer time to execute and is executed in multiple stages:

1. FileCopy() function is called and an immediate result is returned, indicating success or failure of the file copy initialization.

2. FileCopy() function executes the copy procedure in the background, and InTouch scripting continues execution while the file copying is in progress. You can monitor the file copying progress with an integer tag.

3. FileCopy() function returns a file copy result, indicating success or failure of the file copy procedure.

If the destination folder is not available (i.e. another computer on the network), the function waits for up to 10 seconds to time out, and then posts a message in the Logger.

Note: Do not use the FileCopy() function in asynchronous QuickFunctions.

Syntax

result = FileCopy (sourcefile, destfile, progresstag)

Parameters

sourcefile

Full path and file name of the file to be copied. A literal string value, message tagname, or string expression. You can use the wildcard characters (* and ?) in this parameter to copy just files matching a specified criteria. The path name can also be a UNC path name.

destfile

Full path and file name (or just path name) of the destination. A literal string value, message tagname, or string expression. The path name can also be a UNC path.

progresstag

Name of an integer tag enclosed in double quotes that will contain a value indicating the file copy progress. A literal string value, message tagname (such as a message tag containing the value "IntTag.Name") or string expression. The values have following meaning:

0 - FileCopy() procedure is still in progress.

1 - FileCopy() procedure has completed successfully.

-1 - FileCopy() procedure completed with errors.

Return value

A value of -1, 0, or 1 indicating the following:

1 - FileCopy() function successfully called.

0 - Error when calling the FileCopy() function because another FileCopy() procedure is already in progress.

-1 - Error when calling the FileCopy() function because of a non-existent source file or the destination is read only.

Example(s)

This script copies the file c:\MyData\output.log to the directory d:\archive and renames the file to output.txt. The progress of the file copy is written to the integer tag Monitor.

Status=FileCopy("c:\MyData\output.log","d:\archive\output.txt","Monitor");

This script copies all files with file ending .txt in the c:\ root directory to the destination directory c:\Backup.

Status=FileCopy("c:\*.txt", "c:\Backup", "Monitor");

This script copies a file whose full path and file name is contained in the message tag LogFile to the destination directory c:\results\ and renames it to logxxx.txt where xxx is a timestamp.

Status=FileCopy(LogFile, "c:\results\log" + $DateString + $TimeString + ".txt", "Monitor");