Programmer Guide/Shell Items

STx implements a number of different objects which can be used to manipulate files, graphics, dialogs, etc. These objects are called shell items.

A shell item is an object designed to be good at a specific range of tasks. There is, for example, a file item which allowing to read, write, copy, rename, and list files: and there is a dialog item, allowing to design, and display dialog boxes, and to react to user input.

Shell items are implemented in C++, making them very performant. The STx programmer may interact with shell items

• by executing commands they provide;
• by reading, or writing, their attributes; and
• by receiving their messages

The commands, attributes, and messages each kind of shell item provides are documented in the chapter on the respective shell item (see the list below).

Every instance of a shell item has a unique name, either chosen by the STx programmer, if he and/or she so wishes, automatically assigned by STx itself. This item name is used as a reference (a kind of pointer) to the item.

Currently STx supports the following shell items

DCOM	A shell item for working with Distributed Component Object Model (DCOM) interfaces (e.g. with the DCOM interface for the statistics package R).
DDECONV	A shell item for initiating a Dynamic Data Exchange (DDE) conversation with a DDE server and exchanging data between the server and the item (e.g. to exchange data with microsoft EXCEL or WORD).
MENU (dialog)	A shell item for designing and displaying dialog boxes and processing user input. A dialog is always a part of a display item. Note:For historical reasons the type id used for dialog items is MENU.
DISPLAY	A shell item for displaying one or more graph items and optionally a dialog. Each window displayed by STx is a display item.
FILE	A shell item for accessing files on disk and manipulating files in memory. It can be used to list files, to apply system commands (like copy, rename, move, ...) to files or to access data of different file formats (plane text, section files, xml, binary).
GRAPH	A shell item for displaying graphical representations of data, e.g. spectrograms. A graph is always a part of a display item.
INSTANCE	A shell item instance of an STx class. The instance items are used to implemented object oriented script programming.
IP	A shell item for sending and receiving data via the TCP/IP protocol. The ip item supports both the TCP and the UDP protocols and can act as server or client. The ip item can transfer data using the Open Sound Control protocol (OSC), an STx protocol, or as ASCII or UNICODE strings.
SPU	A shell item for controlling Signal Processing Units (SPUs). An SPU is a circuit connecting one or more Signal Processing Atom (see the SPU Reference for details) together.
TABLE	A shell item for storing data in columns and rows with sorting and find functions. The table items can be used to implement simple database functions and for numerical operations.
VALUE	A shell item for exchanging data between SPU and graph items and macros. They can also be used as timers and for numerical operations.
WAVE	A shell item to access stored signal, playback and record wave soundfiles as well as create and manipulate sound sequences. It is also possible to use wave items in numerical operations (e.g. to read source signals are write output signals of a dsp algorithm).
Reference	A shell item reference is not an item in itself, but rather a reference to an existing shell item. It is mainly used to share shell items between shells (for data exchange reasons). E.g. the dataset file item and the config file item are file items which are created by the master-shell of STx but shared between all application shells.

Note: Shell items of types TABLE, VALUE, FILE, and WAVE also may be directly used in numerical expressions (see the EVAL command).

Creating and deleting items, executing item functions

The commands NEW, SET and DELETE are used for dealing with shell items.

NEW itemtype itemname …

create and initialize a shell item. On success, the command returns the name of the created shell item (identical to the itemname argument, if other than *). If there is an error, the command returns the string *. If the argument itemname is set to *, the item will be assigned a unique name (e.g. T#1, T#2, … for tables).

SET itemname function ...

perform an action on a shell item. In most cases you may omit the string SET altogether, meaning that the command SET itemname function ... is equivalent to itemname function ....

DELETE itemname ...

delete shell item(s).

Note that:

• Certain kinds of items may not be deleted at will. For example, an SPU must not be deleted before it has reached the EXIT state.
• The deletion of an item owned by another item is deferred until the owner itself has been deleted. For example, graphs are deleted when the owning display is deleted.

NEW

see NEW itemtype itemname …

// create a simple table item
// simple tables can be used to store strings (e.g. filenames)

#table := new table *

// create a parameter table item with 20 numerical fields
#data := new table * * num:x:20

// open a textfile for reading; the variable #path contains the path of the file
#textfile := new file * '$#path' /read /text

SET

see SET itemname function ...

// append 2 lines to a simple table
set $#table * 'first entry'  // explicit SET command
$#table * 'second entry'     // implicit SET command

// copy the content of a table to the clipboard
$#table clipboard

// load a whole file into a table
$#textfile load $#table

DELETE

see DELETE itemname ...

// delete an item whose name is stored in a variable
// (this is a common use case)
delete $#table

// delete an item whose name is stored in a variable,
// *and* clear the respective variable
// (today, this is the most common use case)
delete /Var #table

// delete an item by its name
// (this is a slightly unusual use case)
delete T#8

Item Attributes

All shell items have attributes which may be accessed with the following syntax:

itemName[!attributeName]	Here, the item is referred to by its item name directly. This is, actually, the less common use case - normally, STx programmers store their item names in an STx variable.
$varname[!attributeName]	if the item name is stored in a variable, which is the most common use case.

For example, you may retrieve the sampling rate of a wave item as follows:

#srate := $#wave[!srate]

If the attribute being requested does not exist, then an empty string is returned. Please see the documentation of each shell item type for a list of the supported attributes.

Some items have attributes with more than one value. Such attribute values are addressed by comma separated IDs.

// get item name, row and column of all graphs of a display
for #i := 0 to $#i < $#display[!graphs] step #i := int $#i+1
    readstr '$#display[!graph,$#i]' #gname #grow #gcol
    conlog 'graph $#gname is displayed in column $#gcol of row $#grow'
end

In some cases it may be necessary to use an item attribute in a string. To make sure that the item name is correctly terminated, the character ~ (tilde) should be used:

#table := new table MyTable
MyTable * 'just testing'

// The following statement will NOT work, actually trying to
// access the non-existent table textMyTable
writelog 'textMyTable[0]'  // → will not work

// The following statement will work, printing the string
// "testjust testing"  (no intervening blank!)
writelog 'text~MyTable[0]' // → okay

// The following statement will work, too, but there will
// be a blank between "test" and "just": "test just testing"
writelog 'text MyTable[0]' // → okay

Item Messages

Some items uses messages to send informations to the shell. The messages can be processed by the command MSG or by the message handling system implemented via the library macros SETMSGHANDLER (install/remove message handler for an item) and GETMESSAGE (message loop, get and process messages).

The message sent to the shell contains information about the sending item and the message data in the following format:

itemtype itemname msgid msgpar

itemtype, itemname

the type and the name of the sending item

msgid, msgpar

the message id and the optional message data

Please see the individual shell item documentation for a list of messages.

References to shell items

A shell item reference can be used to refer to to an already existing item, even if it is owned by another shell. This feature makes it possible to share shell items between shells. Creating references is only possible for table, file and instance items.

refName := NEW origType * /Z origName [ origShell ]

This command creates the reference refName, which refers to the original item with type origType and name origName. If the original item is owned by another shell, also the id origShell of this shell must be specified. The option /Z causes the NEW command to create a reference and not a new item.

• A reference has the same type, attributes and data content as the original item, this means, it can be used like the original.
• If the reference and the original item are owned by different shells, the access to the items must be synchronized. For this purpose functions to LOCK and UNLOCK an item are implemented.
• The workspace object BSTXIni and the project object BDataSet are using references, to make the content of the xml-file items containing the workspace and project data available to all running shells.
• The item itself (e.g. the table) is deleted, when all references (including the original item) are deleted.

Protected shell items

In some situations it may be useful to protect shell items from (accidental) deletion. E.g. the script console uses this feature to protect all required items. STx implements to item protection methods.

Single Item Protection

• protects only one item

protecedItem := NEW itemtype itemname ... /u

create a protected item

DELETE protectedItem /u

delete a protected item

Global Item Protection

• uses a master-item to enable / disable global protection
• protects all items created before the master-item
• items created after the master are not proteced
• only one master-item is possible
• the global protection is enabled when the master item is created, and disabled when it is deleted

masterItem := NEW itemtype itemname ... /U

create the master-item and enable global protection

DELETE masterItem /u

delete the master-item and disable global protection

The options used for item protection control (/U and /u) are case sensitive!

Temporary shell items

A temporary shell item (also called local shell item) is a shell item, which is automatically deleted, when the macro which creates the shell item is leaved.

A temporary shell item is created ...

• by the command NEW, if the option /Garbage is specified

#table := new table * /g

• by the EVAL command, if the return value is a vector or a matrix and the result is not assigned to an item. The returned data are stored in a automatically created temporary parameter table.

#matrix := eval init(100,100,0)

• if a row or column of a value item or table item is extracted and not assigned to an item. The extracted data are stored in a automatically created temporary parameter table.

#rowVector := $#table[10,*]

It is possible to return temporary shell items from a macro. In this case the name of the temporary shell item must be the only return value of the macro and the return value must be assigned directly to a variable of the caller.

[macro testTempItem]
// create vector #1; the temporary vector returned by makeZeroVector is 
// converted (during the assignment) to a temporary vector of testTempItem
#vector1 := makeZeroVector 20        
showitem $#vector1      // display the content of table $#vector1
// create vector #2; the temporary vector returned by makeZeroVector is not 
// assigned and therefore deleted; the name of the (now invalid) item is 
// stored in the variable RESULT 
makeZeroVector 10                    
readvar result #vector2 // copy the returned item name to a local variable
showitem $#vector2      // display content of table $#vector2 failes, 
                        // because the string stored in #vector2 is not the name of an item
// exit (and delete temporary #vector1)
exit                                 

[macro makeZeroVector #size=100]
// create a vector with #size zeros; the result of the eval command is a 
// temporary numerical table item with 1 column and $#size rows
#vector := eval fill($#size, 0, 0)   
// return the vector (temporary table item) to the caller
exit 1 set $#vector