Tips & Tricks

When I told them there was a better way to send us large files. They'd been accustomed to sending large image files via an e-mail attachment; I wanted to get them away from this practice and suggested that they use FTP (file transfer protocol). That's where I hit the roadblock. Many of our clients only knew how to send e-mail, surf the Web or create a document in Microsoft Word.

So rather than spend several hours trying to teach each of them how to use an FTP program, I turned to ColdFusion for a quick and easy solution. With ColdFusion I could create a simple and easy-to-understand Web interface that our clients could use without a fearsome learning curve. Getting Started

Two main tags are essential to the implementation of the FTP application: <CFFILE> and <CFFTP>. The former will be used to transport the files from the user's browser to the ColdFusion server; the latter to transfer the files from the ColdFusion server to the FTP server.

You need to be aware of a few issues when using these tags, though. The major one is security. Giving someone the ability to upload files to your server can be very dangerous, so make sure that only those who are supposed to have access to the application can do this. I enable this application on an as-needed basis only, and I don't recommend leaving it running all the time unless absolutely necessary.

Another issue is that basic ColdFusion security settings may not allow CFFTP to execute. To resolve this problem, enable CFObject on the basic security page. Now we're ready to examine the steps necessary to implement this FTP application.

Logging In and Choosing Your File
The first step is to have the client log in. I have the correct login information stored in an Access database, which I use to authenticate the users as well as to track the files they upload. You can use any method you prefer to manage client state; I chose client variables. I store the users' login information in a client variable for use when they begin to transfer files.

After the login, the next step is to select the file they want to upload via a standard HTML form. The following code shows the basic structure for setting up the form.

<FORM ACTION="sendfile.cfm" METHOD="post" ENCTYPE="multipart/form-data">
<INPUT TYPE="file" NAME="filetosend" SIZE="30">
<INPUT TYPE="submit" NAME="SEND">
</FORM>

The main difference between this form and a regular form is the ENCTYPE="multipart/form-data", which is necessary to process the uploaded file. After the appropriate file has been selected to send to the server and the send button has been clicked, the file transfer process starts.

Introducing <CFFILE>
Once the process has been started, the <CFFILE> tag will transfer the file to a folder specified on the ColdFusion server. Three attributes of the tag are required to upload a file, plus several that are optional. First is the ACTION attribute, which needs to be set to UPLOAD. Also required is the DESTINATION attribute, which specifies the location where the file is to be saved on the ColdFusion server. The full path to the directory needs to be listed, and the trailing slash also needs to be included. The final parameter is FORMFIELD, which is the name of the form field that the users specified their file in. Note that it isn't necessary to include the # signs with this field.

The optional attributes for <CF-FILE> can be very useful. The first, NAMECONFLICT, tells the server what to do if a file with the same name already exists on the server. With this attribute you can tell the server to ERROR without saving the file; SKIP, which neither saves the file nor throws an error; OVERWRITE, which will overwrite the file; or MAKEUNIQUE, which tells the server to create a unique file name.

The next attribute, ACCEPT, allows you to specify what types of files are accepted. For example, if you want to allow only GIFs or JPGs to be uploaded, you can set the attribute to:

ACCEPT="image/gif", "image/jpg"

This attribute also helps with security concerns if you know that only certain types of files are going to be uploaded.

The next attribute, MODE, which applies only to UNIX users, allows you to specify permissions. Thus MODE=777 assigns the file read, write and execute permissions for everyone.

The final attribute, ATTRIBUTES, allows you to set the following attributes on a file being uploaded: ReadOnly, Temporary, Archive, Hidden, System and Normal. If the attribute isn't used, the file maintains its original attributes.

Sample Code for <CFFILE>
<CFFILE ACTION="Upload"
FORMFIELD="filetosend"
DESTINATION="C:\cffile\uploads\"
NAMECONFLICT="MakeUnique"
ACCEPT="image/gif, image/jpg"
>

Once the file has been uploaded, a number of parameters are available to check the status of the upload. You can check the file name and directory in which the file was saved; whether or not the file was actually saved; how big the file is; and, most important, the actual file name that was saved to the server. This variable will be used to continue the process and actually move the file to its final destination on the FTP Server. I've included the full list of attributes and their definitions from the CFML language reference in the sidebar.

<CFFTP>
This brings us to the final step in the process – moving the file from the ColdFusion server to the FTP server and deleting it from the ColdFusion server.

The <CFFTP>, like the <CFFILE> tag, has required and optional attributes. The tags required to upload to the server are ACTION, SERVER, USERNAME, PASSWORD, LOCALFILE and REMOTEFILE. For uploading, the ACTION attribute must be set to PutFile. The SERVER attribute is just what it sounds like – the server name, that is, ftp.yourdomain.com. USERNAME and PASSWORD are also pretty self-explanatory. This is where I use the client variables that I saved from the earlier login. LOCALFILE is the name of the file on the ColdFusion server, and REMOTEFILE is the name of the file on the FTP server. This is where the #ServerFile# variable comes into play from the <CFFILE> status variables. #ServerFile# is the name of the file that it was given on the ColdFusion server. This will supply the correct file name in the event that it was changed from the original file name on the user's machine. This would happen if the MAKEUNIQUE attribute was specified and the file already existed on the ColdFusion server. Use this variable to specify both the LOCALFILE and REMOTEFILE attributes.

The optional attributes for <CFFTP> tag supply an array of useful tools. TIMEOUT allows you to specify the length in seconds for the timeout of all operations. The default is 30 seconds. PORT allows you to specify a port value for the FTP server if different from the default of 21. CONNECTION is used to name your connection if you want to cache it. If you make a call to <CFFTP> with the name attribute specified, it will use the same FTP information as the other connection of the same name, if it was cached. PROXYSERVER allows you to specify a proxyserver to use if proxy access was specified. If not, the tag retrieves proxy information from the registry. PROXYBYPASS allows you to specify a local IP and bypass the proxy server. If this attribute isn't specified, the tag reads the bypass list from the registry. RETRYCOUNT allows you to specify the number of retries until a failure is reported. The default is 1. STOP-ONERROR allows you to specify whether to stop on an error. If yes, all processing stops and an error message is displayed. If no, the error information is saved to three variables: CFFTP.Succeeded (yes or no), CFFTP.ErrorCode (Error Number) and CFFTP.ErrorText (Text explaining error type). PASSIVE is a boolean value indicating whether to enable passive mode. The default is disabled.

Sample Code for <CFFTP>
<CFFTP
ACTION="PutFile"
SERVER="ftp.yourdomain.com"
USERNAME="#client.username#"
PASSWORD="#client.password#'
LOCALFILE="#serverfile#
REMOTEFILE="#serverfile#
>

Final Step – File Removal
The last step in the process is to remove the file from the ColdFusion server, using the <CFFILE> tag with the ACTION attribute set to DELETE. The file to be deleted must be specified using the FILE attribute. Once again, you can use the #ServerFile# variable from the <CFFILE> status variables. When this is finished, the file will be on the FTP server and will also have been removed from the ColdFusion server.

Sample Code for <CFFILE>
<CFILE ACTION="Delete"
FILE="C:\cffile\uploads\#ServerFile#"
>

Summary
ColdFusion offers an impressive variety of tools for file manipulation and FTP. This example touches on only one facet of many that can be implemented using these powerful tags. I've discovered that most of our clients find this an easy and understandable way to send us their files. It's simplified their lives and made my job a little less hectic. I'm sure the time I saved by using this solution (versus training our clients on FTP) should help me take that vacation I've been planning.

Notice:
When specifying the LOCALFILE attribute in the <CFFTP> tag you must use the full path name of the file, similar to the <CFFILE> DESTINATION attribute. Also if you want the uploaded file to be anywhere other than the root directory of the FTP server you must specify the directory as well as the file name in the REMOTEFILE attribute.