Door 3 - Binary File

Behind door 3 is a component that is mostly unseen, but is used in many applications by customers and has become essential. It is the BinaryFile component. You can use it to read binary data from a file and also write it to a file.

But what is it actually good for? Although the texts are saved as binary data, you can also create normal text files with this component and read them out again later. For example, you can create a log file yourself in which you can write information. We would like to do this now by logging in the file when a certain script has been called and what result it has. The aim is to have as less code as possible in the script that we want to log so that the script doesn't become confusing. For this reason, we use the Perform Script script step and call a script that writes the desired text to the log file. We pass the text that we want to write to the log file as a parameter. In this way, for example, the results that were calculated in the script can also be written to the file.

In the script below, a line should be written to the file containing the timestamp, the script name of the calling script and the information that the script was started at this time. The script is then executed. In this script we stop for 2 seconds so that we can also see a change in the timestamp and set the result of the script in the variable $res. Let's call the same script as at the beginning again and pass the text in the parameter again. This again contains the timestamp and script name and this time still returns the result that we have in the calling script.

Perform Script [ Specified: From list ; "Write" ; Parameter: Get ( CurrentTimestamp ) & "-" & Get(ScriptName) & "-Start" ]

Pause/Resume Script [ Duration (seconds): 2 ] 
Set Variable [ $res ; Value: 1 ] 

Perform Script [ Specified: From list ; "Write" ; Parameter: Get ( CurrentTimestamp ) & "-" & Get(ScriptName)  & "-Finish-res:" & $res ]

The Write script which executes the log entries looks like this:

Set Variable [ $Param ; Value: Get(ScriptParameter) ] 
Set Variable [ $Path ; Value: MBS("Path.AddPathComponent"; MBS("Folders.UserDesktop"); "MBS_Binary_File.txt") ] 
If [ MBS("Files.FileExists"; $Path) ] 
	# Add Information
	Set Variable [ $ref ; Value: MBS( "BinaryFile.Append"; $Path ) ] 
	Set Variable [ $r ; Value: MBS( "BinaryFile.WriteText"; $ref; "¶" & $Param ; "UTF-8"  ) ] 
	Set Variable [ $r ; Value: MBS( "BinaryFile.Close"; $ref ) ] 
Else
	# Create one
	Set Variable [ $ref ; Value: MBS( "BinaryFile.Create"; $Path ) ] 
	Set Variable [ $r ; Value: MBS("BinaryFile.WriteText"; $ref; $Param;"UTF-8") ] 
	Set Variable [ $r ; Value: MBS( "BinaryFile.Close"; $ref ) ] 
	
End If

First we save the text from the passed parameter. Next, we assemble the path where the file is located. More about this in a later door . The path now leads to a file with the name MBS_Binary_File.txt which is located on the desktop. Now we have to make our procedure dependent on whether the file already exists or still has to be created. We check this with the Files.FileExists function.

If the file already exists, we use the "BinaryFile.Append" function to open the file. It returns a reference to this file. The cursor is at the last position of the document. We now call BinaryFile.WriteText and first pass the document reference and the text to be written to the file. We place a line break in front of the text so that each new entry is on a new line. We can also specify the encoding in the optional parameter. By default this is UTF-8 but can be changed to ANSI, ISO-8859-1, Latin1, Mac, Native, DOS, Hex, Base64 or Windows. When we are finished with the entry, we call the function "BinaryFile.Close", which closes the file again.

It is a little different if we do not yet have a file. In this case, it is first created and opened with the "BinaryFile.Create" function. We receive the reference number again and can then enter the text in the file as usual, with the difference that we do not need the line break here, because we write the first line in the document.

For example, it is also possible for you to log errors. Here we have a script in which an MBS function is used incorrectly and thus throws an error, the reason being that the sybology ABC does not exist. This error is now entered in the text file.

...
Set Variable [ $r ; Value: MBS("Barcode.Generate"; "ABC"; "xyz") ] 
If [ MBS("IsError") ] 
	Perform Script [ Specified: From list ; "Write" ; Parameter: Get ( CurrentTimestamp ) & "-" & Get(ScriptName)  & "Error: " & $r ]
	Exit Script [ Text Result:] 
End If
...

We can now not only write normal text to the document, but also a value in hexadecimal, for which we have the BinaryFile.WriteHex function. In the parameters, you can specify a character string coded in hexadecimal, which is then written to the document as text. For example, if we pass the character string 48656C6C6F20576F726C64 to this function, our output will look like this:

ke to add a line break before the hexadecimal text. We would therefore like to enter a Chr(13) in the document. This can be realized with the function BinaryFile.WriteByte. We write a single byte into the file with this function. We pass the desired character to be written to this function.

...
	Set Variable [ $r ; Value: MBS("BinaryFile.WriteByte"; $ref; 13) ] 
	Set Variable [ $r ; Value: MBS("BinaryFile.WriteHex"; $ref; $Param) ] 
...

In addition to writing text to a file, you can also write the content of a container to a file. To do this, use the BinaryFile.WriteContainer function. In the parameters, enter the reference to the file and the container of which the content is supposed to be written to the file.

Set Variable [ $Param ; Value: Get(ScriptParameter) ] 
Set Variable [ $Path ; Value: MBS("Path.AddPathComponent"; MBS("Folders.UserDesktop"); "MBS_Container.png") ] 
Set Variable [ $ref ; Value: MBS( "BinaryFile.Create"; $Path ) ] 
Set Variable [ $r ; Value: MBS("BinaryFile.WriteContainer"; $ref; DoorThree::Container) ] 
Set Variable [ $r ; Value: MBS( "BinaryFile.Close"; $ref ) ] 

Now, of course, we don't just want to write data to a file, we also want to be able to read it. We have the "BinaryFile.ReadText" function for this purpose. This reads out as many letters as we specify in the parameters, starting from our current position. As we do not want to change the file in this case, we open it with the "BinaryFile.Open" function.

Set Variable [ $Path ; Value: MBS("Path.AddPathComponent"; MBS("Folders.UserDesktop"); "MBS_Binary_File.txt") ] 
Set Variable [ $ref ; Value: MBS("BinaryFile.Open"; $Path) ] 
Set Variable [ $r ; Value: MBS("BinaryFile.Seek"; $ref; DoorThree::Start) ] 
Set Field [ DoorThree::Text ; MBS( "BinaryFile.ReadText"; $ref; DoorThree::Length; "UTF-8" ) ] 
Set Variable [ $r ; Value: MBS("BinaryFile.Close"; $ref) ] 

In our example, you have the option of defining the start position and the readout length in two fields. We can change the current position with the BinaryFile.Seek function. If you want to determine what the current position is, use the BinaryFile.Position function. If you want the length of the entire document, call BinaryFile.Length.

But here, too, we not only have the option of reading out normal text, but we can also read out hexadecimal values, for example. To do this, we use the BinaryFile.ReadHex function instead of the BinaryFile.ReadText function.

In the image you can see that the first two characters in this document are a 0 and a 3 which have been output in hexadecimal.

I hope you enjoyed this excursion into the world of binary files and I'll see you again tomorrow.