Copy File Action Icon

Copy File

Declaration

<AMFILECOPY SOURCE="text" DEST="text" SUBFOLDERS="yes/no" EMPTYFOLDERS="yes/no" OVERWRITE="yes/no" ISNEWER="yes/no" ONLYFOLDERSTRUCT="yes/no" OVERWRITEREADONLY="yes/no" OVERWRITEHIDDEN="yes/no" ONLYIFEXIST="yes/no" ISNEWERTHAN="date" ISOLDERTHAN="date" ARCHIVETURNOFF="yes/no" EXCLUDE="text" ATTRFILTER="text"RESULTDATASET="text">

See Also

Calculate File Checksum | Change Folder | Concatenate Files | Copy File | Create Folder | Delete File | Get File(s) information | Join File | Move File | Read from File | Remove Folder | Rename File | Rename Folder

File System - Copy

Declaration

<AMFILECOPY SOURCE="text" DEST="text" SUBFOLDERS="yes/no" EMPTYFOLDERS="yes/no" OVERWRITE="yes/no" ISNEWER="yes/no" ONLYFOLDERSTRUCT="yes/no" OVERWRITEREADONLY="yes/no" OVERWRITEHIDDEN="yes/no" ONLYIFEXIST="yes/no" ISNEWERTHAN="date" ISOLDERTHAN="date" ARCHIVETURNOFF="yes/no" EXCLUDE="text" ATTRFILTER="text"RESULTDATASET="text">

See Also

Calculate File Checksum | Change Folder | Concatenate Files | Copy | Create Folder | Delete | Join File | Move | Read from File | Remove Folder

Description

Copies one or more folders/files from the source path to the destination path. To specify more than one folder/file, use wildcard characters (i.e. * or ?). To specify multiple files or wildcard masks, separate them with a pipe character (i.e. c:\*.txt|c:\*.bak).

Practical Usage

Commonly used to back-up files or complete folder structures. Could also be used to copy files to a shared folder on the network where they can be accessed by your business community.

Parameters

General Properties

Property

Type

Req'd

Default

Markup

Description

File/Folder

Text (Options)

Yes

File

MODE="folder"

Indicates what this activity should be performed on. The available options are:

  • File (default) -  This activity should be performed on file(s). A file is the common storage unit in a computer. All programs and data are contained in a file, and the computer reads and writes files.

  • Folder - This activity should be performed on folder(s). A folder holds one or more files, although a folder can also be empty. Folders provide a method for organizing files similar to a manila file folder containing paper documents in a file cabinet.

Different parameters may become available depending on which option is selected.

Source

Text

Yes

(Empty)

  1. SOURCE="c:\sourcefolder\file.txt"

  2. SOURCE="c:\sourcefolder\*.txt"

  3. SOURCE="c:\folder\*.txt|c:\folder\*.bak"

  4. SOURCE="c:\foldername\subfoldername

Specifies the folder(s)/file(s) to copy. This can be a fully qualified path and folder/file name (preferred) or a folder/file name only (requires use of the Change Folder action). Wildcard characters (* or ?) may be used to copy folders/files matching a certain mask. Multiple files and file masks may be entered by separating the entries with a pipe symbol (i.e. c:\*.txt|c:\*.bak).

Destination

Text

Yes

(Empty)

  1. DEST="c:\destfolder\file.txt"

  2. DEST="c:\destfolder\*.txt

  3. DEST="c:\destfolder\*.*"

  4. DEST="c:\destfolder

Indicates 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.

Create and populate dataset with result information

Text

No

(Empty)

RESULTDATASET="DatasetName"

Specifies the name of a dataset to be created and populated with the results of this operation. More information about the fields that this dataset creates are entered below under Notes.

 

File Options Properties

Property

Type

Req'd

Default

Markup

Description

Include Subfolders

Yes/No

No

No

SUBFOLDERS="YES"

If set to YES, denotes that, if present, subfolders should be searched for files matching the mask specified in the Source parameter. If set to NO (default), subfolders are ignored. Only files that exist in the root of the source folder will be searched.

Preserve Folder Structure

Yes/No

No

Yes

KEEPFOLDERSTRUCT="NO"

If set to YES (default), subfolders found in the source folder will be created in the destination folder and source files will be copied into their respective folders. If set to NO, subfolders will not be created. Files that exist in these subfolders will be copied into the root of the source folder instead. This parameter is active only if the Include Subfolders parameter is set to YES.

Include Empty Subfolders

Yes/No

No

No

EMPTYFOLDERS="YES"

If set to YES, subfolders found in the source folder will be created in the destination folder even if they do not contain any files. If set to NO (default), empty subfolders are ignored. This parameter is active only if the Include Subfolders parameter is set to YES.

Only Folder Structure

Yes/No

No

No

ONLYFOLDERSTRUCT="YES"

If set to YES, subfolders found in the source folder will be created in the destination folder but files that reside in these subfolders will not be copied. This parameter is set to NO by default and is active only if the Include Subfolders parameter is set to YES.

NOTE: Setting this option to YES causes all other folder-specific parameters to be ignored.

Overwrite if Exist

Yes/No

No

No

OVERWRITE="YES"

If set to YES, matching files found in the destination folder are to be overwritten. If set to NO (default), an error will occur as a result of a matching file found.

Only if Newer

Yes/No

No

No

ISNEWER="YES"

If set to YES, only source files that are newer than those that match in the destination are to be overwritten folder will overwrite existing files. If set to NO (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 set to YES.

Only if Exist in Destination

Yes/No

No

No

ONLYIFEXIST="YES"

If set to YES, only files that already exist in the destination folder will be copied from the source folder. All other files, regardless of whether they match the mask or other parameter settings will be bypassed. This parameter is set to NO by default and becomes active only if the Overwrite if Exist parameter is set to YES.

Overwrite Read-Only Files

Yes/No

No

No

OVERWRITEREADONLY="YES"

If set to YES, matching files found in the destination folder will be overwritten even if they are marked with the read-only attribute. If set to NO (default), read-only files are not overwritten. This parameter is active only if the Overwrite if Exist parameter is set to YES.

Overwrite Hidden Files

Yes/No

No

No

OVERWRITEHIDDEN="YES"

If set to YES, matching files found in the destination folder will be overwritten even if they are marked with the hidden attribute. If set to NO (default), hidden files are not overwritten. This parameter is active only if the Overwrite if Exist parameter is set to YES.

Turn Archive Attribute Off

Yes/No

No

No

ARCHIVETURNOFF="YES"

If set to YES, archive attribute of the source files will 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 set to NO by default.

Exclude Mask

Text

No

(Empty)

EXCLUDE="*.txt"

Causes this action to omit files matching the mask(s) 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

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 Filters Properties

Attributes Properties

Property

Type

Req'd

Default

Markup

Description

Attributes

Text (Options)

No

(Empty)

ATTRFILTER="+R+A-H" (copy read-only & archive files but not hidden files)

This group of settings causes the action to filter which files are affected by the attribute change based on the original attribute settings of the source files.

In visual mode, a group of controls are provided to assist in the selection of this parameter. In AML mode, a single text item must be specified that contains the original attribute mask of the files you wish to affect.

Available Options:

  • R—Read-only: Specifying "+R" causes files with this attribute turned on to be included, "-R" causes files with this attribute turned off to be included, not specifying the letter (default) causes this attribute to be ignored.

  • A—Archive: Specifying "+A" causes files with this attribute turned on to be included, "-A" causes files with this attribute turned off to be included, not specifying the letter (default) causes this attribute to be ignored.

  • S—System: Specifying "+S" causes files with this attribute turned on to be included, "-S" causes files with this attribute turned off to be included, not specifying the letter (default) causes this attribute to be ignored.

  • H—Hidden: Specifying "+R" causes files with this attribute turned on to be included, "-H" causes files with this attribute turned off to be included, not specifying the letter (default) causes this attribute to be ignored.

  • C—Compression: Specifying "+C" causes files with this attribute turned on to be included, "-C" causes files with this attribute turned off to be included, not specifying the letter (default) causes this attribute to be ignored.

 

Description Properties

The Description tab allows you to customize the text description of any step as it appears in the Task Builder's Steps Pane.

More on setting custom step description

Error Causes Properties

The Error Causes tab allows you to select/omit specific errors that should cause a particular step to fail.

More on Error Causes properties

On Error Properties

The On Error tab allows you to determine what the task should do if a particular step encounters an error.

More about On Error properties

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.

Variables and Expressions

All text fields allow the use of expressions, which can be entered by surrounding the expression in percentage signs (example: %MYVARIABLE%, %Left('Text',2)%). To help construct these expressions, you can open Expression Builder from these fields by pressing F2.

More on variables
More on expressions

More on the expression builder

Example

NOTE: The code below can be copied and pasted directly into the Steps pane of the Task Builder.

 

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.

 

<AMFILECOPY SOURCE="C:\Folder1\*.*" DEST="C:\Folder2" SUBFOLDERS="YES" OVERWRITE="YES" ISNEWER="YES" OVERWRITEREADONLY="YES" ONLYIFEXIST="YES" ISNEWERTHAN="%DateSerial(2007,02,24) + TimeSerial(15,40,34)%" ARCHIVETURNOFF="YES" EXCLUDE="*.pri" ATTRFILTER="+a-s" RESULTDATASET="FileCopyDataset" />

<AMLOOP TYPE="DATASET" DATASET="FileCopyDataset">

     <AMSHOWDIALOG WINDOWTITLE="Results of copy file operation.">Source - %FileCopyDataset.Source%

Destination - %FileCopyDataset.Destination%

Result - %FileCopyDataset.Result%

Message - %FileCopyDataset.Message%</AMSHOWDIALOG>

</AMLOOP>

 

↑ Top of Page