Shell Items

Introduction

STx implements a number of different objects which can be used to manipulate files, graphics, dialogs, etc. These objects are called shell items. See Introducing Shell Items for an introduction to shell items. For a complete list of available shell items, see below.

A new instance of a shell item is created using the NEW command. For deleting an instance of a shell item, there is the DELETE command.

#tableItem := new table hugo   // will create a new table item called hugo
                               // and store its name (i.e., the string "hugo")
                               // in the variable #tableItem

   // either command will delete the recently allocated table item:
delete hugo                    // (a) delete the table item by its name
   // - OR -
delete $#tableItem             // (b) delete the table item by its name stored in #tableItem
   // - OR -
delete /Var #tableItem         // like (b), plus: the variable #tableItem will be cleared

Shell items (alphabetical list)

Introducing Shell Items

A shell item is an object designed to be good at a specific range of tasks. E.g. there is a file item which allows you to read, write, copy, rename and list files and there is a dialog item, which allows you to design and display dialog boxes, and react to user input.

Shell items are implemented in C++ and made accessible to the STx programmer via commands, attributes and messages; these are documented in the Shell Items help chapter. The name of an item is used as a reference (pointer) to the item.

Currently STx implements 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).
Dialog - A shell item for designing and displaying dialog boxes and processing user input. A dialog is always a part of a display item.
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 type TABLE, VALUE and FILE can also be used directly in numerical expressions (EVAL)

Working with shell items

Commands

The commands NEW, SET and DELETE can be used to deal with shell items in scripts.

NEW itemtype itemname ...: create a shell item
SET itemname function ...: perfrom an action with a shell item
DELETE itemname ...: delete shell item(s)

In most cases it is not necessary to specify the SET command explicit, because it is used implizit if a command line begins with the name of an item. This means the command SET itemname function ... is equivalent to itemname function ....

Examples:

NEW:

// 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:

// append 2 lines to a simple table
set $#table * 'first entry'  // explizit SET command
$#table * 'second entry'     // implizite SET command
// copy the content of a table to the clipboard
$#table clipboard
// load the whole file into a table
$#textfile load $#table

DELETE:

// delete an item
delete $#table
// delete items, the item names are stored in the specified variables;
// the variables are also deleted (set to empty)
delete #data #textfile /variable /?

Messages

Attributes

You create a shell item using the NEW command. E.g.:

// create a new table identified by the name 'tStrings'
NEW TABLE tStrings
if '$RC' > '0' WRITELOG Shell table creation failed ($RC): $EMSG

If the NEW command was successful, then a table item now exists called 'tStrings' and can be used until the shell in which it was created is deleted, or the table item itself is deleted (see Deleting a shell item). If the NEW command fails, then the shell variables RC and EMSG indicate the reason for the error.

Rather than explicitly giving each shell item a name, most STx programmers take advantage of the automatic unique name generation available in the NEW command (specify an asterisk for the item name). E.g.:

// create a new table identified by an automatically generated
// unique name.
NEW TABLE *
if '$#NEW' == '*' WRITELOG Shell table creation failed ($RC): $EMSG

The unique name is automatically stored in the local variable #NEW if the NEW command was successful. If the command fails, the #NEW variable's value is set to an asterisk.

The most compact way to create a shell item is as follows:

// create a new table and assign the automatically generated name
// directly to a local variable
#table := NEW TABLE *
if '$#table[?]' != 'table' WRITELOG Shell table creation failed ($RC): $EMSG

Checking an item's type

The following syntax will return the type of a valid shell item identified by the specified name:

itemName[?]
// or
$#item[?] // if the name is stored in a variable

The string which is returned is the same as the string passed to the NEW command, e.g. wave for a wave item, table for a table item. This item check is most useful for determining the nature of parameters passed to your macro. E.g.:

[macro istable]
        if '$#argv[?]' != 'table' exit 1 int -1
exit 1 int 0

Note that prior to STx version 3.7.0, the syntax for retrieving the shell item's type was ~$#item.==Accessing shell item attributes==

Most shell items have attributes which can be accessed using the following syntax:

itemName[!attributeName]

For example, you can 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 individual shell item documentation for a list of supported attributes.

Note that prior to STx version 3.7.0, the syntax for accessing a shell item's attributes was ~$#item[!ATTRIBUTE].==Executing shell item commands==

Every shell item has specific commands which they can execute. E.g. a dialog can display a context menu:

SET $#dialog CONTEXTMENU $#menuId

The SET command is optional, so the following command does the same:

$#dialog CONTEXTMENU $#menuId

If the command is successful, then the RC shell variable is set to 0. If the command was unsuccessful, then the programmer should use the RC and EMSG variables to process the error. E.g.:

$#dialog CONTEXTMENU $#menuId
if '$RC' > '0' then
        WRITELOG The dialog command CONTEXTMENU failed ($RC): $EMSG
then

Deleting a shell item

You can delete a shell item with the DELETE command. E.g.:

// Delete the shell item identified by the name 'tStrings'
DELETE tStrings

You can also delete multiple items

DELETE $#t $#f $#w

Best practice is to check that the item is valid before deleting it.

if '$#t[?]' == 'table' delete $#t

References to shell items

Protected shell items

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.

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

Shell Items

Contents

Introduction

Shell items (alphabetical list)

Introducing Shell Items

Working with shell items

Commands

Messages

Attributes

Checking an item's type

Deleting a shell item

References to shell items

Protected shell items

Temporary shell items

Navigation menu

Page actions

Page actions

Personal tools

Navigation

Search

Tools