[[PageOutline]]
= Remote job submission =

This document describes interfaces for remotely submitting batches of jobs
to a BOINC server.

Users can submit jobs only if they have been given access
(via a web interface) by project administrators.

In addition, project admins can restrict the apps for which
each user is allowed to submit jobs.

== PHP interface ==

=== boinc_estimate_batch() ===

This function returns an estimate of the elapsed time
required to complete a given batch.

Arguments: a "request object" whose fields include
 * '''project''': the project URL
 * '''authenticator''': the user's authenticator
 * '''app_name''': the name of the application for which jobs are being submitted
 * '''jobs''': an array of job descriptors (see example)

Return value: a 2-element array containing
 * The estimate (in seconds)
 * An error message (null if success)

Example:
{{{
$req->project = "http://foo.bar.edu/test/";
$req->authenticator = "xxx";
$req->app_name = "uppercase";
$req->jobs = array();

$f->source = "http://foo.bar.edu/index.php";
$f->name = "in";
$job->input_files = array($f);

for ($i=10; $i<20; $i++) {
	$job->rsc_fpops_est = $i*1e9;
	$job->command_line = "--t $i";
	$req->jobs[] = $job;
}

list($e, $errmsg) = boinc_estimate_batch($req);
}}}

=== boinc_submit_batch() ===

Similar to '''boinc_estimate_batch()''', but submits the batch.
The return value is a 2-element array containing
 * The batch ID
 * An error message (null if success)

=== boinc_query_batches() ===
=== boinc_query_batch() ===
=== boinc_abort_batch() ===

== HTTPS/XML interface ==

The APIs are accessed by sending a POST request,
using HTTPS, to PROJECT_URL/submit.php

The inputs and outputs of each function are XML documents.
If an operation fails, the output is of the form
{{{
<error>
   <message>X</message>
</error>
}}}
where X is an error message.

All operations include the authenticator of the user making the request.
This user must be marked as a "job submitter" in the BOINC database.

=== Describing a batch ===

A job is described by
{{{
<job>
   [<command_line>C</command_line>]
   [<input_file>URL or path</input_file>]
   ... other input files
</job>
}}}

Each input file is specified either by a URL accessible to the server,
or by a path on the server.

A batch of jobs is described by:
{{{
<batch>
   <app>appname</app>
   [<input_template>x</input_template>]
   [<output_template>x</output_template>]
   <job>...</job>
   ... more jobs
</batch>
}}}

The names of the input and output template files may be specified;
otherwise the defaults '''appname_in''' and '''appname_out''' are used.

=== Batch runtime estimation ===

This function estimates the completion time of a batch.
Input:
{{{
<batch_estimate>
   <authenticator>X</authenticator>
   <batch> ... </batch>
   [<priority>N</priority>]
</batch_estimate>
}}}

'''Priority''', if specified, is relative to other batches submitted by this user.

Output:
{{{
<estimate>
   <seconds>X</seconds>
</estimate>
}}}

=== Submitting a batch ===

Input:
{{{
<batch_submit>
   <authenticator>X</authenticator>
   <batch> ... </batch>
   [<priority>N</priority>]
</batch_submit>
}}}

Output:
{{{
<batch_id>N</batch_id>
}}}

=== Querying batches ===
=== Querying a batch ===

Input:
{{{
<query_batch>
   <authenticator>X</authenticator>
   <batch_id>N</batch_id>
</query_batch>
}}}

Output:
{{{
<batch_status>
   <fraction_done>X</fraction_done>
   <jobs_completed>N</jobs_completed>
   <remaining_time>X</remaining_time>
</batch_status>
}}}

=== Aborting a batch ===

== Implementation notes ==

New tables

{{{
batch
  id
  create_time
  logical_start_time
  logical_end_time
  estimated_completion_time
  njobs

user_submit
  user_id
  quota
  logical_start_time
  bool all_apps

user_app
  user_id
  app_id
}}}