% 
% 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_VIADUCC'></a>}
\fi
    \section{viaducc and java\_viaducc}
    \label{sec:cli.viaducc}

    \paragraph{Description:}
        Viaducc is a small script wrapper around the \hyperref[sec:cli.ducc-process-submit]{\em
          ducc\_process\_submit } CLI to facilitate launching processes on DUCC-managed machines,
          either from the command line or from an Eclipse run configuration.

        \begin{sloppypar}
          When run from the command line as ``viaducc'', the arguments are bundled into the form expected by
          \hyperref[sec:cli.ducc-process-submit]{\em ducc\_process\_submit } and submitted to DUCC.
          By default the remote stdin and stdout of the deployed process are mapped back to the 
          command line terminal.
        \end{sloppypar}
        
        If a symbolic link to the viaducc script is created with the name ``java\_viaducc''
        and used from the command line,
        the arguments are assumed to be a Java classname and its arguments.
        The java process will be executed using DUCC's default JRE, or
        optionally, a specific JRE supplied by the user with a -D argument.

        If the ``java\_viaducc'' symbolic link is installed in a JRE/bin directory, DUCC will use
        the java executable from the same directory. More interestingly, it may be specified as an alternative
        to the ``java'' command in an eclipse launcher.  The remote stdin and stdout of the deployed
        DUCC process are redirected to the Eclipse console.  This provides essentially transparent
        execution of code in an Eclipse workspaces on DUCC-managed resources.

    \paragraph{Usage:}
\begin{verbatim}
     viaducc [defines] [command and parameters]
\end{verbatim}
     or
\begin{verbatim}
     java_viaducc [defines] [java-class and parameters]
\end{verbatim}

     The ``defines'' are described below.  The ``command and parameters'' are either any command
     (with full path) and it's arguments, or a Java class (with a ``main'') and its arguments (including
     the classpath if necessary.)

     \paragraph{Defines}

     The arguments are specified in the syntax of Java ``-D'' system properties, to be more consistent
     with execution under Eclipse.
     \begin{description}
         \item[-DDUCC\_MEMORY\_SIZE] This specifies the memory required, in GB.  If not specified, the
           smallest memory quanta configured for the scheduler is used.
         \item[-DDUCC\_CLASS] This is the scheduling class to submit the process to.  It should generally
           be a non-preemptable class.  If not specified, it defaults to class ``fixed''.
         \item[-DDUCC\_ENVIRONMENT] This species additional environment parameters to pass to the job.
           It should specify a quoted string of blank-delimited K=V environment values.  For example:
\begin{verbatim}
      -DDUCC_ENVIRONMENT="DUCC_RLIMIT_NOFILE=1000 V1=V2 A=B"
\end{verbatim}
         \item[-DJAVA\_BIN] This species the exact ``java'' command to use, for ``java\_viaducc''.  It
           must be a full path to some JRE that is known to be installed on all the DUCC nodes.  If not
           specified, the JRE used to run ducc is used.
         \item[-DDUCC\_DESCRIPTION] The description string to use for the submission.
           If not specified, the description defaults to the executable name, viaducc or java\_viaducc.
         \item[-DDUCC\_NO\_CANCEL\_ON\_INTERRUPT] If specified this no-argument option disables 
           automatic process cancellation when the submitting process terminates before the remote process.
    \end{description}