FTP - Advanced

Declaration

<AMFTP ACTIVITY="advanced" FTPCOMMAND="text (options)" PARAMETER="text" SUPPRESSADDITIONALOPERATIONS="YES/NO" TRANSFEROPTION="text (options)" SENTDATAVARIABLE="text" RESULTVARIABLE="text" FTPLONGLISTDATASET="text" SESSION="text" />

Related Topics

Overview

Sends specific customized commands to an FTP server. For most transactions, use the standard FTP Upload/Download activities.

NOTE: An FTP session is required to run this activity. Use the FTP - Logon activity to create a session.

Practical usage

The standard FTP download and upload commands send predetermined command sequences to the server. FTP Advanced is useful when it is necessary to create or perform a customized sequence of commands. For example, you can use this activity to return a folder listing. This list can be looped to examine each file (such as the date) before performing some other action for each individual file based on the result.

You can also use advanced FTP to perform commands that are server specific and/or not supported by other Automate Desktop FTP activities such as Move (moves the file on the FTP Server without downloading it first).

Parameters

Connection

Property Type Required Default Markup Description
Session Text Yes FTPSession1 SESSION="SessionName" Specifies the session name (created by a previous FTP - Logon step) where this activity originates. This permits several FTP activities to be linked to a specific session, allowing multiple simultaneous FTP transfers to take place within a single task.  

Advanced

Property Type Required Default Markup Description
FTP command Text Yes (Empty)
  • FTPCOMMAND="long_list"
  • FTPCOMMAND="short_list"
  • FTPCOMMAND="get"
  • FTPCOMMAND="mget"
  • FTPCOMMAND="put"
  • FTPCOMMAND="mput"
  • FTPCOMMAND="delete"
  • FTPCOMMAND="mdelete"
  • FTPCOMMAND="rename"
  • FTPCOMMAND="passive"
  • FTPCOMMAND="ccc"
  • FTPCOMMAND="system"
  • FTPCOMMAND="help"
  • FTPCOMMAND="ascii_mode"
  • FTPCOMMAND="binary_mode"
  • FTPCOMMAND="up_folder"
  • FTPCOMMAND="make_folder"
  • FTPCOMMAND="remove_folder"
  • FTPCOMMAND="change_folder"
  • FTPCOMMAND="get_current_folder"
  • FTPCOMMAND="file_exist"
  • FTPCOMMAND="folder_exist"
  • FTPCOMMAND="checksum"
  • FTPCOMMAND="site"
  • FTPCOMMAND="user_defined"
 Specifies the advanced command to execute. Information regarding the list of advanced commands in the drop-down combo box is available in the following Advanced FTP commands table.
NOTE: The FTP command you need to execute mightnot be included in the list or you might be required to run a custom or server specific command. In such cases, you can select the User defined option from the FTP command drop-down list to define a custom command, or select the Site command option to define a server or site specific command. Use the Parameter(s) parameter to enter your custom or site specific command.
Parameter(s) Text Yes, depending on the option selected for the FTP command parameter (see Description for details) (Empty)
  • PARAMETER="c:\filename.txt"
  • PARAMETER="*.txt"
  • PARAMETER="Foldername"
 Indicates the parameters for the specified FTP command . The use of parameters vary, depending on the FTP command selected and in certain cases may not be required.
NOTE: Use an absolute path for FTP commands requiring a file path.

This parameter is required if the FTP command parameter is set to Download file, Download multiple files (mget), Upload file, Upload multiple files (mput), Delete file, Delete multiple files (mdelete), Rename file, Create folder, Remove folder, Change folder, File exist, Folder exist, Get file checksum, Site command, or User defined.
Suppress additional operations Yes/No No No SUPPRESSADDITIONALOPERATIONS="YES" If selected, additional operations are suppressed during file transfers. This parameter is disabled by default and only available if the FTP command parameter is set to Download file, Download multiple files (mget), Upload files, or Upload multiple files (mput).
Transfer options (unlabeled) Text (options) No Do not overwrite existing file
  • TRANSFEROPTION="overwrite"
  • TRANSFEROPTION="append"
  • TRANSFEROPTION="resume"
 Defines the action which is performed if the corresponding target file already exists. This parameter is only available if the FTP command parameter is set to Download file, Download multiple files (mget), Upload files, or Upload multiple files (mput).

The available options are:

  • Do not overwrite existing file - If a file in the destination folder already exists, it is not overwritten, however, an error occurs as a result.
  • Overwrite existing file - If a file in the destination folder matches the name of the file being transferred, it is overwritten.
  • Append to existing file - If a file in the destination folder matches the name of the file being transferred, data is extracted from the transferred file and appended to the end of the existing file. This option is not available if the FTP command parameter is set to Upload file or Upload multiple files (mput) and the Suppress additional operations parameter is selected.
  • Resume file transfer - Specifies downloads resume on files that are partially downloaded (if the server supports resuming transfers). If a file in the destination folder matches the name of the file being transferred, it treats the destination file as an incomplete transfer. If the destination file is already a complete file, the transferred file replaces the destination file. This option is not available if the FTP command parameter is set to Download file or Download multiple files (mget) and the Suppress additional operations parameter is selected.
Populate variable with sent data Text No (Empty) SENTDATAVARIABLE="variableName" Specifies the name of an existing variable to be populated with information regarding the command or any data sent to the server.
Populate variable with return data Text No (Empty) RESULTVARIABLE="variableName" Specifies the name of an existing variable to be populated with information regarding return data (depending on the command sent).
Create dataset with file listing information Text No (Empty) FTPLONGLISTDATASET="datasetname" Specifies the name of the dataset to be populated with file listing information. Only available if the Get long file list command is selected, which retrieves all files that reside in the location specified and populates a dataset with the results. You can loop through the dataset  and perform other actions on each file or determine whether or not to download the current file depending on the name, date, size, etc. More on the exclusive column names that this dataset creates are detailed below under Datasets.

Advanced FTP commands

The following table describes the available FTP commands found in the FTP command drop-down list (displayed in alphabetical order for convenience). Data includes command name, compatible command line entry, general description, and sample syntax (if applicable). Note that depending on the version of FTP and the operating system, some of the following commands might not work.

Command DOS Description Sample Syntax (if applicable)
ASCII mode TYPE A Switches the mode of file transfer to ASCII. Often used when transferring text files with FTP servers that do not use ASCII as the base character set. For example, EBCDIC. ASCII
Binary mode TYPE I Switches the mode of file transfer to binary. Normally used to transfer binary files or any file types other than ASCII.
NOTE: Use binary when transferring executable files. In binary mode, the file is moved byte-by-byte.
 BINARY
Change folder CWD Changes the current working directory or folder to a new working directory or folder in the remote server. "/ParentFolder/NewFolder"
Clear command channel mode CCC Reverts a secured control/command channel back to plaintext (unsecured). If the CCC command is enabled, the FTP client connects to the server, negotiates a secure connection, authenticates the user, then reverts back to plaintext.
NOTE: SSL connections require CCC when connecting in PORT mode from behind a NAT firewall.
 N/A
Create folder MKD Creates a folder or directory in the remote server. MKD NewFolder
Delete file DELE Deletes a single file in the remote server. "/Home/FileToDelete.txt"
Delete multiple files (mdelete) MDELETE Deletes one or more files in the remote server using a mask. *.dat
Download file GET Downloads a single file (PORT followed by RETR). "/RemoteFileName.exe/" [optional]\"C:\\LocalFileName.exe\"
Download multiple files (mget) MGET Downloads one or more remote files to the local computer "/RemoteFolder/*.html"
File exists --- Checks if a file exists in the remote server. "/RemotePath/FileName"
Folder exists --- Checks if a folder exists in the remote server. "RemoteFolderPath"
Get file checksum --- Gets the checksum of the remote file using a specific algorithm (CRC, MD5, SHA1). N/A
Get long file list LIST Retrieves a remote server verbose file listing (PORT command followed by LIST).   *.exe
Get short file list NLST Retrieves a basic file listing located in the remote server (PORT command followed by NLST command). *.exe
Help HELP Displays FTP help information N/A
Passive mode PASV Switches to passive mode to properly negotiate server connections through firewalls. In the passive mode, the client sends a PASV command to the server and then receives a server IP address and server port number, which the client then uses to open a data connection to the server IP address and server port number received. N/A
Remove folder RMD Removes a folder in the remote server.   \"Old Folder\"
Rename file RNFR Renames a file in the remote server (for example, RNFR command followed by RNTO command). "/Home/Folder/FileName.txt" "/Home/NewFolder/NewFileName.txt"
Retrieve current folder PWD Displays the current directory on the remote computer (literally, print working directory). "FolderName"
Site command SITE Sends site specific commands to remote server. CHMOD or DIRSTYLE
System information SYST Retrieves information about the remote server.
NOTE: Only supported in FTP with normal SSL/TLS connection types.
 N/A
Up one folder CDUP Change to the parent folder N/A
Upload file PUT Upload one file (PORT followed by STOR). \"C:\\Local FileName.exe\" [optional]\"\Remote FileName.exe\"
Upload multiple files MPUT Upload one or more files (PORT followed by MPUT). \"C:\\*.exe\" [optional]\"\RemoteFolder\"
Upload file PUT Upload one file (PORT followed by STOR). \"C:\\Local FileName.exe\" [optional]\"/Remote FileName.exe\"
User defined --- Issues a custom command to the FTP server. N/A

Description

Error Causes

On Error

Additional 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 in addition to the standard dataset fields. The following table describes these fields (assuming the dataset name assigned is theDataset):

Name Data Type Return Value
theDataset.FTPFileName Text The name of the current file.
theDataset.FTPFileSize Number The size of the current file.
theDataset.FTPFileDate Date The last modified date of the current file.
theDataset.FTPFileType Boolean Whether the current file type is a folder or file. If it is a folder, 0 is returned. If it is a file, 1 is returned.

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

The following sample task demonstrates how Automate Desktop can delete files older than 30 days using FTP. The first step logs onto to an FTP server. Next, a Get long file list command using the FTP Advanced action populates a dataset with the file list results. A Loop - Dataset activity loops through the dataset that holds the list of files and folders on the FTP server. Within the loop block of steps, an If action is used specifying the %DateDiff()% function, which gets a day differential between today's date and the date of the file on the FTP server. If the file is older than 30 days, it is deleted. If not, it is skipped. The last step logs out of the FTP server.

Copy 
<AMFTP ACTIVITY="logon" SERVER="YourFTPHost" USERNAME="YourUsername" PASSWORD="AM1NYGaQ+SuSz0MaN4SJbOlag==aME" SESSION="FtpSession1" />
<AMFTP ACTIVITY="advanced" FTPCOMMAND="long_list" PARAMETER="*.*" FTPLONGLISTDATASET="FileList" SESSION="FtpSession1" />
<AMLOOP ACTIVITY="dataset" DATASET="FileList"><AMIF EXPRESSION="%DateDiff(&quot;d&quot;, DateValue(FileList.FTPFileDate), Now())% &gt; 30"><AMFTP ACTIVITY="delete" SOURCE="%FileList.FTPFileName%" SESSION="FtpSession1" /></AMIF></AMLOOP>
<AMIF EXPRESSION="%DateDiff(&quot;d&quot;, DateValue(FileList.FTPFileDate), Now())%" USECOMPLEXUI="YES" />
<AMFTP ACTIVITY="delete" SOURCE="%FileList.FTPFileName%" SESSION="FtpSession1" />
<AMIF ACTIVITY="end" />
<AMLOOP ACTIVITY="end" />
<AMFTP ACTIVITY="logoff" SESSION="FtpSession1" />