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 (e.g., 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.

General Parameters

Property	Type	Required	Default	Markup	Description
Wait until	Text (options)	Yes	Wait until file exists	ACTION="exists" ACTION="not_exist" ACTION="changed"	The file condition to wait for. The available options are: File exists (default) - Wait until the file exists on the system. This can be a file that has been copied onto the system or one that is newly created. File does not exist - Wait until the file does not exist (e.g., file moved or deleted). File has changed - Wait until changes are made to the file.
File(s)	Text	Yes	(Empty)	FILE="C:\Folder\File.txt" FILE="C:\Folder\*.jpg" FILE="FileName.txt"	The path and filename(s) of the file(s) to wait for. Wildcard characters (* 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 set to YES (default), 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 set to NO, 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(s) that caused this step waited for. Note that 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(s) that caused this step to wait. In addition to the standard fields, this dataset will contain the fields listed below under Datasets.

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

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

The sample AML code below can be copied and pasted directly into the Steps panel of the Task Builder.

Sample 1: This task waits for file "C:\Temp3\File.txt" to no longer exist. Wait until file is not in use as well. Additionally, create and populate a dataset named "theDatasetName" with details of the file that caused this action to continue. Finally, a Message Box is generated that furnishes some details about the file.

<AMWAITFORFILE ACTION="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>

Sample 2: This task waits for any file to be added to the C:\Temp directory excluding log files, Excel documents and files that are older than 30 days. Populate a variable named "theVar" with details in regards to the file that is added.

<AMWAITFORFILE FILE="C:\Temp\*.*" EXCLUDE="*.log |*.xls" 
ISNEWERTHAN="%DateAdd( &quot;n&quot;, -30, CStr( 
Now() ))%" INUSE="NO" RESULTVARIABLE="theVar" />