pbs_rsub(1B)

NAME
pbs_rsub - create a PBS advance or standing reservation

SYNOPSIS
pbs_rsub [-D <duration>] [-E <end time>] [-g <group list>]
    [-G <auth group list>] [-H <auth host list>] [-I <block time>] [-m <mail events>] [-M <mail list>] [-N <reservation name>] [-q <destination>] [-r <recurrence rule>] [-R <start time>] [-u <user list>] [-U <auth user list>] [-W <attribute value list>] -l <resource request> [-l <placement>]
pbs_rsub --version

DESCRIPTION
The pbs_rsub command is used to create an advance or standing reservation. An advance reservation reserves specific resources for the requested time period, and a standing reservation reserves specific resources for recurring time periods. When a reservation is created, it has an associated queue. After the reservation is requested, it is either confirmed or denied. Once the reservation has been confirmed, authorized users submit jobs to the reservation's queue via qsub and qmove. A confirmed reservation will accept jobs at any time. The jobs in its queue can run only during the reservation period, whether during a single advance reservation or during the occurrences of a standing reservation. When an advance reservation ends, all of its jobs are deleted, whether running or queued. When an occurrence of a standing reservation ends, only its running jobs are deleted; those jobs still in the queue are not deleted. To get information about a reservation, use the pbs_rstat command. To delete a reservation, use the pbs_rdel command. Do not use the qdel command. The behavior of the pbs_rsub command may be affected by any site hooks. Site hooks can modify the reservation's attributes.

REQUIREMENTS
When using pbs_rsub to request a reservation, you must specify two of the following options: -R, -E, and -D. The resource request -l walltime can be used instead of the -D option. If you want to run jobs in a reservation that will request exclusive placement, you must create the reservation with exclusive placement via -l place=excl.

OPTIONS

-D <duration>
    Specifies reservation duration. If the start time and end time are the only times specified, this duration time is calculated.
    Format: Duration. See FORMATS.
    Default: none

-E <end time>
    Specifies the reservation end time. If start time and duration are the only times specified, the end time value is calculated.
    Format: Datetime. See FORMATS.
    Default: none.

-g <group list>
    The group list is a comma-separated list of group names. The server uses entries in this list, along with an ordered set of rules, to associate a group name with the reservation. The reservation creator's primary group is automatically added to this list.
    Format: <group>@<hostname>[,<group>@<hostname> ...]

-G <auth group list>
    Comma-separated list of names of groups who can or cannot submit jobs to this reservation. Group names are interpreted in the context of the server's host, not the context of the host from which the job is submitted.
    This list becomes the acl_groups list for the reservation's queue. More specific entries should be listed before more general, because the list is read left-to-right, and the first match determines access.
    If both the Authorized_Users and Authorized_Groups reservation attributes are set, a user must belong to both in order to be able to submit jobs to this reservation. If the reservation creator specifies this list, the creator's group is not automatically added to the list.
    Refer to the Authorized_Groups reservation attribute in the pbs_resv_attributes(7B) man page.
    Format: [+|-]<group name>[,[+|-]<group name> ...]
    Default: All groups are authorized to submit jobs.

-H <auth host list>
    Comma-separated list of hosts from which jobs can and cannot be submitted to this reservation. This list becomes the acl_hosts list for the reservation's queue.
    More specific entries should be listed before more general, because the list is read left-to-right, and the first match determines access. If the reservation creator specifies this list, the creator's host is not automatically added to the list.
    See the Authorized_Hosts reservation attribute in the pbs_resv_attributes(7B) man page.
    Format: [+|-]<hostname>[,[+|-]<hostname> ...]
    Default: All hosts are authorized to submit jobs

-I <block time>
    Specifies interactive mode. The pbs_rsub command will block, up to block time seconds, while waiting for the reservation request to be confirmed or denied.
    If block time is positive, and the reservation isn't confirmed or denied in the specified time, the ID string for the reservation is returned with the status "UNCONFIRMED".
    If block time is negative, and a scheduler doesn't confirm or deny the reservation in the specified time, the reservation is deleted.
    Format: Integer.
    Default: Not interactive

-l <placement>
    The placement specifies how vnodes are reserved. The place statement can contain the following elements, in any order:

    -l place=[ <arrangement> ][: <sharing> ][: <grouping> ]

    where

    arrangement
        Whether this reservation chunk is willing to share this vnode or host with other chunks from this reservation. One of free | pack | scatter | vscatter

    sharing
        Whether this reservation chunk is willing to share this vnode or host with other reservations or jobs. One of excl | share | exclhost

    grouping
        Whether the chunks from this reservation should be placed on vnodes that all have the smae value for a resource. Can have only one instance of group=resource

    and where

    free
        Place reservation on any vnode(s).

    pack
        All chunks are taken from one host.

    scatter
        Only one chunk with any MPI processes is taken from a host. A chunk with no MPI processes may be taken from the same vnode as another chunk.

    vscatter
        Only one chunk is taken from any vnode. Each chunk must fit on a vnode.

    excl
        Only this reservation uses the vnodes chosen.

    exclhost
        The entire host is allocated to the reservation.

    shared
        This reservation can share the vnodes chosen.

    group=<resource>
        Chunks are grouped according to a resource. All vnodes in the group must have a common value for resource, which can be either the built-in resource host or a custom vnode-level resource.
        resource must be a string or a string array.

    If you want to run jobs in the reservation that will request exclusive placement, you must create the reservation with exclusive placement via -l place=excl. The place statement cannot begin with a colon. Colons are delimiters; use them only to separate parts of a place statement, unless they are quoted inside resource values. Note that nodes can have sharing attributes that override job placement requests. See the pbs_node_attributes(7B) man page.

    For more on reservations, see The PBS Professional User's Guide.

-l resource request
    The resource request specifies the resources required for the reservation. These resources are used for the limits on the queue that is dynamically created for the reservation. The aggregate amount of resources for currently running jobs from this queue will not exceed these resource limits. Jobs in the queue that request more of a resource than the queue limit for that resource are not allowed to run. Also, the queue inherits the value of any resource limit set on the server, and these are used for the job if the reservation request itself is silent about that resource. A non-privileged user cannot submit a reservation requesting a custom resource which has been created to be invisible or read-only for users. Resources are requested by using the -l option, either in chunks inside of selection statements, or in job-wide requests using <resource name>=<value> pairs. Requesting resources in chunks:

        -l select=[N:]<chunk>[+[N:]<chunk> ...]

    where N specifies how many of that chunk, and a chunk is of the form:

        <resource name>=<value>[:<resource name>=<value> ...]

    Requesting job-wide resources:

        -l <resource name>=<value>[,<resource name>=<value> ...]

-m <mail events>
    Specifies the set of events that cause mail to be sent to the list of users specified in the -M mail list option.
    Format: string consisting of one of the following:
    1) any combination of "a", "b", "c" or "e"
    2) the single character "n"

    a   Notify if the reservation is terminated for whatever 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.

    Default: ac

-M <mail list>
    The list of users to whom mail is sent whenever the reservation transitions to one of the states specified in the -m mail events option.
    Format: <username>[@<hostname>][,<username>[@<hostname>]...]
    Default: reservation owner.

-N <reservation name>
    Specifies a name for the reservation.
    Format: Reservation name. See FORMATS.
    Default: None.

-q <destination>
    Specifies the destination server at which to create the reservation.
    Default: The default server is used if this option is not selected.

-r <recurrence rule>
    Specifies rule for recurrence of standing reservations. Rule must conform to iCalendar syntax, and is specified using a subset of parameters from RFC 2445.
    Valid syntax for recurrence rule takes one of two forms:
    FREQ=<freq spec>;COUNT=<count spec>;<interval spec>

    or
    FREQ=<freq spec>;UNTIL=<until spec>; <interval spec>

    where

    freq spec
        Frequency with which the standing reservation repeats. Valid values are:
        WEEKLY|DAILY|HOURLY

    count spec
        The exact number of occurrences. Number up to 4 digits in length. Format: integer.

    interval spec
        Specifies interval. Format is one or both of:
        BYDAY = MO|TU|WE|TH|FR|SA|SU
        or
        BYHOUR = 0|1|2|...|23
        When using both, separate them with a semicolon.
        Elements specified in the recurrence rule override those specified in the arguments to the -R and -E options. For example, the BYHOUR specification overrides the hourly part of the -R option. For example,
        -R 0730 -E 0830 ... BYHOUR=9
        results in a reservation that starts at 9:30 and runs for 1 hour. See the PBS Professional User's Guide.

    until spec
        Occurrences will start up to but not after date and time specified.
        Format: YYYYMMDD[THHMMSS]
        Note that the year-month-day section is separated from the hour-minute-second section by a capital T.

    Requirements:
    The recurrence rule must be on one unbroken line and must be enclosed in double quotes. A start and end date must be used when specifying a recurrence rule. See the R and E options. The PBS_TZID environment variable must be set at the submission host. The format for PBS_TZID is a timezone location. Examples: America/Los_Angeles, America/Detroit, Europe/Berlin, Asia/Calcutta. See the PBS Professional User's Guide. Examples of Standing Reservations
    For a reservation that runs every day from 8am to 10am, for a total of 10 occurrences:

        pbs_rsub -R 0800 -E 1000 -r "FREQ=DAILY;COUNT=10"

    Every weekday from 6am to 6pm until December 10 2008

        pbs_rsub -R 0600 -E 1800
        -r "FREQ=WEEKLY; BYDAY=MO,TU,WE,TH,FR; UNTIL=20081210"

    Every week from 3pm to 5pm on Monday, Wednesday, and Friday, for 9 occurrences, i.e., for three weeks:
        pbs_rsub -R 1500 -E 1700
        -r "FREQ=WEEKLY;BYDAY=MO,WE,FR; COUNT=3"

-R <start time>

    Specifies reservation starting time. If the reservation's end time and duration are the only times specified, this start time is calculated. If the day, DD , is not specified, it defaults to today if the time hhmm is in the future. Otherwise, the day is set to tomorrow. For example, if you submit a reservation with the specification -R 1110 at 11:15 a.m., it is interpreted as being for 11:10am tomorrow. If the month portion, MM , is not specified, it defaults to the current month, provided that the specified day 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: Datetime

-u <user list>
    Not used. Comma-separated list of user names.
    Format: <username>[@<hostname>][,<username>[@<hostname>] ...]
    Default: None

-U <auth user list>
    Comma-separated list of users who are and are not allowed to submit jobs to this reservation. This list becomes the acl_users attribute for the reservation's queue. More specific entries should be listed before more general, because the list is read left-to-right, and the first match determines access. If both the Authorized_Users and Authorized_Groups reservation attributes are set, a user must belong to both in order to be able to submit jobs to this reservation. The reservation creator's username is automatically added to this list, whether or not the reservation creator specifies this list. Refer to the Authorized_Users reservation attribute on the pbs_resv_attributes man page.
    Format: [+|-]<username>@<hostname>[,[+|-]<username>@<hostname>...]
    Default: Job owner only

-W attribute value list
    This allows you to define other attributes for the reservation. Supported attributes:

    qmove=<job ID>
        Converts a normal job designated by job ID into a reservation job that will run as soon as possible. Creates the reservation with its queue and moves the job into the reservation's queue. Uses the resources requested by the job to create the reservation. When the reservation is created, it inherits its resources from the job, not from the resources requested through the pbs_rsub command. You can use the -I option to specify a timeout for the conversion. If you use the qmove option to convert a job to a reservation, and the reservation is not confirmed within the timeout period, the reservation is deleted. The default timeout period is 10 seconds. There is no option for this kind of reservation to be unconfirmed. To specify the timeout, you must give a negative value for the -I option. For example, to specify a timeout of 300 seconds:
           pbs_rsub -Wqmove=<job ID> -I -300 The -R and -E options to pbs_rsub are disabled when using the qmove=<job ID> attribute. Some shells require that you enclose a job array ID in double quotes.

--version
    The pbs_rsub command returns its PBS version information and exits. This option can only be used alone.

OUTPUT
The pbs_rsub command returns the reservation identifier.
For an advance reservation, this has the form

    R<NNNN>.<server name>

where NNNN is a unique integer. The associated queue's name is the prefix, R<NNNN>. For a standing reservation, this has the form

    S<NNNN>.<server name>

where NNNN is a unique integer. The associated queue's name is the prefix, S<NNNN>.

FORMATS

Datetime format
    [[[[CC]YY]MM]DD]hhmm[.SS]

Reservation name
    String up to 236 characters in length. It must consist of printable, non-white space characters with the first character alphabetic. The first character must be alphabetic, numeric, plus sign, dash or minus, or underscor. The name must not contain special characters.

SEE ALSO
The PBS Professional User's Guide, the PBS Professional Administrator's Guide,
pbs_resv_attributes(7B), pbs_rdel(1B), pbs_rstat(1B), qmove(1B), qsub(1B)