<< Click To Display Table Of Contents >> You Are Here:  MADRIX Script (Introduction) > Basics > Reading From External Files

Asynchronous File Reading

The function

int ReadAsync(string file, string txt, int encoding)
 

reads the content from a file with a certain encoding as text into the string txt. The file is opened and closed automatically. There is no "open" function like in other programming languages. The parameter file may contain a filename of a local file, like "C:/config.txt". In addition, the HTTP protocol is supported. That means it is possible to retrieve data from a web server. For example: "https://www.madrix.com". The following examples would read some content from different files.

string txt;
ReadAsync("C:/config.txt", txt);
ReadAsync("http://www.testserver.de/testfile.txt", txt);
 

Here is an example which reads some numbers from a file (to be found at C:/temp/src.txt)  and renders a curve on the matrix.

float g_pos[] = {0.8, 0.5};
string file = "C:/temp/src.txt";
string txt;
 
void InitEffect()
{
 SetAsync(true);
 SetBpm(300);
}
 
void RenderEffect()
{
 ShiftVectorMatrix(0.0, 0.0, 1.0, 1.0, SHIFT_LEFT, 0.1);
 ReadAsync(file, txt);
 float f = (float)txt;
 
 DrawVectorLine(WHITE, g_pos[0], g_pos[1], g_pos[0] + 0.1, f);
 g_pos[1] = f;
}
 
 
 

Let's take for example a program which writes the temperature from an external sensor connected to USB to the file and MADRIX draws the curve onto a matrix. As described later on, it would also be possible to write a macro for the SCE Ticker effect to display the values as text.

The function can return several codes/status updates for different scenarios:

In addition, ReadAsync can take a third parameter to specify the file encoding. If the parameter is omitted, an automatic detection is applied. The following values are valid:

UTF (Unicode Transformation Format) encoded files are recommended in order to handle special characters (e.g. from Asian languages) correctly. The actual encoding of a text file can be figured out or even changed by using an appropriate text editor, for example.

 

Example

For testing purposes there are two scripts which deliver random numbers at the end of this chapter. Or you could play with this test set-up for SCE Ticker / Scrolling Text:

@scriptname="ReadAsync Test Set-Up";
@author="";
@version="";
@description="";
 
string file = "C:/temp/src.txt"; //location of the source text file
string txt;
int interval = 600000; //interval = 10 minutes
 
void InitEffect()
{
         SetReadAsyncInterval(file, interval);
}
 
void PreRenderEffect()
{
    switch(ReadAsync(file, txt))
         {
         case FILE_OK : WriteText("FILE_OK"); SetText(txt); break; // txt is displayed
         case FILE_NOT_EXIST : WriteText("FILE_NOT_EXIST");break;
         case FILE_ERROR : WriteText("FILE_ERROR");break;
         case NETWORK_ERROR : WriteText("NETWORK_ERROR");break;
         case INVALID_HOST : WriteText("INVALID_HOST");break;
         default : break;
         }
}
 
void PostRenderEffect()
{
 
}
 
 
 

Detailed Information About 'ReadAsync'

As you can see, it is neither necessary to explicitly open the file nor to close it. During the first call of the function, the specified file is opened. File reading happens asynchronously, which means that the function immediately returns a value but does not wait for the physical reading. Internally, the file will be read and the content is stored in a buffer. The function itself just reads from this buffer. This also means that after the first call of the function, it is more likely that no text will be read. There is a big advantage of this behavior. It is not necessary for the script to wait for potentially long reading times, which may occur, especially if you read content from internet servers.

 

Setting The Reading Interval

The file will be continuously read in the background. ReadAsync always receives the result of the last reading process. It is possible to control the interval of the reading process. The default value is 1000 ms which means that an opened file will be read one time each second. The function

int SetReadAsyncInterval(string file, int interval)
 
 

sets the reading interval for a certain file. The int interval is given in milliseconds. The minimum reading interval is 10 ms. Imagine your sensor writes data every 500 ms. Therefore, you can set the interval to 500 ms in order to let MADRIX instantly show the values. Or you can set it higher, e.g. to 5000 ms (5 seconds), in order to save resources.

If the file in question has not been opened yet, e.g. by a call of ReadAsync, the file will be opened to begin internal reading. It makes sense to set the reading interval within the InitEffect function in order to have the content of the file read before the first call of ReadAsync, which is perhaps located in RenderEffect.

 

Tips For Using Files In MADRIX Script

Overview

Up to now, MADRIX Script is not designed to operate on strings. There aren't many proper functions available that may help you to parse strings or even manipulate them. Furthermore, such functionality requires a lot of computing time, which is not necessarily available within MADRIX Script. It may be better to have external tools (e.g. python scripts, PHP, or Visual basic scripts) which prepare files for MADRIX Script in order to have faster scripts.

Another interesting possibility is to have interactive scripts. Imagine a small application which retrieves input from a user and writes it to a file. A script may read the file and react to the input.

The following scripts are external scripts which may be used to test the script above or to play around with the reading functionality of MADRIX Script. Both scripts deliver random numbers using a local file or via HTTP request.

 

A Python Script To Create Random Numbers

The following script creates random values between 0 and 1 and writes them to the file "C:/temp/src.txt". In order to use a different file, set the file variable in the third line of the script to a different one. Please do not forget to change the script above to read the same file. Each second one value is written. In order to test HTTP functionality, this script may also run on a web server and you can request the written file from the web server.

import time
import random
 
file = "C:/temp/src.txt"
 
while True:
 f = random.random()
 s = "%.2f" % f
 try:
         wf = open(file, "w")
         wf.write(s)
         wf.close()
 except:
         print "Can't open file"
 
 print "Wert %.2f" %f
 
 time.sleep(1)
 
 
 

A PHP Script To Create Random Numbers

The following PHP script delivers a random number between 0 and 1 each time it is called.

<?php
 echo (rand() / getrandmax()) . "\n";
?>