[[xnjs-custom-resources]]

Custom resource definitions
~~~~~~~~~~~~~~~~~~~~~~~~~~~

Most sites (especially in HPC) have special settings that cannot be 
mapped to the generic JSDL elements shown in the previous section. 
Therefore UNICORE 6 includes a mechanism to allow sites to specify 
their own system settings and allow users to set these using the 
Grid middleware.


This requires two things
  
  - Custom resource definitions in the IDB
  
  - Customisation of the TSI Submit.pm module
  
If this mechanism is not flexible enough for your needs, consider looking 
at dynamic incarnation which is described in xref:xnjs-dynamicincarnation.
  
==== The IDB

You can insert <Resource> elements into the Resources section, an example follows.
  
---------------------------------------------
   
 <jsdl:Resources>
 
    <idb:Resource xmlns:idb="http://www.fz-juelich.de/unicore/xnjs/idb">
      <idb:Name>TasksPerNode</idb:Name>
      <idb:Type>int</idb:Type>
      <idb:Description>The number of tasks per node. If larger than 32, the node will run in SMT mode.</idb:Description>
      <idb:Min>1</idb:Min>
      <idb:Max>64</idb:Max>
      <idb:Default>32</idb:Default>
    </idb:Resource>
   
  </jsdl:Resources>
    
--------------------------------------------

Apart from the numeric types <int> or <double>, there are the <string>, <choice> and <boolean> types.
The <choice> allows you to specify a set of allowed values. This is useful for example to
specify a selection of batch queues, or a selection of network topologies.

For example, defining queues could look like this:

  
---------------------------------------------
   
 <jsdl:Resources>
 
    <idb:Resource xmlns:idb="http://www.fz-juelich.de/unicore/xnjs/idb">
      <idb:Name>Queue</idb:Name>
      <idb:Type>choice</idb:Type>
      <idb:Description>The batch queue to use</idb:Description>
      <idb:Default>normal</idb:Default>
      <idb:AllowedValue>normal</idb:AllowedValue>
      <idb:AllowedValue>fast</idb:AllowedValue>
      <idb:AllowedValue>small</idb:AllowedValue>
      <idb:AllowedValue>development</idb:AllowedValue>
    </idb:Resource>
   
  </jsdl:Resources>
    
--------------------------------------------

This example defines four available queues, with the "normal" one being used by default.

[NOTE]
======================
The resource name "Queue" is recognized automatically by UNICORE and mapped to the correct 
TSI_QUEUE parameter when sending the job to the TSI.
======================


[NOTE]
======================
The resource name "Project" (i.e. the "TSI_PROJECT" TSI parameter) is mapped to the 
account parameter of the batch system, for example "-A" in the case of Torque. 
Note that JSDL has also a parameter allowing the user to set a job's project. 
It will be also translated to the TSI_PROJECT parameter. The JSDL project is currently 
an independent feature to the resource-defined "Project" and if IDB defines ranges for
the resource "Project", then the JSDL project is not checked against them. 
If both JSDL project and resource "Project" are received then the one defined as 
the resource takes the precedence. 
======================


==== Submitted JSDL

Clients can now send a special element in the JSDL job, for example requesting a 
certain value for the "TasksPerNode" setting:

-----------------------------------
    <jsdl:JobDescription>
  ...
        <jsdl:Resources>

          <jsdl-u:ResourceRequest xmlns:jsdl-u="http://www.unicore.eu/unicore/jsdl-extensions">
            <jsdl-u:Name>TasksPerNode</jsdl-u:Name>
            <jsdl-u:Value>64</jsdl-u:Value>
          </jsdl-u:ResourceRequest>

        </jsdl:Resources>
      </jsdl:JobDescription>
-----------------------------------

or for the queue example:


-----------------------------------
    <jsdl:JobDescription>
  ...
        <jsdl:Resources>

          <jsdl-u:ResourceRequest xmlns:jsdl-u="http://www.unicore.eu/unicore/jsdl-extensions">
            <jsdl-u:Name>Queue</jsdl-u:Name>
            <jsdl-u:Value>development</jsdl-u:Value>
          </jsdl-u:ResourceRequest>

        </jsdl:Resources>
      </jsdl:JobDescription>
-----------------------------------


==== TSI request  

The UNICORE/X server will send the following snippet to the TSI:
  
------------------
#!/bin/sh
#TSI_SUBMIT
# ...
#TSI_SSR_TASKSPERNODE 64.0
# ....

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


As you can see, a special TSI command tag "#TSI_SSR_TASKSPERNODE" has been added.
Now the remaining step is to have the TSI Submit.pm module has to parse this properly, and 
generate the correct batch system command.

Note that every name of a custom resource defined in IDB is converted to upper case and
spaces are replaced with the underscore character "_".



