<commit_before><?xml version="1.0" encoding="UTF-8"?>
<?xml-stylesheet type="text/css" href="../viewDocbook.css"?>
<chapter id="scheduler_tutorial">
	<title> Scheduler Tutorial</title>

<sect1 id="Sched_tuto">
<title>ProActive Scheduler Tutorial</title>
	<sect2 id="proactive_scheduler_tutorial_intro">
		<title>introduction</title>
		<para>
		This document aims to present in a practical way the ProActive Scheduler. 
		Scheduler is a tool which administer deployment and maintenance of a jobs queue 
		over various platforms and infrastructures (Grid or P2P infrastructure) 
		following one of many set of rules regarding the job management.
		<itemizedlist>
		<listitem>
			Scheduler architecture <xref linkend="sched_archi"/>
		</listitem>
		<listitem>
			Task flow concept : <xref linkend="taskflow_concept"/>
		</listitem>
<!--		
		<listitem>
			We will create our first Scheduler job : <xref linkend="first_job"/>
		</listitem>
		<listitem>
			Then we will launch the scheduler and submit the job created :<xref linkend="launching"/>
		</listitem>
		</itemizedlist>	
		<para>
		After we will see some additional functionalities and different kinds of job runnable on the scheduler :
		</para>
		<itemizedlist>
		<listitem>
			Adding init parameters to a task : <xref linkend="add_parameters"/>
		</listitem>		
		<listitem>
			How to pass result of a task to another task : <xref linkend="result_passing_mechanism"/>
		</listitem>
-->	
		<listitem>
			Schedule a native executable : <xref linkend="native_job"/>
		</listitem>
		<listitem>
			Launch Scheduler and submit a job :<xref linkend="launching"/>
		</listitem>		
		<listitem>
			Node selection mechanism : <xref linkend="add_sel_script"/>
		</listitem>
		<listitem>
			PreScript and PostScript features : <xref linkend="pre_post"/>
		</listitem>
		<listitem>
			How to generate dynamically a native command to execute, depending to the node architecture : <xref linkend="command_generator"/>
		</listitem>
		<listitem>
			Exported Environment variables introduced into the task's execution environment    : <xref linkend="tasks_env_var"/>
		</listitem>		
		</itemizedlist>

		</para>
		<sect3 id="prerequisites">
		<title>Prerequisites and conventions :</title>
		<itemizedlist>
		<listitem>
			<para>
			You must have an Eclipse 3.2 IDE installed, and the ProActive Project open in your Eclipse. 
			</para>
		</listitem>
		<listitem>			
			<para>
			The directory of ProActive in your system project is represented by the tag : <literal>[ProActive_dir]</literal>.
			</para>
		</listitem>
		<listitem>			
			<para>
			You need  a working directory in your system, represented here by <literal>[working_dir]</literal>.
		 	</para>
		</listitem>
		</itemizedlist>				 	
		</sect3>
	</sect2>
	<sect2 id="sched_archi">
		<title>Scheduler architecture</title>
		<para>
			The scheduler is made of two main components : the Scheduler and the Resource Manager.  
			Each of them has its own functionality :
		<itemizedlist>			
		<listitem>
			<para>
			The scheduler is in charge of registering jobs submitted 
			and put them in a queue according to a scheduling policy. 
			Then it is charged to ask Resources at the Resource Manager, 
			and execute jobs on those retrieved resources.
			</para>
		</listitem>
		<listitem>			
			<para>
			The Resource Manager (RM) handle a set of resources available for scheduling jobs.
			It takes benefits of the Proactive Library, so it can handle resources from LAN, 
			on cluster of workstations on P2P desktop Grids, or on Internet Grids. 
			Resource Manager provides the scheduler in resources, according to criteria (Operating System, dynamic libraries,
			Memory...). Resources, at ProActive point of view, are called nodes,
			so Resource Manager supplies scheduler in ProActive nodes.
			</para>
		</listitem>
		</itemizedlist>
		</para>
		<figure id="scheduler_arch">
				<title>Scheduler architecture</title>
				<mediaobject>
					<imageobject>
						<imagedata align="center"
							fileref="scheduler/pics/tuto/arch.jpg" format="JPG" />
					</imageobject>
				</mediaobject>
	</figure>
	<para>
		These two components (Scheduler and IM) are independent and run as non GUI daemon/service.
		So they can run on two different hosts.
	</para>
</sect2>
<sect2 id="taskflow_concept">
	<title>Task-flow Concept</title>
	<para> Submit a job to the ProActive Scheduler means submitting a <emphasis role="bold">task flow</emphasis>,
	which is a set of tasks. A task can be defined as a part of the job, a step to execute in the job.
	Jobs can also be made of different tasks, i.e. different steps to execute.
	Task is most little part of a job, the smallest schedulable entity. ProActive Scheduler has 
	computing nodes to execute jobs, basically it launches on each node an execution
	of a task, and when task is ended, launches another etc...
	</para>
	<sect3 id="task_flow_illust">
	<title>Parallel tasks,  predecessor tasks</title>
	<para>
		When you build your job, you create a graph of tasks, with a definition of predecessor/successor between tasks :
	</para>
	<figure id="scheduler_job">
				<title>Scheduler architecture</title>
				<mediaobject>
					<imageobject>
						<imagedata align="center"
							fileref="scheduler/pics/core/schedulerJob.jpg" format="JPG" />
					</imageobject>
				</mediaobject>
	</figure>
	<para>
	In this tasks graph, we see that task 4 is preceded by task 1, that means scheduler waits end of task 1 execution 
	before launching task 4. In a more concrete way, task 1 could be calculation of a part of the problem to solve, 
	and task 4 takes result provided by task 1 and compute another step of the calculation. 
	We introduce here concept of <emphasis role="bold">result passing</emphasis> between tasks, explained later. 
	This relation is called a dependence, and we say that task 4 <emphasis role="bold">depends</emphasis> on task 1. 
	</para>
	<para>
	We see that task 1, 2 and 3 are not linked, so these three tasks can be executed in <emphasis role="bold">parallel</emphasis>, 
	because there are independent from each other.
	</para>
	<para>	
	Finally we see task 7 and 8 are at end of the oriented graph, These are task which produce final
	results of the job expected by the user, we call these final results <emphasis role="bold">Precious result</emphasis>.
	</para>
	<para>
	Definition of the task-flow graph is made at job's definition, before scheduling, and cannot be modified during
	execution of the job, this kind of work flow is called a <emphasis role="bold">static work flow</emphasis>.
	A Task flow job is described in XML language.
	</para>
	</sect3>
</sect2>

<!--



<sect2 id="first_job">
	<title>Developing my first job</title>	
	<para>
	In this part we will build a basic job 's example which can be submitted to the scheduler. 
	For the first example we will create a job containing just one task. We have two files to provide :
		<itemizedlist>
		<listitem>
			a Java Class file representing the computing code of the task.
		</listitem>
		<listitem>
			an XML file describing the job (tasks composing the job).
		</listitem>
		</itemizedlist>
	</para>

		<sect3 id="Task_Code.">
			<title>Task Code</title>
			<para>
				We will create a Java class derived from JavaExecutable and containing the primitive execute. 
				This function should be declared to implement the "business code" of the task. 
				When the task is deployed on a resource (a node), this function is called to complete task's objective. 
				Open ProActive project in your Eclipse IDE and create a new Java class called HelloTask.java 
				in the the src/Extensions/org/objectweb/proactive/extensions/scheduler/examples directory. 
				Type in the file the code below :
			</para>
			<para>
			 <emphasis role="bold">project : </emphasis>ProActive
			</para>
			<para>			 
			 <emphasis role="bold">directory : </emphasis>src/Extensions/org/objectweb/proactive/extensions/scheduler/examples
			</para>
			<para>			 
			 <emphasis role="bold">file : </emphasis>HelloTask.java
			</para>
			<programlisting lang="java">			
package org.objectweb.proactive.extensions.scheduler.examples;

import org.objectweb.proactive.core.util.ProActiveInet;
import org.objectweb.proactive.extensions.scheduler.common.task.TaskResult;
import org.objectweb.proactive.extensions.scheduler.common.task.executable.JavaExecutable;

public class HelloTask extends JavaExecutable{

	public Object execute(TaskResult... results) {
		  	String result= "HelloWorld task, host : ";
            result += ProActiveInet.getInstance().getHostname();
            System.out.println(result);
      		return result;
	  }
}						
			</programlisting>
	<para>
	In this example, the task says Hello, and display host address of the resource (node) where the task is executed.
	We see that primitive execute() have TaskResult objects in arguments, and must return an Object, 
	which is considered as the result of the task. these two aspects of the primitive are made 
	for the result passing mechanism between tasks, and will be explained later.
	</para>
	<para>
	Compile these file. You can compile with your eclipse IDE,  or type this command (For Unix systems) :
	</para>
	<para>
	<literal>
	[ProActive_dir]/compile/build compile
	</literal> 
	</para>
	<para>
	If your a are on a windows system, type :
	</para>
	<para>
	<literal>
	[ProActive_dir]/compile/build.bat compile
	</literal> 
	</para>			
	</sect3>
	<sect3 id="XML_description">
	<title>XML job description</title>
		<para>
		Now we need to write an XML file which describe the job.
		In this XML file we specify tasks composing the job, and the "predecessor/successor" orders in tasks. 
		Create a file job_HelloWorld.xml in your [working_dir], 
		and type the XML description of our simple Hello World job example.	
		</para>
		<para>
		<emphasis role="bold">directory : </emphasis><literal>[working_dir]</literal>.
		</para>
		<para>			 
		<emphasis role="bold">file : </emphasis>job_HelloWorld.xml
		</para>
		<programlisting lang="xml"><textobject><textdata fileref="scheduler/job_descriptors/java_job_1_task.xml"></textdata></textobject>	
		</programlisting>
		<para>
	<emphasis role="bold">Job tag :</emphasis>
	</para>
	<para>
	Specifies XML schema related to a job descriptor : schedulerjob.xsd
	Job have a specified name (here "Job_Hello").
	We specify the scheduling priority of the job, there are tree priority levels : lowest, low, normal (for the user, actually there are five levels, 
	but the two other levels, high and highest, can only be setted by scheduler's administrator).
	We specify a log file for the Job (don't forget to replace <literal>[working_dir]</literal> by the path of your “real” working directory. standard and error outputs of All tasks are written in this file.
	</para>
	<para>
	<emphasis role="bold">Description tag of the job: </emphasis>
	</para>
	<para>
	A literary description of the job.
	</para>
	<para>
	<emphasis role="bold">Taskflow tag :</emphasis>
	</para>
	<para>
	Specifies that the job is made of tasks that need to be executed in a certain order.
	This is not very interesting here because we have just one task ! (This Scheduler tutorial presents only this kind of job).
	</para>
	<para>
	<emphasis role="bold">Task tag :</emphasis>
	</para>
	<para>
	specifies task of the job. The task name (here "hello") is used to 
	identify the task from each other in the job, this parameter is mandatory 
	and must be unique for each task in the XML job descriptor. 
	Parameter preciousResult="true" is here to said that the task's result 
	is needed and have to be recoverable at end the of the job.
	Taskflow specification in job descriptor will be explained later.
	</para>
	<para>
	<emphasis role="bold">Description tag of the task :</emphasis>
	</para>
	<para>
	A literary description of the task.
	</para>
	<para>
	<emphasis role="bold">javaExecutable tag :</emphasis>
	</para>
	<para>
	In this tag we will define the kind of the task to schedule, 
	and where is "the business code", developed earlier. 
	So our task is a Java process and the class name of the task is 
	org.objectweb.proactive.extensions.scheduler.examples.HelloTask.
	</para>
	<para>
	Now our job is defined and ready to be scheduled !
	</para>
	</sect3>
</sect2>
<sect2 id="add_parameters">
	<title>Adding init parameters to the task</title>	
	<para>
	We can specify “init" parameters for a task, these parameters are specified in the XML descriptor,
	and are then available for the task. Let's add to our example an integer parameter 
	which specify how many times the task has to say “hello”.
	</para>	
	<sect3 id="xml_desc_add_para">
		<title>XML job description</title>	
		<para>
		<emphasis role="bold">directory : </emphasis><literal>[working_dir]</literal>.
		</para>
		<para>			 
		<emphasis role="bold">file : </emphasis>job_HelloWorld.xml
		</para>
		<programlisting lang="xml"><textobject><textdata fileref="scheduler/job_descriptors/java_job_1_task_with_param.xml"></textdata></textobject>	
		</programlisting>
		<para>
	 	We can see the new tag <emphasis role="bold">&lt;Parameters&gt;</emphasis> with its child “parameter”, 
	 	included in the javaExecutable tag. A parameter is made of a name (identifier) and a value.
	 	You can specify as parameters as you need. 
		</para>
	</sect3>
	<sect3 id="get_params">
		<title>Getting parameters in the task code</title>
	<para>
		Complete java code of the task as below :
	</para>
	<para>
			<emphasis role="bold">project : </emphasis>ProActive
			</para>
			<para>			 
			 <emphasis role="bold">directory : </emphasis>src/Extensions/org/objectweb/proactive/extensions/scheduler/examples
			</para>
			<para>			 
			 <emphasis role="bold">file : </emphasis>HelloTask.java
			</para>
			<programlisting lang="java">
package org.objectweb.proactive.extensions.scheduler.examples;

import java.util.Map;

import org.objectweb.proactive.core.util.ProActiveInet;
import org.objectweb.proactive.extensions.scheduler.common.task.TaskResult;
import org.objectweb.proactive.extensions.scheduler.common.task.executable.JavaExecutable;

public class HelloTask extends JavaExecutable{

	private int hello_number;

	public void init(Map&lt;String, Object&gt; args) {
	   if (args.containsKey("hello_number")){
	       try {
			hello_number =
			Integer.parseInt(args.get("hello_number").toString());
	       } catch (NumberFormatException e) {
	       }
	   }
	}

	public Object execute(TaskResult... results) {
		String result="";
		for(int i=0; i&lt;this.hello_number; i++)
		{	   
			result += "HelloWorld task, host : "+
			ProActiveInet.getInstance().getHostname()+"\n";
		}
        System.out.println(result);
		return result;
	  }
}
			</programlisting>
			<para>	
			We have implemented the init() function, which have in argument a Java HashMap object 
			containing init parameters, so parameters are available by their names given in the XML descriptor.
			</para>
			
	</sect3>		
</sect2>
<sect2 id="result_passing_mechanism">
	<title>result passing mechanism</title>
	<para>
	Now we will complete our HelloWorld example, we will create a task flow made of two tasks
	(called "Hello1" and "Hello2"), and the second task Hello2, will be executed after the termination
	of the Hello1 task. We will see the mechanism of results passing between two tasks,
	for example the Hello1 task will give a String with its execution date to the Hello2 task.
	</para>
	<sect3 id="task_flow_job_desc">
		<title>XML job description</title>
		<para>
		<emphasis role="bold">directory : </emphasis><literal>[working_dir]</literal>.
		</para>
		<para>			 
		<emphasis role="bold">file : </emphasis>job_HelloWorld.xml
		</para>
		<programlisting lang="xml"><textobject><textdata fileref="scheduler/job_descriptors/java_job_2_task.xml"></textdata></textobject></programlisting>
		<para>
		The job is made of two tasks. We can see that first task Hello1 hasn't got a precious 
		result anymore, but task Hello2  has it. A task-flow job must have at least one task
		with a preciousResult parameter set true. We can see in Hello2 task description a new Tag
		called <emphasis role="bold">&lt;depends&gt;</emphasis> which specify a list of tasks that have to be executed and terminated before task execution. So here, Hello2 task can be launched only if Hello1 task is terminated.
		</para>
		<para>
		We can see a new parameter in job tag : cancelOnException="false". The job continues even
		if a problem occurred on a task. With this parameter set to true, the whole job is aborted 
		if an error occurs on a task.
		</para>
		<para>
		The two tasks launch the same Java process. Let's complete our HelloTask.java file.
		</para>
</sect3>
<sect3 id="result_passing_task_code">
		<title>Task Code </title>
	<para>
		Complete java code of the task as below :
	</para>
	<para>
			 <emphasis role="bold">project : </emphasis>ProActive
			</para>
			<para>			 
			 <emphasis role="bold">directory : </emphasis>src/Extensions/org/objectweb/proactive/extensions/scheduler/examples
			</para>
			<para>			 
			 <emphasis role="bold">file : </emphasis>HelloTask.java
			</para>
			<programlisting lang="java">		
package org.objectweb.proactive.extensions.scheduler.examples;

import java.util.Date;

import org.objectweb.proactive.core.util.ProActiveInet;
import org.objectweb.proactive.extensions.scheduler.common.task.TaskResult;
import org.objectweb.proactive.extensions.scheduler.common.task.executable.JavaExecutable;

public class HelloTask extends JavaExecutable{
	
	public Object execute(TaskResult... results) throws Throwable{
		String predecessor_result=null;
		String result="";

		try{
			//get results of predecessors tasks
			for (TaskResult res : results)
				predecessor_result = ((String)res.value());
			}
			catch (Throwable e){
				   throw new Throwable("getting task input failed",e);
			}

			if(predecessor_result !=null)
				result= "my predecessor has send  : "+ predecessor_result + "\n";

			result+= "HelloWorld task, "+ new Date().toString() + " host : "
			+ProActiveInet.getInstance().getHostname()+"\n";
			System.out.println(result);
			return result;
		  } //execute()
}			
			</programlisting>
			<para>				
			We access to results of predecessor tasks by the TaskResult array in input of execute() primitive. 
			This array have a size corresponding to the number of predecessor tasks defined in the job.
			Each member of this array is a Java Object, and is accessible by the TaskResult.value() primitive.
			</para>
			<para>
			It's interesting to see the "throw Throwable" added to the primitive execute, 
			and the try/catch blocks. When we access to result of the previous task, 
			this result could be result of a task which has failed on its execution. When an error occurs on a task,
			task 's result is a Java Throwable object. That's why we have added a try/catch block for accessing 
			to the TaskResult array, because one these results could be an error. 
			The method which throws a Throwable is TaskResult.value(), you can verify if result is an exception
			by using TaskResult.hadException() method which returns a boolean, set to true if result is an error.
			</para>
			<para>
			So the catch block here is the way to implement what to do when a predecessor task has failed.
			We have chosen here to throw again a Throwable which wrap the first Throwable received.
			</para>
			<para>
			If you don't want to be annoyed with error management, you can just let the "throw Throwable" clause
			in the execute primitive, and suppress the try/catch block. If your access to a value of the TaskResult object
			(input of the primitive) which throws any Throwable, this Throwable will be automatically forwarded to the next tasks.
			</para>
			<para>
			If you set cancelOnException="true" in the XML descriptor of the job, any Throwable (or exception)
			launched by the primitive execute of a task will cancel the whole job.
			</para>				
	</sect3>
</sect2>
-->

<sect2 id="native_job">
	<title>Schedule a native task</title>
	<para>
	The scheduler provides the possibility to launch jobs containing tasks which are native executables,
	like a C/C++ program. Now we will launch a native Unix executable called nativTask, 
	this executable displayd ten dots an waits (a number of seconds given in argument) between each dot's display.
	</para>
	<sect3 id="native_c_code">
		<title>Native C code of the task</title>
	<para>
		Complete native C code of the task as below :
	</para>
	<para>
			<emphasis role="bold">project : </emphasis>ProActive
			</para>
			<para>			 
			 <emphasis role="bold">directory : </emphasis>descriptors/deployments/scheduler/jobs/job_native_linux
			</para>
			<para>			 
			 <emphasis role="bold">file : </emphasis>nativTask.c
			</para>
			<programlisting lang="c"><textobject><textdata
  						fileref="scheduler/job_descriptors/native_code_c.txt"></textdata></textobject></programlisting>
			<para>	
			You have also an unix compiled version of this program named nativTask in the same directory. Compile the native code above (or take the already compiled version), and place the executable in your <literal>[working_dir]</literal>.		
			Now we need to write an XML file which describe the job.
			</para>
	</sect3>
	<sect3 id="native_job_desc">
		<title>XML job description</title>
		<para>
		<emphasis role="bold">directory : </emphasis><literal>[working_dir]</literal>.
		</para>
		<para>
		In this XML file we specify tasks composing the job, and the "predecessor/successor" orders in tasks. 
		Create a file job_HelloWorld.xml in your [working_dir], 
		and write the code below :
		</para>
		<para>
		<emphasis role="bold">file : </emphasis>job_native.xml
		</para>
		<programlisting lang="xml"><textobject><textdata fileref="scheduler/job_descriptors/native_job.xml"></textdata></textobject></programlisting>
		<para>		
		<emphasis role="bold">Job tag :</emphasis>
		</para>
		<para>
		Specifies XML schema related to a job descriptor : schedulerjob.xsd
		Job have a specified name (here "job_nativ").
		We specify the scheduling priority of the job, there are tree priority levels : lowest, low, normal (for the user, actually there are five levels, 
		but the two other levels, high and highest, can only be setted by scheduler's administrator).
		We specify an execution path for the job, path indicates native executable location.
		We specify a log file for the Job. standard and error outputs of All native programs launched are written in this file.
		you can see ${EXE_PATH} variable, it's variable, and is explained below. 
		</para>
		<para>		
		<emphasis role="bold">Variables tag :</emphasis>
		</para>
		<para>
		Here we define the directory path variable called “EXEC_PATH”. 
		So we have just to put ${EXEC_PATH} if we want to reuse the string defined in this variable. 
		This a way for not repeating strings and doing changes rapidly. 
		</para>			
		<para>
		<emphasis role="bold">Description tag of the job: </emphasis>
		</para>
		<para>
		A literary description of the job.
		</para>
		<para>
		<emphasis role="bold">Taskflow tag :</emphasis>
		</para>
		<para>
		Specifies that the job is made of tasks that need to be executed in a certain order.
		This is not very interesting here because we have just one task ! (This Scheduler tutorial presents only this kind of job).
		</para>
		<para>
		<emphasis role="bold">Task tag :</emphasis>
		</para>
		<para>
		specifies task of the job. The task name is used to 
		identify the task from each other in the job, this parameter is mandatory 
		and must be unique for each task in the XML job descriptor. 
		Parameter preciousResult="true" is here to said that the task's result 
		is needed and have to be recoverable at end the of the job.
		We can see in 'task2 task description a Tag
		called <emphasis role="bold">&lt;depends&gt;</emphasis> which specify a list of tasks that have to be executed
		and terminated before task execution. So here, task2 can be launched only if Hello1 task is terminated.
		</para>
		<para>
		<emphasis role="bold">Description tag of the task :</emphasis>
		</para>
		<para>
		A literary description of the task.
		</para>
		<para>
		<emphasis role="bold">nativeExecutable tag :</emphasis>
		</para>
		<para>
		This tag is used in order to specify that task is execution of a native program. 
		This tag have an under tag called staticCommand with a value ;
		the path of executable file to launch. We see here utilization of EXE_PATH variable. 
		We have arguments tag under staticCommand, which permits to give parameters to the executable.
		So that you can specify parameters for execution as if you write parameters in a command line.
		In this tag we will define the kind of the task to schedule, 
		and where is "the business code", developed earlier. 
		So our task is a Java process and the class name of the task is 
		org.objectweb.proactive.extensions.scheduler.examples.HelloTask.
		</para>
		<para>
		Now our job is defined and ready to be scheduled !
		</para>
		<para>
		Launch this job. If you get results of this job, you have in result the return code
		of task1 and task2. In [working_dir]/nativTask.log, you have tasks standard and error outputs.
		</para>
	</sect3>
</sect2>
<sect2 id="launching">
	<title>Launching the scheduler and submit a job.</title>
	<para>
	Now in this part we will launch scheduler program and submit our job made of two native tasks.
	These actions are performed by scripts in directory :
	</para>
	<para>
	<literal>[ProActive_dir]/scripts/[OS]/scheduler/</literal>
	</para>
	<para>
	(we assume below we are working with a Unix system, but script for windows with .bat extension are available too).
	</para>
		<sect3 id="launch_RM">
		<title>Launching the Resource manager</title>
	Launch Resource manager with script RMlauncher.sh, it takes one argument,the path of an XML file which describes 
	the grid infrastructure on which the Resource Manager (RM) will book resources (nodes) tasks execution. 
	For the moment, launch this script without arguments, so Resource manager will
	launch 4 Java virtual machines (4 nodes) on your computer  (RM deploy by default
	<literal>[ProActive_dir]/descriptors/scheduler/deployment/Local4JVM.xml</literal>) :
	<para>
	<literal>$ RMlauncher.sh</literal>
	</para>
	<para>
	(you must refer to the ProActive documentation at http://proactive.inria.fr/release-doc/html/index.html to have more information about deployment/acquisition of nodes with the ProActive library).
	</para>
	<para>
	You can see on the standard output that RMlauncher.sh have created Resource Manager service at the URL :
	</para>
	<para>
		<literal>//localhost/RMCORE</literal>
	</para>
	</sect3>
	<sect3 id="laucnh_sched">
		<title>Launching the scheduler</title>
	<para>
	Type on the same directory (on another console):
	</para>
	<para>
	<literal>$ scheduler.sh //localhost</literal>
	</para>
	<para>
	Parameter of this shell specifies hostname of a running Resource Manager. 
	Type a hostname that has a running RM (if you don't specify an URL for the RM, scheduler creates itself a Resource Manager). 
	This script will launch the scheduler service, and the scheduler will connect 
	to Resource Manager which has been previously launched. You can see in the standard output the line :
	</para>
	<para>
	<literal>[SCHEDULER] Scheduler has just been started !</literal>
	</para>
	</sect3>
	<sect3 id="submission">
		<title>Submitting the job</title>
	<para>
	Last we submit our hello World example :
	</para>
	<para>
		<literal>$ jobLauncher.sh  -j [working_dir]/Job_native.xml -l user1</literal>
	</para>
	<para>
		-j option specifies the xml file specififying the job. -l option specifies the username.
		By default a username "user1" exists and its password is "<PASSWORD>". Type the password on the command line.
	</para>
	<para>
		This script will submit the job to the scheduler.
	</para>
	<para>
	On the standard output you see a short summary of the job, tasks and relevant parameters. 
	Important parameter is the job's ID, unique identifier of the job in scheduler. 
	This ID will be used for retrieve result of the job.
	If you return to standard output of the Scheduler service, you see the main operations of the scheduling ; 
	the new job incoming, node request to Resource Manager, node acquisition, 
	beginning of the job (with its scheduling ID), the start and end of the task, and finally the end of the job.
	</para>
	</sect3>
	<sect3 id="retrieve_result">
		<title>Retrieving the result</title>
	<para>
	When the scheduling of a job is finished, scheduler stores job's result and wait for the user to retrieve it.
	Now we will retrieve job's result thanks to its ID, launch on scheduler host this command 
	(always in <literal>[ProActive_dir]/scripts/[OS]/scheduler/</literal> directory) :	
	</para>
	<para>
		<literal>$ getResult.sh -l user1</literal> 
	</para>
	<para>
		Type the user1's password, and enter the job ID (displayed in jobLauncher standard output).
		So the job's result is displayed. Here result is just a String :
	</para>
	<para>
	<literal>
	$Job 1 Result =>
         task1 : 0
         task2 : 0
    </literal>
	</para>
	<para>
	You have two return codes of the native programs.
	</para>
	<para>
	You can open the job's log file ; <literal>[working_dir]/nativTask.log </literal>, and see the standard output of our task.
	</para>
	</sect3>		
	<sect3 id="sched_gui">
	<title>Using GUI client application for job submission</title>	
	<para>
		An RCP graphical user interface exists for jobs submition and results consultation. 
		Uncompress the application, go to Scheduler directory of uncompressed files, and launch the program : 
	</para>
	<para>
	<literal> Scheduler $ ./Scheduler 	</literal>
	</para>
	<para>
	You should have a window like this :
	</para>
	<figure id="rcp_startup">
		<title>Scheduler GUI Client on statup</title>
		<mediaobject>
		<imageobject>
		<imagedata align="center"
			fileref="scheduler/pics/tuto/rcp_startup.png" format="PNG" />
		</imageobject>
	</mediaobject>
	</figure>
	<para>
	Right click to open connection dialog, and fill fields like below :
	</para>
	<figure id="rcp_connect">
		<title>connection window of Scheduler GUI</title>
		<mediaobject>
		<imageobject>
		<imagedata align="center"
			fileref="scheduler/pics/tuto/connect.png" format="PNG" />
		</imageobject>
	</mediaobject>
	</figure>
	<para>
	Your are correctly connected to the Scheduler. You can see a first 
	glimpse of the Scheduler activity. You have on the top left, list of pending jobs, 
	on the top middle, list of currently running jobs with a progress bar, and on the top right,
	list of finished jobs which are waiting to be retrieved by their submitters.
	</para>
	<para>
	Now Launch again your job developped earlier, 
	right click in a blank area and <emphasis role="bold">choose submit a job : </emphasis> 
	</para>
	<figure id="rcp_submit">
		<title>Context menu</title>
		<mediaobject>
		<imageobject>
		<imagedata align="center"
			fileref="scheduler/pics/tuto/context_menu.png" format="PNG" />
		</imageobject>
	</mediaobject>
	</figure>
	</sect3>
	<para>
	This action creates a file explorer window, go to your <literal>[working_dir]</literal>,
	and double click on <literal>job_native.xml</literal>. The job is submitted.
	</para>
	<para>
	You can see your job staying in pending jobs area, which correspond to the waiting queue,
	then your see your job's execution and the then finally comes to the finished jobs list.
	Execution is also terminated. You can submit several jobs at the same time.
	</para>
	<para>
	If you click on the job line, you have at the bottom right of the interface, 
	a description of the job, its execution time and a brief description. 
	There is also in the task tab, list of tasks composing the jobs. 
	Click on task's line and you will see on tab right below, result obtained by the task.
	</para>
</sect2>
<sect2 id="add_sel_script">
		<title>Adding a selection script to the task</title>
		<para>
		A very useful functionality is the possibility to add a selection script to a task. 
		This selection script provides ability for the scheduler to find and select a node 
		respecting criteria for the good execution of a task. Let's complete our previous nativ
		job example with a verification script, specifying that the executable nativTask must be
		executed on a Unix/Linux system (so must not be executed on a Windows System).
		</para>
		<sect3 id="add_sel_script_xml_code">
		<title>XML job description</title>
		<para>
		Complete your xml job descriptor as below :
		</para>			
		<para>
		<emphasis role="bold">directory : </emphasis><literal>[working_dir]</literal>.
		</para>		
		<para>			 
		<emphasis role="bold">file : </emphasis>job_native.xml
		</para>		
		<programlisting lang="xml"><textobject><textdata fileref="scheduler/job_descriptors/job_native_with_s_script.xml"></textdata></textobject></programlisting>
		<para>
		We can see in the two tasks definitions, after the task's description, 
		there is a new “selection” tag which contains a path to a Javascript file.
		When the task has to be executed, the scheduler will launch this script to nodes,
		and will select a node that has answered "yes" at the execution of this script,
		then will deploy the task to this node.
		</para>
		</sect3>
		<sect3 id="select_script_js">
		<title>Code of the node selection Javascript</title>
		<para>
		Create in your <literal>[working_dir]</literal> a file as below :
		</para>		
		<para>
		<emphasis role="bold">directory : </emphasis><literal>[working_dir]</literal>.
		</para>		
		<para>			 
		<emphasis role="bold">file : </emphasis>check_unix_os.js
		</para>						
			<programlisting lang="java">			
importPackage(java.lang);

if(System.getProperty("os.name").contains("Windows"))
	selected=false;
else
	selected=true;
			</programlisting>
		<para>
		There is just one rule to know for verifying scripts creation, the script must a have a variable 
		named "<emphasis role="bold">selected</emphasis>", and must have a true or false value at the end of script execution. 
		Node selection mechanism is simple; Scheduler ask to resource manager one or several nodes that verify that script. 
		So Resource Manager will execute this script on its nodes, if after execution, one of its node has "selected" variable set to true,
		Resource manager considers that node verify selection script, and gives node to scheduler,
		which will execute the task on this node.
		If a node return "selected" variable set to false,
		Resource manager will try to provide to scheduler in another node, which validates this selection script.
		</para>				
		</sect3>
		
</sect2>
<sect2 id="pre_post">
<title>PreScript and PostScript</title>
		<para>
		Another functionality is the possibility to define pre and post scripts.
		For a given task (Java task or native task), it is possible to launch a script before
		and after its execution. This possibility can be useful to copy files to a node,
		or clean a directory before or after task execution, for example. This a way to separate from business code the preparation of execution environment and its cleaning. Here an XML sample of a task defining preTask and postTask scripts. So we will add to our native job example a script which remove a list of files from a specified directory.
		</para>
		<sect3 id="pre_post_script_xml_code">
		<title>XML job description</title>
		<para>
		Complete your xml job descriptor as below :
		</para>	
		<para>
		<emphasis role="bold">directory : </emphasis><literal>[working_dir]</literal>.
		</para>		
		<para>			 
		<emphasis role="bold">file : </emphasis>job_native.xml
		</para>		
				<programlisting lang="xml"><textobject><textdata fileref="scheduler/job_descriptors/pre_post_script.xml"></textdata></textobject>	
		</programlisting>
		</sect3>
		<sect3 id="java_script_code">
		<title>code of the removing files Javascript</title>
		<para>
		Create in your <literal>[working_dir]</literal> a file as below :
		</para>		
		<para>
		<emphasis role="bold">directory : </emphasis><literal>[working_dir]</literal>.
		</para>		
		<para>			 
		<emphasis role="bold">file : </emphasis>remove_files.js
		</para>						
			<programlisting lang="java">			
importPackage(java.io);
print("clean working directory \n");
for(i=0; i&lt;args.length;i++)
{
	var f= new File(args[i]);
	if(f["delete"]()) {
		print(args[i] +" deleted\n");
	} else {
		print("deleting "+ args[i] +" failed\n");
        }
}
			</programlisting>
		<para>
		So create in your [working_dir] 1.tmp and 2.tmp, and execute the job.
		You will see that 1.tmp is removed just  before task starting, and 2.tmp is removed at task's end.
		</para>					
		</sect3>
</sect2>
<sect2 id="command_generator">
	<title>Command generator Script</title>
	<para>
	We have seen that a native task can be launched by the scheduler on different operating systems, 
	unix or Windows for example. That's because Resource Manager can handle nodes from different computer
	architectures. We have seen the possibility to select nodes compatible with the native task to execute.
	But we can also adapt the native command to execute, corresponding to the node that Resource manager has provided.
	 ProActive Scheduler has possibility to generate dynamically the native command to launch for a task. 
	 This functionality is practical if you have versions of your native program for different OS,
	 or different versions of the native executable, optimized for dynamic libraries which differ from a host to another.
	</para>
	<para>
	Now we develop a job with a task able to launch our native executable “nativTask” on windows system or 
	on a UNIX system. First compile and build nativTask.c on a windows system in order to have a Windows specific 
	version. Let's implement a task with a command generator.
	</para>
		<sect3 id="cmd_generator_code">
		<title>XML job description</title>
		<para>
		Complete your xml job descriptor as below :
		</para>	
		<para>
		<emphasis role="bold">directory : </emphasis><literal>[working_dir]</literal>.
		</para>		
		<para>			 
		<emphasis role="bold">file : </emphasis>job_native.xml
		</para>	
			<programlisting lang="xml"><textobject><textdata fileref="scheduler/job_descriptors/command_generator.xml"></textdata></textobject></programlisting>
		</sect3>
		<sect3 id="cmd_generator_code_script">
		<title>Code of the command generator script</title>
		<para>
		Create in your <literal>[working_dir]</literal> a file as below :
		</para>		
		<para>
		<emphasis role="bold">directory : </emphasis><literal>[working_dir]</literal>.
		</para>		
		<para>			 
		<emphasis role="bold">file : </emphasis>commandGenerator.js
		</para>				
			<programlisting lang="java">
importPackage(java.lang);

if(System.getProperty("os.name").contains("Windows"))
command="c:\nativTask.exe"
else
command="[working_dir]/nativTask"
		</programlisting>
		<para>
		The script get the OS type, a build a command corresponding to the OS type.
		A generation script must define a variable named “command” which contains the native 
		command to execute. That's the only rule to know. After scheduler will get this variable
		and execute the native command defined by the Javascript.
		</para>					
		</sect3>
</sect2>

<sect2 id="tasks_env_var">
	<title>Using exported environment variables</title>
	<para>
	We have seen that each job have a  specified name in its deployment descriptor and a unique job ID given at the moment of job's submission.
	All tasks have these two same parameters specifid at the same time. You can acces to these values in task's execution environment, during task's execution.
	When a native task is launched, the task have also 4 exported environment variables :
	<itemizedlist>
		<listitem>
			<emphasis role="bold">$PAS_JOB_NAME</emphasis>: Job's name defined in its XML descriptor
		</listitem>
		<listitem>
			<emphasis role="bold">$PAS_JOB_ID</emphasis>: unique job's ID given at submission time.
		</listitem>
		<listitem>			
			<emphasis role="bold">$PAS_TASK_NAME</emphasis>: name of the task currently launched (name defined in XML descriptor).
		</listitem>
		<listitem>			
			<emphasis role="bold">$PAS_TASK_ID</emphasis>: unique task's ID.
		</listitem>
	</itemizedlist>
	</para>
	<para>
	Now we will submit a native executable which produces a file in output.
	We want to launch in parallel 4 execution of a native c executable, which takes an integer in parameter, 
	and produces a file named output.txt in its current (launching) directory. 
	If we launch simultaneously several executions instances, it will produce a collision in file output, because the different execution instances 
	will create and write into the same file in the same directory. We don't want to be annoyed by creation of
	directories for each execution instance, So this job provides a launcher.sh Unix shell which performs
	these operations automatically. launcher.sh creates before launching the executable, a temporary  dir for each task,
	its name corresponds to current task's ID environment exported variable. So this job is made of a XMl job descriptor, a native executable,
	and shell script which performs the launching.
	</para>
	<sect3 id="xml_file_output">
		<title>XML job description</title>
		<para>
		Create a new  xml job descriptor,and complete as below :
		</para>	
		<para>
		<emphasis role="bold">directory : </emphasis><literal>[working_dir]</literal>.
		</para>		
		<para>			 
		<emphasis role="bold">file : </emphasis>job_file_output.xml
		</para>	
			<programlisting lang="xml"><textobject><textdata fileref="scheduler/job_descriptors/job_file_output.xml"></textdata></textobject></programlisting>
	</sect3>
	<sect3 id="native_c_code_exec">
		<title>Native C code of the executable which produces an output file</title>
	<para>
		Create your native C executable with the code below :
	</para>
	<para>
			<emphasis role="bold">project : </emphasis>ProActive
			</para>
			<para>			 
			 <emphasis role="bold">directory : </emphasis>descriptors/deployments/scheduler/jobs/job_native_linux_file_output
			</para>
			<para>			 
			 <emphasis role="bold">file : </emphasis>nativTask.c
			</para>
			<programlisting lang="c"><textobject><textdata
  						fileref="scheduler/job_descriptors/file_output_exe.txt"></textdata></textobject></programlisting>
			<para>	
			You have also an unix compiled version of this program, named task_with_output, in the same directory.
			</para>
	</sect3>
	<sect3 id="launching_shell_script_code">
		<title>Launching shell script</title>
	<para>
			finally write your launching Shell : 
	</para>
	<para>
			<emphasis role="bold">project : </emphasis>ProActive
			</para>
			<para>			 
			 <emphasis role="bold">directory : </emphasis>descriptors/deployments/scheduler/jobs/job_native_linux_file_output
			</para>
			<para>			 
			 <emphasis role="bold">file : </emphasis>launcher.sh
			</para>
			<programlisting lang="c"><textobject><textdata
  						fileref="scheduler/job_descriptors/launcher_sh.txt"></textdata></textobject></programlisting>
			<para>
			Copy your compiled executable (task_with_output) and your launching shell script, and submit this job.
			You will see, after job's execution, 4 directories created in your <literal>[working_dir]</literal> named by the 4 tasks ID of youtr execution,
			and directories contains a file, output.txt, corresponding to outputs of the 4 execution instances launched by the job.
			</para>
	</sect3>	
</sect2>
</sect1>
</chapter>
<commit_msg>minor changes in introduction<commit_after><?xml version="1.0" encoding="UTF-8"?>
<?xml-stylesheet type="text/css" href="../viewDocbook.css"?>
<chapter id="scheduler_tutorial">
	<title> Scheduler Tutorial</title>

<sect1 id="Sched_tuto">
<title>ProActive Scheduler Tutorial</title>
	<sect2 id="proactive_scheduler_tutorial_intro">
		<title>introduction</title>
		<para>
		This chapter is a guide on using the ProActive Scheduler. 
		The Scheduler is a tool for deployment, administration and maintenance of a jobs queue 
		over  a Grid or P2P infrastructure and  over various platforms 
		following one of many set of rules regarding the job management.
		</para>
		<para>The chapter is structured in the following sections:</para>
		<itemizedlist>
		<listitem>
			Scheduler architecture <xref linkend="sched_archi"/>
		</listitem>
		<listitem>
			Task flow concept : <xref linkend="taskflow_concept"/>
		</listitem>
<!--		
		<listitem>
			We will create our first Scheduler job : <xref linkend="first_job"/>
		</listitem>
		<listitem>
			Then we will launch the scheduler and submit the job created :<xref linkend="launching"/>
		</listitem>
		</itemizedlist>	
		<para>
		After we will see some additional functionalities and different kinds of job runnable on the scheduler :
		</para>
		<itemizedlist>
		<listitem>
			Adding init parameters to a task : <xref linkend="add_parameters"/>
		</listitem>		
		<listitem>
			How to pass result of a task to another task : <xref linkend="result_passing_mechanism"/>
		</listitem>
-->	
		<listitem>
			Schedule a native executable : <xref linkend="native_job"/>
		</listitem>
		<listitem>
			Launch Scheduler and submit a job :<xref linkend="launching"/>
		</listitem>		
		<listitem>
			Node selection mechanism : <xref linkend="add_sel_script"/>
		</listitem>
		<listitem>
			PreScript and PostScript features : <xref linkend="pre_post"/>
		</listitem>
		<listitem>
			How to generate dynamically a native command to execute, depending to the node architecture : <xref linkend="command_generator"/>
		</listitem>
		<listitem>
			Exported Environment variables introduced into the task's execution environment    : <xref linkend="tasks_env_var"/>
		</listitem>		
		</itemizedlist>

		<sect3 id="prerequisites">
		<title>Prerequisites and conventions :</title>
		<itemizedlist>
		<listitem>
			<para>
			You must have an Eclipse 3.2 IDE installed, and the ProActive Project open in your Eclipse. 
			</para>
		</listitem>
		<listitem>			
			<para>
			The directory of ProActive in your system project is represented by the tag : <literal>[ProActive_dir]</literal>.
			</para>
		</listitem>
		<listitem>			
			<para>
			You need  a working directory in your system, represented here by <literal>[working_dir]</literal>.
		 	</para>
		</listitem>
		</itemizedlist>				 	
		</sect3>
	</sect2>
	<sect2 id="sched_archi">
		<title>Scheduler architecture</title>
		<para>
			The scheduler is made of two main components : the Scheduler and the Resource Manager.  
			Each of them has its own functionality :
		<itemizedlist>			
		<listitem>
			<para>
			The scheduler is in charge of registering jobs submitted 
			and put them in a queue according to a scheduling policy. 
			Then it is charged to ask Resources at the Resource Manager, 
			and execute jobs on those retrieved resources.
			</para>
		</listitem>
		<listitem>			
			<para>
			The Resource Manager (RM) handle a set of resources available for scheduling jobs.
			It takes benefits of the Proactive Library, so it can handle resources from LAN, 
			on cluster of workstations on P2P desktop Grids, or on Internet Grids. 
			Resource Manager provides the scheduler in resources, according to criteria (Operating System, dynamic libraries,
			Memory...). Resources, at ProActive point of view, are called nodes,
			so Resource Manager supplies scheduler in ProActive nodes.
			</para>
		</listitem>
		</itemizedlist>
		</para>
		<figure id="scheduler_arch">
				<title>Scheduler architecture</title>
				<mediaobject>
					<imageobject>
						<imagedata align="center"
							fileref="scheduler/pics/tuto/arch.jpg" format="JPG" />
					</imageobject>
				</mediaobject>
	</figure>
	<para>
		These two components (Scheduler and IM) are independent and run as non GUI daemon/service.
		So they can run on two different hosts.
	</para>
</sect2>
<sect2 id="taskflow_concept">
	<title>Task-flow Concept</title>
	<para> Submit a job to the ProActive Scheduler means submitting a <emphasis role="bold">task flow</emphasis>,
	which is a set of tasks. A task can be defined as a part of the job, a step to execute in the job.
	Jobs can also be made of different tasks, i.e. different steps to execute.
	Task is most little part of a job, the smallest schedulable entity. ProActive Scheduler has 
	computing nodes to execute jobs, basically it launches on each node an execution
	of a task, and when task is ended, launches another etc...
	</para>
	<sect3 id="task_flow_illust">
	<title>Parallel tasks,  predecessor tasks</title>
	<para>
		When you build your job, you create a graph of tasks, with a definition of predecessor/successor between tasks :
	</para>
	<figure id="scheduler_job">
				<title>Scheduler architecture</title>
				<mediaobject>
					<imageobject>
						<imagedata align="center"
							fileref="scheduler/pics/core/schedulerJob.jpg" format="JPG" />
					</imageobject>
				</mediaobject>
	</figure>
	<para>
	In this tasks graph, we see that task 4 is preceded by task 1, that means scheduler waits end of task 1 execution 
	before launching task 4. In a more concrete way, task 1 could be calculation of a part of the problem to solve, 
	and task 4 takes result provided by task 1 and compute another step of the calculation. 
	We introduce here concept of <emphasis role="bold">result passing</emphasis> between tasks, explained later. 
	This relation is called a dependence, and we say that task 4 <emphasis role="bold">depends</emphasis> on task 1. 
	</para>
	<para>
	We see that task 1, 2 and 3 are not linked, so these three tasks can be executed in <emphasis role="bold">parallel</emphasis>, 
	because there are independent from each other.
	</para>
	<para>	
	Finally we see task 7 and 8 are at end of the oriented graph, These are task which produce final
	results of the job expected by the user, we call these final results <emphasis role="bold">Precious result</emphasis>.
	</para>
	<para>
	Definition of the task-flow graph is made at job's definition, before scheduling, and cannot be modified during
	execution of the job, this kind of work flow is called a <emphasis role="bold">static work flow</emphasis>.
	A Task flow job is described in XML language.
	</para>
	</sect3>
</sect2>

<!--



<sect2 id="first_job">
	<title>Developing my first job</title>	
	<para>
	In this part we will build a basic job 's example which can be submitted to the scheduler. 
	For the first example we will create a job containing just one task. We have two files to provide :
		<itemizedlist>
		<listitem>
			a Java Class file representing the computing code of the task.
		</listitem>
		<listitem>
			an XML file describing the job (tasks composing the job).
		</listitem>
		</itemizedlist>
	</para>

		<sect3 id="Task_Code.">
			<title>Task Code</title>
			<para>
				We will create a Java class derived from JavaExecutable and containing the primitive execute. 
				This function should be declared to implement the "business code" of the task. 
				When the task is deployed on a resource (a node), this function is called to complete task's objective. 
				Open ProActive project in your Eclipse IDE and create a new Java class called HelloTask.java 
				in the the src/Extensions/org/objectweb/proactive/extensions/scheduler/examples directory. 
				Type in the file the code below :
			</para>
			<para>
			 <emphasis role="bold">project : </emphasis>ProActive
			</para>
			<para>			 
			 <emphasis role="bold">directory : </emphasis>src/Extensions/org/objectweb/proactive/extensions/scheduler/examples
			</para>
			<para>			 
			 <emphasis role="bold">file : </emphasis>HelloTask.java
			</para>
			<programlisting lang="java">			
package org.objectweb.proactive.extensions.scheduler.examples;

import org.objectweb.proactive.core.util.ProActiveInet;
import org.objectweb.proactive.extensions.scheduler.common.task.TaskResult;
import org.objectweb.proactive.extensions.scheduler.common.task.executable.JavaExecutable;

public class HelloTask extends JavaExecutable{

	public Object execute(TaskResult... results) {
		  	String result= "HelloWorld task, host : ";
            result += ProActiveInet.getInstance().getHostname();
            System.out.println(result);
      		return result;
	  }
}						
			</programlisting>
	<para>
	In this example, the task says Hello, and display host address of the resource (node) where the task is executed.
	We see that primitive execute() have TaskResult objects in arguments, and must return an Object, 
	which is considered as the result of the task. these two aspects of the primitive are made 
	for the result passing mechanism between tasks, and will be explained later.
	</para>
	<para>
	Compile these file. You can compile with your eclipse IDE,  or type this command (For Unix systems) :
	</para>
	<para>
	<literal>
	[ProActive_dir]/compile/build compile
	</literal> 
	</para>
	<para>
	If your a are on a windows system, type :
	</para>
	<para>
	<literal>
	[ProActive_dir]/compile/build.bat compile
	</literal> 
	</para>			
	</sect3>
	<sect3 id="XML_description">
	<title>XML job description</title>
		<para>
		Now we need to write an XML file which describe the job.
		In this XML file we specify tasks composing the job, and the "predecessor/successor" orders in tasks. 
		Create a file job_HelloWorld.xml in your [working_dir], 
		and type the XML description of our simple Hello World job example.	
		</para>
		<para>
		<emphasis role="bold">directory : </emphasis><literal>[working_dir]</literal>.
		</para>
		<para>			 
		<emphasis role="bold">file : </emphasis>job_HelloWorld.xml
		</para>
		<programlisting lang="xml"><textobject><textdata fileref="scheduler/job_descriptors/java_job_1_task.xml"></textdata></textobject>	
		</programlisting>
		<para>
	<emphasis role="bold">Job tag :</emphasis>
	</para>
	<para>
	Specifies XML schema related to a job descriptor : schedulerjob.xsd
	Job have a specified name (here "Job_Hello").
	We specify the scheduling priority of the job, there are tree priority levels : lowest, low, normal (for the user, actually there are five levels, 
	but the two other levels, high and highest, can only be setted by scheduler's administrator).
	We specify a log file for the Job (don't forget to replace <literal>[working_dir]</literal> by the path of your “real” working directory. standard and error outputs of All tasks are written in this file.
	</para>
	<para>
	<emphasis role="bold">Description tag of the job: </emphasis>
	</para>
	<para>
	A literary description of the job.
	</para>
	<para>
	<emphasis role="bold">Taskflow tag :</emphasis>
	</para>
	<para>
	Specifies that the job is made of tasks that need to be executed in a certain order.
	This is not very interesting here because we have just one task ! (This Scheduler tutorial presents only this kind of job).
	</para>
	<para>
	<emphasis role="bold">Task tag :</emphasis>
	</para>
	<para>
	specifies task of the job. The task name (here "hello") is used to 
	identify the task from each other in the job, this parameter is mandatory 
	and must be unique for each task in the XML job descriptor. 
	Parameter preciousResult="true" is here to said that the task's result 
	is needed and have to be recoverable at end the of the job.
	Taskflow specification in job descriptor will be explained later.
	</para>
	<para>
	<emphasis role="bold">Description tag of the task :</emphasis>
	</para>
	<para>
	A literary description of the task.
	</para>
	<para>
	<emphasis role="bold">javaExecutable tag :</emphasis>
	</para>
	<para>
	In this tag we will define the kind of the task to schedule, 
	and where is "the business code", developed earlier. 
	So our task is a Java process and the class name of the task is 
	org.objectweb.proactive.extensions.scheduler.examples.HelloTask.
	</para>
	<para>
	Now our job is defined and ready to be scheduled !
	</para>
	</sect3>
</sect2>
<sect2 id="add_parameters">
	<title>Adding init parameters to the task</title>	
	<para>
	We can specify “init" parameters for a task, these parameters are specified in the XML descriptor,
	and are then available for the task. Let's add to our example an integer parameter 
	which specify how many times the task has to say “hello”.
	</para>	
	<sect3 id="xml_desc_add_para">
		<title>XML job description</title>	
		<para>
		<emphasis role="bold">directory : </emphasis><literal>[working_dir]</literal>.
		</para>
		<para>			 
		<emphasis role="bold">file : </emphasis>job_HelloWorld.xml
		</para>
		<programlisting lang="xml"><textobject><textdata fileref="scheduler/job_descriptors/java_job_1_task_with_param.xml"></textdata></textobject>	
		</programlisting>
		<para>
	 	We can see the new tag <emphasis role="bold">&lt;Parameters&gt;</emphasis> with its child “parameter”, 
	 	included in the javaExecutable tag. A parameter is made of a name (identifier) and a value.
	 	You can specify as parameters as you need. 
		</para>
	</sect3>
	<sect3 id="get_params">
		<title>Getting parameters in the task code</title>
	<para>
		Complete java code of the task as below :
	</para>
	<para>
			<emphasis role="bold">project : </emphasis>ProActive
			</para>
			<para>			 
			 <emphasis role="bold">directory : </emphasis>src/Extensions/org/objectweb/proactive/extensions/scheduler/examples
			</para>
			<para>			 
			 <emphasis role="bold">file : </emphasis>HelloTask.java
			</para>
			<programlisting lang="java">
package org.objectweb.proactive.extensions.scheduler.examples;

import java.util.Map;

import org.objectweb.proactive.core.util.ProActiveInet;
import org.objectweb.proactive.extensions.scheduler.common.task.TaskResult;
import org.objectweb.proactive.extensions.scheduler.common.task.executable.JavaExecutable;

public class HelloTask extends JavaExecutable{

	private int hello_number;

	public void init(Map&lt;String, Object&gt; args) {
	   if (args.containsKey("hello_number")){
	       try {
			hello_number =
			Integer.parseInt(args.get("hello_number").toString());
	       } catch (NumberFormatException e) {
	       }
	   }
	}

	public Object execute(TaskResult... results) {
		String result="";
		for(int i=0; i&lt;this.hello_number; i++)
		{	   
			result += "HelloWorld task, host : "+
			ProActiveInet.getInstance().getHostname()+"\n";
		}
        System.out.println(result);
		return result;
	  }
}
			</programlisting>
			<para>	
			We have implemented the init() function, which have in argument a Java HashMap object 
			containing init parameters, so parameters are available by their names given in the XML descriptor.
			</para>
			
	</sect3>		
</sect2>
<sect2 id="result_passing_mechanism">
	<title>result passing mechanism</title>
	<para>
	Now we will complete our HelloWorld example, we will create a task flow made of two tasks
	(called "Hello1" and "Hello2"), and the second task Hello2, will be executed after the termination
	of the Hello1 task. We will see the mechanism of results passing between two tasks,
	for example the Hello1 task will give a String with its execution date to the Hello2 task.
	</para>
	<sect3 id="task_flow_job_desc">
		<title>XML job description</title>
		<para>
		<emphasis role="bold">directory : </emphasis><literal>[working_dir]</literal>.
		</para>
		<para>			 
		<emphasis role="bold">file : </emphasis>job_HelloWorld.xml
		</para>
		<programlisting lang="xml"><textobject><textdata fileref="scheduler/job_descriptors/java_job_2_task.xml"></textdata></textobject></programlisting>
		<para>
		The job is made of two tasks. We can see that first task Hello1 hasn't got a precious 
		result anymore, but task Hello2  has it. A task-flow job must have at least one task
		with a preciousResult parameter set true. We can see in Hello2 task description a new Tag
		called <emphasis role="bold">&lt;depends&gt;</emphasis> which specify a list of tasks that have to be executed and terminated before task execution. So here, Hello2 task can be launched only if Hello1 task is terminated.
		</para>
		<para>
		We can see a new parameter in job tag : cancelOnException="false". The job continues even
		if a problem occurred on a task. With this parameter set to true, the whole job is aborted 
		if an error occurs on a task.
		</para>
		<para>
		The two tasks launch the same Java process. Let's complete our HelloTask.java file.
		</para>
</sect3>
<sect3 id="result_passing_task_code">
		<title>Task Code </title>
	<para>
		Complete java code of the task as below :
	</para>
	<para>
			 <emphasis role="bold">project : </emphasis>ProActive
			</para>
			<para>			 
			 <emphasis role="bold">directory : </emphasis>src/Extensions/org/objectweb/proactive/extensions/scheduler/examples
			</para>
			<para>			 
			 <emphasis role="bold">file : </emphasis>HelloTask.java
			</para>
			<programlisting lang="java">		
package org.objectweb.proactive.extensions.scheduler.examples;

import java.util.Date;

import org.objectweb.proactive.core.util.ProActiveInet;
import org.objectweb.proactive.extensions.scheduler.common.task.TaskResult;
import org.objectweb.proactive.extensions.scheduler.common.task.executable.JavaExecutable;

public class HelloTask extends JavaExecutable{
	
	public Object execute(TaskResult... results) throws Throwable{
		String predecessor_result=null;
		String result="";

		try{
			//get results of predecessors tasks
			for (TaskResult res : results)
				predecessor_result = ((String)res.value());
			}
			catch (Throwable e){
				   throw new Throwable("getting task input failed",e);
			}

			if(predecessor_result !=null)
				result= "my predecessor has send  : "+ predecessor_result + "\n";

			result+= "HelloWorld task, "+ new Date().toString() + " host : "
			+ProActiveInet.getInstance().getHostname()+"\n";
			System.out.println(result);
			return result;
		  } //execute()
}			
			</programlisting>
			<para>				
			We access to results of predecessor tasks by the TaskResult array in input of execute() primitive. 
			This array have a size corresponding to the number of predecessor tasks defined in the job.
			Each member of this array is a Java Object, and is accessible by the TaskResult.value() primitive.
			</para>
			<para>
			It's interesting to see the "throw Throwable" added to the primitive execute, 
			and the try/catch blocks. When we access to result of the previous task, 
			this result could be result of a task which has failed on its execution. When an error occurs on a task,
			task 's result is a Java Throwable object. That's why we have added a try/catch block for accessing 
			to the TaskResult array, because one these results could be an error. 
			The method which throws a Throwable is TaskResult.value(), you can verify if result is an exception
			by using TaskResult.hadException() method which returns a boolean, set to true if result is an error.
			</para>
			<para>
			So the catch block here is the way to implement what to do when a predecessor task has failed.
			We have chosen here to throw again a Throwable which wrap the first Throwable received.
			</para>
			<para>
			If you don't want to be annoyed with error management, you can just let the "throw Throwable" clause
			in the execute primitive, and suppress the try/catch block. If your access to a value of the TaskResult object
			(input of the primitive) which throws any Throwable, this Throwable will be automatically forwarded to the next tasks.
			</para>
			<para>
			If you set cancelOnException="true" in the XML descriptor of the job, any Throwable (or exception)
			launched by the primitive execute of a task will cancel the whole job.
			</para>				
	</sect3>
</sect2>
-->

<sect2 id="native_job">
	<title>Schedule a native task</title>
	<para>
	The scheduler provides the possibility to launch jobs containing tasks which are native executables,
	like a C/C++ program. Now we will launch a native Unix executable called nativTask, 
	this executable displayd ten dots an waits (a number of seconds given in argument) between each dot's display.
	</para>
	<sect3 id="native_c_code">
		<title>Native C code of the task</title>
	<para>
		Complete native C code of the task as below :
	</para>
	<para>
			<emphasis role="bold">project : </emphasis>ProActive
			</para>
			<para>			 
			 <emphasis role="bold">directory : </emphasis>descriptors/deployments/scheduler/jobs/job_native_linux
			</para>
			<para>			 
			 <emphasis role="bold">file : </emphasis>nativTask.c
			</para>
			<programlisting lang="c"><textobject><textdata
  						fileref="scheduler/job_descriptors/native_code_c.txt"></textdata></textobject></programlisting>
			<para>	
			You have also an unix compiled version of this program named nativTask in the same directory. Compile the native code above (or take the already compiled version), and place the executable in your <literal>[working_dir]</literal>.		
			Now we need to write an XML file which describe the job.
			</para>
	</sect3>
	<sect3 id="native_job_desc">
		<title>XML job description</title>
		<para>
		<emphasis role="bold">directory : </emphasis><literal>[working_dir]</literal>.
		</para>
		<para>
		In this XML file we specify tasks composing the job, and the "predecessor/successor" orders in tasks. 
		Create a file job_HelloWorld.xml in your [working_dir], 
		and write the code below :
		</para>
		<para>
		<emphasis role="bold">file : </emphasis>job_native.xml
		</para>
		<programlisting lang="xml"><textobject><textdata fileref="scheduler/job_descriptors/native_job.xml"></textdata></textobject></programlisting>
		<para>		
		<emphasis role="bold">Job tag :</emphasis>
		</para>
		<para>
		Specifies XML schema related to a job descriptor : schedulerjob.xsd
		Job have a specified name (here "job_nativ").
		We specify the scheduling priority of the job, there are tree priority levels : lowest, low, normal (for the user, actually there are five levels, 
		but the two other levels, high and highest, can only be setted by scheduler's administrator).
		We specify an execution path for the job, path indicates native executable location.
		We specify a log file for the Job. standard and error outputs of All native programs launched are written in this file.
		you can see ${EXE_PATH} variable, it's variable, and is explained below. 
		</para>
		<para>		
		<emphasis role="bold">Variables tag :</emphasis>
		</para>
		<para>
		Here we define the directory path variable called “EXEC_PATH”. 
		So we have just to put ${EXEC_PATH} if we want to reuse the string defined in this variable. 
		This a way for not repeating strings and doing changes rapidly. 
		</para>			
		<para>
		<emphasis role="bold">Description tag of the job: </emphasis>
		</para>
		<para>
		A literary description of the job.
		</para>
		<para>
		<emphasis role="bold">Taskflow tag :</emphasis>
		</para>
		<para>
		Specifies that the job is made of tasks that need to be executed in a certain order.
		This is not very interesting here because we have just one task ! (This Scheduler tutorial presents only this kind of job).
		</para>
		<para>
		<emphasis role="bold">Task tag :</emphasis>
		</para>
		<para>
		specifies task of the job. The task name is used to 
		identify the task from each other in the job, this parameter is mandatory 
		and must be unique for each task in the XML job descriptor. 
		Parameter preciousResult="true" is here to said that the task's result 
		is needed and have to be recoverable at end the of the job.
		We can see in 'task2 task description a Tag
		called <emphasis role="bold">&lt;depends&gt;</emphasis> which specify a list of tasks that have to be executed
		and terminated before task execution. So here, task2 can be launched only if Hello1 task is terminated.
		</para>
		<para>
		<emphasis role="bold">Description tag of the task :</emphasis>
		</para>
		<para>
		A literary description of the task.
		</para>
		<para>
		<emphasis role="bold">nativeExecutable tag :</emphasis>
		</para>
		<para>
		This tag is used in order to specify that task is execution of a native program. 
		This tag have an under tag called staticCommand with a value ;
		the path of executable file to launch. We see here utilization of EXE_PATH variable. 
		We have arguments tag under staticCommand, which permits to give parameters to the executable.
		So that you can specify parameters for execution as if you write parameters in a command line.
		In this tag we will define the kind of the task to schedule, 
		and where is "the business code", developed earlier. 
		So our task is a Java process and the class name of the task is 
		org.objectweb.proactive.extensions.scheduler.examples.HelloTask.
		</para>
		<para>
		Now our job is defined and ready to be scheduled !
		</para>
		<para>
		Launch this job. If you get results of this job, you have in result the return code
		of task1 and task2. In [working_dir]/nativTask.log, you have tasks standard and error outputs.
		</para>
	</sect3>
</sect2>
<sect2 id="launching">
	<title>Launching the scheduler and submit a job.</title>
	<para>
	Now in this part we will launch scheduler program and submit our job made of two native tasks.
	These actions are performed by scripts in directory :
	</para>
	<para>
	<literal>[ProActive_dir]/scripts/[OS]/scheduler/</literal>
	</para>
	<para>
	(we assume below we are working with a Unix system, but script for windows with .bat extension are available too).
	</para>
		<sect3 id="launch_RM">
		<title>Launching the Resource manager</title>
	Launch Resource manager with script RMlauncher.sh, it takes one argument,the path of an XML file which describes 
	the grid infrastructure on which the Resource Manager (RM) will book resources (nodes) tasks execution. 
	For the moment, launch this script without arguments, so Resource manager will
	launch 4 Java virtual machines (4 nodes) on your computer  (RM deploy by default
	<literal>[ProActive_dir]/descriptors/scheduler/deployment/Local4JVM.xml</literal>) :
	<para>
	<literal>$ RMlauncher.sh</literal>
	</para>
	<para>
	(you must refer to the ProActive documentation at http://proactive.inria.fr/release-doc/html/index.html to have more information about deployment/acquisition of nodes with the ProActive library).
	</para>
	<para>
	You can see on the standard output that RMlauncher.sh have created Resource Manager service at the URL :
	</para>
	<para>
		<literal>//localhost/RMCORE</literal>
	</para>
	</sect3>
	<sect3 id="laucnh_sched">
		<title>Launching the scheduler</title>
	<para>
	Type on the same directory (on another console):
	</para>
	<para>
	<literal>$ scheduler.sh //localhost</literal>
	</para>
	<para>
	Parameter of this shell specifies hostname of a running Resource Manager. 
	Type a hostname that has a running RM (if you don't specify an URL for the RM, scheduler creates itself a Resource Manager). 
	This script will launch the scheduler service, and the scheduler will connect 
	to Resource Manager which has been previously launched. You can see in the standard output the line :
	</para>
	<para>
	<literal>[SCHEDULER] Scheduler has just been started !</literal>
	</para>
	</sect3>
	<sect3 id="submission">
		<title>Submitting the job</title>
	<para>
	Last we submit our hello World example :
	</para>
	<para>
		<literal>$ jobLauncher.sh  -j [working_dir]/Job_native.xml -l user1</literal>
	</para>
	<para>
		-j option specifies the xml file specififying the job. -l option specifies the username.
		By default a username "user1" exists and its password is "<PASSWORD>". Type the password on the command line.
	</para>
	<para>
		This script will submit the job to the scheduler.
	</para>
	<para>
	On the standard output you see a short summary of the job, tasks and relevant parameters. 
	Important parameter is the job's ID, unique identifier of the job in scheduler. 
	This ID will be used for retrieve result of the job.
	If you return to standard output of the Scheduler service, you see the main operations of the scheduling ; 
	the new job incoming, node request to Resource Manager, node acquisition, 
	beginning of the job (with its scheduling ID), the start and end of the task, and finally the end of the job.
	</para>
	</sect3>
	<sect3 id="retrieve_result">
		<title>Retrieving the result</title>
	<para>
	When the scheduling of a job is finished, scheduler stores job's result and wait for the user to retrieve it.
	Now we will retrieve job's result thanks to its ID, launch on scheduler host this command 
	(always in <literal>[ProActive_dir]/scripts/[OS]/scheduler/</literal> directory) :	
	</para>
	<para>
		<literal>$ getResult.sh -l user1</literal> 
	</para>
	<para>
		Type the user1's password, and enter the job ID (displayed in jobLauncher standard output).
		So the job's result is displayed. Here result is just a String :
	</para>
	<para>
	<literal>
	$Job 1 Result =>
         task1 : 0
         task2 : 0
    </literal>
	</para>
	<para>
	You have two return codes of the native programs.
	</para>
	<para>
	You can open the job's log file ; <literal>[working_dir]/nativTask.log </literal>, and see the standard output of our task.
	</para>
	</sect3>		
	<sect3 id="sched_gui">
	<title>Using GUI client application for job submission</title>	
	<para>
		An RCP graphical user interface exists for jobs submition and results consultation. 
		Uncompress the application, go to Scheduler directory of uncompressed files, and launch the program : 
	</para>
	<para>
	<literal> Scheduler $ ./Scheduler 	</literal>
	</para>
	<para>
	You should have a window like this :
	</para>
	<figure id="rcp_startup">
		<title>Scheduler GUI Client on statup</title>
		<mediaobject>
		<imageobject>
		<imagedata align="center"
			fileref="scheduler/pics/tuto/rcp_startup.png" format="PNG" />
		</imageobject>
	</mediaobject>
	</figure>
	<para>
	Right click to open connection dialog, and fill fields like below :
	</para>
	<figure id="rcp_connect">
		<title>connection window of Scheduler GUI</title>
		<mediaobject>
		<imageobject>
		<imagedata align="center"
			fileref="scheduler/pics/tuto/connect.png" format="PNG" />
		</imageobject>
	</mediaobject>
	</figure>
	<para>
	Your are correctly connected to the Scheduler. You can see a first 
	glimpse of the Scheduler activity. You have on the top left, list of pending jobs, 
	on the top middle, list of currently running jobs with a progress bar, and on the top right,
	list of finished jobs which are waiting to be retrieved by their submitters.
	</para>
	<para>
	Now Launch again your job developped earlier, 
	right click in a blank area and <emphasis role="bold">choose submit a job : </emphasis> 
	</para>
	<figure id="rcp_submit">
		<title>Context menu</title>
		<mediaobject>
		<imageobject>
		<imagedata align="center"
			fileref="scheduler/pics/tuto/context_menu.png" format="PNG" />
		</imageobject>
	</mediaobject>
	</figure>
	</sect3>
	<para>
	This action creates a file explorer window, go to your <literal>[working_dir]</literal>,
	and double click on <literal>job_native.xml</literal>. The job is submitted.
	</para>
	<para>
	You can see your job staying in pending jobs area, which correspond to the waiting queue,
	then your see your job's execution and the then finally comes to the finished jobs list.
	Execution is also terminated. You can submit several jobs at the same time.
	</para>
	<para>
	If you click on the job line, you have at the bottom right of the interface, 
	a description of the job, its execution time and a brief description. 
	There is also in the task tab, list of tasks composing the jobs. 
	Click on task's line and you will see on tab right below, result obtained by the task.
	</para>
</sect2>
<sect2 id="add_sel_script">
		<title>Adding a selection script to the task</title>
		<para>
		A very useful functionality is the possibility to add a selection script to a task. 
		This selection script provides ability for the scheduler to find and select a node 
		respecting criteria for the good execution of a task. Let's complete our previous nativ
		job example with a verification script, specifying that the executable nativTask must be
		executed on a Unix/Linux system (so must not be executed on a Windows System).
		</para>
		<sect3 id="add_sel_script_xml_code">
		<title>XML job description</title>
		<para>
		Complete your xml job descriptor as below :
		</para>			
		<para>
		<emphasis role="bold">directory : </emphasis><literal>[working_dir]</literal>.
		</para>		
		<para>			 
		<emphasis role="bold">file : </emphasis>job_native.xml
		</para>		
		<programlisting lang="xml"><textobject><textdata fileref="scheduler/job_descriptors/job_native_with_s_script.xml"></textdata></textobject></programlisting>
		<para>
		We can see in the two tasks definitions, after the task's description, 
		there is a new “selection” tag which contains a path to a Javascript file.
		When the task has to be executed, the scheduler will launch this script to nodes,
		and will select a node that has answered "yes" at the execution of this script,
		then will deploy the task to this node.
		</para>
		</sect3>
		<sect3 id="select_script_js">
		<title>Code of the node selection Javascript</title>
		<para>
		Create in your <literal>[working_dir]</literal> a file as below :
		</para>		
		<para>
		<emphasis role="bold">directory : </emphasis><literal>[working_dir]</literal>.
		</para>		
		<para>			 
		<emphasis role="bold">file : </emphasis>check_unix_os.js
		</para>						
			<programlisting lang="java">			
importPackage(java.lang);

if(System.getProperty("os.name").contains("Windows"))
	selected=false;
else
	selected=true;
			</programlisting>
		<para>
		There is just one rule to know for verifying scripts creation, the script must a have a variable 
		named "<emphasis role="bold">selected</emphasis>", and must have a true or false value at the end of script execution. 
		Node selection mechanism is simple; Scheduler ask to resource manager one or several nodes that verify that script. 
		So Resource Manager will execute this script on its nodes, if after execution, one of its node has "selected" variable set to true,
		Resource manager considers that node verify selection script, and gives node to scheduler,
		which will execute the task on this node.
		If a node return "selected" variable set to false,
		Resource manager will try to provide to scheduler in another node, which validates this selection script.
		</para>				
		</sect3>
		
</sect2>
<sect2 id="pre_post">
<title>PreScript and PostScript</title>
		<para>
		Another functionality is the possibility to define pre and post scripts.
		For a given task (Java task or native task), it is possible to launch a script before
		and after its execution. This possibility can be useful to copy files to a node,
		or clean a directory before or after task execution, for example. This a way to separate from business code the preparation of execution environment and its cleaning. Here an XML sample of a task defining preTask and postTask scripts. So we will add to our native job example a script which remove a list of files from a specified directory.
		</para>
		<sect3 id="pre_post_script_xml_code">
		<title>XML job description</title>
		<para>
		Complete your xml job descriptor as below :
		</para>	
		<para>
		<emphasis role="bold">directory : </emphasis><literal>[working_dir]</literal>.
		</para>		
		<para>			 
		<emphasis role="bold">file : </emphasis>job_native.xml
		</para>		
				<programlisting lang="xml"><textobject><textdata fileref="scheduler/job_descriptors/pre_post_script.xml"></textdata></textobject>	
		</programlisting>
		</sect3>
		<sect3 id="java_script_code">
		<title>code of the removing files Javascript</title>
		<para>
		Create in your <literal>[working_dir]</literal> a file as below :
		</para>		
		<para>
		<emphasis role="bold">directory : </emphasis><literal>[working_dir]</literal>.
		</para>		
		<para>			 
		<emphasis role="bold">file : </emphasis>remove_files.js
		</para>						
			<programlisting lang="java">			
importPackage(java.io);
print("clean working directory \n");
for(i=0; i&lt;args.length;i++)
{
	var f= new File(args[i]);
	if(f["delete"]()) {
		print(args[i] +" deleted\n");
	} else {
		print("deleting "+ args[i] +" failed\n");
        }
}
			</programlisting>
		<para>
		So create in your [working_dir] 1.tmp and 2.tmp, and execute the job.
		You will see that 1.tmp is removed just  before task starting, and 2.tmp is removed at task's end.
		</para>					
		</sect3>
</sect2>
<sect2 id="command_generator">
	<title>Command generator Script</title>
	<para>
	We have seen that a native task can be launched by the scheduler on different operating systems, 
	unix or Windows for example. That's because Resource Manager can handle nodes from different computer
	architectures. We have seen the possibility to select nodes compatible with the native task to execute.
	But we can also adapt the native command to execute, corresponding to the node that Resource manager has provided.
	 ProActive Scheduler has possibility to generate dynamically the native command to launch for a task. 
	 This functionality is practical if you have versions of your native program for different OS,
	 or different versions of the native executable, optimized for dynamic libraries which differ from a host to another.
	</para>
	<para>
	Now we develop a job with a task able to launch our native executable “nativTask” on windows system or 
	on a UNIX system. First compile and build nativTask.c on a windows system in order to have a Windows specific 
	version. Let's implement a task with a command generator.
	</para>
		<sect3 id="cmd_generator_code">
		<title>XML job description</title>
		<para>
		Complete your xml job descriptor as below :
		</para>	
		<para>
		<emphasis role="bold">directory : </emphasis><literal>[working_dir]</literal>.
		</para>		
		<para>			 
		<emphasis role="bold">file : </emphasis>job_native.xml
		</para>	
			<programlisting lang="xml"><textobject><textdata fileref="scheduler/job_descriptors/command_generator.xml"></textdata></textobject></programlisting>
		</sect3>
		<sect3 id="cmd_generator_code_script">
		<title>Code of the command generator script</title>
		<para>
		Create in your <literal>[working_dir]</literal> a file as below :
		</para>		
		<para>
		<emphasis role="bold">directory : </emphasis><literal>[working_dir]</literal>.
		</para>		
		<para>			 
		<emphasis role="bold">file : </emphasis>commandGenerator.js
		</para>				
			<programlisting lang="java">
importPackage(java.lang);

if(System.getProperty("os.name").contains("Windows"))
command="c:\nativTask.exe"
else
command="[working_dir]/nativTask"
		</programlisting>
		<para>
		The script get the OS type, a build a command corresponding to the OS type.
		A generation script must define a variable named “command” which contains the native 
		command to execute. That's the only rule to know. After scheduler will get this variable
		and execute the native command defined by the Javascript.
		</para>					
		</sect3>
</sect2>

<sect2 id="tasks_env_var">
	<title>Using exported environment variables</title>
	<para>
	We have seen that each job have a  specified name in its deployment descriptor and a unique job ID given at the moment of job's submission.
	All tasks have these two same parameters specifid at the same time. You can acces to these values in task's execution environment, during task's execution.
	When a native task is launched, the task have also 4 exported environment variables :
	<itemizedlist>
		<listitem>
			<emphasis role="bold">$PAS_JOB_NAME</emphasis>: Job's name defined in its XML descriptor
		</listitem>
		<listitem>
			<emphasis role="bold">$PAS_JOB_ID</emphasis>: unique job's ID given at submission time.
		</listitem>
		<listitem>			
			<emphasis role="bold">$PAS_TASK_NAME</emphasis>: name of the task currently launched (name defined in XML descriptor).
		</listitem>
		<listitem>			
			<emphasis role="bold">$PAS_TASK_ID</emphasis>: unique task's ID.
		</listitem>
	</itemizedlist>
	</para>
	<para>
	Now we will submit a native executable which produces a file in output.
	We want to launch in parallel 4 execution of a native c executable, which takes an integer in parameter, 
	and produces a file named output.txt in its current (launching) directory. 
	If we launch simultaneously several executions instances, it will produce a collision in file output, because the different execution instances 
	will create and write into the same file in the same directory. We don't want to be annoyed by creation of
	directories for each execution instance, So this job provides a launcher.sh Unix shell which performs
	these operations automatically. launcher.sh creates before launching the executable, a temporary  dir for each task,
	its name corresponds to current task's ID environment exported variable. So this job is made of a XMl job descriptor, a native executable,
	and shell script which performs the launching.
	</para>
	<sect3 id="xml_file_output">
		<title>XML job description</title>
		<para>
		Create a new  xml job descriptor,and complete as below :
		</para>	
		<para>
		<emphasis role="bold">directory : </emphasis><literal>[working_dir]</literal>.
		</para>		
		<para>			 
		<emphasis role="bold">file : </emphasis>job_file_output.xml
		</para>	
			<programlisting lang="xml"><textobject><textdata fileref="scheduler/job_descriptors/job_file_output.xml"></textdata></textobject></programlisting>
	</sect3>
	<sect3 id="native_c_code_exec">
		<title>Native C code of the executable which produces an output file</title>
	<para>
		Create your native C executable with the code below :
	</para>
	<para>
			<emphasis role="bold">project : </emphasis>ProActive
			</para>
			<para>			 
			 <emphasis role="bold">directory : </emphasis>descriptors/deployments/scheduler/jobs/job_native_linux_file_output
			</para>
			<para>			 
			 <emphasis role="bold">file : </emphasis>nativTask.c
			</para>
			<programlisting lang="c"><textobject><textdata
  						fileref="scheduler/job_descriptors/file_output_exe.txt"></textdata></textobject></programlisting>
			<para>	
			You have also an unix compiled version of this program, named task_with_output, in the same directory.
			</para>
	</sect3>
	<sect3 id="launching_shell_script_code">
		<title>Launching shell script</title>
	<para>
			finally write your launching Shell : 
	</para>
	<para>
			<emphasis role="bold">project : </emphasis>ProActive
			</para>
			<para>			 
			 <emphasis role="bold">directory : </emphasis>descriptors/deployments/scheduler/jobs/job_native_linux_file_output
			</para>
			<para>			 
			 <emphasis role="bold">file : </emphasis>launcher.sh
			</para>
			<programlisting lang="c"><textobject><textdata
  						fileref="scheduler/job_descriptors/launcher_sh.txt"></textdata></textobject></programlisting>
			<para>
			Copy your compiled executable (task_with_output) and your launching shell script, and submit this job.
			You will see, after job's execution, 4 directories created in your <literal>[working_dir]</literal> named by the 4 tasks ID of youtr execution,
			and directories contains a file, output.txt, corresponding to outputs of the 4 execution instances launched by the job.
			</para>
	</sect3>	
</sect2>
</sect1>
</chapter>

{'fraction_non_alphanumeric': 0.09606680910699106, 'fraction_numerical': 0.003147471684241965, 'mean_word_length': 4.00517449548669, 'pattern_counts': {'":': 0, '<': 1765, '<?xml version=': 2, '>': 1767, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 80}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 2, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '99591', 'n_tokens_mistral': 28212, 'n_tokens_neox': 25120, 'n_words': 10409}