5 Script Files

Using script files to control map3d has numerous advantages, for example:

complex layouts and specifications can be created and then held for later reuse,
execution of the program reduces to a single word that starts the script,
scripts are shell programs and can include logic and computation steps that automate the execution of the program; the user can even interact with the script and control one script to execute many different actions.

5.1 What are script files?

A script files are simple programs written in the language of the Unix shell. There are actually several languages, one for each type of shell, and the user is free to select. At the CVRTI we have decided to use the Bourne shell for script programming (and the Korn shell for interactive use) and so all scripts will assume the associate language conventions. The shell script language is much simpler to use and learn than a complete, general purpose language such as C or Fortran, but is very well suited to executing Unix commands; in fact, the script files consist mostly of lists of commands as you might enter them at the Unix prompt. Even more simply, a script file can consist of nothing more than the list of commands you would need to type to execute the same task from the system prompt.

5.2 How to make script files

Script files are simple text files and so are usually created with an editor such as emacs. You can, however, also generate a script file from a program, or even another script. But all script files can be read and edited by emacs and this is the way most are composed. To learn about the full range of possibilities in script files requires some study of a book such as ``Unix Shell Programming'' by Kochan and Wood but the skills needed to make map3d script files are much more modest; any book on Unix will contain enough information for this. The instructions and examples below may be enough for many users. Here are some rules and tips that apply to script files:

5.2.0.1 Use a new line for each command

This is not a requirement but makes for simpler files that are easier to read and edit. If the command is longer than one line, then use a continuation character ``
'', e.g.,backslash


         map3d -f geomfilename.fac \

               -p potfilename.data \

              -cl channelsfilename

Make sure that there are no characters (even blank spaces) after the continuation character!!! This has to be the most frequent error when the script file fails to run or stops abruptly.

5.2.0.2 Make script files executable

Script files can be executed by typing . scriptfile but the simplest thing is to make then executable files so that they work simply by typing their names. To do this, use the chmod command as follows:


         chmod 755 script_filename

5.2.0.3 Use the .sh extension for scripts

This convention makes it easy to recognize shell scripts as such, but also invokes some editor help when you edit the file in emacs. The mode will switch to shell (much like Fortran or C mode when editing programs with .f and .c extensions) and has some automatic tabbing and layout tools that can be helpful.

5.2.0.4 Variables in scripts

The shell script is a language and like any computer language there are variables. To define a variable, simply use it and equate it to a value, e.g.,


         varname=2

         varname="some text"

         varname=a_name

Do not leave any spaces around the ``='' sign or the command will fail and set the variable to an empty string. Once defined, the variables can be used elsewhere in the script as follows:


         geomdir=/u/macleod/torso/geom

         geomfile=datorso.fac

         datafile=dipole.data

         map3d -f ${geomdir}/${geomfile} -p $datafile

The curly braces are required when the variable name is concatenated with other text of variable names but is optional otherwise. To concatenate text and variables you simply write them together (e.g., geomdir/geomfile.pts concatenates the two variables with a ``/'' and the extension ``.pts''.

5.2.0.5 Environment variables in scripts

All the environment variables are available and can be set in the script. For example:


         mydir=${HOME}

sets the variable $mydir equal to the user's home directory. Likewise,


         MAP3D_DATAPATH=/scratch/bt2feb93/

         export MAP3D_DATAPATH

defines and ``exports'' the environment variable used by map3d to find .pak files.

5.3 Examples

Below are some sample scripts, from simple, to fairly complex:

5.3.0.1 Set the geometry, data, and window size and location


         map3d -f ${HOME}/torso/geom/dal/daltorso.fac \

               -as 100 500 300 700 \

               -p ${HOME}/maprodxn/andy3/10feb95/data/cooling.data \

               -s 1 1000

5.3.0.2 `map3d-tank1.sh`, included with this distribution


       MAP3D=../map3d

       GEOM=../geom/tank

       DATA=../data/tank



       $MAP3D -nw -f ${GEOM}/25feb97_sock.fac \

               -p ${DATA}/cool1-atdr_new.data@1 -s 1 1000 \

               -ch ${GEOM}/sock128.channels \

               -f ${GEOM}/25feb97_sock_closed.geom \

               -p ${DATA}/cool1-atdr_new.data@2 -s 1 1000\

               -ch ${GEOM}/sock128.channels

5.3.0.3 `map3d-tank2.sh`, included with this distribution


       MAP3D=../map3d

       GEOM=../geom/tank

       DATA=../data/tank



       $MAP3D -nw  -f ${GEOM}/25feb97_sock.fac \

               -as 200 600 400 800 \

               -p ${DATA}/cool1-atdr_new.data@1 -s 1 476 \

               -at 200 600 200 420 -t 9\

               -ch ${GEOM}/sock128.channels \

               -f ${GEOM}/25feb97_sock_closed.geom \

               -as 590 990 400 800 \

               -p ${DATA}/cool1-atdr_new.data@2 -s 1 476 \

               -at 590 990 200 420 -t 126 \

               -ch ${GEOM}/sock128.channels

5.3.0.4 `map3d-torso1.sh`, included with this distribution


       MAP3D=../map3d

       GEOM=../geom/torso

       DATA=../data/torso



       $MAP3D -f ${GEOM}/daltorso.geom -p ${DATA}/dipole2.data -s 1 6

5.3.0.5 `map3d-torso2.sh`, included with this distribution


       MAP3D=../map3d

       GEOM=../geom/torso

       DATA=../data/torso



       $MAP3D -f ${GEOM}/daltorsoepi.geom@1 \

               -p ${DATA}/p2_3200_77_torso.data -s 1 200 \

               -f ${GEOM}/daltorsoepi.geom@2 \

               -p ${DATA}/p2_3200_77_epi.data -s 1 200

5.3.0.6 Set some environment variables, then layout the whole display


       #!/bin/sh

       # A script for the spmag 1996 article

       #

       ######################################################################

       map3d=/usr/local/bin/map3d

       map3d=${ROBHOME}/gl/map3d/map3d.sh

       MAP3D_DATAPATH=/scratch/bt26mar91pack/

       export MAP3D_DATAPATH

       echo "MAP3D_DATAPATH = $MAP3D_DATAPATH"

       basedir=/u/macleod/maprodxn/plaque/26mar91

       $map3d -b -nw \

               -f $basedir/geom/525sock.geom \

               -as 150 475 611 935 \

               -at 150 475 485 610 -t 237 \

               -p $basedir/data/pace-center.data@1 \

               -s 65 380 \

               -f $basedir/geom/525sock.geom \

               -as 476 800 611 935 \

               -at 476 800 485 610 -t 237 \

               -p $basedir/data/pace-center.data@1 \

               -s 65 380 \

               -f $basedir/geom/525sock.geom \

               -as 150 475 176 500 \

               -at 150 475 50 175 -t 237 \

               -p $basedir/data/pace-center.data@1 \

               -s 65 380 \

               -f $basedir/geom/525sock.geom \

               -as  476 800 176 500 \

               -at  476 800 50 175 -t 237 \

               -p $basedir/data/pace-center.data@1 \

               -s 65 380

Rob Macleod 2004-04-08