Merge pull request #6765 from JamesDeFabia/11031DocumentMAXLENGTHOptions

HPCC-11031 Document MAXLENGTH Options

Reviewed-by: Gavin Halliday <ghalliday@hpccsystems.com>

docs/ECLLanguageReference/ECLR_mods/BltInFunc-BUILD.xml

@@ -196,7 +196,10 @@
     role="bold">] ) [, THRESHOLD<indexterm>
         <primary>THRESHOLD</primary>
       </indexterm>(</emphasis><emphasis>size</emphasis><emphasis role="bold">)
-    ] ]</emphasis></emphasis></para>
+    ] ] <emphasis role="bold">[, MAXLENGTH<indexterm>
+        <primary>MAXLENGTH</primary>
+      </indexterm>[(</emphasis><emphasis>value</emphasis><emphasis
+    role="bold">)] ] ]</emphasis></emphasis></emphasis></para>
 
     <para><informaltable colsep="1" frame="all" rowsep="1">
         <tgroup cols="2">
@@ -303,12 +306,19 @@
             </row>
 
             <row>
-              <entry><emphasis
-              role="bold">FILEPOSITION(false)</emphasis></entry>
+              <entry><emphasis role="bold">FILEPOSITION</emphasis></entry>
 
-              <entry>Optional. Prevents the implicit fileposition field from
-              being created and will not treat a trailing integer field any
-              differently from the rest of the payload.</entry>
+              <entry>Optional. If <emphasis>flag</emphasis> is FALSE, prevents
+              the implicit fileposition field from being created and will not
+              treat a trailing integer field any differently from the rest of
+              the payload.</entry>
+            </row>
+
+            <row>
+              <entry><emphasis>flag</emphasis></entry>
+
+              <entry>Optional. TRUE or FALSE, indicating whether or not to
+              create the implicit fileposition field.</entry>
             </row>
 
             <row>
@@ -445,9 +455,31 @@
               <entry>An integer value indicating the minimum number of bytes
               for a single part. Default is 1GB.</entry>
             </row>
+
+            <row>
+              <entry><emphasis role="bold">MAXLENGTH</emphasis></entry>
+
+              <entry>Optional. This option is used to create indexes that are
+              backward compatible for platform versions prior to 3.0.
+              Specifies the maximum length of a variable-length index record.
+              Fixed length records always use the minimum size required. If
+              the default maximum length causes inefficiency problems, it can
+              be explicitly overridden.</entry>
+            </row>
+
+            <row>
+              <entry><emphasis>value</emphasis></entry>
+
+              <entry>Optional. An integer value indicating the maximum length.
+              If omitted, the maximum size is calculated from the record
+              structure. Variable-length records that do not specify MAXLENGTH
+              may be slightly inefficient</entry>
+            </row>
           </tbody>
         </tgroup>
       </informaltable></para>
+
+    <para></para>
   </sect2>
 
   <sect2 id="BUILD_an_Access_Index">

docs/ECLLanguageReference/ECLR_mods/RecordStructure.xml

@@ -66,20 +66,23 @@
         <row>
           <entry><emphasis role="bold">MAXLENGTH</emphasis></entry>
 
-          <entry>Optional. Specifies the maximum number of characters allowed
-          in the RECORD structure or field. MAXLENGTH on the RECORD structure
-          overrides any MAXLENGTH on a field definition, which overrides any
-          MAXLENGTH specified in the TYPE structure<indexterm>
+          <entry>Optional. This option is used to create indexes that are
+          backward compatible for platform versions prior to 3.0. Specifies
+          the maximum number of characters allowed in the RECORD structure or
+          field. MAXLENGTH on the RECORD structure overrides any MAXLENGTH on
+          a field definition, which overrides any MAXLENGTH specified in the
+          TYPE structure<indexterm>
               <primary>TYPE structure</primary>
             </indexterm> if the <emphasis>datatype</emphasis> names an alien
           data type. This option defines the maximum size of variable-length
-          records. If omitted, a warning is generated. The default maximum
-          size of a record containing variable-length fields is 4096 bytes
-          (this may be overridden by using
+          records. If omitted, fixed size records use the minimum size
+          required and variable length records produce a warning. The default
+          maximum size of a record containing variable-length fields is 4096
+          bytes (this may be overridden by using
           <emphasis>#OPTION(maxLength,####)</emphasis> to change the default).
           The maximum record size should be set as conservatively as possible,
           and is better set on a per-field basis (see the <emphasis
-          role="bold">Field Modifiers</emphasis>section below).</entry>
+          role="bold">Field Modifiers</emphasis>section below). </entry>
         </row>
 
         <row>

docs/ECLLanguageReference/ECLR_mods/Recrd-Index.xml

@@ -24,20 +24,30 @@
       <primary>FIRST</primary>
     </indexterm>) ]</emphasis><emphasis role="bold"> [,DISTRIBUTED<indexterm>
       <primary>DISTRIBUTED</primary>
-    </indexterm>]) <emphasis
-  role="bold">[,FILEPOSITION(<emphasis>false</emphasis>);</emphasis></emphasis><emphasis></emphasis></para>
+    </indexterm>] [,FILEPOSITION( [
+  </emphasis><emphasis>flag</emphasis><emphasis role="bold">] ) ] [,
+  MAXLENGTH<indexterm>
+      <primary>MAXLENGTH</primary>
+    </indexterm>[</emphasis>(<emphasis>**value</emphasis>**)<emphasis
+  role="bold">] ] );</emphasis></para>
 
   <para><emphasis> attr</emphasis><emphasis role="bold"> :=
   INDEX([</emphasis><emphasis> baserecset, </emphasis><emphasis
   role="bold">]</emphasis><emphasis> keys, payload, indexfile
-  </emphasis><emphasis role="bold">[,SORTED] [,PRELOAD]</emphasis><emphasis
-  role="bold"> [,OPT] [,COMPRESSED( LZW | ROW | FIRST) ]</emphasis><emphasis
-  role="bold"> [,DISTRIBUTED]) </emphasis><emphasis
-  role="bold">[,FILEPOSITION(<emphasis>false</emphasis>);</emphasis><emphasis></emphasis></para>
+  </emphasis><emphasis role="bold">[,SORTED] [,PRELOAD][,OPT] [,COMPRESSED(
+  LZW | ROW | FIRST) ] [,DISTRIBUTED] [,FILEPOSITION( [
+  </emphasis><emphasis>flag</emphasis><emphasis role="bold">] ) ] [,
+  MAXLENGTH<indexterm>
+      <primary>MAXLENGTH</primary>
+    </indexterm>[</emphasis>(<emphasis>value</emphasis>)<emphasis
+  role="bold">] ]</emphasis>);</para>
 
   <para><emphasis> attr</emphasis><emphasis role="bold"> :=
   INDEX(</emphasis><emphasis>index,newindexfile</emphasis><emphasis
-  role="bold">);</emphasis></para>
+  role="bold"> [, MAXLENGTH<indexterm>
+      <primary>MAXLENGTH</primary>
+    </indexterm>[</emphasis>(<emphasis>value</emphasis>)<emphasis
+  role="bold">] ]); </emphasis></para>
 
   <informaltable colsep="1" frame="all" rowsep="1">
     <tgroup cols="2">
@@ -160,11 +170,19 @@
         </row>
 
         <row>
-          <entry><emphasis role="bold">FILEPOSITION(false)</emphasis></entry>
+          <entry><emphasis role="bold">FILEPOSITION</emphasis></entry>
 
-          <entry>Optional. Prevents the implicit fileposition field from being
-          created and will not treat a trailing integer field any differently
-          from the rest of the payload.</entry>
+          <entry>Optional. If <emphasis>flag</emphasis> is FALSE, prevents the
+          normal behavior of implicit fileposition field being created and
+          will not treat a trailing integer field any differently from the
+          rest of the payload.</entry>
+        </row>
+
+        <row>
+          <entry><emphasis>flag</emphasis></entry>
+
+          <entry>Optional. TRUE or FALSE, indicating whether or not to create
+          the implicit fileposition field.</entry>
         </row>
 
         <row>
@@ -182,6 +200,26 @@
           Filenames</emphasis> section for more on logical
           filenames.</para></entry>
         </row>
+
+        <row>
+          <entry><emphasis role="bold">MAXLENGTH</emphasis></entry>
+
+          <entry>Optional. This option is used to create indexes that are
+          backward compatible for platform versions prior to 3.0. Specifies
+          the maximum length of a variable-length index record. Fixed length
+          records always use the minimum size required. If the default maximum
+          length causes inefficiency problems, it can be explicitly
+          overridden.</entry>
+        </row>
+
+        <row>
+          <entry><emphasis>value</emphasis></entry>
+
+          <entry>Optional. An integer value indicating the maximum length. If
+          omitted, the maximum size is calculated from the record structure.
+          Variable-length records that do not specify MAXLENGTH may be
+          slightly inefficient</entry>
+        </row>
       </tbody>
     </tgroup>
   </informaltable>