T.O.C. Index Bug Report ASCEND IV Home

script Script

Chapter 3 Script


The Script Utility (see Figure 3-1) allows us to record the process of solving a model, or any other user interface process. Once this process is recorded in the form of a script, the script can be repeated either fully or in part. The solution process for a given model can be communicated to another modeler by distributing a script saved to a file. Following is an outline of the various menus and buttons on the script window along with a library of the ASCEND commands which can be recorded.

3.1 The Script Menu Bar

3.1.1 Script File Menu

The script file menu provides several functions for managing script files. The script utility may contain multiple scripts but will only display one at any given time. Upon startup a scratch workspace is provided

New File
Request a buffer name and creates a new buffer with this name.

Read File
Requests a filename through the file selection box and proceeds to load this file (which is assumed to contain ASCEND Script and/or Tcl statements) into a new Script window buffer. No error checking is performed on the loaded file.

Import File
Requests a filename through the file selection box and appends the text contained in this file to the end of the current buffer.

Save
Saves the text in the current script buffer window to the current script file (indicated by the filename at the bottom of the script window). The existing file is overwritten.

Save As
Request a filename through the file selection box and saves the text in the current script buffer window to this file. If the specified file exists, it is overwritten.

Buffer List
A list of scripts used in the current ASCEND session is displayed at the bottom of the file menu. A script can be redisplayed in the script window by selecting it from the buffer list.

3.1.2 Script Edit Menu

Write selection
Saves the selected (highlighted) text to a file which is specified through the file selection dialog box. Selecting text is discussed in Section 3.4.

Select all
Selects (highlights) all text in the window.

Remove statements
Removes (cuts) the selected text. The removed text is NOT saved for later pasting.

3.1.3 Script Execute Menu

Statements selected
This button takes the selected text, breaks it into statements delimited by any semicolons (;) that appear in the selection, and executes each statement in the Tcl global environment.

3.1.4 Script toolbox menu

This menu has exactly the same content as the ASCEND toolbox window. See the chapter corresponding to the toolbox for details.

3.1.5 Script Help menu

On ASCEND/TCL Scripts
The highlighted selection is executed when you click Script.Execute.Selected_statements. The selection is broken into statements at semicolons. Each statement is sent to Tcl for execution. If the statement doesn't return any errors, it is unhighlighted and the next statement is processed. The # character is the Tcl comment. It is most often used at the beginning of a line, and its effect stops at the end of a line. The SCRIPT automatically wraps lines too long for the window.

On SCRIPT

3.2 SCRIPT Grill Menu

Record actions
When the record function is activated a log of interface events with defined ASCEND Script commands is appended to the end of the current script window buffer. Most, but not all, interface events have corresponding script commands. The record function can be turned on and off by toggling the pull down button on the grill menu or the record button at the bottom of the script window.

3.3 The Script Language

3.3.1 Summary

Script keywords are commands defined for ASCEND (in CAPS) which may be used on the commandline or in the Script. Keywords are actually Tcl functions which encapsulate one or more of the C primitives and other Tcl procedures, so that the user can conveniently emulate button presses. A working knowledge of tcl is not necessary to benefit from the Script's functionality; however, the tcl literate user will be able to create very powerful scripts.

Each keyword takes 0 or more arguments. The use of arguments is given in the following syntax:

<arg>
indicates the use of arg is required.

<a1,a2>
indicates that the use of either a1 or a2 is required

<a1 a2>
indicates use of both a1 and a2 required. Usually written
<a1> <a2>

[a1]
indicates the use of a1 is optional.

[a,b]
indicates that either a or b is optional, but not both.

qlfdid
is short for `QuaLiFieD IDentifier'

qlfpid
is short for `QuaLiFied Procedure IDentifier'

OF, WITH, TO, and other args in all CAPS are modifiers to the keyword which make it do different things.

{}
It is generally best to enclose all object names and units in {braces} to prevent Tcl from performing string substitution.

3.3.2 Quick reference:

ASSIGN
Sets the value of something atomic

BROWSE
Exports an object to the browser

CLEAR_VARS
Sets all the fixed flags to FALSE

COMPILE
Compiles a simulation of a given type

DELETE
Deletes a simulation or the type library

DISPLAY*
Displays something

INTEGRATE
Runs an IVP integrator

MERGE
Performs an ARE_THE_SAME

PLOT
Creates a plot file

PRINT
Prints one of the printable windows

PROBE
Exports an object to the probe

READ
Reads in a model, script, or values file.

REFINE
Performs an IS_REFINED_TO

RESTORE*
Reads a simulation from disk.

RESUME
Resumes compiling a simulation

RUN
Runs a procedure

SAVE*
Writes a simulation to disk

SHOW
Calls a unix plot program on a file from PLOT

SOLVE
Runs the solver

WRITE
Writes values in Tcl format to disk

* Items not yet implemented.

3.3.3 Commands

ASSIGN
ASSIGN <qlfdid> <value> [units]
Sets the value of atom `qlfdid' from the script. If value is real, it is required to give a set of units compatible with the dimensions of the variable. If the variable has no dimensions yet, ASSIGN will fix the dimensions.

BROWSE
BROWSE <qlfdid>
Exports qlfdid to the browser, displaying it as the current instance in the browser.

CLEAR_VARS
CLEAR_VARS <qlfdid> 
Sets the value of the fixed flag to FALSE for all the variables on qlfdid.

COMPILE
COMPILE <simname> [OF] <type>
Build a simulation of the type given with name simname. You can get away with leaving out OF or spelling it wrong.

DELETE
DELETE <TYPES,simname>
The modifier TYPES will cause all simulations to be deleted. If a simulation name (simname) is specified only that simulation will be deleted.

DISPLAY
DISPLAY <kind> [OF] <qlfdid>
How qlfdid is displayed varies with kind. kinds are: VALUE ATTRIBUTES CODE ANCESTRY

INTEGRATE
INTEGRATE {qlfdid args}
Runs an integrator on qlfdid. There are several permutations on the syntax. It is best to have solved qlfdid before hand to have good initial values.

INTEGRATE qlfdid (assumes LSODE and entire range)
INTEGRATE qlfdid WITH (assumes entire range)
INTEGRATE qlfdid FROM n1 TO n2 (assumes lsode)
INTEGRATE qlfdid FROM n1 TO n2 WITH integrator
Requires:

ARE_THE_SAME qlfdid1 and qlfdid2 if possible.

OBJECTIVE
OBJECTIVE
Semantics of OBJECTIVE that will be supported are unclear as no OBJECTIVE other than the declarative one is yet supported. Not implemented yet

PLOT
PLOT <qlfdid> [filename]
Writes plot data from qlfdid, which must be a plottable instance, to filename.

PRINT
PRINT <PROBE,DISPLAY>
Prints out the text currently in the Probe or Display.

PROBE
PROBE ONE qlfdid
Exports the item qlfdid to the Probe.

PROBE ALL qlfdid
PROBE qlfdid
Exports items found in qlfdid matching the current specifications of Visit in the Browser. By default, all variables and relations.

Items always go to currently selected probe context.

READ
READ [FILE,<VALUES,SCRIPT>] <filename>
Loads a file from disk. Searches for files in directories (Working directory):.:$ASCENDLIBRARY unless a full path name is given for filename.

The modifier FILE is used to indicate that the file contains ASCEND source code (ASCEND source code files normally have a .asc extension).

The modifier VALUES is used to indicate that the file contains variable data written by WRITE VALUES (These files normally have a .values extension).

The modifier SCRIPT is used to indicate that the file is a script file to be loaded at the end of the Script window (Script files normally have a .s extension).

If neither VALUES nor SCRIPT are found, FILE will be assumed. Note: You will get quite a spew from the parser if you leave out the SCRIPT or VALUES modifier by accident.

REFINE
REFINE <qlfdid> [TO] <type>
Refines qlfdid to given type if they are conformable.

RESTORE
RESTORE <file>
Reloads a simulation from disk

RESUME
RESUME <simname>
Reinvokes compiler on simname.

RUN
RUN <qlfpid>
Run the procedure qlfpid as if from the browser Initialize button.

SAVE
SAVE <sim> [TO] <filename>
Filename will be assumed to be in Working directory (on utils page) unless it starts with a / or a ~. Not implemented yet.

SHOW
SHOW <filename,LAST>
Invokes the plotter program on the filename given or on the file LAST generated by PLOT.

SOLVE
SOLVE <qlfdid> [WITH] [solvername]
Exports qlfdid to the solver and attempts to solve it with the default solver (usually QRSlv) or the solver indicated by the optional solvername argument. Solvername must be given as it appears on the menu buttons. Bugs: Should use current solver rather than default.

WRITE
WRITE <kind> <qlfdid> <file> [args]
Write something (what sort of write indicated by kind) about qlfdid to a file. args may modify as determined by kind. At present only VALUES is supported. SYSTEM (for solver dump) would be nice.

WRITE VALUES filename.
Filename must be a full path name or in the pwd, also known as `.' .

3.4 Script Window Bindings

In the event binding descriptions that follow, M1 is short for mouse-button-1 (the left mousebutton), M2 is the middle button, and M3 is the right mouse button. On machines with no middle button, M3 is still the right mouse-button and M2 is unavailable.

M1
repositions the cursor.

M1-Drag
selects text.

Shift-M1[-Drag]
extends the selection.

Double-M1
selects the nearest word.

Double-M1-Drag
selects the nearest word and those you drag over, whole words at a time.

Triple-M1
selects the nearest line.

Triple-M1-Drag
selects the nearest line and those you drag over, whole lines at a time.

M2
does nothing.

M2-Held-Down
has an effect similar to the scrollbar.

M3
does nothing.

Control-M1
Starts another part of a disjoint selection.

UNIX bindings:
The text widgets in ASCEND share a common stack of cut/copy/paste text pieces. This is a CMU extension of the text bindings, not default Tk behavior, and it is EMACS-like, but not EMACS (EMACS uses a ring, not a stack.) When the stack is empty, Paste does nothing. This is a design decision. The Tcl function ascPopText can be changed to behave differently.

Control-k
Cuts text to the end of the current line, putting it on the stack.

Control-w
Cuts the selected text, putting it on the stack.

Meta-w
(e.g. diamond-w on most Sun keyboards) Copies the selected text onto the stack.

Control-y
Pastes the most recent text added to the stack, and removes it from the stack.

Meta-y
Not supported.

MSW bindings:
The standard Control-X, Control-C, Control-V bindings of Microsoft Windows clipboard apply to text widgets. The UNIX text stack is not available.


Last Modified: 02:53pm EDT, September 30, 1997
9/26/97 Release 0.8 authors T.O.C. Index Bug Report ASCEND IV Home