*******************************************************************************
*                                                                             *
*                          Network Job Control (NJC)                          *
*                                                                             *
*                               R E A D M E                                   *
*                                                                             *
*                   Copyright (c) Joerg-R. Hill, April 1992                   *
*                                                                             *
*******************************************************************************

The Network Job Control (NJC) system is designed to manage jobs in a UNIX
(TCP/IP) network. It enables the users to submit jobs to all hosts in the
network without having to login. The Network Job Control system works with
a queue so that jobs can be submitted whenever the user wants and the job
will run whenever a machine is idle.
The programme was tested on the IBM RS6000 under AIX 3.2.x, on a number of
Silicon Graphics machines under IRIX, and on Linux (Kernel versions 1.2.13
and 2.0.27). With other UNIX versions some adjustments mainly concerning
the include files may be necessary. Contributions are welcome.

Network Job Control, Copyright (C) 1997  Joerg-Ruediger Hill

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.

CONTENTS
========
Check that you have the following files:
-rw-r-----    1 jrh      users      17982 Sep 21 18:53 LICENSE
-rw-------    1 jrh      users       8318 Sep 22 10:33 README
drwxr-xr-x    2 jrh      users        512 Sep 22 10:08 man
-rw-r--r--    1 jrh      users        805 Sep 22 10:37 queue.cfg
-rw-rw-rw-    1 jrh      users          0 Sep 21 17:22 queue.running
-rw-rw-rw-    1 jrh      users          0 Sep 21 17:22 queue.waiting
-rwxr-xr-x    1 jrh      users       1941 Sep 22 10:33 rmjob
drwxr-x---    2 jrh      users        512 Sep 22 10:43 source
-rw-r--r--    1 jrh      users          0 Sep 22 10:36 submit.deny

./man:
total 30
-rw-r--r--    1 jrh      users        769 Sep 21 17:26 queuec.1
-rw-r--r--    1 jrh      users       5253 Sep 21 17:33 queued.1
-rw-r--r--    1 jrh      users       8276 Sep 21 17:37 submit.1

./source:
total 206
-rw-r-----    1 jrh      users       2949 Sep 22 10:31 Makefile
-rw-r-----    1 jrh      users       1300 Sep 22 10:39 checkpids.c
-rw-r-----    1 jrh      users       2527 Sep 22 10:39 error_msg.c
-rwxr-x---    1 jrh      users       1826 Sep 22 10:32 getmachine
-rw-r-----    1 jrh      users       1764 Sep 22 10:40 queue.h
-rw-r-----    1 jrh      users       4729 Sep 22 10:40 queuec.c
-rw-r-----    1 jrh      users      14552 Sep 22 10:41 queued.c
-rw-r-----    1 jrh      users       7660 Sep 22 10:32 read_pids.c
-rw-r-----    1 jrh      users      13043 Sep 22 10:42 startjob.c
-rw-r-----    1 jrh      users      45637 Sep 22 10:42 submit.c
-rw-r-----    1 jrh      users       4665 Sep 22 10:43 util.c
-rw-r-----    1 jrh      users       1627 Sep 22 10:43 xdr.c

INSTALLATION
============
The installation requires super user privilege.
1) Log in as root.
2) Choose a directory for NJC (note: it must reside on a NFS
   file system which is mounted on all hosts which shall be
   included in the job management)
3) Edit the queue.h file. There is a line at the beginning

   #define NJCPATH "/users/njc"    /* directory where NJC is located */

   Change this line so that NJCPATH contains the correct path for your
   installation. Have a look at the define's of MAXLENHOSTNAME,
   MAXHOSTS and MAXPROCESS. Adjust these if you need.
4) If you are running one of the operating systems mentioned above
   skip to 5).
   If you are running another operating system as mentioned above you
   have to look into Makefile and to change getmachine so that the
   options necessary for your system are set (this is explained in
   Makefile).
5) Make the system by typing: make all
   This will make you one version of each of the programmes queued, queuec
   and submit. If you have a heterogenous network (hosts with are not binary
   compatible) you have to make the queuec and the submit programme for
   each of your machines. A good way to do so is to rename the programmes
   e. g. submit.ibm or queuec.iris (which is automatically done by make)
   or whatever convenient. Then remove all object files by typing:
   make clean
   and make the submit and queuec programme on the other machines by
   typing: make submit
   and:    make queuec
6) Adapt the queue.cfg file. It has to contain the names of all hosts in the
   network you want to use, the number of jobs, the maximum number of jobs,
   the nice value and the starting method for a job. You need one machine as
   server. It is a good idea to put the entry for the server as the first one
   in the queue.cfg file. The number of jobs specifies how many jobs can run
   simultanously on the corresponding host. The maximum number of jobs
   specifies the upper limit for the number of jobs (every user can change
   the number of jobs between 1 and the maximum number of jobs). The nice
   value specifies the nice value for running the jobs. These three parameters
   can be changed in the running NJC system by means of submit.
7) Start queued by typing: queued
   at the server.
   (NOTE: Don't wonder if the system prompt appears immediately after
   this, you started a daemon process which runs in background)
8) On every machine which is registered in the queue.cfg file
   (including the server) type: queuec
   (NOTE: Don't wonder if the system prompt appears immediately after
   this, you started a daemon process which runs in background)
   It may happen that it will take some time and then you will
   get a message like this:
   queuec: WARNING: Cannot contact server. Retrying ...
   This message means that the client does not find a server among
   the machines which can be found in the queue.cfg file. Maybe you
   forgot to start queued on one of these machines or there are
   some problems with your network. Queuec will try to find a server
   until one is responding, you can only use the kill command to stop
   it.
9) When the server and all clients are running you can issue a
   submit -s. You will see what you have specified in the queue.cfg
   file and a test result of the whole NJC. On Linux I have experienced
   problems using submit in a xterm. Submit uses the (n)curses library
   to format its output. If TERM is set to xterm submit restores at
   the end the contents of the window and overwrites its own output.
   If TERM is set to vt102 (start xterm with: xterm -tn vt102) every-
   thing works fine.
10) Enjoy NJC.

For further details see the manual pages. You should copy these to
/usr/man/man1. Then you can use: man queued or man submit
(NOTE: You need the nroff (groff) command for this).

The Network Job Control system runs in our network made from IBM RS6000
and Silicon Graphics workstations without problems and very stable
and is heavily used. It has recently been ported (well, recompiled) to
Linux and seems to work there equally well. Experiences with other UNIX
versions (e. g. an extension of getmachine for these systems are welcome.

--------------------------------------------------------------------------------
Joerg-Ruediger Hill developed NJC while being a PhD student in:

Arbeitsgruppe Quantenchemie an der Humboldt-Universitaet
Max-Planck-Gesellschaft
Jaegerstrasse 10/11
D-10117 Berlin

to get his jobs for his thesis done. He can now be reached at:

Molecular Simulations Inc.
9685 Scranton Road
San Diego, CA, 92121-3752
E-Mail: jxh@msi.com
