File system functions

This chapter is dedicated to all file system related features, that is, functions that allows a script to access files on the host computer either for writing or reading of data. Please note for security reason, a script cannot read or write to/from any file: Only a file path that have been specified by the user in the GUI using file system GUI items can be accessed. For instance, to be able to access a file from a script, there must be one of those two GUI elements:

ScanaStudio.gui_add_file_save(id,...)
ScanaStudio.gui_add_file_load(id,...)

Please refer to the GUI functions chapter for more details about the usage of those two functions. It's worth reminding though that the id parameter of this function is what is needed to access the file set by the user, as it will be explained in details in this chapter. (This confirms that at no time, the scripts gets to know anything about the host's file system or the actual path to the file).

To access a file for reading, first, you need to add a GUI elements in a relevant GUI (like the signal builder GUI). Below is an example:

ScanaStudio.gui_add_file_load("my_file_id", "Select CSV file", "*.csv");

which should create a GUI element that looks like this:

Please note that the text string "my_file_id" must be a unique ID in your script's GUI, and is used to open a file.

ScanaStudio.file_system_open("file_id","mode");

Description: This function open a file before being able to read or write to it.

Parameters:

• "file_id": the unique text string ID of the GUI elements used to define the file path.
• "mode": a single character text string that defines the access mode, according the the table below

Mode	Description
"r"	Read only
"w"	Write only (Deletes existing file content before writing)
"a"	Append (Preserves existing file content)

Return value: In case of error (unable to open the file) this function returns -1. otherwise, this function returns the file handle that can later be used for writing and reading.

Context: Global context

ScanaStudio.file_system_close(file_handle)

Description: This function is used to close a file.

Parameters:

• file_handle: The handle that was returned by the function ScanaStudio.file_system_open().

Return value: None.

Context: Global context

ScanaStudio.file_system_read_binary(file_handle)

Description: This function read the content of a file and return the content in binary format

Parameters:

• file_handle: The handle that was returned by the function ScanaStudio.file_system_open().

Return value: Returns an array of integers, each integer represent a byte the file.

Context: Global context

ScanaStudio.file_system_read_text(file_handle,"encoding")

Description: This function is used to read the content of a file in text format.

Parameters:

• file_handle: The handle that was returned by the function ScanaStudio.file_system_open().
• "encoding": A text string that defines the encoding used to read the file in text format, e.g. "UTF-16". The full list of supported formats is:
  • Big5
  • Big5-HKSCS
  • CP949
  • EUC-JP
  • EUC-KR
  • GB18030
  • HP-ROMAN8
  • IBM 850
  • IBM 866
  • IBM 874
  • ISO 2022-JP
  • ISO 8859-1 to 10
  • ISO 8859-13 to 16
  • Iscii-Bng, Dev, Gjr, Knd, Mlm, Ori, Pnj, Tlg, and Tml
  • KOI8-R
  • KOI8-U
  • Macintosh
  • Shift-JIS
  • TIS-620
  • TSCII
  • UTF-8
  • UTF-16
  • UTF-16BE
  • UTF-16LE
  • UTF-32
  • UTF-32BE
  • UTF-32LE
  • Windows-1250 to 1258

Return value: Returns a text string containing the content of the file

Context: Global context

ScanaStudio.file_system_write_binary(file_handle,data_array)

Description: This function writes binary data to a file (i.e. an array of bytes)

Parameters:

• file_handle: the handle that was returned by the function ScanaStudio.file_system_open().
• data_array: An array containing the bytes that should be written to the file.

Return value: None.

Context: Global context

ScanaStudio.file_system_write_text(file_handle, "text", "encoding")

Description: This function writes text to a file.

Parameters:

• file_handle: the handle that was returned by the function ScanaStudio.file_system_open().
• "text": the text to be written to the file
• "encoding": A text string that defines the encoding used to write to the file in text format, e.g. "UTF-16". The full list of supported formats is:
  • Big5
  • Big5-HKSCS
  • CP949
  • EUC-JP
  • EUC-KR
  • GB18030
  • HP-ROMAN8
  • IBM 850
  • IBM 866
  • IBM 874
  • ISO 2022-JP
  • ISO 8859-1 to 10
  • ISO 8859-13 to 16
  • Iscii-Bng, Dev, Gjr, Knd, Mlm, Ori, Pnj, Tlg, and Tml
  • KOI8-R
  • KOI8-U
  • Macintosh
  • Shift-JIS
  • TIS-620
  • TSCII
  • UTF-8
  • UTF-16
  • UTF-16BE
  • UTF-16LE
  • UTF-32
  • UTF-32BE
  • UTF-32LE
  • Windows-1250 to 1258

Return value: Returns

Context: Global context

Full example

A good example that demonstrates the file system features is the CSV import script, which takes a CSV file containing some samples, and builds logic signals from those samples. Those samples can be used to generate signals using a compatible signal generator (like the SQ series logic analyzer devices). Below is simplified version of the script:

var ENCODING = "UTF-8";

//Signal builder GUI
function on_draw_gui_signal_builder()
{
  ScanaStudio.gui_add_file_load("csv_file","Select CSV file","*.csv");
  ScanaStudio.gui_add_text_input("sep","Column separator",";");
  ScanaStudio.gui_add_new_tab("CSV Mapping",false);
    var ch;
    for (ch = 0; ch < ScanaStudio.get_device_channels_count(); ch++)
    {
      ScanaStudio.gui_add_combo_box("col_ch"+ch,"CH " + (ch+1).toString());
      ScanaStudio.gui_add_item_to_combo_box("Do not import",false);
      for (col = 0; col <= ScanaStudio.get_device_channels_count(); col++)
      {
        ScanaStudio.gui_add_item_to_combo_box("Column "+(col).toString(), ((col == (ch+1))?true:false));
      }
    }
  ScanaStudio.gui_end_tab();
}


//Function called to build siganls (to be generate by capable device)
function on_build_signals()
{
  //Use the function below to get the number of samples to be built
  var samples_to_build = ScanaStudio.builder_get_maximum_samples_count();
  var sample_rate = ScanaStudio.builder_get_sample_rate();
  var max_time = samples_to_build / sample_rate;
  var file = ScanaStudio.file_system_open("csv_file","r");
  if (file < 0) //Is the file successfully opened?
  {
    return;
  }
  var separator = ScanaStudio.gui_get_value("sep");
  var data = ScanaStudio.file_system_read_text(file,ENCODING);;
  var lines = data.match(/[^\r\n]+/g);
  ScanaStudio.file_system_close(file);
  var ch_map = [];
  var ch;
  for (ch = 0; ch < ScanaStudio.get_device_channels_count(); ch++)
  {
    ch_map.push(ScanaStudio.gui_get_value("col_ch"+ch)-1);
  }
  var samples_acc = 0;
  var i = 0;
  for (i=0; i < lines.length; i++)
  {
    var cols = lines[i].split(separator);
    var new_line = "";
    //process one line:
    samples_acc += 1;
    if (samples_acc > samples_to_build)
    {
      break;
    }
    for (ch = 0; ch < ScanaStudio.get_device_channels_count(); ch++)
    {
      if (ch_map[ch] != -1)
      {
        sample_val = parseInt(cols[ch_map[ch]]);
        ScanaStudio.builder_add_samples(ch,sample_val,1);
      }
    }
  }
}