Adobe ColdFusion 8

Evaluating the results of a file upload

After a file upload is completed, you can retrieve status information using file upload status variables. This status information includes data about the file, such as its name and the directory where it was saved.

You can access file upload status variables using dot notation, using either file.varname or cffile.varname. Although you can use either the File or cffile prefix for file upload status variables, cffile is preferred; for example, cffile.ClientDirectory. The File prefix is retained for backward compatibility.

Note: File status variables are read-only. They are set to the results of the most recent cffile operation. If two cffile tags execute, the results of the first are overwritten by the subsequent cffile operation.

The following table describes the file upload status variables that are available after an upload:

Variable

Description

attemptedServerFile

Initial name that ColdFusion uses when attempting to save a file; for example, myfile.txt. (see Resolving conflicting filenames).

clientDirectory

Directory on the client's system from which the file was uploaded.

clientFile

Full name of the source file on the client's system with the file extension; for example, myfile.txt.

clientFileExt

Extension of the source file on the client's system without a period; for example, txt (not .txt).

clientFileName

Name of the source file on the client's system without an extension; for example, myfile.

contentType

MIME content type of the saved file; for example, image for image/gif.

contentSubType

MIME content subtype of the saved file; for example, gif for image/gif.

dateLastAccessed

Date that the uploaded file was last accessed.

fileExisted

Indicates (Yes or No) whether the file already existed with the same path.

fileSize

Size of the uploaded file.

fileWasAppended

Indicates (Yes or No) whether ColdFusion appended the uploaded file to an existing file.

fileWasOverwritten

Indicates (Yes or No) whether ColdFusion overwrote a file.

fileWasRenamed

Indicates (Yes or No) whether the uploaded file was renamed to avoid a name conflict.

fileWasSaved

Indicates (Yes or No) whether ColdFusion saved the uploaded file.

oldFileSize

Size of the file that was overwritten in the file upload operation. Empty if no file was overwritten.

serverDirectory

Directory where the file was saved on the server.

serverFile

Full name of the file saved on the server with the file extension; for example, myfile.txt.

serverFileExt

Extension of the file saved on the server without a period; for example, txt (not .txt).

serverFileName

Name of the file saved on the server without an extension; for example, myfile.

timeCreated

Date and time the uploaded file was created.

timeLastModified

Date and time of the last modification to the uploaded file.

Moving, renaming, copying, and deleting server files

With the cffile tag, you can create application pages to manage files on your web server. You can use the tag to move files from one directory to another, rename files, copy a file, or delete a file.

The examples in the following table show static values for many of the attributes. However, the value of all or part of any attribute in a cffile tag can be a dynamic parameter.

Action

Example code

Move a file

 <cffile action="move" source="c:\files\upload\KeyMemo.doc" destination="c:\files\memo\">

Rename a file

 <cffile action="rename" source="c:\files\memo\KeyMemo.doc" destination="c:\files\memo\OldMemo.doc">

Copy a file

 <cffile action="copy" source="c:\files\upload\KeyMemo.doc" destination="c:\files\backup\">

Delete a file

 <cffile action="delete" file="c:\files\upload\oldfile.txt">

This example sets the ReadOnly flag bit for the uploaded file:

<cffile action="Copy"
    source="c:\files\upload\keymemo.doc"
    destination="c:\files\backup\"
    attributes="ReadOnly">

Note: Ensure you include the trailing slash (\) when you specify the destination directory. Otherwise, ColdFusion treats the last element in the pathname as a filename. This only applies to copy actions.

Reading, writing, and appending to a text file

In addition to managing files on the server, you can use the cffile tag to read, create, and modify text files. As a result, you can do the following things:

  • Create log files. (You can also use cflog to create and write to log files.)
  • Generate static HTML documents.
  • Use text files to store information that can be incorporated into web pages.

Reading a text file

You can use the cffile tag to read an existing text file. The file is read into a local variable that you can use anywhere in the application page. For example, you could read a text file and then insert its contents into a database, or you could read a text file and then use one of the string replacement functions to modify the contents.

Read a text file

  1. Create a ColdFusion page with the following content:
    <html>
<head>
    <title>Read a Text File</title>
</head>

<body>
Ready to read the file:<br>
<cffile action="read"
    file="C:\inetpub\wwwroot\mine\message.txt"
    variable="Message">

<cfoutput>
    #Message#
</cfoutput>
</body>
</html>

  2. Replace C:\inetpub\wwwroot\mine\message.txt with the location and name of a text file on the server.
  3. Save the file as readtext.cfm in the myapps directory under your web_root and view it in the browser.

Writing a text file on the server

You can use the cffile tag to write a text file based on dynamic content. For example, you could create static HTML files or log actions in a text file.

Create a form in to capture data for a text file

  1. Create a ColdFusion page with the following content:
    <html>
<head>
    <title>Put Information into a Text File</title>
</head>

<body>
<h2>Put Information into a Text File</h2>

<form action="writetextfileaction.cfm" method="Post">
    <p>Enter your name: <input type="text" name="Name" size="25"></p>
    <p>Enter the name of the file: <input type="text" name="FileName" size="25">.txt</p>
    <p>Enter your message:
    <textarea name="message"cols=45 rows=6></textarea>
    </p>
    <input type="submit" name="submit" value="Submit"> 
</form>
</body>
</html>

  2. Save the file as writetextfileform.cfm in the myapps directory under your web_root.

Note: The form will not work until you write an action page for it (see the next procedure).

Write a text file

  1. Create a ColdFusion page with the following content:
    <html>
<head>
    <title>Write a Text File</title>
</head>
<body>
<cffile action="write"
    file="C:\inetpub\wwwroot\mine\#Form.FileName#.txt"
    output="Created By: #Form.Name#
#Form.Message# ">
</body>
</html>

  2. Modify the path C:\inetpub\wwwroot\mine\ to point to a path on your server.
  3. Save the file as writetextfileaction.cfm in the myapps directory under your web_root.
  4. View the file writetextfileform.cfm in the browser, enter values, and submit the form.

    The text file is written to the location you specified. If the file already exists, it is replaced.

Appending a text file

You can use the cffile tag to append additional text to the end of a text file; for example, when you create log files.

Append a text file

  1. Open the writetextfileaction.cfm file.
  2. Change the value for the action attribute from write to append so that the file appears as follows:
    <html>
<head>
    <title>Append a Text File</title>
</head>
<body>
<cffile action="append"
    file="C:\inetpub\wwwroot\mine\message.txt"
    output="Appended By: #Form.Name#">
</body>
</html>

  3. Save the file as writetextfileaction.cfm in the myapps directory under your web_root.
  4. View the file in the browser, enter values, and submit the form.

    The appended information displays at the end of the text file.