HPCC-16283 Document BUILD after MERGE

Signed-off-by: Jim DeFabia <[email protected]>

docs/EN_US/ECLLanguageReference/ECLR_mods/BltInFunc-BUILD.xml

@@ -23,9 +23,11 @@
   );</emphasis></para>
 
   <para><emphasis role="bold">[</emphasis><emphasis>attrname</emphasis>
-  :=<emphasis role="bold"> ] BUILD(</emphasis><emphasis> indexdef
-  </emphasis><emphasis role="bold">[, </emphasis><emphasis>options
-  </emphasis><emphasis role="bold">] );</emphasis></para>
+  :=<emphasis role="bold"> ] BUILD(</emphasis><emphasis> indexdef</emphasis>
+  <emphasis role="bold">[,</emphasis><emphasis>indexfile</emphasis><emphasis
+  role="bold">]</emphasis> <emphasis role="bold">[,
+  </emphasis><emphasis>options </emphasis><emphasis role="bold">]
+  );</emphasis></para>
 
   <para><emphasis role="bold">[</emphasis><emphasis>attrname</emphasis>
   :=<emphasis role="bold"> ] BUILD(</emphasis><emphasis> indexdef, dataset,
@@ -691,17 +693,26 @@ BUILD(Vehicles,SearchTerms,Payload,'vkey::st.city2');
     <title>BUILD from an INDEX Definition</title>
 
     <para><emphasis role="bold">[</emphasis><emphasis>attrname</emphasis>
-    :=<emphasis role="bold"> ] BUILD(</emphasis><emphasis> indexdef
-    </emphasis><emphasis role="bold">[, </emphasis><emphasis>options
-    </emphasis><emphasis role="bold">] );</emphasis></para>
+    :=<emphasis role="bold"> ] BUILD(</emphasis><emphasis> indexdef</emphasis>
+    <emphasis role="bold">[,</emphasis><emphasis>indexfile</emphasis><emphasis
+    role="bold">]</emphasis> <emphasis role="bold">[,
+    </emphasis><emphasis>options </emphasis><emphasis role="bold">]
+    );</emphasis></para>
 
     <para>Form 3 creates an index file by using a previously defined INDEX
-    definition.</para>
+    definition. </para>
+
+    <para>You can also use this form to build an index based upon two MERGEd
+    indexes. To write a MERGEd index to disk, you must use the BUILD action
+    and include the optional <emphasis>indexfile</emphasis> parameter.</para>
 
     <para>Example:</para>
 
-    <programlisting>nameKey := INDEX(mainTable,{surname,forename,filepos},'name.idx');
+    <programlisting lang="ECL" role="NOTrunnable">nameKey := INDEX(mainTable,{surname,forename,filepos},'name.idx');
 BUILD(nameKey); //gets all info from the INDEX definition
+
+// BUILDing a MERGEd index
+BUILD(MERGE(idx1,idx2,'~idx::MergedIndex');
 </programlisting>
   </sect2>
 

docs/EN_US/ECLLanguageReference/ECLR_mods/BltInFunc-MERGE.xml

@@ -169,9 +169,14 @@
   <emphasis>recordsetset</emphasis>. This is particularly useful for
   incremental data updates as it allows you to merge a smaller set of new
   records into an existing large dataset or index without having to re-process
-  all the source data again. The <emphasis>recordsetset</emphasis> form makes
-  merging a variable number of datasets possible when used inside a GRAPH
-  function.</para>
+  all the source data again. </para>
+
+  <para>The <emphasis>recordsetset</emphasis> form makes merging a variable
+  number of datasets possible when used inside a GRAPH function.</para>
+
+  <para>To write a MERGEd index to disk, you must use the BUILD action.</para>
+
+  <?hard-pagebreak ?>
 
   <para>Example:</para>
 
@@ -192,4 +197,6 @@ ds4 := MERGE(SetDS,SORTED(letter,number));
 OUTPUT(ds3);
 OUTPUT(ds4);
 </programlisting>
+
+  <para>See Also: <link linkend="BUILD">BUILD</link></para>
 </sect1>