openpbs/doc/man1/pbs_ralter.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 pbs_ralter 1B "18 May 2018" Local "PBS Professional"
.SH NAME
.B pbs_ralter 
\- modify an existing advance or standing reservation
.SH SYNOPSIS
.B pbs_ralter
[-E <end time>] [-I <block time>] [-m <mail points>] 
           [-M <mail list>] [-N <reservation name>] [-R <start time>] 
           <reservation ID>
.br
.B pbs_ralter
--version
.SH DESCRIPTION
You can use the 
.B pbs_ralter 
command to alter an existing advance or standing reservation.  You can
change the start time, end time, events that generate mail, mail
recipient list, and reservation name.  You can change the end time for
a running reservation with running jobs.  

You can use this command to change an advance reservation or the next
or current instance of a standing reservation.  

After the change is requested, the change is either confirmed or
denied. On denial of the change, the reservation is not deleted and is
left as is, and the following message appears in the server's log:
.nf
   Unable to alter reservation <reservation ID> 
.fi

When a reservation is
confirmed, the following message appears in the server's log:
.nf
   Reservation alter successful for <reservation ID> 
.fi

To find out whether or not the change was allowed: 
.RS 3
Use the pbs_rstat command: see whether you altered reservation attribute(s) 

Use the interactive option: check for confirmation after the blocking time has run out 

Check the server log for confirmation or denial messages
.RE

Before the change is confirmed or denied, the change is unconfirmed,
and the reservation state is 
.I AL.  

Once a reservation change is confirmed, the reservation state is 
.I CO 
or 
.I RN.  

If the reservation has not started and it cannot be confirmed on the same vnodes, PBS
searches for another set of vnodes.

.B Required Privilege
.br
You must be the reservation owner or the PBS Administrator to run this command.

.SH Options to pbs_ralter

.IP "-R <start time>" 10
Specifies reservation's new start time. This option can be used either
when the reservation is not running or there are no jobs are submitted
to the reservation.  You cannot use this option when a reservation is
not empty and has started running.

The specifications for providing the time are the same as for pbs_rsub:
.br
If the day, 
.I DD, 
is not specified, it defaults to today if the time
.I hhmm 
is in the future.  Otherwise, the day is set to tomorrow.  For
example, if you alter a reservation with the specification -R 1110 at
11:15 a.m., it is interpreted as being for 11:10 a.m. tomorrow.  If
the month portion,
.I MM, 
is not specified, it defaults to the current month, provided that the specified day 
.I DD, 
is in the future.  Otherwise, the month is set to next month.  Similar
rules apply to the two other optional, left-side components.

Format: 
.I Datetime

.IP "-E <end time>" 10
Specifies reservation's new end time. This option can be used even
when the reservation is running and has jobs that are submitted to
and/or are running in the reservation.

Format: 
.I Datetime

.IP "-I <block time>" 10
Specifies interactive mode. The pbs_ralter command will block, up to
.I block time 
seconds, while waiting for the reservation's change request
to be confirmed or denied.

The value for 
.I block time 
must be positive. The pbs_ralter command
returns either the status 
.I "CONFIRMED" 
or the status 
.I "DENIED".

Format: 
.I Integer

Default: Not interactive

.IP "-m <mail points>" 10
Specifies the set of events that cause mail to be sent to the list of
users specified in the 
.I -M <mail list> 
option.

Format: 
.I String
.br
Syntax: Either of
.RS 13
1) any combination of "a", "b", "c" or "e", or
.br
2) the single character "n"
.RE
.IP
.nf
Suboptions to -m Option:

Character   Meaning
--------------------------------------------------------------
a           Notify if reservation is terminated for any reason
b           Notify when the reservation period begins
c           Notify when the reservation is confirmed
e           Notify when the reservation period ends
n           Send no mail.  Cannot be used with any of a, b, c or e.
.fi

Default: No default; if not specified, mail events are unchanged

.IP "-M <mail list>" 10
The list of users to whom mail is sent whenever the reservation
transitions to one of the states specified in the
.I -m <mail points> 
option.  

Format: 
.I <username>[@<hostname>][,<username>[@<hostname>]...]

Default: No default; if not specified, user list is unchanged

.IP "-N <reservation name>" 10
Specifies a name for the reservation.  

Format: 
.RS 13
String up to 15 characters in length.  It must consist of printable,
non-white space characters with the first character alphabetic.
.RE
.IP
Default: No default; if not specified, reservation name is unchanged

.IP "--version" 10
The 
.B pbs_ralter
command returns its PBS version information and exits.
This option can only be used alone.

.SH OPERANDS
The pbs_ralter command takes a reservation ID.
.br
For an advance reservation this has the form:
.RS 4
.I "R<sequence number>[.<server name>][@<remote server>]"
.RE
For a standing reservation this has the form:
.RS 4
.I "S<sequence number>[.<server name>][@<remote server>]"
.RE

.I @<remote server> 
specifies a reservation at a server other than the default server.