[GRASSLIST:1511] Re: multiple terminal sessions

[Glynn Clements]

Ed Davison wrote:

> I have noticed that a user cannot login to a grass session more than
> once and that is understood.
> 
> But, I would like to run multiple xterms to work on various aspects of a
> coverage at the same time.  For example, right now I have a large data
> load taking place but I would like to be able to do other things with
> layers and maps that are not being loaded (the load will likely take
> about 6 hours even on my fast computer).
> 
> I see that in tcltkgrass (which I do not use) that it can launch
> multiple xterms and get things done that way.  
> 
> I have tried this myself and everytime I launch an xterm (either with
> "xterm &" or with "exec xterm") they come up with their own environment
> that is NOT capable of using GRASS.
> 
> How do I do this with just an xterm without having to use tcltkgrass?

First, if you try to run multiple GRASS commands concurrently within
the same mapset, the behaviour is undefined (and may include
corrupting your data). GRASS doesn't perform any locking on the files
which it uses, i.e. the files which comprise the maps, the WIND file
(which stores the current region), $GISRC (which stores various
session parameters such as the active monitor) etc.

Although tcltkgrass spawns xterms for some commands (typically those
which may attempt to interact with the user via a terminal), all
commands are run sequentially; it won't attempt to start a new command
before the previous command has completed.

Having said all of that:

The essential pre-condition for running any GRASS command is that
certain environment variables have to be set appropriately. For a
normal GRASS session, the startup script ($GISBASE/etc/Init.sh) sets
the environment variables and then either spawns a shell (bash, csh
etc) or tcltkgrass.

Apart from setting the environment variables, the startup script also
initialises the session file ($GISRC; normally ~/.grassrc5) with the
database, location and mapset which the user selects. It does one
other thing, which you've noticed, i.e. it creates a lock file
(~/.gislock5) to prevent the user from running multiple sessions
concurrently.

If you want to create a GRASS session (i.e. an environment in which
the various GRASS commands will work) yourself, you should set the
following envirionment variables:

	GISBASE=/usr/local/grass5
	GISRC=$HOME/.grassrc5
	GIS_LOCK=$$
	TCLTKGRASSBASE=$GISBASE/tcltkgrass
	
	GRASS_GNUPLOT=gnuplot
	GRASS_PAGER=less
	GRASS_PERL=perl
	GRASS_TCLSH=tclsh
	GRASS_WISH=wish
	
	PATH=$GISBASE/bin:$GISBASE/scripts:$PATH
	MANPATH=$GISBASE/man:$MANPATH
	LD_LIBRARY_PATH=$GISBASE/lib:$LD_LIBRARY_PATH
	
	PAGER=less
	
	export GISBASE GISRC TCLTKGRASSBASE
	export GIS_LOCK
	export GRASS_GNUPLOT GRASS_PAGER GRASS_PERL GRASS_TCLSH GRASS_WISH
	export PATH MANPATH LD_LIBRARY_PATH
	export PAGER

If you put the above commands into a file, you can read it (with the
built-in shell commands "source" or ".") into an existing shell in
order to enable the use of GRASS commands without having to start a
separate session (the database/location/mapset will be whatever is
currently set in the $GISRC file).

Some of these warrant some additional comments:

GISBASE is the root of the GRASS installation (the default is
/usr/local/grass5, but can be changed at compile time).

GISRC is the name of the session file. If you want to run multiple
concurrent sessions (with different mapsets), each session will have
to use a different file, e.g.

	GISRC=$HOME/.grassrc5.$$

[The shell variable $$ contains the PID of the shell process, so it's
a safe bet for a unique identifier; unless you're trying to spawn
multiple GRASS sessions from a single parent process, in which case
you would need to use something else.]

This file needs to contain definitions for at least GISDBASE,
LOCATION_NAME and MAPSET, e.g.

	GISDBASE: /opt/grass-data
	LOCATION_NAME: spearfish
	MAPSET: glynn

[These are the three values which are entered into the startup
screen.]

GIS_LOCK *isn't* related to the lock file which normally enforces the
one-session-per-user limit. It is occasionally used for locking
additional devices; specifically, v.digit and the digitiser code use
it for locking the digitiser device, and the monitor library uses it
for locking FIFOs (the default is to use sockets rather than FIFOs, so
this is usually irrelevant).

TCLTKGRASSBASE is the root of the tcltkgrass installation, and will
always be $GISBASE/tcltkgrass.

The various GRASS_* variables are used to select certain external
programs, and should be mostly self-explanatory. GRASS_PAGER is the
pager used for displaying large amounts of text; "less" and "more" are
typical settings, although you can use "cat" if you don't want to use
a pager (e.g. if you would rather just use the terminal's scrollback
feature).

IIRC, all GRASS programs should use GRASS_PAGER, but some external
programs (e.g. "man") will use PAGER; it's also possible that some
GRASS programs use it, so it's best to set it anyhow (programs which
use the above variables don't generally bother to implement a fallback
if the variable isn't set).

Adding $GISBASE/bin and $GISBASE/scripts to PATH is essential for the
GRASS programs to be found.

MANPATH is used by "man" to locate manual pages; you may want to set
this in e.g. /etc/profile so that the pages can be read outside of a
GRASS session.

LD_LIBRARY_PATH is used by Linux and Solaris (maybe others) for
locating shared libraries. The above setting is normally only relevant
if you are using a shared GDAL library which is installed in
$GISBASE/lib (AFAIK, this is typically the case for the GRASS binary
distributions).

-- 
Glynn Clements <glynn.clements at virgin.net>