% 
% Licensed to the Apache Software Foundation (ASF) under one
% or more contributor license agreements.  See the NOTICE file
% distributed with this work for additional information
% regarding copyright ownership.  The ASF licenses this file
% to you under the Apache License, Version 2.0 (the
% "License"); you may not use this file except in compliance
% with the License.  You may obtain a copy of the License at
% 
%   http://www.apache.org/licenses/LICENSE-2.0
% 
% Unless required by applicable law or agreed to in writing,
% software distributed under the License is distributed on an
% "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
% KIND, either express or implied.  See the License for the
% specific language governing permissions and limitations
% under the License.
% 
% Create well-known link to this spot for HTML version
\ifpdf
\else
\HCode{<a name='DUCC_CLI_RESERVE'></a>}
\fi
    \section{ducc\_reserve}

    \paragraph{Description:}
    The reserve CLI is used to request a reservation of resources. Reservations can be for machines 
    based on memory requirements. All reservations are persistent: 
    the resources remain dedicated to the requester until explicitly returned. All reservations are 
    performed on an "all-or-nothing" basis: either the entire set of requested resources is reserved, 
    or the reservation request fails. 

    All forms of ducc\_reserve block until the reservation is complete (or fails) at which point the DUCC
    ID of the reservation and the names of the reserved nodes are printed to the console and the
    command returns.

    \paragraph{Usage:}
        \begin{description}
        \item[Script wrapper] \ducchome/bin/ducc\_reserve {\em options}
        \item[Java Main]      java -cp \ducchome/lib/uima-ducc-cli.jar org.apache.uima.ducc.cli.DuccReservationSubmit {\em options}
        \end{description}

    \paragraph{Options:}
    
        \begin{description}

            \item[$--$cancel\_on\_interrupt] If specified, the request is monitored 
              and will be canceled if the reserve command is interrupted, e.g. with CTRL-C. 
              This option always implies $--$wait\_for\_completion.

            \item[$--$debug ]          
              Prints internal debugging information, intended for DUCC developers or extended problem determination.
              
            \item[$--$description {[text]}]               
              The text is any string used to describe the reservation. It is displayed in the Web Server. 
              
            \item[$--$help ]             
              Prints the usage text to the console. 
                            
            \item[$--$memory\_size {[integer]}]               
              This specifies the amount of memory the reserved machine must support. After rounding
              up it must match the total usable memory on the machine. (Required)

              Alias: $--$instance\_memory\_size

            \item[$--$scheduling\_class {[classname]}]               
              This specifies the name of the scheduling class used to determine the resource 
              allocation for each process. It must be one implementing the RESERVE policy.
              If not specified, the RESERVE default is taken from the site class definitions file
              described \hyperref[subsubsec:class.configuration]{here.} 
              
            \item[$-$f, $--$specification {[file]}]               
              All the parameters used to request a reservation may be placed in a standard Java 
              properties file. This file may then be used to submit the request (rather than providing all 
              the parameters directory to submit). 

           \item[$--$timestamp ]
             If specified, messages from the submit process are timestamped. This is intended primarily 
             for use with a monitor with --wait\_for\_completion. 

           \item[$--$wait\_for\_completion ]             
             By default, the reserve command monitors the request and prints periodic
             state and progress information to the console.  When the reservation completes, the monitor
             is terminated and the reserve command returns.  If the command is interrupted, e.g. with CTRL-C,
             the request will not be canceled unless $--$cancel\_on\_interrupt is also specified.
             If this option is disabled by specifying a value of ``false'', the command returns as
             soon as the request has been submitted.


        \end{description}
            
    \paragraph{Notes:}
    Reservations must be for entire machines, in a job class implementing the RESERVE scheduling
    policy. The default DUCC distribution configures class {\em reserve} for entire machine
    reservations.  If there is no available machine in that class matching the requested size (after
    rounding up) the request is queued.  The user may cancel the request with {\em ducc\_unreserve}
    or with CTRL-C if $--$cancel\_on\_interrupt was specified.