Chapter 6 using% File object

If you want to manipulate the File itself, you need to use% library The% New() method of File instantiates the% File object. The class also provides instance methods that allow the File to be used.

Note: this section provides several examples of using the% File object for illustration.

For simple file reading and writing, use% stream Filecharacter and% stream FileBinary. Because they provide additional features, such as automatically opening files in the correct mode.

Create an instance of the% File object

To use a File, you need to instantiate the% File object representing the File using the% New() method. The File may or may not exist on disk.

The following example is the File export. In the default directory XML instantiates a% File object.

set fileObj = ##class(%File).%New("export.xml")

Opening and closing files

After instantiating the% File object, you need to use the open() method to open the File to read or write to it:

USER>set status = fileObj.Open()

USER>write status
1

Close the file using the Close() method:

USER>do fileObj.Close()

Check the properties of the% File object

Once the file is instantiated, you can directly check the properties of the file.

USER>write fileObj.Name
export.xml
USER>write fileObj.Size
2512
USER>write $zdate(fileObj.DateCreated)
11/18/2020
USER>write $zdate(fileObj.DateModified)
11/18/2020
USER>write fileObj.LastModified
2020-11-18 14:24:38
USER>write fileObj.IsOpen
0

Note that LastModified is a human readable timestamp, not a date in $H format.

The properties Size, creation date DateCreated, modification date DateModified, and last modification date LastModified are calculated at access time. Accessing these properties for a file that does not exist returns - 2, indicating that the file cannot be found.

Note: Windows is currently the only platform that tracks the actual creation date. The date when the last file status change was stored on another platform.

USER>write ##class(%File).Exists("foo.xml")
0
USER>set fooObj = ##class(%File).%New("foo.xml")
 
USER>write fooObj.Size
-2

If the file is open, you can view its canonical name by accessing the CanonicalName property, which is the full path to the root directory.

USER>write fileObj.CanonicalName
 
USER>set status = fileObj.Open()
 
USER>write fileObj.IsOpen
1
USER>write fileObj.CanonicalName
c:\intersystems\IRIS\mgr\user\export.xml

Read from file

To read a file, open the file and use the Read() method.

The following example reads messages The first 200 characters of the log.

USER>set messages = ##class(%File).%New(##class(%File).ManagerDirectory() _ "messages.log")
 
USER>set status =  messages.Open("RU")
 
USER>write status
1
USER>set text = messages.Read(200, .sc)

USER>write text
 
 
 
*** Recovery started at Mon Dec 09 16:42:01 2019
     Current default directory: c:\intersystems\IRIS\mgr
     Log file directory: .\
     WIJ file spec: c:\intersystems\IRIS\mgr\IR
USER>write sc
1
USER>do messages.Close() 

To read the entire line from the file, use the ReadLine() method, which inherits from% library File's parent class% library AbstractStream.

The following example reads e: \ temp \ new Txt.

///desc: read data
/// w ##class(Demo.FileDemo).ReadFileData("E:\temp\new.txt")
ClassMethod ReadFileData(str)
{
	s fileObj  = ##class(%File).%New(str)
	s status =  fileObj.Open("RU")
	w status,!
	s text = fileObj.ReadLine(,.sc)
	w text,!
	w sc,!
	d fileObj.Close()
	
	q ""
}

write file

To write to a file, you can open the file and use the Write() or WriteLine() methods.

The following example writes a line of text to a new file.

///desc: write data
/// w ##class(Demo.FileDemo).WriteFileData("E:\temp\new.txt")
ClassMethod WriteFileData(str)
{
	s fileObj = ##class(%File).%New(str)
	s status = fileObj.Open("RUWSN")
	w status,!
	s status = fileObj.WriteLine("Writing to a new file.")
	w status,!
	w fileObj.Size,!
	d fileObj.Rewind()
	s text = fileObj.ReadLine(,.sc)
	w text,!
	q ""
}

Rewind file

After reading from or writing to a file, you want to rewind the file using the Rewind() method so that you can perform the operation from the beginning of the file.

Starting where the previous example stopped, fileObj is now at the end. Rewinding the file and using WriteLine() again overwrites the file.

USER>set status = fileObj.Rewind()

USER>write status
1
USER>set status = fileObj.WriteLine("Rewriting the file from the beginning.")
 
USER>write status
1
USER>write fileObj.Size
40

Closing the file and reopening it will also rewind the file.

USER>do fileObj.Close()
 
USER>set status = fileObj.Open("RU")
 
USER>write status
1
USER>set text = fileObj.ReadLine(,.sc)
 
USER>write sc
1
USER>write text
Rewriting the file from the beginning.

Clear file

To clear a file, open the file and use the Clear() method. This will delete the file from the file system.

The following example clears junk. In the default directory xml.

USER>write ##class(%File).Exists("junk.xml")
1
USER>set fileObj = ##class(%File).%New("junk.xml")

USER>set status = fileObj.Open()

USER>write status
1
USER>set status = fileObj.Clear()
 
USER>write status
1
USER>write ##class(%File).Exists("junk.xml")
0