The File and Folder commands, which appeared in 4D v17 R5, enable you to manage folders and files on disk in a modern and efficient way.

When it comes to writing and reading, the setText and getText functions are at your disposal to read or write the entire content. But what to do if you want to read or add one or more lines to an existing document? This can be done more efficiently than ever using the new “file handles” objects in 4D v19 R7.

Keep reading for details!

HDI Use file handles

What are File handles?

File handles are objects created based on “File” objects and have functions to access any part of documents and, from there, to read or write their content sequentially.

Even if, in the general case, we read from the beginning to the end, it is possible to define precisely the position of the “reading head.”

In the same way, when you want to open a document to write new information, it is generally at the end of the document you want to write. You can position the “writing head” wherever you want.

But it’s not all!

The file handle’s primary and most significant feature is that it will avoid opening and closing documents, which is a big time-consuming operation. And the best thing is closing files by programming is no longer mandatory. As soon as the file handled is not referenced anywhere in your code, the file will be closed automatically! That’s why, as we’ll see later, no .close() function is needed!

Let’s dive into a quick sample.

The goal is to add lines to a log file. Let’s create a class called Logger and a function called writeLine and see how to call it !

Class constructor($logName : Text)
	
	var $file : 4D.File
	
	$file:=File("/LOGS/"+$logName)
	$file.parent.create()  // check that parent folder exists; Otherwise it will be created.
	This.fh:=$file.open("append")
	
Function writeLine($logText : Text)
	
	This.fh.writeLine($logText)

Once this class is created, let’s call it !

var $logger : cs.Logger
var $logName : Text

$logName:=Replace string(Timestamp; ":"; "-")+".txt"
$logger:=cs.Logger.new($logName)

For ($i; 1; 10)
	$logger.writeLine("test_"+String(Random))
End for 

At this point, we could close the file by setting the $logger object to NULL, but it’s not mandatory ! At the end of this code, the $logger (and its attribute .fh) will be NULL so the file will be closed!

Attributes and functions

New file Function:

The first function, open(), is a new function of the File allowing the creation of the handle. The handle can be created in read, write, or append modes.

$handle:=$file.open("write")

You can also use an object as a parameter if you need to specify the charset and the read or write delimiters.

$o:=New object()
$o.mode:="append"
$o.charset:="UTF-8"
$o.breakModeRead:=Document with CRLF
$o.breakModeWrite:=Document with CRLF
$handle:=$file.open($o)

Once the handle is created, more attributes and functions will be available:

Two more Handle useful Attributes

• .offset is the current offset of the data stream (position inside the document)
  • This attribute is writable. Use it only if you need to set the read or write position at a specific place. Just remember its values changes automatically after a read or write operation.
• .eof is false as long as the end of the document is not reached.

 

The .eof attribute allows you to browse a file in an exquisite way

$fileHandle:=$file.open("read")  
While (Not($fileHandle.eof))  // eof = end of file
	$text:=$fileHandle.readLine() 
	//…	
End while 

handle Functions

The handle class comes with many functions that allow to:

• Read and write text
• Read and write lines (with automatic management of line breaks)
• Get and set the size of a document
• Read and write Blobs! 

Where to go from here?

Find more details on the documentation center. And feel free to reach out to us on the 4D forums; we will be happy to help.