Wait for File Action Icon

Wait for File

Declaration

<AMWAITFORFILE ACTION="text (options)" FILE="text" RESULTVARIABLE="text" RESULTDATASET="text" />

See Also

Pause Task | Wait for File | Wait for Pixel | Wait for Pointer | Wait for Process | Wait for Window | Stop Timer | Read Timer  | Start Timer

Description

Causes task execution to pause at the current line until the specified file exists, no longer exists or has been modified. This action is also capable of waiting until a file is no longer in a locked state (or in use). The file to wait for may be a local file or one that exists on the network. This action accepts wildcard characters (* or ?).

NOTE: If specifying a file that exists on the network, make sure to enter the path in UNC (Universal Naming Convention) format as opposed to a mapped drive. For example: z:\share\Book1.xls should be entered as \\server\share\Book1.xls. A mapped drive is only accessible 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 an external application to exist or wait until a file has been closed indicating a process has completed successfully. 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 action can pause execution to wait for the workbook to be closed before continuing, allowing modifications to be properly saved.

Parameters

General Properties

Property

Type

Req'd

Default

Markup

Description

Action

Text (options)

Yes

Wait until file exists

ACTION="not_exist"

The file action to wait for. The available options are:

  • Wait until file exists - 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.

  • Wait until file does not exist - Wait until the file does not exist (i.e. file moved or deleted).

  • Wait until 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 name of the file(s) to perform a wait on. This should be a fully qualified file name, containing the complete drive and path. Wildcard characters (* or ?) may be used to wait for files matching a certain mask. Assume that C:\FolderName\*.txt is entered in this field.

  • If the Action parameter is set to Wait until file exists, this step will wait until ANY text file exists in C:\FolderName.

  • If the Action parameter is set to Wait until file does not exist, this step will wait until ALL text files no longer exist in C:\FolderName.

  • If the Action parameter is set to Wait until file has changed, this step will wait until ANY text file located in C:\FolderName has been modified.

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 done being transferred or written.

Populate filename into variable

Text

No

(Empty)

RESULTVARIABLE="myvarname"

The name of an already created variable that should be populated with the file name that caused this step to continue. This is especially useful if wildcard characters are used in the File parameter so that the file itself may be referenced in later steps.

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

Text

No

(Empty)

DAY="sameday"

The name of a dataset to be created and populated with the file data for the file that caused this step to continue.

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 file mask. In all other cases, the first file name will be populated. In addition to the standard fields, this dataset will contain the fields listed below under Notes.

Options Properties

Property

Type

Req'd

Default

Markup

Description

Exclude Mask

Text

No

(Empty)

EXCLUDE="*.txt"

Causes this action to ignore files matching the mask(s) 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

Only if Newer Than

Date

No

No

ISNEWERTHAN=

"%DateSerial(2001,10,12) + TimeSerial(00,00,00)%"

If enabled, only files that are newer than the date specified will be monitored. If disabled (default), file dates are ignored.

Only if Older Than

Date

No

No

ISOLDERTHAN=

"%DateSerial(2001,10,12) + TimeSerial(00,00,00)%"

If enabled, only files that are older than the date specified will be monitored. If disabled (default), file dates are ignored.

Attributes Properties

Property

Type

Req'd

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 are affected by the attribute change based on the original attribute settings of the source files.

In visual mode, a group of controls are provided to assist in the selection of this parameter. In AML mode, a single text item must be specified that contains the original attribute mask of the files you wish to affect.

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 Properties

The Description tab allows you to customize the text description of any step as it appears in the Task Builder's Steps Pane.

More on setting custom step description

Error Causes Properties

The Error Causes tab allows you to select/omit specific errors that should cause a particular step to fail.

More on Error Causes properties

On Error Properties

The On Error tab allows you to determine what the task should do if a particular step encounters an error.

More about On Error properties

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.

Variables and Expressions

All text fields allow the use of expressions, which can be entered by surrounding the expression in percentage signs (example: %MYVARIABLE%, %Left('Text',2)%). To help construct these expressions, you can open Expression Builder from these fields by pressing F2.

More on variables
More on expressions

More on the expression builder

Example

NOTE: The code below can be copied and pasted directly into the Steps pane of the Task Builder.

 

Example 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>

 

 

Example 2 - Wait 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" />

 

 

↑ Top of Page