QRSUB(1)                    General Commands Manual                   QRSUB(1)



NAME
       qrsub   - Submit an Advance Reservation (AR) to Univa Grid Engine.

SYNTAX
       qrsub  [-a  date_time]  [-A account_string] [-ckpt ckpt_name] [-d time]
       [-e date_time] [-fr yes|no] [-he  yes|no]  [-help]  [-l  resource_list]
       [-now]  [-M  user[@host],...]   [-N ar_name] [-P project_name] [-w e|v]
       [-pe pe_name slot_range] [-q wc_queue_list]  [-rao  yes|no]  [-si  ses-
       sion_id] [-u wc_user_list] [-cal_week weekly_calendar] [-cal_depth num-
       ber] [-cal_jmp number]

DESCRIPTION
       Qrsub provides a means for operators, managers or users  referenced  in
       the  ACL (see access_list(5)) "arusers" to create a Advance Reservation
       (AR) or a Standing Reservation (SR) in the Univa  Grid  Engine  queuing
       system. ARs allow to reserve particular consumable resources for future
       use. These reserved resources are only available  for  jobs  requesting
       the AR and the scheduler ensures the availability of the resources when
       the start time is reached. Job requesting  the  AR  can  only  use  the
       reserved  consumable  resources.  SRs  are recurring ARs which follow a
       given calendar. All ARs within one SR has the same ID.

       During AR submit time the Univa Grid Engine queuing system selects  the
       best  suited  queues  for  the AR request and then reserves the desired
       amount of resources.  For a reservation, all queues  that  are  not  in
       orphaned  state are considered as suited. Only if the AR request can be
       fulfilled, the AR will be granted.

       ARs will be deleted either automatically when the end time is  reached,
       or manually using qrdel .  In both cases, first all jobs requesting the
       AR will be removed and then AR itself. Already granted ARs can be shown
       with qrstat(.)

       Note: To make AR behavior predictable, it is necessary to have reserved
       resources available at the time of AR start. This is  done  by  keeping
       jobs with a unlimited runtime limit separated from ARs, and not consid-
       ering resources used by such jobs for reservation.

       Note: Resource Quotas are not considered for AR queue selection and nor
       for jobs requesting a AR.

       When an AR was successfully added to the Univa Grid Engine queuing sys-
       tem qrsub returns a unique integer ID referring the the  newly  created
       AR. The highest AR ID is 9999999. If the highest ID is reached, a wrap-
       around happens and the next unused ID, starting with 1, will be used.

       For qrsub, the administrator and the user may  define  default  request
       files (analogous to Univa Grid Engine_request for qsub), which can con-
       tain any of the possible command line options.
       A cluster wide default request file is optional.   If  such  a  default
       request file is used, it must be placed under
       $SGE_ROOT/$SGE_CELL/common/sge_ar_request (global defaults file).
       A user private default request file is optional. If it is used, it must
       be placed under
       $HOME/.sge_ar_request (user private defaults file).

OPTIONS
       -a date_time
              Defines the activation (start) date and  time  of  an  AR.   The
              option  is  not  mandatory. If omitted, the current date_time is
              assumed. Either a duration or end date_time  must  be  specified
              for ARs. For details about date_time please see sge_types(1) For
              SRs the start time is optional and determines the earliest  pos-
              sible  allocation time of an AR (but not the actual beginning of
              the first AR).

       -A account_string
              Identifies the account to which the resource reservation of  the
              AR  should be charged. For "account_string" value details please
              see the "name" definition in sge_types(1).  In  the  absence  of
              this  parameter Univa Grid Engine will place the default account
              string "sge" in the accounting record of the AR.

       -cal_week weekly_calendar
              If a calendar is defined it is a Standing  Reservation  request.
              The  weekly  calendar  has  the  same  format as in the calendar
              object (see calendar_conf(5)) with the exception that only  "on"
              as state is allowed. The weekly calendar defines the time ranges
              for which AR instances should be created.  The  scheduler  tries
              to allocate a fixed amount of ARs. That amount can be influenced
              with the depth ("-cal_depth") parameter. All  ARs  within  a  SR
              have  the  same ID. Jobs running within one AR are deleted at AR
              end (like with ARs) but queued jobs are staying  queued  waiting
              for  the  next AR occurrence within the SR. Giving a start time,
              end time, or duration is optional for SRs. If  given  the  start
              time  determines  the  earliest allowed start time for the first
              AR.  The end time determines the last possible end time  of  the
              last  AR within the SR. The duration specifies the end time.  If
              one AR within the SR ends new ARs are  scheduled  automatically,
              so  that  the  total amount of allocated ARs are equal to the SR
              depth.

       -cal_depth number
              Specifies the depth of the SR. The depth determines how many ARs
              are  allocated  (scheduled) at one point in time for the future.
              ARs which can not get enough resources are un-allocated and  not
              counted.  If  un-allocated  ARs are allowed for the SR is deter-
              mined by the "-cal_jmp" parameter. If one AR  ends  further  ARs
              are allocated so that the depth is restored again.

       -cal_jmp number
              The  jmp  parameter  determines how many calendar entries can be
              jumped over if they can not be allocated for ARs due to  missing
              resources.  Per default it is not allowed to jump over non-allo-
              cated ARs (0). The SR will end then.

       -ckpt ckpt_name
              Selects the checkpointing environment (see checkpoint(5)) the AR
              jobs  may request. Using this option guarantees queues that only
              providing this checkpoint environment will be reserved.

       -d time
              Defines the duration of the AR. The use of "-d time" is optional
              if "-e date_time" is requested.  For details about  "time" defi-
              nition  please  see  sge_types(1).   For  SRs  the  duration  is
              optional  and  determines implicitly the end time, i.e. the last
              possible end time for the last AR within the SR.

       -e date_time
              Defines the end  date  and  time  of  an  AR.  The  use  of  "-e
              date_time"  is  optional if "-d time" is requested.  For details
              about "date_time" definition please see sge_types(1).   For  SRs
              the  end  time  is optional and determines the last possible end
              time for the last AR within the SR.

       -fr y[es]|n[o]
              Specifies the behaviour of the AR at AR start time.  With  ("-fr
              yes") jobs still blocking resources being granted to the AR will
              be killed.  With  default  behaviour  ("-fr  no")  jobs  holding
              resources  being  granted to the AR can continue running and may
              prevent start of jobs in the AR.  In the current  implementation
              only  resources  requested by the AR via exclusive complexes are
              freed.  The feature is suited for freeing whole queue  instances
              or  hosts  or  even the whole cluster, e.g. for maintenance pur-
              poses.  Requesting "-fr yes" requires operator rights.

       -he y[es]|n[o]
              Specifies the behavior when the AR goes into an error state. The
              AR  goes into error state when a reserved host goes into unknown
              state, a queue error happens, or when a  queue  is  disabled  or
              suspended.

              A  hard  error,  "-he  yes", means as long as the AR is in error
              state no jobs using the AR will be scheduled.   If  soft  error,
              "-he  no",  is  specified the AR stays usable with the remaining
              resources.
              By default soft error handling is used.


       -help  Prints a list of all options.

       -l resource=value,...
              Creates an AR in a Univa Grid Engine queue, providing the  given
              resource  request  list.   complex(5)  describes  how  a list of
              available resources and their associated valid value  specifiers
              can be obtained.
              There may be multiple -l switches in a single command.

       -m b|e|a|n
              Defines  or  redefines  under  which circumstances mail is to be
              sent to the AR owner or to the users defined with the -M  option
              described  below.  The option arguments have the following mean-
              ing:

              `b'     Mail is sent at the beginning of the AR
              `e'     Mail is sent at the end of the AR
              `a'     Mail is sent when the AR goes into error state
              `n'     No mail is sent, default for qrsub

       -M user[@host],...
              Defines or redefines the list of  users  to  which  the  qmaster
              sends mail.

       -masterq wc_queue_list
              Only  meaningful for a parallel AR request together with the -pe
              option.

              This option is used to reserve the proper queues to  match  this
              request  if  it  would  be requested by a qsub.  A more detailed
              description of wc_queue_list can be found in sge_types(1).

       -now y[es]|n[o]
              This options impacts the queues selection for reservation.
              With the "-now y" option, only queues with the  qtype  "INTERAC-
              TIVE"  assigned will be considered for reservation.  "-now n" is
              the default for qrsub.

       -N name
              The name of the AR. The name,  if  requested,  must  conform  to
              "name" as defined in sge_types(1).  Invalid names will be denied
              at submit time.

       -P project_name
              This option binds the AR to a  project.  Only  members  of  this
              project are allowed to use this AR.

       -w e|v Specifies the validation level applied to the AR request.

              The specifiers e and v define the following validation modes:

              `v'  verify - does not submit the AR but prints
                   an extensive validation report
              `e'  error - rejects request if requirements cannot
                   be fulfilled, default for qrsub

       -pe parallel_env n[-[m]]|[-]m,...
              Parallel programming environment (PE) to select for the AR queue
              reservation.  Please see the details of a PE in sge_pe(5).

       -q wc_queue_list
              Defines or redefines a list of cluster queues, queue domains  or
              queue  instances,  that may be reserved by the AR. Please find a
              description of wc_queue_list in  sge_types(1).   This  parameter
              has  all the properties of a resource request and will be merged
              with requirements derived from the -l option described above.

       -rao y[es]|n[o]
              Specifies which resources will be considered for the AR at  sub-
              mission / reservation time.  With -rao yes only currently avail-
              able resources will be reserved, this means  only  queues  which
              are  not in disabled, suspended or error state.  Default setting
              for -rao is "no".  A cluster wide  setting  for  only  reserving
              available    resources    can    be   done   via   qmaster_param
              AR_RESERVE_AVAILABLE_ONLY, see also sge_conf(5).

       -si session_id
              Requests sent by this client to the sge_qmaster(1)  daemon  will
              be done as part of the specified session. If the switch is omit-
              ted or if NONE is specified as  session_id  then  such  requests
              will be executed outside the control of a session.

              Find more information concerning sessions in session_conf(5).

       -u [username|@access_list],...
              Defines  the users allowed to submit jobs requesting the AR. The
              access is specified by a comma separated  list  containing  UNIX
              users or ACLs (see access_list(5)).  prefixing the ACL name with
              an '@' sign.
              By default only the AR owner is allowed to submit jobs  request-
              ing the AR.

              Note:  Only  queues,  where all users specified in the list have
              access, are considered for reservation (see queue_conf(5)).

ENVIRONMENTAL VARIABLES
       SGE_ROOT       Specifies the location of the Univa Grid Engine standard
                      configuration files.

       SGE_CELL       If set, specifies the default Univa Grid Engine cell. To
                      address a Univa Grid Engine cell, qsub, qsh,  qlogin  or
                      qalter use (in the order of precedence):

                             The name of the cell specified in the environment
                             variable SGE_CELL, if it is set.

                             The name of the default cell, i.e. default.

       SGE_DEBUG_LEVEL
                      If set, specifies that debug information should be writ-
                      ten  to stderr. In addition the level of detail in which
                      debug information is generated is defined.

       SGE_QMASTER_PORT
                      If set, specifies the TCP port on  which  sge_qmaster(8)
                      is  expected to listen for communication requests.  Most
                      installations will use a services map entry for the ser-
                      vice "sge_qmaster" instead of defining the port.

FILES
       $SGE_ROOT/$SGE_CELL/common/sge_ar_request
                      global defaults file
       $HOME/.sge_ar_request
                      user private defaults file

SEE ALSO
       qrdel(1),  qrstat(1), qsub(1), sge_types(1), checkpoint(5), complex(5),
       queue_conf(5), session_conf(5), sge_pe(5), sge_resource_quota(5).  cal-
       endar_conf(5).

COPYRIGHT
       See sge_intro(1) for a full statement of rights and permissions.




Univa Grid Engine User Commands    UGE 8.5.4                          QRSUB(1)