3. QUANTA Scripting Language

---

Contents

---

Introduction

QUANTA is designed such that every mouse click corresponds to a typed ("keyboard") command. The QUANTA "record" mode saves all commands, whether from the keyboard or the mouse, into a single file. This consistency lets you record a movie-like script, illustrating and highlighting key points of a structure or interaction for a later presentation, with a minimum of effort.

The commands can be removed later if rotations and translations are not required for end use. The Record functionality may also be used for precisely recording a sequence of manipulations for an archive, or to generate commands to be used as the core of a more complex script (a "macro").

To generalize a script and to increase its power, you may use variable substitution and add flow-control commands. QUANTA supports a subset of the Tool Command Language (TCL) for this purpose. See Introduction to TCL Scripting Control on page 115. The addition of TCL commands and QUANTA command modifications must be done with a text editor.

---

Command Logging

---

Creating a QUANTA log file

Creating a QUANTA log file (record script) is straightforward.

1.   To begin recording commands, select File/Record Session/Start from the QUANTA interface menu.

2.   In the window, enter the file name for the script ("script.rec" for example), or type "record start script.rec".

3.   When you wish to stop, pause or resume recording, select the menu pulldown at File/Record Session or type in "record <keyword>" where <keyword> is "stop", "pause" or "resume."

---

Playing back a script

Depending on the script, you may need to reset QUANTA by closing files. QUANTA record scripts can be started in two ways:

1.   Use the interface menu (or its keyboard equivalent); for example File/Replay Session/Start >.

2.   Type:

> @<script name> 

Assuming a script name of script.rec, correct commands would be: @script.rec or @script.

---

Script Modification

Script modification is necessary when you want something other than an exact logging of a QUANTA session. QUANTA provides no tools for adding TCL commands or editing record files. Scripts are ASCII files; they can be modified using any text editor. Common modifications are script simplification (removing unnecessary commands), changes of the target of the scripts, or introduction of flow (looping and branch logic). Flow control is discussed in Introduction to TCL Scripting Control on page 113.

---

Script simplification

If a given script is not meant for visual illustration, the first step to simplify it is generally to remove some or all mouse-introduced translation and rotation and other related commands from the file.

QUANTA logs mouse-based rotation, translation, zoom, and z-clipping adjustment commands as relative motion commands. All begin with %MOUSE. Similarly, commands issued using the pseudo-dials box in QUANTA are logged as %TRANS.

QUANTA does record some movement-related commands. A record file can be significantly reduced in size by removing "redundant" %mouse commands. The following awk script does this:

awk 'BEGIN {old = " "}; \
   $1 == "%MOUSE" || $1 == "%TRANS" \ 
     {if ($0 != old){print $0; old=$0} }; \
   $1 != "%MOUSE" && $1 != "%TRANS" \
     {print $0; old=" "}' \
  input.rec > output.rec

If a script requires no structure movement, then all movement commands can be removed.

In UNIX a simple way to remove all %MOUSE commands is to filter them out using the "grep" command:

> grep -v '%MOUSE' script.rec > short_script.rec

Table 28 displays a summary of the %MOUSE command parameters.

Note the number (nn) is derived from a binary code:

• 1 = left mouse button

• 2 = middle mouse button

• 4 = right mouse button

• 8 =  <Ctrl> key

• 16 = <Shift> key

• 32 = <Alt> key

xxxx and yyyy are the xy position of the mouse on the screen (screen size dependent).

mp = 1 when the mouse button is depressed. It signals the start position. mp = 0 for subsequent contiguous mouse commands.

---

Adding new commands to a script with a text editor

While creating a script starting with a record file, you may find that some commands that are absent from the initial script are needed, or that some commands should be changed. You could have QUANTA generate a new record file and generate a new script. Another option, which is perhaps the best way to learn the QUANTA syntax, is to use the QUANTA "command echo" option. When you use this feature, QUANTA reports in the text window the syntax of each command as it is executed.

To turn on command echoing, type:

> set echo on

For some commands, you may prefer to use keyboard commands that are never generated by the interface. For example, you can replace mouse movement commands with explicit movement commands such as ROT x 90 and TRAN y -10. For a summary of useful keyboard commands, see the Appendix on page 115.

---

Introduction to TCL Scripting Control

The real power of QUANTA scripts comes from TCL additions to QUANTA commands. These additions include variables, branching, lists, and subroutines.

All TCL commands in QUANTA must be preceded with the "!" character. All comments must contain an "*" in the first non-blank column.

Please refer to Tool Command Language (TCL), for more information about TCL.

---

Variable definitions and usage.

!set protein 1crn.msf
!set str_len 3
!set aaname ""

Variables must be preceded by the "$" character when used (as opposed to being defined) in an expression:

clip $width
mole open $protein, behavior replace ok 

TCL commands that return values are placed in square brackets:

!set str_res [!expr $colon_index+1]
!set resid [!string range $string $str_res $str_len]

---

Branching and looping

FOREACH command:

	!set count 0
	!foreach value $value_list {
		. . .
                 !incr count
             }

FOR command:

	!for {!set count 0} {$count < $max} {!incr count} {
		. . .
            }

IF/ELSE command:

	!if {$value < 0} then {
         . . .
      } else {
	   . . .
	}

WHILE command:

	!while {$start < [!expr $len-1]} {
	   . . .
      }

Below is a full TCL script that rotates a pre-saved scene (save the scene using File/Save Status):

# This script a requires a QUANTA status file called "scene1"
#
#  Reinstates the molecule, scene and settings
stat rest scene1
# Begin controlled transformations
!for {!set frame 1} {$frame<=4} {!incr frame} {
  scale 1.08
}
!for {!set frame 1} {$frame<=90} {!incr frame} {
  rota y 1.0
}
!for {!set frame 1} {$frame<=60} {!incr frame} {
  rota x 0.666667
}

---

Lists creation and modification

!list $val1 $val2 $val3

!glob -nocomplain  *.msf

!lappend shrt_list $item

List extraction

!lsearch $abig_list $str

!lindex  $my_list $index

Operations

!expr $index+($val/2.0)

!incr $variable<optional inc. value>

!string range $string $f $l

!string tolower $str

!scan $string {%I %I} $val1 $val2

Input / Output

!echo "there are $numfiles files loaded"

!set $fileid [!open  myfile.txt <r|w|a>]

!puts $fileid "There are [!llength $result] pairs."

!set string  [!gets $fileid]	

---

Appendix

---

Commonly used QUANTA keyboard commands:

SET ECHO ON

SET ECHO OFF

SCALE <scale>

ROTate <x|y|z> <angstrom value>	

TRANslate <x|y|z> <angstrom value>

CLIP  <angstrom value>

MAP TAB SHOW     

MAP TAB HIDE     

MAP ON 

MAP OFF

---

TCL documentation

Please refer to Tool Command Language (TCL), for detailed information about TCL.

---

Sample TCL/rec scripts

See QUANTA Script Examples.

---

Binding commands to function keys

QUANTA commands can be bound to function keys on your workstation keyboard. Function keys F3 through F12 may be redefined. Either a single command or a pair of commands can be bound. In the former case, every time the function key is pressed, the command you have associated with the key is sent to the QUANTA command interpreter. In the latter case, the commands are sent alternately to allow toggling.

By default, function key bindings are defined by the file $HYD LIB/function key.dat. To view the default settings, open the Information menu in the menu bar. Select Current Session to open a pull-right menu and select Function Keys. The list of function key bindings is listed in the Textport.

You may print the PostScript file $HYD_LIB/funkey.ps to create a strip showing the default bindings to place above the function keys on your keyboard.

Complete the following exercise to familiarize yourself with the procedure for assigning customized key bindings.

1.   Define function key F5.

Another dialog box is displayed asking:

A third dialog box is displayed, requesting:

> List atom all in the data entry field. 

You have defined key F5.

2.   Define function key F6.

When you complete the last step in defining F5, the dialog box for specifying the function key number to be defined is redisplayed with the number 5 as the default.

The next dialog box is displayed, asking:

How should FK6 behave?

A third dialog box is displayed, requesting:

Enter the command this key will send.

> %Clear ID

The % denotes that the command is a palette selection.

You have defined key F6.

3.   Define function F7.

The dialog box for specifying the function key number to be defined is displayed, this time with the number 6 as the default.

The next dialog box is displayed, asking:

How should FK7 behave?

A third dialog box is displayed, requesting:

Enter the command this key will send.

> VIEW STEREO

Another data entry dialog box is displayed.

> VIEW MONO 

4.   Save your changes to a local directory.

Finish the definition process.

Another dialog box is displayed.

A final dialog box is displayed with choices for saving the changes.

© 2006 Accelrys Software Inc.