BScript - The runtime environment of Scripts

The STx application implements an environment for the development, debugging and execution of user scripts. It is used by the Script Controller and the Console to load a script file and to test, debug or run a macro defined in this file. When the execution of the macro is finished, the script file is unloaded and the runtime environment is deleted.

The term script is a synonym for an application implemented using one or more macros, classes and SPUs. Scripts can be used to implement ...

• applying standard STx signal processing to multiple signals
• signal processing applications (like the STx Spectrogram & Parameters Viewer)
• complex database operations on the opened STx project (e.g. using macro DataSetCmd and classes BDataSet and BSTXIni
• a solution for the Towers of Hanoi problem
• in fact, everything you see in STx can be programmed in the scripting language
• in fact, everything you see in STx is programmed in the scripting language

Running a Script

To run a script use the Script Controller dialog to select/create a file, select the macro and supply arguments or the [[User_Guide/STX_Console|Console command STS file::macro arguments /Run. In both cases a new instance of the application BScript is started and the script file name, the macro name and the supplied arguments are passed to this instance. Before the execution of the script begins, following initialization steps are performed.

• The specified script file is loaded and it is tested, if the specified macro (called scriptmain) is defined in the loaded file.
• All source files defined in the section Libraries of the script file are loaded.
• The script environment is initialzed: Some informations about the script are stored in the shell variable space and an instance of the class BScript named CON is created. The member functions of this instance can be used show/hide the console window, to write informations to the console window and for some other purposes.
• The macro scriptmain is started.
  • In the debug mode, the debugger window is shown and the break mode is entered before the execution of scriptmain begins.

The user application implemented by scriptmain is active until this macro is finished, than the control is returned to the BScript application, which performs some cleanup steps:

• All shell items (tables, files, instances, spu's, ...) are deleted in a save way. For instances the destructor member function is called.
• If the variable AutoCloseSF equals 1: All soundfiles opened by the script are closed automatically.
  • Note: To manage (create, open, close and select) soundfiles a script should always use the macro BSF instead of the commands LOAD and UNLOAD.

Script Environment

All variables and items described here are assigned or created, before the script main macro is called.

These variables must not be changed:

ScriptDirectory

the directory of the script file

ScriptFilePath

the full path of the script file

ScriptFileName

the name of the script file; only the name without directory and filetype

ScriptMainName

the name of the script main macro

ScriptRevision

the STx revision number used to create the script file; this value is undefined, if the script file was not created with the New function of the Script Controller or the line containing this information was changed or removed

STXRevision

the actual STx revision number of the running program

These variables can/should be set by the user script before the script main macro exits:

AutoCloseSF

set this variable 1 if all sound files opened during the script execution should be closed automatically and to 0 if not (default: 0)

ShowLogOnExit

set this variable 1 if the console window should be shown when the script ends, 0 otherwise (default: 1). If the console window shown, the user must close it manually.

Instance items:

CON - instance of class BScript

this instance implements the console window and a set of useful utility functions.

$BSTXIni - instance of class BSTXIni

an interface object to access the workspace data; the name of the instance is stored in the shell variable BSTXIni

$BDataSet - instance of class BDataSet

an interface object to access the project data; the name of the instance is stored in the shell variable BDataSet

• The items listed above are deleted automatically when the script application exits.
• Both instances $BSTXIni and $BDataSet are accessing global data objects which are (or may be) used by other currently running shells. To gurantee a save access to workspace and project data, the data must be locked to the script (shell) before read and/or write operations.

The following example shows a save way to use the project data. The functions used here are also available for the workspace interface instance.

...
if '$($bdataset attach)' == '' then // lock the project-data
    // LOCK failed! Its not possible to access the project-data now!
    conlog /error 'lock project-data failed!' // write error message to the console window
    // do something else but do not use the project-data!
    ...
 else
    // LOCK succeeded! Now its save to access project-data!
    // use the $BDataSet instance members to access project-data
    ...
    $bdataset detach // unlock project-data, 
                     // this is necessary to make the project-data available to other shells
 end
 ...

Fuctions Implemented by BScript and CON

The functions described below are available in the script runtime environment only. They implement some control and output functions for the Console window and some other useful functions.

Note: All functions described here, except the special functions are also available in the command line of the Console.

Special Functions

The functions listed below are used to prepare and unprepare the script runtime environment and there should be no necessity to use them in your script:

BSCRIPT LOAD filepath [ ; mainmacro ]
BSCRIPT UNLOAD
BSCRIPT VERSIONCHECK filepath [ ; showmsgbox ]

A description of these functions is only available in the source file BScript.stx

Setup Functions

BSCRIPT GETSETUPPATH [subset; empty]
CON getSetupPath [set; empty]

Returns the internal reference (iref) of the workspace set containing the script setup elements. This function can be used to save or load script parameters. Arguments:

subset: The relative reference to a sub-set of the standard setup-set (see example)

empty: If this argument is set to yes or 1 the selected set or sub-set is emptied (this means all child elements and sets are deleted), otherwise nothing is deleted. This option can be used (carefully) to delete script settings.

Example 1: load current/default script settings

...
// lock the workspace before you load the current settings from the workspace
if '$($bstxini attach)' != '' then
    // lock okay -> try to load settings from standard script-settings path
    #currSetup := $bstxini loadsetelement 'Table; $ScriptMainName; $(con getsetuppath)'
    // don't forget to unlock the workspace
    $bstxini detach
end
// check if current settings are loaded
if '$#currSetup[?]' != table then
    // load default settings from the section [DefaultSettings] of the script source file
    // if current settings are not available
    #currSetup := sectionfile '$ScriptFilePath ; Load * DefaultSettings'
end
// Th current/default settings are now stored in the simple table $#currSetup and can
// be accessed with the READTAB command or another table access method.
...

Example 2: save current script settings

...
// lock the workspace before you save the current settings into the workspace
if '$($bstxini attach)' != '' then
    // lock okay -> save settings to standard script-settings path
    $bstxini SaveSetupElement '$#currSetup; 0 ; Table; $ScriptMainName; $(con getsetuppath)'
    $bstxini detach
end
...

Console Window Functions

CON logOpen

Open the Console window.

CON setTitle [title]

Set the caption of the Console window to title. If no caption is specified, the default caption (ScriptFilePath and ScriptMainName) is used.

CON setWindow x y w h

Set the position and size of the Console window.

x,y: The upper left corner position of the window in pixels

w,h: The width and height of the window in pixels.

For more details see macro SetWindowPos.

CON log [textline]
CON logText [textline]

Write one textline to the Console window.

CON logExt [mode=overwrite ; text]

Extended Console window log-function. The argument mode can be set to overwrite, to overwrite the last line with text, or to append, to append text to the last line. This function is e.g. useful to show the progress of a (longer lasting) script process.

CON eLog level ; [result] ; textline

Write the error|exit message textline to the Console window and execute the return command EXIT level SET 'result'. This function is a simple way, to show a text message when returning from a macro.

Example:

con elog 2; 1; the return value of "$#mac" is "1" // show the message and return 1 to the caller of $#mac

CON cls
CON logClear

Clear the Console window.

CON logClose

Close the Console window.

File I/O Functions

CON loadData textmode; filepath [; colsep=blank; header=0; skiplines=0; loadlines=*]

This function loads numerical data tables or string data tables from the specified text file filepath. The result of the function is a parameter table item or an extended table containing the loaded data or an empty string if the function failes.

textmode:

• text for numerical text files; use textcontinuation if the text file may contain continuation lines
• string for normal text files; stringcontinuation if the text file may contain continuation lines

filepath: the path of the file containing the data to be loaded

colsep: the column seperator: blank, tab, comma or semicolon

header: If set to yes (or 1), the first line of the file is interpreted as header-line, and the value of each header column is used as name for the corresponding table field. Otherwise, no header-line is assumed and the table fields are not named.

skiplines: number of file lines to be skipped (not stored in the table)

loadlines: number of file lines to be loaded; use the character * (=default) to load the whole file

CON loadData binary; filepath [; combine=0; sec1 [mv1]; ...]

Load the specified sections (sec1, ..) of the binary file filepath. If combine is set to yes (or 1) the loaded data are combined into one parameter table, otherwise for each section one parameter table is used. The result of this function is a blank seperated list of parameter table items (combine=0), one parametr table item (combine=1 or only one section was specified) or an empty sting if the function failes. The missing value (mv1, ..) parameter, which can be specified for each section separately, is only necessary if multiple sections are combined into one table. In this the missing value parameters are passed to the function [[Programmer_Guide/Command_Reference/EVAL/interp|eval interp()], which is used to allign all data to the same length.

CON saveData text|ascii; table; filepath [; header=0; colsep=blank; decsym=DOT; floatfmt=%g;  intfmt=%g]

Save the parameter or extended table table into the text file filepath.

header: If set to yes (or 1), field names of the table are stored in the first line of the text file. Otherwise, no header-line is stored in the file.

colsep: the column seperator: blank, tab, comma or semicolon

decsym: the decimal symbol to be used for floating point numbers: dot or comma

floatfmt: the format of floating point numbers; any valid float/double C-format string (e.g.: %g, %.2f, ...)

intfmt: the format of integer numbers; any valid float/double C-format string (e.g.: %.0f, ...)

CON saveData text|ascii; table; CLIPBOARD [; header=0; colsep=blank; decsym=DOT; floatfmt=%g;  intfmt=%g; fieldlist]

Copy the parameter or extended table table to the clipboard. All arguments have the same meaning as for the file output. In the extra argument fieldlist a blank seperated list of table field-ids which should be copied ca be specified. If this argument is not supplied, all fields are copied.

For example, the command con savedata text; datatable; clipboard; yes; semicolon; comma can be used to copy the datatable to the clipboard, from where it can be pasted into a spreadsheet application.

CON saveDataDlg table [; trans=no; title=Save Table; colsep=blank; decsym=dot; header=no; floatfmt=%g; intfmt=%d]

This function displays a dialog where the arguments of the saveData functions can be entered.