GRASS and Shell

This page contains information about GRASS GIS' own shell setup and use.

For information about scripting for GRASS, please refer to the page Shell scripting.

Automated batch jobs: Setting the GRASS environmental variables

Main article: Working with GRASS without starting it explicitly

This section applies to jobs which shall set the entire GRASS environment. You have to set a couple of variables to enable GRASS command to run (see 'GRASS Batch jobs' below for a solution when you want to run the GRASS job from outside GRASS):

  # Example in bash shell syntax:

  # path to GRASS binaries and libraries:
  export GISBASE=/usr/local/grass64

  export PATH=$PATH:$GISBASE/bin:$GISBASE/scripts
  export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$GISBASE/lib

  # use process ID (PID) as lock file number:
  export GIS_LOCK=$$

  # settings for graphical output to PNG file (optional)
  export GRASS_PNGFILE=/tmp/grass6output.png
  export GRASS_TRUECOLOR=TRUE
  export GRASS_WIDTH=900
  export GRASS_HEIGHT=1200
  export GRASS_PNG_COMPRESSION=1
  export GRASS_MESSAGE_FORMAT=plain

The following variable defines where the GRASS settings file is stored. This can be anywhere on the system. You could also generate the '.grassrc6' on the fly in your script, even with different name. Just indicate it correctly:

  # path to GRASS settings file
  export GISRC=$HOME/.grassrc6

  # The following three settings are only recommended if you will be calling
  # the script from another program - e.g. a PHP web page using system() or exec()
  export HOME=/var/www
  export USER=www-data
  export GROUP=www-data

Now you can test:

  # this should print the GRASS version used:
  g.version
  # other calculations go here ...

You should cleanup internal tmp files like this:

  # run GRASS' cleanup routine
  $GISBASE/etc/clean_temp

  # remove session tmp directory:
  rm -rf /tmp/grass6-$USER-$GIS_LOCK

If this works, you can launch other GRASS commands. The approach works within Shell scripts and also in the command line terminal.

Changing the prompt:

  PS1_BACKUP="$PS1"
  export PS1="GRASS 6> "

Once you are done, you can set it back (see also next hint about unsetting variables):

  export PS1="$PS1_BACKUP"

Unsetting variables after usage:

  Using the "unset VARNAME" command you get rid of it:
  unset GISBASE
  unset GISRC
  ...

Example

• GRASS shell script job to generate a Recent Earthquakes Map (get the grass_earthquakes.sh shell script)

Parallel GRASS jobs

See Parallel GRASS jobs for Grid Engine, PBS etc.

GRASS Batch jobs

Since GRASS GIS 6.4, there is an alternative method to easily run jobs in GRASS from a collection of commands in a shell script file. Just define the environmental variable GRASS_BATCH_JOB with the shell script file containing GRASS (or whatever) commands, preferably with full path. Then launch GRASS and it will be executed. It is best to launch GRASS in -text mode and to provide gisdbase/location/mapset as parameters. The job script needs executable file permissions (chmod on Unix). In order to get readable percentage output during the processing (0..2..4... 100%), we set the environment variable GRASS_MESSAGE_FORMAT to "plain":

Example:

#### 1) PREPARATION
# First we generate a script which contains the command(s) to be executed:
# for convenience, we save the file in our HOME directory
echo "export GRASS_MESSAGE_FORMAT=plain ; v.random mymap3000 n=3000" > $HOME/my_grassjob.sh

# verify the content of the file
cat $HOME/my_grassjob.sh

# make it user executable (this is important, use 'chmod' or via file manager)
chmod u+x $HOME/my_grassjob.sh

#### 2) USING THE BATCH JOB
# define job file as environmental variable
export GRASS_BATCH_JOB="$HOME/my_grassjob.sh"

# run the job
grass64 ~/grassdata/nc_spm_08_grass7/user1
# or
# grass70 ~/grassdata/nc_spm_08_grass7/user1

# switch back to interactive mode
unset GRASS_BATCH_JOB

The grass64 (or grass70) command starts GRASS in the given mapset, executes the contents of the job file and leaves GRASS. Since the normal startup/closure is used, all tmp files are properly removed.

Note: The $HOME variable (or the ~ shortcut) cannot be used in the batch job since the variables are not available here.

Example

• Another set of GRASS shell scripts to run the job to generate another version of the Recent Earthquakes Map (find the setup files in the "batch_processing" tutorials section of the GRASS SVN)

Unattended execution

• GNU_Screen is another extremely valuable tool if you need to detatch and leave long-running processes unattended. It is well worth your time to learn how to use it if you run scripts on remote systems. There are many good tutorials on the web.

Usage:

Run "screen" in the terminal. You will reach again the command line but now in screen mode. Now start GRASS.

- To disconnect from the session press Control-A, Control-D.

- To list your screens type "screen -ls" (to find it back)

- To reconnect with a disconnected screen run "screen -r [identifier]" (the "identifier" you need only if you have several screens running)

Enjoy.

• Along with the "nohup" (no hang-up) command you can login to your machine, launch the job and leave the machine again.

The process will continue after you logged off when you start it with nohup:

       nohup grass64 ~/grassdata/spearfish60/neteler/ &

Receive a notification when finished

Maybe put email notification at the end of 'my_grassjob.sh' using the "mail" or the "mutt" program, for example like this:

       echo "Finished at `date`" > /tmp/done.txt && \
       EDITOR=touch mutt -s "Job done" \
       me@mydomain.org < /tmp/done.txt && rm -f /tmp/done.txt

or like this:

       mail -s "GRASS job $0 finished" me@mydomain.org <<EOF
         GRASS GIS has finished the batch job $0
       EOF

or simply like this:

       echo "GRASS GIS has finished the batch job $0" | mail -s "GRASS job finished" me@mydomain.org

Stupid pet tricks (don't use them!)

Note: This is highly discouraged. Keep fingers off from manually modifying the content of a GRASS GIS mapset (at least don't complain if you break things).

;Quick cd to the MAPSET directory To make a quick little function called 'g.cd' to change into the mapset dir, add this to ~/.grass.bashrc:

g.cd()
{
  MAPSET=`g.gisenv get=MAPSET`
  LOCATION_NAME=`g.gisenv get=LOCATION_NAME`
  GISDBASE=`g.gisenv get=GISDBASE`
  LOCATION="$GISDBASE/$LOCATION_NAME/$MAPSET"
  cd "$LOCATION/$1"
}

With that you can also do like: "g.cd colr/" to get to the color tables directory, or "g.cd .." to get to the LOCATION directory.

Another method would be

  alias g.home='cd `dirname "$HISTFILE"`'

Simpler command completion from command history

Add this to a file called ~/.inputrc in your home dir:

set prefer-visible-bell

# -------- Bind page up/down wih history search ---------
"\e[5~": history-search-backward
"\e[6~": history-search-forward

Then you can type a bit of a command and use PgUp and PgDn to cycle through the command history which matches in a way less clumsy that Ctrl-r. Also it tells to make the shell flash on alarm instead of sending a beep to the speaker (making tab-completion compatible with your office mates).

See also

Generic Shell script tutorials:

• Advance bash-scripting guide
• Bash scripting Tutorial

GRASS Shell script tutorials:

• GRASS Book script examples
• List of important UNIX system commands

Misc:

• Script portability
• Other GRASS environment variables
• GRASS and Python
• Working with GRASS without starting it explicitly