File System - Copy

Declaration

<AMFILESYSTEM SOURCE="text (options)" 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

Copies one or more files or folders from one directory to another. To specify more than one file/folder, use wildcard characters (for example, * or ?). To specify multiple files or wildcard masks, separate them with a pipe character (for example, c:\*).

Practical Usage

Commonly used to back-up files or complete folder structures. Could also be used as a batch copying tool. For example, you can set this activity to copy PDF files to a shared folder on the network where they can be accessed by the community.

Parameters

General

Property Type Required Default Markup Description
File/Folder Text (Options) Yes File MODE="folder" Indicates the type of items to copy. Parameters located in the File options section vary depending on which option is selected. The available options are:
  • File (default) -  This activity will copy one or more files.
  • Folder - This activity will copy one or more folders.
Source Text Yes (Empty)
  • SOURCE="c:\folder\file.txt"
  • SOURCE="c:\folder\*.txt"
  • SOURCE="c:\folder1\|c:\folder2"
  • SOURCE="c:\folder\subfolder"
 The path and file name to copy. 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.
Destination Text Yes (Empty)
  • DEST="c:\destfolder\file.txt"
  • DEST="c:\destfolder\*.txt"
  • DEST="c:\destfolder\*.*"
  • DEST="c:\destfolder"
 The destination folder (and optionally, file name) that the source should be copied to. This can be a fully qualified path or folder/file name only. Folders that do not exist will be automatically created at runtime. When copying a single file or folder (omitting wildcards), this activity can rename the file/folder to be copied by specifying a different path and file/folder name in this parameter.
Create and populate dataset with results (optional) Text No (Empty) RESULTDATASET="DatasetName" The name of the dataset to create and populate with the results of this operation. More information about the individual fields that this dataset creates are entered 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. Only files that exist in the root of the source folder will be searched. This parameter is active only if this activity is configured to copy files (not folders).
Preserve folder structure Yes/No No No KEEPFOLDERSTRUCT="NO" If selected, subfolders found in the source folder will be created in the destination folder and source files will be copied into their respective folders. If disabled (default), subfolders will not be created in the destination. Instead, source files that exist in these subfolders will be copied into the root of the destination folder. This parameter is active only if the Include subfolders parameter is selected.
Merge if folder exists Yes/No No No MERGEFOLDER="YES" If selected, indicates that, if subfolders with matching names already exists in the destination, contents contained in the source folder, such as files and subfolders, will be merged into their respective destination folders. If disabled (default), files will not be merged, however, a runtime error will occur as a result. This parameter is active only if this activity is configured to copy folders (not files).
Only folder structure Yes/No No No ONLYFOLDERSTRUCT="YES" If selected, subfolders found in the source folder will be created in the destination folder but files that reside in these subfolders will not be copied. If disabled (default), files that reside in the source folder will be copied as well. This parameter is active only if this activity is configured to copy folders (not files).
NOTE: Setting this option to YES causes all other folder-specific parameters to be ignored.
Overwrite if exists Yes/No No No OVERWRITE="YES" If selected, indicates that, if files with matching names already exists in the destination, they will be overwritten. If disabled (default), files with matching names will not be overwritten, however, an error will occur during runtime stating a file with the same name already exists.
Only if newer Yes/No No No ISNEWER="YES" If selected, indicates that, if files with matching names already exists in the destination, only source files that are newer will overwrite existing files. If disabled (default), all matching files found in the destination folder will be overwritten regardless of their date properties. 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 files that already exist in the destination will be copied from the source. All other files, regardless of whether they match the mask or other parameter settings will be bypassed. This parameter is disabled by default and becomes active only if the Overwrite if Exist parameter is selected.
Overwrite read-only files Yes/No No No OVERWRITEREADONLY="YES" If selected, matching files found in the destination folder will be overwritten even if they are marked with the read-only attribute. If disabled (default), read-only files are not overwritten. This parameter is active only if the Overwrite if Exist parameter is selected.
Overwrite hidden files Yes/No No No OVERWRITEHIDDEN="YES" If selected, matching files found in the destination folder will be overwritten even if they are marked with the hidden attribute. If disabled (default), hidden files are not overwritten. This parameter is active only if the Overwrite if Exist parameter is selected.
Exclude mask Text No (Empty)
  • EXCLUDE="*.txt"
  • EXCLUDE="*.txt|*.bak"
  • EXCLUDE="c:\foldename"
 Causes this action to omit files matching the masks specified. File names or wildcard masks may be used. Multiple entries may be specified by separating them with a pipe symbol (|) (for example, *.txt|*.bak)
Regular expression Yes/No No No RE="yes" If selected, indicates 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)%" If enabled, causes this action to only act on files that are newer than the date/time specified. If this parameter is left blank or disabled (default), file dates are ignored.

Click the Custom button to select from a list of pre-defined date parameters. Enable the Expression option to allow entry of a date/time expression.
Only if older than Date No (Empty) ISOLDERTHAN="%DateSerial(2001,10,12) + TimeSerial(00,00,00)%" If enabled, causes this action to only act on files that are older than the date/time specified. If this parameter is left blank or disabled (default), file dates are ignored.

Click the Custom button to select from a list of pre-defined date parameters. Enable the Expression option 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.

Example

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.

Description

This sample task performs a copy operation and saves results to a dataset. A Loop Dataset action then loops through the dataset and displays information about the copied files in a message box.

Copy 
<AMFILESYSTEM SOURCE="C:\Folder1\*.*" DEST="C:\Folder2" RESULTDATASET="FileCopyDataset" SUBFOLDERS="YES" ARCHIVETURNOFF="YES" OVERWRITE="YES" ISNEWER="YES" ONLYIFEXIST="YES" OVERWRITEREADONLY="YES" EXCLUDE="*.pri" ISNEWERTHAN="%DateSerial(2019,12,06)+TimeSerial(14,11,50)%" ATTRFILTER="+a-s" />
<AMLOOP ACTIVITY="dataset" DATASET="FileCopyDataset" />
<AMSHOWDIALOG WINDOWTITLE="Results of copy file operation.">Source - %FileCopyDataset.Source%Destination - %FileCopyDataset.Destination%Result - %FileCopyDataset.Result%Message - %FileCopyDataset.Message%</AMSHOWDIALOG>
<AMLOOP ACTIVITY="end" />