ADVANCED macromedia COLDFUSION MX 7 Application Development [Electronic resources]

<cfftp>

The other transfer protocol this chapter examines is the File Transfer Protocol (FTP). FTP is a streamlined mechanism for transferring files from one computer to another. Because both ASCII and binary transfers are supported by the FTP protocol, it is a de facto way of distributing software and files across the Internet. This protocol is not used as a means to interact with other servers for processing, as HTTP is used. Rather, FTP provides a mechanism for delivery or pulling across the Internet.

In ColdFusion, the <cfftp> tag is used to implement FTP operations. In its default configuration, the <cfftp> tag caches connections for reuse within the same template.

Operations using the <cfftp> tag are divided into two types:

• Connection operations

• File and directory operations

Connection Operations with <cfftp>

The syntax used in connection operations for the <cfftp> tag is as follows:

<cfftp action="action"
username="username"
password="password"
server="server"
timeout="timeout in seconds"
port="port"
connection="name"
proxyServer="proxyserver"
retryCount="number"
passive="YES/NO"
stopOnError="Yes/No"
result="cfftp">

This form of the <cfftp> tag is used to establish or close an FTP connection. No file manipulation can occur without a valid connection to the FTP server. Connections to the server can be made with each and every request by providing all the connection information for each request or by establishing a named connection and referring it in the connection attribute. If a connection is established, all subsequent requests can be referred to by the connection name in the connection attribute.

The attributes that control the behavior of the <cfftp> tag during the establishment or closure of a session are shown in Table 21.4.

Listing 21.9 shows a simple template that establishes an FTP connection.

Listing 21.9. ftp1.cfmEstablishing an FTP Connection

<!---
Filename: ftp1.cfm
Purpose: Do a simple FTP operation
--->
<cfftp action="open" username="anonymous" password="
server="ftp.mozilla.org" connection="mozilla" stoponerror="No">
<cfif cfftp.succeeded>
<cfoutput>
  FTP Operation Successful: #CFFTP.succeeded#<br>
FTP Return Value: <pre>#CFFTP.returnValue#</pre>
</cfoutput>
<cfftp action="close" connection="mozilla" stoponerror="No">
<cfelse>
<cfoutput>
FTP Error Code: #CFFTP.ErrorCode#<br>
FTP Error Text: #CFFTP.ErrorText#<br>
</cfoutput>
</cfif>

This simple example opens an FTP connection to Mozilla's FTP server, checks the status, and then closes the connection.

NOTE

<cfftp> can be used to push and pull files

only on servers that have an FTP service running.

During a connection, the <cfftp> tag always requires the username and password attributes. When you need to use an anonymous access to an FTP site, set username to anonymous and password to blank.

Looking at the first example, notice that the second <cfftp> didn't have to specify the server, username, or password attribute. This opened a cached connection in the first <cfftp>, enabling you to perform a series of file and directory operations without the overhead of opening and closing a connection. This is accomplished by the connection attribute when the FTP connection is established. All subsequent calls to the <cfftp> tag in the same template use the same connection name. Using this name forces <cfftp> to automatically reuse the connection information, which results in faster connections and improves file transfer performance.

NOTE

If you're using a cached connection, you do not have to specify the username, password, and server attributes for your file and directory operations.

The scope of the connection in the first example is local to the current template. To cache connections across multiple pages, you must set the connection attribute to a persistent scope, such as session or application. Even though it can maintain a connection across multiple pages, it is recommended that you keep it open only for the duration of your requests. Managing the number of unique connections to the FTP server is critical because most FTP servers allow a set number of concurrent connections at any one time. Having a persistent connection to the FTP server effectively ties up one of the connections to the server.

Depending on the FTP server you are connecting to, making changes to cached connection settings, such as changing retryCount or timeout, will require shutting down and reestablishing the connection.

File and Directory Operations with <cfftp>

After you establish an FTP connection, you can perform various file and directory operations to send files to the server or receive files and directory listings from the server. ; cfm; cfml; ; l; css; asp; and asa.

TRansferMode

Optional. The FTP transfer mode. Valid entries are ASCII, Binary, and Auto. The default is Auto.

failIfExists

Optional. YES or NO. Defaults to YES. Specifies whether a GetFile operation will fail if a local file of the same name exists.

directory

Required for action=ChangeDir, CreateDir, ListDir, and ExistsDir. Specifies the directory on which the operation will be performed.

localFile

Required for action=GetFile and PutFile. Specifies a file on the local filesystem.

remoteFile

Required for action=GetFile, PutFile, and ExistsFile. Specifies the filename of the FTP server.

item

Required for action=Exists and Remove. Specifies the file, object, or directory for these actions.

existing

Required for action=Rename. Specifies the current name of the file or directory on the remote server.

new

Required for ACTION=Rename. Specifies the new name of the file or directory on the remote server.

stopOnError

Optional. YES or NO. When YES (the default), halts all processing and displays an appropriate error. When NO, three variables can be checked to determine success: CFFTP.SucceededYES or NO. CFFTP.ErrorCodethe error number (see Table 18.9). CFFTP.ErrorTextthe message text explaining the error type.

proxyServer

Optional. A string that contains the name of the proxy server (or servers) to use if proxy access was specified.

passive

Optional. YES or NO. Indicates whether to enable passive mode.

result

Optional. Defaults to CFFTP. Determines the name of the result structure from the FTP operation.

Table 21.6 shows the attributes required for <cfftp> actions when a cached connection is used. If a cached connection is not used, the username, password, and server attributes must also be set.

Errors and Results for a <cfftp> Call

Each FTP request, regardless of success or failure, results in CFFTP variables. (Remember, however, that you can rename this variable by using the result attribute.) The value of these variables depends in part on the action requested. The CFFTP is represented as a ColdFusion structure for manipulation.