Loop - Files
Declaration
<AMLOOP ACTIVITY="text" FOLDER="text" RESULTVARIABLE="text" ONLYFILENAME="yes/no" SORT="text (options)" SORTON="text (options)" MODE="text (options)" RESULTDATASET="text" SUBFOLDERS="yes/no" EXCLUDE="text" RE="yes/no" ISNEWERTHAN="number (date)" ISOLDERTHAN="number (date)" ATTRFILTER="-r-a-s-h-c-e">
Description: Loops through the files contained in a directory and populates a variable with the name of the current file. With each successive iteration, the next filename is retrieved. The loop ends after all the filenames have been retrieved or when a Break is encountered.
Practical Usage
Can be used to perform one or more activities on every file or sub-folder contained in the specified directory, such as re-naming all sub-folders to include the current date or re-sizing all image files to a particular size. This activity accepts wildcard characters (such as * and ?) as a way to specify which files should be included in the search.
General Parameters
Property |
Type |
Required |
Default |
Markup |
Description |
---|---|---|---|---|---|
Folder |
Text |
Yes |
While |
|
The folder that should be scanned for files. The loop will be executed on files and/or sub-folders inside contained inside this folder. This parameter also acts as an Include Filter and accepts wildcard characters such as * and ? to specify which files to scan. For example, entering "C:\myFolder\*.txt" will scan all text (.txt) files contained in myFolder. |
Populate variable with file data |
Text |
Yes |
(Empty) |
RESULTVARIABLE="varname" |
The name of an existing variable to be populated with the next filename during each successive loop. |
Mode |
Text (options) |
No |
File |
|
The file category to loop. The available options are:
|
Create and populate dataset with result info |
Text |
No |
(Empty) |
RESULTDATASET="DatasetName" |
The name of a dataset to be created and populated with specific information regarding the files being looped through. More on the dataset that this action creates can be found below under Datasets. |
Sorting |
Text (options) |
No |
Do not sort list |
|
Specifies the order in which files should be arranged relative to the field selected in the Field to sort on parameter. The available options are:
|
Field to sort on |
Text (options) |
No |
File Name |
|
The field that sorting should be applied to. This parameter is available only if the Sorting parameter is set to Ascending or Descending. The available options are:
|
Do not include path information (filename only) |
Yes/No |
No |
No |
ONLYFILENAME="yes" |
If set to YES, only the name of the file and not the path information (drive and folder names) will be returned in the variable or dataset. If set to NO (default), the full path and name of the file will be returned. |
File Options Parameters
Property |
Type |
Required |
Default |
Markup |
Description |
---|---|---|---|---|---|
Include subfolders |
Yes/No |
No |
No |
SUBFOLDERS="yes" |
If set to YES, specifies that the loop will include files or folders inside sub-folders of the folder specified. If set to NO (default), sub-folders will be ignored. |
Exclude Mask |
Text |
No |
(Empty) |
EXCLUDE="*.txt" |
Indicates a wildcard mask to designate files that should be omitted from the loop. Asterisk (*) or question mark (?) can be used as wildcard characters. For example, if *notepad* was specified, the loop would ignore file that included the text notepad in its name. To specify multiple wildcard masks, separate each one with a pipe (|) character (*.txt|*.jpg). |
Regular expression |
Yes/No |
No |
No |
RE="yes" |
If set to YES, specifies that the value entered in the Exclude Mask parameter should be treated as a regular expression. If set to NO (default), the value should be viewed in normal form. |
Include Files |
Yes/No |
No |
Yes |
FILES="yes" |
If set to YES, specifies that the loop will include files as an item to loop. By default, files are looped. |
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 Parameters
Property |
Type |
Required |
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 this 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 are:
|
Datasets
This action creates a dataset with the following fields (assuming the name of the dataset is theDataset):
Name |
Data Type |
Return Value |
---|---|---|
theDataset.Name |
Text |
Returns the name of the file. |
theDataset.Size |
Number |
Returns the file size. |
theDataset.CreatedOn |
Date |
Returns the file creation date. |
theDataset.ModifiedOn |
Date |
Returns the date the file was last modified. |
theDataset.AccessedOn |
Date |
Returns the date the file was last accessed. |
theDataset.IsFolder |
Yes/No |
Returns whether the file name is a folder (yes/no). |
theDataset.IsReadOnly |
Yes/No |
Returns whether the file attribute is read-only (yes/no). |
theDataset.IsArchive |
Yes/No |
Returns whether the file attribute is archive (yes/no). |
theDataset.IsSystem |
Yes/No |
Returns whether the file attribute is system (yes/no). |
theDataset.IsHidden |
Yes/No |
Returns whether the file attribute is hidden (yes/no). |
theDataset.IsCompressed |
Yes/No |
Returns whether the file is compressed (yes/no). |
theDataset.IsAccessible |
Yes/No |
Returns whether the file is accessible (yes/no). |
Examples
The sample AML code below can be copied and pasted directly into the Steps panel of the Task Builder.
Sample 1 - This task loops through all files that reside in c:\temp. Only file names are populated. A message box will display each file name within each successful loop. For this task to work, create a c:\temp folder and add some files to it or modify step 2 (Loop Files action) to point to a valid directory that includes some files.
<AMVARIABLE NAME="theCurrentFile"></AMVARIABLE> <AMLOOP TYPE="FOLDER" FOLDER="C:\Temp" RESULTVARIABLE="theCurrentFile" ONLYFILENAME="YES"> <AMMESSAGEBOX>The current file is %theCurrentFile%</AMMESSAGEBOX> </AMLOOP>
Sample 2 - This task loops through all folders only (no files) that reside in c:\temp. Folders are sorted in ascending alphabetical order. A message box will display each folder name within each successful loop. For this task to work, create a c:\temp folder and add some subfolders to it or modify step 2 (Loop Files action) to point to a valid directory that includes some folders.
<AMVARIABLE NAME="theCurrentFolder"></AMVARIABLE> <AMLOOP TYPE="FOLDER" FOLDER="C:\Temp" RESULTVARIABLE="theCurrentFolder" ONLYFILENAME="YES" FOLDERS="YES" FILES="NO" SORT="ascending" RESULTDATASET="theDataset"> <AMMESSAGEBOX>The current folder is %theCurrentFolder%</AMMESSAGEBOX> </AMLOOP>