SQS - Simple Queueing System
                      ----------------------------

                        Version 3.1 May, 2011.
                        ------------------------

INSTALLATION
------------

1. Download the file sqs-3.1.tar.gz and unzip and tar it to give the
directory sqs-{version} where {version} is the version number, e.g.
3.1.

2. You can install sqs as root or locally. If you install locally, other
users can still use sqs. If you do not want that, install locally and
then alter the permissions on the scripts in $bindir and on the
directory $sqsdir.

3. Edit sqs.pm. There are two ways to do this. The first, of course, is
the direct use of an editor. The second uses a script called
"config-sqs", but needs the Term::ReadKey module. The latter method is
particularly usefull for making small changes, once you are familiar
with the system. With both methods, the first time is the most
difficult. The "config-sqs" script generates a sqs.pm file with none of
the comments in the original. It is therefore a good idea to save a copy
of the original sqs.pm as, say "sqs.pm.orig", but not "sqs.pm.save" as
that file is created by "config-sqs". There is a version of
"sqs.pm.orig" in the release which is good starting point.

   If you are going to use "config-sqs", you must have the Term::ReadKey
module, and you should check that the first line correctly identifies
where your perl is.

   Edit sqs.pm or run config-sqs. Everything you add is a name, a path
or a number. Do not use any odd characters in names. Keep to letters or
mumbers, although you can use "-" and "_". 

You must change each variable or confirm they are already correct:-

   '$noofqueues'   Set to the number of queues.

   For each queue, you have to define the appropriate element of the
following five arrays:-

   '@queue'        The queue name.

   '@maxqu'        For each queue set to the maximum number of jobs that can 
                   run at any one time. If set to '0', the queue is defined
                   as a general queue, which submits the job to one of the
                   other queues, that are designated as being a pool queue, 
                   selected to have the lowest load.
 
   '@maxperuser'   For each queue set to the maximum number of jobs any one user 
                   can run at once in the given queue. This is useful on dual 
                   processor machines where setting $maxqu = 2 and 
                   $maxperuser = 1 allows each user to run jobs that depend 
                   on the output from the previous job.

   '@quhost'       Set to the hosts, as returned by `hostname -s`, for the
                   machines to which the queues are linked.

   '@pool'         Set to '1' if queue is in the pool to be selected by
                   a general queue.

   '@web'          Set to '1' if queue is a web use queue, and to '0' otherwise.
 
   You then have to define the following directories:-

   '$sqsdir'.      This points to where the 'sqs.users', 'sqs.id', pid files
                   queue files and 'sqs.log' files will go. This directory will 
                   be created if it does not exist. Check sqs.pm using the 
                   instructions there. It has to be world executable.

                   For a local install, edit sqs.pm as directed in that file.
                   $HOME/.sqs is a good choice for $sqsdir, but note you must
                   expand $HOME so it is an absolute path, otherwise other users
                   look in their own home directories, not yours.

   '$bindir'.      This points to where 'install.pl' will put the scripts and sqs.pm. 
		   For a root install, this should probably be /usr/local/bin, 
                   but it can be different. The same applies as for $sqsdir. This 
                   is set in sqs.pm. Read that file carefully as for $sqsdir. 
                   Note you must use a full path for $bindir, not $HOME, to allow 
                   other users to use SQS. $bindir is created if it does not exist.

                   Note that '$bindir' must be on the path of all users of sqs.

    '$mandir'.     This points to where the man pages will be installed,
                   typically /usr/local/man for a root install and
                   $HOME/man for a local install. The man pages are put
                   into $mandir/man1. Again you must expand out $HOME in
                   sqs.pm. If this is a local install, each user must
                   add $mandir to their $MANPATH. If you define $mandir = ''
                   the man pages will never be installed.

   If you wanting to inspect and modify queues on remote machines, you
have to define some variables for these machines. 
   
   If you are not going to configure for remote machines, you must still
define null values for these variables. If you are using 'config.sqs'
this will be done automatically. If you are editing by hand, take care
to leave the assignments of three variables in this section to null or
zero as in sqs.pm.orig.

   If you are going to configure for remote machines, you must set:-

   $noremote       The number of remote machines you are defining, i.e.
                   the size of the lists below.

   @remotealias    A list of aliases for the remote machines. These are
                   true aliases, used only by the user in sqs commands.

   @remotehosts    A list of host names that will reach the remote host,
                   such that ssh 'host name' will work. An example is
                   ('monster','xxx.edu','bduke@scratchy.cs.ntu.edu.au').
                   The third needs the username as it is different from
                   the one on the home machine. The first does not need
                   the full address as it is on a home network. Different 
                   users on the same machine can be defined as separate
                   remote machines here. See sqs.pm.orig for more
                   details.

   The next section defines $wait, @psexe and @psflag. On linux
$psexe[$i] is always 'ps' and $psflag[$i] is usually -U. On Cygwin, it
should be changed to 'procps' and $psflag[$i] should be set to "-f -U".
$psflag[$i] and $psflag[$i] are arrays to be set for each queue.

   If you are going to use SQS for submitting jobs from web scripts, you
need to set some variables here. 

   If you are not going to configure for web use, you must still define
null values for these variables. If you are using 'config.sqs' this will
be done automatically. If you are editing by hand, take care to leave
the assignments of three variables in this section to null as in
sqs.pm.orig.

   If you are going to configure for web use, you must set:-

   'webhost'       The short hostname, such as 'magog'.

   'webuser'       The user name for the web server, such as 'wwwrun',
                   'nobody' or 'apache'.

   'webserver'     The long hostname, such as 'magog.vcp.monash.edu.au'.

4. Edit 'install.pl' so that the first line is correct for where Perl is
   on your system. 

5. Run:-

   ./install.pl 

   For a root install, you must be root to do this.

   This will edit the scripts and install them, and 'sqs.pm', in $bindir.

   It then installs 'sqs.id', 'sqs.log', the queue files, README and the
man pages. 

6. A call:-

   ./install.pl 'script name'

   will install just a single script.

   Calls:-

   ./install.pl perl
   ./install.pl sqs.pm
   ./install.pl README
   ./install.pl man

   installs just the perl scripts (useful if you want to just update the
scripts and leave the queues intact, although take care - an update may
have a different format for the queue files if a new feature has been
added), the sqs.pm configuration file, the README file and all the man
pages respectively.

   A call ./install.pl queue {queue-name} will install the queue file
for queue {queue-name}. This is necessary if you alter sqs.pm to add new
queues.

7. You can call install.pl as './install.pl -u' to uninstall everything.

8. Web pages giving some information on SQS and web access to the README
files, this INSTALL file, and the ChangeLog file are available in the
htdocs directory and are installed on http://sqs.sourceforge.com. The
five text files are updated in the htdocs directory when you run a full
install.
 
9. You may now want to write some scripts that simplify calling 'qsub'
for specific types of jobs. These are generally bash scripts that are
much more complex than the simple Perl scripts 'qexample' and
qexample.simple discussed in the README file. Our script for running the
computational chemistry code, Gaussian03, is called 'sub_g03' and is:-

   #!/bin/bash
   # To use for Gaussian98 or Gaussian09 change '03' to '98' or '03'
   # throughout.
   cat > $1.job << END
   cd $PWD
   rm -f core
   g03 $1
   END
   chmod 0775 $1.job
   qsub -d -q molecule $PWD/$1.job > /dev/null

   If you are running Gaussian03 on a cluster machine with SQS, you have
to add a few lines, that are normally in the .bash_profile file. These
ensure that the Gaussian variables are set. This version also has the
queue as the 2nd parameter, and uses the queue name to define the
scratch directory. We have modified g03.profile, so that it does not add
the Gaussian directories to the path if they are already there.  This
prevents the path from steadily getting longer.

   #!/bin/bash
   # To use for Gaussian98 or Gaussian09 change '03' to '98' or '03'
   # throughout.
   cat > $1.job << END
   cd $PWD
   export g03root="/home/qchem"
   . \$g03root/g03/bsd/g03.profile
   export GAUSS_SCRDIR="/scr/$2"
   rm -f core
   g03 $1 
   END
   chmod 0755 $1.job
   qsub -d -q $2 $PWD/$1.job > /dev/null

   Our script for running the computational chemistry code, Gamess, is
called 'sub_gam' and is:-

   #!/bin/bash
   cat > $1.job << END
   cd $PWD
   rm -f $1.dat
   rm -f $1.irc
   rungms $1 > $1.log 
   END
   chmod 0775 $1.job
   qsub -d -q molecule $PWD/$1.job > /dev/null

   These scripts are available in the scripts sub-directory. There are
other scripts including 'sub_g03_full' which allows you to add '-h'
and/or '-p priority' as arguments of sub_g03 after the job and queue.
Others relate to remote and cluster jobs.

-----------------------------------------------------------------------------

Brian Salter-Duke          b_duke@bigpond.net.au          May, 2011.