Connection: File and directory operations

Description

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

If you use connection caching to an active FTP connection, you do not have to respecify the connection attributes:

username
password
server

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 = "proxyserver"
  passive = "Yes" or "No">

Attributes

Attribute

Description

action
Required (if connection is not cached). Determines the FTP operation to perform. Can be one of the following:

changedir

createDir

listDir TagOnly

removeDir

getFile

putFile

rename

remove

getCurrentDir

getCurrentURL

existsDir

existsFile

exists

username
Required if the FTP connection is not cached. If connection caching is used, the username attribute is not required. User name to pass in the FTP operation.

name
Required for action = "listDir". Specifies the query name to hold the directory listing.

server
Required if the FTP connection is not cached. If connection caching is used, the server attribute is not required. The FTP server to connect to.

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

port
Optional. The remote port to connect to. Defaults to 21 for FTP

connection
Optional. The name of the FTP connection. Used to cache a new FTP connection or to reuse an existing connection. If the username, password, and server attributes are specified, a connection is created, if no connection exists for the specified user. Calls to cfftp with the same connection name reuse the FTP connection information.

ASCIIExtensionList
Optional. A semicolon-delimited list of file extensions that force ASCII transfer mode when transferMode = "auto". Default extension list is:
txt;htm;html;cfm;cfml;shtm;shtml;css;asp;asa

transferMode
Optional. The FTP transfer mode to use. Options are ASCII, Binary, or Auto. Defaults to Auto.

failIfExists
Optional. Yes or No. Defaults to Yes. Specifies whether a getFile operation will fail if a local file of the same name already exists.

directory
Required for action = "changedir", createDir, listDir, and existsDir. Specifies the directory on which to perform an operation.

localFile
Required for action = "getFile", and putFile. Specifies the name of the file on the local file system.

remoteFile
Required for action = "getFile", putFile, and existsFile. Specifies the name of the file on the FTP server's file system

item
Required for action = "exists", and remove. Specifies the object, file or directory, of 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

retryCount
Optional. Number of retries until failure is reported. Default is one (1).

stopOnError
Optional. Yes or No. If Yes, halts processing and displays an appropriate error. Default is No.
When No, three variables are populated:

cfftp.succeeded - Yes or No.

cfftp.errorCode - Error number. Please refer to IETF Network Working Group RFC 959: File Transfer Protocol (FTP) for information about FTP error codes: http://www.ietf.org/rfc/rfc0959.txt.

cfftp.errorText - Message text that explains error condition

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

passive
Optional. Yes or No. Defaults to No. Indicates whether to enable passive mode

Attribute	Description
action	Required (if connection is not cached). Determines the FTP operation to perform. Can be one of the following: changedir createDir listDir TagOnly removeDir getFile putFile rename remove getCurrentDir getCurrentURL existsDir existsFile exists
username	Required if the FTP connection is not cached. If connection caching is used, the `username` attribute is not required. User name to pass in the FTP operation.
name	Required for `action = "listDir"`. Specifies the query name to hold the directory listing.
server	Required if the FTP connection is not cached. If connection caching is used, the `server` attribute is not required. The FTP server to connect to.
timeout	Optional. Value in seconds for the timeout of all operations, including individual data request operations. Defaults to 30 seconds.
port	Optional. The remote port to connect to. Defaults to 21 for FTP
connection	Optional. The name of the FTP connection. Used to cache a new FTP connection or to reuse an existing connection. If the `username`, `password`, and `server` attributes are specified, a connection is created, if no connection exists for the specified user. Calls to `cfftp` with the same connection name reuse the FTP connection information.
ASCIIExtensionList	Optional. A semicolon-delimited list of file extensions that force ASCII transfer mode when `transferMode = "auto"`. Default extension list is: txt;htm;html;cfm;cfml;shtm;shtml;css;asp;asa
transferMode	Optional. The FTP transfer mode to use. Options are ASCII, Binary, or Auto. Defaults to Auto.
failIfExists	Optional. Yes or No. Defaults to Yes. Specifies whether a `getFile` operation will fail if a local file of the same name already exists.
directory	Required for `action = "changedir"`, `createDir`, `listDir`, and `existsDir`. Specifies the directory on which to perform an operation.
localFile	Required for `action = "getFile"`, and `putFile`. Specifies the name of the file on the local file system.
remoteFile	Required for `action = "getFile"`, `putFile`, and `existsFile`. Specifies the name of the file on the FTP server's file system
item	Required for `action = "exists"`, and `remove`. Specifies the object, file or directory, of 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
retryCount	Optional. Number of retries until failure is reported. Default is one (1).
stopOnError	Optional. Yes or No. If Yes, halts processing and displays an appropriate error. Default is No. When No, three variables are populated: `cfftp.succeeded` - Yes or No. `cfftp.errorCode` - Error number. Please refer to IETF Network Working Group RFC 959: File Transfer Protocol (FTP) for information about FTP error codes: http://www.ietf.org/rfc/rfc0959.txt. `cfftp.errorText` - Message text that explains error condition
proxyServer	Optional. A string that contains the name of the proxy server (or servers) to use if proxy access is specified
passive	Optional. Yes or No. Defaults to No. Indicates whether to enable passive mode

Usage

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

When 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 the following actions:

getCurrentDir
getCurrentURL
existsDir
existsFile
exists

For more information, see the "Action (cfftp.ReturnValue variable)".

Note

Names of objects (files and directories) are case-sensitive.

Action (cfftp.ReturnValue variable)

Description

The results of the action attribute determine the value of the cfftp.returnValue variable.

cfftp Action

Value of cfftp.returnValue

getCurrentDir
String value containing the current directory

getCurrentURL
String value containing the current URL

existsDir
Yes or No

existsFile
Yes or No

exists
Yes or No

Connection: File and directory operations

Description

Category

Syntax

See also

Attributes

Usage

Action (cfftp.ReturnValue variable)

Description

cfftp Action	Value of cfftp.returnValue
getCurrentDir	String value containing the current directory
getCurrentURL	String value containing the current URL
existsDir	Yes or No
existsFile	Yes or No
exists	Yes or No

CFML Reference
ColdFusion Tags