[[ucc_jobs]]
Running jobs
------------

Introduction
~~~~~~~~~~~~
  
The UCC can run jobs specified in a simple job description format xref:ucc_jobdescription[] .
In the following it is assumed that you have UCC installed xref:ucc_install[] and
tried some examples xref:ucc_quickstart[] .

For example, assume the file "myjob.u" looks as follows

--------------
{
 ApplicationName="Date", ApplicationVersion="1.0"
}
--------------

To run this through UCC, issue the following command
  
-------------
ucc run myjob.u
-------------
  
This will submit the job, wait for completion, download the stdout and stderr files,
and place them in your default output directory. The run command has many options, to see
all the possibilities use the built-in help:

-------------
ucc run -h
-------------



==== Controlling the output location and file names

Output files will be placed in the directory given by the "-o" option, if not given, the current
directory is used. Also, file names will be put into a subdirectory named as the job id, 
to prevent accidental overwriting of existing files. This behaviour can be changed using the "-b" 
option. When "-b" is given on the command line, no subdirectory will be created.

==== Specifying the site

In the example above, a random site will be chosen to execute the job. To control it, you can use the "-s" option.
This will accept the name of a target system. The target systems available to you can be listed by

----------
ucc list-sites
---------

Options overview
~~~~~~~~~~~~~~~~

The following options are available when running jobs (see also the general options overview in xref:ucc_options[].

.General options for UCC
[options="header"]
|=======================
|Option|Short and long form    |Description
| -s,--sitename SITE  | Site where the job shall be run
| -o,--output <Output_dir> | Directory for any output produced (default is the current directory)
| -b,--brief |  Do not create a sub-directory for output files
| -O,--stdout | specify a name for the exported standard out (by default: 'stdout') 
| -E,--stderr | specify a name for the exported standard error (by default: 'stderr') 
| -a,--asynchronous | Run asynchronously 
| -y,--with-timing | Timing mode 
|=======================  
  
Processing jobs asynchronously  
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

In case of long-running jobs, you will want to run the job asynchronously, i.e. just submit the job,
stage in any files and start it, in order to get the results later. UCC supports this, of course.
The basic idea is that when submitting a job in asynchronous mode, 
a job descriptor file is written that contains the job's address, and 
any information about export files.

==== Asynchronous submission

Use the "-a" flag when submitting a job
  
--------------
ucc run -a <job file>
--------------

This will submit the job, stage-in any local files, start the job and exit.
A job descriptor file (ending in ".job") will be written to your configured output
directory.

==== Get the status of a particular job

The command 
--------------
ucc get-status <job_desc>
--------------

will retrieve the job status. If not given on the command line, the job id will be read from the console.
  

==== Download results
    
To get stdout, stderr and other files you have marked for export in your link:jobs.html[job description],
do 

--------------
ucc get-output -o <outdir> <job_desc>
--------------
  
Here, the option "-o" specifies the directory where to put the output, by default the current
directory is used. As before, the job address can also be read from the console.
  
==== Referencing a job by its EPR (Endpoint reference)

In case you want to check on a job not submitted through UCC, or in case you do not
have the job descriptor file any more, you can also refer to a job given its EPR.
For example, the "list-jobs" command will produce a list of all job EPRs that you can 
access.

Note that in this case UCC will only retrieve stdout and stderr files. To download
other result files, you'll have to use the datamovement functions described 
in xref:ucc_datamanagement[].

==== Uploading and executing an executable

To upload and execute a file on a remote server, you might need a small 
helper script to make the uploaded file executable and run it:

------------
#!/bin/sh
chmod +x myapp
./myapp
-----------  

Your ucc job description would then look as follows
    
------------
{
  Executable: "/bin/sh",
  Arguments: ["helper.sh"],
  Imports: [
    {From: "helper.sh", To: "helper.sh"},
    {From: "myapp", To: "myapp"},
  ],
}
-----------  

[NOTE]
==================
Recent servers do not require this trick, and you should be able
to directly execute your uploaded executable without requiring
a helper script.
==================

  
==== Scheduling job submission to the batch system

Sometimes a user wishes to control the time when a job is
submitted to the batch queue, for example because she knows that
a certain queue will be empty at that time.

[NOTE]
==================
This feature only works with server release 6.4.0 or higher.
==================


To schedule a job, you can either use the "-S" option to the ucc "run"
command:


----------------
ucc run -S "12:24" ...
----------------

Alternatively, you can specify the start time in your job file using the "Not before" key word

--------------
{

 Not before: "12:30",

}
--------------

In both cases, the specified start time can be given in the brief "HH:mm" (hours and minutes) 
format shown above, or in the full ISO 8601 format including year, date, time and time zone:

--------------
{

 Not before: "2011-12-24T12:30:00+0200",

}
--------------

