Big-Data-HPC-Platform/docs/ServiceLibraryReference.xml

<?xml version="1.0"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<book lang="en_US">
  <bookinfo>
    <author>
      <surname>Greg Panagiotatos</surname>
    </author>

    <date>2010-12-17</date>
  </bookinfo>

  <chapter id="Service_Library_Reference">
    <title>Service Library Reference</title>

    <sect1 id="String_Handling">
      <title><emphasis>String Handling</emphasis></title>

      <para></para>

      <para></para>

      <sect2 id="CleanSpaces">
        <title><emphasis>CleanSpaces</emphasis></title>

        <para><emphasis role="bold">StringLib.StringCleanSpaces(</emphasis><emphasis>source</emphasis><emphasis role="bold">)</emphasis><emphasis role="bold">UnicodeLib.UnicodeCleanSpaces(</emphasis><emphasis>source</emphasis><emphasis role="bold">)</emphasis></para>

        <para><emphasis>source</emphasis> A string containing the data to
        clean.</para>

        <para>Return:<emphasis> </emphasis>CleanSpaces returns either a STRING
        or UNICODE value, as appropriate.</para>

        <para>All variations of the <emphasis role="bold">CleanSpaces
        </emphasis>function return the <emphasis>source</emphasis> string with
        all instances of multiple adjacent space characters (2 or more spaces
        together, or a tab character) reduced to a single space character. It
        also trims off all leading and trailing spaces.</para>

        <para>Example:</para>

        <programlisting>A := StringLib.StringCleanSpaces('ABCDE  ABCDE');
  //A contains 'ABCDE ABCDE'
UNICODE C := UnicodeLib.UnicodeCleanSpaces(U'ABCDE ABCDE');   //C contains U'ABCDE ABCDE'
</programlisting>

        <para></para>
      </sect2>

      <sect2 id="CompareAtStrength">
        <title><emphasis>CompareAtStrength</emphasis></title>

        <para><emphasis role="bold">UnicodeLib.UnicodeCompareAtStrength(</emphasis><emphasis>source1,
        source2, strength</emphasis><emphasis role="bold">)</emphasis><emphasis role="bold">UnicodeLib.UnicodeLocaleCompareAtStrength(</emphasis><emphasis>source1,source2,locale,strength</emphasis><emphasis role="bold">)</emphasis></para>

        <para><emphasis>source1</emphasis> A string containing the data to
        compare.</para>

        <para><emphasis>source2</emphasis> A string containing the data to
        compare.</para>

        <para><emphasis>strength</emphasis> An integer value indicating how to
        compare. Valid values are:</para>

        <para>1 ignores accents and case, differentiating only between
        letters.</para>

        <para>2 ignores case but differentiates between accents.</para>

        <para>3 differentiates between accents and case but ignores e.g.
        differences between Hiragana and Katakana</para>

        <para>4 differentiates between accents and case and e.g.
        Hiragana/Katakana, but ignores e.g. Hebrew cantellation marks</para>

        <para>5 differentiates between all strings whose canonically
        decomposed forms (NFD—Normalization Form D) are non-identical</para>

        <para><emphasis>locale</emphasis> A null-terminated string containing
        the language and country code to use to determine correct sort order
        and other operations.</para>

        <para>Return:<emphasis> </emphasis>CompareAtStrength returns an
        INTEGER value.</para>

        <para>The <emphasis role="bold">CompareAtStrength </emphasis>functions
        return zero (0) if the <emphasis>source1</emphasis> and
        <emphasis>source2</emphasis> strings contain the same data, ignoring
        any differences in the case of the letters. These functions return
        negative one (-1) if <emphasis>source1</emphasis> &lt;
        <emphasis>source2</emphasis> or positive one (1) if
        <emphasis>source1</emphasis> &gt; <emphasis>source2</emphasis>.</para>

        <para>Example:</para>

        <programlisting>base := u'caf\u00E9';   // U+00E9 is lowercase e with acute
prim := u'coffee shop'; // 1st difference, different letters
seco := u'cafe';        // 2nd difference, accents (no acute)
tert := u'Caf\u00C9';   // 3rd, caps (U+00C9 is u/c E + acute)

A := unicodeLib.UnicodeCompareAtStrength(base, prim, 1) != 0;
 // base and prim differ at all strengths

A := unicodeLib.UnicodeCompareAtStrength(base, seco, 1) = 0;
 // base and seco same at strength 1 (differ only at strength 2)

A := unicodeLib.UnicodeCompareAtStrength(base, tert, 1) = 0;
  // base and tert same at strength 1 (differ only at strength 3)
    
A := unicodeLib.UnicodeCompareAtStrength(base, seco, 2) != 0;
 // base and seco differ at strength 2

A := unicodeLib.UnicodeCompareAtStrength(base, tert, 2) = 0;
  // base and tert same at strength 2 (differ only at strength 3)
    
A := unicodeLib.UnicodeCompareAtStrength(base, seco, 3) != 0;
 // base and seco differ at strength 2
    
A := unicodeLib.UnicodeCompareAtStrength(base, tert, 3) != 0;
 // base and tert differ at strength 3
</programlisting>
      </sect2>

      <sect2 id="CompareIgnoreCase">
        <title><emphasis>CompareIgnoreCase</emphasis></title>

        <para><emphasis role="bold">StringLib.StringCompareIgnoreCase(</emphasis><emphasis>source1,source2</emphasis><emphasis role="bold">)</emphasis><emphasis role="bold">UnicodeLib.UnicodeCompareIgnoreCase(</emphasis><emphasis>source1,source2</emphasis><emphasis role="bold">)</emphasis><emphasis role="bold">UnicodeLib.UnicodeLocaleCompareIgnoreCase(</emphasis><emphasis>source1,source2,
        locale</emphasis><emphasis role="bold">)</emphasis></para>

        <para><emphasis>source1</emphasis> A string containing the data to
        compare.</para>

        <para><emphasis>source2</emphasis> A string containing the data to
        compare.</para>

        <para><emphasis>locale</emphasis> A null-terminated string containing
        the language and country code to use to determine correct sort order
        and other operations.</para>

        <para>Return:<emphasis> </emphasis>CompareIgnoreCase returns an
        INTEGER value.</para>

        <para>The <emphasis role="bold">CompareIgnoreCase </emphasis>functions
        return zero (0) if the <emphasis>source1</emphasis> and
        <emphasis>source2</emphasis> strings contain the same data, ignoring
        any differences in the case of the letters. These functions return
        negative one (-1) if <emphasis>source1</emphasis> &lt;
        <emphasis>source2</emphasis> or positive one (1) if
        <emphasis>source1</emphasis> &gt; <emphasis>source2</emphasis>.</para>

        <para>Example:</para>

        <programlisting>A := StringLib.StringCompareIgnoreCase('ABCDE','abcde');
 //A contains 0 -- they “match”

B := StringLib.StringCompareIgnoreCase('ABCDE','edcba');
 //B contains -1 -- they do not “match”
</programlisting>
      </sect2>

      <sect2 id="Contains">
        <title><emphasis>Contains</emphasis></title>

        <para><emphasis role="bold">StringLib.StringContains(</emphasis><emphasis>source,
        pattern, nocase</emphasis><emphasis role="bold">)</emphasis><emphasis role="bold">UnicodeLib.UnicodeContains(</emphasis><emphasis>source,
        pattern, nocase</emphasis><emphasis role="bold">)</emphasis></para>

        <para><emphasis>source</emphasis> A string containing the data to
        search.</para>

        <para><emphasis>pattern</emphasis> A string containing the characters
        to compare. An empty string ( ‘’ ) always returns true.</para>

        <para><emphasis>nocase</emphasis> A boolean true or false indicating
        whether to ignore the case.</para>

        <para>Return:<emphasis> </emphasis>Contains returns a BOOLEAN
        value.</para>

        <para>The <emphasis role="bold">Contains </emphasis>functions return
        true if all the characters in the <emphasis>pattern</emphasis> appear
        in the <emphasis>source, </emphasis>otherwise they return
        false.</para>

        <para>Example:</para>

        <programlisting>A := stringlib.stringContains(
  'the quick brown fox jumps over the lazy dog',
  'ABCdefghijklmnopqrstuvwxyz', true);

B:= stringlib.stringContains(
 'the speedy ochre vixen leapt over the indolent retriever',
 'abcdefghijklmnopqrstuvwxyz', false);
</programlisting>

        <para></para>
      </sect2>

      <sect2 id="Data2String">
        <title><emphasis>Data2String</emphasis></title>

        <para><emphasis role="bold">StringLib.Data2String(</emphasis><emphasis>source</emphasis><emphasis role="bold">)</emphasis></para>

        <para><emphasis>source</emphasis> A DATA string to convert.</para>

        <para>Return:<emphasis> </emphasis>Data2String returns a STRING
        value.</para>

        <para>The <emphasis role="bold">Data2String </emphasis>function
        returns a string containing the hexadeciomal characters from the
        <emphasis>source</emphasis> DATA value.</para>

        <para>Example:</para>

        <programlisting>DATA2 CrLf := x’0A0D’; //2-bytes of hex
STRING4 CrLfString := StringLib.Data2String(CrLf); //results in a ‘0A0D’ 4-byte string
</programlisting>

        <para></para>
      </sect2>

      <sect2 id="EditDistance">
        <title><emphasis>EditDistance</emphasis></title>

        <para><emphasis role="bold">StringLib.EditDistance(</emphasis><emphasis>string1,
        string2</emphasis><emphasis role="bold">)</emphasis></para>

        <para><emphasis>string1</emphasis> The first of a pair of strings to
        compare.</para>

        <para><emphasis>string2</emphasis> The second of a pair of strings to
        compare.</para>

        <para>Return:<emphasis> </emphasis>EditDistance returns an UNSIGNED4
        value.</para>

        <para>The <emphasis role="bold">EditDistance </emphasis>function
        returns a standard Levenshtein distance algorithm score for the edit
        ditance between <emphasis>string1</emphasis> and
        <emphasis>string2</emphasis>. This score i\reflects the minimum number
        of operations needed to transform <emphasis>string1</emphasis> into
        <emphasis>string2</emphasis>.</para>

        <para>.</para>

        <para>Example:</para>

        <programlisting>StringLib.EditDistance('CAT','CAT');  //returns 0
StringLib.EditDistance('CAT','BAT');  //returns 1
StringLib.EditDistance('BAT','BAIT'); //returns 1
StringLib.EditDistance('CAT','BAIT'); //returns 2
</programlisting>
      </sect2>

      <sect2 id="Extract">
        <title><emphasis>Extract</emphasis></title>

        <para><emphasis role="bold">StringLib.StringExtract(</emphasis><emphasis>source,
        instance</emphasis><emphasis role="bold">)</emphasis><emphasis role="bold">UnicodeLib.UnicodeExtract(</emphasis><emphasis>source,
        instance</emphasis><emphasis role="bold">)</emphasis></para>

        <para><emphasis role="bold">source</emphasis><emphasis role="bold"> A
        string containing a comma-delimited list of data.</emphasis></para>

        <para><emphasis>instance </emphasis>An integer specifying the ordinal
        position of the data item within the <emphasis>source</emphasis> to
        return.</para>

        <para>Return:<emphasis> </emphasis>Extract returns either a STRING or
        UNICODE value, as appropriate.</para>

        <para>The <emphasis role="bold">Extract </emphasis>function returns
        the data at the ordinal position specified by the <emphasis>instance
        </emphasis>within the comma-delimited <emphasis>source</emphasis>
        string.</para>

        <para>Example:</para>

        <programlisting>//all these examples result in 'Success'
   
A := IF(StringLib.StringExtract('AB,CD,,G,E',0) = '',
   'Success',
   'Failure -1');
    
B := IF(StringLib.StringExtract('AB,CD,,G,E',1) = 'AB',
   'Success',
   'Failure -2');
    
C := IF(StringLib.StringExtract('AB,CD,,G,E',2) = 'CD',
   'Success',
   'Failure -3');

D := IF(StringLib.StringExtract('AB,CD,,G,E',3) = '',
   'Success',
   'Failure -4');
    
E := IF(StringLib.StringExtract('AB,CD,,G,E',4) = 'G',
   'Success',
   'Failure -5');

F := IF(StringLib.StringExtract('AB,CD,,G,E',5) = 'E',
   'Success',
   'Failure -6');
    
G := IF(StringLib.StringExtract('AB,CD,,G,E',6) = '',
   'Success',
   'Failure -7');
</programlisting>
      </sect2>

      <sect2 id="Filter">
        <title><emphasis>Filter</emphasis></title>

        <para><emphasis role="bold">StringLib.StringFilter(</emphasis><emphasis>source,
        filterstring</emphasis><emphasis role="bold">)</emphasis><emphasis role="bold">UnicodeLib.UnicodeFilter(</emphasis><emphasis>source,
        filterstring</emphasis><emphasis role="bold">)</emphasis></para>

        <para><emphasis>source</emphasis> A string containing the data to
        filter.</para>

        <para><emphasis>filterstring </emphasis>A string containing the
        characters to use as the filter.</para>

        <para>Return:<emphasis> </emphasis>Filter returns a STRING or UNICODE
        value, as appropriate.</para>

        <para>The <emphasis role="bold">StringFilter </emphasis>functions
        return the <emphasis>source</emphasis> string with all the characters
        except those in the <emphasis>filterstring </emphasis>removed.</para>

        <para>Example:</para>

        <programlisting>//all these examples result in 'Success'

A := IF(StringLib.StringFilter('ADCBE', 'BD') = 'DB',
   'Success',
   'Failure - 1');
    
B := IF(StringLib.StringFilter('ADCBEREBD', 'BDG') = 'DBBD',
   'Success',
   'Failure - 2');
    
C := IF(StringLib.StringFilter('ADCBE', '') = '',
   'Success',
   'Failure - 3');
   
D := IF(StringLib.StringFilter('', 'BD') = '',
   'Success',
   'Failure - 4');
    
E := IF(StringLib.StringFilter('ABCDE', 'EDCBA') = 'ABCDE',
   'Success',
   'Failure - 5');
</programlisting>
      </sect2>

      <sect2 id="FilterOut">
        <title><emphasis>FilterOut</emphasis></title>

        <para><emphasis role="bold">StringLib.StringFilterOut(</emphasis><emphasis>source,
        filterstring</emphasis><emphasis role="bold">)</emphasis><emphasis role="bold">UnicodeLib.UnicodeFilterOut(</emphasis><emphasis>source,
        filterstring</emphasis><emphasis role="bold">)</emphasis></para>

        <para><emphasis>source</emphasis> A string containing the data to
        filter.</para>

        <para><emphasis>filterstring </emphasis>A string containing the
        characters to use as the filter.</para>

        <para>Return:<emphasis> </emphasis>FilterOut returns a STRING or
        UNICODE value, as appropriate.</para>

        <para>The <emphasis role="bold">FilterOut </emphasis>functions return
        the <emphasis>source</emphasis> string with all the characters in the
        <emphasis>filterstring </emphasis>removed.</para>

        <para>Example:</para>

        <programlisting>//all these examples result in 'Success'

A := IF(StringLib.StringFilterOut('ABCDE', 'BD') = 'ACE',
   'Success',
   'Failure - 1');
    
B := IF(StringLib.StringFilterOut('ABCDEABCDE', 'BD') = 'ACEACE',
   'Success',
   'Failure - 2');
    
C := IF(StringLib.StringFilterOut('ABCDEABCDE', '') = 'ABCDEABCDE',
   'Success',
   'Failure - 3');
    
D := IF(StringLib.StringFilterOut('', 'BD') = '',
   'Success',
   'Failure - 4');
</programlisting>

        <para></para>
      </sect2>

      <sect2 id="Find">
        <title><emphasis>Find</emphasis></title>

        <para><emphasis role="bold">StringLib.StringFind(</emphasis><emphasis>source, target,
        instance</emphasis><emphasis role="bold">)</emphasis><emphasis role="bold">StringLib.EbcdicStringFind(</emphasis><emphasis>source,
        target, instance</emphasis><emphasis role="bold">)</emphasis><emphasis role="bold">UnicodeLib.UnicodeFind(</emphasis><emphasis>source,
        target, instance</emphasis><emphasis role="bold">)</emphasis><emphasis role="bold">UnicodeLib.UnicodeLocaleFind(</emphasis><emphasis>source,
        target, instance, locale</emphasis><emphasis role="bold">)</emphasis></para>

        <para><emphasis>source</emphasis> A string containing the data to
        search.</para>

        <para><emphasis>target </emphasis>A string containing the substring to
        search for.</para>

        <para><emphasis>instance </emphasis>An integer specifying which
        occurrence of the <emphasis>target</emphasis> to find.</para>

        <para><emphasis>locale</emphasis> A null-terminated string containing
        the language and country code to use to determine correct sort order
        and other operations.</para>

        <para>Return:<emphasis> </emphasis>Find returns an INTEGER
        value.</para>

        <para>The <emphasis role="bold">Find </emphasis>functions return the
        beginning index position within the <emphasis>source</emphasis> string
        of the specified <emphasis>instance</emphasis> of the <emphasis>target
        </emphasis>string. If the <emphasis>target</emphasis> is not found or
        the specified <emphasis>instance</emphasis> is greater than the number
        of occurrences of the <emphasis>target</emphasis> in the
        <emphasis>source</emphasis>, StringFind returns zero (0).</para>

        <para>Example:</para>

        <programlisting>A := IF(StringLib.StringFind('ABCDE', 'BC',1) = 2,
   'Success',
   'Failure - 1');  //success
    
B := IF(StringLib.StringFind('ABCDEABCDE', 'BC', 2) = 7,
   'Success',
   'Failure - 2');  //success
    
C := IF(StringLib.StringFind('ABCDEABCDE', '') = 0,
   'Success',
   'Failure - 3');  //syntax error, missing 3rd parameter
    
D := IF(StringLib.StringFind('', 'BD', 1) = 0,
   'Success',
   'Failure - 4');  //success
</programlisting>
      </sect2>

      <sect2 id="StringUnboundedUnsafeFind">
        <title><emphasis>StringUnboundedUnsafeFind</emphasis></title>

        <para><emphasis role="bold">StringLib.StringUnboundedUnsafeFind(</emphasis><emphasis>source,
        target</emphasis><emphasis role="bold">)</emphasis><emphasis role="bold">StringLib.EbcdicStringUnboundedUnsafeFind(</emphasis><emphasis>source,
        target</emphasis><emphasis role="bold">)</emphasis></para>

        <para><emphasis>source</emphasis> A string containing the data to
        search.</para>

        <para><emphasis>target </emphasis>A string containing the substring to
        search for.</para>

        <para>Return:<emphasis> </emphasis>Find2 returns an INTEGER
        value.</para>

        <para>The <emphasis role="bold">StringUnboundedUnsafeFind
        </emphasis>functions return the beginning index position within the
        <emphasis>source</emphasis> string of the first instance of the
        <emphasis>target </emphasis>string. If the <emphasis>target</emphasis>
        string is not in the <emphasis>source</emphasis> string (or somewhere
        beyond), it creates a runtime exception.</para>

        <para><emphasis role="bold">The StringUnboundedUnsafeFind functions
        scan the </emphasis><emphasis role="bold">source</emphasis><emphasis role="bold"> string AND BEYOND until it finds what it is looking
        for.</emphasis> It is designed for use in variable length string input
        routines. Essentially you can pass it a <emphasis>source</emphasis>
        that is of length one and it will keep reading beyond the end of the
        <emphasis>source</emphasis> to find the <emphasis>target</emphasis>
        string and will tell you how far it had to go. Typically, this be used
        would search for an end-of-string delimiter to determine how many
        bytes of variable-length data there are. This can cause problems if
        the <emphasis>target</emphasis> string does not exist.</para>

        <para>Example:</para>

        <programlisting>A := IF(StringLib.StringUnboundedUnsafeFind('ABCDE', 'BC') = 2,
   'Success',
   'Failure - 1');  //success
    
B := IF(StringLib.StringFind2('ABCDEABCDE', 'BC') = 7,
   'Success',
   'Failure - 2');  //failure
    
C := IF(StringLib.StringFind2('ABCDEABCDE', '') = 0,
   'Success',
   'Failure - 3');  //failure
    
D := IF(StringLib.StringFind2('', 'BD') = 0,
   'Success',
   'Failure - 4');  //runtime exception
</programlisting>
      </sect2>

      <sect2 id="FindCount">
        <title><emphasis>FindCount</emphasis></title>

        <para><emphasis role="bold">StringLib.StringFindCount(</emphasis><emphasis>source,
        target</emphasis><emphasis role="bold">)</emphasis></para>

        <para><emphasis>source</emphasis> A string containing the data to
        search.</para>

        <para><emphasis>target </emphasis>A string containing the substring to
        search for.</para>

        <para>Return:<emphasis> </emphasis>StringFindCount returns an INTEGER
        value.</para>

        <para>The <emphasis role="bold">FindCount </emphasis>function returns
        the number of non-overlapping instances of the <emphasis>target
        </emphasis>string within the <emphasis>source</emphasis>
        string.</para>

        <para>Example:</para>

        <programlisting>A := IF(StringLib.StringFindCount('ABCDE', 'BC') = 1,
   'Success',
   'Failure - 1');  //success
    
B := IF(StringLib.StringFindCount('ABCDEABCDE', 'BC') = 2,
   'Success',
   'Failure - 2');  //failure
</programlisting>
      </sect2>

      <sect2 id="FindAtStrength">
        <title><emphasis>FindAtStrength</emphasis></title>

        <para><emphasis role="bold">UnicodeLib.UnicodeLocaleFindAtStrength(</emphasis><emphasis>source,target,instance,locale,strength</emphasis><emphasis role="bold">)</emphasis></para>

        <para><emphasis>source</emphasis> A string containing the data to
        search.</para>

        <para><emphasis>target </emphasis>A string containing the substring to
        search for.</para>

        <para><emphasis>instance </emphasis>An integer specifying which
        occurrence of the <emphasis>target</emphasis> to find.</para>

        <para><emphasis>locale</emphasis> A null-terminated string containing
        the language and country code to use to determine correct sort order
        and other operations.</para>

        <para><emphasis>strength</emphasis> An integer value indicating how to
        compare. Valid values are:</para>

        <para>1 ignores accents and case, differentiating only between
        letters</para>

        <para>2 ignores case but differentiates between accents.</para>

        <para>3 differentiates between accents and case but ignores e.g.
        differences between Hiragana and Katakana</para>

        <para>4 differentiates between accents and case and e.g.
        Hiragana/Katakana, but ignores e.g. Hebrew cantellation marks</para>

        <para>5 differentiates between all strings whose canonically
        decomposed forms (NFD—Normalization Form D) are non-identical</para>

        <para>Return:<emphasis> </emphasis>FindAtStrength returns an INTEGER
        value.</para>

        <para>The <emphasis role="bold">FindAtStrength </emphasis>function
        returns the beginning index position within the
        <emphasis>source</emphasis> string of the specified
        <emphasis>instance</emphasis> of the <emphasis>target
        </emphasis>string. If the <emphasis>target</emphasis> is not found or
        the specified <emphasis>instance</emphasis> is greater than the number
        of occurrences of the <emphasis>target</emphasis> in the
        <emphasis>source</emphasis>, StringFind returns zero (0).</para>

        <para>Example:</para>

        <programlisting>base := u'caf\u00E9';   // U+00E9 is lowercase e with acute
prim := u'coffee shop'; // 1st difference, different letters
seco := u'cafe';      // 2nd difference, accents (no acute)
tert := u'Caf\u00C9';   // 3rd, caps (U+00C9 is u/c E + acute)
search := seco + tert + base;
unicodelib.UnicodeLocaleFindAtStrength(search, base, 1, 'fr', 1) = 1;
 // at strength 1, base matches seco (only secondary diffs)
unicodelib.UnicodeLocaleFindAtStrength(search, base, 1, 'fr', 2) = 5;
 // at strength 2, base matches tert (only tertiary diffs)
unicodelib.UnicodeLocaleFindAtStrength(search, base, 1, 'fr', 3) = 9;
 // at strength 3, base doesn't match either seco or tert
unicodelib.UnicodeLocaleFindAtStrength(u'le caf\u00E9 vert',
         u'cafe', 1, 'fr', 2) = 4;
  // however, an accent on the source,
unicodelib.UnicodeLocaleFindAtStrength(u'le caf\u00E9 vert',
         u'cafe', 1, 'fr', 3) = 4;
 // rather than on the pattern,
unicodelib.UnicodeLocaleFindAtStrength(u'le caf\u00E9 vert',
         u'cafe', 1, 'fr', 4) = 4;
 // is ignored at strengths up to 4,
unicodelib.UnicodeLocaleFindAtStrength(u'le caf\u00E9 vert',
         u'cafe', 1, 'fr', 5) = 0;
 // and only counts at strength 5
</programlisting>
      </sect2>

      <sect2 id="FindAtStrengthReplace">
        <title><emphasis>FindAtStrengthReplace</emphasis></title>

        <para><emphasis role="bold">UnicodeLib.UnicodeLocaleFindAtStrengthReplace(</emphasis><emphasis>source,
        target,</emphasis><emphasis> replacement, locale, strength
        </emphasis><emphasis role="bold">)</emphasis></para>

        <para><emphasis>source</emphasis> A string containing the data to
        search.</para>

        <para><emphasis>target </emphasis>A string containing the substring to
        search for.</para>

        <para><emphasis>replacement </emphasis>A string containing the
        replacement data.</para>

        <para><emphasis>locale</emphasis> A null-terminated string containing
        the language and country code to use to determine correct sort order
        and other operations.</para>

        <para><emphasis>strength</emphasis> An integer value indicating how to
        compare. Valid values are:</para>

        <para>1 ignores accents and case, differentiating only between
        letters.</para>

        <para>2 ignores case but differentiates between accents.</para>

        <para>3 differentiates between accents and case but ignores e.g.
        differences between Hiragana and Katakana</para>

        <para>4 differentiates between accents and case and e.g.
        Hiragana/Katakana, but ignores e.g. Hebrew cantellation marks</para>

        <para>5 differentiates between all strings whose canonically
        decomposed forms (NFD—Normalization Form D) are non-identical</para>

        <para>Return:<emphasis> </emphasis>FindAtStrengthReplace returns a
        UNICODE value.</para>

        <para>The <emphasis role="bold">FindAtStrengthReplace
        </emphasis>functions return the <emphasis>source</emphasis> string
        with the <emphasis>replacement</emphasis> string substituted for all
        instances of the <emphasis>target </emphasis>string. If the
        <emphasis>target</emphasis> string is not in the
        <emphasis>source</emphasis> string, it returns the
        <emphasis>source</emphasis> string unaltered.</para>

        <para>Example:</para>

        <programlisting>unicodelib.UnicodeLocaleFindAtStrengthReplace(u'e\u00E8E\u00C9eE',
   u'e\u00E9', u'xyz', 'fr', 1) = u'xyzxyzxyz';
unicodelib.UnicodeLocaleFindAtStrengthReplace(u'e\u00E8E\u00C9eE',
   u'e\u00E9', u'xyz', 'fr', 2) = u'e\u00E8xyzeE';
unicodelib.UnicodeLocaleFindAtStrengthReplace(u'e\u00E8E\u00C9eE',
   u'e\u00E9', u'xyz', 'fr', 3) = u'e\u00E8E\u00C9eE';
</programlisting>

        <para></para>
      </sect2>

      <sect2 id="FindReplace">
        <title><emphasis>FindReplace</emphasis></title>

        <para><emphasis role="bold">StringLib.StringFindReplace(</emphasis><emphasis>source,
        target, replacement</emphasis><emphasis role="bold">)</emphasis><emphasis role="bold">UnicodeLib.UnicodeFindReplace(</emphasis><emphasis>source,
        target, replacement</emphasis><emphasis role="bold">)</emphasis><emphasis role="bold">UnicodeLib.UnicodeLocaleFindReplace(</emphasis><emphasis>source,
        target, replacement, locale </emphasis><emphasis role="bold">)</emphasis></para>

        <para><emphasis>source</emphasis> A string containing the data to
        search.</para>

        <para><emphasis>target </emphasis>A string containing the substring to
        search for.</para>

        <para><emphasis>replacement </emphasis>A string containing the
        replacement data.</para>

        <para><emphasis>locale</emphasis> A null-terminated string containing
        the language and country code to use to determine correct sort order
        and other operations.</para>

        <para>Return:<emphasis> </emphasis>FindReplace returns a STRING or
        UNICODE value, as appropriate.</para>

        <para>The <emphasis role="bold">FindReplace </emphasis>functions
        return the <emphasis>source</emphasis> string with the
        <emphasis>replacement</emphasis> string substituted for all instances
        of the <emphasis>target </emphasis>string . If the
        <emphasis>target</emphasis> string is not in the
        <emphasis>source</emphasis> string, it returns the
        <emphasis>source</emphasis> string unaltered.</para>

        <para>Example:</para>

        <programlisting>A := StringLib.StringFindReplace('ABCDEABCDE', 'BC','XY');
   //A contains ‘AXYDEAXYDE’
A := unicodelib.UnicodeFindReplace(u'abcde', u'a', u'AAAAA');
   //A contains u'AAAAAbcde'
A := unicodelib.UnicodeFindReplace(u'aaaaa', u'aa', u'b');
   //A contains u'bba'
A := unicodelib.UnicodeFindReplace(u'aaaaaa', u'aa', u'b');
   //A contains u'bbb'
A := unicodelib.UnicodeLocaleFindReplace(u'gh\u0131klm', u'hyk', u'XxXxX', 'lt');
   //A contains u'gXxXxXlm'
A := unicodelib.UnicodeLocaleFindReplace(u'gh\u0131klm', u'hyk', u'X', 'lt');
   //A contains u'gXlm'
</programlisting>

 

        <para></para>
      </sect2>

      <sect2 id="StringGetBuildInfo">
        <title><emphasis>GetBuildInfo</emphasis></title>

        <para><emphasis role="bold">StringLib.GetBuildInfo()</emphasis></para>

        <para>Return:<emphasis> </emphasis>GetBuildInfo returns a VARSTRING
        (null-terminated) value.</para>

        <para>The <emphasis role="bold">GetBuildInfo </emphasis>functions
        return a string containing information that specifies the build number
        and date/time stamp of the supercomputer software.</para>

        <para>Example:</para>

        <programlisting>A := StringLib.GetBuildInfo();
</programlisting>
      </sect2>

      <sect2 id="GetDateYYYYMMDD">
        <title><emphasis>GetDateYYYYMMDD</emphasis></title>

        <para><emphasis role="bold">StringLib.GetDateYYYYMMDD()</emphasis></para>

        <para>Return:<emphasis> </emphasis>GetDateYYYYMMDD returns a STRING
        value.</para>

        <para>The <emphasis role="bold">GetDateYYYYMMDD </emphasis>function
        returns a string containing the current date in YYYYMMDD
        format.</para>

        <para>Example:</para>

        <programlisting>A := GetDateYYYYMMDD();
</programlisting>
      </sect2>

      <sect2 id="Repad">
        <title><emphasis>Repad</emphasis></title>

        <para><emphasis role="bold">StringLib.StringRepad(</emphasis><emphasis>source,
        size</emphasis><emphasis role="bold">)</emphasis><emphasis role="bold">UnicodeLib.UnicodeRepad(</emphasis><emphasis>source,
        size</emphasis><emphasis role="bold">)</emphasis></para>

        <para><emphasis>source</emphasis> A string containing the data to
        resize.</para>

        <para><emphasis>size </emphasis>A positive integer containing the
        number of characters in the result string.</para>

        <para>Return:<emphasis> </emphasis>Repad returns a STRING or UNICODE
        value, as appropriate.</para>

        <para>The <emphasis role="bold">Repad </emphasis>functions return the
        <emphasis>source</emphasis> string, stripped of any leading spaces, at
        the specified number of characters. Trailing spaces are added as
        needed to achieve the required <emphasis>size</emphasis>.</para>

        <para>Example:</para>

        <programlisting>// All these examples result in 'Success'
A := IF(StringLib.StringRepad('ABCDE     ', 6) = 'ABCDE ',
   'Success',
   'Failure - 1');

B := IF(StringLib.StringRepad('     ',6) = '      ',
   'Success',
   'Failure - 2');
    
C := IF(StringLib.StringRepad('ABCDE     ',0)='',
   'Success',
   'Failure - 3');

D := IF(StringLib.StringRepad('ABCDE     ', 3) = 'ABC',
   'Success',
   'Failure - 4');
    
E := IF(StringLib.StringRepad('  ABCDE     ', 3) = 'ABC',
   'Success',
   'Failure - 5');
</programlisting>
      </sect2>

      <sect2 id="Reverse">
        <title><emphasis>Reverse</emphasis></title>

        <para><emphasis role="bold">StringLib.StringReverse(</emphasis><emphasis>source</emphasis><emphasis role="bold">)</emphasis><emphasis role="bold">UnicodeLib.UnicodeReverse(</emphasis><emphasis>source</emphasis><emphasis role="bold">)</emphasis></para>

        <para><emphasis>source</emphasis> A string containing the data to
        reverse.</para>

        <para>Return:<emphasis> </emphasis>Reverse returns a STRING or UNICODE
        value, as appropriate.</para>

        <para>The <emphasis role="bold">Reverse </emphasis>functions return
        the <emphasis>source</emphasis> string with all characters in reverse
        order.</para>

        <para>Example:</para>

        <programlisting>A := StringLib.StringReverse('ABCDE'); //A contains 'EDCBA'
</programlisting>
      </sect2>

      <sect2 id="String2Data">
        <title><emphasis role="bold">String2Data</emphasis></title>

        <para><emphasis role="bold">StringLib.String2Data(</emphasis><emphasis>source</emphasis><emphasis role="bold">)</emphasis></para>

        <para><emphasis>source</emphasis> A STRING to convert.</para>

        <para>Return:<emphasis> </emphasis>String2Data returns a DATA
        value.</para>

        <para>The <emphasis role="bold">String2Data </emphasis>function
        returns the DATA value for the hexadecimal characters contained in the
        <emphasis>source</emphasis> STRING. This function is the opposite of
        the Data2String function.</para>

        <para>Example:</para>

        <programlisting>DATA2 CrLf := x’0A0D’; //2-bytes of hex
STRING4 CrLfString := StringLib.Data2String(CrLf);
 //results in a ‘0A0D’ 4-byte string
DATA2 NewCrLf := StringLib.String2Data(CrLfString);
 //and back again
</programlisting>
      </sect2>

      <sect2 id="Substitute">
        <title><emphasis>Substitute</emphasis></title>

        <para><emphasis role="bold">StringLib.StringSubstitute(</emphasis><emphasis>source,
        target, replacement</emphasis><emphasis role="bold">)</emphasis><emphasis role="bold">UnicodeLib.UnicodeSubstitute(</emphasis><emphasis>source,
        target, replacement</emphasis><emphasis role="bold">)</emphasis></para>

        <para><emphasis>source</emphasis> A string containing the data to
        search.</para>

        <para><emphasis>target </emphasis>A string containing the substring to
        search for.</para>

        <para><emphasis>replacement </emphasis>A string containing the
        replacement character.</para>

        <para>Return:<emphasis> </emphasis>Substitute returns a STRING or
        UNICODE value, as appropriate.</para>

        <para>The <emphasis role="bold">Substitute </emphasis>functions return
        the <emphasis>source</emphasis> string with the
        <emphasis>replacement</emphasis> character substituted for all
        characters except those in the <emphasis>target </emphasis>string. If
        the <emphasis>target</emphasis> string is not in the
        <emphasis>source</emphasis> string, it returns the
        <emphasis>source</emphasis> string with all characters replaced by the
        <emphasis>replacement</emphasis> character.</para>

        <para>Example:</para>

        <programlisting>A := unicodelib.UnicodeSubstitute(u'abcdeabcdec', u'cd', u'x');
  //A contains u'xxcdxxxcdxc';
</programlisting>
      </sect2>

      <sect2 id="SubstituteOut">
        <title><emphasis>SubstituteOut</emphasis></title>

        <para><emphasis role="bold">StringLib.StringSubstituteOut(</emphasis><emphasis>source,
        target, replacement</emphasis><emphasis role="bold">)</emphasis><emphasis role="bold">UnicodeLib.UnicodeSubstituteOut(</emphasis><emphasis>source,
        target, replacement</emphasis><emphasis role="bold">)</emphasis></para>

        <para><emphasis>source</emphasis> A string containing the data to
        search.</para>

        <para><emphasis>target </emphasis>A string containing the substring to
        search for.</para>

        <para><emphasis>replacement </emphasis>A string containing the
        replacement character.</para>

        <para>Return:<emphasis> </emphasis>Substitute returns a STRING or
        UNICODE value, as appropriate.</para>

        <para>The <emphasis role="bold">Substitute </emphasis>functions return
        the <emphasis>source</emphasis> string with the
        <emphasis>replacement</emphasis> character substituted for all
        characters that exist in both the <emphasis>source</emphasis> and the
        <emphasis>target </emphasis>string. If no <emphasis>target</emphasis>
        string characters are in the <emphasis>source</emphasis> string, it
        returns the <emphasis>source</emphasis> string unaltered.</para>

        <para>Example:</para>

        <programlisting>A := unicodelib.UnicodeSubstituteOut(u'abcde', u'cd', u'x');
   //A contains u'abxxe';
</programlisting>
      </sect2>

      <sect2 id="ToLowerCase">
        <title><emphasis>ToLowerCase</emphasis></title>

        <para><emphasis role="bold">StringLib.StringToLowerCase(</emphasis><emphasis>source</emphasis><emphasis role="bold">)</emphasis><emphasis role="bold">UnicodeLib.UnicodeToLowerCase(</emphasis><emphasis>source</emphasis><emphasis role="bold">)</emphasis><emphasis role="bold">UnicodeLib.UnicodeLocaleToLowerCase(</emphasis><emphasis>
        source, locale </emphasis><emphasis role="bold">)</emphasis></para>

        <para><emphasis>source</emphasis> A string containing the data to
        change case.</para>

        <para><emphasis>locale</emphasis> A null-terminated string containing
        the language and country code to use to determine correct sort order
        and other operations.</para>

        <para>Return:<emphasis> </emphasis>ToLowerCase returns a STRING or
        UNICODE value, as appropriate.</para>

        <para>The <emphasis role="bold">ToLowerCase </emphasis>functions
        return the <emphasis>source</emphasis> string with all upper case
        characters converted to lower case.</para>

        <para>Example:</para>

        <programlisting>A := StringLib.StringToLowerCase('ABCDE'); //A contains ‘abcde’
</programlisting>
      </sect2>

      <sect2 id="ToProperCase">
        <title><emphasis>ToProperCase</emphasis></title>

        <para><emphasis role="bold">StringLib.StringToProperCase(</emphasis><emphasis>source</emphasis><emphasis role="bold">)</emphasis><emphasis role="bold">UnicodeLib.UnicodeToProperCase(</emphasis><emphasis>source</emphasis><emphasis role="bold">)</emphasis><emphasis role="bold">UnicodeLib.UnicodeLocaleToProperCase(</emphasis><emphasis>
        source, locale </emphasis><emphasis role="bold">)</emphasis></para>

        <para><emphasis>source</emphasis> A string containing the data to
        change case.</para>

        <para><emphasis>locale</emphasis> A null-terminated string containing
        the language and country code to use to determine correct sort order
        and other operations.</para>

        <para>Return:<emphasis> </emphasis>ToProperCase returns a STRING or
        UNICODE value, as appropriate.</para>

        <para>The <emphasis role="bold">ToProperCase </emphasis>functions
        return the <emphasis>source</emphasis> string with the first letter of
        each word in upper case and all other letters left as-is.</para>

        <para>Example:</para>

        <programlisting>A := StringLib.StringToProperCase('ABCDE ABCDE ');
 //A contains ‘Abcde Abcde’
</programlisting>

        <para></para>
      </sect2>

      <sect2 id="ToUpperCase">
        <title><emphasis>ToUpperCase</emphasis></title>

        <para><emphasis role="bold">StringLib.StringToUpperCase(</emphasis><emphasis>source</emphasis><emphasis role="bold">)</emphasis><emphasis role="bold">UnicodeLib.UnicodeToUpperCase(</emphasis><emphasis>source</emphasis><emphasis role="bold">)</emphasis><emphasis role="bold">UnicodeLib.UnicodeLocaleToUpperCase(</emphasis><emphasis>
        source, locale </emphasis><emphasis role="bold">)</emphasis></para>

        <para><emphasis>source</emphasis> A string containing the data to
        change case.</para>

        <para><emphasis>locale</emphasis> A null-terminated string containing
        the language and country code to use to determine correct sort order
        and other operations.</para>

        <para>Return:<emphasis> </emphasis>StringToUpperCase returns a STRING
        value.</para>

        <para>The <emphasis role="bold">ToUpperCase </emphasis>functions
        return the <emphasis>source</emphasis> string with all lower case
        characters converted to upper case.</para>

        <para>Example:</para>

        <programlisting>A := StringLib.StringToUpperCase('abcde');
 //A contains ‘ABCDE’
</programlisting>
      </sect2>

      <sect2 id="WildMatch">
        <title><emphasis>WildMatch</emphasis></title>

        <para><emphasis role="bold">StringLib.StringWildMatch(</emphasis><emphasis>source,
        pattern, nocase</emphasis><emphasis role="bold">)</emphasis><emphasis role="bold">UnicodeLib.UnicodeWildMatch(</emphasis><emphasis>source,
        pattern, nocase</emphasis><emphasis role="bold">)</emphasis></para>

        <para><emphasis>source</emphasis> A string containing the data to
        search.</para>

        <para><emphasis>pattern </emphasis>A string containing the wildcard
        expression to match. Valid wildcards are ? (single character) and *
        (multiple character).</para>

        <para><emphasis>nocase</emphasis> A boolean true or false indicating
        whether to ignore the case.</para>

        <para>Return:<emphasis> </emphasis>WildMatch returns a BOOLEAN
        value.</para>

        <para>The <emphasis role="bold">WildMatch </emphasis>function returns
        TRUE if the <emphasis>pattern</emphasis> matches the
        <emphasis>source</emphasis>.</para>

        <para>The case-insensitive version of UnicodeWildMatch has been
        optimized for speed over accuracy. For accurate case-folding, you
        should either use the UnicodeToUpperCase function explicity and then a
        case-sensitive UnicodeWildMatch, or use REGEXFIND.</para>

        <para>Example:</para>

        <programlisting>stringlib.stringwildmatch('abcdeabcdec', 'a?c*', false) = TRUE;
</programlisting>

        <para></para>
      </sect2>
    </sect1>

    <sect1 id="Data_Handling">
      <title><emphasis>Data Handling</emphasis></title>

      <sect2 id="AddressClean">
        <title><emphasis role="bold">AddressClean</emphasis></title>

        <para><emphasis role="bold">DataLib.AddressClean(</emphasis><emphasis>source1,source2</emphasis><emphasis role="bold">)</emphasis></para>

        <para><emphasis>source1</emphasis> A string containing the street
        address line to clean.</para>

        <para><emphasis>source2</emphasis> A string containing the
        city/state/zip address line to clean.</para>

        <para>Return:<emphasis> </emphasis>AddressClean returns a STRING
        value.</para>

        <para>The <emphasis role="bold">AddressClean </emphasis>function
        returns a 261-byte string in the following format:</para>

        <para><emphasis role="bold">Byte Position Component</emphasis></para>

        <para>1 primary address number</para>

        <para>11 predirectional (N,NE,E,SE,S,SW,W,NW)</para>

        <para>13 street name</para>

        <para>41 suffix (ST, AVE, BLVD, etc.)</para>

        <para>45 postdirectional (N,NE,E,SE,S,SW,W,NW)</para>

        <para>47 secondary address indentifier (APT, STE, etc.)</para>

        <para>57 secondary address range</para>

        <para>65 city</para>

        <para>90 state</para>

        <para>92 5-digit zipcode</para>

        <para>97 zip plus4</para>

        <para>101 country</para>

        <para>141 confidence level (0-9, 0=good 9=bad)</para>

        <para>142 person (if source1 contains a name also)</para>

        <para>Example:</para>

        <programlisting>A := DataLib.AddressClean('4590 NW 23rd Boulevard South Suite 307','Boca Raton, Fl 33434-6332');
/* A contains ‘4590 NW23RD BLVDS STE 307 BOCA RATON FL 33434 6332 1’ */
</programlisting>

        <para></para>
      </sect2>

      <sect2 id="CompanyClean">
        <title><emphasis role="bold">CompanyClean</emphasis></title>

        <para><emphasis role="bold">DataLib.CompanyClean(</emphasis><emphasis>source</emphasis><emphasis role="bold">)</emphasis></para>

        <para><emphasis>source</emphasis> A string containing the company
        name.</para>

        <para>Return:<emphasis> </emphasis>CompanyClean returns a STRING
        value.</para>

        <para>The <emphasis role="bold">CompanyClean </emphasis>function
        returns a 120-byte string in the following format:</para>

        <para><emphasis role="bold">Byte Position Component</emphasis></para>

        <para>1 cleaned primary part of company name</para>

        <para>41 cleaned secondary part of company name</para>

        <para>81 “discardable” words (such as Corp. Inc. Ltd.)</para>

        <para>Example:</para>

        <programlisting>A := DataLib.CompanyClean('The Seisint Data Mgmnt Company, Inc. Ltd');
/* A contains ‘THE SEISINT DATA MGMNT COMPANY INC LTD’ */
</programlisting>
      </sect2>

      <sect2 id="DeDouble">
        <title><emphasis role="bold">DeDouble</emphasis></title>

        <para><emphasis role="bold">DataLib.DeDouble(</emphasis><emphasis>source</emphasis><emphasis role="bold">)</emphasis></para>

        <para><emphasis>source</emphasis> A string to process.</para>

        <para>Return:<emphasis> </emphasis>DeDouble returns a STRING
        value.</para>

        <para>The <emphasis role="bold">DeDouble </emphasis>function returns
        the <emphasis>source</emphasis> string with all instances of multiple
        adjacent characters (2 or more like characters together) reduced to a
        single instance.</para>

        <para>Example:</para>

        <programlisting>A := DataLib.DeDouble('ABBBCCDE'); //A contains 'ABCDE'
</programlisting>
      </sect2>

      <sect2 id="Gender">
        <title><emphasis role="bold">Gender</emphasis></title>

        <para><emphasis role="bold">DataLib.Gender(</emphasis><emphasis>name</emphasis><emphasis role="bold">)</emphasis></para>

        <para><emphasis>name</emphasis> A string containing the forename to
        process.</para>

        <para>Return:<emphasis> </emphasis>Gender returns a STRING1 value,
        .</para>

        <para>The <emphasis role="bold">Gender </emphasis>function returns the
        gender most commonly associated with the <emphasis>name</emphasis>
        string as M (male), F (female), N (neutral), or U (unkown).</para>

        <para>Example:</para>

        <programlisting>A := DataLib.Gender('DAVID');   //A contains 'M'
B := DataLib.Gender('LESLIE');   //B contains 'N'
C := DataLib.Gender('SUSAN');    //C contains 'F'
D := DataLib.Gender('ABCDE');    //D contains 'U'
</programlisting>
      </sect2>

      <sect2 id="LeadMatch">
        <title><emphasis role="bold">LeadMatch</emphasis></title>

        <para><emphasis role="bold">DataLib.LeadMatch(</emphasis><emphasis>source1,source2</emphasis><emphasis role="bold">)</emphasis></para>

        <para><emphasis>source1</emphasis> A string to compare.</para>

        <para><emphasis>source2</emphasis> A string to compare.</para>

        <para>Return:<emphasis> </emphasis>LeadMatch returns an UNSIGNED
        INTEGER value.</para>

        <para>The <emphasis role="bold">LeadMatch </emphasis>function returns
        the number of matching characters at the beginning of the
        <emphasis>source1</emphasis> and <emphasis>source2</emphasis>
        strings.</para>

        <para>Example:</para>

        <programlisting>A := DataLib.LeadMatch('ABCDE','ABXDE'); //A contains 2
</programlisting>
      </sect2>

      <sect2 id="NameClean">
        <title><emphasis role="bold">NameClean</emphasis></title>

        <para><emphasis role="bold">DataLib.NameClean(</emphasis><emphasis>source</emphasis><emphasis role="bold">)</emphasis></para>

        <para><emphasis>source</emphasis> A string containing the name.</para>

        <para>Return:<emphasis> </emphasis>NameClean returns a STRING
        value.</para>

        <para>The <emphasis role="bold">NameClean </emphasis>function returns
        a 142-byte string in the following format:</para>

        <para><emphasis role="bold">Byte Position Component</emphasis></para>

        <para>1 first name</para>

        <para>41 middle name</para>

        <para>81 last name</para>

        <para>121 name prefix (MR, MRS, DR, etc.)</para>

        <para>131 name suffix (JR, SR, III, etc.)</para>

        <para>141 gender code (M, F, N)</para>

        <para>142 confidence flag (0-9, 0=good 9=bad)</para>

        <para>Example:</para>

        <programlisting>A := DataLib.NameClean('Betty Ann Boop');
/*A contains ‘BETTY ANN BOOP F0’ */
B := DataLib.NameClean('Leslie Jean Boop');
/*B contains ‘LESLIE JEAN BOOP N0’ */
</programlisting>
      </sect2>

      <sect2 id="NameMatch">
        <title><emphasis role="bold">NameMatch</emphasis></title>

        <para><emphasis role="bold">DataLib.NameMatch(</emphasis><emphasis>leftfirst,leftmiddle,leftlast,rightfirst,rightmiddle,rightlast</emphasis><emphasis role="bold">)</emphasis></para>

        <para><emphasis>leftfirst</emphasis> A string containing the first
        name.</para>

        <para><emphasis>leftmiddle</emphasis> A string containing the middle
        name.</para>

        <para><emphasis>leftlast</emphasis> A string containing the last
        name.</para>

        <para><emphasis>rightfirst</emphasis> A string containing the first
        name.</para>

        <para><emphasis>rightmiddle</emphasis> A string containing the middle
        name.</para>

        <para><emphasis>rightlast</emphasis> A string containing the last
        name.</para>

        <para>Return:<emphasis> </emphasis>NameMatch returns an UNSIGNED
        INTEGER4 value.</para>

        <para>The <emphasis role="bold">NameMatch </emphasis>function returns
        a score indicating how closely the <emphasis>leftfirst, leftmiddle,
        </emphasis>and <emphasis>leftlast </emphasis>name matches the
        <emphasis>rightfirst, rightmiddle, </emphasis>and <emphasis>rightlast
        </emphasis>name. The lower the score, the closer the match, with zero
        (0) indicating a perfect match.</para>

        <para>This function compares the probability of the two incoming names
        referring to the same person versus one of the names referring to
        somebody else (this is not quite the same as them not being a
        reference to the same person). The main distinction is in the area of
        noise. Noise is defined as: a name (first or middle) that is not in
        our tables (we have more than 100K in our tables), or a last name we
        have never encountered with repeating characters or too few vowels,
        etc. Noise causes that portion of the name to be underwieghted in the
        final scoring.</para>

        <para>Example:</para>

        <programlisting>A1 := DataLib.NameMatch('RICHARD', 'L', 'TAYLOR',
    'RICHARD', 'L', 'TAYLOR'); //returns 0
A2 := DataLib.NameMatch('RICH', 'L', 'TAYLOR',
    'RICHARD', 'L', 'TAYLOR');  //returns 1
A3 := DataLib.NameMatch('RICH', '', 'TAYLOR',
    'RICHARD', 'L', 'TAYLOR');  //returns 2
A4 := DataLib.NameMatch('ROD', 'L', 'TAYLOR',
    'RICHARD', 'L', 'TAYLOR');  //returns 99
 //this gets a high score because there is a high chance
 // of ROD being a valid name of somebody else
A5 := DataLib.NameMatch('ZXCVBNM', 'L', 'T',
    'RICHARD', 'L', 'TAYLORSKY'); //returns 100
A6 := DataLib.NameMatch('ZXCVBNM', 'B', 'T',
    'RICHARD', 'L', 'TAYLOR'); //returns 199
A7 := DataLib.NameMatch('T', 'L', 'ZXCVBNM',
    'TAYLOR', 'L', 'RICHARD');  //returns 100
</programlisting>
      </sect2>

      <sect2 id="NameSimilar">
        <title><emphasis role="bold">NameSimilar</emphasis></title>

        <para><emphasis role="bold">DataLib.NameSimilar(</emphasis><emphasis>left,right,
        blanks</emphasis><emphasis role="bold">)</emphasis></para>

        <para><emphasis>left</emphasis> A string containing the name.</para>

        <para><emphasis>right</emphasis> A string containing the name.</para>

        <para><emphasis>blanks</emphasis> A boolean value. When TRUE, it
        strips trailing spaces for the comparison between
        <emphasis>left</emphasis> and <emphasis>right</emphasis>.</para>

        <para>Return:<emphasis> </emphasis>NameSimilar returns an UNSIGNED
        INTEGER4 value.</para>

        <para>The <emphasis role="bold">NameSimilar </emphasis>function
        returns a score indicating how closely the <emphasis>left
        </emphasis>name matches the <emphasis>right </emphasis>name. The lower
        the score, the closer the match, with zero (0) indicating a perfect
        match.</para>

        <para>Example:</para>

        <programlisting>A1 := datalib.NameSimilar('Fred Smith','Fred Smith',1); // returns 0
A2 := datalib.NameSimilar('Fred Smith','Fred Smythe',1); // returns 1
A3 := datalib.NameSimilar('Fred Smith','Fred Jones',1); // returns 99
</programlisting>
      </sect2>

      <sect2 id="PositionalMatch">
        <title><emphasis role="bold">PositionalMatch</emphasis></title>

        <para><emphasis role="bold">DataLib.PositionalMatch(</emphasis><emphasis>source1,source2</emphasis><emphasis role="bold">)</emphasis></para>

        <para><emphasis>source1</emphasis> A string to compare.</para>

        <para><emphasis>source2</emphasis> A string to compare.</para>

        <para>Return:<emphasis> </emphasis>PositionalMatch returns an UNSIGNED
        INTEGER value.</para>

        <para>The <emphasis role="bold">PositionalMatch </emphasis>function
        returns the number of matching characters at the exactly the same
        positions within the <emphasis>source1</emphasis> and
        <emphasis>source2</emphasis> strings.</para>

        <para>Example:</para>

        <programlisting>A := DataLib.PositionalMatch(‘ABCDE’,’ABXDE’); //A contains 4
B := DataLib.PositionalMatch(‘ABCDE’,’ABCDE’); //B contains 5
C := DataLib.PositionalMatch(‘ABCDE’,’EABCDE’); //C contains 0
</programlisting>
      </sect2>

      <sect2 id="PreferredFirst">
        <title><emphasis role="bold">PreferredFirst</emphasis></title>

        <para><emphasis role="bold">DataLib.PreferredFirst(</emphasis><emphasis>source</emphasis><emphasis role="bold">)</emphasis></para>

        <para><emphasis>source</emphasis> A string containing the first
        name.</para>

        <para>Return:<emphasis> </emphasis>PreferredFirst returns a STRING
        value.</para>

        <para>The <emphasis role="bold">PreferredFirst </emphasis>function
        returns the preferred first name replacement for the <emphasis>source
        </emphasis>first name given. This is used to replace nicknames with
        their more formal equivalents.</para>

        <para>Example:</para>

        <programlisting>A := DataLib.PreferredFirst('Dick'); //A contains ‘RICHARD’
B := DataLib.PreferredFirst('RICHIE'); //B contains ‘RICHARD’
C := DataLib.PreferredFirst('GWEN'); //C contains ‘GWENDOLYN’
</programlisting>
      </sect2>

      <sect2 id="SlidingMatch">
        <title><emphasis role="bold">SlidingMatch</emphasis></title>

        <para><emphasis role="bold">DataLib.SlidingMatch(</emphasis><emphasis>source1,source2</emphasis><emphasis role="bold">)</emphasis></para>

        <para><emphasis>source1</emphasis> A string to compare.</para>

        <para><emphasis>source2</emphasis> A string to compare.</para>

        <para>Return:<emphasis> </emphasis>SlidingMatch returns an UNSIGNED
        INTEGER value.</para>

        <para>The <emphasis role="bold">SlidingMatch </emphasis>function
        returns the number of characters in <emphasis>source2</emphasis> which
        appear in exactly the same sequence within the
        <emphasis>source1</emphasis> string. There is a penalty imposed if
        subsequent slides happen without at least two matches in
        between.</para>

        <para>Example:</para>

        <programlisting>A := DataLib.SlidingMatch('CBABT','CAT'); //A contains 2 (penalty)
B := DataLib.SlidingMatch('CABT','CAT');  //B contains 3 (no penalty)
C := DataLib.SlidingMatch('CBAT','CAT');  //C contains 3 (no penalty)
D := DataLib.SlidingMatch('CAT','CAT');   //D contains 3
</programlisting>
      </sect2>

      <sect2 id="StrCompare">
        <title><emphasis role="bold">StrCompare</emphasis></title>

        <para><emphasis role="bold">DataLib.StrCompare(</emphasis><emphasis>source1,
        source2</emphasis><emphasis role="bold">)</emphasis></para>

        <para><emphasis>source1</emphasis> A string to compare.</para>

        <para><emphasis>source2</emphasis> A string to compare.</para>

        <para>Return:<emphasis> </emphasis>StrCompare returns an INTEGER
        value.</para>

        <para>The <emphasis role="bold">StrCompare </emphasis>function returns
        a score from 0 to 100 that indicates how closely the
        <emphasis>source1</emphasis> and <emphasis>source2</emphasis> strings
        match.</para>

        <para>Example:</para>

        <programlisting>A := DataLib.StrCompare('ABCDEABCDE','ABCDEABCDE');  //A contains 100
B := DataLib.StrCompare('ABCDEABCDE','ABCDE ABCDE'); //B contains 95
C := DataLib.StrCompare('ABCDEABCDE','WXYZ ABCDE');  //C contains 50
D := DataLib.StrCompare('ABCDEABCDE','WXYZ WXYZ');   //D contains 0
</programlisting>
      </sect2>

      <sect2 id="StringFind">
        <title><emphasis role="bold">StringFind</emphasis></title>

        <para><emphasis role="bold">DataLib.StringFind(</emphasis><emphasis>source, target,
        instance</emphasis><emphasis role="bold">)</emphasis></para>

        <para><emphasis>source</emphasis> A string containing the data to
        search.</para>

        <para><emphasis>target </emphasis>A string containing the substring to
        search for.</para>

        <para><emphasis>instance </emphasis>An integer specifying which
        occurrence of the substring to find.</para>

        <para>Return:<emphasis> </emphasis>StringFind returns an INTEGER
        value.</para>

        <para>The <emphasis role="bold">StringFind </emphasis>function returns
        the beginning index position within the <emphasis>source</emphasis>
        string of the specified <emphasis>instance</emphasis> of the
        <emphasis>target </emphasis>string. If the <emphasis>target</emphasis>
        is not found or the specified <emphasis>instance</emphasis> is greater
        than the number of occurrences of the <emphasis>target</emphasis> in
        the <emphasis>source</emphasis>, StringFind returns zero (0).</para>

        <para>Example:</para>

        <programlisting>A := IF(DataLib.StringFind('ABCDE', 'BC',1) = 2,
   'Success',
   'Failure - 1');  //success

B := IF(DataLib.StringFind('ABCDEABCDE', 'BC', 2) = 7,
   'Success',
   'Failure - 2');  //success

C := IF(DataLib.StringFind('ABCDEABCDE', '') = 0,
   'Success',
   'Failure - 3');  //syntax error

D := IF(DataLib.StringFind('', 'BD', 1) = 0,
   'Success',
   'Failure - 4');  //success
</programlisting>
      </sect2>

      <sect2 id="StringReplaceSmaller">
        <title><emphasis role="bold">StringReplaceSmaller</emphasis></title>

        <para><emphasis role="bold">DataLib.StringReplaceSmaller(</emphasis><emphasis>source,
        target, replacement</emphasis><emphasis role="bold">)</emphasis></para>

        <para><emphasis>source</emphasis> A string containing the data to
        search.</para>

        <para><emphasis>target </emphasis>A string containing the substring to
        search for.</para>

        <para><emphasis>replacement </emphasis>A string containing the
        replacement data.</para>

        <para>Return:<emphasis> </emphasis>StringReplaceSmaller returns a
        STRING value.</para>

        <para>The <emphasis role="bold">StringReplaceSmaller
        </emphasis>function returns the <emphasis>source</emphasis> string
        with the <emphasis>replacement</emphasis> string substituted for all
        instances of the <emphasis>target </emphasis>string, but only if the
        length of the <emphasis>replacement</emphasis> string is &lt;= the
        length of the <emphasis>target</emphasis> string . If the
        <emphasis>target</emphasis> string is not in the
        <emphasis>source</emphasis> string or the
        <emphasis>replacement</emphasis> is too long, it returns the
        <emphasis>source</emphasis> string unaltered.</para>

        <para>Example:</para>

        <programlisting>A := DataLib.StringReplaceSmaller('ABCDEABCDE', 'BC','XY');
  //A contains ‘AXYDEAXYDE’
</programlisting>
      </sect2>

      <sect2 id="StringSimilar100">
        <title><emphasis role="bold">StringSimilar100</emphasis></title>

        <para><emphasis role="bold">DataLib.StringSimilar100(</emphasis><emphasis>left,right</emphasis><emphasis role="bold">)</emphasis></para>

        <para><emphasis>left</emphasis> A string.</para>

        <para><emphasis>right</emphasis> A string.</para>

        <para>Return:<emphasis> </emphasis>StringSimilar100 returns an
        UNSIGNED INTEGER4 value.</para>

        <para>The <emphasis role="bold">StringSimilar </emphasis>function
        returns a score indicating how closely the <emphasis>left
        </emphasis>string matches the <emphasis>right </emphasis>string. The
        lower the score, the closer the match, with zero (0) indicating a
        perfect match.</para>

        <para>Example:</para>

        <programlisting>A1 := datalib.stringsimilar100('abc','abc'); //returns 0
A2 := datalib.stringsimilar100('abc','cde'); //returns 67
A3 := datalib.stringsimilar100('abc','abcde'); //returns 27
A4 := datalib.stringsimilar100('abc','ABC'); //returns 100
A5 := datalib.stringsimilar100('abc','xyz'); //returns 100
</programlisting>
      </sect2>
    </sect1>

    <sect1 id="File_Handling">
      <title><emphasis>File Handling</emphasis></title>

      <sect2 id="CompareFiles">
        <title><emphasis role="bold">CompareFiles</emphasis></title>

        <para><emphasis role="bold">FileServices.CompareFiles(</emphasis><emphasis> file1,
        file2 </emphasis><emphasis role="bold">[</emphasis><emphasis>,
        logicalonly </emphasis><emphasis role="bold">]</emphasis><emphasis>
        </emphasis><emphasis role="bold">[</emphasis><emphasis>, usecrcs
        </emphasis><emphasis role="bold">]</emphasis><emphasis>
        </emphasis><emphasis role="bold">)</emphasis></para>

        <para><emphasis>file1</emphasis> A null-terminated string containing
        the logical name of the first file.</para>

        <para><emphasis>file2</emphasis> A null-terminated string containing
        the logical name of the second file.</para>

        <para><emphasis>logicalonly</emphasis> Optional. A boolean TRUE/FALSE
        flag that, when TRUE, does not compare physical information from disk
        but only the logical information in the system datastore (Dali). If
        omitted, the default is TRUE.</para>

        <para><emphasis>usecrcs</emphasis> Optional. A boolean TRUE/FALSE flag
        indicating that, when TRUE, compares physical CRCs of all the parts on
        disk. This may be slow on large files. If omitted, the default is
        FALSE.</para>

        <para>Return:<emphasis> </emphasis>CompareFiles returns returns an
        INTEGER4 value.</para>

        <para>The <emphasis role="bold">CompareFiles </emphasis>function
        compares <emphasis>file1</emphasis> against <emphasis>file2</emphasis>
        and returns the following values:</para>

        <para>0 <emphasis>file1</emphasis> and <emphasis>file2</emphasis>
        match exactly 1 <emphasis>file1</emphasis> and
        <emphasis>file2</emphasis> contents match, but
        <emphasis>file1</emphasis> is newer than <emphasis>file2</emphasis> -1
        <emphasis>file1</emphasis> and <emphasis>file2</emphasis> contents
        match, but <emphasis>file2</emphasis> is newer than
        <emphasis>file1</emphasis> 2 <emphasis>file1</emphasis> and
        <emphasis>file2</emphasis> contents do not match and
        <emphasis>file1</emphasis> is newer than <emphasis>file2</emphasis> -2
        <emphasis>file1</emphasis> and <emphasis>file2</emphasis> contents do
        not match and <emphasis>file2</emphasis> is newer than
        <emphasis>file1</emphasis></para>

        <para>Example:</para>

        <programlisting>A := FileServices.CompareFiles('Fred1', 'Fred2');
</programlisting>
      </sect2>

      <sect2 id="DeleteLogicalFile">
        <title><emphasis role="bold">DeleteLogicalFile</emphasis></title>

        <para><emphasis role="bold">FileServices.DeleteLogicalFile(</emphasis><emphasis>
        filename </emphasis><emphasis role="bold">[</emphasis><emphasis>,
        ifexists </emphasis><emphasis role="bold">] )</emphasis></para>

        <para><emphasis>filename</emphasis> A null-terminated string
        containing the logical name of the file.</para>

        <para><emphasis>ifexists</emphasis> Optional. A boolean value
        indicating whether to post an error if the
        <emphasis>filename</emphasis> does not exist. If omitted, the default
        is FALSE.</para>

        <para>The <emphasis role="bold">DeleteLogicalFile </emphasis>function
        removes the named file from disk.</para>

        <para>Example:</para>

        <programlisting>A := FileServices.DeleteLogicalFile('Fred');
</programlisting>
      </sect2>

      <sect2 id="LogicalFileList">
        <title><emphasis role="bold">LogicalFileList</emphasis></title>

        <para><emphasis role="bold">FileServices.LogicalFileList(</emphasis><emphasis>
        </emphasis><emphasis role="bold">[ </emphasis><emphasis>pattern
        </emphasis><emphasis role="bold">] [,
        </emphasis><emphasis>includenormal</emphasis><emphasis role="bold"> ]
        [, </emphasis><emphasis>includesuper</emphasis><emphasis role="bold">
        ]</emphasis><emphasis role="bold"> [,
        </emphasis><emphasis>unknownszero </emphasis><emphasis role="bold">]
        )</emphasis></para>

        <para><emphasis>pattern</emphasis> Optional. A null-terminated string
        containing the mask of the files to list. If omitted,the default is
        '*' (all files).</para>

        <para><emphasis>includenormal</emphasis> Optional. A boolean flag
        indicating whether to include “normal” files. If omitted, the default
        is TRUE.</para>

        <para><emphasis>includesuper</emphasis> Optional. A boolean flag
        indicating whether to include SuperFiles. If omitted, the default is
        FALSE.</para>

        <para><emphasis>unknownszero</emphasis> Optional. A boolean flag
        indicating to set file sizes that are unknown to zero (0) instead of
        minus-one (-1). If omitted, the default is FALSE.</para>

        <para>Return:<emphasis> </emphasis>LogicalFileList returns returns a
        dataset in the following format:</para>

        <para><programlisting>EXPORT FsLogicalFileNameRecord := RECORD</programlisting></para>

        <para><programlisting>STRING name;</programlisting></para>

        <para><programlisting>END;</programlisting></para>

        <para><programlisting>EXPORT FsLogicalFileInfoRecord :=</programlisting></para>

        <programlisting>RECORD(FsLogicalFileNameRecord)</programlisting>

        <programlisting>BOOLEAN superfile;</programlisting>

        <programlisting>UNSIGNED8 size;</programlisting>

        <programlisting>UNSIGNED8 rowcount;</programlisting>

        <programlisting>STRING19 modified;</programlisting>

        <programlisting>STRING owner;</programlisting>

        <programlisting>STRING cluster;</programlisting>

        <programlisting>END;</programlisting>

        <para>The <emphasis role="bold">LogicalFileList </emphasis>function
        returns a list of the logical files in the environment files as a
        dataset in the format listed above.</para>

        <para>Example:</para>

        <programlisting>OUTPUT(FileServices.LogicalFileList());
  //returns all normal files
    
OUTPUT(FileServices.LogicalFileList(,FALSE,TRUE));
  //returns all SuperFiles</programlisting>
      </sect2>

      <sect2 id="FileExists">
        <title><emphasis role="bold">FileExists</emphasis></title>

        <para><emphasis role="bold">FileServices.FileExists(</emphasis><emphasis> filename
        </emphasis><emphasis role="bold">[,
        </emphasis><emphasis>physicalcheck</emphasis><emphasis role="bold">]
        )</emphasis></para>

        <para><emphasis>filename</emphasis> A null-terminated string
        containing the logical name of the file.</para>

        <para><emphasis>physicalcheck</emphasis> Optional. A boolean
        TRUE/FALSE to indicate whether to check for the physical existence the
        <emphasis>filename</emphasis> on disk. If omitted, the default is
        FALSE.</para>

        <para>Return:<emphasis> </emphasis>FileExists returns a BOOLEAN
        value.</para>

        <para>The <emphasis role="bold">FileExists </emphasis>function returns
        TRUE if the specified <emphasis>filename</emphasis> is present in the
        Distributed File Utility (DFU) and is not a SuperFile (use the
        FileServices.SuperFileExists function to detect their presence or
        absence). If <emphasis>physicalcheck</emphasis> is set to TRUE, then
        the file’s physical presence on disk is also checked.</para>

        <para>Example:</para>

        <programlisting>A := FileServices.FileExists('~CLASS::RT::IN::People');</programlisting>
      </sect2>

      <sect2 id="ForeignLogicalFileName">
        <title><emphasis role="bold">ForeignLogicalFileName</emphasis></title>

        <para><emphasis role="bold">FileServices.ForeignLogicalFileName(</emphasis><emphasis>filename
        </emphasis><emphasis role="bold">[,</emphasis><emphasis>foreigndali
        </emphasis><emphasis role="bold">]
        [,</emphasis><emphasis>absolutepath</emphasis><emphasis role="bold">]
        )</emphasis></para>

        <para><emphasis>filename</emphasis> A null-terminated string
        containing the logical name of the file.</para>

        <para><emphasis>foreigndali</emphasis> A null-terminated string
        containing the IP address of the foreign Dali. If omitted, the
        <emphasis>filename</emphasis> is presumed to be a foreign logical file
        name, which is converted to a local logical file name.</para>

        <para><emphasis>absolutepath</emphasis> Optional. A boolean TRUE/FALSE
        to indicate whether to prepend a tilde (~) to the resulting foreign
        logical file name. If omitted, the default is FALSE.</para>

        <para>Return:<emphasis> </emphasis>ForeignLogicalFileName returns
        returns a VARSTRING (null-terminated) value.</para>

        <para>The <emphasis role="bold">ForeignLogicalFileName
        </emphasis>function returns either a foreign logical file name (if the
        <emphasis>foreigndali</emphasis> parameter is present) or a local
        logical file name.</para>

        <para>Example:</para>

        <programlisting>sf := '~thor_data400::BASE::Business_Header';
ff := FileServices.ForeignLogicalFileName(sf,'10.150.29.161',true);
 //results in: ~foreign::10.150.29.161::thor_data400::base::business_header
lf := FileServices.ForeignLogicalFileName(ff,'',true);
 //results in: ~thor_data400::base::business_header</programlisting>
      </sect2>

      <sect2 id="FileServicesGetBuildInfo">
        <title><emphasis role="bold">FS GetBuildInfo</emphasis></title>

        <para><emphasis role="bold">FileServices.GetBuildInfo()</emphasis></para>

        <para>Return:<emphasis> </emphasis>GetBuildInfo returns a VARSTRING
        (null-terminated) value.</para>

        <para>The <emphasis role="bold">GetBuildInfo </emphasis>functions
        return a string containing information that specifies the build number
        and date/time stamp of the supercomputer software.</para>

        <para>Example:</para>

        <programlisting>A := FileServices.GetBuildInfo();</programlisting>
      </sect2>

      <sect2 id="GetExpandLogicalFileName">
        <title><emphasis role="bold">GetExpandLogicalFileName</emphasis></title>

        <para><emphasis role="bold">ThorLib.GetExpandLogicalFileName(
        </emphasis><emphasis>filename </emphasis><emphasis role="bold">)</emphasis></para>

        <para><emphasis>filename</emphasis> A null-terminated string
        containing the logical name of the file.</para>

        <para>Return:<emphasis> </emphasis>GetExpandLogicalFileName returns a
        VARSTRING (null-terminated) value.</para>

        <para>The <emphasis role="bold">GetExpandLogicalFileName
        </emphasis>function returns a string containing the expanded logical
        filename (ncluding the default scope, if the filename does not contain
        a leading tilde), all in lowercase. This is the same value as is used
        internally by DATASET and OUTPUT.</para>

        <para>Example:</para>

        <programlisting>A := ThorLib.GetExpandLogicalFileName('Fred');</programlisting>
      </sect2>

      <sect2 id="GetFileDescription">
        <title><emphasis role="bold">GetFileDescription</emphasis></title>

        <para><emphasis role="bold">FileServices.GetFileDescription(
        </emphasis><emphasis>filename </emphasis><emphasis role="bold">)</emphasis></para>

        <para><emphasis>filename</emphasis> A null-terminated string
        containing the logical name of the file.</para>

        <para>Return:<emphasis> </emphasis>GetFileDescription returns a
        VARSTRING (null-terminated) value.</para>

        <para>The <emphasis role="bold">GetFileDescription </emphasis>function
        returns a string containing the description information stored by the
        DFU about the specified <emphasis>filename</emphasis>. This
        description is set either through ECL watch or by using the
        FileServices.SetFileDescription function.</para>

        <para>Example:</para>

        <programlisting>A := FileServices.GetFileDescription('Fred');</programlisting>
      </sect2>

      <sect2 id="RemoteDirectory">
        <title><emphasis role="bold">RemoteDirectory</emphasis></title>

        <para><emphasis role="bold">FileServices.RemoteDirectory(</emphasis><emphasis>
        machineIP, directory </emphasis><emphasis role="bold">[</emphasis><emphasis>, mask </emphasis><emphasis role="bold">][</emphasis><emphasis>, includesubs </emphasis><emphasis role="bold">]</emphasis><emphasis> </emphasis><emphasis role="bold">)</emphasis></para>

        <para><emphasis>machineIP</emphasis> A null-terminated string
        containing the IP address of the remote machine.</para>

        <para><emphasis>directory</emphasis> A null-terminated string
        containing the path to the directory to read. This must be in the
        appropriate format for the operating system running on the remote
        machine.</para>

        <para><emphasis>mask</emphasis> Optional. A null-terminated string
        containing the filemask specifying which files to include in the
        result. If omitted,the default is '*' (all files).</para>

        <para><emphasis>includesubdir</emphasis> Optional. A boolean flag
        indicating whether to include files from sub-directories under the
        <emphasis>directory</emphasis>. If omitted, the default is
        FALSE.</para>

        <para>Return:<emphasis> </emphasis>RemoteDirectory returns a dataset
        in the following format:</para>

        <para>EXPORT FsFilenameRecord := RECORD</para>

        <para>STRING name; //filename</para>

        <para>UNSIGNED8 size; //filesize</para>

        <para>STRING19 modified; //date-time stamp</para>

        <para>END;</para>

        <para>The <emphasis role="bold">RemoteDirectory </emphasis>function
        returns a list of files as a dataset in the format listed above from
        the specified <emphasis>machineIP</emphasis> and
        <emphasis>directory</emphasis>. If <emphasis>includesubdir</emphasis>
        is set to TRUE, then the name field contains the relative path to the
        file from the specified <emphasis>directory</emphasis>.</para>

        <para>Example:</para>

        <programlisting>OUTPUT(FileServices.RemoteDirectory('edata12','\in','*.d00'));
OUTPUT(FileServices.RemoteDirectory('10.150.254.6',
      '/c$/training',,TRUE));</programlisting>
      </sect2>

      <sect2 id="RenameLogicalFile">
        <title><emphasis role="bold">RenameLogicalFile</emphasis></title>

        <para><emphasis role="bold">FileServices.RenameLogicalFile(</emphasis><emphasis>
        filename, newname </emphasis><emphasis role="bold">)</emphasis></para>

        <para><emphasis>filename</emphasis> A null-terminated string
        containing the current logical name of the file.</para>

        <para><emphasis>newname</emphasis> A null-terminated string containing
        the new logical name for the file.</para>

        <para>The <emphasis role="bold">RenameLogicalFile </emphasis>function
        changes the logical <emphasis>filename</emphasis> to the
        <emphasis>newname</emphasis>.</para>

        <para>Example:</para>

        <programlisting>A := FileServices.RenameLogicalFile('Fred', 'Freddie');</programlisting>
      </sect2>

      <sect2 id="Replicate">
        <title><emphasis role="bold">Replicate</emphasis></title>

        <para><emphasis role="bold">FileServices.Replicate(</emphasis><emphasis> filename
        </emphasis><emphasis role="bold">[</emphasis><emphasis>, timeout
        </emphasis><emphasis role="bold">] [</emphasis><emphasis>,
        espserverIPport</emphasis><emphasis role="bold">])</emphasis><emphasis>dfuwuid </emphasis><emphasis role="bold">:= FileServices.fReplicate(</emphasis><emphasis> filename
        </emphasis><emphasis role="bold">[</emphasis><emphasis>, timeout
        </emphasis><emphasis role="bold">] [</emphasis><emphasis>,
        espserverIPport</emphasis><emphasis role="bold">]);</emphasis></para>

        <para><emphasis>filename</emphasis> A null-terminated string
        containing the logical name of the file.</para>

        <para><emphasis>timeout</emphasis> Optional. An integer value
        indicating the timeout setting. If omitted, the default is -1. If set
        to zero (0), execution control returns immediately to the ECL workunit
        without waiting for the DFU workunit to complete.</para>

        <para><emphasis>espserverIPport</emphasis> Optional. A null-terminated
        string containing the protocol, IP, port, and directory, or the DNS
        equivalent, of the ESP server program. This is usually the same IP and
        port as ECL Watch, with “/FileSpray” appended. If omitted, the default
        is the value contained in the lib_system.ws_fs_server
        attribute.</para>

        <para><emphasis>dfuwuid</emphasis> The attribute name to recieve the
        null-terminated string containing the DFU workunit ID (DFUWUID)
        generated for the job.</para>

        <para>The <emphasis role="bold">Replicate </emphasis>function copies
        the individual parts of the <emphasis>filename</emphasis> to the
        mirror disks for the cluster. Typically, this means that the file part
        on one node’s C drive is copied to its neighbors D drive.</para>

        <para>Example:</para>

        <programlisting>A := FileServices.Replicate('Fred');</programlisting>
      </sect2>

      <sect2 id="SendEmail">
        <title><emphasis role="bold">SendEmail</emphasis></title>

        <para><emphasis role="bold">FileServices.SendEmail(
        </emphasis><emphasis>sendto, subject, body, server, port,
        sender</emphasis><emphasis role="bold"> )</emphasis></para>

        <para><emphasis>sendto</emphasis> A null-terminated string containing
        a comma-delimited list of the addresses of the intended recipients.
        The validity of the addresses is not checked, so it is the
        programmer’s responsibility to ensure they are all valid.</para>

        <para><emphasis>subject</emphasis> A null-terminated string containing
        the subject line.</para>

        <para><emphasis>body</emphasis> A null-terminated string containing
        the text of the email to send. This must be character encoding
        “ISO-8859-1 (latin1)” (the ECL default character set). Text in any
        other character set must be sent as an attachment (see the
        FileServices.SendEmailAttachText() function).</para>

        <para><emphasis>server</emphasis> Optional. A null-terminated string
        containing the name of the mail server. If omitted, defaults to the
        value in the lib_system.SMTPserver attribute.</para>

        <para><emphasis>port</emphasis> Optional. An UNSIGNED4 integer value
        containing the port number. If omitted, defaults to the value in the
        lib_system.SMTPport attribute.</para>

        <para><emphasis>sender</emphasis> Optional. A null-terminated string
        containing the address of the sender. If omitted, defaults to the
        value in the lib_system.emailAddress attribute.</para>

        <para>The <emphasis role="bold">SendEmail </emphasis>function sends an
        email message.</para>

        <para>Example:</para>

        <programlisting>FileServices.SendEmail( 'me@mydomain.com', 'testing 1,2,3', 'this is a test message');</programlisting>
      </sect2>

      <sect2 id="SendEmailAttachData">
        <title><emphasis role="bold">SendEmailAttachData</emphasis></title>

        <para><emphasis role="bold">FileServices.SendEmailAttachData(
        </emphasis><emphasis>sendto, subject, body, attachment, mimietype,
        filename, server, port, sender</emphasis><emphasis role="bold">
        )</emphasis></para>

        <para><emphasis>sendto</emphasis> A null-terminated string containing
        a comma-delimited list of the addresses of the intended recipients.
        The validity of the addresses is not checked, so it is the
        programmer’s responsibility to ensure they are all valid.</para>

        <para><emphasis>subject</emphasis> A null-terminated string containing
        the subject line.</para>

        <para><emphasis>body</emphasis> A null-terminated string containing
        the text of the email to send. This must be character encoding
        “ISO-8859-1 (latin1)” (the ECL default character set). Text in any
        other character set must be sent as an
        <emphasis>attachment</emphasis>.</para>

        <para><emphasis>attachment</emphasis> A DATA value containing the
        binary data to attach.</para>

        <para><emphasis>mimetype</emphasis> A null-terminated string
        containing the MIME-type of the <emphasis>attachment</emphasis>, which
        may include parameters (such as ‘text/plain; charset=ISO-8859-3’).
        When attaching general binary data for which no specific MIME type
        exists, use ‘application/octet-stream’.</para>

        <para><emphasis>filename</emphasis> A null-terminated string
        containing the name of the <emphasis>attachment</emphasis> for the
        mail reader to display.</para>

        <para><emphasis>server</emphasis> Optional. A null-terminated string
        containing the name of the mail server. If omitted, defaults to the
        value in the lib_system.SMTPserver attribute.</para>

        <para><emphasis>port</emphasis> Optional. An UNSIGNED4 integer value
        containing the port number. If omitted, defaults to the value in the
        lib_system.SMTPport attribute.</para>

        <para><emphasis>sender</emphasis> Optional. A null-terminated string
        containing the address of the sender. If omitted, defaults to the
        value in the lib_system.emailAddress attribute.</para>

        <para>The <emphasis role="bold">SendEmailAttachData
        </emphasis>function sends an email message with a binary
        <emphasis>attachment</emphasis>.</para>

        <para>Example:</para>

        <programlisting>DATA15 attachment :=  D'test attachment';
FileServices.SendEmailAttachData( 'me@mydomain.com',
                                  'testing 1,2,3',
                                  'this is a test message',
                                   attachment,
                                  'application/octet-stream',
                                  'attachment.txt');</programlisting>
      </sect2>

      <sect2 id="SendEmailAttachText">
        <title><emphasis role="bold">SendEmailAttachText</emphasis></title>

        <para><emphasis role="bold">FileServices.SendEmailAttachText(
        </emphasis><emphasis>sendto, subject, body, attachment, mimietype,
        filename, server, port, sender</emphasis><emphasis role="bold">
        )</emphasis></para>

        <para><emphasis>sendto</emphasis> A null-terminated string containing
        a comma-delimited list of the addresses of the intended recipients.
        The validity of the addresses is not checked, so it is the
        programmer’s responsibility to ensure they are all valid.</para>

        <para><emphasis>subject</emphasis> A null-terminated string containing
        the subject line.</para>

        <para><emphasis>body</emphasis> A null-terminated string containing
        the text of the email to send. This must be character encoding
        “ISO-8859-1 (latin1)” (the ECL default character set). Text in any
        other character set must be sent as an
        <emphasis>attachment</emphasis>.</para>

        <para><emphasis>attachment</emphasis> A null-terminated string
        containing the text to attach.</para>

        <para><emphasis>mimetype</emphasis> A null-terminated string
        containing the MIME-type of the <emphasis>attachment</emphasis>, which
        may include parameters (such as ‘text/plain;
        charset=ISO-8859-3’).</para>

        <para><emphasis>filename</emphasis> A null-terminated string
        containing the name of the <emphasis>attachment</emphasis> for the
        mail reader to display.</para>

        <para><emphasis>server</emphasis> Optional. A null-terminated string
        containing the name of the mail server. If omitted, defaults to the
        value in the lib_system.SMTPserver attribute.</para>

        <para><emphasis>port</emphasis> Optional. An UNSIGNED4 integer value
        containing the port number. If omitted, defaults to the value in the
        lib_system.SMTPport attribute.</para>

        <para><emphasis>sender</emphasis> Optional. A null-terminated string
        containing the address of the sender. If omitted, defaults to the
        value in the lib_system.emailAddress attribute.</para>

        <para>The <emphasis role="bold">SendEmailAttachText
        </emphasis>function sends an email message with a text
        <emphasis>attachment</emphasis>.</para>

        <para>Example:</para>

        <programlisting>FileServices.SendEmailAttachText( 'me@mydomain.com', 'testing 1,2,3',
                                 'this is a test message', 'this is a test attachment',
                                 'text/plain; charset=ISO-8859-3',  'attachment.txt');</programlisting>
      </sect2>

      <sect2 id="SetFileDescription">
        <title><emphasis role="bold">SetFileDescription</emphasis></title>

        <para><emphasis role="bold">FileServices.SetFileDescription(
        </emphasis><emphasis>filename , value </emphasis><emphasis role="bold">)</emphasis></para>

        <para><emphasis>filename</emphasis> A null-terminated string
        containing the logical name of the file.</para>

        <para><emphasis>value</emphasis> A null-terminated string containing
        the description to place on the file.</para>

        <para>The <emphasis role="bold">SetFileDescription </emphasis>function
        changes the description information stored by the DFU about the
        specified <emphasis>filename </emphasis>to the specified
        <emphasis>value</emphasis>. This description is seen either through
        ECL watch or by using the FileServices.GetFileDescription
        function.</para>

        <para>Example:</para>

        <programlisting>A := FileServices.SetFileDescription('Fred','All the Freds in the world');</programlisting>
      </sect2>

      <sect2 id="SetReadOnly">
        <title><emphasis role="bold">SetReadOnly</emphasis></title>

        <para><emphasis role="bold">FileServices.SetReadOnly(</emphasis><emphasis> filename
        </emphasis><emphasis role="bold">, </emphasis><emphasis>flag
        </emphasis><emphasis role="bold">)</emphasis></para>

        <para><emphasis>filename</emphasis> A null-terminated string
        containing the logical name of the file.</para>

        <para><emphasis>flag</emphasis> A boolean value indicating which way
        to set the read-only attribute of the
        <emphasis>filename</emphasis>.</para>

        <para>The <emphasis role="bold">SetReadOnly </emphasis>function
        toggles the read-only attribute of the filename. If the
        <emphasis>flag</emphasis> is TRUE, read-only is set on.</para>

        <para>Example:</para>

        <programlisting>A := FileServices.SetReadOnly('Fred',TRUE);
 //set read only flag on
</programlisting>
      </sect2>

      <sect2 id="VerifyFile">
        <title><emphasis role="bold">VerifyFile</emphasis></title>

        <para><emphasis role="bold">FileServices.VerifyFile(</emphasis><emphasis> file,
        usecrcs </emphasis><emphasis role="bold">)</emphasis></para>

        <para><emphasis>file</emphasis> A null-terminated string containing
        the logical name of the file.</para>

        <para><emphasis>usecrcs</emphasis> A boolean TRUE/FALSE flag
        indicating that, when TRUE, compares physical CRCs of all the parts on
        disk. This may be slow on large files.</para>

        <para>Return:<emphasis> </emphasis>VerifyFile returns returns a
        VARSTRING value.</para>

        <para>The <emphasis role="bold">VerifyFile </emphasis>function checks
        the system datastore (Dali) information for the
        <emphasis>file</emphasis> against the physical parts on disk and
        returns the following values:</para>

        <para>OK The file parts match the datastore information</para>

        <para>Could not find file: <emphasis>filename</emphasis><emphasis>
        </emphasis> The logical <emphasis>filename</emphasis> was not
        found</para>

        <para>Could not find part file:
        <emphasis>partname</emphasis><emphasis> </emphasis> The
        <emphasis>partname</emphasis> was not found</para>

        <para>Modified time differs for:
        <emphasis>partname</emphasis><emphasis> </emphasis> The
        <emphasis>partname</emphasis> has a different timestamp</para>

        <para>File size differs for: <emphasis>partname</emphasis><emphasis>
        </emphasis> The <emphasis>partname</emphasis> has a file size</para>

        <para>File CRC differs for: <emphasis>partname</emphasis><emphasis>
        </emphasis> The <emphasis>partname</emphasis> has a different
        CRC</para>

        <para>Example:</para>

        <programlisting>A := FileServices.VerifyFile('Fred1', TRUE);
</programlisting>
      </sect2>
    </sect1>

    <sect1 id="External_File_Support">
      <title><emphasis>External File Support</emphasis></title>

      <sect2 id="ExternalLogicalFileName">
        <title><emphasis role="bold">ExternalLogicalFileName</emphasis></title>

        <para><emphasis role="bold">FileServices.ExternalLogicalFileName(</emphasis><emphasis>
        machineIP, filename </emphasis><emphasis role="bold">)</emphasis></para>

        <para><emphasis>machineIP</emphasis> A null-terminated string
        containing the IP address of the remote machine.</para>

        <para><emphasis>filename</emphasis> A null-terminated string
        containing the path/name of the file.</para>

        <para>Return:<emphasis> </emphasis>ExternalLogicalFileName returns
        returns a VARSTRING (null-terminated) value.</para>

        <para>The <emphasis role="bold">ExternalLogicalFileName
        </emphasis>function returns an appropriately encoded external logical
        file name that can be used to directly read a file from any node that
        is running the dafilesrv utility (typically a landing zone). It
        handles upper case characters by escaping those characters inthe
        return string.</para>

        <para>Example:</para>

        <programlisting>IP   := '10.150.254.6';
file := '/c$/training/import/AdvancedECL/people';
DS1  := DATASET(FileServices.ExternalLogicalFileName(IP,file),
        Training_Advanced.Layout_PeopleFile, FLAT);
OUTPUT(FileServices.ExternalLogicalFileName(IP,file));
//returns:
//~file::10.150.254.6::c$::training::import::^advanced^e^c^l::people
OUTPUT(DS1);
//returns records from the external file
</programlisting>
      </sect2>

      <sect2 id="GetHostName">
        <title><emphasis role="bold">GetHostName</emphasis></title>

        <para><emphasis>result</emphasis><emphasis role="bold"> :=
        FileServices.GetHostName(</emphasis><emphasis> ip </emphasis><emphasis role="bold">);</emphasis></para>

        <para><emphasis>ip</emphasis> A null-terminated string containing the
        IP address of the remote machine.</para>

        <para>Return:<emphasis> </emphasis>GetHostName returns returns a
        VARSTRING (null-terminated) value.</para>

        <para>The <emphasis role="bold">GetHostName </emphasis>function does a
        reverse DNS lookup to return the host name for the machine at the
        specified <emphasis>ip</emphasis> address.</para>

        <para>Example:</para>

        <programlisting>IP   := '10.150.254.6';
   
OUTPUT(FileServices.GetHostName(IP));
</programlisting>
      </sect2>

      <sect2 id="ResolveHostName">
        <title><emphasis role="bold">ResolveHostName</emphasis></title>

        <para><emphasis>result</emphasis><emphasis role="bold"> :=
        FileServices.ResolveHostName(</emphasis><emphasis> host
        </emphasis><emphasis role="bold">);</emphasis></para>

        <para><emphasis>host</emphasis> A null-terminated string containing
        the DNS name of the remote machine.</para>

        <para>Return:<emphasis> </emphasis>ResolveHostName returns returns a
        VARSTRING (null-terminated) value.</para>

        <para>The <emphasis role="bold">ResolveHostName </emphasis>function
        does a DNS lookup to return the ip address for the specified
        <emphasis>host</emphasis> name.</para>

        <para>Example:</para>

        <programlisting>host := 'dataland_dali.br.seisint.com';
OUTPUT(FileServices.ResolveHostName(host));
</programlisting>
      </sect2>

      <sect2 id="MoveExternalFile">
        <title><emphasis role="bold">MoveExternalFile</emphasis></title>

        <para><emphasis role="bold">FileServices.MoveExternalFile(</emphasis><emphasis>
        location, frompath, topath </emphasis><emphasis role="bold">)</emphasis></para>

        <para><emphasis>location</emphasis> A null-terminated string
        containing the IP address of the remote machine.</para>

        <para><emphasis>frompath</emphasis> A null-terminated string
        containing the path/name of the file to move.</para>

        <para><emphasis>topath</emphasis> A null-terminated string containing
        the path/name of the target file.</para>

        <para>The <emphasis role="bold">MoveExternalFile </emphasis>function
        moves the single physical file specified by the
        <emphasis>frompath</emphasis> to the <emphasis>topath</emphasis>. Both
        <emphasis>frompath</emphasis> and <emphasis>topath</emphasis> are on
        the same remote machine, identified by the
        <emphasis>location</emphasis>. The dafileserv utility program must be
        running on the <emphasis>location</emphasis> machine.</para>

        <para>Example:</para>

        <programlisting>IP      := '10.150.254.6';
infile  := '/c$/training/import/AdvancedECL/people';
outfile := '/c$/training/import/DFUtest/people';
FileServices.MoveExternalFile(IP,infile,outfile);</programlisting>
      </sect2>

      <sect2 id="DeleteExternalFile">
        <title><emphasis role="bold">DeleteExternalFile</emphasis></title>

        <para><emphasis role="bold">FileServices.DeleteExternalFile(</emphasis><emphasis>
        location, path </emphasis><emphasis role="bold">)</emphasis></para>

        <para><emphasis>location</emphasis> A null-terminated string
        containing the IP address of the remote machine.</para>

        <para><emphasis>path</emphasis> A null-terminated string containing
        the path/name of the file to remove.</para>

        <para>The <emphasis role="bold">DeleteExternalFile </emphasis>function
        removes the single physical file specified by the
        <emphasis>path</emphasis> from the <emphasis>location</emphasis>. The
        dafileserv utility program must be running on the
        <emphasis>location</emphasis> machine.</para>

        <para>Example:</para>

        <programlisting>IP   := '10.150.254.6';
infile := '/c$/training/import/AdvancedECL/people';
FileServices.DeleteExternalFile(IP,infile);
</programlisting>
      </sect2>

      <sect2 id="CreateExternalDirectory">
        <title><emphasis role="bold">CreateExternalDirectory</emphasis></title>

        <para><emphasis role="bold">FileServices.CreateExternalDirectory(</emphasis><emphasis>
        location, path </emphasis><emphasis role="bold">)</emphasis></para>

        <para><emphasis>location</emphasis> A null-terminated string
        containing the IP address of the remote machine.</para>

        <para><emphasis>path</emphasis> A null-terminated string containing
        the directory path to create.</para>

        <para>The <emphasis role="bold">CreateExternalDirectory
        </emphasis>function creates the <emphasis>path</emphasis> on the
        <emphasis>location </emphasis>(if it does not already exist). The
        dafileserv utility program must be running on the
        <emphasis>location</emphasis> machine.</para>

        <para>Example:</para>

        <programlisting>IP   := '10.150.254.6';
path := '/c$/training/import/NewDir';
FileServices.CreateExternalDirectory(IP,path);
</programlisting>
      </sect2>
    </sect1>

    <sect1 id="Remote_File_Support">
      <title><emphasis>Remote File Support</emphasis></title>

      <para></para>

      <para></para>

      <sect2 id="RfsQuery">
        <title><emphasis role="bold">RfsQuery</emphasis></title>

        <para><emphasis>result</emphasis><emphasis role="bold"> :=
        FileServices.RfsQuery(</emphasis><emphasis> server, query
        </emphasis><emphasis role="bold">);</emphasis></para>

        <para><emphasis>server</emphasis> A null-terminated string containing
        the ip:port address for the remote file server.</para>

        <para><emphasis>query</emphasis> A null-terminated string containing
        the query to send to the <emphasis>server</emphasis>.</para>

        <para>Return:<emphasis> </emphasis>RfsQuery returns a null-terminated
        string containing the result of the <emphasis>query</emphasis>.</para>

        <para>The <emphasis role="bold">RfsQuery </emphasis>function returns a
        string that can be used in a DATASET declaration to read data from an
        RFS (Remote File Server) instance (e.g. rfsmysql) on another
        node.</para>

        <para>Example:</para>

        <programlisting>rfsserver := '10.173.207.1:7080';
rec := RECORD,MAXLENGTH(8192)
  STRING  mydata;
END;
OUTPUT(DATASET(FileServices.RfsQuery( rfsserver,
              'SELECT data FROM xml_testnh'),rec,CSV(MAXLENGTH(8192))));</programlisting>
      </sect2>

      <sect2 id="RfsAction">
        <title><emphasis role="bold">RfsAction</emphasis></title>

        <para><emphasis role="bold">FileServices.RfsAction(</emphasis><emphasis> server, query
        </emphasis><emphasis role="bold">);</emphasis></para>

        <para><emphasis>server</emphasis> A null-terminated string containing
        the ip:port address for the remote file server.</para>

        <para><emphasis>query</emphasis> A null-terminated string containing
        the query to send to the <emphasis>server</emphasis>.</para>

        <para>The <emphasis role="bold">RfsAction </emphasis>function sends
        the <emphasis>query</emphasis> to the <emphasis>server</emphasis>.
        This is used when there is no expected return value</para>

        <para>Example:</para>

        <programlisting>rfsserver := '10.173.207.1:7080';
FileServices.RfsAction(rfsserver,'INSERT INTO xml_testnh (data) VALUES (\''+TRIM(A)+'\' )');</programlisting>
      </sect2>
    </sect1>

    <sect1 id="Field_Name_Token_Support">
      <title><emphasis>Field Name Token Support</emphasis></title>

      <sect2 id="FirstNameToToken">
        <title><emphasis role="bold">FirstNameToToken</emphasis></title>

        <para><emphasis>result</emphasis><emphasis role="bold"> :=
        NameLib.FirstNameToToken(</emphasis><emphasis> name
        </emphasis><emphasis role="bold">);</emphasis></para>

        <para><emphasis>name</emphasis> A string expression containing the
        name to tokenize. Maximum sixe: 20 characters.</para>

        <para>Return:<emphasis> </emphasis>FirstNameToToken returns a
        string.</para>

        <para>The <emphasis role="bold">FirstNameToToken </emphasis>function
        returns a string containing a tokenized representation of the
        <emphasis>name</emphasis>..</para>

        <para>Example:</para>

        <programlisting>x := namelib.FirstNameToToken('Thompson');</programlisting>
      </sect2>

      <sect2 id="TokenToFirstName">
        <title><emphasis role="bold">TokenToFirstName</emphasis></title>

        <para><emphasis>result</emphasis><emphasis role="bold"> :=
        NameLib.TokenToFirstName(</emphasis><emphasis> token
        </emphasis><emphasis role="bold">);</emphasis></para>

        <para><emphasis>token</emphasis> A string expression containing the
        token resulting from the FirstNameToToken function.</para>

        <para>Return:<emphasis> </emphasis>TokenToFirstName returns a
        20-character string.</para>

        <para>The <emphasis role="bold">TokenToFirstName </emphasis>function
        returns a string containing the name represented by the
        <emphasis>token</emphasis>.</para>

        <para>Example:</para>

        <programlisting>y := namelib.TokenToFirstName(x);   //returns 'Thompson'</programlisting>
      </sect2>

      <sect2 id="TokenToLength">
        <title><emphasis role="bold">TokenToLength</emphasis></title>

        <para><emphasis>result</emphasis><emphasis role="bold"> :=
        NameLib.TokenToLength(</emphasis><emphasis> token </emphasis><emphasis role="bold">);</emphasis></para>

        <para><emphasis>token</emphasis> A string expression containing the
        token resulting from the FirstNameToToken function.</para>

        <para>Return:<emphasis> </emphasis>TokenToLength returns an unsigned
        4-byte integer value.</para>

        <para>The <emphasis role="bold">TokenToLength </emphasis>function
        returns the number of characters in the
        <emphasis>token</emphasis>.</para>

        <para>Example:</para>

        <programlisting>x := namelib.FirstNameToToken('Thompson');
y := namelib.TokenToFirstName(x);
z := namelib.TokenToLength(x);
ds := dataset([{x,y,z}],{string Tok, string Name, unsigned4 Len});
output(ds);</programlisting>
      </sect2>
    </sect1>

    <sect1 id="File_Browsing_Support">
      <title><emphasis>File Browsing Support</emphasis></title>

      <sect2 id="SetColumnMapping">
        <title><emphasis role="bold">SetColumnMapping</emphasis></title>

        <para><emphasis role="bold">FileServices.SetColumnMapping(</emphasis><emphasis> file,
        mapping </emphasis><emphasis role="bold">);</emphasis></para>

        <para><emphasis>file</emphasis> A null-terminated string containing
        the logical filename.</para>

        <para><emphasis>mapping</emphasis> A null-terminated string containing
        a comma-delimited list of field mappings.</para>

        <para>The <emphasis role="bold">SetColumnMapping </emphasis>function
        defines how the data in the fields of the <emphasis>file</emphasis>
        mist be transformed between the actual data storage format and the
        input format used to query that data.</para>

        <para>The format for each field in the <emphasis>mapping</emphasis>
        list is:</para>

        <para><emphasis role="bold">&lt;field&gt;{set(&lt;transform&gt;(</emphasis><emphasis>args</emphasis><emphasis role="bold">),...),get(&lt;transform&gt;,...),displayname(&lt;</emphasis><emphasis>name</emphasis><emphasis role="bold">&gt;)}</emphasis></para>

        <para><emphasis role="bold">&lt;field&gt;</emphasis> The name of the
        field in the file.</para>

        <para><emphasis role="bold">set</emphasis> Optional. Specifies the
        transforms applied to the values supplied by the user to convert them
        to values in the file.</para>

        <para><emphasis role="bold">&lt;transform&gt;</emphasis> Optional. The
        name of a function to apply to the value. This is typically the name
        of a plugin function. The value being converted is always provided as
        the first parameter to the function, but extra parameters can be
        specified in brackets after the transform name (similar to SALT
        hygiene).</para>

        <para><emphasis role="bold">get</emphasis> Optional. Specifies the
        transforms applied to the values in the file to convert them to the
        formatted values as they are understood by the user.</para>

        <para><emphasis role="bold">displayname</emphasis> Optional. Allows a
        different <emphasis>name</emphasis> to be associated with the field
        than the user would naturally understand.</para>

        <para>Note that you may mix unicode and string functions, as the
        system automatically converts the parameters to the appropriate types
        expected for the functions.</para>

        <para>Example:</para>

        <programlisting>// A file where the firstname(string) and lastname(unicode) are
//always upper-cased:
// There is no need for a displayname since it isn't really a
// different field as far as the user is concerned, and there is
// obviously no get transformations.
 firstname{set(stringlib.StringToUpperCase)},
                surname{set(unicodelib.UnicodeToUpperCase)}
// A name translated using a phonetic key
// it is worth specifying a display name here, because it will make
// more sense to the user, and the user may want to enter either the
// translated or untranslated names.
 dph_lname{set(metaphonelib.DMetaPhone1),
      displayname(lname)}
// A file where a name is converted to a token using the namelib
// functions.  (I don't think we have an example of this)
// (one of the few situations where a get() attribute is useful)
 fnametoken{set(namelib.nameToToken),
       get(namelib.tokenToName),
       displayname(fname)}
// upper case, and only include digits and alphabetic.
 searchname{set(stringlib.StringToUpperCase,
      stringlib.StringFilter(
        'ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789'))}
// A file with a field that that needs to remove accents and then
// uppercase:
 lastname{set(unicodeLIb.CleanAccents,stringLib.StringToUpperCase)}
</programlisting>
      </sect2>

      <sect2 id="GetColumnMapping">
        <title><emphasis role="bold">GetColumnMapping</emphasis></title>

        <para><emphasis>result</emphasis><emphasis role="bold"> :=
        FileServices.GetColumnMapping(</emphasis><emphasis> file
        </emphasis><emphasis role="bold">);</emphasis></para>

        <para><emphasis>file</emphasis> A null-terminated string containing
        the logical filename.</para>

        <para>Return:<emphasis> </emphasis>GetColumnMapping returns a
        null-terminated string containing the comma-delimited list of field
        mappings for the <emphasis>file</emphasis>.</para>

        <para>The <emphasis role="bold">GetColumnMapping </emphasis>function
        returns the field mappings for the <emphasis>file</emphasis>, in the
        same format specified for the SetColumnMapping function.</para>

        <para>Example:</para>

        <programlisting>Maps := FileServices.GetColumnMapping('Thor::in::SomeFile');
</programlisting>
      </sect2>

      <sect2 id="AddFileRelationship">
        <title><emphasis role="bold">AddFileRelationship</emphasis></title>

        <para><emphasis role="bold">FileServices.AddFileRelationship(</emphasis><emphasis>
        primary, secondary,</emphasis><emphasis> primaryfields,
        secondaryfields, </emphasis><emphasis role="bold"> [
        </emphasis><emphasis>relationship </emphasis><emphasis role="bold">]</emphasis><emphasis>, cardinality, payload
        </emphasis><emphasis role="bold"> [</emphasis><emphasis>, description
        </emphasis><emphasis role="bold">] );</emphasis></para>

        <para><emphasis>primary</emphasis> A null-terminated string containing
        the logical filename of the primary file.</para>

        <para><emphasis>secondary</emphasis> A null-terminated string
        containing the logical filename of the secondary file.</para>

        <para><emphasis>primaryfields</emphasis> A null-terminated string
        containing the name of the primary key field for the
        <emphasis>primary</emphasis> file. The value “__fileposition__”
        indicates the <emphasis>secondary</emphasis> is an INDEX that must use
        FETCH to access non-keyed fields.</para>

        <para><emphasis>secondaryfields</emphasis> A null-terminated string
        containing the name of the foreign key field relating to the
        <emphasis>primary</emphasis> file.</para>

        <para><emphasis>relationship</emphasis> A null-terminated string
        containing either “link” or “view” indicating the type of relationship
        between the <emphasis>primary</emphasis> and
        <emphasis>secondary</emphasis> files. If omitted, the default is
        “link.”</para>

        <para><emphasis>cardinality</emphasis> A null-terminated string
        containing the kind of relationship between the
        <emphasis>primary</emphasis> and <emphasis>secondary</emphasis> files.
        The format is X:Y where X indicates the <emphasis>primary</emphasis>
        and Y indicates the <emphasis>secondary</emphasis>. Valid values for X
        and Y are “1” or ‘M’.</para>

        <para><emphasis>payload</emphasis> A BOOLEAN value indicating whether
        the <emphasis>primary</emphasis> or <emphasis>secondary</emphasis> are
        payload INDEXes.</para>

        <para><emphasis>description</emphasis> A null-terminated string
        containing the relationship description.</para>

        <para>The <emphasis role="bold">AddFileRelationship</emphasis>
        function defines the relationship between two files. These may be
        DATASETs or INDEXes. Each record in the <emphasis>primary</emphasis>
        file should be uniquely defined by the
        <emphasis>primaryfields</emphasis> (ideally), preferably
        efficiently.</para>

        <para>The <emphasis>primaryfields</emphasis> and
        <emphasis>secondaryfields</emphasis> parameters can have the same
        format as the column mappings for a file (see the SetColumnMappings
        function documentation) , although they will often be just a list of
        fields.</para>

        <para>They are currently used in two different ways:</para>

        <para>First, the roxie browser needs a way of determining which
        indexes are built from which files. A “view” relationship should be
        added each time an index is built from a file, like this:</para>

        <para>fileServices.AddFileRelationship(DG_FlatFileName,
        DG_IndexFileName,</para>

        <para>'', '', 'view', '1:1', false);</para>

        <para>To implement the roxie browser there is no need to define the
        <emphasis>primaryfields</emphasis> or
        <emphasis>secondaryfields</emphasis>, so passing blank strings is
        recommended.</para>

        <para>Second, the browser needs a way of finding all the original
        information from the file from an index.</para>

        <para>This stage depends on the nature of the index:</para>

        <para>a) If the index contains all the relevant data from the original
        file you don’t need to do anything.</para>

        <para>b) If the index uses a fileposition field to FETCH extra data
        from the original file then add a relationship between the original
        file and the index, using a special value of __fileposition__ to
        indicate the record is retrieved using a FETCH.</para>

        <para>fileServices.AddFileRelationship('fetch_file',
        'new_index',</para>

        <para>'__fileposition__',</para>

        <para>'index_filepos_field', 'link',</para>

        <para>'1:1', true);</para>

        <para>The original file is the primary, since the rows are uniquely
        identified by the fileposition (also true of the index), and the
        retrieval is efficient.</para>

        <para>c) If the index uses a payload field which needs to be looked up
        in another index to provide the information, then you need to define a
        relationship between the new index and the index that provides the
        extra information. The index providing the extra information is the
        primary.</para>

        <para>fileServices.AddFileRelationship('related_index',
        'new_index',</para>

        <para>'related_key_fields',</para>

        <para>'index_filepos_field', 'link',</para>

        <para>'1:M', true);</para>

        <para>The <emphasis>payload </emphasis>flag is there so that the roxie
        browser can distinguish this link from a more general relationship
        between two files.</para>

        <para>You should ensure any super-file names are expanded if the
        relation is defined between the particular sub-files.</para>

        <para>While going through all the attributes it may be worth examining
        whether it makes sense to add relationships for any other combinations
        of files. It won’t have any immediate beneficial effect, but would
        once we add an ER diagram to the system. A couple of examples may help
        illustrate the syntax.</para>

        <para>For a typical example, datasets with a household and person
        file, the following defines a relationship linking by house hold id
        (hhid):</para>

        <para>fileServices.AddFileRelationship('HHFile','PersonFile',
        'hhid',</para>

        <para>'hhid', 'link', '1:M', false);</para>

        <para>Here’s a more hypothetical example—a file query with firstname,
        lastname related to an index with phonetic names you might
        have:</para>

        <para>fileServices.AddFileRelationship('names', 'inquiries',</para>

        <para>'plastname{set(phonetic)},pfirstname{set(phonetic)}',</para>

        <para>'lastname{set(fail)},firstname{set(fail)}',</para>

        <para>'link', '1:M', false);</para>

        <para>Note, the fail mapping indicates that you can use the phonetic
        mapping from inquiries to names, but there is no way of mapping from
        names to inquiries. There could equally be get(fail) attributes on the
        index fields.</para>

        <para>Example:</para>

        <programlisting>Maps := FileServices.GetColumnMapping('Thor::in::SomeFile');
</programlisting>
      </sect2>

      <sect2 id="FileRelationshipList">
        <title><emphasis role="bold">FileRelationshipList</emphasis></title>

        <para><emphasis role="bold">FileServices.FileRelationshipList(</emphasis><emphasis>
        primary, secondary</emphasis><emphasis> </emphasis><emphasis role="bold">[</emphasis><emphasis>, primaryfields </emphasis><emphasis role="bold">]</emphasis><emphasis> </emphasis><emphasis role="bold">[</emphasis><emphasis>, secondaryfields
        </emphasis><emphasis role="bold">]</emphasis><emphasis role="bold">
        [</emphasis><emphasis>,</emphasis><emphasis role="bold">
        </emphasis><emphasis>relationship </emphasis><emphasis role="bold">]);</emphasis></para>

        <para><emphasis>primary</emphasis> A null-terminated string containing
        the logical filename of the primary file.</para>

        <para><emphasis>secondary</emphasis> A null-terminated string
        containing the logical filename of the secondary file.</para>

        <para><emphasis>primaryfields</emphasis> A null-terminated string
        containing the name of the primary key field for the
        <emphasis>primary</emphasis> file. The value “__fileposition__”
        indicates the <emphasis>secondary</emphasis> is an INDEX that must use
        FETCH to access non-keyed fields. If omitted, the default is an empty
        string.</para>

        <para><emphasis>secondaryfields</emphasis> A null-terminated string
        containing the name of the foreign key field relating to the
        <emphasis>primary</emphasis> file. If omitted, the default is an empty
        string.</para>

        <para><emphasis>relationship</emphasis> A null-terminated string
        containing either “link” or “view” indicating the type of relationship
        between the <emphasis>primary</emphasis> and
        <emphasis>secondary</emphasis> files. If omitted, the default is
        “link.”</para>

        <para>Return: FileRelationshipList returns a dataset in the
        FsFileRelationshipRecord format.</para>

        <para>The <emphasis role="bold">FileRelationshipList</emphasis>
        function returns a list file relationships between the
        <emphasis>primary</emphasis> and <emphasis>secondary</emphasis> files.
        The return records are structured in the FsFileRelationshipRecord
        format:</para>

        <para>EXPORT FsFileRelationshipRecord := RECORD</para>

        <para>STRING primaryfile {MAXLENGTH(1023)};</para>

        <para>STRING secondaryfile {MAXLENGTH(1023)};</para>

        <para>STRING primaryflds {MAXLENGTH(1023)};</para>

        <para>STRING secondaryflds {MAXLENGTH(1023)};</para>

        <para>STRING kind {MAXLENGTH(16)};</para>

        <para>STRING cardinality {MAXLENGTH(16)};</para>

        <para>BOOLEAN payload;</para>

        <para>STRING description {MAXLENGTH(1023)};</para>

        <para>END;</para>

        <para>Example:</para>

        <programlisting>OUTPUT(fileServices.FileRelationshipList('names', 'inquiries'));
See Also:  AddFileRelationship
</programlisting>
      </sect2>

      <sect2 id="RemoveFileRelationship">
        <title><emphasis role="bold">RemoveFileRelationship</emphasis></title>

        <para><emphasis role="bold">FileServices.RemoveFileRelationship(</emphasis><emphasis>
        primary, secondary,</emphasis><emphasis> </emphasis><emphasis role="bold">[</emphasis><emphasis>, primaryfields </emphasis><emphasis role="bold">]</emphasis><emphasis> </emphasis><emphasis role="bold">[</emphasis><emphasis>, secondaryfields
        </emphasis><emphasis role="bold">]</emphasis><emphasis role="bold">
        [</emphasis><emphasis>,</emphasis><emphasis role="bold">
        </emphasis><emphasis>relationship </emphasis><emphasis role="bold">]);</emphasis></para>

        <para><emphasis>primary</emphasis> A null-terminated string containing
        the logical filename of the primary file.</para>

        <para><emphasis>secondary</emphasis> A null-terminated string
        containing the logical filename of the secondary file.</para>

        <para><emphasis>primaryfields</emphasis> A null-terminated string
        containing the name of the primary key field for the
        <emphasis>primary</emphasis> file. The value “__fileposition__”
        indicates the <emphasis>secondary</emphasis> is an INDEX that must use
        FETCH to access non-keyed fields. If omitted, the default is an empty
        string.</para>

        <para><emphasis>secondaryfields</emphasis> A null-terminated string
        containing the name of the foreign key field relating to the
        <emphasis>primary</emphasis> file. If omitted, the default is an empty
        string.</para>

        <para><emphasis>relationship</emphasis> A null-terminated string
        containing either “link” or “view” indicating the type of relationship
        between the <emphasis>primary</emphasis> and
        <emphasis>secondary</emphasis> files. If omitted, the default is
        “link.”</para>

        <para>The <emphasis role="bold">RemoveFileRelationship</emphasis>
        function removes a file relationshuip between the
        <emphasis>primary</emphasis> and <emphasis>secondary</emphasis>
        files.</para>

        <para>Example:</para>

        <programlisting>fileServices.RemoveFileRelationship('names', 'inquiries');
See Also:  AddFileRelationship
</programlisting>
      </sect2>
    </sect1>

    <sect1 id="Monitoring_Functions">
      <title><emphasis>Monitoring Functions</emphasis></title>

      <sect2 id="MonitorFile">
        <title><emphasis role="bold">MonitorFile</emphasis></title>

        <para><emphasis role="bold">FileServices.MonitorFile(</emphasis><emphasis> event,
        </emphasis><emphasis role="bold">[</emphasis><emphasis> ip
        </emphasis><emphasis role="bold">] , </emphasis><emphasis>filename,
        </emphasis><emphasis role="bold">
        [</emphasis><emphasis>,subdirs</emphasis><emphasis role="bold">]
        [</emphasis><emphasis>,shotcount</emphasis><emphasis role="bold">]
        [</emphasis><emphasis>,espserverIPport</emphasis><emphasis role="bold">] )</emphasis><emphasis>dfuwuid </emphasis><emphasis role="bold">:= FileServices.fMonitorFile(</emphasis><emphasis> event,
        </emphasis><emphasis role="bold">[</emphasis><emphasis> ip
        </emphasis><emphasis role="bold">] , </emphasis><emphasis>filename,
        </emphasis><emphasis role="bold">
        [</emphasis><emphasis>,subdirs</emphasis><emphasis role="bold">]
        [</emphasis><emphasis>,shotcount</emphasis><emphasis role="bold">]
        [</emphasis><emphasis>,espserverIPport</emphasis><emphasis role="bold">] );</emphasis></para>

        <para><emphasis>event</emphasis> A null-terminated string containing
        the user-defined name of the event to fire when the
        <emphasis>filename</emphasis> appears. This value is used as the first
        parameter to the EVENT function.</para>

        <para><emphasis>ip</emphasis> Optional. A null-terminated string
        containing the ip address for the file to monitor. This is typically a
        landing zone. This may be omitted only if the
        <emphasis>filename</emphasis> parameter contains a complete
        URL.</para>

        <para><emphasis>filename</emphasis> A null-terminated string
        containing the full path to the file to monitor. This may contain
        wildcard characters (* and ?).</para>

        <para><emphasis>subdirs</emphasis> Optional. A boolean value
        indicating whether to include files in sub-directories that match the
        wildcard mask when the <emphasis>filename</emphasis> contains
        wildcards. If omitted, the default is false.</para>

        <para><emphasis>shotcount</emphasis> Optional. An integer value
        indicating the number of times to generate the event before the
        monitoring job completes. A negative one (-1) value indicates the
        monitoring job continues until manually aborted. If omitted, the
        default is 1.</para>

        <para><emphasis>espserverIPport</emphasis> Optional. A null-terminated
        string containing the protocol, IP, port, and directory, or the DNS
        equivalent, of the ESP server program. This is usually the same IP and
        port as ECL Watch, with “/FileSpray” appended. If omitted, the default
        is the value contained in the lib_system.ws_fs_server
        attribute.</para>

        <para><emphasis>dfuwuid</emphasis> The attribute name to recieve the
        null-terminated string containing the DFU workunit ID (DFUWUID)
        generated for the monitoring job.</para>

        <para>Return:<emphasis> </emphasis>fMonitorFile returns a
        null-terminated string containing the DFU workunit ID
        (DFUWUID).</para>

        <para>The <emphasis role="bold">MonitorFile </emphasis>function
        creates a file monitor job in the DFU Server. Once the job is received
        it goes into a 'monitoring' mode (which can be seen in the eclwatch
        DFU Workunit display), which polls at a fixed interval (settable by
        configenv but default 15 mins). If an appropriately named file arrives
        in this interval it will fire the <emphasis>event</emphasis> with the
        name of the triggering object as the event subtype (see the EVENT
        function).</para>

        <para>This process continues until either:</para>

        <para>1) The <emphasis>shotcount</emphasis> number of events have been
        generated.</para>

        <para>2) The user aborts the DFU workunit.</para>

        <para>The FileServices.AbortDfuWorkunit and
        FileServices.WaitDfuWorkunit functions can be used to abort or wait
        for the DFU job by passing them the returned
        <emphasis>dfuwuid</emphasis>.</para>

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

        <para>1) Events are only generated when the monitor job starts or
        subsequently on the polling interval.</para>

        <para>2) Note that the <emphasis>event</emphasis> is generated if the
        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>3) 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.</para>

        <para>Example:</para>

        <programlisting>EventName := 'MyFileEvent';
FileName  := 'c:\\test\\myfile';
LZ := '10.150.50.14';
FileServices.MonitorFile(EventName,LZ,FileName);
OUTPUT('File Found') : WHEN(EVENT(EventName,'*'),COUNT(1));
</programlisting>
      </sect2>

      <sect2 id="MonitorLogicalFileName">
        <title><emphasis role="bold">MonitorLogicalFileName</emphasis></title>

        <para><emphasis role="bold">FileServices.MonitorLogicalFileName(</emphasis><emphasis>
        event, </emphasis><emphasis role="bold">
        </emphasis><emphasis>filename, </emphasis><emphasis role="bold">
        [</emphasis><emphasis>, shotcount </emphasis><emphasis role="bold">]
        [</emphasis><emphasis>, espserverIPport </emphasis><emphasis role="bold">] )</emphasis><emphasis>dfuwuid </emphasis><emphasis role="bold">:=
        FileServices.fMonitorLogicalFileName(</emphasis><emphasis> event,
        </emphasis><emphasis role="bold"> </emphasis><emphasis>filename,
        </emphasis><emphasis role="bold"> [</emphasis><emphasis>, shotcount
        </emphasis><emphasis role="bold">] [</emphasis><emphasis>,
        espserverIPport </emphasis><emphasis role="bold">]
        );</emphasis></para>

        <para><emphasis>event</emphasis> A null-terminated string containing
        the user-defined name of the event to fire when the
        <emphasis>filename</emphasis> appears. This value is used as the first
        parameter to the EVENT function.</para>

        <para><emphasis>filename</emphasis> A null-terminated string
        containing the name of the logical file in the DFU to monitor. This
        may contain wildcard characters ( * and ?).</para>

        <para><emphasis>shotcount</emphasis> Optional. An integer value
        indicating the number of times to generate the event before the
        monitoring job completes. A negative one (-1) value indicates the
        monitoring job continues until manually aborted. If omitted, the
        default is 1.</para>

        <para><emphasis>espserverIPport</emphasis> Optional. A null-terminated
        string containing the protocol, IP, port, and directory, or the DNS
        equivalent, of the ESP server program. This is usually the same IP and
        port as ECL Watch, with “/FileSpray” appended. If omitted, the default
        is the value contained in the lib_system.ws_fs_server
        attribute.</para>

        <para><emphasis>dfuwuid</emphasis> The attribute name to recieve the
        null-terminated string containing the DFU workunit ID (DFUWUID)
        generated for the monitoring job.</para>

        <para>Return:<emphasis> </emphasis>fMonitorLogicalFileName returns a
        null-terminated string containing the DFU workunit ID
        (DFUWUID).</para>

        <para>The <emphasis role="bold">MonitorLogicalFileName
        </emphasis>function creates a file monitor job in the DFU Server. Once
        the job is received it goes into a 'monitoring' mode (which can be
        seen in the eclwatch DFU Workunit display), which polls at a fixed
        interval (settable by configenv but default 15 mins). If an
        appropriately named file arrives in this interval it will fire the
        <emphasis>event</emphasis> with the name of the triggering object as
        the event subtype (see the EVENT function).</para>

        <para>This process continues until either:</para>

        <para>1) The <emphasis>shotcount</emphasis> number of events have been
        generated.</para>

        <para>2) The user aborts the DFU workunit.</para>

        <para>The FileServices.AbortDfuWorkunit and
        FileServices.WaitDfuWorkunit functions can be used to abort or wait
        for the DFU job by passing them the returned
        <emphasis>dfuwuid</emphasis>.</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>Example:</para>

        <programlisting>EventName := 'MyFileEvent';
FileName  := 'test::myfile';
IF (FileServices.FileExists(FileName),
         FileServices.DeleteLogicalFile(FileName));
FileServices.MonitorLogicalFileName(EventName,FileName);
OUTPUT('File Created') : WHEN(EVENT(EventName,'*'),COUNT(1));
    
rec       := RECORD
   STRING10 key;
     STRING10 val;
          END;
afile := DATASET([{ 'A', '0'}], rec);
OUTPUT(afile,,FileName);
</programlisting>
      </sect2>
    </sect1>

    <sect1 id="File_Spray_and_Despray">
      <title><emphasis>File Spray and Despray</emphasis></title>

      <sect2 id="AbortDfuWorkunit">
        <title><emphasis role="bold">AbortDfuWorkunit</emphasis></title>

        <para><emphasis role="bold">FileServices.AbortDfuWorkunit(</emphasis><emphasis>
        dfuwuid</emphasis><emphasis role="bold">
        [</emphasis><emphasis>,espserverIPport </emphasis><emphasis role="bold">] )</emphasis></para>

        <para><emphasis>dfuwuid</emphasis> A null-terminated string containing
        the DFU workunit ID (DFUWUID) for the job to abort. This value is
        returned by the “leading-f” versions of the Copy, DKC, SprayFixed,
        SprayVariable, SprayXML, and Despray FileServices functions.</para>

        <para><emphasis>espserverIPport</emphasis> Optional. A null-terminated
        string containing the protocol, IP, port, and directory, or the DNS
        equivalent, of the ESP server program. This is usually the same IP and
        port as ECL Watch, with “/FileSpray” appended. If omitted, the default
        is the value contained in the lib_system.ws_fs_server
        attribute.</para>

        <para>The <emphasis role="bold">AbortDfuWorkunit</emphasis> function
        aborts the specified DFU workunit. Typically that workunit will have
        been launched with its <emphasis>timeout </emphasis>parameter set to
        zero (0).</para>

        <para>Example:</para>

        <programlisting>FileServices.AbortDfuWorkunit('D20051108-143758');
</programlisting>
      </sect2>

      <sect2 id="Copy">
        <title><emphasis role="bold">Copy</emphasis></title>

        <para><emphasis role="bold">FileServices.Copy(</emphasis><emphasis>
        logicalname, destinationGroup</emphasis><emphasis role="bold">,
        </emphasis><emphasis>destinationLogicalname, </emphasis><emphasis role="bold"> [</emphasis><emphasis>,scrDali</emphasis><emphasis role="bold">] [</emphasis><emphasis>,timeout</emphasis><emphasis role="bold">] [</emphasis><emphasis>,espserverIPport
        </emphasis><emphasis role="bold">]</emphasis><emphasis role="bold">
        [</emphasis><emphasis>,maxConnections</emphasis><emphasis role="bold">]
        [</emphasis><emphasis>,allowoverwrite</emphasis><emphasis role="bold">]</emphasis><emphasis role="bold">
        [</emphasis><emphasis>,replicate</emphasis><emphasis role="bold">]
        [</emphasis><emphasis>,asSuperfile</emphasis><emphasis role="bold">]
        );</emphasis><emphasis>dfuwuid</emphasis><emphasis role="bold"> :=
        FileServices.fCopy(</emphasis><emphasis> logicalname,
        destinationGroup</emphasis><emphasis role="bold">,</emphasis><emphasis role="bold"> </emphasis><emphasis>destinationLogicalname,
        </emphasis><emphasis role="bold">
        [</emphasis><emphasis>,scrDali</emphasis><emphasis role="bold">]
        [</emphasis><emphasis>,timeout</emphasis><emphasis role="bold">]
        [</emphasis><emphasis>,espserverIPport </emphasis><emphasis role="bold">]</emphasis><emphasis role="bold">
        [</emphasis><emphasis>,maxConnections</emphasis><emphasis role="bold">]
        [</emphasis><emphasis>,allowoverwrite</emphasis><emphasis role="bold">]</emphasis><emphasis role="bold">
        [</emphasis><emphasis>,replicate</emphasis><emphasis role="bold">]
        [</emphasis><emphasis>,asSuperfile</emphasis><emphasis role="bold">]
        );</emphasis></para>

        <para><emphasis>logicalname</emphasis> A null-terminated string
        containing the logical name of the file.</para>

        <para><emphasis>destinationGroup</emphasis> A null-terminated string
        containing the destination cluster for the file.</para>

        <para><emphasis>destinationLogicalname</emphasis>A null-terminated
        string containing the new logical name of the file.</para>

        <para><emphasis>srcDali</emphasis> Optional. A null-terminated string
        containing the IP and Port of the Dali containing the file to copy. If
        omitted, the default is an intra-Dali copy.</para>

        <para><emphasis>timeout</emphasis> Optional. An integer value
        indicating the timeout setting. If omitted, the default is -1. If set
        to zero (0), execution control returns immediately to the ECL workunit
        without waiting for the DFU workunit to complete.</para>

        <para><emphasis>espserverIPport</emphasis> Optional. A null-terminated
        string containing the protocol, IP, port, and directory, or the DNS
        equivalent, of the ESP server program. This is usually the same IP and
        port as ECL Watch, with “/FileSpray” appended. If omitted, the default
        is the value contained in the lib_system.ws_fs_server
        attribute.</para>

        <para><emphasis>maxConnections</emphasis> Optional. An integer
        specifying the maximum number of connections. If omitted, the default
        is one (1).</para>

        <para><emphasis>allowoverwrite</emphasis> Optional. A boolean TRUE or
        FALSE flag indicating whether to allow the new file to overwrite an
        existing file of the same name. If omitted, the default is
        FALSE.</para>

        <para><emphasis>replicate</emphasis> Optional. A boolean TRUE or FALSE
        flag indicating whether to automatically replicate the new file. If
        omitted, the default is FALSE.</para>

        <para><emphasis>asSuperfile</emphasis> Optional. A boolean TRUE or
        FALSE flag indicating whether to treat the file as a superfile. If
        omitted, the default is FALSE. If TRUE and the file to copy is a
        superfile, then the operation creates a superfile on the target,
        creating subfiles as needed while overwriting only those already
        existing subfiles whose content has changed. If FALSE and the file to
        copy is a superfile, then the operation consolidates all the superfile
        content into a single logical file on the target, not a
        superfile.</para>

        <para><emphasis>dfuwuid</emphasis> The attribute name to recieve the
        null-terminated string containing the DFU workunit ID (DFUWUID)
        generated for the job.</para>

        <para>Return:<emphasis> </emphasis>fCopy returns a null-terminated
        string containing the DFU workunit ID (DFUWUID).</para>

        <para>The <emphasis role="bold">Copy </emphasis>function takes a
        logical file and copies it to another logical file. This may be done
        within the same cluster, or to another cluster, or to a cluster in a
        completely separate Dali.</para>

        <para>Example:</para>

        <programlisting>FileServices.Copy('OUT::MyFile','400way','OUT::MyNewFile');
</programlisting>
      </sect2>

      <sect2 id="DeSpray">
        <title><emphasis role="bold">DeSpray</emphasis></title>

        <para><emphasis role="bold">FileServices.DeSpray(</emphasis><emphasis>
        logicalname, destinationIP </emphasis><emphasis role="bold">,
        </emphasis><emphasis>destinationpath, </emphasis><emphasis role="bold">[</emphasis><emphasis>,timeout</emphasis><emphasis role="bold">]</emphasis><emphasis role="bold">
        [</emphasis><emphasis>,espserverIPport </emphasis><emphasis role="bold">]
        [</emphasis><emphasis>,maxConnections</emphasis><emphasis role="bold">]
        [</emphasis><emphasis>,allowoverwrite</emphasis><emphasis role="bold">])</emphasis><emphasis>dfuwuid</emphasis><emphasis role="bold"> := FileServices.fDeSpray(</emphasis><emphasis>
        logicalname, destinationIP </emphasis><emphasis role="bold">,
        </emphasis><emphasis>destinationpath, </emphasis><emphasis role="bold"> [</emphasis><emphasis>,timeout</emphasis><emphasis role="bold">] [</emphasis><emphasis>,espserverIPport
        </emphasis><emphasis role="bold">]
        [</emphasis><emphasis>,maxConnections</emphasis><emphasis role="bold">]</emphasis><emphasis role="bold">
        [</emphasis><emphasis>,allowoverwrite</emphasis><emphasis role="bold">]);</emphasis></para>

        <para><emphasis>logicalname</emphasis> A null-terminated string
        containing the logical name of the file.</para>

        <para><emphasis>destinationIP</emphasis> A null-terminated string
        containing the destination IP address of the file.</para>

        <para><emphasis>destinationpath</emphasis> A null-terminated string
        containing the path and name of the file.</para>

        <para><emphasis>timeout</emphasis> Optional. An integer value
        indicating the timeout setting. If omitted, the default is -1. If set
        to zero (0), execution control returns immediately to the ECL workunit
        without waiting for the DFU workunit to complete.</para>

        <para><emphasis>espserverIPport</emphasis> Optional. A null-terminated
        string containing the protocol, IP, port, and directory, or the DNS
        equivalent, of the ESP server program. This is usually the same IP and
        port as ECL Watch, with “/FileSpray” appended. If omitted, the default
        is the value contained in the lib_system.ws_fs_server
        attribute.</para>

        <para><emphasis>maxConnections</emphasis> Optional. An integer
        specifying the maximum number of connections. If omitted, the default
        is one (1).</para>

        <para><emphasis>allowoverwrite</emphasis> Optional. A boolean TRUE or
        FALSE flag indicating whether to allow the new file to overwrite an
        existing file of the same name. If omitted, the default is
        FALSE.</para>

        <para><emphasis>dfuwuid</emphasis> The attribute name to recieve the
        null-terminated string containing the DFU workunit ID (DFUWUID)
        generated for the job.</para>

        <para>Return:<emphasis> </emphasis>fDeSpray returns a null-terminated
        string containing the DFU workunit ID (DFUWUID).</para>

        <para>The <emphasis role="bold">DeSpray </emphasis>function takes a
        logical file and desprays it (combines all parts on each supercomputer
        node into a single physical file) to the landing zone.</para>

        <para>Example:</para>

        <programlisting>FileServices.DeSpray('OUT::MyFile',
      '10.150.50.14',
        'c:\\OutputData\\MyFile.txt',
      -1,
      'http://10.150.50.12:8010/FileSpray');
</programlisting>
      </sect2>

      <sect2 id="DKC">
        <title><emphasis role="bold">DKC</emphasis></title>

        <para><emphasis role="bold">FileServices.DKC(</emphasis><emphasis>
        logicalname, destinationIP </emphasis><emphasis role="bold">,
        </emphasis><emphasis>destinationpath, </emphasis><emphasis role="bold">[</emphasis><emphasis>,timeout</emphasis><emphasis role="bold">]</emphasis><emphasis role="bold">
        [</emphasis><emphasis>,espserverIPport </emphasis><emphasis role="bold">]
        [</emphasis><emphasis>,maxConnections</emphasis><emphasis role="bold">]
        [</emphasis><emphasis>,allowoverwrite</emphasis><emphasis role="bold">])</emphasis><emphasis>dfuwuid</emphasis><emphasis role="bold"> := FileServices.fDKC(</emphasis><emphasis> logicalname,
        destinationIP </emphasis><emphasis role="bold">,
        </emphasis><emphasis>destinationpath, </emphasis><emphasis role="bold"> [</emphasis><emphasis>,timeout</emphasis><emphasis role="bold">] [</emphasis><emphasis>,espserverIPport
        </emphasis><emphasis role="bold">]
        [</emphasis><emphasis>,maxConnections</emphasis><emphasis role="bold">]</emphasis><emphasis role="bold">
        [</emphasis><emphasis>,allowoverwrite</emphasis><emphasis role="bold">]);</emphasis></para>

        <para><emphasis>logicalname</emphasis> A null-terminated string
        containing the logical name of the file.</para>

        <para><emphasis>destinationIP</emphasis> A null-terminated string
        containing the destination IP address of the file.</para>

        <para><emphasis>destinationpath</emphasis> A null-terminated string
        containing the path and name of the file.</para>

        <para><emphasis>timeout</emphasis> Optional. An integer value
        indicating the timeout setting. If omitted, the default is -1. If set
        to zero (0), execution control returns immediately to the ECL workunit
        without waiting for the DFU workunit to complete.</para>

        <para><emphasis>espserverIPport</emphasis> Optional. A null-terminated
        string containing the protocol, IP, port, and directory, or the DNS
        equivalent, of the ESP server program. This is usually the same IP and
        port as ECL Watch, with “/FileSpray” appended. If omitted, the default
        is the value contained in the lib_system.ws_fs_server
        attribute.</para>

        <para><emphasis>maxConnections</emphasis> Optional. An integer
        specifying the maximum number of connections. If omitted, the default
        is one (1).</para>

        <para><emphasis>allowoverwrite</emphasis> Optional. A boolean TRUE or
        FALSE flag indicating whether to allow the new file to overwrite an
        existing file of the same name. If omitted, the default is
        FALSE.</para>

        <para><emphasis>dfuwuid</emphasis> The attribute name to recieve the
        null-terminated string containing the DFU workunit ID (DFUWUID)
        generated for the job.</para>

        <para>Return:<emphasis> </emphasis>fDKC returns a null-terminated
        string containing the DFU workunit ID (DFUWUID).</para>

        <para>The <emphasis role="bold">DKC </emphasis>function takes an INDEX
        file and desprays it (combines all parts on each supercomputer node
        into a single physical file) to the landing zone.</para>

        <para>Example:</para>

        <programlisting>FileServices.DKC('OUT::MyIndex',
      '10.150.50.14',
        'c:\\OutputData\\MyIndex.txt',
      -1,
      'http://10.150.50.12:8010/FileSpray');
</programlisting>
      </sect2>

      <sect2 id="RemotePull">
        <title><emphasis role="bold">RemotePull</emphasis></title>

        <para><emphasis role="bold">FileServices.RemotePull(</emphasis><emphasis> remoteURL,
        sourcelogicalname, destinationGroup</emphasis><emphasis role="bold">,</emphasis><emphasis role="bold">
        </emphasis><emphasis>destinationlogicalname, </emphasis><emphasis role="bold">[</emphasis><emphasis>,timeout</emphasis><emphasis role="bold">]
        [</emphasis><emphasis>,maxConnections</emphasis><emphasis role="bold">]</emphasis><emphasis role="bold">
        [</emphasis><emphasis>,allowoverwrite</emphasis><emphasis role="bold">] [</emphasis><emphasis>,replicate</emphasis><emphasis role="bold">] [</emphasis><emphasis>,asSuperfile</emphasis><emphasis role="bold">])</emphasis><emphasis>dfuwuid</emphasis><emphasis role="bold"> := FileServices.RemotePull(</emphasis><emphasis>
        remoteURL, sourcelogicalname,</emphasis><emphasis> destinationGroup
        </emphasis><emphasis role="bold">,
        </emphasis><emphasis>destinationlogicalname, </emphasis><emphasis role="bold">[</emphasis><emphasis>,timeout</emphasis><emphasis role="bold">]</emphasis><emphasis role="bold">
        [</emphasis><emphasis>,maxConnections</emphasis><emphasis role="bold">]
        [</emphasis><emphasis>,allowoverwrite</emphasis><emphasis role="bold">] [</emphasis><emphasis>,replicate</emphasis><emphasis role="bold">]</emphasis><emphasis role="bold">
        [</emphasis><emphasis>,asSuperfile</emphasis><emphasis role="bold">]);</emphasis></para>

        <para><emphasis>remoteURL</emphasis> A null-terminated string
        containing the protocol, IP, port, and directory, or the DNS
        equivalent, of the remote ESP server program. This is usually the same
        IP and port as its ECL Watch, with “/FileSpray” appended.</para>

        <para><emphasis>sourcelogicalname</emphasis> A null-terminated string
        containing the local logical name of the file.</para>

        <para><emphasis>destinationGroup</emphasis> A null-terminated string
        containing the name of the destination cluster.</para>

        <para><emphasis>destinationlogicalname</emphasis> A null-terminated
        string containing the logical name to give the file on the remote
        cluster (this must be completely specified, including the
        domain).</para>

        <para><emphasis>timeout</emphasis> Optional. An integer value
        indicating the timeout setting. If omitted, the default is -1. If set
        to zero (0), execution control returns immediately to the ECL workunit
        without waiting for the DFU workunit to complete.</para>

        <para><emphasis>maxConnections</emphasis> Optional. An integer
        specifying the maximum number of connections. If omitted, the default
        is one (1).</para>

        <para><emphasis>allowoverwrite</emphasis> Optional. A boolean TRUE or
        FALSE flag indicating whether to allow the new file to overwrite an
        existing file of the same name. If omitted, the default is
        FALSE.</para>

        <para><emphasis>replicate</emphasis> Optional. A boolean TRUE or FALSE
        flag indicating whether to automatically replicate the new file. If
        omitted, the default is FALSE.</para>

        <para><emphasis>asSuperfile</emphasis> Optional. A boolean TRUE or
        FALSE flag indicating whether to treat the file as a superfile. If
        omitted, the default is FALSE. If TRUE and the file to copy is a
        superfile, then the operation creates a superfile on the target,
        creating subfiles as needed while overwriting only those already
        existing subfiles whose content has changed. If FALSE and the file to
        copy is a superfile, then the operation consolidates all the superfile
        content into a single logical file on the target, not a
        superfile.</para>

        <para><emphasis>dfuwuid</emphasis> The attribute name to recieve the
        null-terminated string containing the DFU workunit ID (DFUWUID)
        generated for the job.</para>

        <para>Return:<emphasis> </emphasis>fRemotePull returns a
        null-terminated string containing the DFU workunit ID
        (DFUWUID).</para>

        <para>The <emphasis role="bold">RemotePull </emphasis>function
        executes on the <emphasis>remoteURL</emphasis>, copying the
        <emphasis>sourcelogicalname</emphasis> from the local environment that
        instantiated the operation to the remote environment’s
        <emphasis>destinationGroup</emphasis> cluster, giving it the
        <emphasis>destinationlogicalname</emphasis>. This is very similar to
        using the FileServices.Copy function and specifying its
        <emphasis>espserverIPport </emphasis>parameter. Since the DFU workunit
        executes on the remote DFU server, the user name authentication must
        be the same on both systems, and the use must have rights to copy
        files on both systems.</para>

        <para>Example:</para>

        <programlisting>FileServices.RemotePull('http://10.150.50.14:8010/FileSpray',
    '~THOR::LOCAL::MyFile',
    'RemoteThor',
    '~REMOTETHOR::LOCAL::MyFile');
</programlisting>
      </sect2>

      <sect2 id="SprayFixed">
        <title><emphasis role="bold">SprayFixed</emphasis></title>

        <para><emphasis role="bold">FileServices.SprayFixed(</emphasis><emphasis> sourceIP
        </emphasis><emphasis role="bold">, </emphasis><emphasis>sourcepath,
        recordsize, destinationgroup,</emphasis><emphasis>
        destinationlogicalname </emphasis><emphasis role="bold">[</emphasis><emphasis>,timeout</emphasis><emphasis role="bold">] [</emphasis><emphasis>, espserverIPport
        </emphasis><emphasis role="bold">]</emphasis><emphasis>
        </emphasis><emphasis role="bold"> [</emphasis><emphasis>,
        maxConnections </emphasis><emphasis role="bold">]
        [</emphasis><emphasis>, allowoverwrite </emphasis><emphasis role="bold">] [</emphasis><emphasis>, replicate </emphasis><emphasis role="bold">]</emphasis><emphasis role="bold"> [</emphasis><emphasis>,
        compress </emphasis><emphasis role="bold">])</emphasis><emphasis>dfuwuid</emphasis><emphasis role="bold"> := FileServices.fSprayFixed(</emphasis><emphasis>
        sourceIP </emphasis><emphasis role="bold">,
        </emphasis><emphasis>sourcepath, recordsize,</emphasis><emphasis>
        destinationgroup, destinationlogicalname </emphasis><emphasis role="bold">[</emphasis><emphasis>,timeout</emphasis><emphasis role="bold">]</emphasis><emphasis role="bold"> [</emphasis><emphasis>,
        espserverIPport </emphasis><emphasis role="bold">]</emphasis><emphasis> </emphasis><emphasis role="bold">[</emphasis><emphasis>, maxConnections
        </emphasis><emphasis role="bold">]</emphasis><emphasis role="bold">
        [</emphasis><emphasis>, allowoverwrite </emphasis><emphasis role="bold">] [</emphasis><emphasis>, replicate </emphasis><emphasis role="bold">] [</emphasis><emphasis>, compress </emphasis><emphasis role="bold">]);</emphasis></para>

        <para><emphasis>sourceIP</emphasis> A null-terminated string
        containing the IP address of the file.</para>

        <para><emphasis>sourcepath</emphasis> A null-terminated string
        containing the path and name of the file.</para>

        <para><emphasis>recordsize</emphasis> An integer containing the size
        of the records in the file.</para>

        <para><emphasis>destinationgroup</emphasis> A null-terminated string
        containing the name of the specific supercomputer within the target
        cluster.</para>

        <para><emphasis>destinationlogicalname</emphasis>A null-terminated
        string containing the logical name of the file.</para>

        <para><emphasis>timeout</emphasis> Optional. An integer value
        indicating the timeout setting. If omitted, the default is -1. If set
        to zero (0), execution control returns immediately to the ECL workunit
        without waiting for the DFU workunit to complete.</para>

        <para><emphasis>espserverIPport</emphasis> A null-terminated string
        containing the protocol, IP, port, and directory, or the DNS
        equivalent, of the ESP server program. This is usually the same IP and
        port as ECL Watch, with “/FileSpray” appended. If omitted, the default
        is the value contained in the lib_system.ws_fs_server
        attribute.</para>

        <para><emphasis>maxConnections</emphasis> Optional. An integer
        specifying the maximum number of connections. If omitted, the default
        is one (1).</para>

        <para><emphasis>allowoverwrite</emphasis> Optional. A boolean TRUE or
        FALSE flag indicating whether to allow the new file to overwrite an
        existing file of the same name. If omitted, the default is
        FALSE.</para>

        <para><emphasis>replicate</emphasis> Optional. A boolean TRUE or FALSE
        flag indicating whether to replicate the new file. If omitted, the
        default is FALSE.</para>

        <para><emphasis>compress</emphasis> Optional. A boolean TRUE or FALSE
        flag indicating whether to compress the new file. If omitted, the
        default is FALSE.</para>

        <para><emphasis>dfuwuid</emphasis> The attribute name to recieve the
        null-terminated string containing the DFU workunit ID (DFUWUID)
        generated for the job.</para>

        <para>Return:<emphasis> </emphasis>fSprayFixed returns a
        null-terminated string containing the DFU workunit ID
        (DFUWUID).</para>

        <para>The <emphasis role="bold">SprayFixed </emphasis>function takes
        fixed-format file from the landing zone and distributes it across the
        nodes of the destination supercomputer.</para>

        <para>Example:</para>

        <programlisting>FileServices.SprayFixed('10.150.50.14','c:\\InputData\\MyFile.txt',
    255,'400way','IN::MyFile',-1,
    'http://10.150.50.12:8010/FileSpray');
</programlisting>
      </sect2>

      <sect2 id="SprayVariable">
        <title><emphasis role="bold">SprayVariable</emphasis></title>

        <para><emphasis role="bold">FileServices.SprayVariable(</emphasis><emphasis> sourceIP
        </emphasis><emphasis role="bold">, </emphasis><emphasis>sourcepath ,
        </emphasis><emphasis role="bold">[</emphasis><emphasis> maxrecordsize
        </emphasis><emphasis role="bold">] </emphasis><emphasis>,
        </emphasis><emphasis role="bold"> [</emphasis><emphasis>
        srcCSVseparator </emphasis><emphasis role="bold">]
        </emphasis><emphasis>, </emphasis><emphasis role="bold">[</emphasis><emphasis> srcCSVterminator
        </emphasis><emphasis role="bold">] </emphasis><emphasis>,
        </emphasis><emphasis role="bold">[</emphasis><emphasis> srcCSVquote
        </emphasis><emphasis role="bold">] </emphasis><emphasis>,
        </emphasis><emphasis role="bold">
        </emphasis><emphasis>destinationgroup, destinationlogicalname
        </emphasis><emphasis role="bold">[</emphasis><emphasis>,timeout</emphasis><emphasis role="bold">]</emphasis><emphasis role="bold">
        [</emphasis><emphasis>,espserverIPport</emphasis><emphasis role="bold">]</emphasis><emphasis> </emphasis><emphasis role="bold">[</emphasis><emphasis>,maxConnections</emphasis><emphasis role="bold">]</emphasis><emphasis role="bold">
        [</emphasis><emphasis>,allowoverwrite</emphasis><emphasis role="bold">] [</emphasis><emphasis>,replicate</emphasis><emphasis role="bold">] [</emphasis><emphasis>, compress </emphasis><emphasis role="bold">])</emphasis><emphasis>dfuwuid</emphasis><emphasis role="bold"> := FileServices.fSprayVariable(</emphasis><emphasis>
        sourceIP </emphasis><emphasis role="bold">,
        </emphasis><emphasis>sourcepath , </emphasis><emphasis role="bold">
        [</emphasis><emphasis> maxrecordsize </emphasis><emphasis role="bold">] </emphasis><emphasis>, </emphasis><emphasis role="bold">[</emphasis><emphasis> srcCSVseparator
        </emphasis><emphasis role="bold">] </emphasis><emphasis>,
        </emphasis><emphasis role="bold">[</emphasis><emphasis>
        srcCSVterminator </emphasis><emphasis role="bold">]
        </emphasis><emphasis>, </emphasis><emphasis role="bold">
        [</emphasis><emphasis> srcCSVquote </emphasis><emphasis role="bold">]
        </emphasis><emphasis>, destinationgroup, destinationlogicalname
        </emphasis><emphasis role="bold">
        [</emphasis><emphasis>,timeout</emphasis><emphasis role="bold">]
        [</emphasis><emphasis>,espserverIPport</emphasis><emphasis role="bold">]</emphasis><emphasis> </emphasis><emphasis role="bold">[</emphasis><emphasis>,maxConnections</emphasis><emphasis role="bold">]</emphasis><emphasis role="bold">
        [</emphasis><emphasis>,allowoverwrite</emphasis><emphasis role="bold">] [</emphasis><emphasis>,replicate</emphasis><emphasis role="bold">] [</emphasis><emphasis>, compress </emphasis><emphasis role="bold">]);</emphasis></para>

        <para><emphasis>sourceIP</emphasis> A null-terminated string
        containing the IP address of the file.</para>

        <para><emphasis>sourcepath</emphasis> A null-terminated string
        containing the path and name of the file.</para>

        <para><emphasis>maxrecordsize</emphasis> Optional. An integer
        containing the maximum size of the records in the file. If omitted,
        the default is 4096.</para>

        <para><emphasis>srcCSVseparator</emphasis> Optional. A null-terminated
        string containing the CSV field separator. If omitted, the default is
        '\\,'</para>

        <para><emphasis>srcCSVterminator</emphasis>Optional. A null-terminated
        string containing the CSV record separator. If omitted, the default is
        '\\n,\\r,\\n'</para>

        <para><emphasis>srcCSVquote</emphasis> Optional. A null-terminated
        string containing the CSV quoted field delimiter. If omitted, the
        default is '\''</para>

        <para><emphasis>destinationgroup</emphasis> A null-terminated string
        containing the name of the specific supercomputer within the target
        cluster.</para>

        <para><emphasis>destinationlogicalname</emphasis>A null-terminated
        string containing the logical name of the file.</para>

        <para><emphasis>timeout</emphasis> Optional. An integer value
        indicating the timeout setting. If omitted, the default is -1. If set
        to zero (0), execution control returns immediately to the ECL workunit
        without waiting for the DFU workunit to complete.</para>

        <para><emphasis>espserverIPport</emphasis> Optional. A null-terminated
        string containing the protocol, IP, port, and directory, or the DNS
        equivalent, of the ESP server program. This is usually the same IP and
        port as ECL Watch, with “/FileSpray” appended. If omitted, the default
        is the value in the lib_system.ws_fs_server attribute.</para>

        <para><emphasis>maxConnections</emphasis> Optional. An integer
        specifying the maximum number of connections. If omitted, the default
        is one (1).</para>

        <para><emphasis>allowoverwrite</emphasis> Optional. A boolean TRUE or
        FALSE flag indicating whether to allow the new file to overwrite an
        existing file of the same name. If omitted, the default is
        FALSE.</para>

        <para><emphasis>replicate</emphasis> Optional. A boolean TRUE or FALSE
        flag indicating whether to replicate the new file. If omitted, the
        default is FALSE.</para>

        <para><emphasis>compress</emphasis> Optional. A boolean TRUE or FALSE
        flag indicating whether to compress the new file. If omitted, the
        default is FALSE.</para>

        <para><emphasis>dfuwuid</emphasis> The attribute name to recieve the
        null-terminated string containing the DFU workunit ID (DFUWUID)
        generated for the job.</para>

        <para>Return:<emphasis> </emphasis>fSprayVariable returns a
        null-terminated string containing the DFU workunit ID
        (DFUWUID).</para>

        <para>The <emphasis role="bold">SprayVariable </emphasis>function
        takes a variable length file from the landing zone and distributes it
        across the nodes of the destination supercomputer.</para>

        <para>Example:</para>

        <programlisting>FileServices.SprayVariable('10.150.50.14',
       'c:\\InputData\\MyFile.txt',
       ,,,,
       '400way',
       'IN::MyFile',
       -1,
       'http://10.150.50.12:8010/FileSpray');</programlisting>
      </sect2>

      <sect2 id="SprayXML">
        <title><emphasis role="bold">SprayXML</emphasis></title>

        <para><emphasis role="bold">FileServices.SprayXML(</emphasis><emphasis> sourceIP
        </emphasis><emphasis role="bold">, </emphasis><emphasis>sourcepath ,
        </emphasis><emphasis role="bold">[</emphasis><emphasis> maxrecordsize
        </emphasis><emphasis role="bold">] </emphasis><emphasis>,
        </emphasis><emphasis role="bold"> </emphasis><emphasis> srcRowTag
        </emphasis><emphasis role="bold"> </emphasis><emphasis>,
        </emphasis><emphasis role="bold">[</emphasis><emphasis> srcEncoding
        </emphasis><emphasis role="bold">] </emphasis><emphasis>,
        </emphasis><emphasis role="bold">
        </emphasis><emphasis>destinationgroup, destinationlogicalname
        </emphasis><emphasis role="bold">[</emphasis><emphasis>,timeout</emphasis><emphasis role="bold">]</emphasis><emphasis role="bold">
        [</emphasis><emphasis>,espserverIPport</emphasis><emphasis role="bold">]</emphasis><emphasis> </emphasis><emphasis role="bold">[</emphasis><emphasis>,maxConnections</emphasis><emphasis role="bold">]</emphasis><emphasis role="bold">
        [</emphasis><emphasis>,allowoverwrite</emphasis><emphasis role="bold">] [</emphasis><emphasis>,replicate</emphasis><emphasis role="bold">] [</emphasis><emphasis>, compress </emphasis><emphasis role="bold">])</emphasis><emphasis>dfuwuid</emphasis><emphasis role="bold"> := FileServices.fSprayXML(</emphasis><emphasis>
        sourceIP</emphasis><emphasis role="bold">,
        </emphasis><emphasis>sourcepath, </emphasis><emphasis role="bold">[</emphasis><emphasis> maxrecordsize </emphasis><emphasis role="bold">] </emphasis><emphasis>, </emphasis><emphasis role="bold">
        </emphasis><emphasis>srcRowTag</emphasis><emphasis role="bold">
        </emphasis><emphasis>, </emphasis><emphasis role="bold">[</emphasis><emphasis> srcEncoding </emphasis><emphasis role="bold">]
        </emphasis><emphasis>,destinationgroup,</emphasis><emphasis>
        destinationlogicalname </emphasis><emphasis role="bold">[</emphasis><emphasis>,timeout</emphasis><emphasis role="bold">]
        [</emphasis><emphasis>,espserverIPport</emphasis><emphasis role="bold">]</emphasis><emphasis> </emphasis><emphasis role="bold">
        [</emphasis><emphasis>,maxConnections</emphasis><emphasis role="bold">]
        [</emphasis><emphasis>,allowoverwrite</emphasis><emphasis role="bold">] [</emphasis><emphasis>,replicate</emphasis><emphasis role="bold">] [</emphasis><emphasis>, compress </emphasis><emphasis role="bold">]);</emphasis></para>

        <para><emphasis>sourceIP</emphasis> A null-terminated string
        containing the IP address of the file.</para>

        <para><emphasis>sourcepath</emphasis> A null-terminated string
        containing the path and name of the file.</para>

        <para><emphasis>maxrecordsize</emphasis> Optional. An integer
        containing the maximum size of the records in the file. If omitted,
        the default is 8192.</para>

        <para><emphasis>srcRowTag</emphasis> A null-terminated string
        containing the row delimiting XML tag.</para>

        <para><emphasis>srcEncoding</emphasis> Optional. A null-terminated
        string containing the encoding. If omitted, the default is
        'utf8'</para>

        <para><emphasis>destinationgroup</emphasis> A null-terminated string
        containing the name of the specific supercomputer within the target
        cluster.</para>

        <para><emphasis>destinationlogicalname</emphasis>A null-terminated
        string containing the logical name of the file.</para>

        <para><emphasis>timeout</emphasis> Optional. An integer value
        indicating the timeout setting. If omitted, the default is -1. If set
        to zero (0), execution control returns immediately to the ECL workunit
        without waiting for the DFU workunit to complete.</para>

        <para><emphasis>espserverIPport</emphasis> Optional. A null-terminated
        string containing the protocol, IP, port, and directory, or the DNS
        equivalent, of the ESP server program. This is usually the same IP and
        port as ECL Watch, with “/FileSpray” appended. If omitted, the default
        is the value contained in the lib_system.ws_fs_server
        attribute.</para>

        <para><emphasis>maxConnections</emphasis> Optional. An integer
        specifying the maximum number of connections. If omitted, the default
        is one (1).</para>

        <para><emphasis>allowoverwrite</emphasis> Optional. A boolean TRUE or
        FALSE flag indicating whether to allow the new file to overwrite an
        existing file of the same name. If omitted, the default is
        FALSE.</para>

        <para><emphasis>replicate</emphasis> Optional. A boolean TRUE or FALSE
        flag indicating whether to replicate the new file. If omitted, the
        default is FALSE.</para>

        <para><emphasis>compress</emphasis> Optional. A boolean TRUE or FALSE
        flag indicating whether to compress the new file. If omitted, the
        default is FALSE.</para>

        <para><emphasis>dfuwuid</emphasis> The attribute name to recieve the
        null-terminated string containing the DFU workunit ID (DFUWUID)
        generated for the job.</para>

        <para>Return:<emphasis> </emphasis>fSprayXML returns a null-terminated
        string containing the DFU workunit ID (DFUWUID).</para>

        <para>The <emphasis role="bold">SprayXML </emphasis>function takes a
        well-formed XML file from the landing zone and distributes it across
        the nodes of the destination supercomputer, producing a well-formed
        XML file on each node.</para>

        <para>Example:</para>

        <programlisting>FileServices.SprayXML('10.150.50.14','c:\\InputData\\MyFile.txt',,
      'Row',,'400way','IN::MyFile',-1,
      'http://10.150.50.12:8010/FileSpray');</programlisting>
      </sect2>

      <sect2 id="WaitDfuWorkunit">
        <title><emphasis role="bold">WaitDfuWorkunit</emphasis></title>

        <para><emphasis role="bold">FileServices.WaitDfuWorkunit(</emphasis><emphasis>
        dfuwuid</emphasis><emphasis role="bold">
        [</emphasis><emphasis>,timeout</emphasis><emphasis role="bold">]
        [</emphasis><emphasis>,espserverIPport </emphasis><emphasis role="bold">] )</emphasis></para>

        <para><emphasis>dfuwuid</emphasis> A null-terminated string containing
        the DFU workunit ID (DFUWUID) for the job to wait for. This value is
        returned by the “leading-f” versions of the Copy, DKC, SprayFixed,
        SprayVariable, SprayXML, and Despray FileServices functions.</para>

        <para><emphasis>timeout</emphasis> Optional. An integer value
        indicating the timeout setting. If omitted, the default is -1. If set
        to zero (0), execution control returns immediately to the ECL workunit
        without waiting for the DFU workunit to complete.</para>

        <para><emphasis>espserverIPport</emphasis> Optional. A null-terminated
        string containing the protocol, IP, port, and directory, or the DNS
        equivalent, of the ESP server program. This is usually the same IP and
        port as ECL Watch, with “/FileSpray” appended. If omitted, the default
        is the value contained in the lib_system.ws_fs_server
        attribute.</para>

        <para>Return:<emphasis> </emphasis>WaitDfuWorkunit returns a
        null-terminated string containing the final status string of the DFU
        workunit (such as: scheduled, queued, started, aborted, failed,
        finished, or monitoring).</para>

        <para>The <emphasis role="bold">WaitDfuWorkunit</emphasis> function
        waits for the specified DFU workunit to finish. Typically that
        workunit will have been launched with its <emphasis>timeout
        </emphasis>parameter set to zero (0).</para>

        <para>Example:</para>

        <programlisting>FileServices.WaitDfuWorkunit('D20051108-143758');</programlisting>
      </sect2>
    </sect1>

    <sect1 id="SuperFile_Management">
      <title><emphasis>SuperFile Management</emphasis></title>

      <sect2 id="CreateSuperFile">
        <title><emphasis role="bold">CreateSuperFile</emphasis></title>

        <para><emphasis role="bold">FileServices.CreateSuperFile(</emphasis><emphasis>
        superfile </emphasis><emphasis role="bold">[</emphasis><emphasis>,
        sequentialflag </emphasis><emphasis role="bold">]
        [</emphasis><emphasis>, ifdoesnotexist </emphasis><emphasis role="bold">]</emphasis><emphasis> </emphasis><emphasis role="bold">)</emphasis></para>

        <para><emphasis>superfile</emphasis> A null-terminated string
        containing the logical name of the superfile.</para>

        <para><emphasis>sequentialflag</emphasis> Optional. A boolean value
        indicating whether to the sub-files must be sequentially ordered. If
        omitted, the default is FALSE.</para>

        <para><emphasis>ifdoesnotexist</emphasis> Optional. A boolean value
        indicating whether to post an error if the
        <emphasis>superfile</emphasis> already exists. If TRUE, no error is
        posted. If omitted, the default is FALSE.</para>

        <para>Return:<emphasis> </emphasis>Null.</para>

        <para>The <emphasis role="bold">CreateSuperFile </emphasis>function
        creates an empty <emphasis>superfile</emphasis>. This function is not
        included in a superfile transaction.</para>

        <para>The <emphasis>sequentialflag</emphasis> parameter set to TRUE
        governs the unusual case where the logical numbering of sub-files must
        be sequential (for example, where all sub-files are already globally
        sorted). With <emphasis>sequentialflag</emphasis> FALSE (the default)
        the subfile parts are interleaved so the parts are found
        locally.</para>

        <para>For example, if on a 4-way cluster there are 3 files (A, B, and
        C) then the parts are as follows:</para>

        <para>A._1_of_4, B._1_of_4, and C_1_of_4 are on node 1 A._2_of_4,
        B._2_of_4, and C_2_of_4 are on node 2 A._3_of_4, B._3_of_4, and
        C_3_of_4 are on node 3 A._4_of_4, B._4_of_4, and C_4_of_4 are on node
        4</para>

        <para>Reading the superfile created with
        <emphasis>sequentialflag</emphasis> FALSE on Thor will read the parts
        in the order:</para>

        <para>[A1,B1,C1,] [A2,B2,C2,] [A3,B3,C3,] [A4,B4,C4]</para>

        <para>so the reads will all be local (i.e. A1,B1,C1 on node 1 etc).
        Setting <emphasis>sequentialflag</emphasis> to TRUE will read the
        parts in subfile order, like this:</para>

        <para>[A1,A2,A3,] [A4,B1,B2] [,B3,B4,C1,] [C2,C3,C4]</para>

        <para>so that the global order of A,B,C,D is maintained. However, the
        parts cannot all be read locally (e.g. A2 and A3 will be read on part
        1). Because of this it is much less efficient to set
        <emphasis>sequentialflag</emphasis> true, and as it is unusual anyway
        to have files that are partitioned in order, it becomes a very unusual
        option to set.</para>

        <para>Example:</para>

        <programlisting>FileServices.CreateSuperFile('~CLASS::RT::IN::SF1');</programlisting>
      </sect2>

      <sect2 id="SuperFileExists">
        <title><emphasis role="bold">SuperFileExists</emphasis></title>

        <para><emphasis role="bold">FileServices.SuperFileExists(</emphasis><emphasis>
        filename </emphasis><emphasis role="bold">)</emphasis></para>

        <para><emphasis>filename</emphasis> A null-terminated string
        containing the logical name of the superfile.</para>

        <para>Return:<emphasis> </emphasis>SuperFileExists returns a BOOLEAN
        value.</para>

        <para>The <emphasis role="bold">SuperFileExists </emphasis>function
        returns TRUE if the specified <emphasis>filename</emphasis> is present
        in the Distributed File Utility (DFU) and is a SuperFile. It returns
        FALSE if the <emphasis>filename</emphasis> does exist in the DFU but
        is not a SuperFile (i.e. is a normal DATASET—use the
        FileServices.FileExists function to detect their presence or
        absence).</para>

        <para>This function is not included in a superfile transaction.</para>

        <para>Example:</para>

        <programlisting>A := FileServices.SuperFileExists('~CLASS::RT::IN::SF1');</programlisting>
      </sect2>

      <sect2 id="DeleteSuperFile">
        <title><emphasis role="bold">DeleteSuperFile</emphasis></title>

        <para><emphasis role="bold">FileServices.DeleteSuperFile(</emphasis><emphasis>
        superfile </emphasis><emphasis role="bold">[</emphasis><emphasis>,
        subdeleteflag </emphasis><emphasis role="bold">]</emphasis><emphasis>
        </emphasis><emphasis role="bold">)</emphasis></para>

        <para><emphasis>superfile</emphasis> A null-terminated string
        containing the logical name of the superfile.</para>

        <para><emphasis>subdeleteflag</emphasis> A boolean value indicating
        whether to delete the sub-files. If omitted, the default is FALSE.
        <emphasis role="bold">This option should not be used if the
        </emphasis><emphasis role="bold">superfile</emphasis><emphasis role="bold"> contains any foreign file or foreign
        superfile.</emphasis></para>

        <para>Return:<emphasis> </emphasis>Null.</para>

        <para>The <emphasis role="bold">DeleteSuperFile </emphasis>function
        deletes the <emphasis>superfile</emphasis>.</para>

        <para>This function is not included in a superfile transaction.</para>

        <para>Example:</para>

        <programlisting>FileServices.DeleteSuperFile('~CLASS::RT::IN::SF1');</programlisting>
      </sect2>

      <sect2 id="GetSuperFileSubCount">
        <title><emphasis role="bold">GetSuperFileSubCount</emphasis></title>

        <para><emphasis role="bold">FileServices.GetSuperFileSubCount(</emphasis><emphasis>
        superfile </emphasis><emphasis role="bold">)</emphasis></para>

        <para><emphasis>superfile</emphasis> A null-terminated string
        containing the logical name of the superfile.</para>

        <para>Return:<emphasis> </emphasis>GetSuperFileSubCount returns an
        INTEGER4 value.</para>

        <para>The <emphasis role="bold">GetSuperFileSubCount
        </emphasis>function returns the number of sub-files comprising the
        <emphasis>superfile</emphasis>.</para>

        <para>This function is not included in a superfile transaction.</para>

        <para>Example:</para>

        <programlisting>A := FileServices.GetSuperFileSubCount('~CLASS::RT::IN::SF1');</programlisting>
      </sect2>

      <sect2 id="GetSuperFileSubName">
        <title><emphasis role="bold">GetSuperFileSubName</emphasis></title>

        <para><emphasis role="bold">FileServices.GetSuperFileSubName(</emphasis><emphasis>
        superfile, subfile </emphasis><emphasis role="bold">[,</emphasis><emphasis>absolutepath</emphasis><emphasis role="bold">] )</emphasis></para>

        <para><emphasis>superfile</emphasis> A null-terminated string
        containing the logical name of the superfile.</para>

        <para><emphasis>subfile</emphasis> An integer in the range of one (1)
        to the total number of sub-files in the <emphasis>superfile</emphasis>
        specifying the ordinal position of the sub-file whose name to
        return.</para>

        <para><emphasis>absolutepath</emphasis> Optional. A boolean TRUE/FALSE
        to indicate whether to prepend a tilde (~) to the resulting foreign
        logical file name. If omitted, the default is FALSE.</para>

        <para>Return:<emphasis> </emphasis>GetSuperFileSubName returns a
        VARSTRING value.</para>

        <para>The <emphasis role="bold">GetSuperFileSubName
        </emphasis>function returns the logical name of the specified
        <emphasis>subfile</emphasis> in the
        <emphasis>superfile</emphasis>.</para>

        <para>This function is not included in a superfile transaction.</para>

        <para>Example:</para>

        <programlisting>A := FileServices.GetSuperFileSubName('~CLASS::RT::IN::SF1', 1);
   //get name of first sub-file
//this example gets the name of the first sub-file in
// a foreign superfile
sf := '~thor_data400::BASE::Business_Header';
sub := FileServices.GetSuperFileSubName(  FileServices.ForeignLogicalFileName (sf,
         '10.150.29.161',
         TRUE),
  1,TRUE);
OUTPUT(FileServices.ForeignLogicalFileName(sub,''));</programlisting>
      </sect2>

      <sect2 id="LogicalFileSuperOwners">
        <title><emphasis role="bold">LogicalFileSuperOwners</emphasis></title>

        <para><emphasis role="bold">FileServices.LogicalFileSuperOwners(</emphasis><emphasis>
        </emphasis><emphasis role="bold"> </emphasis><emphasis>filename
        </emphasis><emphasis role="bold"> )</emphasis></para>

        <para><emphasis>filename</emphasis> A null-terminated string
        containing the logical name of the file.</para>

        <para>Return:<emphasis> </emphasis>LogicalFileSuperOwners returns a
        dataset in the following format:</para>

        <para>EXPORT FsLogicalFileNameRecord := RECORD</para>

        <para>STRING name;</para>

        <para>END;</para>

        <para>The <emphasis role="bold">LogicalFileSuperOwners
        </emphasis>function returns a list of the logical filenames of all the
        SuperFiles that contain the <emphasis>filename</emphasis> as a
        sub-file.</para>

        <para>This function is not included in a superfile transaction.</para>

        <para>Example:</para>

        <programlisting>OUTPUT(FileServices.LogicalFileSuperowners('~CLASS::RT::SF::Daily1'));
  //returns all SuperFiles that “own” the Daily1 file</programlisting>
      </sect2>

      <sect2 id="LogicalFileSuperSubList">
        <title><emphasis role="bold">LogicalFileSuperSubList</emphasis></title>

        <para><emphasis role="bold">FileServices.LogicalFileSuperSubList(</emphasis><emphasis>
        </emphasis><emphasis role="bold">)</emphasis></para>

        <para>Return:<emphasis> </emphasis>LogicalFileSuperSubList returns a
        dataset in the following format:</para>

        <para>EXPORT FsLogicalSuperSubRecord := RECORD</para>

        <para>STRING supername{MAXLENGTH(255)};</para>

        <para>STRING subname{MAXLENGTH(255)};</para>

        <para>END;</para>

        <para>The <emphasis role="bold">LogicalFileSuperSubList
        </emphasis>function returns a list of the logical filenames of all the
        SuperFiles and their component sub-files.</para>

        <para>This function is not included in a superfile transaction.</para>

        <para>Example:</para>

        <programlisting>OUTPUT(FileServices.LogicalFileSuperSubList());
  //returns all SuperFiles and their sub-files</programlisting>
      </sect2>

      <sect2 id="SuperFileContents">
        <title><emphasis role="bold">SuperFileContents</emphasis></title>

        <para><emphasis role="bold">FileServices.SuperFileContents(</emphasis><emphasis>
        </emphasis><emphasis role="bold"> </emphasis><emphasis>filename
        </emphasis><emphasis role="bold">[</emphasis><emphasis>,
        recurse</emphasis><emphasis role="bold"> ] )</emphasis></para>

        <para><emphasis>filename</emphasis> A null-terminated string
        containing the logical name of the SuperFile.</para>

        <para><emphasis>recurse</emphasis> A boolean flag indicating whether
        to expand nested SuperFiles withinthe filename so that only logical
        files are returned. If omitted, the default is FALSE.</para>

        <para>Return:<emphasis> </emphasis>SuperFileContents returns a dataset
        in the following format:</para>

        <para>EXPORT FsLogicalFileNameRecord := RECORD</para>

        <para>STRING name;</para>

        <para>END;</para>

        <para>The <emphasis role="bold">SuperFileContents </emphasis>function
        returns a list of the logical filenames of all the sub-files in the
        <emphasis>filename</emphasis>.</para>

        <para>This function is not included in a superfile transaction.</para>

        <para>Example:</para>

        <programlisting>OUTPUT(FileServices.SuperFileContents('~CLASS::RT::SF::Daily'));
  //returns all files in the SuperFile</programlisting>
      </sect2>

      <sect2 id="FindSuperFileSubName">
        <title><emphasis role="bold">FindSuperFileSubName</emphasis></title>

        <para><emphasis role="bold">FileServices.FindSuperFileSubName(</emphasis><emphasis>
        superfile, subfile </emphasis><emphasis role="bold">)</emphasis></para>

        <para><emphasis>superfile</emphasis> A null-terminated string
        containing the logical name of the superfile.</para>

        <para><emphasis>subfile</emphasis> A null-terminated string containing
        the logical name of the sub-file.</para>

        <para>Return:<emphasis> </emphasis>FindSuperFileSubName returns an
        INTEGER4 value.</para>

        <para>The <emphasis role="bold">FindSuperFileSubName
        </emphasis>function returns the ordinal position of the specified
        <emphasis>subfile</emphasis> in the
        <emphasis>superfile</emphasis>.</para>

        <para>This function is not included in a superfile transaction.</para>

        <para>Example:</para>

        <programlisting>A := FileServices.GetSuperFileSubName('~CLASS::RT::IN::SF1', 'Sue');    //get position of sub-file Sue</programlisting>
      </sect2>

      <sect2 id="StartSuperFileTransaction">
        <title><emphasis role="bold">StartSuperFileTransaction</emphasis></title>

        <para><emphasis role="bold">FileServices.StartSuperFileTransaction(</emphasis><emphasis>
        </emphasis><emphasis role="bold">)</emphasis></para>

        <para>Return:<emphasis> </emphasis>Null.</para>

        <para>The <emphasis role="bold">StartSuperFileTransaction
        </emphasis>function begins a transaction frame for superfile
        maintenance. The transaction frame is terminated by calling the
        FinishSuperFileTransaction function. Within the transaction frame,
        multiple superfiles may be maintained by adding, removing, clearing,
        swapping, and replacing sub-files.</para>

        <para>The FinishSuperFileTransaction function does an automatic
        rollback of the transaction if any error or failure occurs during the
        transaction frame. If no error occurs, then the commit or rollback of
        the transaction is controlled by the <emphasis>rollback</emphasis>
        parameter to the FinishSuperFileTransaction function.</para>

        <para>Example:</para>

        <programlisting>FileServices.StartSuperFileTransaction();</programlisting>
      </sect2>

      <sect2 id="AddSuperFile">
        <title><emphasis role="bold">AddSuperFile</emphasis></title>

        <para><emphasis role="bold">FileServices.AddSuperFile(</emphasis><emphasis> superfile,
        subfile </emphasis><emphasis role="bold">[</emphasis><emphasis>, atpos
        </emphasis><emphasis role="bold">] [</emphasis><emphasis>, addcontent
        </emphasis><emphasis role="bold">] [</emphasis><emphasis>,strict
        </emphasis><emphasis role="bold">])</emphasis></para>

        <para><emphasis>superfile</emphasis> A null-terminated string
        containing the logical name of the superfile.</para>

        <para><emphasis>subfile</emphasis> A null-terminated string containing
        the logical name of the sub-file. Ths may be another superfile.</para>

        <para><emphasis>atpos</emphasis> An integer specifying the position of
        the <emphasis>subfile</emphasis> in the
        <emphasis>superfile</emphasis>. If omitted, the default is zero (0),
        which places the <emphasis>subfile </emphasis>at the end of the
        <emphasis>superfile</emphasis>.</para>

        <para><emphasis>addcontent</emphasis> A boolean flag specifying
        whether the contents of a <emphasis>subfile</emphasis> that is itself
        a superfile are added to the <emphasis>superfile </emphasis>by copying
        or by reference. If omitted, the default is to add by
        reference.</para>

        <para><emphasis>strict</emphasis> A boolean flag specifying, in the
        case of a <emphasis>subfile</emphasis> that is itself a superfile,
        whether to check for the existence of the superfile<emphasis>
        </emphasis>and raising an error if it does not. Also, if
        <emphasis>addcontent</emphasis> is set to TRUE, it will ensure the
        <emphasis>subfile</emphasis> that is itself a superfile is not empty.
        If omitted, the default is false.</para>

        <para>Return:<emphasis> </emphasis>Null.</para>

        <para>The <emphasis role="bold">AddSuperFile </emphasis>function adds
        the <emphasis>subfile</emphasis> to the list of files comprising the
        <emphasis>superfile</emphasis>. All <emphasis>subfiles</emphasis> in
        the <emphasis>superfile</emphasis> must have exactly the same
        structure type and format.</para>

        <para>This function may be included in a superfile transaction.</para>

        <para>Example:</para>

        <programlisting>SEQUENTIAL(
 FileServices.StartSuperFileTransaction(),
 FileServices.AddSuperFile('MySuperFile','MySubFile'),
 FileServices.FinishSuperFileTransaction()
);</programlisting>
      </sect2>

      <sect2 id="RemoveSuperFile">
        <title><emphasis role="bold">RemoveSuperFile</emphasis></title>

        <para><emphasis role="bold">FileServices.RemoveSuperFile(</emphasis><emphasis>
        superfile, subfile </emphasis><emphasis role="bold">[</emphasis><emphasis>, delete</emphasis><emphasis role="bold">] [</emphasis><emphasis>,
        removecontents</emphasis><emphasis role="bold">])</emphasis></para>

        <para><emphasis>superfile</emphasis> A null-terminated string
        containing the logical name of the superfile.</para>

        <para><emphasis>subfile</emphasis> A null-terminated string containing
        the logical name of the sub-file. This may be another superfile or a
        foreign file or superfile.</para>

        <para><emphasis>delete</emphasis> A boolean flag specifying whether to
        delete the <emphasis>subfile</emphasis> from disk or just remove it
        from the <emphasis>superfile </emphasis>list of files. If omitted, the
        default is to just remove it from the <emphasis>superfile
        </emphasis>list of files. <emphasis role="bold">This option should not
        be used if the </emphasis><emphasis role="bold">subfile</emphasis><emphasis role="bold"> is a foreign file
        or foreign superfile.</emphasis></para>

        <para><emphasis>removecontents</emphasis> A boolean flag specifying
        whether the contents of a <emphasis>subfile</emphasis> that is itself
        a superfile are recursively removed.</para>

        <para>Return:<emphasis> </emphasis>Null.</para>

        <para>The <emphasis role="bold">RemoveSuperFile </emphasis>function
        removes the <emphasis>subfile</emphasis> from the list of files
        comprising the <emphasis>superfile</emphasis>.</para>

        <para>This function may be included in a superfile transaction.</para>

        <para>Example:</para>

        <programlisting>SEQUENTIAL(
 FileServices.StartSuperFileTransaction(),
 FileServices.RemoveSuperFile('MySuperFile','MySubFile'),
 FileServices.FinishSuperFileTransaction()
);</programlisting>
      </sect2>

      <sect2 id="ClearSuperFile">
        <title><emphasis role="bold">ClearSuperFile</emphasis></title>

        <para><emphasis role="bold">FileServices.ClearSuperFile(</emphasis><emphasis>
        superfile, </emphasis><emphasis role="bold">[</emphasis><emphasis>,
        delete </emphasis><emphasis role="bold">] )</emphasis></para>

        <para><emphasis>superfile</emphasis> A null-terminated string
        containing the logical name of the superfile.</para>

        <para><emphasis>delete</emphasis> A boolean flag specifying whether to
        delete the sub-files from disk or just remove them from the
        <emphasis>superfile </emphasis>list of files. If omitted, the default
        is to just remove them from the <emphasis>superfile </emphasis>list of
        files.</para>

        <para>Return:<emphasis> </emphasis>Null.</para>

        <para>The <emphasis role="bold">ClearSuperFile </emphasis>function
        removes all sub-files from the list of files comprising the
        <emphasis>superfile</emphasis>.</para>

        <para>This function may be included in a superfile transaction.</para>

        <para>Example:</para>

        <programlisting>SEQUENTIAL(
 FileServices.StartSuperFileTransaction(),
 FileServices.ClearSuperFile('MySuperFile'),
 FileServices.FinishSuperFileTransaction()
);</programlisting>
      </sect2>

      <sect2 id="SwapSuperFile">
        <title><emphasis role="bold">SwapSuperFile</emphasis></title>

        <para><emphasis role="bold">FileServices.SwapSuperFile(</emphasis><emphasis>
        superfile1, superfile2 </emphasis><emphasis role="bold">)</emphasis></para>

        <para><emphasis>superfile1</emphasis> A null-terminated string
        containing the logical name of the superfile.</para>

        <para><emphasis>superfile2</emphasis> A null-terminated string
        containing the logical name of the superfile.</para>

        <para>Return:<emphasis> </emphasis>Null.</para>

        <para>The <emphasis role="bold">SwapSuperFile </emphasis>function
        moves all sub-files from <emphasis>superfile1 </emphasis>to
        <emphasis>superfile2 </emphasis>and vice versa.</para>

        <para>This function may be included in a superfile transaction.</para>

        <para>Example:</para>

        <programlisting>SEQUENTIAL(
 FileServices.StartSuperFileTransaction(),
 FileServices.SwapSuperFile('MySuperFile','YourSuperFile'),
 FileServices.FinishSuperFileTransaction()
);</programlisting>
      </sect2>

      <sect2 id="ReplaceSuperFile">
        <title><emphasis role="bold">ReplaceSuperFile</emphasis></title>

        <para><emphasis role="bold">FileServices.ReplaceSuperFile(</emphasis><emphasis>
        superfile, subfile1 , subfile2 </emphasis><emphasis role="bold">)</emphasis></para>

        <para><emphasis>superfile</emphasis> A null-terminated string
        containing the logical name of the superfile.</para>

        <para><emphasis>subfile1</emphasis> A null-terminated string
        containing the logical name of the sub-file. Ths may be another
        superfile.</para>

        <para><emphasis>subfile2</emphasis> A null-terminated string
        containing the logical name of the sub-file. Ths may be another
        superfile.</para>

        <para>Return:<emphasis> </emphasis>Null.</para>

        <para>The <emphasis role="bold">ReplaceSuperFile </emphasis>function
        removes the <emphasis>subfile1</emphasis> from the list of files
        comprising the <emphasis>superfile </emphasis>and replaces it with
        <emphasis>subfile2</emphasis>.</para>

        <para>This function may be included in a superfile transaction.</para>

        <para>Example:</para>

        <programlisting>SEQUENTIAL(
 FileServices.StartSuperFileTransaction(),
 FileServices.ReplaceSuperFile('MySuperFile',
      'MyOldSubFile',
      'MyNewSubFile'),
 FileServices.FinishSuperFileTransaction()
);</programlisting>
      </sect2>

      <sect2 id="PromoteSuperFileList">
        <title><emphasis role="bold">PromoteSuperFileList</emphasis></title>

        <para><emphasis role="bold">FileServices.PromoteSuperFileList(</emphasis><emphasis>
        superfiles </emphasis><emphasis role="bold">[</emphasis><emphasis>,
        addhead </emphasis><emphasis role="bold">]</emphasis><emphasis>
        </emphasis><emphasis role="bold">[</emphasis><emphasis>, deltail
        </emphasis><emphasis role="bold">]</emphasis><emphasis>
        </emphasis><emphasis role="bold"> [</emphasis><emphasis>,
        createjustone </emphasis><emphasis role="bold">]</emphasis><emphasis>
        </emphasis><emphasis role="bold">[</emphasis><emphasis>, reverse
        </emphasis><emphasis role="bold">]</emphasis><emphasis>
        </emphasis><emphasis role="bold">)</emphasis><emphasis>oldlist</emphasis><emphasis role="bold"> :=
        FileServices.fPromoteSuperFileList(</emphasis><emphasis> superfiles
        </emphasis><emphasis role="bold">[</emphasis><emphasis>, addhead
        </emphasis><emphasis role="bold">]</emphasis><emphasis>
        </emphasis><emphasis role="bold"> [</emphasis><emphasis>, deltail
        </emphasis><emphasis role="bold">]</emphasis><emphasis>
        </emphasis><emphasis role="bold">[</emphasis><emphasis>, createjustone
        </emphasis><emphasis role="bold">]</emphasis><emphasis>
        </emphasis><emphasis role="bold">[</emphasis><emphasis>, reverse
        </emphasis><emphasis role="bold">]</emphasis><emphasis>
        </emphasis><emphasis role="bold">);</emphasis></para>

        <para><emphasis>superfiles</emphasis> A set of null-terminated strings
        containing the logical names of the superfiles to act on. Any that
        don’t exist will be created. The contents of each superfile will be
        moved to the next in the list (NB -- each superfile must contain
        different sub-files).</para>

        <para><emphasis>addhead</emphasis> Optional. A null-terminated string
        containing a comma-delimited list of logical file names to add to the
        first <emphasis>superfile </emphasis>after the promotion process is
        complete.</para>

        <para><emphasis>deltail</emphasis> Optional. A boolean value
        specifying whether to physically delete the contents moved out of the
        last superfile. If omitted, the default is FALSE.</para>

        <para><emphasis>createjustone</emphasis> Optional. A boolean value
        specifying whether to only create a single superfile (truncate the
        list at the first non-existent superfile). If omitted, the default is
        FALSE.</para>

        <para><emphasis>reverse</emphasis> Optional. A boolean value
        specifying whether to reverse the order of procesing the
        <emphasis>superfiles</emphasis> list, effectively “demoting” instead
        of “promoting” the sub-files. If omitted, the default is FALSE.</para>

        <para><emphasis>oldlist</emphasis> The name of the attribute that
        receives the returned string containing the list of the previous
        subfile contents of the emptied superfile.</para>

        <para>Return:<emphasis> </emphasis>PromoteSupeFileList returns Null;
        fPromoteSupeFileList returns a string.</para>

        <para>The <emphasis role="bold">PromoteSuperFileList
        </emphasis>function moves the subfiles from the first entry in the
        list of <emphasis>superfiles</emphasis> to the next in the list,
        subsequently repeating the process through the list of
        <emphasis>superfiles</emphasis>.</para>

        <para>This function does not use superfile transactions, it is an
        atomic operation.</para>

        <para>Example:</para>

        <programlisting>FileServices.PromoteSuperFileList(['Super1','Super2','Super3'],
         'NewSub1');
//Moves what was in Super1 to Super2,
// what was in Super2 to Super3, replacing what was in Super3,
// and putting NewSub1 in Super1</programlisting>
      </sect2>

      <sect2 id="FinishSuperFileTransaction">
        <title><emphasis role="bold">FinishSuperFileTransaction</emphasis></title>

        <para><emphasis role="bold">FileServices.FinishSuperFileTransaction( [
        </emphasis><emphasis>rollback </emphasis><emphasis role="bold">]
        )</emphasis></para>

        <para><emphasis>rollback</emphasis> Optional. A boolean flag that
        indicates whether to commit (FALSE) or roll back (TRUE) the
        transaction. If omitted, the default is FALSE.</para>

        <para>Return:<emphasis> </emphasis>Null.</para>

        <para>The <emphasis role="bold">FinishSuperFileTransaction
        </emphasis>function terminates a superfile maintenance transaction
        frame. If the <emphasis>rollback</emphasis> flag is FALSE, the
        transction is committed atomically and the transaction frame closes.
        Otherwise, the transaction is rolled back and the transaction frame
        closes.</para>

        <para>Example:</para>

        <programlisting>FileServices.FinishSuperFileTransaction();</programlisting>
      </sect2>
    </sect1>

    <sect1 id="Cluster_Handling">
      <title><emphasis>Cluster Handling</emphasis></title>

      <sect2 id="Cluster">
        <title><emphasis role="bold">Cluster</emphasis></title>

        <para><emphasis role="bold">Thorlib.Cluster(</emphasis><emphasis>
        </emphasis><emphasis role="bold">)</emphasis></para>

        <para>Return:<emphasis> </emphasis>Cluster returns a VARSTRING
        value.</para>

        <para>The <emphasis role="bold">Cluster </emphasis>function returns
        the name of the cluster running the workunit. Not supported on Roxie
        clusters. This name is used by ECLplus.exe to specify the the target
        cluster for a workunit.</para>

        <para>Example:</para>

        <programlisting>A := Thorlib.Cluster();</programlisting>
      </sect2>

      <sect2 id="DaliServers">
        <title><emphasis role="bold">DaliServers</emphasis></title>

        <para><emphasis role="bold">Thorlib.DaliServers(</emphasis><emphasis>
        </emphasis><emphasis role="bold">)</emphasis></para>

        <para>Return:<emphasis> </emphasis>Daliservers returns a VARSTRING
        value.</para>

        <para>The <emphasis role="bold">Daliservers </emphasis>function
        returns the IP and port of the system data store (Dali) servers for
        the environment running the workunit.</para>

        <para>Example:</para>

        <programlisting>A := Thorlib.Daliservers();</programlisting>
      </sect2>

      <sect2 id="GetEnv">
        <title><emphasis role="bold">GetEnv</emphasis></title>

        <para><emphasis role="bold">Thorlib.GetEnv( </emphasis><emphasis>name,
        default </emphasis><emphasis role="bold">)</emphasis></para>

        <para><emphasis>name </emphasis>A null-terminated string containing
        the name of the environment variable.</para>

        <para><emphasis>default </emphasis>A null-terminated string containing
        the default value of the environment variable.</para>

        <para>Return:<emphasis> </emphasis>GetEnv returns a VARSTRING
        value.</para>

        <para>The <emphasis role="bold">GetEnv </emphasis>function returns the
        value stored in the <emphasis>name</emphasis> environment variable. If
        the environment variable does not exist or contains no value, the
        <emphasis>default</emphasis> value is returned.</para>

        <para>Example:</para>

        <programlisting>A := Thorlib.GetEnv('SomeEnvironmentVar','Default');</programlisting>
      </sect2>

      <sect2 id="Group">
        <title><emphasis role="bold">Group</emphasis></title>

        <para><emphasis role="bold">Thorlib.Group( )</emphasis></para>

        <para>Return:<emphasis> </emphasis>Group returns a VARSTRING
        value.</para>

        <para>The <emphasis role="bold">Group </emphasis>function returns the
        name of the node group running the workunit. Not supported on Roxie
        clusters. This name is used in ECL code to specify the target CLUSTER
        for an OUTPUT action or a PERSISTed attribute.</para>

        <para>Example:</para>

        <programlisting>A := Thorlib.Group();</programlisting>
      </sect2>

      <sect2 id="JobName">
        <title><emphasis role="bold">JobName</emphasis></title>

        <para><emphasis role="bold">Thorlib.JobName(</emphasis><emphasis>
        </emphasis><emphasis role="bold">)</emphasis></para>

        <para>Return:<emphasis> </emphasis>JobName returns a VARSTRING
        value.</para>

        <para>The <emphasis role="bold">JobName </emphasis>function returns
        the name of the workunit.</para>

        <para>Example:</para>

        <programlisting>A := Thorlib.JobName();</programlisting>
      </sect2>

      <sect2 id="JobOwner">
        <title><emphasis role="bold">JobOwner</emphasis></title>

        <para><emphasis role="bold">Thorlib.JobOwner(</emphasis><emphasis>
        </emphasis><emphasis role="bold">)</emphasis></para>

        <para>Return:<emphasis> </emphasis>JobOwner returns a VARSTRING
        value.</para>

        <para>The <emphasis role="bold">JobOwner </emphasis>function returns
        the username of the person running the workunit.</para>

        <para>Example:</para>

        <programlisting>A := Thorlib.JobOwner();</programlisting>
      </sect2>

      <sect2 id="LogString">
        <title><emphasis role="bold">LogString</emphasis></title>

        <para><emphasis role="bold">Thorlib.LogString(
        </emphasis><emphasis>message </emphasis><emphasis role="bold">)</emphasis></para>

        <para><emphasis>message </emphasis>A string expression containinig the
        text to place in the log file.</para>

        <para>Return:<emphasis> </emphasis>LogString returns an INTEGER
        value.</para>

        <para>The <emphasis role="bold">LogString </emphasis>function outputs
        “USER:” followed by the <emphasis>message</emphasis> text to the
        eclagant or Roxie log file and returns the length of the text written
        to the file.</para>

        <para>Example:</para>

        <programlisting>A := Thorlib.LogString('The text message to log');
 //places USER:The text message to log
 //in the log file   </programlisting>
      </sect2>

      <sect2 id="OS">
        <title><emphasis role="bold">OS</emphasis></title>

        <para><emphasis role="bold">Thorlib.OS(</emphasis><emphasis>
        </emphasis><emphasis role="bold">)</emphasis></para>

        <para>Return:<emphasis> </emphasis>OS returns a VARSTRING
        value.</para>

        <para>The <emphasis role="bold">OS </emphasis>function returns the
        operating system (windows or linux) of the cluster running the
        workunit.</para>

        <para>Example:</para>

        <programlisting>A := Thorlib.OS();</programlisting>
      </sect2>

      <sect2 id="Platform">
        <title><emphasis role="bold">Platform</emphasis></title>

        <para><emphasis role="bold">Thorlib.Platform(</emphasis><emphasis>
        </emphasis><emphasis role="bold">)</emphasis></para>

        <para>Return:<emphasis> </emphasis>Platform returns a VARSTRING
        value.</para>

        <para>The <emphasis role="bold">Platform </emphasis>function returns
        the platform name (hthor, thor, or roxie) of the cluster running the
        workunit.</para>

        <para>Example:</para>

        <programlisting>A := Thorlib.Platform();</programlisting>
      </sect2>

      <sect2 id="Priority">
        <title><emphasis role="bold">Priority</emphasis></title>

        <para><emphasis role="bold">Thorlib.Priority(</emphasis><emphasis>
        </emphasis><emphasis role="bold">)</emphasis></para>

        <para>Return:<emphasis> </emphasis>Priority returns a VARSTRING
        value.</para>

        <para>The <emphasis role="bold">Priority </emphasis>function returns
        the priority level of the workunit.</para>

        <para>Example:</para>

        <programlisting>A := Thorlib.Priority();</programlisting>
      </sect2>

      <sect2 id="L2P">
        <title><emphasis role="bold">L2P</emphasis></title>

        <para><emphasis role="bold">Thorlib.L2P(</emphasis><emphasis> filename
        </emphasis><emphasis role="bold">[</emphasis><emphasis>, createflag
        </emphasis><emphasis role="bold">]</emphasis><emphasis>
        </emphasis><emphasis role="bold">)</emphasis></para>

        <para><emphasis>filename</emphasis> A null-terminated string
        containing the logical name of the file.</para>

        <para><emphasis>createflag</emphasis> A boolean value indicating
        whether to create the <emphasis>filename</emphasis>. If omitted, the
        default is FALSE.</para>

        <para>Return:<emphasis> </emphasis>L2P returns a VARSTRING
        value.</para>

        <para>The <emphasis role="bold">L2P </emphasis>function (Logical to
        Physical) returns the physical name of the file represented by the
        logical <emphasis>filename</emphasis>.</para>

        <para>Example:</para>

        <programlisting>A := Thorlib.L2P('Fred');</programlisting>
      </sect2>

      <sect2 id="Node">
        <title><emphasis role="bold">Node</emphasis></title>

        <para><emphasis role="bold">Thorlib.Node(</emphasis><emphasis>
        </emphasis><emphasis role="bold">)</emphasis></para>

        <para>Return:<emphasis> </emphasis>Node returns an UNSIGNED INTEGER4
        value.</para>

        <para>The <emphasis role="bold">Node </emphasis>function returns the
        (zero-based) number of the Data Refinery (THOR) or Rapid Data Delivery
        Engine (ROXIE) node.</para>

        <para>Example:</para>

        <programlisting>A := Thorlib.Node();</programlisting>
      </sect2>

      <sect2 id="Nodes">
        <title><emphasis role="bold">Nodes</emphasis></title>

        <para><emphasis role="bold">Thorlib.Nodes(</emphasis><emphasis>
        </emphasis><emphasis role="bold">)</emphasis></para>

        <para>Return:<emphasis> </emphasis>Nodes returns an UNSIGNED INTEGER4
        value.</para>

        <para>The <emphasis role="bold">Nodes </emphasis>function returns the
        number of nodes in the cluster. This number is the same as the
        CLUSTERSIZE compile time constant. The Nodes function is evaluated
        each time it is called, so the choice to use the function versus the
        constant depends upon the circumstances.</para>

        <para>Example:</para>

        <programlisting>A := Thorlib.Nodes();</programlisting>
      </sect2>

      <sect2 id="WUID">
        <title><emphasis role="bold">WUID</emphasis></title>

        <para><emphasis role="bold">Thorlib.WUID(</emphasis><emphasis>
        </emphasis><emphasis role="bold">)</emphasis></para>

        <para>Return:<emphasis> </emphasis>WUID returns a VARSTRING
        value.</para>

        <para>The <emphasis role="bold">WUID </emphasis>function returns the
        workunit identifier of the current job. This is the same as the
        WORKUNIT compile time constant. The WUID function is evaluated each
        time it is called, so the choice to use the function versus the
        constant depends upon the circumstances.</para>

        <para>Example:</para>

        <programlisting>A := Thorlib.WUID();   </programlisting>
      </sect2>
    </sect1>

    <sect1 id="Word_Handling">
      <title><emphasis>Word Handling</emphasis></title>

      <sect2 id="Lead_Contains">
        <title><emphasis role="bold">Lead_Contains</emphasis></title>

        <para><emphasis role="bold">LIB_Word.Lead_Contains(</emphasis><emphasis> leftstring ,
        rightstring </emphasis><emphasis role="bold">)</emphasis></para>

        <para><emphasis>leftstring</emphasis> A string value.</para>

        <para><emphasis>rightstring</emphasis> A string value.</para>

        <para>Return:<emphasis> </emphasis>Lead_Contains returns a BOOLEAN
        value.</para>

        <para>The <emphasis role="bold">Lead_Contains </emphasis>function
        returns TRUE if the <emphasis>leftstring</emphasis> and
        <emphasis>rightstring</emphasis> both begin with the same characters.
        It compares the shorter of the two parameters against the same number
        of characters in the longer and returns TRUE if they match.</para>

        <para>Example:</para>

        <programlisting>Import LIB_Word;
A := LIB_Word.Lead_Contains('Fred','Jo');
 //A contains False -- 'Jo' != 'Fr'
B := LIB_Word.Lead_Contains('Fred','Freddie');
 //B contains True --  'Fred' = 'Fred'</programlisting>
      </sect2>

      <sect2 id="StripTail">
        <title><emphasis role="bold">StripTail</emphasis></title>

        <para><emphasis role="bold">LIB_Word.StripTail(</emphasis><emphasis>
        leftstring , stripstring </emphasis><emphasis role="bold">)</emphasis></para>

        <para><emphasis>leftstring</emphasis> A string containing the word to
        strip.</para>

        <para><emphasis>stripstring</emphasis> A string containing the
        characters to strip.</para>

        <para>Return:<emphasis> </emphasis>StripTail returns a STRING
        value.</para>

        <para>The <emphasis role="bold">StripTail </emphasis>function returns
        the <emphasis>leftstring</emphasis> with any
        <emphasis>stripstring</emphasis> characters removed from the
        end.</para>

        <para>Example:</para>

        <programlisting>Import LIB_Word;
A := 'FRED\'S'; // value is FRED’S
B := LIB_Word.StripTail(LIB_Word.StripTail(A,'\''),'\'S');
 //B contains 'FRED' stripped of the possesive form FRED'S</programlisting>
      </sect2>

      <sect2 id="StripUpToWord">
        <title><emphasis role="bold">StripUpToWord</emphasis></title>

        <para><emphasis role="bold">LIB_Word.StripUpToWord(</emphasis><emphasis> leftstring ,
        n </emphasis><emphasis role="bold">)</emphasis></para>

        <para><emphasis>leftstring</emphasis> A string containing the words to
        strip.</para>

        <para><emphasis>n</emphasis> An integer containing the number of words
        to strip.</para>

        <para>Return:<emphasis> </emphasis>StripUpToWord returns a STRING
        value.</para>

        <para>The <emphasis role="bold">StripUpToWord </emphasis>function
        returns the <emphasis>leftstring</emphasis> with
        <emphasis>n</emphasis> number of words removed.</para>

        <para>Example:</para>

        <programlisting>Import LIB_Word;
A := 'FRED JO ME YOU';
B := LIB_Word.StripUpToWord(A,1);
 //B contains 'JO ME YOU'
C := LIB_Word.StripUpToWord(A,2);
 //C contains 'ME YOU'</programlisting>
      </sect2>

      <sect2 id="Tails">
        <title><emphasis role="bold">Tails</emphasis></title>

        <para><emphasis role="bold">LIB_Word.Tails(</emphasis><emphasis>
        leftstring , rightstring </emphasis><emphasis role="bold">)</emphasis></para>

        <para><emphasis>leftstring</emphasis> A string value.</para>

        <para><emphasis>rightstring</emphasis> A string value.</para>

        <para>Return:<emphasis> </emphasis>Tails returns a BOOLEAN
        value.</para>

        <para>The <emphasis role="bold">Tails </emphasis>function returns TRUE
        if the <emphasis>leftstring</emphasis> ends with the same characters
        as the <emphasis>rightstring</emphasis>.</para>

        <para>Example:</para>

        <programlisting>Import LIB_Word;
A1 := 'FRED\'S'; // value is FRED'S
A2 := 'FRED'; // value is FRED
B := '\'S';  //B contains 'S
C := LIB_Word.Tails(A1,B); // returns TRUE
D := LIB_Word.Tails(A2,B); // returns FALSE</programlisting>
      </sect2>

      <sect2 id="Word">
        <title><emphasis role="bold">Word</emphasis></title>

        <para><emphasis role="bold">LIB_Word.Word(</emphasis><emphasis>
        leftstring , n </emphasis><emphasis role="bold">)</emphasis></para>

        <para><emphasis>leftstring</emphasis> A string of space-delimited
        words..</para>

        <para><emphasis>n</emphasis> A 1-byte integer value specifying which
        word to return.</para>

        <para>Return:<emphasis> </emphasis>Word returns a STRING value.</para>

        <para>The <emphasis role="bold">Word </emphasis>function returns the
        <emphasis>n</emphasis>th word from the
        <emphasis>leftstring</emphasis>.</para>

        <para>Example:</para>

        <programlisting>Import LIB_Word;
A := 'FRED JO ME YOU';
B := LIB_Word.Word(A,1);
 //B contains 'FRED'
C := LIB_Word.Word(A,2);
 //C contains 'JO'</programlisting>
      </sect2>
    </sect1>

    <sect1 id="Date_Handling">
      <title><emphasis>Date Handling</emphasis></title>

      <sect2 id="Date_I2_YYYYMM">
        <title><emphasis role="bold">Date_I2_YYYYMM</emphasis></title>

        <para><emphasis role="bold">LIB_Date.Date_I2_YYYYMM(</emphasis><emphasis> date
        </emphasis><emphasis role="bold">)</emphasis></para>

        <para><emphasis>date</emphasis> An integer value containing a date
        value in the form of the number of months since 1900 (January, 1900 =
        1 while January 2001 = 1213).</para>

        <para>Return:<emphasis> </emphasis>Date_I2_YYYYMM returns a 6-byte
        STRING value.</para>

        <para>The <emphasis role="bold">Date_I2_YYYYMM </emphasis>function
        returns the <emphasis>date</emphasis> integer value translated into a
        YYYYMM string value.</para>

        <para>Example:</para>

        <programlisting>Import LIB_Date;
A := LIB_Date.Date_I2_YYYYMM(1213);
 //A contains '200101'
B := LIB_Date.Date_I2_YYYYMM(1);
 //B contains '190001'</programlisting>
      </sect2>

      <sect2 id="Date_MMDDYY_I2">
        <title><emphasis role="bold">Date_MMDDYY_I2</emphasis></title>

        <para><emphasis role="bold">LIB_Date.Date_MMDDYY_I2(</emphasis><emphasis> date
        </emphasis><emphasis role="bold">)</emphasis></para>

        <para><emphasis>date</emphasis> A 6-byte string value containing a
        date in MMDDYY format.</para>

        <para>Return:<emphasis> </emphasis>Date_MMDDYY_I2 returns an UNSIGNED
        INTEGER value.</para>

        <para>The <emphasis role="bold">Date_MMDDYY_I2 </emphasis>function
        returns the <emphasis>date</emphasis> string value translated into an
        integer containing the date in YYYYMMDD format. If the YY postion of
        the date is &lt; 40, then the <emphasis>date</emphasis> is considered
        to be after 2000, otherwise the <emphasis>date </emphasis>is
        considered to be in the 1900’s. Therefore, the valid range of years
        this function can handle is 1940 - 2039.</para>

        <para>Example:</para>

        <programlisting>Import LIB_Date;
A := LIB_Date.Date_MMDDYY_I2(' 010101');
 //A contains the integer value 20010101 (20,010,101)
B := LIB_Date.Date_MMDDYY_I2(' 010145');
 //B contains the integer value 19450101 (19,450,101)</programlisting>
      </sect2>

      <sect2 id="Date_Overlap">
        <title><emphasis role="bold">Date_Overlap</emphasis></title>

        <para><emphasis role="bold">LIB_Date.Date_Overlap(</emphasis><emphasis> leftfirst,
        leftlast, rightfirst, rightlast </emphasis><emphasis role="bold">)</emphasis></para>

        <para><emphasis>leftfirst</emphasis> An integer value containing the
        start date of a date range in YYYYMM format.</para>

        <para><emphasis>leftlast</emphasis> An integer value containing the
        end date of a date range in YYYYMM format.</para>

        <para><emphasis>rightfirst</emphasis> An integer value containing the
        start date of a date range in YYYYMM format.</para>

        <para><emphasis>rightlast</emphasis> An integer value containing the
        end date of a date range in YYYYMM format.</para>

        <para>Return:<emphasis> </emphasis>Date_Overlap returns an INTEGER
        value.</para>

        <para>The <emphasis role="bold">Date_Overlap </emphasis>function
        returns the number of months of overlap between the
        <emphasis>leftfirst</emphasis> to <emphasis>leftlast</emphasis> and
        <emphasis>rightfirst </emphasis>to <emphasis>rightlast </emphasis>date
        ranges.</para>

        <para>Example:</para>

        <programlisting>Import LIB_Date;
A := LIB_Date.date_overlap(200001,200303,200201,200302);
 //A contains 13 -- the overlap from 200201 to 200302
</programlisting>
      </sect2>

      <sect2 id="Date_Overlap_First">
        <title><emphasis role="bold">Date_Overlap_First</emphasis></title>

        <para><emphasis role="bold">LIB_Date.Date_Overlap_First(</emphasis><emphasis>
        leftfirst, leftlast, rightfirst, rightlast </emphasis><emphasis role="bold">)</emphasis></para>

        <para><emphasis>leftfirst</emphasis> An integer value containing the
        start date of a date range in YYYYMM format.</para>

        <para><emphasis>leftlast</emphasis> An integer value containing the
        end date of a date range in YYYYMM format.</para>

        <para><emphasis>rightfirst</emphasis> An integer value containing the
        start date of a date range in YYYYMM format.</para>

        <para><emphasis>rightlast</emphasis> An integer value containing the
        end date of a date range in YYYYMM format.</para>

        <para>Return:<emphasis> </emphasis>Date_Overlap_First returns an
        INTEGER value.</para>

        <para>The <emphasis role="bold">Date_Overlap_First </emphasis>function
        returns the starting overlap date between the
        <emphasis>leftfirst</emphasis> to <emphasis>leftlast</emphasis> and
        <emphasis>rightfirst </emphasis>to <emphasis>rightlast </emphasis>date
        ranges.</para>

        <para>Example:</para>

        <programlisting>Import LIB_Date;
A := LIB_Date.date_overlap_first(200001,200303,200201,200302);
//A contains 200201 -- the two ranges overlap from 200201 to 200302
</programlisting>
      </sect2>

      <sect2 id="Date_Overlap_Last">
        <title><emphasis role="bold">Date_Overlap_Last</emphasis></title>

        <para><emphasis role="bold">LIB_Date.Date_Overlap_Last(</emphasis><emphasis>
        leftfirst, leftlast, rightfirst, rightlast </emphasis><emphasis role="bold">)</emphasis></para>

        <para><emphasis>leftfirst</emphasis> An integer value containing the
        start date of a date range in YYYYMM format.</para>

        <para><emphasis>leftlast</emphasis> An integer value containing the
        end date of a date range in YYYYMM format.</para>

        <para><emphasis>rightfirst</emphasis> An integer value containing the
        start date of a date range in YYYYMM format.</para>

        <para><emphasis>rightlast</emphasis> An integer value containing the
        end date of a date range in YYYYMM format.</para>

        <para>Return:<emphasis> </emphasis>Date_Overlap_First returns an
        INTEGER value.</para>

        <para>The <emphasis role="bold">Date_Overlap_Last </emphasis>function
        returns the ending overlap date between the
        <emphasis>leftfirst</emphasis> to <emphasis>leftlast</emphasis> and
        <emphasis>rightfirst </emphasis>to <emphasis>rightlast </emphasis>date
        ranges.</para>

        <para>Example:</para>

        <programlisting>Import LIB_Date;
A := LIB_Date.date_overlap_last(200001,200303,200201,200302);
//A contains 200302 -- the two ranges overlap from 200201 to 200302</programlisting>
      </sect2>

      <sect2 id="Date_YYYYMM_I2">
        <title><emphasis role="bold">Date_YYYYMM_I2</emphasis></title>

        <para><emphasis role="bold">LIB_Date.Date_YYYYMM_I2(</emphasis><emphasis> date
        </emphasis><emphasis role="bold">)</emphasis></para>

        <para><emphasis>date</emphasis> A 6-byte STRING value containing a
        date in YYYYMM format.</para>

        <para>Return:<emphasis> </emphasis>Date_YYYYMM_I2 returns an INTEGER
        value.</para>

        <para>The <emphasis role="bold">Date_I2_YYYYMM </emphasis>function
        returns the <emphasis>date</emphasis> string translated into an
        integer representing the number of months since 1900 (January, 1900 =
        1 while January 2001 = 1213).</para>

        <para>Example:</para>

        <programlisting>Import LIB_Date;
A := LIB_Date.Date_YYYYMM_I2('200101' );
 //A contains 1213
B := LIB_Date.Date_YYYYMM_I2('190001' );
 //B contains 1</programlisting>
      </sect2>

      <sect2 id="DayOfYear">
        <title><emphasis role="bold">DayOfYear</emphasis></title>

        <para><emphasis role="bold">LIB_Date.DayOfYear(</emphasis><emphasis>
        year, month, day </emphasis><emphasis role="bold">)</emphasis></para>

        <para><emphasis>year</emphasis> An integer value containing the
        4-digit year.</para>

        <para><emphasis>month</emphasis> An integer value containing the month
        number.</para>

        <para><emphasis>day</emphasis> An integer value containing the day
        number within the <emphasis>month</emphasis>.</para>

        <para>Return:<emphasis> </emphasis>DayOfYear returns an INTEGER
        value.</para>

        <para>The <emphasis role="bold">DayOfYear </emphasis>function returns
        the julian date for the date passed to it as the
        <emphasis>year</emphasis>, <emphasis>month</emphasis>, and
        <emphasis>day</emphasis> parameters. It does properly handle leap
        years.</para>

        <para>Example:</para>

        <programlisting>Import LIB_Date;
A := LIB_Date.DayOfYear(2000,1,1 );
 //A contains 1
B := LIB_Date.DayOfYear(2000,3,1 );
 //B contains 61</programlisting>
      </sect2>

      <sect2 id="DaysApart">
        <title><emphasis role="bold">DaysApart</emphasis></title>

        <para><emphasis role="bold">LIB_Date.DaysApart(</emphasis><emphasis>
        date1, date2 </emphasis><emphasis role="bold">)</emphasis></para>

        <para><emphasis>date1</emphasis> An 8-byte STRING value containing a
        date in YYYYMMDD format.</para>

        <para><emphasis>date2</emphasis> An 8-byte STRING value containing a
        date in YYYYMMDD format.</para>

        <para>Return:<emphasis> </emphasis>DaysApart returns an INTEGER
        value.</para>

        <para>The <emphasis role="bold">DaysApart </emphasis>function returns
        the number of days between <emphasis>date1 </emphasis>and
        <emphasis>date2</emphasis>. It does properly handle leap years, but
        only works with dates since 1900.</para>

        <para>Example:</para>

        <programlisting>Import LIB_Date;
A := LIB_Date.DaysApart('20030101' , '20030110' );
 //A contains 9</programlisting>
      </sect2>

      <sect2 id="DaysSince1900">
        <title><emphasis role="bold">DaysSince1900</emphasis></title>

        <para><emphasis role="bold">LIB_Date.DaysSince1900(</emphasis><emphasis> year, month,
        day </emphasis><emphasis role="bold">)</emphasis></para>

        <para><emphasis>year</emphasis> An integer value containing the
        4-digit year.</para>

        <para><emphasis>month</emphasis> An integer value containing the month
        number.</para>

        <para><emphasis>day</emphasis> An integer value containing the day
        number within the <emphasis>month</emphasis>.</para>

        <para>Return:<emphasis> </emphasis>DaysSince1900 returns an INTEGER
        value.</para>

        <para>The <emphasis role="bold">DaysSince1900 </emphasis>function
        returns a julian-type date containng the number of days since 1/1/1900
        and the date passed to it as the <emphasis>year</emphasis>,
        <emphasis>month</emphasis>, and <emphasis>day</emphasis> parameters.
        It does properly handle leap years.</para>

        <para>Example:</para>

        <programlisting>Import LIB_Date;
A := LIB_Date.DaysSince1900(2003,1,1);
 //A contains 37621
B := LIB_Date.DaysSince1900(1900,1,1);
 //B contains 1</programlisting>
      </sect2>

      <sect2 id="EarliestDate">
        <title><emphasis role="bold">EarliestDate</emphasis></title>

        <para><emphasis role="bold">LIB_Date.EarliestDate(</emphasis><emphasis> date1, date2
        </emphasis><emphasis role="bold">)</emphasis></para>

        <para><emphasis>date1</emphasis> An INTEGER value containing a
        date.</para>

        <para><emphasis>date2</emphasis> An INTEGER value containing a
        date.</para>

        <para>Return:<emphasis> </emphasis>EarliestDate returns an INTEGER
        value.</para>

        <para>The <emphasis role="bold">EarliestDate </emphasis>function
        returns the earlier of the passed <emphasis>date1 </emphasis>and
        <emphasis>date2 </emphasis>parameters. Both the <emphasis>date1
        </emphasis>and <emphasis>date2 </emphasis>parameters should contain
        values derived from similar processes.</para>

        <para>Example:</para>

        <programlisting>Import LIB_Date;
A := LIB_Date.EarliestDate(20030101 , 20030110 );
 //A contains 20030101
B := LIB_Date.EarliestDate(LIB_Date.DaysSince1900(2003,1,1),
       LIB_Date.DaysSince1900(2003,1,10) );
 //B contains 37621
 // (the return value from LIB_Date.DaysSince1900(2003,1,1))</programlisting>
      </sect2>

      <sect2 id="EarliestDateString">
        <title><emphasis role="bold">EarliestDateString</emphasis></title>

        <para><emphasis role="bold">LIB_Date.EarliestDateString(</emphasis><emphasis> date1,
        date2 </emphasis><emphasis role="bold">)</emphasis></para>

        <para><emphasis>date1</emphasis> An STRING value containing a
        date.</para>

        <para><emphasis>date2</emphasis> An STRING value containing a
        date.</para>

        <para>Return:<emphasis> </emphasis>EarliestDateString returns a STRING
        value.</para>

        <para>The <emphasis role="bold">EarliestDateString </emphasis>function
        returns the earlier of the passed <emphasis>date1 </emphasis>and
        <emphasis>date2 </emphasis>parameters. Both the <emphasis>date1
        </emphasis>and <emphasis>date2 </emphasis>parameters should be in
        YYYYMMDD or YYYYMM format for proper evaluation.</para>

        <para>Example:</para>

        <programlisting>Import LIB_Date;
A := LIB_Date.EarliestDateString('20030101' , '20030110' );
 //A contains 20030101</programlisting>
      </sect2>

      <sect2 id="Format_Date">
        <title><emphasis role="bold">Format_Date</emphasis></title>

        <para><emphasis role="bold">LIB_Date.Format_Date(</emphasis><emphasis>
        year, month, day </emphasis><emphasis role="bold">)</emphasis></para>

        <para><emphasis>year</emphasis> An integer value containing the
        4-digit year.</para>

        <para><emphasis>month</emphasis> An integer value containing the month
        number.</para>

        <para><emphasis>day</emphasis> An integer value containing the day
        number within the <emphasis>month</emphasis>.</para>

        <para>Return:<emphasis> </emphasis>FormatDate returns a STRING
        value.</para>

        <para>The <emphasis role="bold">Format_Date </emphasis>function
        returns a date string in YYYY/MM/DD format.</para>

        <para>Example:</para>

        <programlisting>Import LIB_Date;
A := LIB_Date.Format_Date(2003,1,1);
 //A contains “2003/01/01”</programlisting>
      </sect2>

      <sect2 id="GetAge">
        <title><emphasis role="bold">GetAge</emphasis></title>

        <para><emphasis role="bold">LIB_Date.GetAge(</emphasis><emphasis> date
        </emphasis><emphasis role="bold">)</emphasis></para>

        <para><emphasis>date</emphasis> An 8-byte STRING value containing a
        date in YYYYMMDD format.</para>

        <para>Return:<emphasis> </emphasis>GetAge returns an INTEGER
        value.</para>

        <para>The <emphasis role="bold">GetAge </emphasis>function returns the
        number of years between the current system date and the passed
        <emphasis>date</emphasis>.</para>

        <para>Example:</para>

        <programlisting>Import LIB_Date;
A := LIB_Date.GetAge('20000101' );
 //A contains 3, assuming the current date is
 // sometime within the 2003 calendar year</programlisting>
      </sect2>

      <sect2 id="LatestDate">
        <title><emphasis role="bold">LatestDate</emphasis></title>

        <para><emphasis role="bold">LIB_Date.LatestDate(</emphasis><emphasis>
        date1, date2 </emphasis><emphasis role="bold">)</emphasis></para>

        <para><emphasis>date1</emphasis> An INTEGER value containing a
        date.</para>

        <para><emphasis>date2</emphasis> An INTEGER value containing a
        date.</para>

        <para>Return:<emphasis> </emphasis>LatestDate returns an INTEGER
        value.</para>

        <para>The <emphasis role="bold">LatestDate </emphasis>function returns
        the later of the passed <emphasis>date1 </emphasis>and <emphasis>date2
        </emphasis>parameters. Both the <emphasis>date1 </emphasis>and
        <emphasis>date2 </emphasis>parameters should contain values derived
        from similar processes.</para>

        <para>Example:</para>

        <programlisting>Import LIB_Date;
A := LIB_Date.LatestDate(20030101 , 20030110 );
 //A contains 20030110
B := LIB_Date.LatestDate(LIB_Date.DaysSince1900(2003,1,1),
     LIB_Date.DaysSince1900(2003,1,10) );
 //B contains 37630
 // (the return value from LIB_Date.DaysSince1900(2003,1,10))</programlisting>
      </sect2>

      <sect2 id="LeapYear">
        <title><emphasis role="bold">LeapYear</emphasis></title>

        <para><emphasis role="bold">LIB_Date.LeapYear(</emphasis><emphasis>
        year </emphasis><emphasis role="bold">)</emphasis></para>

        <para><emphasis>year</emphasis> An integer value containing the
        4-digit year.</para>

        <para>Return:<emphasis> </emphasis>LeapYear returns a BOOLEAN
        value.</para>

        <para>The <emphasis role="bold">LeapYear </emphasis>function returns
        TRUE if the passed <emphasis>year </emphasis>parameter is a leap
        year.</para>

        <para>Example:</para>

        <programlisting>Import LIB_Date;
A := LIB_Date.LeapYear(2000);
 //A contains TRUE
B := LIB_Date.LeapYear(2001);
 //B contains FALSE</programlisting>
      </sect2>
    </sect1>

    <sect1 id="Auditing">
      <title><emphasis>Auditing</emphasis></title>

      <sect2 id="Audit">
        <title><emphasis role="bold">Audit</emphasis></title>

        <para><emphasis role="bold">AuditLib.Audit(</emphasis><emphasis> type,
        message </emphasis><emphasis role="bold">)</emphasis></para>

        <para><emphasis>type</emphasis> A string constant containing the type
        of audit entry. Currently, only INFO is provided.</para>

        <para><emphasis>message</emphasis> A string containing the audit entry
        text.</para>

        <para>Return:<emphasis> </emphasis>Audit returns a BOOLEAN value
        indicating whether it was successful or not.</para>

        <para>The <emphasis role="bold">Audit </emphasis>function writes the
        <emphasis>message</emphasis> into the Windows event log or Linux
        system log on the ECL Agent computer. The entries can be retrieved
        from the logs using standard operating system tools.</para>

        <para>Example:</para>

        <programlisting>AuditLib.Audit('INFO','Audit Message');</programlisting>
      </sect2>

      <sect2 id="AuditData">
        <title><emphasis role="bold">AuditData</emphasis></title>

        <para><emphasis role="bold">AuditLib.Auditdata(</emphasis><emphasis>
        type, message, datablock </emphasis><emphasis role="bold">)</emphasis></para>

        <para><emphasis>type</emphasis> A string constant containing the type
        of audit entry. Currently, only INFO is provided.</para>

        <para><emphasis>message</emphasis> A string containing the audit entry
        text.</para>

        <para><emphasis>datablock</emphasis> An unstructured block of data,
        which the application reading the log entry must know how to
        read.</para>

        <para>Return:<emphasis> </emphasis>AuditData returns a BOOLEAN value
        indicating whether it was successful or not.</para>

        <para>The <emphasis role="bold">AuditData </emphasis>function writes
        the <emphasis>message</emphasis> into the Windows event log or Linux
        system log on the ECL Agent computer. The entries can be retrieved
        from the logs using standard operating system tools.</para>

        <para>Example:</para>

        <programlisting>DATA2 DataBlock := x'0D0A';
AuditLib.AuditData('INFO','Audit Message',DataBlock);</programlisting>
      </sect2>
    </sect1>

    <sect1 id="Parsing_Support">
      <title><emphasis>Parsing Support</emphasis></title>

      <sect2 id="GetParseTree">
        <title><emphasis role="bold">GetParseTree</emphasis></title>

        <para><emphasis role="bold">ParseLib.GetParseTree(</emphasis><emphasis>
        </emphasis><emphasis role="bold">)</emphasis></para>

        <para>Return:<emphasis> </emphasis>GetParseTree returns a STRING
        value.</para>

        <para>The <emphasis role="bold">GetParseTree </emphasis>function
        returns a textual representation of the match that occurred, using
        square brackets (such as: a[b[c]d] ) to indicate nesting. This
        function is only used within the RECORD or TRANSFORM structure that
        defines the result of a PARSE operation. This function is useful for
        debugging PARSE operations.</para>

        <para>Example:</para>

        <programlisting>r := {string150 line};
d := dataset([
{'Ge 34:2 And when Shechem the son of Hamor the Hivite, '+
 'prince of the country, saw her, he took her, and lay with her, '+
 'and defiled her.'},
{'Ge 36:10 These are the names of Esaus sons; Eliphaz the son of '+
 'Adah the wife of Esau, Reuel the son of Bashemath the wife of '+
 'Esau.'}
],r);
PATTERN ws := [' ','\t',',']*;
PATTERN patStart := FIRST | ws;
PATTERN patEnd := LAST | ws;
PATTERN article := ['A','The','Thou','a','the','thou'];
TOKEN patWord := PATTERN('[a-zA-Z]+');
TOKEN Name := PATTERN('[A-Z][a-zA-Z]+');
RULE Namet := name OPT(ws 'the' ws name);
PATTERN produced_by := OPT(article ws) ['son of','daughter of'];
PATTERN produces_with := OPT(article ws) ['wife of'];
RULE progeny := namet ws ( produced_by | produces_with ) ws namet;
results := RECORD
  STRING LeftName   := MATCHTEXT(Namet[1]);
  STRING RightName  := MATCHTEXT(Namet[2]);
  STRING LinkPhrase := IF(MATCHTEXT(produced_by[1])&lt;&gt;'',
      MATCHTEXT(produced_by[1]),
      MATCHTEXT(produces_with[1]));
  STRING Tree       := 'Tree: ' + parseLib.getParseTree();
END;
outfile1 := PARSE(d,line,progeny,results,SCAN ALL);
/* the Tree field output looks like this:
Tree: [namet[name"Shechem"] ws" " produced_by"the son of" ws" " namet[name"Hamor"]]
*/</programlisting>
      </sect2>

      <sect2 id="GetXMLParseTree">
        <title><emphasis role="bold">GetXMLParseTree</emphasis></title>

        <para><emphasis role="bold">ParseLib.GetXMLParseTree(</emphasis><emphasis>
        </emphasis><emphasis role="bold">)</emphasis></para>

        <para>Return:<emphasis> </emphasis>GetXMLParseTree returns a STRING
        value.</para>

        <para>The <emphasis role="bold">GetXMLParseTree </emphasis>function
        returns a textual representation of the match that occurred, using XML
        tags to indicate nesting. This function is only used within the RECORD
        or TRANSFORM structure that defines the result of a PARSE operation.
        This function is useful for debugging PARSE operations.</para>

        <para>Example:</para>

        <programlisting>r := {string150 line};
d := dataset([
{'Ge 34:2 And when Shechem the son of Hamor the Hivite, '+
 'prince of the country, saw her, he took her, and lay with her, '+
 'and defiled her.'},
{'Ge 36:10 These are the names of Esaus sons; Eliphaz the son of '+
 'Adah the wife of Esau, Reuel the son of Bashemath the wife of '+
 'Esau.'}
],r);
    
PATTERN ws := [' ','\t',',']*;
PATTERN patStart := FIRST | ws;
PATTERN patEnd := LAST | ws;
PATTERN article := ['A','The','Thou','a','the','thou'];
TOKEN patWord := PATTERN('[a-zA-Z]+');
TOKEN Name := PATTERN('[A-Z][a-zA-Z]+');
RULE Namet := name OPT(ws 'the' ws name);
PATTERN produced_by := OPT(article ws) ['son of','daughter of'];
PATTERN produces_with := OPT(article ws) ['wife of'];
RULE progeny := namet ws ( produced_by | produces_with ) ws namet;
results := RECORD
  STRING LeftName   := MATCHTEXT(Namet[1]);
  STRING RightName  := MATCHTEXT(Namet[2]);
  STRING LinkPhrase := IF(MATCHTEXT(produced_by[1])&lt;&gt;'',
      MATCHTEXT(produced_by[1]),
      MATCHTEXT(produces_with[1]));
  STRING Tree       := 'Tree: ' + parseLib.getXMLParseTree();
END;
outfile1 := PARSE(d,line,progeny,results,SCAN ALL);
/* the Tree field output looks like this:
Tree: &lt;namet&gt;
 &lt;name&gt;Shechem&lt;/name&gt;
&lt;/namet&gt;
&lt;ws&gt; &lt;/ws&gt;
&lt;produced_by&gt;the son of&lt;/produced_by&gt;
&lt;ws&gt; &lt;/ws&gt;
&lt;namet&gt;
 &lt;name&gt;Hamor&lt;/name&gt;
&lt;/namet&gt;
*/
</programlisting>
      </sect2>
    </sect1>

    <sect1 id="Metaphone_Support">
      <title><emphasis>Metaphone Support</emphasis></title>

      <sect2 id="DMetaphone1">
        <title><emphasis role="bold">DMetaphone1</emphasis></title>

        <para><emphasis role="bold">MetaphoneLib.DMetaphone1(</emphasis><emphasis>
        source</emphasis><emphasis role="bold"> )</emphasis></para>

        <para><emphasis>source</emphasis> The string to process.</para>

        <para>Return:<emphasis> </emphasis>DMetaphone1 returns a STRING
        value.</para>

        <para>The <emphasis role="bold">DMetaphone1 </emphasis>function
        returns a textual representation of the <emphasis>source</emphasis>
        data, similar to a soundex code. This function returns the first
        return value from the Double Metaphone algorithm.</para>

        <para>Example:</para>

        <programlisting>r := RECORD
  STRING source;
  STRING M1;
  STRING M2;
  STRING Mboth;
END;
r XF(ProgGuide.Person.File L) := TRANSFORM
  SELF.source := L.LastName;
  SELF.M1     := MetaphoneLib.DMetaphone1( L.LastName );
  SELF.M2     := MetaphoneLib.DMetaphone2( L.LastName );
  SELF.Mboth  := MetaphoneLib.DMetaphoneBoth( L.LastName );
END;
ds := PROJECT(ProgGuide.Person.File,XF(LEFT));
COUNT(ds);
COUNT(ds(M1 &lt;&gt; M2));
OUTPUT(ds);
OUTPUT(ds(M1 &lt;&gt; M2));
</programlisting>
      </sect2>

      <sect2 id="DMetaphone2">
        <title><emphasis role="bold">DMetaphone2</emphasis></title>

        <para><emphasis role="bold">MetaphoneLib.DMetaphone2(</emphasis><emphasis>
        source</emphasis><emphasis role="bold"> )</emphasis></para>

        <para><emphasis>source</emphasis> The string to process.</para>

        <para>Return:<emphasis> </emphasis>DMetaphone2 returns a STRING
        value.</para>

        <para>The <emphasis role="bold">DMetaphone2 </emphasis>function
        returns a textual representation of the <emphasis>source</emphasis>
        data, similar to a soundex code. This function returns the second
        return value from the Double Metaphone algorithm.</para>

        <para>Example:</para>

        <programlisting>r := RECORD
  STRING source;
  STRING M1;
  STRING M2;
  STRING Mboth;
END;
r XF(ProgGuide.Person.File L) := TRANSFORM
  SELF.source := L.LastName;
  SELF.M1     := MetaphoneLib.DMetaphone1( L.LastName );
  SELF.M2     := MetaphoneLib.DMetaphone2( L.LastName );
  SELF.Mboth  := MetaphoneLib.DMetaphoneBoth( L.LastName );
END;
ds := PROJECT(ProgGuide.Person.File,XF(LEFT));
COUNT(ds);
COUNT(ds(M1 &lt;&gt; M2));
OUTPUT(ds);
OUTPUT(ds(M1 &lt;&gt; M2));</programlisting>
      </sect2>

      <sect2 id="DMetaphoneBoth">
        <title><emphasis role="bold">DMetaphoneBoth</emphasis></title>

        <para><emphasis role="bold">MetaphoneLib.DMetaphoneBoth(</emphasis><emphasis>
        source</emphasis><emphasis role="bold"> )</emphasis></para>

        <para><emphasis>source</emphasis> The string to process.</para>

        <para>Return:<emphasis> </emphasis>DMetaphoneBoth returns a STRING
        value.</para>

        <para>The <emphasis role="bold">DMetaphoneBoth </emphasis>function
        returns a textual representation of the <emphasis>source</emphasis>
        data, similar to a soundex code. This function returns both return
        value from the Double Metaphone algorithm, concatenating the two into
        a single result string.</para>

        <para>Example:</para>

        <programlisting>r := RECORD
  STRING source;
  STRING M1;
  STRING M2;
  STRING Mboth;
END;
r XF(ProgGuide.Person.File L) := TRANSFORM
  SELF.source := L.LastName;
  SELF.M1     := MetaphoneLib.DMetaphone1( L.LastName );
  SELF.M2     := MetaphoneLib.DMetaphone2( L.LastName );
  SELF.Mboth  := MetaphoneLib.DMetaphoneBoth( L.LastName );
END;
ds := PROJECT(ProgGuide.Person.File,XF(LEFT));
COUNT(ds);
COUNT(ds(M1 &lt;&gt; M2));
OUTPUT(ds);
OUTPUT(ds(M1 &lt;&gt; M2));</programlisting>
      </sect2>
    </sect1>

    <sect1 id="Workunit_Services">
      <title><emphasis>Workunit Services</emphasis></title>

      <sect2 id="WorkunitList">
        <title><emphasis role="bold">WorkunitList</emphasis></title>

        <para><emphasis role="bold">WorkunitServices.WorkunitList(</emphasis><emphasis>
        lowwuid </emphasis><emphasis role="bold">[</emphasis><emphasis>,
        highwuid </emphasis><emphasis role="bold">] [</emphasis><emphasis>,
        username </emphasis><emphasis role="bold">]</emphasis><emphasis role="bold"> [</emphasis><emphasis>, cluster </emphasis><emphasis role="bold">] [</emphasis><emphasis>, jobname </emphasis><emphasis role="bold">] [</emphasis><emphasis>, state </emphasis><emphasis role="bold">] [</emphasis><emphasis>, priority </emphasis><emphasis role="bold">]</emphasis><emphasis role="bold"> [</emphasis><emphasis>,
        fileread </emphasis><emphasis role="bold">] [</emphasis><emphasis>,
        filewritten </emphasis><emphasis role="bold">] [</emphasis><emphasis>,
        roxiecluster </emphasis><emphasis role="bold">]</emphasis><emphasis role="bold"> [</emphasis><emphasis>, eclcontains </emphasis><emphasis role="bold">] [</emphasis><emphasis>, online </emphasis><emphasis role="bold">] [</emphasis><emphasis>, archived </emphasis><emphasis role="bold">])</emphasis></para>

        <para><emphasis>lowwuid</emphasis> A null-terminated string containing
        the lowest WorkUnit IDentifier to list. This may be an empty
        string.</para>

        <para><emphasis>highwuid</emphasis> Optional. A null-terminated string
        containing the highest WorkUnit IDentifier to list. If omitted, the
        default is an empty string.</para>

        <para><emphasis>cluster</emphasis> Optional. A null-terminated string
        containing the name of the cluster the workunit ran on. If omitted,
        the default is an empty string.</para>

        <para><emphasis>jobname</emphasis> Optional. A null-terminated string
        containing the name of the workunit. This may contain wildcard ( * ? )
        characters. If omitted, the default is an empty string.</para>

        <para><emphasis>state</emphasis> Optional. A null-terminated string
        containing the state of the workunit. If omitted, the default is an
        empty string.</para>

        <para><emphasis>priority</emphasis> Optional. A null-terminated string
        containing the priority of the workunit. If omitted, the default is an
        empty string.</para>

        <para><emphasis>fileread</emphasis> Optional. A null-terminated string
        containing the name of a file read by the workunit. This may contain
        wildcard ( * ? ) characters. If omitted, the default is an empty
        string.</para>

        <para><emphasis>filewritten</emphasis> Optional. A null-terminated
        string containing the name of a file written by the workunit. This may
        contain wildcard ( * ? ) characters. If omitted, the default is an
        empty string.</para>

        <para><emphasis>roxiecluster</emphasis> Optional. A null-terminated
        string containing the name of the Roxie cluster. If omitted, the
        default is an empty string.</para>

        <para><emphasis>eclcontains</emphasis> Optional. A null-terminated
        string containing text to search for in the workunit’s ECL code. This
        may contain wildcard ( * ? ) characters. If omitted, the default is an
        empty string.</para>

        <para><emphasis>online</emphasis> Optional. A Boolean true/false value
        specifying whether the search is performed online. If omitted, the
        default is TRUE.</para>

        <para><emphasis>archived</emphasis> Optional. A Boolean true/false
        value specifying whether the seacrh is performed in the archives. If
        omitted, the default is FALSE.</para>

        <para>Return:<emphasis> </emphasis>WorkunitList returns a
        DATASET.</para>

        <para>The <emphasis role="bold">WorkunitList </emphasis>function
        returns a dataset of all workunits that meet the search criteria
        specified by the parameters passed to the function. All the parameters
        are search values and all but the first are omittable, therefore the
        easiest way to pass a particular single search parameter would be to
        use the NAMED parameter passing technique.</para>

        <para>The resulting DATASET is in this format:</para>

        <para>WorkunitRecord := RECORD</para>

        <para>STRING24 wuid;</para>

        <para>STRING owner{MAXLENGTH(64)};</para>

        <para>STRING cluster{MAXLENGTH(64)};</para>

        <para>STRING roxiecluster{MAXLENGTH(64)};</para>

        <para>STRING job{MAXLENGTH(256)};</para>

        <para>STRING10 state;</para>

        <para>STRING7 priority;</para>

        <para>STRING20 created;</para>

        <para>STRING20 modified;</para>

        <para>BOOLEAN online;</para>

        <para>BOOLEAN protected;</para>

        <para>END;</para>

        <para>Example:</para>

        <programlisting>OUTPUT(WorkunitServices.WorkunitList(''));
 //list all current workunits
OUTPUT(WorkunitServices.WorkunitList('',
       NAMED eclcontains := 'COUNT'));
 //list only those where the ECL code contains the word 'COUNT'
 //this search is case insensitive and does include comments</programlisting>
      </sect2>

      <sect2 id="WorkunitExists">
        <title><emphasis role="bold">WorkunitExists</emphasis></title>

        <para><emphasis role="bold">WorkunitServices.WorkunitExists(</emphasis><emphasis> wuid
        </emphasis><emphasis role="bold">[</emphasis><emphasis>, online
        </emphasis><emphasis role="bold">] [</emphasis><emphasis>, archived
        </emphasis><emphasis role="bold">] )</emphasis></para>

        <para><emphasis>wuid</emphasis> A null-terminated string containing
        the WorkUnit IDentifier to locate.</para>

        <para><emphasis>online</emphasis> Optional. A Boolean true/false value
        specifying whether the search is performed online. If omitted, the
        default is TRUE.</para>

        <para><emphasis>archived</emphasis> Optional. A Boolean true/false
        value specifying whether the seacrh is performed in the archives. If
        omitted, the default is FALSE.</para>

        <para>Return:<emphasis> </emphasis>WorkunitExists returns a BOOLEAN
        value.</para>

        <para>The <emphasis role="bold">WorkunitExists </emphasis>function
        returns whether the <emphasis>wuid</emphasis> exists.</para>

        <para>Example:</para>

        <programlisting>OUTPUT(WorkunitServices.WorkunitExists('W20070308-164946'));</programlisting>
      </sect2>

      <sect2 id="WUIDonDate">
        <title><emphasis role="bold">WUIDonDate</emphasis></title>

        <para><emphasis role="bold">WorkunitServices.WUIDonDate(</emphasis><emphasis> year,
        month, day, hour, minute </emphasis><emphasis role="bold">
        )</emphasis></para>

        <para><emphasis>year</emphasis> An unsigned integer containing the
        year value.</para>

        <para><emphasis>month</emphasis> An unsigned integer containing the
        month value.</para>

        <para><emphasis>day</emphasis> An unsigned integer containing the day
        value.</para>

        <para><emphasis>hour</emphasis> An unsigned integer containing the
        hour value.</para>

        <para><emphasis>minute</emphasis> An unsigned integer containing the
        minute value.</para>

        <para>Return:<emphasis> </emphasis>WUIDonDate returns a VARSTRING
        value.</para>

        <para>The <emphasis role="bold">WUIDonDate </emphasis>function returns
        a valid WorkUnit IDentifier for a workunit that meets the passed
        parameters.</para>

        <para>Example:</para>

        <programlisting>lowwuid  := WorkunitServices.WUIDonDate(2008,02,13,13,00);
highwuid := WorkunitServices.WUIDonDate(2008,02,13,14,00);
OUTPUT(WorkunitServices.WorkunitList(lowwuid,highwuid));
 //returns a list of workunits between 1 &amp; 2 PM on 2/13/08</programlisting>
      </sect2>

      <sect2 id="WUIDdaysAgos">
        <title><emphasis role="bold">WUIDdaysAgos</emphasis></title>

        <para><emphasis role="bold">WorkunitServices.WUIDdaysAgo(</emphasis><emphasis> daysago
        </emphasis><emphasis role="bold"> )</emphasis></para>

        <para><emphasis>daysago</emphasis> An unsigned integer containing the
        number of days to go back.</para>

        <para>Return:<emphasis> </emphasis>WUIDdaysAgo returns a VARSTRING
        value.</para>

        <para>The <emphasis role="bold">WUIDdaysAgo </emphasis>function
        returns a valid WorkUnit IDentifier for a workunit that would have run
        within the last <emphasis>daysago</emphasis> days.</para>

        <para>Example:</para>

        <programlisting>daysago := WorkunitServices.WUIDdaysAgo(3);
OUTPUT(WorkunitServices.WorkunitList(daysago));
 //returns a list of workunits run in the last 72 hours</programlisting>
      </sect2>

      <sect2 id="WorkunitTimeStamps">
        <title><emphasis role="bold">WorkunitTimeStamps</emphasis></title>

        <para><emphasis role="bold">WorkunitServices.WorkunitTimeStamps(</emphasis><emphasis>
        wuid </emphasis><emphasis role="bold">)</emphasis></para>

        <para><emphasis>wuid</emphasis> A null-terminated string containing
        the WorkUnit IDentifier.</para>

        <para>Return:<emphasis> </emphasis>WorkunitTimeStamps returns a
        DATASET value.</para>

        <para>The <emphasis role="bold">WorkunitTimeStamps </emphasis>function
        returns a DATASET with this format:</para>

        <para>EXPORT WsTimeStamp := RECORD</para>

        <para>STRING32 application;</para>

        <para>STRING16 id;</para>

        <para>STRING20 time;</para>

        <para>STRING16 instance;</para>

        <para>END;</para>

        <para>Each record in the returned dataset specifies a step in the
        workunit’s excution process (creation, compilation, etc.).</para>

        <para>Example:</para>

        <programlisting>OUTPUT(WorkunitServices.WorkunitTimeStamps('W20070308-164946'));
/* produces output like this:
'workunit     ','Created ','2008-02-13T18:28:20Z','              '
'workunit     ','Modified','2008-02-13T18:32:47Z','              '
'EclServer    ','Compiled','2008-02-13T18:28:20Z','10.173.9.2:0  '
'EclAgent     ','Started ','2008-02-13T18:32:35Z','training009003'
'Thor - graph1','Finished','2008-02-13T18:32:47Z','training009004'
'Thor - graph1','Started ','2008-02-13T18:32:13Z','training009004'
'EclAgent     ','Finished','2008-02-13T18:33:09Z','training009003'
*/</programlisting>
      </sect2>

      <sect2 id="WorkunitMessages">
        <title><emphasis role="bold">WorkunitMessages</emphasis></title>

        <para><emphasis role="bold">WorkunitServices.WorkunitMessages(</emphasis><emphasis>
        wuid </emphasis><emphasis role="bold">)</emphasis></para>

        <para><emphasis>wuid</emphasis> A null-terminated string containing
        the WorkUnit IDentifier.</para>

        <para>Return:<emphasis> </emphasis>WorkunitMessages returns a DATASET
        value.</para>

        <para>The <emphasis role="bold">WorkunitMessages </emphasis>function
        returns a DATASET with this format:</para>

        <para>EXPORT WsMessage := RECORD</para>

        <para>UNSIGNED4 severity;</para>

        <para>INTEGER4 code;</para>

        <para>STRING32 location;</para>

        <para>UNSIGNED4 row;</para>

        <para>UNSIGNED4 col;</para>

        <para>STRING16 source;</para>

        <para>STRING20 time;</para>

        <para>STRING message{MAXLENGTH(1024)};</para>

        <para>END;</para>

        <para>Each record in the returned dataset specifies a message in the
        workunit.</para>

        <para>Example:</para>

        <programlisting>OUTPUT(WorkunitServices.WorkunitMessages('W20070308-164946'));</programlisting>
      </sect2>

      <sect2 id="WorkunitFilesRead">
        <title><emphasis role="bold">WorkunitFilesRead</emphasis></title>

        <para><emphasis role="bold">WorkunitServices.WorkunitFilesRead(</emphasis><emphasis>
        wuid </emphasis><emphasis role="bold">)</emphasis></para>

        <para><emphasis>wuid</emphasis> A null-terminated string containing
        the WorkUnit IDentifier.</para>

        <para>Return:<emphasis> </emphasis>WorkunitFilesRead returns a DATASET
        value.</para>

        <para>The <emphasis role="bold">WorkunitFilesRead </emphasis>function
        returns a DATASET with this format:</para>

        <para>EXPORT WsFileRead := RECORD</para>

        <para>STRING name{MAXLENGTH(256)};</para>

        <para>STRING cluster{MAXLENGTH(64)};</para>

        <para>BOOLEAN isSuper;</para>

        <para>UNSIGNED4 usage;</para>

        <para>END;</para>

        <para>Each record in the returned dataset specifies a file read by the
        workunit.</para>

        <para>Example:</para>

        <programlisting>OUTPUT(WorkunitServices.WorkunitFilesRead('W20070308-164946'));
/* produces results that look like this
'rttest::difftest::superfile','thor','true','1'
'rttest::difftest::base1','thor','false','1'
*/</programlisting>
      </sect2>

      <sect2 id="WorkunitFilesWritten">
        <title><emphasis role="bold">WorkunitFilesWritten</emphasis></title>

        <para><emphasis role="bold">WorkunitServices.WorkunitFilesWritten(</emphasis><emphasis>
        wuid </emphasis><emphasis role="bold">)</emphasis></para>

        <para><emphasis>wuid</emphasis> A null-terminated string containing
        the WorkUnit IDentifier.</para>

        <para>Return:<emphasis> </emphasis>WorkunitFilesWritten returns a
        DATASET value.</para>

        <para>The <emphasis role="bold">WorkunitFilesWritten
        </emphasis>function returns a DATASET with this format:</para>

        <para>EXPORT WsFileRead := RECORD</para>

        <para>STRING name{MAXLENGTH(256)};</para>

        <para>STRING10 graph;</para>

        <para>STRING cluster{MAXLENGTH(64)};</para>

        <para>UNSIGNED4 kind;</para>

        <para>END;</para>

        <para>Each record in the returned dataset specifies a file written by
        the workunit.</para>

        <para>Example:</para>

        <programlisting>OUTPUT(WorkunitServices.WorkunitFilesWritten('W20070308-164946'));
/* produces results that look like this
'rttest::testfetch','graph1','thor','0'
*/</programlisting>
      </sect2>

      <sect2 id="WorkunitTimings">
        <title><emphasis role="bold">WorkunitTimings</emphasis></title>

        <para><emphasis role="bold">WorkunitServices.WorkunitTimings(</emphasis><emphasis>
        wuid </emphasis><emphasis role="bold">)</emphasis></para>

        <para><emphasis>wuid</emphasis> A null-terminated string containing
        the WorkUnit IDentifier.</para>

        <para>Return:<emphasis> </emphasis>WorkunitTimings returns a DATASET
        value.</para>

        <para>The <emphasis role="bold">WorkunitTimings </emphasis>function
        returns a DATASET with this format:</para>

        <para>EXPORT WsTiming := RECORD</para>

        <para>UNSIGNED4 count;</para>

        <para>UNSIGNED4 duration;</para>

        <para>UNSIGNED4 max;</para>

        <para>STRING name{MAXLENGTH(64)};</para>

        <para>END;</para>

        <para>Each record in the returned dataset specifies a timing for the
        workunit.</para>

        <para>Example:</para>

        <programlisting>OUTPUT(WorkunitServices.WorkunitTimings('W20070308-164946'));
/* produces results that look like this
'1','4','4','EclServer: tree transform'
'1','0','0','EclServer: tree transform: normalize.scope'
'1','1','1','EclServer: tree transform: normalize.initial'
'1','18','18','EclServer: write c++'
'1','40','40','EclServer: generate code'
'1','1010','1010','EclServer: compile code'
'1','33288','33288','Graph graph1 - 1 (1)'
'1','33629','33629','Total thor time: '
'2','1','698000','WorkUnit_lockRemote'
'1','2','2679000','SDS_Initialize'
'1','0','439000','Environment_Initialize'
'1','33775','3710788928','Process'
'1','1','1942000','WorkUnit_unlockRemote'
*/</programlisting>
      </sect2>
    </sect1>
  </chapter>
</book>