====== 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 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.

===== TOOL interactive commands =====

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

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




===== Calling a Shell Script =====

A shell script is invoked by the following syntax from the TOOL command line:

<code>
TOOL> tool {options} fileName objectList
</code>

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:

<code>
TOOL> tool -l myToolScript.t
</code>

===== Using Local Mode =====

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.

===== Example session =====
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):
<file>
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])
</file>
  * 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

<code>
TOOL> where()
TOOL> look()
TOOL> moveto("the appropriate path to your testing directory")
</code>
  * Make sure your $informDir points to the model informants you wish to use.
<code>
TOOL> showenv()
TOOL> $informPath = "full path to model's informants directory"
</code>
  * 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!
<code>
TOOL> look()
</code>
  * Run your script:
<code>
TOOL> tool myScript.t
</code>

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





===== 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:

<code>
$informPath = $home + "/V2/informants"
</code>

Environment variables, including the inform path can be checked by calling the command (either in your script or on the command line):
<code> showenv() </code>

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
]