FTP Download Action

Declaration

<AMFTPDOWNLOAD SOURCE="text" DEST="text" EXCLUDE="text" TRANSFERTYPE="ASCII" SUBFOLDERS="yes/no" KEEPFOLDERSTRUCT="yes/no" ONLYFOLDERSTRUCT="yes/no" OVERWRITE="yes/no" ONLYIFEXIST="yes/no" SESSION="text">

See Also

FTP Download Action-Setting Properties, FTP Log On, FTP Upload, FTP Download, FTP Delete, FTP Rename, FTP Create Folder, FTP Remove Folder, FTP Change Folder, HTTP Post

Description

Downloads the file(s) specified from the FTP server. To specify more than one file, use wildcards (i.e. * or ?). To specify multiple files or wildcard masks, separate them with a vertical bar (i.e. *.txt|*.bak).

Practical Usage

Automated download of files from an FTP Server such as program updates, databases, reports, etc.

Parameters

General Tab

Remote File

Text, Required
MARKUP:
a) SOURCE="/sourcefoldername/file.txt"
b) SOURCE="/sourcefoldername/*.txt"
c) SOURCE="/sourcefoldername/*.txt|/sourcefoldername/*.doc"
c) SOURCE="file.txt"

Specifies the file(s) to download. This can be a fully qualified UNIX style path and filename (preferred) or a single file (requires use of the FTP Change Folder action). Wildcards (i.e. *.* or ?) may be used to download files matching a certain mask. Multiple file and/or file masks may be specified by separating the entries with the | symbol  (i.e. *.txt|*.bak).

Local File

Text, Required
MARKUP:
a) DEST="c:\foldername\file.txt"
b) DEST="c:\foldername\*.txt"
c) DEST="file.txt"

Specifies the destination folder and (optional) filename for the file(s) being downloaded. This can be a fully qualified path or a filename. Folders that do not exist will be automatically created at runtime.

Session Name

Text, Optional default="default"
MARKUP: SESSION="SeverB"

Specifies the session (created in a previous FTP Log On action) that should be used to perform the download. This allows for multiple simultaneous FTP transfers to take place. The default session name is FTPSession.

Create and populate dataset (only available in non compatibilty mode)

Variable, Optional default - (blank)
MARKUP: RESULTDATASET="datasetname"

Specifies the name of a dataset to be populated with information regarding the files to download. Refer to the Notes section below for more details about created datasets.

NOTE: If enabling Compatibility Mode is required, the 'FTP Advanced' action can be used to populate a dataset with file listings. For example:

Get short file list: Retrieve a basic file listing (PORT followed by NLST).

Get long file list: Retrieve a verbose file listing (PORT followed by LIST).

Options Tab

Include subfolders

Yes/No, Optional default - NO
MARKUP: SUBFOLDERS="YES"

When set to YES, specifies that, if present, subfolders should be searched for files matching the mask specified in the Remote File parameter.

Preserve Folder Structure

Yes/No, Optional default - YES
MARKUP: KEEPFOLDERSTRUCT="NO"

When set to YES, specifies that subfolders found in the source folder should be created in the destination folder and source files should be copied into their respective folders rather than directly into the root of the target folder specified in the Local File parameter. This option is available only if the Include subfolder parameter is set to YES. If set to NO this parameter is ignored.

Only folder structure

Yes/No, Optional default - NO
MARKUP: ONLYFOLDERSTRUCT="YES"

When set to YES, specifies that subfolders found in the source folder should be created in the destination folder but no files will be copied. Enabling this option causes any file-specific parameters to be ignored. This parameter is valid only if the Include subfolder parameter is set to YES.

Overwrite Existing Files

Yes/No, Optional default - NO
MARKUP: OVERWRITE="YES"

When set to YES, specifies that, if files already exist they should be overwritten.

Only if exist in destination

Yes/No, Optional default - NO
MARKUP: EMPTYFOLDERS="YES"

When set to YES, specifies that only files that already exist in the destination will be copied from the source. All other files, regardless of whether they match the mask or other parameter settings will be bypassed. Valid only if the Include subfolder parameter is YES.

Exclude Mask

Text, Optional default - (blank)
MARKUP: EXCLUDE="*.txt"

Causes the action to omit the download of files matching the mask(s) specified. Filenames or wildcard (i.e. * or ?) masks may be used, multiple entries may be specified by separating them with the | symbol (i.e. *.txt|*.bak).

Notes

Fixed field Dataset

Using the Create and populate dataset parameter creates a fixed field AutoMate dataset. A dataset is a multiple column, multiple row container object.

 

More On Datasets

 

Exclusive Column Name Description

The table below describes the set of columns that a dataset creates exclusive to this action (assuming the dataset name assigned was theDataset).

 

Name

Data Type

Return Value

theDataset.DownloadResult

Boolean

The result of the download. If successful, 1 is returned. Otherwise, 0 is returned.

theDataset.FTPFileDate

Date

The modified date and time of the file to download.

theDataset.FTPFileName

Number

The name of the file to download.

theDataset.FTPFileSize
 

Date

The size of the file to download (in kb).

theDataset.LocalFileName
 

Number

The local file name of the file.

theDataset.SQLQuery
 

Text

The SQL Query that was used to generate this dataset (If a SQL Query was not used, this value is empty).

theDataset.Datasource
 

Text

The datasource used for the SQL Query, if applicable.

theDataset.ColumnNames
 

Text

A comma-delimited list of the column names in the dataset

 

Specific Column Name Description

The table below describes the common set of columns that a dataset creates (assuming the dataset name assigned was theDataset).

Name

Data Type

Return Value

theDataset.CurrentRow

Number

The current row that will be accessed in the dataset by an expression that does not contain a specific row index.

theDataset.TotalRows

Number

The total number of rows in the dataset

theDataset.TotalColumns

Number

The total number of columns (not including the static columns) in the dataset.

theDataset.ExecutionDate
 

Date

The date and time the dataset was created and populated

theDataset.RowsAffected
 

Number

The number of rows affected by an update.

theDataset.SQLQuery
 

Text

The SQL Query that was used to generate this dataset (If a SQL Query was not used, this value is empty).

theDataset.Datasource
 

Text

The datasource used for the SQL Query, if applicable.

theDataset.ColumnNames
 

Text

A comma-delimited list of the column names in the dataset

 

Custom Description

This action includes the Description tab for entering a custom step description.

More on setting custom step description

Standard Error Handling Options

This action also includes the standard Error Causes and On Error failure handling options/tabs.

More on Error Handling Options

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.

<AMFTPDOWNLOAD SOURCE="/Public/*.*" DEST="C:\Temp\*.*" SUBFOLDERS="YES" OVERWRITE="YES" />