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 .

Note 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