HiLA Shell User Guide
=====================
:Author: UNICORE Team
:Email: unicore-support@lists.sourceforge.net
:Revision: 1.0.0
:Date: April 2011
:numbered:

Preface
-------

HiLA Shell is Grid client based on the HiLA API. It was incepted as a
demonstrator application to show the features of HiLA in use and to
give developers a better understanding of the underlying concepts. At
the same time, the commands implemented in the Shell can serve as
templates for ones own developments with HiLA.

Nonetheless, HiLA Shell can be used to access Grid resources and act
upon them. In the following, the available commands of HiLA Shell will
be described.

Commands
--------

The first command you should know is ++help++. It will list all available
commands.

-------------------------
:> help
Available commands are: 
Available commands are: 
cleanup    cat        lls        rm         ls         lcd        cancel     run        quit
version    help       time       import     chdir      move       copy       export     transfer
monitor    submit     status     mv         lpwd       mkdir      exit       pwd        cp
start      chmod      cd         abort
:>
-------------------------

Most commands have a ++--help++ or ++-h++ option that describes the
command and lists possible options and arguments.

We have separated the commands into five categories for documentation
purposes.

The <<cat-location, Location commands>> category documents all
commands that are related to location like the current location or
others.
The <<cat-task,Task Management>> category describes all commands that
are needed for task management, like aborting or querying the status
of a running task.
Commands for handling acutal compute jobs are documented in the
<<cat-job,Job Management>> category.
Data handling commands are described in the <<cat-data,Data Handling>>
section.
The <<cat-general,General>> category documents all other commands that
could not be attributed to a single one of the other categories.

[[cat-general]]
General commands
----------------

[[cmd-exit]]
exit
~~~~

Exit HiLA Shell.


[[cmd-help]]
help
~~~~

List available commands.


[[cmd-ls]]
ls
~~

List children of the current location.

------
sites :> ls
unicore6:/sites/EMI-UNICOREX_201104071445
sites :> 
------

or 

------
tasks :> ls
unicore6:/sites/EMI-UNICOREX_201104071445/tasks/de6f68c8-99b4-4a77-a873-c94a87e27c96
unicore6:/sites/EMI-UNICOREX_201104071445/tasks/c77f3714-c1c5-4c59-befc-7f1191246704
unicore6:/sites/EMI-UNICOREX_201104071445/tasks/2dbd7cb4-4098-429a-929f-b092eff82f52
tasks :> 
------

[[cmd-quit]]
quit
~~~~

An alias for <<cmd-exit, exit>>.


[[cmd-time]]
time
~~~~

Execute a command and print how long it took.

-------------------------
tasks :> time run -e /bin/date -s unicore6:/sites/VSGC_201007221554
Fr 23. Jul 13:51:51 CEST 2010

Execution of run took 4269ms.
tasks :> 
--------------------


[[cmd-version]]
version
~~~~~~~

Prints version information about HiLA shell to the console. The output will look
similar to this.

----------------------------
 :> version
HiLA Shell 2.2  (20110216-0757)
 :> 
----------------------------

This information is useful if you ask developers for support,
e.g. on the UNICORE support mailing list <unicore-support@lists.sourceforge.net>.

[[cmd-alias]]
alias
~~~~~

The alias command allows you to define your own aliases for
commands. It works similar as the Bash alias command. You can even
redefine the existing commands, e.g. for adding default parameters to
them. An alias is only evaluated once, i.e. you cannot use aliased
aliases.

-------------------
:> alias ls='ls -l'
:> alias
alias ls='ls -l'
:> ls unicore6:/sites/DEMO-SITE/storages/Home/files/
-rw-     372 unicore6:/sites/DEMO-SITE/storages/Home/files/.bashrc
...
:> unalias ls
:> ls unicore6:/sites/DEMO-SITE/storages/Home/files/
unicore6:/sites/DEMO-SITE/storages/Home/files/.bashrc
-------------------

[[cmd-unalias]]

Delete an alias command from the list of aliases. This command will
not complain if the alias did not exists. An example has been given
above.

[[cat-location]]
Location Commands
-----------------

[[cmd-cd]]
cd
~~

Change directory.

HiLA Shell keeps track about the current location. This command
resembles command line behavior, where ++cd++ or ++chdir++ change the
current directory, respectively the current location.

[[cmd-chdir]]
chdir
~~~~~

An alias for <<cmd-cd, cd>>.


[[cmd-lcd]]
lcd
~~~

Change the current local diretory. This is useful if you want to use
relative local paths for certain commands, e.g. import/export.

[[cmd-lls]]
lls
~~~

List local directory.


[[cmd-lpwd]]
lpwd
~~~~

Display current local directory.

------
sites :> lpwd
/home/bjoernh
sites :> 
------

[[cmd-pwd]]
pwd
~~~

Display the current (remote) ++Location++.

------
EMI-UNICOREX_201104071445 :> pwd
unicore6:/sites/EMI-UNICOREX_201104071445
EMI-UNICOREX_201104071445 :> 
------

[[cat-task]]
Task Management
---------------

[[cmd-abort]]
abort
~~~~~

This command aborts a running Task.

------
abort <task location> ...
------

Options
^^^^^^^
-h, --help          Print help message.

[[cmd-cancel]]
cancel
~~~~~~

An alias for <<cmd-abort, abort>>.


[[cmd-monitor]]
monitor
~~~~~~~

Monitor the forthcoming of a task, e.g. import, export, or compute
task. Actually, this command works on the ++Progressable++ interface,
thus any ++Resource++ implementing this interface can be monitored by
it.



[[cmd-status]]
status
~~~~~~

Display status of ++Task++s.

Options
^^^^^^^

-l, --log           Print the job log. +
-h, --help          Print help message.


[[cat-job]]
Job Management
--------------

[[cmd-submit]]
submit
~~~~~~

Submit a job to a ++Site++

Options
^^^^^^^

-s, --site          Site to which to submit the job. +
-r, --run           Run job right away. +
-j, --jsdl          JSDL document to be submitted. +
-h, --help          Print help.

[[cmd-start]]
start
~~~~~

Start a ++Job++ that is in state NEW.

Options
^^^^^^^

-b                  Block on task. Optional argument for blocking limited number of ms. +
-h, --help          Print this help message.

[[cmd-run]]
run
~~~

Run a remote command and display its output.

Options
^^^^^^^

-arg, --arg         Argument +
-e, --exec          Executable +
-s, --site          Site to which to submit the job. +
-an, --application  Application name +
-ver, --version     Application version +
-h, --help          Print help message.

Example
^^^^^^^

The following command will run ++/usr/bin/whoami++ at the site given by the ++-s++ option.

----------------------------
 :> run -e /usr/bin/whoami -s unicore6:/sites/DEMO-SITE_201004221047
demo
 :> 
----------------------------


[[cmd-cleanup]]
cleanup
~~~~~~~

Clean up a Job, i.e. remove it from the site. The -a option will
export all files from the working directory of the Job to the local
export directory, usually ~/.hila2/data/<job id>. The -e option, which
can be given multiple times, only exports files that are mentioned by
the option. Files can be given with a path relative to the working
directory of the job.

Options
^^^^^^^

-e, --export        Export files from working directory.
-a, --export-all    Export all files.
-h, --help          Print help message.



[[cat-data]]
Data handling commands
----------------------

[[copy-semantics]]
Copy Semantics
~~~~~~~~~~~~~~

Some of the data handling commands deal with the movement of data,
i.e.  copying or moving files either within a single storage or
between two storages. These operations imply that files can already be
existing at the target location. Therefore, we describe the semantics
of handling these cases here. All copy and data movement commands
follow these semantics.

Consider operation

------
op <source file location> <target file location>
------

where ++op++ is one of the respective commands and ++source file
location++ and ++target file location++ are valid local or remote file
locations.

If target file location does not exist yet, but its parent location
does and points to a directory, then the source file is put into that
directory and given the name of the source file. If the parent
location is an ordinary file, then the operation will fail, as files
cannot be put underneath other ordinary files.

If <target file location> points to an already existing file, the
following will happen. If <file location2> points to a directory, then
the file will be copied into the directory. If <file location2> points
to an ordinary file, then that file will only be overwritten, if the
-f/--force option is given.

[[cmd-cat]]
cat
~~~
Output the contents of a remote file to the local console.

------
cat <remote file location>
------

Be careful with ++cat++ing binary files, they may render your console
unusable.


[[cmd-chmod]]
chmod
~~~~~

Change file mode bits. File mode bits can only be set for the user,
not for the group or other users like you may know from the UNIX
command ++chmod++.

chmod [-w true/false] [-r true/false] [-x true/false] ++<file location>++

Options
^^^^^^^

-w, --write         Set write permission to true/false +
-r, --read          Set read permission to true/false +
-h, --help          This help message. +
-x, --execute       Set executable permission to true/false


[[cmd-copy]]
copy
~~~~

Copy a file within a storage.

copy <file location1> <file location2>

<<copy-semantics,Copy semantics>> apply.

Options
^^^^^^^

-f, --force         Force overwrite +                                         
-r, --recursive     recursive operation +
-h, --help          Print help message.

[[cmd-cp]]
cp
~~

An alias for <<cmd-copy, copy>>.

[[cmd-import]]
import
~~~~~~

Import files from local file system to remote storages.

<<copy-semantics,Copy semantics>> apply.


[[cmd-export]]
export
~~~~~~

Export files from remote storages to local file system.

export <file location> <local file path>

<<copy-semantics,Copy semantics>> apply.

[[cmd-mkdir]]
mkdir
~~~~~

Make directory.

Be sure to give a valid file location. Creating directories does not
make sense if you do not create them inside a storage.

[[cmd-move]]
move
~~~~

Move files within a ++Storage++.


[[cmd-mv]]
mv
~~

An alias for <<cmd-move, move>>.

<<copy-semantics,Copy semantics>> apply.


[[cmd-transfer]]
transfer
~~~~~~~~

Transfer a remote file to another file or directory.

transfer <remote:/file/a> <remote:/file/b>

<<copy-semantics,Copy semantics>> apply.

[[cmd-rm]]
rm
~~

Remove files or directories. If you want to remove a directory, the
++-r++ option needs to be given.

Options
^^^^^^^

-r, --recursive
