Shell items are a kind of their own. Each shell item has a handle – actually kind of an internal name – that is not normally directly known to the programmer. Shell items may be created using the "new" command, and they may – and should – be disposed of properly after use which is done with the "delete" command. The handle to a shell item is normally stored in an S_TOOLS-STx variable.
There are different sorts of shell items, the most important being file items (representing disk files), graph items (representing graphs visible to the user), dialog items (representing GUI dialogs, menus, windows, and the like), table items (representing in-memory databases, numerical vectors, and matrices), and instances of user-defined classes. We will come to each of them later.
Beginners occasionally find it difficult to grasp the difference between a variable and a shell item. It is often helpful to remember the following properties:
Shell items are very complex objects like files or tables that normally consist of many parts (e.g. the rows and columns of a table, or the records of a file) most of which are themselves complex objects.
Variables, on the other hand, are very simple and dumb things: They store one string each – nothing complex in that.
Shell items are referred to by their handle, variables by their name.
You usually store the handle of a shell item in a variable.
You usually do not access a shell item directly, but by using the variable storing its item handle.
For using a variable, i.e. accessing its contents, you need the dollar sign ("$"). Opposed to this there is no dollar sign with item handles, because there is no such thing as a simple content of an item.
You may at any time request some action from an existing shell item. For doing so, you use the following command:
set itemhandle actionrequest
Here "itemhandle" is the internal handle of the respective S_TOOLS-STx item, and the exact nature of "actionrequest" depends on what kind of item you are dealing with; you may, e.g., request a table item to add or remove one or more rows, or a file item to write or to read data.
Since requesting some item to do something is such common a task, you may abbreviate it by completely omitting the "set" command. This means that instead of "set itemhandle actionrequest", you may at any time type the following command:
itemhandle actionrequest
So there would actually be no need of even knowing about the "set" command, were it not for the fact that with the S_TOOLS-STx online help, you find the actions each kind of item supports under the keyword "set itemtype", e.g., "set table".
Let's have a first simple example on how shell items are normally used:
// create a table whose handle is called "myhandle"
new table myhandle
// set third line (first and second line will be created empty)
set myhandle 2 'third line' // explicitly using "set"
// replace empty first line with a string
myhandle 0 'first line' // not using "set" works just as well
// now replace the second line, too
myhandle 1 'second line'
// show the table
showitem myhandle ; Showing table "myhandle"
// now, just for fun, delete the second row – note that, again,
// either using "set" or omitting it makes no change at all
set myhandle 1 /Delete
// finally, show the reduced table
showitem myhandle; Showing table myhandle" after deleting its second row
delete myhandle // don't forget to delete the item after use
In this example, we create a table item whose handle is the string "myhandle". Any further access to this item is done with this handle. Note that there is no dollar sign when using "myhandle", because "myhandle" is not a variable, but an item handle. If, by mistake, we would use the expression "$myhandle", S_TOOLS-STx would replace this expression by the contents of the shell-global variable "myhandle" – an empty string in case of there being no such variable, and surely an undesired result. Bluntly put: Item handles and variables reside in different namespaces, and you may well have like-named variables and item handles (of course this is not at all recommended because it may lead to some degree of confusion.)
All that being said, it is, though, common practice not to choose a handle of one's own, but to let S_TOOLS-STx do the choosing. In this case, the automatically chosen handle is normally stored in an S_TOOLS-STx variable:
// create a table item with a handle of STX's choice (e.g. T#27)
// (the asterisk instructs STX to choose a handle on its own).
// the handle will be stored in a variable called "#tab"
#tab := new table *
// set third line (first and second line will be created empty)
$#tab 2 'third line'
// replace empty first line with a string
$#tab 0 'first line'
// now replace the second line, too
$#tab 1 'second line'
// show the table
showitem $#tab ; Showing table "#tab"
// now, just for fun, delete the second row
$#tab 1 /Delete
// finally, show the reduced table
showitem $#tab ; Showing table "#tab" after deleting second row
delete $#tab // important: delete after use
N.B.: Whenever actively allocating a shell item (normally with the "new" command), you should delete it as soon as you no longer need it. If you don't, your macro(s) will consume an unnecessarily high amount of memory which may, for large macro applications, impair performance.
XXX insert the overview è right here ç