Rename File Action

Declaration

<AMFILERENAME SOURCE="text" DEST="text" SUBFOLDERS="yes/no" KEEPFOLDERSTRUCT="yes/no" OVERWRITE="yes/no" ISNEWER="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

Rename File Action-Setting Properties, Copy File, Move File, Delete File, Delete Folder, Rename Folder

Description

Renames one or more files from a source path to a destination path.

Practical Usage

Used to rename one or more files, and optionally, to move the files to a new location. Supports multiple file renaming, such as adding a date or changing the extension on a group of files. To specify more than one file, use wildcard characters (* or ?). To specify multiple file names or wildcard masks, separate them with a pipe symbol. Example: c:\*.txt|c:\*.bak

Parameters

General Tab

Original File Name

Text, Required
MARKUP:
a) SOURCE="c:\sourcefoldername\file.txt"
b) SOURCE="c:\sourcefoldername\*.txt"
c) SOURCE="C:\sourcefoldername\*.txt|C:\sourcefoldername\*.doc"
d) SOURCE="file.txt"

Specifies the files to rename. This can be a fully qualified path and filename (preferred) or a file name only (requires use of the Change Folder action). Wildcard characters (* or ?) may be used to rename files matching a certain mask. Multiple files and file masks may be specified by separating the entries with a pipe (|) symbol.

New File Name

Text, Required
MARKUP:
a) DEST="c:\destfoldername\newfilename.txt"
b) DEST="c:\destfoldername\*.txt"
c) DEST="c:\destfoldername\"
d) DEST="newfilename.txt"

Specifies the destination folder and (optionally) the filename for the files being renamed. This can be a fully qualified path or a filename. Folders specified that do not exist will be automatically created at runtime. Wildcard characters (* or ?) may be used.

Create and Populate Dataset with Result Information

Text, Optional
MARKUP: RESULTDATASET="DatasetName"

Specifies the name of a dataset to be created and populated with the result. In addition to the standard dataset fields, the dataset will contain the following:

Options Tab

Include Subfolders

Yes/No, Optional, Default: NO
MARKUP: SUBFOLDERS="YES"

When set to YES, specifies that, if present, subfolders should be searched for files matching the mask specified in the Original File Name [SOURCE] parameter.

Preserve Folder Structure

Yes/No, Optional, Default: YES
MARKUP: KEEPFOLDERSTRUCT="NO"

Valid only if the Include subfolders [SUBFOLDERS] parameter is YES. When set to YES, specifies that subfolders found in the source folder should be created in the destination folder, and source files should be renamed in their respective folders rather than placed directly into the root of the target folder specified in the New File Name [DEST] parameter. If the Include subfolders [SUBFOLDERS] parameter is set to NO this parameter is ignored.

Overwrite if Exist

Yes/No, Optional, Default: NO
MARKUP: OVERWRITE="YES"

When set to YES, specifies that if files already exist in the destination folder they should be overwritten.

Only if Newer

Yes/No, Optional, Default: NO
MARKUP: ISNEWER="YES"

Valid only if the Overwrite if exist [OVERWRITE] parameter is YES. When set to YES, specifies that only files that are newer than those in the destination folders will overwrite existing files.

Only if Exist in Destination

Yes/No, Optional, Default: NO
MARKUP: ONLYIFEXIST="YES"

Valid only if the Overwrite if exist [OVERWRITE] parameter is YES. When set to YES, specifies that only files that already exist in the destination will be renamed from the source. All other files, regardless of whether they match the mask or other parameter settings will be bypassed.

Overwrite Read-Only Files

Yes/No, Optional, Default: NO
MARKUP: OVERWRITEREADONLY="YES"

Valid only if the Overwrite if exist [OVERWRITE] parameter is YES. When set to YES, specifies that already existing files should be overwritten even if the file in the destination is marked with the read-only attribute. By default, read only files are not overwritten.

Overwrite Hidden Files

Yes/No, Optional, Default: NO
MARKUP: OVERWRITEHIDDEN="YES"

Valid only if the Overwrite if exist [OVERWRITE] parameter is YES. When set to YES, specifies that already existing files should be overwritten even if the file in the destination is marked with the hidden attribute. By default, hidden files are bypassed.

Turn Archive Attribute Off

Yes/No, Optional, Default: NO
MARKUP: ARCHIVETURNOFF="YES"

When set to YES, 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.

Exclude Mask

Text, Optional, Default: (blank)
MARKUP: EXCLUDE="*.txt"

Causes the action to not rename files matching the masks specified. Filenames 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, Optional, Default: (none)
MARKUP: ISNEWERTHAN="%DateSerial(2007,10,12) + TimeSerial(00,00,00)%"

Causes the action to only rename 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 [ISNEWER] parameter).

Only if Older Than

Date, Optional, Default: (none)
MARKUP: ISOLDERTHAN="%DateSerial(2007,10,12) + TimeSerial(00,00,00)%"

Causes the action to only rename 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 [ISNEWER] parameter).

Attributes Tab

Attributes

Text, Optional, Default: (blank)
MARKUP:
ATTRFILTER="+R+A-S-H" (rename read-only and archive files, not system or hidden)
ATTRFILTER="-S" (do not rename "system" files)

This group of settings causes the action to filter which files are renamed based on the attribute settings of the source files.

In visual mode, a group of controls are provided to assist in the selection of this parameter. In markup mode, a single text item must be specified that contains the attributes of the files you wish to copy.

Available Options:

Notes

Custom Description

This action includes the Description tab for entering a custom step description.

More on setting custom step description

Standard Error Handling Options

This action also includes the standard Error Causes and On Error failure handling options/tabs.

More on Error Handling Options

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

Examples

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

<AMFILERENAME SOURCE="c:\folder1\*.*" DEST="c:\folder2\" SUBFOLDERS="YES" OVERWRITE="YES" />

<AMFILERENAME SOURCE="c:\folder1\originalname.txt" DEST="c:\folder2\newname.txt" SUBFOLDERS="YES" OVERWRITE="YES">

<AMFILERENAME SOURCE="c:\folder1\*.*" DEST="c:\folder2\" SUBFOLDERS="YES" OVERWRITE="YES" ISNEWERTHAN="%DateSerial(2001,10,12) + TimeSerial(00,00,00)%" RESULTDATASET="RenamedFilesDS" />

<AMFILERENAME SOURCE="C:\FolderName\FileName1.doc" DEST="C:\FolderName\FileName2.doc" OVERWRITE="YES" ISNEWER="YES" OVERWRITEREADONLY="YES" ATTRFILTER="-a-s" RESULTDATASET="RenamedFilesDS" />