.. _commands:

commands
========

Below is a list of popular SGE :ref:`commands <cli>`.

.. seealso::

    :ref:`A Sun Grid Engine tutorial <analysis>`.

.. _qsub:

qsub
----
submit a batch job to Sun Grid Engine

    Run 'qsub' to to submit `simple.sh script <../shell.html>`_::

        $ qsub simple.sh

    Error 'e' and output 'o' files are created in your home directory:
    
       | simple.sh.e96606
       | simple.sh.o96606


    .. Note::

        You can monitor job status with :ref:`qstat`. 


    Below is a subset of qsub options you may define:
        +--------------------------+------------------------------------------------------------------------------------------------+
        +--------------------------+------------------------------------------------------------------------------------------------+
        | -M emailaddress          | | Change 'emailaddress' to specify where you want to receive notifications                     |
        |                          | | The default value is the email address specified in the .forward file in your home directory |
        +--------------------------+------------------------------------------------------------------------------------------------+
        | -m b|e|a|s|n             | | The frequency of e-mail notifications.                                                       |
        |                          | | The default is:                                                                              |
        |                          | | -m as                                                                                        |
        |                          | | The arguments have the following meaning:                                                    |
        |                          | | - b :   Mail is sent at the beginning of the job                                             |
        |                          | | - e :   Mail is sent at the end of the job                                                   |
        |                          | | - a :   Mail is sent when the job is aborted or rescheduled                                  |
        |                          | | - s :   Mail is sent when the job is suspended                                               |
        |                          | | - n :   No mail is sent                                                                      |
        +--------------------------+------------------------------------------------------------------------------------------------+
        | -e path                  | | The directory for SGE error files                                                            |
        |                          | | Change 'path' to the directory where Grid Engine saves error files                           |
        |                          | | e.g. $HOME/sge/logs                                                                          |
        |                          | | The default is your home directory. If you change the default, verify the directory exists   |
        +--------------------------+------------------------------------------------------------------------------------------------+
        | -o path                  | | The directory for SGE output files (can be the same as above)                                |
        |                          | | Change 'path' to the directory where Grid Engine saves error files                           |
        |                          | | e.g. $HOME/sge/logs                                                                          |
        |                          | | The default is your home directory. If you change the default, verify the directory exists   |
        +--------------------------+------------------------------------------------------------------------------------------------+
        | -N name                  | | The name of the job                                                                          |
        |                          | | e.g. -N test                                                                                 |
        +--------------------------+------------------------------------------------------------------------------------------------+
        | -j yes                   | | Merge the output and error files                                                             |
        +--------------------------+------------------------------------------------------------------------------------------------+
        | -l mem_free=value        | | Define the memory requirements for your job                                                  |
        |                          | | Change 'value' to the amount of memory required by your script.                              |
        |                          | | e.g. -l mem_free=15G reserves 15GB of RAM for the script                                     |
        +--------------------------+------------------------------------------------------------------------------------------------+
        
        
    A full list of options is described in the qsub manual page, available from the :ref:`command line <cli>`:

        ::

            man qsub

    The manual page may be navigated with the space bar and arrow keys. Type 'q' to quit.


.. _qload:

qload
-----
prints a summary of everyone's submitted jobs, and lists your running jobs with system CPU/memory information.


.. _qdel:

qdel 
----
deletes a job from the queue 

    To delete all of your jobs::

        $ qdel -u $USER

    .. Note::

       $USER will be interpreted by the shell as your unix account name. You may use $USER in shell commands and shell scripts instead of your unix account name. 

    To delete a single job::

        $ qdel 6033


.. _qstat:

qstat 
-----
prints information about incomplete jobs, including errors and scheduling information. See :ref:`qstattrouble` for more information. 

.. _qacct:

qacct
-----
prints information about completed jobs, including how much memory a job used. See :ref:`memory` for more information.