cfftp


<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.

Table 21.4. <cfftp> Tag Attributes

ATTRIBUTE

DESCRIPTION

action

Required. Determines the FTP operation to perform. Use open to open an FTP connection. Use close to close an FTP connection.

username

Required to open the session. Username to pass to the FTP server.

password

Required to open the session. Password to log in the user specified in username.

server

Required to open the session. The FTP server to connect to, such as ftp.myserver.com.

timeout

Optional. Value in seconds for the timeout of all operations, including individual data-request operations. Defaults to 30 seconds.

port

Optional. The remote TCP/IP port to connect to. The default is 21 for FTP.

connection

Optional. Name of the FTP connection. Used to cache the FTP connection information or to reuse a previously opened connection.

proxyServer

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

retryCount

Optional. Number of retries until failure is reported. Default is 1.

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.Succeededeither YES or NO. CFFTP.ErrorCodethe error number (see Table 21.9.). CFFTP.ErrorTextmessage text explaining the error type.

passive

Optional. YES or NO. Indicates whether to enable passive mode. Set to YES if ColdFusion is behind a firewall.

result

Optional. Defaults to "cfftp". The result of the FTP operation is stored in a variable called cfftp. The result attribute lets you specify another variable name to use.


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. Table 21.5 shows the attributes for file and directory operations.

Table 21.5. <cfftp> File and Directory Operation Attributes

ATTRIBUTE

DESCRIPTION

action

Required if the connection is not already cached using the connection attribute. Determines the FTP operation to perform. It can be ChangeDir, CreateDir, RemoveDir, ListDir, GetFile, PutFile, Rename, Remove, GetCurrentDir, GetCurrentURL, ExistsDir, ExistsFile, or Exists.

username

Required if the connection is not already cached.

password

Required if the connection is not already cached.

server

Required if the connection is not already cached.

connection

Optional. Name of the FTP connection. Used to cache the FTP connection information or to reuse a previously opened connection.

name

Required for action=ListDir. Specifies the query object in which results will be stored.

asciiExtensionList

Optional. Semicolon-delimited list of file extensions that forces ASCII transfer mode when transferMode=""Autodetect"". The default list is txt; htm; html; cfm; cfml; shtm; shtml; 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.

Table 21.6. <cfftp> Required Attributes Shown by Action

ACTION

ATTRIBUTE

ChangeDir

directory

Close

None

CreateDir

directory

Exists

item, remoteFile

ExistsDir

directory

ExistsFile

remoteFile

GetCurrentDir

None

GetCurrentURL

None

GetFile

localFile, remoteFile

ListDir

name, directory

Open

None

PutFile

localFile, remoteFile

RemoveDir

item

Remove

item

Rename

existing, new


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. Table 21.7 lists the CFFTP variables available and their possible values. Because the value of CFFTP.ReturnValue is dependent on the type of action, see Table 21.8 for an explanation of what that value means.

Table 21.7. CFFTP Variables

KEY

DESCRIPTION

CFFTP.Succeeded

Boolean specifying whether the action was successful.

CFFTP.ErrorCode

The error number returned by the <cfftp> tag.

CFFTP.ErrorText

Message text that explains the error code thrown. Do not use error code embedded in the CFFTP.ErrorText variable for the conditional statements; instead, use CFFTP.ErrorCode.

CFFTP.ReturnValue

General holding variable used by various <cfftp> actions to store resulting parameters. See Table 21.8 for values based on an action. For actions not listed, the value is the same as the CFFTP.ErrorText variable.


Table 21.8. Values of the CFFTP.ReturnValue Variable

<cfftp> ACTION

VALUE OF CFFTP.ReturnValue

GetCurrentDir

String value containing name of the current directory

GetCurrentURL

String value containing the current URL

ExistsDir

YES or NO

ExistsFile

YES or NO

Exists

YES or NO


Error handling with the <cfftp> tag can be done through the traditional error-handling framework of ColdFusion or through checking the status code on the resulting CFFTP scope. The attribute stopOnError is used to determine which mode you are running in. With its value set to TRUE, it will raise an error upon failure. However, this option is not recommended for handling errors with <cfftp> for two reasons. First, the errors are not as descriptive as the status errors returned through the CFFTP structure; second, no CFFTP structure is created if <cfftp> tHRows the error itself. Therefore, stopOnError should only be set to True if you want to just stop the page right there and do nothing with the error itself.

The other way to handle errors is to set the stopOnError value to False. This causes ColdFusion to suppress the normal error handling and instead record the error into several CFFTP variables. To verify the success of the request, simply query the CFFTP.Succeeded variable. This is a Boolean value that determines whether the request was successful. Due to the granularity of the information provided in this structure, this is the recommended way to handle errors when you want to handle the error at all programmatically.

TIP

If you want to fold errors from a <cfftp> call into the error-handling framework of ColdFusion, use the <cfthrow> tag to raise the error. To populate its attributes, use the keys of the resulting CFFTP structure.


Table 21.9 shows the possible error codes and their text descriptions.

Table 21.9. <cfftp> Error Codes

ERROR CODE

DESCRIPTION

0

Operation succeeded.

1

System error (operating system or FTP protocol error).

2

Internet session could not be established.

3

FTP session could not be opened.

4

File transfer mode not recognized.

5

Search connection could not be established.

6

Invoked operation valid only during a search.

7

Invalid timeout value.

8

Invalid port number.

9

Not enough memory to allocate system resources.

10

Cannot read contents of local file.

11

Cannot write to local file.

12

Cannot open remote file for reading.

13

Cannot read remote file.

14

Cannot open local file for writing.

15

Cannot write to remote file.

16

Unknown error.

17

Reserved.

18

File already exists.

19

Reserved.

20

Reserved.

21

Invalid retry count specified.




Advanced Macromedia ColdFusion MX 7 Application Development
Advanced Macromedia ColdFusion MX 7 Application Development
ISBN: 0321292693
EAN: 2147483647
Year: 2006
Pages: 240
Authors: Ben Forta, et al

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net