This is an old revision of the document!
Table of Contents
TOOL Shell Scripts
Sometimes it is useful to use TOOL scripts in a “sandbox” or “scratchpad” manner—for experimentation, learning new tools, instant feedback, etc.—without the overhead of setting up a new model family and framework, and without the worry of breaking anything. In this cases, TOOL shell scripts can be handy.
Calling a Shell Script
A shell script is invoked by the following syntax from the TOOL command line:
TOOL> tool {options} fileName objectList
Where options is a list of options available to TOOL that provide it with extra instruction. Each option is a letter(s) preceded by the hyphen character '-'. The valid options are:
| Option | Description |
|---|---|
| -h | help: will cause the syntax for invoking TOOL to be displayed. |
| -l | local : tells TOOL to look for files and create new files in the current working (local) directory that have the exact names as the objects that are used in the script. You do not need to include the objectList parameter when using TOOL in local mode. You are responsible for the management of all files associated with a script when you use local as files will be created for all objects that are not declared as locals in the script. |
| -v | verbose: tells TOOL to display each line of the TOOL script as the script runs. This option is used to help debug a script. By default, only the output from say, mumble, listen, and menu commands is displayed while a script is running |
| -e | error: tells TOOL to continue running the TOOL script even if an error occurs. This option is used to help debug a script. The default is for a TOOL script to stop running as soon as an error occurs. |
| -s | single step: (invokes v automatically) causes the script to be executed one line at a time and the user must carrage return to initiate the next line |
| -doo | display output object: causes the script to display the contents of every output object as it is created according to the displayOutObjs link defined in the TOOL Links File |
| -link | link: used to invoke a link to TOOL. A TOOL link defines the interface between TOOL and any other software that uses the TOOL language. A link consists of a name to identify the link and a mapping to one or more TOOL tools that are to be used whenever the link is invoked. In this sense, a link merely provides a translation from a link name to a tool name. This option is used by Scenario and Model Manager (SAMM). When using this option, you must enter the option in the following form: -link linkName where linkName is the name of the link to be invoked. The mapping from the link name to TOOL tools must be placed in a file called the TOOL links file. This file is accessed by TOOL whenever it is invoked with the link option. The linkName must exist in the TOOL links file. TOOL will first look for this file in the current directory from which TOOL was invoked, then in the directory indicated by the UNIX environment variable $HOME and finally at the top level of the TOOL account. |
fileName is the name of the TOOL script file to be run. It is helpful to adopt a convention for the naming of TOOL script files. A useful convention is to use the '.t' file extension on all script file names so that you can easily see that the file contains tool script. An example would be a script called 'popImpact.t'.
objectList is a list containing the files that are to be used for all input objects and output objects that are used within the script. This list must match the input and output object declarations within the script in both order and size. TOOL will map the files that you provide in the objectList to the object declarations in the script in the order that they appear. This list can be placed inside a file in which case you would specify the file name instead of the object list when invoking the script. This list does not need to be included when using TOOL in local mode as TOOL will look in the current working directory for files of the same name as the objects used in the script.
[step through the setup and running of a simple shell script]
Examples
From the interactive TOOL command line, run:
TOOL> tool -l myToolScript.t
Using Local Mode
One of the challenges of running shell scripts in standard mode is the need to create and shape objects. [objectList appears to provide a mechanism for passing in and out objects, but this seems clunky for interactive, low-overhead TOOL - used by SAMM, views, etc?]. To mitigate this, TOOL scripts can be run in local mode in which TOOL objects - as files - can be accessed from and output to the the local working directory. This is especially useful if certain TOOL objects (with instance data) exist in a modelbase. These variables can be exported directly from SAMM (right click on variable | Export Variables…) to the working directory. The TOOL file format preserves shape and instance data.
Other Useful Information
Note that the informants path used by the tool script is set in the tool.init file in the account home directory. An example of this setting is:
$informPath = $home + "/V2/informants"
Environment variables, including the inform path can be checked by calling the command showenv().
Other useful TOOL navigation commands are where(), moveto(pathName), up() and look(); the declaration localinformant is useful. [move this stuff further up so the user knows to get up and running quickly; inform path and home, explain these concepts earlier]
[somewhere, maybe not in this article, list the “scratchpad” or instant-feedback alternatives to a full model load:
- TOOl shell scripts
- Running data through documenter
- Side-loading code and diagrams into SAMM
]
