Programmer Guide/Shell Items

Shell Items
DCOM	DDECONV	DIALOG|MENU	DISPLAY	FILE	GRAPH	INSTANCE	IP	SPU	TABLE	VALUE	WAVE	Shell Item Reference

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 is really good in reading, writing, copying, renaming, and listing 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, or 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 (in fairly alphabetic order):

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, a spreadsheet application popular among Windows users, or Word, a kind of text editor).
DIALOG|MENU	A shell item for designing and displaying dialog boxes and processing user input. A dialog is always a part of a display item. Note: It is a bit misleading that the dialog item may also be called a MENU item. This has historical reasons, and is retained for backward compatibility (as of STx 4.3.
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, plain 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 Transmission Control Protocol (TCP) and the User Datagram Protocol (UDP). It 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 (American Standard Code for Information Interchange) or UNICODE strings.
SPU	A shell item for controlling Signal Processing Units (SPUs). An SPU is a circuit connecting one or more Signal Processing Atoms (see the SPU Reference for details).
TABLE	A shell item for storing data in columns and rows and for indexed access. There are a lot of methods providing e.g. sorting and searching. 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 for handling wave soundfiles, allowing playback and recording wave soundfiles as well as creating and manipulating sound sequencess. Wave items may also be used in numerical operations (e.g. to apply a DSP algorithm on a signal).
Shell Item 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). For example, 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 the asterisk, "*"). If there is an error, the command returns the string "*" (the asterisk). If you supply an asterisk for the itemname argument , 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 itemname1 …

delete shell item(s) itemname₁, and so on.

The type of an item can be retrieved using this syntax: itemname[?]. E.g.:

#table := new table *
if '$#table[?]' == table then
  // the new table command was successful
end

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 itemname1 …

// 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, or should be:), 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

Shell item references are entities that refer 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 of synchronization issues - see below, and see the LOCK and UNLOCK functions). References may only refer to table, file, and instance items.

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

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 item has, obviously, exactly the same properties (type, attributes, data content,…) as the item it is referring to, 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.
• 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.

If the option /I is specified, errors will generate warning messages rather than error messages. See the Silent Flag page for details.

Protected shell items

In some situations it may be useful to protect shell items from (accidental) deletion. Our first user of this feature is the script console which protects all its vital objects.

STx implements two kinds of item protection:

Single Item Protection

As the name implies, this protects a single item.

protecedItem := NEW itemtype itemname… /u

creates a protected item. Note that, unlike with STx commands, the option letter for single item protection is case-sensitive. It must be the lower-case letter "u".

DELETE protectedItem /u

deletes a protected item. Here, too, the option letter must be lower case.

Global Item Protection

Global item protection uses a master item to control (i.e., enable/disable) global protection.

• Only those items created before the master item are protected.
• Items created after the master item will not be protected.
• There must be no more than one master item at any time.
• Global protection is enabled as soon as the master item is created.
• Global protection is disabled when the master item is deleted

Enabling Global Protection

The following command will create the master-item and enable global protection:

masterItem := NEW itemtype itemname… /U

Note that, unlike with other STx commands, the option letter for global item protection is case-sensitive. It must be the upper-case letter "U".

Disabling Global Protection

The following command deletes the master item and disables global protection.

DELETE masterItem /u

Here the option letter is case-sensitive, too.

Temporary shell items

A temporary shell item, also called local shell item, is a shell item that is deleted automatically as soon as control-flow leaves the context where the item has been created.

There are two ways to (intentionally, or unintentionally) create a temporary shell item:

• supplying the option /Garbage to the NEW command;
• using an expression returning a vector or a matrix, and not assigning the resulting entity to an existing shell item of the appropriate type. Such expressions are:
  1. certain EVAL functions;
  2. expressions extracting a row or a column from a value item, or from a table item; and
• calling a user-defined macro function returning a temporary shell item as its sole result, and not assigning its result to an existing shell item of the appropriate type.

The NEW /Garbage command

The most straightforward way to create a temporary shell item is to explicitly supply the /Garbage option when creating an item with the NEW command:

#table := new table * /garbage

Expressions returning a vector or a matrix

Firstly, using an EVAL expression returning a matrix or a vector will always create a temporary parameter table item, unless you are assigning the respective entity to an existing shell item of the appropriate type (in which case the matrix or the vector will directly be stored in the target item). For example, provided that #matrix does not contain the name of an existing shell item, the command…

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

…will create a temporary parameter table, and will assign its name (e.g. T#9A) to the variable #matrix.

Secondly, any expression that extracts a row or a column from a value item or a table item will normally create a temporary parameter table - unless, again, you are assigning the expression to an existing shell item of the appropriate type, in which case the extracted row or column will directly be stored in the existing target item.

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

Here, again, #rowVector will be assigned a temporary vector, provided that #rowVector does not already contain the name of an appropriate shell item the vector may directly be assigned to.

Returning temporary items from macro functions

It is also possible for a macro function to return a temporary shell item. For this to happen, 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
                        // because the string stored in #vector2 is not the
                        // name of an item anymore
// 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