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 these cases, TOOL shell scripts can be handy.

Using the TOOL shell application, which can be launched from the Programs menu under the whatIf grouping, gives you an interactive TOOL session which can be used to run tool commands directly or run a tool script.

When you launch the TOOL shell you will be asked for server connection information and then you will see a prompt:

 TOOL> 

You can run tool commands directly or you can run a script from a file. The most commonly a script file is used. Before you run a script you will need to get to the right directory and setup the environment. Here are a few common commands you may find useful, more detail can be found in the documentation under TOOL Language/TOOL Commands.

• showenv() - shows all the builtin variables like $informPath, $toolsDir and $dir which you may want to set
• where() - shows what directory on the server you are in.
• moveto(“path”) - changes the current directory to path which can be either a relative or full path
• look() - shows what is in the current directory optionally a string can be provided to filter the results

TIP: In the interactive TOOL window hit <Ctrl> and the up arrow key to get the previous command to save typing

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:

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]

From the interactive TOOL command line, run:

TOOL> tool -l myToolScript.t

One of the challenges of running shell scripts in standard mode is the need to create and shape objects. 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.

Suppose you wanted to test some code in a script which required building a shaped object (with an informant from your model called canReg) running a couple of tools and then showing the result with table. Here's one example of how to use interactive TOOL and a tool script to do that.

• Make a sub directory in your model account (can also be done in a user account depending on what you want to do) to hold your test script and any data it may create
• In that directory write your script text file (myScript.t) just as you would any other piece of tool code (most similar to view writing):

informant canReg[]

local myStock[cr,ts] = create(; dim=canReg, dim=SEQ;time:1992:1994:1;year)
myStock[cr,ts] = import(; rowTitles=on, dataFile=$home/primaryData/inputStock.txt )

local myStockTot[ts] = sum (myStock[cr,ts]; dim=canReg)

table (myStockTot[ts])

• Launch interactive TOOL - find it under Start/All Programs/whatIf/TOOL
• Login as your model account
• Check where you are and move to the directory you created above:

TIP: In the interactive TOOL window hit <Ctrl> and the up arrow key to get the previous command to save typing

TOOL> where()
TOOL> look()
TOOL> moveto("the appropriate path to your testing directory")

• Make sure your $informDir points to the model informants you wish to use.

TOOL> showenv()
TOOL> $informPath = "full path to model's informants directory"

• Look to see that your script exists in the current directory if not check where you are and that the file actually does exist where you think it should!

TOOL> look()

• Run your script:

TOOL> tool myScript.t

You can modify your script with a text editor and save it and then re-run it in the same TOOL session.

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 (either in your script or on the command line):

 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

]