<CFFILE ACTION="Action"
ATTRIBUTE="value"
ATTRIBUTE="value"
ATTRIBUTE="value">
Use the CFILE tag to handle all interactions with files. The attributes you use with CFILE depend on the value of the ACTION attribute. For example, if the ACTION is "Write," Cold Fusion expects the attributes associated with writing a text file.
See the individual CFFILE topics below for details about which attributes apply to which ACTIONs.
CFFILE ACTION attributes
Depending on the value you assign to the ACTION attribute of CFFILE, there are several additional atributes you can set. This table shows which attributes you can use with each CFFILE ACTION.
Attributes Used with CFFILE ACTION Values
|
ACTION
|
Attributes |
Upload
|
ACCEPT
DESTINATION
FILEFIELD
NAMECONFLICT
MODE
ATTRIBUTES |
Move
|
SOURCE
DESTINATION
ATTRIBUTES |
Rename
|
SOURCE
DESTINATION
ATTRIBUTES |
Copy
|
SOURCE
DESTINATION
ATTRIBUTES |
Delete
|
FILE |
Read
|
FILE
VARIABLE |
Write
|
OUTPUT
FILE
MODE
ATTRIBUTES |
Append
|
OUTPUT
FILE
MODE
ATTRIBUTES | Sections that follow describe these values nd attributes in greater detail.
<CFFILE ACTION="Upload">
Use CFFILE with the Upload action to upload a file specified in a form field to a directory on the Web server.
Note that the MODE attribute applies only to Cold Fusion on Solaris.
Syntax
<CFFILE ACTION="Upload"
FILEFIELD="formfield"
DESTINATION="directory"
NAMECONFLICT="behavior"
ACCEPT="file_extension"
MODE="permission"
ATTRIBUTES="file_attributes">
Attributes
FILEFIELD
|
Required. The name of the form field that was used to select the file.
Note: Do not use pound signs (#) to specify the field name. |
DESTINATION
|
Required. The destination directory on the Web server where the file should be saved.
Note: The directory does not need to be beneath the root of the Web server document directory. |
NAMECONFLICT
|
Optional. Default is error. Determines how the file should be handled if its name conflicts with the name of a file that already exists in the directory. Valid entries are:
-
Error Default. The file will not be saved, and Cold Fusion will stop processing the page and return an error.
-
Skip Neither saves the file nor throws an error. This setting is intended to allow custom behavior based on inspection of FILE properties. See Evaluating the results of a file upload later in this section for more information.
-
Overwrite Replaces an existing file if it shares the same name as the CFFILE destination.
-
MakeUnique Automatically generates a unique filename for the upload. This name will be stored in the FILE object variable "ServerFile." You can use this variable to record what name was used when the file was saved.
|
ACCEPT
|
Optional. Use to limit what types of files will be accepted. Enter one or more MIME types, each separated by comma, of the file types you want to accept. For example, to allow uploads of GIF and Microsoft Word files, enter:
ACCEPT="image/gif, application/msword"
Note: The browser uses the file extension to determine file type. |
MODE
|
Optional. Defines permissions for an uploaded file in Solaris. Ignored in Windows. Valid entries correspond to the octal values (not symbolic) of the Unix chmod command. Permissions are assigned for owner, group, and other, respectively. For example:
MODE=644
Assigns the owner read/write permissions and group/other read permission.
MODE=666
Assigns read/write permissions for owner, group, and other.
MODE=777
Assigns read, write, and execute permissions for all. |
ATTRIBUTES
|
Optional. A comma-delimited list of file attributes to be set on the file being uploaded. The following file attributes are supported:
-
ReadOnly
-
Temporary
-
Archive
-
Hidden
-
System
-
Normal
If ATTRIBUTES is not used, the file's attributes are maintained. If Normal is specified as well as any other attributes, Normal is overridden by whatever other attribute is specified. | Examples
The following example will create a unique filename if there is a name conflict when the file is uploaded:
<CFFILE ACTION="Upload"
FILEFIELD="FileContents"
DESTINATION="c:\web\uploads\"
ACCEPT="text/html"
NAMECONFLICT="MakeUnique">
This following three examples show the use of the MODE attribute for UNIX. The first example creates the file /tmp/foo with permissions defined as rw-rr-- (owner=read/write, group/other=read).
<CFFILE ACTION="Write"
FILE="/tmp/foo"
MODE=644>
This example appends to the specified file and makes permissions read/write (rw) for all.
<CFFILE ACTION="Append"
DESTINATION="/home/tomj/testing.txt"
MODE=666
OUTPUT="Is this a test?">
The next example uploads a file and gives it rwx-rw-rw permissions (owner/group/other=read/write).
CFFILE ACTION="Upload"
FILEFIELD="fieldname"
DESTINATION="/tmp/program.exe"
MODE=755>
Evaluating the results of a file upload
After a file upload is completed, you can retrieve status information using file upload parameters. This status information includes a wide range of data about the file, such as the files name and the directory where it was saved.
File upload status parameters use the "File" prefix, for example, File.ClientDirectory. The file status parameters can be used anywhere other Cold Fusion parameters can be used.
The following file upload status parameters are available after an upload.
File Upload Parameters
|
Parameter
|
Description |
AttemptedServerFile
|
Initial name Cold Fusion used attempting to save a file, for example, myfile.txt. |
ClientDirectory
|
Directory location of the file uploaded from the clients system. |
ClientFile
|
Name of the file uploaded from the clients system. |
ClientFileExt
|
Extension of the uploaded file on the clients system without a period, for example, txt not .txt. |
ClientFileName
|
Filename without an extension of the uploaded file on the clients system. |
ContentSubType
|
MIME content subtype of the saved file. |
ContentType
|
MIME content type of the saved file. |
DateLastAccessed
|
Date and time the uploaded file was last accessed. |
FileExisted
|
Indicates (Yes or No) whether or not the file already existed with the same path. |
FileSize
|
Size of the uploaded file. |
FileWasAppended
|
Indicates (Yes or No) whether or not Cold Fusion appended the uploaded file to an existing file. |
FileWasOverwritten
|
Indicates (Yes or No) whether or not Cold Fusion overwrote a file. |
FileWasRenamed
|
Indicates (Yes or No) whether or not the uploaded file was renamed to avoid a name conflict. |
FileWasSaved
|
Indicates (Yes or No) whether or not Cold Fusion saved a file. |
OldFileSize
|
Size of a file that was overwritten in the file upload operation. |
ServerDirectory
|
Directory of the file actually saved on the server. |
ServerFile
|
Filename of the file actually saved on the server. |
ServerFileExt
|
Extension of the uploaded file on the server, without a period, for example, txt not .txt. |
ServerFileName
|
Filename, without an extension, of the uploaded file on the server. |
TimeCreated
|
Time the uploaded file was created. |
TimeLastModified
|
Date and time of the last modification to the uploaded file. | Tip: Use the File prefix to refer to these parameters, for example, #File.FileExisted#.
Note: File status parameters 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.)
<CFFILE ACTION="Move">
The CFFILE MOVE action can be used to move a file from one location on the server to another.
Syntax
<CFFILE ACTION="Move"
SOURCE="file_name"
DESTINATION="directory_name">
Attributes
SOURCE
|
Required. The file to move (with directory location). |
DESTINATION
|
Required. The directory to which the file will be moved. For UNIX, a trailing slash must be included in the target when moving a directory. Backward slashes (\), used in Windows are interpreted as forward slashes (/) in UNIX, and vice versa. |
ATTRIBUTES
|
Optional. A comma-delimited list of file attributes to be set on the file being moved. The following file attributes are supported:
-
ReadOnly
-
Temporary
-
Archive
-
Hidden
-
System
-
Normal
If ATTRIBUTES is not used, the file's attributes are maintained. If Normal is specified as well as any other attributes, Normal is overridden by whatever other attribute is specified. | Example
The following example moves the keymemo.doc file from the c:\files\upload\ directory to the c:\files\memo\ directory:
<CFFILE ACTION="Move"
SOURCE="c:\files\upload\keymemo.doc"
DESTINATION="c:\files\memo\">
<CFFILE ACTION="Rename">
Use CFFILE with the Rename action to rename a file that already exists on the server.
Syntax
<CFFILE ACTION="Rename"
SOURCE="file_name"
DESTINATION="file_name">
Attributes
SOURCE
|
Required. The file to rename (with directory location). |
DESTINATION
|
Required. The new name for the file (with directory location). |
ATTRIBUTES
|
Optional. A comma-delimited list of file attributes to be set on the file being renamed. The following file attributes are supported:
-
ReadOnly
-
Temporary
-
Archive
-
Hidden
-
System
-
Normal
If ATTRIBUTES is not used, the file's attributes are maintained. If Normal is specified as well as any other attributes, Normal is overridden by whatever other attribute is specified. | Example
The following example renames the file keymemo.doc to oldmemo.doc:
<CFFILE ACTION="Rename"
SOURCE="c:\files\memo\keymemo.doc"
DESTINATION="c:\files\memo\oldmemo.doc">
<CFFILE ACTION="Copy">
The CFFILE tag can be used to copy a file from one directory to another on the server.
Syntax
<CFFILE ACTION="Copy"
SOURCE="file_name"
DESTINATION="directory_name">
Attributes
SOURCE
|
Required. The file to copy (with directory location). |
DESTINATION
|
Required. The directory where the copy of the file will be saved. |
ATTRIBUTES
|
Optional. A comma-delimited list of file attributes to be set on the file being copied. The following file attributes are supported:
-
ReadOnly
-
Temporary
-
Archive
-
Hidden
-
System
-
Normal
If ATTRIBUTES is not used, the file's attributes are maintained. If Normal is specified as well as any other attributes, Normal is overridden by whatever other attribute is specified. | Example
The following example saves a copy of the keymemo.doc file in the c:\files\backup\ directory:
<CFFILE ACTION="Copy"
SOURCE="c:\files\upload\keymemo.doc"
DESTINATION="c:\files\backup\">
<CFFILE ACTION="Delete">
The CFFILE tag can be used to delete a file on the server.
Syntax
<CFFILE ACTION="Delete"
FILE="file_name">
Attribute
FILE
|
Required. The file to delete (with directory location). | Example
The following example permanently deletes the specified file:
<CFFILE ACTION="Delete"
FILE="c:\files\upload\#Variables.DeleteFileName#">
<CFFILE ACTION="Read">
You can use the CFFILE tag to read an existing text file. The file is read into a dynamic parameter you can use anywhere in the page like any other dynamic parameter. 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 find and replace functions to modify its contents.
Syntax
<CFFILE ACTION="Read"
FILE="file_name"
VARIABLE="var_name">
Attributes
FILE
|
Required. The text file to be read (with directory location). |
VARIABLE
|
Required. The name of the variable that will contain the contents of the text file after it has been read. | Example
The following example creates a variable named "Message" that will contain the contents of the file message.txt.
<CFFILE ACTION="Read"
FILE="c:\web\message.txt"
VARIABLE="Message">
The variable "Message" could then be used in the page. For example, you could display the contents of the message.txt file in the final Web page:
<CFOUTPUT>#File.Message#</CFOUTPUT>
Cold Fusion supports a number of powerful functions for manipulating the contents of text files. You can also use variable created by a CFFILE Read operation in ArrayToList and ListToArray functions. See String Functions in Chapter 3, for more information about how to use these functions and Array Functions for information about working with arrays.
<CFFILE ACTION="Write">
You can use the CFFILE tag to write a text file based on dynamic content. For example, you could create static HTML files from this content or log actions in a text file.
Syntax
<CFFILE ACTION="Write"
FILE="file_name"
OUTPUT="content"
MODE="permission">
Attributes
FILE
|
Required. The name of the file to be created (with directory location). |
OUTPUT
|
Required. The content of the file to be created. |
MODE
|
Optional. Defines permissions for a file in Solaris. Ignored in Windows. Valid entries correspond to the octal values (not symbolic) of the Unix chmod command. Permissions are assigned for owner, group, and other, respectively. For example:
MODE=644
Assigns the owner read/write permissions and group/other read permission.
MODE=666
Assigns read/write permissions for owner, group, and other.
MODE=777
Assigns read, write, and execute permissions for all. |
ATTRIBUTES
|
Optional. A comma-delimited list of file attributes to be set on the file being written. The following file attributes are supported:
-
ReadOnly
-
Temporary
-
Archive
-
Hidden
-
System
-
Normal
If ATTRIBUTES is not used, the file's attributes are maintained. If Normal is specified as well as any other attributes, Normal is overridden by whatever other attribute is specified. | Example
The following example creates a file with the information a user entered into an HTML insert form:
<CFFILE ACTION="Write"
FILE="c:\files\updates\#Form.UpdateTitle#.txt"
OUTPUT="Created By: #Form.FullName#
Date: #Form.Date#
#Form.Content#">
If the user submitted a form where:
UpdateTitle="FieldWork"
FullName="World B. Frueh"
Date="10/30/97"
Content="We had a wonderful time in Cambridgeport."
Cold Fusion would create a file named FieldWork.txt in the c:\files\updates\ directory and the file would contain the text:
Created By: World B. Frueh
Date: 10/30/97
We had a wonderful time in Cambridgeport.
This following examples show the use of the MODE attribute for UNIX. The first, creates the file /tmp/foo with permissions defined as rw-rr-- (owner=read/write, group/other=read).
<CFFILE ACTION="Write"
FILE="/tmp/foo"
MODE=644>
This example appends to the specified file and makes permissions read/write (rw) for all.
<CFFILE ACTION="Append"
DESTINATION="/home/tomj/testing.txt"
MODE=666
OUTPUT="Is this a test?">
The next example uploads a file and gives it rwx-rw-rw permissions (owner/group/other=read/write).
CFFILE ACTION="Upload"
FILEFIELD="fieldname"
DESTINATION="/tmp/program.exe"
MODE=755>
<CFFILE ACTION="Append">
Use CFFILE with the Append action to append additional text to the end of an existing text file, for example, when creating log files.
Syntax
<CFFILE ACTION="Append"
FILE="file_name"
OUTPUT="string">
Attributes
FILE
|
Required. The file to which the content of the OUTPUT attribute is appended (with directory location). |
OUTPUT
|
Required. The string to be appended to the file designated in the DESTINATION attribute. |
ATTRIBUTES
|
Optional. A comma-delimited list of file attributes to be set on the file being appended. The following file attributes are supported:
-
ReadOnly
-
Temporary
-
Archive
-
Hidden
-
System
-
Normal
If ATTRIBUTES is not used, the file's attributes are maintained. If Normal is specified as well as any other attributes, Normal is overridden by whatever other attribute is specified. | Example
The following example appends the text string "But Davis Square is the place to be." to the file fieldwork.txt which was created in the previous example:
<CFFILE ACTION="Append"
FILE="c:\files\updates\fieldwork.txt"
OUTPUT="<B>But Davis Square is the place to be.</B>">
|