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. These messages may be intercepted by the user program by the aid of the command MSG, or by the message handling system implemented in 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

Here, itemtype and itemname are the type and the name of the sending item, whereas msgid and msgpar are the message ID and the optional message data.

For a full documentation of the messages sent by each kind of shell item, see the documentation of the respective item.

References to shell items

There are shell item references, i.e. entities that may be used to referring to to a shell item instance. This works even if the owner of the target item (the item the reference is referring to) is a different shell, making shell item references a convenient way of sharing data between shells (but beware synchronization issues - see below, and see the LOCK and UNLOCK functions). References may refer to table, file, and instance items.

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

This command creates the reference refName, which refers to the original item whose type is origType and whose name is origName. If the original item is owned by another shell, its shell ID origShell must be specified, too. It is the option letter /Z that causes the NEW command to create a reference instead of a new item.

• A reference has the same type, attributes, and data content as the original item, meaning that it may be used just 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 there are the functions LOCK and UNLOCK.
• The workspace object BSTXIni and the project object BDataSet use references in order to share the XML workspace file and the XML project file accessible for all running shells.
• Deletion of the target item (i.e., the item a reference is referring to) is deferred until the last reference to the respective item gets 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