User Guide

172 Chapter 2: ColdFusion Tags
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 you 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, put the connection name in the
Session or Application scope; for example, specify
connection="Session.FTPConnection".
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"
retryCount Optional 1 Number of retries until failure is reported.
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: enables passive mode.
• no
Attribute Req/Opt Default Description