cffile action = "read"

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_path_name"
   variable = "var_name"
   charset = "charset_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 a 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, you must 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.