General functions

This chapter is dedicated to general purpose functions that are used for general tasks like:

• Script debugging
• Progress reporting (for slow script operations)

Script renaming

It may be of interest to rename an instance of a script to a more unique name. For example, a workspace may have several instances of the UART protocol decoder scripts, each one targeting a different channel. If they all keep their default name, that is: “UART”, then it’s impossible to know which decoder is for which channel. For that particular reason, a script renaming function is provided so that at any given moment, a script can rename itself to a more “unique” name.

If we keep the example of the multiple UART decoder scripts, one solution would be to call the script renaming function in the GUI evaluation function, which is the moment where we know exactly what channel is targeted by that script.

The different UART decoders could then be renamed:

• UART on CH1
• UART on CH2
• UART on CH3
• etc…

The script renaming function is presented below

ScanaStudio.set_script_instance_name(“script_name”)

Description: This function renames the instance of the script. This temporary name changing does not affect the hard coded name of the script which is defined via meta-information tags (see chapter 2).

Parameters:

• “script_name”: The new script of the name. This name will totally replace the script

Context: Global

Progress reporting

ScanaStudio.report_progress(progress_percentage)

This function provides the user with a progress indication for slow operations (like decoding a very big amount of logic signals). This function should be called periodically (as often as deemed necessary). Calling the report_progress() function multiple times with the same progress_percentage value will have no effect (only a progress_percentage value different that previous one will be considered). It is highly recommend to implement this function in your script, for each and every entry-point function.

Example:

function on_decode_signals(resume)
{
  for (int i = 0; i < total_samples_count; i++)
  {
    ScanaStudio.report_progress(i*100/total_samples_count);

    /*
    Your slow, time consuming decoding code goes here
    */
  }
}

Context : Global

Console messages

ScanaStudio.console_info_msg(“msg”,sample)

Description: This function prints the message msg in a console box in ScanaStudio. sample parameter is optional. If sample is defined, the console message will be displayed as hyperlink linked to the provided sample number. If the user clicks on that hyperlink, ScanaStudio’s waveform will center on that specific sample. This function is intended for debugging phase of a script, that being said, it may be used to display messages to the script’s end user if it does not fit elsewhere.

Example:

ScanaStudio.console_info_msg("A simple message");
ScanaStudio.console_info_msg("My variable =" + variable);
ScanaStudio.console_info_msg("A simple message linked to a sample", 50000);

Context : Global

ScanaStudio.console_warning_msg(“msg”,sample)

Description: This function is identical in operation to ScanaStudio.console_info_msg(). The only difference is the way messages will be presented to the user as a “warning messages”.

Context : Global

ScanaStudio.console_error_msg(“msg”,sample)

Description: This function is identical in operation to ScanaStudio.console_info_msg(). The only difference is the way messages will be presented to the user as an “error messages”.

Context : Global

Formatting

ScanaStudio.engineering_notation(number,digits)

Description: This function formats a number in engineering notation. For example, ScanaStudio.engineering_notation("1500",3) would return “1.50 k”

Parameters:

• number: The number to be formatted
• digits: The number of digits (Please note that the minimum allowed number of digits is 3).

Return value: Returns text containing formatted number along with engineering prefix.

Context: Global