.\" 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_resv_attributes 7B "20 April 2018" Local "PBS Professional"
.SH NAME
.B pbs_resv_attributes 
\- attributes of PBS advance and standing reservations

.SH DESCRIPTION
PBS advance and standing reservations have the following attributes:

.IP Account_Name 8
No longer used.

.IP Authorized_Groups 8
List of groups who can or cannot submit jobs to this reservation.
Group names are interpreted relative to the server, not the 
submission host.  List is evaluated left-to-right; first match in 
list is used.  This list is used to set the reservation queue's 
.I acl_groups 
attribute.  See the 
.I G 
option to the 
.I pbs_rsub 
command.
.br
Readable by all; settable by all.
.br
Format: 
.I String
.br
Syntax:
.RS 11
.I [+|-]<group name> [,[+|-]<group name> ...] 
.RE
.IP
Python type:
.I pbs.acl
.br
Default: Reservation owner's login group

.IP Authorized_Hosts 8
The list of hosts from which jobs can and cannot be submitted to this reservation. 
List is evaluated left-to-right; first match in list is used.  
This list is used to set the reservation queue's 
.I acl_hosts
attribute.  See the 
.I H
option to the 
.I pbs_rsub 
command.  
.br
Readable by all; settable by all.
.br
Format: 
.I String
.br
Syntax:
.RS 11
.I [+|-]<hostname> [,[+|-]<hostname> ...]
.br
Hostnames may be wildcarded using an asterisk, according to the following rules:
.RS 3
- A hostname can contain at most one asterisk
.br
- The asterisk must be the leftmost label
.RE
Examples:
.RS 3
*.test.example.com
.br
*.example.com
.br
*.com
.RE
.RE
.RE
.IP
Python type:
.I pbs.acl
.br
Default: No default (Jobs can be submitted from all hosts)

.IP Authorized_Users 8
The list of users who can or cannot submit jobs to this reservation.
List is evaluated left-to-right; first match in list is used.  
This list is used to set the reservation queue's 
.I acl_users
attribute.  See the 
.I U 
option to the 
.I pbs_rsub 
command.
.br
Readable by all; settable by all.
.br
Format: 
.I String
.br
Syntax:
.RS 11
.I [+|-]<username>[<hostname>.<domain>] [, [+|-]<username>[<hostname>.<domain>] ...]
.br
where '-' means "deny" and '+' means "allow". 
.br
The hostname portion of a username may be wildcarded using an asterisk, 
according to the following rules:
.RS 3
- A hostname can contain at most one asterisk
.br
- The asterisk must be the leftmost label in the hostname
.RE
Examples:
.RS 3
*.test.example.com
.br
*.example.com
.br
*.com
.RE
.RE
.RE
.IP
Python type:
.I pbs.acl
.br
Default: Reservation owner only

.IP ctime 8
The time that the reservation was created.
.br
Readable by all; set by PBS.
.br
Format: 
.I Timestamp
.RS 11
Printed by qstat in human-readable
.I Date
format.  
.br
Output in hooks as seconds since epoch.
.RE
.IP 
Python type:
.I int
.br
Default: No default

.IP group_list 8
No longer used.

.IP hashname 8
No longer used.

.IP "interactive" 8
Number of seconds that the 
.I pbs_rsub 
command will block while waiting for confirmation or denial of the 
reservation.  
See the 
.I -I block_time
option to the 
.I pbs_rsub 
command.
.br
Readable by all; settable by all.
.br
Format:
.I Integer
.br
Behavior:
.RS 11
.IP "Less than zero" 3
The reservation is automatically deleted if it cannot be confirmed in the time specified.
.IP "Zero or greater than zero" 3
The reservation is not automatically deleted after this time.  
.RE
.IP
Python type:
.I int
.br
Default: 
.I Zero

.IP "Mail_Points" 8
Sets the list of events for which mail is sent by the server.  Mail 
is sent to the list of users specified in the 
.I Mail_Users
attribute.  See the 
.I m mail_points 
option to the 
.I pbs_rsub 
command.
.br
Readable by all; settable by all.
.br
Format:
.I String 
.br
Syntax:
.RS 11
One or more letters "a", "b", "c", "e", or the string "n".  
.br
Cannot use "n" with any other letter.
.RE
.IP
Behavior:
.RS 11
.IP a 3
Notify when reservation is terminated
.IP b 3
Notify when reservation period begins
.IP c 3
Notify when reservation is confirmed
.IP e 3
Notify when reservation period ends
.IP n 3
Do not send mail.  Cannot be used with other letters.
.RE
.IP
Python type:
.I pbs.group_list
.br
Default: "ac"

.IP "Mail_Users" 8
The set of users to whom mail is sent for the reservation events
specified in the 
.I Mail_Points
attribute.  See the 
.I M mail_list 
option to the 
.I pbs_rsub 
command.
.br
Readable by all; settable by all.
.br
Format:
.I String 
.br
Syntax:
.RS 11
.I <username>@<hostname>[,<username>@<hostname> ...]
.RE
.IP
Python type:
.I pbs.user_list
.br
Default: Reservation owner only

.IP mtime 8
The time that the reservation was last modified.
.br
Readable by all; set by PBS.
.br
Format: 
.I Timestamp
.RS 11
Printed by qstat in human-readable
.I Date
format.  
.br
Output in hooks as seconds since epoch.
.RE
.IP
Python type:
.I int
.br
Default: No default

.IP Priority 8
No longer used.

.IP queue 8
Name of the reservation queue.  Jobs that 
are to use resources belonging to this reservation are submitted to this queue. 
.br
Readable by all; set by PBS.
.br
Format:
.I String
.RS 11
Format for an advance reservation:
.I R<unique integer>
.br
Format for a standing reservation:
.I S<unique integer>
.RE
.IP
Python type:
.I pbs.queue
.br
Default: No default

.IP reserve_count 8
The total number of occurrences in a standing reservation.
.br 
Readable by all; settable by all.
.br
Format:
.I Integer
.br
Python type:
.I int
.br
Default: No default

.IP reserve_duration 8
Reservation duration in seconds.  For a standing reservation, this is the
duration for one occurrence.
.br
Readable by all; settable by all.
.br
Format:
.I Integer
.br
Python type:
.I pbs.duration
.br
Default: No default

.IP reserve_end 8
The date and time when an advance reservation or soonest occurrence of a
standing reservation ends.  
.br
Readable by all; settable by all.
.br
Format: 
.I Timestamp
.RS 11
Printed by qstat in human-readable
.I Date
format.  
.br
Output in hooks as seconds since epoch.
.RE
.IP
Python type:
.I int
.br
Default: No default

.IP reserve_ID 8
The reservation identifier. 
.br
Format:
.I String 
.RS 11
Format for an advance reservation: 
.I R<unique integer>.<server name>
.br
Format for a standing reservation: 
.I S<unique integer>.<server name>
.RE
.IP
Python type:
.I str
.br
Default: No default

.IP reserve_index 8
The index of the soonest occurrence of a standing reservation.
.br
Readable by all; set by PBS.
.br
Format:
.I Integer
.br
Python type:
.I int
.br
Default: No default

.IP "Reserve_Name" 8
The name assigned to the reservation during creation, if specified.  See the 
.I N 
option to the 
.I pbs_rsub 
command.
.br
Readable by all; settable by all.
.br
Format:
.I String 
.br
Syntax:
Up to 15 characters.  First character is alphabetic.
.br
Python type:
.I str
.br
Default: No default

.IP "Reserve_Owner" 8
The login name on the submitting host of the user who created the
reservation.
.br
Readable by all; set by PBS.
.br
Format:
.I String
.br
Syntax:
.I <username>@<hostname>
.br
Python type:
.I str
.br
Default: Login name of creator

.IP reserve_retry 8
If this reservation becomes degraded, this is set to the 
next time that PBS will attempt to reconfirm this reservation.
.br
Readable by all; set by PBS.
.br
Format: 
.I Timestamp
.RS 11
Printed by qstat in human-readable
.I Date
format.  
.br
Output in hooks as seconds since epoch.
.RE
.IP
Python type:
.I int
.br
Default: No default

.IP reserve_rrule 8
The rule that describes the recurrence pattern of a standing reservation.
See the 
.I r
option to the 
.I pbs_rsub
command.
.br
Readable by all; settable by all.
.br
Format: 
.I String
.br
Syntax: either of two forms:
.RS 11
"FREQ=
.I <freq_spec>;
COUNT=
.I <count_spec>;
.I <interval_spec>"
.br
or
.br
"FREQ=
.I <freq_spec>;
UNTIL=
.I <until_spec>; <interval_spec>"
.br
where
.IP freq_spec 15
Frequency with which the standing reservation repeats.  Valid values are:
.br
WEEKLY|DAILY|HOURLY

.IP count_spec 15
The exact number of occurrences.  Number up to 4 digits in length.  
.br
Format:
.I Integer

.IP interval_spec 15
Specifies interval.  
.br
Format is one or both of:
.br
.I BYDAY = MO|TU|WE|TH|FR|SA|SU 
.br
or
.br
.I BYHOUR = 0|1|2|...|23
.br

.IP until_spec 15
Occurrences will start up to but not after date and time 
specified.
.br
.br
Format:
.I YYYYMMDD[THHMMSS] 
.br
Note that the year-month-day section is separated from 
the hour-minute-second section by a capital T.
.RE
.IP
Python type:
.I str
.br
Default: No default

.IP reserve_start 8
The date and time when the reservation period for the reservation 
or soonest occurrence begins.  
.br
Readable by all; settable by all.
.br
Format: 
.I Timestamp
.RS 11
Printed by qstat in human-readable
.I Date
format.  
.br
Output in hooks as seconds since epoch.
.RE
.IP
Python type:
.I int

.IP reserve_state 8
The state of the reservation.  
.br
Readable by all; set by PBS.
.br
Format: 
.I String
.br
Python type:
Each value has its own reservation state constant.

The following table shows each abbreviation, state, and Python constant:
.RS

.IP "NO   RESV_NONE            pbs.RESV_STATE_NONE"
No reservation yet.

.IP "UN   RESV_UNCONFIRMED     pbs.RESV_STATE_UNCONFIRMED "
Reservation request is awaiting confirmation.

.IP "CO   RESV_CONFIRMED       pbs.RESV_STATE_CONFIRMED "
Reservation has been confirmed.  For a standing reservation, this means
that all occurrences of the reservation have been confirmed.

.IP "WT   RESV_WAIT            pbs.RESV_STATE_WAIT "
Unused.  

.IP "TR   RESV_TIME_TO_RUN     pbs.RESV_STATE_TIME_TO_RUN "
Start of the reservation period.

.IP "RN   RESV_RUNNING         pbs.RESV_STATE_RUNNING "
Reservation period has started and reservation is running.

.IP "FN   RESV_FINISHED        pbs.RESV_STATE_FINISHED "
End of the reservation period.

.IP "BD   RESV_BEING_DELETED   pbs.RESV_STATE_BEING_DELETED "
Reservation is being deleted.

.IP "DE   RESV_DELETED         pbs.RESV_STATE_DELETED "
Reservation has been deleted.

.IP "DJ   RESV_DELETING_JOBS   pbs.RESV_STATE_DELETING_JOBS "
Jobs belonging to the reservation are being deleted.
.RE
.IP
Default: No default

.IP reserve_substate 8
The substate of the reservation or occurrence.  The 
substate is used internally by PBS.
.br
Readable by all; set by PBS.
.br
Format:
.I Integer
.br
Python type:
.I int
.br
Default: No default

.IP reserve_type 8
No longer used.

.IP "Resource_List" 8
The list of resources allocated to the reservation.  Jobs running in
the reservation cannot use in aggregate more than the specified amount
of a resource.
.br
Readable by all; settable by all.
.br
Format:
.I String
.br
Syntax:
.RS 11
.I Resource_List.<resource name>=<value>[,Resource_List.<resource name>=<value> ...]
.RE
.IP
Python type: 
.I pbs.pbs_resource
.br
Syntax:
.RS 11
.I Resource_List["<resource name>"]=<resource value>
.br
where 
.I resource name 
is any built-in or custom resource
.RE
.IP
Default: No default

.IP resv_nodes 8
The list of vnodes and resources allocated from them to satisfy 
the chunks requested for this reservation or occurrence.
.br
Readable by all; set by PBS.
.br
Format:
.I String
.br
Syntax:  
.RS 11
.I (<vnode name>:<resource name>=<value>[:<resource name>=<value>]...) 
.I [+(<vnode name>:<resource name>=<value>[:<resource name>=<value>])+...]
.RE
.IP
Python type:
.I pbs.exec_vnode
.br
Default: No default

.IP server 8
Name of server.
.br
Readable by all; set by PBS.
.br
Format:
.I String
.br
Python type:
.I pbs.server
.br
Default: No default

.IP User_List 8
No longer used.

.IP Variable_List 8
Not used.


.SH SEE ALSO
The
.I PBS Professional User's Guide,
the
.I PBS Professional Administrator's Guide,
.br
pbs_rstat(1B), 
pbs_rsub(1B), 
pbs_resources(7B)