source: trunk/doc/src/docbook/appendix/jobagent.sh.xml @ 3992

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE appendix PUBLIC 
    "-//Dawid Weiss//DTD DocBook V3.1-Based Extension for XML and graphics inclusion//EN" 
    "../../../../lib/docbook/preprocess/dweiss-docbook-extensions.dtd">
<!--
  $Id: jobagent.sh.xml 3992 2007-11-22 13:19:37Z nicklas $
  
  Copyright (C) 2007 Jari Hakkinen, Peter Johansson, Nicklas Nordborg
  
  This file is part of BASE - BioArray Software Environment.
  Available at http://base.thep.lu.se/
  
  BASE 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.
  
  BASE 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., 59 Temple Place - Suite 330,
  Boston, MA  02111-1307, USA.
-->

<appendix id="appendix.jobagent.sh">
  <title>jobagent.sh reference</title>

  <para>
    The <filename>jobagent.sh</filename> (or <filename>jobagent.bat</filename> on
    Windows) is a command-line utility for controlling the job agent. 
    The syntax is:

    <informalexample>
    <programlisting>
./jobagent.sh [options] command
</programlisting>
    </informalexample>

    The options are optional, but a <command>command</command>
    must always be given. The script is located in the 
    <filename>&lt;base-dir&gt;/bin</filename> directory and you must
    change to that directory to be able to use the script.
  </para>


  <simplesect id="appendix.jobagent.sh.options">
    <title>Options</title>
    
    <variablelist>
    <varlistentry>
      <term><option>-c</option></term>
      <listitem>
        <para>
          The path to the configuration file to use, for example:
          
          <informalexample>
          <programlisting>
./jobagent.sh -c other.config start
</programlisting>
          </informalexample>
          
          The default value is <filename>jobagent.properties</filename>.
          The classpath is not searched which means that it doesn't find
          the configuration file in <filename>&lt;base-dir&gt;/www/WEB-INF/classes/</filename>
          unless you specify the path to it.
          See <xref linkend="appendix.jobagent.properties" /> 
          for more information about job agent configuration files.
        </para>
      </listitem>
    </varlistentry>
    </variablelist>
    </simplesect>

  <simplesect id="appendix.jobagent.sh.commands">
    <title>Commands</title>
    
    <variablelist>
    <varlistentry>
      <term><command>register</command></term>
      <listitem>
        <para>
          Register the job agent with the BASE server. 
          If the job agent already exists this command does nothing.
        </para>
      </listitem>
    </varlistentry>

    <varlistentry>
      <term><command>unregister</command></term>
      <listitem>
        <para>
          Unregister/delete the job agent from the BASE server. If the 
          job agent does not exist this command does nothing.
        </para>
      </listitem>
    </varlistentry>

    <varlistentry>
      <term><command>start</command></term>
      <listitem>
        <para>
          Start the job agent. As soon as it is up and running it will 
          check the database for jobs that are waiting to be executed.
        </para>
      </listitem>
    </varlistentry>
    
    <varlistentry>
      <term><command>pause</command></term>
      <listitem>
        <para>
          Pause the job agent. The job agent will continue running but 
          does not check the database for jobs. To start it again use the 
          <command>start</command> command.   
        </para>
      </listitem>
    </varlistentry>

    <varlistentry>
      <term><command>stop</command></term>
      <listitem>
        <para>
          Stop the job agent. To start it again use the <command>start</command>
          command.    
        </para>
      </listitem>
    </varlistentry>

    <varlistentry>
      <term><command>info</command></term>
      <listitem>
        <para>
          Get information about the job agent. This will output a string
          in the form:
          <computeroutput>
          <literallayout>
Status:Running
Job:1
Job:5
</literallayout>
</computeroutput>
          <emphasis>Status</emphasis> can be either <constant>Running</constant>
          or <constant>Paused</constant>. For each job that is currently 
          running, the ID is given. In the future, the <command>info</command>
          command may output more information. For example, there is already
          infrastructure code for CPU and memory usage. The only problem is
          that the information is not easy to get for a Java program.
        </para>
      </listitem>
    </varlistentry>
    
    <varlistentry>
      <term><command>status</command></term>
      <listitem>
        <para>
          Similar to the <command>info</command> command but with less output.
          The output is either <computeroutput>Running, Pauses or Stopped</computeroutput>.
          In case of an unexpected error, an error message may be displayed instead.
        </para>
      </listitem>
    </varlistentry>

    <varlistentry>
      <term><command>help</command></term>
      <listitem>
        <para>
          Display usage information.    
        </para>
      </listitem>
    </varlistentry>

    </variablelist>
    </simplesect>

</appendix>