User Guide

cfftp: Opening and closing FTP server connections 139
Usage
When you establish a connection with cfftp action="open" and specify a name in the
connection attribute, ColdFusion caches the connection so that you can reuse it to perform
additional FTP operations. When use a cached connection for subsequent FTP operations, you
do not have to specify the
username, password, or server connection attributes. The FTP
operations that use the same
connection name automatically use the information stored in the
cached connection. Using a cached connection helps save connection time and improves file
transfer performance.
You do not need to open a connection for single, simple, FTP operations, such as
GetFile or
PutFile.
To keep a connection open throughout a session or longer, you can use a Session or Application
variable as the connection name. However, if you do this, you must specify the full variable name
in all FTP operations, and you must use the
close action when you are finished. Keeping a
connection open prevents others from using the FTP server; so close a connection as soon as
possible. If you do not assign the connection name to Session or Application variable, the
connection remains open for the current page only, and you do not have to close it manually.
Changes to a cached connection, such as changing
retryCount or timeout values, might require
reestablishing the connection.
Example
<p>cfftp lets users implement File Transfer Protocol operations.
By default, cfftp caches an open connection to an FTP server.
<p>cfftp operations are usually of two types:
<ul>
<li>Establishing a connection
<li>Performing file and directory operations
</ul>
<p>This example opens and verifies a connection, lists the files in a
directory, and closes the connection.
<p>Open a connection
<cfftp action = "open"
username = "anonymous"
connection = "My_query"
password = "[e-mail]"
server = "ftp.tucows.com"
stopOnError = "Yes">
<p>Did it succeed? <cfoutput>#cfftp.succeeded#</cfoutput>
<p>List the files in a directory:
<cfftp action = "LISTDIR"
stopOnError Optional No • Yes: halts processing, displays an appropriate error.
• No: populates these variables:
- cfftp.succeeded – Yes or No.
- cfftp.errorCode – Error number. See the IETF Network
Working Group RFC 959: File Transfer Protocol (FTP)
www.ietf.org/rfc/rfc0959.txt.
- cfftp.errorText – Message text
For conditional operations, use
cfftp.errorCode. Do not use
cfftp.errorText for this purpose.
passive Optional No • Yes: enable passive mode
• No
Attribute Req/Opt Default Description