<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
                         "http://docbook.org/xml/4.4/docbookx.dtd">
<chapter>
    <title>Execution</title>
    <sect1>
        <title>Synopsis</title>
        <para>Write the execution script for the component and pre/post scripts if required.</para>
    </sect1>
    <sect1>
        <title>Usage</title>
        <para>This page defines how the tool will be executed. At least for one operation system
            (Windows or Linux) an execution command must be defined. It is possible to provide both,
            the correct one will be chosen at workflow start. The scripting language is Batch/Shell.
            Also, you can provide a pre-execution and a post-execution script. These run before
            resp. after the execution of the tool and are written in Python (it is a Java adapted
            version of Python, called Jython. Please note that Jython does not support all external
            modules for Python.)</para>
        <para>In the scripts and commands, you are able to use some of the elements you defined on
            the previous pages. They are listed in the dropdown boxes on the righthand side. To use
            them, select the desired one and click on “Insert” and a placeholder for the chosen
            element will be inserted into the active script. You could also just write the correct
            placeholder syntax into the script. The elements are:<itemizedlist>
                <listitem>
                    <para><emphasis role="bold">Inputs:</emphasis> Placeholder: ${in:Input name}:
                        These placeholders will be replaced with the values that was received by the
                        component as input in the current run. Every type except File and Directory
                        is replaced with the actual value (e.g. a float placeholder “${in:x} will be
                        replaced with “1.0” if that value was received). File and Directory will not
                        be replaced with the content, but with the absolute path of the
                        corresponding file or folder. Strings and the inserted paths need (single)
                        quotation marks in the scripts to be used (e.g. “ ‘${in:file}’ ”). Please
                        note that placeholders for inputs that do not have any input data in the
                        current run (e.g. input constraint "Required if connected" and no output
                        currently connected) will not be replaced at runtime.</para>
                    <para>Inputs are available for every script.</para>
                    <para><emphasis role="italic">Vector/Matrix: If you have an input of the type
                            vector/matrix, the placeholder can be used in the pre and post script
                            like an array in Python. So ‘${in:vec}[0]’/‘${in:matrix}[0][0]’ will
                            return the first element of the incoming vector ‘vec’ resp. matrix
                            'matrix'. In the command execution scripts, inserting a vector/matrix is
                            not possible.</emphasis></para>
                </listitem>
                <listitem>
                    <para><emphasis role="bold">Outputs:</emphasis> Placeholder: ${out:Output name}:
                        Outputs are only available in the pre/post execution scripts. They will be
                        replaced by a special variable for RCE, to identify them after the script
                        has finished. Its current value is read and written to the corresponding
                        component output. Again, File and Directory do not provide their content,
                        but the absolute path. Output placeholders should only be used as
                        assignments.</para>
                </listitem>
                <listitem>
                    <para><emphasis role="bold">Properties: </emphasis> Placeholder: ${prop: key }:
                        These are the properties you can define on the “Property Configuration
                        Page”. You can insert them into the scripts and they will be replaced by the
                        value that is entered when configuring a workflow. Properties are available
                        for every script.</para>
                </listitem>
                <listitem>
                    <para><emphasis role="bold">Directories:</emphasis> Placeholder: ${dir:type}:
                        The directory placeholders are provided by the integration and represent the
                        directories that are created in the temp directory. There are four types of
                        directories which are available for every script:<itemizedlist>
                            <listitem>
                                <para><emphasis role="bold">Config dir:</emphasis> This is the
                                    absolute path to the created configuration directory. Here, the
                                    files from the properties are written and other configuration
                                    files can be stored here.</para>
                            </listitem>
                            <listitem>
                                <para><emphasis role="bold">Working dir:</emphasis> This is the
                                    directory where “Input” and “Config” will be created. It can be
                                    the same on each run, but if you chose the option for a new
                                    working directory on each iteration, it will be different every
                                    run. From this directory, the tool will be called, so if the
                                    tool writes output into the folder relative to its caller, this
                                    will be the place to look at.</para>
                            </listitem>
                            <listitem>
                                <para><emphasis role="bold">Input dir:</emphasis> In this directory,
                                    every input file or directory received by the component is
                                    written.</para>
                            </listitem>
                            <listitem>
                                <para><emphasis role="bold">Tool dir:</emphasis> This is absolute
                                    path to the tool directory. If the tool is not copied to the
                                    working directory, it is exactly the same path that was chosen
                                    in the launch config. If the tool is copied once or on each run
                                    to the working directory, it is the absolute path to the new
                                    (copied) tool directory.</para>
                            </listitem>
                            <listitem>
                                <para><emphasis role="bold">Output dir:</emphasis>In this directory
                                    output files or directories to be sent by the component can be
                                    written.</para>
                            </listitem>
                        </itemizedlist></para>
                </listitem>
                <listitem>
                    <para><emphasis role="bold">Additional Properties:</emphasis> Placeholder:
                        ${addProp:key}: This are properties which are provided by the component. At
                        the moment, this is only the exit code from the tool command. It is only
                        available in the post-execution script.</para>
                    <para>If the tool needs same inputs to be copied in another folder than the
                        Input folder, it should be done using the pre-execution script.<note>
                            <para>During execution, all content to replace in pre, post or command
                                scripts will be tested for insecure characters (such as /,?,* etc.).
                                If it contains insecure characters, the replacement will be denied
                                and the execution of the workflow will fail. This stringent behavior
                                is needed to prevent malicious code execution, especially on remote
                                hosts like compute nodes.</para>
                        </note></para>
                </listitem>
                <listitem>
                    <para><emphasis role="bold">Windows/Linux execution scripts:</emphasis> The
                        execution scripts for both operating systems are the native commands (Batch
                        on Windows, Shell on Linux).</para>
                    <para>Every line in these scripts represents a single command. All commands will
                        be concatenated and executed in one terminal. For example, invoking a
                        program:</para>
                    <para>Windows: <programlisting>testTool.exe</programlisting></para>
                    <para>Linux:<programlisting>./testTool.sh</programlisting></para>
                    
                    <note>
                            <para>On Linux, you can specify the shell which should be used for command
                             execution by inserting a shebang in the first line of the script, e.g.: #!/bin/bash</para>
                             <para>This forces RCE to execute the commands in the specified shell instead
                              of using the default one. Make sure that the shebang is the only content of 
                              the first line and that the specified shell is available on your system. Please 
                              note that currently only #!/bin/bash and #!/bin/sh are supported.</para>
                    </note>
                    
                    <para>Placeholder for inputs, directories or properties can also be used as
                        command line parameters, for example:</para>
                    <para>Windows:<programlisting>testTool.exe ${in:NumberOfRuns}</programlisting></para>
                    <para>Linux:<programlisting>./testTool.sh ${in:NumberOfRuns}</programlisting><note>
                            <para>For more information about the command lines see:</para>
                            <para>Windows: <ulink url="http://dosprompt.info/"
                                    >http://dosprompt.info/</ulink></para>
                            <para>Linux: <ulink url="http://linuxcommand.org/learning_the_shell.php"
                                    >http://linuxcommand.org/learning_the_shell.php</ulink></para>
                        </note></para>
                    <para>Example for copying a file: For copying a file, the pre/post execution
                        scripts should be used. In Jython, a file can be copied using the shutil
                        module. The
                        command<programlisting>shutil.copy('${in:inputFile}', '${dir:tool}/test.txt')</programlisting></para>
                    <para>will copy the input file “inputFile” into the tool directory and rename it
                        to ‘test.txt’. Note that since the placeholder for the incoming file and
                        tool directory are replaced before the script execution, the placeholder has
                        to be written with apostrophes.</para>
                    <para>For joining paths, it is possible to use a slash “/” for any operation
                        system.</para>
                    <para>Note that "Insert copy of file/dir ... " on the righthand side opens a
                        helper dialog to construct copying commands as above.</para>
                    <para><emphasis role="bold">Using the RCE Script API:</emphasis></para>
                    <para>Since RCE 6.0.0, the API for the script component is also available in the
                        pre and post scripts in tool integration. With this you can also read and
                        write outputs from/to RCE. There are some other methods for example for
                        writing a "not a value" output to RCE, in case that a component could not
                        run with the current input because it is out of the calculations bounds. You
                        can also let the component fail in the scripts or close outputs for
                        terminating the workflow. More information about the API is in the script
                        components help and you can find examples for all API methods in the example
                        workflow "04_02_Script_And_Tool_Integration_API.wf".</para>
                </listitem>
                <listitem>
                    <para><emphasis role="bold">Execution Options:</emphasis><itemizedlist>
                            <listitem>
                                <para><emphasis role="bold">Exit code other than 0 is not an
                                        error:</emphasis> With this option, the component won’t
                                    crash if your tool returns a different exit code than 0. This is
                                    necessary for some tools since a non zero exit code does not
                                    necessarily mean the tool failed. The tool will just run as if
                                    everything was ok and the exit code can be analyzed in the post
                                    execution script. Note that the exit code is always the code
                                    from the whole execution script. If the tool fails with another
                                    exit code but the script does something successful after it, it
                                    will return a 0.</para>
                            </listitem>
                            <listitem>
                                <para><emphasis role="bold">Execute (command(s), pre/post script,
                                        tool run imitation script) from:</emphasis><itemizedlist>
                                        <listitem>
                                            <para><emphasis role="bold">Working
                                                  directory:</emphasis> The execution command will
                                                be called in the working directory.</para>
                                        </listitem>
                                        <listitem>
                                            <para><emphasis role="bold">Tool directory:</emphasis>
                                                In some cases, the execution directory has to be in
                                                the directory where the tool is located. This option
                                                changes the execution directory to this. (It is like
                                                calling “cd ${dir:tool}” in the execution
                                                command)</para>
                                        </listitem>
                                    </itemizedlist></para>
                            </listitem>
                        </itemizedlist></para>
                </listitem>
                <listitem>
                    <para><emphasis role="bold">Tool Run Imitation:</emphasis> In a workflow usually
                        multiple tools are integrated and complex workflow logic is applied. For
                        debugging purposes, it is sometimes useful not to actually run each tool
                        involved, but to imitate some tool runs until the workflow logic is properly
                        set up. For that use case, a so called "Tool run imitation mode" exists. By
                        default, it is disabled for an integrated tool. You can enable it by
                        checking the box "Support tool run imitation". By doing that you need to
                        define the behavior of an imitated tool run.</para>
                    <para>The workflow creator can decide at workflow design time, whether to run
                        the tool normally or to only imitate tools run. This is defined in the
                        workflow component's properties tab "Imitation mode".</para>
                </listitem>
            </itemizedlist></para>
        <para>When every necessary field is filled, you can integrate your tool on this page. It
            will be saved to your disk and integrated as a workflow component. You also can choose
            just to save the configuration without activating it. </para>
    </sect1>
</chapter>
