.\" manual page for the PBS launching script
.\"
.\" $Id$
.\" Omri Schwarz
.\"
.TH LAUNCH 1 "14 August 2000" "MGH" "Unix User Manual"
.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.SH NAME
launch \- launch a set of interdependent jobs on the PBS queue
.SH SYNOPSIS 
.B name launch 
[ \-m email@somewhere ] template_name [ arguments ]
.SH DESCRIPTION
launch takes for its first argument a template.
After finding the template file, it launces 
a set of jobs into the PBS queue as prescribed, 
inserting the command line arguments into the 
job files as prescribed by the template.
.PP
A template file is composed of lines of the format:
.PP
.RS 4
3:1,2: a command line comes here
.PP
.RE
The number before the first column is the identifier of that
command line. The comma-separated numbers between the first 
and second colons indicate the jobs on which this current 
job depends. After these two entries comes the command line 
for the job.
.PP
So a full template for launching might look like this:
.PP
.RS 4 
1:: Toad that under cold stone, days and nights hath 31
.br
2:: Swelter\'d venom sleeping got
.br
3:1,2: Boil thou first i\' the charmed pot 
.PP
.RE
So, what we have here is three jobs: we put the toad
under a cold stone for 31 days, make sure it gets 
sweltered with venom in its sleep, and then boil in the
charmed pot. Since the toad can get sweltered with venom 
.I while 
it is spending 31 days under a cold stone, we don\'t
make job number 2 dependent on job number one. But,
job number 3 has to be made dependent on both 1 and 2.
.PP
The 
.I launch 
script comes with the ability to insert arguments into
a job sequence. For example:
.PP
.RS 4
1:: Select $1
.br
2:1: Sail to $1 
.br
3:2: Besiege $1 
.br
4:3: Conquer $1
.br
5:4: Loot $1 
.br
6:4: Pillage $1 
.br
7:5,6: Burn $1 
.PP
.RE
Now, if the template is named "Viking" it can be 
launched with the command "launch Viking Redmond" 
and a much desired outcome will be achieved.
Just remember: loot, pillage, 
.I then
burn.

.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.SH OPTIONS
.TP
.B \-m [ email@somewhere ] 
This option just tells PBS to send this address email
every time one of the jobs ends or aborts.

.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.SH FILES
Read the script to find where the directory for
templates is hard-coded. That needs to change at some
point.
.SH "SEE ALSO"
.BR pbsubmit (1), 
.BR qsub (1), 
.BR qdel (1), 
.BR qstat (1).
.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.SH HISTORY
No history as yet. Still in infancy.

.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.SH BUGS
Something smart needs to be done about the 
way a user finds the templates. /usr/share?
.br
Sometimes a job will exit with an error. All jobs that 
depend on it will then be left dangling in the PBS queue.
A policy solution needs to be decided for handling that.

.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.SH AUTHOR
Omri Schwarz <\fomri@nmr.mgh.harvard.edu\fR>