ColdFusion 8 has given a new definition to file operations as compared to ColdFusion 7. In ColdFusion 7, cffile is the tag responsible for handling all file operations (for reading a file, for appending data to a file content, to write to a file and other operations). Though cffile is able to give justification to its work, there are some places or situations which cffile fails to perform perfectly. Lets us consider the first situation where we have two files – one file is of size of only some kb and the other one is some 100 kb bigger the first file. For performing file operations on the first file, the cffile tag works fine, but when it comes to the second case where the file size is bigger, it may not perform perfectly. This is because cffile tag can perform operations at a single shot only. So for reading or writing, we need to read data at one time or provide the whole content at one shot, i.e. the whole content needs to be kept in memory.

When the file size is bigger it can create a burden on the server and if the load is very high, it can lead to OutOfMemory error on the server. It would also lead to slow down in performance of the server as it is required to allocate and deallocate larger part of memory which would lead to more frequent garbage collection cycles. One more demerit with cffile is that it cannot be used within cfscript as cfscript does not support ColdFusion tags. So to perform file operations within a script we need to wind up all the required instructions in a function and call that function within the script. Keeping these problems in mind, in ColdFusion 8 a number of functions have been added to address these disadvantages.

The following are the functions included with ColdFusion 8.

·         FileOpen

·         FileRead

·         FileReadLine

·         FileReadBinary

·         FileWrite

·         FileWriteLine

·         FileMove

·         FileCopy

·         FileDelete

·         FileSetAccessMode

·         FileSetLastModified

·         FileSetAttribute

·         FileExists

·         FileIsEOF

·         FileClose

·         GetFileInfo

Let me discuss the functions in more detail.

FileOpen

This function is used to open a file for reading, writing or appending data to a file. It returns the details of the file which is being opened with such things as the filename, its absolute path, size, date last modified, the mode for which the file is opened, and status of the file.

Listing 1: Syntax

FileOpen (filepath [, mode] [, charset])

Here, mode and charset are both optional parameters.

Filepath is the absolute path for the file. Mode is the action to be performed on the file: read, write, append or readBinary. Charset is the charset (or encoding) of the file.

Listing 2

<cfscript
  oFile = FileOpen>("E:\examples\source.cfm", "read");
</cfscript>
<cfdump var="#oFile.status#">

FileRead

This function is used to read a text file or a file object created by using the FileOpen function. This function can be used to read large files instead of using cffile tag. This function can result in improvement in the performance if used instead of cffile tag for large files because this function does not read the entire file content to the memory.

If we pass the filepath, it returns the contents of the file. If we pass a file object and the buffer size, it returns the number of characters specified.

Listing 3: Syntax

FileRead (filepath [, charset]) or FileRead (fileobject [, buffersize])

Filepath is the absolute path to the text file. Fileobject and buffersize are the file objects from which to read and the number of characters to read, respectively.

Listing 4

<cfscript
oFile = FileRead>("E:\examples\source.cfm");
WriteOutput("#oFile#");
</cfscript>

FileReadLine

The functionality of this function is similar to FileRead. The only difference is that FileReadLine function is used to read one line from a file at a time. It returns the line read.

Listing 5: Syntax

FileReadLine (fileObj)

FileObj is the object from which to read (object normally created using FileOpen function).

Listing 6

<cfscript
oFile = FileOpen>("E:\examples\source.cfm", "read");
x = FileReadLine(oFile);
FileClose(oFile);
</cfscript>

FileReadBinary

This can be used to read a binary file. It returns the entire content of the binary file.

Listing 7: Syntax

FileReadBinary (filepath)

Here the file path is the absolute path to the file.

Listing 8

<cfscript
  oFile = FileReadBinary>("E:\examples\image.jpg");
</cfscript>

FileWrite

This function is used to write data to a file.

Listing 9: Syntax

FileWrite (filepath, content [, charset]) or FileWrite (fileObj, content)

Here if we specify the file path, it writes the content to the file and if we specify the file object, then it writes the text to the file object. The charset is the encoding in which the characters in the file are encoded. Content is the data to be written to a file. File object or file path is the name of the file object or file path of where to write.

Listing 10

<cfscript
  oFile = FileOpen>("E:\examples\source.cfm", "read");
  FileWrite("E:\examples\destination.cfm", "#oFile#");
  FileClose(oFile);
</cfscript>

FileWriteLine

This is used to append a line to a file object at a time.

Listing 11: Syntax

FileWriteLine (fileObj, content)

The file object is the file object of where to write and content is the data to be written.

Listing 12

<cfscript
  oFile = FileOpen>("E:\examples\source.cfm", "read");
  FileWriteLine(oFile,"Example of File Write Line");
</cfscript>

FileMove

The function is used to move a file from one place to another on a server.

Listing 13: Syntax

FileMove (source, destination)

Source is the path where the file is currently present and the destination is the path to where to move the file. The source is the absolute path for the file to copy. If it is not the absolute path, then it needs to be relative to the ColdFusion temporary directory. Similarly, for destination we need to pass the absolute path for the file where the file is copied. If not, ColdFusion copies the source file relative to the source directory.

Listing 14

<cfset oSource="E:\examples\source.cfm">
<cfset oDestination="E:\examples\destination.cfm">
<cfif FileExists(#oSource#)>
      <cfif not(FileExists(#oDestination#))>
      <cfscript>
            FileMove(#oSource#, #oDestination#);
       </cfscript>
      </cfif>
<cfelse>
    <cfoutput>The source file cannot be found.</cfoutput>
</cfif>

FileCopy

This function is used to copy a file to another file. This function also requires two arguments: source and destination.

Listing 15: Syntax

FileCopy (source, destination)

Listing 16

<cfscript>
      oSource = “C:\Examples\test.cfm”;
      oDest = “C:\Examples\copyFile.cfm”;
      if(FileExists(oDest)
      {
            WriteOutPut(“A file with this name already exists”);
      }
      if(FileExists(“oSource”)
      {
            FileCopy(#oSource#,#oDest#);
      }
      else
      {
            WriteOutPut(“The source file does not exists”);
      }
</cfscript>

FileDelete

This function is for deleting a file from a server.

Listing 17: Syntax

FileDelete (filepath)

Here the file path is the path to the file which is required to be deleted.

Listing 18

<cfset fileToBeDeleted = "E:\examples\source.cfm">
<cfif FileExists(#fileToBeDeleted#)>
      <cfscript>
            FileDelete(#fileToBeDeleted#);
      </cfscript>
</cfif>

FileSetAccessMode

This function is used to set the attributes of a file on a UNIX or Linux server.

Listing 19: Syntax

FileSetAccessMode (filepath, mode)

File path is the path for the file and mode is a three digit value in which each digit specifies the permissions for the users or groups.  Each digit in the mode values represents permission for a particular person. The first digit represents the permissions for the owner; the second digit represents the permissions for a group and the third one for everyone. Four stands for read permissions, two for write permissions and one for execution permissions. To give multiple rights to a particular user, we need to add the numbers. For example, to give read and write permissions to the owner only, the mode value would be 600.

Listing 20

<cfscript>
  FileSetAccessMode("E:\examples\source.cfm", "444");
</cfscript>

FileSetLastModified

This function is used to set the last modification date for the file.

Listing 20: Syntax

FileSetLastModified (filepath, date)

Listing 21

<cfscript>
  FileSetLastModified("E:\examples\source.cfm", "#Now()#");
</cfscript>

FileSetAttribute

This is used to set the attributes of a file in Windows.

Listing 22: Syntax

FileSetAttribute (filepath, attribute)

The possible values for the attribute parameter are readOnly, hidden or normal. If we specify the attribute as normal, the file is neither read only nor hidden.

Listing 23

<cfscript>
  FileSetAttribute("E:\examples\source.cfm", "hidden");
</cfscript>

FileExists

This function is used to check whether a particular file is present in a server or not. It returns yes if the file is present. But for accessing present on a remote server, the system which is Running ColdFusion must have access permissions to the file, directory and the remote system.

Listing 24: Syntax

FileExists (filepath)

Filepath is the absolute path to the file.

Listing 25

<cfset fileToBeChecked = "E:\examples\source.cfm">
<cfset valueReturned = FileExists(#fileToBeChecked#)>
<cfif valueReturned>
  <cfoutput>The file is present</cfoutput>
</cfif>

FileIsEOF

This function is used if we have reached the end of the file or not. It returns yes if we have reached the end of file.

Listing 26: Syntax

FileIsEOF (fileObj)

Here fileObj is the file object.

Listing 27

<cfscript
      oFile = FileOpen>("E:\examples\source.cfm", "read");
      while(NOT FileIsEOF(oFile))
      {
      fileData = FileReadLine(oFile);
      WriteOutput("#fileData# <br />");
      }
      FileClose(oFile);
</cfscript>

FileClose

This function is used to close a file which has been opened in read, write or append mode. A file should always be closed after working on the file as when we use fileOpen function to work on a file; a file stream is opened from the disk for performing all operations. So if after working we do not use FileClose function to close the files, the stream still remains open. This may lead to locking of the file and as a result the file would not be available i.e. it would not be able to perform any operations on the file. It can nether be modified, renamed or deleted. To make it usable we need to restart the server. Though ColdFusion has a way to handle this, it tries to handles the situation when the file object goes out of the accessible scope and even then there is no certainty in when it will happen.

Listing 28: Syntax

FileClose (fileObj)

Listing 29

<cfscript
  oFile = FileOpen>("E:\examples\source.cfm", "read");
  fileData = FileRead(oFile, 10)
  WriteOutput("#fileData# <br />");
  FileClose(myfile);
</cfscript>

GetFileInfo

This function is used to retrieve information about a file. It returns all the information regarding the file including the file name, file path, parent directory, size, type, last modification date, and whether the file is writable, readable or is hidden.

Listing 30: Syntax

GetFileInfo(path) 

Where path is the absolute path to the file.

Listing 31

<cfset oFile = "E:\examples\source.cfm">
<cfscript>
  FileSetAttribute(oFile, "hidden");
  WriteOutput(GetFileInfo(oFile).isHidden);
</cfscript>

I hope this will help all the ColdFusion developers perform file operations easily. In ColdFusion 8, a number of new tags and functions have been added for other operations, like for performing operations on an image, etc. I think ColdFusion developers will have great fun in exploring all the new features introduced in ColdFusion 8. So what are you waiting for!

For more details on all the new features added to ColdFusion 8 please refer to the documentations at Adobe site.

By Debjani Mallick