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" />

Related Topics   

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

 
PropertyTypeRequiredDefaultMarkupDescription
FolderTextYes(Empty)
  • C:\
  • C:\FolderName\*.txt"
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 dataTextYes(Empty)RESULTVARIABLE="varname"The name of an existing variable to be populated with the next file name during each successive loop.
ModeText (options)NoFile
  • MODE="file"
  • MODE="folder"
  • MODE="both"
The file category to loop. The available options are:
  • File - The loop will be performed on files only. subfolders will be ignored.
  • Folder - The loop will be performed on subfolders only. Files will be ignored.
  • File and folder - The loop will be performed on both files and subfolders.
Create and populate dataset with result info (optional)TextNo(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.
SortingText (options)NoDo not sort the list
  • SORT="none"
  • SORT="ascending"
  • SORT="descending"
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:
  • Do not sort the list - No sorting will be applied.
  • Sort the list in ascending order - The files will be arranged in ascending order.
  • Sort the list in descending order - The files will be arranges in ascending order.
Field to sort onText (options)NoFile Name
  • SORTON="name"
  • SORTON="createDate"
  • SORTON="modDate"
  • SORTON="size"
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:
  • File name - Sorting will be applied to the names of the files.
  • Date created - Sorting will be applied to creation dates.
  • Date modified - Sorting will be applied to last modified dates.
  • File size - Sorting will be applied to file sizes.
Do not include path information (filename only)Yes/NoNoNoONLYFILENAME="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

 
PropertyTypeRequiredDefaultMarkupDescription
Exclude MaskTextNo(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 expressionYes/NoNoNoRE="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 thanDateNo(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 thanDateNo(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 subfoldersYes/NoNoNoSUBFOLDERS="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 caseYes/NoNoNoMATCHCASE="yes"If enabled, specifies that the loop will match the case sensitivity of file path exactly.

File Filter

 
PropertyTypeRequiredDefaultMarkupDescription
AttributesText (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:

  • Read-only attribute is - 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.
  • Archive attribute is - 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.
  • System attribute is - 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.
  • Hidden attribute is - 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.
  • Compression attribute is - 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.
  • Encrypted attribute is - Specifying "+E" causes files with this attribute turned on to be included, "-E" causes files with this attribute turned off to be included, not specifying the letter (default) causes this attribute to be ignored.

Description

Error Causes

On Error

Additional notes

Datasets

This action creates a dataset with the following fields (assuming the name of the dataset is theDataset):

NameData TypeReturn Value
theDataset.NameTextReturns the name of the file.
theDataset.SizeNumberReturns the file size.
theDataset.CreatedOnDateReturns the file creation date.
theDataset.ModifiedOnDateReturns the date the file was last modified.
theDataset.AccessedOnDateReturns the date the file was last accessed.
theDataset.IsFolderYes/NoReturns whether the file name is a folder (yes/no).  
theDataset.IsReadOnlyYes/NoReturns whether the file attribute is read-only (yes/no).  
theDataset.IsArchiveYes/NoReturns whether the file attribute is archive (yes/no).  
theDataset.IsSystemYes/NoReturns whether the file attribute is system (yes/no).
theDataset.IsHiddenYes/NoReturns whether the file attribute is hidden (yes/no).  
theDataset.IsCompressedYes/NoReturns whether the file is compressed (yes/no).  
theDataset.IsAccessibleYes/NoReturns whether the file is accessible (yes/no).

Examples

NOTE:
  • 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.

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

Copy
<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" />