Home |  Contact |  Feedback 

Scripting Language

The parser of SPDBV scripting language has been generated with flex and yacc, whose combination allows to build very advanced parsers. The scripting language will be quite familiar for persons who know C or perl. The scripting language supports variables, conditionnal branching, loops, arrays and file access. Subroutines are also supported, but you must be aware that all variables are global. Despite this limitation, it allows to make the scripts more compact and readeable, and can also be used to prepare a kind of "jump table" of your favourite functions that can be executed simply by clicking on their name from the SPDBV interface or from added menus.

The scripts can be stopped at specific points to let users interact with the graphical interface before resuming operation. This allows among other things to access commands not directly available from the script, take parameters from the user input, or execute other script commands not included in the script by typing them directly from the "Execute script command" item of the Edit menu. Scripts can be either loaded as TEXT file (with the open TEXT item of the file menu) or with the "Run Script" item of the file menu. On unix systems, scripts can be passed as the last parameter of the command line (after optional PDB files). The place to post and exchange scripts is on the spdbv mailing list maintained by Prof. Gale Rhodes at

newsgrp.html


As we all like to be polite, scripts must start with "please do" and end with "thank you".
All instructions are terminated with a semicolon.
All information following a # is ignored untill the end of the line.


Data Types:

In the manual, data types appear between <>. These means that a value of the mentionned type is expected (or returned). This value can be obtained from a variable, or provided directly.

Supported types are:

vector example: <1.0,1.0,1.0>
float example: 1.0
int example: 42
string example: "Hello World!"
layer example: "1CRN" (alternately, layers can be referred to by position the first layer loaded is 0 the second 1, etc.
selection example: select in <layer> pos <int> to <int>;
file example:
internal variable example: gCurrentOS

There are two types of variables: script variables (that can be used to store values in scripts) and program variables (internal spdbv variables).

Assigning a value to a script variable is done with

$varname = value;

data types for script variables are attributed implicitely during the assignment.

$X = 1.0; will assign the value 1.0 of type <float> to $X.
$X = 1; will assign the value 1 of type <int> to $X.

Operations on variables are (usually) possible only between variables of the same type, but you can force a value to be of a different type through typecasting. for example:

$X = (float)1; will assign the value 1.0 of type <float> to $X.

Valid typecast are: (int) (float) (string)


Arrays:

Currently, only arrays of <int> <float> and <vector> are supported. The syntax is the following:

$X[<int>] = value;

The type of array is automatically determined by the kind of value you put into it the first time. Memory is allocated dynamically and will only be released when a 'thank you' statement is reached: if you want to get back something (memory), you better be polite ;-)


Operations:

it is possible to add, substract, multiply or divide data types. Some operations are of course not possible (multiplying two strings or two atom selections).

Adding two strings will produce a concatenation.

$X = "Hello" + " World!"; is equivalent to $X = "Hello World!";

In the case of vectors, multiplication is scalar if one of the member is of type <float>:

$X = <1.0,1.0,1.0> * 3.0; will put <3.0,3.0,3.0> into $X or performs a dot product if the operation involves two vectors.

The scalar product can be obtained with the 'X' operator:

$X = <0.0,1.0,0.0> X <0.0,0.0,1.0>;

Floating point and integer variables can be pre/post incremented with ++<var> and <var>++ respectively, or pre/post decremented with --<var> and <var>-- respectively. This is mainly used for loops.

The remainder (modulo) of an integer diviision can be accessed by the % operator as in

print 8 % 3;

which would give 2


Commands: (alphabetically)

PRELIMINARY for version 3.7b1, some commands might not be implemented on all platforms. More commands will be added as needed.

You can find several scripts examples in the scripts directory of the SPDBV distribution. Scripts are named very originally script01.txt script02.txt etc. For each of the following commands, it is mentioned in which example script you can find it. The scripts are designed to progressively introduce more and more features and an other way to learn this language is to study the scripts starting from script01.txt

access acos angle align align_pos asin ask atan build center chain color compute clear close cos delete dist do else export fit get goto groupcount hide if inline is_selected layername max min minimize move mutate name normalize num omega open pause phi PI "please do" print psi readln redraw rename renumber res rotate return rms save selcount select set show silent sin ss stop sub substring superpose system tan torsion "thank you" while zoom

Note for offline use: All example scripts use the network import function to open pdb files. If you are working offline, you sould copy the example files to your local disk, (e.g. the spdbv usrstuff directory) and change the exaple scripts accordingly: Instead of

open pdb from net "1CRN";

it should then look like:

open pdb from usrstuff "1CRN.pdb";


access top

will get the relative accessibility of a residue X, compared to a 100% ref value being computed in an extended conformation in the pentapeptide GGXGG. The returned value is of type <float>.

access(<selection>)

alternately, you can access directly a specific residue from a specific layer, which is faster and handy in loops with:

access(<layer>,<int>)

Related commands: name res ss
Demonstrated in example script: 11


acos top

compute the arc cosine of an expression. Values are in radians

acos(<float>)

related commands: sin asin cos tan atan PI
Demonstrated in example script: none


angle top

compute the angle AOB between three atoms (vectors).

<floatvar> = angle(A,O,B);

where A,O and B are <vector> values Result is returned in degrees.

Related commands: dist get torsion
Demonstrated in example script: none


align top

will make a primary sequence alignment between layers.

align <layer> onto <layer>;

where <string> contains the question to be presented to the user.

Related commands: align_pos
Demonstrated in example script: none


align_pos top

will get the position of a residue in an alignment (in the align window). Returned value is of type <int>.

align_pos(<selection>)

alternately, you can access directly a specific residue from a specific layer, which is faster and handy in loops with:

align_pos(<layer>,<int>)

Related commands: "generate structural alignment" superpose rms fit
Demonstrated in example script: none


asin top

compute the arc sinus of an expression. Values are in radians.

asin(<float>)

Related commands: sin cos acos tan atan PI
Demonstrated in example script: none


ask top

will make a dilaog (yes,no) appear for user feedback.

$int_varname = ask <string>;

where <string> contains the question to be presented to the user.

Related commands: if
Demonstrated in example script: 08 and 10


atan top

compute the arc tangent of an expression. Values are in radians.

atan(<float>)

Related commands: sin asin cos acos tan PI
Demonstrated in example script: none


build top

add various objects such as amino acids, molecular surface.

build in <layer> molecular surface of quality <int>;

Related commands: delete
Demonstrated in example script: none


center top

center view on a selection or on visible groups.

center on <selection>;
center on visible;

Demonstrated in example script: 05 09 13


chain top

will get the chain name of the first selected group found in a selection. Returned value is of type <string>.

chain(<selection>)

alternately, you can access directly a specific residue from a specific layer, which is faster and handy in loops with:

chain(<layer>,<int>)

Related commands: name res ss access
Demonstrated in example script: 11


color top

color some parts of the view. This is functionnally equivalent to the color column of the control panel.

color [in <layer>] <part> of <selection> by <vector>;
color <part> of <selection_variable> by <vector>;
color <part> of <selection_variable> in <color>;

when in <layer> is omitted, the current active layer is amumed.
<part> can be any combination of res,side,label,surface,ribbon,vdw.
<vector> is a rgb color (with intensity of each component are between 0.0 and 1.0.
<color> is any of the predefined kyewords: red green blue yellow white black grey cyan orange purple

example: color in "1crn" ribbon of res "F","N" by <1.0,0.0,0.0>;

Related commands: hide show
Demonstrated in example script: 05 13


compute top

performs various computations on a protein.

compute in <layer> electrostatic potiential using "[coulomb|pb]" with "[partial|full]" charges;
compute in <layer> hbond;
<floatvar> = compute in <layer> energy;

Related commands: discard minimize
Demonstrated in example script: 07 and 09


clear top

** USEFUL but DANGEROUS ** clear a file on disk.

clear file <string>;

where <string> is a variable that contains a filename.

Related commands: open close readln


close top

close a layer or a file.

close <layer>;
close file <file>;

where <file> is a variable that contains a file previously open.

Related commands: open clear readln
Demonstrated in example script: 02 03 and 04


cos top

compute the cosine of an expression. This returns the value in radians.

cos(<float>)
cos(<int>)

Related commands: sin asin acos tan atan PI
Demonstrated in example script: none


delete top

delete selected residues, or hydrogens from a layer.

delete <selection>;
delete in <layer> hydrogen;
delete in <layer> molecular surface;
delete in <layer> electrostatic potential;

Related commands: build
Demonstrated in example script: none


dist top

compute the distance between two atoms (vectors).

<floatvar> = dist(<vector>,<vector>);

Related commands: angle get torsion
Demonstrated in example script: 07


export top

this command allows to save images or pov-ray scenes.

export image as <string>;
export stereo image as <string>;
export pov as <string> [and render];

where <string> contains the filename with full path. Alternately, you can save the file in one of the predifined directories [usrstuff|download|temp] with the following command

export pov in [usrstuff|download|temp] as <string> [and render];

See save for more explanations about path and filemames. note that the [and render option] will open the file for rendering on mac and pc, but will automatically launch pov on unix boxes provided you save the scene in the usrstuff directory.

Related commands: save
Demonstrated in example script: 09


fit top

this command is equivalent to the fit (from selection) command of spdbv.

fit <layer> onto <layer> using <string>;

where <string> contains the method to be used ("CA", "backbone", "all").

Related commands: rms superpose
Demonstrated in example script: none


generate structural alignment top

generate structural alignment;

Related commands: rms superpose fit
Demonstrated in example script: none


get top

can access internal spdbv variables or atomic coordinates, retrieve aa sequences, or capture the current selection status of a specific layer (when modified directly from the graphical user interface). The list of internal variables that can be accessed is provided at the end of this guide.

$sel = get selection of <layer>;
$varname = get <internal variable>;
$vector_varname = get coord <string> of <selection>;
$string_varname = get seq of <selection>;

where <string> contains the 4 characters atom name (for. ex " CA ") and selection a selection.

Related commands: set
Demonstrated in example script: 07 08 09 and 10


goto top

one of the most useful (and controversal although it is one of the rare commands to be wired directly on any chip...) command that allow to continue the execution from a different point of the script.

goto <label>;

Execution will continue immediately after <label>, which must end with a colon. example:

goto elsewhere;
print "Never done";
elsewhere: print "welcome";

Related commands: sub do while return
Demonstrated in example script: none


groupcount top

will return the number of groups in a layer. This is functionnally equivalent to a select all followed by a selcount, athough it is quicker.

$int_varname = groupcount of <layer>;

Related commands: selcount
Demonstrated in example script: 02 03 and 04


hide top

hide some parts from the view. This is functionnally equivalent to the control panel.

hide <part> of <selection>;
hide in <layer> <part> of <selection>;

where <part> can be any combination of res,side,label,surface,ribbon,vdw.

Related commands: show color
Demonstrated in example script: 06


inline>
text
<inline top

This is used in conjunction with the open command to load PDB files directly embedded in the script, which is useful mostly for web servers that need to return a script+pdb file in a single file.

Example:

open pdb INLINE> ATOM 1 N THR 1 17.047 14.099 3.625 1.00 13.79 ATOM 2 CA THR 1 16.967 12.784 4.338 1.00 10.80 ATOM 3 C THR 1 15.685 12.755 5.133 1.00 9.19 ATOM 4 O THR 1 15.268 13.825 5.594 1.00 9.85 ATOM 5 CB THR 1 18.170 12.703 5.337 1.00 13.02 ATOM 6 OG1 THR 1 19.334 12.829 4.463 1.00 15.06 ATOM 7 CG2 THR 1 18.150 11.546 6.304 1.00 14.23 <INLINE;

Related commands: open
Demonstrated in example script: none


is_selected top

is_selected(<layer>,<int>)
is_selected(<int>)

When <layer> is omitted, the current active layer is used. Returned value is of type <int> and is 1 if the group is selected and 0 otherwise.

Related commands: select
Demonstrated in example script: 11


layername top

will return the <string> value of the layer name

<string_var> = layername of <int>;

where int is the relative position of the layer from the first loaded which is number 0, of course.

Related commands:
Demonstrated in example script: none


max top

will return the max value of two numbers or variables.

max of (<float>,<float>);
max of (<int>,<int>);

Related commands: min
Demonstrated in example script: none


min top

will return the min value of two numbers or variables.

min of (<float>,<float>);
min of (<int>,<int>);

Related commands: max
Demonstrated in example script: none


minimize top

performs an energy minimization using n cycles of steepest descent

minimize <selection> with <int> cycles;

Related commands: compute
Demonstrated in example script: 07


move top

move a selection.

move <selection> by <vector>;

where <vector> contains the translation in angstroms.

Related commands: zoom rotate
Demonstrated in example script: 09


mutate top

will mutate an amino acid to another. It is currently not possible to browse the rotamer library in a script.

mutate <selection> to <string>;

where <selection> must contain one valid amino acid (first selected is taken) and <string> contains the one letter code of the new residue.

Related commands:
Demonstrated in example script: none


name top

will get the three letter name of the first selected group found in a selection. Returned value is of type <string> for ex: is 'ALA' or 'ATP'.

name(<selection>)

alternately, you can access directly a specific residue from a specific layer, which is faster and handy in loops with:

name(<layer>,<int>)

Related commands: num res chain ss access
Demonstrated in example script: 11


normalize top

will normalize a vector. Returned value is of type <vector>.

normalize(<vector>)

Related commands: vector operations.
Demonstrated in example script: none


num top

will get the number of the first selected group found in a selection. Returned value is of type <int>.

num(<selection>)

Alternately, you can access directly a specific residue from a specific layer, which is faster and handy in loops with:

num(<layer>,<int>)

related commands: name res chain ss access
Demonstrated in example script: 11


omega top

will get the omega peptidic bond torsion angle for the first selected amino acid found in a selection. Returned value is of type <float> and is returned in degrees.

omega(<selection>)

Alternately, you can access directly a specific residue from a specific layer, which is faster and handy in loops with:

omega(<layer>,<int>)

Related commands: phi psi ss
Demonstrated in example script: none


open top

load a pdb file in the workspace (next available layer).

open [pdb] from "disk|net" <string>;

To be able to use the "net" option, you have to set the correct server address in "Network Preferences". Note that it is possible to omit "pdb" as it is the default value. <string> contains the full filename (see below). The filename must be the absolute path of your file. Unix users will enderstand what I mean, but Mac users might be a little confused.

Alternately, to be cross platform, you can also use one of the predetermined directories:

open [pdb] from usrstuff <string>;
open [pdb] from temp <string>;
open [pdb] from download <string>;


Constructing a full path on a Mac:

name_of_disl:name_of_folder:name_of_subfolder:name_of_subsubfolder:filename

For example, assume you store your pdb files in a folder named 'pdb' located in the 'System' disk. You can access the file '1crn.pdb' like this:

System:pdb:1crn.pdb

As you can see, Mac uses ':' as separator. This is of course different for unix which uses '/' and from windows which uses '\'. In order to make your scripts as portable as possible, I would recommend separating the file name from the path, which will let you (or other users) change just the path (one line) to make a generic script run on thieir machine.

Consider this example:

open "System:pdb:1crn.pdb";
open "System:pdb:1atp.pdb";

it is better rewriten like this:

$path = "System:pdb:"; # change this line to point to your pdb files directory.
open $path + "1crn.pdb";
open $path + "1atp.pdb";


The "open" command also allows to create files or open arbitrary text files for further processing, or allows to open a file as read-only.

$file_varname = open file <string>;
$file_varname = open file <string> for reading;

or allows to open a file as write (CAUTION WHEN USING THIS!).

$file_varname = open file <string> for writing;

or allows to append to a file (CAUTION WHEN USING THIS!).

$file_varname = open file <string> for appending;

In fact, using the full path of your file (directories+filename) is potentially dangerous if for some reason the filename get screwed up. Besides, it is not cross-platform and you likely wish to have your scripts running everywhere, I suggest that you and work with files store the files in your 'usrstuff' directory using the following equivalent commands:

$file_varname = open file <string> in usrstuff;
$file_varname = open file <string> in usrstuff for reading;
$file_varname = open file <string> in usrstuff for writing;
$file_varname = open file <string> in usrstuff for appending;

where <string> must *ONLY* contain the file name (no directory, no path) The open command can also be used to open a text file, which is only useful coupled with the graphical user interface.

open text <string>;
open text <string> in usrstuff;
open seq <string>;

this can be used to load a raw sequence to model. Sequence must be in format FASTA, SWISSPROT or SEQRES.

Related commands: close clear readln inline print save
Demonstrated in example script: all


pause top

will stop the script execution for some seconds.

pause <float>;

Related commands: stop 'thank you' 'please do'
Demonstrated in example script: 05 06 07 09


phi top

will get the phi torsion angle for the first selected amino acid found in a selection. Returned value is of type <float> and is returned in degrees.

phi(<selection>)

alternately, you can access directly a specific residue from a specific layer, which is faster and handy in loops with:

phi(<layer>,<int>)

Related commands: psi omega ss
Demonstrated in example script: 01 02 03 04

 


PI top

return the value of PI.

related commands: sin asin cos acos tan atan
Demonstrated in example script:: none


please do top

initiate a script, and reset all scripts variables. Note that this statement must be on the FIRST line of the script.

Related commands: stop pause 'thank you'
Demonstrated in example script: all


print top

prints a value (string, variable, number etc..) onto stdout or in a spdbv communication dialog.

print on dialog; print on stdout;
print on <file> <expression>;
print <expression>;

where expression is any combination of aritmetic values or concatenation of strings. Note that a newline is printed after each print operation. You might then need to prepare a string (from concatenation) before printing.

Demonstrated in example script: 01 02 03 04 06 07 08 11


psi top

will get the psi torsion angle for the first selected amino acid found in a selection. Returned value is of type <float> and is returned in degrees.

psi(<selection>)

alternately, you can access directly a specific residue from a specific layer, which is faster and handy in loops with:

psi(<layer>,<int>)

Related commands: phi omega
Demonstrated in example script: 03 04


readln top

read the next line from a text file or from a dialog box.

$string_varname = readln from file <file>;
$string_varname = readln from user <string>;

where <file> is a file previously open with the open file command. and <string> is a prompt that will appear in the dialog.

Related commands: open close clear substring
Demonstrated in example script: 04 06


redraw top

will force the main window to be refreshed. Useful only in the interactive mode.

Related commands: show
Demonstrated in example script: 05 07


rename top

rename chain of <selection> as <string>;

will change the chain name of the selected residues.

rename <layer> as <string>;

will change the layer name.

Related commands: renumber
Demonstrated in example script: none


renumber top

renumber <selection> from <int>;
renumber <selection> add <int>;

will change the residue number of selected residues.

Related commands: rename
Demonstrated in example script: none


res top

will get the one letter name of the first selected group found in a selection. Returned value is of type <string> e.g.: 'A' or 'C' or 'D',...

res(<selection>)

alternately, you can access directly a specific residue from a specific layer, which is faster and handy in loops with:

res(<layer>,<int>)

Related commands: num name chain ss access
Demonstrated in example script: 11


rotate top

rotate the view successively around axis x,y,z:

rotate <vector>;

where <vector> contains rotation angles in degrees. This command can also be used to rotate a selection around a specific axis.

rotate <selection> by <float> [deg|rad] around axis <vector> <vector>;

or to do a torsion (rotate atoms downstream a bond around this bond) using the following syntax:

rotate atoms of <selection> by <float> [deg|rad] around bond <string> <string>;

Related commands: zoom move
Demonstrated in example script: 05 06 09


return top

It will resume execution where it was before entering the subroutine. See sub for more explanations

Related commands: goto do while sub
Demonstrated in example script: 08 10


rms top

this command is equivalent to the RMS command of spdbv.

rms of <layer> and <layer> using <string>;
<floatvar> = rms of <layer> and <layer> using <string>;

where <string> contains the method to be used ("CA", "backbone", "all").

Related commands: fit superpose
Demonstrated in example script: 05


save top

save a all or part of pdb files from some layers.

save <layer> as <string>;
save selection of <layer> as <string>;

where <string> contains the full filename (see discussion in open). An alternative set of commands that will save files in predifined directories located under the spddbv main directory is available. Directories can be usrstuff,temp or download:

save <layer> in [usrstuff|temp|download] as <string> ;
save selection of <layer> in [usrstuff|temp|download] as <string> ;

in this case <string> must contain *ONLY* the filename, as the directory is implicit. This is very useful to make scripts portable among the various OS supported (Windows, Macintosh, IRIX and Linux).

Related commands: open
Demonstrated in example script: 06


search top

*This function is not yet available.* allows to search 3D patterns in pdb files.

search in <layer> <string>;
search in <layer> <string> >> <string>;

where the first <string> contains the filename of the 3Dsearch pattern description file, and the second (optional) string appends the output to a file (that might be worth clearing before with the clear command).

Demonstrated in example script: none


selcount top

will return the number of selected groups in a layer.

$int_varname = selcount of <layer>;

Related commands: groupcount
Demonstrated in example script: 06


select top

allow to select specific residues and perform logical operations on them. This can then be used to color or hide residues, among other things.

<var> = select [in <layer>] <selection>;
select <var>;

when [in <layer>] is ommitted, the current active layer is assumed. <var> must contain a selection and <selection> can be any combination of:

all  
none  
water hoh solvent h2o  
strand  
helix  
het will select all HETATM
aa will select all amino acids
nt will select all nucleotides
res <string> residue kind example: res "A", "C", "D"
name <string> residue name example: res "ALA", "OXT", "ATP"
chain <string> residue chain example: chain "A", " "
num <int> residue number
pos <int> residue absolute position in layer (start at 0).
pos <int> to <int> residue range absolute position in layer (start at 0).
seq <string> a sequence (can be a prosite pattern).
within <float> of <selection_var>  

example:

$sel1 = select in "1ATP" res "Y" and chain "I";

It is currently not possible to provide very complex selections in one operation, but this is easily overcomed as selections can be added or substracted: Example:

$sel = $sel1 + $sel2 + sel3 - sel4;

A special case allows to get the current selection state of a layer into a variable. This is useful to capture a selection made directly from the user graphical interface.

$sel = get selection of <layer>;

Related commands: selcount
Demonstrated in example script: all


set top

can set internal spdbv variables or atomic coordinates. The list of internal variables that can be accessed is provided at the end of this guide.

set <internal variable> = $varname;
set coord <string> of <selection> = $vector_varname;

where <string> contains the 4 characters atom name (for. ex " CA ") and selection a selection. It also allows to toggle the backbone representation for a layer to "ca_trace":

set ca_trace [ON|OFF] for <layer>;

Related commands: get
Demonstrated in example script: 07


show top

show some parts from the view. This is functionnally equivalent to the control panel.

show <part> of <selection>;
show in <layer> <part> of <selection>;

where <part> can be any combination of res, side ,label, surface, ribbon, vdw.

Related commands: hide color
Demonstrated in example script: 06 09 13


silent top

can be used in conjunction witht the stop command to prevent any feedback of which line the script was stopped.

silent stop;

Related commands: stop
Demonstrated in example script: 08 10


sin top

compute the sinus of an expression.

sin(<float>) sin(<int>)

This returns the value in radians.

Related commands: asin cos acos tan atan PI
Demonstrated in example script: none


ss top

will get the secondary structure assignment of the first selected amino acid found in a selection. Returned value is of type <string> and is 'h' 's' or 'c'.

ss(<selection>)

alternately, you can access directly a specific residue from a specific layer, which is faster and handy in loops with:

ss(<layer>,<int>)

Related commands: phi psi omega
Demonstrated in example script: 11


stop top

will stop the script in a way that it can be continued from the graphical user interface with "shift" open script. Very convenient if you want to interactively inspect a molecule before resuming the script flow.

Related commands: 'please do' 'thank you' pause silent
Demonstrated in example script: 06 08


sub top

this command is nothing else than a goto that remembers where it was before. It will resume execution where it was before entering the subroutine as soon as a return statement is reached.

sub <label>; <--- note that this must be the only command on a line

Execution will continue immediately after <label>, which must end with a colon.

Note that subroutines must be located at the end of the script (after the thank you statement). All variables beeing global, be very careful when you use them, especially loops variables). Example:

please do sub elsewhere; thank you elsewhere: { print "Is grass really greener here?"; return; }

Related commands: goto do while return
Demonstrated in example script: 08 10


substring top

allow to access substrings within a string by position. Substrings are separated by spaces and numbering start from 0.

$string_varname = substring <int> of <string>;

Examples:

$X = substring 0 of "Hello World!"; will put "Hello" into $X.

$X = substring 1 of "Hello World!"; will put "World!" into $X.

Demonstrated in example script: 04


superpose top

this command is equivalent to the magic fit of spdbv.

<int> = superpose <layer> onto <layer> using <string>;

where <string> contains the method to be used ("CA", "backbone", "all","ss"). This returns the number of solutions as an int.
When "ss" is used, and more than one solution is possible, a temp file "match.txt" is written and a window will be opened with one solution per line.

Related commands: rms fit
Demonstrated in example script: 05


system top

** USEFUL but DANGEROUS **. Executes a shell system command.

system <string>;

This command is supported only for SGI and Linux versions. It is mainly useful to execute a script that will put results into a file that can then be open as read-only with the open file command and read line by line with readln.

Demonstrated in example script: none


tan top

compute the tangent of an expression. Returns the value in radians.

tan(<float>)
tan(<int>)

Related commands: sin asin cos acos atan PI
Demonstrated in example script: none


torsion top

compute the torsion angle ABCD between four atoms (vectors). In other words, the angle between planes ABC and BCD.

<floatvar> = torsion(A,B,C,D);

where A,B,C and D are <vector> values. Result is returned in degrees.

Related commands: dist get
Demonstrated in example script: none


thank you top

polite way of ending a script, which will also free any memory assigned for arrays.

Related commands: 'please do'
Demonstrated in example script: all


zoom top

this command changes the camera position to zoom in or out

zoom <float>;

where <float> is the percent change. 100.0 means no change, 110.0 will do a close-up (enlarge the image by 10%) 90.0 will zoom out (decrease the image size by 10%).

Related commands: rotate move
Demonstrated in example script: 05


Tests (conditionnal execution): top

if (expression test expression) { } else { }


Where test can be

== identity
!= different
> greater than
>= greater than or equal to
< smaller than
<= smaller than or equal to

Demonstrated in example script: 04 06 08


Loops: top

Two kinds of loops are supported that allow to cope with any situation. The higher level for(;;) statement is not implemented:

In the following case, statements will be executed at least once, and more depending on the result of the test.

do { <-- note that statements must start on the next line. statements; } while (expression test expression); <-- note the semicolon

In the following case, statements may not be executed at all, depending on the result of the test.

while (expression test expression) { statements; }

Demonstrated in example script: 01 02 03 04 05 06 07 09

Internal variables: top

This is the list of recognized internal spdbv variables, that can be accessed by the get and set commands. Access to additional variables will be added in the future, as needed.

nbLayer returns the position of the last layer as it starts at 0, when one layer is loaded its value is 0. Its value is 1 for two layers etc.
active_layer returns the position of the currently active layer (the one shown in the control panel).
gDotDensity  
gCurrentOS contains "MAC" "SGI" "LINUX" or "WINDOWS"

The following variables affect the behaviour of alerts presented during the load of a protein:

gReconstructSidechain 0 or 1 reconstruct missing sidechains
gShowConnectAlert 0 or 1 report missing or bad CONECT records
gShowHETATMAlert 0 or 1 report ATOM treated as HETATM
gLoadWater 0 or 1 load solvent molecules
gPartialOccupancyWarning 0 or 1  

Demonstrated in example script: 08 10