Differences

This shows you the differences between two versions of the page.

--- howtos:toolcoding:tool_shell_scripts [2009/12/17 21:15]
shona.weldon
+++ howtos:toolcoding:tool_shell_scripts [2011/05/13 12:27] (current)
shona.weldon
@@ Line 1: / Line 1: @@
 ====== 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.
+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 =====
@@ Line 51: / Line 69: @@
 ===== 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.
+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 =====
@@ Line 61: / Line 125: @@
 </code>
-Environment variables, including the inform path can be checked by calling the command ''showenv()''.
+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]

whatIf? Wiki

User Tools

Site Tools

Differences

Page Tools