uima-ducc-duccdocs/src/site/tex/duccbook/part2/cli/ducc-process-submit.tex

% 
% 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.
% 
2y% Create well-known link to this spot for HTML version
\ifpdf
\else
\HCode{<a name='DUCC_CLI_PROCESS_SUBMIT'></a>}
\fi
    \section{ducc\_process\_submit}
    \label{sec:cli.ducc-process-submit}
    \paragraph{Description:}
       Use {\em ducc\_process\_submit} to submit a Managed Reservation, also known as an
       {\em arbitrary process} to DUCC.  The intention
       of this function is an alternative to utilities such as {\em ssh}, in order to allow the
       spawned processes to be fully managed by DUCC.  This allows the DUCC scheduler to allocate
       the necessary resources (and prevent over-allocation), and the DUCC run-time environment
       to manage process lifetime.

       If {\em attach\_console} is specified, Stdin, Stderr, and Stdout of the remote
       process are redirected to the submitting console.  It is thus possible to run interactive
       sessions with remote processes where the resources are managed by DUCC.

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

    \paragraph{Options:}
    \begin{description}
    
        \item[$--$attach\_console] If specified, remote process stdout and stderr are 
          redirected to, and stdin redirected from, the local submitting console.
          
        \item[$--$cancel\_on\_interrupt] If specified, the remote process is monitored 
           and will be canceled if the submit command is interrupted, e.g. with CTRL-C. 
           This option always implies $--$wait\_for\_completion.
        
        \item[$--$description {[text]}] The text is any string used to describe the process. It is
          displayed in the Web Server. When specified on a command-line the text usually must be
          surrounded by quotes to protect it from the shell.

        \item[$--$debug ] Prints internal debugging information, intended for DUCC developers or
          extended problem determination.

        \item[$--$environment {[env vars]}] Blank-delimited list of environment variables and variable
          assignments. 
          Entries will be copied from the user's environment if just the variable name is
          specified, optionally with a final '*' for those with the same prefix.
          If specified, this is used for all DUCC processes in the job. Example:
\begin{verbatim}
--environment TERM=xterm DISPLAY=:1.0 LANG UIMA_*
\end{verbatim}

          \begin{sloppypar}
            Additional entries may be copied from the user's environment based on the setting of
            ducc.submit.environment.propagated in the global DUCC configuration ducc.properties.
          \end{sloppypar}

          Note: When used as a CLI option, the environment string must usually be
          quoted to protect it from the shell.

        \item[$--$help] Prints the usage text to the console.

        \item[$--$log\_directory {[path-to-log directory]} ]

          This specifies the path to the directory for the user logs. If not specified, the default
          is \$HOME/ducc/logs. Example: 
\begin{verbatim}
--log_directory /home/bob 
\end{verbatim}
          
          Within this directory DUCC creates a sub-directory for each process, using the numerical 
          ID of the job. The format of the generated log file names as described
          \hyperref[chap:job-logs]{here}.
          
          Note: Note that $--$log\_directory specifies only the path to a directory where 
          logs are to be stored. In order to manage multiple processes running in multiple 
          machines DUCC, sub-directory and file names are generated by DUCC and may 
          not be directly specified. 

        \item[$--$process\_executable {[program name]}] This is the full path to a program to be
          executed. (Required)

        \item[$--$process\_executable\_args {[argument list]}] This is a list of arguments for
          {\em process\_executable}, if any.   When specified on a command-line the text usually must be
          surrounded by quotes to protect it from the shell.

        \item[$--$process\_memory\_size {[size]} ] This specifies the maximum amount of RAM in GB to
          be allocated to each process.  This value is used by the Resource Manager to allocate
          resources. if this amount is exceeded by a process the Agent terminates the process with a
          ShareSizeExceeded message.

        \item[$--$scheduling\_class {[classname]} ] This specifies the name of the scheduling class the
          RM will use to determine the resource allocation for each process. The names of the
          classes are installation dependent.
          If not specified, the FIXED\_SHARE default is taken from the site class definitions file
          described \hyperref[subsubsec:class.configuration]{here.} 

        \item[$--$specification, $-$f {[file]} ] All the parameters used to submit a process may be placed
          in a standard Java properties file.  This file may then be used to submit the process
          (rather than providing all the parameters directory to submit).
          
          For example, 
\begin{verbatim}
ducc_process_submit --specification job.props 
ducc_process_submit -f job.props 
\end{verbatim}

          where job.props contains: 
\begin{verbatim}
working_directory   = /home/bob/projects
environment         = AE_INIT_TIME=10000 LD_LIBRARY_PATH=/a/bogus/path 
log_directory       = /home/bob/ducc/logs/ 
description         = Simple Process
scheduling_class    = fixed 
process_memory_size = 15 
\end{verbatim}

        \item[$--$suppress\_console\_log] If specified, suppress creation of the log files that 
          normally hold the redirected stdout and stderr.

        \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 ]             
          If specified, the submit command monitors the remote process and prints periodic
          state and progress information to the console.  When the process completes, the monitor
          is terminated and the submit 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.

        \item[$--$working\_directory ] This specifies the working directory to be set by the Job
          Driver and Job Process processes.  If not specified, the current directory is used.

     \end{description}
        
    \paragraph{Notes:}