openpbs/doc/man1/qmove.1B

.\" Copyright (C) 1994-2018 Altair Engineering, Inc.
.\" For more information, contact Altair at www.altair.com.
.\"
.\" This file is part of the PBS Professional ("PBS Pro") software.
.\"
.\" Open Source License Information:
.\"
.\" PBS Pro is free software. You can redistribute it and/or modify it under the
.\" terms of the GNU Affero General Public License as published by the Free
.\" Software Foundation, either version 3 of the License, or (at your option) any
.\" later version.
.\"
.\" PBS Pro is distributed in the hope that it will be useful, but WITHOUT ANY
.\" WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
.\" FOR A PARTICULAR PURPOSE.
.\" See the GNU Affero General Public License for more details.
.\"
.\" You should have received a copy of the GNU Affero General Public License
.\" along with this program.  If not, see <http://www.gnu.org/licenses/>.
.\"
.\" Commercial License Information:
.\"
.\" For a copy of the commercial license terms and conditions,
.\" go to: (http://www.pbspro.com/UserArea/agreement.html)
.\" or contact the Altair Legal Department.
.\"
.\" Altair’s dual-license business model allows companies, individuals, and
.\" organizations to create proprietary derivative works of PBS Pro and
.\" distribute them - whether embedded or bundled with other software -
.\" under a commercial license agreement.
.\"
.\" Use of Altair’s trademarks, including but not limited to "PBS™",
.\" "PBS Professional®", and "PBS Pro™" and Altair’s logos is subject to Altair's
.\" trademark licensing policies.
.\"
.TH qmove 1B "15 December 2017" Local "PBS Professional"
.SH NAME
.B qmove 
- move PBS batch job

.SH SYNOPSIS
.B qmove 
<destination> <job ID> [<job ID> ...]
.br
.B qmove
--version

.SH DESCRIPTION
Moves a job from one queue to another.  

The behavior of the 
.B qmove 
command may be affected by 
any site hooks.  Site hooks can modify the job's attributes, 
change its routing, etc.

.B Restrictions
.br
The
.B qmove
command can be used on job arrays, but not on subjobs or ranges of
subjobs.  

Job arrays can only be moved from one server to another if
they are in the 'Q', 'H', or 'W' states, and only if there are no
running subjobs.  The state of the job array is preserved, and the job
array will run to completion on the new server.
.LP
A job in the
.B Running ,
.B Transiting ,
or
.B Exiting
state cannot be moved.  

A job in the process of provisioning cannot 
be moved.



.SH EFFECT OF PRIVILEGE ON BEHAVIOR

An unprivileged user can use the 
.B qmove 
command to move a job only when
the move would not violate queue restrictions.  A privileged user
(root, Manager, Operator) can use the 
.B qmove 
command to move a job
under some circumstances where an unprivileged user cannot.  The
following restrictions apply only to unprivileged users:

.RS 4
The queue must be enabled

.br
Moving the job into the queue must not exceed the queue limits for
jobs or resources

.br
If the job is an array job, the size of the job array must not exceed 
.I max_array_size 
for the queue

.br 
The queue cannot have its 
.I from_route_only
attribute set to 
.I True
(accepting jobs only from routing queues)
.RE

.SH OPTIONS
.IP "--version" 4
The 
.B qmove
command returns its PBS version information and exits.
This option can only be used alone.


.SH OPERANDS
.IP destination 4
Where job(s) are to end up.  First operand.  Syntax:
.RS 4
.I <queue name>
.RS 4
Moves the job(s) into the specified queue at the job's current server.
.RE
.br
.I @<server name>
.RS 4
Moves the job(s) into the default queue at the specified server.
.RE
.br
.I <queue name>@<server name>
.RS 4
Moves the job(s) into the specified queue at the specified server.
.RE
.RE

.LP
.IP "job ID" 4
Job(s) and/or job array(s) to be moved to the new destination.  The
.B qmove
command accepts one or more
.I job ID
operands of the form:
.RS 4
.I <sequence number>[.<server name>][@<server name>]
.br
.I <sequence number>[][.<server name>][@<server name>]
.RE

Note that some shells require that you enclose a job array identifier 
in double quotes.


.br
.SH STANDARD ERROR
The 
.B qmove 
command writes a diagnostic messages to standard error for each
error occurrence.

.SH EXIT STATUS
.IP Zero 4
Upon success

.IP "Greater than zero" 4
Upon failure


.SH SEE ALSO
The
.I PBS Professional User's Guide,
the
.I PBS Professional Administrator's Guide,
.br
qsub(1B), pbs_movejob(3B)