=head1 NAME

oarwalltime - query or request a change of the walltime of a job handled by the OAR batch scheduler.

=head1 SYNOPSIS

B<oarwalltime> [options] <job_id> [<[+/-]new walltime>]

=head1 DESCRIPTION

This command manages requests to change the walltime of a job.

If no I<new walltime> is given, the command shows the current walltime change status for the job.

If a I<new walltime> is given, the command requests a change of the walltime of the job, or update a previous request.

The I<new walltime> is to be passed in the format [+-]h:m:s. If no sign is used,
The value is a new walltime absolute value (like passed to oarsub). If prefixed
by +, the request is an increase of the walltime by the passed value. If
prefixed by -, it is a decrease request.
A walltime change request that has not been yet accepted by the scheduler can be
cancelled by passing the '+0' value.

Walltime changes can only be requested for a running job.

There is no warranty that walltime can be increased, since it depends on the resources availability (next jobs).

Once a request is registered, it will by handled during the next pass of scheduling and granted if it fits with other jobs.

As per configuration:

=over

=item * the walltime change functionality may be disabled in your installation, and if not there is a maximum to the possible walltime increase

=item * a walltime increase request may only be applied some time before the predicted end of the job. That apply time may be computed as a percentage of the walltime of the job

=item * a walltime increase may happen incrementally, so that other scheduled jobs get more priority. That increment may be computed as a percentage of the walltime of the job

=item * the functionality may be configured differently from one queue to another.

=back

I<Read your site's documentation or ask your administrator to know the configured settings.>

=head1 OPTIONS

=over

=item B<--force>

Request walltime increase to be trialed or applied immediately regardless of any otherwise configured delay.

=item B<--whole>

Request walltime increase to be trialed or applied wholly at once, or not applied otherwise.

=item B<--delay-next-jobs>

Request walltime increase to possibly delay next batch jobs (but not advance reservations), if required to fit in the resources allocation. Warning: this implies delaying any other batch jobs, including the ones from other users. Using this option may be prohibited.

=item B<--timeout>

Specify a timeout (in seconds) after which the walltime change request will be aborted if not already accepted by the scheduler. By default, there is no timeout unless a default timeout is set by the administrator.

=item B<-h, --help>

Print help command message.

=item B<-V, --version>

Print OAR version.

=back

=head1 NOTES


All changes are logged. Changes using the force or delay-next-jobs options are accounted.

I<Please mind the walltime of the job and do not rely too much on that functionality.>

The shell environment variables of the job are not updated (OAR_JOB_WALLTIME, OAR_JOB_WALLTIME_SECONDS).

Walltime change events for a job are listed in the I<oarstat> output.

=head1 SEE ALSO

oarstat(1), oarsub(1), oardel(1)

=head1 COPYRIGHTS

 Copyright 2003-2017 Laboratoire d'Informatique de Grenoble (http://www.liglab.fr). This software is licensed under the GNU General Public License Version 2 or above. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
