File System - Get information

Declaration

<AMFILESYSTEM ACTIVITY="get" MODE="text (options)" DRIVENAME="text" DRIVEINFO="text (options) SOURCE="text" RESULTVARIABLE="text" RESULTDATASET="text" FILEPROPERTY="text (options)" HASHTYPE="text (options)" CALCULATEDIRSIZE="YES/NO" SUBFOLDERS="YES/NO" MATCHCASE="YES/NO" EXCLUDE="text" RE="YES/NO" ISNEWERTHAN="date serial" ISOLDERTHAN="date serial" ATTRFILTER="+r-a+s-h+c-e" />

Related Topics    

Description

Retrieves key information about a file folder or volume and stores the results into an Automate variable or dataset. To specify more than one file, use wildcard characters (for example, * or ?). To specify multiple files or wildcard masks, separate them with a pipe symbol (for example, c:\*.txt|c:\*.bak).

Practical Usage

Commonly used to gather data about one or more files/folders/volumes and perform conditional actions depending on the information.

Parameters

General

Property Type Required Default Markup Description
Mode (unlabeled) Text (options) Yes File
  • MODE="folder"
  • MODE="both"
  • MODE="volume"
 Specifies the mode to use to gather information. The available options are:
  • File (default) -  File information is gathered.
  • Folder - Folder information is gathered.
  • File and Folder - File and folder information is gathered.
  • Volume - Volume information is gathered. A volume can be a single accessible storage area such as a single hard disc or partition.
Source Text Yes (Empty)
  • SOURCE="c:\folder\file.txt"
  • SOURCE="c:\folder\*.pdf"
  • SOURCE="c:\*.txt|c:\*.bak"
  • SOURCE="c:\folder\subfolder"
 Specifies a path to the source files or folders of where to retrieve information. This parameter is available only if the Mode parameter is set to File, Folder or File and Folder. This can be a fully qualified path and file name (preferred) or a single file (requires use of the File System - Change folder activity). Wildcard characters (for example, * or ?) may be used to specify all files matching a certain mask. Multiple files and/or file masks can be specified by separating each entry with a pipe character (|) (for example, c:\temp\*.txt|c:\backup\*.bak). See File Masks & Wildcards for more details.
NOTE: Files with invalid paths are ignored at runtime.
Volume Text Yes C:\ DRIVENAME="C:\" Specifies the volume of where to retrieve information. This parameter is available only if the Mode parameter is set to Volume.
Information to retrieve (file/folder) (unlabeled) Text(options) Yes Fullname
  • FILEPROPERTY="fullname"
  • FILEPROPERTY="parent"
  • FILEPROPERTY="filename"
  • FILEPROPERTY="extension"
  • FILEPROPERTY="size"
  • FILEPROPERTY="isreadonly"
  • FILEPROPERTY="creationtime"
  • FILEPROPERTY="lastaccesstime"
  • FILEPROPERTY="lastwritetime"
  • FILEPROPERTY="attributes"
  • FILEPROPERTY="isdirectory"
  • FILEPROPERTY="checksum"
 Specifies the type of file/folder information to retrieve and use to populate the variable. This parameter is available only if the Mode parameter is set to File, Folder, or File and folder. The available options are:
  • Full name - The full path and file name of the file (for example, c:\temp\filename.txt).
  • Parent - The parent folder (for example, c:\temp).
  • File name - The file name and extension, excluding path (for example, filename.txt).
  • Extension - The file's extension (for example, .txt)
  • Size - The size of the file measured in bytes (for example, 1024000).
  • Is read only - Whether the file is Read-Only (True or False).
  • Creation time - The file's creation date/time (for example, 3/20/2020 9:20:20 AM).
  • Last access time - The date/time the file was last accessed (for example, 3/20/2020 9:20:20 AM).
  • Last write time - The date/time the file was last written to (for example, 3/20/2020 9:20:20 AM).
  • Attributes - The file's attributes (for example, Archive).
  • Is directory - Specifies if the item selected is a directory (true) or not (false).
  • Checksum - The checksum value of the file.
Information to retrieve (volume) Text(options) Yes Fullname
  • DRIVEINFO="volumetype"
  • DRIVEINFO="volumelabel"
  • DRIVEINFO="filesystem"
  • DRIVEINFO="availablespaceforuser"
  • DRIVEINFO="totalavailablespace"
  • DRIVEINFO="totalcapacity"
  • DRIVEINFO="usedspace"
 Specifies the type of volume information to retrieve and use to populate the variable. This parameter is available only if the Mode parameter is set to Volume. The available options are:
  • Volume type (default) - The volume type (for example, Removable).
  • Volume label - The volume label.
  • File system - The file system used (for example, FAT32, NTFS).
  • Current user's available space - The available space for the user currently logged on (in Kb).
  • Total available space - Total volume space (in Kb)
  • Total capacity - Total volume capacity (in Kb).
  • Used space - Total used space (in Kb).
Populate variable with result Text No (Empty) RESULTVARIABLE="theVariableName" The name of an existing variable to populate with the specified property/information selected. If multiple files, folders, or volumes are specified, the variable is populated with each item property separated by a semicolon (for example, fileA.txt;fileB.txt;fileC.txt).
Create and populate dataset with result Text Yes (Empty) RESULTDATASET="theDatasetName" If enabled, specifies the name of the dataset to create and 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 CALCULATEDIRSIZE="YES" If selected (default), the total size of the specified folder is calculated. This parameter is available only if the Mode parameter is set to Folder or File and folder.

File Options

Property Type Required Default Markup Description
Exclude mask Text No (Empty)
  • EXCLUDE="*.txt"
  • EXCLUDE="*.txt|*.bak
  • EXCLUDE="c:\foldename"
 Causes this activity to omit folders/files matching the masks specified. Folder/File names or wildcard masks may be used. Multiple entries may be specified by separating them with a pipe character (|) (for example, *.txt|*.bak|*.png).
Regular expression Yes/No No No RE="YES" If selected, specifies the value entered in the Exclude mask parameter is interpreted as a regular expression. If disabled (default), the value is 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 predefined date parameters. Enable the Expression check-box 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 predefined date parameters. Enable the Expression checkbox to allow entry of a date/time expression.
Include subfolders Yes/No No No SUBFOLDERS="yes" If selected, subfolders are searched for folders/ files matching the mask specified in the Source parameter. If disabled (default), subfolders are ignored.
Match case Yes/No No No MATCHCASE="yes" If selected, this activity filters out results that match the case of the mask specified in the Source parameter. If disabled (default), case is ignored.
Include checksum Text (options) No None
  • HASHTYPE="crc"
  • HASHTYPE="md5"
  • HASHTYPE="sha1"
  • HASHTYPE="sha256"
  • HASHTYPE="sha384"
  • HASHTYPE="512"
 Specifies a checksum to validate file data. Available algorithms are placed in order from quickest but least efficient to slowest but most efficient. This parameter is available only if the Mode parameter is set to File. The available options are:
  • None (default) - No checksum is used.
  • CRC - Cyclical Redundancy Checking. Fastest and least secure.
  • MD5 - Message Digest 5. Slower and more secure than CRC.
  • SHA1 - Secure Hash Algorithm-1. Slower and more secure than MD5.
  • SHA256 - Secure Hash Algorithm-256. Slower and more secure than SHA1.
  • SHA384 - Secure Hash Algorithm-384. Slower and more secure than SHA256.
  • SHA512 - Secure Hash Algorithm-512. Slowest and most secure.

File Filter

Property Type Required Default Markup Description
Attributes Text (options) No Doesn't matter ATTRFILTER="+R+A-H" (compress read-only & archive files but not hidden files) Instructs the activity to filter which files to act on, based on whether the file's original attribute settings match the attribute settings specified in this parameter. In Task Builder's visual mode, drop-down boxes are provided within the activity's settings to assist in the selection of attribute settings. In Task Builder's AML mode, a text item must be entered that contains the original attribute mask of the files you wish to affect. For example, if Read-only attribute is set to Off (in visual mode) or -R (in AML mode) , only source files with the Read-only attribute turned off are affected. Source files with Read-only attribute turned on will be ignored. The available options are:
  • Read-only attribute is - Specifying On or +R includes files with this attribute turned on. Specifying Off or -R includes files with this attribute turned off. Specifying Doesn't matter (default) or excluding the letter ignores this attribute.
  • Archive attribute is - Specifying On or +A includes files with this attribute turned on. Specifying Off or -A includes files with this attribute turned off. Specifying Doesn't matter (default) or excluding the letter ignores this attribute.
  • System attribute is - Specifying On or +S includes files with this attribute turned on. Specifying Off or -S includes files with this attribute turned off. Specifying Doesn't matter (default) or excluding the letter ignores this attribute.
  • Hidden attribute is- Specifying On or +H includes files with this attribute turned on. Specifying Off or -H includes files with this attribute turned off. Specifying Doesn't matter (default) or excluding the letter ignores this attribute.
  • Compression attribute is - Specifying On or +C includes files with this attribute turned on. Specifying Off or -C includes files with this attribute turned off. Specifying Doesn't matter (default) or excluding the letter ignores this attribute.
  • Encrypted attribute is - Specifying On or +E includes files with this attribute turned on. Specifying Off or -E includes files with this attribute turned off. Specifying Doesn't matter (default) or excluding the letter ignores this attribute.

Description

Error Causes

On Error

Additional Notes

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 Data Type Return Value
theDataset.FullName String Returns the absolute path (or full path) of the file. An absolute path is  one that contains the root directory and all other subdirectories up to and including the file name and extension (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).
theDataset.FileName String Returns the file name only (for example, if the source is c:\temp\foldername\filename.txt, the file name is filename.txt).
theDataset.Extension String

Returns the file extension only (for example, if the source is c:\temp\coldercame\filename.txt, the extension is .txt).
theDataset.Size Number Returns the size of the file in kilobytes (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 last write to the folder/file occurred.
theDataset.Attributes String Returns the attributes for the file.
theDataset.IsDirectory 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.

Datasets (Volume)

The table below describes the volume associated dataset fields created and populated (assuming the dataset name assigned was theDataset).

Name Data Type Return Value
theDataset.Drive Text Returns the drive from which corresponding data is retrieved.
theDataset.VolumeType Text Returns the volume type (for example, Removable).
theDataset.VolumeLabel Text Returns the volume label.
theDataset.FileSystem Text Returns the file system (for example, 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.

Example

NOTE:
  • The sample AML code below can be copied and pasted directly into the Steps Panel of the Task Builder.
  • Parameters containing user credentials, files, file paths, and/or other information specific to the task must be customized before the sample code can run successfully.

Description

This sample task gets information about PDF files in a directory, and then populates the dataset named "theDataset" with the results. A Loop activity loops through the dataset and during each iteration, displays file information in a dialog box.

Copy 
<AMFILESYSTEM ACTIVITY="get" SOURCE="C:\Temp\*.pdf" RESULTDATASET="theDataset" FILEPROPERTY="filename" SUBFOLDERS="YES" />
<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 ACTIVITY="end" />