Go to the previous, next section.

Facilities within the Command Interpreter

This is a guide to the use of SM variables, the macro processor, the help command, and the history facilities. The vector arithmetic and plotting facilities are described below. Various examples are scattered throughout the text, to give some guidance on the use of SM's capabilities.

Perhaps the most important thing to know is how to escape from SM. If you have a prompt, simply type QUIT @footnote #{or q which is a macro defined as DELETE HISTORY QUIT. This will exit SM just the same, but the quit won't appear on your history list, waiting to be playedback accidently. Actually, q will query you before quitting}. If you are running some command, try ^C to get a prompt. Most commands will eventually return control to the keyboard following a ^C. In addition, the parser is reset, and the input buffer cleared. Sometimes ^C leaves a } on the buffer if it thinks that it'll help get back to the prompt, which can generate an irrelevant syntax error. Occasionally it can still be confused -- try typing a few characters and maybe a }.

When you have interrupted SM with a ^C, a macro called error_handler is executed, if it is defined. The one that we provide does things like setting the expansion back to 1, and resetting any window commands that you might have issued, and then prints a message handler... to tell you that it's done its work. If you don't like this, see `private initialisation' in the index for how to get your own handler loaded automatically.

If you make a mistake, and SM notices a syntax error, it'll print a message indicating where you were and which macro you were running. It is possible for the wrong macro to be reported (if SM has finished reading the macro before detecting the error), in which case you'll be told that the error occurred in a macro that called the offender. Setting VERBOSE (@xref{VERBOSE}) to 3 or 4 provides a more direct way of finding the true location of the error.

If you define the variable traceback to be 1 (maybe with the line traceback 1 in your `.sm' file) you'll get a traceback of what macros were active when the error occurred; the same caveats about the wrong macro being reported apply. In addition, the usual interrupt capabilities of your operating system will work under SM, with a couple of quirks.

Under Unix, in case of emergency, type ^\, and SM will ask you if you want to return to the prompt, and if you don't it'll offer a core dump, and then exit. As usual, typing ^Z (from the C-shell) will interrupt the process, which may be restarted later. Under VMS, ^Z will interrupt SM, and return you to the command interpreter (DCL). Typing CONTINUE will then allow you to restart SM @footnote %{If you are using VMS, you may prefer to use ^Y as your interrupt character. A suitable set of key definitions is in a file called maps_vms.dat in the top SM directory. It may be read with the READ EDIT command (see section Changing Key-Bindings), and this may be done automatically in your startup macro by the variable edit in your `.sm' file.}.

If SM is running in a SPAWNed sub-process, then ^Z will reATTACH you to its parent. To continue SM, use the DCL ATTACH command. We strongly suggest that you learn how to do this, it makes life much easier -- all you have to do is SPAWN a process from DCL and start SM from there. Do check with your VMS system manager to ensure that you have the right quotas for SPAWNing (Process limit must be at least 3, because SM will use one for itself and one for hardcopies). An especially simple way to do all this is is to use the command file `kept_SM.com' in the main SM directory. It'll handle the spawning and attaching for you.

Another fact to bear in mind is that the characters ^, $, and # are special, as ^ is used by the history system, $ introduces a variable, and # starts a comment. The special meanings of all of these characters except ^ can be turned off by preceding them with a \. To type a ^, use the quote_next character (initially ^Q or ESC-q) to quote the ^; i.e. type ESC-q. @footnote ^{In fact you can rebind any character to replace ^, see section Command History} A \n is interpreted as a carriage return, and a \ as the last character on a line escapes the newline, so that the line and the one following it are treated as one long line. A \ preceding any other character (except a "; see next paragraph) is simply a \. This character is used to set font types in the LABEL commands, so it has no special meaning to the command interpreter, which simplifies the entering of strings for LABEL commands.

A further problem is that symbols such as +, -, *, and / are used to separate words, which is what you want for mathematics, but maybe not what you had in mind for filenames. Enclosing a word in double quotes turns off all special meanings except ^; an embedded " may be escaped with a \. Single quotes are used quite differently; enclosing a word in 'single quotes' makes it into a string so '12' is a two-character string and not an integer at all. There are times when this is important; for example if(y == 'yes') tests if the vector y is equal to the string `yes', whereas if('yes' == 'yes') asks whether two identical strings are equal (they are). When you remember that I can legally say set yes='no' you'll appreciate the distinction.

The characters {2 also perform quoting, turning off the special meanings of all characters (including single and double quotes, but not ^). The difference between double quotes and braces is that the latter have grammatical value; they are part of the syntax that SM understands. In most cases you can use angle brackets instead of curly ones if the grammar needs the brackets but you don't want to turn off expansions.

SM is case-sensitive. It will accept keywords in either upper or lower case, but this is a special dispensation on its part. If you insist on typing in uppercase say load uppercase when you first start SM, or put the line uppercase 1 in your `.sm' file. Furthermore keywords may not be abbreviated. This is not a great hardship as it is easy to define macros which make the minimum abbreviation a synonym for the full command. Many such macros are predefined for you when you first use SM; see section The System Macro Libraries for details. In particular, certain common abbreviations of commands have been predefined by the SM startup file.

Every time that SM is started, it looks for an environment file called `.sm' which consists of names of variables and their values. From # to the end of a line is taken to be a comment. A list of directories to be searched in order for `.sm' files is compiled into SM, it usually consists of the currect directory, then your home directory, and then some system directory. The system default can be over-ridden by defining the environment variable SMPATH which is a list of directories separated by single spaces. Each directory on the search path is tried in turn until a file is found containing the desired variable, which allows your choices to take preference over those of the system administrator. In the list of directories . is taken to be the current directory, and ~ is your home directory unless you specified a command line -u name option, in which case it is taken to be name's home directory instead. This means that sm -u name will usually run SM as if you were name. The default path is equivalent to an SMPATH of

export SMPATH=". ~ /u/sm/lib/"

An example file would be (the filenames are written in Unix)

# I'm a comment line
fonts       /users/sm/fonts.bin
graphcap    /users/sm/graphcap
help        /users/sm/help/
macro       /users/sm/macros/
name        Robert         # Or alternatively `Dr._Lupton'

SM then tries to read in any macros in the file `default' in the directory `macro' and attempts to execute the macro startup if it exists. If -m filename appears on the command line, this is taken to be the name of another file of macros and these are read, and the eponymous macro is executed (after any pre- or suf- fix has been removed. For instance if you start SM with the command sm -m /home/tst.m, it will first read the file /home/tst.m, and then attempt to execute the macro tst). @footnote *{Under VMS, SM must have been installed as a foreign command for this to work, and it must not have been linked with the debugger}

Anything left on the command line is treated as if it had been typed at the prompt, for example sm restore vital.save will start by RESTORing from the file vital.save (see RESTORE if you want to know what this means). The -m option is not really a good way to personalise SM. The startup macro discussed under `useful macros', which is run everytime that you start SM, looks for a directory macro2 in your `.sm' file, and if it is there reads a file `default' from it, and executes the macro startup2 which it expects to find there. On case-insensitive operating systems, such as VMS, you may need to quote the command line to prevent it being translated to upper case. SM then attempts to read a set of history commands from a file in the current working directory, passes control to the input routine and issues a prompt. The file is given by the entry hist_file in your `.sm' file, and if it isn't present then no history will be remembered.

You are then able to type commands, as many as will fit on one line @footnote +{Occasionally a <CR> is required by SM, so putting two commands on one line will give a syntax error. The cause is the way that the grammar is written (see section The Command Interpreter), the fix is either to use two lines, or else to put an explicit carriage return at the appropriate point with a \n}, and use the features described below.

You can use a combination of these features to run SM in `batch' mode. If you had a history file that you just wanted to run, then you could start SM, say playback, and quit. You could have a macro called batch in batch.m that did just that, and say sm -m batch.m to execute it. In fact, you don't even need your own macro as one is pre-defined for you so sm batch is sufficient. You could write your own macros along this lines to do more complex tasks. A more convenient alternative (under unix) would be sm -S < history_file where the -S is explained in the next paragraph.

For completeness, we should mention the other six command line flags, -h, -l logfile, -q, -s, -S, and -v#. The -h prints a summary of command line options, if you specify a logfile with -l everything that you type at the keyboard is copied into the logfile (except editing commands). The -s (for `stupid', or `silent' or `suppress') flag disables the command line editor (although the history list is still saved, so commands like playback will work), -q suppresses the initial `Hello' message, and -S is like -s but it also suppresses the prompt and stops SM from intercepting ^c. You can get the same effect as -s from inside SM with the command TERMTYPE none. If you are reading from a file or pipe SM behaves as if you had invoked it with the -S flag. This is useful if SM is being run from inside another programme, via a pipe (VMS: mailbox), or on a very stupid terminal. If you want to set a particular value of verbose, use -v for example -v-3 is equivalent to the VERBOSE -3 command given interactively.

Go to the previous, next section.