# Performing File Operations with CFFTP

The CFFTP tag allows you to perform tasks on remote servers via the File Transfer Protocol (FTP). CFFTP allows you to cache connections for batch file transfers.

Note | In order to use CFFTP, make sure CFOBJECT is enabled on the Basic Security page of the ColdFusion Administrator.

For server/browser operations, use the CFFILE, CFCONTENT, and CFDIRECTORY tags.

Note | CFFTP is a COM object and is not supported in Microsoft Windows NT 3.51.

Using CFFTP involves two distinct types of operations, connecting and transferring files. For a complete list of attributes, see the CFML Language Reference .

| To open an FTP connection and retrieve a file listing:

1. Open a new file in Studio.
2. Modify the file so that it appears as follows:

       <--- open FTP connection --->
       <CFFTP CONNECTION=FTP
           USERNAME="betauser"
           PASSWORD="monroe"
           SERVER="beta.company.com"
           ACTION="Open"
           STOPONERROR="Yes">

       <--- get current directory name --->
       <CFFTP CONNECTION=FTP
           ACTION="GetCurrentDir"
           STOPONERROR="Yes">

       <--- output directory name --->
       <CFOUTPUT>
           FTP directory listing of #cfftp.returnvalue#.<p>
       </CFOUTPUT>

       <--- get directory info --->
       <CFFTP CONNECTION=FTP
           ACTION="listdir"
           DIRECTORY="/*."
           NAME="q"
           STOPONERROR="Yes">

       <--- output dirlist results --->
       <HR>
       <P>FTP Directory Listing:</P>

       <CFTABLE QUERY="q" HTMLTABLE>
           <CFCOL HEADER="<B>Name</B>" TEXT="#name#">
           <CFCOL HEADER="<B>Path</B>" TEXT="#path#">
           <CFCOL HEADER="<B>URL</B>" TEXT="#url#">
           <CFCOL HEADER="<B>Length</B>" TEXT="#length#">
           <CFCOL HEADER="<B>LastModified</B>"
           TEXT="Date(Format#lastmodified#)">
           <CFCOL HEADER="<B>IsDirectory</B>"
               TEXT="#isdirectory#">
       </CFTABLE>

3. Change beta.company.com to the name of a server you have permission to FTP to.
4. Change betauser and monroe to a valid username and password.

   To establish an anonymous connection enter "anonymous" as the username and an email address (by convention) for the password.

5. Save the file as `ftpconnect.cfm` in `myapps` under your Web root directory.

Once you've established a connection with CFFTP, you can reuse the connection to perform additional FTP operations. When you access an already active FTP connection, you don't need to re-specify the username, password, or server. In this case, make sure that when you use frames, only one frame uses the connection object.

## Caching connections across multiple pages

CFFTP caching is maintained only in the current page unless you explicitly assign a CFFTP connection to a variable with application or session scope. Assigning a CFFTP connection to an application variable could cause problems, since multiple users could access the same connection object at the same time. Creating a session variable for a CFFTP connection makes the most sense.

You cache a connection object for a session by assigning the connection name to a session variable:

### Example: Caching a connection

    <CFFTP ACTION=connect
        USERNAME="anonymous"
        PASSWORD="me@home.com"
        SERVER="ftp.eclipse.com"
        CONNECTION="Session.myconnection">

In this example, the connection cache remains available to other pages within the current session. Of course, you need to be sure that you've enabled session variables in your application first.

Note | Changes to a cached connection, such as changing RETRYCOUNT or TIMEOUT values, may require re-establishing the connection.

## Connection caching actions and attributes

The following table shows which CFFTP attributes are required for CFFTP actions when employing connection caching. If connection caching is not used, the connection attributes USERNAME, PASSWORD, and SERVER must be specified.

CFFTP Required Attributes by Action
Action | Attributes | Action | Attributes
--- | --- | --- | ---
Open | none | Rename | EXISTING NEW
Close | none | Remove | SERVER ITEM
ChangeDir | DIRECTORY | GetCurrentDir | none
CreateDir | DIRECTORY | GetCurrentURL | none
ListDir | NAME DIRECTORY | ExistsDir | DIRECTORY
GetFile | LOCALFILE REMOTEFILE | ExistsFile | REMOTEFILE
PutFile | LOCALFILE REMOTEFILE | Exists | ITEM