Wait - For file
Declaration
<AMWAIT ACTIVITY="file" MODE="text (options)" FILE="text" INUSE="YES/NO" RESULTVARIABLE="text" RESULTDATASET="text" EXCLUDE="text" RE="YES/NO" ISNEWERTHAN="%DateSerial%" ISOLDERTHAN="%DateSerial%" />
Description
Causes task execution to pause at the current step until the specified file exists, no longer exists or has been modified. This activity also supports waiting until a file is no longer in a locked state (that is, no longer in use by another file or program). The file to wait for may be a local file or one that exists remotely.
Practical usage
Commonly used to wait for a file generated by a user or external application and perform subsequent activities as a result. For example, you may have a task that opens and modifies data in an Excel workbook. If that workbook is currently open and in use by someone else, the task won't be able to save changes made to it. This activity can pause execution to wait for the workbook to be closed before continuing, allowing modifications to be properly saved.
Parameters
General
| Property | Type | Required | Default | Markup | Description |
|---|---|---|---|---|---|
| Wait until | Text (options) | Yes | File exists |
|
The file condition to wait for. The available options are:
|
| Files | Text | Yes | (Empty) |
|
The path and file names of the files to wait for. Wildcard characters (that is, * or ?) may be used to wait for multiple files matching a certain mask. For example, entering C:\FolderName\*.txt will detect all text files in C:\FolderName\. |
| Wait until file is not in use | Yes/No | No | Yes | INUSE="NO" | If
selected, the step should continue waiting until the
file has not only met the condition, but is also no longer in a
locked state (or in use). If disabled, execution continues once
the file condition has been met, even though it is still locked
or in use. NOTE: It is useful to set this option to YES to ensure, for example,
that the task does not continue until a file is completely transferred
or written. |
| Populate filename into variable | Text | No | (Empty) | RESULTVARIABLE="myvarname" | The
name of an existing variable to populate with the file name
that caused this step waited for. NOTE: If the Action
parameter is set to Wait until
file does not exist, this variable will be populated with
the last file name matching the chosen mask. In all other cases,
the first file name will be populated. |
| Create and populate dataset with result information | Text | No | (Empty) | DAY="sameday" | The name of a dataset to be created and populated with information about the file that caused this step to wait. In addition to the standard fields, this dataset will contain the fields listed below under Datasets. |
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 these fields (assuming the dataset name assigned was theDataset).
| Name | 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 YES if the file is a folder. Returns NO if it's not. |
| theDataset.IsReadOnly | Yes/No | Returns YES if the file's attribute is set to Read Only. Otherwise, returns NO. |
| theDataset.IsArchive | Yes/No | Returns YES if the file's attribute is set to Archive. Otherwise, returns NO. |
| theDataset.IsSystem | Yes/No | Returns YES if the file's attribute is set to System. Otherwise, returns NO. |
| theDataset.IsHidden | Yes/No | Returns YES if the file's attribute is set to Hidden. Otherwise, returns NO. |
| theDataset.IsCompressed | Yes/No | Returns YES if the file is compressed. Otherwise, returns NO. |
| theDataset.IsAccessible | Yes/No | Returns YES if the file is accessible. Otherwise, returns NO. |
Examples
- 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.
Example 1
This task waits for file "C:\Temp3\File.txt" to no longer exist. When the condition results to TRUE, a dataset is created and populated with details about the monitored file. Finally, a message box is generated that furnishes details (previously populated into the dataset) about the file in question.
<AMWAIT ACTIVITY="file" MODE="not_exist" FILE="C:\Temp3\File.txt" RESULTDATASET="theDatasetName" />
<AMSHOWDIALOG>File name - %theDataset.Name%File size - %theDataset.Size%File's last modified date - %theDataset.ModifiedOn%</AMSHOWDIALOG>Example 2
This task waits for any text file with a creation date of 30 days or less to exist in directory C:\Temp and displays a message dialog with details in regards to the file, such as file name, size, creation and last modified date.
<AMVARIABLE NAME="theVar" VALUE="" />
<AMWAIT ACTIVITY="file" FILE="C:\Temp\*.txt" INUSE="NO" RESULTVARIABLE="theVar" RESULTDATASET="theFileData" EXCLUDE="*log" ISNEWERTHAN="%DateAdd( "d", -30, CStr( Now() ))%" />
<AMSHOWDIALOG WINDOWTITLE="File Info">File name - %theFileData.Name%File size - %theFileData.Size%File creation date - %theFileData.CreatedOn%File last modified - %theFileData.ModifiedOn%</AMSHOWDIALOG>