Programmer Guide/Introduction

This chapter contains a general introduction to the structure of the STx programming and execution environment.

Application Environment

The application environment contains all the data structures and functionallities which are available to the whole application.

Loaded Source Files

All scripts, macros, classes and spu's must be loaded from the source file before they can be executed or instantiated. All loaded sources are available to the whole application.

See also: shell commands LOAD, UNLOAD and LIST

Open Soundfiles

All soundfiles which are opened to STx a stored in a global list and can be accessed by all shells. Before the content (signal or metadata) of a soundfile ca be accessed, it must be opened using the command LOAD SOUNDFILE.

See also: shell commands LOAD, UNLOAD and LIST; wave items

Active Shells

All running shells are registered in the application envrionment.

See also: shell commands SHELL, and LIST

Global Variables

The application environment contains a global variable space, which can be accessed from the whole application. All name prefix character @ is used to address the global variable space. The global variables are used for configuration purposes and should not be changed. The following table shows some of the most important global variables.

name	description
@WORK	The full pathname of the working directory
@ROOT	the full pathname of the STx installation directory
@TEMPDIR	The full pathname of the directory for temporary files
@DATASETFILE	The full pathname of the active project file
@MASTER	The id of the master shell
@OSVER	The operating system version
@PROFILE	The full pathname of the workspace file

Shell

A shell is the command interpreter and the envrionment executing the loaded code objects. It is created with the SHELL command and ends when the last macro running in the shell is finished (EXIT). All shell are registered in the application environment. A shell can exchange messages with other shells. If a shell is started via the command SHELL mainmacro {arguments}, the macro mainmacro takes control of the shell. If this macro is finished, the shell is also ended

Message Loop

A shell can receive and send messages. The messages are used to communicate with other shells, with the shell items owned by a shell and with the main window of the application. To access the message queue and process messages the command MSG or the library macros GETMESSAGE, DISPATCHMSG, MSGQUEUE, POSTMESSAGE and SETMSGHANDLER can be used.

Shell Items

A shell maintains a list of the owned [Programmer_Guide/Shell_Items|shell items]]. A shell item is owned by a shell if it was created in a macro or instance of a class executed by the shell. Shell items are managed by the commands NEW and DELETE.

• Normally a shell item is visible only inside a shell, but it is possible to share selected items between shells by using . This technique is used for the workspace and the project
• All shell items must be deleted before the shell is finished. If the shell executes a user script, using the BScript application, an application cleanup function is used to delete shell items which was created but not deleted by the script.

Shell items are connecting STx with the operation system and its peripherals.

• The GUI is implemented by the display-, the graph- and the dialog items.
• The file item can be used to create and access files of several formats, but also to test the existence of a file and to scan directories.
• tables implements simple database features but can also be used as numerical objects in expressions.
• The wave item addresses signals stored in soundfiles and/or virtual sequences of synthetic signals. The interface to the sound devices of system for playback and recording is also implemented via the wave items.
• Via the SPU items a programmable signal processing circuit subsystem is implemented. SPUs can be connected to graphs, value items and to other SPUs.
• The value item can be used as input for SPUs, as timer and as numerical object in expressions.
• DCOM and DDECONV items implements interfaces to other applications.
• ...

Shell Variables

The shell contains a variable space, which can be accessed from all macros and classes executed by the shell. All variables starting with a letter are stored in the shell variable space.

name	description	see also
SHELL	The id of the shell and of the parent shell (thisshell parentshell). This variable is used by some library macros to communicate with other shells.	POSTMESSAGE
BDATASET	The name of the project instance. This variable must be used to access the content of the current project file.	BDATASET
BSTXINI	The name of the workspace instance. This variable must be used to access the content of the current workspace file.	BSTXINI
APPNAME	The name of the application. Only valid if the shell implements a STx application and was started via the application management system.	APPMAIN
APPTITLE	The title of the application. Only valid if the shell implements a STx application and was started via the application management system.	APPMAIN
APPMODE	The run mode of the application. Only valid if the shell implements a STx application and was started via the application management system. >0: the application is running, message processing is activated <=0: the application is finished, message processing is deactivated	APPMAIN
PARENT	The name of the display used as parent window of the application.	CREATEMENU
RC	The completion code of the last shell command
EMSG	The text message corresponding to RC
CSF	The full path of the currently selected soundfile. If this variable is empty, no soundfile is selected.	LOAD SOUNDFILE
CSFH	The header parameters of the currently selected soundfile (samplingrate channels numberOfSamples samplingCode fileFormat accessMode)	LOAD SOUNDFILE

Macros

A macro is a collection of command lines which can be executed. Macros are used to implement an application, a script or a library function. The macro source code is defined in a source file which must be loaded before the macro can be executed.

During its execution the macro can access:

• all loaded files (macros, classes, spu's and soundfiles)
• the global variables (@variablename)
• all items of the shell executing the macro
• the shell variables
• the local variables of the macro (#variablename)

The local variable space of a macro is created when the execution of a macro starts and deleted at the end of the macro execution. The following table shows the special local variables.

name	description	see also
#ARGV, #ARGC	The macro argument string without parsing and the number of arguments passed to the macro. These variables are generated on macro start and used for read: argument passing style.	macro header, READVAR
#QARGV, #QARGC	The macro argument string with parsing information and the number of arguments passed to the macro. These variables are generated on macro start and used for arg: and argopt: argument passing style.	macro header, ARG, SHIFT,
#MAC	The name of the macro.
#READ	The result returned by the last READ command.
#MSG	The result returned by the last MSG command.
#NEW	The result returned by the last NEW command.

Normally shell items created in a macro remain existing when the macro is finished, but in some cases temporary shell items are created, which are automatically deletet at the end of the macro.

Classes, Instances

A class is a special type of macro which enables the programmer to use object-oriented programming techniques. There a two possibilities to execute classes.

• A class can be used like a macro if its name is used as command.

classname argumens

• The class can be passed to the NEW command to create an instance of the class.

NEW INSTANCE classname

A member function of an instance can be called by using the following syntax:

instanceItemName memberFunctionName {memberFunctionArguments}

A member function is a part of a class source code starting at the member function label and ending with an EXIT command.

During its execution the member function can access:

• all loaded files (macros, classes, spu's and soundfiles)
• the global variables (@variablename)
• all items of the shell executing the macro
• the shell variables
• the local variables of the member function (#variablename)
• the member variables of the instance (&variablename)

The local variable space of a member function exists only during the runtime of the member function. In addition to the special local variables as described for macros, the following variables are stored in the local variable space when a member function is called

name	description
#THIS	The name of the instance item. This variable is used by some library macros to communicate with other shells.
#THISMF	The name of the member function.

The member variable space of an instance has the same lifetime as the instance itself. This means it exists from the creation to the deletion of the instance item. No special member variables are defined.

The member variables can be accessed from outside the instance as follows:

• Assign a value to a member variable:

instance.variablename := value

instance.&variablename := value

• Retrieve a value of a member variable:

instance[!VARIABLE,variablename]

instance[!VARIABLE,&variablename]

• Parse a member variable:

READVAR instance.variablename targetvar1 ...

READVAR instance.&variablename targetvar1 ...

Note: The member variable prefix character & is assumed, if not specified, and is therefor optional.

If a member variable of an instance is bound to a control of a dialog (e.g. EDIT, COMBOBOX, ...) to syntax instance.variablename (with or without &) should be used, to ensure the dialog item can always access the variable.

Script Commands

A script is a collection of commands to be executed. There are different types of commands.

Build-In Commands

shellcommand argumentstring

shellcommand

a build-in command of the shell command interpreter

argstring

the arguments and options supplied to the command

The argstring of a shell command consists of arguments and options. An argument is seperated from each other by blanks or by quotes. If an argument contains whitespace characters (blank, tab, ...) it must be enclosed in quotes.

Examples:

arg1 arg2'arg3' arg4 'arg 5'

This argument string consists of five arguments with the values arg1, arg2, arg3, arg4 and arg 5.

'arg1 arg2 arg3'arg4'arg 5'

This argument string consists of three arguments with the values arg1 arg2 arg3, arg4 and and arg 5.

If a shell command supports options, they must be specified using the syntax /optionname (for switches) or /optionname=optionvalue. The option must start with the character / (slash) and not be inside a quoted part of argstring. Only the first character of optionname is significant. Normally the options are not case sensitive, but there are some exceptions from this rule (e.g.: the options /U and /u of the NEW command).

Example:

arg1 /a/b '/c=arg3' /d='arg4' /e=evalue

This argument string consists of the arguments arg1, /c=arg3, arg4 and the options a, b and e=evalue.

Note: If a parsing character (like / or ') or a special tag character (like $ or [) should be used as part of an argument, it can be escaped with the backquote (`).

Example:

`/oname `$vname iname`[aname`]

This argument string consists of the arguments /oname, $vname and iname[aname]. Without escaping the arguments would be: value of variable vname, attribute aname of shell item iname and the option o.

A build-in command has two return values: The completion code and the command result. *The completion code indicates if the command execution was successful or has failed. It consists of a numerical code, which is stored in the variable RC (0 = success), and the corresponing error description, stored in the variable EMSG (empty if RC=0).

• The command result is the value returned by the command. This value replaces the command statement and is used in (optional) assignments. For a lot of commands, the completion code is also used as command result.

Call Commands

A call command is a statement which is used to call a source code object implemented in a script. There a several possible call commands:

macroname argstring

Calls the macro macroname with the arguments argstring.

classname argstring

Calls the class classname with the arguments argstring. If a class is called like this, it is executed like a macro. This statement type is used to implement static functions of a class.

GOSUB subrlabel argstring

Calls the local subroutine subrlabel with the arguments argstring. The label subrlabel is the entry-point of the subroutine and must be a label of the macro containing the call statement.

institem memfun argstring

Calls the member function memfun of the instance institem with the arguments argstring. memfun must be a member function of the class of institem and must be visible to the caller.

memfun argstring

This call statement can only be used in a member function. It calls the member function memfun of the same instance.

The argument parsing rules are depending on the parsing-style used in the source code of the function.

ARG- or ARGS-style

Same rules as for build-in commands without options.

ARGOPT-style

Same rules as for build-in commands with options. For details read the chapter definition of macros and the description of the build-in command ARG.

READ-style

This is the older parsing method, but it is used by the most standard macros and classes. The argument string is passed to the function after command-line processing (parsing information is removed!) and the READVAR command is used to parse the arguments which are stored in the variable #ARGV. Macros using this method do often use the semi-colon (;) to seperate arguments.

Examples:

testmacro this is a 'test message'

The argument string stored in #ARGV is this is atest message

butil msgbox 'msg ; hallo'

This statement is a call to the standard library macro BUTIL and should display a message box with the text hallo. The call will not work, because the argument string msgboxmsg ; hallo is passed and the function msgboxmsg is not implemented. A valid statement format is: butil 'msgbox msg; hallo'.

A call command has only one return value: the function result. The value is generated by the EXIT command, which ends the execution of the called function. This value is stored in the variable RESULT and also used in (optional) assignments.

Control Commands

Normally the commands are executed in the order as they appear in the source file. The control commands, can be used to change this natural order of execution.

GOTO labname

Unconditional jump. Continue execution at the label labname.

IF condexpr condcmd

Conditional command execution. The command condcmd is executed if the condition condexpr is true.

IF-THEN-ELSE-END

Block IF. A block IF may consist of one or more THEN-clauses (one is required) and an ELSE-clause. The commands of the first THEN-clause where condexpr is true are executed. If no condition is true, the commands of the ELSE-clause (if any) are executed.

IF condexpr THEN
   ...
{ELSE IF condexpr THEN
   ...
}
{ELSE
   ...
}
END

WHILE condexpr

While loop. The commands in the loop are executed while the condition condexpr is true.

WHILE condexpr
   ...
END

FOR initcmd TO condexpr STEP stepcmd

For loop. The commands in the loop are executed while the condition condexpr is true. Before the loop is entered, the initcmd is executed. After each execution of the command block the stepcmd is executed. All parts of the command are optional.

FOR {initcmd} TO {condexpr} STEP {stepcmd}
   ...
END

FOREVER

Run forever. The execution of the commands block will never end. Only the EXIT and BREAK command can be used to leave the loop.

Inside a loop the commands CONTINUE and BREAK to start the next iteration or to leave the loop.

Examples:

// use a for-loop to sum the integers from 1 to #n
#nsum := 0
for #i := 0 to $#i < $#n step #i := int $#i+1
   #nsum := int #nsum + $#i
end

// type depending item processing
if $#item[?] == table then
    // process table item
else if $#item[?] == wave then
    // process value item
else
   butil msgbox msg ; no processing for items of type "$#item[?]" implemented
end 

// find all occurrences of a value in a table (version 1)
#pos := set '*'
while '$(#pos := find $#table $#pos keyfield'$#keyvalue')'
   // process table entry $#pos
end
// find all occurrences of a value in a table (version 2)
for #pos := set '*' to '$(#pos := find $#table $#pos keyfield'$#keyvalue')' step
   // process table entry $#pos
end

Conditional Expressions

All commands using conditions use the same syntax and evaluation rules. A condition consists of one or more comparisons which are joined with logical (binary) operators. Each comparison compares two values and can evaluate to true or false.

condition = comparison {loperator comparison {loperator ..}}

comparison

A comparison comprising two expressions separated by a comparison operator. There are two types of comparison supported - see below for comparison operators for details. Both types of comparison can be used within one condition.

loperator

A logical operator, which combines the results of two comparisons. Logical operators are evaluated strictly from left to right; bracketing is not possible; it is explicitly undefined if a part of an expression that is strictly not required for judging on the truth, or falshood, of the whole expression, gets evaluated, or not. So you should not use expressions with side-effects.

The logical operators supported by STx conditional commands are the following

AND	returns true if both comparison results are true
&&	the same as AND
OR	returns true if either of the comparison results are true
||	the same as OR

The general syntax for a comparison is as follows:

expression operator expression

expression

A numerical expression or a string.

operator

A comparison operator (see below).

Simple comparison

A simple comparison will be numerical if both arguments are numerical. Otherwise, a case-insensitive string comparison will be performed.

==	evaluates to true if both sides are equal.
!=	evaluates to true if sides are not equal
<	evaluates to true if the left hand side is less than the right hand side
>	evaluates to true if the left hand side is greater than the right hand side
<=	evaluates to true if the left hand side is less than or equal to the right hand side
>=	evaluates to true if the left hand side is greater than or equal to the right hand side Wildcard Pattern Matching The left side expression is called string and the right side expression is called mask. The mask can contain wildcard characters * (one or more characters) and ? (one character). Note that, instead of a string, the argument to a pattern matching comparison may also be an STx name, i.e. a string subject to the syntax restrictions for STx names. You can discern the full string comparison operators from the name comparison operators by there second character which is S for string comparison (e.g. !SI), and N for name comparison (e.g. !NI). string operator name operator description =SI =NI returning true if string matches mask, ignoring the case !SI !NI returning true if string does not match mask, ignoring the case =SR =SR returning true if string matches mask, respecting the case !SR !NR returning true if string does not match mask, respecting the case POSIX regular expression pattern matching The left side expression is called string and the right side expression is called mask. The mask is a POSIX regual expression. string operator name operator description =RSI =RNI returns true if the string matches the regular expression, ignoring case !RSI !RNI returns true if string does not match the regular expression, ignoring the case =RSR =RNR returns true if the string matches the regular expression, respecting case !RSR !RNR returns true if the string does not match the regular expression, respecting the case Regular expressions make heavy use of characters that have a special meaning for STx. In order to use such characters, you need to escape them with the STx escape character, "`" (back-tick). The STx regular expressions are implemented using the TRE library.