The script option

Introduction

Often you want to start a session many times in a row with a fixed set of commands. WHAT IF offers the possibility to store these commands in a so-called script file. The general command SCRIPT activates this option. You will have to provide a file with valid WHAT IF commands in it. Here all commands, and answers to WHAT IF questions must be present in the correct order, and without one single error.

If the SCRIPT option is activated, the program opens the script file. From that moment on the INPUT routines in WHAT IF will only read input from the script file, and no longer from the terminal. The prompts and answers that are read from the script are displayed on the screen in lines marked "SCRIPT>>>>>" and "SCRIPT<<<<<". Once End Of File on the script is reached, the prompt to the question is displayed on the screen, and normal input is resumed.

A useful exception to this rule is when the line that is read from the script reads "@HUMAN some text". When the keyword "@HUMAN" is encountered in a script file, WHAT IF will ask the question to the person working at the terminal instead. If extra text is supplied after the "@HUMAN" option, that text is used as the prompt instead of the standard prompt: in one of examples below "mutate residue" will be printed as the prompt. This makes "customizable" scripts easy to make.

Lines in a script that start with a number sign (#) are not interpreted by WHAT IF. You can use them to write comments for human readability of your script files.

For the automatic creation of a script, see the option AUTOON.

Lines that start with a dollar sign ($) are used by the SCRIPT option for special purposes (see below).

Startup scripts (STARTUP)

Sometimes you find yourself always typing the same commands every time you restart WHAT IF. For this goal WHAT IF has the feature of automatic startup scripts. When you first start WHAT IF it looks whether a file STARTUP.FIL exists in the current directory. If yes, it is executed as a script. You could use this in a project directory to load the molecule that you are working on, or put a RESSOU or RESSTA command in there so that you automatically resume your saved session (like the program "O" does).

If the STARTUP.FIL file does NOT exist, WHAT IF looks in your login directory for the file ".whatifrc", and execute that instead (notice that the name of this file starts with a dot (.), so you won't see it every time you do "ls"). In no case will both STARTUP.FIL and .whatifrc be executed.

Examples (SCRIPT)

A script should hold a series of valid WHAT IF commands. Scripts are understood easiest from examples. Several examples are presented here. Many more examples are found in the directory called tutorial.

Example 1

The following is an example for a script file to restart a WHAT IF session. Let us assume that you already read some molecules and went to the GRAFIC menu to look at them. Now you want to re-initialize the soup, you want to read the files X.PDB and Y.PDB, and you want to put both colored by atom type at the screen.

Your script file should then look like (without the texts starting with the esclamation signs of course):

SOUP           !\
INISOU         ! or simply combine these three by %INISOU
END            !/
GETMOL         ! read the first file
X.PDB          ! file name
X              ! set name
# This is a comment
GETMOL         ! read the second file
Y.PDB          ! file name
Y              ! set name
COLOUR         ! here you see again that the color commands are embedded
COLATM         !   between the command to go to, and the command to leave
ALL            !   the COLOUR menu.
END            !
INIT -1        ! Delete the graphics objects
SHOALL 1 Q     ! And create the new display

Example 2

In the second example we will do a lot of calculations. First, the SOUP is initialized. Then 1crn.brk is read in. The sequence is listed, the secondary structure determined, and finally, some accessibility calculations are done and the results are written in a log file.

SOUP           ! Go to the soup menu
INISOU         ! Initialize the soup
GETMOL         ! Read a PDB file
1crn.brk       ! File name
CRN            ! Set name
LISTR          ! List the residues
SHOHST         ! Determine secondary structure 
ACCESS         ! Goto the accessibility menu
PARAMS         ! Goto the sub menu for accessibility parameters
ACPREC         ! Set the accessibility precision
4              ! 0 is very fast, 2 is default, 4 is slow but precise
ACCTYP         ! Set the type of calculations
1              ! 0=molecular surface; 1=accessible surface
END            ! Return to the accessibility menu
INIACC         ! Initialize all accessibilities
SETACC         ! Go calculate accessibilities
ALL            ! Calculate for all residues
1              ! Molecule 1 will be used as 'environment'
N              ! We do not want to create a dot file for graphics
DOLOG          ! Open the log file
ACCESS.OUT     ! Name of the log file
Y              ! YES, we want to write a comment in the log file
My comment     ! Any comment up to 79 characters allowed
Second comment ! Second comment line
               ! Empty line (or 0) to indicate end of comment
SHOACC         ! List the accessibilities per residue
11 20          ! Residues to be listed
22             ! Residues to be listed
0              ! No more residues to be listed
ANASRF         ! Analyze the total surface
M1             ! Analyze molecule 1
NOLOG          ! Close the log file

Example 3

We'll now mutate a single residue in a protein stored in the file X.PDB in the current directory. The resulting new protein will be saved as mutation.pdb in the current directory. This example shows the use of the @HUMAN trick to make a script interactive.

DOLOG                   ! We want to make a log-file of our work
mutation.log            !   named mutation.log
N                       !   without any comments
GETMOL X                ! Read in the molecule
                        !   with the default set name X
MUTATE                  ! Starts the mutation
@HUMAN Residue mutate:  ! Get the residue from the terminal
Y                       ! Use the experimental version
                        ! Show the possibilities by typing nothing
@HUMAN Mutate to:       ! Get the new residue from terminal
%MAKMOL                 ! Save the resulting coordinates
X.PDB                   !    Header from X.PDB
mutation.pdb            !    Into mutation.pdb,
Mutated file by WHAT IF !    comment
0                       !    No more comments
m1                      !    molecule 1
n                       !    and nothing else
NOLOG                   ! Close the logfile
FULLST Y                ! End WHAT IF

Example 3

The following example shows how scripts can use scripts as subroutines.


&TEXT
Between the command $TEXT and $ENDTEXT you can put some
text that will be put literally in the text window. At the end
of this text you get the `Give return to continue` prompt
&ENDTEXT
# Set language to Dutch  ! This is a comment
DUTCH
CRIPLE                   ! Make WHAT IF cripple for tutorial purposes
SMPLON                   ! MOL-objects and items are set automatically
SOUP 
  INISOU                 ! Indenting is allowed in scripts
  START X                ! Reads in the standard demo molecule (crambin)
END
# Now we will do graphics! This is a comment
GRAFIC 
  INIGRA                 ! Initialize the graphics window
  VIEWOP  
  SCRIPT                 ! Here we call a script from a script
  SHOALL                 ! SHOALL is a script (see below)
  SCRIPT
  SHOHBO                 ! SHOHBO is a script see below
  ITMADM 
    OBJON 1              ! Make sure MOL-object 1 is on upon GO
    OBJOFF 2             ! Make sure MOL-object 2 is off upon GO
  END
  CENTER GO              ! Center graphics screen and pass control to it
  SMPLOF                 ! Prompt user again for MOL-objects and MOL-items
END

This script calls the scripts SHOALL and SHOHBO. And these in turn call again a script called COLATM. You better make sure that scripts do not call each other in two directions. Also, you should not make the tree of scripts that call each other deeper than four calls. The subroutine scripts given below explicitly require that the SMPLON option was used.

# Script subroutine SHOALL
#
# Colour all atoms by atom type and display them
#
  SCRIPT                 ! Call the script called COLATM (see below)
  COLATM 
  SHOALL                 ! This is command SHOALL, not the script!

# Script subroutine SHOHBO
#
# Display all hydrogen bonds coloured by atom type 
#
  SCRIPT                 ! Call the script called COLATM (see below)
  COLATM 
  HBONDS                 ! Go to the hydrogen bonds menu
    SHOHBO ALL ALL N     ! Execute the SHOHBO command
  END                    ! Return to the menu where we came from

# Script subroutine COLATM
#
# Colour all atoms by atom type 
#
  COLOUR                 ! Go to the colour menu
    COLATM ALL           ! Colour all atoms
  END                    ! Return to the menu where we came from

Repeating a script over many files (LSCRIP)

The command LSCRIP will cause WHAT IF to prompt you for a file with file names and for a script file. The default for the file with file names is SCRIPT.FLS. This file should hold the names of PDB files, including the full path. Use only one file name per line.

The second file, the normal script file, has as default name SCRIPT.FIL, and is described above (see SCRIPT).

WHAT IF will start executing the INISOU command (see INISOU in the SOUP menu), and will thereafter run the script for each file listed in the file with file names.

Be aware that the script is executed over-and-over again. So, if for example, you create a log-file in the script, and close it in the script, WHAT IF will for every new PDB file create this log-file and close it again, thus overwriting the log-file from the previous PDB file every time. In such cases, you should open the log-file before the LSCRIP option, and close it afterwards by hand.

Script related commands

Several commands are very handy in conjunction with scripts. For example the command-renaming options can be very useful, because they can almost be used as subroutines in script files. (See the chapter on general commands).

Pausing a script (WAIT)

The command WAIT will cause WHAT IF to prompt you for the duration of a pause. Nothing will happen during this pause. This option is, of course, only useful in scripts; especially if long demo scripts are created where the audience is supposed to follow what happens.

Picking options from a script file (BUTON)

The command BUTON will activate one of the 36 options at the bottom of the screen. Be aware that usage of this option can create total catastrophes!

The boxes are labeleb 1 - 12, 13 - 24, and 25 - 36 for the top, middle and bottom ror respectively. So, MOL0 can be activated with `BUTON 25` and the labels can be switched on with `BUTON 36`.

Picking options from a script file (BUTOF)

The command BUTOF will de-activate one of the 36 options at the bottom of the screen. Be aware that usage of this option can create total catastrophes!

The boxes are labeleb 1 - 12, 13 - 24, and 25 - 36 for the top, middle and bottom ror respectively. So, MOL0 can be de-activated with `BUTON 25` and the labels can be switched off with `BUTON 36`.

Switching MOL-objects on (OBJON)

The command OBJON is the text window equivalent of switching a MOL-object on by picking the MOL* button. If the MOL-object was already on, nothing will happen.

Switching MOL-objects off (OBJOFF)

The command OBJOFF is the text window equivalent of switching a MOL-object off by picking the MOL* button. If the MOL-object was already off, nothing will happen.

Automatic MOL-object numbers and MOL-item names (SMPLON)

The command SIMPLE toggles the mode in which WHAT IF automatically chooses MOL-object numbers and MOL-item names on/off. Since in scripts it is often difficult to remember whether the SIMPLE mode is on or off, the commands SMPLON and SMPLOF are added. SMPLON toggles the SIMPLE mode on. If it was on already, nothing happens. SMPLOF toggles the SIMPLE mode off. If it was off already, nothing happens.

Manual MOL-object numbers and MOL-item names (SMPLOF)

SMPLOF does the oposite of SMPLON (see SMPLON).

Automatic MOL-object numbers and MOL-item names (SIMPLE)

The command SIMPLE toggles the mode in which WHAT IF automatically chooses MOL-object numbers and MOL-item names on/off. See SMPLON.

Disabling interactive options (CRIPLE)

The command CRIPLE will partly/selectively cripple WHAT IF. Many of the interactive options will no longer work after this command was issued. This seems a rather stupid option, but it can be very useful for tutorial and teaching scripts because in these cases you normally want to reduce the number of possibilities offered to the user.