Big-Data-HPC-Platform/docs/HPCCClientTools/CT_Mods/CT_Comm_Line_DFU.xml

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<book>
  <bookinfo>
    <title>Client Tools Overview</title>

    <author>
      <firstname>Boca Raton</firstname>

      <surname>Documentation Team</surname>

      <affiliation>
        <orgname>Lexis Nexis</orgname>
      </affiliation>
    </author>

    <pubdate>Sept. 2011</pubdate>
  </bookinfo>

  <chapter id="Command_Line_DFU">
    <title><emphasis role="bold">Command Line DFU</emphasis></title>

    <sect1 id="Command_Line_InterfaceDFU" role="nobrk">
      <title>Command Line Interface</title>

      <sect2 id="DFUPlusexe">
        <title><emphasis>dfuplus.exe</emphasis></title>

        <para><emphasis role="bold">dfuplus </emphasis><emphasis>
        </emphasis><emphasis role="bold">action=</emphasis><emphasis>operation
        </emphasis><emphasis role="bold">[</emphasis><emphasis> @filename
        </emphasis><emphasis role="bold">| </emphasis><emphasis>options
        </emphasis><emphasis role="bold">]</emphasis></para>

        <informaltable colsep="0" frame="none" rowsep="0">
          <tgroup cols="2">
            <colspec align="left" colwidth="85.40pt" />

            <colspec />

            <tbody>
              <row>
                <entry><emphasis>operation</emphasis></entry>

                <entry>One of the following actions: spray, despray, copy,
                remove, rename, list, add, addsuper, removesuper, listsuper,
                savexml, status, abort, resubmit, monitor</entry>
              </row>

              <row>
                <entry><emphasis>@filename</emphasis></entry>

                <entry>Optional. The name of a file containing necessary
                <emphasis>options</emphasis>. If omitted and no command line
                <emphasis>options</emphasis> are specified, the appropriate
                <emphasis>options</emphasis> must be in the dfuplus.ini
                file.</entry>
              </row>

              <row>
                <entry><emphasis>options</emphasis></entry>

                <entry>Optional. A space-delimited list of optional items
                (listed below) appropriate to the
                <emphasis>operation</emphasis> being executed. If omitted and
                no <emphasis>@filename</emphasis> is specified, the
                appropriate <emphasis>options</emphasis> must be in the
                dfuplus.ini file.</entry>
              </row>
            </tbody>
          </tgroup>
        </informaltable>

        <para>The <emphasis role="bold">dfuplus.exe</emphasis> application
        accepts command line parameters to send to the Distributed File
        Utility (DFU) engine via the ESP server. These
        <emphasis>options</emphasis> can be specified on the command line, in
        the <emphasis>@filename</emphasis>, in the dfuplus.ini file, or any
        combination. Command line <emphasis>options</emphasis> override any in
        the nominated <emphasis>@filename</emphasis>, which in turn override
        any in the dfuplus.ini file.</para>

        <sect3>
          <title>General Options:</title>

          <para>The following <emphasis>options </emphasis>are common to every
          <emphasis>operation</emphasis>:</para>

          <informaltable colsep="0" frame="none" rowsep="0">
            <tgroup cols="2">
              <colspec align="left" colwidth="125.40pt" />

              <colspec />

              <tbody>
                <row>
                  <entry><emphasis>server</emphasis></entry>

                  <entry>The URL (http:// or https://) and/or IP address of
                  the ESP server. The port may also be included.</entry>
                </row>

                <row>
                  <entry><emphasis>username</emphasis></entry>

                  <entry>A userid with authorized access to the
                  <emphasis>server</emphasis>.</entry>
                </row>

                <row>
                  <entry><emphasis>password</emphasis></entry>

                  <entry>The password authorizing access for the
                  <emphasis>username</emphasis>.</entry>
                </row>

                <row>
                  <entry><emphasis>overwrite</emphasis></entry>

                  <entry>Optional. A boolean flag (0 | 1) indicating whether
                  to overwrite any existing file of the same name. If omitted,
                  the default is 0.</entry>
                </row>

                <row>
                  <entry><emphasis>replicate</emphasis></entry>

                  <entry><para>Optional. A boolean flag (1 | 0) indicating
                  whether to replicate the file. If omitted, the default is
                  1.</para><para><emphasis role="bold">This option is only
                  available on systems where replication has been
                  enabled.</emphasis></para></entry>
                </row>

                <row>
                  <entry><emphasis>autorecover</emphasis></entry>

                  <entry>Optional. The number of times to attempt recovery of
                  a failed <emphasis>operation</emphasis>. If omitted, the
                  default is 0.</entry>
                </row>

                <row>
                  <entry><emphasis><emphasis>nowait</emphasis></emphasis></entry>

                  <entry>Optional. A boolean flag (0 | 1) indicating whether
                  to return immediately without waiting for completion of the
                  <emphasis>operation</emphasis>. If omitted, the default is
                  0.</entry>
                </row>

                <row>
                  <entry><emphasis><emphasis>connect</emphasis></emphasis></entry>

                  <entry>Optional. The number of simultaneous connections to
                  limit the <emphasis>operation </emphasis>to. If omitted, the
                  default is 25.</entry>
                </row>

                <row>
                  <entry><emphasis><emphasis>throttle</emphasis></emphasis></entry>

                  <entry>Optional. The transfer speed (in Mbits/second) to
                  restrict the <emphasis>operation</emphasis> to. If omitted,
                  the default is the best system speed in Linux and
                  multiple-destination Windows, or the NIC speed of a
                  single-destination Windows box.</entry>
                </row>

                <row>
                  <entry><emphasis><emphasis><emphasis>norecover</emphasis>
                  </emphasis></emphasis></entry>

                  <entry>Optional. A boolean flag (0 | 1) indicating whether
                  to create or recover the <emphasis>operation</emphasis> from
                  recovery information. If omitted, the default is 0.</entry>
                </row>

                <row>
                  <entry><emphasis><emphasis><emphasis>nosplit</emphasis>
                  </emphasis></emphasis></entry>

                  <entry>Optional. A boolean flag (0 | 1) indicating whether
                  to split file parts to multiple target parts. If omitted,
                  the default is 0.</entry>
                </row>

                <row>
                  <entry>compress</entry>

                  <entry>Optional. A boolean flag (0 | 1) indicating whether
                  to compress the target file.</entry>
                </row>

                <row>
                  <entry>push</entry>

                  <entry>Optional. A boolean flag (0 | 1) indicating whether
                  to override push/pull default.</entry>
                </row>

                <row>
                  <entry>encrypt=&lt;password&gt;</entry>

                  <entry>Optional. Specifies to encrypt the target filename
                  using the supplied password.</entry>
                </row>

                <row>
                  <entry>decrypt=&lt;password&gt;</entry>

                  <entry>Optional. Specifies to decrypt the source filename
                  using the supplied password.</entry>
                </row>

                <row>
                  <entry>jobname=&lt;jobname&gt;</entry>

                  <entry>Specify a jobname for the DFU operation's
                  workunit.</entry>
                </row>

                <row>
                  <entry>transferbuffersize=nnn</entry>

                  <entry>Optional. Overrides the DFU Server's buffer size
                  value (default is 64k)</entry>
                </row>
              </tbody>
            </tgroup>
          </informaltable>
        </sect3>

        <?hard-pagebreak ?>

        <sect3>
          <title>dfuplus.ini</title>

          <para>Any <emphasis>options</emphasis> can be specified in a file
          called dfuplus.ini. If your operating system is case-sensitive, make
          sure the filename is in lowercase. Options that rarely change can be
          put in the dfuplus.ini file. For example:</para>

          <programlisting>server=http://10.150.50.12:8010
username=rlor
password=password
overwrite=1
replicate=1</programlisting>

          <para>In all the examples below, we'll assume dfuplus.ini has the
          above content.</para>

          <para><informaltable colsep="1" frame="all" rowsep="0">
              <tgroup cols="2">
                <colspec colwidth="49.50pt" />

                <colspec />

                <tbody>
                  <row>
                    <entry><graphic fileref="../../images/caution.png"
                    scale="noin" /></entry>

                    <entry>We do not recommend storing your password in the
                    ini file (which is clear text). The password is included
                    in the ini file for these examples to simplify the example
                    code.</entry>
                  </row>
                </tbody>
              </tgroup>
            </informaltable></para>
        </sect3>

        <sect3>
          <title>Spray Operations:</title>

          <para>The <emphasis role="bold">spray</emphasis>
          <emphasis>operation</emphasis> copies a file from the landing zone,
          distributing it across all the nodes of the destination HPCC.</para>

          <para>These <emphasis>options </emphasis>are used by the <emphasis
          role="bold">spray</emphasis> <emphasis>operation</emphasis>:</para>

          <para><informaltable colsep="0" frame="none" rowsep="0">
              <tgroup cols="2">
                <colspec align="left" colwidth="122.50pt" />

                <colspec />

                <tbody>
                  <row>
                    <entry>srcip</entry>

                    <entry>Optional. The IP address of the source machine. If
                    omitted, the information must be supplied by the
                    <emphasis>srcxml</emphasis> parameter.</entry>
                  </row>

                  <row>
                    <entry>srcfile</entry>

                    <entry>Optional. The path to the source file. This may
                    contain wildcard characters (* and ?) to include multiple
                    source files in the spray to a single
                    <emphasis>dstname</emphasis>. If omitted, the information
                    must be supplied by the <emphasis>srcxml</emphasis>
                    parameter.</entry>
                  </row>

                  <row>
                    <entry>srcxml</entry>

                    <entry>The name of the XML file containing the information
                    required for the <emphasis>srcip</emphasis> and
                    <emphasis>srcfile</emphasis> parameters. This file may
                    have been obtained by previous use of the savexml
                    <emphasis>operation</emphasis>. This option provides the
                    feature of combining multiple source files into a single
                    resulting logical file in the HPCC.</entry>
                  </row>

                  <row>
                    <entry>dstname</entry>

                    <entry>The logical name of the destination file.</entry>
                  </row>

                  <row>
                    <entry>dstcluster</entry>

                    <entry>The name of the destination cluster.</entry>
                  </row>

                  <row>
                    <entry>prefix</entry>

                    <entry>Optional. Both of the following (separated by a
                    comma):</entry>
                  </row>

                  <row>
                    <entry><emphasis
                    role="bold">filename{:</emphasis><emphasis>length</emphasis><emphasis
                    role="bold">}</emphasis></entry>

                    <entry>Prepends the filename (optionally limited to
                    <emphasis>length</emphasis> characters) to the
                    data.</entry>
                  </row>

                  <row>
                    <entry><emphasis
                    role="bold">filesize{:[B|L][1-8]}</emphasis></entry>

                    <entry>Prepends the size of the file to the data.
                    Optionally, you can specify the format of that integer
                    (<emphasis role="bold">B</emphasis> specifies big endian,
                    <emphasis role="bold">L</emphasis> specifies little
                    endian) and the size of integer to contain it (<emphasis
                    role="bold">1</emphasis> to <emphasis
                    role="bold">8</emphasis> bytes). If format and size are
                    omitted, the default is L4.</entry>
                  </row>

                  <row>
                    <entry><emphasis>format</emphasis></entry>

                    <entry>Optional. One of the following values: <emphasis
                    role="bold">fixed csv delimited xml recfmv
                    recfmb</emphasis> If omitted, the default is
                    fixed.</entry>
                  </row>

                  <row>
                    <entry><emphasis role="bold">fixed</emphasis>
                    <emphasis>format</emphasis> options:</entry>
                  </row>

                  <row>
                    <entry><emphasis>recordsize</emphasis></entry>

                    <entry>The fixed size of each record, in bytes.</entry>
                  </row>

                  <row>
                    <entry><emphasis role="bold">csv/delimited</emphasis>
                    <emphasis>format </emphasis>options:</entry>
                  </row>

                  <row>
                    <entry><emphasis>encoding</emphasis></entry>

                    <entry>Optional. One of the following: ascii, utf8, utf8n,
                    utf16, utf16le, utf16be, utf32, utf32le, utf32be ; If
                    omitted, the default is ascii.</entry>
                  </row>

                  <row>
                    <entry><emphasis>maxrecordsize</emphasis></entry>

                    <entry>Optional. The maximum size of each record, in
                    bytes. If omitted, the default is 8192.</entry>
                  </row>

                  <row>
                    <entry><emphasis>separator</emphasis></entry>

                    <entry>Optional. The field delimiter. If omitted, the
                    default is a comma (\,).</entry>
                  </row>

                  <row>
                    <entry><emphasis>terminator</emphasis></entry>

                    <entry>Optional. The record delimiter. If omitted, the
                    default is line feed or carriage return line feed
                    (\r,\r\n).</entry>
                  </row>

                  <row>
                    <entry><emphasis>quote</emphasis></entry>

                    <entry>Optional. The string quote character. If omitted,
                    the default is single quote (’).</entry>
                  </row>

                  <row>
                    <entry><emphasis role="bold">xml</emphasis>
                    <emphasis>format </emphasis>options:</entry>
                  </row>

                  <row>
                    <entry><emphasis>rowtag</emphasis></entry>

                    <entry>The XML tag identifying each record.</entry>
                  </row>

                  <row>
                    <entry><emphasis>encoding</emphasis></entry>

                    <entry>Optional. One of the following: utf8 utf8n utf16
                    utf16le utf16be utf32 utf32le utf32beIf omitted, the
                    default is utf8.</entry>
                  </row>

                  <row>
                    <entry><emphasis>maxrecordsize</emphasis></entry>

                    <entry>Optional. The maximum size of each record, in
                    bytes. If omitted, the default is 8192.</entry>
                  </row>
                </tbody>
              </tgroup>
            </informaltable></para>

          <para>Examples:</para>

          <programlisting>//fixed spray example:
dfuplus action=spray srcip=10.150.50.14
          srcfile=c:\import\timezones.txt dstname=RTTEMP::timezones.txt
          dstcluster=thor format=fixed recordsize=155

//fixed spray example using a srcxml file:
dfuplus action=spray srcxml=c:\import\flattimezones.xml
          dstname=RTTEMP::timezones.txt dstcluster=thor recordsize=155

//csv spray example:
dfuplus action=spray srcip=10.150.50.14
          srcfile=c:\import\timezones.csv dstname=RTTEMP::timezones.csv
          dstcluster=thor format=csv

//the spray.xml file contains:
&lt;File directory="c:\import\"
   group="thor"
   modified="2004-04-27T14:58:38"
   name="zip"
   numparts="2"
   partmask="zip._$P$_of_$N$"&gt;
&lt;Attr job="zip1"
   owner="rtaylor"
   recordSize="5"
   replicated="1"
   workunit="D20040427-111857"/&gt;
&lt;Part modified="2004-04-27T14:58:40"
   node="10.150.51.29"
   num="1"
   size="165"/&gt;
&lt;Part modified="2004-04-27T14:58:40"
   node="10.150.51.29"
   num="2"
   size="165"/&gt;
&lt;/File&gt;

//fixed spray example using the above spray.xml file to
          combine
// multiple source files into a single logical file
// in this case, zip._1_of_3, zip._2_of_3, and zip._3_of_3
          into zip1:
dfuplus action=spray srcxml=spray.xml
          dstcluster=thordstname=RTTEMP::myzip1 recordsize=5

//xml spray example:
dfuplus action=spray srcip=10.150.50.14
          srcfile=c:\import\timezones.xml dstname=RTTEMP::timezones.xml
          dstcluster=thor format=xml rowtag=area

//Multiple spray all .JPG and .BMP files under
// c:\import on 10.150.51.26 to single logical file
          LE::imagedb:
dfuplus action=spray srcip=10.150.51.26
          srcfile=c:\import\*.jpg,c:\import\*.bmp

dstcluster=le_thor dstname=LE::imagedb overwrite=1
          prefix=FILENAME,FILESIZE nosplit=1
//this would result in a RECORD structure like this:
imageRecord := RECORD
STRING filename;
DATA image; //first 4 bytes contain the length of the image data
END;</programlisting>
        </sect3>

        <sect3>
          <title>Despray Operations:</title>

          <para>The <emphasis role="bold">despray</emphasis>
          <emphasis>operation</emphasis> combines file parts from all the
          nodes of the cluster into a single file on the landing zone.</para>

          <para>These <emphasis>options </emphasis>are used by the <emphasis
          role="bold">despray</emphasis> operation:</para>

          <informaltable colsep="0" frame="none" rowsep="0">
            <tgroup cols="2">
              <colspec align="left" colwidth="122.50pt" />

              <colspec />

              <tbody>
                <row>
                  <entry><emphasis>srcname</emphasis></entry>

                  <entry>The logical name of the source file. This may contain
                  wildcard characters (* and ?) to include multiple source
                  files in the despray to a single
                  <emphasis>dstfile</emphasis>.</entry>
                </row>

                <row>
                  <entry><emphasis>dstip</emphasis></entry>

                  <entry>Optional. The IP address of the destination machine.
                  If omitted, the information must be supplied by the
                  <emphasis>dstxml</emphasis> parameter.</entry>
                </row>

                <row>
                  <entry><emphasis>dstfile</emphasis></entry>

                  <entry>Optional. The path to the destination file. This may
                  contain wildcard characters (* and ?) to despray a single
                  <emphasis>srcname</emphasis>to multiple
                  <emphasis>dstfiles</emphasis>. If omitted, the information
                  must be supplied by the <emphasis>dstxml</emphasis>
                  parameter.</entry>
                </row>

                <row>
                  <entry><emphasis>dstxml</emphasis></entry>

                  <entry>The name of the XML file containing the information
                  required for the <emphasis>dstip</emphasis> and
                  <emphasis>dstfile</emphasis> parameters. This file may have
                  been obtained by previous use of the savexml
                  <emphasis>operation</emphasis>. This option provides the
                  feature of splitting a single resulting logical file in the
                  cluster into multiple destination files.</entry>
                </row>

                <row>
                  <entry><emphasis>splitprefix</emphasis></entry>

                  <entry>Optional. Both of the following (separated by a
                  comma):</entry>
                </row>

                <row>
                  <entry><emphasis
                  role="bold">filename{:</emphasis><emphasis>length</emphasis><emphasis
                  role="bold">}</emphasis></entry>

                  <entry>Uses the prepended filename (see the
                  <emphasis>prefix</emphasis> option to the spray
                  <emphasis>operation</emphasis>) to split out the data into
                  separate files.</entry>
                </row>

                <row>
                  <entry><emphasis
                  role="bold">filesize{:[B|L][1-8]}</emphasis></entry>

                  <entry>Uses the prepended size of the file (see the
                  <emphasis>prefix</emphasis> option to the spray
                  <emphasis>operation</emphasis>) to split out the data into
                  separate files.</entry>
                </row>
              </tbody>
            </tgroup>
          </informaltable>

          <para>Examples:</para>

          <programlisting>dfuplus action=despray dstip=10.150.50.14
   dstfile=c:\import\despray\timezones.txt srcname=RTTEMP::timezones.txt
//the spray.xml file contains:
&lt;File directory="c:\import\"
   group="thor"
   modified="2004-04-27T14:58:38"
   name="zip"
   numparts="2"
   partmask="zip._$P$_of_$N$"&gt;
&lt;Attr job="zip1"
   owner="rtaylor"
   recordSize="5"
   replicated="1"
   workunit="D20040427-111857"/&gt;
&lt;Part modified="2004-04-27T14:58:40"
   node="10.150.51.29"
   num="1"
   size="165"/&gt;
&lt;Part modified="2004-04-27T14:58:40"
   node="10.150.51.29"
   num="2"
size="165"/&gt;
&lt;/File&gt;
//despray example using the above spray.xml file to split a single
// logical file into multiple destination files
// in this case, zip._1_of_3, zip._2_of_3, and zip._3_of_3 from zip1:
dfuplus action=despray dstxml=spray.xml dstcluster=thor
          srcname=RTTEMP::myzip1


//from a RECORD structure that looks like this:
imageRecord := RECORD
STRING filename;
DATA image; //first 4 bytes contain the length of the image data
          END;

//you can despray into its component files like this:
dfuplus action=dspray srcname=le::imagedb
          dstip=10.150.51.26 dstfile=c:\export\
          splitprefix=FILENAME,FILESIZE
</programlisting>
        </sect3>

        <sect3>
          <title>Copy Operations:</title>

          <para>The <emphasis role="bold">copy</emphasis>
          <emphasis>operation</emphasis> copies a logical file (all file parts
          from all the nodes of the cluster), typically from one cluster to
          another. It appropriately handles re-distributing the file parts if
          the source and destination clusters do not have the same number of
          nodes. It may also be used to copy files from other HPCC
          environments (using the <emphasis>srcdali</emphasis> option).</para>

          <para>These <emphasis>options </emphasis>are used by the <emphasis
          role="bold">copy</emphasis> <emphasis>operation</emphasis>:</para>

          <informaltable colsep="0" frame="none" rowsep="0">
            <tgroup cols="2">
              <colspec align="left" colwidth="122.40pt" />

              <colspec />

              <tbody>
                <row>
                  <entry><emphasis><emphasis>srcname</emphasis></emphasis></entry>

                  <entry>The logical name of the source file.</entry>
                </row>

                <row>
                  <entry><emphasis>dstname</emphasis></entry>

                  <entry>The logical name of the destination file.</entry>
                </row>

                <row>
                  <entry><emphasis><emphasis>dstcluster</emphasis>
                  </emphasis></entry>

                  <entry>The name of the destination cluster.</entry>
                </row>

                <row>
                  <entry><emphasis><emphasis>srcdali</emphasis></emphasis></entry>

                  <entry>Optional. The IP address of the source Dali server,
                  if different from the destination Dali (associated with the
                  ESP Server specified in the <emphasis>server</emphasis>
                  option).</entry>
                </row>

                <row>
                  <entry><emphasis>srcusername</emphasis></entry>

                  <entry>Optional. The username to use to access the
                  <emphasis>srcdali</emphasis>. If omitted, the General
                  Options <emphasis>username</emphasis> is used.</entry>
                </row>

                <row>
                  <entry><emphasis><emphasis>srcpassword</emphasis>
                  </emphasis></entry>

                  <entry>Optional. The password to use to access the
                  <emphasis>srcdali</emphasis>. If omitted, the General
                  Options <emphasis>password</emphasis> is used.</entry>
                </row>
              </tbody>
            </tgroup>
          </informaltable>

          <para>Example:</para>

          <programlisting>dfuplus action=copy srcname=RTTEMP::timezones.txt
          dstname=srcname=RTTEMP::COPY::timezones.txt dstcluster=thor</programlisting>
        </sect3>

        <sect3>
          <title>Remove Operations:</title>

          <para>The <emphasis role="bold">remove</emphasis> operation deletes
          a logical file from the system data store, optionally leavingthe
          physical files in place.</para>

          <para>These <emphasis>options </emphasis>are used by the <emphasis
          role="bold">remove</emphasis> <emphasis>operation</emphasis>:</para>

          <para><informaltable colsep="0" frame="none" rowsep="0">
              <tgroup cols="2">
                <colspec align="left" colwidth="122.40pt" />

                <colspec />

                <tbody>
                  <row>
                    <entry><emphasis><emphasis><emphasis>name</emphasis></emphasis></emphasis></entry>

                    <entry>The logical name of the file to remove.</entry>
                  </row>
                </tbody>
              </tgroup>
            </informaltable> Example:</para>

          <programlisting>dfuplus action=remove name=RTTEMP::timezones.txt</programlisting>

          <para></para>
        </sect3>

        <sect3>
          <title>Rename Operations:</title>

          <para>The <emphasis role="bold">rename</emphasis> operation renames
          a logical file in the system data store.</para>

          <para>These <emphasis>options </emphasis>are used by the <emphasis
          role="bold">rename</emphasis> <emphasis>operation</emphasis>:</para>

          <informaltable colsep="0" frame="none" rowsep="0">
            <tgroup cols="2">
              <colspec align="left" colwidth="122.40pt" />

              <colspec />

              <tbody>
                <row>
                  <entry><emphasis><emphasis><emphasis><emphasis>srcname</emphasis></emphasis></emphasis></emphasis></entry>

                  <entry>The logical name of the source file.</entry>
                </row>

                <row>
                  <entry><emphasis><emphasis>dstname</emphasis></emphasis></entry>

                  <entry>The logical name of the destination file.</entry>
                </row>
              </tbody>
            </tgroup>
          </informaltable>

          <para>Example:</para>

          <programlisting>dfuplus action=rename srcname=RTTEMP::timezones.txt dstname=RTTEMP::NewTimezones.txt</programlisting>
        </sect3>

        <sect3>
          <title>List Operations:</title>

          <para>The <emphasis role="bold">list</emphasis> operation produces a
          list of logical files in the system data store.</para>

          <para>These <emphasis>options </emphasis>are used by the <emphasis
          role="bold">list</emphasis> <emphasis>operation</emphasis>:</para>

          <para><informaltable colsep="0" frame="none" rowsep="0">
              <tgroup cols="2">
                <colspec align="left" colwidth="122.40pt" />

                <colspec />

                <tbody>
                  <row>
                    <entry><emphasis><emphasis><emphasis><emphasis>name</emphasis></emphasis></emphasis></emphasis></entry>

                    <entry>The mask defining the logical file names to
                    list.</entry>
                  </row>
                </tbody>
              </tgroup>
            </informaltable></para>

          <para>Example:</para>

          <programlisting>dfuplus action=list name=*</programlisting>
        </sect3>

        <sect3>
          <title>Add Operations:</title>

          <para>The <emphasis role="bold">add</emphasis> operation adds a new
          logical file to the system data store.</para>

          <para>These <emphasis>options </emphasis>are used by the <emphasis
          role="bold">add</emphasis> <emphasis>operation</emphasis>:</para>

          <para><informaltable colsep="0" frame="none" rowsep="0">
              <tgroup cols="2">
                <colspec colwidth="122.40pt" />

                <colspec />

                <tbody>
                  <row>
                    <entry><emphasis><emphasis><emphasis><emphasis><emphasis>srcxml</emphasis>
                    </emphasis></emphasis></emphasis></emphasis></entry>

                    <entry>The logical name of the source XML file map
                    (typically from a previous savexml operation).</entry>
                  </row>

                  <row>
                    <entry><emphasis><emphasis>dstname</emphasis></emphasis></entry>

                    <entry>The logical name of the destination file.</entry>
                  </row>
                </tbody>
              </tgroup>
            </informaltable></para>

          <para>These <emphasis>options </emphasis>are used by the <emphasis
          role="bold">add</emphasis> <emphasis>operation </emphasis>to add
          files from a remote Dali:</para>

          <informaltable colsep="0" frame="none" rowsep="0">
            <tgroup cols="2">
              <colspec align="left" colwidth="122.40pt" />

              <colspec />

              <tbody>
                <row>
                  <entry><emphasis><emphasis>dstname</emphasis></emphasis></entry>

                  <entry>The logical name of the destination file.</entry>
                </row>

                <row>
                  <entry><emphasis>srcname</emphasis></entry>

                  <entry>The logical name of the source file.</entry>
                </row>

                <row>
                  <entry><emphasis><emphasis>srcdali</emphasis>
                  </emphasis></entry>

                  <entry>The IP address of the source Dali server.</entry>
                </row>

                <row>
                  <entry><emphasis>srcusername</emphasis></entry>

                  <entry>Optional. The username to use to access the
                  <emphasis>srcdali</emphasis>. If omitted, the General
                  Options <emphasis>username</emphasis> is used.</entry>
                </row>

                <row>
                  <entry><emphasis><emphasis>srcpassword</emphasis>
                  </emphasis></entry>

                  <entry>Optional. The password to use to access the
                  <emphasis>srcdali</emphasis>. If omitted, the General
                  Options <emphasis>password</emphasis> is used.</entry>
                </row>
              </tbody>
            </tgroup>
          </informaltable>

          <para>Example:</para>

          <programlisting>dfuplus action=add srcxml=flattimezones.xml dstname=flattimezones.txt</programlisting>

          <para></para>
        </sect3>

        <sect3>
          <title>Addsuper Operations:</title>

          <para>The <emphasis role="bold">addsuper</emphasis> operation adds
          subfiles to an existing superfile (see the <emphasis>SuperFile
          Management </emphasis>section of the <emphasis>Service Library
          Reference</emphasis>).</para>

          <para>These <emphasis>options </emphasis>are used by the <emphasis
          role="bold">addsuper</emphasis>
          <emphasis>operation</emphasis>:</para>

          <informaltable colsep="0" frame="none" rowsep="0">
            <tgroup cols="2">
              <colspec align="left" colwidth="122.40pt" />

              <colspec />

              <tbody>
                <row>
                  <entry><emphasis><emphasis><emphasis>superfile</emphasis>
                  </emphasis></emphasis></entry>

                  <entry>The logical name of the superfile.</entry>
                </row>

                <row>
                  <entry><emphasis><emphasis>subfiles</emphasis></emphasis></entry>

                  <entry>A comma-delimited list of the logical names of files
                  to add to the superfile. There must be no spaces between the
                  names.</entry>
                </row>

                <row>
                  <entry><emphasis>before</emphasis></entry>

                  <entry>Optional. The logical name of the subfile to follow
                  the added <emphasis>subfiles</emphasis>. If omitted, the
                  <emphasis>subfiles</emphasis> are added to the end.</entry>
                </row>
              </tbody>
            </tgroup>
          </informaltable>

          <para>Example:</para>

          <programlisting>dfuplus action=addsuper superfile=mysuper subfiles=file1,file2</programlisting>
        </sect3>

        <sect3>
          <title>Removesuper Operations:</title>

          <para>The <emphasis role="bold">removesuper</emphasis> operation
          removes subfiles to an existing superfile (see the
          <emphasis>SuperFile Management </emphasis>section of the
          <emphasis>Service Library Reference</emphasis>).</para>

          <para>These <emphasis>options </emphasis>are used by the <emphasis
          role="bold">removesuper</emphasis>
          <emphasis>operation</emphasis>:</para>

          <informaltable colsep="0" frame="none" rowsep="0">
            <tgroup cols="2">
              <colspec align="left" colwidth="122.40pt" />

              <colspec />

              <tbody>
                <row>
                  <entry><emphasis><emphasis><emphasis>superfile</emphasis>
                  </emphasis></emphasis></entry>

                  <entry>The logical name of the superfile.</entry>
                </row>

                <row>
                  <entry><emphasis><emphasis>subfiles</emphasis></emphasis></entry>

                  <entry>Optional. A comma-delimited list of the logical names
                  of files to remove from the superfile. There must be no
                  spaces between the names. If omitted, all files are removed
                  from the superfile.</entry>
                </row>

                <row>
                  <entry><emphasis>delete</emphasis></entry>

                  <entry>Optional. A boolean flag (1 | 0) indicating whether
                  to physically delete the <emphasis>subfiles</emphasis> in
                  addition to removing them from the superfile. If omitted,
                  the default is 1—physically delete.</entry>
                </row>
              </tbody>
            </tgroup>
          </informaltable>

          <para>Example:</para>

          <programlisting>dfuplus action=removesuper superfile=mysuper subfiles=file1,file2</programlisting>
        </sect3>

        <sect3>
          <title>Listsuper Operations:</title>

          <para>The <emphasis role="bold">listsuper</emphasis> operation lists
          the subfiles in an existing superfile (see the <emphasis>SuperFile
          Management </emphasis>section of the <emphasis>Service Library
          Reference</emphasis>).</para>

          <para>These <emphasis>options </emphasis>are used by the <emphasis
          role="bold">listsuper</emphasis>
          <emphasis>operation</emphasis>:</para>

          <para><informaltable colsep="0" frame="none" rowsep="0">
              <tgroup cols="2">
                <colspec colwidth="122.40pt" />

                <colspec />

                <tbody>
                  <row>
                    <entry><emphasis><emphasis><emphasis>superfile</emphasis>
                    </emphasis></emphasis></entry>

                    <entry>The logical name of the superfile.</entry>
                  </row>
                </tbody>
              </tgroup>
            </informaltable></para>

          <para>Example:</para>

          <programlisting>dfuplus action=listsuper superfile=mysuper</programlisting>
        </sect3>

        <sect3>
          <title>Status Operations:</title>

          <para>The <emphasis role="bold">status</emphasis> operation returns
          the current operational status of a workunit.</para>

          <para>These <emphasis>options </emphasis>are used by the <emphasis
          role="bold">status</emphasis> <emphasis>operation</emphasis>:</para>

          <para><informaltable colsep="0" frame="none" rowsep="0">
              <tgroup cols="2">
                <colspec colwidth="122.40pt" />

                <colspec />

                <tbody>
                  <row>
                    <entry><emphasis><emphasis><emphasis>wuid</emphasis>
                    </emphasis></emphasis></entry>

                    <entry>The workunit identifier of the workunit.</entry>
                  </row>
                </tbody>
              </tgroup>
            </informaltable>Example:</para>

          <programlisting>dfuplus action=status wuid=W20050309-093020</programlisting>

          <para></para>
        </sect3>

        <sect3>
          <title>Abort Operations:</title>

          <para>The <emphasis role="bold">abort</emphasis> operation aborts
          execution of a workunit.</para>

          <para>These <emphasis>options </emphasis>are used by the <emphasis
          role="bold">abort</emphasis> <emphasis>operation</emphasis>:</para>

          <para><informaltable colsep="0" frame="none" rowsep="0">
              <tgroup cols="2">
                <colspec colwidth="122.40pt" />

                <colspec />

                <tbody>
                  <row>
                    <entry><emphasis><emphasis><emphasis>wuid</emphasis>
                    </emphasis></emphasis></entry>

                    <entry>The workunit identifier of the workunit.</entry>
                  </row>
                </tbody>
              </tgroup>
            </informaltable></para>

          <para>Example:</para>

          <programlisting>dfuplus action=abort wuid=W20050309-093020</programlisting>

          <para></para>
        </sect3>

        <sect3>
          <title>Resubmit Operations:</title>

          <para>The <emphasis role="bold">resubmit</emphasis> operation
          re-submits a workunit.</para>

          <para>These <emphasis>options </emphasis>are used by the <emphasis
          role="bold">resubmit</emphasis>
          <emphasis>operation</emphasis>:</para>

          <para><informaltable colsep="0" frame="none" rowsep="0">
              <tgroup cols="2">
                <colspec colwidth="122.40pt" />

                <colspec />

                <tbody>
                  <row>
                    <entry><emphasis><emphasis><emphasis>wuid</emphasis>
                    </emphasis></emphasis></entry>

                    <entry>The workunit identifier of the workunit.</entry>
                  </row>
                </tbody>
              </tgroup>
            </informaltable></para>

          <para>Example:</para>

          <programlisting>dfuplus action=resubmit wuid=W20050309-093020</programlisting>

          <para></para>
        </sect3>

        <sect3>
          <title>Savexml Operations:</title>

          <para>The <emphasis role="bold">savexml</emphasis> operation saves
          the logical file map to an XML file.</para>

          <para>These <emphasis>options </emphasis>are used by the <emphasis
          role="bold">savexml</emphasis>
          <emphasis>operation</emphasis>:</para>

          <para><emphasis>srcname</emphasis> The logical name of the source
          file.</para>

          <para></para>

          <informaltable colsep="0" frame="none" rowsep="0">
            <tgroup cols="2">
              <colspec colwidth="122.40pt" />

              <colspec />

              <tbody>
                <row>
                  <entry><emphasis>srcname</emphasis></entry>

                  <entry>The logical name of the source file.</entry>
                </row>

                <row>
                  <entry><emphasis><emphasis>dstxml</emphasis>
                  </emphasis></entry>

                  <entry>Optional. The logical name of the destination XML
                  file. If omitted, the XML result is sent to stdout.</entry>
                </row>
              </tbody>
            </tgroup>
          </informaltable>

          <para>Example:</para>

          <programlisting>dfuplus action=savexml srcname=RTTEMP::timezones.txt
          dstxml=flattimezones.xml
    // this results in the following XML file:
    &lt;File directory="c:\thordata\rttemp"
          group="thor"
          modified="2004-06-18T14:17:16"
          name="timezones.txt"
          numparts="3"
          partmask="timezones.txt._$P$_of_$N$"&gt;
    &lt;Attr job="timezones.txt"
          owner="rtaylor"
          recordSize="155"
          replicated="1"
          size="51305"
          workunit="D20040618-101716"/&gt;
    &lt;OrigName&gt;rttemp::timezones.txt&lt;/OrigName&gt;
    &lt;Part modified="2004-06-18T14:17:18"
          node="10.150.50.15"
          num="1"
          size="17050"/&gt;
    &lt;Part modified="2004-06-18T14:17:17"
          node="10.150.50.18"
          num="2"
          size="17050"/&gt;
    &lt;Part modified="2004-06-18T14:17:17"
          node="10.150.50.16"
          num="3"
          size="17205"/&gt;
    &lt;/File&gt;</programlisting>
        </sect3>

        <sect3>
          <title>Monitor Operations:</title>

          <para>The <emphasis role="bold">monitor</emphasis> operation
          initiates a DFU workunit to monitor the appearance of a physical or
          logical file and trigger an event when that file appears.</para>

          <para>These <emphasis>options </emphasis>are used by the <emphasis
          role="bold">monitor</emphasis>
          <emphasis>operation</emphasis>:</para>

          <para><informaltable colsep="0" frame="none" rowsep="0">
              <tgroup cols="2">
                <colspec colwidth="85.55pt" />

                <colspec />

                <tbody>
                  <row>
                    <entry><emphasis>event</emphasis></entry>

                    <entry>The name of the user-defined event to trigger. This
                    is used as the first parameter of the ECL EVENT
                    function.</entry>
                  </row>

                  <row>
                    <entry><emphasis>lfn</emphasis></entry>

                    <entry>Optional. The name of the logical file in the DFU
                    to look for. Using this option precludes using the
                    <emphasis>ip</emphasis>, <emphasis>file</emphasis>, and
                    <emphasis>sub</emphasis> options.</entry>
                  </row>

                  <row>
                    <entry><emphasis>ip</emphasis></entry>

                    <entry>Optional. The IP address or name of the server on
                    which the physical file will reside. This may be omitted
                    if the <emphasis>file</emphasis> option contains a full
                    URL.</entry>
                  </row>

                  <row>
                    <entry><emphasis>file</emphasis></entry>

                    <entry>Optional. The fully qualified path of the physical
                    file to look for. This may contain wildcard characters (*
                    and ?).</entry>
                  </row>

                  <row>
                    <entry><emphasis>sub</emphasis></entry>

                    <entry>Optional. Specifies searching subdirectories for
                    the physical file if the <emphasis>file</emphasis> option
                    contains wildcard characters (* and ?).</entry>
                  </row>

                  <row>
                    <entry><emphasis>shotlimit</emphasis></entry>

                    <entry>Optional. The number of arrival events to generate
                    before marking the DFU workunit as complete. A value of
                    negative one (-1) indicates continuing until the workunit
                    is manually aborted. If omitted, the default value is one
                    (1).</entry>
                  </row>
                </tbody>
              </tgroup>
            </informaltable></para>

          <para><emphasis role="bold">Note the following caveats and
          restrictions:</emphasis></para>

          <para>1) If a matching file already exists when the DFU Monitoring
          job is started, that file will <emphasis
          role="underline">not</emphasis> generate an event. It will only
          generate an event once the file has been deleted and
          recreated.</para>

          <para>2) If a file is created and then deleted (or deleted then
          re-created) between polling intervals, it will not be seen by the
          monitor and will not trigger an event.</para>

          <para>3) Events are only generated on the polling interval.</para>

          <para>4) Note that the <emphasis>event</emphasis> is generated if
          the physical file has been created since the last polling interval.
          Therefore, the <emphasis>event</emphasis> may occur before the file
          is closed and the data all written. To ensure the file is not
          subsequently read before it is complete you should use a technique
          that will preclude this possibillity, such as using a separate
          'flag' file instead of the file, itself or renaming the file once it
          has been created and completely written.</para>

          <para>5) The EVENT function’s subtype parameter (its 2nd parameter)
          when monitoring physical files is the full URL of the file, with an
          absolute IP rather than DNS/netbios name of the file. This parameter
          cannot be retrieved but can only be used for matching a particular
          value in this.</para>

          <para>Example:</para>

          <programlisting>dfuplus action=monitor event=MyEvent ip=edata10 file=/dz/arr.txt
dfuplus action=monitor event=MyEvent ip=10.150.10.75
            file=c:\dz\* shotlimit=-1 sub=1
dfuplus action=monitor event=MyEvent file=//10.15.13.21/dz/*.txt
dfuplus action=monitor event=MyEvent lfn=RTTEMP::OUT::MyFile</programlisting>
        </sect3>
      </sect2>
    </sect1>
  </chapter>
</book>