Loop - Files
Declaration
<AMLOOP ACTIVITY="folder" FOLDER="text" RESULTVARIABLE="text" MODE="text (options)" ONLYFILENAME="yes/no" SORT="text (options)" SORTON="text (options)" RESULTDATASET="text" SUBFOLDERS="yes/no" MATCHCASE="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 file name is retrieved. The loop ends after all the file names have been retrieved or when a Break is encountered.
Practical usage
Can be used to perform one or more activities on every file or subfolder contained in the specified directory, such as renaming all subfolders to include the current date or resizing all image files to a particular size. This activity accepts wildcard characters (that is, * and ?) as a way to specify which files should be included in the search.
Parameters
General
Property | Type | Required | Default | Markup | Description |
---|---|---|---|---|---|
Folder | Text | Yes | (Empty) |
| The folder that should be scanned for files. The loop will be executed on files and / or subfolders inside contained inside this folder. This parameter also acts as an Include Filter and accepts wildcard characters (that is, * and ?) to specify which files to scan. For example, entering C:\myFolder\*.txt will scan all text files contained in c:\myFolder\. |
Populate variable with file data | Text | Yes | (Empty) | RESULTVARIABLE="varname" | The name of an existing variable to be populated with the next file name 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 (optional) | 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 fields that this action creates can be found below under Datasets. |
Sorting | Text (options) | No | Do not sort the 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 enabled, only the name of the file and not the path information (drive and folder names) will be returned in the variable or dataset. If disabled (default), the full path and name of the file will be returned. |
File Options
Property | Type | Required | Default | Markup | Description |
---|---|---|---|---|---|
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). See File
Masks & Wildcards for more details. NOTE: Files with invalid paths are ignored at runtime. |
Regular expression | Yes/No | No | No | RE="yes" | If enabled, specifies that the value entered in the Exclude Mask parameter should be treated as a regular expression. If disabled (default), the value should be viewed in normal form. |
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. |
Include subfolders | Yes/No | No | No | SUBFOLDERS="yes" | If set to enabled, specifies that the loop will include files or folders inside subfolders of the folder specified. If disabled (default), subfolders will be ignored. |
Match case | Yes/No | No | No | MATCHCASE="yes" | If enabled, specifies that the loop will match the case sensitivity of file path exactly. |
File Filter
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:
|
Additional notes
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
- Copy and paste the sample AML code below directly into the Task Builder Steps Panel.
- To successfully run the sample code, update parameters containing user credentials, files, file paths, or other information specific to the task to match your environment.
Example 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 activity) to point to a valid directory that includes some files.
<AMVARIABLE NAME="theCurrentFile" VALUE="" />
<AMLOOP ACTIVITY="folder" FOLDER="C:\Temp" RESULTVARIABLE="theCurrentFile" ONLYFILENAME="YES" />
<AMSHOWDIALOG>The current file is %theCurrentFile%</AMSHOWDIALOG>
<AMLOOP ACTIVITY="end" />
Example 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 activity) to point to a valid directory that includes some folders.
<AMVARIABLE NAME="theCurrentFolder" VALUE="" />
<AMLOOP ACTIVITY="folder" FOLDER="C:\Temp" RESULTVARIABLE="theCurrentFolder" MODE="folder" RESULTDATASET="theDataset" ONLYFILENAME="YES" SORT="ascending" />
<AMSHOWDIALOG>The current folder is %theCurrentFolder%</AMSHOWDIALOG>
<AMLOOP ACTIVITY="end" />