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

  1. MODE="file"

  2. MODE="folder"

  3. MODE="both"

  4. MODE="volume"

Indicates what this activity should be performed on. The available options are:

  • File (default) -  This activity will be performed on file(s).

  • Folder - This activity will be performed on folder(s).

  • File and Folder - This activity will be performed on files and folders.

  • Volume - This activity will be performed on volume(s). A volume can be a single accessible storage area such as a single hard disc or partition.

Source

Text

Yes

(Empty)

  1. SOURCE="c:\

  2. SOURCE="c:\folder\file.txt"

  3. SOURCE="c:\folder\*.pdf"

  4. SOURCE="c:\source\*.txt|c:\source\*.bak"

  5. SOURCE="c:\folder\subfolder"

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

  1. FILEPROPERTY="fullname"

  2. FILEPROPERTY="parent"

  3. FILEPROPERTY="filename"

  4. FILEPROPERTY="extension"

  5. FILEPROPERTY="size"

  6. FILEPROPERTY="isreadonly"

  7. FILEPROPERTY="creationtime"

  8. FILEPROPERTY="lastaccesstime"

  9. FILEPROPERTY="lastwritetime"

  10. FILEPROPERTY="attributes"

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:

  • Full name - The full path and file name of the file (e.g., C:\Temp\FileName.txt)

  • Parent - The parent folder (e.g., C:\Temp)

  • Filename - The file name and extension, excluding path (e.g., FileName.txt)

  • Extension - The file's extension (e.g., .txt)

  • Size - The size of the file in KB (e.g., 1592)

  • Is read only - Whether the file is Read Only (e.g., True or False)

  • Creation time - The file's creation date/time (e.g., 3/20/2010 9:20:20 AM)

  • Last access time - The date/time the file was last accessed (e.g., 3/20/2010 9:20:20 AM)

  • Last write time - The date/time the file was last written to (e.g., 3/20/2010 9:20:20 AM)

  • Attributes - The file's attribute (e.g., Archive)

Information to retrieve (volume)

Text

(options)

Yes

Fullname

  1. DRIVEINFO="volumetype"

  2. DRIVEINFO="volumelabel"

  3. DRIVEINFO="filesystem"

  4. DRIVEINFO="availablespaceforuser"

  5. DRIVEINFO="totalavailablespace"

  6. DRIVEINFO="totalcapacity"

  7. DRIVEINFO="usedspace"

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:

  • Volume type (default) - The volume type (e.g., Removable).

  • Volume label - The volume label.

  • File system - The file system used (e.g., 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="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)

  1. EXCLUDE="*.txt"

  2. EXCLUDE="*.txt|*.bak

  3. EXCLUDE="c:\foldename"

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:

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

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