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

  1. C:\FolderName\SubfolderName\

  2. C:\FolderName\*.txt"

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

  1. MODE="file"

  2. MODE="folder"

  3. MODE="both"

The file category to loop. The available options are:

  • File - The loop will be performed on files only. Sub-folders will be ignored.

  • Folder - The loop will be performed on sub-folders only. Files will be ignored.

  • File and folder - The loop will be performed on both files and sub-folders.

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

  1. SORT="none"

  2. SORT="ascending"

  3. 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 list (default) - 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 on

Text (options)

No

File Name

  1. SORTON="name"

  2. SORTON="creationdate"

  3. SORTON="modificationdate"

  4. 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/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:

  • R—Read-only - 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.

  • A—Archive - 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.

  • S—System - 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.

  • H—Hidden - 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.

  • C—Compression - 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.

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>