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.

Note: If the file to wait for exists on the network, it must be entered in UNC (Universal Naming Convention) format instead of pointing to a mapped drive. For example: 'z:\ShareName\FileName.xls' should be '\\ServerName\ShareName\FileName.xls'. This is because mapped drives are only accessible if/when a user is logged on, whereas, a file specified in UNC format is accessible even if the machine is locked or the user logged off.

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

Wait until file exists

  1. ACTION="exists"

  2. ACTION="not_exist"

  3. 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)

  1. FILE="C:\Folder\File.txt"

  2. FILE="C:\Folder\*.jpg"

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

Error Causes

On Error

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

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