ColdFusion 9.0 Resources

cffile action = "read"

Note: You can specify this tag’s attributes in an attributeCollection attribute whose value is a structure. Specify the structure name in the attributeCollection attribute and use the tag’s attribute names as structure keys.

Description

Reads a text file on the server. The file is read into a dynamic, local variable that you can use in the page. For example:

Read a text file; insert the file’s contents into a database
Read a text file; use the find and replace function to modify the file’s contents

Note: This action reads the file into a variable in the local Variables scope. It is not intended for use with large files, such as logs, because this can bring down the server.

Syntax

<cffile  
    action = "read"  
    file = "full pathname" 
    variable = "variable name" 
    charset = "character set option">

History

See the History section of the main cffile tag page.

Attributes

Attribute	Req/Opt	Default	Description
`action`	Required		Type of file manipulation that the tag performs.
`file`	Required		Pathname of the file to read. If not an absolute path (starting with a drive letter and a colon, or a forward or backward slash), it is relative to the ColdFusion temporary directory, which is returned by the `GetTempDirectory` function.
`variable`	Required		Name of variable to contain contents of text file.
`charset`	Optional	Character encoding identified by the file’s byte order mark, if any; otherwise, JVM default file character set.	The character encoding in which the file contents is encoded. The following list includes commonly used values: `utf-8` `iso-8859-1` `windows-1252` `us-ascii` `shift_jis` `iso-2022-jp` `euc-jp` `euc-kr` `big5` `euc-cn` `utf-16` If the file starts with a byte order mark and you set this attribute to a conflicting character encoding, ColdFusion generates an error. For more information character encodings, see www.w3.org/International/O-charset.html.

Usage

The following example creates a variable named Message for the contents of the file message.txt:

<cffile action = "read"  
    file = "c:\web\message.txt"  
    variable = "Message">

The variable Message can be used in the page. For example, you could display the contents of the message.txt file in the final web page as follows:

<cfoutput>#Message#</cfoutput>

ColdFusion supports functions for manipulating the contents of text files. You can also use the variable that is created by a cffile action = "read" operation in the ArrayToList and ListToArray functions.

Note: If you use this tag to read a file that is encoded using the Windows Cp1252 (windows-1252) encoding of the Latin-1 character set on a system whose default character encoding is Cp1252, and the files has characters encoded in the Hex 8x or 9x range, specify charset="windows-1252" attribute, even though this is the default encoding. Otherwise, some characters in the Hex8x and 9x ranges that do not map correctly and display incorrectly.