File
System - Get file metadata
Declaration
<AMFILESYSTEM ACTIVITY="get_metadata" FILE="text" RESULTDATASET="text" SUBFOLDERS="YES/NO" MATCHCASE="YES/NO" EXCLUDE="text" RE="YES/NO" ISNEWERTHAN="%DateSerial+TimeSerial%" ISOLDERTHAN="%DateSerial+TimeSerial%" ATTRFILTER="+r+a-s+h-c-e" />
Description
Retrieves metadata information of one or more files and populates a dataset with results. To specify multiple files of the same type, use wildcard characters (for example, * or ?). To specify multiple files of different types or multiple wildcard masks, separate them with a pipe symbol (for example, c:\*).
Practical usage
Commonly used as a file management tool for cataloging or categorizing archived information due to its ability to identify precise information about a file. For instance, metadata written into a digital photo file will identify who owns it, copyright & contact information, what camera created the file, along with exposure information and descriptive information such as keywords about the photo, making the file searchable on the computer and/or the Internet.
Parameters
General
| Property | Type | Required | Default | Markup | Description |
|---|---|---|---|---|---|
| File | Text | Yes | (Empty) | FILE="c:\temp\file.txt" | The path and file name of the files to retrieve metadata from. This can be a fully qualified path and file name (preferred) or a single file (requires use of the File System - Change folder activity). You can use wildcard characters (for example, * or ?) to specify all files matching a certain mask. You can specify multiple files and file masks by separating each entry with a pipe character (|) (for example, c:\temp\*.txt|c:\backup\*.bak). See File Masks & Wildcards for more details. |
| Create and populate dataset with result | Text | No | (Empty) | RESULTDATASET="theData" | The name of the dataset to create and populate with metadata information. The number and types of metadata populated into the dataset depends largely on the type of file the metadata was retrieved from. A list of metadata common to most file types can be found below under Datasets. |
File Options
| Property | Type | Required | Default | Markup | Description |
|---|---|---|---|---|---|
| Include subfolders | Yes/No | No | No | SUBFOLDERS="YES" | If selected, denotes that, if present, subfolders should be searched for files matching the mask specified in the File parameter. If disabled (default), subfolders are ignored. Only files that exist in the root of the source folder will be searched. |
| Match case | Yes/No | No | No | MATCHCASE="YES" |
If selected, the activity becomes case sensitive. If disabled (default), the activity becomes case insensitive, whereas, it does not distinguish between uppercase and lowercase characters. |
| Exclude mask | Text | No | (Empty) | EXCLUDE="*.txt" |
Causes this action to omit files matching the masks specified. 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 selected, indicates that the value entered in the Exclude mask parameter will be interpreted as a regular expression. If disabled (default) the value will be interpreted as normal readable 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
| 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:
|
Additional notes
Datasets
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.Computer | Text | Returns the name of the computer where the file resides. |
| theDataset.Date_accessed | Date | Returns the date/time the file was last accessed. |
| theDataset.Date_created | Date | Returns the date/time the file was last created. |
| theDataset.Date_modified | Date | Returns the date/time the file was last modified. |
| theDataset.Name | String | Returns the file name only. For example, if the source is c:\temp\folderName\filename.txt, the file name is filename.txt. |
| theDataset.Filename | String | Returns the file name only, similar to" theDataset.Name." |
| theDataset.Size | Number | Returns the size of the file in kB. |
| theDataset.Folder | Text | Returns the root folder of where the file resides. For example, if the source is c:\temp\foldername\filename.txt, the value returned is "Temp (C:)." |
| theDataset.Folder_path | Text | Returns the full path to the file omitting the file name). For example, if the source is c:\temp\foldername\filename.txt, the value returned is c:\temp\foldername. |
| theDataset.Path | Text | Returns the full path to the file including the file name. |
| theDataset.Item_type | Text | Returns the type of file. |
| theDataset.Owner | Text | Returns the name of the file's owner. |
| theDataset.Shared | Yes/No | Returns YES if the file is shared. Returns NO if not shared. |
| 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. |
Example
- 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.
Description
This sample task gets metadata from files and stores it into a dataset.
<AMFILESYSTEM ACTIVITY="get_metadata" FILE="C:\Temp\*.pdf" RESULTDATASET="theDataset" />
<AMLOOP ACTIVITY="dataset" DATASET="theDataset" />
<AMSHOWDIALOG WINDOWTITLE="Metadata ">File name: %theDataset.Filename%File size: %theDataset.Size%File path: %theDataset.Path%File type: %theDataset.Item_type%File owner: %theDataset.Owner%File creation date: %theDataset.Date_created%File modified date: %theDataset.Date_modified%</AMSHOWDIALOG>
<AMLOOP ACTIVITY="end" />