.. _cli:

command line
============
To access the command line from your NX session, open a terminal window: right-click on the background, and select 'Open Terminal Here': 

   .. image:: ../images/terminal-menu.png

Alternatively, there is a shortcut icon in the lower left of the screen:

   .. image:: ../images/terminal-shortcut.png



.. _shellscript:

shell script
============

A shell script is a series of commands saved to a file for later execution. 

You can create a script with a text editor. Text editors available on the cluster include:

    * gedit: simple editor with a graphical interface
    * nano: simple editor with a curses-based interface
    * emacs: advanced editor with a graphical interface
    * vi: advanced editor with a text interface

Below is an example of a script that prints the date, and then sleeps 20 seconds.

#. Start a text editor::

    $ nano

#. Enter the following text, and save as 'simple.sh':

    |  #!/bin/sh
    |  date
    |  sleep 20
    
#. Make the script executable::
    
    $ chmod a+x simple.sh
    
#. Run the command at the shell prompt::
    
    $ ./simple.sh

.. _iteration:

iteration
=========
A common use of shell programming is to perform a task multiple times, iterating over a list.


In this example, we use a 'for' loop to run the 'echo' command 5 times. As a result, the value of 'i' is printed (echo'd) to the screen, where i=1, i=2, i=3, i=4 and i=5. The for loop is terminated with the 'done' statement. You may copy (and paste) the lines below into a terminal window, or copy them into a file, and run it as a :ref:`shell script<shellscript>`::

    for i in {1..5}; do
        echo "$i"
    done


The 'seq' command prints a sequence of numbers, and has options to define the increment, pad with zeros, etc. In this example, we evaluate the numbers 0 to 20 by increments of 4. (A line starting with a pound symbol, #, is ignored)::

    # define j
    j=0  
    # define i
    for i in `seq 0 4 20`; do    
        # print value of i
        echo "i:$i"
        # print equation, including current values of both i and j
        echo "j=${i}+${j}"
        # add i+j
        ((j = $j + $i))
        # print value of j
        echo "j:$j"
    done

Again, you may copy the above lines, and paste them directly into a terminal window, or copy them into a file, and run it as a :ref:`shell script<shellscript>`.  To learn more about seq, run 'man seq' (to quit the 'man' command, type 'q'). 

.. _suspend:

.. suspend/resume a process
.. ========================
.. | You may suspend and resume a process you own. This may be necessary if your jobs use more resources than is currently available. 
.. |
.. | To run more than 4 CPU-intensive processes on a single workstation, use :ref:`Grid Engine<sge>` or email support-neuro@berkeley.edu for assistance.
.. 
.. To list suspended processes, run::

    .. $ pss -u <UserName>
.. 
.. For example::
.. 
    .. $ pss -u joe
    .. USER    PID     S   %CPU    %MEM    ELAPSED     COMMAND
    .. joe     10441   T   0.0     0.0     2-22:11:14  python
.. 
.. There are (at least) 2 ways to suspend/resume a process:
.. 
.. #. If the process was started from the command line, and is running in the foreground (meaning there is no command prompt), then type Ctrl-Z to suspend it. To resume the process, type 'fg' at the prompt in the same terminal window. 
.. 
.. #. You may suspend and resume processes from a new terminal window with the 'kill' command.
.. 
   .. To suspend a process::
.. 
        .. # use 'pgrep' to search process named <ProcessName> that is owned by <UserName> 
        .. $ pgrep -l -u <UserName> <ProcessName>
.. 
        .. # use 'kill -stop' to resume <ProcessID>
        .. $ kill -stop <ProcessID>
.. 
   .. Example to suspend a process::
.. 
        .. $ pgrep -l -u joe MATLAB 
        .. 11398 MATLAB
.. 
        .. $ kill -stop 11398
.. 
.. .. _resume:
.. 
   .. To resume a process::
.. 
        .. # use 'pss' to list suspended processes for <UserName>
        .. $ pss -u <UserName>
.. 
        .. # use 'kill -cont' to resume <ProcessID>
        .. $ kill -cont <ProcessID>
.. 
   .. Example to resume a process::
.. 
        .. $ pss -u joe
        .. USER    PID     S   %CPU    %MEM    ELAPSED     COMMAND
        .. joe     10441   T   0.0     0.0     2-22:11:14  python
.. 
        .. $ kill -cont 10441
.. 
.. _unixcommands:

useful commands
===============

See :ref:`cheatsheet`