File System - Get Information
Declaration
<AMFILESYSTEM ACTIVITY="get" SUBFOLDERS="yes/no" MATCHCASE="yes/no" EXCLUDE="text" RE="yes/no" ISNEWERTHAN="DateSerial" MODE="text (options)" SOURCE="text" RESULTVARIABLE="text" RESULTDATASET="text" FILEPROPERTY="text (options)" />
Description: Retrieves key information and attributes about one or more files, folders, or volumes and stores the results a variable or dataset. To specify more than one file, use wildcard characters (e.g., * or ?). To specify multiple files or wildcard masks, separate them with a pipe symbol (e.g., c:\*.
Practical Usage
Commonly used to gather data about one or more files/folders and perform conditional actions depending on the information.
General Parameters
Property |
Type |
Required |
Default |
Markup |
Description |
---|---|---|---|---|---|
Mode |
Text (options) |
Yes |
File |
|
Indicates what this activity should be performed on. The available options are:
|
Source |
Text |
Yes |
(Empty) |
|
A fully qualified path to the source file(s) or folder(s) in which to retrieve information from. Wildcard characters (* or ?) may be used to specify files matching a certain mask. Multiple file and/or file masks may be specified by separating the entries with a pipe symbol (c:\*. |
Volume |
Text |
Yes |
A:\ |
DRIVENAME="A:\" |
The volume to retrieve information from. This parameter is available only if the Mode parameter is set to Volume. |
Information to retrieve (file/folder) |
Text (options) |
Yes |
Fullname |
|
The file/folder property in which to populate the variable with. This parameter is available only if the Mode parameter is set to File, Folder or File andFolder. The available options are:
|
Information to retrieve (volume) |
Text (options) |
Yes |
Fullname |
|
The volume property in which to populate the variable with. This parameter is available only if the Mode parameter is set to Volume. The available options are:
|
Populate variable with result |
Text |
No |
(Empty) |
RESULTVARIABLE="varName" |
The name of an existing variable to populate with the specified property/information selected. If multiple files, folders or volumes are specified, the variable will be populated with each item property separated by a semi colon. For example, if the file property selected is File name, the variable will store information in this manner: fileA.txt;fileB.txt;fileC.txt |
Dataset to populate |
Text |
Yes |
(Empty) |
RESULTDATASET="DatasetName" |
If enabled, specifies the name of the dataset to populate with information about the source. Different dataset fields/values are populated depending on whether the source specified is a file/folder or volume. For a complete list of dataset fields, see below under Datasets (file/folder) or Datasets (volume) . |
Calculate directory size |
Yes/No |
No |
No |
SIZE=yes |
If set to YES (default), the total size of the specified folder will be calculated. This parameter is available only if the Mode parameter is set to Folder or File and folder. |
File Parameters
Property |
Type |
Required |
Default |
Markup |
Description |
---|---|---|---|---|---|
Include subfolders |
Yes/No |
No |
No |
SUBFOLDERS="yes" |
If set to YES, denotes that, if present, subfolders should be searched for folders/ files matching the mask specified in the Source parameter. If set to NO (default), subfolders are ignored. |
Match case |
Yes/No |
No |
No |
MATCHCASE="yes" |
If set to YES, this activity filters out results that match the case of the mask specified in the Source parameter. If set to NO (default), case is ignored. |
Exclude mask |
Text |
No |
(Empty) |
|
Causes this activity to omit folders/files matching the mask(s) specified. Folder/File names or wildcard masks may be used. Multiple entries may be specified by separating them with a pipe symbol (|), for example: *.txt|*.bak |
Regular expression |
Yes/No |
No |
No |
RE="yes" |
If set to YES, specifies that the value entered in the Exclude mask parameter will be interpreted as a regular expression. If set to NO (default), the value will be interpreted as regular text. |
Only if newer than |
Date |
No |
(Empty) |
ISNEWERTHAN= "%DateSerial(2001,10,12) + TimeSerial(00,00,00)%" |
If enabled, causes this activity 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 checkbox 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 activity 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 checkbox 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 the action to filter which files should information be retrieved from based on the attribute settings of the source file(s). In visual mode, a group of controls are provided to assist in the selection of this parameter. In markup mode, a single text item must be specified that contains the attributes of the files you wish to copy. Available Options:
|
Description tab - A custom description can be provided on the Description tab to convey additional information or share special notes about a task step.
Error Causes tab - Specify how this step should behave upon the occurrence of an error. (Refer to Task Builder > Error Causes Tab for details.)
On Error tab - Specify what AWE should do if this step encounters an error as defined on the Error Causes tab. (Refer to Task Builder > On Error Tab for details.)
Datasets (File/Folder)
A dataset is a multiple column, multiple row container object. This activity creates and populates a dataset containing a specific set of fields. The table below describes the file/folder related dataset fields created and populated (assuming the dataset name assigned was theDataset).
Name |
Type |
Return Value |
---|---|---|
theDataset.FullName |
String |
Returns the full path and file name of the file. For Example: C:\Temp\FolderName\FileName.txt |
theDataset.Parent |
String |
Returns the path to the parent folder. For example: If the source is C:\Temp\FolderName\FileName.txt, the parent is C:\Temp\FolderName |
theDataset.FileName |
String |
Returns the file name only. For example: If the source is C:\Temp\FolderName\FileName.txt, the filename is FileName.txt |
theDataset.Extension |
String |
Returns the file extension only. For example: If the source is C:\Temp\FolderName\FileName.txt, the extension is .txt |
theDataset.Size |
Number |
Returns the size of the file in kb. |
theDataset.IsReadOnly |
True/False |
Returns TRUE if the folder/file is read only. Otherwise, returns FALSE. |
theDataset.CreationTime |
Date |
Returns the creation date/time of the folder/file. |
theDataset.LastAccessTime |
Date |
Returns the date and time the folder/file was last accessed. |
theDataset.LastWriteTime |
Date |
Returns the date and time the folder/file was last written to. |
theDataset.Attributes |
String |
Returns the attributes for the file. |
theDataset.IsDireactory |
True/False |
Returns TRUE if the item specified is a folder or directory. Otherwise, returns FALSE. |
theDataset.Checksum |
Number |
Returns the checksum value of the file. This field is populated only if the Calculate file checksum parameter is enabled. |
Datasets (Volume)
The table below describes the volume associated dataset fields created and populated (assuming the dataset name assigned was theDataset).
Name |
Type |
Return Value |
---|---|---|
theDataset.Drive |
Text |
Returns the drive from which corresponding data is retrieved. |
theDataset.VolumeType |
Text |
Returns the volume type (e.g., Removable) |
theDataset.VolumeLabel |
Text |
Returns the volume label. |
theDataset.FileSystem |
Text |
Returns the file system (e.g., NTFS) |
theDataset.AvailableSpaceforUser |
Number |
Returns the current user's available space. |
theDataset.TotalAvailableSpace |
Number |
Returns the total available space. |
theDataset.TotalSizeofDrive |
Number |
Returns the total size of the drive. |
theDataset.UsedSpace |
Number |
Returns the used space. |
Examples
The sample AML code below can be copied and pasted directly into the Steps panel of the Task Builder.
Example 1: Get information about PDF files that reside in C:\Temp and populate the dataset named "theDataset" with results. Loop through the dataset and during each iteration, display file information about the current file in a message box.
<AMFILESYSTEM ACTIVITY="get" SUBFOLDERS="yes" SOURCE="C:\Temp\*.pdf" RESULTDATASET="theDataset" FILEPROPERTY="filename" /> <AMLOOP ACTIVITY="dataset" DATASET="theDataset"> <AMSHOWDIALOG WINDOWTITLE="File Information">File name: %theDataset.Filename% File size: %theDataset.Size% File path: %theDataset.Fullname% File type: %theDataset.Extension% File creation date: %theDataset.CreationTime% File attributes: %theDataset.Attributes% </AMSHOWDIALOG> </AMLOOP> |
Example 2 - Copy file(s) from "C:\Folder1\*.*" to "C:\Folder2\". Include sub folders. Exclude the file mask(s) "*.pri". Overwrite read-only files and files that exist exist in the destination. Create and populate dataset "FileCopyDataset" with details of the file(s) to be copied.
<AMFILECOPY SOURCE="C:\Folder1\*.*" DEST="C:\Folder2" SUBFOLDERS="YES" OVERWRITE="YES" ISNEWER="YES" OVERWRITEREADONLY="YES" ONLYIFEXIST="YES" ISNEWERTHAN="%DateSerial(2007,02,24) + TimeSerial(15,40,34)%" ARCHIVETURNOFF="YES" EXCLUDE="*.pri" ATTRFILTER="+a-s" RESULTDATASET="FileCopyDataset" /> |