Commands and Scripts

Command files are files containing circuit descriptions and/or shell commands. The first line of a command file is ignored, so must be blank or a comment. This is a result of the source command being used for both circuit input and command file execution.

A pure script file, i.e., one which does not include a circuit description, consists of an unread ``title'' line, followed by a control block. The control block begins with a ``.control'' line, continues with one or more executable statements, and terminates with a ``.endc'' line. In WRspice, an ``.exec'' line can be used rather than the .control line, though for backward compatibility with SPICE3, it is recommended that the traditional .control be used. The executable statements are any statements understandable to the WRspice shell. Typically, such statements appear just as they would be entered on the command line if given as text input. A script may be executed by entering its file name (there is an implicit <tt>source</tt> command) followed by any arguments. Scripts can call other scripts to any depth.

In script text, the `#' character is used to designate a comment. If the `#' is the first character in a line, or follows white space, the `#', and the preceding white space, and any trailing text, is ignored. If the `#' is preceded by a backslash, the comment interpretation is explicitly suppressed. The in-line comment interpretation of `#' applies only in scripts, not from the command line.

Before a script is read, the variables argc and argv are set to the number of words on the command line, and a list of those words respectively. Their previous values (if any) are pushed onto a stack, and popped back in place when the script terminates. Thus, within a command script, these predefined variables are available for use in the script. Otherwise, command files may not be reentrant since there are no local variables, however, the procedures may explicitly manipulate a stack.

If a command file contains a circuit discription, then there is a subtle difference between .control and .exec blocks, either or both of which can be contained in the file. By ``file'' we actually mean the totality of text after expanding all .include, .lib and similar statements. The .exec block is executed before the circuit lines are parsed, and thus before the lines are shell and parameter expanded. Thus, shell variables set in the .exec block will be used when expanding the circuit. The .control block is executed after the circuit is parsed, and is therefor the correct place to put analysis and post-processing commands.

There may be various command scripts installed in the default scripts directory, and the default sourcepath includes this directory, so one can use these command files (almost) like built-in commands. In addition to scripts, there is an executable data structure called a ``codeblock''. Codeblocks are derived from scripts, but store the command text internally, so are somewhat more efficient. A codeblock has the same name (in general) as the script file from which it was derived. See the description of the codeblock command (in 4.5.1) for more information.

When a line of input is given to WRspice, the first word on the line determines how the line is processed. The following logic is used to make this determination.

1. If the word is an alias, the line is replaced with the result after alias substitution, and the line is re-parsed.

2. If the word matches the name of a codeblock in memory, the codeblock is executed.

3. If the word matches the name of an internal command, that command is executed.

4. If the first word is a vector name and is followed by ``='', the line is taken to be an implicit let command (an assignment), in which case the line is executed as if it were preceded by the word ``let''.

5. If the word matches the name of a file found in one of the directories of the current sourcepath (search path), an implicit source command is assumed. The line is executed as if it were preceded by the word ``source''. Thus, typing the name of a circuit or script file will source or run the file.

6. If the variable unixcom is set, and the word matches the name of a command known to the operating system, the line will be sent to the operating system for execution.

If the variable unixcom is set and the operating system is supportive, commands which are not built-ins are considered shell commands and executed as if the program were a shell. However, using this option increases the start-up time of the program. Probably WRspice should not be used as a login shell.

WRspice can be used as the ``shell'' in UNIX shell scripts. In these scripts, the wrspice executable should be called, using the convention applicable to the user's UNIX shell. This generally requires that the first line of the script begin with the characters ``#!'' and be followed by a space-separated program invocation string. The remainder of the file should consist of standard WRspice command file lines, the first line of which (second line of the file) will be ignored.

For example, below is a script that can be saved in a file, which should be made executable (using the UNIX command ``chmod +x filename''). From the UNIX shell, typing the name of the file will run WRspice on the example file mosamp2.cir and display the plot.

#! wrspice -J
#
.control
source /usr/local/xictools/wrspice/examples/mosamp2.cir
set noaskquit
echo Press Enter to quit
pause
quit
.endc

Typing the name of the file is the same as executing ``wrspice -J file''. WRspice ignores the #!... line, so that the next line is the ``title'' line and is also ignored. The -J (JSPICE3 compatibility) means to not bring up the Tool Control window.