FileMove() function

Moves a source file to a destination file and returns a status result. It can be also used to rename a file. This function may take a longer time to execute and executes in multiple stages:

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

2. FileMove() function executes the move procedure in the background, InTouch scripting continues execution while the file moving is in progress. You can monitor the file moving progress with an integer tag.

3. FileMove() function returns a file move result, indicating success or failure of the file moving procedure.

Do not use the FileMove() function in asynchronous QuickFunctions.

Syntax

result = FileMove (sourcefile, destfile, progresstag)

Parameters

sourcefile

Full path and file name of the file to be moved. A literal string value, message tagname, or string expression. You can use the wildcard characters (* and ?) in this parameter to move 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 moving progress. A literal string value, message tagname (such as a message tag containing the value "IntTag") or string expression. The values have following meaning:

0 - FileMove() procedure is still in progress

1 - FileMove() procedure has completed successfully

-1 - FileMove() procedure completed with errors

Return value

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

1 - FileMove() function successfully called

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

-1 - Error when calling the FileMove() function. Possible errors are attempts to move a non-existent file.

Example(s)

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

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

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

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

This script moves 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=FileMove(LogFile, "c:\results\log" + $DateString + $TimeString + ".txt", "Monitor");