# CFFTP

CFFTP allows users to implement File Transfer Protocol operations.

Note | The CFFTP tag is for moving files between a ColdFusion server and an FTP server. CFFTP cannot move files between a ColdFusion server and a browser (client). Use CFFILE ACTION="UPLOAD" to transfer files from the client to a ColdFusion server; use CFCONTENT to transfer files from a ColdFusion server to the browser.

Note also that ColdFusion Server Basic security settings may prevent CFFTP from executing. These settings are managed using the ColdFusion Administrator Basic Security page. If you write ColdFusion applications designed to run on a server that is used by multiple customers, you need to consider the security of the files that the customer can move. Please refer to Administering ColdFusion Server for more information about securing ColdFusion tags.

### CFFTP topics:

- Establishing a Connection with CFFTP
- File and Directory Operations with CFFTP
- Accessing the Columns in a Query Object
- CFFTP.ReturnValue Variable
- Connection Caching

## Establishing a Connection with CFFTP

Use the CONNECTION attribute of the CFFTP tag to establish a connection with an FTP server.

If you use connection caching to an already active FTP connection, you don't need to respecify the connection attributes:

- USERNAME
- PASSWORD
- SERVER

Note | Changes to a cached connection, such as changing RETRYCOUNT or TIMEOUT values, may require reestablishing the connection.

### Syntax

    <CFFTP ACTION="action"
        USERNAME="name"
        PASSWORD="password"
        SERVER="server"
        TIMEOUT="timeout in seconds"
        PORT="port"
        CONNECTION="name"
        PROXYSERVER="proxyserver"
        RETRYCOUNT="number"
        STOPONERROR="Yes/No"
        PASSIVE="Yes/No">

#### ACTION

Required. Determines the FTP operation to perform. To create an FTP connection, use Open. To terminate an FTP connection, use Close. See Connection Caching for more information.

#### USERNAME

Required for Open. User name to pass in the FTP operation.

#### PASSWORD

Required for Open. Password to log in the user.

#### SERVER

Required for Open. The FTP server to connect to, as in `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 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 new connection is created if no connection exists for the specified user. All calls to CFFTP with the same connection name will reuse the same FTP connection information.

#### PROXYSERVER

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

#### RETRYCOUNT

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

#### STOPONERROR

Optional. Yes or No. When Yes, halts all processing and displays an appropriate error. Default is Yes.

When No, three variables are populated:

- CFFTP.Succeeded - Yes or No.
- CFFTP.ErrorCode - Error number (See following Note for critical information.)
- CFFTP.ErrorText - Message text explaining error type

  Note | Use CFFTP.ErrorCode for conditional operations. Do not use CFFTP.ErrorText for this purpose.

#### PASSIVE

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

### Example

    cfftp<!--- This view-only example shows the use of CFFTP --->
    <HTML>
    <HEAD>
    <TITLE>CFFTP Example</TITLE>
    </HEAD>
    <BODY>

    <H3>CFFTP Example</H3>
    <P>CFFTP allows users to 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 view-only example opens and verifies a connection,
    lists the files in a directory, and closes the connection.
    <!---
    <P>Open a connection

    <CFFTP ACTION="open"
    USERNAME="anonymous"
    CONNECTION="My_query"
    PASSWORD="youremail@email.net"
    SERVER="ftp.tucows.com"
    STOPONERROR="Yes">

    <P>Did it succeed? <CFOUTPUT>#CFFTP.Succeeded#</CFOUTPUT>
    <P>List the files in a directory:
    <CFFTP ACTION="LISTDIR"
           STOPONERROR="Yes"
           NAME="ListFiles"
           DIRECTORY="lib"
           CONNECTION="my_query">
    <CFOUTPUT QUERY="ListFiles">
        #name#<BR>
    </CFOUTPUT>

    <P>Close the connection:
    <CFFTP ACTION="close"
    CONNECTION="My_query"
    STOPONERROR="Yes">
    <P>Did it succeed? <CFOUTPUT>#CFFTP.Succeeded#</CFOUTPUT>
    --->

    </BODY>
    </HTML>

## File and Directory Operations with CFFTP

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

If you use connection caching to an already active FTP connection, you don't need 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/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/No">

#### ACTION

Required if connection is not already cached. If connection caching is used, the ACTION attribute is not required. Determines the FTP operation to perform. Can be one of the following:

- ChangeDir
- CreateDir
- ListDir
- GetFile
- PutFile
- Rename
- Remove
- GetCurrentDir
- GetCurrentURL
- ExistsDir
- ExistsFile
- Exists

#### USERNAME

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

#### PASSWORD

Required if the FTP connection is not already cached. If connection caching is used, the PASSWORD attribute is not required. Password to log the user.

#### NAME

Required for ACTION="ListDir". Specifies the query name to hold the directory listing. See Usage for more information.

#### SERVER

Required if the FTP connection is not already 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 new connection is created if no connection exists for the specified user. All calls to CFFTP with the same connection name will reuse the same FTP connection information.

#### ASCIIEXTENSIONLIST

Optional. A semicolon delimited list of file extensions that force ASCII transfer mode when TRANSFERMODE="AutoDetect". Default extension list is:

    txt;htm;html;cfm;cfml;shtm;shtml;css;asp;asa

#### TRANSFERMODE

Optional. The FTP transfer mode you want to use. Valid entries are ASCII, Binary, or AutoDetect. Defaults to AutoDetect.

#### 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. When Yes, halts all processing and displays an appropriate error. Default is No.

When No, three variables are populated:

- CFFTP.Succeeded - Yes or No.
- CFFTP.ErrorCode - Error number (See STOPONERROR variables, below)
- CFFTP.ErrorText - Message text explaining error condition

#### 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. Defaults to No. Indicates whether to enable passive mode.

### Usage

When `ACTION="ListDir"`, the Attributes column returns either "Directory" or "Normal." Other platform-specific values, such as "Hidden" and "System" are no longer supported.

When`ACTION="ListDir",` a `"Mode"` column is returned. This column contains an octal string representation of UNIX permissions, for example, "777," when appropriate.

Note also that there is a CFFTP.ReturnValue variable that provides the return value for some of these actions. The actions for which this variable returns a value are as follows:

- GetCurrentDir
- GetCurrentURL
- ExistsDir
- ExistsFile
- Exists

The section CFFTP.ReturnValue Variable explains what is returned in this variable.

Note | Names of objects (files and directories) are case-sensitive; thus, using ListDir on "`test.log` " will not find a file named "`test.LOG`. "

## CFFTP.ReturnValue Variable

The value of the CFFTP.ReturnValue variable is determined by the results of the ACTION attribute used in CFFTP.

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

## Accessing the Columns in a Query Object

###

When you use CFFTP with the ListDir action, you must also specify a value for the NAME attribute. The value of the NAME attribute is used to hold the results of the ListDir action in a query object. The query object consists of columns you can reference in the form:

    queryname.columname[row]

Where queryname is the name of the query as specified in the NAME attribute and columnname is one of the columns returned in the query object as shown in the following table. Row is the row number for each file/directory entry returned by the ListDir operation. A separate row is created for each entry.

CFFTP Query Object Columns
Column | Description
--- | ---
Name | Filename of the current element
Path | File path (without drive designation) of the current element
URL | Complete URL for the current element (file or directory)
Length | Number indicating file size of the current element
LastModified | Unformatted date/time value of the current element
Attributes | String indicating attributes of the current element: Normal or Directory.
IsDirectory | Boolean value indicating whether object is a file or directory
Mode | An octal string representing UNIX permissions, when running on UNIX, for example, "rwxrwxrwx" in a directory listing is represented as "777".

Note | Previously supported query column values that pertain to system- specific information are no longer supported, for example, "Hidden" and "System."

## Connection Caching

Once you've established a connection with CFFTP, you can reuse the connection to perform additional FTP operations. To do this, you use the CONNECTION attribute to define and name an FTP connection object that stores information about the connection. Any additional FTP operations that use the same CONNECTION name automatically make use of the information stored in the connection object. This facility helps save connection time and drastically improves file transfer operation performance.

If you need to keep the connection open throughout a session or longer, you can use a session or application variable as the connection name. However, if you do this, you must explicitly specify the full variable name with the Close action when you are finished. Note that keeping a connection open prevents others from using the FTP server; therefore, you should close the connection as soon as possible.

Note | Changes to a cached connection, such as changing RETRYCOUNT or TIMEOUT values, may require reestablishing the connection.

### Example

The following example opens an FTP connection, retrieves a file listing, showing file or directory name, path, URL, length, and modification date. Connection caching is used to maintain the link to the server, and automatic error checking is enabled.

    <CFFTP CONNECTION=FTP
        USERNAME="betauser"
        PASSWORD="monroe"
        SERVER="beta.company.com"
        ACTION="Open"
        STOPONERROR="Yes">

    <CFFTP CONNECTION=FTP
        ACTION="GetCurrentDir"
        STOPONERROR="Yes">

    <CFOUTPUT>
        FTP directory listing of #cfftp.returnvalue#.<P>
    </CFOUTPUT>

        <CFOUTPUT>Return is #cfftp.returnvalue#</CFOUTPUT><BR>

    <CFFTP CONNECTION="FTP"
        ACTION="listdir"
        DIRECTORY="/*."
        NAME="q"
        STOPONERROR="Yes">
    <HR>FTP Directory Listing:<P>
    <CFTABLE QUERY="q" HTMLTABLE>
        <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="Date(Format#lastmodified#)">
        <CFCOL HEADER="<B>IsDirectory</B>" TEXT="#isdirectory#">
    </CFTABLE>