[[xnjs_execution_environments]]
Execution Environments
~~~~~~~~~~~~~~~~~~~~~~

Execution environments are an advanced feature that allows you to configure 
the way an executable is executed in a more detailed and user-friendly fashion. 
A common scenario is the configuration of an environment for parallel 
execution of a program, such as MPI.

A typical simple MPI invocation looks like this

-----------------

/usr/local/bin/openmpi -np 4 ./my_mpi_program [my_program_arguments]

-----------------

but of course there are many more possible arguments to the MPI command, which also depend 
on the local installation. By using a predefined execution environment, a UNICORE user 
need not know all the details, but can set up her job in a simple fashion.
  
This document covers the options that are available to configure execution environments in the IDB.


 - XML Schema for the execution environments: the current XML schema for the execution environment specification can be read from the 
http://unicore.svn.sourceforge.net/viewvc/unicore/jsdl-xmlbeans/trunk/src/main/schema/jsdl-unicore.xsd[SVN repository].

IDB definition of execution environments
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The server-side setup of an execution environment is by adding an XML entry into the IDB. 
A simple environment might be used to run a user command using 'time'. This example shows 
every possible option. You might want to consult the man page of 'time'.

------------
<idb:IDB xmlns:idb="http://www.fz-juelich.de/unicore/xnjs/idb">

<!-- sample execution environment definition in the IDB -->
  <ee:ExecutionEnvironment xmlns:ee="http://www.unicore.eu/unicore/jsdl-extensions">
    <ee:Name>TIME</ee:Name>
    <ee:Version>1.0</ee:Version>
    <ee:Description>Runs the user's command using the 'time' tool, measuring the used CPU time.</ee:Description>
    <ee:ExecutableName>/usr/bin/time</ee:ExecutableName>
    <ee:CommandlineTemplate>#EXECUTABLE #ARGS #USERCOMMAND #USERARGS</ee:CommandlineTemplate>
    <ee:Argument>
      <ee:Name>Output</ee:Name>
      <ee:IncarnatedValue>-o</ee:IncarnatedValue>
      <ee:ArgumentMetadata>
        <ee:Type>string</ee:Type>
        <ee:Description>Write the resource use statistics to a FILE instead of to the standard error stream</ee:Description>
      </ee:ArgumentMetadata>
    </ee:Argument>
    <ee:Option>
      <ee:Name>Verbose</ee:Name>
      <ee:IncarnatedValue>-v</ee:IncarnatedValue>
      <ee:OptionMetadata>
        <ee:Description>Enable verbose mode</ee:Description>
      </ee:OptionMetadata>
    </ee:Option>
    <ee:PreCommand>
      <ee:Name>PRINT_START_TIME</ee:Name>
      <ee:IncarnatedValue>echo "Started at $(date)"</ee:IncarnatedValue>
      <ee:OptionMetadata>
        <ee:Description>Explicitely print the start time</ee:Description>
      </ee:OptionMetadata>
    </ee:PreCommand>
    <ee:PostCommand>
      <ee:Name>PRINT_FINISH_TIME</ee:Name>
      <ee:IncarnatedValue>echo "Finished at $(date)"</ee:IncarnatedValue>
      <ee:OptionMetadata>
        <ee:Description>Explicitely print the finishing time</ee:Description>
      </ee:OptionMetadata>
    </ee:PostCommand>
   </ee:ExecutionEnvironment>

</idb:IDB>

------------  

If a client now submits a job including a request for the "TIME" execution 
environment (in the JSDL +Resources+ element), UNICORE will generate a shell 
script that wraps the user command in the "time" invocation. Let's say 
the job request includes the "Output" argument, the "Verbose" option and both 
precommand and postcommand:
  
-----------
  <!-- sample execution environment request sent from client to server -->
  <ee:ExecutionEnvironment xmlns:ee="http://www.unicore.eu/unicore/jsdl-extensions">
    <ee:Name>TIME</ee:Name>
    <ee:Version>1.0</ee:Version>
    <ee:Argument>
      <ee:Name>Output</ee:Name>
      <ee:Value>time_profile</ee:IncarnatedValue>
    </ee:Argument>
    <ee:Option>
      <ee:Name>Verbose</ee:Name>
    </ee:Option>
    <ee:PreCommand>
      <ee:Name>PRINT_START_TIME</ee:Name>
    </ee:PreCommand>
    <ee:PostCommand>
      <ee:Name>PRINT_FINISH_TIME</ee:Name>
     </ee:PostCommand>
   </ee:ExecutionEnvironment>
-----------

The script generated by UNICORE will look like this (leaving out some standard things):
  
-----------
#!/bin/bash

# ...

echo "Started at $(date)"
/usr/bin/time -o time_profile -v /path/to/my_user_application
echo "Finished at $(date)"

# ...

----------- 

In the following the various XML tags that are available are explained in detail.
 

 - +ExecutableName+ : This is the name of the executable that "defines" the environment.
  
 - +CommandlineTemplate+ : To control the exact commandline that is created, this template is used. 

The default template is

----
#EXECUTABLE #ARGS #USERCOMMAND #USERARGS
----

where
  
  - +#EXECUTABLE+ is the executable defined using ExecutableName
  
  - +#ARGS+ are the arguments and options for the executable
  
  - +#USERCOMMAND+ is the user's executable
  
  - +#USERARGS+ are the arguments to the user's executable
  

  - +Argument+ : the Argument elements are used to create arguments to the executable. 
They have several subtags.
  
  - +Name+ is the name of the argument.
  
  - +IncarnatedValue+ is the argument as used in the commandline.
  
  - +ArgumentMetadata+ are described below.
 
  - +ArgumentMetadata+ : This element allows to describe an Argument in more detail. It has the following subtags
  
  - +Type+ the argument type. Valid values are "string", "boolean", "int", "float" and "choice"
  
  - +Description+ is a human-friendly description
  
  - +Default+ a possible default value
  
  - +ValidValue+ tags are used to denote possible values
  
  - +DependsOn+ denotes other arguments that this argument requires
  
  - +Excludes+ denotes other arguments that clash with this argument 
   
  - +PreCommand+ : This tag denotes a command that is executed immediately before the 
actual executable. Its subtags are the same as for +Option+.

  -  +PostCommand+ : This tag denotes a command that is executed after the actual 
execution. Its subtags are the same as for +PreCommand+.



