File System - Move

Declaration

<AMFILESYSTEM ACTIVITY="move" MODE="text (options)" SOURCE="text" DEST="text" RESULTDATASET="text" SUBFOLDERS="YES/NO" KEEPFOLDERSTRUCT="YES/NO" ARCHIVETURNOFF="YES/NO" OVERWRITE="YES/NO" ISNEWER="YES/NO" ONLYIFEXIST="YES/NO" OVERWRITEREADONLY="YES/NO" OVERWRITEHIDDEN="YES/NO" EXCLUDE="text" RE="YES/NO" ISNEWERTHAN="%DateSerial+TimeSerial%" ISOLDERTHAN="%DateSerial+TimeSerial%" ATTRFILTER="+r+a+s+h+c+e" />

Related Topics    

Description

Moves a single or multiple files or folders from a source path to a destination path. To specify more than one file/folder, use wildcard characters (* or ?). To specify multiple wildcard masks, separate them with a pipe symbol (for example, c:\*.txt|c:\*.bak). If an attempt is made to move a file/folder to a destination folder that does not exist, it will be created during runtime. This activity can optionally rename and/or move a file/folder to a different location by specifying a new destination path and file name/foldername.

Practical Usage

Commonly used to move one or more files or complete folder structures to another location, drive, or share on the network. Can be used to move files generated by other Automate activities and/or overwrite an existing copy of a destination file.

Parameters

General

Property Type Required Default Markup Description
File/Folder Text (options) Yes File
  • MODE="file"
  • MODE="folder"
 Indicates what objects this activity should move. Parameters vary depending on the option selected. The available options are:
  • File (default) -  One or more files will be moved.
  • Folder - One or more folders will be moved.
Source Text Yes (Empty)
  • SOURCE="c:\sourcefolder\file.txt"
  • SOURCE="c:\sourcefolder\*.txt"
  • SOURCE="c:\folder\*.txt|c:\folder\*.bak"
  • SOURCE="c:\foldername\subfoldername"
 The path of the files/folders to move. This can be a fully qualified path and file name (preferred) or a single file (requires use of the File System - Change folder activity). Wildcard characters (for example, * or ?) may be used to specify all files matching a certain mask. Multiple files and/or file masks can be specified by separating each entry with a pipe character (|) (for example, c:\temp\*.txt|c:\backup\*.bak). See File Masks & Wildcards for more details.
NOTE:
  • Files with invalid paths are ignored at runtime.
  • The prefix \\?\ will prepend paths exceeding 260 characters.
Destination Text Yes (Empty)
  • DEST="c:\destfolder\file.txt"
  • DEST="c:\destfolder\*.txt"
  • DEST="c:\destfolder\*.*"
  • DEST="c:\destfolder\"

The destination folder and/or file name in which to move the source files/folders. If the destination folder does not exist, it will be created during runtime.

NOTE: The prefix \\?\ will prepend paths exceeding 260 characters.
Create and Populate Dataset with Result Information Text No (Empty) RESULTDATASET="DatasetName" The name of the dataset to create and populate with results of this operation. More information about the individual fields that this dataset creates can be found below under Datasets.

File Options

Property Type Required Default Markup Description
Include subfolders Yes/No No No SUBFOLDERS="YES" If selected, denotes that, if present, subfolders should be searched for files matching the mask specified in the Source parameter. If disabled (default), subfolders are ignored. This parameter is available only if the Mode parameter is set to File.
Preserve folder structure Yes/No No Yes KEEPFOLDERSTRUCT="NO" If selected (default), subfolders found in the source folder will be created in the destination folder and source files will be moved into their respective folders rather than directly into the root of the target folder specified in the Destination parameter. If disabled, source files will be moved into the root of the target folder instead. This parameter is active only if the Include Subfolders parameter is selected.
Merge if folder exists Yes/No No No MERGEFOLDER="yes" If selected, specifies that, if a matching folder already exists in the destination, the source folder and all its contents will be merged onto that folder. If disabled (default) the merge will not take place, however, a runtime error will occur as a result.  This parameter is available only if the Mode parameter is set to Folder.
Overwrite if exists Yes/No No No OVERWRITE="YES"

If selected, matching destination files/folders will be overwritten. If disabled, no files/folders will be overwritten, however, an error will occur as a result.
Only if newer Yes/No No No ISNEWER="YES" If selected, only source files/folders that are newer than those that match in the destination folder will overwrite existing files. Disabled by default. This parameter is active only if the Overwrite if exists parameter is selected.
Only if exists in destination Yes/No No No ONLYIFEXIST="YES" If selected, only matching files/folders that already exist in the destination will be overwritten. All other files, regardless of whether they match the mask or other parameter settings will be bypassed. This parameter is disabled by default and is active only if the Overwrite if exists parameter is selected.
Overwrite read-only files Yes/No No No OVERWRITEREADONLY="YES" If selected, matching files/folders marked with the read-only attribute that already exist in the destination will be overwritten. By default, read-only files are not overwritten. This parameter is active only if the Overwrite if exists parameter is selected.
Overwrite hidden files Yes/No No No OVERWRITEHIDDEN="YES" If selected, matching files/folders marked with the hidden attribute that already exist in the destination will be overwritten. By default, hidden files are not overwritten. This parameter is active only if the Overwrite if Exist parameter is selected.
Turn archive attribute off Yes/No No No ARCHIVETURNOFF="YES" If selected, specifies that the archive attribute of the source files should be switched OFF. The Windows archive attribute is generally used to track whether a file has been backed-up. Turning the source file's archive attribute off indicates to many backup programs that the file has already been backed-up. This parameter is disabled by default and only available if the Mode parameter is set to File.
Exclude mask Text No (Empty)
  • EXCLUDE="*.txt"
  • EXCLUDE="*.txt|*.bak"
  • EXCLUDE="c:\foldename"
 Causes this activity to omit folders/files matching the masks specified. Folder/File names or wildcard masks may be used. Multiple entries may be specified by separating them with a pipe character (|) (for example, *.txt|*.bak|*.png).
Regular expression Yes/No No No RE="YES" If selected, specifies that the value entered in the Exclude mask parameter will be interpreted as a regular expression. If disabled (default), the value will be interpreted as normal readable text.
Only if newer than Date No (Empty) ISNEWERTHAN="%DateSerial(2001,10,12) + TimeSerial(00,00,00)%" Causes this activity to only move files if the source is newer than the date/time specified. If this parameter is left blank or not included, the date of the files will be ignored (excluding Only if newer parameter). Click the Custom button to select from a list of pre-defined date parameters. Enable the Expression checkbox to allow entry of a date/time expression.
Only if Older Than Date No (Empty) ISOLDERTHAN="%DateSerial(2001,10,12) + TimeSerial(00,00,00)%" Causes the action to only move files if the source is older than the date/time specified. If this parameter is left blank or not included, the date of the files will be ignored (excluding Only if newer parameter). Click the Custom button to select from a list of pre-defined date parameters. Enable the Expression checkbox to allow entry of a date/time expression.

File Filter

Property Type Required Default Markup Description
Attributes Text (options) No Doesn't matter ATTRFILTER="+R+A-H" (compress read-only & archive files but not hidden files) Instructs the activity to filter which files to act on, based on whether the file's original attribute settings match the attribute settings specified in this parameter. In Task Builder's visual mode, drop-down boxes are provided within the activity's settings to assist in the selection of attribute settings. In Task Builder's AML mode, a text item must be entered that contains the original attribute mask of the files you wish to affect. For example, if Read-only attribute is set to Off (in visual mode) or -R (in AML mode) , only source files with the Read-only attribute turned off are affected. Source files with Read-only attribute turned on will be ignored. The available options are:
  • Read-only attribute is - Specifying On or +R includes files with this attribute turned on. Specifying Off or -R includes files with this attribute turned off. Specifying Doesn't matter (default) or excluding the letter ignores this attribute.
  • Archive attribute is - Specifying On or +A includes files with this attribute turned on. Specifying Off or -A includes files with this attribute turned off. Specifying Doesn't matter (default) or excluding the letter ignores this attribute.
  • System attribute is - Specifying On or +S includes files with this attribute turned on. Specifying Off or -S includes files with this attribute turned off. Specifying Doesn't matter (default) or excluding the letter ignores this attribute.
  • Hidden attribute is- Specifying On or +H includes files with this attribute turned on. Specifying Off or -H includes files with this attribute turned off. Specifying Doesn't matter (default) or excluding the letter ignores this attribute.
  • Compression attribute is - Specifying On or +C includes files with this attribute turned on. Specifying Off or -C includes files with this attribute turned off. Specifying Doesn't matter (default) or excluding the letter ignores this attribute.
  • Encrypted attribute is - Specifying On or +E includes files with this attribute turned on. Specifying Off or -E includes files with this attribute turned off. Specifying Doesn't matter (default) or excluding the letter ignores this attribute.

Description

Error Causes

On Error

Additional Notes

Datasets

A dataset is a multiple column, multiple row container object. This activity creates and populates a dataset containing a specific set of fields. The table below describes these fields (assuming the dataset name assigned was "theDataset").

Name Type Return Value
theDataset.Source Text The path and file name of the source folder/ file.
theDataset.Size Number The size of the folder/file (in kB).
theDataset.Destination Text The path and file name of the destination file.
theDataset.Result True/False Returns TRUE if result of activity is a success, otherwise, returns a FALSE.
theDataset.Message Text The textual information associated to the result.

Examples

NOTE:
  • The sample AML code below can be copied and pasted directly into the Steps Panel of the Task Builder.
  • Parameters containing user credentials, files, file paths, and/or other information specific to the task must be customized before the sample code can run successfully.

Example 1

This sample task moves files from one folder to another folder and then creates and populates a dataset with the results.

Copy 
<AMFILESYSTEM ACTIVITY="move" SUBFOLDERS="yes" KEEPFOLDERSTRUCT="yes" OVERWRITE="yes" ISNEWER="yes" ONLYIFEXIST="yes" OVERWRITEREADONLY="yes" OVERWRITEHIDDEN="yes" ARCHIVETURNOFF="yes" EXCLUDE="text" RE="yes" ISNEWERTHAN="%DateSerial(2013,03,15)+TimeSerial(13,30,27)%" SOURCE="c:\temp\*.pdf" DEST="c:\archive\*.*" RESULTDATASET="theDataset" />

Example 2

This sample task moves folders and then creates and populates a dataset with the results.

Copy 
<AMFILESYSTEM ACTIVITY="move" OVERWRITE="yes" ISNEWER="yes" ONLYIFEXIST="yes" OVERWRITEREADONLY="yes" OVERWRITEHIDDEN="yes" EXCLUDE="text" RE="yes" ISNEWERTHAN="%DateSerial(2013,03,15)+TimeSerial(13,30,27)%" MODE="folder" SOURCE="c:\temp\*" DEST="c:\archive\*" RESULTDATASET="theDataset" />