cfftp: Connection: File and directory operations

Description

Use this form of the cfftp tag to perform file and directory operations with cfftp.

Syntax

<cfftp 
   action = "action"
   username = "name"
   password = "password"
   name = "query_name"
   server = "server"
   ASCIIExtensionList = "extensions"
   transferMode = "mode"
   failIfExists = "yes" or "no"
   directory = "directory name"
   localFile = "filename"
   remoteFile = "filename"
   item = "directory or file"
   existing = "file or directory name"
   new = "file or directory name"
   proxyServer = "proxy server"
   passive = "yes" or "no">
result = "result_name"

Attributes

Attribute	Req/Opt	Default	Description
action	Required if connection is not cached		FTP operation to perform: changedir createDir listDir removeDir getFile putFile rename remove getCurrentDir getCurrentURL existsDir existsFile exists
username	Required if connection is not cached		User name to pass in the FTP operation.
password	Required if `action = "open"`		Password to log in the user.
name	Required if `action = "listDir"`		Query name of directory listing.
server	Required if FTP connection is not cached		FTP server to which to connect; for example, `ftp.myserver.com`.
ASCIIExtensionList	Optional	txt;htm;html;cfm;cfml; shtm;shtml; css;asp;asa	Delimited list of file extensions that force ASCII transfer mode, if `transferMode` `=` `"auto"`.
transferMode	Optional	Auto	ASCII FTP transfer mode Binary FTP transfer mode Auto FTP transfer mode
failIfExists	Optional	yes	yes: if a local file with same name exists, the getFile action will fail. no
directory	Required if `action = "changedir"`, `"createDir",` `"listDir", or` `"existsDir"`		Directory on which to perform an operation.
localFile	Required if `action = "getFile"` or `"putFile"`		Name of the file on the local file system.
remoteFile	Required if `action = "getFile"`, `"putFile"`, or `"existsFile"`		Name of the file on the FTP server file system.
item	Required if `action = "exists"` or `"remove"`		Object of these actions: file or directory.
existing	Required if `action = "rename"`		Current name of the file or directory on the remote server.
new	Required if `action = "rename"`		New name of file or directory on the remote server.
proxyServer	Optional		String. Name of the proxy server (s) to use, if proxy access is specified.
passive	Optional	no	yes: enables passive mode. no
result	Optional		Specifies a name for the structure in which cfftp stores the `returnValue` variable. If set, this value replaces `cfftp` as the prefix to use when accessing `returnVariable`. See the Usage section for more information

Usage

If you use connection caching to an active FTP connection, you do not have to respecify the username, password, or server connection attributes.

Changing a cached connection, such as changing retryCount or timeout values, might require reestablishing the connection.

If action = "listDir", the attributes column returns directory or normal. Other platform-specific values, such as hidden and system, are no longer supported.

If action = "listDir", a mode column is returned. The column contains an octal string representation of UNIX permissions; for example, "777."

The cfftp.returnValue variable provides the return value for these actions:

getCurrentDir
getCurrentURL
existsDir
existsFile
exists

For more information, see ColdFusion MX Developer's Guide.

Caution: Object (file and directory) names are case-sensitive.

Action (cfftp.ReturnValue variable)

The results of an action determine the value of the returnValue variable, as the following table shows:

cfftp action	Value of cfftp.returnValue
getCurrentDir	String. Current directory.
getCurrentURL	String. Current URL.
existsDir	yes or no.
existsFile	yes or no.
exists	yes or no.

To access the returnValue variable, you must prefix it with either cfftp or the value specified by the result attribute, if it is set. The result attribute provides a way for cfftp calls from multiple pages, possibly at the same time, to avoid overwriting the results of one with another. If you set the result attribute to myResult, for example, you would access the returnVariable variable as myResult.returnVariable. Otherwise, you would access it as cfftp.returnVariable.

Example

The following example opens a connection and gets a file listing showing file or directory name, path, URL, length, and modification date:

<p>Open a connection
<cfftp connection = "myConnection" 
   username = "myUserName"
   password = "myUserName@allaire.com"
   server = "ftp.allaire.com"
   action = "open" 
   stopOnError = "Yes"> 

<p>Did it succeed? <cfoutput>#cfftp.succeeded#</cfoutput>
<cfftp connection = "myConnection"
    action = "LISTDIR"
    stopOnError = "Yes"
    name = "ListDirs"
    directory = "/">

<p>FTP Directory Listing:<br> 
<cftable query = "ListDirs" HTMLTable = "Yes" colHeaders = "Yes"> 
   <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>

<p>Move Image File to Remote Server:<br></p>
<!--- The image will be put into the root directory of the FTP server unless 
otherwise noted. 
i.e. remoteFile = "somewhere_put.jpg" vs remoteFile = "/support/somewhere_put.jpg"
---> 
<cfftp 
connection = "myConnection"
action = "putFile" 
name = "uploadFile" 
transferMode = "binary" 
localFile = "C:\files\upload\somewhere.jpg" 
remoteFile = "somewhere_put.jpg" 
>
<p>Did it succeed? <cfoutput>#cfftp.succeeded#</cfoutput> 

<p>Close the connection:
<cfftp connection = "myConnection"
    action = "close"
    stopOnError = "Yes">
<p>Did it succeed? <cfoutput>#cfftp.succeeded#</cfoutput>

View comments in LiveDocs