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   

Overview

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 of the file names are 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 (* and ?) to specify which files are included in the search.

Parameters

General

 
PropertyTypeRequiredDefaultMarkupDescription
FolderTextYes(Empty)
  • C:\
  • C:\FolderName\*.txt"
The folder to scan for files. The loop is executed on files and/or subfolders contained inside this folder. This parameter also acts as an Include Filter and accepts wildcard characters (* and ?) to specify the files to scan. For example, entering C:\myFolder\*.txt scans 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 is performed on files only. Subfolders are ignored.
  • Folder - The loop is performed on subfolders only. Files are ignored.
  • File and folder - The loop is performed on both files and subfolders.
Create and populate dataset with result info (optional)TextNo(Empty)RESULTDATASET="DatasetName"The name of a dataset to create and populate with specific information regarding the files being looped through. See Datasets for more information on dataset fields that this action creates.
SortingText (options)NoDo not sort the list
  • SORT="none"
  • SORT="ascending"
  • SORT="descending"
Specifies the order files are arranged relative to the field selected in the Field to sort on parameter. The available options are:
  • Do not sort the list - No sorting is applied.
  • Sort the list in ascending order - The files are arranged in ascending order.
  • Sort the list in descending order - The files are 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 is applied to the names of the files.
  • Date created - Sorting is applied to creation dates.
  • Date modified - Sorting is applied to last modified dates.
  • File size - Sorting is 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) are returned in the variable or dataset. If disabled (default), the full path and name of the file is returned.

File Options

 
PropertyTypeRequiredDefaultMarkupDescription
Exclude MaskTextNo(Empty)EXCLUDE="*.txt"Indicates a wildcard mask to designate files that should be omitted from the loop. You can use asterisks (*) or question marks (?) as wildcard characters. For example, if *notepad* is specified, the loop ignores files that include the text notepad in its name. To specify multiple wildcard masks, separate each one with a pipe (|) (*.txt|*.jpg). See File Masks & Wildcards for more information.
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 is treated as a regular expression. If disabled (default), the value is 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 Custom to select from a list of pre-defined date parameters. Select the Expression check box 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 Custom to select from a list of pre-defined date parameters. Select the Expression check box to allow entry of a date/time expression.
Include subfoldersYes/NoNoNoSUBFOLDERS="yes"If set to enabled, specifies that the loop includes files or folders inside subfolders of the folder specified. If disabled (default), subfolders are ignored.
Match caseYes/NoNoNoMATCHCASE="yes"If enabled, specifies that the loop matches 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 want 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

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

NameData TypeReturn Value
theDataset.NameTextThe name of the file.
theDataset.SizeNumberThe file size.
theDataset.CreatedOnDateThe file creation date.
theDataset.ModifiedOnDateThe date the file was last modified.
theDataset.AccessedOnDateThe date the file was last accessed.
theDataset.IsFolderYes/NoReturns if the file name is a folder (yes/no).  
theDataset.IsReadOnlyYes/NoReturns if the file attribute is read-only (yes/no).  
theDataset.IsArchiveYes/NoReturns if the file attribute is archive (yes/no).  
theDataset.IsSystemYes/NoReturns if the file attribute is system (yes/no).
theDataset.IsHiddenYes/NoReturns if the file attribute is hidden (yes/no).  
theDataset.IsCompressedYes/NoReturns if the file is compressed (yes/no).  
theDataset.IsAccessibleYes/NoReturns if 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

The following task loops through all files that reside in c:\temp. Only file names are populated. A message box displays 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

The following task loops through all folders only (no files) that reside in c:\temp. Folders are sorted in ascending alphabetical order. A message box displays 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" />