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

Description

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, this activity could be used to return a folder listing. This list could then be looped to "examine" each file (such as the date) before performing some other action for each individual file based on the result.

Advanced FTP can also be used to perform commands that are server specific and/or not supported by other Automate 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 Advanced FTP Commands table below.
NOTE: The FTP command you need to execute may not be included in the list or you may 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 comb box 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 required parameters for the command specified. The use of parameters vary depending on the command selected and in certain cases may not be required. 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 will not be overwritten, however, an error will occur as a result.
  • Overwrite existing file - If a file in the destination folder matches the name of the file being transferred, it will be 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 will 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 then 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 table below describes the available FTP commands found in the FTP command drop-down comb box (displayed in alphabetical order for convenience). Data includes command name, compatible command line entry, general description and sample syntax (if applicable). Note that depending upon the version of FTP and the operating system being used, each of the below commands may or may 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. One example is 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: Binary should be used 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 (i.e., 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 table below describes these fields (assuming the dataset name assigned was 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 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:
  • The sample AML code below can be copied and pasted directly into the Steps Panel of the Task Builder.
  • Parameters containing user credentials, files, file paths, and/or other information specific to the task must be customized before the sample code can run successfully.

Description

This sample task will demonstrate how Automate can delete files older than 30 days by way of 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 off 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" />