<?xml version="1.0"?>
 
 <!--
 File: AthASK/doc/job.xml
 Author: Wim Lavrijsen (LBNL, WLavrijsen@lbl.gov)
 Created: 03/03/04
 Last: 12/16/05
 -->
 
 <!DOCTYPE sect1 PUBLIC "-//OASIS/DTD DocBook XML V4.4//EN"
                        "http://docbook.org/xml/4.4/docbookx.dtd" [
 
  <!ENTITY % entities                    SYSTEM "AthASK.ent">
  <!ENTITY % glossary                    SYSTEM "glossary/glossary.ent">
 
  %entities;
  %glossary;
 
 ]>
 
 <sect1 id="sec-job">
 <title>Simple jobs</title>
 
 <para>
 This section describes a way of running jobs on CERN &lsf;, using &athask;.
 The scripts that are used are flexible enough the run all tutorials that are
 provided in the appendices.
 They do not, however, provide any job provenance, data management, or other
 bookkeeping, and are as such unsuitable for real production: this text is
 provided for educational purposes only.
 </para>
 
 <note><para>
 Running a batch job is somewhat complicated at the moment, because access
 to the repository is restricted (you can not get a &kerberos; ticket, unless
 you are willing to put your password in a file which isn't really an option).
 Thus, if you need packages from the repository, job submission should start
 with copying<footnote><para>A further complication is the fact that &cmt; uses
 hard-wired absolute paths in its configuration files, which must be countered
 by reconfiguring the package after it has been moved.</para></footnote>
 over a package that was previously checked out.
 </para></note>
 
 <sect2>
 <title>Preparation</title>
 
 <para>
 The following will assume that the batch machine shares the file system with
 the interactive machine that you are using.
 This is usually the case when you use &lsf; for batch submission, and work on
 a machine such as lxplus that hosts your home directory on &afs;.
 </para>
 
 <para>
 First, create the following five directories in a work area that is
 reachable from the batch machine (for example, your home directory on &afs;):
 
 <screen>
  $~&gt; mkdir batch
  $~&gt; mkdir scripts
  $~&gt; mkdir log
  $~&gt; mkdir output
  $~&gt; mkdir pool
 </screen>
 
 There is nothing special about these names, so you can change them.
 However, if you do, make sure that you modify the names in all the scripts
 that make use of these directories (the main script allows the location of the
 above directories to be changed with a command line argument).
 </para>
 
 <para>
 Then, write an &athask; based submission script.
 A basic example, that has most of the needed functionality, follows, but it is
 recommended to write a script tailored (if nothing else, at least make sure
 that the directory locations are proper, especially if they're not located in
 $HOME) to your own needs:
 
 <programlisting language="shell">
 <phrase class="comment">#! /usr/bin/env zsh</phrase>
 <phrase class="keyword">local</phrase> jobdir=<phrase class="string">"$HOME"</phrase>
 <phrase class="keyword">local</phrase> packages=<phrase class="string">""</phrase>
 
 <phrase class="comment"># parse and verify options; set local variables accordingly</phrase>
 <phrase class="keyword">while</phrase> getopts d:p:hH o ; <phrase class="keyword">do</phrase>
  <phrase class="keyword">case</phrase> <phrase class="string">"$o"</phrase> <phrase class="keyword">in</phrase>
   d) jobdir=<phrase class="string">"$OPTARG"</phrase> ;;
   p) packages=<phrase class="string">"$OPTARG"</phrase> ;;
   h|H|[?]) echo <phrase class="string">"Usage: $0 [-d jobdir] [-p packages] script"</phrase>
            exit 1 ;;
  <phrase class="keyword">esac</phrase>
 <phrase class="keyword">done</phrase>
 <phrase class="keyword">shift</phrase> $OPTIND-1
 
 <phrase class="keyword">if</phrase> test $# -ne 1 ; <phrase class="keyword">then</phrase>
  echo <phrase class="string">"This job requires one &athask; script, but none were given ... stop!"</phrase>
  exit 1
 <phrase class="keyword">fi</phrase>
 
 <phrase class="comment"># environment variables used in this and the &athask; script</phrase>
 <phrase class="keyword">export</phrase> JOBDIR=$jobdir
 <phrase class="keyword">export</phrase> MYPOOLFILE=$JOBDIR/pool/PoolFileCatalog.xml
 
 <phrase class="comment"># copy the &athask; script to batch work directory</phrase>
 cp -f $JOBDIR/scripts/$1 .
 <phrase class="keyword">if</phrase> test $? -ne 0 ; <phrase class="keyword">then</phrase>
  echo <phrase class="string">"Failed to copy script \"$1\" ... stop!"</phrase>
  exit 2
 <phrase class="keyword">fi</phrase>
 
 <phrase class="comment"># copy POOL catalog file, if available</phrase>
 test -f $MYPOOLFILE &amp;&amp; cp -f $MYPOOLFILE .
 
 <phrase class="comment"># copy all required packages</phrase>
 <phrase class="keyword">setopt</phrase> shwordsplit
 <phrase class="keyword">for</phrase> p <phrase class="keyword">in</phrase> $packages; <phrase class="keyword">do</phrase>
  cp -r $JOBDIR/batch/$p .
  <phrase class="keyword">if</phrase> test $? -ne 0 ; <phrase class="keyword">then</phrase>
   echo <phrase class="string">"Failed to copy package \"$p\" ... stop!"</phrase>
   exit 2
  <phrase class="keyword">fi</phrase>
 <phrase class="keyword">done</phrase>
 
 <phrase class="comment"># setup done, execute &athask; script and return result</phrase>
 ask $1
 exit $?
 </programlisting>
 
 The script takes one argument: the &athask; script that is to be used.
 Optionally, you can provide an alternative directory to locate the
 conventional directories (you can also modify the default in the script), and
 a list of packages that need to be copied.
 The script copies the required files into the work directory on the batch
 machine, starts &athask;, and has it execute the given script, which can
 contain any commands as you are used to issuing on the &athask; CLI.
 Note that that includes any and all &python; code.
 </para>
 
 <para>
 For the tutorials, just copy the above script (call it
 <filename>tutorialjob.sh</filename>) into your work directory and make it
 executable.
 </para>
 
 </sect2><!-- Preparation -->
 
 <sect2>
 <title>Submission and monitoring</title>
 
 <para>
 The following command will submit the job, with &athask; script
 <filename>myscript.py</filename>, into the '1nh' (one normalized hour) batch
 queue and will copy the log file as <filename>mylog.log</filename> into your
 <filename class="directory">log</filename> directory:
 
 <screen>
  $~&gt; bsub -o log/mylog.log -q 1nh tutorialjob.sh myscript.py
 </screen>
 
 If you are not running at CERN, or need a queue that allows for jobs that run
 longer than one hour: issue the <command>bqueues</command> command,
 which will show you all available batch queues.
 You can retrieve the status of your job with the <command>bjobs</command>
 command, and you can look at its output with '<command>bpeek</command> #id'
 (where '#id' is the job identifier, as obtained from <command>bjobs</command>;
 use '-f' to follow the tail).
 Please be considerate, however: if several people issue many of these
 monitoring requests to the system, it will grind to a halt and no-one will be
 able to get any work done.
 </para>
 </sect2><!-- Submission and monitoring -->
 
 </sect1><!-- Job -->

This page was automatically generated by the LXR engine.