FTP - Advanced

Declaration

<AMFTP ACTIVITY="advanced" FTPCOMMAND="long_list" 
PARAMETER="text" SENTDATAVARIABLE="text" RESULTVARIABLE="text" 
FTPLONGLISTDATASET="text" MATCHCASE="YES/NO" />

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

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 FTP activities such as "Move" (moves the file on the FTP Server without downloading it first).

Connection Parameters

Property	Type	Required	Default	Markup	Description
Session	Text	Yes	FTPSession1	SESSION="SessionName"	Specifies the session name (created in a previous FTP Log On step) that this activity should originate from. This permits several FTP activities to be linked to a specific session, thus, allowing multiple simultaneous FTP transfers to take place within a single task.

Advanced Parameters

Property	Type	Required	Default	Markup	Description
FTP command	Text	Yes	(Empty)	FTPCOMMAND="connect"	Specifies the command to execute. FTP commands are the basis of the file transfer technology, and are needed for all aspects of the file sharing and receiving process. The most common FTP commands are dispersed into separate activities. However, there remains myriad commands that are necessary for a successful session. A variety of advanced commands are described in the Advanced FTP Commands table below.
Parameter	Text	No	(Empty)	PARAMETER="c:\filename.txt" PARAMETER="Foldername"	Indicates the parameter for the command specified. The use of this parameter varies depending on the command selected and in certain cases is not required.
Populate variable with sent data	Text	No	(Empty)	SENTDATAVARIABLE="variablename"	Specifies the name of a variable to be populated with information regarding sent data.
Populate variable with return data	Text	No	(Empty)	RESULTVARIABLE="variablename"	Specifies the name of a 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 GetLongFileList 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.
Match Case	Yes/No	Yes	No	MATCHCASE="Yes"	Indicates whether the properties set within this activity should be case sensitive in relation to the FTP server. The default value is NO.

Description tab - A custom description can be provided on the Description tab to convey additional information or share special notes about a task step.

Error Causes tab - Specify how this step should behave upon the occurrence of an error. (Refer to Task Builder > Error Causes Tab for details.)

On Error tab - Specify what AWE should do if this step encounters an error as defined on the Error Causes tab. (Refer to Task Builder > On Error Tab for details.)

Advanced FTP Commands

It's important to keep in mind that this is just a general list of advanced commands and doesn't include company or server specific FTP commands. Remembering them all and knowing when to execute them can be tedious.

Command	DOS	Description	Sample Syntax (if applicable)
Connect		Connect to an FTP server.	ftp.domain.com or 207.46.133.140.
Username	USER	Provide a username for logging in	anonymous
Password	PASS	Provide a password for logging in	password
Help	HELP	Retrieve FTP help information	N/A
System information	SYST	Retrieve information about the remote FTP server	N/A
Site command	SITE	Issue server specific commands that are not part of the FTP RFC.	CHMOD or DIRSTYLE
Passive mode	PASV	Switch to passive mode to negotiate file transfers through firewalls	N/A
Ascii mode	TYPE A	Switch to ASCII transfer mode. Used when transferring text files with FTP servers that do not use ASCII as the base character set.  One example is EBCDIC.	N/A
Binary mode	TYPE I	Switch to binary transfer mode. Used when transferring binary files.	N/A
Download file	GET	Download single file (PORT followed by RETR).	\"/Remote FileName.exe\" [optional]\"C:\\Local FileName.exe\"
Upload file	PUT	Upload one file (PORT followed by STOR).	\"C:\\Local FileName.exe\" [optional]\"/Remote FileName.exe\"
Delete single file	DELE	Delete a file located in the FTP server	\"/FileName.exe\"
Delete multiple files	MDELETE	Delete files using a mask (multiple DELE).	\"/*.exe\"
Rename file	RNFR	Rename a file (RNFR followed by RNTO).	FileName.exe \"New FileName.exe\"
Create folder	MKD	Create a folder or directory.	\"New Folder\"
Remove folder	RMD	Remove a folder.	\"Old Folder\"
Change folder	CWD	Change the current folder	\"New Folder\"
Up one folder	CDUP	Change to the parent folder	N/A
Retrieve current folder	PWD	Retrieve the current folder	N/A
Get short file list	NLST	Retrieve a basic file listing (PORT followed by NLST).	*.exe
Get long file list	LIST	Retrieve a verbose file listing (PORT followed by LIST).	*.exe
Disconnect		Disconnect from an FTP server.	N/A
User defined		Issue a custom command to an FTP server.	N/A

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

The sample AML code below can be copied and pasted directly into the Steps panel of the Task Builder.

Description: This sample task will demonstrate how can delete files older than 30 days via 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 action 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.

 In order for this task to work in your environment, please make the appropriate modifications in the properties of each activity.

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