Performing File Operations with cfftp

The cfftp tag lets you perform tasks on remote servers using File Transfer Protocol (FTP). You can use cfftp to cache connections for batch file transfers.

Note

To use cfftp, the Enable cfftp Tag option must be selected on the Tag Restrictions page of the Basic Security section of the ColdFusion Administrator Security tab.

For server/browser operations, use the cffile, cfcontent, and cfdirectory tags.

Using cfftp involves two major types of operations: connecting, and transferring files. The FTP protocol also provides commands for listing directories and performing other operations. For a complete list of attributes that support FTP operations and additional details on using the cfftp tag, see the CFML Reference.

To open an FTP connection and retrieve a file listing:

Open a new file in ColdFusion Studio.

Modify the file so that it appears as follows:

<html>

<head>

  <title>FTP Test</title>

</head>



<body>

<h1>FTP Test</h1>

<!--- Open ftp connection --->

<cfftp connection="Myftp"

  server="MyServer"

  username="MyUserName"

  password="MyPassword"

  action="Open"

  stoponerror="Yes">



<!--- Get the current directory name. --->

<cfftp connection=Myftp

  action="GetCurrentDir"

  stoponerror="Yes">



<!--- output directory name --->

<cfoutput>

  The current directory is:  #cfftp.returnvalue#<p>

</cfoutput>



<!--- Get a listing of the directory. --->

<cfftp connection=Myftp

  action="listdir"

  directory="#cfftp.returnvalue#"

  name="dirlist"

  stoponerror="Yes">



<!--- Close the connection.--->

<cfftp action="close" connection="Myftp">

<p>Did the connection close successfully? 

  <cfoutput>#cfftp.succeeded#</cfoutput></p>



<!--- output dirlist results --->

<hr>

<p>FTP Directory Listing:</p>



<cftable query="dirlist" colheaders="yes" 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="#DateFormat(lastmodified)#">

  <cfcol header="<B>IsDirectory</b>"

    TEXT="#isdirectory#">

</cftable>

Change MyServer to the name of a server for which you have FTP permission.
Change MyUserName and MyPassword to a valid username and password.
To establish an anonymous connection, enter "anonymous" as the username and an e-mail address (by convention) for the password.
Save the file as ftpconnect.cfm in myapps under your Web root directory.

Reviewing the code

The following table describes the code and its function:

Code

Description

<cfftp connection="Myftp" server="MyServer" username="MyUserName" password="MyPassword" action="Open" stoponerror="Yes">
Open an FTP connection to the MyServer server and log on as MyUserName. If an error occurs, stop processing and display an error. You can use this connection in other cfftp tags by specifying the Myftp connection.

<cfftp connection=Myftp action="GetCurrentDir" stoponerror="Yes"> <cfoutput> The current directory is: #cfftp.returnvalue# </cfoutput>
Use the Myftp connection to get the name of the current directory; stop processing if an error occurs.
Display the current directory.

<cfftp connection=Myftp action="ListDir" directory="#cfftp.returnvalue#" name="dirlist" stoponerror="Yes">
Use the Myftp connection to get a directory listing. Use the value returned by the last cfftp call (the current directory of the connection) to specify the directory to list. Save the results in a variable named dirlist (a query object). Stop processing if there is an error.

<cfftp action="close" connection="Myftp"> Did the connection close successfully? <cfoutput>#cfftp.succeeded#</cfoutput>
Close the connection, and do not stop processing if the operation fails (because you can still use the results). Instead, display the value of the cfftp.succeeded variable, which is Yes if the connection is closed, and No if the operation failed.

<cftable query="dirlist" colheaders="yes" htmltable> <cfcol header="Name" TEXT="#name#"> <cfcol header="Path" TEXT="#path#"> <cfcol header="URL" TEXT="#url#"> <cfcol header="Length" TEXT="#length#"> <cfcol header="LastModified" TEXT="#DateFormat(lastmodified)#"> <cfcol header="IsDirectory" TEXT="#isdirectory#"> </cftable>
Display a table with the results of the ListDir FTP command.

Code	Description
<cfftp connection="Myftp" server="MyServer" username="MyUserName" password="MyPassword" action="Open" stoponerror="Yes">	Open an FTP connection to the MyServer server and log on as MyUserName. If an error occurs, stop processing and display an error. You can use this connection in other `cfftp` tags by specifying the Myftp connection.
<cfftp connection=Myftp action="GetCurrentDir" stoponerror="Yes"> <cfoutput> The current directory is: #cfftp.returnvalue#<p> </cfoutput>	Use the Myftp connection to get the name of the current directory; stop processing if an error occurs. Display the current directory.
<cfftp connection=Myftp action="ListDir" directory="#cfftp.returnvalue#" name="dirlist" stoponerror="Yes">	Use the Myftp connection to get a directory listing. Use the value returned by the last `cfftp` call (the current directory of the connection) to specify the directory to list. Save the results in a variable named dirlist (a query object). Stop processing if there is an error.
<cfftp action="close" connection="Myftp"> <p>Did the connection close successfully? <cfoutput>#cfftp.succeeded#</cfoutput></p>	Close the connection, and do not stop processing if the operation fails (because you can still use the results). Instead, display the value of the `cfftp.succeeded` variable, which is Yes if the connection is closed, and No if the operation failed.
<cftable query="dirlist" colheaders="yes" 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="#DateFormat(lastmodified)#"> <cfcol header="<B>IsDirectory</b>" TEXT="#isdirectory#"> </cftable>	Display a table with the results of the ListDir FTP command.

hafter you establish a connection with cfftp, you can reuse the connection to perform additional FTP operations until either you or the server closes the connection. When you access an already-active FTP connection, you do not 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.

Note

For a single simple FTP operation, such as GetFile or PutFile, you do not need to establish a connection. Specify all the necessary login information, including the server and any login and password, in the single cfftp request.

Caching connections across multiple pages

The FTP connection established by cfftp is maintained only in the current page unless you explicitly assign the 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 more sense, because the connection is available to only one client and does not last past the end of the session.

Example: Caching a connection

<cflock scope="Session" timeout=10>

<cfftp action="Open"

  username="anonymous"

  password="me@home.com"

  server="ftp.eclipse.com"

  connection="Session.myconnection">

</cflock>

In this example, the connection cache remains available to other pages within the current session. You must enable Session variables in your application for this approach to work, and you must lock code that uses Session variables. For information on locking, see "Locking Code with cflock".

Note

Changing a connection's characteristics, such the retrycount or timeout values, might require you to re-establish the connection.

Connection actions and attributes

The following table shows the available cfftp actions and the attributes they require when you use a named (that is, cached) connection. If you do not specify an existing connection name, you must specify the username, password, and server attributes.

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

RemoveDir
directory
ExistsFile
remotefile

GetFile
localfile
remotefile
Exists
item

PutFile
localfile
remotefile

Developing ColdFusion Applications
Interacting with Remote Servers

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
RemoveDir	directory	ExistsFile	remotefile
GetFile	localfile remotefile	Exists	item
PutFile	localfile remotefile