FTP - FXP

Declaration

<AMFTP ACTIVITY="fxp" SOURCE="text" DEST="text" RESULTDATASET="text" SUBFOLDERS="YES/NO" KEEPFOLDERSTRUCT="YES/NO" MATCHCASE="YES/NO" OVERWRITE="YES/NO" ONLYIFEXIST="YES/NO" EXCLUDE="text" RE="YES/NO" TRANSFERTYPE="text (options)" VALIDATECHECKSUM="YES/NO" CHECKSUMTYPE="text (options)" DESTINATIONSESSION="text" SESSION="text" />

Related Topics

Description

File eXchange Protocol (FXP) allows data to be transferred from one FTP server to another (also known as inter-server transfers) without routing the data through the client's connection. FXP eliminates transferring data from one FTP server to a local client then to the second FTP server. In addition, the data transfer rate is independent of the client's Internet connection speed as it is based on the connection speed between the two servers, which is usually higher in bandwidth than a normal client connection.

NOTE: This activity is supported only in standard or SSL/TLS FTP connection types. To use this activity, you must first log onto both the source and destination FTP server using the FTP - Logon activity and create a separate session name for each.

Practical usage

Used for copying data from one FTP server to another. The advantage of using FXP over FTP is evident when a high-bandwidth server demands resources from another high-bandwidth server, but only a low-bandwidth client, such as a network administrator working away from location, has the authority to access the resources on both servers.

Parameters

Connection

Property Type Required Default Markup Description
Source server session Text Yes FTPSession1 SESSION="Server1" The session name to use to log onto the source FTP server.
NOTE: You must first log onto both the source and destination FTP server using the FTP - Logon activity and create a separate session name for each.
Destination server session Text Yes (Empty) DESTINATIONSESSION="Server2" The session name to use to log onto the destination FTP server.  
NOTE: You must first log onto both the source and destination FTP server using the FTP - Logon activity and create a separate session name for each.

File

Property Type Required Default Markup Description
Source server files Text Yes (Empty)
  • SOURCE="/sourcefoldername/file.txt"
  • SOURCE="/sourcefoldername/*.txt"
  • SOURCE="/source/*.txt|/source/*.doc"
  • SOURCE="file.txt"
 The files from the source server to transfer. Enter the file names manually in the provided text box or click the folder icon to open the FTP Browser which allows connection to the server in order to browse available files and folders.

This can be a fully qualified UNIX style path and file name (preferred) or a single file (requires use of the  FTP - Change folder activity). Wildcard characters (for example, * or ?) are used to download files matching a certain mask. Multiple file and/or file masks are specified by separating the entries with a pipe character (for example, *.txt|*.bak). See File Masks & Wildcards for more information.

NOTE: Files with invalid paths are ignored at runtime.
Destination server files Text Yes (Empty)
  • DEST="/destination_folder/file.txt"
  • DEST="/destination_folder/*.txt"
  • DEST="/folder/*.txt|/folder/*.doc"
  • DEST="file.txt"

The location in the destination server of where to transfer the files. Enter the file names manually in the provided text box or click the folder icon to open the FTP Browser which allows connection to the server in order to browse available files and folders.

This can be a fully qualified path or a file name or a single file (requires use of the FTP - Change folder activity).
Create and Populate FXP Dataset Text No (Empty) RESULTDATASET="theDataset" The name of a dataset to be populated with information regarding the files to be transferred. See Datasets below for the fields this dataset creates.

File Options

Property Type Required Default Markup Description
Exclude mask Text No (Empty) EXCLUDE="*.txt" If selected, this activity omits any files matching the masks specified in this parameter. File names or wildcard masks (for example, * or ?) can be used and multiple entries can be specified by separating each with a pipe character (for example, *.txt|*.bak).
Regular expression Yes/No No No RE="YES" If selected, specifies whether the value in the Exclude mask parameter is a regular expression. Regular expression, also referred to as regex or regexp, provide a concise and flexible means for matching strings of text. This parameter is disabled by default.
Transfer type Text (options) Yes Binary TRANSFERTYPE="ascii" Specifies the transfer type to use. The available options are:
  • Binary (default) -  Refers to transferring files as a binary stream of data. Where ASCII mode may use special control characters to format data, binary mode transmits the raw bytes of the file being transferred. In this way, the file is transferred in its exact original form.
  • ASCII - The transferred data is considered to contain only ASCII- formatted text. The party that is receiving the transferred data is responsible for translating the format of the received text to one that is compatible with their operating system.
Validate checksum Yes/No No No VALIDATECHECKSUM="YES" If selected, this parameter validates the integrity of data being transferred by calculating a checksum using the selected algorithm in the checksum type drop-down combo box. This parameter is disabled by deafult.
Checksum type (unlabeled) Options No CRC
  • CHECKSUMTYPE="md5"
  • CHECKSUMTYPE="sha1"

Specifies the checksum algorithm to use. The available options are:

  • CRC (default) - Cyclic redundancy check. 
  • MD5 - Message-digest algorithm 5.
  • SHA1 - Secure hash algorithm 1.
Include subfolders Yes/No No No SUBFOLDERS="YES" If selected, subfolders are searched for files matching the mask specified in the Local file(s) parameter. This parameter is set NO by default.
Preserve folder structure Yes/No No No KEEPFOLDERSTRUCT="YES" If selected, subfolders found in the source folder are created in the destination folder and source files are copied into their respective folders, rather than directly into the root of the target folder specified in the Remote file(s) parameter. This parameter is set NO by default.

This parameter becomes available when the Include subfolders parameter is selected.
Match case Yes/No No No MATCHCASE="YES" If selected, the properties set within this activity are case sensitive in relation to the FTP server. . This parameter is disabled by deafult.
Overwrite if exists Yes/No No No OVERWRITE="YES" If selected, existing files in the destination folder are overwritten. This parameter is disabled by default.

Only if exists in destination

Yes/No

No

No

ONLYIFEXIST="YES"

If selected, indicates 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. The default value is NO.

This parameter is valid only if the Overwrite if exists parameter is selected.

Description

Error Causes

On Error

Additional notes

Datasets

A dataset is a multiple column, multiple row container object where every column represents a particular variable, and each row corresponds to a given member of the dataset in question. Using the Create and populate dataset parameter, this activity creates and populates a dataset containing specific fields (rows) in addition to the standard dataset fields. The table below describes these fields (assuming the dataset name assigned was theDataset).

Name Data Type Return Value
theDataset.FXPResult Boolean The result of the transfer. If successful, 1 is returned. Otherwise, 0 is returned.
theDataset.FTPFileDate Date The modified date and time of the file to download.
theDataset.FTPFileName Text The name of the file to download.
theDataset.FTPFileSize Number The size of the file to download (in kB).
theDataset.LocalFileName Text The local file name of the file.

Example

NOTE:
  • 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.

Description

This sample task demonstrates the activities used to download files from one FTP server to another. The first two steps logs onto two separate FTP hosts and creates a unique session name for each connection. The third step performs the file transfer from one server to another. The last two steps are used to log off each FTP server.

Copy 
<AMFTP ACTIVITY="logon" SESSION="Server1Session" SERVER="ftp.server1.com" USERNAME="theuser" PASSWORD="AM2WknKdIcXr7JaSdh0lRfctA==aME" />
<AMFTP ACTIVITY="logon" SESSION="Server2Session" SERVER="ftp.server2.com" USERNAME="theuser" PASSWORD="AM2WknKdIcXr7JaSdh0lRfctA==aME" />
<AMFTP ACTIVITY="fxp" SOURCE="/Server1/myFolder/*.*" DEST="/Server2/myFolder/*.*" SUBFOLDERS="YES" KEEPFOLDERSTRUCT="YES" OVERWRITE="YES" RESULTDATASET="theDataset" SESSION="Server1Session" DESTINATIONSESSION="Server2Session" />
<AMFTP ACTIVITY="logoff" SESSION="Server1Session" />
<AMFTP ACTIVITY="logoff" SESSION="Server2Session" />