cfdocs.org /
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">

See also

cfdirectory

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.